portal-mojo 0.1.0

package/src/client/client.ts

@@ -0,0 +1,268 @@
+// Mini @mojo/client — the typed django-mojo protocol layer.
+//
+// Contract (from the web-mojo port extraction):
+//   - Envelope: {status, ...} — status:false carries error/message. Unwrapped
+//     HERE, at exactly one boundary. A failed save REJECTS (MojoError); it is
+//     never resolved as success. (web-mojo's Model.save() never-rejects trap
+//     is deliberately not carried forward.)
+//   - Lists: {status, data: T[], count, size, start} → MojoList<T>.
+//   - Singles: {status, data: T} → T.
+//   - Paging: start/size. Sort: 'field' | '-field'. Filters: Django lookups.
+//   - Every request carries the X-Mojo-UID device header; when auth is
+//     initialized (initAuth), a pre-request gate + Authorization header are
+//     installed via installAuthHooks — the client core itself has zero auth
+//     knowledge (web-mojo's Rest-interceptor shape).
+//
+// With VITE_MOJO_API unset the transport is the in-memory mock; set it to a
+// django-mojo origin and the same code talks to the real backend.
+import { mockFetch } from './mock';
+import { MojoError } from './errors';
+import { DUID_HEADER, getDuid } from './duid';
+import type { MojoList, Params } from './types';
+
+export { MojoError, AuthRequiredError } from './errors';
+
+const API_BASE: string = import.meta.env.VITE_MOJO_API ?? '';
+
+/** True when the in-memory mock transport is active (VITE_MOJO_API unset). */
+export function usingMockTransport(): boolean {
+    return !API_BASE;
+}
+
+/** The configured django-mojo origin ('' under the mock transport). */
+export function apiOrigin(): string {
+    return API_BASE;
+}
+
+/**
+ * TanStack Query defaults tuned for the mojo protocol — spread these into the
+ * app's QueryClient:
+ *   · 4xx MojoErrors never retry (a 404/401/403 is deterministic — retrying
+ *     it only delays the error surfacing, e.g. the group-context fallback)
+ *   · networkMode 'always' under the mock (an in-memory backend can't be
+ *     offline; online-pausing would wedge failures forever), 'online' for
+ *     real backends.
+ */
+export function mojoQueryDefaults() {
+    return {
+        queries: {
+            networkMode: (usingMockTransport() ? 'always' : 'online') as 'always' | 'online',
+            retry: (failureCount: number, error: unknown): boolean => {
+                if (error instanceof MojoError && error.status >= 400 && error.status < 500) return false;
+                return failureCount < 1;
+            },
+            // No refetch storm on window focus (web-mojo parity: freshness
+            // comes from explicit refresh + the opt-in autoRefresh interval).
+            // With it on, every hop back from devtools/another window refired
+            // EVERY active query — read as phantom duplicate fetches.
+            refetchOnWindowFocus: false,
+        },
+    };
+}
+
+export function buildQuery(params: Params): string {
+    const qs = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === '') continue;
+        qs.set(key, String(value));
+    }
+    const s = qs.toString();
+    return s ? `?${s}` : '';
+}
+
+export interface FetchOpts {
+    params?: Params;
+    method?: 'GET' | 'POST' | 'DELETE';
+    body?: Record<string, unknown>;
+    /** Cancels the selected transport request. */
+    signal?: AbortSignal;
+}
+
+export interface Envelope {
+    status: boolean;
+    code?: number;
+    data?: unknown;
+    error?: string;
+    error_code?: number | string;
+    message?: string;
+    count?: number;
+    size?: number;
+    start?: number;
+}
+
+/** Installed by auth (initAuth). The transport stays auth-agnostic. */
+export interface AuthHooks {
+    /** Pre-request gate; may throw AuthRequiredError → synthetic-401 reject, no fetch. */
+    preRequest(path: string): Promise<void>;
+    /** Authorization header value, or null when no session exists. */
+    authHeader(): string | null;
+}
+
+let authHooks: AuthHooks | null = null;
+
+export function installAuthHooks(hooks: AuthHooks | null): void {
+    authHooks = hooks;
+}
+
+async function transport(path: string, opts: FetchOpts): Promise<Envelope> {
+    // Gate BEFORE headers are built: after a mid-gate token refresh the fresh
+    // Authorization value is picked up below by construction (web-mojo had to
+    // re-stamp a snapshotted header here).
+    if (authHooks) await authHooks.preRequest(path);
+
+    const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        [DUID_HEADER]: getDuid(),
+    };
+    const bearer = authHooks?.authHeader();
+    if (bearer) headers['Authorization'] = bearer;
+
+    if (!API_BASE) {
+        return (await mockFetch(path, { ...opts, headers })) as Envelope;
+    }
+    const res = await fetch(`${API_BASE}${path}${buildQuery(opts.params ?? {})}`, {
+        method: opts.method ?? 'GET',
+        headers,
+        body: opts.body ? JSON.stringify(opts.body) : undefined,
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        // django-mojo sends its envelope on error responses too — surface the
+        // real message ("Invalid username or password"), not "HTTP 401".
+        let detail = `HTTP ${res.status}`;
+        let errorCode: string | number | undefined;
+        let data: unknown;
+        try {
+            const body = (await res.json()) as Envelope;
+            detail = body.error ?? body.message ?? detail;
+            errorCode = body.error_code;
+            data = body.data;
+        } catch {
+            // Non-JSON error body — keep the status text.
+        }
+        throw new MojoError(detail, res.status, errorCode, data);
+    }
+    return (await res.json()) as Envelope;
+}
+
+/** The single envelope-unwrap boundary. */
+async function unwrap(path: string, opts: FetchOpts): Promise<Envelope> {
+    const body = await transport(path, opts);
+    if (body.status === false) {
+        const legacyStatus = typeof body.error_code === 'number' ? body.error_code : 0;
+        throw new MojoError(
+            body.error ?? body.message ?? 'Request failed',
+            body.code ?? legacyStatus,
+            body.error_code,
+            body.data,
+        );
+    }
+    return body;
+}
+
+/**
+ * Typed escape hatch over the unwrap boundary for protocol modules (auth) and
+ * one-off endpoints. Still the same single boundary — never parse envelopes
+ * anywhere else.
+ */
+export function mojoCall(path: string, opts: FetchOpts = {}): Promise<Envelope> {
+    return unwrap(path, opts);
+}
+
+export async function mojoList<T>(endpoint: string, params: Params = {}): Promise<MojoList<T>> {
+    const body = await unwrap(endpoint, { params });
+    return {
+        rows: (body.data ?? []) as T[],
+        count: body.count ?? 0,
+        start: body.start ?? 0,
+        size: body.size ?? 0,
+    };
+}
+
+export async function mojoGet<T>(endpoint: string, id: number | string): Promise<T> {
+    const body = await unwrap(`${endpoint}/${id}`, {});
+    return body.data as T;
+}
+
+export interface MetricsResponse {
+    labels: string[];
+    datasets: { label: string; data: number[] }[];
+}
+
+/**
+ * django-mojo metrics. The wire shape (verified live) is
+ * `{data: {<slug>: number[]}, labels: string[]}` — a slug-keyed map with NO
+ * granularity/range echo. Normalized HERE (the one boundary) into the
+ * datasets array the chart components consume; display names for slugs are a
+ * presentation concern (MetricsChart), not a wire fact.
+ */
+export async function mojoMetrics(params: Params): Promise<MetricsResponse> {
+    const body = await unwrap('/api/metrics/fetch', { params });
+    const raw = (body.data ?? {}) as { data?: Record<string, number[]>; labels?: string[] };
+    return {
+        labels: raw.labels ?? [],
+        datasets: Object.entries(raw.data ?? {}).map(([slug, data]) => ({ label: slug, data: data ?? [] })),
+    };
+}
+
+/** Create (no id) or update (with id). Rejects on any failure. */
+export async function mojoSave<T>(endpoint: string, id: number | string | null, changes: Record<string, unknown>): Promise<T> {
+    const path = id == null ? endpoint : `${endpoint}/${id}`;
+    const body = await unwrap(path, { method: 'POST', body: changes });
+    return body.data as T;
+}
+
+/**
+ * Delete a record. django-mojo answers `{status: "deleted"}` (a string — the
+ * envelope's only non-boolean status; it passes the unwrap's `=== false`
+ * failure check by design). Failures reject like every other call.
+ */
+export async function mojoDelete(endpoint: string, id: number | string): Promise<void> {
+    await unwrap(`${endpoint}/${id}`, { method: 'DELETE' });
+}
+
+/** Trigger a browser download of an in-memory file. Shared by safe client exports. */
+export function downloadBlob(blob: Blob, filename: string): void {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    URL.revokeObjectURL(url);
+}
+
+/**
+ * Server-side export (mojo/models/rest.py on_rest_list_response): the list
+ * endpoint with `download_format=csv|json` + `filename` streams a file built
+ * from the model's graph fields under the CURRENT filters (paging params are
+ * stripped here — an export is the whole result set). Under the mock the
+ * same filter pipeline synthesizes the file content in-memory.
+ */
+export async function mojoDownload(endpoint: string, params: Params, format: 'csv' | 'json'): Promise<void> {
+    const cleaned: Params = { ...params };
+    delete cleaned.start;
+    delete cleaned.size;
+    const filename = `export-${endpoint.split('/').filter(Boolean).pop() ?? 'data'}.${format}`;
+    const withFormat: Params = { ...cleaned, download_format: format, filename };
+
+    if (authHooks) await authHooks.preRequest(endpoint);
+    const headers: Record<string, string> = { [DUID_HEADER]: getDuid() };
+    const bearer = authHooks?.authHeader();
+    if (bearer) headers['Authorization'] = bearer;
+
+    if (!API_BASE) {
+        const body = (await mockFetch(endpoint, { params: withFormat, headers })) as Envelope;
+        if (body.status === false) {
+            const legacyStatus = typeof body.error_code === 'number' ? body.error_code : 0;
+            throw new MojoError(body.error ?? 'Export failed', body.code ?? legacyStatus, body.error_code, body.data);
+        }
+        const file = body.data as { filename: string; content: string; mime: string };
+        downloadBlob(new Blob([file.content], { type: file.mime }), file.filename);
+        return;
+    }
+    const res = await fetch(`${API_BASE}${endpoint}${buildQuery(withFormat)}`, { headers });
+    if (!res.ok) throw new MojoError(`Export failed (HTTP ${res.status})`, res.status);
+    downloadBlob(await res.blob(), filename);
+}

