@flow-industries/id 0.16.0 → 0.17.0

package/dist/sdk/client/flow-widget.d.ts

@@ -0,0 +1,20 @@
+import type { FlowWidgetHandle, MountFlowWidgetOptions } from "../types";
+/**
+ * Mounts one of the inline Flow ID widgets — the XP strip, the action timer —
+ * as a transparent iframe the embedder positions and sizes itself.
+ *
+ * The reason this exists rather than embedders hand-rolling an `<iframe>`: the
+ * widget reads the Flow ID API from a cross-site frame, where its own origin's
+ * cookie is unavailable or bound to a different audience, so it needs the
+ * host's access token. It gets one by asking over the postMessage bridge, and
+ * only a frame that received the `init` handshake knows which origin to ask.
+ * A hand-rolled iframe never sends `init` and never gets an answer, so it is
+ * silently limited to whatever the cookie happens to allow (AUTH-171).
+ *
+ * The handle exposes the frame instead of styling it, because each embedder
+ * wants different geometry (the in-game overlay is fixed and click-through,
+ * the menu's is a laid-out block) and none of that belongs in the SDK.
+ *
+ * No-op under SSR.
+ */
+export declare function createFlowWidget(options: MountFlowWidgetOptions): FlowWidgetHandle;

package/dist/sdk/client/flow-widget.js

@@ -0,0 +1,78 @@
+import { resolveIdHost } from "../id-host";
+import { getFlow, requireFlow } from "./create-flow";
+import { answerTokenRequest, bridgeToWindow, makeIframe } from "./iframe-host";
+/**
+ * The inline widgets an embedder may mount, mapped to the dialog routes that
+ * serve them. Callers name a widget rather than passing a route so the dialog's
+ * URL space stays an internal detail and an embedder can't point this at an
+ * auth route, which would render a sign-in ceremony inside a decorative frame.
+ */
+const WIDGET_ROUTE = {
+    xp: "/dialog/xp-widget",
+    "action-timer": "/dialog/action-timer",
+};
+/**
+ * Mounts one of the inline Flow ID widgets — the XP strip, the action timer —
+ * as a transparent iframe the embedder positions and sizes itself.
+ *
+ * The reason this exists rather than embedders hand-rolling an `<iframe>`: the
+ * widget reads the Flow ID API from a cross-site frame, where its own origin's
+ * cookie is unavailable or bound to a different audience, so it needs the
+ * host's access token. It gets one by asking over the postMessage bridge, and
+ * only a frame that received the `init` handshake knows which origin to ask.
+ * A hand-rolled iframe never sends `init` and never gets an answer, so it is
+ * silently limited to whatever the cookie happens to allow (AUTH-171).
+ *
+ * The handle exposes the frame instead of styling it, because each embedder
+ * wants different geometry (the in-game overlay is fixed and click-through,
+ * the menu's is a laid-out block) and none of that belongs in the SDK.
+ *
+ * No-op under SSR.
+ */
+export function createFlowWidget(options) {
+    if (typeof document === "undefined")
+        return {
+            frame: null,
+            post() { },
+            destroy() { },
+        };
+    const flow = options.flow ?? getFlow() ?? requireFlow();
+    const host = resolveIdHost(options.host ?? flow.host);
+    const hostOrigin = new URL(host).origin;
+    const theme = options.theme ?? "light dark";
+    const route = WIDGET_ROUTE[options.widget];
+    const frame = makeIframe(`${host}${route}`);
+    frame.style.background = "transparent";
+    const container = options.container ?? document.body;
+    // Appended before bridging: `contentWindow` is null until the frame is in the
+    // document, and the bridge is bound to that window.
+    container.appendChild(frame);
+    const bridge = bridgeToWindow(frame.contentWindow, {
+        targetOrigin: hostOrigin,
+    });
+    bridge.on("__internal", (payload) => {
+        if (payload.type === "profile-token-request")
+            void answerTokenRequest(bridge, flow, payload.id);
+    });
+    // The widget already loads its own route directly, so `route` here only
+    // confirms where the frame is; what the handshake is really for is telling
+    // the dialog which origin it is embedded by, which is what it later asks for
+    // a token.
+    void bridge.send("__internal", {
+        type: "init",
+        mode: "iframe",
+        referrer: { title: document.title },
+        theme: { colorScheme: theme },
+        route,
+    });
+    return {
+        frame,
+        post(message) {
+            frame.contentWindow?.postMessage(message, hostOrigin);
+        },
+        destroy() {
+            bridge.destroy();
+            frame.remove();
+        },
+    };
+}

package/dist/sdk/client/iframe-host.d.ts

