@crowdedkingdomstudios/crowdyjs 5.1.0 → 5.2.1

package/dist/realtime.d.ts

@@ -2,60 +2,214 @@ import type { SessionStore } from './session.js';
 import type { CrowdyLogger } from './logger.js';
 import { CrowdyRealtimeError } from './errors.js';
 import { type UdpNotificationsSubscription } from './generated/graphql.js';
+/**
+ * Lifecycle state of the realtime WebSocket connection, as reported by
+ * {@link RealtimeClient.status} and {@link RealtimeClient.onStatus}.
+ *
+ * - `idle` — created but never connected; no socket open yet.
+ * - `connecting` — opening the socket / performing the initial handshake.
+ * - `connected` — the subscription is live and receiving notifications.
+ * - `reconnecting` — the socket dropped (or a retry is in progress) while a
+ *   connection is still desired; backoff is running and it will resubscribe.
+ * - `disconnected` — intentionally closed (e.g. {@link RealtimeClient.disconnect}
+ *   or the last subscriber unsubscribing).
+ * - `failed` — a fatal, non-retryable error (e.g. not authenticated, or a
+ *   non-retryable `RealtimeConnectionEvent` such as `APP_ID_REQUIRED`); it will
+ *   not reconnect on its own.
+ */
 export type RealtimeStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'failed';
+/**
+ * Any single message delivered on the `udpNotifications` subscription — the
+ * union of every spatial echo/fan-out notification plus `GenericErrorResponse`
+ * and `RealtimeConnectionEvent`. This is the codegen-derived (canonical)
+ * shape, narrowed to the non-null payload; discriminate the members by their
+ * `__typename`.
+ */
 export type UdpNotification = NonNullable<UdpNotificationsSubscription['udpNotifications']>;
+/**
+ * The members of {@link UdpNotification} that carry a `sequenceNumber` and can
+ * therefore be correlated back to the send that produced them — the spatial
+ * echoes/fan-out (actor/voxel/audio/text/event notifications and responses,
+ * single-actor and channel messages) plus `GenericErrorResponse`. Excludes
+ * `RealtimeConnectionEvent`, which has no sequence number.
+ *
+ * {@link RealtimeClient.waitForSequence} resolves with one of these when a
+ * matching success arrives (it rejects instead when the match is a
+ * `GenericErrorResponse`), which is what powers the `...AndWait` spatial sends.
+ */
 export type SpatialNotification = Extract<UdpNotification, {
     sequenceNumber: number;
 }>;
