@crowdedkingdoms/crowdyjs 8.0.1 → 8.1.0

package/README.md

@@ -12,7 +12,7 @@ npm install @crowdedkingdoms/crowdyjs
 
 CrowdyJS v4 targets browsers by default and uses native `fetch`, `WebSocket`, `crypto`, `btoa`, and `atob`. Node tools can still use the SDK, but must provide browser-compatible globals when opening realtime connections.
 
-> **Server compatibility:** v5.2+ targets environments on release **v0.1.19 or later** (`cks-game-api >= v0.10.3`, `cks-management-api >= v0.1.70`). The destructive mutations send an `idempotencyKey` argument that older servers don't define. v6.1's `client.gameApps.deleteGrid` additionally requires release **v0.1.33+** (`cks-game-api >= v0.12.3`).
+> **Server compatibility:** v5.2+ targets environments on release **v0.1.19 or later** (`cks-game-api >= v0.10.3`, `cks-management-api >= v0.1.70`). The destructive mutations send an `idempotencyKey` argument that older servers don't define. v6.1's `client.gameApps.deleteGrid` additionally requires release **v0.1.33+** (`cks-game-api >= v0.12.3`). The game-model **permission effects** fields (`permissionEffects` on `gameModel.upsertFunction`/`seed`, `permissionEffectsAppliedJson` on events) require a `cks-game-api` build with the `2026-07-17-model-permission-effects` migration; older servers reject queries/mutations that include them (omit the fields and everything else keeps working).
 
 ## Standalone builds and schema refresh
 
