@pouchy_ai/admin-sdk 0.31.0 → 0.31.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.31.1 — 2026-09-06
+
+- **`AdminApiError.errorId`** — the server's lookup reference (`err_…`) for a
+  persisted 5xx, when the envelope carried one. An uncaught console-plane fault
+  is sanitized to "An unexpected error occurred." before it leaves the server;
+  the `errorId` is the one thing an operator can resolve to the real cause, and
+  the client read `error` / `code` / `retryAfter` and dropped it. Additive;
+  absent on 4xx and on a 5xx that was not persisted; string-only, like `code`.
+  Quote it in a support request.
+
 ## 0.31.0 — 2026-09-05
 
 - **`Agent.spawnSubtasks?`** and **`Agent.replyCues?`** (`ReplyCues`

package/README.md

@@ -346,6 +346,11 @@ try {
 }
 ```
 
+On a persisted 5xx the message is sanitized server-side ("An unexpected error
+occurred.") and `AdminApiError.errorId` carries the server's `err_…` lookup
+reference (0.31.1) — quote it in a support request; it is what resolves to the
+real cause.
+
 ### Failure codes (409)
 
 **Every machine-readable failure on this API is a 409**, so `status` separates

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.31.0";
+export declare const ADMIN_SDK_VERSION = "0.31.1";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1/admin";
 /** Deadline for the routes whose server handler declares `maxDuration: 300` —
  *  the server's own ceiling plus headroom, so a client abort can only ever mean
@@ -95,7 +95,14 @@ export declare class AdminApiError extends Error {
     status: number;
     readonly retryAfter?: number;
     readonly code?: AdminErrorCode;
-    constructor(message: string, status: number, retryAfter?: number, code?: string);
+    /** The server's lookup reference for a persisted 5xx (`err_…`), when the
+     *  envelope carried one. An uncaught console-plane fault is sanitized to
+     *  "An unexpected error occurred." before it leaves the server, so this is
+     *  the ONE greppable thing the operator can resolve to the real cause —
+     *  quote it in a support request. Absent on 4xx and on a 5xx that was not
+     *  persisted (0.31.1; until then the client dropped the field). */
+    readonly errorId?: string;
+    constructor(message: string, status: number, retryAfter?: number, code?: string, errorId?: string);
 }
 export type Env = 'live' | 'test';
 export type AgentStatus = 'draft' | 'published';

package/dist/index.js

@@ -8,7 +8,7 @@
 //   import { createAdminClient } from '@pouchy_ai/admin-sdk';
 //   const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
 //   const { agents } = await admin.listAgents();
-export const ADMIN_SDK_VERSION = '0.31.0';
+export const ADMIN_SDK_VERSION = '0.31.1';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1/admin';
 /** Default per-request timeout (ms). A hung upstream otherwise never rejects. */
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -124,7 +124,14 @@ export class AdminApiError extends Error {
     status;
     retryAfter;
     code;
-    constructor(message, status, retryAfter, code) {
+    /** The server's lookup reference for a persisted 5xx (`err_…`), when the
+     *  envelope carried one. An uncaught console-plane fault is sanitized to
+     *  "An unexpected error occurred." before it leaves the server, so this is
+     *  the ONE greppable thing the operator can resolve to the real cause —
+     *  quote it in a support request. Absent on 4xx and on a 5xx that was not
+     *  persisted (0.31.1; until then the client dropped the field). */
+    errorId;
+    constructor(message, status, retryAfter, code, errorId) {
         super(message);
         this.name = 'AdminApiError';
         this.status = status;
@@ -135,6 +142,8 @@ export class AdminApiError extends Error {
         // a `switch (e.code)` would fall through on in a way the caller can't see.
         if (typeof code === 'string' && code)
             this.code = code;
+        if (typeof errorId === 'string' && errorId)
+            this.errorId = errorId;
     }
 }
 /** The `code` a non-2xx body named, or undefined. Kept beside `retryAfterFrom`
@@ -144,6 +153,12 @@ function codeFrom(body) {
     const v = body?.code;
     return typeof v === 'string' && v ? v : undefined;
 }
+/** The `errorId` a persisted 5xx envelope named, or undefined — same
+ *  string-only rule as `codeFrom`. */
+function errorIdFrom(body) {
+    const v = body?.errorId;
+    return typeof v === 'string' && v ? v : undefined;
+}
 /** Seconds to wait before retrying a throttled response, or undefined when the
  *  server named neither a body field nor a header.
  *
@@ -228,7 +243,7 @@ export function createAdminClient(opts) {
         }
         const data = (await res.json().catch(() => ({})));
         if (!res.ok)
-            throw new AdminApiError(data?.error ?? `HTTP ${res.status}`, res.status, retryAfterFrom(res, data), codeFrom(data));
+            throw new AdminApiError(data?.error ?? `HTTP ${res.status}`, res.status, retryAfterFrom(res, data), codeFrom(data), errorIdFrom(data));
         return data;
     }
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/admin-sdk",
-	"version": "0.31.0",
+	"version": "0.31.1",
 	"description": "Typed TypeScript client for the Pouchy Admin API \u2014 manage agents, keys, end users, knowledge, skills, channels, schedules, webhooks and credentials headlessly, with a project Admin key.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",