@flow-industries/id 0.19.4 → 0.21.0

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

@@ -0,0 +1,20 @@
+import type { ActionsApi, ActiveSessionConflict, StartActionResult } from "../types";
+/** Thrown on any non-2xx actions response other than a start's 409;
+ * `reason` carries the route's machine-readable code (`rate_limited`,
+ * `not_found`, `subject_required`, ...). */
+export declare class ActionsRequestError extends Error {
+    readonly status: number;
+    readonly reason?: string | undefined;
+    constructor(status: number, message: string, reason?: string | undefined);
+}
+/** Whether a start collided with a running session instead of opening one. */
+export declare function isActiveSessionConflict(result: StartActionResult): result is ActiveSessionConflict;
+/**
+ * Thin typed client for the caller's own action sessions, bound to a host and
+ * the Flow token supplier — the `createRoomsApi` pattern. The catalog is
+ * public; everything under `/me` attaches the caller's bearer and fails fast
+ * with a 401-shaped error when no session exists. A start that collides with
+ * a running session resolves to the conflict rather than throwing, because a
+ * "switch?" prompt is the ordinary next step, not a fault.
+ */
+export declare function createActionsApi(host: string, getToken: () => Promise<string | null>): ActionsApi;

package/dist/sdk/client/actions.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { createJsonApi } from "./json-api";
+/** Thrown on any non-2xx actions response other than a start's 409;
+ * `reason` carries the route's machine-readable code (`rate_limited`,
+ * `not_found`, `subject_required`, ...). */
+export class ActionsRequestError extends Error {
+    status;
+    reason;
+    constructor(status, message, reason) {
+        super(message);
+        this.status = status;
+        this.reason = reason;
+        this.name = "ActionsRequestError";
+    }
+}
+const conflictSchema = z.object({
+    error: z.literal("active_session"),
+    active: z.object({ sessionId: z.string() }).loose(),
+});
+/** Whether a start collided with a running session instead of opening one. */
+export function isActiveSessionConflict(result) {
+    return "error" in result && result.error === "active_session";
+}
+/**
+ * Thin typed client for the caller's own action sessions, bound to a host and
+ * the Flow token supplier — the `createRoomsApi` pattern. The catalog is
+ * public; everything under `/me` attaches the caller's bearer and fails fast
+ * with a 401-shaped error when no session exists. A start that collides with
+ * a running session resolves to the conflict rather than throwing, because a
+ * "switch?" prompt is the ordinary next step, not a fault.
+ */
+export function createActionsApi(host, getToken) {
+    const api = createJsonApi(host, "/api/actions", getToken, (status, message, reason) => new ActionsRequestError(status, message, reason));
+    return {
+        catalog: () => api.request("/catalog"),
+        me: () => api.request("/me", { authRequired: true }),
+        async start(input) {
+            const body = {
+                ...input,
+                sessionId: input.sessionId ?? crypto.randomUUID(),
+            };
+            const result = await api.exchange("/me/start", {
+                method: "POST",
+                body,
+                authRequired: true,
+            });
+            if (result.status === 409 &&
+                conflictSchema.safeParse(result.payload).success) {
+                /* SAFETY: the schema just confirmed the 409 body is the active_session conflict. */
+                return result.payload;
+            }
+            if (!result.ok)
+                throw api.failure(result);
+            /* SAFETY: a 2xx from /me/start is the { session } envelope. */
+            return result.payload;
+        },
+        event: (request) => api.request("/me/event", {
+            method: "POST",
+            body: request,
+            authRequired: true,
+        }),
+        finish: (request) => api.request("/me/finish", {
+            method: "POST",
+            body: request,
+            authRequired: true,
+        }),
+    };
+}

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

@@ -1,5 +1,7 @@
 export { defaultIdHost, isLocalHostname } from "../id-host";
-export type { AccessKeyOptions, AdditionalSession, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, LoginOptions, MethodName, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, ProfileButtonHandle, ProfilePosition, Session, } from "../types";
+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 { 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";
@@ -8,3 +10,4 @@ export { closeProfile, openProfile } from "./open-profile";
 export { createProfileButton } from "./profile-button";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
 export { createStaticFlow } from "./static-flow";
+export { createStudyApi, StudyRequestError } from "./study";

package/dist/sdk/client/index.js

@@ -1,4 +1,6 @@
 export { defaultIdHost, isLocalHostname } from "../id-host";
+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";
@@ -7,3 +9,4 @@ export { closeProfile, openProfile } from "./open-profile";
 export { createProfileButton } from "./profile-button";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
 export { createStaticFlow } from "./static-flow";
+export { createStudyApi, StudyRequestError } from "./study";

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

@@ -0,0 +1,25 @@
+export type JsonRequestOptions = {
+    method?: "GET" | "POST" | "PATCH" | "DELETE";
+    body?: unknown;
+    /** Fail fast with a 401-shaped error when the caller has no token, instead
+     * of spending a request the server is going to refuse. */
+    authRequired?: boolean;
+};
+export type JsonExchange = {
+    ok: boolean;
+    status: number;
+    /** The decoded JSON body, or `{}` when there was none to decode. */
+    payload: unknown;
+};
+export type JsonApiError = (status: number, message: string, reason?: string) => Error;
+/**
+ * The transport under the typed clients: one host, one route prefix, the Flow
+ * token supplier, and the error class a client throws. `exchange` returns the
+ * 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): {
+    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

@@ -0,0 +1,51 @@
+import { z } from "zod";
+/** Every first-party JSON route answers a failure as `{ error, reason? }`;
+ * for the actions and study routes `error` is itself the machine code. */
+const failureSchema = z.object({
+    error: z.string().optional(),
+    reason: z.string().optional(),
+});
+/**
+ * The transport under the typed clients: one host, one route prefix, the Flow
+ * token supplier, and the error class a client throws. `exchange` returns the
+ * 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) {
+    /** 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) {
+        const parsed = failureSchema.safeParse(exchange.payload);
+        const { error, reason } = parsed.success ? parsed.data : {};
+        return makeError(exchange.status, error ?? `Request failed (${exchange.status})`, reason ?? error);
+    }
+    async function exchange(path, options = {}) {
+        const headers = {};
+        const token = await getToken();
+        if (token) {
+            headers.Authorization = `Bearer ${token}`;
+        }
+        else if (options.authRequired) {
+            throw makeError(401, "Sign in first");
+        }
+        if (options.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(`${host}${prefix}${path}`, {
+            method: options.method ?? "GET",
+            headers,
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        });
+        const payload = await res.json().catch(() => ({}));
+        return { ok: res.ok, status: res.status, payload };
+    }
+    async function request(path, options = {}) {
+        const result = await exchange(path, options);
+        if (!result.ok)
+            throw failure(result);
+        /* SAFETY: each caller names the response type of the route it just called; a
+           non-ok status has already thrown above with the server's own wording. */
+        return result.payload;
+    }
+    return { exchange, request, failure };
+}

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