@@ -106,6 +106,7 @@ If `managementUrl` is omitted, the SDK falls back to `httpUrl` for backwards-com
 | `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, `sendClientEvent`). |
 | `client.realtime` | Connection status, manual `connect()` / `disconnect()`, `onStatus()` listener. |
 | `client.world(appId)` | Higher-level helpers for browser games (`actor.join`, `actor.sendState`, `actor.sendText`). |
+| `client.kit(appId)` | Game Kit: ready-made mappings of game concepts onto the game model — `kit.inventory`, `kit.objects` (lockable doors/chests with custom permissions), `kit.npcs`, plus blueprint builders + `kit.deploy(...)` for the admin "load the rules" step. |
 
 **Studio-admin surface** (privileged; drive with a server-side / studio token, grouped under `client.admin`):
 
@@ -268,6 +269,45 @@ await actor.sendToActor(
 
 The world helpers are thin wrappers over `client.udp.*` with the appId pre-bound — convenient for browser games. Advanced callers can always use `client.udp.*` with the generated GraphQL input types directly.
 
+## Game Kit
+
+`client.kit(appId)` maps traditional game concepts onto the abstract game
+model + automations API. Studios **deploy blueprints** (the admin "load the
+state/rules" step, requires `manage_apps`); game clients then use the typed
+runtime helpers. Everything composes `client.gameModel` — no new server
+surface.
+
+```ts
+// Studio setup (admin context):
+import { inventoryBlueprint, lockBlueprint, npcBlueprint } from '@crowdedkingdoms/crowdyjs';
+
+await admin.kit(appId).deploy([
+  inventoryBlueprint(),
+  lockBlueprint({ objectTypeName: 'Door', authority: { kind: 'key' } }),
+  npcBlueprint({
+    behaviors: [{
+      name: 'npc-wander',
+      role: 'wanderer',
+      trigger: { intervalMs: 60000 },
+      mutations: [
+        { target: 'self', property: 'x', expression: 'self.x + rand_int(-2, 2)' },
+        { target: 'self', property: 'z', expression: 'self.z + rand_int(-2, 2)' },
+      ],
+    }],
+  }),
+]);
+
+// Game client (player token):
+const kit = game.kit(appId);
+const bag = await kit.inventory.ensure(me.userId);
+const result = await kit.objects.open(doorId, { keyId });
+if (!result.success) console.warn('locked:', result.errorMessage);
+```
+
+See the docs guides [Modeling game concepts](https://docs.crowdedkingdoms.com/game-api/modeling-game-concepts)
+(the underlying model) and [Game Kit](https://docs.crowdedkingdoms.com/crowdyjs/game-kit)
+(the SDK surface).
+
 ## Errors
 
 Transport and protocol failures throw structured error classes:

package/dist/crowdy-client.d.ts

@@ -27,6 +27,7 @@ import { SubscriptionManager } from './subscriptions.js';
 import type { CrowdyLogger } from './logger.js';
 import type { TokenStore } from './session.js';
 import { WorldClient } from './world.js';
+import { GameKitClient, type GameKitOptions } from './kit/index.js';
 import { AuthAPI } from './domains/auth.js';
 import { UsersAPI } from './domains/users.js';
 import { AppsAPI } from './domains/apps.js';
@@ -196,6 +197,20 @@ export declare class CrowdyClient {
      * @param appId - The app to scope realtime traffic to (BigInt as a decimal string).
      */
     world(appId: string): WorldClient;
+    /**
+     * App-scoped **Game Kit** facade over `client.gameModel`: high-level
+     * building blocks that map traditional game concepts onto Game Models +
+     * Automations — `kit.inventory` (bags/item stacks), `kit.objects` (lockable
+     * doors/chests with custom permissions), `kit.npcs` (server-driven NPCs),
+     * and the studio-side `kit.deploy(blueprints)` that loads the matching
+     * rules/state into the app (requires `manage_apps`). See
+     * {@link GameKitClient} and the "CrowdyJS → Game Kit" docs guide.
+     *
+     * @param appId - The app to scope model calls to (BigInt as a decimal string).
+     * @param options - Optional per-helper config when your blueprints use
+     *   non-default type names/prefixes.
+     */
+    kit(appId: string, options?: GameKitOptions): GameKitClient;
     /** Closes the WebSocket and clears the in-memory auth token. */
     close(): void;
 }

package/dist/crowdy-client.d.ts.map

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

package/dist/crowdy-client.js

@@ -25,6 +25,7 @@ import { GraphQLClient } from './client.js';
 import { LbCookieStore } from './lb-cookie-store.js';
 import { SubscriptionManager } from './subscriptions.js';
 import { WorldClient } from './world.js';
+import { GameKitClient } from './kit/index.js';
 import { AuthAPI } from './domains/auth.js';
 import { UsersAPI } from './domains/users.js';
 import { AppsAPI } from './domains/apps.js';
@@ -140,6 +141,22 @@ export class CrowdyClient {
     world(appId) {
         return new WorldClient(appId, this.udp);
     }
+    /**
+     * App-scoped **Game Kit** facade over `client.gameModel`: high-level
+     * building blocks that map traditional game concepts onto Game Models +
+     * Automations — `kit.inventory` (bags/item stacks), `kit.objects` (lockable
+     * doors/chests with custom permissions), `kit.npcs` (server-driven NPCs),
+     * and the studio-side `kit.deploy(blueprints)` that loads the matching
+     * rules/state into the app (requires `manage_apps`). See
+     * {@link GameKitClient} and the "CrowdyJS → Game Kit" docs guide.
+     *
+     * @param appId - The app to scope model calls to (BigInt as a decimal string).
+     * @param options - Optional per-helper config when your blueprints use
+     *   non-default type names/prefixes.
+     */
+    kit(appId, options) {
+        return new GameKitClient(appId, this.gameModel, options);
+    }
     /** Closes the WebSocket and clears the in-memory auth token. */
     close() {
         this.realtime.close();

package/dist/generated/graphql.d.ts

@@ -2039,6 +2039,19 @@ export type FunctionParamInput = {
     /** int | float | string | bool | array | object | container_ref */
     valueType: Scalars['String']['input'];
 };
+/** A declarative grid-permission effect the function applies TRANSACTIONALLY with its property mutations: grant or revoke runtime grid permissions (the same ACL Buddy enforces on movement/voxel writes) driven by game logic. Expressions are compiled server-side and evaluated in the invocation context (params plus the injected $caller_user_id / $self_owner_id / $session_id / $current_turn_user_id). If an effect fails, the whole invocation rolls back. Applied effects are recorded on the invocation event. */
+export type FunctionPermissionEffectInput = {
+    /** 'grant' (upsert direct grants, optionally expiring) or 'revoke' (delete direct grants for the listed keys). */
+    action: Scalars['String']['input'];
+    /** Expression resolving the grid id (int) the permissions apply to, e.g. "self.grid_id". The grid must belong to the app. */
+    gridIdExpression: Scalars['String']['input'];
+    /** Runtime permission keys to grant/revoke (validated against the runtime_permissions catalog, e.g. 'access', 'teleport', 'update_voxel_data', 'use_voice_chat'). */
+    permissionKeys: Array<Scalars['String']['input']>;
+    /** Grant only: optional expression resolving a TTL in seconds (int > 0) after which the grant expires (rentals/leases), e.g. '86400'. Omit for a non-expiring grant. */
+    ttlSecondsExpression?: InputMaybe<Scalars['String']['input']>;
+    /** Expression resolving the target user id (int), e.g. "$caller_user_id" or "self.owner_user_id". */
+    userExpression: Scalars['String']['input'];
+};
 /** Startup contract for browser game clients. Fetch this after login to initialize protocol/version checks and UDP proxy state in one round trip. */
 export type GameClientBootstrap = {
     __typename?: 'GameClientBootstrap';
@@ -2454,6 +2467,8 @@ export type GmEvent = {
     mutationsAppliedJson: Scalars['String']['output'];
     /** JSON object of params. */
     paramsJson: Scalars['String']['output'];
+    /** JSON array of grid-permission effects this invocation applied (audit trail for model-driven grants/revokes): [{ action, permission_keys, user_id, grid_id, expires_at }]. */
+    permissionEffectsAppliedJson: Scalars['String']['output'];
     /** JSON-encoded return value. */
     returnValueJson: Maybe<Scalars['String']['output']>;
     /** The self container id the function ran against. */
@@ -2496,6 +2511,8 @@ export type GmFunction = {
     notifications: Array<GmFunctionNotification>;
     /** Typed parameters the function accepts. */
     parameters: Array<GmFunctionParam>;
+    /** Declarative grid-permission effects (grant/revoke runtime grid ACL rows) applied atomically with the function's mutations. */
+    permissionEffects: Array<GmFunctionPermissionEffect>;
     /** Optional expression whose value becomes the invoke result. */
     returnExpression: Maybe<Scalars['String']['output']>;
     /** Optional declared return value type. */
@@ -2539,6 +2556,20 @@ export type GmFunctionParam = {
     /** Value type: int | float | string | bool | array | object | container_ref. */
     valueType: Scalars['String']['output'];
 };
+/** A declarative grid-permission effect applied transactionally with the function's mutations: grant or revoke runtime grid permissions (the ACL Buddy enforces) driven by game logic. */
+export type GmFunctionPermissionEffect = {
+    __typename?: 'GmFunctionPermissionEffect';
+    /** 'grant' or 'revoke'. */
+    action: Scalars['String']['output'];
+    /** The expression (source) resolving the grid id. */
+    gridIdExpression: Scalars['String']['output'];
+    /** Runtime permission keys granted/revoked. */
+    permissionKeys: Array<Scalars['String']['output']>;
+    /** Grant only: optional expression resolving a TTL in seconds. */
+    ttlSecondsExpression: Maybe<Scalars['String']['output']>;
+    /** The expression (source) resolving the target user id. */
+    userExpression: Scalars['String']['output'];
+};
 /** The outcome of a gameModelInvoke call (return value, applied writes, and any error). */
 export type GmInvokeResult = {
     __typename?: 'GmInvokeResult';
@@ -5287,6 +5318,8 @@ export type SeedFunctionInput = {
     notifications?: InputMaybe<Array<FunctionNotificationInput>>;
     /** Typed parameters the function accepts. */
     parameters?: InputMaybe<Array<FunctionParamInput>>;
+    /** Declarative grid-permission effects (grant/revoke runtime grid ACL rows) applied atomically with the function's mutations. Max 4 per function. */
+    permissionEffects?: InputMaybe<Array<FunctionPermissionEffectInput>>;
     /** Optional expression whose value becomes the invoke result. */
     returnExpression?: InputMaybe<Scalars['String']['input']>;
     /** Optional declared return value type. */
@@ -6062,6 +6095,8 @@ export type UpsertFunctionInput = {
     notifications?: InputMaybe<Array<FunctionNotificationInput>>;
     /** Typed parameters the function accepts. */
     parameters?: InputMaybe<Array<FunctionParamInput>>;
+    /** Declarative grid-permission effects (grant/revoke runtime grid ACL rows) applied atomically with the function's mutations. Max 4 per function. */
+    permissionEffects?: InputMaybe<Array<FunctionPermissionEffectInput>>;
     /** Optional expression whose value becomes the invoke result. */
     returnExpression?: InputMaybe<Scalars['String']['input']>;
     /** Optional declared return value type. */
@@ -9647,6 +9682,7 @@ export type GameModelEventsQuery = {
         automationId: string | null;
         paramsJson: string;
         mutationsAppliedJson: string;
+        permissionEffectsAppliedJson: string;
         returnValueJson: string | null;
         success: boolean;
         errorMessage: string | null;
@@ -9681,6 +9717,7 @@ export type GameModelEventsConnectionQuery = {
                 automationId: string | null;
                 paramsJson: string;
                 mutationsAppliedJson: string;
+                permissionEffectsAppliedJson: string;
                 returnValueJson: string | null;
                 success: boolean;
                 errorMessage: string | null;
@@ -9734,6 +9771,14 @@ export type GmFunctionFieldsFragment = {
             expression: string;
         }>;
     }>;
+    permissionEffects: Array<{
+        __typename?: 'GmFunctionPermissionEffect';
+        action: string;
+        permissionKeys: Array<string>;
+        userExpression: string;
+        gridIdExpression: string;
+        ttlSecondsExpression: string | null;
+    }>;
 };
 export type GmPropertyDefFieldsFragment = {
     __typename?: 'GmPropertyDef';
@@ -9855,6 +9900,14 @@ export type GameModelUpsertFunctionMutation = {
                 expression: string;
             }>;
         }>;
+        permissionEffects: Array<{
+            __typename?: 'GmFunctionPermissionEffect';
+            action: string;
+            permissionKeys: Array<string>;
+            userExpression: string;
+            gridIdExpression: string;
+            ttlSecondsExpression: string | null;
+        }>;
     };
 };
 export type GameModelDeleteFunctionMutationVariables = Exact<{
@@ -9959,6 +10012,14 @@ export type GameModelTypeSchemaQuery = {
                     expression: string;
                 }>;
             }>;
+            permissionEffects: Array<{
+                __typename?: 'GmFunctionPermissionEffect';
+                action: string;
+                permissionKeys: Array<string>;
+                userExpression: string;
+                gridIdExpression: string;
+                ttlSecondsExpression: string | null;
+            }>;
         }>;
     };
 };
@@ -10040,6 +10101,14 @@ export type GameModelFunctionQuery = {
                 expression: string;
             }>;
         }>;
+        permissionEffects: Array<{
+            __typename?: 'GmFunctionPermissionEffect';
+            action: string;
+            permissionKeys: Array<string>;
+            userExpression: string;
+            gridIdExpression: string;
+            ttlSecondsExpression: string | null;
+        }>;
     };
 };
 export type GameModelFunctionsQueryVariables = Exact<{
@@ -10086,6 +10155,14 @@ export type GameModelFunctionsQuery = {
                 expression: string;
             }>;
         }>;
+        permissionEffects: Array<{
+            __typename?: 'GmFunctionPermissionEffect';
+            action: string;
+            permissionKeys: Array<string>;
+            userExpression: string;
+            gridIdExpression: string;
+            ttlSecondsExpression: string | null;
+        }>;
     }>;
 };
 export type GameModelFeaturesQueryVariables = Exact<{