@crowdedkingdoms/crowdyjs 8.4.3 → 8.4.5

package/README.md

@@ -12,38 +12,30 @@ 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`). 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 (v0.13.11+); older servers reject queries/mutations that include them (omit the fields and everything else keeps working). The **permission-read** surface (the `has_grid_permission`/`grid_at`/`has_chunk_permission` expression builtins the kit's `chunkPermission` locks compile to, and selector `*PermissionWhere` predicates) additionally requires `cks-game-api` **v0.13.12+**.
+> **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 (v0.13.11+); older servers reject queries/mutations that include them (omit the fields and everything else keeps working). The **permission-read** surface (the `has_grid_permission`/`grid_at`/`has_chunk_permission` expression builtins the kit's `chunkPermission` locks compile to, and selector `*PermissionWhere` predicates) additionally requires `cks-game-api` **v0.13.12+**. Older `cks-game-api` builds report game-model **invoke policy denials** as `FORBIDDEN` GraphQL errors instead of resolving with `success: false`; as of this version the kit's invoke helpers map that error onto the documented `{ success: false, errorMessage }` result, so kit callers behave identically against both server generations.
 
 ## Standalone builds and schema refresh
 
-CrowdyJS is a standalone public package. A clean external clone must be able to
-run `npm install && npm run build` without sibling CKS API repos checked out.
-For that reason the build uses committed schema artifacts in this repo:
+CrowdyJS is a standalone public package: a clean clone builds with
+`npm install && npm run build` using the schema artifacts committed to this
+repo — no other repositories and no network access required:
 
 - `schema.gql` — merged Management API + Game API SDL.
 - `src/generated/graphql.ts` — generated TypeScript operation types.
 
-Schema refresh is explicit:
+Schema refresh (maintainers) is explicit, from the published SDLs
+([management-api.graphql](https://docs.crowdedkingdoms.com/schema/management-api.graphql),
+[game-api.graphql](https://docs.crowdedkingdoms.com/schema/game-api.graphql)):
 
 ```bash
-# Refresh from the published production SDLs.
 npm run schema:sync:prod
 npm run codegen
