@crowdedkingdoms/crowdyjs 8.0.0 → 8.1.0

package/dist/kit/objects.d.ts

@@ -0,0 +1,108 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link ObjectsKit}. Must match the deployed lock blueprint. */
+export interface ObjectsKitOptions {
+    /** The `objectTypeName` the lock blueprint was deployed with. Defaults to `'Lockable'`. */
+    objectTypeName?: string;
+    /** The `keyTypeName` the lock blueprint was deployed with. */
+    keyTypeName?: string;
+}
+/**
+ * Runtime helpers for the {@link lockBlueprint} conventions: instantiate
+ * lockable world objects, grant key items, and operate the objects through
+ * their authority-gated `open`/`close` functions. Authorization is decided
+ * entirely server-side; a denied attempt resolves with `success: false`.
+ *
+ * Obtained via `client.kit(appId).objects` (or `client.kit(appId)
+ * .objectsFor('Door')` for a non-default type name).
+ */
+export declare class ObjectsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: ObjectsKitOptions);
+    /**
+     * Instantiate a lockable object (admin/studio call — the type is
+     * admin-instantiable). For key-gated objects set `requiredKeyId` to the key
+     * id that opens it; for owner-gated objects set `ownerUserId`.
+     */
+    create(input: {
+        displayName: string;
+        requiredKeyId?: string;
+        ownerUserId?: Scalars['BigInt']['input'];
+        properties?: SeedPropertyInput[];
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /**
+     * Grant a player a key item (admin/studio call). Creates a key container
+     * owned by the player, with the owner mirrored into the `owner_user_id`
+     * property that the key condition policy reads.
+     */
+    grantKey(input: {
+        keyId: string;
+        toUserId: Scalars['BigInt']['input'];
+        displayName?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** List the key items a player holds. */
+    keysOf(userId: Scalars['BigInt']['input']): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }[]>;
+    /**
+     * Try to open an object. Pass `keyId` (the **container id** of a key the
+     * caller holds) when the object is key-gated; owner/grid/group authorities
+     * need no params. A denial is not an exception — check `success`.
+     */
+    open(objectId: string, options?: {
+        keyId?: string;
+    }): Promise<KitInvokeResult<boolean>>;
+    /** Try to close an object; same authority as {@link open}. */
+    close(objectId: string, options?: {
+        keyId?: string;
+    }): Promise<KitInvokeResult<boolean>>;
+    /** Read whether an object is currently open. */
+    isOpen(objectId: string): Promise<boolean>;
+    /** List all objects of this lockable type. */
+    list(options?: {
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }[]>;
+}
+//# sourceMappingURL=objects.d.ts.map

package/dist/kit/objects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../../src/kit/objects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAGf,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,iBAAsB;IAKjC;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACzC,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IAwBD;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACrC,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB;;;;;;;;;;;IAiBD,yCAAyC;IACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC;;;;;;;;;;;IAU/C;;;;OAIG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IASpC,8DAA8D;IACxD,KAAK,CACT,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IASpC,gDAAgD;IAC1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAShD,8CAA8C;IACxC,IAAI,CAAC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;CAOhD"}

package/dist/kit/objects.js

@@ -0,0 +1,110 @@
+import { lockNames } from './blueprints.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link lockBlueprint} conventions: instantiate
+ * lockable world objects, grant key items, and operate the objects through
+ * their authority-gated `open`/`close` functions. Authorization is decided
+ * entirely server-side; a denied attempt resolves with `success: false`.
+ *
+ * Obtained via `client.kit(appId).objects` (or `client.kit(appId)
+ * .objectsFor('Door')` for a non-default type name).
+ */
+export class ObjectsKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.names = lockNames(options.objectTypeName, options.keyTypeName);
+    }
+    /**
+     * Instantiate a lockable object (admin/studio call — the type is
+     * admin-instantiable). For key-gated objects set `requiredKeyId` to the key
+     * id that opens it; for owner-gated objects set `ownerUserId`.
+     */
+    async create(input) {
+        const properties = [
+            { key: 'is_open', valueType: 'bool', valueJson: 'false' },
+            ...(input.requiredKeyId !== undefined
+                ? [
+                    {
+                        key: 'required_key_id',
+                        valueType: 'string',
+                        valueJson: JSON.stringify(input.requiredKeyId),
+                    },
+                ]
+                : []),
+            ...(input.properties ?? []),
+        ];
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.objectType,
+            displayName: input.displayName,
+            ...(input.ownerUserId !== undefined ? { ownerUserId: input.ownerUserId } : {}),
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            properties,
+        });
+    }
+    /**
+     * Grant a player a key item (admin/studio call). Creates a key container
+     * owned by the player, with the owner mirrored into the `owner_user_id`
+     * property that the key condition policy reads.
+     */
+    async grantKey(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.keyType,
+            displayName: input.displayName ?? `Key ${input.keyId}`,
+            ownerUserId: input.toUserId,
+            properties: [
+                { key: 'key_id', valueType: 'string', valueJson: JSON.stringify(input.keyId) },
+                {
+                    key: 'owner_user_id',
+                    valueType: 'int',
+                    valueJson: String(input.toUserId),
+                },
+            ],
+        });
+    }
+    /** List the key items a player holds. */
+    async keysOf(userId) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.keyType,
+        });
+        return containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(userId));
+    }
+    /**
+     * Try to open an object. Pass `keyId` (the **container id** of a key the
+     * caller holds) when the object is key-gated; owner/grid/group authorities
+     * need no params. A denial is not an exception — check `success`.
+     */
+    async open(objectId, options = {}) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.openFn,
+            selfContainerId: objectId,
+            params: options.keyId !== undefined ? { key_id: options.keyId } : {},
+        });
+    }
+    /** Try to close an object; same authority as {@link open}. */
+    async close(objectId, options = {}) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.closeFn,
+            selfContainerId: objectId,
+            params: options.keyId !== undefined ? { key_id: options.keyId } : {},
+        });
+    }
+    /** Read whether an object is currently open. */
+    async isOpen(objectId) {
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), objectId);
+        return props.is_open === true;
+    }
+    /** List all objects of this lockable type. */
+    async list(options = {}) {
+        return this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.objectType,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+        });
+    }
+}

