@crowdedkingdoms/crowdyjs 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * CrowdyJS SDK — client SDK for Crowded Kingdoms.
+ *
+ * As of the management/game-api split, the SDK targets **two** GraphQL
+ * endpoints behind a single `CrowdyClient`:
+ *
+ *   - `cks-management-api` for identity (`client.auth`, `client.users`).
+ *     This is where `game_tokens` get minted.
+ *   - `cks-game-api` for everything game-side (`client.chunks`,
+ *     `client.voxels`, `client.actors`, `client.teleport`, `client.state`,
+ *     `client.serverStatus`, `client.udp`).
+ *
+ * Both clients share a single `AuthState` so the token returned by
+ * `client.auth.login()` is automatically attached to every subsequent
+ * request, regardless of which endpoint serves it.
+ *
+ * Usage:
+ *
+ *   import { CrowdyClient } from '@crowdedkingdoms/crowdyjs';
+ *
+ *   const client = new CrowdyClient({
+ *     httpUrl: 'https://dev-game-api.crowdedkingdoms.com',
+ *     wsUrl:   'wss://dev-game-api.crowdedkingdoms.com',
+ *     managementUrl: 'https://dev-management-api.crowdedkingdoms.com',
+ *   });
+ *
+ *   const { token, user } = await client.auth.login({ email, password });
+ *   const me = await client.users.me();
+ *   const unsub = client.udp.subscribe({ actorUpdate: (n) => { ... } }, appId);
+ *
+ * As of v6 the SDK wraps the **full** public surface of both APIs, namespaced
+ * by audience: the game-client surface (`auth`, `users`, `udp`, `world`,
+ * `chunks`/`voxels`/`actors`/`avatars`/`state`/`teleport`/`channels`/`teams`/
+ * `gameModel`/`host`), the privileged studio-admin surface grouped under
+ * `client.admin` (`organizations`, `appAccess`, `billing`, `payments`,
+ * `quotas`, `environments`, `usage`, `sharedEnvironment`, `gameApps`; also
+ * available top-level), and the operator control-plane surface under
+ * `client.operator` (requires `is_operator`). Admin/operator calls still
+ * require the appropriate token + permission — the server enforces them; the
+ * SDK only provides typed wrappers. Drive admin/operator from a studio backend
+ * or internal tooling, never an untrusted browser.
+ */
+/** The published package version. Mirrors `package.json`. */
+export declare const VERSION = "1.0.0";
+export { CrowdyClient, createCrowdyClient, type CrowdyClientConfig, } from './crowdy-client.js';
+export { BrowserLocalStorageTokenStore, SessionStore, type SessionListener, type TokenStore, } from './session.js';
+export { GraphQLClient, GraphQLTransport, type GraphQLClientConfig, } from './client.js';
+export { RealtimeClient, type RealtimeConfig, type RealtimeStatus, type SpatialNotification, type UdpNotification, type UdpNotificationHandlers, } from './realtime.js';
+export { WorldClient, ActorClient, type ActorOptions } from './world.js';
+export { CrowdyError, CrowdyGraphQLError, CrowdyHttpError, CrowdyNetworkError, CrowdyProtocolError, CrowdyRealtimeError, CrowdyTimeoutError, } from './errors.js';
+export { SequenceAllocator, decodeBase64, encodeBase64, generateCrowdyUuid, validateChunkCoordinates, validateCrowdyUuid, } from './utils.js';
+export type { BigInt, ChunkCoordinates, VoxelCoordinates, ActorUpdateNotification, ActorUpdateResponse, VoxelUpdateNotification, VoxelUpdateResponse, ClientAudioNotification, ClientTextNotification, ClientEventNotification, ServerEventNotification, GenericErrorResponse, ActorUpdateHandler, ActorUpdateResponseHandler, VoxelUpdateHandler, VoxelUpdateResponseHandler, ClientAudioHandler, ClientTextHandler, ClientEventHandler, ServerEventHandler, GenericErrorHandler, UnsubscribeFn, } from './types.js';
+export { UdpErrorCode } from './types.js';
+export { AuthAPI } from './domains/auth.js';
+export { UsersAPI } from './domains/users.js';
+export { AppsAPI, type AppRoute } from './domains/apps.js';
+export { PlatformAPI, type PlatformConfig } from './domains/platform.js';
+export { OrganizationsAPI } from './domains/organizations.js';
+export { AppAccessAPI } from './domains/appAccess.js';
+export { BillingAPI } from './domains/billing.js';
+export { PaymentsAPI } from './domains/payments.js';
+export { QuotasAPI } from './domains/quotas.js';
+export { EnvironmentsAPI } from './domains/environments.js';
+export { UsageAPI } from './domains/usage.js';
+export { SharedEnvironmentAPI } from './domains/sharedEnvironment.js';
+export { ControlPlaneAPI } from './domains/controlPlane.js';
+export { AdminAPI } from './domains/admin.js';
+export { AvatarsAPI } from './domains/avatars.js';
+export { HostAPI } from './domains/host.js';
+export { GameAppsAPI } from './domains/gameApps.js';
+export { ChunksAPI } from './domains/chunks.js';
+export { VoxelsAPI } from './domains/voxels.js';
+export { ActorsAPI } from './domains/actors.js';
+export { TeleportAPI } from './domains/teleport.js';
+export { StateAPI } from './domains/state.js';
+export { ServerStatusAPI } from './domains/serverStatus.js';
+export { ChannelsAPI } from './domains/channels.js';
+export { TeamsAPI } from './domains/teams.js';
+export { UdpAPI } from './domains/udp.js';
+export { GameModelAPI } from './domains/gameModel.js';
+export type { ChunkCoordinatesInput, VoxelCoordinatesInput, ActorUpdateRequestInput, VoxelUpdateRequestInput, ClientAudioPacketInput, ClientTextPacketInput, ClientEventNotificationInput, UdpProxyConnectionStatus, RealtimeConnectionEvent, GameClientBootstrap, LoginUserInput, RegisterUserInput, ResetPasswordInput, UpdateGamertagInput, CreateActorInput, UpdateActorInput, ActorFilterInput, BatchActorLookupInput, CreateUserAppStateInput, UpdateUserStateInput, UpdateAvatarStateInput, UpdateActorStateInput, UpdateChunkStateInput, UpdateChunkLodsInput, ChunkUpdateInput, UpdateVoxelInput, RollbackVoxelUpdatesInput, GetChunkInput, GetChunkLodsInput, GetChunksByDistanceInput, GetVoxelListInput, ListVoxelsInput, ListVoxelUpdatesByDistanceInput, TeleportRequestInput, LodDataInput, VoxelStateInput, Chunk, ChunkLodsResponse, ChunksByDistanceResponse, ChunkVoxelResponse, ChunkVoxelUpdatesResponse, Voxel, VoxelUpdatesByDistanceResponse, VoxelUpdateHistoryEvent, RollbackVoxelEventResult, Actor, Avatar, AvatarDto, TeleportResponse, UserAppState, ServerStatus, GraphQlServer, ServerVersionInfo, VersionInfo, PageInfo, UdpNotificationsSubscription, GmContainer, GmContainerState, GmContainerType, GmPropertyDef, GmFunction, GmFunctionParam, GmFunctionMutation, GmSession, GmSessionParticipant, GmEdge, GmTraverseResult, GmInvokeResult, GmMutationApplied, GmEvent, GmTypeSchema, GmAppFeature, GmTierFeature, GmAppPolicy, GmSeedResult, UpsertContainerTypeInput, UpsertPropertyDefInput, UpsertFunctionInput, FunctionParamInput, FunctionMutationInput, SeedGameModelInput, SeedContainerInput, SeedContainerTypeInput, SeedPropertyDefInput, SeedFunctionInput, SeedEdgeInput, SeedPropertyInput, CreateSessionInput, JoinSessionInput, SetSessionTurnInput, CreateContainerInput, SetContainerPropertyInput, AddEdgeInput, InvokeFunctionInput, DefineAppFeatureInput, GrantTierFeatureInput, SetGameModelPolicyInput, Scalars, } from './generated/graphql.js';
+export type { CreateAppInput, UpdateAppInput, CreateOrganizationInput, CreateOrgTokenInput, UpdateOrgTokenInput, InviteOrgMemberInput, CreateOrgRoleInput, UpdateOrgRoleInput, CreateAccessTierInput, UpdateAccessTierInput, GrantAppAccessInput, CreateCheckoutInput, CheckoutFilterInput, SetQuotaInput, } from './generated/graphql.js';
+export { ServerState, AppVisibility } from './generated/graphql.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,85 @@
+/**
+ * CrowdyJS SDK — client SDK for Crowded Kingdoms.
+ *
+ * As of the management/game-api split, the SDK targets **two** GraphQL
+ * endpoints behind a single `CrowdyClient`:
+ *
+ *   - `cks-management-api` for identity (`client.auth`, `client.users`).
+ *     This is where `game_tokens` get minted.
+ *   - `cks-game-api` for everything game-side (`client.chunks`,
+ *     `client.voxels`, `client.actors`, `client.teleport`, `client.state`,
+ *     `client.serverStatus`, `client.udp`).
+ *
+ * Both clients share a single `AuthState` so the token returned by
+ * `client.auth.login()` is automatically attached to every subsequent
+ * request, regardless of which endpoint serves it.
+ *
+ * Usage:
+ *
+ *   import { CrowdyClient } from '@crowdedkingdoms/crowdyjs';
+ *
+ *   const client = new CrowdyClient({
+ *     httpUrl: 'https://dev-game-api.crowdedkingdoms.com',
+ *     wsUrl:   'wss://dev-game-api.crowdedkingdoms.com',
+ *     managementUrl: 'https://dev-management-api.crowdedkingdoms.com',
+ *   });
+ *
+ *   const { token, user } = await client.auth.login({ email, password });
+ *   const me = await client.users.me();
+ *   const unsub = client.udp.subscribe({ actorUpdate: (n) => { ... } }, appId);
+ *
+ * As of v6 the SDK wraps the **full** public surface of both APIs, namespaced
+ * by audience: the game-client surface (`auth`, `users`, `udp`, `world`,
+ * `chunks`/`voxels`/`actors`/`avatars`/`state`/`teleport`/`channels`/`teams`/
+ * `gameModel`/`host`), the privileged studio-admin surface grouped under
+ * `client.admin` (`organizations`, `appAccess`, `billing`, `payments`,
+ * `quotas`, `environments`, `usage`, `sharedEnvironment`, `gameApps`; also
+ * available top-level), and the operator control-plane surface under
+ * `client.operator` (requires `is_operator`). Admin/operator calls still
+ * require the appropriate token + permission — the server enforces them; the
+ * SDK only provides typed wrappers. Drive admin/operator from a studio backend
+ * or internal tooling, never an untrusted browser.
+ */
+/** The published package version. Mirrors `package.json`. */
+export const VERSION = '1.0.0';
+export { CrowdyClient, createCrowdyClient, } from './crowdy-client.js';
+export { BrowserLocalStorageTokenStore, SessionStore, } from './session.js';
+export { GraphQLClient, GraphQLTransport, } from './client.js';
+export { RealtimeClient, } from './realtime.js';
+export { WorldClient, ActorClient } from './world.js';
+export { CrowdyError, CrowdyGraphQLError, CrowdyHttpError, CrowdyNetworkError, CrowdyProtocolError, CrowdyRealtimeError, CrowdyTimeoutError, } from './errors.js';
+export { SequenceAllocator, decodeBase64, encodeBase64, generateCrowdyUuid, validateChunkCoordinates, validateCrowdyUuid, } from './utils.js';
+export { UdpErrorCode } from './types.js';
+// -----------------------------------------------------------------------------
+// Domain wrappers.
+// AuthAPI / UsersAPI / AppsAPI target cks-management-api; the rest target
+// cks-game-api.
+// -----------------------------------------------------------------------------
+export { AuthAPI } from './domains/auth.js';
+export { UsersAPI } from './domains/users.js';
+export { AppsAPI } from './domains/apps.js';
+export { PlatformAPI } from './domains/platform.js';
+export { OrganizationsAPI } from './domains/organizations.js';
+export { AppAccessAPI } from './domains/appAccess.js';
+export { BillingAPI } from './domains/billing.js';
+export { PaymentsAPI } from './domains/payments.js';
+export { QuotasAPI } from './domains/quotas.js';
+export { EnvironmentsAPI } from './domains/environments.js';
+export { UsageAPI } from './domains/usage.js';
+export { SharedEnvironmentAPI } from './domains/sharedEnvironment.js';
+export { ControlPlaneAPI } from './domains/controlPlane.js';
+export { AdminAPI } from './domains/admin.js';
+export { AvatarsAPI } from './domains/avatars.js';
+export { HostAPI } from './domains/host.js';
+export { GameAppsAPI } from './domains/gameApps.js';
+export { ChunksAPI } from './domains/chunks.js';
+export { VoxelsAPI } from './domains/voxels.js';
+export { ActorsAPI } from './domains/actors.js';
+export { TeleportAPI } from './domains/teleport.js';
+export { StateAPI } from './domains/state.js';
+export { ServerStatusAPI } from './domains/serverStatus.js';
+export { ChannelsAPI } from './domains/channels.js';
+export { TeamsAPI } from './domains/teams.js';
+export { UdpAPI } from './domains/udp.js';
+export { GameModelAPI } from './domains/gameModel.js';
+export { ServerState, AppVisibility } from './generated/graphql.js';

