@podosoft/podokit 1.1.6 → 1.3.0

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.ts

@@ -21,28 +21,36 @@ export const handle: Handle = async ({ event, resolve }) => {
     return applySearchIndexingHeaders(response, event.url.pathname);
   }
 
-  // Public site settings (branding, locale/timezone defaults, maintenance, …),
-  // loaded once here and reused by the layout load. A visitor with no locale
-  // cookie falls back to the admin-configured site locale, then the app default.
+  // Public site settings (branding, locale/timezone defaults, maintenance, …)
+  // and the session are independent, so both requests run at once. The
+  // settings are loaded once here and reused by the layout load. The async
+  // wrappers turn a synchronous client failure into a settled rejection.
+  const api = serverApiClient(event);
+  const [siteResult, sessionResult] = await Promise.allSettled([
+    (async () => api.get<SiteSettings>("/site/settings"))(),
+    (async () => api.auth.getSession())(),
+  ]);
+
   event.locals.siteUnavailable = false;
   let site: SiteSettings | null = null;
-  try {
-    site = await serverApiClient(event).get<SiteSettings>("/site/settings");
-  } catch (cause: unknown) {
-    site = null;
+  if (siteResult.status === "fulfilled") {
+    site = siteResult.value;
+  } else {
     // A request-level 4xx proves that the backend is reachable. In particular,
     // the require-2FA guard returns 403 until enrolment and must remain able to
     // redirect the user to /setup-2fa instead of being masked as an outage.
-    event.locals.siteUnavailable = isTemporaryServiceFailure(cause);
+    event.locals.siteUnavailable = isTemporaryServiceFailure(siteResult.reason);
   }
   event.locals.site = site;
+  // A visitor with no locale cookie falls back to the admin-configured site
+  // locale, then the app default.
   event.locals.locale = resolveLocale(event.cookies.get("locale") ?? site?.locale ?? undefined);
 
   event.locals.user = null;
   event.locals.session = null;
   event.locals.authUnavailable = false;
-  try {
-    const { data, error } = await serverApiClient(event).auth.getSession();
+  if (sessionResult.status === "fulfilled") {
+    const { data, error } = sessionResult.value;
     // Better Auth returns HTTP authentication failures as data/error. A 401 is
     // a confirmed anonymous session; every other error means that the session
     // could not be checked and must not be treated as a logout.
@@ -54,7 +62,7 @@ export const handle: Handle = async ({ event, resolve }) => {
         ? { id: data.session.id, impersonatedBy: (data.session as { impersonatedBy?: string | null }).impersonatedBy ?? null }
         : null;
     }
-  } catch {
+  } else {
     // Transport failures do not invalidate the browser's session cookie. A
     // protected loader will fail closed with 503 until the backend recovers.
     event.locals.authUnavailable = true;

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/account-data.server.ts

@@ -1,43 +1,17 @@
 import type { Capabilities } from "@podosoft/podokit-api-client";
+import { getCapabilities, type CapabilitiesEvent } from "#lib/server/capabilities.js";
 
-type ServerFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-
-const defaultCapabilities: Capabilities = {
-  twoFactor: false,
-  providers: [],
-  deleteAccount: false,
-  auditLog: false,
-  emailVerification: false,
-  signupApprovalRequired: false,
-  passwordBreachCheck: false,
-  magicLink: false,
-  emailOtp: false,
-  username: false,
-  multiSession: false,
-  phoneNumber: false,
-  apiKey: false,
-  passkey: false,
-  organization: false,
-  oidcProvider: false,
-  roles: ["admin", "user"],
-};
-
-export async function loadAccountData(locals: App.Locals, fetch: ServerFetch): Promise<{
+export async function loadAccountData(
+  locals: App.Locals,
+  fetch: CapabilitiesEvent["fetch"],
+): Promise<{
   user: App.Locals["user"];
   currentSessionId: string | null;
   capabilities: Capabilities;
 }> {
-  let capabilities = defaultCapabilities;
-  try {
-    const response = await fetch("/api/account/capabilities");
-    if (response.ok) capabilities = (await response.json()) as Capabilities;
-  } catch {
-    /* Keep safe defaults if the capability endpoint is unavailable. */
-  }
-
   return {
     user: locals.user,
     currentSessionId: locals.session?.id ?? null,
-    capabilities,
+    capabilities: await getCapabilities({ locals, fetch }),
   };
 }

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/sessions.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { KeysetPages, listAdminSessions, revokeAdminSession } from "./sessions";
+
+describe("listAdminSessions", () => {
+  it("asks for one page with the cursor, trimmed search, and user", async () => {
+    const paths: string[] = [];
+    const client = {
+      get: <T>(path: string): Promise<T> => {
+        paths.push(path);
+        return Promise.resolve({ items: [], nextCursor: null, total: 0 } as unknown as T);
+      },
+    };
+
+    await listAdminSessions(client, { limit: 15, cursor: "abc", search: "  ada  ", userId: "user-1" });
+    await listAdminSessions(client, { limit: 15, cursor: null, search: " " });
+
+    expect(paths).toEqual([
+      "/admin/sessions?limit=15&cursor=abc&search=ada&userId=user-1",
+      "/admin/sessions?limit=15",
+    ]);
+  });
+});
+
+describe("revokeAdminSession", () => {
+  it("revokes by id", async () => {
+    const paths: string[] = [];
+    const client = {
+      del: <T>(path: string): Promise<T> => {
+        paths.push(path);
+        return Promise.resolve(undefined as unknown as T);
+      },
+    };
+
+    await revokeAdminSession(client, "id/with slash");
+
+    expect(paths).toEqual(["/admin/sessions/id%2Fwith%20slash"]);
+  });
+});
+
+describe("KeysetPages", () => {
+  it("offers the visited pages plus the next one", () => {
+    const pages = new KeysetPages();
+    expect(pages.cursorFor(1)).toBeNull();
+    expect(pages.cursorFor(2)).toBeUndefined();
+    expect(pages.pagerTotal(100, 15)).toBe(15);
+
+    pages.record(1, "c2");
+    pages.record(2, "c3");
+    expect(pages.cursorFor(2)).toBe("c2");
+    expect(pages.cursorFor(3)).toBe("c3");
+    expect(pages.pagerTotal(100, 15)).toBe(45);
+  });
+
+  it("stops at the last page and never exceeds the total", () => {
+    const pages = new KeysetPages();
+    pages.record(1, "c2");
+    pages.record(2, null);
+    expect(pages.cursorFor(3)).toBeUndefined();
+    expect(pages.pagerTotal(20, 15)).toBe(20);
+    expect(pages.pagerTotal(0, 15)).toBe(0);
+  });
+
+  it("drops later cursors when a page is reloaded", () => {
+    const pages = new KeysetPages();
+    pages.record(1, "c2");
+    pages.record(2, "c3");
+    pages.record(1, "c2-new");
+    expect(pages.cursorFor(2)).toBe("c2-new");
+    expect(pages.cursorFor(3)).toBeUndefined();
+
+    pages.reset();
+    expect(pages.cursorFor(2)).toBeUndefined();
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/sessions.ts

@@ -0,0 +1,73 @@
+import type { ApiClient } from "@podosoft/podokit-api-client";
+
+/** An active session from `GET /admin/sessions`. The API never returns the session token. */
+export type AdminSession = {
+  id: string;
+  userId: string;
+  userEmail: string;
+  userName: string;
+  ipAddress: string | null;
+  userAgent: string | null;
+  impersonatedBy: string | null;
+  createdAt: string;
+  expiresAt: string;
+};
+
+export type AdminSessionPage = {
+  items: AdminSession[];
+  nextCursor: string | null;
+  total: number;
+};
+
+export type AdminSessionQuery = {
+  limit: number;
+  cursor?: string | null;
+  search?: string;
+  userId?: string;
+};
+
+export function listAdminSessions(
+  client: Pick<ApiClient, "get">,
+  query: AdminSessionQuery,
+): Promise<AdminSessionPage> {
+  const params = new URLSearchParams({ limit: String(query.limit) });
+  if (query.cursor) params.set("cursor", query.cursor);
+  const search = query.search?.trim();
+  if (search) params.set("search", search);
+  if (query.userId) params.set("userId", query.userId);
+  return client.get<AdminSessionPage>(`/admin/sessions?${params.toString()}`);
+}
+
+/** Revokes by session id; the server looks up the token, so it never reaches the browser. */
+export function revokeAdminSession(client: Pick<ApiClient, "del">, id: string): Promise<void> {
+  return client.del<void>(`/admin/sessions/${encodeURIComponent(id)}`);
+}
+
+/**
+ * Remembers the keyset cursor that starts each page reached so far. The API pages
+ * forward only, so the DataTable pager offers the pages already visited plus the
+ * next one, while the footer label still shows the full total.
+ */
+export class KeysetPages {
+  #cursors: Array<string | null> = [null];
+
+  reset(): void {
+    this.#cursors = [null];
+  }
+
+  /** The cursor that starts `page` (1-based): `null` for the first page, `undefined` when not reached yet. */
+  cursorFor(page: number): string | null | undefined {
+    return this.#cursors[page - 1];
+  }
+
+  /** Records the result of loading `page`; cursors after it are stale once the page is reloaded. */
+  record(page: number, nextCursor: string | null): void {
+    this.#cursors.length = page;
+    if (nextCursor) this.#cursors.push(nextCursor);
+  }
+
+  /** The row count to give the DataTable pager so it shows exactly the reachable pages. */
+  pagerTotal(total: number, perPage: number): number {
+    return Math.min(total, this.#cursors.length * perPage);
+  }
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/users.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import {
+  adminUsersQuery,
+  keepLatestFilter,
+  listAdminUsers,
+  listUsersQuery,
+  type UserListState,
+} from "./users";
+
+const base: UserListState = {
+  page: 1,
+  perPage: 15,
+  sort: null,
+  search: "",
+  searchField: "email",
+  role: "",
+  status: "",
+};
+
+describe("adminUsersQuery", () => {
+  it("pages newest first by default", () => {
+    expect(adminUsersQuery({ ...base, page: 3 })).toEqual({
+      limit: 15,
+      offset: 30,
+      sortBy: "createdAt",
+      sortDirection: "desc",
+    });
+  });
+
+  it("sorts by a table column on the server", () => {
+    expect(adminUsersQuery({ ...base, sort: { key: "name", dir: "asc" } })).toMatchObject({
+      sortBy: "name",
+      sortDirection: "asc",
+    });
+    expect(adminUsersQuery({ ...base, sort: { key: "status", dir: "asc" } })).toMatchObject({
+      sortBy: "createdAt",
+      sortDirection: "desc",
+    });
+  });
+
+  it("searches the chosen field with the text trimmed", () => {
+    expect(adminUsersQuery({ ...base, search: "  Ada@Example.COM " })).toMatchObject({
+      search: "Ada@Example.COM",
+      searchField: "email",
+    });
+    expect(adminUsersQuery({ ...base, search: "Ada", searchField: "name" })).toMatchObject({
+      search: "Ada",
+      searchField: "name",
+    });
+    expect(adminUsersQuery({ ...base, search: "   " })).not.toHaveProperty("search");
+  });
+
+  it("sends the role and status filters together", () => {
+    expect(adminUsersQuery({ ...base, role: "admin", status: "active" })).toMatchObject({
+      role: "admin",
+      status: "active",
+    });
+    expect(adminUsersQuery({ ...base, status: "pending" })).toMatchObject({ status: "pending" });
+    expect(adminUsersQuery({ ...base, status: "deleted" })).not.toHaveProperty("status");
+    expect(adminUsersQuery(base)).not.toHaveProperty("role");
+  });
+});
+
+describe("listAdminUsers", () => {
+  it("asks GET /admin/users for one page", async () => {
+    const paths: string[] = [];
+    const client = {
+      get: <T>(path: string): Promise<T> => {
+        paths.push(path);
+        return Promise.resolve({ items: [], total: 0 } as unknown as T);
+      },
+    };
+
+    await listAdminUsers(client, adminUsersQuery({ ...base, page: 2, search: "ada", role: "admin", status: "banned" }));
+    await listAdminUsers(client, adminUsersQuery(base));
+
+    expect(paths).toEqual([
+      "/admin/users?limit=15&offset=15&sortBy=createdAt&sortDirection=desc&search=ada&searchField=email&role=admin&status=banned",
+      "/admin/users?limit=15&offset=0&sortBy=createdAt&sortDirection=desc",
+    ]);
+  });
+});
+
+// Application-owned users pages from 1.2 still import these.
+describe("deprecated listUsers helpers", () => {
+  it("still builds the single-filter Better Auth query", () => {
+    expect(listUsersQuery({ ...base, page: 2, search: " Ada@Example.COM ", status: "banned" })).toEqual({
+      limit: 15,
+      offset: 15,
+      sortBy: "createdAt",
+      sortDirection: "desc",
+      searchValue: "ada@example.com",
+      searchField: "email",
+      searchOperator: "contains",
+      filterField: "banned",
+      filterValue: true,
+      filterOperator: "eq",
+    });
+    expect(keepLatestFilter({ role: "admin", status: "" }, { role: "admin", status: "banned" }))
+      .toEqual({ role: "", status: "banned" });
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/users.ts

@@ -0,0 +1,141 @@
+import type { ApiClient } from "@podosoft/podokit-api-client";
+
+// Builds the `GET /admin/users` query for the server-paged users table.
+
+export type UserListSort = { key: string; dir: "asc" | "desc" };
+
+export type UserListState = {
+  page: number;
+  perPage: number;
+  sort: UserListSort | null;
+  search: string;
+  searchField: string;
+  role: string;
+  status: string;
+};
+
+export type AdminUserStatus = "active" | "pending" | "banned";
+
+/** A user from `GET /admin/users`. */
+export type AdminUser = {
+  id: string;
+  name: string;
+  email: string;
+  role: string | null;
+  emailVerified: boolean;
+  signupApproved: boolean;
+  banned: boolean;
+  banReason: string | null;
+  banExpires: string | null;
+  createdAt: string;
+};
+
+export type AdminUserPage = { items: AdminUser[]; total: number };
+
+export type AdminUserQuery = {
+  limit: number;
+  offset: number;
+  sortBy: string;
+  sortDirection: "asc" | "desc";
+  search?: string;
+  searchField?: "email" | "name";
+  role?: string;
+  status?: AdminUserStatus;
+};
+
+export const DEFAULT_USER_SORT: UserListSort = { key: "createdAt", dir: "desc" };
+
+const SORTABLE_FIELDS = new Set(["name", "email", "role", "createdAt"]);
+const STATUSES = new Set<string>(["active", "pending", "banned"]);
+
+function isStatus(value: string): value is AdminUserStatus {
+  return STATUSES.has(value);
+}
+
+export function adminUsersQuery(state: UserListState): AdminUserQuery {
+  const sort = state.sort && SORTABLE_FIELDS.has(state.sort.key) ? state.sort : DEFAULT_USER_SORT;
+  const search = state.search.trim();
+  return {
+    limit: state.perPage,
+    offset: (Math.max(state.page, 1) - 1) * state.perPage,
+    sortBy: sort.key,
+    sortDirection: sort.dir,
+    // The server matches case-insensitively, so the text is sent as typed.
+    ...(search ? { search, searchField: state.searchField === "name" ? "name" as const : "email" as const } : {}),
+    ...(state.role ? { role: state.role } : {}),
+    ...(isStatus(state.status) ? { status: state.status } : {}),
+  };
+}
+
+/** Reads one page; the role and status filters combine on the server. */
+export function listAdminUsers(client: Pick<ApiClient, "get">, query: AdminUserQuery): Promise<AdminUserPage> {
+  const params = new URLSearchParams({
+    limit: String(query.limit),
+    offset: String(query.offset),
+    sortBy: query.sortBy,
+    sortDirection: query.sortDirection,
+  });
+  if (query.search) {
+    params.set("search", query.search);
+    params.set("searchField", query.searchField ?? "email");
+  }
+  if (query.role) params.set("role", query.role);
+  if (query.status) params.set("status", query.status);
+  return client.get<AdminUserPage>(`/admin/users?${params.toString()}`);
+}
+
+// The 1.2 users page is application-owned and still imports the helpers below,
+// which build a Better Auth `admin.listUsers` query. Keep them until the next
+// major release so `podo update` does not break that page; new pages use
+// `adminUsersQuery` and `listAdminUsers`.
+
+/** @deprecated Use `AdminUserQuery` with `listAdminUsers`. */
+export type ListUsersQuery = {
+  limit: number;
+  offset: number;
+  sortBy: string;
+  sortDirection: "asc" | "desc";
+  searchValue?: string;
+  searchField?: "email" | "name";
+  searchOperator?: "contains";
+  filterField?: "role" | "banned" | "signupApproved";
+  filterValue?: string | boolean;
+  filterOperator?: "eq";
+};
+
+function filterFor(role: string, status: string): Pick<ListUsersQuery, "filterField" | "filterValue" | "filterOperator"> {
+  if (status === "pending") return { filterField: "signupApproved", filterValue: false, filterOperator: "eq" };
+  if (status === "banned") return { filterField: "banned", filterValue: true, filterOperator: "eq" };
+  if (role) return { filterField: "role", filterValue: role, filterOperator: "eq" };
+  return {};
+}
+
+/** @deprecated Use `adminUsersQuery`; `listUsers` accepts only one filter. */
+export function listUsersQuery(state: UserListState): ListUsersQuery {
+  const sort = state.sort && SORTABLE_FIELDS.has(state.sort.key) ? state.sort : DEFAULT_USER_SORT;
+  const searchField = state.searchField === "name" ? "name" : "email";
+  const search = state.search.trim();
+  return {
+    limit: state.perPage,
+    offset: (Math.max(state.page, 1) - 1) * state.perPage,
+    sortBy: sort.key,
+    sortDirection: sort.dir,
+    ...(search
+      ? {
+          searchValue: searchField === "email" ? search.toLowerCase() : search,
+          searchField,
+          searchOperator: "contains" as const,
+        }
+      : {}),
+    ...filterFor(state.role, state.status),
+  };
+}
+
+/** @deprecated `GET /admin/users` combines the role and status filters. */
+export function keepLatestFilter(
+  previous: { role: string; status: string },
+  next: { role: string; status: string },
+): { role: string; status: string } {
+  if (!next.role || !next.status) return next;
+  return next.status !== previous.status ? { role: "", status: next.status } : { role: next.role, status: "" };
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/audit-log.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import {
+  auditLogUrl,
+  cursorForPage,
+  emptyTrail,
+  fetchAuditLogPage,
+  recordPage,
+  trailCount,
+} from "./audit-log";
+
+const none = { action: "", actor: "", target: "" };
+
+describe("auditLogUrl", () => {
+  it("sends only the filters that are set", () => {
+    expect(auditLogUrl(none, "desc", null, 15)).toBe("/api/audit-logs?limit=15");
+    expect(auditLogUrl({ action: "user.ban", actor: " a@example.com ", target: "" }, "asc", "abc", 15))
+      .toBe("/api/audit-logs?limit=15&order=asc&cursor=abc&action=user.ban&actor=a%40example.com");
+  });
+});
+
+describe("fetchAuditLogPage", () => {
+  it("reads the entries and the next cursor header", async () => {
+    const fetcher = async (): Promise<Response> =>
+      new Response(JSON.stringify([{ id: "1" }]), { headers: { "x-next-cursor": "next" } });
+    await expect(fetchAuditLogPage(fetcher, none, "desc", null, 15)).resolves.toEqual({
+      entries: [{ id: "1" }],
+      nextCursor: "next",
+    });
+  });
+
+  it("fails on an error status", async () => {
+    const fetcher = async (): Promise<Response> => new Response("{}", { status: 403 });
+    await expect(fetchAuditLogPage(fetcher, none, "desc", null, 15)).rejects.toThrow("403");
+  });
+});
+
+describe("cursor trail", () => {
+  it("reaches one page past the last one loaded until the end appears", () => {
+    let trail = emptyTrail();
+    expect(cursorForPage(trail, 1)).toBeNull();
+    expect(cursorForPage(trail, 2)).toBeUndefined();
+
+    trail = recordPage(trail, 1, 15, "c2");
+    expect(cursorForPage(trail, 2)).toBe("c2");
+    expect(trailCount(trail, 15)).toBe(30);
+
+    trail = recordPage(trail, 2, 15, "c3");
+    trail = recordPage(trail, 3, 4, null);
+    expect(trail.cursors).toEqual([null, "c2", "c3"]);
+    expect(trailCount(trail, 15)).toBe(34);
+  });
+
+  it("keeps later pages when an earlier page still leads to them", () => {
+    let trail = recordPage(recordPage(emptyTrail(), 1, 15, "c2"), 2, 15, "c3");
+    trail = recordPage(trail, 1, 15, "c2");
+    expect(cursorForPage(trail, 3)).toBe("c3");
+  });
+
+  it("forgets later pages when new entries shift an earlier page", () => {
+    let trail = recordPage(recordPage(emptyTrail(), 1, 15, "c2"), 2, 3, null);
+    trail = recordPage(trail, 1, 15, "c2-shifted");
+    expect(trail).toEqual({ cursors: [null, "c2-shifted"], end: null });
+  });
+
+  it("counts an empty first page as no rows", () => {
+    expect(trailCount(recordPage(emptyTrail(), 1, 0, null), 15)).toBe(0);
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/audit-log.ts

@@ -0,0 +1,108 @@
+// Client for the audit-log module's cursor-paged list (GET /api/audit-logs).
+// The body is an array; the cursor for the next page arrives in a header.
+
+export type AuditLogEntry = {
+  id: string;
+  action: string;
+  actorId: string | null;
+  actorName: string | null;
+  actorEmail: string | null;
+  targetLabel: string | null;
+  ip: string | null;
+  createdAt: string;
+};
+
+export type AuditLogOrder = "asc" | "desc";
+
+export type AuditLogFilters = {
+  action: string;
+  /** Exact actor email. */
+  actor: string;
+  /** Exact target label. */
+  target: string;
+};
+
+export type AuditLogPage = {
+  entries: AuditLogEntry[];
+  nextCursor: string | null;
+};
+
+export const AUDIT_NEXT_CURSOR_HEADER = "x-next-cursor";
+
+export type Fetcher = (url: string) => Promise<Response>;
+
+export function auditLogUrl(
+  filters: AuditLogFilters,
+  order: AuditLogOrder,
+  cursor: string | null,
+  limit: number,
+): string {
+  const params = new URLSearchParams({ limit: String(limit) });
+  if (order === "asc") params.set("order", "asc");
+  if (cursor) params.set("cursor", cursor);
+  for (const key of ["action", "actor", "target"] as const) {
+    const value = filters[key].trim();
+    if (value) params.set(key, value);
+  }
+  return `/api/audit-logs?${params.toString()}`;
+}
+
+export async function fetchAuditLogPage(
+  fetcher: Fetcher,
+  filters: AuditLogFilters,
+  order: AuditLogOrder,
+  cursor: string | null,
+  limit: number,
+): Promise<AuditLogPage> {
+  const response = await fetcher(auditLogUrl(filters, order, cursor, limit));
+  if (!response.ok) throw new Error(`Audit log request failed with status ${response.status}`);
+  return {
+    entries: (await response.json()) as AuditLogEntry[],
+    nextCursor: response.headers.get(AUDIT_NEXT_CURSOR_HEADER),
+  };
+}
+
+export async function fetchAuditActions(fetcher: Fetcher): Promise<string[]> {
+  const response = await fetcher("/api/audit-logs/actions");
+  if (!response.ok) throw new Error(`Audit action request failed with status ${response.status}`);
+  return (await response.json()) as string[];
+}
+
+// A cursor-paged list has no total, so the pager learns its pages as they load:
+// `cursors[n]` opens page n + 1, and `end` is set once a page comes back
+// without a next cursor.
+export type CursorTrail = {
+  cursors: Array<string | null>;
+  end: { page: number; size: number } | null;
+};
+
+export function emptyTrail(): CursorTrail {
+  return { cursors: [null], end: null };
+}
+
+/** The cursor that opens `page`, or undefined when that page is not reachable yet. */
+export function cursorForPage(trail: CursorTrail, page: number): string | null | undefined {
+  return page >= 1 ? trail.cursors[page - 1] : undefined;
+}
+
+/** Records what loading `page` revealed about the pages after it. */
+export function recordPage(
+  trail: CursorTrail,
+  page: number,
+  size: number,
+  nextCursor: string | null,
+): CursorTrail {
+  // An unchanged next cursor means the later pages learned earlier still line up.
+  if (nextCursor !== null && trail.cursors[page] === nextCursor) return trail;
+  return {
+    cursors: [...trail.cursors.slice(0, page), ...(nextCursor === null ? [] : [nextCursor])],
+    end: nextCursor === null ? { page, size } : null,
+  };
+}
+
+/** Row count for the pager: exact once the end is known, else every reachable page as full. */
+export function trailCount(trail: CursorTrail, perPage: number): number {
+  return trail.end
+    ? (trail.end.page - 1) * perPage + trail.end.size
+    : trail.cursors.length * perPage;
+}