+/**
+ * Per-notification callbacks passed to `client.udp.subscribe(handlers, appId)`
+ * (or `client.world(appId).subscribe`). Every handler is optional — supply
+ * only the ones you care about. Each key maps a notification's GraphQL
+ * `__typename` to its callback, except {@link any} and {@link error}, which are
+ * special (see below).
+ *
+ * Handlers are dispatched synchronously as messages arrive, and exceptions
+ * thrown inside one are caught and logged so a single bad handler can't tear
+ * down the stream. For each notification {@link any} runs first, then the
+ * matching typed handler.
+ */
 export interface UdpNotificationHandlers {
+    /**
+     * Another actor's position/state changed within your area of interest —
+     * the spatial fan-out of someone else's `sendActorUpdate`. `state` is
+     * base64-encoded actor state.
+     */
     actorUpdate?: (notification: Extract<UdpNotification, {
         __typename?: 'ActorUpdateNotification';
     }>) => void;
+    /**
+     * Server acknowledgement echoing one of **your own** actor updates. This is
+     * the notification a `sendActorUpdateAndWait` correlates to via
+     * `sequenceNumber`.
+     */
     actorUpdateResponse?: (notification: Extract<UdpNotification, {
         __typename?: 'ActorUpdateResponse';
     }>) => void;
+    /**
+     * A voxel changed within range — the fan-out of another client's voxel edit.
+     * `voxelState` is base64-encoded.
+     */
     voxelUpdate?: (notification: Extract<UdpNotification, {
         __typename?: 'VoxelUpdateNotification';
     }>) => void;
+    /**
+     * Server acknowledgement echoing one of **your own** voxel updates (the
+     * `sendVoxelUpdateAndWait` correlation target).
+     */
     voxelUpdateResponse?: (notification: Extract<UdpNotification, {
         __typename?: 'VoxelUpdateResponse';
     }>) => void;
+    /**
+     * A nearby client sent a voice/audio packet; `audioData` is base64-encoded
+     * compressed audio (decode with {@link decodeBase64}).
+     */
     audio?: (notification: Extract<UdpNotification, {
         __typename?: 'ClientAudioNotification';
     }>) => void;
+    /** A nearby client sent a text/chat message (`text` is UTF-8). */
     text?: (notification: Extract<UdpNotification, {
         __typename?: 'ClientTextNotification';
     }>) => void;
+    /**
+     * A nearby client emitted a custom client event (a client-defined
+     * `eventType` with a base64 `state` payload).
+     */
     clientEvent?: (notification: Extract<UdpNotification, {
         __typename?: 'ClientEventNotification';
     }>) => void;
+    /**
+     * A server-originated spatial event broadcast to a region (e.g. world or NPC
+     * events), shaped like a client event (`eventType` + base64 `state`).
+     */
     serverEvent?: (notification: Extract<UdpNotification, {
         __typename?: 'ServerEventNotification';
     }>) => void;
+    /**
+     * A direct actor-to-actor message addressed specifically to you; `payload`
+     * is base64. There is no sender echo, so this only ever arrives on the
+     * recipient's subscription.
+     */
     singleActorMessage?: (notification: Extract<UdpNotification, {
         __typename?: 'SingleActorMessageNotification';
     }>) => void;
+    /**
+     * A message broadcast on a channel (group) you're subscribed to; `payload`
+     * is base64 and opaque to the server.
+     */
     channelMessage?: (notification: Extract<UdpNotification, {
         __typename?: 'ChannelMessageNotification';
     }>) => void;
+    /**
+     * An asynchronous error for a previously sent datagram. Correlate it to the
+     * originating send via `sequenceNumber` and read `errorCode`
+     * ({@link UdpErrorCode}) for the reason. The matching `...AndWait` promise
+     * rejects on this; the handler still fires for observability.
+     */
     genericError?: (notification: Extract<UdpNotification, {
         __typename?: 'GenericErrorResponse';
     }>) => void;
+    /**
+     * A connection-lifecycle event from the game-api (handshake / auth /
+     * routing), carrying `status`, `code`, `message`, and `retryable`. A
+     * non-retryable event such as `code: 'APP_ID_REQUIRED'` means the
+     * subscription was rejected and will not be retried automatically.
+     */
     connectionEvent?: (notification: Extract<UdpNotification, {
         __typename?: 'RealtimeConnectionEvent';
     }>) => void;
+    /**
+     * SDK-level realtime failures surfaced as a {@link CrowdyRealtimeError}
+     * (socket error, auth token cleared, subscription failed, wait timeout).
+     * This is a **client-side** signal, not a server notification.
+     */
     error?: (error: CrowdyRealtimeError) => void;
+    /**
+     * Catch-all invoked for **every** notification, before the specific typed
+     * handler above. Handy for logging, metrics, or custom dispatch.
+     */
     any?: (notification: UdpNotification) => void;
 }
+/**
+ * Tuning options for {@link RealtimeClient} (the WebSocket subscription layer),
+ * passed through from `CrowdyClient`'s `realtime` config. Every field is
+ * optional and has a default.
+ */
 export interface RealtimeConfig {
+    /**
+     * WebSocket URL of the game-api GraphQL endpoint (e.g.
+     * `wss://game.example.com/graphql`). Used when {@link wsEndpoint} is not set;
+     * falls back to `ws://localhost:3000/graphql` when both are omitted.
+     */
     wsUrl?: string;
+    /** Alias for {@link wsUrl}; used only when {@link wsUrl} is not provided. */
     wsEndpoint?: string;
+    /**
+     * Maximum number of automatic reconnect attempts after the socket drops
+     * before giving up. Defaults to `8`.
+     */
     retryAttempts?: number;
+    /**
+     * Base delay in **milliseconds** for the exponential reconnect backoff (also
+     * the upper bound of the random jitter added to each wait). Defaults to
+     * `250`.
+     */
     retryInitialDelayMs?: number;
+    /**
+     * Ceiling in **milliseconds** for the reconnect backoff, so the delay never
+     * grows past this between attempts. Defaults to `5000`.
+     */
     retryMaxDelayMs?: number;
+    /**
+     * Default time in **milliseconds** a `...AndWait` send waits for its matching
+     * echo before timing out (overridable per call via
+     * {@link RealtimeClient.waitForSequence}). Defaults to `5000`.
+     */
     waitTimeoutMs?: number;
+    /** Optional logger for realtime diagnostics. Defaults to a silent logger. */
     logger?: CrowdyLogger;
 }
