@pouchy_ai/world-sdk 0.27.0 → 0.28.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @pouchy_ai/world-sdk
 
+## 0.28.1
+
+- **`WorldApiError.errorId`** — the server's lookup reference (`err_…`) for a
+  persisted 5xx, when the envelope carried one. An uncaught world-plane fault is
+  sanitized to "An unexpected error occurred." before it leaves the server; the
+  `errorId` on that envelope is the one thing an operator can resolve to the
+  real cause, and the client read `error` / `code` / `retryAfterSec` and dropped
+  it — so a 5xx gave you `500 server_error` and nothing to quote. Additive;
+  absent on every 4xx and on a 5xx that was not persisted; string-only, like
+  `serverCode`. Quote it in a support request.
+
+## 0.28.0
+
+- **`WorldApiError.serverCode`** — the server's own machine-readable `code`
+  on a refusal, when it sent one. `code` maps the STATUS (every 409 is
+  `conflict`), and the world answers 409 for several different reasons whose
+  right response differs: `stale_deliberation` (re-run `deliberate`),
+  `episode_ended` (start the next episode), `has_instances`,
+  `episode_history_incomplete`, `story_contract_v{2,3,4}_write_disabled`. The
+  server has carried that field since those refusals were written; the client
+  read `error` into `detail` and dropped `code`, so the only thing an
+  integrator could branch on was a prose sentence that varies per site — and
+  the JSDoc on `deliberate` named a code the error never surfaced.
+- Absent when the body carries no string `code` — "the server did not say"
+  stays distinct from a conflict with no sub-reason. Additive; nothing else
+  moves.
+
 ## 0.27.0
 
 - **`WorldProgressCheckpointV1.publicFlags` / `publicFlagsTruncated`** — Story

package/README.md

@@ -249,9 +249,11 @@ an `approved` editorial can be exported.
 
 **Helpers** — `signSourceRequest` (the exact canonical the server verifies),
 `newTurnId` / `isReservedTurnId` (idempotency), `describeTurn` (read a result
-without guessing), `WorldApiError` with typed codes, `.retryable`, and
-`rejectedEffects` (which of YOUR proposed ops the world refused, and why —
-validation is all-or-nothing, so one bad op moves nothing).
+without guessing), `WorldApiError` with typed codes, `.retryable`,
+`serverCode` (the server's own `code` on a refusal — which 409, since `code`
+maps the status), `errorId` (the server's `err_…` lookup reference on a
+persisted 5xx — quote it in a support request), and `rejectedEffects` (which of YOUR proposed ops the world
+refused, and why — validation is all-or-nothing, so one bad op moves nothing).
 
 ## When a signed door refuses you
 

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  *  a project is running — which is exactly the field you reach for when a
  *  customer's integration behaves like an older SDK than they say they have.
  *  It sat at '0.1.0' for eight releases before anything compared the two. */
-export declare const WORLD_SDK_VERSION = "0.27.0";
+export declare const WORLD_SDK_VERSION = "0.28.1";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1";
 /** One direction a beat could take. The WHOLE of what a deliberation shows a
  *  player: no reasoning, no role secrets, no simulated effects, no scores. */
