@crowdedkingdoms/crowdyjs 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Minimal HTTP GraphQL client. Reads its bearer token from `AuthState` so the
+ * WebSocket subscription manager and HTTP client always agree on who's
+ * authenticated. The `login` / `register` / `connectUdpProxy` /
+ * `sendActorUpdate` / etc. shortcuts that used to live here are gone -
+ * everything goes through the typed sub-clients on `CrowdyClient` (e.g.
+ * `client.auth.login`, `client.udp.sendActorUpdate`).
+ */
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import type { SessionStore } from './session.js';
+import type { CrowdyLogger } from './logger.js';
+/**
+ * Configuration for {@link GraphQLClient}, the low-level HTTP transport. You
+ * normally don't build this yourself — `CrowdyClient` constructs the transport
+ * from its own config — but it is exported for advanced or standalone use.
+ */
+export interface GraphQLClientConfig {
+    /**
+     * Absolute base URL of the GraphQL HTTP service (e.g.
+     * `https://game.example.com/graphql`). Used when {@link graphqlEndpoint} is
+     * not set. When both are omitted the client falls back to
+     * `http://localhost:3000/graphql`.
+     */
+    httpUrl?: string;
+    /**
+     * Explicit GraphQL endpoint URL. Takes precedence over {@link httpUrl} when
+     * both are provided.
+     */
+    graphqlEndpoint?: string;
+    /**
+     * Per-request timeout in **milliseconds**. When it elapses the request is
+     * aborted and a {@link CrowdyTimeoutError} is thrown. Defaults to `60000`
+     * (60 seconds).
+     */
+    timeout?: number;
+    /**
+     * Optional logger for transport diagnostics. Defaults to a silent logger
+     * that discards all output.
+     */
+    logger?: CrowdyLogger;
+}
+/**
+ * Low-level HTTP transport for GraphQL operations against the game or
+ * management API. It POSTs operations to a single endpoint, attaches the
+ * shared Bearer token read fresh from the {@link SessionStore} on every
+ * request (so the HTTP client and the realtime socket never disagree about who
+ * is authenticated), enforces a timeout, and normalizes every failure into a
+ * typed {@link CrowdyError} subclass.
+ *
+ * Most consumers should use the typed sub-clients on `CrowdyClient` instead;
+ * reach for this directly only via the low-level escape hatch
+ * (`client.graphql.request(...)`).
+ *
+ * Failure modes:
+ * - {@link CrowdyHttpError} — the endpoint returned a non-2xx HTTP status.
+ * - {@link CrowdyGraphQLError} — a 200 response whose `errors[]` was non-empty.
+ * - {@link CrowdyNetworkError} — `fetch` itself failed (DNS, TLS, refused).
+ * - {@link CrowdyTimeoutError} — the request exceeded
+ *   {@link GraphQLClientConfig.timeout}.
+ *
+ * Also exported under the alias {@link GraphQLTransport}.
+ */
+export declare class GraphQLClient {
+    private readonly graphqlEndpoint;
+    private readonly timeout;
+    private readonly session;
+    private readonly logger;
+    /**
+     * @param config - Endpoint, timeout, and logger options; see
+     *   {@link GraphQLClientConfig}.
+     * @param session - Shared session/token store. Its current token is read
+     *   fresh on every request and sent as `Authorization: Bearer <token>`, so
+     *   HTTP auth always tracks the active session.
+     */
+    constructor(config: GraphQLClientConfig | undefined, session: SessionStore);
+    /**
+     * The resolved GraphQL endpoint URL this client POSTs to.
+     *
+     * @returns The absolute endpoint URL.
+     */
+    getEndpoint(): string;
+    /**
+     * Execute a typed GraphQL operation produced by codegen and return its
+     * `data` payload. This is the preferred entry point: the
+     * {@link TypedDocumentNode} ties `variables` and the result together so both
+     * are fully type-checked.
+     *
+     * @typeParam TResult - The operation's result (`data`) type.
+     * @typeParam TVariables - The operation's variables type.
+     * @param document - The typed operation document (e.g. `ActorDocument`).
+     * @param variables - Variables for the operation; omit for operations that
+     *   take none.
+     * @param options - Optional `signal` to abort the request from your own
+     *   `AbortController` (in addition to the built-in timeout).
+     * @returns The operation's `data` payload.
+     * @throws {CrowdyHttpError} on a non-2xx HTTP status.
+     * @throws {CrowdyGraphQLError} when the response carries a non-empty
+     *   `errors[]` array.
+     * @throws {CrowdyNetworkError} on a network-level `fetch` failure.
+     * @throws {CrowdyTimeoutError} when the request exceeds the configured
+     *   timeout.
+     */
+    request<TResult, TVariables>(document: TypedDocumentNode<TResult, TVariables>, variables?: TVariables, options?: {
+        signal?: AbortSignal;
+    }): Promise<TResult>;
+    /**
+     * Escape hatch for executing a **raw** GraphQL query string. Prefer
+     * {@link request} with a {@link TypedDocumentNode}; this exists for
+     * hand-written adapters that haven't migrated to typed documents yet. It
+     * POSTs `{ query, variables }`, attaches the Bearer token, applies the
+     * timeout, and unwraps the response's `data`.
+     *
+     * @typeParam T - Expected shape of the returned `data` (defaults to `any`).
+     * @param query - The GraphQL document text.
+     * @param variables - Variable values keyed by name. Defaults to `{}`.
+     * @param options - Optional `signal` to abort from your own
+     *   `AbortController`; otherwise the internal timeout controls abortion.
+     * @returns The response's `data` payload, typed as `T`.
+     * @throws {CrowdyHttpError} on a non-2xx HTTP status.
+     * @throws {CrowdyGraphQLError} when the response carries a non-empty
+     *   `errors[]` array.
+     * @throws {CrowdyNetworkError} on a network-level `fetch` failure.
+     * @throws {CrowdyTimeoutError} when the request exceeds the configured
+     *   timeout.
+     */
+    query<T = any>(query: string, variables?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<T>;
+}
+/**
+ * Alias for {@link GraphQLClient}, provided so callers can refer to the HTTP
+ * layer as a "transport". The two names are the exact same class.
+ */
+export { GraphQLClient as GraphQLTransport };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAWhD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC;;;;;;OAMG;gBACS,MAAM,EAAE,mBAAmB,YAAK,EAAE,OAAO,EAAE,YAAY;IAUnE;;;;OAIG;IACH,WAAW,IAAI,MAAM;IAIrB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,OAAO,EAAE,UAAU,EAC/B,QAAQ,EAAE,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC,EAChD,SAAS,CAAC,EAAE,UAAU,EACtB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,OAAO,CAAC,OAAO,CAAC;IASnB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,KAAK,CAAC,CAAC,GAAG,GAAG,EACjB,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACvC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,OAAO,CAAC,CAAC,CAAC;CA+Cd;AAED;;;GAGG;AACH,OAAO,EAAE,aAAa,IAAI,gBAAgB,EAAE,CAAC"}

package/dist/client.js

@@ -0,0 +1,150 @@
+/**
+ * Minimal HTTP GraphQL client. Reads its bearer token from `AuthState` so the
+ * WebSocket subscription manager and HTTP client always agree on who's
+ * authenticated. The `login` / `register` / `connectUdpProxy` /
+ * `sendActorUpdate` / etc. shortcuts that used to live here are gone -
+ * everything goes through the typed sub-clients on `CrowdyClient` (e.g.
+ * `client.auth.login`, `client.udp.sendActorUpdate`).
+ */
+import { print } from 'graphql';
+import { silentLogger } from './logger.js';
+import { CrowdyError, CrowdyGraphQLError, CrowdyHttpError, CrowdyNetworkError, CrowdyTimeoutError, } from './errors.js';
+/**
+ * Low-level HTTP transport for GraphQL operations against the game or
+ * management API. It POSTs operations to a single endpoint, attaches the
+ * shared Bearer token read fresh from the {@link SessionStore} on every
+ * request (so the HTTP client and the realtime socket never disagree about who
+ * is authenticated), enforces a timeout, and normalizes every failure into a
+ * typed {@link CrowdyError} subclass.
+ *
+ * Most consumers should use the typed sub-clients on `CrowdyClient` instead;
+ * reach for this directly only via the low-level escape hatch
+ * (`client.graphql.request(...)`).
+ *
+ * Failure modes:
+ * - {@link CrowdyHttpError} — the endpoint returned a non-2xx HTTP status.
+ * - {@link CrowdyGraphQLError} — a 200 response whose `errors[]` was non-empty.
+ * - {@link CrowdyNetworkError} — `fetch` itself failed (DNS, TLS, refused).
+ * - {@link CrowdyTimeoutError} — the request exceeded
+ *   {@link GraphQLClientConfig.timeout}.
+ *
+ * Also exported under the alias {@link GraphQLTransport}.
+ */
+export class GraphQLClient {
+    /**
+     * @param config - Endpoint, timeout, and logger options; see
+     *   {@link GraphQLClientConfig}.
+     * @param session - Shared session/token store. Its current token is read
+     *   fresh on every request and sent as `Authorization: Bearer <token>`, so
+     *   HTTP auth always tracks the active session.
+     */
+    constructor(config = {}, session) {
+        this.graphqlEndpoint =
+            config.graphqlEndpoint ||
+                config.httpUrl ||
+                'http://localhost:3000/graphql';
+        this.timeout = config.timeout || 60000;
+        this.session = session;
+        this.logger = config.logger ?? silentLogger;
+    }
+    /**
+     * The resolved GraphQL endpoint URL this client POSTs to.
+     *
+     * @returns The absolute endpoint URL.
+     */
+    getEndpoint() {
+        return this.graphqlEndpoint;
+    }
+    /**
+     * Execute a typed GraphQL operation produced by codegen and return its
+     * `data` payload. This is the preferred entry point: the
+     * {@link TypedDocumentNode} ties `variables` and the result together so both
+     * are fully type-checked.
+     *
+     * @typeParam TResult - The operation's result (`data`) type.
+     * @typeParam TVariables - The operation's variables type.
+     * @param document - The typed operation document (e.g. `ActorDocument`).
+     * @param variables - Variables for the operation; omit for operations that
+     *   take none.
+     * @param options - Optional `signal` to abort the request from your own
+     *   `AbortController` (in addition to the built-in timeout).
+     * @returns The operation's `data` payload.
+     * @throws {CrowdyHttpError} on a non-2xx HTTP status.
+     * @throws {CrowdyGraphQLError} when the response carries a non-empty
+     *   `errors[]` array.
+     * @throws {CrowdyNetworkError} on a network-level `fetch` failure.
+     * @throws {CrowdyTimeoutError} when the request exceeds the configured
+     *   timeout.
+     */
+    async request(document, variables, options = {}) {
+        const queryStr = print(document);
+        return this.query(queryStr, (variables ?? {}), options);
+    }
+    /**
+     * Escape hatch for executing a **raw** GraphQL query string. Prefer
+     * {@link request} with a {@link TypedDocumentNode}; this exists for
+     * hand-written adapters that haven't migrated to typed documents yet. It
+     * POSTs `{ query, variables }`, attaches the Bearer token, applies the
+     * timeout, and unwraps the response's `data`.
+     *
+     * @typeParam T - Expected shape of the returned `data` (defaults to `any`).
+     * @param query - The GraphQL document text.
+     * @param variables - Variable values keyed by name. Defaults to `{}`.
+     * @param options - Optional `signal` to abort from your own
+     *   `AbortController`; otherwise the internal timeout controls abortion.
+     * @returns The response's `data` payload, typed as `T`.
+     * @throws {CrowdyHttpError} on a non-2xx HTTP status.
+     * @throws {CrowdyGraphQLError} when the response carries a non-empty
+     *   `errors[]` array.
+     * @throws {CrowdyNetworkError} on a network-level `fetch` failure.
+     * @throws {CrowdyTimeoutError} when the request exceeds the configured
+     *   timeout.
+     */
+    async query(query, variables = {}, options = {}) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const token = this.session.getToken();
+        const signal = options.signal ?? controller.signal;
+        try {
+            const requestBody = { query, variables };
+            const response = await fetch(this.graphqlEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                },
+                body: JSON.stringify(requestBody),
+                signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new CrowdyHttpError(response.status, errorText);
+            }
+            const result = await response.json();
+            if (result.errors) {
+                throw new CrowdyGraphQLError(result.errors);
+            }
+            return result.data;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new CrowdyTimeoutError(this.timeout);
+            }
+            if (error instanceof CrowdyError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                throw new CrowdyNetworkError(error);
+            }
+            this.logger.error?.('GraphQL request failed', error);
+            throw new CrowdyNetworkError(error);
+        }
+    }
+}
+/**
+ * Alias for {@link GraphQLClient}, provided so callers can refer to the HTTP
+ * layer as a "transport". The two names are the exact same class.
+ */
+export { GraphQLClient as GraphQLTransport };