package/dist/kit/shared.d.ts

@@ -0,0 +1,32 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { GameModelInvokeMutation } from '../generated/graphql.js';
+/** The raw server result of a `gameModelInvoke` call. */
+export type RawInvokeResult = GameModelInvokeMutation['gameModelInvoke'];
+/**
+ * A kit invoke outcome: the server's authority/evaluation verdict plus the
+ * parsed return value. Authority denials and expression errors are **not**
+ * exceptions — check {@link success}.
+ */
+export interface KitInvokeResult<T = unknown> {
+    /** `false` when the invoke policy denied the caller or the logic errored (rolled back). */
+    success: boolean;
+    /** The parsed `returnValueJson`, when present and `success` is true. */
+    returnValue?: T;
+    /** The server's error message when `success` is false. */
+    errorMessage?: string;
+    /** The full server result (event id, applied mutations, …). */
+    raw: RawInvokeResult;
+}
+/** Wrap a raw invoke result, parsing the JSON return value. */
+export declare function toKitInvokeResult<T>(raw: RawInvokeResult): KitInvokeResult<T>;
+/** Invoke a model function and wrap the result. */
+export declare function kitInvoke<T = unknown>(gameModel: GameModelAPI, input: {
+    appId: string;
+    functionName: string;
+    selfContainerId: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+}): Promise<KitInvokeResult<T>>;
+/** Read a container's visible properties as a parsed object. */
+export declare function kitContainerProperties(gameModel: GameModelAPI, appId: string, containerId: string): Promise<Record<string, unknown>>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/kit/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/kit/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,2FAA2F;IAC3F,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,GAAG,EAAE,eAAe,CAAC;CACtB;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,CAAC,CAAC,CAe7E;AAED,mDAAmD;AACnD,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE;IACL,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAS7B;AAED,gEAAgE;AAChE,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAOlC"}

package/dist/kit/shared.js