@@ -0,0 +1,17 @@
+import type { StudyApi } from "../types";
+/** Thrown on any non-2xx study response; `reason` carries the route's
+ * machine-readable code (`name_taken`, `subject_limit`, `field_unknown`,
+ * `not_found`, ...). */
+export declare class StudyRequestError extends Error {
+    readonly status: number;
+    readonly reason?: string | undefined;
+    constructor(status: number, message: string, reason?: string | undefined);
+}
+/**
+ * Thin typed client for the study catalog, the caller's study subjects and
+ * their finished study time, bound to a host and the Flow token supplier. The
+ * catalog is public and long-cached by the browser; every other route attaches
+ * the caller's bearer and fails fast with a 401-shaped error when no session
+ * exists.
+ */
+export declare function createStudyApi(host: string, getToken: () => Promise<string | null>): StudyApi;

package/dist/sdk/client/study.js

@@ -0,0 +1,55 @@
+import { createJsonApi } from "./json-api";
+/** Thrown on any non-2xx study response; `reason` carries the route's
+ * machine-readable code (`name_taken`, `subject_limit`, `field_unknown`,
+ * `not_found`, ...). */
+export class StudyRequestError extends Error {
+    status;
+    reason;
+    constructor(status, message, reason) {
+        super(message);
+        this.status = status;
+        this.reason = reason;
+        this.name = "StudyRequestError";
+    }
+}
+/**
+ * Thin typed client for the study catalog, the caller's study subjects and
+ * their finished study time, bound to a host and the Flow token supplier. The
+ * catalog is public and long-cached by the browser; every other route attaches
+ * the caller's bearer and fails fast with a 401-shaped error when no session
+ * exists.
+ */
+export function createStudyApi(host, getToken) {
+    const api = createJsonApi(host, "/api/study", getToken, (status, message, reason) => new StudyRequestError(status, message, reason));
+    const subjectPath = (id) => `/subjects/${encodeURIComponent(id)}`;
+    return {
+        catalog: () => api.request("/catalog"),
+        subjects: (options) => api.request(options?.archived ? "/subjects?archived=1" : "/subjects", { authRequired: true }),
+        createSubject: (input) => api.request("/subjects", {
+            method: "POST",
+            body: input,
+            authRequired: true,
+        }),
+        updateSubject: (id, patch) => api.request(subjectPath(id), {
+            method: "PATCH",
+            body: patch,
+            authRequired: true,
+        }),
+        deleteSubject: (id) => api.request(subjectPath(id), {
+            method: "DELETE",
+            authRequired: true,
+        }),
+        summary: (range) => api.request(`/summary?${new URLSearchParams({ range: range ?? "today" })}`, { authRequired: true }),
+        sessions: (options) => {
+            const params = new URLSearchParams({ subject: options.subject });
+            if (options.before !== undefined)
+                params.set("before", options.before);
+            if (options.limit !== undefined) {
+                params.set("limit", String(options.limit));
+            }
+            return api.request(`/sessions?${params}`, {
+                authRequired: true,
+            });
+        },
+    };
+}

package/dist/sdk/driver-error.d.ts

@@ -6,3 +6,6 @@
 /** Reads a named string field off a driver error. */
 export declare function errField(cause: unknown, key: string): string;
 export declare function errCause(cause: unknown): object | undefined;
+/** Whether a driver error is Postgres's unique_violation (23505), read off the
+ * error itself or the cause a query wrapper nests it under. */
+export declare function isUniqueViolation(cause: unknown): boolean;

package/dist/sdk/driver-error.js

@@ -15,3 +15,9 @@ export function errCause(cause) {
     const value = Object.entries(Object(cause)).find(([k]) => k === "cause")?.[1];
     return isObject(value) ? value : undefined;
 }
+/** Whether a driver error is Postgres's unique_violation (23505), read off the
+ * error itself or the cause a query wrapper nests it under. */
+export function isUniqueViolation(cause) {
+    return (errField(cause, "code") === "23505" ||
+        errField(errCause(cause), "code") === "23505");
+}

package/dist/sdk/react/active-action.d.ts