@@ -1,4 +1,5 @@
 import * as Messenger from "../dialog/remote/Messenger";
+import type { Flow } from "../types";
 /**
  * Permissions the dialog iframe needs to run WebAuthn passkey ceremonies and
  * copy recovery values. Shared by every Flow iframe host (the dialog host and
@@ -21,3 +22,14 @@ export declare function makeIframe(src: string): HTMLIFrameElement;
 export declare function bridgeToWindow(target: Window, options?: {
     targetOrigin?: string;
 }): Messenger.Bridge;
+/**
+ * Answers a widget's request for the host's credential. Every Flow iframe that
+ * reads the Flow ID API from a cross-site frame asks for this, because its own
+ * origin's cookie is unavailable or bound to another audience there.
+ *
+ * `getToken` refreshes a token that is missing or near expiry, so a widget left
+ * open past the 1h access-token lifetime still gets a live one rather than a
+ * 401. A failure answers `null` — "no session", which widgets render as signed
+ * out — instead of leaving the request to time out.
+ */
+export declare function answerTokenRequest(bridge: Messenger.Bridge, flow: Flow, id: string): Promise<void>;

package/dist/sdk/client/iframe-host.js

@@ -32,3 +32,17 @@ export function bridgeToWindow(target, options = {}) {
         waitForReady: true,
     });
 }
+/**
+ * Answers a widget's request for the host's credential. Every Flow iframe that
+ * reads the Flow ID API from a cross-site frame asks for this, because its own
+ * origin's cookie is unavailable or bound to another audience there.
+ *
+ * `getToken` refreshes a token that is missing or near expiry, so a widget left
+ * open past the 1h access-token lifetime still gets a live one rather than a
+ * 401. A failure answers `null` — "no session", which widgets render as signed
+ * out — instead of leaving the request to time out.
+ */
+export async function answerTokenRequest(bridge, flow, id) {
+    const token = await flow.getToken().catch(() => null);
+    void bridge.send("__internal", { type: "profile-token", id, token });
+}

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

@@ -1,7 +1,8 @@
 export { defaultIdHost, isLocalHostname } from "../id-host";
-export type { AccessKeyOptions, AdditionalSession, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, LoginOptions, MethodName, MountProfileOptions, ProfileButtonHandle, ProfilePosition, Session, } from "../types";
+export type { AccessKeyOptions, AdditionalSession, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, LoginOptions, MethodName, MountFlowWidgetOptions, MountProfileOptions, ProfileButtonHandle, ProfilePosition, Session, } from "../types";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
+export { createFlowWidget } from "./flow-widget";
 export { METHODS } from "./methods";
 export { createProfileButton } from "./profile-button";
 export { createRoomsApi, RoomsRequestError } from "./rooms";

package/dist/sdk/client/index.js

@@ -1,6 +1,7 @@
 export { defaultIdHost, isLocalHostname } from "../id-host";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
+export { createFlowWidget } from "./flow-widget";
 export { METHODS } from "./methods";
 export { createProfileButton } from "./profile-button";
 export { createRoomsApi, RoomsRequestError } from "./rooms";

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

@@ -1,6 +1,6 @@
 import { resolveIdHost } from "../id-host";
 import { getFlow, requireFlow } from "./create-flow";
-import { bridgeToWindow, makeIframe } from "./iframe-host";
+import { answerTokenRequest, bridgeToWindow, makeIframe } from "./iframe-host";
 const POSITION_STYLE = {
     "top-right": { top: "0", right: "0" },
     "top-left": { top: "0", left: "0" },
@@ -81,13 +81,6 @@ export function createProfileButton(options) {
             ? { username: user.username, isGuest: user.isGuest === true }
             : null;
     }
-    // The widget's only credential. `getToken` refreshes a token that is missing
-    // or near expiry, so a widget open on a page left idle past the 1h access-
-    // token lifetime still gets a live one instead of a 401.
-    async function answerTokenRequest(bridge, id) {
-        const token = await flow.getToken().catch(() => null);
-        void bridge.send("__internal", { type: "profile-token", id, token });
-    }
     // ----- the persistent pill (stays mounted; sizes to its own content) -----
     const pill = makeFrame();
     let pillWidth = 0;
@@ -113,7 +106,7 @@ export function createProfileButton(options) {
             showDialog();
         }
         else if (payload.type === "profile-token-request") {
-            void answerTokenRequest(pillBridge, payload.id);
+            void answerTokenRequest(pillBridge, flow, payload.id);
         }
     });
     // ----- the dialog overlay (lazy; a separate fullscreen iframe layered ABOVE
