@podosoft/podokit 1.1.5 → 1.2.0

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-settings/site-settings.service.ts

@@ -27,46 +27,63 @@ interface SiteSettingRow {
 }
 
 export interface SiteFavicon {
-  body: Buffer;
+  object: ObjectData;
+  /** The type validated on upload. */
   contentType: string;
+  /** The `faviconUpdatedAt` setting that pages put in the favicon URL. */
+  version: string | null;
 }
 
-async function objectBuffer(object: ObjectData): Promise<Buffer> {
-  const chunks: Uint8Array[] = [];
-  for await (const chunk of object.body) chunks.push(chunk);
-  return Buffer.concat(chunks);
+// Every page render reads the site settings, so one short-lived snapshot serves
+// concurrent renders. Writes on this replica clear it immediately; another
+// replica sees the change within this window.
+const SNAPSHOT_TTL_MS = 3_000;
+
+interface Snapshot {
+  values: Record<string, string>;
+  expiresAt: number;
 }
 
 export class SiteSettingsService {
+  private snapshot: Snapshot | null = null;
+  private pending: Promise<Record<string, string>> | null = null;
+  private generation = 0;
+
   constructor(
     private readonly sql: SQL,
     private readonly storage: ObjectStore,
+    private readonly now: () => number = Date.now,
   ) {}
 
+  /** Every `site.*` setting, keyed without the prefix. */
   async getAll(): Promise<Record<string, string>> {
-    const rows = await this.sql<SiteSettingRow[]>`
-      SELECT "key", "value" FROM "app_setting" WHERE "key" LIKE 'site.%'
-    `;
-    const result: Record<string, string> = {};
-    for (const row of rows) result[row.key.slice(PREFIX.length)] = row.value;
-    return result;
+    const snapshot = this.snapshot;
+    if (snapshot && snapshot.expiresAt > this.now()) return { ...snapshot.values };
+    return { ...(await this.load()) };
   }
 
   async get(key: string): Promise<string | null> {
-    const rows = await this.sql<SiteSettingRow[]>`
-      SELECT "key", "value" FROM "app_setting" WHERE "key" = ${PREFIX + key}
-    `;
-    return rows[0]?.value ?? null;
+    return (await this.getAll())[key] ?? null;
   }
 
   async setMany(update: Record<string, string>): Promise<Record<string, string>> {
-    for (const [key, value] of Object.entries(update)) {
-      await this.sql`
-        INSERT INTO "app_setting" ("key", "value", "updatedAt")
-        VALUES (${PREFIX + key}, ${value}, CURRENT_TIMESTAMP)
-        ON CONFLICT ("key") DO UPDATE
-        SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
-      `;
+    const entries = Object.entries(update);
+    if (entries.length > 0) {
+      try {
+        await this.sql.begin(async (tx) => {
+          for (const [key, value] of entries) {
+            await tx`
+              INSERT INTO "app_setting" ("key", "value", "updatedAt")
+              VALUES (${PREFIX + key}, ${value}, CURRENT_TIMESTAMP)
+              ON CONFLICT ("key") DO UPDATE
+              SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
+            `;
+          }
+        });
+      } finally {
+        // Also after a failure: the outcome of an interrupted commit is unknown.
+        this.invalidate();
+      }
     }
     return this.getAll();
   }
@@ -79,17 +96,50 @@ export class SiteSettingsService {
     });
   }
 
+  /** The favicon with its content unread, or null when none is set. */
   async getFavicon(): Promise<SiteFavicon | null> {
-    const contentType = await this.get("faviconContentType");
+    const settings = await this.getAll();
+    const contentType = settings.faviconContentType;
     if (!contentType) return null;
-    try {
-      return { body: await objectBuffer(await this.storage.get(FAVICON_KEY)), contentType };
-    } catch {
-      return null;
-    }
+    const object = await this.storage.get(FAVICON_KEY);
+    return object ? { object, contentType, version: settings.faviconUpdatedAt ?? null } : null;
   }
 
   faviconVersion(): Promise<string | null> {
     return this.get("faviconUpdatedAt");
   }
+
+  /** One query at a time; concurrent readers share it. */
+  private load(): Promise<Record<string, string>> {
+    if (this.pending) return this.pending;
+    const generation = this.generation;
+    const pending = this.query()
+      .then((values) => {
+        // A write that finished meanwhile may not be in these rows.
+        if (generation === this.generation) {
+          this.snapshot = { values, expiresAt: this.now() + SNAPSHOT_TTL_MS };
+        }
+        return values;
+      })
+      .finally(() => {
+        if (this.pending === pending) this.pending = null;
+      });
+    this.pending = pending;
+    return pending;
+  }
+
+  private invalidate(): void {
+    this.generation += 1;
+    this.snapshot = null;
+    this.pending = null;
+  }
+
+  private async query(): Promise<Record<string, string>> {
+    const rows = await this.sql<SiteSettingRow[]>`
+      SELECT "key", "value" FROM "app_setting" WHERE "key" LIKE 'site.%'
+    `;
+    const result: Record<string, string> = {};
+    for (const row of rows) result[row.key.slice(PREFIX.length)] = row.value;
+    return result;
+  }
 }

