@crowdedkingdomstudios/crowdyjs 5.2.0 → 5.3.0

package/dist/domains/gameModel.js

@@ -4,109 +4,515 @@ GameModelCreateSessionDocument, GameModelJoinSessionDocument, GameModelSetSessio
 // Studio authoring ops
 GameModelSeedDocument, GameModelUpsertContainerTypeDocument, GameModelUpsertPropertyDefDocument, GameModelUpsertFunctionDocument, GameModelDeleteFunctionDocument, GameModelDefineFeatureDocument, GameModelGrantTierFeatureDocument, GameModelSetPolicyDocument, GameModelTypeSchemaDocument, } from '../generated/graphql.js';
 /**
- * Abstract game model sub-client (cks-game-api). Studios author the model
- * (container types, property schemas, functions, tier features) and players
- * query state + invoke functions at runtime.
+ * Abstract **game-model** sub-client on the **game-api** — a schema-driven,
+ * server-authoritative layer for modelling game/world logic on top of the
+ * spatial voxel world. Studios *author* the model; players *query* state and
+ * *invoke* functions at runtime. Exposed as `client.gameModel`.
  *
- * Arbitrary JSON values are passed/returned as JSON-encoded strings (the
- * `*Json` fields); callers JSON.parse / JSON.stringify around them.
+ * The model is a typed graph of entities:
+ * - **Container types** are the schemas (like classes) for a kind of entity.
+ *   **Property definitions** are their typed fields, each with a default value,
+ *   a read **visibility** (`public | owner | hidden`) and a **writability**
+ *   (`function | owner | admin`). See {@link upsertContainerType} /
+ *   {@link upsertPropertyDef} / {@link typeSchema}.
+ * - **Containers** are the runtime instances of a type, optionally scoped to a
+ *   session and carrying property values. See {@link createContainer},
+ *   {@link container}, {@link containers}, {@link containerState}.
+ * - **Functions** are named, sandboxed behaviours over containers: typed
+ *   parameters, declared property **mutations** (expressions compiled to an AST
+ *   server-side — never `eval`'d), an optional return expression, an
+ *   `invokeScope` (`player | server | internal`), and an **invoke policy** — an
+ *   authority rule tree of `owner_of_self`, `is_host`, `is_current_turn`,
+ *   `is_participant`, `tier_feature`, `group_permission`, `grid_permission`, and
+ *   `condition` rules. {@link invoke} is the primary, *safe* way for players to
+ *   mutate state: the server checks the policy, evaluates the expressions,
+ *   applies the mutations atomically, and logs an **event**.
+ * - **Sessions** are isolated instance scopes (a match, room, or save) with
+ *   **participants**, a creator, and an optional current-**turn** user for
+ *   turn-based play. See {@link createSession}, {@link joinSession},
+ *   {@link setSessionTurn}, {@link session}, {@link sessions}.
+ * - **Edges** are directed, typed relationships between containers (the model is
+ *   a graph); {@link traverse} walks them from a root up to a depth. See
+ *   {@link addEdge}.
+ * - **Events** are an audit log of every function invocation and its outcome.
+ *   See {@link events}.
+ * - **App features** are keys functions gate on (via `tier_feature` rules) and
+ *   that **access tiers** can be granted ({@link defineFeature},
+ *   {@link grantTierFeature}); **policy** governs who may create sessions and the
+ *   default participant role ({@link setPolicy}).
+ * - {@link seed} bulk-creates definitions *and* instances in one transaction for
+ *   model init/import.
  *
- * Exposed as `client.gameModel`.
+ * **Encoding.** `BigInt` ids (`appId`, `tierId`, every `*UserId`) are sent and
+ * received as decimal **strings**. Container, session, function, edge, and event
+ * ids are opaque **UUID strings**. All structured values travel as JSON-encoded
+ * strings in the `*Json` fields (`metadataJson`, `propertiesJson`, `paramsJson`,
+ * `valueJson`, `returnValueJson`, `invokePolicyJson`, `idMapJson`, …) — callers
+ * `JSON.parse` / `JSON.stringify` around them. (Unlike actor/state blobs, these
+ * are JSON text, not base64.)
+ *
+ * **Auth.** Every call requires an authenticated session (a Bearer token set via
+ * `client.auth.login()` or `client.setToken()`) scoped to the target app, or it
+ * throws {@link CrowdyGraphQLError} (`UNAUTHENTICATED` / `SCOPE_MISSING`). The
+ * **studio-authoring** methods ({@link seed}, {@link upsertContainerType},
+ * {@link upsertPropertyDef}, {@link upsertFunction}, {@link deleteFunction},
+ * {@link defineFeature}, {@link grantTierFeature}, {@link setPolicy}) and the
+ * {@link typeSchema} query additionally require the app-admin **`manage_apps`**
+ * permission (otherwise `FORBIDDEN`, with `extensions.requiredPermission ===
+ * 'manage_apps'`); the runtime/player methods need only a valid token plus
+ * whatever per-operation policy applies (session-creation policy, a type's
+ * `instantiableBy` rule, a property's `writable` rule, or a function's invoke
+ * policy).
+ *
+ * @example
+ * ```ts
+ * // Studio authors a type, then a player creates a session and invokes a function.
+ * await client.gameModel.upsertContainerType({ appId, typeName: 'Player', displayName: 'Player' });
+ * const session = await client.gameModel.createSession({ appId, name: 'Match 1' });
+ * const result = await client.gameModel.invoke({
+ *   appId,
+ *   functionName: 'takeDamage',
+ *   selfContainerId,
+ *   paramsJson: JSON.stringify({ amount: 10 }),
+ * });
+ * if (!result.success) console.warn(result.errorMessage); // authority/eval failures don't throw
+ * ```
  */
 export class GameModelAPI {
     constructor(gql) {
         this.gql = gql;
     }
     // -- Runtime (player) -------------------------------------------------------
+    /**
+     * **Sessions** — create a runtime session: an isolated instance scope for
+     * containers (e.g. a match, room, or save). Subject to the app's
+     * session-creation policy ({@link setPolicy}); the caller becomes the creator
+     * and a participant.
+     *
+     * @param input - {@link CreateSessionInput}: `appId` (decimal string), an
+     *   optional `name`, optional `metadataJson` (a JSON-object string), and
+     *   optional `participantUserIds` (decimal-string ids of initial participants
+     *   besides the creator).
+     * @returns The created {@link GmSession} (`sessionId`, `status`, creator,
+     *   current turn, metadata, …).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING` if the token
+     *   is missing or not scoped to the app, `FORBIDDEN` if the session-creation
+     *   policy disallows the caller, or `BAD_USER_INPUT` for malformed input.
+     */
     async createSession(input) {
         const data = await this.gql.request(GameModelCreateSessionDocument, { input });
         return data.gameModelCreateSession;
     }
+    /**
+     * **Sessions** — join an existing session as a participant, optionally with a
+     * role. Requires a valid token and access to the app.
+     *
+     * @param input - {@link JoinSessionInput}: `appId` (decimal string),
+     *   `sessionId`, and an optional participant `role`.
+     * @returns The {@link GmSessionParticipant} record (`sessionId`, `userId`,
+     *   `role`).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `NOT_FOUND` if no such session, or `FORBIDDEN` if joining isn't permitted.
+     */
     async joinSession(input) {
         const data = await this.gql.request(GameModelJoinSessionDocument, { input });
         return data.gameModelJoinSession;
     }
+    /**
+     * **Sessions** — set or clear the session's current-turn user, for turn-based
+     * play (turn authority is enforced by the service).
+     *
+     * @param input - {@link SetSessionTurnInput}: `appId` (decimal string),
+     *   `sessionId`, and `userId` (the decimal-string id of the user whose turn it
+     *   now is) — pass `userId: null` to **clear** the turn.
+     * @returns The updated {@link GmSession} (with `currentTurnUserId` reflecting
+     *   the change).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `NOT_FOUND` if the session doesn't exist, or `FORBIDDEN` if the caller may
+     *   not change the turn.
+     */
     async setSessionTurn(input) {
         const data = await this.gql.request(GameModelSetSessionTurnDocument, { input });
         return data.gameModelSetSessionTurn;
     }
+    /**
+     * **Containers** — instantiate a container (a runtime entity of a given type),
+     * optionally within a session, with an owner and initial property values.
+     * Subject to the type's `instantiableBy` rule (`admin | member | owner`).
+     *
+     * @param input - {@link CreateContainerInput}: `appId` (decimal string), an
+     *   optional `sessionId` (omit for an app-global container), the `typeName` to
+     *   instantiate, a `displayName`, optional `description`, optional
+     *   `ownerUserId` (decimal string; defaults to the caller for member/owner
+     *   instantiation), optional `metadataJson` (JSON-object string), and optional
+     *   initial `properties` (each `{ key, valueType, valueJson }` with a
+     *   JSON-encoded value).
+     * @returns The created {@link GmContainer}.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` if `instantiableBy` disallows the caller, `NOT_FOUND` for an
+     *   unknown type, or `BAD_USER_INPUT` for malformed properties.
+     */
     async createContainer(input) {
         const data = await this.gql.request(GameModelCreateContainerDocument, { input });
         return data.gameModelCreateContainer;
     }
+    /**
+     * **Containers** — set a single property value on a container directly (outside
+     * a function). Allowed only when the property's `writable` rule
+     * (`function | owner | admin`) permits the caller; the value is JSON-encoded
+     * and coerced to the property's declared value type. For game-logic changes
+     * prefer {@link invoke}, which enforces an authority policy and logs an event.
+     *
+     * @param input - {@link SetContainerPropertyInput}: `appId` (decimal string),
+     *   `containerId`, the property `key`, its `valueType` (must match the property
+     *   definition), and `valueJson` (the JSON-encoded value to write).
+     * @returns The updated {@link GmContainer}.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` if the property's `writable` rule forbids a direct write,
+     *   `NOT_FOUND` for an unknown container/property, or `BAD_USER_INPUT` for a
+     *   value-type mismatch.
+     */
     async setProperty(input) {
         const data = await this.gql.request(GameModelSetPropertyDocument, { input });
         return data.gameModelSetProperty;
     }
+    /**
+     * **Edges** — create a directed relationship edge between two containers (the
+     * game model is a graph), with a relationship type and optional weight.
+     *
+     * @param input - {@link AddEdgeInput}: `appId` (decimal string),
+     *   `fromContainerId` (source) and `toContainerId` (target), a
+     *   `relationshipType` label, an optional numeric `weight`, and optional
+     *   `metadataJson` (JSON-object string).
+     * @returns The created {@link GmEdge} (`edgeId`, endpoints, type, weight).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `NOT_FOUND` if either container is unknown, or `BAD_USER_INPUT`.
+     */
     async addEdge(input) {
         const data = await this.gql.request(GameModelAddEdgeDocument, { input });
         return data.gameModelAddEdge;
     }
+    /**
+     * **Functions** — invoke a studio-defined function against a `self` container
+     * with JSON params. This is the primary, *safe* way for players to mutate game
+     * state: the server enforces the function's invoke policy (the authority rule
+     * tree — `owner_of_self` / `is_host` / `is_current_turn` / `is_participant` /
+     * `tier_feature` / `group_permission` / `grid_permission` / `condition`),
+     * evaluates its expressions, atomically applies its declared property
+     * mutations, and logs an {@link events | event}. Only `player`-scope functions
+     * are invocable here.
+     *
+     * Note: an authority denial or an expression-evaluation error is **not** a
+     * thrown exception — it comes back as a resolved result with `success: false`
+     * and an `errorMessage`. Inspect `result.success` rather than relying on
+     * `try/catch` for those cases.
+     *
+     * @param input - {@link InvokeFunctionInput}: `appId` (decimal string), the
+     *   `functionName`, the `selfContainerId` (the container the function runs
+     *   against, referenced as `self` in expressions), an optional `sessionId`
+     *   context, and `paramsJson` (a JSON-object string of params).
+     * @returns A {@link GmInvokeResult}: `success`, the logged `eventId`, the
+     *   JSON-encoded `returnValueJson`, the `mutationsApplied` (each with
+     *   before/after JSON values), and `errorMessage` when `success` is `false`.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `NOT_FOUND` for an unknown function/container, `FORBIDDEN` if the function
+     *   isn't `player`-scope, or `BAD_USER_INPUT` for malformed params. (Authority
+     *   and evaluation failures surface as `success: false`, see above.)
+     */
     async invoke(input) {
         const data = await this.gql.request(GameModelInvokeDocument, { input });
         return data.gameModelInvoke;
     }
+    /**
+     * **Containers** — fetch one container (instance) by id, with its full record
+     * (unfiltered metadata). For a player-facing view whose property values are
+     * filtered to what the caller may see, use {@link containerState} instead.
+     *
+     * @param variables - `{ appId, containerId }`: `appId` (decimal string) is the
+     *   owning app and `containerId` is the container UUID to fetch.
+     * @returns The {@link GmContainer}.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`, or
+     *   `NOT_FOUND` if no such container.
+     */
     async container(variables) {
         const data = await this.gql.request(GameModelContainerDocument, variables);
         return data.gameModelContainer;
     }
+    /**
+     * **Containers** — list containers in an app, optionally narrowed by container
+     * type and/or session.
+     *
+     * @param variables - `{ appId, typeName?, sessionId? }`: `appId` (decimal
+     *   string); optional `typeName` (omit for all types); optional `sessionId`
+     *   (omit for all containers, including app-global ones).
+     * @returns The matching {@link GmContainer}s.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`.
+     */
     async containers(variables) {
         const data = await this.gql.request(GameModelContainersDocument, variables);
         return data.gameModelContainers;
     }
+    /**
+     * **Containers** — fetch a container together with its property values
+     * filtered to what the **calling** user is allowed to see (`public` always;
+     * `owner`/`hidden` depend on the caller's relationship to the container). Use
+     * this for a player-facing view of an entity.
+     *
+     * @param variables - `{ appId, containerId }`: `appId` (decimal string) and
+     *   the `containerId` UUID whose visible state to fetch.
+     * @returns A {@link GmContainerState}; its `propertiesJson` is a JSON-object
+     *   string of the properties visible to the caller (`JSON.parse` it).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`, or
+     *   `NOT_FOUND` if no such container.
+     */
     async containerState(variables) {
         const data = await this.gql.request(GameModelContainerStateDocument, variables);
         return data.gameModelContainerState;
     }
+    /**
+     * **Edges** — traverse the container graph from a root container along a
+     * relationship type up to a given depth, returning the reachable nodes and the
+     * edges between them.
+     *
+     * @param variables - `{ appId, rootId, relationshipType, depth? }`: `appId`
+     *   (decimal string); the `rootId` container UUID to start from; the
+     *   `relationshipType` edge label to follow; and optional `depth`, the number
+     *   of edge hops to follow from the root (defaults to `1`).
+     * @returns A {@link GmTraverseResult}: the `rootId`, the reachable `nodes`
+     *   ({@link GmContainer}[]), and the traversed `edges` ({@link GmEdge}[]).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`, or
+     *   `NOT_FOUND` if the root container is unknown.
+     */
     async traverse(variables) {
         const data = await this.gql.request(GameModelTraverseDocument, variables);
         return data.gameModelTraverse;
     }
+    /**
+     * **Sessions** — fetch one session by id.
+     *
+     * @param variables - `{ appId, sessionId }`: `appId` (decimal string) and the
+     *   `sessionId` to fetch.
+     * @returns The {@link GmSession}.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`, or
+     *   `NOT_FOUND` if no such session.
+     */
     async session(variables) {
         const data = await this.gql.request(GameModelSessionDocument, variables);
         return data.gameModelSession;
     }
+    /**
+     * **Sessions** — list sessions in an app, optionally filtered by status.
+     *
+     * @param variables - `{ appId, status? }`: `appId` (decimal string) and an
+     *   optional `status` filter (e.g. `'active'`; omit for all statuses).
+     * @returns The matching {@link GmSession}s.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`.
+     */
     async sessions(variables) {
         const data = await this.gql.request(GameModelSessionsDocument, variables);
         return data.gameModelSessions;
     }
+    /**
+     * **Events** — query the function-invocation event log (audit trail) with
+     * optional filters and pagination. Useful for debugging functions or showing
+     * recent activity.
+     *
+     * @param variables - `{ appId, sessionId?, selfContainerId?, functionName?,
+     *   success?, limit?, offset? }`: `appId` (decimal string); optional
+     *   `sessionId`; optional `selfContainerId` (the UUID the function ran
+     *   against); optional `functionName`; optional `success` (`true` = succeeded,
+     *   `false` = failed). `limit` (page size) and `offset` (rows to skip) are
+     *   **deprecated** — see below.
+     * @returns The matching {@link GmEvent}s (each with `paramsJson`,
+     *   `mutationsAppliedJson`, `returnValueJson`, `success`, `errorMessage`, and
+     *   `executedAt`).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`.
+     * @remarks The `limit`/`offset` fields use deprecated offset pagination. For
+     *   large logs prefer the Relay-style `gameModelEventsConnection(first:, after:)`
+     *   cursor query (available on the schema via `client.graphql`). See
+     *   https://docs.crowdedkingdoms.com/overview/pagination.
+     */
     async events(variables) {
         const data = await this.gql.request(GameModelEventsDocument, variables);
         return data.gameModelEvents;
     }
     // -- Studio authoring -------------------------------------------------------
+    /**
+     * **Seed** — bulk-create game-model definitions (container types, property
+     * defs, functions) and optionally instances (containers + edges) in one
+     * transaction; used to initialize or import a model.
+     *
+     * Requires the app-admin **`manage_apps`** permission.
+     *
+     * @param input - {@link SeedGameModelInput}: `appId` (decimal string); an
+     *   optional `sessionId` to seed instances into (omit/`null` = app-global);
+     *   and arrays of `containerTypes`, `propertyDefinitions`, `functions`,
+     *   `containers`, and `edges` to create. Seed containers carry a developer
+     *   `tempId`; seed edges reference containers by those temp ids
+     *   (`fromTempId`/`toTempId`).
+     * @returns A {@link GmSeedResult}: the counts created, non-fatal `warnings`,
+     *   and `idMapJson` — a JSON-object string mapping each seed `tempId` to the
+     *   created container UUID (`JSON.parse` it to wire up follow-up calls).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` (with `extensions.requiredPermission === 'manage_apps'`) if the
+     *   caller lacks app-admin, or `BAD_USER_INPUT` for malformed definitions.
+     */
     async seed(input) {
         const data = await this.gql.request(GameModelSeedDocument, { input });
         return data.gameModelSeed;
     }
+    /**
+     * **Container types** — create or update a container type: the studio-defined
+     * schema for a kind of runtime entity (like a class). Idempotent on
+     * `(appId, typeName)`.
+     *
+     * Requires the app-admin **`manage_apps`** permission.
+     *
+     * @param input - {@link UpsertContainerTypeInput}: `appId` (decimal string);
+     *   the `typeName` (the stable upsert key, unique per app); a `displayName`;
+     *   optional `description`; optional `instantiableBy` (`admin | member |
+     *   owner`); optional `defaultPropertyVisibility` (`public | owner | hidden`);
+     *   and optional `metadataJson` (JSON-object string).
+     * @returns The upserted {@link GmContainerType}.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` (`requiredPermission === 'manage_apps'`), or `BAD_USER_INPUT`.
+     */
     async upsertContainerType(input) {
         const data = await this.gql.request(GameModelUpsertContainerTypeDocument, { input });
         return data.gameModelUpsertContainerType;
     }
+    /**
+     * **Property definitions** — create or update a typed property on a container
+     * type (a field with a default value, read visibility, and writability).
+     * Idempotent on `(appId, containerTypeName, key)`.
+     *
+     * Requires the app-admin **`manage_apps`** permission.
+     *
+     * @param input - {@link UpsertPropertyDefInput}: `appId` (decimal string); the
+     *   `containerTypeName` to define on; the property `key` (part of the upsert
+     *   key); a `valueType` (`int | float | string | bool | array | object |
+     *   container_ref`); optional `defaultValueJson` (JSON-encoded default);
+     *   optional `visibility` (`public | owner | hidden`); optional `writable`
+     *   (`function | owner | admin`); and optional `description`.
+     * @returns The upserted {@link GmPropertyDef}.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` (`requiredPermission === 'manage_apps'`), `NOT_FOUND` for an
+     *   unknown container type, or `BAD_USER_INPUT`.
+     */
     async upsertPropertyDef(input) {
         const data = await this.gql.request(GameModelUpsertPropertyDefDocument, { input });
         return data.gameModelUpsertPropertyDef;
     }
+    /**
+     * **Functions** — create or update a studio-defined function: a named,
+     * sandboxed behaviour with typed parameters, declared property mutations
+     * (expressions compiled to an AST server-side — never `eval`'d), an optional
+     * return expression, an invoke scope, and an invoke policy (authority rule
+     * tree). Idempotent on `(appId, name)`. Players run these via {@link invoke}.
+     *
+     * Requires the app-admin **`manage_apps`** permission.
+     *
+     * @param input - {@link UpsertFunctionInput}: `appId` (decimal string); the
+     *   `name` (upsert key, used to invoke it); optional `containerTypeName` to
+     *   bind to (omit for a global function); optional `description`; optional
+     *   `returnType`; `parameters` (typed `{ name, valueType, required?,
+     *   defaultValueJson?, … }`); `mutations` (declared writes `{ target, property,
+     *   expression }`, applied atomically); optional `returnExpression`;
+     *   `invokeScope` (`player | server | internal`); and `invokePolicyJson` (a
+     *   JSON-encoded authority rule tree).
+     * @returns The upserted {@link GmFunction}, including any non-fatal
+     *   static-analysis `warnings` from this upload.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` (`requiredPermission === 'manage_apps'`), or `BAD_USER_INPUT`
+     *   for an expression/policy that fails to compile.
+     */
     async upsertFunction(input) {
         const data = await this.gql.request(GameModelUpsertFunctionDocument, { input });
         return data.gameModelUpsertFunction;
     }
+    /**
+     * **Functions** — delete a studio-defined function by name. **Destructive.**
+     *
+     * Requires the app-admin **`manage_apps`** permission.
+     *
+     * @param variables - `{ appId, name }`: `appId` (decimal string) and the
+     *   function `name` to delete.
+     * @returns `true` if a function was deleted, `false` if none matched.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`, or
+     *   `FORBIDDEN` (`requiredPermission === 'manage_apps'`) if the caller lacks
+     *   app-admin.
+     */
     async deleteFunction(variables) {
         const data = await this.gql.request(GameModelDeleteFunctionDocument, variables);
         return data.gameModelDeleteFunction;
     }
+    /**
+     * **App features** — define an app feature key that functions can gate on (via
+     * a `tier_feature` authority rule) and that access tiers can be granted.
+     * Idempotent on `(appId, featureKey)`.
+     *
+     * Requires the app-admin **`manage_apps`** permission.
+     *
+     * @param input - {@link DefineAppFeatureInput}: `appId` (decimal string); the
+     *   `featureKey` (referenced by `tier_feature` rules); and an optional
+     *   `description`.
+     * @returns The defined {@link GmAppFeature}.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` (`requiredPermission === 'manage_apps'`), or `BAD_USER_INPUT`.
+     */
     async defineFeature(input) {
         const data = await this.gql.request(GameModelDefineFeatureDocument, { input });
         return data.gameModelDefineFeature;
     }
+    /**
+     * **App features** — grant a feature key to an access tier, so users on that
+     * tier satisfy `tier_feature` authority checks for it.
+     *
+     * Requires the app-admin **`manage_apps`** permission.
+     *
+     * @param input - {@link GrantTierFeatureInput}: `appId` (decimal string); the
+     *   `tierId` (decimal string) of the access tier; and the `featureKey` to
+     *   grant to that tier.
+     * @returns The {@link GmTierFeature} grant record.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` (`requiredPermission === 'manage_apps'`), or `NOT_FOUND` for an
+     *   unknown tier/feature.
+     */
     async grantTierFeature(input) {
         const data = await this.gql.request(GameModelGrantTierFeatureDocument, { input });
         return data.gameModelGrantTierFeature;
     }
+    /**
+     * **Policy** — set the app's game-model runtime policy: who may create
+     * sessions and the default role assigned to new session participants.
+     *
+     * Requires the app-admin **`manage_apps`** permission.
+     *
+     * @param input - {@link SetGameModelPolicyInput}: `appId` (decimal string); an
+     *   optional `sessionCreationPolicy` (`admin | member | anyone`); and an
+     *   optional `defaultParticipantRole`.
+     * @returns The updated {@link GmAppPolicy}.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` (`requiredPermission === 'manage_apps'`), or `BAD_USER_INPUT`.
+     */
     async setPolicy(input) {
         const data = await this.gql.request(GameModelSetPolicyDocument, { input });
         return data.gameModelSetPolicy;
     }
+    /**
+     * **Container types** — fetch a container type's full schema: its property
+     * definitions plus the functions available on it. A studio/authoring read.
+     *
+     * Requires the app-admin **`manage_apps`** permission.
+     *
+     * @param variables - `{ appId, typeName }`: `appId` (decimal string) and the
+     *   `typeName` whose schema to fetch.
+     * @returns A {@link GmTypeSchema}: the `typeName`, its `propertyDefinitions`
+     *   ({@link GmPropertyDef}[]), and its `functions` ({@link GmFunction}[]).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `SCOPE_MISSING`,
+     *   `FORBIDDEN` (`requiredPermission === 'manage_apps'`), or `NOT_FOUND` for an
+     *   unknown type.
+     */
     async typeSchema(variables) {
         const data = await this.gql.request(GameModelTypeSchemaDocument, variables);
         return data.gameModelTypeSchema;

package/dist/domains/platform.d.ts

@@ -1,33 +1,49 @@
+import type { GraphQLClient } from '../client.js';
 /**
- * Platform discovery sub-client. Targets `cks-management-api`. Lets a client
- * find the shared game-api URL (for apps published to the shared environment)
- * BEFORE it has a per-app endpoint, then build a game-api `CrowdyClient`
- * against it.
- *
- * Typical pattern:
- *
- *   const base = createCrowdyClient({ managementUrl: 'https://api.example.com' });
- *   const cfg = await base.platform.config();
- *   const gameClient = createCrowdyClient({
- *     managementUrl: 'https://api.example.com',
- *     httpUrl: cfg.sharedGameApiUrl ?? undefined,
- *     wsUrl: cfg.sharedGameApiWsUrl ?? undefined,
- *     tokenStore: base.session.tokenStore,
- *   });
+ * Public platform discovery returned by {@link PlatformAPI.config}: how SDKs
+ * find the shared game-api so they can route apps deployed to the shared
+ * environment. All fields are public (no auth required to read them).
  */
-import type { GraphQLClient } from '../client.js';
 export interface PlatformConfig {
-    /** Shared game-api HTTP/GraphQL root for shared-environment apps. */
+    /** Shared game-api HTTP/GraphQL root for shared-environment apps; `null` if unset. */
     sharedGameApiUrl: string | null;
-    /** Shared game-api WebSocket root (subscriptions / UDP proxy). */
+    /** Shared game-api WebSocket root (subscriptions / UDP proxy); `null` if unset. */
     sharedGameApiWsUrl: string | null;
-    /** Free shared app slots an org gets before a paid subscription. */
+    /** Free shared app slots an org gets before a paid subscription is required. */
     freeAppsPerOrg: number;
 }
+/**
+ * Public platform discovery — exposed as `client.platform`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`).
+ * **Public**: no authentication required. Lets a client discover the shared
+ * game-api URL (for apps published to the shared environment) *before* it has a
+ * per-app endpoint, then build a game-api `CrowdyClient` against it.
+ *
+ * @example
+ * ```ts
+ * const base = createCrowdyClient({ managementUrl: 'https://api.example.com' });
+ * const cfg = await base.platform.config();
+ * const gameClient = createCrowdyClient({
+ *   managementUrl: 'https://api.example.com',
+ *   httpUrl: cfg.sharedGameApiUrl ?? undefined,
+ *   wsUrl: cfg.sharedGameApiWsUrl ?? undefined,
+ *   tokenStore: base.session.tokenStore,
+ * });
+ * ```
+ */
 export declare class PlatformAPI {
     private readonly management;
     constructor(management: GraphQLClient);
-    /** Fetch public platform discovery (shared game-api URL, free app quota). */
+    /**
+     * Fetch public platform discovery: the shared game-api URL clients use for
+     * shared-environment apps, plus the free shared-app quota. **Public** — no
+     * authentication required.
+     *
+     * @returns A {@link PlatformConfig} (`sharedGameApiUrl`, `sharedGameApiWsUrl`,
+     *   and `freeAppsPerOrg`).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
     config(): Promise<PlatformConfig>;
 }
 //# sourceMappingURL=platform.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/domains/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;CACxB;AAiBD,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,aAAa;IAEtD,6EAA6E;IACvE,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;CAIxC"}
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/domains/platform.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mFAAmF;IACnF,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,gFAAgF;IAChF,cAAc,EAAE,MAAM,CAAC;CACxB;AAiBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,aAAa;IAEtD;;;;;;;;OAQG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;CAIxC"}

package/dist/domains/platform.js

@@ -1,20 +1,3 @@
-/**
- * Platform discovery sub-client. Targets `cks-management-api`. Lets a client
- * find the shared game-api URL (for apps published to the shared environment)
- * BEFORE it has a per-app endpoint, then build a game-api `CrowdyClient`
- * against it.
- *
- * Typical pattern:
- *
- *   const base = createCrowdyClient({ managementUrl: 'https://api.example.com' });
- *   const cfg = await base.platform.config();
- *   const gameClient = createCrowdyClient({
- *     managementUrl: 'https://api.example.com',
- *     httpUrl: cfg.sharedGameApiUrl ?? undefined,
- *     wsUrl: cfg.sharedGameApiWsUrl ?? undefined,
- *     tokenStore: base.session.tokenStore,
- *   });
- */
 import { parse } from 'graphql';
 // Hand-written document so the SDK can discover the shared game-api URL even
 // before codegen picks up the new schema (see src/operations/platform/).
@@ -27,11 +10,39 @@ const PlatformConfigDocument = parse(/* GraphQL */ `
     }
   }
 `);
+/**
+ * Public platform discovery — exposed as `client.platform`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`).
+ * **Public**: no authentication required. Lets a client discover the shared
+ * game-api URL (for apps published to the shared environment) *before* it has a
+ * per-app endpoint, then build a game-api `CrowdyClient` against it.
+ *
+ * @example
+ * ```ts
+ * const base = createCrowdyClient({ managementUrl: 'https://api.example.com' });
+ * const cfg = await base.platform.config();
+ * const gameClient = createCrowdyClient({
+ *   managementUrl: 'https://api.example.com',
+ *   httpUrl: cfg.sharedGameApiUrl ?? undefined,
+ *   wsUrl: cfg.sharedGameApiWsUrl ?? undefined,
+ *   tokenStore: base.session.tokenStore,
+ * });
+ * ```
+ */
 export class PlatformAPI {
     constructor(management) {
         this.management = management;
     }
-    /** Fetch public platform discovery (shared game-api URL, free app quota). */
+    /**
+     * Fetch public platform discovery: the shared game-api URL clients use for
+     * shared-environment apps, plus the free shared-app quota. **Public** — no
+     * authentication required.
+     *
+     * @returns A {@link PlatformConfig} (`sharedGameApiUrl`, `sharedGameApiWsUrl`,
+     *   and `freeAppsPerOrg`).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
     async config() {
         const data = await this.management.request(PlatformConfigDocument, {});
         return data.platformConfig;