package/dist/crowdy-client.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Public surface of the SDK. Construct one `CrowdyClient` per session and
+ * access everything via the typed sub-clients (`client.auth`, `client.udp`,
+ * `client.chunks`, ...).
+ *
+ * The management/game-api split means CrowdyJS now talks to **two** GraphQL
+ * endpoints behind the scenes:
+ *
+ *   - `managementUrl` / `managementGraphqlEndpoint` -> `cks-management-api`
+ *     used by `auth` (login, register, logout, password / email flows) and
+ *     `users` (me, updateGamertag, deleteMyAccount). This is also where
+ *     `game_tokens` are minted.
+ *
+ *   - `httpUrl` / `graphqlEndpoint` -> `cks-game-api`
+ *     used by every game / world / replication sub-client
+ *     (`chunks`, `voxels`, `actors`, `teleport`, `state`, `serverStatus`,
+ *     `udp`). WebSocket subscriptions (`wsUrl`) also target this endpoint.
+ *
+ * A single `AuthState` is shared across both clients, so once
+ * `client.auth.login()` returns, every subsequent SDK call (against either
+ * endpoint) carries the Bearer token automatically.
+ */
+import { AuthState } from './auth-state.js';
+import { GraphQLClient } from './client.js';
+import { SubscriptionManager } from './subscriptions.js';
+import type { CrowdyLogger } from './logger.js';
+import type { TokenStore } from './session.js';
+import { WorldClient } from './world.js';
+import { AuthAPI } from './domains/auth.js';
+import { UsersAPI } from './domains/users.js';
+import { AppsAPI } from './domains/apps.js';
+import { PlatformAPI } from './domains/platform.js';
+import { OrganizationsAPI } from './domains/organizations.js';
+import { AppAccessAPI } from './domains/appAccess.js';
+import { BillingAPI } from './domains/billing.js';
+import { PaymentsAPI } from './domains/payments.js';
+import { QuotasAPI } from './domains/quotas.js';
+import { EnvironmentsAPI } from './domains/environments.js';
+import { UsageAPI } from './domains/usage.js';
+import { SharedEnvironmentAPI } from './domains/sharedEnvironment.js';
+import { ControlPlaneAPI } from './domains/controlPlane.js';
+import { AdminAPI } from './domains/admin.js';
+import { ChunksAPI } from './domains/chunks.js';
+import { AvatarsAPI } from './domains/avatars.js';
+import { HostAPI } from './domains/host.js';
+import { GameAppsAPI } from './domains/gameApps.js';
+import { VoxelsAPI } from './domains/voxels.js';
+import { ActorsAPI } from './domains/actors.js';
+import { TeleportAPI } from './domains/teleport.js';
+import { StateAPI } from './domains/state.js';
+import { ServerStatusAPI } from './domains/serverStatus.js';
+import { ChannelsAPI } from './domains/channels.js';
+import { TeamsAPI } from './domains/teams.js';
+import { UdpAPI } from './domains/udp.js';
+import { GameModelAPI } from './domains/gameModel.js';
+export interface CrowdyClientConfig {
+    /** game-api HTTP root (e.g. `https://dev-game-api.crowdedkingdoms.com`). */
+    httpUrl?: string;
+    /** game-api WS root. */
+    wsUrl?: string;
+    /** game-api GraphQL endpoint. Defaults to `${httpUrl}/graphql`. */
+    graphqlEndpoint?: string;
+    /** game-api WS endpoint. Defaults to `${wsUrl}/graphql`. */
+    wsEndpoint?: string;
+    /**
+     * management-api HTTP root (e.g.
+     * `https://dev-management-api.crowdedkingdoms.com`). When set,
+     * `client.auth` and `client.users` route here. If left empty the SDK
+     * falls back to `httpUrl` for backwards-compatibility with the legacy
+     * single-endpoint deployment, but new code should set this explicitly.
+     */
+    managementUrl?: string;
+    /** management-api GraphQL endpoint. Defaults to `${managementUrl}/graphql`. */
+    managementGraphqlEndpoint?: string;
+    /** Per-request HTTP timeout in milliseconds (applies to both endpoints). */
+    timeout?: number;
+    /**
+     * Persistence for the Bearer token across reloads. `BrowserLocalStorageTokenStore`
+     * is provided; supply your own for SSR/Node. When omitted the token lives only
+     * in memory for the lifetime of the client.
+     */
+    tokenStore?: TokenStore;
+    /** Optional logger for SDK diagnostics (request/realtime lifecycle). */
+    logger?: CrowdyLogger;
+    /** Realtime (WebSocket) tuning for reconnect backoff and `...AndWait` timeouts. */
+    realtime?: {
+        /** Max reconnect attempts before giving up (default tuned for browsers). */
+        retryAttempts?: number;
+        /** Initial reconnect backoff in milliseconds. */
+        retryInitialDelayMs?: number;
+        /** Maximum reconnect backoff in milliseconds (the backoff is capped here). */
+        retryMaxDelayMs?: number;
+        /** Default timeout for `...AndWait` round-trips that await a matching echo. */
+        waitTimeoutMs?: number;
+    };
+}
+export declare class CrowdyClient {
+    /** Shared token state for both game-api and management-api requests. */
+    readonly session: AuthState;
+    /** game-api HTTP client. */
+    readonly graphql: GraphQLClient;
+    /** game-api WebSocket subscription manager. */
+    readonly realtime: SubscriptionManager;
+    /** management-api HTTP client. Same `AuthState` as `graphql`. */
+    readonly management: GraphQLClient;
+    /** Auth + session: login, register, logout, password/email flows. */
+    readonly auth: AuthAPI;
+    /** Current-user identity: `me`, gamertag, account deletion. */
+    readonly users: UsersAPI;
+    /** App discovery + routing (which game-api serves a given app). */
+    readonly apps: AppsAPI;
+    /** Public platform discovery (shared game-api URL, free app quota). */
+    readonly platform: PlatformAPI;
+    /** Organizations, members, RBAC roles, and org API tokens (studio admin). */
+    readonly organizations: OrganizationsAPI;
+    /** App access tiers + per-user access grants (studio admin). */
+    readonly appAccess: AppAccessAPI;
+    /** Org wallet + per-app spend budgets (studio admin). */
+    readonly billing: BillingAPI;
+    /** Payment checkouts: wallet top-ups, plan purchases (studio admin). */
+    readonly payments: PaymentsAPI;
+    /** Usage quotas at the org/app scope (studio admin). */
+    readonly quotas: QuotasAPI;
+    /** Dedicated customer environments: provision, scale, deploy (studio admin). */
+    readonly environments: EnvironmentsAPI;
+    /** Replication + GraphQL usage reporting (studio admin). */
+    readonly usage: UsageAPI;
+    /** Shared-environment publishing, runtime gating, auto-billing (studio admin). */
+    readonly sharedEnvironment: SharedEnvironmentAPI;
+    /** Operator (control-plane) surface — requires `is_operator`. */
+    readonly operator: ControlPlaneAPI;
+    /**
+     * Studio-admin facade grouping the privileged management sub-clients
+     * (`organizations`, `appAccess`, `billing`, `payments`, `quotas`,
+     * `environments`, `usage`, `sharedEnvironment`, `grids`) under one namespace.
+     */
+    readonly admin: AdminAPI;
+    /** Chunk reads/writes: terrain, LODs, chunk state, distance queries. */
+    readonly chunks: ChunksAPI;
+    /** Voxel reads/writes: list, history, rollback, single-voxel edits. */
+    readonly voxels: VoxelsAPI;
+    /** Persisted-actor CRUD (durable records; realtime is `udp`/`world`). */
+    readonly actors: ActorsAPI;
+    /** Teleport: move an actor to a destination chunk/world. */
+    readonly teleport: TeleportAPI;
+    /** Per-user/per-app persisted state blobs. */
+    readonly state: StateAPI;
+    /** Server status + version discovery (UDP availability, version floors). */
+    readonly serverStatus: ServerStatusAPI;
+    /** Channels: location-independent pub/sub messaging groups. */
+    readonly channels: ChannelsAPI;
+    /** Teams: app-scoped player groups with roles and delegated management. */
+    readonly teams: TeamsAPI;
+    /** UDP proxy: spatial sends + the shared realtime notification subscription. */
+    readonly udp: UdpAPI;
+    /** Abstract game model: containers, properties, functions, sessions. */
+    readonly gameModel: GameModelAPI;
+    /** Durable avatars + per-app avatar state (owner-aware reads). */
+    readonly avatars: AvatarsAPI;
+    /** Game-host election + actor liveness heartbeat. */
+    readonly host: HostAPI;
+    /** App grids + grid runtime-permission administration (app admin). */
+    readonly gameApps: GameAppsAPI;
+    constructor(config?: CrowdyClientConfig);
+    /** Imperatively set the Bearer token (useful for SSO / token rehydrate). */
+    setToken(token: string | null): void;
+    /** Read the current Bearer token (null if no session). */
+    getToken(): string | null;
+    /**
+     * Ergonomic, app-scoped realtime facade. `client.world(appId)` returns a
+     * {@link WorldClient} whose `actor()` and `subscribe()` helpers pass `appId`
+     * for you and manage chunk/sequence bookkeeping — the recommended entry point
+     * for game loops. The lower-level `client.udp` remains available.
+     *
+     * @param appId - The app to scope realtime traffic to (BigInt as a decimal string).
+     */
+    world(appId: string): WorldClient;
+    /** Closes the WebSocket and clears the in-memory auth token. */
+    close(): void;
+}
+export declare function createCrowdyClient(config?: CrowdyClientConfig): CrowdyClient;
+//# sourceMappingURL=crowdy-client.d.ts.map