@@ -0,0 +1,14 @@
+import type { ActiveActionState, UseActiveActionOptions } from "../types";
+/**
+ * The caller's running action session, kept current without polling: it is
+ * read from `GET /api/actions/me` on mount, whenever the tab becomes visible
+ * again, after this hook's own `start`/`event`/`finish`, and on `refresh()`.
+ * Between reads the clock runs locally from the server's `accruedSeconds`, so
+ * a reload mid-session recovers the right time and a paused session stands
+ * still. Signed-out callers read as idle rather than as an error.
+ *
+ * ```tsx
+ * const { active, elapsedSeconds, start, finish } = useActiveAction();
+ * ```
+ */
+export declare function useActiveAction(options?: UseActiveActionOptions): ActiveActionState;

package/dist/sdk/react/active-action.js

@@ -0,0 +1,124 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ActionsRequestError, createActionsApi, isActiveSessionConflict, } from "../client/actions";
+import { useFlow } from "./hooks";
+function asError(cause) {
+    return cause instanceof Error ? cause : new Error(String(cause));
+}
+function elapsedFromAnchor(anchor, now) {
+    if (anchor.paused)
+        return anchor.accrued;
+    return anchor.accrued + (now - anchor.at) / 1000;
+}
+/**
+ * The caller's running action session, kept current without polling: it is
+ * read from `GET /api/actions/me` on mount, whenever the tab becomes visible
+ * again, after this hook's own `start`/`event`/`finish`, and on `refresh()`.
+ * Between reads the clock runs locally from the server's `accruedSeconds`, so
+ * a reload mid-session recovers the right time and a paused session stands
+ * still. Signed-out callers read as idle rather than as an error.
+ *
+ * ```tsx
+ * const { active, elapsedSeconds, start, finish } = useActiveAction();
+ * ```
+ */
+export function useActiveAction(options = {}) {
+    const flow = useFlow();
+    const host = options.host ?? flow.host;
+    const api = useMemo(() => createActionsApi(host, flow.getToken), [host, flow]);
+    const [active, setActive] = useState(null);
+    const [elapsedSeconds, setElapsedSeconds] = useState(0);
+    const [loaded, setLoaded] = useState(false);
+    const [error, setError] = useState(null);
+    const anchor = useRef(null);
+    const activeId = useRef(null);
+    // Bumped by every adoption, so a read that was in flight when a start or
+    // finish answered cannot land afterwards and resurrect the older state.
+    const generation = useRef(0);
+    const adopt = useCallback((next) => {
+        generation.current += 1;
+        anchor.current = next
+            ? { accrued: next.accruedSeconds, at: Date.now(), paused: next.paused }
+            : null;
+        activeId.current = next?.sessionId ?? null;
+        setActive(next);
+        setElapsedSeconds(next?.accruedSeconds ?? 0);
+    }, []);
+    const refresh = useCallback(async () => {
+        const ticket = generation.current;
+        try {
+            const next = await api.me();
+            if (ticket !== generation.current)
+                return;
+            adopt(next);
+            setError(null);
+        }
+        catch (cause) {
+            if (ticket !== generation.current)
+                return;
+            if (cause instanceof ActionsRequestError && cause.status === 401) {
+                adopt(null);
+                setError(null);
+            }
+            else {
+                setError(asError(cause));
+            }
+        }
+        finally {
+            setLoaded(true);
+        }
+    }, [api, adopt]);
+    useEffect(() => {
+        void refresh();
+        const onVisibility = () => {
+            if (document.visibilityState === "visible")
+                void refresh();
+        };
+        document.addEventListener("visibilitychange", onVisibility);
+        return () => document.removeEventListener("visibilitychange", onVisibility);
+    }, [refresh]);
+    // A render clock, not a poll: one local tick per second while the session's
+    // clock runs, and nothing at all while it is paused or idle.
+    const running = active !== null && !active.paused;
+    useEffect(() => {
+        if (!running)
+            return;
+        const tick = () => {
+            const a = anchor.current;
+            if (a)
+                setElapsedSeconds(elapsedFromAnchor(a, Date.now()));
+        };
+        const timer = setInterval(tick, 1000);
+        return () => clearInterval(timer);
+    }, [running]);
+    const start = useCallback(async (input) => {
+        const result = await api.start(input);
+        if (!isActiveSessionConflict(result))
+            adopt(result.session);
+        return result;
+    }, [api, adopt]);
+    const event = useCallback(async (request) => {
+        const response = await api.event(request);
+        // Whether the clock stopped is the server's derivation from the event
+        // log, so a pause or resume re-reads rather than guessing.
+        if (request.kind === "pause" || request.kind === "resume") {
+            await refresh();
+        }
+        return response;
+    }, [api, refresh]);
+    const finish = useCallback(async (request) => {
+        const response = await api.finish(request);
+        if (activeId.current === request.sessionId)
+            adopt(null);
+        return response;
+    }, [api, adopt]);
+    return {
+        active,
+        elapsedSeconds,
+        loading: !loaded,
+        error,
+        refresh,
+        start,
+        event,
+        finish,
+    };
+}

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

@@ -1,4 +1,5 @@
-export type { FlowIdProviderProps, FlowWidgetProps, ProfileButtonProps, UseOpenProfileOptions, } from "../types";
+export type { ActiveActionState, FlowIdProviderProps, FlowWidgetProps, ProfileButtonProps, UseActiveActionOptions, UseOpenProfileOptions, } from "../types";
+export { useActiveAction } from "./active-action";
 export { FlowWidget } from "./flow-widget";
 export { useFlow, useFlowId, useFlowState, useRoom, useRooms } from "./hooks";
 export { useOpenProfile } from "./open-profile";

package/dist/sdk/react/index.js

