@pouchy_ai/admin-sdk 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.7.0 — 2026-07-27
+
+Adds: a throttled request now tells you how long to wait.
+
+- **`AdminApiError.retryAfter`** — seconds, present on a 429 and `undefined` on
+  every other failure. Every write this client makes (`POST` / `PATCH` /
+  `DELETE`) passes through one per-IP throttle on the server — a
+  `v1-admin-write` bucket of 120 non-GET requests per minute across all of
+  `/v1/*` — and the natural migration loop (`updateAgent` per agent,
+  `setUserSuspended` per user, `setSkillRate` per skill) reaches 120 in seconds.
+  The server has always answered with both a `Retry-After` header and a body
+  `retryAfter`; this package discarded both, so the one caller who provably
+  needs a backoff number had only the prose message to guess from — and a
+  guessed-too-short retry keeps the sliding window saturated, extending the
+  throttle it is trying to escape.
+
+  ```ts
+  try {
+    await admin.updateAgent(id, patch);
+  } catch (e) {
+    if (e instanceof AdminApiError && e.status === 429) {
+      await new Promise((r) => setTimeout(r, (e.retryAfter ?? 5) * 1000));
+    }
+  }
+  ```
+
+  Resolution order matches the companion JS SDK's `retryAfterFrom`: body
+  `retryAfterSec`, then body `retryAfter` (the key the `/v1` throttle actually
+  emits), then the `Retry-After` header as seconds, then its RFC 9110 HTTP-date
+  form converted to a non-negative delta. A response that names none leaves
+  `retryAfter` **undefined** — never `0`, which would tell backoff code to retry
+  immediately.
+
+- **Back-compatible.** New optional third constructor argument and a new
+  optional readonly property; `status`, `message` and the `instanceof
+  AdminApiError` check are untouched. Minor bump because the public error type
+  gained a member.
+
+  Both sibling SDKs already surfaced this value (JS `CompanionError.retryAfter`,
+  python `CompanionError.retry_after`) — same name, same units, same precedence.
+
 ## 0.6.1 — 2026-07-27
 
 Fix: the four long-running requests are no longer cut at 30s while the server is

package/README.md

@@ -95,6 +95,33 @@ try {
 }
 ```
 
+### Throttling (429)
+
+Writes are rate-limited per IP — 120 non-`GET` requests per minute across the
+whole `/v1` plane — so a migration loop over agents, users or skills will hit it.
+On a 429, `AdminApiError.retryAfter` carries the server's backoff in **seconds**
+(from the body's `retryAfter` / `retryAfterSec`, or the `Retry-After` header).
+It is `undefined` on every other failure, and `undefined` — never `0` — when the
+server named no delay, so `??` your own floor rather than retrying immediately:
+
+```ts
+async function withBackoff<T>(call: () => Promise<T>, tries = 5): Promise<T> {
+  for (let i = 0; ; i++) {
+    try {
+      return await call();
+    } catch (e) {
+      if (!(e instanceof AdminApiError) || e.status !== 429 || i >= tries) throw e;
+      await new Promise((r) => setTimeout(r, (e.retryAfter ?? 5) * 1000));
+    }
+  }
+}
+
+await withBackoff(() => admin.updateAgent(id, { status: 'published' }));
+```
+
+Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
+0.7.0.
+
 ## Surface
 
 | Area | Methods |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.6.1";
+export declare const ADMIN_SDK_VERSION = "0.7.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
@@ -45,10 +45,25 @@ export interface AdminClientOptions {
     timeoutMs?: number;
 }
 /** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
- *  server's `error` string when present. */
+ *  server's `error` string when present; `retryAfter` is the throttle's own
+ *  backoff in SECONDS on a 429 (undefined on every other failure).
+ *
+ *  Why `retryAfter` exists: the entire write surface of this SDK sits behind one
+ *  per-IP throttle — `hooks.server.ts` runs a `v1-admin-write` bucket (120
+ *  non-GET requests / minute) over every `/v1/*` path, and `/v1/admin` is where
+ *  this client lives. A migration loop (`updateAgent` per agent,
+ *  `setUserSuspended` per user, `setSkillRate` per skill) reaches 120 in
+ *  seconds. The server answers with BOTH a `Retry-After` header and a body
+ *  `retryAfter`, and this package used to discard both — leaving the one caller
+ *  who provably needs a backoff number with nothing but a prose message to
+ *  guess from, and a guessed-too-short retry keeps the sliding window
+ *  saturated. Both sibling SDKs already surface it (JS
+ *  `CompanionError.retryAfter`, python `CompanionError.retry_after`); this is
+ *  the same value under the same name. */
 export declare class AdminApiError extends Error {
     status: number;
-    constructor(message: string, status: number);
+    readonly retryAfter?: number;
+    constructor(message: string, status: number, retryAfter?: number);
 }
 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.6.1';
