@crowdedkingdomstudios/crowdyjs 5.1.0 → 5.2.1

package/dist/domains/gameModel.d.ts

@@ -1,40 +1,446 @@
 import type { GraphQLClient } from '../client.js';
 import { type GameModelCreateSessionMutation, type GameModelCreateSessionMutationVariables, type GameModelJoinSessionMutation, type GameModelJoinSessionMutationVariables, type GameModelSetSessionTurnMutation, type GameModelSetSessionTurnMutationVariables, type GameModelCreateContainerMutation, type GameModelCreateContainerMutationVariables, type GameModelSetPropertyMutation, type GameModelSetPropertyMutationVariables, type GameModelAddEdgeMutation, type GameModelAddEdgeMutationVariables, type GameModelInvokeMutation, type GameModelInvokeMutationVariables, type GameModelContainerQuery, type GameModelContainerQueryVariables, type GameModelContainersQuery, type GameModelContainersQueryVariables, type GameModelContainerStateQuery, type GameModelContainerStateQueryVariables, type GameModelTraverseQuery, type GameModelTraverseQueryVariables, type GameModelSessionQuery, type GameModelSessionQueryVariables, type GameModelSessionsQuery, type GameModelSessionsQueryVariables, type GameModelEventsQuery, type GameModelEventsQueryVariables, type GameModelSeedMutation, type GameModelSeedMutationVariables, type GameModelUpsertContainerTypeMutation, type GameModelUpsertContainerTypeMutationVariables, type GameModelUpsertPropertyDefMutation, type GameModelUpsertPropertyDefMutationVariables, type GameModelUpsertFunctionMutation, type GameModelUpsertFunctionMutationVariables, type GameModelDeleteFunctionMutation, type GameModelDeleteFunctionMutationVariables, type GameModelDefineFeatureMutation, type GameModelDefineFeatureMutationVariables, type GameModelGrantTierFeatureMutation, type GameModelGrantTierFeatureMutationVariables, type GameModelSetPolicyMutation, type GameModelSetPolicyMutationVariables, type GameModelTypeSchemaQuery, type GameModelTypeSchemaQueryVariables } 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 declare class GameModelAPI {
     private gql;
     constructor(gql: GraphQLClient);
+    /**
+     * **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.
+     */
     createSession(input: GameModelCreateSessionMutationVariables['input']): Promise<GameModelCreateSessionMutation['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.
+     */
     joinSession(input: GameModelJoinSessionMutationVariables['input']): Promise<GameModelJoinSessionMutation['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.
+     */
     setSessionTurn(input: GameModelSetSessionTurnMutationVariables['input']): Promise<GameModelSetSessionTurnMutation['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.
+     */
     createContainer(input: GameModelCreateContainerMutationVariables['input']): Promise<GameModelCreateContainerMutation['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.
+     */
     setProperty(input: GameModelSetPropertyMutationVariables['input']): Promise<GameModelSetPropertyMutation['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`.
+     */
     addEdge(input: GameModelAddEdgeMutationVariables['input']): Promise<GameModelAddEdgeMutation['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.)
+     */
     invoke(input: GameModelInvokeMutationVariables['input']): Promise<GameModelInvokeMutation['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.
+     */
     container(variables: GameModelContainerQueryVariables): Promise<GameModelContainerQuery['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`.
+     */
     containers(variables: GameModelContainersQueryVariables): Promise<GameModelContainersQuery['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.
+     */
     containerState(variables: GameModelContainerStateQueryVariables): Promise<GameModelContainerStateQuery['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.
+     */
     traverse(variables: GameModelTraverseQueryVariables): Promise<GameModelTraverseQuery['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.
+     */
     session(variables: GameModelSessionQueryVariables): Promise<GameModelSessionQuery['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`.
+     */
     sessions(variables: GameModelSessionsQueryVariables): Promise<GameModelSessionsQuery['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.
+     */
     events(variables: GameModelEventsQueryVariables): Promise<GameModelEventsQuery['gameModelEvents']>;
+    /**
+     * **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.
+     */
     seed(input: GameModelSeedMutationVariables['input']): Promise<GameModelSeedMutation['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`.
+     */
     upsertContainerType(input: GameModelUpsertContainerTypeMutationVariables['input']): Promise<GameModelUpsertContainerTypeMutation['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`.
+     */
     upsertPropertyDef(input: GameModelUpsertPropertyDefMutationVariables['input']): Promise<GameModelUpsertPropertyDefMutation['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.
+     */
     upsertFunction(input: GameModelUpsertFunctionMutationVariables['input']): Promise<GameModelUpsertFunctionMutation['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.
+     */
     deleteFunction(variables: GameModelDeleteFunctionMutationVariables): Promise<GameModelDeleteFunctionMutation['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`.
+     */
     defineFeature(input: GameModelDefineFeatureMutationVariables['input']): Promise<GameModelDefineFeatureMutation['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.
+     */
     grantTierFeature(input: GameModelGrantTierFeatureMutationVariables['input']): Promise<GameModelGrantTierFeatureMutation['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`.
+     */
     setPolicy(input: GameModelSetPolicyMutationVariables['input']): Promise<GameModelSetPolicyMutation['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.
+     */
     typeSchema(variables: GameModelTypeSchemaQueryVariables): Promise<GameModelTypeSchemaQuery['gameModelTypeSchema']>;
 }
 //# sourceMappingURL=gameModel.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"gameModel.d.ts","sourceRoot":"","sources":["../../src/domains/gameModel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gameModel.d.ts","sourceRoot":"","sources":["../../src/domains/gameModel.ts"],"names":[],"mappings":"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"}