@@ -1,3 +1,4 @@
+export { useActiveAction } from "./active-action";
 export { FlowWidget } from "./flow-widget";
 export { useFlow, useFlowId, useFlowState, useRoom, useRooms } from "./hooks";
 export { useOpenProfile } from "./open-profile";

package/dist/sdk/types/actions.d.ts

@@ -0,0 +1,108 @@
+/** The SDK-side contract for actions and study: what `createActionsApi`,
+ * `createStudyApi` and `useActiveAction` take and return. The wire shapes
+ * themselves live in `./xp` and `./study`; this file only names the client
+ * inputs and the composed results a consumer app programs against. */
+import type { CreateStudySubjectInput, StudyCatalog, StudyRange, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRemovalResponse, StudySummary, UpdateStudySubjectInput } from "./study";
+import type { ActionCatalogEntry, ActionCatalogResponse, ActionTransitionKind, ActiveActionResponse, ActiveSessionConflict, FinishActionResponse, StartActionResponse, UserActionSurface } from "./xp";
+/** The curve parameters `estimateActionXp` reads. A catalog entry satisfies
+ * it, and so does the server's own registry descriptor, so the widget and a
+ * consumer app estimate from the same function without a conversion. */
+export type ActionCurve = Pick<ActionCatalogEntry, "mode" | "base" | "tauMinutes" | "dailyCapXp" | "minDurationSeconds" | "flowMultiplier">;
+/** What a live estimate is computed from: the running session's elapsed time
+ * plus the day context `GET /api/actions/me` carries. */
+export interface XpEstimateContext {
+    elapsedSeconds: number;
+    /** Minutes already credited to this source today, so a day-cumulative curve
+     * starts from the right point. */
+    priorMinutes: number;
+    flowScore: number;
+}
+/** Body of POST /api/actions/me/start as the SDK takes it. `sessionId` is the
+ * client-minted idempotency key for the whole session; the client mints a UUID
+ * when it is omitted. */
+export interface StartActionInput {
+    source: string;
+    sessionId?: string;
+    subjectId?: string;
+    /** Recorded as `metadata.surface`; defaults to `web` on the server. */
+    surface?: UserActionSurface;
+    /** Finish and grant the running session before starting this one. */
+    replace?: boolean;
+}
+/** A start either opened (or replayed) a session or collided with a running
+ * one. The 409 is a value, not an error: the UI's next step is a "switch?"
+ * prompt, not an error state. */
+export type StartActionResult = StartActionResponse | ActiveSessionConflict;
+/** Body of POST /api/actions/me/event. */
+export interface ActionEventRequest {
+    sessionId: string;
+    kind: ActionTransitionKind;
+}
+/** Response of POST /api/actions/me/event. `recorded` is false when the
+ * transition was a no-op (pausing a paused session, a second focus_lost). */
+export interface ActionEventResponse {
+    ok: true;
+    recorded: boolean;
+}
+/** Body of POST /api/actions/me/finish. */
+export interface FinishActionRequest {
+    sessionId: string;
+}
+/** Typed client for the caller's own action sessions and the public catalog. */
+export interface ActionsApi {
+    catalog(): Promise<ActionCatalogResponse>;
+    /** The caller's running session, or null when idle. */
+    me(): Promise<ActiveActionResponse | null>;
+    start(input: StartActionInput): Promise<StartActionResult>;
+    event(request: ActionEventRequest): Promise<ActionEventResponse>;
+    finish(request: FinishActionRequest): Promise<FinishActionResponse>;
+}
+export interface ListStudySubjectsOptions {
+    /** Include archived subjects after the live ones. */
+    archived?: boolean;
+}
+/** Query of GET /api/study/sessions as the SDK takes it: one subject's
+ * finished sessions, newest first. Feed a page's `nextBefore` back as
+ * `before` until it is null. */
+export interface ListStudySessionsOptions {
+    /** The subject's id; an archived subject is readable too. */
+    subject: string;
+    /** ISO instant; only sessions started strictly before it are listed. */
+    before?: string;
+    /** 1..100; the server defaults to 50. */
+    limit?: number;
+}
+/** Envelope of every single-subject study route. */
+export interface StudySubjectResponse {
+    subject: StudySubject;
+}
+/** Typed client for the study catalog and the caller's study subjects. */
+export interface StudyApi {
+    catalog(): Promise<StudyCatalog>;
+    subjects(options?: ListStudySubjectsOptions): Promise<StudySubjectList>;
+    createSubject(input: CreateStudySubjectInput): Promise<StudySubjectResponse>;
+    updateSubject(id: string, patch: UpdateStudySubjectInput): Promise<StudySubjectResponse>;
+    deleteSubject(id: string): Promise<StudySubjectRemovalResponse>;
+    /** Finished study time per subject and category; `range` defaults to
+     * `today`. The running session is absent: add `/api/actions/me` live. */
+    summary(range?: StudyRange): Promise<StudySummary>;
+    sessions(options: ListStudySessionsOptions): Promise<StudySessionPage>;
+}
+export type UseActiveActionOptions = {
+    /** Override the Flow ID origin; defaults to the resolved Flow's `host`. */
+    host?: string;
+};
+/** What `useActiveAction` returns. `elapsedSeconds` is extrapolated locally
+ * from the server's `accruedSeconds` and stands still while `paused`. */
+export interface ActiveActionState {
+    active: ActiveActionResponse | null;
+    elapsedSeconds: number;
+    /** True until the first read of `/api/actions/me` has answered. */
+    loading: boolean;
+    error: Error | null;
+    /** Re-reads the running session from the server. */
+    refresh: () => Promise<void>;
+    start: (input: StartActionInput) => Promise<StartActionResult>;
+    event: (request: ActionEventRequest) => Promise<ActionEventResponse>;
+    finish: (request: FinishActionRequest) => Promise<FinishActionResponse>;
+}

