@crowdedkingdomstudios/crowdyjs 5.2.0 → 5.3.0

package/dist/domains/serverStatus.d.ts

@@ -1,22 +1,90 @@
 import type { GraphQLClient } from '../client.js';
 import { type ServerWithLeastClientsQuery, type GraphqlServersQuery, type ActiveGraphQlServersQuery, type VersionInfoQuery, type GameClientBootstrapQuery, type GameClientBootstrapQueryVariables } from '../generated/graphql.js';
 /**
- * Server status / version info queries.
- *
+ * Server discovery, version, and client-bootstrap queries on the **game-api**.
  * Exposed as `client.serverStatus`.
  *
- * NOTE: there is no separate "buddy server" query in the schema -- the
- * least-loaded UDP game server is selected automatically when a session
- * is opened. `serverWithLeastClients` returns a hint of which UDP server
- * a new session would land on.
+ * This is the **client bootstrap path**: call {@link ServerStatusAPI.gameClientBootstrap}
+ * once after login to get everything a play session needs (identity, version
+ * floors, UDP status, realtime protocol details, and spatial limits) in a single
+ * round-trip, and use {@link ServerStatusAPI.versionInfo} for standalone version
+ * discovery / update gating. The remaining queries expose UDP/GraphQL server
+ * fleet info for discovery and routing.
+ *
+ * NOTE: there is no separate "buddy server" query in the schema — the
+ * least-loaded UDP game server is selected automatically when a session is
+ * opened. {@link ServerStatusAPI.serverWithLeastClients} returns a hint of which
+ * UDP server a new session would land on.
+ *
+ * Auth varies per method: {@link ServerStatusAPI.gameClientBootstrap} and
+ * {@link ServerStatusAPI.serverWithLeastClients} require a Bearer game token (set
+ * via `client.auth.login()` or `client.setToken()`), while
+ * {@link ServerStatusAPI.listAll}, {@link ServerStatusAPI.listActiveGraphqlServers}
+ * and {@link ServerStatusAPI.versionInfo} need no authentication. `appId` is a
+ * `BigInt` sent as a decimal string.
  */
 export declare class ServerStatusAPI {
     private gql;
     constructor(gql: GraphQLClient);
+    /**
+     * Pick a low-load UDP game server for a **native (direct-UDP)** client to
+     * connect to: returns a random server from the least-loaded ~20% (by client
+     * count) of `ReadyForClients` servers to spread load. As a side effect it
+     * authorizes the token's P2P session with the chosen Buddy so the native
+     * client's spatial datagrams are accepted; connect the client to the returned
+     * `ip4` + `clientPort`. Browser clients should instead use the UDP proxy
+     * (`client.udp` / `udpNotifications`) and do not need this.
+     *
+     * @returns A {@link ServerStatus} describing the selected UDP server.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if no valid game token is
+     *   present.
+     */
     serverWithLeastClients(): Promise<ServerWithLeastClientsQuery['serverWithLeastClients']>;
+    /**
+     * List every registered GraphQL API server (both `management-api` and
+     * `game-api` kinds), regardless of health/state — for service discovery. To
+     * route clients, prefer {@link ServerStatusAPI.listActiveGraphqlServers}
+     * (healthy only). No authentication required.
+     *
+     * @returns Every registered {@link GraphQLServer}.
+     */
     listAll(): Promise<GraphqlServersQuery['graphqlServers']>;
+    /**
+     * List only healthy GraphQL API servers (`status = ReadyForClients`) for client
+     * routing/discovery. No authentication required.
+     *
+     * @returns The healthy {@link GraphQLServer}s.
+     */
     listActiveGraphqlServers(): Promise<ActiveGraphQlServersQuery['activeGraphQLServers']>;
+    /**
+     * Get the current server version and the minimum client version the server
+     * accepts. No authentication required — compare your build against
+     * `minimumClientVersion` before connecting and prompt an update if it is too
+     * old.
+     *
+     * @returns A {@link ServerVersionInfo} (`serverVersion` + `minimumClientVersion`,
+     *   each a major/minor/patch/build {@link VersionInfo}).
+     */
     versionInfo(): Promise<VersionInfoQuery['versionInfo']>;
+    /**
+     * Single startup payload for browser game clients: the authenticated user,
+     * server/min-client version requirements, current UDP proxy status, realtime
+     * protocol details (subprotocol + subscription name), and the spatial send
+     * limits/constants. Read-only — does **not** open a UDP proxy session. Call this
+     * once after login to initialize a play session instead of issuing several
+     * separate queries.
+     *
+     * @param appId - The app (game) the client is initializing for (`BigInt` as a
+     *   decimal string). Scopes the returned UDP status and mirrors the app's
+     *   entitlements; reuse the same `appId` when subscribing and on every spatial
+     *   send.
+     * @returns A {@link GameClientBootstrap}: `me`, `versionInfo`,
+     *   `udpProxyConnectionStatus`, `realtimeProtocol`, `subscriptionName`, and the
+     *   spatial limits `maxReplicationDistance` (max `distance` fan-out, in chunk
+     *   units), `maxDecayRate`, and `sequenceNumberModulo` (256).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` without a valid game token, or
+     *   `FORBIDDEN` if not entitled to the app.
+     */
     gameClientBootstrap(appId: GameClientBootstrapQueryVariables['appId']): Promise<GameClientBootstrapQuery['gameClientBootstrap']>;
 }
 //# sourceMappingURL=serverStatus.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"serverStatus.d.ts","sourceRoot":"","sources":["../../src/domains/serverStatus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,2BAA2B,EAEhC,KAAK,mBAAmB,EAExB,KAAK,yBAAyB,EAE9B,KAAK,gBAAgB,EAErB,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EACvC,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;GASG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEhC,sBAAsB,IAAI,OAAO,CAAC,2BAA2B,CAAC,wBAAwB,CAAC,CAAC;IAKxF,OAAO,IAAI,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAKzD,wBAAwB,IAAI,OAAO,CAAC,yBAAyB,CAAC,sBAAsB,CAAC,CAAC;IAKtF,WAAW,IAAI,OAAO,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAKvD,mBAAmB,CACvB,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,GAChD,OAAO,CAAC,wBAAwB,CAAC,qBAAqB,CAAC,CAAC;CAI5D"}
