@pouchy_ai/admin-sdk 0.31.1 → 0.32.1

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.32.1 — 2026-09-06
+
+- **A transport failure now names the request.** `AdminApiError.message` on a
+  timeout or a network error is `GET /agents — request timed out after 30000ms`
+  / `POST /knowledge — network error: fetch failed`, where it used to be the
+  bare tail. Status 0 failures carry no `code` and no `errorId`, and ~70
+  methods share one request funnel, so the message was the only place the call
+  could have been named and it was the one place that did not name it — the
+  README's own `console.error(e.status, e.message)` read identically for every
+  route. The sibling `@pouchy_ai/world-sdk` has always spelled `${method}
+  ${path}` here. The non-2xx path is UNCHANGED: the server's own `error` string
+  is still passed through verbatim, because that is the message this SDK
+  documents and integrators match on. Only its no-body fallback gained the
+  prefix (`GET /agents → HTTP 502`, previously `HTTP 502`), where there was no
+  server text to displace. If you assert on exact message text for a timeout or
+  network error, match on a substring.
+
+## 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

package/README.md

@@ -351,6 +351,20 @@ 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.
 
+A **transport** failure has no status, no `code` and no `errorId`, so since
+0.32.1 its message names the request that failed:
+
+```text
+GET /agents — request timed out after 30000ms
+POST /knowledge/url — network error: fetch failed
+```
+
+Every method shares one request funnel, so without that prefix a timeout on a
+five-minute knowledge ingest and a timeout on `listAgents` printed the same
+line. HTTP errors are unchanged: the message is the server's own `error` string
+(`"unknown agent"`), and only its no-body fallback names the request
+(`GET /agents → HTTP 502`).
+
 ### 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.1";
+export declare const ADMIN_SDK_VERSION = "0.32.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
@@ -65,10 +65,21 @@ export declare const ADMIN_ERROR_CODES: readonly ["story_contract_v2_write_disab
  *  codes newer than this SDK build while preserving autocomplete — same
  *  doctrine as the companion SDK's `CompanionErrorCodeValue`. */
 export type AdminErrorCode = (typeof ADMIN_ERROR_CODES)[number] | (string & {});
-/** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
- *  server's `error` string when present; `retryAfter` is the throttle's own
- *  backoff in SECONDS on a 429 (undefined on every other failure); `code` is the
- *  server's machine tag when it named one (undefined otherwise).
+/** Thrown on any non-2xx response AND on a transport failure that never reached
+ *  the server (network / DNS / timeout), which carries `status: 0`. `status` is
+ *  the HTTP status; `retryAfter` is the throttle's own backoff in SECONDS on a
+ *  429 (undefined on every other failure); `code` is the server's machine tag
+ *  when it named one (undefined otherwise).
+ *
+ *  `message` has two shapes, and which one you get follows `status`. On a
+ *  non-2xx it is the server's own `error` string, verbatim — that is what this
+ *  package documents and what integrators read. On a status-0 transport failure
+ *  there IS no server string, and no `code` or `errorId` either, so the message
+ *  names the request instead (`GET /agents — request timed out after 30000ms`);
+ *  ~70 methods share one funnel, and without it a hung five-minute knowledge
+ *  ingest printed the same line as a hung `listAgents` (0.32.1). The non-2xx
+ *  fallback for a body with no `error` at all is named the same way
+ *  (`GET /agents → HTTP 502`). Prose either way: switch on `code`, not on this.
  *
  *  Why `code` exists: the Admin API's machine-readable failures are ALL on
  *  409, so `status` cannot separate them and this package used to discard the
@@ -517,8 +528,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
@@ -529,16 +540,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.1';
+export const ADMIN_SDK_VERSION = '0.32.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;
@@ -94,10 +94,21 @@ export const ADMIN_ERROR_CODES = [
     'run_not_waiting',
     'event_mismatch'
 ];
-/** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
- *  server's `error` string when present; `retryAfter` is the throttle's own
- *  backoff in SECONDS on a 429 (undefined on every other failure); `code` is the
- *  server's machine tag when it named one (undefined otherwise).
+/** Thrown on any non-2xx response AND on a transport failure that never reached
+ *  the server (network / DNS / timeout), which carries `status: 0`. `status` is
+ *  the HTTP status; `retryAfter` is the throttle's own backoff in SECONDS on a
+ *  429 (undefined on every other failure); `code` is the server's machine tag
+ *  when it named one (undefined otherwise).
+ *
+ *  `message` has two shapes, and which one you get follows `status`. On a
+ *  non-2xx it is the server's own `error` string, verbatim — that is what this
+ *  package documents and what integrators read. On a status-0 transport failure
+ *  there IS no server string, and no `code` or `errorId` either, so the message
+ *  names the request instead (`GET /agents — request timed out after 30000ms`);
+ *  ~70 methods share one funnel, and without it a hung five-minute knowledge
+ *  ingest printed the same line as a hung `listAgents` (0.32.1). The non-2xx
+ *  fallback for a body with no `error` at all is named the same way
+ *  (`GET /agents → HTTP 502`). Prose either way: switch on `code`, not on this.
  *
  *  Why `code` exists: the Admin API's machine-readable failures are ALL on
  *  409, so `status` cannot separate them and this package used to discard the
@@ -239,11 +250,29 @@ export function createAdminClient(opts) {
         }
         catch (e) {
             const isTimeout = e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError');
-            throw new AdminApiError(isTimeout ? `request timed out after ${timeoutMs}ms` : `network error: ${e instanceof Error ? e.message : String(e)}`, 0);
+            // The REQUEST is named, because nothing else in the envelope can name it.
+            // ~70 methods share this one funnel and a transport failure has status 0,
+            // no `code` and no `errorId` — so the README's own
+            // `console.error(e.status, e.message)` read `0 "request timed out after
+            // 30000ms"` for every route alike, and an operator could not tell a hung
+            // knowledge ingest from a hung `listAgents`. The sibling world-sdk has
+            // spelled `${method} ${path}` on both of its transport throws since it
+            // shipped; this is the same prefix, for the same reason.
+            throw new AdminApiError(isTimeout
+                ? `${method} ${path} — request timed out after ${timeoutMs}ms`
+                : `${method} ${path} — network error: ${e instanceof Error ? e.message : String(e)}`, 0);
         }
         const data = (await res.json().catch(() => ({})));
         if (!res.ok)
-            throw new AdminApiError(data?.error ?? `HTTP ${res.status}`, res.status, retryAfterFrom(res, data), codeFrom(data), errorIdFrom(data));
+            throw new AdminApiError(
+            // The server's own `error` string is passed through UNCHANGED — it is
+            // the message this SDK documents (`404 "unknown agent"`), integrators
+            // match on it, and `status` / `code` / `errorId` already disambiguate a
+            // coded failure. Only the FALLBACK is prefixed, and only because there
+            // is no server text there to displace: an edge 502 whose body is HTML
+            // (`res.json()` rejects → `{}`) used to read `HTTP 502` with nothing
+            // saying which of ~70 calls produced it.
+            data?.error ?? `${method} ${path} → 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.1",
+	"version": "0.32.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",