package/dist/sdk/types/actions.js

@@ -0,0 +1,4 @@
+/** The SDK-side contract for actions and study: what `createActionsApi`,
+ * `createStudyApi` and `useActiveAction` take and return. The wire shapes
+ * themselves live in `./xp` and `./study`; this file only names the client
+ * inputs and the composed results a consumer app programs against. */

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

@@ -1,3 +1,4 @@
+export type { ActionCurve, ActionEventRequest, ActionEventResponse, ActionsApi, ActiveActionState, FinishActionRequest, ListStudySessionsOptions, ListStudySubjectsOptions, StartActionInput, StartActionResult, StudyApi, StudySubjectResponse, UseActiveActionOptions, XpEstimateContext, } from "./actions";
 export type { AccountSession, AccountSessionsResponse, AdditionalSession, AuthConfig, AuthResponse, AuthResponseWithWebAuthn, BioNormalization, BioRejection, BioWriteRefusal, BioWriteResult, FlowCredential, FlowUser, PasskeyPluginOptions, RevokeAllSessionsResponse, RevokeSessionResponse, SecurityActivityEntry, SecurityActivityResponse, SessionUser, VerifiedFlowJWT, VerifyOptions, WebAuthnSignature, } from "./auth";
 export type { BodyRegion, CosmeticItem, CosmeticMaterial, CosmeticPaint, CosmeticSlot, EquipConflict, EquippedCosmetic, EquippedCosmetics, EquipRegion, PaintSlot, SettingsConflict, } from "./cosmetics";
 export { BODY_REGIONS, COSMETIC_MATERIALS } from "./cosmetics";
