@crowdedkingdomstudios/crowdyjs 5.1.0 → 5.2.1

package/dist/domains/voxels.d.ts

@@ -1,17 +1,122 @@
 import type { GraphQLClient } from '../client.js';
 import { type ListVoxelsQuery, type ListVoxelsQueryVariables, type ListVoxelUpdatesByDistanceQuery, type ListVoxelUpdatesByDistanceQueryVariables, type UpdateVoxelMutation, type UpdateVoxelMutationVariables, type VoxelUpdateHistoryQuery, type VoxelUpdateHistoryQueryVariables, type RollbackVoxelUpdatesMutation, type RollbackVoxelUpdatesMutationVariables } from '../generated/graphql.js';
 /**
- * Voxel queries and mutations: list, history, rollback, single-voxel update.
+ * Voxel-edit queries and mutations for an app's world on the **game-api**: list,
+ * distance scans, history, rollback, and single-voxel writes. Exposed as
+ * `client.voxels`.
  *
- * Exposed as `client.voxels`.
+ * A "voxel edit" is one row of the `voxel_updates` log (a {@link Voxel}): the
+ * app / chunk / local position that changed, the new voxel type, an optional
+ * base64 state blob, and who/when. A background maintenance job later folds these
+ * edits into the chunk's packed grid (see {@link ChunksAPI}). For high-frequency
+ * realtime edits prefer the UDP path (`client.udp.sendVoxelUpdate(...)`); use
+ * this API for authoritative reads, audit history, and administrative rollback.
+ *
+ * Coordinate & encoding conventions:
+ * - **Chunk coordinates** are int64 **decimal strings**; **voxel positions**
+ *   (`location`) are signed 16-bit ints, `0-15` per axis for in-bounds voxels.
+ * - `appId` / `userId` are `BigInt` sent and received as decimal strings.
+ * - Voxel `state` blobs are **base64-encoded** binary.
+ *
+ * Every method requires an authenticated session (a Bearer token set via
+ * `client.auth.login()` or `client.setToken()`); an app-scoped token may only
+ * touch its own app, otherwise {@link CrowdyGraphQLError} is thrown
+ * (`UNAUTHENTICATED` / `FORBIDDEN`). {@link VoxelsAPI.update} additionally
+ * requires the `update_voxel_data` runtime permission and
+ * {@link VoxelsAPI.rollback} the `manage_apps` permission
+ * (`SCOPE_MISSING` / `FORBIDDEN`).
  */
 export declare class VoxelsAPI {
     private gql;
     constructor(gql: GraphQLClient);
+    /**
+     * List recorded voxel edits for a single chunk, newest first (optionally only
+     * those at/after a timestamp). Read-only.
+     *
+     * @param input - {@link ListVoxelsInput}: `appId`, chunk `coordinates`, and an
+     *   optional inclusive `since` lower time bound (only edits with
+     *   `createdAt >= since`).
+     * @returns The matching {@link Voxel} edits, newest first (each `state` blob
+     *   base64-encoded).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
     list(input: ListVoxelsQueryVariables['input']): Promise<ListVoxelsQuery['listVoxels']>;
+    /**
+     * List recorded voxel edits for all chunks within a cubic (Chebyshev) radius of
+     * a center chunk, grouped per chunk and ordered by increasing distance,
+     * paginated over chunks. Read-only.
+     *
+     * @param input - {@link ListVoxelUpdatesByDistanceInput}: `appId`,
+     *   `centerCoordinate`, `maxDistance` (in chunk units, integer `1-8`), optional
+     *   `limit` (max **chunks**, not voxels — default 1000) / `skip` (default 0),
+     *   and an optional `since` lower time bound.
+     * @returns A {@link VoxelUpdatesByDistanceResponse}: per-chunk groups of voxel
+     *   edits ordered by increasing distance from `centerCoordinate`, plus an echo
+     *   of the applied `limit`/`skip`.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. `maxDistance` outside
+     *   `1-8`), `UNAUTHENTICATED`, or `FORBIDDEN`.
+     */
     listByDistance(input: ListVoxelUpdatesByDistanceQueryVariables['input']): Promise<ListVoxelUpdatesByDistanceQuery['listVoxelUpdatesByDistance']>;
+    /**
+     * Record (upsert) a single voxel edit in the `voxel_updates` log for one chunk.
+     * **Writes world state**; a background job later folds the edit into the
+     * chunk's packed grid. Requires voxel-edit permission for the target region:
+     * active app access plus the `update_voxel_data` runtime permission (and, where
+     * grids cover the chunk, `update_voxel_data` on a covering grid).
+     *
+     * @param input - {@link UpdateVoxelInput}: `appId`, chunk `coordinates`, the
+     *   local voxel `location` (`0-15` per axis), the `voxelType` to write
+     *   (`0-255`), and an optional base64 `state` blob.
+     * @returns The resulting {@link Voxel}.
+     * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
+     *   `update_voxel_data`), `BAD_USER_INPUT`, or `UNAUTHENTICATED`.
+     */
     update(input: UpdateVoxelMutationVariables['input']): Promise<UpdateVoxelMutation['updateVoxel']>;
+    /**
+     * Read entries from the immutable voxel edit history (`voxel_updates_history`)
+     * for an app, newest first, optionally filtered by user id and a changed-at
+     * time window. Read-only.
+     *
+     * @param args - Query variables:
+     *   - `appId` — app whose history to read (`BigInt` decimal string).
+     *   - `userId` — optional filter: only edits made by this user (decimal string).
+     *   - `from` / `to` — optional inclusive changed-at time window (ISO-8601).
+     *   - `limit` — **deprecated** max entries (default 500, range `1-50000`).
+     *   - `offset` — **deprecated** entries to skip (default 0, range `0-1000000`).
+     * @returns The matching {@link VoxelUpdateHistoryEvent} entries, newest first.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     * @remarks The `limit`/`offset` arguments use deprecated offset pagination.
+     *   For large histories prefer the Relay-style `voxelUpdateHistoryConnection(first:,
+     *   after:)` query (available on the schema via `client.graphql`) — page with
+     *   `first` plus the previous page's `after` cursor. See
+     *   https://docs.crowdedkingdoms.com/overview/pagination.
+     */
     history(args: VoxelUpdateHistoryQueryVariables): Promise<VoxelUpdateHistoryQuery['voxelUpdateHistory']>;
+    /**
+     * Revert every voxel edit made by `userId` in `appId` between `from` and `to`,
+     * returning one result per affected voxel. **Defaults to a dry run**
+     * (`dryRun: true`) that only PREVIEWS the planned reversions without writing;
+     * pass `dryRun: false` to actually apply them (**destructive** — mutates world
+     * state). Privileged: requires the `manage_apps` permission on the org that
+     * owns `appId` (super admins bypass). Requires game-api ≥ v0.10.3.
+     *
+     * Pass `idempotencyKey` to make retries safe: replaying with the same key and
+     * identical input returns the first result instead of re-applying, while the
+     * same key with **different** input throws {@link CrowdyGraphQLError} with
+     * `code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h. Unlike
+     * {@link ActorsAPI.delete}, the key is a **field on the input object**
+     * ({@link RollbackVoxelUpdatesInput}), not a separate argument.
+     *
+     * @param input - {@link RollbackVoxelUpdatesInput}: `appId`, `userId` (decimal
+     *   strings), the inclusive `from`/`to` window, `dryRun` (default `true`), and
+     *   an optional `idempotencyKey`.
+     * @returns One {@link RollbackVoxelEventResult} per affected voxel; each
+     *   `applied` flag is `true` only when actually written (always `false` in a
+     *   dry run).
+     * @throws {CrowdyGraphQLError} `IDEMPOTENCY_CONFLICT`, `SCOPE_MISSING` /
+     *   `FORBIDDEN` (missing `manage_apps`), `BAD_USER_INPUT`, or
+     *   `UNAUTHENTICATED`.
+     */
     rollback(input: RollbackVoxelUpdatesMutationVariables['input']): Promise<RollbackVoxelUpdatesMutation['rollbackVoxelUpdates']>;
 }
 //# sourceMappingURL=voxels.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"voxels.d.ts","sourceRoot":"","sources":["../../src/domains/voxels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAE7B,KAAK,+BAA+B,EACpC,KAAK,wCAAwC,EAE7C,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EAErC,KAAK,4BAA4B,EACjC,KAAK,qCAAqC,EAC3C,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEhC,IAAI,CACR,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAKnC,cAAc,CAClB,KAAK,EAAE,wCAAwC,CAAC,OAAO,CAAC,GACvD,OAAO,CAAC,+BAA+B,CAAC,4BAA4B,CAAC,CAAC;IAKnE,MAAM,CACV,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAKxC,OAAO,CACX,IAAI,EAAE,gCAAgC,GACrC,OAAO,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAKnD,QAAQ,CACZ,KAAK,EAAE,qCAAqC,CAAC,OAAO,CAAC,GACpD,OAAO,CAAC,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;CAIjE"}