+{"version":3,"file":"serverStatus.d.ts","sourceRoot":"","sources":["../../src/domains/serverStatus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,2BAA2B,EAEhC,KAAK,mBAAmB,EAExB,KAAK,yBAAyB,EAE9B,KAAK,gBAAgB,EAErB,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EACvC,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;;;OAYG;IACG,sBAAsB,IAAI,OAAO,CAAC,2BAA2B,CAAC,wBAAwB,CAAC,CAAC;IAK9F;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAK/D;;;;;OAKG;IACG,wBAAwB,IAAI,OAAO,CAAC,yBAAyB,CAAC,sBAAsB,CAAC,CAAC;IAK5F;;;;;;;;OAQG;IACG,WAAW,IAAI,OAAO,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAK7D;;;;;;;;;;;;;;;;;;OAkBG;IACG,mBAAmB,CACvB,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,GAChD,OAAO,CAAC,wBAAwB,CAAC,qBAAqB,CAAC,CAAC;CAI5D"}

package/dist/domains/serverStatus.js

@@ -1,34 +1,102 @@
 import { ServerWithLeastClientsDocument, GraphqlServersDocument, ActiveGraphQlServersDocument, VersionInfoDocument, GameClientBootstrapDocument, } from '../generated/graphql.js';
 /**
- * Server status / version info queries.
- *
+ * Server discovery, version, and client-bootstrap queries on the **game-api**.
  * Exposed as `client.serverStatus`.
  *
- * NOTE: there is no separate "buddy server" query in the schema -- the
- * least-loaded UDP game server is selected automatically when a session
- * is opened. `serverWithLeastClients` returns a hint of which UDP server
- * a new session would land on.
+ * This is the **client bootstrap path**: call {@link ServerStatusAPI.gameClientBootstrap}
+ * once after login to get everything a play session needs (identity, version
+ * floors, UDP status, realtime protocol details, and spatial limits) in a single
+ * round-trip, and use {@link ServerStatusAPI.versionInfo} for standalone version
+ * discovery / update gating. The remaining queries expose UDP/GraphQL server
+ * fleet info for discovery and routing.
+ *
+ * NOTE: there is no separate "buddy server" query in the schema — the
+ * least-loaded UDP game server is selected automatically when a session is
+ * opened. {@link ServerStatusAPI.serverWithLeastClients} returns a hint of which
+ * UDP server a new session would land on.
+ *
+ * Auth varies per method: {@link ServerStatusAPI.gameClientBootstrap} and
+ * {@link ServerStatusAPI.serverWithLeastClients} require a Bearer game token (set
+ * via `client.auth.login()` or `client.setToken()`), while
+ * {@link ServerStatusAPI.listAll}, {@link ServerStatusAPI.listActiveGraphqlServers}
+ * and {@link ServerStatusAPI.versionInfo} need no authentication. `appId` is a
+ * `BigInt` sent as a decimal string.
  */
 export class ServerStatusAPI {
     constructor(gql) {
         this.gql = gql;
     }
+    /**
+     * Pick a low-load UDP game server for a **native (direct-UDP)** client to
+     * connect to: returns a random server from the least-loaded ~20% (by client
+     * count) of `ReadyForClients` servers to spread load. As a side effect it
+     * authorizes the token's P2P session with the chosen Buddy so the native
+     * client's spatial datagrams are accepted; connect the client to the returned
+     * `ip4` + `clientPort`. Browser clients should instead use the UDP proxy
+     * (`client.udp` / `udpNotifications`) and do not need this.
+     *
+     * @returns A {@link ServerStatus} describing the selected UDP server.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if no valid game token is
+     *   present.
+     */
     async serverWithLeastClients() {
         const data = await this.gql.request(ServerWithLeastClientsDocument, undefined);
         return data.serverWithLeastClients;
     }
+    /**
+     * List every registered GraphQL API server (both `management-api` and
+     * `game-api` kinds), regardless of health/state — for service discovery. To
+     * route clients, prefer {@link ServerStatusAPI.listActiveGraphqlServers}
+     * (healthy only). No authentication required.
+     *
+     * @returns Every registered {@link GraphQLServer}.
+     */
     async listAll() {
         const data = await this.gql.request(GraphqlServersDocument, undefined);
         return data.graphqlServers;
     }
+    /**
+     * List only healthy GraphQL API servers (`status = ReadyForClients`) for client
+     * routing/discovery. No authentication required.
+     *
+     * @returns The healthy {@link GraphQLServer}s.
+     */
     async listActiveGraphqlServers() {
         const data = await this.gql.request(ActiveGraphQlServersDocument, undefined);
         return data.activeGraphQLServers;
     }
+    /**
+     * Get the current server version and the minimum client version the server
+     * accepts. No authentication required — compare your build against
+     * `minimumClientVersion` before connecting and prompt an update if it is too
+     * old.
+     *
+     * @returns A {@link ServerVersionInfo} (`serverVersion` + `minimumClientVersion`,
+     *   each a major/minor/patch/build {@link VersionInfo}).
+     */
     async versionInfo() {
         const data = await this.gql.request(VersionInfoDocument, undefined);
         return data.versionInfo;
     }
+    /**
+     * Single startup payload for browser game clients: the authenticated user,
+     * server/min-client version requirements, current UDP proxy status, realtime
+     * protocol details (subprotocol + subscription name), and the spatial send
+     * limits/constants. Read-only — does **not** open a UDP proxy session. Call this
+     * once after login to initialize a play session instead of issuing several
+     * separate queries.
+     *
+     * @param appId - The app (game) the client is initializing for (`BigInt` as a
+     *   decimal string). Scopes the returned UDP status and mirrors the app's
+     *   entitlements; reuse the same `appId` when subscribing and on every spatial
+     *   send.
+     * @returns A {@link GameClientBootstrap}: `me`, `versionInfo`,
+     *   `udpProxyConnectionStatus`, `realtimeProtocol`, `subscriptionName`, and the
+     *   spatial limits `maxReplicationDistance` (max `distance` fan-out, in chunk
+     *   units), `maxDecayRate`, and `sequenceNumberModulo` (256).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` without a valid game token, or
+     *   `FORBIDDEN` if not entitled to the app.
+     */
     async gameClientBootstrap(appId) {
         const data = await this.gql.request(GameClientBootstrapDocument, { appId });
         return data.gameClientBootstrap;

package/dist/domains/state.d.ts

@@ -1,16 +1,64 @@
 import type { GraphQLClient } from '../client.js';
 import { type UserAppStateQuery, type UserAppStateQueryVariables, type UserAppStatesQuery, type UpdateUserAppStateMutation, type UpdateUserAppStateMutationVariables, type DeleteUserAppStateMutation, type DeleteUserAppStateMutationVariables } from '../generated/graphql.js';
 /**
- * Per-user, per-app state storage (formerly `userMapState`).
- *
+ * Per-user, per-app state storage on the **game-api** (formerly `userMapState`).
  * Exposed as `client.state`.
+ *
+ * Each row is the authenticated user's own opaque state blob scoped to one app
+ * (keyed by `appId` + `userId`) — a convenient place to persist small
+ * per-player, per-game data. The `state` blob is **base64-encoded** binary
+ * (null when cleared) and `appId` is a `BigInt` sent and received as a decimal
+ * string.
+ *
+ * Every method requires an authenticated session (a Bearer game token set via
+ * `client.auth.login()` or `client.setToken()`) and only ever reads or writes
+ * the **caller's own** state, otherwise {@link CrowdyGraphQLError} is thrown
+ * (`UNAUTHENTICATED`).
  */
 export declare class StateAPI {
     private gql;
     constructor(gql: GraphQLClient);
+    /**
+     * Read the authenticated user's per-app state for `appId`.
+     *
+     * @param appId - App (game) id the state is scoped to (`BigInt` as a decimal
+     *   string).
+     * @returns The {@link UserAppState} (its `state` blob base64-encoded), or
+     *   `null` when no row exists.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED`.
+     */
     getOne(appId: UserAppStateQueryVariables['appId']): Promise<UserAppStateQuery['userAppState']>;
+    /**
+     * List all of the authenticated user's per-app state rows, ordered
+     * newest-updated first. Takes no arguments.
+     *
+     * @returns The caller's {@link UserAppState} rows (each `state` blob
+     *   base64-encoded).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED`.
+     */
     getAll(): Promise<UserAppStatesQuery['userAppStates']>;
+    /**
+     * Create or replace (upsert) the authenticated user's per-app state for
+     * `input.appId`, keyed by `appId` + `userId`. Always writes the caller's own
+     * state.
+     *
+     * @param input - {@link CreateUserAppStateInput}: the target `appId` (decimal
+     *   string) and the new `state` blob (base64-encoded binary; omit/null to clear
+     *   it).
+     * @returns The upserted {@link UserAppState}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` or `UNAUTHENTICATED`.
+     */
     update(input: UpdateUserAppStateMutationVariables['input']): Promise<UpdateUserAppStateMutation['updateUserAppState']>;
+    /**
+     * **Destructive:** delete the authenticated user's per-app state row for
+     * `appId` and return the deleted row. Acts only on the caller's own state.
+     *
+     * @param appId - App (game) id whose state row to delete (`BigInt` as a decimal
+     *   string).
+     * @returns The deleted {@link UserAppState}.
+     * @throws {CrowdyGraphQLError} when no state row exists for `appId`
+     *   (not-found), or `UNAUTHENTICATED`.
+     */
     delete(appId: DeleteUserAppStateMutationVariables['appId']): Promise<DeleteUserAppStateMutation['deleteUserAppState']>;
 }
 //# sourceMappingURL=state.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/domains/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAE/B,KAAK,kBAAkB,EAEvB,KAAK,0BAA0B,EAC/B,KAAK,mCAAmC,EAExC,KAAK,0BAA0B,EAC/B,KAAK,mCAAmC,EACzC,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,qBAAa,QAAQ;IACP,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEhC,MAAM,CACV,KAAK,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACzC,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAKvC,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAKtD,MAAM,CACV,KAAK,EAAE,mCAAmC,CAAC,OAAO,CAAC,GAClD,OAAO,CAAC,0BAA0B,CAAC,oBAAoB,CAAC,CAAC;IAKtD,MAAM,CACV,KAAK,EAAE,mCAAmC,CAAC,OAAO,CAAC,GAClD,OAAO,CAAC,0BAA0B,CAAC,oBAAoB,CAAC,CAAC;CAI7D"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/domains/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAE/B,KAAK,kBAAkB,EAEvB,KAAK,0BAA0B,EAC/B,KAAK,mCAAmC,EAExC,KAAK,0BAA0B,EAC/B,KAAK,mCAAmC,EACzC,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ;IACP,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;OAQG;IACG,MAAM,CACV,KAAK,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACzC,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAK7C;;;;;;;OAOG;IACG,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAK5D;;;;;;;;;;OAUG;IACG,MAAM,CACV,KAAK,EAAE,mCAAmC,CAAC,OAAO,CAAC,GAClD,OAAO,CAAC,0BAA0B,CAAC,oBAAoB,CAAC,CAAC;IAK5D;;;;;;;;;OASG;IACG,MAAM,CACV,KAAK,EAAE,mCAAmC,CAAC,OAAO,CAAC,GAClD,OAAO,CAAC,0BAA0B,CAAC,oBAAoB,CAAC,CAAC;CAI7D"}

package/dist/domains/state.js

@@ -1,25 +1,73 @@
 import { UserAppStateDocument, UserAppStatesDocument, UpdateUserAppStateDocument, DeleteUserAppStateDocument, } from '../generated/graphql.js';
 /**
- * Per-user, per-app state storage (formerly `userMapState`).
- *
+ * Per-user, per-app state storage on the **game-api** (formerly `userMapState`).
  * Exposed as `client.state`.
+ *
+ * Each row is the authenticated user's own opaque state blob scoped to one app
+ * (keyed by `appId` + `userId`) — a convenient place to persist small
+ * per-player, per-game data. The `state` blob is **base64-encoded** binary
+ * (null when cleared) and `appId` is a `BigInt` sent and received as a decimal
+ * string.
+ *
+ * Every method requires an authenticated session (a Bearer game token set via
+ * `client.auth.login()` or `client.setToken()`) and only ever reads or writes
+ * the **caller's own** state, otherwise {@link CrowdyGraphQLError} is thrown
+ * (`UNAUTHENTICATED`).
  */
 export class StateAPI {
     constructor(gql) {
         this.gql = gql;
     }
+    /**
+     * Read the authenticated user's per-app state for `appId`.
+     *
+     * @param appId - App (game) id the state is scoped to (`BigInt` as a decimal
+     *   string).
+     * @returns The {@link UserAppState} (its `state` blob base64-encoded), or
+     *   `null` when no row exists.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED`.
+     */
     async getOne(appId) {
         const data = await this.gql.request(UserAppStateDocument, { appId });
         return data.userAppState;
     }
+    /**
+     * List all of the authenticated user's per-app state rows, ordered
+     * newest-updated first. Takes no arguments.
+     *
+     * @returns The caller's {@link UserAppState} rows (each `state` blob
+     *   base64-encoded).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED`.
+     */
     async getAll() {
         const data = await this.gql.request(UserAppStatesDocument, undefined);
         return data.userAppStates;
     }
+    /**
+     * Create or replace (upsert) the authenticated user's per-app state for
+     * `input.appId`, keyed by `appId` + `userId`. Always writes the caller's own
+     * state.
+     *
+     * @param input - {@link CreateUserAppStateInput}: the target `appId` (decimal
+     *   string) and the new `state` blob (base64-encoded binary; omit/null to clear
+     *   it).
+     * @returns The upserted {@link UserAppState}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` or `UNAUTHENTICATED`.
+     */
     async update(input) {
         const data = await this.gql.request(UpdateUserAppStateDocument, { input });
         return data.updateUserAppState;
     }
+    /**
+     * **Destructive:** delete the authenticated user's per-app state row for
+     * `appId` and return the deleted row. Acts only on the caller's own state.
+     *
+     * @param appId - App (game) id whose state row to delete (`BigInt` as a decimal
+     *   string).
+     * @returns The deleted {@link UserAppState}.
+     * @throws {CrowdyGraphQLError} when no state row exists for `appId`
+     *   (not-found), or `UNAUTHENTICATED`.
+     */
     async delete(appId) {
         const data = await this.gql.request(DeleteUserAppStateDocument, { appId });
         return data.deleteUserAppState;