-
-# Or, inside the CKS wrapper repo, refresh from local API checkouts.
-npm run schema:sync:local
-npm run codegen
-
-# Or use exact file/URL sources.
-npm run schema:sync:paths -- \
-  --management ../cks-management-api/schema.gql \
-  --game ../cks-game-api/schema.gql
-npm run codegen
 ```
 
-Commit `schema.gql` and `src/generated/graphql.ts` together whenever the public
-GraphQL surface changes. Do not make `npm run build` depend on local API repos or
-network access; use `npm run check:schema` in CI/release work to detect drift.
+(`npm run schema:sync:paths -- --management <file-or-url> --game <file-or-url>`
+accepts explicit sources.) Commit `schema.gql` and `src/generated/graphql.ts`
+together whenever the public GraphQL surface changes; `npm run check:schema`
+detects drift in CI/release work.
 
 ## Quick start
 

package/dist/index.d.ts

@@ -45,7 +45,7 @@
  * or internal tooling, never an untrusted browser.
  */
 /** The published package version. Mirrors `package.json`. */
-export declare const VERSION = "8.4.3";
+export declare const VERSION = "8.4.4";
 export { LbCookieStore } from './lb-cookie-store.js';
 export { CrowdyClient, createCrowdyClient, type CrowdyClientConfig, } from './crowdy-client.js';
 export { BrowserLocalStorageTokenStore, SessionStore, type SessionListener, type TokenStore, } from './session.js';

package/dist/index.js

@@ -45,7 +45,7 @@
  * or internal tooling, never an untrusted browser.
  */
 /** The published package version. Mirrors `package.json`. */
-export const VERSION = '8.4.3';
+export const VERSION = '8.4.4';
 export { LbCookieStore } from './lb-cookie-store.js';
 export { CrowdyClient, createCrowdyClient, } from './crowdy-client.js';
 export { BrowserLocalStorageTokenStore, SessionStore, } from './session.js';

package/dist/kit/shared.d.ts

@@ -6,6 +6,12 @@ export type RawInvokeResult = GameModelInvokeMutation['gameModelInvoke'];
  * A kit invoke outcome: the server's authority/evaluation verdict plus the
  * parsed return value. Authority denials and expression errors are **not**
  * exceptions — check {@link success}.
+ *
+ * Older `cks-game-api` builds violate that contract for policy denials: they
+ * throw a GraphQL error with `extensions.code === 'FORBIDDEN'` instead of
+ * resolving with `success: false`. {@link kitInvoke} tolerates both server
+ * generations by mapping that error onto a denial result — see {@link raw}
+ * for how to recognize the mapped case.
  */
 export interface KitInvokeResult<T = unknown> {
     /** `false` when the invoke policy denied the caller or the logic errored (rolled back). */
@@ -14,12 +20,29 @@ export interface KitInvokeResult<T = unknown> {
     returnValue?: T;
     /** The server's error message when `success` is false. */
     errorMessage?: string;
-    /** The full server result (event id, applied mutations, …). */
+    /**
+     * The full server result (event id, applied mutations, …).
+     *
+     * When an older server reported a policy denial as a `FORBIDDEN` GraphQL
+     * error (see the interface doc above), no server result exists; the SDK
+     * synthesizes a minimal one — `success: false`, `errorMessage` from the
+     * GraphQL error, `eventId: ''`, and no applied mutations.
+     */
     raw: RawInvokeResult;
 }
 /** Wrap a raw invoke result, parsing the JSON return value. */
 export declare function toKitInvokeResult<T>(raw: RawInvokeResult): KitInvokeResult<T>;
-/** Invoke a model function and wrap the result. */
+/**
+ * Invoke a model function and wrap the result.
+ *
+ * Server-generation tolerance: current `cks-game-api` builds resolve policy
+ * denials with `success: false` (the kit contract), but older builds throw a
+ * {@link CrowdyGraphQLError} with `extensions.code === 'FORBIDDEN'` instead.
+ * This helper catches that specific error and maps it to a
+ * `{ success: false, errorMessage }` result with a synthesized {@link
+ * KitInvokeResult.raw}, so kit callers see one contract against both server
+ * generations. Any other error is rethrown unchanged.
+ */
 export declare function kitInvoke<T = unknown>(gameModel: GameModelAPI, input: {
     appId: string;
     functionName: string;

package/dist/kit/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/kit/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,2FAA2F;IAC3F,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,GAAG,EAAE,eAAe,CAAC;CACtB;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,CAAC,CAAC,CAe7E;AAED,mDAAmD;AACnD,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE;IACL,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAS7B;AAED,gEAAgE;AAChE,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAOlC"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/kit/shared.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,2FAA2F;IAC3F,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,GAAG,EAAE,eAAe,CAAC;CACtB;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,CAAC,CAAC,CAe7E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE;IACL,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CA6B7B;AAED,gEAAgE;AAChE,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAOlC"}

package/dist/kit/shared.js

@@ -1,3 +1,4 @@
+import { CrowdyGraphQLError } from '../errors.js';
 /** Wrap a raw invoke result, parsing the JSON return value. */
 export function toKitInvokeResult(raw) {
     let returnValue;
@@ -16,15 +17,46 @@ export function toKitInvokeResult(raw) {
         raw,
     };
 }
-/** Invoke a model function and wrap the result. */
+/**
+ * Invoke a model function and wrap the result.
+ *
+ * Server-generation tolerance: current `cks-game-api` builds resolve policy
+ * denials with `success: false` (the kit contract), but older builds throw a
+ * {@link CrowdyGraphQLError} with `extensions.code === 'FORBIDDEN'` instead.
+ * This helper catches that specific error and maps it to a
+ * `{ success: false, errorMessage }` result with a synthesized {@link
+ * KitInvokeResult.raw}, so kit callers see one contract against both server
+ * generations. Any other error is rethrown unchanged.
+ */
 export async function kitInvoke(gameModel, input) {
-    const raw = await gameModel.invoke({
-        appId: input.appId,
-        functionName: input.functionName,
-        selfContainerId: input.selfContainerId,
-        paramsJson: JSON.stringify(input.params ?? {}),
-        ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
-    });
+    let raw;
+    try {
+        raw = await gameModel.invoke({
+            appId: input.appId,
+            functionName: input.functionName,
+            selfContainerId: input.selfContainerId,
+            paramsJson: JSON.stringify(input.params ?? {}),
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof CrowdyGraphQLError && error.code === 'FORBIDDEN') {
+            return {
+                success: false,
+                returnValue: undefined,
+                errorMessage: error.message,
+                raw: {
+                    eventId: '',
+                    functionName: input.functionName,
+                    success: false,
+                    returnValueJson: null,
+                    errorMessage: error.message,
+                    mutationsApplied: [],
+                },
+            };
+        }
+        throw error;
+    }
     return toKitInvokeResult(raw);
 }
 /** Read a container's visible properties as a parsed object. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/crowdyjs",
-  "version": "8.4.3",
+  "version": "8.4.5",
   "description": "Client SDK for Crowded Kingdoms GraphQL API with UDP proxy support",
   "type": "module",
   "main": "dist/index.js",