@flow-industries/id 0.18.0 → 0.19.1

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/events.d.ts

@@ -9,7 +9,7 @@ export type AuthOutcome = "success" | "failure" | "info";
 export type AuthMode = "sign-up" | "sign-in";
 /** Client-only funnel steps reported via the `/api/events` beacon. */
 export type FunnelStep = "mode_selected" | "email_entered" | "ceremony_started" | "ceremony_failed" | "done_shown";
-export type AuthEventName = "auth.username.checked" | "auth.signup.succeeded" | "auth.signup.failed" | "auth.otp.sent" | "auth.otp.verified" | "auth.otp.failed" | "auth.email.verify.sent" | "auth.email.verify.succeeded" | "auth.email.verify.failed" | "auth.email.changed" | "auth.avatar.upload.succeeded" | "auth.avatar.upload.failed" | "auth.challenge.issued" | "auth.signin.succeeded" | "auth.signin.failed" | "auth.passkey.added" | "auth.passkey.add_failed" | "auth.restore.succeeded" | "auth.restore.failed" | "auth.restore.no_session" | "auth.refresh.succeeded" | "auth.refresh.failed" | "auth.refresh.reuse" | "auth.refresh.grace" | "auth.jwt.verified" | "auth.jwt.rejected" | "auth.signout" | "auth.session.revoked" | "auth.session.revoked_all" | "auth.audience.rejected" | "auth.audience.minted" | "auth.guest.created" | "auth.guest.restored" | "auth.guest.upgraded" | "auth.guest.failed" | "auth.role.granted" | "auth.role.revoked" | "auth.funnel.mode_selected" | "auth.funnel.email_entered" | "auth.funnel.ceremony_started" | "auth.funnel.ceremony_failed" | "auth.funnel.done_shown" | "room_event.activated" | "room_event.completed" | "room_event.reminder_dispatched" | "room_event.reminder_failed";
+export type AuthEventName = "auth.username.checked" | "auth.signup.succeeded" | "auth.signup.failed" | "auth.otp.sent" | "auth.otp.verified" | "auth.otp.failed" | "auth.email.verify.sent" | "auth.email.verify.succeeded" | "auth.email.verify.failed" | "auth.email.changed" | "auth.avatar.upload.succeeded" | "auth.avatar.upload.failed" | "auth.challenge.issued" | "auth.signin.succeeded" | "auth.signin.failed" | "auth.passkey.added" | "auth.passkey.add_failed" | "auth.restore.succeeded" | "auth.restore.failed" | "auth.restore.no_session" | "auth.refresh.succeeded" | "auth.refresh.failed" | "auth.refresh.reuse" | "auth.refresh.grace" | "auth.jwt.verified" | "auth.jwt.rejected" | "auth.signout" | "auth.session.revoked" | "auth.session.revoked_all" | "auth.audience.rejected" | "auth.audience.minted" | "auth.guest.created" | "auth.guest.restored" | "auth.guest.upgraded" | "auth.guest.failed" | "auth.role.granted" | "auth.role.revoked" | "room.restriction.issued" | "room.restriction.lifted" | "auth.funnel.mode_selected" | "auth.funnel.email_entered" | "auth.funnel.ceremony_started" | "auth.funnel.ceremony_failed" | "auth.funnel.done_shown" | "room_event.activated" | "room_event.completed" | "room_event.reminder_dispatched" | "room_event.reminder_failed";
 export type AuthErrorCode = "username_taken" | "credential_taken" | "email_taken" | "email_not_verified" | "no_email" | "image_upload_forbidden" | "image_upload_rate_limited" | "invalid_image_type" | "image_too_large" | "image_upload_failed" | "otp_invalid" | "otp_expired" | "otp_attempts_exceeded" | "otp_resend_cooldown" | "otp_resend_limit" | "otp_global_limit" | "otp_send_failed" | "challenge_expired" | "unknown_credential" | "invalid_assertion_type" | "invalid_assertion_origin" | "user_verification_required" | "invalid_signature" | "user_not_found" | "missing_audience" | "audience_not_allowed" | "audience_mismatch" | "no_session" | "no_passkey" | "refresh_token_invalid" | "refresh_token_expired" | "refresh_epoch_stale" | "refresh_user_epoch_stale" | "refresh_reuse_detected" | "guest_rate_limited" | "guest_global_limit" | "guest_username_exhausted" | "guest_session" | "passkey_exists" | "already_upgraded" | "malformed_token" | "unknown_key" | "verification_failed" | "webauthn_not_allowed" | "webauthn_security" | "webauthn_invalid_state" | "webauthn_not_supported" | "webauthn_constraint" | "webauthn_aborted" | "webauthn_unknown" | "internal_error";
 /** One flat record per event = one row in the `auth_events` stream. */
 export interface AuthEventRecord {
@@ -32,6 +32,9 @@ export interface AuthEventRecord {
     actorId: string | null;
     roleFrom: GlobalRole | null;
     roleTo: GlobalRole | null;
+    roomId: string | null;
+    restrictionKind: string | null;
+    restrictionExpiresAt: string | null;
     ip: string | null;
     country: string | null;
     userAgent: string | null;

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, 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, 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";
+export type { ActionDayContext, ActionEventKind, ActionSessionState, ActionTransitionKind, 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,65 @@ 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;
+}
+export interface VoiceDecisionSubject {
+    roomId: string;
+    sub: string;
+}
+export type VoiceDecisionReason = "room_not_found" | "user_not_found" | "banned" | "private_not_member";
+/** Current server-authoritative room admission and shared text/voice mute
+ * state for one active LiveKit participant. */
+export interface VoiceRoomDecision extends VoiceDecisionSubject {
+    admitted: boolean;
+    muted: boolean;
+    mutedUntil: string | null;
+    reason?: VoiceDecisionReason;
+}
+/**
+ * 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 +178,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 +205,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 +220,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/types/xp.d.ts

@@ -43,17 +43,18 @@ export interface ActionDayContext {
     priorMinutes: number;
     flowScore: number;
 }
-/** Lifecycle state of a durable action session. `abandoned` is set by the
- * orphan reaper when the game server stops heartbeating a still-active
- * session (e.g. a server crash). */
+/** Lifecycle state of a durable action session. `abandoned` is set when the
+ * janitor finds a session older than the safety window; it never grants XP. */
 export type ActionSessionState = "active" | "finished" | "abandoned";
 /** An action-session transition kind, appended to the action_event log.
- * `focus_lost`/`focus_gained` mark the tab going background/foreground — accrual
- * never stops (they only split focused vs unfocused time for stats). */
-export type ActionEventKind = "start" | "focus_lost" | "focus_gained" | "finish" | "abandon";
+ * Paused intervals do not accrue; focus transitions split the accrued time for
+ * stats without stopping it. */
+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 server-authoritative accrued duration. (Always an
+ * live XP estimate from the timestamp-derived accrued duration. (Always an
  * `active` session by definition, so the lifecycle state isn't carried.) */
 export interface ActiveActionResponse extends ActionDayContext {
     source: string;

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 {};