@flow-industries/id 0.18.0 → 0.19.0

package/dist/sdk/types/cosmetics.js

@@ -0,0 +1,78 @@
+/**
+ * Cosmetic items, the space they occupy on the model, and the equipped set a
+ * game server receives on `/api/session/verify`.
+ *
+ * Two region vocabularies live here and must never be collapsed into one:
+ * {@link EquipRegion} is *item vs item* (can these be worn together), while
+ * {@link BodyRegion} is *cosmetic vs body* (what geometry must stop drawing so
+ * nothing pokes through). TF2 keeps them separate — equip regions and
+ * bodygroups — and conflating them is what produces the clipping bugs.
+ *
+ * {@link CosmeticMaterial} is a third vocabulary and belongs to neither: it
+ * names a *surface* of the model rather than a space on it, and it is what a
+ * colour is applied to.
+ */
+/**
+ * Every body area a cosmetic may suppress — the bodygroup half's whole
+ * vocabulary, head down.
+ *
+ * SOURCE OF TRUTH: the `regions` keys of
+ * `game/games/arena/player/luna_bodygroups.tres`, which is authored against
+ * the shipped model. This is a mirror, kept as a constant so auth can resolve
+ * a loadout without reaching into the game repo at runtime.
+ *
+ * WHEN THE MODEL IS RE-CUT: update this list to the new `regions` keys, then
+ * fix whatever `hides` in the catalog no longer resolves. `cosmetics.test.ts`
+ * fails on the first entry that names a region absent here, and the type below
+ * makes the same mistake a typecheck error — which is the whole point of
+ * mirroring the names into one constant. AUTH-210 is what happens without it:
+ * the catalog was written from a nine-region proposal in
+ * `docs/internal/cosmetics/bodygroups.md` section 6, the fifteen-region cut
+ * that actually shipped shared not one name with it, and every cosmetic
+ * silently suppressed nothing.
+ */
+export const BODY_REGIONS = [
+    "head",
+    "ears",
+    "hair",
+    "body_neck",
+    "body_chest",
+    "body_arm_upper_l",
+    "body_arm_upper_r",
+    "body_arm_lower_l",
+    "body_arm_lower_r",
+    "body_hand_l",
+    "body_hand_r",
+    "body_pelvis",
+    "body_leg_upper_l",
+    "body_leg_upper_r",
+    "body_leg_lower_l",
+    "body_leg_lower_r",
+    "body_foot_l",
+    "body_foot_r",
+];
+/**
+ * Every material the shipped model set exposes, body and cosmetic alike — the
+ * surfaces a colour can be applied to.
+ *
+ * SOURCE OF TRUTH: the glTF material names inside
+ * `game/games/arena/resources/models/LUNA12.7.glb` (`skin`, `brownhair`,
+ * `tshirt`, `shorts`) and the per-cosmetic GLBs beside it
+ * (`cosmetics/LUNA_boots.glb` names `Shoes`, `cosmetics/LUNA_glasses.glb`
+ * names `outline`). `Shoes` is capitalised because the model capitalises it: a
+ * tidied-up copy here would name a material no renderer can find, and the
+ * paint would silently land nowhere.
+ *
+ * WHEN THE MODEL IS RE-CUT: update this list to the new material names, then
+ * fix whatever `paintable` in the catalog no longer resolves. This is the same
+ * mirror-and-guard {@link BODY_REGIONS} is, kept for the same reason —
+ * AUTH-210 is what a hardcoded copy with no test looks like a month later.
+ */
+export const COSMETIC_MATERIALS = [
+    "skin",
+    "brownhair",
+    "tshirt",
+    "shorts",
+    "Shoes",
+    "outline",
+];

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