@@ -12,5 +13,6 @@ export type { CreateRoomEventInput, RoomEventArchive, RoomEventAttendance, RoomE
 export type { CreateRoomInput, GlobalRole, ModerationSubject, MyRooms, PlayerPositionReport, RoleChangeVerdict, RoomCapabilities, RoomCapability, RoomChannel, RoomDetail, RoomList, RoomMemberEntry, RoomMembers, RoomOccupancy, RoomOwner, RoomPlayerPosition, RoomPresenceEntry, RoomPresenceSnapshot, RoomRestrictionKind, RoomRole, RoomSummary, RoomSurfaceSettings, RoomsApi, RoomVisibility, StaffEntry, UpdateRoomInput, VerifyRoomContext, Viewer, VoiceDecisionReason, VoiceDecisionSubject, VoiceRoomDecision, } from "./rooms";
 export type { AccessKeyOptions, AccessKeyPreparation, Address, ColorScheme, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowCookieNames, FlowIdProviderProps, FlowSessionState, FlowState, FlowWidgetHandle, FlowWidgetName, FlowWidgetProps, Listener, LoginOptions, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ProfileButtonHandle, ProfileButtonProps, ProfilePosition, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SigningContext, SignMessageArgs, SignTypedDataArgs, Store, StoredAccessKey, UseOpenProfileOptions, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
 export type { GracefulShutdownCleanup, GracefulShutdownOptions, GracefulShutdownServer, GracefulShutdownSignal, ResolvedFlowSession, ResolveSessionOptions, SessionRouteOptions, SessionRouteResponse, SessionRouteSession, } from "./server";
+export type { CreateStudySubjectInput, ListStudySessionsInput, StudyCatalog, StudyCategory, StudyCategoryTotals, StudyField, StudyRange, StudySessionEntry, StudySessionPage, StudySessionsResult, StudySubject, StudySubjectCreation, StudySubjectList, StudySubjectRefusal, StudySubjectRemoval, StudySubjectRemovalResponse, StudySubjectTotals, StudySubjectUpdate, StudySummary, UpdateStudySubjectInput, } from "./study";
 export type { CoinAsset, IdentifiedTx, TxApprove, TxConvert, TxSend, TxSwap, } from "./tx";
-export type { ActionDayContext, ActionEventKind, ActionSessionState, ActionTransitionKind, ActiveActionResponse, LevelProgress, PublicProfile, PublicProfileRefusal, PublicProfileResult, PublicProfileSignal, PublicUserProfile, XpGrantResult, XpRecentGrant, XpSummary, } from "./xp";
+export type { ActionCatalogEntry, ActionCatalogResponse, ActionDayContext, ActionEventKind, ActionSessionState, ActionSubjectRef, ActionSurface, ActionTransitionKind, ActiveActionResponse, ActiveSessionConflict, CurrentAction, FinishActionResponse, LevelProgress, PublicProfile, PublicProfileRefusal, PublicProfileResult, PublicProfileSignal, PublicUserProfile, StartActionResponse, StartUserSessionResult, UserActionSurface, XpGrantResult, XpMode, XpRecentGrant, XpSummary, } from "./xp";

package/dist/sdk/types/rooms.d.ts

@@ -1,4 +1,5 @@
 import type { RawRecord } from "../json";
+import type { CurrentAction } from "./xp";
 /** Room registry types shared by the server routes and the client SDK. */
 export type RoomVisibility = "public" | "unlisted" | "private";
 /**
@@ -93,6 +94,16 @@ export interface RoomMemberEntry {
      * producers omit it; this one because a whole deployment might.
      */
     isGuest?: boolean;
+    /**
+     * The member's active action session as the roster may show it — "Studying",
+     * "Meditating" — or `null` when they have none. The subject rides inside
+     * only when that member shares it (`study.share_subject`).
+     *
+     * Optional for the reason `isGuest` is: this server always sends it, but a
+     * server older than the field omits it, and `undefined` must read as
+     * "unknown" rather than as "idle".
+     */
+    currentAction?: CurrentAction | null;
     role: RoomRole;
     joinedAt: string;
 }

package/dist/sdk/types/study.d.ts

@@ -0,0 +1,154 @@
+/** Study catalog and study-subject shapes that cross the server/SDK boundary. */
+import type { ActionSubjectRef, ActionSurface } from "./xp";
+/**
+ * One predefined thing a person can study. `slug` is `category/field`,
+ * lowercase ASCII and stable forever — it is what a subject row stores and
+ * what totals roll up on. `label` and `aliases` are display and search only,
+ * so either may change without touching data.
+ */
+export interface StudyField {
+    slug: string;
+    label: string;
+    aliases?: readonly string[];
+}
+export interface StudyCategory {
+    slug: string;
+    label: string;
+    fields: readonly StudyField[];
+}
+/** Response of GET /api/study/catalog. */
+export interface StudyCatalog {
+    version: number;
+    categories: readonly StudyCategory[];
+}
+/**
+ * One of the caller's study subjects, as every `/api/study/subjects` route
+ * returns it. `field` is a catalog field slug, a bare category slug (a custom
+ * subject that rolls up under one category), or null for a subject the catalog
+ * has no home for. `name` is the user's own words for it.
+ */
+export interface StudySubject {
+    id: string;
+    field: string | null;
+    name: string;
+    archivedAt: string | null;
+    createdAt: string;
+    lastUsedAt: string;
+}
+/** Response of GET /api/study/subjects. */
+export interface StudySubjectList {
+    subjects: StudySubject[];
+}
+/** Body of POST /api/study/subjects. `name` defaults to the field's label. */
+export interface CreateStudySubjectInput {
+    field?: string | null;
+    name?: string;
+}
+/** Body of PATCH /api/study/subjects/:id — every key optional, at least one required. */
+export interface UpdateStudySubjectInput {
+    name?: string;
+    field?: string | null;
+    archived?: boolean;
+}
+/** Why a subject write was refused; each is also the `error` code the route answers with. */
+export type StudySubjectRefusal = "field_unknown" | "name_invalid" | "name_taken" | "subject_limit" | "not_found";
+/** Outcome of a create: `created: false` means a live subject with that name
+ * already existed and is returned instead (the route answers 200, not 201). */
+export type StudySubjectCreation = {
+    ok: true;
+    created: boolean;
+    subject: StudySubject;
+} | {
+    ok: false;
+    reason: Exclude<StudySubjectRefusal, "not_found" | "name_taken">;
+};
+export type StudySubjectUpdate = {
+    ok: true;
+    subject: StudySubject;
+} | {
+    ok: false;
+    reason: StudySubjectRefusal;
+};
+/** Outcome of a delete: a subject no session references is removed outright;
+ * one with history is archived instead and returned. */
+export type StudySubjectRemoval = {
+    ok: true;
+    outcome: "deleted";
+    subject: null;
+} | {
+    ok: true;
+    outcome: "archived";
+    subject: StudySubject;
+} | {
+    ok: false;
+    reason: "not_found";
+};
+/** Response of DELETE /api/study/subjects/:id. */
+export type StudySubjectRemovalResponse = Extract<StudySubjectRemoval, {
+    ok: true;
+}>;
+/** The window GET /api/study/summary totals over. Days are UTC calendar days,
+ * like the XP curve's: `today` is since UTC midnight, `7d` and `30d` are the
+ * 7 and 30 UTC days ending today, `all` is unbounded. */
+export type StudyRange = "today" | "7d" | "30d" | "all";
+/** One subject's finished study time in a range. `lastAt` is the start of
+ * the most recent session counted. The subject resolves whether or not it has
+ * since been archived, so history keeps its name. */
+export interface StudySubjectTotals {
+    subject: ActionSubjectRef;
+    seconds: number;
+    focusedSeconds: number;
+    sessions: number;
+    lastAt: string;
+}
+/** One catalog category's finished study time in a range: the sum over every
+ * subject whose `field` is that category or one of its fields. */
+export interface StudyCategoryTotals {
+    slug: string;
+    label: string;
+    seconds: number;
+}
+/**
+ * Response of GET /api/study/summary: finished `action.study` sessions only,
+ * summed from the durations materialized at finish. `subjects` and
+ * `categories` are ordered by seconds descending. Sessions without a subject
+ * (a game Study started while the user had none) count in `total` only.
+ */
+export interface StudySummary {
+    range: StudyRange;
+    subjects: StudySubjectTotals[];
+    categories: StudyCategoryTotals[];
+    total: {
+        seconds: number;
+        sessions: number;
+    };
+}
+/** One finished study session as GET /api/study/sessions lists it. */
+export interface StudySessionEntry {
+    sessionId: string;
+    startedAt: string;
+    finishedAt: string;
+    seconds: number;
+    focusedSeconds: number;
+    xpGranted: number;
+    surface: ActionSurface;
+}
+/** Response of GET /api/study/sessions: newest first, `nextBefore` is the
+ * `before` of the next page or null on the last one. */
+export interface StudySessionPage {
+    sessions: StudySessionEntry[];
+    nextBefore: string | null;
+}
+export interface ListStudySessionsInput {
+    subjectId: string;
+    /** Exclusive upper bound on `startedAt`; omit for the newest page. */
+    before?: Date;
+    limit: number;
+}
+export type StudySessionsResult = {
+    ok: true;
+    page: StudySessionPage;
+} | {
+    ok: false;
+    reason: "not_found";
+};

package/dist/sdk/types/study.js

@@ -0,0 +1 @@
+/** Study catalog and study-subject shapes that cross the server/SDK boundary. */

package/dist/sdk/types/xp.d.ts

@@ -1,4 +1,8 @@
 /** XP / leveling shapes that cross the server/dialog boundary. */
+/** How a source turns activity into XP: a flat amount per grant, XP per
+ * minute, or a day-saturating curve. The curves themselves live in
+ * `src/xp/registry.ts`. */
+export type XpMode = "fixed" | "linear" | "consistency";
 export interface LevelProgress {
     /** Level within the current tier, 1..100 — it resets to 1 on each tier-up. */
     level: number;
@@ -52,15 +56,95 @@ export type ActionSessionState = "active" | "finished" | "abandoned";
 export type ActionEventKind = "start" | "pause" | "resume" | "focus_lost" | "focus_gained" | "finish" | "abandon";
 /** Reporter-supplied transitions accepted while an action is active. */
 export type ActionTransitionKind = Extract<ActionEventKind, "pause" | "resume" | "focus_lost" | "focus_gained">;
-/** Response of GET /api/actions/active — the caller's current in-progress
- * action (or null when idle), plus the day context so the timer can render the
- * live XP estimate from the timestamp-derived accrued duration. (Always an
- * `active` session by definition, so the lifecycle state isn't carried.) */
+/** Where a session was started: the game world under the report token, or a
+ * web surface under the caller's own session. Recorded in
+ * `action_session.metadata.surface`; the source id stays surface-agnostic, so
+ * Meditate is `game.action.meditation` whether it began in the game or in
+ * Talk. */
+export type ActionSurface = "game" | "talk" | "web";
+/** The surfaces a caller may claim on POST /api/actions/me/start; `game` is
+ * reserved for the report-token path. */
+export type UserActionSurface = Exclude<ActionSurface, "game">;
+/** The study subject a session is attributed to, resolved from the joined
+ * `study_subject` row whether or not it has since been archived, so history
+ * keeps its name. Null for a source without subjects and for a Study the
+ * game started while the user had none. */
+export interface ActionSubjectRef {
+    id: string;
+    name: string;
+    field: string | null;
+}
+/** The caller's own view of one session — the shape of GET /api/actions/me
+ * and /active (null when idle), of the `session` a start returns, and of the
+ * `active` a 409 carries — plus the day context so a timer can render the
+ * live XP estimate from the timestamp-derived accrued duration. The lifecycle
+ * state is not carried: an idle caller reads null, and a start or finish
+ * answers with the session as it stands at that instant. */
 export interface ActiveActionResponse extends ActionDayContext {
+    sessionId: string;
     source: string;
     label: string | null;
+    surface: ActionSurface;
+    /** ISO timestamp of the session's start. */
+    startedAt: string;
+    /** Whether the last pause/resume transition left the clock stopped. */
+    paused: boolean;
     accruedSeconds: number;
+    subject: ActionSubjectRef | null;
+}
+/** One user-startable action as GET /api/actions/catalog lists it: the
+ * registry descriptor minus its reporter, with the curve parameters a client
+ * needs to estimate XP the way the server grants it. `label` and
+ * `description` are always present (a source without them lists under its
+ * id); the curve fields are present only when the source declares them. */
+export interface ActionCatalogEntry {
+    id: string;
+    label: string;
+    description: string;
+    mode: XpMode;
+    base: number;
+    tauMinutes?: number;
+    dailyCapXp?: number;
+    minDurationSeconds?: number;
+    flowMultiplier: boolean;
+    userStartable: boolean;
+    requiresSubject: boolean;
+}
+/** Response of GET /api/actions/catalog, in registry declaration order. */
+export interface ActionCatalogResponse {
+    actions: ActionCatalogEntry[];
+}
+/** Response of POST /api/actions/me/start (201 created, 200 on an idempotent
+ * replay of the same sessionId). */
+export interface StartActionResponse {
+    session: ActiveActionResponse;
+}
+/** The 409 body of POST /api/actions/me/start: the session already running,
+ * which `replace: true` would finish. */
+export interface ActiveSessionConflict {
+    error: "active_session";
+    active: ActiveActionResponse;
+}
+/** Response of POST /api/actions/me/finish. Idempotent: a replay answers with
+ * the XP and duration the session was credited when it ended. */
+export interface FinishActionResponse {
+    ok: true;
+    xpGranted: number;
+    durationSeconds: number;
 }
+/** Outcome of a user-initiated start. The refusals map to one status each in
+ * the route; `subject_unknown` is a subjectId that is not one of the caller's
+ * live subjects, `session_id_taken` a client id that another user's session
+ * already holds, and `rate_limited` the per-user hourly start cap. */
+export type StartUserSessionResult = {
+    status: "created" | "replayed";
+    session: ActiveActionResponse;
+} | {
+    status: "active_session";
+    active: ActiveActionResponse;
+} | {
+    status: "unknown_source" | "not_startable" | "subject_required" | "subject_unknown" | "session_id_taken" | "rate_limited";
+};
 /** Non-sensitive profile facts any player may see about another — nested into
  * the /api/session/verify payload beside `appearance` so game servers can
  * broadcast them (avatar + level badge on nametags) without extra fetches.
@@ -111,3 +195,20 @@ export type PublicProfileResult = {
     reason: PublicProfileRefusal;
     signal: PublicProfileSignal;
 };
+/**
+ * What a user is doing right now, as OTHER users see it — the room roster's
+ * view of an active `action_session`, not the owner's own
+ * {@link ActiveActionResponse}. Deliberately narrower: no clock, no XP
+ * context, no session id, because a reader has no session to drive. `label`
+ * is `null` for a source the registry no longer names, exactly as the owner's
+ * view reports it. `subject` is the study subject's name and is present only
+ * while the owner's `study.share_subject` setting is on — the subject is their
+ * own words ("Bar exam prep"), so its absence is the default, not a gap.
+ */
+export interface CurrentAction {
+    source: string;
+    label: string | null;
+    /** ISO timestamp of the session's start. */
+    since: string;
+    subject?: string;
+}

package/dist/sdk/xp/curve.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The pure XP curve math: the Flow Score multiplier, the day-saturating
+ * consistency curve, and the live estimate a timer renders from them. No
+ * registry, no DB, no I/O — this module is shipped in the SDK and imported by
+ * the grant service alike, so a count-up in a consumer app and the ledger row
+ * the server writes come from one function and cannot drift.
+ */
+import type { ActionCurve, XpEstimateContext } from "../types";
+export declare const FLOW_SCORE_MAX = 10;
+export declare function clampFlowScore(score: number): number;
+/** The Flow Score IS the XP multiplier: score 10 grants 10x. Floored at 1x so a
+ * lapsed player (score 0 or 1) still earns full base XP. */
+export declare function flowMultiplier(flowScore: number): number;
+/** The (unrounded) cumulative pre-multiplier XP a consistency source has earned
+ * after `totalMinutes` of activity in the day — a saturating curve toward
+ * `base`. A single session's grant is the delta between this at the new and old
+ * totals, so the first minutes of the day are worth the most. The live timer
+ * uses this raw form for a smooth count-up; grants round it. */
+export declare function consistencyCurve(source: Pick<ActionCurve, "base" | "tauMinutes">, totalMinutes: number): number;
+/**
+ * The XP a session of `elapsedSeconds` would grant if it finished now,
+ * mirroring the grant service: consistency is the delta on the day-cumulative
+ * curve from today's prior minutes, linear is `base` per minute, fixed is flat;
+ * below the source's minimum duration it is 0. The Flow Score multiplies the
+ * result, and a daily cap bounds it by what is left of the day's ceiling after
+ * the prior minutes. Unrounded curve, rounded once at the end, so a count-up
+ * advances smoothly and lands on the number the ledger will show.
+ */
+export declare function estimateActionXp(entry: ActionCurve, context: XpEstimateContext): number;

package/dist/sdk/xp/curve.js

@@ -0,0 +1,64 @@
+/**
+ * The pure XP curve math: the Flow Score multiplier, the day-saturating
+ * consistency curve, and the live estimate a timer renders from them. No
+ * registry, no DB, no I/O — this module is shipped in the SDK and imported by
+ * the grant service alike, so a count-up in a consumer app and the ledger row
+ * the server writes come from one function and cannot drift.
+ */
+export const FLOW_SCORE_MAX = 10;
+export function clampFlowScore(score) {
+    return Math.min(FLOW_SCORE_MAX, Math.max(0, Math.trunc(score)));
+}
+/** The Flow Score IS the XP multiplier: score 10 grants 10x. Floored at 1x so a
+ * lapsed player (score 0 or 1) still earns full base XP. */
+export function flowMultiplier(flowScore) {
+    return Math.max(1, clampFlowScore(flowScore));
+}
+/** The (unrounded) cumulative pre-multiplier XP a consistency source has earned
+ * after `totalMinutes` of activity in the day — a saturating curve toward
+ * `base`. A single session's grant is the delta between this at the new and old
+ * totals, so the first minutes of the day are worth the most. The live timer
+ * uses this raw form for a smooth count-up; grants round it. */
+export function consistencyCurve(source, totalMinutes) {
+    const tau = source.tauMinutes ?? 40;
+    return source.base * (1 - Math.exp(-Math.max(0, totalMinutes) / tau));
+}
+/**
+ * The XP a session of `elapsedSeconds` would grant if it finished now,
+ * mirroring the grant service: consistency is the delta on the day-cumulative
+ * curve from today's prior minutes, linear is `base` per minute, fixed is flat;
+ * below the source's minimum duration it is 0. The Flow Score multiplies the
+ * result, and a daily cap bounds it by what is left of the day's ceiling after
+ * the prior minutes. Unrounded curve, rounded once at the end, so a count-up
+ * advances smoothly and lands on the number the ledger will show.
+ */
+export function estimateActionXp(entry, context) {
+    const { elapsedSeconds, priorMinutes, flowScore } = context;
+    if (entry.minDurationSeconds !== undefined &&
+        elapsedSeconds < entry.minDurationSeconds) {
+        return 0;
+    }
+    const elapsedMinutes = Math.max(0, elapsedSeconds) / 60;
+    const prior = Math.max(0, priorMinutes);
+    const multiplier = entry.flowMultiplier ? flowMultiplier(flowScore) : 1;
+    let base;
+    let priorBase = 0;
+    if (entry.mode === "fixed") {
+        base = entry.base;
+    }
+    else if (entry.mode === "linear") {
+        base = entry.base * elapsedMinutes;
+        priorBase = entry.base * prior;
+    }
+    else {
+        base =
+            consistencyCurve(entry, prior + elapsedMinutes) -
+                consistencyCurve(entry, prior);
+        priorBase = consistencyCurve(entry, prior);
+    }
+    const xp = Math.max(0, Math.round(base * multiplier));
+    if (entry.dailyCapXp === undefined)
+        return xp;
+    const remaining = Math.max(0, entry.dailyCapXp - Math.round(priorBase * multiplier));
+    return Math.min(xp, remaining);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.19.4",
+  "version": "0.21.0",
   "license": "MIT",
   "repository": {
     "type": "git",