@@ -143,7 +136,7 @@ export function createProfileButton(options) {
             }
             else if (payload.type === "profile-token-request") {
                 if (dialogBridge)
-                    void answerTokenRequest(dialogBridge, payload.id);
+                    void answerTokenRequest(dialogBridge, flow, payload.id);
             }
         });
         void dialogBridge.send("__internal", {

package/dist/sdk/react/flow-widget.d.ts

@@ -0,0 +1,12 @@
+import type { FlowWidgetProps } from "../types";
+/**
+ * Drops an inline Flow ID widget — the XP strip, the action timer — into a
+ * React tree. Renders a host element (style it via `className` for placement
+ * and size) that the widget iframe fills. Resolves the Flow instance from a
+ * `<FlowIdProvider>` or the createFlow() singleton.
+ *
+ * Prefer this over embedding the widget's URL in your own `<iframe>`: only a
+ * frame mounted this way completes the handshake that lets it authenticate as
+ * the signed-in user from a cross-site page (AUTH-171).
+ */
+export declare function FlowWidget({ widget, className, host, theme, }: FlowWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist/sdk/react/flow-widget.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { createFlowWidget } from "../client/flow-widget";
+import { useFlow } from "./hooks";
+/**
+ * Drops an inline Flow ID widget — the XP strip, the action timer — into a
+ * React tree. Renders a host element (style it via `className` for placement
+ * and size) that the widget iframe fills. Resolves the Flow instance from a
+ * `<FlowIdProvider>` or the createFlow() singleton.
+ *
+ * Prefer this over embedding the widget's URL in your own `<iframe>`: only a
+ * frame mounted this way completes the handshake that lets it authenticate as
+ * the signed-in user from a cross-site page (AUTH-171).
+ */
+export function FlowWidget({ widget, className, host, theme, }) {
+    const flow = useFlow();
+    const ref = useRef(null);
+    useEffect(() => {
+        const container = ref.current;
+        if (!container)
+            return;
+        const handle = createFlowWidget({
+            widget,
+            container,
+            flow,
+            ...(host ? { host } : {}),
+            ...(theme ? { theme } : {}),
+        });
+        if (handle.frame) {
+            handle.frame.style.width = "100%";
+            handle.frame.style.height = "100%";
+            handle.frame.style.display = "block";
+        }
+        return () => handle.destroy();
+    }, [widget, flow, host, theme]);
+    return _jsx("div", { ref: ref, className: className });
+}

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

@@ -1,4 +1,5 @@
-export type { FlowIdProviderProps, ProfileButtonProps } from "../types";
+export type { FlowIdProviderProps, FlowWidgetProps, ProfileButtonProps, } from "../types";
+export { FlowWidget } from "./flow-widget";
 export { useFlow, useFlowId, useFlowState, useRoom, useRooms } from "./hooks";
 export { ProfileButton } from "./profile-button";
 export { FlowIdProvider } from "./provider";

package/dist/sdk/react/index.js

@@ -1,3 +1,4 @@
+export { FlowWidget } from "./flow-widget";
 export { useFlow, useFlowId, useFlowState, useRoom, useRooms } from "./hooks";
 export { ProfileButton } from "./profile-button";
 export { FlowIdProvider } from "./provider";

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";
+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 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 {
@@ -37,6 +37,13 @@ export interface AuthEventRecord {
     userAgent: string | null;
     durationMs: number | null;
     traceId: string | null;
+    /** Room-event scheduler fields: which series and dated instance a transition
+     * or dispatch was about, and for a dispatch, which reminder and how many
+     * subscribers it reached. */
+    roomEventId: string | null;
+    occurrenceId: string | null;
+    dispatchKind: string | null;
+    recipients: number | null;
 }
 /** Body accepted by `POST /api/events` from the dialog. */
 export interface BeaconBody {

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

@@ -4,8 +4,9 @@ export type { AuthErrorCode, AuthEventName, AuthEventRecord, AuthMode, AuthOutco
 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 { CreateRoomInput, GlobalRole, ModerationSubject, MyRooms, RoleChangeVerdict, RoomChannel, RoomDetail, RoomList, RoomMemberEntry, RoomMembers, RoomOccupancy, RoomOwner, RoomPresenceEntry, RoomPresenceSnapshot, RoomRestrictionKind, RoomRole, RoomSummary, RoomSurfaceSettings, RoomsApi, RoomVisibility, StaffEntry, UpdateRoomInput, VerifyRoomContext, } from "./rooms";
-export type { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowCookieNames, FlowIdProviderProps, FlowSessionState, FlowState, Listener, LoginOptions, 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 { 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 { AccessKeyOptions, AccessKeyPreparation, Address, 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 { 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/room-events.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Room events — scheduled happenings inside a room, shared by the server
+ * routes and the client SDK.
+ *
+ * Deliberately named `room-events` throughout: `types/events.ts` and
+ * `routes/events.ts` already mean structured product/telemetry events, and the
+ * two must never blur.
+ *
+ * Two shapes, and which one an endpoint speaks is load-bearing. A
+ * {@link RoomEventSeries} is what an owner authors and edits; an instance is
+ * one dated occurrence of it. Players only ever address occurrences — interest,
+ * reminders and attendance all attach to an instance, so a weekly race's third
+ * week is a thing in its own right.
+ */
+/** Discord's Guild Scheduled Event lifecycle, mirrored exactly. */
+export type RoomEventStatus = "scheduled" | "active" | "completed" | "cancelled";
+export type RoomEventFrequency = "daily" | "weekly" | "monthly";
+/**
+ * The RRULE subset a series may repeat on. Expanded in the event's IANA
+ * timezone by the (db-free) expander, never in UTC. `until` is an ISO instant;
+ * `until` and `count` are mutually exclusive and both may be absent for an
+ * open-ended series.
+ */
+export interface RoomEventRecurrence {
+    freq: RoomEventFrequency;
+    interval?: number;
+    /** 0 = Sunday … 6 = Saturday, matching `Date.prototype.getDay`. */
+    byweekday?: number[];
+    bymonthday?: number[];
+    until?: string;
+    count?: number;
+}
+/** The room an event belongs to, denormalized so a listing needs no second read. */
+export interface RoomEventRoomRef {
+    id: string;
+    slug: string;
+    displayName: string;
+}
+/**
+ * Interest in one dated instance. `interestedCount` is public; the two viewer
+ * flags are meaningful only when the request carried a bearer and read false
+ * otherwise — the same shape the room payload uses for the caller's role.
+ *
+ * A player counts as interested in an instance either by marking that instance
+ * or by following its whole series, so `viewerInterested` can be true while
+ * `viewerFollowing` is what actually produced it.
+ */
+export interface RoomEventInterest {
+    interestedCount: number;
+    viewerInterested: boolean;
+    viewerFollowing: boolean;
+}
+/**
+ * One dated instance, as it appears under the series that owns it: only what
+ * differs per instance, since the series already carries the title, room and
+ * timezone. `startsAt`/`endsAt` are ISO instants in UTC — render them in the
+ * series' `timezone` to show the local time the owner scheduled.
+ */
+export interface RoomEventInstance extends RoomEventInterest {
+    id: string;
+    startsAt: string;
+    endsAt: string | null;
+    status: RoomEventStatus;
+    /** Moved or cancelled on its own, so a series-wide edit leaves it alone. */
+    overridden: boolean;
+    /** Written once the instance completes — the history view reads these rather
+     * than scanning presence. Null while it has not finished. */
+    attendance: RoomEventAttendance | null;
+}
+/** What actually happened, as observed from room presence while it ran. */
+export interface RoomEventAttendance {
+    attendeeCount: number;
+    peakConcurrent: number;
+    startedAt: string | null;
+    endedAt: string | null;
+}
+/** An instance standing on its own in a listing, carrying enough of its series
+ * and room to render a card. */
+export interface RoomEventOccurrence extends RoomEventInstance {
+    eventId: string;
+    room: RoomEventRoomRef;
+    title: string;
+    description: string | null;
+    coverUrl: string | null;
+    timezone: string;
+    /** True when the parent series repeats, so a card can badge it as recurring. */
+    recurring: boolean;
+    createdBy: string | null;
+}
+/** The authored series, with the instances it has materialized so far. */
+export interface RoomEventSeries {
+    id: string;
+    room: RoomEventRoomRef;
+    title: string;
+    description: string | null;
+    coverUrl: string | null;
+    startsAt: string;
+    endsAt: string | null;
+    timezone: string;
+    recurrence: RoomEventRecurrence | null;
+    /** Minutes before the start at which subscribers are reminded; null is the
+     * default schedule, an empty list is silence. */
+    reminderOffsets: number[] | null;
+    status: RoomEventStatus;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    occurrences: RoomEventInstance[];
+}
+export interface RoomEventList {
+    events: RoomEventOccurrence[];
+}
+export interface CreateRoomEventInput {
+    title: string;
+    description?: string | null;
+    coverUrl?: string | null;
+    startsAt: string;
+    endsAt?: string | null;
+    timezone?: string;
+    recurrence?: RoomEventRecurrence | null;
+    reminderOffsets?: number[] | null;
+}
+/** Every create field, all optional — a patch is merged over the stored row and
+ * validated by the same rules, so the two shapes can never drift. */
+export type UpdateRoomEventInput = Partial<CreateRoomEventInput>;
+export interface SetInterestInput {
+    /** Also follow (or unfollow) the whole series, not just this instance. */
+    series?: boolean;
+}
+/** What the interest endpoints answer with, so a card can update in place. */
+export interface RoomEventInterestState extends RoomEventInterest {
+    occurrenceId: string;
+}

package/dist/sdk/types/room-events.js

@@ -0,0 +1,14 @@
+/**
+ * Room events — scheduled happenings inside a room, shared by the server
+ * routes and the client SDK.
+ *
+ * Deliberately named `room-events` throughout: `types/events.ts` and
+ * `routes/events.ts` already mean structured product/telemetry events, and the
+ * two must never blur.
+ *
+ * Two shapes, and which one an endpoint speaks is load-bearing. A
+ * {@link RoomEventSeries} is what an owner authors and edits; an instance is
+ * one dated occurrence of it. Players only ever address occurrences — interest,
+ * reminders and attendance all attach to an instance, so a weekly race's third
+ * week is a thing in its own right.
+ */

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

@@ -18,6 +18,14 @@ export interface ModerationSubject {
     globalRole: GlobalRole;
     roomRole: RoomRole | null;
 }
+/** A verified caller resolved against one room: the raw composite the rank
+ * lattice needs, plus the wire projection every route-side gate compares. */
+export interface Viewer {
+    sub: string;
+    guest: boolean;
+    subject: ModerationSubject;
+    role: RoomRole | null;
+}
 /** One row of `GET /api/admin/staff` — a user holding a non-`user` tier. */
 export interface StaffEntry {
     userId: string;

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

@@ -217,6 +217,54 @@ export type ProfileButtonHandle = {
     /** Tears down the iframe, listeners, and any auto-created container. */
     destroy: () => void;
 };
+/** The inline Flow ID widgets an embedder can mount alongside its own UI. */
+export type FlowWidgetName = "xp" | "action-timer";
+export type MountFlowWidgetOptions = {
+    /** Which inline widget to mount. */
+    widget: FlowWidgetName;
+    /**
+     * Element to append the widget iframe to. Defaults to `document.body`, which
+     * is what a fixed-position overlay wants; pass a container to lay the widget
+     * out inline instead.
+     */
+    container?: HTMLElement;
+    /**
+     * The Flow ID origin serving the widget (e.g. https://id.flow.industries).
+     * Defaults to the resolved Flow instance's `host`, then the SDK default.
+     */
+    host?: string;
+    /**
+     * Color scheme for the widget chrome. Set this to match the host (the dark
+     * game UI passes "dark"). Defaults to "light dark" (follows the OS).
+     */
+    theme?: "light" | "dark" | "light dark";
+    /** Explicit Flow instance. Defaults to the createFlow() singleton. */
+    flow?: Flow;
+};
+export type FlowWidgetHandle = {
+    /**
+     * The mounted iframe, so the embedder owns geometry and visibility. Null
+     * under SSR, where nothing was mounted.
+     */
+    readonly frame: HTMLIFrameElement | null;
+    /**
+     * Sends a widget-specific message (e.g. `{ type: "xp-refresh" }`), pinned to
+     * the Flow ID origin.
+     */
+    post: (message: unknown) => void;
+    /** Tears down the iframe and its bridge. */
+    destroy: () => void;
+};
+export type FlowWidgetProps = {
+    /** Which inline widget to mount. */
+    widget: FlowWidgetName;
+    /** Class applied to the host element the widget iframe fills. */
+    className?: string;
+    /** Override the Flow ID origin; defaults to the resolved Flow's `host`. */
+    host?: string;
+    /** Color scheme for the widget chrome; defaults to "light dark" (the OS). */
+    theme?: "light" | "dark" | "light dark";
+};
 export type DialogHost = {
     open: (options?: DialogOpenOptions) => void;
     close: () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "main": "./dist/sdk/client/index.js",
   "module": "./dist/sdk/client/index.js",
   "types": "./dist/sdk/client/index.d.ts",
@@ -58,6 +58,7 @@
     "build:sdk": "tsc --project tsconfig.sdk.json",
     "prepublishOnly": "bun run build:sdk",
     "start": "bun run src/index.ts",
+    "worker": "bun run src/worker.ts",
     "email:dev": "email dev --dir src/emails --port 3010",
     "db:generate": "bunx @better-auth/cli generate",
     "db:migrate:gen": "bunx drizzle-kit generate",