@crowdedkingdoms/crowdyjs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CrowdedKingdoms
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,247 @@
+# CrowdyJS 1.0.0 — npm org rename
+
+The package moved to the **`@crowdedkingdoms`** npm organization and its version
+line was reset:
+
+- **Old:** `@crowdedkingdomstudios/crowdyjs@6.1.0`
+- **New:** `@crowdedkingdoms/crowdyjs@1.0.0` — **identical code**, new package name.
+
+To upgrade, change your install and imports:
+
+```bash
+npm uninstall @crowdedkingdomstudios/crowdyjs
+npm install @crowdedkingdoms/crowdyjs
+```
+
+```ts
+// before: import { createCrowdyClient } from '@crowdedkingdomstudios/crowdyjs';
+import { createCrowdyClient } from '@crowdedkingdoms/crowdyjs';
+// generated docs export likewise: '@crowdedkingdoms/crowdyjs/generated'
+```
+
+No API, behavior, or type changes vs `@crowdedkingdomstudios/crowdyjs@6.1.0`. The
+old package is deprecated and points here. The notes below (kept for history)
+describe the feature set as of the former 6.x line, which `1.0.0` ships as-is.
+
+# CrowdyJS v6.1 Notes
+
+v6.1 is **additive** — new methods and fields only, no breaking changes. It
+completes the "full-surface" goal so every non-deprecated public root field on
+both APIs now has a typed SDK method, and adds Relay cursor-pagination variants
+alongside the existing offset list methods.
+
+## Added
+
+- **Grids**: `client.gameApps.deleteGrid(input)` (also `client.admin.grids.deleteGrid`)
+  — delete a studio-created peer grid (game-api `deleteGrid`, requires
+  `cks-game-api >= v0.12.3`).
+- **Game model (studio reads + revoke)**: `client.gameModel.containerTypes`,
+  `propertyDefs`, `getFunction`, `functions`, `features`, `tierFeatures`,
+  `policy`, and `revokeTierFeature`.
+- **Management admin reads/mutations**: `client.users.{get, paginated, setOperator,
+  setSuperAdmin, setEarlyAccessOverride, updateType, forceLogout, updateState,
+  freePlayWindow}`; `client.organizations.memberRoles`;
+  `client.appAccess.{runtimePermissions, grantMemberCandidates, claimFree, grantMine}`;
+  `client.apps.marketplace`; `client.billing.{buddyTiers, graphqlTiers,
+  postgresTiers}`; `client.environments.updateBillingTiers`;
+  `client.payments.{capturePaypal, events}`; `client.usage.playerPulse`.
+- **Relay `*Connection` variants** (preferred over the deprecated offset lists):
+  `client.actors.listConnection`, `client.voxels.historyConnection`,
+  `client.gameModel.eventsConnection`, `client.users.listConnection`,
+  `client.apps.marketplaceConnection`, `client.appAccess.usersByAppConnection`,
+  `client.billing.walletTransactionsConnection`,
+  `client.payments.{mineConnection, allConnection, eventsConnection}`.
+- **New fields on existing operations**: `environmentQuote` /
+  `orgEnvironment(s)` now return `environmentClass` + `singleBoxFlavor`;
+  `appUsageSummary` now returns `automationRuns` / `automationInvocations` /
+  `automationComputeUnits`.
+
+## Server compatibility
+
+`deleteGrid` requires a server on release **v0.1.33+** (`cks-game-api >= v0.12.3`).
+The new management fields require `cks-management-api` recent enough to expose them.
+All additions are backward compatible at the SDK API level.
+
+# CrowdyJS v6 Notes
+
+v6 is **additive** at the SDK API level (new sub-clients only) but is a **scope
+change**: CrowdyJS now wraps the **full** public management-api + game-api surface
+instead of just the game-client subset. Existing sub-clients (`auth`, `users`,
+`udp`, `world`, `chunks`/`voxels`/`actors`/`avatars`/`state`/`teleport`/`channels`/
+`teams`/`gameModel`) are unchanged — no migration needed for existing code.
+
+## Added
+
+- **Studio-admin sub-clients** (target `managementUrl`): `client.organizations`,
+  `client.appAccess`, `client.billing`, `client.payments`, `client.quotas`,
+  `client.environments`, `client.usage`, `client.sharedEnvironment`, and
+  `client.gameApps` (grid admin, game-api). All are also grouped under a
+  `client.admin` facade for discoverability (`client.admin.organizations`, …,
+  `client.admin.grids`).
+- **Operator surface**: `client.operator` (control plane — environments, change
+  orders, secrets, release management, audit). Requires `users.is_operator`.
+- **Game-side**: `client.avatars` (durable avatars + per-app avatar state — the
+  README previously referenced this before it existed) and `client.host`
+  (game-host election + actor `heartbeat`).
+
+## Security note
+
+These admin/operator operations are **privileged**. The SDK only provides typed
+wrappers; the server still enforces the org/app permission (or `is_operator`) on
+every call. Drive `client.admin.*` from a studio backend with an org-scoped/admin
+token and `client.operator` from internal tooling — **not** from an untrusted
+browser. The game-client surface remains browser-safe with an end-user token.
+
+---
+
+# CrowdyJS v5.2.1 Notes
+
+v5.2.1 is **documentation-only** — no API, type, or behavior changes.
+
+## Changed
+
+- Comprehensive TSDoc across the entire public surface (every sub-client class
+  and method, the error classes, the realtime types, the token store, and the
+  config). Descriptions mirror the GraphQL schema's field semantics and add
+  SDK-specific notes — auth/permission requirements, the stable
+  `extensions.code`s each call can throw, encoding/units conventions (`BigInt`
+  as decimal strings, base64 blobs, 32-char actor ids, chunk-unit distances),
+  idempotency-key replay/`IDEMPOTENCY_CONFLICT` behavior, and realtime
+  `...AndWait` echo/timeout semantics. These now show up on hover in your IDE
+  and in the published `.d.ts`.
+- Two doc-accuracy fixes: `...AndWait` echo timeouts reject with
+  `CrowdyRealtimeError` (`code === 'UDP_SEQUENCE_TIMEOUT'`), not
+  `CrowdyTimeoutError`; and only actor/voxel sends echo to the sender, so the
+  audio/text/event `...AndWait` variants are documented as fire-and-forget-with-error-wait.
+
+---
+
+# CrowdyJS v5.2 Notes
+
+v5.2 is additive at the SDK API level (new optional parameters only) and
+refreshes the bundled schema, but it **raises the minimum server version**.
+
+## Added
+
+- **Idempotency keys on destructive mutations.** The four destructive
+  game-client mutations now accept an optional idempotency key. Replaying the
+  same call with the same key returns the first result instead of re-applying
+  the side effect; the same key with different arguments returns an
+  `IDEMPOTENCY_CONFLICT` error. Keys expire server-side after 24h.
+
+  ```ts
+  const key = crypto.randomUUID();
+  await client.actors.delete(uuid, key);   // first call deletes
+  await client.actors.delete(uuid, key);   // retry replays the first result
+  await client.teams.remove(groupId, key);
+  await client.teams.leave(groupId, key);
+  await client.voxels.rollback({ ...input, idempotencyKey: key }); // input field
+  ```
+
+  All four parameters are optional and trailing, so existing call sites are
+  unchanged.
+
+- **Refreshed bundled schema.** Re-synced against `cks-management-api` and
+  `cks-game-api` so generated types now include the new Relay-style `*Connection`
+  queries (offset `limit`/`offset` args are now marked `@deprecated`), the
+  machine-readable `@requiresPermission` directive metadata, and the enumerated
+  error codes. `CrowdyGraphQLError` already surfaces these via `extensions.code`,
+  `extensions.remediation`, and `extensions.requiredPermission` — no new error
+  class is needed.
+
+## Requires
+
+- `cks-game-api >= v0.10.3` and `cks-management-api >= v0.1.70`. The destructive
+  mutation documents now send the `idempotencyKey` argument, so those four
+  operations require a server that defines it. Point the SDK at an environment
+  running release **v0.1.19** or later.
+
+---
+
+# CrowdyJS v5.1 Notes
+
+v5.1 is additive and non-breaking.
+
+## Added
+
+- **`client.teams`** — the Teams API is now a first-class sub-client, mirroring
+  `client.channels`. Create / update / delete teams, manage membership and
+  roles, set the per-app team policy, and read `mine` (`myTeams`), `list`
+  (`teams`), `get`, `members`, `roles`, and `policy`. Teams are app-scoped
+  player groups with roles and delegated management (no realtime messaging
+  path — that is Channels).
+
+  ```ts
+  const team = await client.teams.create({ appId: '1', name: 'Red Squad' });
+  await client.teams.join(team.groupId);
+  const mine = await client.teams.mine('1');
+  ```
+
+## Removed
+
+- The `gameModelEventStream` GraphQL subscription has been removed from the Game
+  API and the bundled schema. It was never wrapped by a CrowdyJS method, so no
+  SDK call sites change. To react to game-model changes, have the mutating
+  client send a lightweight notification over the realtime UDP path — a channel
+  message (`client.udp.sendChannelMessage`, recommended) or a spatial client
+  event (`client.udp.sendClientEvent`) — and have peers re-pull authoritative
+  state via `client.gameModel.containerState(...)` / `client.gameModel.events(...)`.
+
+---
+
+# CrowdyJS v5 Migration Notes
+
+CrowdyJS v5 makes the realtime subscription **app-scoped** to fix a cross-app
+notification leak: a single game token is app-agnostic and one UDP proxy
+session is shared by every subscription on that token, so a token reused across
+apps (e.g. a player in multiple tabs/apps) used to receive other apps' spatial
+fan-out.
+
+## Breaking change
+
+- `client.udp.subscribe(handlers, appId)` — **`appId` is now required**. The
+  game-api fences `udpNotifications` by app and **rejects app-agnostic
+  subscriptions** with a `RealtimeConnectionEvent` `code = 'APP_ID_REQUIRED'`.
+
+  ```ts
+  // Before (v4):
+  client.udp.subscribe({ actorUpdate });
+  // After (v5):
+  client.udp.subscribe({ actorUpdate }, '1');
+  // Or use the world helper, which passes its appId automatically:
+  client.world('1').subscribe({ actorUpdate });
+  ```
+
+  Run one client per app (sharing the same `tokenStore`) when a player is in
+  multiple apps at once.
+
+- Requires a game-api that enforces the app fence (`cks-game-api >= v0.9.0`).
+
+---
+
+# CrowdyJS v3 Migration Notes
+
+CrowdyJS v3 is a breaking rewrite focused on browser game clients.
+
+## Main Changes
+
+- Use `createCrowdyClient()` or `new CrowdyClient()` with `httpUrl` and `wsUrl`.
+- Use `client.auth.login({ email, password })` instead of `client.login(email, password)`.
+- Use `client.udp.subscribe({ actorUpdate })` instead of `client.onActorUpdate(...)`.
+- Use `client.udp.sendActorUpdate(...)` or `client.udp.sendActorUpdateAndWait(...)` instead of root-level send methods.
+- Use `client.udp.disconnect()` instead of `client.disconnectUdpProxy()`.
+- Use `client.session` for token restore, manual token injection, and token persistence.
+- Use `client.realtime.onStatus()` for connection state and reconnect visibility.
+- Import generated operation documents from `@crowdedkingdoms/crowdyjs/generated`.
+
+## API Field Renames
+
+- `CreateGridInput.app_id` is now `CreateGridInput.appId`.
+- `TeleportRequestInput.UUID` is now `TeleportRequestInput.uuid`.
+- `connectUdpProxy` takes no input.
+
+## Error Handling
+
+GraphQL failures now throw `CrowdyGraphQLError`, preserving every GraphQL error
+including `path` and `extensions.code`. Realtime failures use
+`CrowdyRealtimeError` and subscription-level `RealtimeConnectionEvent` payloads.