+{"version":3,"file":"voxels.d.ts","sourceRoot":"","sources":["../../src/domains/voxels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAE7B,KAAK,+BAA+B,EACpC,KAAK,wCAAwC,EAE7C,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EAErC,KAAK,4BAA4B,EACjC,KAAK,qCAAqC,EAC3C,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;OAUG;IACG,IAAI,CACR,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAKzC;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAClB,KAAK,EAAE,wCAAwC,CAAC,OAAO,CAAC,GACvD,OAAO,CAAC,+BAA+B,CAAC,4BAA4B,CAAC,CAAC;IAKzE;;;;;;;;;;;;;OAaG;IACG,MAAM,CACV,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAK9C;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CACX,IAAI,EAAE,gCAAgC,GACrC,OAAO,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAKzD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,QAAQ,CACZ,KAAK,EAAE,qCAAqC,CAAC,OAAO,CAAC,GACpD,OAAO,CAAC,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;CAIjE"}

package/dist/domains/voxels.js

@@ -1,29 +1,134 @@
 import { ListVoxelsDocument, ListVoxelUpdatesByDistanceDocument, UpdateVoxelDocument, VoxelUpdateHistoryDocument, RollbackVoxelUpdatesDocument, } from '../generated/graphql.js';
 /**
- * Voxel queries and mutations: list, history, rollback, single-voxel update.
+ * Voxel-edit queries and mutations for an app's world on the **game-api**: list,
+ * distance scans, history, rollback, and single-voxel writes. Exposed as
+ * `client.voxels`.
  *
- * Exposed as `client.voxels`.
+ * A "voxel edit" is one row of the `voxel_updates` log (a {@link Voxel}): the
+ * app / chunk / local position that changed, the new voxel type, an optional
+ * base64 state blob, and who/when. A background maintenance job later folds these
+ * edits into the chunk's packed grid (see {@link ChunksAPI}). For high-frequency
+ * realtime edits prefer the UDP path (`client.udp.sendVoxelUpdate(...)`); use
+ * this API for authoritative reads, audit history, and administrative rollback.
+ *
+ * Coordinate & encoding conventions:
+ * - **Chunk coordinates** are int64 **decimal strings**; **voxel positions**
+ *   (`location`) are signed 16-bit ints, `0-15` per axis for in-bounds voxels.
+ * - `appId` / `userId` are `BigInt` sent and received as decimal strings.
+ * - Voxel `state` blobs are **base64-encoded** binary.
+ *
+ * Every method requires an authenticated session (a Bearer token set via
+ * `client.auth.login()` or `client.setToken()`); an app-scoped token may only
+ * touch its own app, otherwise {@link CrowdyGraphQLError} is thrown
+ * (`UNAUTHENTICATED` / `FORBIDDEN`). {@link VoxelsAPI.update} additionally
+ * requires the `update_voxel_data` runtime permission and
+ * {@link VoxelsAPI.rollback} the `manage_apps` permission
+ * (`SCOPE_MISSING` / `FORBIDDEN`).
  */
 export class VoxelsAPI {
     constructor(gql) {
         this.gql = gql;
     }
+    /**
+     * List recorded voxel edits for a single chunk, newest first (optionally only
+     * those at/after a timestamp). Read-only.
+     *
+     * @param input - {@link ListVoxelsInput}: `appId`, chunk `coordinates`, and an
+     *   optional inclusive `since` lower time bound (only edits with
+     *   `createdAt >= since`).
+     * @returns The matching {@link Voxel} edits, newest first (each `state` blob
+     *   base64-encoded).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
     async list(input) {
         const data = await this.gql.request(ListVoxelsDocument, { input });
         return data.listVoxels;
     }
+    /**
+     * List recorded voxel edits for all chunks within a cubic (Chebyshev) radius of
+     * a center chunk, grouped per chunk and ordered by increasing distance,
+     * paginated over chunks. Read-only.
+     *
+     * @param input - {@link ListVoxelUpdatesByDistanceInput}: `appId`,
+     *   `centerCoordinate`, `maxDistance` (in chunk units, integer `1-8`), optional
+     *   `limit` (max **chunks**, not voxels — default 1000) / `skip` (default 0),
+     *   and an optional `since` lower time bound.
+     * @returns A {@link VoxelUpdatesByDistanceResponse}: per-chunk groups of voxel
+     *   edits ordered by increasing distance from `centerCoordinate`, plus an echo
+     *   of the applied `limit`/`skip`.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. `maxDistance` outside
+     *   `1-8`), `UNAUTHENTICATED`, or `FORBIDDEN`.
+     */
     async listByDistance(input) {
         const data = await this.gql.request(ListVoxelUpdatesByDistanceDocument, { input });
         return data.listVoxelUpdatesByDistance;
     }
+    /**
+     * Record (upsert) a single voxel edit in the `voxel_updates` log for one chunk.
+     * **Writes world state**; a background job later folds the edit into the
+     * chunk's packed grid. Requires voxel-edit permission for the target region:
+     * active app access plus the `update_voxel_data` runtime permission (and, where
+     * grids cover the chunk, `update_voxel_data` on a covering grid).
+     *
+     * @param input - {@link UpdateVoxelInput}: `appId`, chunk `coordinates`, the
+     *   local voxel `location` (`0-15` per axis), the `voxelType` to write
+     *   (`0-255`), and an optional base64 `state` blob.
+     * @returns The resulting {@link Voxel}.
+     * @throws {CrowdyGraphQLError} `SCOPE_MISSING` / `FORBIDDEN` (missing
+     *   `update_voxel_data`), `BAD_USER_INPUT`, or `UNAUTHENTICATED`.
+     */
     async update(input) {
         const data = await this.gql.request(UpdateVoxelDocument, { input });
         return data.updateVoxel;
     }
+    /**
+     * Read entries from the immutable voxel edit history (`voxel_updates_history`)
+     * for an app, newest first, optionally filtered by user id and a changed-at
+     * time window. Read-only.
+     *
+     * @param args - Query variables:
+     *   - `appId` — app whose history to read (`BigInt` decimal string).
+     *   - `userId` — optional filter: only edits made by this user (decimal string).
+     *   - `from` / `to` — optional inclusive changed-at time window (ISO-8601).
+     *   - `limit` — **deprecated** max entries (default 500, range `1-50000`).
+     *   - `offset` — **deprecated** entries to skip (default 0, range `0-1000000`).
+     * @returns The matching {@link VoxelUpdateHistoryEvent} entries, newest first.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     * @remarks The `limit`/`offset` arguments use deprecated offset pagination.
+     *   For large histories prefer the Relay-style `voxelUpdateHistoryConnection(first:,
+     *   after:)` query (available on the schema via `client.graphql`) — page with
+     *   `first` plus the previous page's `after` cursor. See
+     *   https://docs.crowdedkingdoms.com/overview/pagination.
+     */
     async history(args) {
         const data = await this.gql.request(VoxelUpdateHistoryDocument, args);
         return data.voxelUpdateHistory;
     }
+    /**
+     * Revert every voxel edit made by `userId` in `appId` between `from` and `to`,
+     * returning one result per affected voxel. **Defaults to a dry run**
+     * (`dryRun: true`) that only PREVIEWS the planned reversions without writing;
+     * pass `dryRun: false` to actually apply them (**destructive** — mutates world
+     * state). Privileged: requires the `manage_apps` permission on the org that
+     * owns `appId` (super admins bypass). Requires game-api ≥ v0.10.3.
+     *
+     * Pass `idempotencyKey` to make retries safe: replaying with the same key and
+     * identical input returns the first result instead of re-applying, while the
+     * same key with **different** input throws {@link CrowdyGraphQLError} with
+     * `code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h. Unlike
+     * {@link ActorsAPI.delete}, the key is a **field on the input object**
+     * ({@link RollbackVoxelUpdatesInput}), not a separate argument.
+     *
+     * @param input - {@link RollbackVoxelUpdatesInput}: `appId`, `userId` (decimal
+     *   strings), the inclusive `from`/`to` window, `dryRun` (default `true`), and
+     *   an optional `idempotencyKey`.
+     * @returns One {@link RollbackVoxelEventResult} per affected voxel; each
+     *   `applied` flag is `true` only when actually written (always `false` in a
+     *   dry run).
+     * @throws {CrowdyGraphQLError} `IDEMPOTENCY_CONFLICT`, `SCOPE_MISSING` /
+     *   `FORBIDDEN` (missing `manage_apps`), `BAD_USER_INPUT`, or
+     *   `UNAUTHENTICATED`.
+     */
     async rollback(input) {
         const data = await this.gql.request(RollbackVoxelUpdatesDocument, { input });
         return data.rollbackVoxelUpdates;

package/dist/errors.d.ts

@@ -1,35 +1,145 @@
+/**
+ * Structured error classes thrown by CrowdyJS.
+ *
+ * Every failure the SDK raises is an instance of {@link CrowdyError} (which
+ * extends the native `Error`), so you can catch the base class and branch on
+ * the concrete subclass with `instanceof`. Transport-level problems
+ * (`CrowdyHttpError`, `CrowdyNetworkError`, `CrowdyTimeoutError`) are distinct
+ * from API-level problems (`CrowdyGraphQLError`), which lets you retry network
+ * blips without retrying a rejected mutation.
+ *
+ * For API errors prefer branching on the **stable** `extensions.code`
+ * (e.g. `UNAUTHENTICATED`, `SCOPE_MISSING`, `FORBIDDEN`, `IDEMPOTENCY_CONFLICT`,
+ * `RATE_LIMITED`) rather than the human-readable message — see the
+ * [error-code reference](https://docs.crowdedkingdoms.com/overview/error-codes).
+ *
+ * @example
+ * ```ts
+ * import { CrowdyGraphQLError, CrowdyTimeoutError } from '@crowdedkingdomstudios/crowdyjs';
+ * try {
+ *   await client.actors.delete(uuid, key);
+ * } catch (err) {
+ *   if (err instanceof CrowdyGraphQLError && err.code === 'IDEMPOTENCY_CONFLICT') {
+ *     // same key was already used with different arguments — don't retry blindly
+ *   } else if (err instanceof CrowdyTimeoutError) {
+ *     // safe to retry with the same idempotency key
+ *   }
+ * }
+ * ```
+ */
+/** A single GraphQL error entry as returned in a response's `errors[]` array. */
 export interface CrowdyGraphQLErrorPayload {
+    /** Human-readable message. Do not branch on this — use {@link extensions}.code. */
     message: string;
+    /** Source locations in the operation document, when the server reports them. */
     locations?: readonly unknown[];
+    /** Response path to the field that errored (e.g. `['createCheckout']`). */
     path?: readonly (string | number)[];
+    /**
+     * Server-provided metadata. Carries the stable `code` plus, where applicable,
+     * `remediation` (a short hint on how to resolve it) and `requiredPermission`
+     * (the scope the caller is missing). See the published error-code reference.
+     */
     extensions?: Record<string, unknown>;
 }
+/** Options accepted by the {@link CrowdyError} base constructor. */
 export interface CrowdyErrorOptions {
+    /** Message passed to the native `Error`. */
     message: string;
+    /** Underlying cause (an inner error, rejected promise value, etc.). */
     cause?: unknown;
 }
+/**
+ * Base class for every error thrown by the SDK. Catch this to handle any
+ * CrowdyJS failure uniformly; `error.name` is set to the concrete subclass
+ * name. Prefer `instanceof` checks on the subclasses below for branching.
+ */
 export declare class CrowdyError extends Error {
+    /** The underlying cause, if this error wraps another. */
     readonly cause?: unknown;
     constructor(options: CrowdyErrorOptions);
 }
+/**
+ * A GraphQL endpoint returned a non-2xx HTTP status. This is a transport-level
+ * failure (the request never reached resolver execution cleanly) — distinct
+ * from {@link CrowdyGraphQLError}, which carries structured `errors[]` from a
+ * 200 response. Typical causes: a `401` from an expired token at the gateway,
+ * a `413`/`400` malformed request, or a `5xx`.
+ */
 export declare class CrowdyHttpError extends CrowdyError {
+    /** HTTP status code of the response. */
     readonly status: number;
+    /** Raw response body (often JSON text or an error page). */
     readonly body: string;
     constructor(status: number, body: string);
 }
+/**
+ * The server returned a 200 response whose `errors[]` array was non-empty.
+ * This is the SDK's primary API-error type: authentication, authorization,
+ * validation, idempotency conflicts, and business-rule rejections all surface
+ * here.
+ *
+ * Branch on {@link code} (the first error's `extensions.code`) — it is a stable
+ * contract; the message text is not. The full array is preserved on
+ * {@link graphqlErrors} for multi-error responses.
+ */
 export declare class CrowdyGraphQLError extends CrowdyError {
+    /** Every GraphQL error entry from the response, in server order. */
     readonly graphqlErrors: CrowdyGraphQLErrorPayload[];
     constructor(errors: CrowdyGraphQLErrorPayload[]);
+    /**
+     * Stable machine-readable code of the first error (its `extensions.code`),
+     * e.g. `'UNAUTHENTICATED'`, `'SCOPE_MISSING'`, `'FORBIDDEN'`,
+     * `'IDEMPOTENCY_CONFLICT'`, `'RATE_LIMITED'`, `'BAD_USER_INPUT'`. Returns
+     * `undefined` when the server didn't attach a code. Branch on this rather
+     * than parsing {@link message}.
+     */
     get code(): unknown;
+    /**
+     * The `extensions` bag of the first error: may include `remediation` (a hint
+     * on how to fix it) and `requiredPermission` (the missing scope for
+     * `FORBIDDEN`/`SCOPE_MISSING`).
+     */
+    get extensions(): Record<string, unknown> | undefined;
 }
+/**
+ * A network-level failure before any HTTP response was received: DNS failure,
+ * TLS error, connection refused, or an aborted `fetch`. Generally retryable
+ * with backoff. The original failure is on {@link CrowdyError.cause}.
+ */
 export declare class CrowdyNetworkError extends CrowdyError {
     constructor(cause: unknown);
 }
+/**
+ * An HTTP request to a GraphQL endpoint exceeded the configured `timeout`.
+ *
+ * Note: realtime `...AndWait` echo timeouts do **not** throw this — they reject
+ * with {@link CrowdyRealtimeError} (`code === 'UDP_SEQUENCE_TIMEOUT'`). For
+ * idempotent operations — or any mutation you passed an `idempotencyKey` — a
+ * retry is safe; the server replays the first result.
+ */
 export declare class CrowdyTimeoutError extends CrowdyError {
     constructor(timeoutMs: number);
 }
+/**
+ * A realtime/WebSocket failure: a subscription couldn't be established, was
+ * rejected, or dropped — or an `...AndWait` spatial send didn't receive its
+ * matching echo in time.
+ *
+ * Branch on {@link code}:
+ * - `'UDP_SEQUENCE_TIMEOUT'` — an `...AndWait` send timed out (retryable).
+ * - `'APP_ID_REQUIRED'` — subscribed without an `appId` (not retryable).
+ * - `'AUTH_REQUIRED'` / `'AUTH_CLEARED'` — no/!cleared session token.
+ * - `'WEBSOCKET_ERROR'` / `'SUBSCRIPTION_FAILED'` — transport-level drops.
+ *
+ * When an `...AndWait` send is answered by a server `GenericErrorResponse`,
+ * {@link code} carries that server error code instead. Use {@link retryable}
+ * to decide whether to reconnect/retry.
+ */
 export declare class CrowdyRealtimeError extends CrowdyError {
+    /** Server- or client-assigned reason code, when available. */
     readonly code?: string;
+    /** Whether reconnecting is expected to succeed (transient vs. fatal). */
     readonly retryable?: boolean;
     constructor(message: string, options?: {
         code?: string;
@@ -37,6 +147,12 @@ export declare class CrowdyRealtimeError extends CrowdyError {
         cause?: unknown;
     });
 }
+/**
+ * A server response failed the SDK's structural validation — the payload was
+ * shaped unexpectedly (e.g. a missing required field on a notification). Almost
+ * always indicates an SDK/server version mismatch; check the server
+ * compatibility floor in the README.
+ */
 export declare class CrowdyProtocolError extends CrowdyError {
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC/B,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,kBAAkB;CAKxC;AAED,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAKzC;AAED,qBAAa,kBAAmB,SAAQ,WAAW;IACjD,QAAQ,CAAC,aAAa,EAAE,yBAAyB,EAAE,CAAC;gBAExC,MAAM,EAAE,yBAAyB,EAAE;IAK/C,IAAI,IAAI,IAAI,OAAO,CAElB;CACF;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,KAAK,EAAE,OAAO;CAG3B;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,SAAS,EAAE,MAAM;CAG9B;AAED,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAKnG;AAED,qBAAa,mBAAoB,SAAQ,WAAW;CAAG"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,iFAAiF;AACjF,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IACpC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,kBAAkB;CAKxC;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAKzC;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;IACjD,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,yBAAyB,EAAE,CAAC;gBAExC,MAAM,EAAE,yBAAyB,EAAE;IAK/C;;;;;;OAMG;IACH,IAAI,IAAI,IAAI,OAAO,CAElB;IAED;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEpD;CACF;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,KAAK,EAAE,OAAO;CAG3B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,SAAS,EAAE,MAAM;CAG9B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAKnG;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;CAAG"}

package/dist/errors.js

@@ -1,3 +1,37 @@
+/**
+ * Structured error classes thrown by CrowdyJS.
+ *
+ * Every failure the SDK raises is an instance of {@link CrowdyError} (which
+ * extends the native `Error`), so you can catch the base class and branch on
+ * the concrete subclass with `instanceof`. Transport-level problems
+ * (`CrowdyHttpError`, `CrowdyNetworkError`, `CrowdyTimeoutError`) are distinct
+ * from API-level problems (`CrowdyGraphQLError`), which lets you retry network
+ * blips without retrying a rejected mutation.
+ *
+ * For API errors prefer branching on the **stable** `extensions.code`
+ * (e.g. `UNAUTHENTICATED`, `SCOPE_MISSING`, `FORBIDDEN`, `IDEMPOTENCY_CONFLICT`,
+ * `RATE_LIMITED`) rather than the human-readable message — see the
+ * [error-code reference](https://docs.crowdedkingdoms.com/overview/error-codes).
+ *
+ * @example
+ * ```ts
+ * import { CrowdyGraphQLError, CrowdyTimeoutError } from '@crowdedkingdomstudios/crowdyjs';
+ * try {
+ *   await client.actors.delete(uuid, key);
+ * } catch (err) {
+ *   if (err instanceof CrowdyGraphQLError && err.code === 'IDEMPOTENCY_CONFLICT') {
+ *     // same key was already used with different arguments — don't retry blindly
+ *   } else if (err instanceof CrowdyTimeoutError) {
+ *     // safe to retry with the same idempotency key
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Base class for every error thrown by the SDK. Catch this to handle any
+ * CrowdyJS failure uniformly; `error.name` is set to the concrete subclass
+ * name. Prefer `instanceof` checks on the subclasses below for branching.
+ */
 export class CrowdyError extends Error {
     constructor(options) {
         super(options.message);
@@ -5,6 +39,13 @@ export class CrowdyError extends Error {
         this.cause = options.cause;
     }
 }
+/**
+ * A GraphQL endpoint returned a non-2xx HTTP status. This is a transport-level
+ * failure (the request never reached resolver execution cleanly) — distinct
+ * from {@link CrowdyGraphQLError}, which carries structured `errors[]` from a
+ * 200 response. Typical causes: a `401` from an expired token at the gateway,
+ * a `413`/`400` malformed request, or a `5xx`.
+ */
 export class CrowdyHttpError extends CrowdyError {
     constructor(status, body) {
         super({ message: `HTTP ${status}: ${body}` });
@@ -12,25 +53,78 @@ export class CrowdyHttpError extends CrowdyError {
         this.body = body;
     }
 }
+/**
+ * The server returned a 200 response whose `errors[]` array was non-empty.
+ * This is the SDK's primary API-error type: authentication, authorization,
+ * validation, idempotency conflicts, and business-rule rejections all surface
+ * here.
+ *
+ * Branch on {@link code} (the first error's `extensions.code`) — it is a stable
+ * contract; the message text is not. The full array is preserved on
+ * {@link graphqlErrors} for multi-error responses.
+ */
 export class CrowdyGraphQLError extends CrowdyError {
     constructor(errors) {
         super({ message: errors.map((error) => error.message).join('; ') });
         this.graphqlErrors = errors;
     }
+    /**
+     * Stable machine-readable code of the first error (its `extensions.code`),
+     * e.g. `'UNAUTHENTICATED'`, `'SCOPE_MISSING'`, `'FORBIDDEN'`,
+     * `'IDEMPOTENCY_CONFLICT'`, `'RATE_LIMITED'`, `'BAD_USER_INPUT'`. Returns
+     * `undefined` when the server didn't attach a code. Branch on this rather
+     * than parsing {@link message}.
+     */
     get code() {
         return this.graphqlErrors[0]?.extensions?.code;
     }
+    /**
+     * The `extensions` bag of the first error: may include `remediation` (a hint
+     * on how to fix it) and `requiredPermission` (the missing scope for
+     * `FORBIDDEN`/`SCOPE_MISSING`).
+     */
+    get extensions() {
+        return this.graphqlErrors[0]?.extensions;
+    }
 }
+/**
+ * A network-level failure before any HTTP response was received: DNS failure,
+ * TLS error, connection refused, or an aborted `fetch`. Generally retryable
+ * with backoff. The original failure is on {@link CrowdyError.cause}.
+ */
 export class CrowdyNetworkError extends CrowdyError {
     constructor(cause) {
         super({ message: `Network error: ${String(cause)}`, cause });
     }
 }
+/**
+ * An HTTP request to a GraphQL endpoint exceeded the configured `timeout`.
+ *
+ * Note: realtime `...AndWait` echo timeouts do **not** throw this — they reject
+ * with {@link CrowdyRealtimeError} (`code === 'UDP_SEQUENCE_TIMEOUT'`). For
+ * idempotent operations — or any mutation you passed an `idempotencyKey` — a
+ * retry is safe; the server replays the first result.
+ */
 export class CrowdyTimeoutError extends CrowdyError {
     constructor(timeoutMs) {
         super({ message: `Request timed out after ${timeoutMs}ms` });
     }
 }
+/**
+ * A realtime/WebSocket failure: a subscription couldn't be established, was
+ * rejected, or dropped — or an `...AndWait` spatial send didn't receive its
+ * matching echo in time.
+ *
+ * Branch on {@link code}:
+ * - `'UDP_SEQUENCE_TIMEOUT'` — an `...AndWait` send timed out (retryable).
+ * - `'APP_ID_REQUIRED'` — subscribed without an `appId` (not retryable).
+ * - `'AUTH_REQUIRED'` / `'AUTH_CLEARED'` — no/!cleared session token.
+ * - `'WEBSOCKET_ERROR'` / `'SUBSCRIPTION_FAILED'` — transport-level drops.
+ *
+ * When an `...AndWait` send is answered by a server `GenericErrorResponse`,
+ * {@link code} carries that server error code instead. Use {@link retryable}
+ * to decide whether to reconnect/retry.
+ */
 export class CrowdyRealtimeError extends CrowdyError {
     constructor(message, options = {}) {
         super({ message, cause: options.cause });
@@ -38,5 +132,11 @@ export class CrowdyRealtimeError extends CrowdyError {
         this.retryable = options.retryable;
     }
 }
+/**
+ * A server response failed the SDK's structural validation — the payload was
+ * shaped unexpectedly (e.g. a missing required field on a notification). Almost
+ * always indicates an SDK/server version mismatch; check the server
+ * compatibility floor in the README.
+ */
 export class CrowdyProtocolError extends CrowdyError {
 }