@crowdedkingdoms/crowdyjs 1.0.0

package/dist/realtime.js

@@ -0,0 +1,390 @@
+import { print } from 'graphql';
+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;
+        this.release = null;
+        this.desired = false;
+        this.statusValue = 'idle';
+        this.statusListeners = new Set();
+        this.subscribers = new Map();
+        this.pending = new Map();
+        this.nextSubscriberId = 1;
+        // App this realtime session is scoped to. Sent in connectionParams so the
+        // game-api only fans this app's spatial notifications to this subscription.
+        // The game-api rejects subscriptions that arrive without it.
+        this.subscribedAppId = null;
+        this.wsUrl = config.wsUrl || config.wsEndpoint || 'ws://localhost:3000/graphql';
+        this.logger = config.logger ?? silentLogger;
+        this.retryAttempts = config.retryAttempts ?? 8;
+        this.retryInitialDelayMs = config.retryInitialDelayMs ?? 250;
+        this.retryMaxDelayMs = config.retryMaxDelayMs ?? 5000;
+        this.waitTimeoutMs = config.waitTimeoutMs ?? 5000;
+        this.session.onChange((token) => {
+            if (!this.desired)
+                return;
+            if (!token) {
+                this.disconnect();
+                this.dispatchError(new CrowdyRealtimeError('Realtime disconnected because the session token was cleared', {
+                    code: 'AUTH_CLEARED',
+                    retryable: false,
+                }));
+                return;
+            }
+            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);
+        return () => {
+            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?.();
+        this.release = null;
+        this.client?.dispose();
+        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
+        // literal string "undefined".
+        this.subscribedAppId = appId != null ? String(appId) : null;
+        const id = `s${this.nextSubscriberId++}`;
+        this.subscribers.set(id, handlers);
+        this.connect();
+        return () => {
+            this.subscribers.delete(id);
+            if (this.subscribers.size === 0 && this.desired) {
+                this.disconnect();
+            }
+        };
+    }
+    /**
+     * 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(() => {
+                this.removePending(sequenceNumber, wait);
+                reject(new CrowdyRealtimeError(`Timed out waiting for UDP response sequence ${sequenceNumber}`, { code: 'UDP_SEQUENCE_TIMEOUT', retryable: true }));
+            }, timeoutMs);
+            const wait = { resolve, reject, timer };
+            const waits = this.pending.get(sequenceNumber) ?? [];
+            waits.push(wait);
+            this.pending.set(sequenceNumber, waits);
+        });
+    }
+    ensureSubscription() {
+        if (this.release)
+            return;
+        const token = this.session.getToken();
+        if (!token) {
+            const error = new CrowdyRealtimeError('Must be authenticated to subscribe', {
+                code: 'AUTH_REQUIRED',
+                retryable: false,
+            });
+            this.setStatus('failed');
+            this.dispatchError(error);
+            throw error;
+        }
+        this.setStatus('connecting');
+        this.client = createClient({
+            url: this.wsUrl,
+            lazy: true,
+            retryAttempts: this.retryAttempts,
+            connectionParams: () => {
+                const currentToken = this.session.getToken();
+                if (!currentToken)
+                    return {};
+                const params = {
+                    Authorization: `Bearer ${currentToken}`,
+                };
+                if (this.subscribedAppId != null)
+                    params.appId = this.subscribedAppId;
+                return params;
+            },
+            retryWait: async (retries) => {
+                this.setStatus('reconnecting');
+                const delay = Math.min(this.retryMaxDelayMs, this.retryInitialDelayMs * 2 ** retries);
+                const jitter = Math.floor(Math.random() * this.retryInitialDelayMs);
+                await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+            },
+            on: {
+                connected: () => this.setStatus('connected'),
+                closed: () => {
+                    if (this.desired) {
+                        this.setStatus('reconnecting');
+                    }
+                    else {
+                        this.setStatus('disconnected');
+                    }
+                },
+                error: (error) => {
+                    this.logger.error?.('Realtime WebSocket error', error);
+                    this.dispatchError(new CrowdyRealtimeError('Realtime WebSocket error', {
+                        code: 'WEBSOCKET_ERROR',
+                        retryable: true,
+                        cause: error,
+                    }));
+                },
+            },
+        });
+        this.release = this.client.subscribe({ query: print(UdpNotificationsDocument) }, {
+            next: (message) => {
+                const data = message.data;
+                const notification = data?.udpNotifications;
+                if (notification)
+                    this.dispatch(notification);
+                if (message.errors?.length) {
+                    this.dispatchError(new CrowdyRealtimeError(message.errors[0]?.message ?? 'Subscription error', {
+                        code: 'SUBSCRIPTION_ERROR',
+                        retryable: true,
+                        cause: message.errors,
+                    }));
+                }
+            },
+            error: (error) => {
+                this.setStatus('failed');
+                this.dispatchError(new CrowdyRealtimeError('Realtime subscription failed', {
+                    code: 'SUBSCRIPTION_FAILED',
+                    retryable: true,
+                    cause: error,
+                }));
+            },
+            complete: () => {
+                this.release = null;
+                if (this.desired) {
+                    this.setStatus('reconnecting');
+                    this.ensureSubscription();
+                }
+            },
+        });
+    }
+    restart() {
+        this.release?.();
+        this.release = null;
+        this.client?.dispose();
+        this.client = null;
+        this.ensureSubscription();
+    }
+    dispatch(notification) {
+        this.resolvePending(notification);
+        // A non-retryable connection event (e.g. APP_ID_REQUIRED, AUTH_REQUIRED)
+        // means the server completed the subscription and resubscribing would just
+        // be rejected again. Stop wanting the connection so the `complete` handler
+        // doesn't immediately reopen it (lazy graphql-ws then closes the socket).
+        if (notification.__typename === 'RealtimeConnectionEvent' &&
+            notification.retryable === false) {
+            this.desired = false;
+            this.setStatus('failed');
+        }
+        for (const handlers of [...this.subscribers.values()]) {
+            try {
+                handlers.any?.(notification);
+                switch (notification.__typename) {
+                    case 'ActorUpdateNotification':
+                        handlers.actorUpdate?.(notification);
+                        break;
+                    case 'ActorUpdateResponse':
+                        handlers.actorUpdateResponse?.(notification);
+                        break;
+                    case 'VoxelUpdateNotification':
+                        handlers.voxelUpdate?.(notification);
+                        break;
+                    case 'VoxelUpdateResponse':
+                        handlers.voxelUpdateResponse?.(notification);
+                        break;
+                    case 'ClientAudioNotification':
+                        handlers.audio?.(notification);
+                        break;
+                    case 'ClientTextNotification':
+                        handlers.text?.(notification);
+                        break;
+                    case 'ClientEventNotification':
+                        handlers.clientEvent?.(notification);
+                        break;
+                    case 'ServerEventNotification':
+                        handlers.serverEvent?.(notification);
+                        break;
+                    case 'SingleActorMessageNotification':
+                        handlers.singleActorMessage?.(notification);
+                        break;
+                    case 'ChannelMessageNotification':
+                        handlers.channelMessage?.(notification);
+                        break;
+                    case 'GenericErrorResponse':
+                        handlers.genericError?.(notification);
+                        break;
+                    case 'RealtimeConnectionEvent':
+                        handlers.connectionEvent?.(notification);
+                        break;
+                }
+            }
+            catch (error) {
+                this.logger.error?.('Realtime notification handler threw', error);
+            }
+        }
+    }
+    resolvePending(notification) {
+        if (!('sequenceNumber' in notification))
+            return;
+        const waits = this.pending.get(notification.sequenceNumber);
+        if (!waits?.length)
+            return;
+        this.pending.delete(notification.sequenceNumber);
+        for (const wait of waits) {
+            clearTimeout(wait.timer);
+            if (notification.__typename === 'GenericErrorResponse') {
+                wait.reject(new CrowdyRealtimeError(`UDP request failed: ${notification.errorCode}`, {
+                    code: notification.errorCode,
+                    retryable: false,
+                }));
+            }
+            else {
+                wait.resolve(notification);
+            }
+        }
+    }
+    removePending(sequenceNumber, wait) {
+        const waits = this.pending.get(sequenceNumber);
+        if (!waits)
+            return;
+        const next = waits.filter((candidate) => candidate !== wait);
+        if (next.length) {
+            this.pending.set(sequenceNumber, next);
+        }
+        else {
+            this.pending.delete(sequenceNumber);
+        }
+    }
+    rejectAllPending(error) {
+        for (const waits of this.pending.values()) {
+            for (const wait of waits) {
+                clearTimeout(wait.timer);
+                wait.reject(error);
+            }
+        }
+        this.pending.clear();
+    }
+    dispatchError(error) {
+        for (const handlers of [...this.subscribers.values()]) {
+            handlers.error?.(error);
+        }
+    }
+    setStatus(status) {
+        if (status === this.statusValue)
+            return;
+        this.statusValue = status;
+        for (const listener of [...this.statusListeners]) {
+            listener(status);
+        }
+    }
+}

package/dist/session.d.ts

@@ -0,0 +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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,96 @@
+/**
+ * {@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;
+    }
+    get() {
+        if (typeof localStorage === 'undefined')
+            return null;
+        return localStorage.getItem(this.key);
+    }
+    set(token) {
+        if (typeof localStorage === 'undefined')
+            return;
+        localStorage.setItem(this.key, token);
+    }
+    clear() {
+        if (typeof localStorage === 'undefined')
+            return;
+        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;
+        this.token = token;
+        if (options.persist !== false) {
+            if (token) {
+                void this.tokenStore?.set(token);
+            }
+            else {
+                void this.tokenStore?.clear();
+            }
+        }
+        for (const listener of [...this.listeners]) {
+            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);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+}

package/dist/subscriptions.d.ts

@@ -0,0 +1,2 @@
+export { RealtimeClient as SubscriptionManager, type RealtimeConfig as SubscriptionManagerConfig, type UdpNotificationHandlers, } from './realtime.js';
+//# sourceMappingURL=subscriptions.d.ts.map

package/dist/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../src/subscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,IAAI,mBAAmB,EACrC,KAAK,cAAc,IAAI,yBAAyB,EAChD,KAAK,uBAAuB,GAC7B,MAAM,eAAe,CAAC"}

package/dist/subscriptions.js

@@ -0,0 +1 @@
+export { RealtimeClient as SubscriptionManager, } from './realtime.js';