@crowdedkingdomstudios/crowdyjs 3.0.0 → 4.0.0

package/README.md

@@ -1,8 +1,6 @@
-# CrowdyJS SDK
+# CrowdyJS
 
-Browser-first SDK for Crowded Kingdoms game clients. CrowdyJS wraps the GraphQL
-API, the UDP proxy subscription, auth/session state, and spatial send helpers in
-one typed client.
+The official browser-first TypeScript SDK for **Crowded Kingdoms**. CrowdyJS gives you one typed client that handles auth, the world/replication GraphQL API, and the UDP proxy subscription stream behind a single shared session.
 
 ## Install
 
@@ -10,11 +8,9 @@ one typed client.
 npm install @crowdedkingdomstudios/crowdyjs
 ```
 
-CrowdyJS v3 targets browsers by default and uses native `fetch`, `WebSocket`,
-`crypto`, `btoa`, and `atob`. Node tools can still use the SDK, but must provide
-browser-compatible globals when they open realtime connections.
+CrowdyJS v4 targets browsers by default and uses native `fetch`, `WebSocket`, `crypto`, `btoa`, and `atob`. Node tools can still use the SDK, but must provide browser-compatible globals when opening realtime connections.
 
-## Quick Start
+## Quick start
 
 ```ts
 import {
@@ -23,8 +19,11 @@ import {
 } from '@crowdedkingdomstudios/crowdyjs';
 
 const client = createCrowdyClient({
-  httpUrl: 'https://api.example.com/graphql',
-  wsUrl: 'wss://api.example.com/graphql',
+  // Game API (world data + UDP proxy)
+  httpUrl: 'https://game.example.com',
+  wsUrl: 'wss://game.example.com',
+  // Management API (login, register, profile)
+  managementUrl: 'https://management.example.com',
   tokenStore: new BrowserLocalStorageTokenStore(),
   realtime: {
     retryAttempts: 8,
@@ -32,35 +31,78 @@ const client = createCrowdyClient({
   },
 });
 
+// Restore a previous session if there is one, otherwise log in.
 await client.session.restore();
-
 if (!client.session.getToken()) {
   await client.auth.login({ email: 'player@example.com', password: 'secret' });
 }
 
+// Fetch the per-app bootstrap (version requirements, UDP availability, spatial limits).
 const bootstrap = await client.serverStatus.gameClientBootstrap('1');
 console.log(bootstrap.versionInfo.minimumClientVersion);
 ```
 
-## Game Loop Lifecycle
+Both endpoints share a single `AuthState`, so once `client.auth.login()` returns, every subsequent SDK call (against either endpoint) carries the bearer token automatically.
+
+If `managementUrl` is omitted, the SDK falls back to `httpUrl` for backwards-compat with the single-endpoint deployment.
+
+## Sub-clients at a glance
+
+| Sub-client | What it does |
+|---|---|
+| `client.auth` | Register, log in, log out, password reset, email confirmation. |
+| `client.users` | `me`, `updateGamertag`, profile reads. |
+| `client.session` | Token store, `restore()`, `getToken()`, manual `setToken()`. |
+| `client.serverStatus` | `gameClientBootstrap(appId)` — per-app version info, UDP status, spatial limits. |
+| `client.chunks`, `client.voxels`, `client.actors`, `client.avatars`, `client.state` | World data reads + writes. |
+| `client.teleport` | Teleport requests. |
+| `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, `sendClientEvent`). |
+| `client.realtime` | Connection status, manual `connect()` / `disconnect()`, `onStatus()` listener. |
+| `client.world(appId)` | Higher-level helpers for browser games (`actor.join`, `actor.sendState`, `actor.sendText`). |
 
-1. Authenticate with `client.auth.login()` or restore a previous token through
-   `client.session.restore()`.
-2. Subscribe to UDP proxy notifications with `client.udp.subscribe()` or
-   `client.realtime.connect()`.
+Auth and user reads always target `managementUrl`. Everything else targets `httpUrl` / `wsUrl`.
+
+## Game-loop lifecycle
+
+1. Authenticate with `client.auth.login()` or restore a previous token through `client.session.restore()`.
+2. Subscribe to UDP proxy notifications with `client.udp.subscribe()` (the SDK will open the realtime socket on demand).
 3. Join a chunk by sending an initial actor update.
-4. Send actor, voxel, text, audio, and client-event updates through `client.udp`
-   or the higher-level `client.world(appId)` helpers.
-5. Call `client.udp.disconnect()` when leaving the world, then `client.close()`
-   when disposing the SDK instance.
+4. Send actor, voxel, text, audio, and client-event updates through `client.udp` or the higher-level `client.world(appId)` helpers.
+5. Call `client.udp.disconnect()` when leaving the world.
+6. Call `client.close()` when disposing the SDK instance.
 
-## Realtime Notifications
+## Per-app routing
+
+When a player is about to join an app, query its routing fields on the management API first:
+
+```graphql
+query AppForRouting($id: BigInt!) {
+  app(id: $id) {
+    appId
+    splitMode
+    gameApiUrl
+  }
+}
+```
+
+If `splitMode && gameApiUrl`, the app lives behind its own Game API deployment. Build a **second** `CrowdyClient` with `httpUrl: gameApiUrl` (and the matching `wsUrl`) **sharing the same `tokenStore` as the first client**, then drive gameplay through that client. Apps without `splitMode` keep working against the default `httpUrl` you configured.
+
+## Realtime notifications
 
 ```ts
 const unsubscribe = client.udp.subscribe({
   actorUpdate: (event) => {
     console.log(event.uuid, event.state);
   },
+  voxelUpdate: (event) => { /* ... */ },
+  text: (event) => { /* ... */ },
+  audio: (event) => { /* ... */ },
+  clientEvent: (event) => { /* ... */ },
+  serverEvent: (event) => { /* ... */ },
+  singleActorMessage: (event) => {
+    // A direct actor-to-actor message addressed to you.
+    console.log(event.uuid, event.payload); // payload is base64
+  },
   genericError: (event) => {
     console.warn(event.sequenceNumber, event.errorCode);
   },
@@ -75,20 +117,21 @@ const unsubscribe = client.udp.subscribe({
 client.realtime.onStatus((status) => {
   console.log('realtime:', status);
 });
+
+// Later:
+unsubscribe();
 ```
 
-The SDK uses the `graphql-transport-ws` protocol through `graphql-ws`, reconnects
-with backoff, re-reads the current token before reconnecting, and resubscribes to
-the generated `UdpNotifications` document.
+The SDK uses the `graphql-transport-ws` protocol through `graphql-ws`, reconnects with backoff, re-reads the current token before reconnecting, and resubscribes automatically.
 
-## Raw UDP Sends
+## Spatial sends
 
 ```ts
 const response = await client.udp.sendActorUpdateAndWait({
   appId: '1',
   chunk: { x: '0', y: '0', z: '0' },
   uuid: '0123456789abcdef0123456789abcdef',
-  state: 'AA==',
+  state: 'AA==',           // base64-encoded payload
   distance: 8,
   decayRate: 1,
 });
@@ -96,12 +139,24 @@ const response = await client.udp.sendActorUpdateAndWait({
 console.log(response.__typename, response.sequenceNumber);
 ```
 
-The plain `sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`,
-`sendTextPacket`, and `sendClientEvent` methods return the GraphQL mutation
-result immediately. The `AndWait` variants allocate a `sequenceNumber` when one
-is missing and wait for either a matching notification or `GenericErrorResponse`.
+The plain `sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, and `sendClientEvent` methods return the GraphQL mutation result immediately. The `AndWait` variants allocate a `sequenceNumber` when one is missing and wait for either a matching notification or `GenericErrorResponse`.
 
-## World Helpers
+### Actor-to-actor messages
+
+```ts
+// Delivered only to the actor whose UUID matches `targetUuid`; you must know
+// that actor's current chunk. Fire-and-forget — the sender gets no echo, so
+// there is no `AndWait` variant. The target receives a
+// `SingleActorMessageNotification` on its subscription.
+await client.udp.sendSingleActorMessage({
+  appId: '1',
+  chunk: { x: '7', y: '1', z: '2' }, // the TARGET actor's chunk
+  targetUuid: '0123456789abcdef0123456789abcdef',
+  payload: 'aGVsbG8=', // base64; embed sender identity here if you need it
+});
+```
+
+## World helpers
 
 ```ts
 const world = client.world('1');
@@ -110,29 +165,48 @@ const actor = world.actor();
 await actor.join({ x: '0', y: '0', z: '0' });
 await actor.sendState('AA==');
 await actor.sendText('hello nearby players');
+
+// Direct message to one other actor (you supply its UUID + current chunk):
+await actor.sendToActor(
+  '0123456789abcdef0123456789abcdef',
+  'aGVsbG8=', // base64 payload
+  { x: '7', y: '1', z: '2' },
+);
 ```
 
-The world helpers are convenience wrappers for browser games. Advanced callers
-can always use `client.udp.*` with generated GraphQL input types.
+The world helpers are thin wrappers over `client.udp.*` with the appId pre-bound — convenient for browser games. Advanced callers can always use `client.udp.*` with the generated GraphQL input types directly.
 
 ## Errors
 
-Transport and protocol failures use structured error classes:
+Transport and protocol failures throw structured error classes:
+
+- `CrowdyHttpError` — non-2xx response from a GraphQL endpoint.
+- `CrowdyGraphQLError` — preserves every GraphQL error including `path` and `extensions.code`.
+- `CrowdyNetworkError` — network-level failure (DNS, TLS, connection refused).
+- `CrowdyTimeoutError` — request or `AndWait` timed out.
+- `CrowdyRealtimeError` — realtime subscription couldn't be established or was dropped.
+- `CrowdyProtocolError` — server response failed schema validation.
 
-- `CrowdyHttpError`
-- `CrowdyGraphQLError`
-- `CrowdyNetworkError`
-- `CrowdyTimeoutError`
-- `CrowdyRealtimeError`
-- `CrowdyProtocolError`
+## Auth notes
 
-`CrowdyGraphQLError` preserves every GraphQL error, including `path` and
-`extensions.code`.
+- Use `client.auth.setToken(token)` if you need to seed a token externally (e.g. when restoring auth from a non-default storage).
+- `client.session.restore()` reads from the configured `tokenStore`. `BrowserLocalStorageTokenStore` is provided; bring your own for SSR or Node usage.
+- A single `AuthState` is observed by both the HTTP client and the realtime socket, so HTTP and WebSocket auth can never drift.
 
-## Low-Level GraphQL Access
+## What's NOT in CrowdyJS
 
-Game-client methods are first-class, but generated operations are still
-available through the transport escape hatch:
+CrowdyJS focuses on the **game-client surface**: auth, world data, UDP proxy, profile reads. The following operations are **not** exposed by the SDK and should be called against the management GraphQL API directly (with a server-side token, typically from a studio backend):
+
+- Org / app / billing / payments / quotas operations
+- Access-tier and runtime-permission administration
+- Game-token issuance / revocation
+- Marketplace and catalog management
+
+The SDK is intentionally scoped to client-side, end-user-facing flows.
+
+## Low-level GraphQL access
+
+Game-client methods are first-class, but generated operation documents are also available through a transport escape hatch:
 
 ```ts
 import { VersionInfoDocument } from '@crowdedkingdomstudios/crowdyjs/generated';
@@ -140,18 +214,12 @@ import { VersionInfoDocument } from '@crowdedkingdomstudios/crowdyjs/generated';
 const data = await client.graphql.request(VersionInfoDocument);
 ```
 
-Most consumers should prefer the methods on `client.auth`, `client.udp`,
-`client.serverStatus`, `client.users`, `client.apps`, and `client.world()`.
+Most consumers should prefer the typed methods on `client.auth`, `client.users`, `client.udp`, `client.serverStatus`, and `client.world()`.
 
-## Development
+## Migration
 
-```bash
-npm install
-npm run codegen
-npm run build
-npm test
-```
+See [MIGRATION.md](MIGRATION.md) for breaking changes between SDK majors.
+
+## License
 
-`npm run codegen` syncs `../cks-graphql-api/schema.gql` when the API repo is
-checked out beside this SDK. `npm run check:schema` fails if the committed SDL or
-generated types drift from the API schema.
+MIT

package/dist/client.d.ts.map

@@ -1 +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,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,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;gBAE1B,MAAM,EAAE,mBAAmB,YAAK,EAAE,OAAO,EAAE,YAAY;IAQnE,WAAW,IAAI,MAAM;IAIrB;;;OAGG;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;;;;OAIG;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,OAAO,EAAE,aAAa,IAAI,gBAAgB,EAAE,CAAC"}
+{"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,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,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;gBAE1B,MAAM,EAAE,mBAAmB,YAAK,EAAE,OAAO,EAAE,YAAY;IAUnE,WAAW,IAAI,MAAM;IAIrB;;;OAGG;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;;;;OAIG;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,OAAO,EAAE,aAAa,IAAI,gBAAgB,EAAE,CAAC"}

package/dist/client.js

@@ -12,7 +12,9 @@ import { CrowdyError, CrowdyGraphQLError, CrowdyHttpError, CrowdyNetworkError, C
 export class GraphQLClient {
     constructor(config = {}, session) {
         this.graphqlEndpoint =
-            config.httpUrl || config.graphqlEndpoint || 'http://localhost:3000/graphql';
+            config.graphqlEndpoint ||
+                config.httpUrl ||
+                'http://localhost:3000/graphql';
         this.timeout = config.timeout || 60000;
         this.session = session;
         this.logger = config.logger ?? silentLogger;

package/dist/crowdy-client.d.ts

@@ -1,9 +1,24 @@
 /**
  * Public surface of the SDK. Construct one `CrowdyClient` per session and
  * access everything via the typed sub-clients (`client.auth`, `client.udp`,
- * `client.orgs`, ...). The legacy `client.login()` / `client.sendActorUpdate`
- * shortcuts are gone - use `client.auth.login()` / `client.udp.sendActorUpdate()`
- * instead.
+ * `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';
@@ -13,12 +28,7 @@ import type { TokenStore } from './session.js';
 import { WorldClient } from './world.js';
 import { AuthAPI } from './domains/auth.js';
 import { UsersAPI } from './domains/users.js';
-import { OrganizationsAPI } from './domains/organizations.js';
 import { AppsAPI } from './domains/apps.js';
-import { AppAccessAPI } from './domains/appAccess.js';
-import { BillingAPI } from './domains/billing.js';
-import { QuotasAPI } from './domains/quotas.js';
-import { PaymentsAPI } from './domains/payments.js';
 import { ChunksAPI } from './domains/chunks.js';
 import { VoxelsAPI } from './domains/voxels.js';
 import { ActorsAPI } from './domains/actors.js';
@@ -27,10 +37,24 @@ import { StateAPI } from './domains/state.js';
 import { ServerStatusAPI } from './domains/serverStatus.js';
 import { UdpAPI } from './domains/udp.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;
     timeout?: number;
     tokenStore?: TokenStore;
     logger?: CrowdyLogger;
@@ -42,17 +66,17 @@ export interface CrowdyClientConfig {
     };
 }
 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;
     readonly auth: AuthAPI;
     readonly users: UsersAPI;
-    readonly orgs: OrganizationsAPI;
     readonly apps: AppsAPI;
-    readonly appAccess: AppAccessAPI;
-    readonly billing: BillingAPI;
-    readonly quotas: QuotasAPI;
-    readonly payments: PaymentsAPI;
     readonly chunks: ChunksAPI;
     readonly voxels: VoxelsAPI;
     readonly actors: ActorsAPI;
@@ -61,6 +85,10 @@ export declare class CrowdyClient {
     readonly serverStatus: ServerStatusAPI;
     readonly udp: UdpAPI;
     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;
     world(appId: string): WorldClient;
     /** Closes the WebSocket and clears the in-memory auth token. */
     close(): void;

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

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

package/dist/crowdy-client.js

@@ -1,9 +1,24 @@
 /**
  * Public surface of the SDK. Construct one `CrowdyClient` per session and
  * access everything via the typed sub-clients (`client.auth`, `client.udp`,
- * `client.orgs`, ...). The legacy `client.login()` / `client.sendActorUpdate`
- * shortcuts are gone - use `client.auth.login()` / `client.udp.sendActorUpdate()`
- * instead.
+ * `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';
@@ -11,12 +26,7 @@ import { SubscriptionManager } from './subscriptions.js';
 import { WorldClient } from './world.js';
 import { AuthAPI } from './domains/auth.js';
 import { UsersAPI } from './domains/users.js';
-import { OrganizationsAPI } from './domains/organizations.js';
 import { AppsAPI } from './domains/apps.js';
-import { AppAccessAPI } from './domains/appAccess.js';
-import { BillingAPI } from './domains/billing.js';
-import { QuotasAPI } from './domains/quotas.js';
-import { PaymentsAPI } from './domains/payments.js';
 import { ChunksAPI } from './domains/chunks.js';
 import { VoxelsAPI } from './domains/voxels.js';
 import { ActorsAPI } from './domains/actors.js';
@@ -39,14 +49,21 @@ export class CrowdyClient {
             logger: config.logger,
             ...config.realtime,
         }, this.session);
-        this.auth = new AuthAPI(this.graphql, this.session);
-        this.users = new UsersAPI(this.graphql);
-        this.orgs = new OrganizationsAPI(this.graphql);
-        this.apps = new AppsAPI(this.graphql);
-        this.appAccess = new AppAccessAPI(this.graphql);
-        this.billing = new BillingAPI(this.graphql);
-        this.quotas = new QuotasAPI(this.graphql);
-        this.payments = new PaymentsAPI(this.graphql);
+        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.chunks = new ChunksAPI(this.graphql);
         this.voxels = new VoxelsAPI(this.graphql);
         this.actors = new ActorsAPI(this.graphql);
@@ -55,6 +72,14 @@ export class CrowdyClient {
         this.serverStatus = new ServerStatusAPI(this.graphql);
         this.udp = new UdpAPI(this.graphql, this.realtime);
     }
+    /** 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();
+    }
     world(appId) {
         return new WorldClient(appId, this.udp);
     }

package/dist/domains/apps.d.ts

@@ -1,27 +1,55 @@
-import type { GraphQLClient } from '../client.js';
-import { type AppQuery, type AppQueryVariables, type AppBySlugQuery, type AppBySlugQueryVariables, type MyAppsQuery, type AppsForOrgQuery, type AppsForOrgQueryVariables, type MarketplaceAppsQuery, type MarketplaceAppsQueryVariables, type CreateAppMutation, type CreateAppMutationVariables, type UpdateAppMutation, type UpdateAppMutationVariables, type ArchiveAppMutationVariables, type SetAppVisibilityMutation, type SetAppVisibilityMutationVariables } from '../generated/graphql.js';
 /**
- * App (game / world) lifecycle and discovery. Exposed as `client.apps`.
+ * Apps sub-client. Targets `cks-management-api` (where the apps catalog
+ * lives). After the DB split each app may be served by its own per-tenant
+ * cks-game-api; the marketplace returns `gameApiUrl` for those rows so the
+ * caller can build a per-app `CrowdyClient` against the correct endpoint.
+ *
+ * Typical pattern:
  *
- * `marketplace()` is a public listing (no auth) of every app where
- * visibility = PUBLIC and status = LIVE; the rest of the methods require
- * either org-membership permissions or super admin.
+ *   const baseClient = createCrowdyClient({
+ *     managementUrl: 'https://api.example.com',
+ *     httpUrl: 'https://legacy-game-api.example.com', // pre-split fallback
+ *   });
+ *   await baseClient.auth.login({ email, password });
+ *
+ *   const route = await baseClient.apps.routeFor(appId);
+ *   if (route.splitMode && route.gameApiUrl) {
+ *     const perAppClient = createCrowdyClient({
+ *       managementUrl: 'https://api.example.com',
+ *       httpUrl: route.gameApiUrl,
+ *       wsUrl: route.gameApiUrl.replace(/^https?/, 'wss'),
+ *       tokenStore: baseClient.session.tokenStore,
+ *     });
+ *     // drive gameplay through perAppClient
+ *   }
  */
+import type { GraphQLClient } from '../client.js';
+import { type AppQuery, type AppBySlugQuery, type MyAppsQuery } from '../generated/graphql.js';
+/**
+ * Subset of an `App` row that the SDK exposes for routing decisions. The
+ * fields are typed loosely as `unknown` because the generated types lag
+ * behind the `splitMode` / `gameApiUrl` selection until codegen runs.
+ */
+export interface AppRoute {
+    appId: string;
+    splitMode: boolean;
+    gameApiUrl: string | null;
+}
 export declare class AppsAPI {
-    private gql;
-    constructor(gql: GraphQLClient);
-    marketplace(args?: MarketplaceAppsQueryVariables): Promise<MarketplaceAppsQuery['apps']>;
-    byId(appId: AppQueryVariables['appId']): Promise<AppQuery['app']>;
-    bySlug(args: AppBySlugQueryVariables): Promise<AppBySlugQuery['appBySlug']>;
+    private readonly management;
+    constructor(management: GraphQLClient);
+    /** Fetch a single app by id. */
+    app(appId: string): Promise<AppQuery['app']>;
+    /** Fetch by org slug + app slug (marketplace links). */
+    appBySlug(orgSlug: string, appSlug: string): Promise<AppBySlugQuery['appBySlug']>;
+    /** Apps the caller can play (org membership OR active access). */
     myApps(): Promise<MyAppsQuery['myApps']>;
-    forOrg(orgSlug: AppsForOrgQueryVariables['orgSlug']): Promise<AppsForOrgQuery['appsForOrg']>;
-    create(input: CreateAppMutationVariables['input']): Promise<CreateAppMutation['createApp']>;
-    update(args: UpdateAppMutationVariables): Promise<UpdateAppMutation['updateApp']>;
-    archive(appId: ArchiveAppMutationVariables['appId']): Promise<{
-        appId: any;
-        status: string;
-        updatedAt: any;
-    }>;
-    setVisibility(args: SetAppVisibilityMutationVariables): Promise<SetAppVisibilityMutation['setAppVisibility']>;
+    /**
+     * Convenience: returns just the routing tuple for a given app. If the
+     * app row is missing or the API does not expose split-mode fields yet,
+     * returns `{ appId, splitMode: false, gameApiUrl: null }` so the caller
+     * keeps using the legacy single-endpoint deployment.
+     */
+    routeFor(appId: string): Promise<AppRoute>;
 }
 //# sourceMappingURL=apps.d.ts.map

package/dist/domains/apps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/domains/apps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,iBAAiB,EAEtB,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAE5B,KAAK,WAAW,EAEhB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAE7B,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAElC,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAE/B,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAE/B,KAAK,2BAA2B,EAEhC,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EACvC,MAAM,yBAAyB,CAAC;AAEjC;;;;;;GAMG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEhC,WAAW,CACf,IAAI,GAAE,6BAAkC,GACvC,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAKlC,IAAI,CAAC,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAKjE,MAAM,CACV,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IAKjC,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAKxC,MAAM,CACV,OAAO,EAAE,wBAAwB,CAAC,SAAS,CAAC,GAC3C,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAKnC,MAAM,CACV,KAAK,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACzC,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAKpC,MAAM,CACV,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAKpC,OAAO,CACX,KAAK,EAAE,2BAA2B,CAAC,OAAO,CAAC,GAC1C,OAAO,CAAC;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,GAAG,CAAA;KAAE,CAAC;IAKpD,aAAa,CACjB,IAAI,EAAE,iCAAiC,GACtC,OAAO,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;CAIzD"}
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/domains/apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAIL,KAAK,QAAQ,EAEb,KAAK,cAAc,EAEnB,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAcD,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,aAAa;IAEtD,gCAAgC;IAC1B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAQlD,wDAAwD;IAClD,SAAS,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IAQvC,kEAAkE;IAC5D,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAQ9C;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;CAUjD"}