@@ -0,0 +1,58 @@
+import type { RawRecord } from "../json";
+/**
+ * Game-server lifecycle telemetry. The same record shape is POSTed to the
+ * OpenObserve `game_events` stream (ops, TTL'd) and to this server's durable
+ * ingest (`POST /api/game/events`), so one emitter feeds both and a new event
+ * kind needs no wire change here.
+ */
+/** One lifecycle record as the game server reports it. `sessionId` pairs a
+ * player's join with their leave, which is what makes time-present a self-join
+ * instead of a guess about reused peer ids. Anything not named here rides in
+ * `detail`. */
+export interface GameEventReport {
+    /** The reporter's idempotency key. Resending a batch with stable ids is a
+     * no-op; omit it and the server mints one, making the retry a duplicate. */
+    id?: string;
+    event: string;
+    ts: string;
+    serverId: string;
+    sessionId?: string;
+    roomId?: string;
+    roomSlug?: string;
+    sub?: string;
+    reason?: string;
+    detail?: RawRecord;
+}
+/** A player's stay in a room, reconstructed by pairing the join and leave rows
+ * that share a `sessionId`. A same-server shutdown closes a missing leave;
+ * `leftAt` remains null only while the session is open or when neither closing
+ * record survived. */
+export interface GamePlayerSession {
+    sessionId: string;
+    userId: string;
+    roomId: string | null;
+    roomSlug: string | null;
+    joinedAt: string;
+    leftAt: string | null;
+    reason: string | null;
+}
+export declare const GAME_LIFECYCLE_EVENT_NAMES: readonly ["game.server.boot", "game.server.shutdown", "game.room.open", "game.room.close", "game.player.join", "game.player.leave"];
+export type GameLifecycleEventName = (typeof GAME_LIFECYCLE_EVENT_NAMES)[number];
+/** Product-safe projection of a durable lifecycle record. Raw `detail` is
+ * intentionally absent from this service-to-service contract. */
+export interface GameLifecycleFeedEvent {
+    id: string;
+    event: GameLifecycleEventName;
+    occurredAt: string;
+    serverId: string;
+    sessionId: string | null;
+    roomId: string | null;
+    roomSlug: string | null;
+    userId: string | null;
+    reason: string | null;
+}
+export interface GameLifecycleFeedPage {
+    events: GameLifecycleFeedEvent[];
+    nextCursor: string;
+    hasMore: boolean;
+}

package/dist/sdk/types/game.js

@@ -0,0 +1,8 @@
+export const GAME_LIFECYCLE_EVENT_NAMES = [
+    "game.server.boot",
+    "game.server.shutdown",
+    "game.room.open",
+    "game.room.close",
+    "game.player.join",
+    "game.player.leave",
+];

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