@@ -50,6 +50,24 @@ export declare class WorldApiError extends Error {
     readonly status: number;
     /** The server's own message, when it sent one. */
     readonly detail?: string;
+    /** The server's own machine-readable `code`, when the refusal carried one —
+     *  the field a 409 uses to say WHICH conflict, since `code` above maps a
+     *  status and every 409 is `conflict` there. `stale_deliberation` (re-run
+     *  `deliberate`), `episode_ended` (start the next episode), `has_instances`,
+     *  `episode_history_incomplete`, `story_contract_v{2,3,4}_write_disabled`
+     *  are the server's vocabulary today; a refusal that carries only prose
+     *  leaves this undefined — absent means "the server did not say", never
+     *  "no conflict". Until 0.28.0 the client read `error` into `detail` and
+     *  dropped `code` on the floor, so the one carrier an integrator could
+     *  branch on never arrived. */
+    readonly serverCode?: string;
+    /** The server's lookup reference for a persisted 5xx (`err_…`), when the
+     *  envelope carried one. A world-plane fault is sanitized to "An unexpected
+     *  error occurred." before it leaves the server; the `errorId` is the ONE
+     *  greppable thing the operator can resolve to the real cause — quote it in
+     *  a support request. Absent on every 4xx and on a 5xx that was not
+     *  persisted (0.28.1; until then the client dropped it). */
+    readonly errorId?: string;
     readonly retryAfterSec?: number;
     /** Why the world refused the effects you proposed — per op, with the
      *  server's own reason and code.
@@ -78,6 +96,8 @@ export declare class WorldApiError extends Error {
         status: number;
         message: string;
         detail?: string;
+        serverCode?: string;
+        errorId?: string;
         retryAfterSec?: number;
         rejectedEffects?: readonly {
             readonly index: number;

package/dist/index.js

@@ -23,7 +23,7 @@ import { createHash, createHmac, randomUUID } from 'node:crypto';
  *  a project is running — which is exactly the field you reach for when a
  *  customer's integration behaves like an older SDK than they say they have.
  *  It sat at '0.1.0' for eight releases before anything compared the two. */
-export const WORLD_SDK_VERSION = '0.27.0';
+export const WORLD_SDK_VERSION = '0.28.1';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 /** Read the commit turn id out of an envelope, so the signature covers the id
  *  the server will commit under. The payload half is base64url JSON; the
@@ -60,6 +60,24 @@ export class WorldApiError extends Error {
     status;
     /** The server's own message, when it sent one. */
     detail;
+    /** The server's own machine-readable `code`, when the refusal carried one —
+     *  the field a 409 uses to say WHICH conflict, since `code` above maps a
+     *  status and every 409 is `conflict` there. `stale_deliberation` (re-run
+     *  `deliberate`), `episode_ended` (start the next episode), `has_instances`,
+     *  `episode_history_incomplete`, `story_contract_v{2,3,4}_write_disabled`
+     *  are the server's vocabulary today; a refusal that carries only prose
+     *  leaves this undefined — absent means "the server did not say", never
+     *  "no conflict". Until 0.28.0 the client read `error` into `detail` and
+     *  dropped `code` on the floor, so the one carrier an integrator could
+     *  branch on never arrived. */
+    serverCode;
+    /** The server's lookup reference for a persisted 5xx (`err_…`), when the
+     *  envelope carried one. A world-plane fault is sanitized to "An unexpected
+     *  error occurred." before it leaves the server; the `errorId` is the ONE
+     *  greppable thing the operator can resolve to the real cause — quote it in
+     *  a support request. Absent on every 4xx and on a 5xx that was not
+     *  persisted (0.28.1; until then the client dropped it). */
+    errorId;
     retryAfterSec;
     /** Why the world refused the effects you proposed — per op, with the
      *  server's own reason and code.
@@ -84,6 +102,10 @@ export class WorldApiError extends Error {
         this.status = input.status;
         if (input.detail !== undefined)
             this.detail = input.detail;
+        if (input.serverCode !== undefined)
+            this.serverCode = input.serverCode;
+        if (input.errorId !== undefined)
+            this.errorId = input.errorId;
         if (input.retryAfterSec !== undefined)
             this.retryAfterSec = input.retryAfterSec;
         if (input.rejectedEffects !== undefined)
@@ -921,11 +943,24 @@ export class PouchyWorldClient {
                 : undefined;
             const retryAfterSec = retryAfterFrom(response, parsed && typeof parsed === 'object' ? parsed : null);
             const rejectedEffects = rejectedEffectsFrom(parsed);
+            // A string only: a body whose `code` is not text (a number, an
+            // object) would hand the integrator a value the type does not
+            // promise, so it stays absent rather than coerced.
+            const serverCode = parsed && typeof parsed === 'object' && typeof parsed.code === 'string'
+                ? parsed.code
+                : undefined;
+            // Same string-only rule as `serverCode`: the envelope's lookup ref, or
+            // nothing — never a coerced non-string.
+            const errorId = parsed && typeof parsed === 'object' && typeof parsed.errorId === 'string'
+                ? parsed.errorId || undefined
+                : undefined;
             throw new WorldApiError({
                 code: codeForStatus(response.status),
                 status: response.status,
                 message: `${method} ${path} → ${response.status}`,
                 ...(detail !== undefined ? { detail } : {}),
+                ...(serverCode !== undefined ? { serverCode } : {}),
+                ...(errorId !== undefined ? { errorId } : {}),
                 ...(retryAfterSec !== undefined ? { retryAfterSec } : {}),
                 ...(rejectedEffects !== undefined ? { rejectedEffects } : {})
             });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/world-sdk",
-	"version": "0.27.0",
+	"version": "0.28.1",
 	"description": "Server-side TypeScript client for Pouchy World \u2014 story packages, world definitions, world sessions, coordinated turns, trusted events, replay verification and script drafts. Node only: it holds a project Secret Key and a source signing key, which never belong in a browser or a mobile app.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",