+/**
+ * Manages the single WebSocket subscription to the game-api's
+ * `udpNotifications` stream — the realtime layer behind `client.udp` and
+ * `client.realtime`. It opens the socket lazily on the first {@link subscribe},
+ * authenticates with the shared session token, scopes the session to one
+ * `appId`, reconnects with jittered exponential backoff, re-reads the token and
+ * resubscribes on reconnect, fans each notification out to the registered
+ * {@link UdpNotificationHandlers}, and resolves `...AndWait` sends via
+ * {@link waitForSequence}.
+ *
+ * The connection lifecycle is observable through {@link status} /
+ * {@link onStatus} ({@link RealtimeStatus}). A realtime session is scoped to a
+ * single app, so run one client per app (sharing the same token store) for a
+ * player who is in multiple apps at once.
+ *
+ * You normally interact with this through `client.udp` / `client.realtime`
+ * rather than constructing it directly.
+ */
 export declare class RealtimeClient {
     private readonly session;
     private readonly wsUrl;
@@ -73,13 +227,85 @@ export declare class RealtimeClient {
     private readonly pending;
     private nextSubscriberId;
     private subscribedAppId;
+    /**
+     * @param config - Reconnect/timeout/endpoint tuning; see
+     *   {@link RealtimeConfig}.
+     * @param session - Shared session store. The client reads the Bearer token
+     *   from it for the connection handshake and watches it for changes: clearing
+     *   the token tears the connection down (emitting an `AUTH_CLEARED`
+     *   {@link CrowdyRealtimeError}), while a token change made while connected
+     *   forces a reconnect using the new token.
+     */
     constructor(config: RealtimeConfig | undefined, session: SessionStore);
+    /**
+     * The current connection state.
+     *
+     * @returns The latest {@link RealtimeStatus}.
+     */
     status(): RealtimeStatus;
+    /**
+     * Subscribe to connection-state changes. The listener is invoked
+     * **immediately** with the current status, then again on every transition.
+     *
+     * @param listener - Called with each new {@link RealtimeStatus}.
+     * @returns An unsubscribe function that removes the listener.
+     */
     onStatus(listener: (status: RealtimeStatus) => void): () => void;
+    /**
+     * Mark the connection as desired and open the subscription if it isn't
+     * already open. You usually don't call this directly — {@link subscribe}
+     * calls it for you; use it (or `client.realtime.connect()`) only to pre-warm
+     * the socket.
+     *
+     * @throws {CrowdyRealtimeError} `AUTH_REQUIRED` if there is no session token.
+     */
     connect(): void;
+    /**
+     * Close the socket and stop wanting a connection. Outstanding
+     * {@link waitForSequence} promises are left intact (they will time out on
+     * their own); use {@link close} to also reject those and drop all
+     * subscribers. Safe to call when already disconnected.
+     */
     disconnect(): void;
+    /**
+     * Fully tear down the client: {@link disconnect}, drop all notification
+     * subscribers, and reject every outstanding {@link waitForSequence} promise
+     * with a non-retryable {@link CrowdyRealtimeError}. Call this when disposing
+     * the SDK instance.
+     */
     close(): void;
+    /**
+     * Register a set of {@link UdpNotificationHandlers} and ensure the realtime
+     * connection is open, scoping the session to `appId`. The game-api requires
+     * an app id and rejects an app-agnostic subscription with a
+     * `RealtimeConnectionEvent` (`code: 'APP_ID_REQUIRED'`).
+     *
+     * Multiple handler sets can be registered at once; the returned function
+     * unregisters this one, and the socket closes automatically once the last
+     * subscriber unsubscribes.
+     *
+     * @param handlers - Callbacks for the notification types you care about.
+     * @param appId - The app to scope this realtime session to (decimal id;
+     *   coerced to a string). Required.
+     * @returns An unsubscribe function that removes these handlers (and
+     *   disconnects when none remain).
+     */
     subscribe(handlers: UdpNotificationHandlers, appId: string): () => void;
+    /**
+     * Return a promise that resolves when a notification carrying the given
+     * `sequenceNumber` arrives — the mechanism behind the `...AndWait` spatial
+     * sends. Resolves with the matching {@link SpatialNotification}, or rejects
+     * if that match is a `GenericErrorResponse` or the wait times out.
+     *
+     * @param sequenceNumber - The sequence number to wait for (as allocated by
+     *   {@link SequenceAllocator} and stamped on the send).
+     * @param timeoutMs - How long to wait before rejecting, in milliseconds.
+     *   Defaults to the configured {@link RealtimeConfig.waitTimeoutMs}.
+     * @returns The matching spatial notification.
+     * @throws {CrowdyRealtimeError} `UDP_SEQUENCE_TIMEOUT` (retryable) on timeout,
+     *   or carrying the server `errorCode` when the match is a
+     *   `GenericErrorResponse`.
+     */
     waitForSequence(sequenceNumber: number, timeoutMs?: number): Promise<SpatialNotification>;
     private ensureSubscription;
     private restart;

package/dist/realtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"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"}

package/dist/realtime.js

@@ -3,7 +3,34 @@ import { createClient } from 'graphql-ws';
 import { silentLogger } from './logger.js';
 import { CrowdyRealtimeError } from './errors.js';
 import { UdpNotificationsDocument, } from './generated/graphql.js';
+/**
+ * Manages the single WebSocket subscription to the game-api's
+ * `udpNotifications` stream — the realtime layer behind `client.udp` and
+ * `client.realtime`. It opens the socket lazily on the first {@link subscribe},
+ * authenticates with the shared session token, scopes the session to one
+ * `appId`, reconnects with jittered exponential backoff, re-reads the token and
+ * resubscribes on reconnect, fans each notification out to the registered
+ * {@link UdpNotificationHandlers}, and resolves `...AndWait` sends via
+ * {@link waitForSequence}.
+ *
+ * The connection lifecycle is observable through {@link status} /
+ * {@link onStatus} ({@link RealtimeStatus}). A realtime session is scoped to a
+ * single app, so run one client per app (sharing the same token store) for a
+ * player who is in multiple apps at once.
+ *
+ * You normally interact with this through `client.udp` / `client.realtime`
+ * rather than constructing it directly.
+ */
 export class RealtimeClient {
+    /**
+     * @param config - Reconnect/timeout/endpoint tuning; see
+     *   {@link RealtimeConfig}.
+     * @param session - Shared session store. The client reads the Bearer token
+     *   from it for the connection handshake and watches it for changes: clearing
+     *   the token tears the connection down (emitting an `AUTH_CLEARED`
+     *   {@link CrowdyRealtimeError}), while a token change made while connected
+     *   forces a reconnect using the new token.
+     */
     constructor(config = {}, session) {
         this.session = session;
         this.client = null;
@@ -38,9 +65,21 @@ export class RealtimeClient {
             this.restart();
         });
     }
+    /**
+     * The current connection state.
+     *
+     * @returns The latest {@link RealtimeStatus}.
+     */
     status() {
         return this.statusValue;
     }
+    /**
+     * Subscribe to connection-state changes. The listener is invoked
+     * **immediately** with the current status, then again on every transition.
+     *
+     * @param listener - Called with each new {@link RealtimeStatus}.
+     * @returns An unsubscribe function that removes the listener.
+     */
     onStatus(listener) {
         this.statusListeners.add(listener);
         listener(this.statusValue);
@@ -48,10 +87,24 @@ export class RealtimeClient {
             this.statusListeners.delete(listener);
         };
     }
+    /**
+     * Mark the connection as desired and open the subscription if it isn't
+     * already open. You usually don't call this directly — {@link subscribe}
+     * calls it for you; use it (or `client.realtime.connect()`) only to pre-warm
+     * the socket.
+     *
+     * @throws {CrowdyRealtimeError} `AUTH_REQUIRED` if there is no session token.
+     */
     connect() {
         this.desired = true;
         this.ensureSubscription();
     }
+    /**
+     * Close the socket and stop wanting a connection. Outstanding
+     * {@link waitForSequence} promises are left intact (they will time out on
+     * their own); use {@link close} to also reject those and drop all
+     * subscribers. Safe to call when already disconnected.
+     */
     disconnect() {
         this.desired = false;
         this.release?.();
@@ -60,11 +113,33 @@ export class RealtimeClient {
         this.client = null;
         this.setStatus('disconnected');
     }
+    /**
+     * Fully tear down the client: {@link disconnect}, drop all notification
+     * subscribers, and reject every outstanding {@link waitForSequence} promise
+     * with a non-retryable {@link CrowdyRealtimeError}. Call this when disposing
+     * the SDK instance.
+     */
     close() {
         this.disconnect();
         this.subscribers.clear();
         this.rejectAllPending(new CrowdyRealtimeError('Realtime client closed', { retryable: false }));
     }
+    /**
+     * Register a set of {@link UdpNotificationHandlers} and ensure the realtime
+     * connection is open, scoping the session to `appId`. The game-api requires
+     * an app id and rejects an app-agnostic subscription with a
+     * `RealtimeConnectionEvent` (`code: 'APP_ID_REQUIRED'`).
+     *
+     * Multiple handler sets can be registered at once; the returned function
+     * unregisters this one, and the socket closes automatically once the last
+     * subscriber unsubscribes.
+     *
+     * @param handlers - Callbacks for the notification types you care about.
+     * @param appId - The app to scope this realtime session to (decimal id;
+     *   coerced to a string). Required.
+     * @returns An unsubscribe function that removes these handlers (and
+     *   disconnects when none remain).
+     */
     subscribe(handlers, appId) {
         // appId is required by the type; guard for JS callers so a missing value
         // is sent as "no app" (cleanly rejected by the game-api) rather than the
@@ -80,6 +155,21 @@ export class RealtimeClient {
             }
         };
     }
+    /**
+     * Return a promise that resolves when a notification carrying the given
+     * `sequenceNumber` arrives — the mechanism behind the `...AndWait` spatial
+     * sends. Resolves with the matching {@link SpatialNotification}, or rejects
+     * if that match is a `GenericErrorResponse` or the wait times out.
+     *
+     * @param sequenceNumber - The sequence number to wait for (as allocated by
+     *   {@link SequenceAllocator} and stamped on the send).
+     * @param timeoutMs - How long to wait before rejecting, in milliseconds.
+     *   Defaults to the configured {@link RealtimeConfig.waitTimeoutMs}.
+     * @returns The matching spatial notification.
+     * @throws {CrowdyRealtimeError} `UDP_SEQUENCE_TIMEOUT` (retryable) on timeout,
+     *   or carrying the server `errorCode` when the match is a
+     *   `GenericErrorResponse`.
+     */
     waitForSequence(sequenceNumber, timeoutMs = this.waitTimeoutMs) {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {

package/dist/session.d.ts

@@ -1,27 +1,73 @@
+/** Callback notified whenever the active token changes (`null` on sign-out). */
 export type SessionListener = (token: string | null) => void;
+/**
+ * Pluggable persistence for the Bearer token. Implement this to back the
+ * session with whatever storage your runtime offers (cookies, secure storage,
+ * a database for SSR, etc.). All three methods may be sync or async.
+ *
+ * `BrowserLocalStorageTokenStore` is provided for browser apps.
+ */
 export interface TokenStore {
+    /** Return the persisted token, or `null`/`undefined` if none. */
     get(): string | null | Promise<string | null>;
+    /** Persist a token (called on login and token refresh). */
     set(token: string): void | Promise<void>;
+    /** Remove the persisted token (called on logout). */
     clear(): void | Promise<void>;
 }
+/**
+ * {@link TokenStore} backed by the browser `localStorage`. No-ops gracefully
+ * when `localStorage` is unavailable (e.g. SSR), so it's safe to construct
+ * unconditionally.
+ */
 export declare class BrowserLocalStorageTokenStore implements TokenStore {
     private readonly key;
+    /** @param key - localStorage key under which the token is stored. */
     constructor(key?: string);
     get(): string | null;
     set(token: string): void;
     clear(): void;
 }
+/**
+ * In-memory token holder with change notifications and optional persistence via
+ * a {@link TokenStore}. Setting the token fans out to every {@link onChange}
+ * listener, which is how the HTTP client and the WebSocket stay in lock-step
+ * (their auth can never drift).
+ */
 export declare class SessionStore {
     private readonly tokenStore?;
     private token;
     private readonly listeners;
+    /** @param tokenStore - Optional persistence; when omitted the token is memory-only. */
     constructor(tokenStore?: TokenStore | undefined);
+    /**
+     * Load the token from the {@link TokenStore} into memory (without re-persisting)
+     * and notify listeners. Call once on startup to resume a saved session.
+     *
+     * @returns The restored token, or `null` if none was stored.
+     */
     restore(): Promise<string | null>;
+    /** The current in-memory token, or `null` if there's no active session. */
     getToken(): string | null;
+    /**
+     * Set (or clear, with `null`) the active token. Persists to the
+     * {@link TokenStore} unless `options.persist` is `false`, then notifies all
+     * listeners. A no-op if the token is unchanged.
+     *
+     * @param token - The new Bearer token, or `null` to sign out.
+     * @param options - `persist: false` updates memory + listeners only.
+     */
     setToken(token: string | null, options?: {
         persist?: boolean;
     }): void;
+    /** Clear the active token (equivalent to `setToken(null)`). */
     clear(): void;
+    /**
+     * Subscribe to token changes. The listener fires immediately with the current
+     * token, then on every change.
+     *
+     * @returns An unsubscribe function.
+     */
     onChange(listener: SessionListener): () => void;
 }
 //# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,GAAG,IAAI,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9C,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,qBAAa,6BAA8B,YAAW,UAAU;IAClD,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,SAAmB;IAEnD,GAAG,IAAI,MAAM,GAAG,IAAI;IAKpB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKxB,KAAK,IAAI,IAAI;CAId;AAED,qBAAa,YAAY;IAIX,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAHxC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;gBAE3B,UAAU,CAAC,EAAE,UAAU,YAAA;IAE9C,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMvC,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI;IAiBzE,KAAK,IAAI,IAAI;IAIb,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI;CAOhD"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,GAAG,IAAI,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9C,2DAA2D;IAC3D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,qDAAqD;IACrD,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,qBAAa,6BAA8B,YAAW,UAAU;IAElD,OAAO,CAAC,QAAQ,CAAC,GAAG;IADhC,qEAAqE;gBACxC,GAAG,SAAmB;IAEnD,GAAG,IAAI,MAAM,GAAG,IAAI;IAKpB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKxB,KAAK,IAAI,IAAI;CAId;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IAKX,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAJxC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD,uFAAuF;gBAC1D,UAAU,CAAC,EAAE,UAAU,YAAA;IAEpD;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMvC,2EAA2E;IAC3E,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI;IAiBzE,+DAA+D;IAC/D,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI;CAOhD"}

package/dist/session.js

@@ -1,4 +1,10 @@
+/**
+ * {@link TokenStore} backed by the browser `localStorage`. No-ops gracefully
+ * when `localStorage` is unavailable (e.g. SSR), so it's safe to construct
+ * unconditionally.
+ */
 export class BrowserLocalStorageTokenStore {
+    /** @param key - localStorage key under which the token is stored. */
     constructor(key = 'crowdyjs:token') {
         this.key = key;
     }
@@ -18,20 +24,42 @@ export class BrowserLocalStorageTokenStore {
         localStorage.removeItem(this.key);
     }
 }
+/**
+ * In-memory token holder with change notifications and optional persistence via
+ * a {@link TokenStore}. Setting the token fans out to every {@link onChange}
+ * listener, which is how the HTTP client and the WebSocket stay in lock-step
+ * (their auth can never drift).
+ */
 export class SessionStore {
+    /** @param tokenStore - Optional persistence; when omitted the token is memory-only. */
     constructor(tokenStore) {
         this.tokenStore = tokenStore;
         this.token = null;
         this.listeners = new Set();
     }
+    /**
+     * Load the token from the {@link TokenStore} into memory (without re-persisting)
+     * and notify listeners. Call once on startup to resume a saved session.
+     *
+     * @returns The restored token, or `null` if none was stored.
+     */
     async restore() {
         const token = (await this.tokenStore?.get()) ?? null;
         this.setToken(token, { persist: false });
         return token;
     }
+    /** The current in-memory token, or `null` if there's no active session. */
     getToken() {
         return this.token;
     }
+    /**
+     * Set (or clear, with `null`) the active token. Persists to the
+     * {@link TokenStore} unless `options.persist` is `false`, then notifies all
+     * listeners. A no-op if the token is unchanged.
+     *
+     * @param token - The new Bearer token, or `null` to sign out.
+     * @param options - `persist: false` updates memory + listeners only.
+     */
     setToken(token, options = {}) {
         if (token === this.token)
             return;
@@ -48,9 +76,16 @@ export class SessionStore {
             listener(token);
         }
     }
+    /** Clear the active token (equivalent to `setToken(null)`). */
     clear() {
         this.setToken(null);
     }
+    /**
+     * Subscribe to token changes. The listener fires immediately with the current
+     * token, then on every change.
+     *
+     * @returns An unsubscribe function.
+     */
     onChange(listener) {
         this.listeners.add(listener);
         listener(this.token);