@flow-industries/id 0.20.0 → 0.21.1

package/README.md

@@ -47,6 +47,38 @@ Full documentation at **[docs.flow.industries/en/auth](https://docs.flow.industr
 - [JWT verify](https://docs.flow.industries/en/auth/jwt-verify) - verify Flow sessions on your backend
 - [API reference](https://docs.flow.industries/en/auth/api) and [self-hosting](https://docs.flow.industries/en/auth/self-hosting)
 
+## Public profile overlays
+
+```ts
+import { closeProfile, openProfile } from "@flow-industries/id";
+import { isValidUsername } from "@flow-industries/id/usernames";
+
+if (isValidUsername(username)) {
+  openProfile(username, { onClose: () => resumeInput() });
+}
+
+closeProfile();
+```
+
+`@flow-industries/id/usernames` also exports `USERNAME_REGEX` and
+`MAX_USERNAME_LENGTH`. It has no browser or server dependencies.
+
+`OpenProfileOptions.onClose?: () => void` fires once after the overlay stops
+accepting input, before its exit animation finishes. It covers the close button,
+backdrop, Escape, `closeProfile()`, and sign-in/sign-out handoffs. The latest
+successful `openProfile` call owns the callback, even when switching profiles
+while open; an omitted callback clears the previous one. Invalid usernames and
+SSR return `false` without replacing it. Closing an already closed overlay is a
+no-op. A callback may open another profile.
+
+React callers pass the same option to
+`useOpenProfile({ onClose: () => resumeInput() })` from
+`@flow-industries/id/react`; the callback is captured when its returned opener
+is called. The overlay belongs to the page and survives component unmounts.
+
+Open from the document that owns the full viewport. Canvas hosts must release
+pointer lock before opening, then use `onClose` to restore their input state.
+
 ## License
 
 MIT

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

@@ -1,5 +1,5 @@
 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, DialogHost, FinishActionRequest, FinishActionResponse, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, ListStudySubjectsOptions, LoginOptions, MethodName, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, ProfileButtonHandle, ProfilePosition, Session, StartActionInput, StartActionResponse, StartActionResult, StudyApi, StudyCatalog, StudyCategory, StudyField, StudySubject, StudySubjectList, StudySubjectRefusal, StudySubjectRemovalResponse, StudySubjectResponse, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, XpMode, } 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";

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

@@ -21,6 +21,7 @@ function createViewer(options) {
     // meant for the page underneath with nothing on screen to explain it.
     let ready = false;
     let visible = false;
+    let onClose;
     function applyHitTesting() {
         if (frame)
             frame.style.pointerEvents = ready && visible ? "auto" : "none";
@@ -78,7 +79,7 @@ function createViewer(options) {
         });
         return opened;
     }
-    function open(username) {
+    function open(username, nextOnClose) {
         const mounted = bridge;
         const live = mounted ?? mount(username);
         // A frame created just now is already on this profile; an existing one is
@@ -93,6 +94,8 @@ function createViewer(options) {
             type: "profile-identity",
             identity: hostIdentity(flow),
         });
+        window.addEventListener("keydown", onKeyDown);
+        onClose = nextOnClose;
         visible = true;
         applyHitTesting();
         void live.send("__internal", { type: "dialog-shown" });
@@ -104,11 +107,21 @@ function createViewer(options) {
     // always-rendered, transparent and click-through while hidden keeps every
     // open animation reliable, on the second open and the tenth.
     function close() {
-        if (!frame || !bridge)
+        if (!visible || !frame || !bridge)
             return;
         visible = false;
+        window.removeEventListener("keydown", onKeyDown);
         applyHitTesting();
         void bridge.send("__internal", { type: "dialog-hidden" });
+        const notifyClose = onClose;
+        onClose = undefined;
+        notifyClose?.();
+    }
+    function onKeyDown(event) {
+        if (event.key !== "Escape" || event.defaultPrevented)
+            return;
+        event.preventDefault();
+        close();
     }
     function setTheme(next) {
         if (next === theme)
@@ -163,7 +176,7 @@ export function openProfile(username, options = {}) {
     viewer = live;
     if (options.theme)
         live.setTheme(options.theme);
-    live.open(username);
+    live.open(username, options.onClose);
     return true;
 }
 /**

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

@@ -8,9 +8,10 @@ export declare class StudyRequestError extends Error {
     constructor(status: number, message: string, reason?: string | undefined);
 }
 /**
- * Thin typed client for the study catalog and the caller's study subjects,
- * bound to a host and the Flow token supplier. The catalog is public and
- * long-cached by the browser; the subject routes attach the caller's bearer
- * and fail fast with a 401-shaped error when no session exists.
+ * 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

@@ -13,10 +13,11 @@ export class StudyRequestError extends Error {
     }
 }
 /**
- * Thin typed client for the study catalog and the caller's study subjects,
- * bound to a host and the Flow token supplier. The catalog is public and
- * long-cached by the browser; the subject routes attach the caller's bearer
- * and fail fast with a 401-shaped error when no session exists.
+ * 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));
@@ -38,5 +39,17 @@ export function createStudyApi(host, getToken) {
             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/react/open-profile.js

@@ -19,6 +19,6 @@ import { useFlow } from "./hooks";
  */
 export function useOpenProfile(options = {}) {
     const flow = useFlow();
-    const { host, theme } = options;
-    return useCallback((username) => openProfile(username, { flow, host, theme }), [flow, host, theme]);
+    const { host, theme, onClose } = options;
+    return useCallback((username) => openProfile(username, { flow, host, theme, onClose }), [flow, host, theme, onClose]);
 }

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

@@ -2,7 +2,7 @@
  * `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, StudySubject, StudySubjectList, StudySubjectRemovalResponse, UpdateStudySubjectInput } from "./study";
+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
@@ -61,6 +61,17 @@ 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;
@@ -72,6 +83,10 @@ export interface StudyApi {
     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`. */

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

@@ -1,4 +1,4 @@
-export type { ActionCurve, ActionEventRequest, ActionEventResponse, ActionsApi, ActiveActionState, FinishActionRequest, ListStudySubjectsOptions, StartActionInput, StartActionResult, StudyApi, StudySubjectResponse, UseActiveActionOptions, XpEstimateContext, } from "./actions";
+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";
@@ -13,6 +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, StudyCatalog, StudyCategory, StudyField, StudySubject, StudySubjectCreation, StudySubjectList, StudySubjectRefusal, StudySubjectRemoval, StudySubjectRemovalResponse, StudySubjectUpdate, UpdateStudySubjectInput, } from "./study";
+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 { ActionCatalogEntry, ActionCatalogResponse, ActionDayContext, ActionEventKind, ActionSessionState, ActionSubjectRef, ActionSurface, ActionTransitionKind, ActiveActionResponse, ActiveSessionConflict, FinishActionResponse, LevelProgress, PublicProfile, PublicProfileRefusal, PublicProfileResult, PublicProfileSignal, PublicUserProfile, StartActionResponse, StartUserSessionResult, UserActionSurface, XpGrantResult, XpMode, 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/sdk.d.ts

@@ -230,6 +230,14 @@ export type ProfileButtonHandle = {
     destroy: () => void;
 };
 export type OpenProfileOptions = {
+    /**
+     * Called once when the overlay closes, including its close button, backdrop,
+     * Escape, closeProfile(), or a sign-in/sign-out handoff. Runs after the
+     * overlay stops accepting input, without waiting for the exit animation.
+     * The latest successful open replaces this callback; omitting it clears the
+     * previous callback. Rejected opens and repeated closes do not notify.
+     */
+    onClose?: () => void;
     /**
      * The Flow ID origin serving the overlay (e.g. https://id.flow.industries).
      * Defaults to the resolved Flow instance's `host`, then the SDK default.
@@ -249,12 +257,7 @@ export type OpenProfileOptions = {
      */
     flow?: Flow;
 };
-export type UseOpenProfileOptions = {
-    /** Override the Flow ID origin; defaults to the resolved Flow's `host`. */
-    host?: string;
-    /** Color scheme for the dialog chrome; defaults to "light dark" (the OS). */
-    theme?: ColorScheme;
-};
+export type UseOpenProfileOptions = Pick<OpenProfileOptions, "host" | "theme" | "onClose">;
 /** The inline Flow ID widgets an embedder can mount alongside its own UI. */
 export type FlowWidgetName = "xp" | "action-timer";
 export type MountFlowWidgetOptions = {

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

@@ -1,4 +1,5 @@
 /** 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
@@ -86,3 +87,68 @@ export type StudySubjectRemoval = {
 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/xp.d.ts

@@ -195,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,6 +19,10 @@
       "types": "./dist/sdk/client/index.d.ts",
       "import": "./dist/sdk/client/index.js"
     },
+    "./usernames": {
+      "types": "./dist/sdk/usernames.d.ts",
+      "import": "./dist/sdk/usernames.js"
+    },
     "./react": {
       "types": "./dist/sdk/react/index.d.ts",
       "import": "./dist/sdk/react/index.js"
@@ -69,6 +73,7 @@
     "usernames:refresh": "bun run scripts/generate-reserved-usernames.ts",
     "lint": "biome check",
     "test": "bun test src",
+    "test:sdk-package": "bash scripts/test-sdk-package.sh",
     "format": "biome format --write",
     "check": "biome check --write",
     "typecheck": "tsr generate && tsc --noEmit"