@@ -0,0 +1,39 @@
+/** Wrap a raw invoke result, parsing the JSON return value. */
+export function toKitInvokeResult(raw) {
+    let returnValue;
+    if (raw.success && raw.returnValueJson != null) {
+        try {
+            returnValue = JSON.parse(raw.returnValueJson);
+        }
+        catch {
+            returnValue = undefined;
+        }
+    }
+    return {
+        success: raw.success,
+        returnValue,
+        errorMessage: raw.errorMessage ?? undefined,
+        raw,
+    };
+}
+/** Invoke a model function and wrap the result. */
+export async function kitInvoke(gameModel, input) {
+    const raw = await gameModel.invoke({
+        appId: input.appId,
+        functionName: input.functionName,
+        selfContainerId: input.selfContainerId,
+        paramsJson: JSON.stringify(input.params ?? {}),
+        ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+    });
+    return toKitInvokeResult(raw);
+}
+/** Read a container's visible properties as a parsed object. */
+export async function kitContainerProperties(gameModel, appId, containerId) {
+    const state = await gameModel.containerState({ appId, containerId });
+    try {
+        return JSON.parse(state.propertiesJson);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/lb-cookie-store.d.ts

@@ -0,0 +1,20 @@
+export declare class LbCookieStore {
+    private value;
+    /** Current `cks_ga=…` header value, or null when unset. */
+    headerValue(): string | null;
+    /** Parse `Set-Cookie` response headers and retain `cks_ga` when present. */
+    ingestSetCookie(headers: Headers): void;
+    /** @internal test helper */
+    getValue(): string | null;
+    /**
+     * Obtain `cks_ga` from the game-api before opening a WebSocket so the
+     * upgrade lands on the same upstream as subsequent HTTP mutations.
+     */
+    primeFromGraphql(args: {
+        endpoint: string;
+        token?: string | null;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+//# sourceMappingURL=lb-cookie-store.d.ts.map

package/dist/lb-cookie-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lb-cookie-store.d.ts","sourceRoot":"","sources":["../src/lb-cookie-store.ts"],"names":[],"mappings":"AAWA,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAuB;IAEpC,2DAA2D;IAC3D,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B,4EAA4E;IAC5E,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAYvC,4BAA4B;IAC5B,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB;;;OAGG;IACG,gBAAgB,CAAC,IAAI,EAAE;QAC3B,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC;CAwBlB"}

package/dist/lb-cookie-store.js

@@ -0,0 +1,73 @@
+/**
+ * In-memory store for the Caddy load-balancer sticky cookie (`cks_ga`).
+ *
+ * CKS shared game LBs set `cks_ga` on the first HTTP response so GraphQL
+ * mutations and the graphql-transport-ws upgrade for the same client land on
+ * one game-api. Browsers persist this automatically; Node `fetch` and `ws` do
+ * not — this store bridges that gap for bots, e2e tests, and other non-browser
+ * runtimes.
+ */
+const CKS_GA_NAME = 'cks_ga';
+export class LbCookieStore {
+    constructor() {
+        this.value = null;
+    }
+    /** Current `cks_ga=…` header value, or null when unset. */
+    headerValue() {
+        return this.value ? `${CKS_GA_NAME}=${this.value}` : null;
+    }
+    /** Parse `Set-Cookie` response headers and retain `cks_ga` when present. */
+    ingestSetCookie(headers) {
+        const setCookies = typeof headers.getSetCookie === 'function'
+            ? headers.getSetCookie()
+            : parseSetCookieFallback(headers.get('set-cookie'));
+        for (const raw of setCookies) {
+            const pair = raw.split(';', 1)[0]?.trim();
+            if (!pair?.startsWith(`${CKS_GA_NAME}=`))
+                continue;
+            this.value = pair.slice(CKS_GA_NAME.length + 1);
+        }
+    }
+    /** @internal test helper */
+    getValue() {
+        return this.value;
+    }
+    /**
+     * Obtain `cks_ga` from the game-api before opening a WebSocket so the
+     * upgrade lands on the same upstream as subsequent HTTP mutations.
+     */
+    async primeFromGraphql(args) {
+        if (this.value)
+            return;
+        const httpEndpoint = toHttpGraphqlEndpoint(args.endpoint);
+        const controller = new AbortController();
+        const timeoutMs = args.timeoutMs ?? 10000;
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        const signal = args.signal ?? controller.signal;
+        try {
+            const response = await fetch(httpEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(args.token ? { Authorization: `Bearer ${args.token}` } : {}),
+                },
+                body: JSON.stringify({ query: '{ __typename }' }),
+                credentials: 'include',
+                signal,
+            });
+            this.ingestSetCookie(response.headers);
+            await response.arrayBuffer().catch(() => undefined);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+function parseSetCookieFallback(header) {
+    if (!header)
+        return [];
+    return [header];
+}
+function toHttpGraphqlEndpoint(endpoint) {
+    return endpoint.replace(/^wss:/i, 'https:').replace(/^ws:/i, 'http:');
+}

package/dist/realtime.d.ts

@@ -1,6 +1,7 @@
 import type { SessionStore } from './session.js';
 import type { CrowdyLogger } from './logger.js';
 import { CrowdyRealtimeError } from './errors.js';
+import type { LbCookieStore } from './lb-cookie-store.js';
 import { type UdpNotificationsSubscription } from './generated/graphql.js';
 /**
  * Lifecycle state of the realtime WebSocket connection, as reported by
@@ -62,9 +63,11 @@ export interface UdpNotificationHandlers {
         __typename?: 'ActorUpdateNotification';
     }>) => void;
     /**
-     * Server acknowledgement echoing one of **your own** actor updates. This is
-     * the notification a `sendActorUpdateAndWait` correlates to via
-     * `sequenceNumber`.
+     * Legacy handler for `ActorUpdateResponse`. Current game servers never emit
+     * this type; the echo of your own actor update arrives as an
+     * `ActorUpdateNotification` (see {@link actorUpdate}), which is what
+     * `sendActorUpdateAndWait` correlates to via `sequenceNumber`. Retained for
+     * backward compatibility.
      */
     actorUpdateResponse?: (notification: Extract<UdpNotification, {
         __typename?: 'ActorUpdateResponse';
@@ -77,8 +80,11 @@ export interface UdpNotificationHandlers {
         __typename?: 'VoxelUpdateNotification';
     }>) => void;
     /**
-     * Server acknowledgement echoing one of **your own** voxel updates (the
-     * `sendVoxelUpdateAndWait` correlation target).
+     * Legacy handler for `VoxelUpdateResponse`. Current game servers never emit
+     * this type; the echo of your own voxel update arrives as a
+     * `VoxelUpdateNotification` (see {@link voxelUpdate}), which is what
+     * `sendVoxelUpdateAndWait` correlates to via `sequenceNumber`. Retained for
+     * backward compatibility.
      */
     voxelUpdateResponse?: (notification: Extract<UdpNotification, {
         __typename?: 'VoxelUpdateResponse';
@@ -191,6 +197,12 @@ export interface RealtimeConfig {
     waitTimeoutMs?: number;
     /** Optional logger for realtime diagnostics. Defaults to a silent logger. */
     logger?: CrowdyLogger;
+    /**
+     * Sticky-LB cookie jar shared with the game-api HTTP client. When set in
+     * Node, the WebSocket upgrade forwards `cks_ga` so HTTP mutations and the
+     * subscription land on the same game-api upstream.
+     */
+    lbCookieStore?: LbCookieStore;
 }
 /**
  * Manages the single WebSocket subscription to the game-api's
@@ -218,6 +230,7 @@ export declare class RealtimeClient {
     private readonly retryInitialDelayMs;
     private readonly retryMaxDelayMs;
     private readonly waitTimeoutMs;
+    private readonly lbCookieStore?;
     private client;
     private release;
     private desired;
@@ -227,6 +240,7 @@ export declare class RealtimeClient {
     private readonly pending;
     private nextSubscriberId;
     private subscribedAppId;
+    private opening;
     /**
      * @param config - Reconnect/timeout/endpoint tuning; see
      *   {@link RealtimeConfig}.
@@ -308,6 +322,7 @@ export declare class RealtimeClient {
      */
     waitForSequence(sequenceNumber: number, timeoutMs?: number): Promise<SpatialNotification>;
     private ensureSubscription;
+    private openSubscription;
     private restart;
     private dispatch;
     private resolvePending;

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

@@ -45,12 +45,14 @@ export class RealtimeClient {
         // 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.opening = 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.lbCookieStore = config.lbCookieStore;
         this.session.onChange((token) => {
             if (!this.desired)
                 return;
@@ -185,6 +187,8 @@ export class RealtimeClient {
     ensureSubscription() {
         if (this.release)
             return;
+        if (this.opening)
+            return;
         const token = this.session.getToken();
         if (!token) {
             const error = new CrowdyRealtimeError('Must be authenticated to subscribe', {
@@ -195,11 +199,24 @@ export class RealtimeClient {
             this.dispatchError(error);
             throw error;
         }
+        this.opening = this.openSubscription(token).finally(() => {
+            this.opening = null;
+        });
+    }
+    async openSubscription(token) {
+        if (this.lbCookieStore) {
+            await this.lbCookieStore.primeFromGraphql({
+                endpoint: this.wsUrl,
+                token,
+            });
+        }
         this.setStatus('connecting');
+        const webSocketImpl = createStickyWebSocketImpl(this.lbCookieStore);
         this.client = createClient({
             url: this.wsUrl,
             lazy: true,
             retryAttempts: this.retryAttempts,
+            ...(webSocketImpl ? { webSocketImpl } : {}),
             connectionParams: () => {
                 const currentToken = this.session.getToken();
                 if (!currentToken)
@@ -388,3 +405,24 @@ export class RealtimeClient {
         }
     }
 }
+function isNodeRuntime() {
+    return (typeof process !== 'undefined' &&
+        typeof process.versions?.node === 'string');
+}
+/**
+ * Node `ws` does not send browser cookies on upgrade. When a sticky cookie jar
+ * is configured, wrap `ws` so `cks_ga` rides on the handshake.
+ */
+function createStickyWebSocketImpl(lbCookieStore) {
+    if (!lbCookieStore || !isNodeRuntime())
+        return undefined;
+    const cookieStore = lbCookieStore;
+    // Node `ws` accepts a third options arg with `headers`; DOM typings do not.
+    const NodeWebSocket = WebSocket;
+    return class StickyLbWebSocket extends NodeWebSocket {
+        constructor(url, protocols) {
+            const cookie = cookieStore.headerValue();
+            super(url, protocols, cookie ? { headers: { Cookie: cookie } } : undefined);
+        }
+    };
+}

package/dist/types.d.ts

@@ -379,8 +379,12 @@ export interface ActorUpdateNotification {
     epochMillis: BigInt;
 }
 /**
- * Server acknowledgement echoing one of **your own** actor updates — the
- * correlation target for `sendActorUpdateAndWait`. Has no `state` payload.
+ * Legacy type retained for backward compatibility. Current game servers do
+ * **not** emit an `ActorUpdateResponse` — the applied echo of your own actor
+ * update arrives as an {@link ActorUpdateNotification} (the sender is included
+ * in the chunk fan-out), correlated by `sequenceNumber`. That notification, not
+ * this type, is what `sendActorUpdateAndWait` resolves with. Has no `state`
+ * payload.
  */
 export interface ActorUpdateResponse {
     /** Discriminator for the {@link UdpNotification} union. */
@@ -445,8 +449,12 @@ export interface VoxelUpdateNotification {
     epochMillis: BigInt;
 }
 /**
- * Server acknowledgement echoing one of **your own** voxel updates — the
- * correlation target for `sendVoxelUpdateAndWait`. Has no voxel payload.
+ * Legacy type retained for backward compatibility. Current game servers do
+ * **not** emit a `VoxelUpdateResponse` — the applied echo of your own voxel
+ * update arrives as a {@link VoxelUpdateNotification} (the sender is included
+ * in the chunk fan-out), correlated by `sequenceNumber`. That notification, not
+ * this type, is what `sendVoxelUpdateAndWait` resolves with. Has no voxel
+ * payload.
  */
 export interface VoxelUpdateResponse {
     /** Discriminator for the {@link UdpNotification} union. */
@@ -634,11 +642,19 @@ export interface CrowdyClientConfig {
 }
 /** Callback for an {@link ActorUpdateNotification} (another actor moved/changed). */
 export type ActorUpdateHandler = (notification: ActorUpdateNotification) => void;
-/** Callback for an {@link ActorUpdateResponse} (echo of your own actor update). */
+/**
+ * Callback for a legacy {@link ActorUpdateResponse}. Current servers never emit
+ * one; your own actor update echoes back as an {@link ActorUpdateNotification}.
+ * Retained for backward compatibility.
+ */
 export type ActorUpdateResponseHandler = (response: ActorUpdateResponse) => void;
 /** Callback for a {@link VoxelUpdateNotification} (a nearby voxel changed). */
 export type VoxelUpdateHandler = (notification: VoxelUpdateNotification) => void;
-/** Callback for a {@link VoxelUpdateResponse} (echo of your own voxel update). */
+/**
+ * Callback for a legacy {@link VoxelUpdateResponse}. Current servers never emit
+ * one; your own voxel update echoes back as a {@link VoxelUpdateNotification}.
+ * Retained for backward compatibility.
+ */
 export type VoxelUpdateResponseHandler = (response: VoxelUpdateResponse) => void;
 /** Callback for a {@link ClientAudioNotification} (nearby voice/audio packet). */
 export type ClientAudioHandler = (notification: ClientAudioNotification) => void;