package/README.md

@@ -0,0 +1,303 @@
+# CrowdyJS
+
+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
+
+```bash
+npm install @crowdedkingdoms/crowdyjs
+```
+
+> **Renamed package.** This SDK moved to the `@crowdedkingdoms` npm org. `@crowdedkingdoms/crowdyjs@1.0.0` is the **same code** as the former `@crowdedkingdomstudios/crowdyjs@6.1.0` — only the package name changed. See [MIGRATION.md](MIGRATION.md).
+
+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.
+
+> **Server compatibility:** v5.2+ targets environments on release **v0.1.19 or later** (`cks-game-api >= v0.10.3`, `cks-management-api >= v0.1.70`). The destructive mutations send an `idempotencyKey` argument that older servers don't define. v6.1's `client.gameApps.deleteGrid` additionally requires release **v0.1.33+** (`cks-game-api >= v0.12.3`).
+
+## Quick start
+
+```ts
+import {
+  BrowserLocalStorageTokenStore,
+  createCrowdyClient,
+} from '@crowdedkingdoms/crowdyjs';
+
+const client = createCrowdyClient({
+  // 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,
+    waitTimeoutMs: 5000,
+  },
+});
+
+// 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);
+```
+
+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
+
+**Game-client surface** (end-user, browser-safe):
+
+| 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.host` | Game-host election + actor liveness `heartbeat`. |
+| `client.teleport` | Teleport requests. |
+| `client.channels`, `client.teams` | Messaging channels and app-scoped player teams (membership + roles). |
+| `client.gameModel` | Abstract game model: containers, properties, functions (incl. model-driven `notify_*` effects), sessions, and **automations / NPCs** (`upsertAutomation`, `runAutomation`, `automationRuns`, `automationStats`, …). |
+| `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`). |
+
+**Studio-admin surface** (privileged; drive with a server-side / studio token, grouped under `client.admin`):
+
+| Sub-client | What it does |
+|---|---|
+| `client.organizations` | Orgs, members, RBAC roles, org API tokens. |
+| `client.apps` | App discovery + routing (`createApp` etc. via the management API directly). |
+| `client.appAccess` | Access tiers + per-user grants. |
+| `client.billing` | Org wallet + per-app spend budgets. |
+| `client.payments` | Payment checkouts (wallet top-ups, plan purchases). |
+| `client.quotas` | Usage quotas at the org/app scope. |
+| `client.environments` | Dedicated environments: quote, provision, scale, deploy, link apps. |
+| `client.usage` | Replication + GraphQL usage reporting. |
+| `client.sharedEnvironment` | Publish to shared, runtime gating, spend caps, auto-billing. |
+| `client.gameApps` | App grids (`createGrid` / `deleteGrid`) + grid runtime-permission administration. |
+
+**Operator surface** (platform operations; requires `is_operator`):
+
+| Sub-client | What it does |
+|---|---|
+| `client.operator` | Control plane: cross-org environments, change orders, secrets, release management, audit. |
+
+Auth, user reads, and the studio-admin / operator surfaces target `managementUrl`; the game-client world/UDP surfaces target `httpUrl` / `wsUrl`. A single shared `AuthState` carries the bearer token to whichever endpoint serves each call.
+
+## 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(handlers, appId)` — `appId` is **required** (the SDK opens the realtime socket on demand and scopes it to that app).
+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.
+6. Call `client.close()` when disposing the SDK instance.
+
+## Per-app routing
+
+When a player is about to join an app, query its routing fields on the management API first:
+
+```graphql
+query AppForRouting($appId: BigInt!) {
+  app(appId: $appId) {
+    appId
+    splitMode
+    deploymentTarget
+    gameApiUrl
+  }
+}
+```
+
+`gameApiUrl` is populated for **both** dedicated (`splitMode`) and shared
+(`deploymentTarget: "shared"`) apps. When it's set, 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 with no `gameApiUrl` keep working against the default `httpUrl` you
+configured.
+
+## Realtime notifications
+
+`subscribe` takes the handlers **and a required `appId`** (second argument). The
+Game API scopes the realtime session to that app and rejects an app-agnostic
+subscription with a `RealtimeConnectionEvent` (`code: 'APP_ID_REQUIRED'`). Run
+one client per app (sharing the same `tokenStore`) when a player is in multiple
+apps at once.
+
+```ts
+const appId = '1';
+
+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);
+    },
+    connectionEvent: (event) => {
+      console.warn(event.code, event.message);
+    },
+    error: (error) => {
+      console.error(error.code, error.message);
+    },
+  },
+  appId,
+);
+
+// Or use the world helper, which passes its appId automatically:
+//   client.world(appId).subscribe(handlers);
+
+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 automatically.
+
+## Spatial sends
+
+```ts
+const response = await client.udp.sendActorUpdateAndWait({
+  appId: '1',
+  chunk: { x: '0', y: '0', z: '0' },
+  uuid: '0123456789abcdef0123456789abcdef',
+  state: 'AA==',           // base64-encoded payload
+  distance: 8,
+  decayRate: 1,
+});
+
+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`.
+
+### 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');
+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 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 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.
+
+GraphQL errors carry a stable `extensions.code` (e.g. `UNAUTHENTICATED`, `SCOPE_MISSING`, `FORBIDDEN`, `IDEMPOTENCY_CONFLICT`) plus, where applicable, `extensions.remediation` and `extensions.requiredPermission`. Branch on `error.extensions?.code` rather than parsing messages.
+
+## Idempotent retries
+
+Destructive game-client mutations accept an optional **idempotency key**. Pass a stable key (e.g. `crypto.randomUUID()`) and a network retry replays the first result instead of applying the side effect twice. Reusing a key with different arguments throws a `CrowdyGraphQLError` with `extensions.code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h.
+
+```ts
+const key = crypto.randomUUID();
+await client.actors.delete(uuid, key);          // first call deletes
+await client.actors.delete(uuid, key);          // retry → replays the first result
+await client.teams.remove(groupId, key);        // deleteTeam
+await client.teams.leave(groupId, key);         // leaveTeam
+await client.voxels.rollback({ ...input, idempotencyKey: key }); // input field
+```
+
+The key parameter is optional and trailing, so it's safe to omit. Requires a server on release v0.1.19+ (see Server compatibility above).
+
+## Auth notes
+
+- 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.
+
+## Surface scope & security
+
+As of v6 (completed in v6.1), CrowdyJS wraps the **full** management-api + game-api
+public surface, not just the game-client subset — every non-deprecated public root
+field has a typed method, with Relay `*Connection` cursor-pagination variants
+alongside the legacy offset lists. The surfaces are namespaced by audience:
+
+- **Game-client** (`client.auth`, `client.users`, `client.udp`, `client.world(...)`,
+  `client.chunks`/`voxels`/`actors`/`avatars`/`state`/`teleport`/`channels`/`teams`/
+  `gameModel`/`host`) — safe for untrusted browser clients with an end-user token.
+- **Studio-admin** (`client.admin.*` — also reachable at the top level, e.g.
+  `client.billing`) — privileged organization/app administration. Drive these from a
+  **studio backend** with an org-scoped or admin token, **not** from an untrusted
+  browser; the server still enforces the relevant org/app permission on every call.
+- **Operator** (`client.operator`) — platform control-plane operations that require
+  `users.is_operator`. For internal operator tooling only.
+
+The SDK never relaxes server-side authorization — exposing an operation here just
+gives you a typed wrapper; the caller still needs the right token and permission. For
+any brand-new server field not yet wrapped, the low-level escape hatch
+(`client.graphql.request(...)` / `client.management.request(...)`) always works.
+
+## 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 '@crowdedkingdoms/crowdyjs/generated';
+
+const data = await client.graphql.request(VersionInfoDocument);
+```
+
+Most consumers should prefer the typed methods on `client.auth`, `client.users`, `client.udp`, `client.serverStatus`, and `client.world()`.
+
+## Migration
+
+See [MIGRATION.md](MIGRATION.md) for breaking changes between SDK majors.
+
+## License
+
+MIT

package/dist/auth-state.d.ts

@@ -0,0 +1,11 @@
+import { SessionStore, type SessionListener, type TokenStore } from './session.js';
+export type AuthStateListener = SessionListener;
+/**
+ * Backwards-compatible internal name for the v3 SessionStore. Public callers
+ * should use `client.session`; older domain wrappers still accept AuthState.
+ */
+export declare class AuthState extends SessionStore {
+    constructor(tokenStore?: TokenStore);
+    subscribe(listener: AuthStateListener): () => void;
+}
+//# sourceMappingURL=auth-state.d.ts.map

package/dist/auth-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-state.d.ts","sourceRoot":"","sources":["../src/auth-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEnF,MAAM,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEhD;;;GAGG;AACH,qBAAa,SAAU,SAAQ,YAAY;gBAC7B,UAAU,CAAC,EAAE,UAAU;IAInC,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI;CAGnD"}

package/dist/auth-state.js

@@ -0,0 +1,13 @@
+import { SessionStore } from './session.js';
+/**
+ * Backwards-compatible internal name for the v3 SessionStore. Public callers
+ * should use `client.session`; older domain wrappers still accept AuthState.
+ */
+export class AuthState extends SessionStore {
+    constructor(tokenStore) {
+        super(tokenStore);
+    }
+    subscribe(listener) {
+        return this.onChange(listener);
+    }
+}