enhanced token management by adding optional expiry refresh in token_get_record and updated session API documentation

common.php

@@ -178,14 +178,29 @@ function token_add(string $token, int $ttlSeconds = 86400, array $extra = []): v
     qdb_save($tmpDb, $lockFp);
 }
 
-function token_get_record(string $token): ?array {
+function token_get_record(string $token, bool $refreshExpiry = true): ?array {
     require_once __DIR__ . '/db_init.php';
-    [$pdo, $tmpDb, $lockFp] = qdb_open(false);
+    require_once __DIR__ . '/lib/settings.php';
+    [$pdo, $tmpDb, $lockFp] = qdb_open($refreshExpiry);
+    $now = time();
     $stmt = $pdo->prepare("SELECT * FROM session WHERE token = :t AND expiresAt >= :now");
-    $stmt->execute([':t' => token_storage_key($token), ':now' => time()]);
+    $storedToken = token_storage_key($token);
+    $stmt->execute([':t' => $storedToken, ':now' => $now]);
     $row = $stmt->fetch(PDO::FETCH_ASSOC);
-    qdb_discard($tmpDb, $lockFp);
-    if (!$row) return null;
+    if (!$row) {
+        qdb_discard($tmpDb, $lockFp);
+        return null;
+    }
+    if ($refreshExpiry) {
+        $settings = qdb_settings_get_on_pdo($pdo);
+        $newExpiry = $now + qdb_session_ttl_seconds($settings, !empty($row['temp']));
+        $pdo->prepare('UPDATE session SET expiresAt = :exp WHERE token = :t')
+            ->execute([':exp' => $newExpiry, ':t' => $storedToken]);
+        $row['expiresAt'] = $newExpiry;
+        qdb_save($tmpDb, $lockFp);
+    } else {
+        qdb_discard($tmpDb, $lockFp);
+    }
     // Map DB columns to the keys the rest of the codebase expects
     return [
         'token'    => $row['token'],