@crowdedkingdoms/crowdyjs 14.0.0 → 14.2.0-dev.1

package/dist/domains/usage.d.ts

@@ -9,7 +9,7 @@ import { type AppGraphqlOperationsQuery, type AppUsageSummaryQuery, type PlayerP
  * counters are returned as string counters because they can exceed the 32-bit
  * Int range. `BigInt` ids are decimal strings.
  *
- * As of the unified galaxy API the per-environment rollups
+ * As of the v13 unified API the per-environment rollups
  * (environmentSummary/orgByEnvironment/environmentByApp) were retired with
  * dedicated customer environments — usage is org/app-scoped.
  *

package/dist/domains/usage.js

@@ -8,7 +8,7 @@ import { AppGraphqlOperationsDocument, AppUsageSummaryDocument, PlayerPulseDocum
  * counters are returned as string counters because they can exceed the 32-bit
  * Int range. `BigInt` ids are decimal strings.
  *
- * As of the unified galaxy API the per-environment rollups
+ * As of the v13 unified API the per-environment rollups
  * (environmentSummary/orgByEnvironment/environmentByApp) were retired with
  * dedicated customer environments — usage is org/app-scoped.
  *

package/dist/errors.d.ts

@@ -102,6 +102,149 @@ export declare class CrowdyGraphQLError extends CrowdyError {
      */
     get extensions(): Record<string, unknown> | undefined;
 }
+/**
+ * Extension code the API uses to say "this app's datacenter is not serving".
+ *
+ * Distinct from {@link WRONG_DATACENTER_CODE}, and the distinction is the whole
+ * point: that one names an endpoint to move to, this one deliberately does not,
+ * because there is nowhere to move to.
+ */
+export declare const APP_UNAVAILABLE_CODE = "APP_UNAVAILABLE";
+/** Extension code the API uses to say "this app lives somewhere else". */
+export declare const WRONG_DATACENTER_CODE = "WRONG_DATACENTER";
+/**
+ * The app's own datacenter is not currently serving clients.
+ *
+ * WHAT MAKES THIS DIFFERENT FROM EVERY OTHER ERROR HERE: there is nothing the
+ * client, the SDK, or the player can do about it. A `WRONG_DATACENTER` is fixed
+ * by moving, an `UNAUTHENTICATED` by logging in, a `RATE_LIMITED` by waiting a
+ * measurable amount of time. This one is fixed by an operator, and the honest
+ * thing for an application to do is stop retrying in a loop and say so.
+ *
+ * {@link message} is written by the server to be shown to a player as-is: it says
+ * what is happening, that it is being worked on, and that there is nothing for
+ * them to do. Prefer it over inventing your own wording, because the server knows
+ * things the client does not — whether this is a brief drain or a whole
+ * datacenter — and its phrasing can improve without an SDK release.
+ *
+ * It carries NO endpoint, on purpose. Do not fall back to a cached one: the
+ * cached one is in the datacenter that is down.
+ *
+ * ```ts
+ * try {
+ *   await client.grids.chunk(appId, x, y, z);
+ * } catch (err) {
+ *   if (err instanceof CrowdyAppUnavailableError) {
+ *     showBanner(err.message);   // "This app is temporarily offline..."
+ *     return;                    // do not retry in a tight loop
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+export declare class CrowdyAppUnavailableError extends CrowdyGraphQLError {
+    /** The app the server refused to serve, when it named one. */
+    get appId(): string | undefined;
+    /**
+     * The datacenter that is not serving. Diagnostic only — do not show a player a
+     * datacenter code, and do not try to reach it.
+     */
+    get appDatacenter(): string | undefined;
+    /**
+     * Whether it is worth trying again later. True today for every case the server
+     * raises this for; read it rather than assuming, so a future permanent variant
+     * (an app placed in a datacenter that has been destroyed, say) can say false
+     * without the SDK changing.
+     */
+    get retryable(): boolean;
+}
+/**
+ * Whose problem a failure is, as the platform attributes it.
+ *
+ * The one question a game cannot answer for itself: from inside a client there is no way
+ * to tell "your function is too slow" from "we were busy and never ran it" from "this app
+ * is out of budget", and until the server started saying so, all three arrived as the
+ * same sentence. Presentation is still yours — this says only whose fault it was.
+ */
+export type CrowdyFaultBlame = 'PLATFORM' | 'AUTHOR' | 'BUDGET';
+/**
+ * The stable reason a call into app-authored code failed.
+ *
+ * Deliberately coarse. It never names an engine, a module, a function or a limit,
+ * because those are the app developer's business and not the player's — the developer
+ * reads the full detail in the Crowdy console. Treat it as an open union: the server may
+ * add a code, and a client that switches on it should have a default branch.
+ */
+export type CrowdyFaultCode = 'USER_CODE_ERROR' | 'USER_CODE_TOO_SLOW' | 'USER_CODE_LIMIT_EXCEEDED' | 'PLATFORM_BUSY' | 'PLATFORM_ERROR' | 'BUDGET_EXCEEDED' | 'RATE_LIMITED' | 'QUOTA_EXHAUSTED' | 'TEMPORARILY_DISABLED' | 'INVALID_REQUEST' | 'NOT_ALLOWED' | 'NOT_FOUND' | 'UNAUTHENTICATED' | 'WRONG_DATACENTER' | 'APP_UNAVAILABLE' | (string & {});
+/** What the platform says about a failure, in the only vocabulary a player is shown. */
+export interface CrowdyPlayerFault {
+    /** A stable, enumerated reason. Branch on this, never on a message. */
+    code: CrowdyFaultCode;
+    /** Whose problem it is. */
+    blame: CrowdyFaultBlame;
+    /** Whether repeating the identical call could succeed with nothing else changing. */
+    retryable: boolean;
+}
+/**
+ * A call into code the platform did not write failed, and the platform has said whose
+ * fault it was.
+ *
+ * WHY THIS EXISTS RATHER THAN A MESSAGE. Until 2026-08-11 a failure inside an app's own
+ * function reached the client as the server's internal text — `Evaluation timed out` was
+ * returned to players of every app for four days while the real cause was a platform
+ * query taking 1.2 seconds. A game rendering that string told its players their own game
+ * was broken, on the platform's behalf, in the platform's words. Nothing on the wire
+ * distinguished the three cases, so no game could have done better.
+ *
+ * Now the server attributes blame and the game decides what to render. Nothing in
+ * {@link message} is written by the app's code or by an engine; it is a platform-authored
+ * sentence, safe to show as-is, and you are expected to replace it with your own.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.compute.invoke({ appId, moduleName: 'combat', exportName: 'hit' });
+ * } catch (err) {
+ *   const fault = playerFaultOf(err);
+ *   if (!fault) throw err;
+ *   if (fault.blame === 'PLATFORM' && fault.retryable) return retryLater();
+ *   if (fault.blame === 'BUDGET') return showBanner('The arena is busy — one moment.');
+ *   return showBanner('That move did not work.');   // AUTHOR: our bug, our wording
+ * }
+ * ```
+ */
+export declare class CrowdyUserCodeFaultError extends CrowdyGraphQLError {
+    /** The platform's attribution: `{ code, blame, retryable }`. */
+    get fault(): CrowdyPlayerFault;
+    /** Whose problem this is. Shorthand for `fault.blame`. */
+    get blame(): CrowdyFaultBlame;
+    /** Whether repeating the identical call could succeed. Shorthand for `fault.retryable`. */
+    get retryable(): boolean;
+}
+/**
+ * Read the platform's attribution from EITHER carrier, so a game branches once.
+ *
+ * There are two, and the split is the server's rather than a wart of this SDK.
+ * `computeInvoke` and `playerComputeInvoke` FAIL — they throw, and the fault arrives in
+ * the GraphQL error's extensions. `gameModelInvoke` RETURNS — a denial or an evaluation
+ * failure is a gameplay verdict that still carries an event id and any writes that did
+ * apply, so it comes back as `success: false` with a `fault` field. Forcing either into
+ * the other's shape would lose something real, so this function accepts both and gives
+ * you one thing to switch on.
+ *
+ * Returns `null` when there is no fault: a successful result, or an error that is not an
+ * attributed one (a network drop, a timeout, an ordinary validation error elsewhere in
+ * the API). `null` means "this is not a question about whose code failed" — keep
+ * handling it the way you already do.
+ *
+ * @example
+ * ```ts
+ * const result = await client.gameModel.invoke({ appId, functionName, selfContainerId });
+ * const fault = playerFaultOf(result);
+ * if (fault?.retryable) scheduleRetry();
+ * ```
+ */
+export declare function playerFaultOf(value: unknown): CrowdyPlayerFault | null;
 /**
  * A network-level failure before any HTTP response was received: DNS failure,
  * TLS error, connection refused, or an aborted `fetch`. Generally retryable

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,iFAAiF;AACjF,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IACpC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,kBAAkB;CAKxC;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAKzC;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;IACjD,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,yBAAyB,EAAE,CAAC;gBAExC,MAAM,EAAE,yBAAyB,EAAE;IAK/C;;;;;;OAMG;IACH,IAAI,IAAI,IAAI,OAAO,CAElB;IAED;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEpD;CACF;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,KAAK,EAAE,OAAO;CAG3B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,SAAS,EAAE,MAAM;CAG9B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAKnG;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;CAAG"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -87,6 +87,174 @@ export class CrowdyGraphQLError extends CrowdyError {
         return this.graphqlErrors[0]?.extensions;
     }
 }
+/**
+ * Extension code the API uses to say "this app's datacenter is not serving".
+ *
+ * Distinct from {@link WRONG_DATACENTER_CODE}, and the distinction is the whole
+ * point: that one names an endpoint to move to, this one deliberately does not,
+ * because there is nowhere to move to.
+ */
+export const APP_UNAVAILABLE_CODE = 'APP_UNAVAILABLE';
+/** Extension code the API uses to say "this app lives somewhere else". */
+export const WRONG_DATACENTER_CODE = 'WRONG_DATACENTER';
+/**
+ * The app's own datacenter is not currently serving clients.
+ *
+ * WHAT MAKES THIS DIFFERENT FROM EVERY OTHER ERROR HERE: there is nothing the
+ * client, the SDK, or the player can do about it. A `WRONG_DATACENTER` is fixed
+ * by moving, an `UNAUTHENTICATED` by logging in, a `RATE_LIMITED` by waiting a
+ * measurable amount of time. This one is fixed by an operator, and the honest
+ * thing for an application to do is stop retrying in a loop and say so.
+ *
+ * {@link message} is written by the server to be shown to a player as-is: it says
+ * what is happening, that it is being worked on, and that there is nothing for
+ * them to do. Prefer it over inventing your own wording, because the server knows
+ * things the client does not — whether this is a brief drain or a whole
+ * datacenter — and its phrasing can improve without an SDK release.
+ *
+ * It carries NO endpoint, on purpose. Do not fall back to a cached one: the
+ * cached one is in the datacenter that is down.
+ *
+ * ```ts
+ * try {
+ *   await client.grids.chunk(appId, x, y, z);
+ * } catch (err) {
+ *   if (err instanceof CrowdyAppUnavailableError) {
+ *     showBanner(err.message);   // "This app is temporarily offline..."
+ *     return;                    // do not retry in a tight loop
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+export class CrowdyAppUnavailableError extends CrowdyGraphQLError {
+    /** The app the server refused to serve, when it named one. */
+    get appId() {
+        const value = this.extensions?.appId;
+        return typeof value === 'string' ? value : undefined;
+    }
+    /**
+     * The datacenter that is not serving. Diagnostic only — do not show a player a
+     * datacenter code, and do not try to reach it.
+     */
+    get appDatacenter() {
+        const value = this.extensions?.appDatacenter;
+        return typeof value === 'string' ? value : undefined;
+    }
+    /**
+     * Whether it is worth trying again later. True today for every case the server
+     * raises this for; read it rather than assuming, so a future permanent variant
+     * (an app placed in a datacenter that has been destroyed, say) can say false
+     * without the SDK changing.
+     */
+    get retryable() {
+        return this.extensions?.retryable !== false;
+    }
+}
+/**
+ * A call into code the platform did not write failed, and the platform has said whose
+ * fault it was.
+ *
+ * WHY THIS EXISTS RATHER THAN A MESSAGE. Until 2026-08-11 a failure inside an app's own
+ * function reached the client as the server's internal text — `Evaluation timed out` was
+ * returned to players of every app for four days while the real cause was a platform
+ * query taking 1.2 seconds. A game rendering that string told its players their own game
+ * was broken, on the platform's behalf, in the platform's words. Nothing on the wire
+ * distinguished the three cases, so no game could have done better.
+ *
+ * Now the server attributes blame and the game decides what to render. Nothing in
+ * {@link message} is written by the app's code or by an engine; it is a platform-authored
+ * sentence, safe to show as-is, and you are expected to replace it with your own.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.compute.invoke({ appId, moduleName: 'combat', exportName: 'hit' });
+ * } catch (err) {
+ *   const fault = playerFaultOf(err);
+ *   if (!fault) throw err;
+ *   if (fault.blame === 'PLATFORM' && fault.retryable) return retryLater();
+ *   if (fault.blame === 'BUDGET') return showBanner('The arena is busy — one moment.');
+ *   return showBanner('That move did not work.');   // AUTHOR: our bug, our wording
+ * }
+ * ```
+ */
+export class CrowdyUserCodeFaultError extends CrowdyGraphQLError {
+    /** The platform's attribution: `{ code, blame, retryable }`. */
+    get fault() {
+        const extensions = this.extensions ?? {};
+        return {
+            code: extensions.code ?? 'PLATFORM_ERROR',
+            blame: extensions.blame ?? 'PLATFORM',
+            // Absent means "we did not say", and the safe reading of that is the one that does
+            // not send a client into a loop.
+            retryable: extensions.retryable === true,
+        };
+    }
+    /** Whose problem this is. Shorthand for `fault.blame`. */
+    get blame() {
+        return this.fault.blame;
+    }
+    /** Whether repeating the identical call could succeed. Shorthand for `fault.retryable`. */
+    get retryable() {
+        return this.fault.retryable;
+    }
+}
+/** Extensions carry `blame` only for a fault the platform has attributed. */
+function faultFromExtensions(extensions) {
+    if (!extensions || typeof extensions.blame !== 'string')
+        return null;
+    return {
+        code: extensions.code ?? 'PLATFORM_ERROR',
+        blame: extensions.blame,
+        retryable: extensions.retryable === true,
+    };
+}
+/**
+ * Read the platform's attribution from EITHER carrier, so a game branches once.
+ *
+ * There are two, and the split is the server's rather than a wart of this SDK.
+ * `computeInvoke` and `playerComputeInvoke` FAIL — they throw, and the fault arrives in
+ * the GraphQL error's extensions. `gameModelInvoke` RETURNS — a denial or an evaluation
+ * failure is a gameplay verdict that still carries an event id and any writes that did
+ * apply, so it comes back as `success: false` with a `fault` field. Forcing either into
+ * the other's shape would lose something real, so this function accepts both and gives
+ * you one thing to switch on.
+ *
+ * Returns `null` when there is no fault: a successful result, or an error that is not an
+ * attributed one (a network drop, a timeout, an ordinary validation error elsewhere in
+ * the API). `null` means "this is not a question about whose code failed" — keep
+ * handling it the way you already do.
+ *
+ * @example
+ * ```ts
+ * const result = await client.gameModel.invoke({ appId, functionName, selfContainerId });
+ * const fault = playerFaultOf(result);
+ * if (fault?.retryable) scheduleRetry();
+ * ```
+ */
+export function playerFaultOf(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    if (value instanceof CrowdyGraphQLError) {
+        return faultFromExtensions(value.extensions);
+    }
+    // The in-band carrier: an invoke result that reports its own failure.
+    const result = value;
+    const fault = result.fault;
+    if (fault && typeof fault.blame === 'string') {
+        return {
+            code: fault.code ?? 'PLATFORM_ERROR',
+            blame: fault.blame,
+            retryable: fault.retryable === true,
+        };
+    }
+    // A raw GraphQL error payload, e.g. one entry pulled out of `graphqlErrors`.
+    const payload = value;
+    if (payload.extensions)
+        return faultFromExtensions(payload.extensions);
+    return null;
+}
 /**
  * A network-level failure before any HTTP response was received: DNS failure,
  * TLS error, connection refused, or an aborted `fetch`. Generally retryable