@pouchy_ai/world-sdk 0.28.0 → 0.28.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @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`

package/README.md

@@ -251,7 +251,8 @@ an `approved` editorial can be exported.
 `newTurnId` / `isReservedTurnId` (idempotency), `describeTurn` (read a result
 without guessing), `WorldApiError` with typed codes, `.retryable`,
 `serverCode` (the server's own `code` on a refusal — which 409, since `code`
-maps the status), and `rejectedEffects` (which of YOUR proposed ops the world
+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.28.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. */
@@ -61,6 +61,13 @@ export declare class WorldApiError extends Error {
      *  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.
@@ -90,6 +97,7 @@ export declare class WorldApiError extends Error {
         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.28.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
@@ -71,6 +71,13 @@ export class WorldApiError extends Error {
      *  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.
@@ -97,6 +104,8 @@ export class WorldApiError extends Error {
             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)
@@ -940,12 +949,18 @@ export class PouchyWorldClient {
             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.28.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",