package/dist/templates/modules/admin-dashboard/files/apps/web/src/app.d.ts

@@ -1,3 +1,4 @@
+import type { Capabilities } from "@podosoft/podokit-api-client";
 import type { Locale } from "#lib/i18n/messages.js";
 import type { SiteSettings } from "#lib/site.svelte.js";
 
@@ -24,6 +25,8 @@ declare global {
       locale: Locale;
       site: SiteSettings | null;
       siteUnavailable: boolean;
+      /** Per-request memo; read it through `getCapabilities()` from `#lib/server/capabilities.js`. */
+      capabilities?: Promise<Capabilities>;
     }
   }
 }

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

@@ -0,0 +1,124 @@
+import { ApiError } from "@podosoft/podokit-api-client";
+import type { RequestEvent } from "@sveltejs/kit";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { handle } from "./hooks.server";
+
+type SessionResult = {
+  data: { user: { id: string }; session: { id: string; impersonatedBy?: string | null } } | null;
+  error: { status: number } | null;
+};
+
+const client = vi.hoisted(() => ({
+  get: vi.fn<(path: string) => Promise<unknown>>(),
+  getSession: vi.fn<() => Promise<SessionResult>>(),
+}));
+
+vi.mock("#lib/server/api.js", () => ({
+  serverApiClient: () => ({ get: client.get, auth: { getSession: client.getSession } }),
+}));
+
+const resolve = vi.fn(async (): Promise<Response> => new Response("ok"));
+
+function requestEvent(pathname: string, cookies: Record<string, string> = {}): RequestEvent {
+  return {
+    route: { id: pathname },
+    url: new URL(`http://localhost${pathname}`),
+    cookies: { get: (name: string) => cookies[name] },
+    locals: {},
+  } as unknown as RequestEvent;
+}
+
+const signedIn: SessionResult = {
+  data: { user: { id: "user-1" }, session: { id: "session-1", impersonatedBy: "admin-1" } },
+  error: null,
+};
+
+describe("handle", () => {
+  beforeEach(() => {
+    client.get.mockReset();
+    client.getSession.mockReset();
+    resolve.mockClear();
+  });
+
+  it("requests the session without waiting for site settings", async () => {
+    let releaseSite: (value: unknown) => void = () => undefined;
+    client.get.mockReturnValue(new Promise((settle) => { releaseSite = settle; }));
+    client.getSession.mockResolvedValue(signedIn);
+    const event = requestEvent("/account");
+
+    const pending = handle({ event, resolve });
+    await vi.waitFor(() => expect(client.getSession).toHaveBeenCalledTimes(1));
+    releaseSite({ locale: "ko" });
+    await pending;
+
+    expect(client.get).toHaveBeenCalledWith("/site/settings");
+    expect(event.locals).toMatchObject({
+      site: { locale: "ko" },
+      siteUnavailable: false,
+      authUnavailable: false,
+      locale: "ko",
+      user: { id: "user-1" },
+      session: { id: "session-1", impersonatedBy: "admin-1" },
+    });
+  });
+
+  it("treats a site settings client error as a reachable backend", async () => {
+    client.get.mockRejectedValue(new ApiError("TWO_FACTOR_REQUIRED", "Two-factor enrolment is required.", 403));
+    client.getSession.mockResolvedValue(signedIn);
+    const event = requestEvent("/account", { locale: "en" });
+
+    await handle({ event, resolve });
+
+    expect(event.locals).toMatchObject({ site: null, siteUnavailable: false, locale: "en" });
+    expect(resolve).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails closed on protected pages when site settings are unavailable", async () => {
+    client.get.mockRejectedValue(new TypeError("fetch failed"));
+    client.getSession.mockResolvedValue(signedIn);
+
+    await expect(handle({ event: requestEvent("/account"), resolve })).rejects.toMatchObject({ status: 503 });
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  it("keeps public pages available with fallbacks when the backend fails", async () => {
+    client.get.mockRejectedValue(new ApiError("UNAVAILABLE", "Unavailable", 503));
+    client.getSession.mockRejectedValue(new TypeError("fetch failed"));
+    const event = requestEvent("/login");
+
+    await handle({ event, resolve });
+
+    expect(event.locals).toMatchObject({
+      site: null,
+      siteUnavailable: true,
+      authUnavailable: true,
+      user: null,
+      session: null,
+      locale: "en",
+    });
+  });
+
+  it("confirms an anonymous visitor on a 401 session response", async () => {
+    client.get.mockResolvedValue({ locale: null });
+    client.getSession.mockResolvedValue({ data: null, error: { status: 401 } });
+    const event = requestEvent("/");
+
+    await handle({ event, resolve });
+
+    expect(event.locals).toMatchObject({ authUnavailable: false, user: null, session: null });
+  });
+
+  it("fails closed on protected pages when the session cannot be checked", async () => {
+    client.get.mockResolvedValue({ locale: null });
+    client.getSession.mockResolvedValue({ data: null, error: { status: 500 } });
+
+    await expect(handle({ event: requestEvent("/account"), resolve })).rejects.toMatchObject({ status: 503 });
+  });
+
+  it("skips runtime lookups for API proxy requests", async () => {
+    await handle({ event: requestEvent("/api/site/settings"), resolve });
+
+    expect(client.get).not.toHaveBeenCalled();
+    expect(client.getSession).not.toHaveBeenCalled();
+  });
+});

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,75 @@
+import { describe, expect, it } from "vitest";
+import { keepLatestFilter, listUsersQuery, type UserListState } from "./users";
+
+const base: UserListState = {
+  page: 1,
+  perPage: 15,
+  sort: null,
+  search: "",
+  searchField: "email",
+  role: "",
+  status: "",
+};
+
+describe("listUsersQuery", () => {
+  it("pages newest first by default", () => {
+    expect(listUsersQuery({ ...base, page: 3 })).toEqual({
+      limit: 15,
+      offset: 30,
+      sortBy: "createdAt",
+      sortDirection: "desc",
+    });
+  });
+
+  it("sorts by a table column on the server", () => {
+    expect(listUsersQuery({ ...base, sort: { key: "name", dir: "asc" } })).toMatchObject({
+      sortBy: "name",
+      sortDirection: "asc",
+    });
+    expect(listUsersQuery({ ...base, sort: { key: "status", dir: "asc" } })).toMatchObject({
+      sortBy: "createdAt",
+      sortDirection: "desc",
+    });
+  });
+
+  it("searches email case-insensitively and names as typed", () => {
+    expect(listUsersQuery({ ...base, search: "  Ada@Example.COM " })).toMatchObject({
+      searchValue: "ada@example.com",
+      searchField: "email",
+      searchOperator: "contains",
+    });
+    expect(listUsersQuery({ ...base, search: "Ada", searchField: "name" })).toMatchObject({
+      searchValue: "Ada",
+      searchField: "name",
+    });
+    expect(listUsersQuery({ ...base, search: "   " })).not.toHaveProperty("searchValue");
+  });
+
+  it("maps the role and status filters to the single server filter", () => {
+    expect(listUsersQuery({ ...base, role: "admin" })).toMatchObject({
+      filterField: "role",
+      filterValue: "admin",
+      filterOperator: "eq",
+    });
+    expect(listUsersQuery({ ...base, status: "pending" })).toMatchObject({
+      filterField: "signupApproved",
+      filterValue: false,
+    });
+    expect(listUsersQuery({ ...base, status: "banned" })).toMatchObject({
+      filterField: "banned",
+      filterValue: true,
+    });
+    expect(listUsersQuery(base)).not.toHaveProperty("filterField");
+  });
+});
+
+describe("keepLatestFilter", () => {
+  it("keeps whichever filter changed last", () => {
+    expect(keepLatestFilter({ role: "admin", status: "" }, { role: "admin", status: "banned" }))
+      .toEqual({ role: "", status: "banned" });
+    expect(keepLatestFilter({ role: "", status: "banned" }, { role: "user", status: "banned" }))
+      .toEqual({ role: "user", status: "" });
+    expect(keepLatestFilter({ role: "", status: "" }, { role: "user", status: "" }))
+      .toEqual({ role: "user", status: "" });
+  });
+});