package/dist/logger.d.ts

@@ -0,0 +1,8 @@
+export interface CrowdyLogger {
+    debug?(message: string, meta?: unknown): void;
+    info?(message: string, meta?: unknown): void;
+    warn?(message: string, meta?: unknown): void;
+    error?(message: string, meta?: unknown): void;
+}
+export declare const silentLogger: CrowdyLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9C,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7C,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/C;AAED,eAAO,MAAM,YAAY,EAAE,YAAiB,CAAC"}

package/dist/logger.js

@@ -0,0 +1 @@
+export const silentLogger = {};

package/dist/realtime.d.ts

@@ -0,0 +1,319 @@
+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;
+    private readonly logger;
+    private readonly retryAttempts;
+    private readonly retryInitialDelayMs;
+    private readonly retryMaxDelayMs;
+    private readonly waitTimeoutMs;
+    private client;
+    private release;
+    private desired;
+    private statusValue;
+    private readonly statusListeners;
+    private readonly subscribers;
+    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;
+    private dispatch;
+    private resolvePending;
+    private removePending;
+    private rejectAllPending;
+    private dispatchError;
+    private setStatus;
+}
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,YAAY,GACZ,WAAW,GACX,cAAc,GACd,cAAc,GACd,QAAQ,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,CACvC,4BAA4B,CAAC,kBAAkB,CAAC,CACjD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,eAAe,EACf;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,CAC3B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,yBAAyB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IAC3G;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,qBAAqB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IAC/G;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,yBAAyB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IAC3G;;;OAGG;IACH,mBAAmB,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,qBAAqB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IAC/G;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,yBAAyB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IACrG,kEAAkE;IAClE,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,wBAAwB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IACnG;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,yBAAyB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IAC3G;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,yBAAyB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IAC3G;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,gCAAgC,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IACzH;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,4BAA4B,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IACjH;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,sBAAsB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IACzG;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,UAAU,CAAC,EAAE,yBAAyB,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IAC/G;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC7C;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,YAAY,EAAE,eAAe,KAAK,IAAI,CAAC;CAC/C;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc;IA+BvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IA9B1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA+C;IAC/E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8C;IAC1E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,gBAAgB,CAAK;IAI7B,OAAO,CAAC,eAAe,CAAuB;IAE9C;;;;;;;;OAQG;gBAED,MAAM,EAAE,cAAc,YAAK,EACV,OAAO,EAAE,YAAY;IAyBxC;;;;OAIG;IACH,MAAM,IAAI,cAAc;IAIxB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI;IAQhE;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;IAKf;;;;;OAKG;IACH,UAAU,IAAI,IAAI;IASlB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,QAAQ,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI;IAgBvE;;;;;;;;;;;;;;OAcG;IACH,eAAe,CACb,cAAc,EAAE,MAAM,EACtB,SAAS,SAAqB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAkB/B,OAAO,CAAC,kBAAkB;IAiG1B,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,QAAQ;IA8DhB,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,SAAS;CAOlB"}