@@ -1,12 +1,16 @@
 export type { AccountSession, AccountSessionsResponse, AdditionalSession, AuthConfig, AuthResponse, AuthResponseWithWebAuthn, 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";
 export type { BoundaryError, DialogCustomFeatures, DialogCustomLabels, DialogError, DialogReferrer, DialogState, Loadable, ProfileData, ProfileIdentity, } from "./dialog";
 export type { AuthErrorCode, AuthEventName, AuthEventRecord, AuthMode, AuthOutcome, BeaconBody, FunnelStep, } from "./events";
+export type { GameEventReport, GameLifecycleEventName, GameLifecycleFeedEvent, GameLifecycleFeedPage, GamePlayerSession, } from "./game";
+export { GAME_LIFECYCLE_EVENT_NAMES } from "./game";
 export type { Bridge, BridgeParameters, FlowAccount, FlowRemote, FlowRemoteConfig, FromWindowOptions, MessageResponse, Messenger, OneOf, Payload, QueuedRequest, ReadyOptions, RemoteFlowState, RemoteState, Schema, Storage, Topic, WithReady, } from "./messenger";
 export type { Call, ConnectCapabilities, ConnectRequest, ConnectResponse, GuestRequest, GuestResponse, MethodName, MethodParams, MethodResult, RestoreResponse, RpcRequest, SendCallsParams, SendCallsRequest, SendCallsResponse, SendTransactionParams, SendTransactionRequest, SendTransactionResponse, SignMessageRequest, SignMessageResponse, SignOutRequest, SignOutResponse, SignTypedDataRequest, SignTypedDataResponse, TransactionArgs, TypedData, TypedDataDomain, TypedDataField, } from "./protocol";
 export { getConnectCapabilities, isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
-export type { CreateRoomEventInput, RoomEventAttendance, RoomEventFrequency, RoomEventInstance, RoomEventInterest, RoomEventInterestState, RoomEventList, RoomEventOccurrence, RoomEventRecurrence, RoomEventRoomRef, RoomEventSeries, RoomEventStatus, SetInterestInput, UpdateRoomEventInput, } from "./room-events";
-export type { CreateRoomInput, GlobalRole, ModerationSubject, MyRooms, RoleChangeVerdict, RoomChannel, RoomDetail, RoomList, RoomMemberEntry, RoomMembers, RoomOccupancy, RoomOwner, RoomPresenceEntry, RoomPresenceSnapshot, RoomRestrictionKind, RoomRole, RoomSummary, RoomSurfaceSettings, RoomsApi, RoomVisibility, StaffEntry, UpdateRoomInput, VerifyRoomContext, Viewer, } from "./rooms";
+export type { CreateRoomEventInput, RoomEventArchive, RoomEventAttendance, RoomEventFrequency, RoomEventInstance, RoomEventInterest, RoomEventInterestState, RoomEventList, RoomEventOccurrence, RoomEventRecurrence, RoomEventRoomRef, RoomEventRun, RoomEventSeries, RoomEventStatus, SetInterestInput, UpdateRoomEventInput, } from "./room-events";
+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, } 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, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ProfileButtonHandle, ProfileButtonProps, ProfilePosition, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SigningContext, SignMessageArgs, SignTypedDataArgs, Store, StoredAccessKey, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
-export type { ResolvedFlowSession, ResolveSessionOptions, SessionRouteOptions, SessionRouteResponse, SessionRouteSession, } from "./server";
+export type { GracefulShutdownCleanup, GracefulShutdownOptions, GracefulShutdownServer, GracefulShutdownSignal, ResolvedFlowSession, ResolveSessionOptions, SessionRouteOptions, SessionRouteResponse, SessionRouteSession, } from "./server";
 export type { CoinAsset, IdentifiedTx, TxApprove, TxConvert, TxSend, TxSwap, } from "./tx";
 export type { ActionDayContext, ActionEventKind, ActionSessionState, ActiveActionResponse, LevelProgress, PublicProfile, XpGrantResult, XpRecentGrant, XpSummary, } from "./xp";

package/dist/sdk/types/index.js

@@ -1 +1,3 @@
+export { BODY_REGIONS, COSMETIC_MATERIALS } from "./cosmetics";
+export { GAME_LIFECYCLE_EVENT_NAMES } from "./game";
 export { getConnectCapabilities, isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";

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

@@ -166,7 +166,7 @@ export type RemoteState = {
 export type Storage = {
     getItem: <value>(name: string) => Promise<value | null> | value | null;
     removeItem: (name: string) => Promise<void> | void;
-    setItem: (name: string, value: unknown) => Promise<void> | void;
+    setItem: <value>(name: string, value: value) => Promise<void> | void;
     sizeLimit: number;
     storages?: readonly Storage[];
 };

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

@@ -1,3 +1,4 @@
+import type { RawRecord, RawValue } from "../json";
 import type { AdditionalSession, FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
 import type { Address } from "./sdk";
 export type MethodName = "wallet_connect" | "personal_sign" | "eth_signTypedData" | "eth_sendTransaction" | "wallet_sendCalls" | "wallet_guest" | "wallet_signout";
@@ -51,7 +52,7 @@ export type TypedData = {
     domain: TypedDataDomain;
     types: Record<string, readonly TypedDataField[]>;
     primaryType: string;
-    message: Record<string, unknown>;
+    message: RawRecord;
 };
 export type SignTypedDataRequest = [address: string, typedData: TypedData];
 export type SignTypedDataResponse = `0x${string}`;
@@ -69,7 +70,7 @@ export type SendCallsRequest = [
     {
         calls: readonly Call[];
         chainId?: string;
-        capabilities?: Record<string, unknown>;
+        capabilities?: RawRecord;
     }
 ];
 export type SendCallsResponse = {
@@ -123,9 +124,9 @@ export type MethodResult = {
 export type RpcRequest = {
     id: string | number;
     method: string;
-    params?: readonly unknown[];
+    params?: readonly RawValue[];
     jsonrpc?: string;
-    [key: string]: unknown;
+    [key: string]: RawValue | readonly RawValue[];
 };
 export type SendTransactionParams = {
     to?: string;
@@ -140,7 +141,7 @@ export type SendCallsParams = {
         data?: string;
     }[];
     chainId?: string;
-    capabilities?: Record<string, unknown>;
+    capabilities?: RawRecord;
 };
 /**
  * Unwraps the connect capabilities from a wallet_connect RPC request (they ride

package/dist/sdk/types/protocol.js

@@ -4,22 +4,28 @@
  * accessKeyHash, guestToken), so the cast lives here rather than being repeated.
  */
 export function getConnectCapabilities(request) {
-    return request?.params?.[0]?.capabilities;
+    const first = request?.params?.[0];
+    const found = Object.entries(Object(first)).find(([k]) => k === "capabilities")?.[1];
+    /* SAFETY: the field is read off this app's own wallet_connect params, whose capabilities
+       block is defined by ConnectCapabilities; a missing one answers undefined. */
+    return found;
 }
 export function isPersonalSignParams(params) {
     if (!params || params.length < 2)
         return false;
-    return typeof params[0] === "string" && typeof params[1] === "string";
+    return String(params[0]) === params[0] && String(params[1]) === params[1];
 }
 export function isSendTransactionParams(params) {
     if (!params || params.length < 1)
         return false;
     const p = params[0];
-    return p != null && typeof p === "object";
+    return p != null && Object(p) === p;
 }
 export function isSendCallsParams(params) {
     if (!params || params.length < 1)
         return false;
     const p = params[0];
-    return p != null && typeof p === "object" && Array.isArray(p.calls);
+    if (p == null || Object(p) !== p)
+        return false;
+    return Array.isArray(Object.entries(p).find(([k]) => k === "calls")?.[1]);
 }

package/dist/sdk/types/room-events.d.ts

@@ -66,12 +66,50 @@ export interface RoomEventInstance extends RoomEventInterest {
     /** Written once the instance completes — the history view reads these rather
      * than scanning presence. Null while it has not finished. */
     attendance: RoomEventAttendance | null;
+    /** When the instance actually ran. Null until something has happened to it.
+     * This — not `attendance` — is the authoritative answer to "did this run, and
+     * when". */
+    run: RoomEventRun | null;
 }
-/** What actually happened, as observed from room presence while it ran. */
+/**
+ * The authoritative run window, stamped by the scheduler at the instant of each
+ * transition.
+ *
+ * `activatedAt` is null on an occurrence the worker slept through and caught up
+ * in one step (scheduled straight to completed): nothing observed it start, so
+ * nothing claims to know. Rows that completed before this was recorded are null
+ * on all three and cannot be backfilled — the instants were never captured.
+ */
+export interface RoomEventRun {
+    activatedAt: string | null;
+    completedAt: string | null;
+    cancelledAt: string | null;
+}
+/**
+ * When players were in the room, derived from game lifecycle edges and merged
+ * with presence samples where reporting gaps remain.
+ *
+ * **This is not the run window.** These instants are the first and last player
+ * *seen*; an occurrence that ran for two hours with one player who left after
+ * fifteen minutes reports fifteen minutes here, and one nobody attended reports
+ * null for both while still having genuinely run. Read {@link RoomEventRun} for
+ * whether and when it ran.
+ */
 export interface RoomEventAttendance {
     attendeeCount: number;
     peakConcurrent: number;
+    /** First player seen in the room. */
+    firstPlayerSeenAt: string | null;
+    /** Last player seen in the room. */
+    lastPlayerSeenAt: string | null;
+    /**
+     * @deprecated Misread as the run window once already, which is why the pair
+     * above exists. Same values, kept so existing consumers keep working; read
+     * `firstPlayerSeenAt`/`lastPlayerSeenAt`, or {@link RoomEventRun} if what you
+     * want is when the event ran.
+     */
     startedAt: string | null;
+    /** @deprecated See {@link RoomEventAttendance.startedAt}. */
     endedAt: string | null;
 }
 /** An instance standing on its own in a listing, carrying enough of its series
@@ -85,6 +123,11 @@ export interface RoomEventOccurrence extends RoomEventInstance {
     timezone: string;
     /** True when the parent series repeats, so a card can badge it as recurring. */
     recurring: boolean;
+    /** The series' rule, denormalized so a card can say *how* it repeats without
+     * a second read. Null for a one-off, and then `recurring` is false too — the
+     * flag stays because it is what a caller branches on, the rule is what it
+     * renders. */
+    recurrence: RoomEventRecurrence | null;
     createdBy: string | null;
 }
 /** The authored series, with the instances it has materialized so far. */
@@ -110,6 +153,11 @@ export interface RoomEventSeries {
 export interface RoomEventList {
     events: RoomEventOccurrence[];
 }
+/** The archive listing: finished and cancelled occurrences, newest first, with
+ * the keyset cursor for the next page (`null` once the history is exhausted). */
+export interface RoomEventArchive extends RoomEventList {
+    nextCursor: string | null;
+}
 export interface CreateRoomEventInput {
     title: string;
     description?: string | null;

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

@@ -1,3 +1,4 @@
+import type { RawRecord } from "../json";
 /** Room registry types shared by the server routes and the client SDK. */
 export type RoomVisibility = "public" | "unlisted" | "private";
 /**
@@ -109,11 +110,52 @@ export interface RoomPresenceSnapshot {
     slug: string;
     channels: Record<RoomChannel, RoomPresenceEntry[]>;
 }
+/**
+ * Where a player was last standing in one room, as handed back on the verify
+ * room context. A hint for the game server's placement pass, not a command:
+ * the world is hand-authored and changes between deploys, so the coordinate is
+ * re-validated against the live physics space before anyone is put on it.
+ * `worldId` records which build of the world produced it; `at` is how fresh it
+ * is. Feet position in metres, `yaw` in radians.
+ */
+export interface RoomPlayerPosition {
+    x: number;
+    y: number;
+    z: number;
+    yaw: number;
+    worldId: string;
+    at: string;
+}
+/** One entry of `POST /api/rooms/position/report`, keyed by the Flow `sub`. */
+export interface PlayerPositionReport {
+    roomId: string;
+    sub: string;
+    x: number;
+    y: number;
+    z: number;
+    yaw: number;
+    worldId: string;
+}
+/**
+ * One server-resolved permission over an admitted room session, keyed by the
+ * Talk operation it authorizes (see `src/rooms/capabilities.ts` for the
+ * derivation). Resolved in admission and re-resolved on every restriction
+ * recheck — the client's copy is explanatory only and never the enforcement
+ * boundary.
+ */
+export type RoomCapability = "history" | "reply" | "react" | "mention" | "attach" | "pin" | "moderate" | "search";
+export type RoomCapabilities = Record<RoomCapability, boolean>;
 /**
  * Room admission context returned by POST /api/session/verify when the caller
  * passes a `room` slug: whether the verified subject may enter, and with which
- * role and per-room game settings. `settings` is delivered only through this
- * server-to-server path — surface blobs may hold secret-ish values.
+ * role and per-room settings (the admission-facing surfaces merged flat —
+ * see `src/rooms/admission.ts`). `settings` is delivered only through this
+ * server-to-server path — surface blobs may hold secret-ish values, and
+ * `lastPosition` is scoped to the room being joined so it never answers "where
+ * is this user" across the fleet. `capabilities` is the resolved permission
+ * set for the session (all-false when `ok` is false — no session exists);
+ * `mutedUntil` carries a live mute's expiry (null for permanent or none) so
+ * consumers can show feedback until it lapses.
  */
 export interface VerifyRoomContext {
     ok: boolean;
@@ -123,7 +165,10 @@ export interface VerifyRoomContext {
     visibility: RoomVisibility | null;
     role: RoomRole | null;
     muted: boolean;
+    mutedUntil: string | null;
+    capabilities: RoomCapabilities;
     settings: Record<string, number | boolean | string>;
+    lastPosition: RoomPlayerPosition | null;
 }
 export interface RoomSurfaceSettings {
     surface: string;
@@ -147,7 +192,7 @@ export interface RoomsApi {
     members(slug: string): Promise<RoomMembers>;
     presence(slug: string): Promise<RoomPresenceSnapshot>;
     settings(slug: string, surface: string): Promise<RoomSurfaceSettings>;
-    saveSettings(slug: string, surface: string, settings: Record<string, unknown>): Promise<RoomSurfaceSettings>;
+    saveSettings(slug: string, surface: string, settings: RawRecord): Promise<RoomSurfaceSettings>;
     transfer(slug: string, userId: string): Promise<void>;
     claim(slug: string): Promise<void>;
     setRole(slug: string, userId: string, role: "moderator" | "member"): Promise<void>;
@@ -162,4 +207,9 @@ export interface RoomsApi {
         expiresInSeconds?: number;
     }): Promise<void>;
     unmute(slug: string, userId: string): Promise<void>;
+    timeout(slug: string, userId: string, options: {
+        seconds: number;
+        reason?: string;
+    }): Promise<void>;
+    removeTimeout(slug: string, userId: string): Promise<void>;
 }

package/dist/sdk/types/rooms.js

@@ -1 +0,0 @@
-/** Room registry types shared by the server routes and the client SDK. */

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

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { Chain, Hex, PrepareTransactionRequestParameters, SendTransactionParameters, SignTypedDataParameters, Transport, WalletClient } from "viem";
 import type { SendCallsParameters } from "viem/actions";
+import type { RawValue } from "../json";
 import type { AdditionalSession, FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
 import type { ConnectCapabilities, ConnectResponse } from "./protocol";
 import type { RoomsApi } from "./rooms";
@@ -262,7 +263,7 @@ export type FlowWidgetHandle = {
      * Sends a widget-specific message (e.g. `{ type: "xp-refresh" }`), pinned to
      * the Flow ID origin.
      */
-    post: (message: unknown) => void;
+    post: (message: RawValue) => void;
     /**
      * Recolors the mounted widget in place, for the same reason the pill exposes
      * it: a remount reloads the frame and flashes it out of the host's layout.

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

@@ -60,3 +60,21 @@ export type SessionRouteResponse = {
      */
     additionalSessions?: AdditionalSession[];
 };
+export type GracefulShutdownSignal = "SIGTERM" | "SIGINT";
+export type GracefulShutdownServer = {
+    /** Stop accepting connections; `true` also closes active connections. */
+    stop(closeActiveConnections?: boolean): Promise<void> | void;
+};
+export type GracefulShutdownOptions = {
+    /**
+     * Total time allowed for active HTTP requests and `onShutdown` to finish.
+     * Defaults to 20 seconds, leaving Kubernetes headroom around the app drain.
+     */
+    timeoutMs?: number;
+    /**
+     * Consumer cleanup started after the server stops accepting connections.
+     * Close WebSockets, flush presence, and finish other process-owned state here.
+     */
+    onShutdown?: (signal: GracefulShutdownSignal) => Promise<void> | void;
+};
+export type GracefulShutdownCleanup = () => void;

package/dist/sdk/verify.js

@@ -33,5 +33,6 @@ export async function verifyFlowJWT(token, opts) {
     });
     if (!payload.sub)
         throw new Error("JWT missing sub");
+    /* SAFETY: jwtVerify already checked the signature, issuer and audience against this issuer's own keys, and `sub` is checked above. */
     return payload;
 }

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

@@ -1,3 +1,4 @@
+import type { RawValue } from "../json";
 import type { FlowConnectorParameters } from "../types";
 /**
  * Wagmi connector adapter for Flow. Drop into your wagmi config with
@@ -17,9 +18,12 @@ import type { FlowConnectorParameters } from "../types";
  * wagmi state stays in sync when login/logout happens via the SDK rather
  * than through wagmi's own `connect()`.
  */
-export declare function flowConnector(parameters?: FlowConnectorParameters): import("@wagmi/core").CreateConnectorFn<{
-    request: (...args: unknown[]) => Promise<unknown>;
-}, Record<string, unknown>, Record<string, unknown>>;
+/** The minimal EIP-1193 surface wagmi needs from this connector. */
+type FlowProvider = {
+    request: (...args: RawValue[]) => Promise<RawValue>;
+};
+export declare function flowConnector(parameters?: FlowConnectorParameters): import("@wagmi/core").CreateConnectorFn<FlowProvider, Record<string, unknown>, Record<string, unknown>>;
 export declare namespace flowConnector {
     var type: "flow";
 }
+export {};

package/dist/sdk/wagmi/index.js

@@ -5,33 +5,14 @@ flowConnector.type = "flow";
 function loginOptionsFromCapabilities(capabilities) {
     const signUp = capabilities?.type === "sign-up" || capabilities?.createAccount;
     const signIn = capabilities?.type === "sign-in" || capabilities?.signIn;
+    const headless = !signUp &&
+        (capabilities?.signInHeadless || capabilities?.type === "sign-in");
     return {
-        ...(signUp ? { signUp: true } : {}),
-        ...(!signUp && signIn ? { signIn: true } : {}),
-        ...(!signUp &&
-            (capabilities?.signInHeadless || capabilities?.type === "sign-in")
-            ? { signInHeadless: true }
-            : {}),
+        signUp: signUp ? true : undefined,
+        signIn: !signUp && signIn ? true : undefined,
+        signInHeadless: headless ? true : undefined,
     };
 }
-/**
- * Wagmi connector adapter for Flow. Drop into your wagmi config with
- * `connectors: [flowConnector()]` — no arguments needed in the common case.
- *
- * Resolution order for the underlying Flow instance:
- *  1. `parameters.flow` (explicit override — useful for tests)
- *  2. The Flow singleton set by a prior `createFlow()` call
- *  3. Lazily created on first connector use (also sets the singleton)
- *
- * This means wagmi-only apps get a working Flow without ever calling
- * `createFlow`, and apps mixing wagmi + direct SDK calls automatically
- * share state because they all resolve to the same singleton.
- *
- * The `setup()` method subscribes to the Flow store and emits wagmi
- * `connect`/`disconnect` events whenever the address changes — that's how
- * wagmi state stays in sync when login/logout happens via the SDK rather
- * than through wagmi's own `connect()`.
- */
 export function flowConnector(parameters = {}) {
     let flow = parameters.flow ?? null;
     return createConnector((config) => {
@@ -64,6 +45,8 @@ export function flowConnector(parameters = {}) {
                         return;
                     lastAddress = next;
                     if (next) {
+                        /* SAFETY: wagmi types `accounts` as a readonly tuple of its own `Address` brand;
+                           `next` is the checksummed address this connector just resolved. */
                         config.emitter.emit("connect", {
                             accounts: [next],
                             chainId: config.chains[0]?.id ?? 1,
@@ -76,6 +59,7 @@ export function flowConnector(parameters = {}) {
             },
             async connect(params = {}) {
                 const f = getFlow();
+                // SAFETY: wagmi passes its own connect options; WagmiConnectParams names the subset read.
                 const connectParams = params;
                 const isReconnecting = connectParams.isReconnecting;
                 // Wagmi calls connect({ isReconnecting: true }) on mount when it
@@ -135,15 +119,18 @@ export function flowConnector(parameters = {}) {
             },
             async getClient({ chainId } = {}) {
                 const f = getFlow();
-                return f.walletClient({ ...(chainId ? { chainId } : {}) });
+                /* SAFETY: wagmi types getClient against viem's Client generic over its own chain
+                   config; the Flow wallet client implements that surface. */
+                return f.walletClient(chainId ? { chainId } : {});
             },
-            async getProvider({ chainId } = {}) {
-                const client = await this.getClient({
-                    ...(chainId ? { chainId } : {}),
-                });
-                return {
-                    request: client.request,
-                };
+            async getProvider(options = {}) {
+                const client = await this.getClient?.({ chainId: options.chainId });
+                /* SAFETY: the wallet client viem builds always carries `request`; wagmi's Client type
+                   does not name it, which is the only reason this is stated rather than inferred. */
+                const request = Object.entries(Object(client)).find(([k]) => k === "request")?.[1];
+                /* SAFETY: the wallet client viem builds always carries `request`; wagmi's Client type
+                   does not name it, which is the only reason this is read by name. */
+                return { request: request };
             },
             onAccountsChanged() { },
             onChainChanged(chain) {