@flow-industries/id 0.21.2 → 0.22.1

package/dist/sdk/client/create-flow.js

@@ -13,11 +13,8 @@ import { createStore, initialFlowState } from "./store";
  * see the result instead of racing it. Falls back to running `fn` directly
  * where Web Locks is unavailable.
  */
-function withOriginLock(name, fn) {
-    const locks = 
-    /* SAFETY: the SDK stashes its singleton on globalThis so two bundles of it share one
-     instance; the property is namespaced and written only here. */
-    globalThis.navigator?.locks;
+async function withOriginLock(name, fn) {
+    const locks = globalThis.navigator?.locks;
     if (locks?.request)
         return locks.request(name, fn);
     return fn();

package/dist/sdk/client/dialog-host.js

@@ -1,4 +1,4 @@
-import { bridgeToWindow, makeIframe } from "./iframe-host";
+import { bridgeToWindow, makeIframe, sendBridgeNotification, } from "./iframe-host";
 import { setOverlayFocus } from "./overlay-focus";
 const HIDDEN_STYLE = {
     position: "fixed",
@@ -106,7 +106,7 @@ export function createDialogHost(options) {
             return;
         initSent = true;
         // SAFETY: the payload map types this topic; the dialog reads exactly these fields.
-        messenger?.send("__internal", {
+        sendBridgeNotification(messenger, "__internal", {
             type: "init",
             mode: "iframe",
             referrer: opts?.referrer ?? { title: document.title },
@@ -124,7 +124,7 @@ export function createDialogHost(options) {
         // widget, so every dialog appears and disappears identically.
         void (
         // SAFETY: the payload map types this topic; the dialog reads exactly these fields.
-        messenger?.send("__internal", { type: "dialog-shown" }));
+        sendBridgeNotification(messenger, "__internal", { type: "dialog-shown" }));
     }
     function hide() {
         if (!iframe)
@@ -137,7 +137,7 @@ export function createDialogHost(options) {
         setOverlayFocus(iframe, false);
         void (
         // SAFETY: the payload map types this topic; the dialog reads exactly these fields.
-        messenger?.send("__internal", { type: "dialog-hidden" }));
+        sendBridgeNotification(messenger, "__internal", { type: "dialog-hidden" }));
     }
     function open(opts) {
         if (opts?.mode === "popup") {
@@ -177,9 +177,14 @@ export function createDialogHost(options) {
         return new Promise((resolve, reject) => {
             pending.set(id, { resolve, reject });
             // SAFETY: the rpc-requests payload shape.
-            messenger.send("rpc-requests", [
+            messenger
+                .send("rpc-requests", [
                 { request: rpcRequest, status: "pending" },
-            ]);
+            ])
+                .catch((error) => {
+                pending.delete(id);
+                reject(error);
+            });
         });
     }
     /** Opens the dialog UI and dispatches an interactive RPC (login, sign, etc.). */

package/dist/sdk/client/flow-widget.js

@@ -1,6 +1,6 @@
 import { resolveIdHost } from "../id-host";
 import { getFlow, requireFlow } from "./create-flow";
-import { answerTokenRequest, bridgeToWindow, makeIframe } from "./iframe-host";
+import { answerTokenRequest, bridgeToWindow, makeIframe, sendBridgeNotification, } from "./iframe-host";
 /**
  * The inline widgets an embedder may mount, mapped to the dialog routes that
  * serve them. Callers name a widget rather than passing a route so the dialog's
@@ -65,7 +65,7 @@ export function createFlowWidget(options) {
     // confirms where the frame is; what the handshake is really for is telling
     // the dialog which origin it is embedded by, which is what it later asks for
     // a token.
-    void bridge.send("__internal", {
+    sendBridgeNotification(bridge, "__internal", {
         type: "init",
         mode: "iframe",
         referrer: { title: document.title },
@@ -81,7 +81,7 @@ export function createFlowWidget(options) {
             if (next === theme)
                 return;
             theme = next;
-            void bridge.send("__internal", {
+            sendBridgeNotification(bridge, "__internal", {
                 type: "set-theme",
                 theme: { colorScheme: next },
             });

package/dist/sdk/client/focus-session.d.ts

@@ -0,0 +1,18 @@
+import type { ActiveAction, ClockAnchor, FocusSessionEvent, FocusSessionState } from "../types";
+/** A re-read only replaces the anchor when it moves the display by more than
+ * this, so request timing never makes the clock jitter. */
+export declare const REANCHOR_TOLERANCE_SECONDS = 2;
+export declare function anchorFor(active: ActiveAction, readAt: number): ClockAnchor;
+export declare function elapsedSeconds(anchor: ClockAnchor, now: number): number;
+/** Whether a fresh server sample should replace the current anchor: yes when
+ * the pause state flipped or the server disagrees with the extrapolated clock
+ * by more than the tolerance (another surface paused, a replaced session). */
+export declare function shouldReanchor(current: ClockAnchor, next: ActiveAction, now: number): boolean;
+/** `mm:ss`, rolling into `h:mm:ss` past an hour. */
+export declare function formatElapsed(seconds: number): string;
+export declare const INITIAL_FOCUS_STATE: FocusSessionState;
+export declare function focusSessionReducer(state: FocusSessionState, event: FocusSessionEvent): FocusSessionState;
+/** The pill and panel headline: "Meditate", or "Practice · Chinese" when a
+ * subject is attached. `fallback` covers a source the catalog no longer
+ * labels. */
+export declare function actionHeadline(action: Pick<ActiveAction, "label" | "source" | "subject">, fallback: string): string;

package/dist/sdk/client/focus-session.js

@@ -0,0 +1,140 @@
+/** A re-read only replaces the anchor when it moves the display by more than
+ * this, so request timing never makes the clock jitter. */
+export const REANCHOR_TOLERANCE_SECONDS = 2;
+export function anchorFor(active, readAt) {
+    return {
+        accruedSeconds: active.accruedSeconds,
+        paused: active.paused,
+        readAt,
+    };
+}
+export function elapsedSeconds(anchor, now) {
+    if (anchor.paused)
+        return anchor.accruedSeconds;
+    return anchor.accruedSeconds + Math.max(0, now - anchor.readAt) / 1000;
+}
+/** Whether a fresh server sample should replace the current anchor: yes when
+ * the pause state flipped or the server disagrees with the extrapolated clock
+ * by more than the tolerance (another surface paused, a replaced session). */
+export function shouldReanchor(current, next, now) {
+    if (current.paused !== next.paused)
+        return true;
+    return (Math.abs(elapsedSeconds(current, now) - next.accruedSeconds) >
+        REANCHOR_TOLERANCE_SECONDS);
+}
+/** `mm:ss`, rolling into `h:mm:ss` past an hour. */
+export function formatElapsed(seconds) {
+    const whole = Math.max(0, Math.floor(seconds));
+    const hours = Math.floor(whole / 3600);
+    const minutes = Math.floor((whole % 3600) / 60);
+    const secs = whole % 60;
+    const mmss = `${String(minutes).padStart(2, "0")}:${String(secs).padStart(2, "0")}`;
+    return hours > 0 ? `${hours}:${mmss}` : mmss;
+}
+export const INITIAL_FOCUS_STATE = {
+    phase: "unknown",
+    active: null,
+    anchor: null,
+    finished: null,
+    conflict: null,
+    busy: false,
+    failed: false,
+};
+function withActive(state, active, at) {
+    const sameSession = state.active?.sessionId === active.sessionId;
+    const anchor = sameSession && state.anchor && !shouldReanchor(state.anchor, active, at)
+        ? state.anchor
+        : anchorFor(active, at);
+    return {
+        ...state,
+        phase: "active",
+        active,
+        anchor,
+        conflict: null,
+        failed: false,
+    };
+}
+export function focusSessionReducer(state, event) {
+    switch (event.type) {
+        case "read": {
+            if (event.active === null) {
+                return {
+                    ...state,
+                    phase: "idle",
+                    active: null,
+                    anchor: null,
+                    failed: false,
+                };
+            }
+            return withActive(state, event.active, event.at);
+        }
+        case "read-failed":
+            return { ...state, failed: true };
+        case "request":
+            return { ...state, busy: true, failed: false };
+        case "request-failed":
+            return { ...state, busy: false, failed: true };
+        case "started":
+            return {
+                ...withActive(state, event.session, event.at),
+                anchor: anchorFor(event.session, event.at),
+                busy: false,
+                finished: null,
+            };
+        case "conflict":
+            return { ...state, busy: false, conflict: event.active };
+        case "paused": {
+            if (!state.active || !state.anchor)
+                return { ...state, busy: false };
+            const frozen = elapsedSeconds(state.anchor, event.at);
+            return {
+                ...state,
+                busy: false,
+                active: { ...state.active, paused: true, accruedSeconds: frozen },
+                anchor: { accruedSeconds: frozen, paused: true, readAt: event.at },
+            };
+        }
+        case "resumed": {
+            if (!state.active || !state.anchor)
+                return { ...state, busy: false };
+            return {
+                ...state,
+                busy: false,
+                active: { ...state.active, paused: false },
+                anchor: { ...state.anchor, paused: false, readAt: event.at },
+            };
+        }
+        case "finished": {
+            const finished = state.active
+                ? {
+                    source: state.active.source,
+                    label: state.active.label,
+                    subject: state.active.subject,
+                    xpGranted: event.result.xpGranted,
+                    durationSeconds: event.result.durationSeconds,
+                }
+                : null;
+            return {
+                ...state,
+                phase: "idle",
+                active: null,
+                anchor: null,
+                busy: false,
+                finished,
+            };
+        }
+        case "dismiss-finished":
+            return { ...state, finished: null };
+        case "dismiss-conflict":
+            return { ...state, conflict: null };
+        case "reset":
+            return INITIAL_FOCUS_STATE;
+    }
+}
+/** The pill and panel headline: "Meditate", or "Practice · Chinese" when a
+ * subject is attached. `fallback` covers a source the catalog no longer
+ * labels. */
+export function actionHeadline(action, fallback) {
+    const label = action.label ?? fallback;
+    return action.subject ? `${label} · ${action.subject.name}` : label;
+}

package/dist/sdk/client/focus.d.ts

@@ -0,0 +1,11 @@
+import type { FocusApi, UserActionSurface } from "../types";
+export type { ActionCatalogEntry, ActionCatalogResponse, ActionCurve, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActionTransitionKind, ActiveAction, CatalogFieldRef, ClockAnchor, CreateStudySubjectInput, FinishActionRequest, FinishActionResponse, FinishedSummary, FocusApi, FocusPhase, FocusSessionEvent, FocusSessionState, ListStudySessionsOptions, ListStudySubjectsOptions, StartActionResult, StartFocusRequest, StudyCatalog, StudyCategory, StudyField, StudyRange, StudySearchHit, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRemovalResponse, StudySubjectResponse, StudySummary, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, } from "../types";
+export { estimateActionXp, flowMultiplier } from "../xp/curve";
+export { ActionsRequestError, isActiveSessionConflict } from "./actions";
+export * from "./focus-session";
+export { StudyRequestError } from "./study";
+export * from "./study-search";
+export declare const MEDITATION_SOURCE = "game.action.meditation";
+export declare const STUDY_SOURCE = "action.study";
+/** Compose action and study requests using the host's credentials and surface. */
+export declare function createFocusApi(host: string, getToken: () => Promise<string | null>, surface: UserActionSurface): FocusApi;

package/dist/sdk/client/focus.js

@@ -0,0 +1,30 @@
+import { createActionsApi } from "./actions";
+import { createStudyApi } from "./study";
+export { estimateActionXp, flowMultiplier } from "../xp/curve";
+export { ActionsRequestError, isActiveSessionConflict } from "./actions";
+export * from "./focus-session";
+export { StudyRequestError } from "./study";
+export * from "./study-search";
+export const MEDITATION_SOURCE = "game.action.meditation";
+export const STUDY_SOURCE = "action.study";
+/** Compose action and study requests using the host's credentials and surface. */
+export function createFocusApi(host, getToken, surface) {
+    const actions = createActionsApi(host, getToken);
+    const study = createStudyApi(host, getToken);
+    return {
+        catalog: actions.catalog,
+        active: actions.me,
+        start(request) {
+            return actions.start({ ...request, surface });
+        },
+        event: actions.event,
+        finish: actions.finish,
+        studyCatalog: study.catalog,
+        subjects: study.subjects,
+        createSubject: study.createSubject,
+        updateSubject: study.updateSubject,
+        deleteSubject: study.deleteSubject,
+        summary: study.summary,
+        sessions: study.sessions,
+    };
+}

package/dist/sdk/client/iframe-host.d.ts

@@ -1,5 +1,5 @@
 import * as Messenger from "../dialog/remote/Messenger";
-import type { Flow, ProfileIdentity } from "../types";
+import type { Flow, Payload, ProfileIdentity, Topic } from "../types";
 /**
  * Permissions the dialog iframe needs to run WebAuthn passkey ceremonies and
  * copy recovery values. Shared by every Flow iframe host (the dialog host and
@@ -48,3 +48,4 @@ export declare function hostIdentity(flow: Flow): ProfileIdentity | null;
  * out — instead of leaving the request to time out.
  */
 export declare function answerTokenRequest(bridge: Messenger.Bridge, flow: Flow, id: string): Promise<void>;
+export declare function sendBridgeNotification<T extends Topic>(bridge: Messenger.Bridge | null | undefined, topic: T, payload: Payload<T>): void;

package/dist/sdk/client/iframe-host.js

@@ -71,5 +71,15 @@ export function hostIdentity(flow) {
  */
 export async function answerTokenRequest(bridge, flow, id) {
     const token = await flow.getToken().catch(() => null);
-    void bridge.send("__internal", { type: "profile-token", id, token });
+    sendBridgeNotification(bridge, "__internal", {
+        type: "profile-token",
+        id,
+        token,
+    });
+}
+export function sendBridgeNotification(bridge, topic, payload) {
+    void bridge?.send(topic, payload).catch((error) => {
+        if (!(error instanceof Messenger.BridgeDestroyedError))
+            throw error;
+    });
 }

package/dist/sdk/client/index.d.ts

@@ -1,13 +1,16 @@
 export { defaultIdHost, isLocalHostname } from "../id-host";
-export type { AccessKeyOptions, ActionCatalogEntry, ActionCatalogResponse, ActionCurve, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActionSurface, ActionsApi, ActionTransitionKind, ActiveActionResponse, ActiveSessionConflict, AdditionalSession, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, CreateStudySubjectInput, CurrentAction, DialogHost, FinishActionRequest, FinishActionResponse, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, ListStudySessionsOptions, ListStudySubjectsOptions, LoginOptions, MethodName, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, ProfileButtonHandle, ProfilePosition, RoomMemberEntry, Session, StartActionInput, StartActionResponse, StartActionResult, StudyApi, StudyCatalog, StudyCategory, StudyCategoryTotals, StudyField, StudyRange, StudySessionEntry, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRefusal, StudySubjectRemovalResponse, StudySubjectResponse, StudySubjectTotals, StudySummary, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, XpMode, } from "../types";
+export type { AccessKeyOptions, ActionCatalogEntry, ActionCatalogResponse, ActionCurve, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActionSurface, ActionsApi, ActionTransitionKind, ActiveAction, ActiveActionResponse, ActiveSessionConflict, AdditionalSession, Address, CatalogFieldRef, ClockAnchor, ConnectCapabilities, ConnectResponse, CreateFlowOptions, CreateStudySubjectInput, CurrentAction, DialogHost, FinishActionRequest, FinishActionResponse, FinishedSummary, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, FocusApi, FocusPhase, FocusSessionEvent, FocusSessionState, ListStudySessionsOptions, ListStudySubjectsOptions, LoginOptions, MethodName, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, ProfileButtonHandle, ProfilePosition, RoomMemberEntry, Session, StartActionInput, StartActionResponse, StartActionResult, StartFocusRequest, StudyApi, StudyCatalog, StudyCategory, StudyCategoryTotals, StudyField, StudyRange, StudySearchHit, StudySessionEntry, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRefusal, StudySubjectRemovalResponse, StudySubjectResponse, StudySubjectTotals, StudySummary, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, XpMode, } from "../types";
 export { consistencyCurve, estimateActionXp, FLOW_SCORE_MAX, flowMultiplier, } from "../xp/curve";
 export { ActionsRequestError, createActionsApi, isActiveSessionConflict, } from "./actions";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
+export { actionHeadline, anchorFor, catalogFieldIndex, createFocusApi, elapsedSeconds, fieldsCoveredBySubjects, focusSessionReducer, formatElapsed, hitLabel, INITIAL_FOCUS_STATE, MEDITATION_SOURCE, matchScore, normalizeSearchText, REANCHOR_TOLERANCE_SECONDS, recentSubjects, STUDY_SOURCE, searchStudy, shouldReanchor, } from "./focus";
 export { METHODS } from "./methods";
 export { closeProfile, openProfile } from "./open-profile";
 export { createProfileButton } from "./profile-button";
+export type { ReportOperation, ReportRequest, ReportResponse } from "./reports";
+export { createReportsApi, ReportRequestError } from "./reports";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
 export { createStaticFlow } from "./static-flow";
 export { createStudyApi, StudyRequestError } from "./study";

package/dist/sdk/client/index.js

@@ -4,9 +4,11 @@ export { ActionsRequestError, createActionsApi, isActiveSessionConflict, } from
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
+export { actionHeadline, anchorFor, catalogFieldIndex, createFocusApi, elapsedSeconds, fieldsCoveredBySubjects, focusSessionReducer, formatElapsed, hitLabel, INITIAL_FOCUS_STATE, MEDITATION_SOURCE, matchScore, normalizeSearchText, REANCHOR_TOLERANCE_SECONDS, recentSubjects, STUDY_SOURCE, searchStudy, shouldReanchor, } from "./focus";
 export { METHODS } from "./methods";
 export { closeProfile, openProfile } from "./open-profile";
 export { createProfileButton } from "./profile-button";
+export { createReportsApi, ReportRequestError } from "./reports";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
 export { createStaticFlow } from "./static-flow";
 export { createStudyApi, StudyRequestError } from "./study";

package/dist/sdk/client/json-api.d.ts

@@ -18,7 +18,7 @@ export type JsonApiError = (status: number, message: string, reason?: string) =>
  * raw status and payload for the few responses a client treats as values (a
  * start's 409); `request` is the common path that throws on any non-2xx.
  */
-export declare function createJsonApi(host: string, prefix: string, getToken: () => Promise<string | null>, makeError: JsonApiError): {
+export declare function createJsonApi(host: string, prefix: string, getToken: () => Promise<string | null>, makeError: JsonApiError, mapFailure?: (exchange: JsonExchange) => Error): {
     exchange: (path: string, options?: JsonRequestOptions) => Promise<JsonExchange>;
     request: <T>(path: string, options?: JsonRequestOptions) => Promise<T>;
     failure: (exchange: JsonExchange) => Error;

package/dist/sdk/client/json-api.js

@@ -11,10 +11,12 @@ const failureSchema = z.object({
  * raw status and payload for the few responses a client treats as values (a
  * start's 409); `request` is the common path that throws on any non-2xx.
  */
-export function createJsonApi(host, prefix, getToken, makeError) {
+export function createJsonApi(host, prefix, getToken, makeError, mapFailure) {
     /** The error a non-2xx exchange throws: the route's own wording when it
      * sent one, and its machine code as `reason`. */
     function failure(exchange) {
+        if (mapFailure)
+            return mapFailure(exchange);
         const parsed = failureSchema.safeParse(exchange.payload);
         const { error, reason } = parsed.success ? parsed.data : {};
         return makeError(exchange.status, error ?? `Request failed (${exchange.status})`, reason ?? error);

package/dist/sdk/client/open-profile.js

@@ -1,7 +1,7 @@
 import { resolveIdHost } from "../id-host";
 import { isValidUsername } from "../usernames";
 import { getFlow, requireFlow } from "./create-flow";
-import { answerTokenRequest, bridgeToWindow, hostIdentity, makeIframe, OVERLAY_STYLE, } from "./iframe-host";
+import { answerTokenRequest, bridgeToWindow, hostIdentity, makeIframe, OVERLAY_STYLE, sendBridgeNotification, } from "./iframe-host";
 import { setOverlayFocus } from "./overlay-focus";
 // One overlay per page, kept for the page's lifetime. The alternative — a
 // handle per call site — would put a second fullscreen iframe over the host the
@@ -47,7 +47,7 @@ function createViewer(options) {
         // `/dialog/` and `init` asks it to land on the profile. Sending the route
         // here rather than as a follow-up message keeps the sign-in root from ever
         // mounting, even for the frame it takes to navigate away from it.
-        void opened.send("__internal", {
+        sendBridgeNotification(opened, "__internal", {
             type: "init",
             mode: "iframe",
             referrer: { title: document.title },
@@ -90,11 +90,14 @@ function createViewer(options) {
         // re-pointed in place. Tearing it down and rebuilding would reload the
         // dialog and lose the open animation on every profile after the first.
         if (mounted)
-            void live.send("__internal", { type: "profile-view", username });
+            sendBridgeNotification(live, "__internal", {
+                type: "profile-view",
+                username,
+            });
         // Pushed on every open rather than tracked with a subscription: it is only
         // read while a profile is on screen, and sending it here means the "this is
         // you" link is decided from the session as it stands at that moment.
-        void live.send("__internal", {
+        sendBridgeNotification(live, "__internal", {
             type: "profile-identity",
             identity: hostIdentity(flow),
         });
@@ -102,7 +105,7 @@ function createViewer(options) {
         onClose = nextOnClose;
         visible = true;
         applyHitTesting();
-        void live.send("__internal", { type: "dialog-shown" });
+        sendBridgeNotification(live, "__internal", { type: "dialog-shown" });
     }
     // Visibility is hit-testing plus a message, and nothing else. The overlay
     // iframe is NEVER set to `display: none` — that pauses the iframe's
@@ -116,7 +119,7 @@ function createViewer(options) {
         visible = false;
         window.removeEventListener("keydown", onKeyDown);
         applyHitTesting();
-        void bridge.send("__internal", { type: "dialog-hidden" });
+        sendBridgeNotification(bridge, "__internal", { type: "dialog-hidden" });
         const notifyClose = onClose;
         onClose = undefined;
         notifyClose?.();
@@ -131,7 +134,7 @@ function createViewer(options) {
         if (next === theme)
             return;
         theme = next;
-        void bridge?.send("__internal", {
+        sendBridgeNotification(bridge, "__internal", {
             type: "set-theme",
             theme: { colorScheme: next },
         });

package/dist/sdk/client/profile-button.js

@@ -1,6 +1,6 @@
 import { resolveIdHost } from "../id-host";
 import { getFlow, requireFlow } from "./create-flow";
-import { answerTokenRequest, bridgeToWindow, hostIdentity, makeIframe, OVERLAY_STYLE, } from "./iframe-host";
+import { answerTokenRequest, bridgeToWindow, hostIdentity, makeIframe, OVERLAY_STYLE, sendBridgeNotification, } from "./iframe-host";
 import { setOverlayFocus } from "./overlay-focus";
 const POSITION_STYLE = {
     "top-right": { top: "0", right: "0" },
@@ -62,7 +62,7 @@ export function createProfileButton(options) {
         const bridge = bridgeToWindow(frame.contentWindow, {
             targetOrigin: hostOrigin,
         });
-        bridge.send("__internal", {
+        sendBridgeNotification(bridge, "__internal", {
             type: "init",
             mode: "iframe",
             referrer: { title: document.title },
@@ -130,7 +130,7 @@ export function createProfileButton(options) {
                     void answerTokenRequest(dialogBridge, flow, payload.id);
             }
         });
-        void dialogBridge.send("__internal", {
+        sendBridgeNotification(dialogBridge, "__internal", {
             type: "profile-identity",
             identity: hostIdentity(flow),
         });
@@ -147,14 +147,18 @@ export function createProfileButton(options) {
             return;
         dialog.style.pointerEvents = "auto";
         setOverlayFocus(dialog, true);
-        void dialogBridge?.send("__internal", { type: "dialog-shown" });
+        sendBridgeNotification(dialogBridge, "__internal", {
+            type: "dialog-shown",
+        });
     }
     function hideDialog() {
         if (!dialog)
             return;
         dialog.style.pointerEvents = "none";
         setOverlayFocus(dialog, false);
-        void dialogBridge?.send("__internal", { type: "dialog-hidden" });
+        sendBridgeNotification(dialogBridge, "__internal", {
+            type: "dialog-hidden",
+        });
     }
     // ----- keep both iframes' identity in sync with the Flow session -----
     // flow.subscribe fires on any store change (jwt/credential/address too), so
@@ -166,9 +170,12 @@ export function createProfileButton(options) {
         if (key === lastIdentityKey)
             return;
         lastIdentityKey = key;
-        void pillBridge.send("__internal", { type: "profile-identity", identity });
+        sendBridgeNotification(pillBridge, "__internal", {
+            type: "profile-identity",
+            identity,
+        });
         if (dialogBridge)
-            void dialogBridge.send("__internal", {
+            sendBridgeNotification(dialogBridge, "__internal", {
                 type: "profile-identity",
                 identity,
             });
@@ -180,11 +187,11 @@ export function createProfileButton(options) {
             if (next === theme)
                 return;
             theme = next;
-            void pillBridge.send("__internal", {
+            sendBridgeNotification(pillBridge, "__internal", {
                 type: "set-theme",
                 theme: { colorScheme: next },
             });
-            void dialogBridge?.send("__internal", {
+            sendBridgeNotification(dialogBridge, "__internal", {
                 type: "set-theme",
                 theme: { colorScheme: next },
             });

package/dist/sdk/client/reports.d.ts

@@ -0,0 +1,9 @@
+import type { ReportsApi, ReportTransport } from "../types/reports";
+export type { ReportOperation, ReportRequest, ReportResponse, } from "../types/reports";
+export declare class ReportRequestError extends Error {
+    readonly status: number;
+    readonly response: string;
+    constructor(status: number, response: string);
+}
+/** Typed service reports. Keep the reporting bearer on trusted servers only. */
+export declare function createReportsApi(host: string, token: string, transport?: ReportTransport): ReportsApi;

package/dist/sdk/client/reports.js

@@ -0,0 +1,30 @@
+import { httpOperations } from "../contracts/http";
+export class ReportRequestError extends Error {
+    status;
+    response;
+    constructor(status, response) {
+        super(`Flow report failed (${status})`);
+        this.status = status;
+        this.response = response;
+        this.name = "ReportRequestError";
+    }
+}
+/** Typed service reports. Keep the reporting bearer on trusted servers only. */
+export function createReportsApi(host, token, transport = fetch) {
+    return async function report(operation, body) {
+        const contract = httpOperations[operation];
+        const request = contract.request.parse(body);
+        const response = await transport(new URL(contract.path, host), {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok)
+            throw new ReportRequestError(response.status, await response.text());
+        // SAFETY: the selected operation owns both this response schema and the mapped response type.
+        return contract.response.parse(await response.json());
+    };
+}

package/dist/sdk/client/rooms.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { createJsonApi } from "./json-api";
 /** Every rooms endpoint answers a failure as `{ error, reason? }`. */
 const failureSchema = z.object({
     error: z.string().optional(),
@@ -22,32 +23,12 @@ export class RoomsRequestError extends Error {
  * bearer and fail fast with a 401-shaped error when no session exists.
  */
 export function createRoomsApi(host, getToken) {
-    async function request(path, options = {}) {
-        const headers = {};
-        const token = await getToken();
-        if (token)
-            headers.Authorization = `Bearer ${token}`;
-        else if (options.authRequired) {
-            throw new RoomsRequestError(401, "Sign in first");
-        }
-        if (options.body !== undefined)
-            headers["Content-Type"] = "application/json";
-        const res = await fetch(`${host}/api/rooms${path}`, {
-            method: options.method ?? "GET",
-            headers,
-            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
-        });
-        const payload = await res.json().catch(() => ({}));
-        if (!res.ok) {
-            const failure = failureSchema.safeParse(payload);
-            throw new RoomsRequestError(res.status, failure.success && failure.data.error
-                ? failure.data.error
-                : `Rooms request failed (${res.status})`, failure.success ? failure.data.reason : undefined);
-        }
-        /* SAFETY: each caller names the response type of the rooms endpoint it just called; a
-           non-ok status has already thrown above with the server's own wording. */
-        return payload;
-    }
+    const { request } = createJsonApi(host, "/api/rooms", getToken, (status, message, reason) => new RoomsRequestError(status, message, reason), ({ status, payload }) => {
+        const parsed = failureSchema.safeParse(payload);
+        return new RoomsRequestError(status, parsed.success && parsed.data.error
+            ? parsed.data.error
+            : `Rooms request failed (${status})`, parsed.success ? parsed.data.reason : undefined);
+    });
     const slugPath = (slug) => `/${encodeURIComponent(slug)}`;
     const act = (slug, action, body) => request(`${slugPath(slug)}/${action}`, {
         method: "POST",

package/dist/sdk/client/study-search.d.ts

@@ -0,0 +1,20 @@
+import type { CatalogFieldRef, StudyCatalog, StudySearchHit, StudySubject } from "../types";
+export declare function normalizeSearchText(text: string): string;
+/** 4 exact, 3 prefix, 2 a later word's prefix, 1 substring, 0 no match.
+ * Both sides are normalized here so callers can pass raw labels. */
+export declare function matchScore(query: string, candidate: string): number;
+export declare function catalogFieldIndex(catalog: StudyCatalog): Map<string, CatalogFieldRef>;
+/** Live subjects newest-used first; auth stamps `lastUsedAt` at creation, so
+ * a subject never studied sorts by when it was added. */
+export declare function recentSubjects(subjects: readonly StudySubject[], limit?: number): StudySubject[];
+/** Catalog fields the user already keeps under the field's own name are
+ * hidden from results — the subject hit covers them and picking the field
+ * again would only re-create the same subject. A renamed subject ("Math for
+ * my test" under Algebra) leaves the field visible for a second subject. */
+export declare function fieldsCoveredBySubjects(subjects: readonly StudySubject[], index: Map<string, CatalogFieldRef>): Set<string>;
+export declare function searchStudy(query: string, options: {
+    catalog: StudyCatalog;
+    subjects: readonly StudySubject[];
+    limit?: number;
+}): StudySearchHit[];
+export declare function hitLabel(hit: StudySearchHit): string;