@pouchy_ai/admin-sdk 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 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
+still working.
+
+- **Per-route request deadlines.** `POST /knowledge`, `POST /knowledge/file`,
+  `POST /knowledge/url` and `DELETE /users/{instanceId}` are the Admin API
+  handlers that declare `maxDuration: 300` — their response headers only arrive
+  when the ingest (chunk + summarize + embed, after OCR / Whisper / vision or an
+  SSRF-guarded page fetch) or the recursive GDPR erasure has FINISHED. Under the
+  flat 30s deadline a real PDF or a data-heavy instance rejected
+  `request timed out after 30000ms` while the operation kept running and
+  billing server-side, and the natural retry then raced the still-running first
+  ingest. Those four now default to `LONG_WORK_TIMEOUT_MS` (310s — the server's
+  own ceiling plus headroom); every other request keeps the 30s default, so a
+  genuinely hung server still fails fast.
+
+  This is the same defect the companion JS SDK fixed as `BUFFERED_TURN_TIMEOUT_MS`
+  (CR-141); 0.6.0 added `/knowledge/file` and `/knowledge/url` behind the old
+  flat deadline without porting it.
+
+- **`timeoutMs` still wins.** A host that sets `timeoutMs` explicitly gets it on
+  every request, long or short — only the DEFAULT is route-aware. No API surface
+  added or removed; purely widening for calls that previously failed.
+
+- New exports for hosts that want the contract in code:
+  `LONG_WORK_TIMEOUT_MS`, `LONG_WORK_REQUESTS`, `requestDeadlineMs(method, path)`.
+
 ## 0.6.0 — 2026-07-21
 
 Additive: knowledge ingestion parity + headless agent version control. Both

package/README.md