package/dist/crowdy-client.d.ts.map

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

package/dist/crowdy-client.js

@@ -0,0 +1,146 @@
+/**
+ * Public surface of the SDK. Construct one `CrowdyClient` per session and
+ * access everything via the typed sub-clients (`client.auth`, `client.udp`,
+ * `client.chunks`, ...).
+ *
+ * The management/game-api split means CrowdyJS now talks to **two** GraphQL
+ * endpoints behind the scenes:
+ *
+ *   - `managementUrl` / `managementGraphqlEndpoint` -> `cks-management-api`
+ *     used by `auth` (login, register, logout, password / email flows) and
+ *     `users` (me, updateGamertag, deleteMyAccount). This is also where
+ *     `game_tokens` are minted.
+ *
+ *   - `httpUrl` / `graphqlEndpoint` -> `cks-game-api`
+ *     used by every game / world / replication sub-client
+ *     (`chunks`, `voxels`, `actors`, `teleport`, `state`, `serverStatus`,
+ *     `udp`). WebSocket subscriptions (`wsUrl`) also target this endpoint.
+ *
+ * A single `AuthState` is shared across both clients, so once
+ * `client.auth.login()` returns, every subsequent SDK call (against either
+ * endpoint) carries the Bearer token automatically.
+ */
+import { AuthState } from './auth-state.js';
+import { GraphQLClient } from './client.js';
+import { SubscriptionManager } from './subscriptions.js';
+import { WorldClient } from './world.js';
+import { AuthAPI } from './domains/auth.js';
+import { UsersAPI } from './domains/users.js';
+import { AppsAPI } from './domains/apps.js';
+import { PlatformAPI } from './domains/platform.js';
+import { OrganizationsAPI } from './domains/organizations.js';
+import { AppAccessAPI } from './domains/appAccess.js';
+import { BillingAPI } from './domains/billing.js';
+import { PaymentsAPI } from './domains/payments.js';
+import { QuotasAPI } from './domains/quotas.js';
+import { EnvironmentsAPI } from './domains/environments.js';
+import { UsageAPI } from './domains/usage.js';
+import { SharedEnvironmentAPI } from './domains/sharedEnvironment.js';
+import { ControlPlaneAPI } from './domains/controlPlane.js';
+import { AdminAPI } from './domains/admin.js';
+import { ChunksAPI } from './domains/chunks.js';
+import { AvatarsAPI } from './domains/avatars.js';
+import { HostAPI } from './domains/host.js';
+import { GameAppsAPI } from './domains/gameApps.js';
+import { VoxelsAPI } from './domains/voxels.js';
+import { ActorsAPI } from './domains/actors.js';
+import { TeleportAPI } from './domains/teleport.js';
+import { StateAPI } from './domains/state.js';
+import { ServerStatusAPI } from './domains/serverStatus.js';
+import { ChannelsAPI } from './domains/channels.js';
+import { TeamsAPI } from './domains/teams.js';
+import { UdpAPI } from './domains/udp.js';
+import { GameModelAPI } from './domains/gameModel.js';
+export class CrowdyClient {
+    constructor(config = {}) {
+        this.session = new AuthState(config.tokenStore);
+        this.graphql = new GraphQLClient({
+            httpUrl: config.httpUrl,
+            graphqlEndpoint: config.graphqlEndpoint,
+            timeout: config.timeout,
+            logger: config.logger,
+        }, this.session);
+        this.realtime = new SubscriptionManager({
+            wsUrl: config.wsUrl,
+            wsEndpoint: config.wsEndpoint,
+            logger: config.logger,
+            ...config.realtime,
+        }, this.session);
+        const managementGraphqlEndpoint = config.managementGraphqlEndpoint ??
+            (config.managementUrl
+                ? `${config.managementUrl.replace(/\/$/, '')}/graphql`
+                : config.graphqlEndpoint);
+        // Management-api client. Falls back to game-api endpoint if the caller
+        // hasn't configured `managementUrl` yet (single-endpoint legacy mode).
+        this.management = new GraphQLClient({
+            httpUrl: config.managementUrl ?? config.httpUrl,
+            graphqlEndpoint: managementGraphqlEndpoint,
+            timeout: config.timeout,
+            logger: config.logger,
+        }, this.session);
+        this.auth = new AuthAPI(this.management, this.session);
+        this.users = new UsersAPI(this.management);
+        this.apps = new AppsAPI(this.management);
+        this.platform = new PlatformAPI(this.management);
+        this.organizations = new OrganizationsAPI(this.management);
+        this.appAccess = new AppAccessAPI(this.management);
+        this.billing = new BillingAPI(this.management);
+        this.payments = new PaymentsAPI(this.management);
+        this.quotas = new QuotasAPI(this.management);
+        this.environments = new EnvironmentsAPI(this.management);
+        this.usage = new UsageAPI(this.management);
+        this.sharedEnvironment = new SharedEnvironmentAPI(this.management);
+        this.operator = new ControlPlaneAPI(this.management);
+        this.chunks = new ChunksAPI(this.graphql);
+        this.voxels = new VoxelsAPI(this.graphql);
+        this.actors = new ActorsAPI(this.graphql);
+        this.teleport = new TeleportAPI(this.graphql);
+        this.state = new StateAPI(this.graphql);
+        this.serverStatus = new ServerStatusAPI(this.graphql);
+        this.channels = new ChannelsAPI(this.graphql);
+        this.teams = new TeamsAPI(this.graphql);
+        this.udp = new UdpAPI(this.graphql, this.realtime);
+        this.gameModel = new GameModelAPI(this.graphql);
+        this.avatars = new AvatarsAPI(this.graphql);
+        this.host = new HostAPI(this.graphql);
+        this.gameApps = new GameAppsAPI(this.graphql);
+        this.admin = new AdminAPI({
+            organizations: this.organizations,
+            appAccess: this.appAccess,
+            billing: this.billing,
+            payments: this.payments,
+            quotas: this.quotas,
+            environments: this.environments,
+            usage: this.usage,
+            sharedEnvironment: this.sharedEnvironment,
+            grids: this.gameApps,
+        });
+    }
+    /** Imperatively set the Bearer token (useful for SSO / token rehydrate). */
+    setToken(token) {
+        this.session.setToken(token);
+    }
+    /** Read the current Bearer token (null if no session). */
+    getToken() {
+        return this.session.getToken();
+    }
+    /**
+     * Ergonomic, app-scoped realtime facade. `client.world(appId)` returns a
+     * {@link WorldClient} whose `actor()` and `subscribe()` helpers pass `appId`
+     * for you and manage chunk/sequence bookkeeping — the recommended entry point
+     * for game loops. The lower-level `client.udp` remains available.
+     *
+     * @param appId - The app to scope realtime traffic to (BigInt as a decimal string).
+     */
+    world(appId) {
+        return new WorldClient(appId, this.udp);
+    }
+    /** Closes the WebSocket and clears the in-memory auth token. */
+    close() {
+        this.realtime.close();
+        this.session.setToken(null);
+    }
+}
+export function createCrowdyClient(config = {}) {
+    return new CrowdyClient(config);
+}