@crowdedkingdomstudios/crowdyjs 5.1.0 → 5.2.1

package/dist/domains/actors.js

@@ -1,40 +1,123 @@
 import { ActorDocument, ActorsDocument, BatchLookupActorsDocument, CreateActorDocument, UpdateActorDocument, DeleteActorDocument, UpdateActorStateDocument, } from '../generated/graphql.js';
 /**
- * Actor (player / NPC) CRUD and filtering.
+ * Persisted-actor (player / NPC) CRUD and filtering on the **game-api**.
+ * Exposed as `client.actors`.
  *
- * Note: this is the persisted-actor API. For high-frequency replication see
- * the existing `client.sendActorUpdate()` UDP path (unchanged).
+ * An "actor" here is the durable, server-stored record of a participant
+ * (identity, owning app, optional avatar, last-known chunk, and a state blob) —
+ * not the high-frequency spatial replication stream. For real-time position
+ * and state fan-out use the UDP path instead (`client.udp.sendActorUpdate(...)`
+ * or the ergonomic `client.world(appId).actor()` helper), which is unchanged
+ * and far cheaper per update.
  *
- * Exposed as `client.actors`.
+ * Actor ids are exactly **32 ASCII characters** (the UDP-wire actor id), **not**
+ * a hyphenated RFC-4122 UUID. Use {@link generateCrowdyUuid} to mint one.
+ * `BigInt` values (`appId`, `avatarId`, `userId`) are sent and received as
+ * decimal strings.
+ *
+ * Every method requires an authenticated session (a Bearer token set via
+ * `client.auth.login()` or `client.setToken()`) and that the caller is
+ * entitled to the target app, or it throws {@link CrowdyGraphQLError}
+ * (`UNAUTHENTICATED` / `FORBIDDEN`).
  */
 export class ActorsAPI {
     constructor(gql) {
         this.gql = gql;
     }
+    /**
+     * Fetch a single persisted actor by its 32-character actor id.
+     *
+     * @param uuid - The actor's 32-ASCII-character id.
+     * @returns The {@link Actor}, or `null` if no actor with that id exists.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` if the caller
+     *   isn't entitled to the actor's app.
+     */
     async get(uuid) {
         const data = await this.gql.request(ActorDocument, { uuid });
         return data.actor;
     }
+    /**
+     * List persisted actors, optionally narrowed by an {@link ActorFilterInput}
+     * (e.g. by app, owning user, or avatar). Omit the filter to use its defaults.
+     *
+     * @param filter - Optional filter; fields are ANDed together.
+     * @returns The matching actors.
+     * @throws {CrowdyGraphQLError} on auth/validation failures.
+     */
     async list(filter) {
         const data = await this.gql.request(ActorsDocument, { filter });
         return data.actors;
     }
+    /**
+     * Resolve many actors in one round-trip by id (and/or the other keys the
+     * {@link BatchActorLookupInput} accepts). Prefer this over calling
+     * {@link get} in a loop — it avoids N requests and N auth checks.
+     *
+     * @param input - The batch lookup keys.
+     * @returns The actors that were found (missing ids are simply omitted).
+     */
     async batchLookup(input) {
         const data = await this.gql.request(BatchLookupActorsDocument, { input });
         return data.batchLookupActors;
     }
+    /**
+     * Create a persisted actor. `input.uuid` must be a unique 32-ASCII-character
+     * id and `input.appId` the owning app; `chunk` is the initial grid position.
+     * `avatarId`, `privateState`, and `publicState` are optional (state blobs are
+     * base64-encoded binary).
+     *
+     * @param input - {@link CreateActorInput}.
+     * @returns The newly created {@link Actor}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. malformed/duplicate
+     *   uuid), `FORBIDDEN` if not entitled to the app, or `UNAUTHENTICATED`.
+     */
     async create(input) {
         const data = await this.gql.request(CreateActorDocument, { input });
         return data.createActor;
     }
+    /**
+     * Patch an existing actor. Only the fields present on `input` change; omitted
+     * fields are left untouched.
+     *
+     * @param uuid - The actor's 32-character id.
+     * @param input - Fields to change ({@link UpdateActorInput}).
+     * @returns The updated {@link Actor}.
+     * @throws {CrowdyGraphQLError} if the actor doesn't exist or the caller lacks
+     *   access.
+     */
     async update(uuid, input) {
         const data = await this.gql.request(UpdateActorDocument, { uuid, input });
         return data.updateActor;
     }
-    async delete(uuid) {
-        const data = await this.gql.request(DeleteActorDocument, { uuid });
+    /**
+     * Delete a persisted actor.
+     *
+     * Pass an `idempotencyKey` to make retries safe: replaying with the same key
+     * returns the first result instead of re-applying, while the same key with a
+     * **different** `uuid` throws {@link CrowdyGraphQLError} with
+     * `code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h.
+     * Requires game-api ≥ v0.10.3.
+     *
+     * @param uuid - The actor's 32-character id.
+     * @param idempotencyKey - Optional client-supplied key for safe retries.
+     * @returns The deleted {@link Actor} (its identifying fields).
+     * @throws {CrowdyGraphQLError} `IDEMPOTENCY_CONFLICT`, `FORBIDDEN`, or
+     *   `UNAUTHENTICATED`.
+     */
+    async delete(uuid, idempotencyKey) {
+        const data = await this.gql.request(DeleteActorDocument, { uuid, idempotencyKey });
         return data.deleteActor;
     }
+    /**
+     * Replace just an actor's state blob(s) without touching its other fields —
+     * a lighter write than {@link update} when only `privateState`/`publicState`
+     * change. State is base64-encoded binary.
+     *
+     * @param uuid - The actor's 32-character id.
+     * @param input - {@link UpdateActorStateInput}.
+     * @returns The updated {@link Actor}.
+     * @throws {CrowdyGraphQLError} on auth/validation failures.
+     */
     async updateState(uuid, input) {
         const data = await this.gql.request(UpdateActorStateDocument, { uuid, input });
         return data.updateActorState;

package/dist/domains/apps.d.ts

@@ -1,65 +1,119 @@
-/**
- * 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:
- *
- *   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.gameApiUrl) {
- *     // Set for both dedicated (split-mode) AND shared-environment apps.
- *     const perAppClient = createCrowdyClient({
- *       managementUrl: 'https://api.example.com',
- *       httpUrl: route.gameApiUrl,
- *       wsUrl: route.gameApiUrl.replace(/^http/, 'ws'),
- *       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.
+ * The minimal routing tuple the SDK derives from an `App` row: just enough to
+ * decide which game-api endpoint should serve a given app. Returned by
+ * {@link AppsAPI.routeFor}.
  */
 export interface AppRoute {
+    /** Numeric id of the app (`BigInt` as a decimal string). */
     appId: string;
+    /**
+     * `true` when the app's runtime data lives in a dedicated per-tenant game-api
+     * database rather than the shared game-api. Used together with `gameApiUrl` to
+     * route gameplay calls.
+     */
     splitMode: boolean;
     /**
-     * 'none' (draft), 'shared' (the shared game-api), or 'dedicated' (a
-     * per-tenant environment). Populated once the schema/codegen expose it.
+     * Where the app runs: `'none'` (draft / not deployed), `'shared'` (the shared
+     * game-api), or `'dedicated'` (a provisioned per-tenant environment). `null`
+     * until the schema/codegen expose it.
      */
     deploymentTarget: string | null;
     /**
-     * The game-api URL to route gameplay to. Set for BOTH dedicated (split-mode)
-     * and shared-environment apps. When non-null, build a game-api client
-     * against it; when null, fall back to the constructor `httpUrl`.
+     * The game-api base URL to route gameplay to. Set for BOTH dedicated
+     * (split-mode) and shared-environment apps. When non-null, build a game-api
+     * client against it; when `null`, fall back to the constructor `httpUrl`.
      */
     gameApiUrl: string | null;
 }
+/**
+ * App discovery & game-api routing — exposed as `client.apps`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`), where
+ * the apps catalog lives. After the database split an app may be served by its
+ * own per-tenant cks-game-api; the catalog returns each app's `gameApiUrl` so
+ * you can build a per-app `CrowdyClient` against the correct endpoint (see
+ * {@link routeFor} / {@link AppRoute}).
+ *
+ * Auth: {@link appBySlug} is **public** (no session; resolves unlisted or draft
+ * apps when the exact slugs are known). {@link app}, {@link myApps}, and
+ * {@link routeFor} require authentication (any signed-in user) and otherwise
+ * throw {@link CrowdyGraphQLError} with `UNAUTHENTICATED`; note {@link app} does
+ * not enforce org/app permissions. `BigInt` ids such as `appId` and `orgId` are
+ * decimal strings.
+ *
+ * @example
+ * ```ts
+ * const base = createCrowdyClient({
+ *   managementUrl: 'https://api.example.com',
+ *   httpUrl: 'https://legacy-game-api.example.com', // pre-split fallback
+ * });
+ * await base.auth.login({ email, password });
+ *
+ * const route = await base.apps.routeFor(appId);
+ * if (route.gameApiUrl) {
+ *   // route gameplay to the app's resolved game-api endpoint
+ *   const perAppClient = createCrowdyClient({
+ *     managementUrl: 'https://api.example.com',
+ *     httpUrl: route.gameApiUrl,
+ *     wsUrl: route.gameApiUrl.replace(/^http/, 'ws'),
+ *     tokenStore: base.session.tokenStore,
+ *   });
+ * }
+ * ```
+ */
 export declare class AppsAPI {
     private readonly management;
     constructor(management: GraphQLClient);
-    /** Fetch a single app by id. */
+    /**
+     * Fetch a single app by its numeric id. Requires authentication (any signed-in
+     * user); does **not** enforce org/app permissions, so it can read apps the
+     * caller does not own, of any visibility/status. Prefer {@link appBySlug} for
+     * slug-based marketplace lookups.
+     *
+     * @param appId - Numeric id of the app (`BigInt` as a decimal string).
+     * @returns The {@link App}, or `null` if the id does not exist.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the caller is not signed in.
+     */
     app(appId: string): Promise<AppQuery['app']>;
-    /** Fetch by org slug + app slug (marketplace links). */
+    /**
+     * Look up a single app by its org slug + app slug (the marketplace URL path).
+     * **Public**: no authentication required, and not filtered by visibility or
+     * status — it can resolve unlisted or draft apps when the exact slugs are
+     * known.
+     *
+     * @param orgSlug - URL slug of the owning organization (e.g. `"acme"` in the
+     *   path `/acme/my-game`).
+     * @param appSlug - URL slug of the app within the org (e.g. `"my-game"`);
+     *   unique per org.
+     * @returns The {@link App}, or `null` if no matching app exists.
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
     appBySlug(orgSlug: string, appSlug: string): Promise<AppBySlugQuery['appBySlug']>;
-    /** Apps the caller can play (org membership OR active access). */
+    /**
+     * List the apps the authenticated caller can see in their account: those owned
+     * by an org they are an active member of, OR those where they hold an active
+     * access grant. Includes apps of any visibility/status (e.g. accessible
+     * drafts), ordered newest-first. Requires authentication.
+     *
+     * @returns The caller's accessible {@link App}s (an empty array if none).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the caller is not signed in.
+     */
     myApps(): Promise<MyAppsQuery['myApps']>;
     /**
-     * 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.
+     * Convenience wrapper over {@link app} that returns just the {@link AppRoute}
+     * routing tuple for an app — i.e. which game-api endpoint should serve it. If
+     * the app row is missing or the API does not expose the split-mode fields yet,
+     * returns a safe default (`{ appId, splitMode: false, deploymentTarget: null,
+     * gameApiUrl: null }`) so the caller keeps using the legacy single-endpoint
+     * deployment.
+     *
+     * @param appId - Numeric id of the app (`BigInt` as a decimal string).
+     * @returns The {@link AppRoute}; route gameplay to `gameApiUrl` when non-null,
+     *   otherwise fall back to the constructor `httpUrl`.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` (it calls {@link app} under
+     *   the hood).
      */
     routeFor(appId: string): Promise<AppRoute>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/domains/apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;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;;;OAGG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAgBD,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;CAWjD"}
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/domains/apps.ts"],"names":[],"mappings":"AAAA,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,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,aAAa;IAEtD;;;;;;;;;OASG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAQlD;;;;;;;;;;;;OAYG;IACG,SAAS,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IAQvC;;;;;;;;OAQG;IACG,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAQ9C;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;CAWjD"}

package/dist/domains/apps.js

@@ -1,29 +1,3 @@
-/**
- * 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:
- *
- *   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.gameApiUrl) {
- *     // Set for both dedicated (split-mode) AND shared-environment apps.
- *     const perAppClient = createCrowdyClient({
- *       managementUrl: 'https://api.example.com',
- *       httpUrl: route.gameApiUrl,
- *       wsUrl: route.gameApiUrl.replace(/^http/, 'ws'),
- *       tokenStore: baseClient.session.tokenStore,
- *     });
- *     // drive gameplay through perAppClient
- *   }
- */
 import { AppDocument, AppBySlugDocument, MyAppsDocument, } from '../generated/graphql.js';
 function appRouteFromAppRow(row) {
     if (!row || typeof row !== 'object')
@@ -38,30 +12,103 @@ function appRouteFromAppRow(row) {
         gameApiUrl: typeof r.gameApiUrl === 'string' && r.gameApiUrl ? r.gameApiUrl : null,
     };
 }
+/**
+ * App discovery & game-api routing — exposed as `client.apps`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`), where
+ * the apps catalog lives. After the database split an app may be served by its
+ * own per-tenant cks-game-api; the catalog returns each app's `gameApiUrl` so
+ * you can build a per-app `CrowdyClient` against the correct endpoint (see
+ * {@link routeFor} / {@link AppRoute}).
+ *
+ * Auth: {@link appBySlug} is **public** (no session; resolves unlisted or draft
+ * apps when the exact slugs are known). {@link app}, {@link myApps}, and
+ * {@link routeFor} require authentication (any signed-in user) and otherwise
+ * throw {@link CrowdyGraphQLError} with `UNAUTHENTICATED`; note {@link app} does
+ * not enforce org/app permissions. `BigInt` ids such as `appId` and `orgId` are
+ * decimal strings.
+ *
+ * @example
+ * ```ts
+ * const base = createCrowdyClient({
+ *   managementUrl: 'https://api.example.com',
+ *   httpUrl: 'https://legacy-game-api.example.com', // pre-split fallback
+ * });
+ * await base.auth.login({ email, password });
+ *
+ * const route = await base.apps.routeFor(appId);
+ * if (route.gameApiUrl) {
+ *   // route gameplay to the app's resolved game-api endpoint
+ *   const perAppClient = createCrowdyClient({
+ *     managementUrl: 'https://api.example.com',
+ *     httpUrl: route.gameApiUrl,
+ *     wsUrl: route.gameApiUrl.replace(/^http/, 'ws'),
+ *     tokenStore: base.session.tokenStore,
+ *   });
+ * }
+ * ```
+ */
 export class AppsAPI {
     constructor(management) {
         this.management = management;
     }
-    /** Fetch a single app by id. */
+    /**
+     * Fetch a single app by its numeric id. Requires authentication (any signed-in
+     * user); does **not** enforce org/app permissions, so it can read apps the
+     * caller does not own, of any visibility/status. Prefer {@link appBySlug} for
+     * slug-based marketplace lookups.
+     *
+     * @param appId - Numeric id of the app (`BigInt` as a decimal string).
+     * @returns The {@link App}, or `null` if the id does not exist.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the caller is not signed in.
+     */
     async app(appId) {
         const data = await this.management.request(AppDocument, { appId });
         return data.app;
     }
-    /** Fetch by org slug + app slug (marketplace links). */
+    /**
+     * Look up a single app by its org slug + app slug (the marketplace URL path).
+     * **Public**: no authentication required, and not filtered by visibility or
+     * status — it can resolve unlisted or draft apps when the exact slugs are
+     * known.
+     *
+     * @param orgSlug - URL slug of the owning organization (e.g. `"acme"` in the
+     *   path `/acme/my-game`).
+     * @param appSlug - URL slug of the app within the org (e.g. `"my-game"`);
+     *   unique per org.
+     * @returns The {@link App}, or `null` if no matching app exists.
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
     async appBySlug(orgSlug, appSlug) {
         const data = await this.management.request(AppBySlugDocument, { orgSlug, appSlug });
         return data.appBySlug;
     }
-    /** Apps the caller can play (org membership OR active access). */
+    /**
+     * List the apps the authenticated caller can see in their account: those owned
+     * by an org they are an active member of, OR those where they hold an active
+     * access grant. Includes apps of any visibility/status (e.g. accessible
+     * drafts), ordered newest-first. Requires authentication.
+     *
+     * @returns The caller's accessible {@link App}s (an empty array if none).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the caller is not signed in.
+     */
     async myApps() {
         const data = await this.management.request(MyAppsDocument, {});
         return data.myApps;
     }
     /**
-     * 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.
+     * Convenience wrapper over {@link app} that returns just the {@link AppRoute}
+     * routing tuple for an app — i.e. which game-api endpoint should serve it. If
+     * the app row is missing or the API does not expose the split-mode fields yet,
+     * returns a safe default (`{ appId, splitMode: false, deploymentTarget: null,
+     * gameApiUrl: null }`) so the caller keeps using the legacy single-endpoint
+     * deployment.
+     *
+     * @param appId - Numeric id of the app (`BigInt` as a decimal string).
+     * @returns The {@link AppRoute}; route gameplay to `gameApiUrl` when non-null,
+     *   otherwise fall back to the constructor `httpUrl`.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` (it calls {@link app} under
+     *   the hood).
      */
     async routeFor(appId) {
         const row = await this.app(appId);

package/dist/domains/auth.d.ts

@@ -1,43 +1,163 @@
-/**
- * Auth sub-client. Talks to `cks-management-api` (NOT the game API) because
- * the management API owns the `game_tokens` table that backs every login /
- * register / password / email-confirm flow.
- *
- * The returned `token` is a `game_tokens` row that game-api will validate
- * against the same shared Postgres. Once the SDK has a token, the rest of
- * the sub-clients (chunks, voxels, actors, udp, ...) use it transparently
- * via the shared `AuthState`.
- */
 import type { GraphQLClient } from '../client.js';
 import type { AuthState } from '../auth-state.js';
 import { type LoginMutation, type LoginUserInput, type RegisterMutation, type RegisterUserInput, type ResetPasswordInput } from '../generated/graphql.js';
+/**
+ * Authentication and account-lifecycle flows — exposed as `client.auth`.
+ *
+ * Targets the **management-api**: every call routes to `managementUrl` (falling
+ * back to the game-api endpoint only in legacy single-endpoint mode). The
+ * management API owns the `game_tokens` table that backs every login / register
+ * / password / email-confirmation flow; the `token` it returns is a
+ * `game_tokens` row that game-api validates against the same shared Postgres.
+ *
+ * {@link login} and {@link register} mint that session token **and** store it on
+ * the shared session state automatically, so every later call on *either*
+ * endpoint (auth, users, apps, actors, chunks, udp, ...) is authenticated
+ * without you threading the token through by hand. Use {@link setToken} to
+ * rehydrate a saved token and {@link getToken} to read the current one. `BigInt`
+ * ids on the returned user (e.g. `userId`, `orgId`) are decimal strings.
+ *
+ * **Public — no session required:** {@link login}, {@link register},
+ * {@link confirmEmail}, {@link requestPasswordReset}, {@link resetPassword}, and
+ * {@link resendConfirmationEmail}. **Require a valid session:** {@link logout},
+ * {@link logoutAllDevices}, and {@link changePassword}, which otherwise throw
+ * {@link CrowdyGraphQLError} with `UNAUTHENTICATED` when the bearer token is
+ * missing, expired, or revoked.
+ */
 export declare class AuthAPI {
     private readonly graphql;
     private readonly session;
     constructor(graphql: GraphQLClient, session: AuthState);
     /**
-     * Log in and persist the resulting `game_tokens` bearer token via the
-     * shared `AuthState`. All subsequent SDK calls (game-api or
-     * management-api) include it automatically.
+     * Authenticate with email + password and start a new session. **Public** — no
+     * existing session required.
+     *
+     * On success the returned `token` is minted **and** stored on the shared
+     * session state, so subsequent calls on any sub-client (management-api or
+     * game-api) carry it automatically — no need to call {@link setToken}.
+     *
+     * @param input - Credentials ({@link LoginUserInput}): `email` and `password`
+     *   (min 8 characters).
+     * @returns An {@link AuthResponse}: the opaque session `token` (sent as
+     *   `Authorization: Bearer <token>`), `gameTokenId` (the session row id, a
+     *   string), and the authenticated `user`.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` on invalid credentials, or
+     *   `BAD_USER_INPUT` on malformed input.
+     * @example
+     * ```ts
+     * const { user } = await client.auth.login({ email, password });
+     * // the session token is now stored; later calls are authenticated for you
+     * await client.users.me();
+     * ```
      */
     login(input: LoginUserInput): Promise<LoginMutation['login']>;
-    /** Register a new user. Same token-persistence behaviour as `login`. */
+    /**
+     * Create a new (initially unconfirmed) account, send a confirmation email, and
+     * return a session for immediate login. **Public** — no existing session
+     * required. Same token-persistence behaviour as {@link login}: the new `token`
+     * is stored on the shared session state automatically.
+     *
+     * @param input - New-account details ({@link RegisterUserInput}): `email`
+     *   (where the confirmation email is sent), `password` (min 8 characters), and
+     *   an optional initial `gamertag` (min 3 characters; can also be set later via
+     *   `client.users.updateGamertag`).
+     * @returns An {@link AuthResponse} (session `token`, `gameTokenId`, and the new
+     *   `user`).
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` if the email already exists or
+     *   the input is invalid.
+     */
     register(input: RegisterUserInput): Promise<RegisterMutation['register']>;
     /**
-     * Single-device logout. Clears the in-memory token after a successful
-     * server-side revoke so other sub-clients don't keep using it.
+     * Single-device logout: revoke the `game_tokens` row that authenticated this
+     * request; other devices/tokens are unaffected. After a successful server-side
+     * revoke the in-memory token is cleared from the shared session state so the
+     * other sub-clients stop using it. Requires a valid session.
+     *
+     * @returns `true` if a token was revoked, or `false` if the request carried no
+     *   game token.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the session is invalid.
      */
     logout(): Promise<boolean>;
-    /** Revoke every `game_tokens` row for the current user. */
+    /**
+     * Revoke **every** active session for the authenticated user (deletes all
+     * their `game_tokens` rows and records revocations). Requires a valid session;
+     * use {@link logout} to end only the current one.
+     *
+     * Note: unlike {@link logout}, this does not clear the SDK's in-memory token —
+     * call {@link setToken}`(null)` afterwards if you also want to drop it locally.
+     *
+     * @returns `true` on success.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the session is invalid.
+     */
     logoutAllDevices(): Promise<boolean>;
+    /**
+     * Confirm a user's email address using the token from the confirmation email.
+     * **Public** — the token itself authorizes the call.
+     *
+     * @param token - The confirmation token from the emailed link.
+     * @returns `true` on success, or `false` if the token is invalid or expired.
+     * @throws {CrowdyGraphQLError} on transport/validation failures (invalid or
+     *   expired tokens resolve to `false` rather than throwing).
+     */
     confirmEmail(token: string): Promise<boolean>;
+    /**
+     * Start the password-reset flow by emailing a reset link to the address.
+     * **Public**. Always returns `true` regardless of whether the email exists or
+     * is confirmed, to prevent account enumeration.
+     *
+     * @param email - Email address to send the password-reset link to.
+     * @returns `true` (always, even when no such account exists).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
     requestPasswordReset(email: string): Promise<boolean>;
+    /**
+     * Complete a password reset using the reset token and a new password.
+     * **Public** — the reset token authorizes the call. Existing sessions are
+     * **not** revoked.
+     *
+     * @param input - {@link ResetPasswordInput}: the `token` from the emailed reset
+     *   link and the `newPassword` to set (min 8 characters).
+     * @returns `true` on success.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` if the token is invalid or
+     *   expired.
+     */
     resetPassword(input: ResetPasswordInput): Promise<boolean>;
+    /**
+     * Re-send the email-confirmation link. **Public**. Always returns `true`
+     * regardless of whether the account exists or is already confirmed (prevents
+     * enumeration); the email is only actually sent for existing unconfirmed
+     * accounts.
+     *
+     * @param email - Email address of the account to re-send confirmation to.
+     * @returns `true` (always).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
     resendConfirmationEmail(email: string): Promise<boolean>;
+    /**
+     * Change the authenticated user's password after verifying the current one.
+     * Requires a valid session. Existing sessions are **not** revoked.
+     *
+     * @param currentPassword - The user's current password, for verification.
+     * @param newPassword - The new password to set (min 8 characters).
+     * @returns `true` on success.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` without a valid session, or
+     *   `BAD_USER_INPUT` if the current password is wrong.
+     */
     changePassword(currentPassword: string, newPassword: string): Promise<boolean>;
-    /** Imperatively replace the in-memory bearer token (e.g. on rehydrate). */
+    /**
+     * Imperatively replace the in-memory bearer token on the shared session state
+     * (e.g. to rehydrate a token persisted to disk). Affects every sub-client.
+     * Local only — performs no network call. Pass `null` to clear it.
+     *
+     * @param token - The bearer token to use, or `null` to clear the session.
+     */
     setToken(token: string | null): void;
-    /** Read the current bearer token. */
+    /**
+     * Read the current in-memory bearer token from the shared session state. Local
+     * only — performs no network call.
+     *
+     * @returns The current bearer token, or `null` if none is set.
+     */
     getToken(): string | null;
 }
 //# sourceMappingURL=auth.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/domains/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAUL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AAEjC,qBAAa,OAAO;IAEhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,SAAS;IAGrC;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAQnE,wEAAwE;IAClE,QAAQ,CACZ,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAQxC;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAMhC,2DAA2D;IACrD,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAKpC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK7C,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOrD,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAO1D,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOxD,cAAc,CAClB,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC;IAQnB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIpC,qCAAqC;IACrC,QAAQ,IAAI,MAAM,GAAG,IAAI;CAG1B"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/domains/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAUL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,OAAO;IAEhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,SAAS;IAGrC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAQnE;;;;;;;;;;;;;;OAcG;IACG,QAAQ,CACZ,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAQxC;;;;;;;;;OASG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAMhC;;;;;;;;;;OAUG;IACG,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAK1C;;;;;;;;OAQG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnD;;;;;;;;OAQG;IACG,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO3D;;;;;;;;;;OAUG;IACG,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAOhE;;;;;;;;;OASG;IACG,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO9D;;;;;;;;;OASG;IACG,cAAc,CAClB,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC;IAQnB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIpC;;;;;OAKG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;CAG1B"}