package/src/client/duid.ts

@@ -0,0 +1,31 @@
+// Device Unique ID — a per-browser UUID django-mojo uses for device tracking
+// and rate limiting. Sent on every request as the X-Mojo-UID header (web-mojo
+// Rest parity, storage key included).
+
+export const DUID_HEADER = 'X-Mojo-UID';
+const DUID_KEY = 'mojo_device_uid';
+
+let duid: string | null = null;
+
+function generate(): string {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+
+/** Stable per-browser DUID; falls back to per-session when storage is blocked. */
+export function getDuid(): string {
+    if (duid) return duid;
+    try {
+        duid = localStorage.getItem(DUID_KEY);
+        if (!duid) {
+            duid = generate();
+            localStorage.setItem(DUID_KEY, duid);
+        }
+    } catch {
+        duid = generate();
+    }
+    return duid;
+}

package/src/client/errors.ts

@@ -0,0 +1,33 @@
+// Error types for the mojo client. Own module so client.ts and auth.ts can
+// both import them without a dependency cycle.
+
+export class MojoError extends Error {
+    status: number;
+    /** Semantic django-mojo error code (`s3_operation_incomplete`, etc.). */
+    errorCode: string | number | undefined;
+    /** Structured, server-sanitized failure evidence. Never log indiscriminately. */
+    data: unknown;
+    constructor(message: string, status = 0, errorCode?: string | number, data?: unknown) {
+        super(message);
+        this.name = 'MojoError';
+        this.status = status;
+        this.errorCode = errorCode;
+        this.data = data;
+    }
+}
+
+/**
+ * Thrown by the pre-request auth gate when the access token is expired and
+ * cannot be refreshed. The transport recognizes it and short-circuits the
+ * request WITHOUT calling fetch — web-mojo's "synthetic 401". web-mojo
+ * resolved a 401-shaped response object (its Rest never rejects); here the
+ * same short-circuit REJECTS, per the failure-is-unmissable rule.
+ */
+export class AuthRequiredError extends MojoError {
+    reason: 'unauthorized';
+    constructor(message = 'Authentication required') {
+        super(message, 401);
+        this.name = 'AuthRequiredError';
+        this.reason = 'unauthorized';
+    }
+}

package/src/client/group-context.ts

@@ -0,0 +1,28 @@
+// Group context plumbing — types + the React context object, in their own
+// module so me.ts (useCan reads the active member) and group.tsx (the
+// provider needs useAuthSnapshot from me.ts) never import each other.
+import { createContext } from 'react';
+import type { MemberLike } from './me';
+
+export interface Group {
+    id: number;
+    name: string;
+    kind: string;
+    uuid?: string | null;
+    parent?: { id: number; name: string; kind?: string } | null;
+    [field: string]: unknown;
+}
+
+export interface GroupContextValue {
+    /** The active group, or null when operating in global context. */
+    group: Group | null;
+    /** The signed-in user's membership in the active group (permissions dict). */
+    member: MemberLike | null;
+    /** True while boot resolution or a switch is in flight. */
+    loading: boolean;
+    setActiveGroup(group: Group): void;
+    clearActiveGroup(): void;
+}
+
+/** Null outside a <GroupProvider> — consumers must handle both. */
+export const GroupContext = createContext<GroupContextValue | null>(null);

package/src/client/group.tsx

@@ -0,0 +1,126 @@
+// GroupProvider — the active-group spine, ported from web-mojo
+// PortalApp.checkActiveGroup / setActiveGroup (PortalApp.js:230-348):
+//   · resolution order: `?group=` URL param BEATS the stored id
+//   · the param rides the REAL search string (before the hash) —
+//     `/?group=5#/users` — so it survives every hash navigation and never
+//     fights the per-route params store
+//   · storage key `active_group_id` (web-mojo parity)
+//   · on activation the user's member record for that group is fetched
+//     (`/api/group/<id>/member`) — group-context permissions flow from it
+//   · URL-group failure falls back to the stored group, then to none
+import { useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { mojoCall, mojoGet } from './client';
+import { useAuthSnapshot } from './me';
+import type { MemberLike } from './me';
+import { GroupContext, type Group, type GroupContextValue } from './group-context';
+
+const STORAGE_KEY = 'active_group_id';
+
+function readUrlGroupParam(): string | null {
+    if (typeof window === 'undefined') return null;
+    return new URLSearchParams(window.location.search).get('group');
+}
+
+function writeUrlGroupParam(id: number | null): void {
+    const params = new URLSearchParams(window.location.search);
+    if (id == null) params.delete('group');
+    else params.set('group', String(id));
+    const qs = params.toString();
+    window.history.replaceState({}, '', window.location.pathname + (qs ? `?${qs}` : '') + (window.location.hash || ''));
+}
+
+function loadStoredGroupId(): number | null {
+    try {
+        const raw = localStorage.getItem(STORAGE_KEY);
+        const id = raw == null ? NaN : Number(raw);
+        return Number.isFinite(id) && id > 0 ? id : null;
+    } catch {
+        return null;
+    }
+}
+
+function saveStoredGroupId(id: number): void {
+    try {
+        localStorage.setItem(STORAGE_KEY, String(id));
+    } catch { /* storage unavailable — context stays session-only */ }
+}
+
+function clearStoredGroupId(): void {
+    try {
+        localStorage.removeItem(STORAGE_KEY);
+    } catch { /* ignore */ }
+}
+
+export function GroupProvider({ children }: { children: ReactNode }) {
+    const auth = useAuthSnapshot();
+    const queryClient = useQueryClient();
+    const [groupId, setGroupId] = useState<number | null>(() => {
+        const urlRaw = readUrlGroupParam();
+        const urlId = urlRaw == null ? NaN : Number(urlRaw);
+        if (Number.isFinite(urlId) && urlId > 0) return urlId;
+        return loadStoredGroupId();
+    });
+
+    const groupQuery = useQuery({
+        queryKey: ['group', groupId, auth.uid],
+        queryFn: () => mojoGet<Group>('/api/group', groupId!),
+        enabled: auth.authenticated && groupId != null,
+        staleTime: 5 * 60_000,
+    });
+
+    // web-mojo's fallback chain: a failing URL/stored group falls back to the
+    // stored one (when different), else the context clears entirely.
+    useEffect(() => {
+        if (!groupQuery.isError || groupId == null) return;
+        const stored = loadStoredGroupId();
+        if (stored != null && stored !== groupId) {
+            console.warn(`[portal-mojo] active group ${groupId} failed to load; falling back to stored group ${stored}`);
+            writeUrlGroupParam(stored);
+            setGroupId(stored);
+        } else {
+            console.warn(`[portal-mojo] active group ${groupId} failed to load; clearing group context`);
+            clearStoredGroupId();
+            writeUrlGroupParam(null);
+            setGroupId(null);
+        }
+    }, [groupQuery.isError, groupId]);
+
+    const group = groupId != null ? (groupQuery.data ?? null) : null;
+
+    const memberQuery = useQuery({
+        queryKey: ['group-member', group?.id, auth.uid],
+        queryFn: async () => (await mojoCall(`/api/group/${group!.id}/member`)).data as MemberLike,
+        enabled: auth.authenticated && group != null,
+        staleTime: 5 * 60_000,
+    });
+
+    const value = useMemo<GroupContextValue>(() => ({
+        group,
+        member: (group != null ? memberQuery.data : null) ?? null,
+        loading: auth.authenticated && groupId != null
+            && (groupQuery.isLoading || (group != null && memberQuery.isLoading)),
+        setActiveGroup(next: Group) {
+            // Seed the cache with the row the switcher already holds — no
+            // refetch flash on switch.
+            queryClient.setQueryData(['group', next.id, auth.uid], next);
+            saveStoredGroupId(next.id);
+            writeUrlGroupParam(next.id);
+            setGroupId(next.id);
+        },
+        clearActiveGroup() {
+            clearStoredGroupId();
+            writeUrlGroupParam(null);
+            setGroupId(null);
+        },
+    }), [group, memberQuery.data, memberQuery.isLoading, groupQuery.isLoading, groupId, auth.authenticated, auth.uid, queryClient]);
+
+    return <GroupContext.Provider value={value}>{children}</GroupContext.Provider>;
+}
+
+/** Active-group context. Throws outside <GroupProvider> — mount it app-wide. */
+export function useActiveGroup(): GroupContextValue {
+    const ctx = useContext(GroupContext);
+    if (!ctx) throw new Error('useActiveGroup requires a <GroupProvider> above it');
+    return ctx;
+}

package/src/client/hooks.ts

@@ -0,0 +1,50 @@
+// TanStack Query wraps the client: caching, dedup, background refetch,
+// loading/error states — everything Collection.fetch + fetch:start/end
+// events + stale guards did by hand in web-mojo.
+import { keepPreviousData, useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { mojoGet, mojoList, mojoSave } from './client';
+import type { MojoList, Params } from './types';
+
+export function useModelList<T>(
+    endpoint: string,
+    params: Params = {},
+    opts: { enabled?: boolean; sanitizeRow?: (row: T) => T } = {},
+) {
+    return useQuery({
+        queryKey: [endpoint, params],
+        queryFn: async (): Promise<MojoList<T>> => {
+            const list = await mojoList<T>(endpoint, params);
+            return opts.sanitizeRow
+                ? { ...list, rows: list.rows.map(opts.sanitizeRow) }
+                : list;
+        },
+        // Old page stays visible while the next loads — no skeleton flash on
+        // page/sort changes (web-mojo needed careful fetch-event juggling for
+        // this; here it's one option).
+        placeholderData: keepPreviousData,
+        // Lets ModelTable hold the first request until persisted view state
+        // has been rehydrated into the URL (persistState).
+        enabled: opts.enabled !== false,
+    });
+}
+
+export function useModel<T>(endpoint: string, id: number | string | null, sanitizeRow?: (row: T) => T) {
+    return useQuery({
+        queryKey: [endpoint, 'one', id],
+        queryFn: async () => {
+            const row = await mojoGet<T>(endpoint, id!);
+            return sanitizeRow ? sanitizeRow(row) : row;
+        },
+        enabled: id != null,
+    });
+}
+
+/** Save mutation; invalidates every query for the endpoint on success. */
+export function useSaveModel<T>(endpoint: string) {
+    const qc = useQueryClient();
+    return useMutation({
+        mutationFn: ({ id, changes }: { id: number | string | null; changes: Record<string, unknown> }) =>
+            mojoSave<T>(endpoint, id, changes),
+        onSuccess: () => qc.invalidateQueries({ queryKey: [endpoint] }),
+    });
+}

package/src/client/index.ts

@@ -0,0 +1,37 @@
+// portal-mojo/client — the typed django-mojo protocol layer: envelope unwrap
+// (one boundary; a failed save REJECTS), start/size paging, '-field' sort,
+// Django lookups, the URL-synced table-params store, TanStack Query hooks,
+// and the auth client (password/magic/passkey flows, single-flight refresh,
+// pre-request gate, DUID). The in-memory mock transport (mock.ts) is internal
+// to client.ts — it is the wire contract's executable spec and evolves in
+// lockstep with the client.
+export * from './client';
+export * from './errors';
+export * from './model';
+export * from './auth';
+export * from './jwt';
+export * from './duid';
+export * from './me';
+export * from './group-context';
+export * from './group';
+export * from './hooks';
+export * from './params';
+export * from './lookups';
+export * from './location';
+export * from './markdown';
+export * from './record-feed';
+export * from './safe-export';
+export * from './upload';
+export * from './realtime';
+export * from './realtime-mock';
+export * from './types';
+// Dev affordance: per-endpoint call counts from the mock (single-flight proof).
+export {
+    armMockReauth, clearMockRequestHistory, getMockCallCounts,
+    getMockRequestHistory, setMockDnsConfigMalformed, setMockDnsAcmeMode, armMockDnsWriteFault,
+    getMockPhoneConfigCredentialState, getMockEffectivePhoneConfigId,
+    deleteMockPhoneGroupForTest,
+    setMockDnsRegistrarMode, armMockRegistrarPurchaseFault,
+    getMockPushConfigCredentialState,
+    armMockUploadFault, armMockRecordNoteFault, clearMockUploadObservations, getMockUploadObservations, setMockUploadMode,
+} from './mock';

package/src/client/jwt.ts

@@ -0,0 +1,75 @@
+// Client-side JWT inspection — decode only, NO signature verification (the
+// server is the authority; the client only needs expiry/identity hints).
+// Ported from web-mojo TokenManager's Token class.
+
+export interface JwtPayload {
+    uid?: string | number;
+    sub?: string | number;
+    user_id?: string | number;
+    email?: string;
+    name?: string;
+    username?: string;
+    exp?: number;
+    iat?: number;
+    [claim: string]: unknown;
+}
+
+/** Decode a JWT payload (URL-safe base64, padded). Null on any malformation. */
+export function decodeJwt(token: string | null | undefined): JwtPayload | null {
+    if (!token || typeof token !== 'string') return null;
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    try {
+        let base64 = parts[1]!.replace(/-/g, '+').replace(/_/g, '/');
+        const padding = 4 - (base64.length % 4);
+        if (padding !== 4) base64 += '='.repeat(padding);
+        return JSON.parse(atob(base64)) as JwtPayload;
+    } catch {
+        return null;
+    }
+}
+
+export interface JwtInfo {
+    raw: string;
+    payload: JwtPayload;
+    uid: string | null;
+    email: string | null;
+    name: string | null;
+    exp: Date | null;
+    iat: Date | null;
+    /** Decodable and (when an exp claim exists) not past it. No exp ⇒ valid. */
+    isValid: boolean;
+    isExpired: boolean;
+    expiringSoon(thresholdMinutes?: number): boolean;
+    /** Minutes since iat, or null when the claim is absent. */
+    ageMinutes(): number | null;
+}
+
+/** Inspect a token. Null when the token is missing or undecodable. */
+export function tokenInfo(token: string | null | undefined): JwtInfo | null {
+    const payload = decodeJwt(token);
+    if (!payload || !token) return null;
+    const nowSec = () => Math.floor(Date.now() / 1000);
+    const isExpired = payload.exp != null ? nowSec() >= payload.exp : false;
+    return {
+        raw: token,
+        payload,
+        uid: payload.uid != null ? String(payload.uid)
+            : payload.sub != null ? String(payload.sub)
+            : payload.user_id != null ? String(payload.user_id) : null,
+        email: payload.email ?? null,
+        name: payload.name ?? payload.username ?? null,
+        exp: payload.exp ? new Date(payload.exp * 1000) : null,
+        iat: payload.iat ? new Date(payload.iat * 1000) : null,
+        isValid: !isExpired,
+        isExpired,
+        expiringSoon(thresholdMinutes = 5) {
+            if (payload.exp == null) return false;
+            return payload.exp - nowSec() <= thresholdMinutes * 60;
+        },
+        ageMinutes() {
+            if (payload.iat == null) return null;
+            return Math.floor((nowSec() - payload.iat) / 60);
+        },
+    };
+}