@pouchy_ai/admin-sdk 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.32.0 — 2026-09-06
+
+- **Diff entries are `{ field, before, after }`** — `diffAgentVersions` and
+  `getAgentPromotion` were typed `{ field, from, to }` since they were added,
+  and the server has always sent `before` / `after` (`diffAgentTemplates`).
+  Reading `d.from` / `d.to` gave `undefined` for every changed field. The
+  types (and the published OpenAPI spec) now say what the wire says; no
+  runtime change. If you read the keys by name, rename them.
+- **`getAgentPromotion().pinnedSnapshotMissing?`** — true when the production
+  pin names an archived snapshot that no longer exists, in which case live
+  instances run the staging head until a re-promote re-pins. Additive;
+  older servers omit it. The diff is empty in that state, so read this before
+  reading an empty diff as "in sync".
+
+## 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.32.0";
 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';
@@ -510,8 +517,8 @@ export interface AdminClient {
         to: string;
         diff: Array<{
             field: string;
-            from: unknown;
-            to: unknown;
+            before: unknown;
+            after: unknown;
         }>;
     }>;
     /** Roll an agent back to an archived revision. git-revert semantics: the
@@ -522,16 +529,21 @@ export interface AdminClient {
     }>;
     /** Promotion status: the head (staging) vs the pinned production version, plus
      *  the diff a promotion would ship (empty when in sync). `pending` is false
-     *  when the agent was never promoted (live follows the head). */
+     *  when the agent was never promoted (live follows the head).
+     *  `pinnedSnapshotMissing` (0.32.0) is true when the pin names a snapshot
+     *  that no longer exists — live instances are then running the staging head
+     *  and a re-promote re-pins; the diff is empty in that state for the OTHER
+     *  reason, so read this field before reading an empty diff as "in sync". */
     getAgentPromotion(agentId: string): Promise<{
         stagingRev: number;
         prodRev: number | null;
         pending: boolean;
         diff: Array<{
             field: string;
-            from: unknown;
-            to: unknown;
+            before: unknown;
+            after: unknown;
         }>;
+        pinnedSnapshotMissing?: boolean;
     }>;
     /** Promote the head to production: freezes the head as an archived version and
      *  pins prodRev WITHOUT bumping the rev. Live instances re-resolve on their

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.32.0';
 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.32.0",
 	"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",