@flow-industries/id 0.20.0 → 0.21.0

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/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/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/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.0",
   "license": "MIT",
   "repository": {
     "type": "git",