@@ -62,10 +62,24 @@ createAdminClient({
   adminKey: 'pchy_admin_…',   // required
   baseUrl: 'https://pouchy.ai/v1/admin', // optional (self-host / staging)
   fetch: myFetch,             // optional (Node <18, or tests)
-  timeoutMs: 30_000           // optional per-request timeout (default 30s)
+  timeoutMs: 30_000           // optional per-request timeout — see below
 });
 ```
 
+`timeoutMs` defaults to **30s**, except for the four requests whose server
+handler declares `maxDuration: 300` and therefore answers only when the work is
+finished — `POST /knowledge`, `POST /knowledge/file`, `POST /knowledge/url`
+(chunk + summarize + embed, after OCR / Whisper / vision or a page fetch) and
+`DELETE /users/{instanceId}` (recursive GDPR erasure). Those default to **310s**
+(`LONG_WORK_TIMEOUT_MS`), so a client abort can only ever mean "the server really
+is hung", never "the server is still working" — a shorter deadline there reports
+a failure for an ingest that is succeeding, and the retry it invites races the
+still-running first one.
+
+Setting `timeoutMs` explicitly always wins and applies to **every** request, long
+or short. `requestDeadlineMs(method, path)` returns the default a given request
+would use.
+
 ## Errors
 
 Every method throws `AdminApiError` on failure — a non-2xx response, a network
@@ -81,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,5 +1,34 @@
-export declare const ADMIN_SDK_VERSION = "0.6.0";
+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
+ *  "the server really is hung", never "the server is still working".
+ *
+ *  Why this exists: a flat client deadline BELOW a route's declared server
+ *  ceiling turns a succeeding, billed operation into a client-side
+ *  `request timed out`. The companion JS SDK hit exactly this (CR-141) and
+ *  fixed it with `BUFFERED_TURN_TIMEOUT_MS = 310_000`; on knowledge ingest it
+ *  is worse than a bad error message, because the integrator's natural retry
+ *  then races the still-running first ingest — the register's CR-14 interleave,
+ *  made systematic instead of rare. This SDK shipped the same flat 30s and, in
+ *  0.6.0, ADDED two more long routes behind it (`/knowledge/file`,
+ *  `/knowledge/url`). Same number as the JS constant, for the same reason. */
+export declare const LONG_WORK_TIMEOUT_MS = 310000;
+/** The Admin API requests whose handler declares `maxDuration: 300`.
+ *
+ *  Derived from the route files, not guessed — `sdk-deadlines.drift.test.ts`
+ *  binds this list to `export const config = { maxDuration }` in
+ *  `src/routes/v1/admin/**` in BOTH directions, so a new long-running admin
+ *  route (or a renamed one) fails a merge instead of silently shipping a
+ *  30s client cut. Paths are SDK-relative (the base URL already carries
+ *  `/v1/admin`). */
+export declare const LONG_WORK_REQUESTS: ReadonlyArray<{
+    method: string;
+    path: RegExp;
+}>;
+/** The deadline a given request runs under when the host set no `timeoutMs`.
+ *  Exported so the contract is assertable without timing anything. */
+export declare function requestDeadlineMs(method: string, path: string): number;
 export interface AdminClientOptions {
     /** A project Admin key (`pchy_admin_…`) from the dashboard Admin Keys page. */
     adminKey: string;
@@ -7,15 +36,34 @@ export interface AdminClientOptions {
     baseUrl?: string;
     /** Inject a fetch impl (Node <18, or for tests). Default global fetch. */
     fetch?: typeof fetch;
-    /** Per-request timeout in ms (default 30s). A request that outlives it
-     *  rejects with an AdminApiError(status 0). */
+    /** Per-request timeout in ms. Default 30s, EXCEPT the requests whose server
+     *  handler declares `maxDuration: 300` (knowledge ingest by text/file/url,
+     *  and the GDPR user delete), which default to
+     *  {@link LONG_WORK_TIMEOUT_MS}. Setting this explicitly always wins and
+     *  applies to every request, long or short. A request that outlives its
+     *  deadline rejects with an AdminApiError(status 0). */
     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,19 +8,113 @@
 //   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.0';
+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;
+/** 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
+ *  "the server really is hung", never "the server is still working".
+ *
+ *  Why this exists: a flat client deadline BELOW a route's declared server
+ *  ceiling turns a succeeding, billed operation into a client-side
+ *  `request timed out`. The companion JS SDK hit exactly this (CR-141) and
+ *  fixed it with `BUFFERED_TURN_TIMEOUT_MS = 310_000`; on knowledge ingest it
+ *  is worse than a bad error message, because the integrator's natural retry
+ *  then races the still-running first ingest — the register's CR-14 interleave,
+ *  made systematic instead of rare. This SDK shipped the same flat 30s and, in
+ *  0.6.0, ADDED two more long routes behind it (`/knowledge/file`,
+ *  `/knowledge/url`). Same number as the JS constant, for the same reason. */
+export const LONG_WORK_TIMEOUT_MS = 310_000;
+/** The Admin API requests whose handler declares `maxDuration: 300`.
+ *
+ *  Derived from the route files, not guessed — `sdk-deadlines.drift.test.ts`
+ *  binds this list to `export const config = { maxDuration }` in
+ *  `src/routes/v1/admin/**` in BOTH directions, so a new long-running admin
+ *  route (or a renamed one) fails a merge instead of silently shipping a
+ *  30s client cut. Paths are SDK-relative (the base URL already carries
+ *  `/v1/admin`). */
+export const LONG_WORK_REQUESTS = [
+    // Synchronous ingest: chunk + summarize + embed before headers.
+    { method: 'POST', path: /^\/knowledge$/ },
+    // …plus OCR / Whisper / vision understanding of the raw file first.
+    { method: 'POST', path: /^\/knowledge\/file$/ },
+    // …plus an SSRF-guarded fetch + HTML reduction first.
+    { method: 'POST', path: /^\/knowledge\/url$/ },
+    // GDPR erasure: recursive delete of the instance's whole users/** subtree
+    // plus the top-level social graph. A client abort here is the worst of the
+    // four — the operator is left not knowing whether the wipe completed.
+    { method: 'DELETE', path: /^\/users\/[^/]+$/ }
+];
+/** The deadline a given request runs under when the host set no `timeoutMs`.
+ *  Exported so the contract is assertable without timing anything. */
+export function requestDeadlineMs(method, path) {
+    const bare = path.split('?')[0];
+    const m = method.toUpperCase();
+    return LONG_WORK_REQUESTS.some((r) => r.method === m && r.path.test(bare))
+        ? LONG_WORK_TIMEOUT_MS
+        : 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();
@@ -37,8 +131,11 @@ export function createAdminClient(opts) {
     const f = opts.fetch ?? globalThis.fetch;
     if (!f)
         throw new AdminApiError('no fetch available — pass opts.fetch on Node <18', 0);
-    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     async function request(method, path, body) {
+        // An explicit host `timeoutMs` always wins (JS SDK contract); otherwise
+        // the deadline is sized to the ROUTE, so the four handlers that declare
+        // `maxDuration: 300` are not cut at 30s while they are still working.
+        const timeoutMs = opts.timeoutMs ?? requestDeadlineMs(method, path);
         // Every failure surfaces as an AdminApiError (the doc contract): a
         // network/DNS error or a timeout would otherwise escape as a raw
         // `TypeError: fetch failed` / AbortError. Status 0 = never reached the
@@ -61,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.0",
+  "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",