+export const ADMIN_SDK_VERSION = '0.7.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;
@@ -56,14 +56,65 @@ export function requestDeadlineMs(method, path) {
         : DEFAULT_TIMEOUT_MS;
 }
 /** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
- *  server's `error` string when present. */
+ *  server's `error` string when present; `retryAfter` is the throttle's own
+ *  backoff in SECONDS on a 429 (undefined on every other failure).
+ *
+ *  Why `retryAfter` exists: the entire write surface of this SDK sits behind one
+ *  per-IP throttle — `hooks.server.ts` runs a `v1-admin-write` bucket (120
+ *  non-GET requests / minute) over every `/v1/*` path, and `/v1/admin` is where
+ *  this client lives. A migration loop (`updateAgent` per agent,
+ *  `setUserSuspended` per user, `setSkillRate` per skill) reaches 120 in
+ *  seconds. The server answers with BOTH a `Retry-After` header and a body
+ *  `retryAfter`, and this package used to discard both — leaving the one caller
+ *  who provably needs a backoff number with nothing but a prose message to
+ *  guess from, and a guessed-too-short retry keeps the sliding window
+ *  saturated. Both sibling SDKs already surface it (JS
+ *  `CompanionError.retryAfter`, python `CompanionError.retry_after`); this is
+ *  the same value under the same name. */
 export class AdminApiError extends Error {
     status;
-    constructor(message, status) {
+    retryAfter;
+    constructor(message, status, retryAfter) {
         super(message);
         this.name = 'AdminApiError';
         this.status = status;
+        if (retryAfter !== undefined)
+            this.retryAfter = retryAfter;
+    }
+}
+/** Seconds to wait before retrying a throttled response, or undefined when the
+ *  server named neither a body field nor a header.
+ *
+ *  Precedence mirrors the JS companion SDK's `retryAfterFrom`, plus the one key
+ *  this plane actually emits: the `/v1` admin-write 429 body says `retryAfter`,
+ *  while the `/api/companion` 429 body says `retryAfterSec`. Accept both so the
+ *  same helper is correct if a route is ever aligned on the other name.
+ *
+ *  A missing/blank header must stay undefined — `Number(null)` is 0, which
+ *  would stamp `retryAfter: 0` on EVERY error without the header (a 404, a
+ *  400 …) and tell backoff code "retry immediately". */
+function retryAfterFrom(res, body) {
+    for (const k of ['retryAfterSec', 'retryAfter']) {
+        const v = body?.[k];
+        if (typeof v === 'number' && Number.isFinite(v) && v >= 0)
+            return v;
     }
+    // Optional-chained because `opts.fetch` is a documented injection point and
+    // hand-rolled test doubles routinely return a bare `{ ok, status, json }`
+    // with no `headers` — reading a header must never turn their 4xx fixture
+    // into a TypeError.
+    const raw = res.headers?.get?.('Retry-After');
+    if (raw === null || raw === undefined || raw.trim() === '')
+        return undefined;
+    const header = Number(raw);
+    if (Number.isFinite(header) && header >= 0)
+        return header;
+    // RFC 9110 also allows an HTTP-date (proxies/CDNs emit it) — convert to a
+    // non-negative seconds delta. Unparseable stays undefined.
+    const at = Date.parse(raw);
+    if (!Number.isNaN(at))
+        return Math.max(0, Math.ceil((at - Date.now()) / 1000));
+    return undefined;
 }
 function qs(params) {
     const u = new URLSearchParams();
@@ -107,7 +158,7 @@ export function createAdminClient(opts) {
         }
         const data = (await res.json().catch(() => ({})));
         if (!res.ok)
-            throw new AdminApiError(data?.error ?? `HTTP ${res.status}`, res.status);
+            throw new AdminApiError(data?.error ?? `HTTP ${res.status}`, res.status, retryAfterFrom(res, data));
         return data;
     }
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/admin-sdk",
-  "version": "0.6.1",
+  "version": "0.7.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",