@pouchy_ai/admin-sdk 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.10.0 — 2026-07-29
+
+- **`AdminApiError.code` — the Admin API's machine-readable failure tag.** The
+  server has been sending `code` on ten failures across nineteen emit sites;
+  this package read `error` off the body and dropped `code` on the floor, so the
+  field was unreachable from the first-party client.
+- **Why it matters more than it sounds: every one of those ten codes is a 409.**
+  On this plane the status line never disambiguates, and two of the durable-run
+  routes answer 409 for two different reasons each, with opposite recoveries —
+  `resumeRun` (`stale_token`: re-read and answer again / `run_not_parked`: stop,
+  someone already decided) and `signalRun` (`event_mismatch`: your event is early
+  or wrong, retry later / `run_not_waiting`: the wait ended, stop). This
+  package's own doc comments told callers to make exactly those distinctions,
+  which was not possible without string-matching English prose.
+- **`ADMIN_ERROR_CODES` + `AdminErrorCode` are exported** so a `switch` is typed.
+  The type carries a `(string & {})` arm (same doctrine as the companion SDK's
+  `CompanionErrorCodeValue`), so a code newer than your installed build still
+  arrives as a readable string instead of being filtered out. The list is
+  drift-gated against the server's own vocabulary in both directions.
+- Additive only — no method signature, request shape, status code or error
+  message changed. `code` is `undefined` on every failure the server did not tag
+  (400s, 404s, the 429, transport errors), and a non-string or empty `code` on
+  the wire leaves it `undefined` rather than stamping a falsy value a `switch`
+  would fall through on.
+
+## 0.9.0 — 2026-07-28
+
+- **Channel CRUD is typed (CR-77).** `createChannel` takes
+  `type: CreatableChannelType` instead of `string` — the full 31-transport
+  union, minus `internal-a2a`, which is in the platform's union but has no
+  adapter and is answered 400, so excluding it turns a runtime rejection into a
+  compile error. `secret` is now `ChannelSecretInput` (`token`,
+  `inboundSecret`, `extra`) rather than `Record<string, unknown>`.
+- The union is a duplicate of the server's `TransportType` (this package is
+  standalone and cannot import it), so a drift gate binds the two and fails CI
+  in BOTH directions — a transport on one side and not the other is either an
+  integrator typed out of a working call, or a compile-time promise the API
+  rejects.
+- Per-transport `secret.extra` field lists are still documented in
+  <https://pouchy.ai/docs/channel-setup> rather than modelled per type: the sets are
+  operator-supplied and move with each provider's own console.
+
 ## 0.8.0 — 2026-07-28
 
 - **Durable runs.** `listRuns`, `createRun`, `getRun`, `cancelRun`, `resumeRun`,

package/README.md

@@ -100,6 +100,62 @@ try {
 }
 ```
 
+### Failure codes (409)
+
+**Every machine-readable failure on this API is a 409**, so `status` separates
+none of them. `AdminApiError.code` is the discriminator — switch on it rather
+than string-matching `message`, which is prose and may be reworded:
+
+```ts
+import { AdminApiError } from '@pouchy_ai/admin-sdk';
+
+// `runId` and `token` come from the run you are answering — the
+// `agent.run_awaiting` webhook carries both, or read them off `getRun`.
+declare const runId: string;
+declare const token: string;
+
+try {
+  await admin.resumeRun(runId, { approved: true, token });
+} catch (e) {
+  if (!(e instanceof AdminApiError)) throw e;
+  switch (e.code) {
+    case 'stale_token': {
+      // The run moved on to a different question. Re-read and answer the
+      // current one — this is the retryable branch.
+      const { run } = await admin.getRun(runId);
+      if (run.awaiting) await admin.resumeRun(runId, { approved: true, token: run.awaiting.token });
+      break;
+    }
+    case 'run_not_parked':
+      // Someone else decided, or the run was cancelled. Do NOT retry.
+      break;
+    default:
+      throw e;
+  }
+}
+```
+
+The vocabulary is exported as `ADMIN_ERROR_CODES` (and the `AdminErrorCode`
+type), and is append-only:
+
+| code | route | what to do |
+|---|---|---|
+| `schedule_limit_reached` | `createSchedule` | delete or disable a schedule, retry |
+| `channel_limit_reached` | `createChannel` | delete an unused connector, retry |
+| `webhook_limit_reached` | `createWebhook` | delete an unused endpoint, retry |
+| `run_limit_reached` | `createRun` | wait for a run to finish, or `cancelRun` one |
+| `reembed_required` | knowledge config | clear + re-ingest to switch embedding model |
+| `run_terminal` | `cancelRun` | the run already finished — nothing to cancel |
+| `run_not_parked` | `resumeRun` | already decided; stop retrying |
+| `stale_token` | `resumeRun` | `getRun`, then answer the current `awaiting.token` |
+| `run_not_waiting` | `signalRun` | the wait ended; stop retrying |
+| `event_mismatch` | `signalRun` | the run wants a different key; your event is early or wrong |
+
+`code` is `undefined` on every failure the server did not tag (400s, 404s, the
+429, transport errors), so always keep a `default` branch. The type has a
+`(string & {})` arm on purpose: a code newer than your installed build still
+arrives as a readable string. Available from **0.10.0**.
+
 ### Throttling (429)
 
 Writes are rate-limited per IP — 120 non-`GET` requests per minute across the
@@ -142,6 +198,11 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | Channels | `listChannels` · `createChannel` · `getChannel` · `updateChannel` · `deleteChannel` |
 | Schedules | `listSchedules` · `createSchedule` · `getSchedule` · `updateSchedule` · `deleteSchedule` |
 | Durable runs | `listRuns` · `createRun` · `getRun` · `cancelRun` · `resumeRun` · `signalRun` |
+
+Channel types are checked at compile time: `createChannel` takes a
+`CreatableChannelType` (the platform's 31-transport union minus the adapterless
+`internal-a2a`), and `secret` is a named `ChannelSecretInput`. Per-transport
+`secret.extra` fields are listed in <https://pouchy.ai/docs/channel-setup>.
 | Webhooks | `listWebhooks` · `createWebhook` · `updateWebhook` · `rotateWebhookSecret` · `deleteWebhook` · `testWebhook` · `redeliverWebhook` |
 | Reporting | `getUsage` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
 | Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.8.0";
+export declare const ADMIN_SDK_VERSION = "0.10.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
@@ -50,9 +50,33 @@ export interface AdminClientOptions {
      *  failed with the self-contradicting `request timed out after 0ms`. */
     timeoutMs?: number;
 }
+/** Machine-readable failure tags the Admin API puts on an error body, mirroring
+ *  the server's own list (`src/lib/server/platform/api-error-codes.ts`) and
+ *  drift-tested against it. APPEND-ONLY: these are documented as switchable, so
+ *  renaming or removing one breaks integrators.
+ *
+ *  Every member is a **409**. That is the whole reason this vocabulary is
+ *  published: on this plane the status line never disambiguates, so two of the
+ *  durable-run routes answer 409 for two entirely different reasons each, with
+ *  different recoveries. `code` is the only thing that tells them apart. */
+export declare const ADMIN_ERROR_CODES: readonly ["schedule_limit_reached", "channel_limit_reached", "webhook_limit_reached", "run_limit_reached", "reembed_required", "run_terminal", "run_not_parked", "stale_token", "run_not_waiting", "event_mismatch"];
+/** `AdminApiError.code` values. The `(string & {})` arm keeps the type open for
+ *  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).
+ *  backoff in SECONDS on a 429 (undefined on every other failure); `code` is the
+ *  server's machine tag when it named one (undefined otherwise).
+ *
+ *  Why `code` exists: the Admin API's ten machine-readable failures are ALL on
+ *  409, so `status` cannot separate them and this package used to discard the
+ *  one field that can. Two routes are the point — `resumeRun` answers 409 for
+ *  `run_not_parked` (someone already decided; re-read, do not retry) or
+ *  `stale_token` (your token aged out; re-read for the current one and answer
+ *  again), and `signalRun` answers 409 for `run_not_waiting` or
+ *  `event_mismatch`. This package's own docs told callers to distinguish those,
+ *  which was not possible without switching on prose.
  *
  *  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
@@ -69,7 +93,8 @@ export interface AdminClientOptions {
 export declare class AdminApiError extends Error {
     status: number;
     readonly retryAfter?: number;
-    constructor(message: string, status: number, retryAfter?: number);
+    readonly code?: AdminErrorCode;
+    constructor(message: string, status: number, retryAfter?: number, code?: string);
 }
 export type Env = 'live' | 'test';
 export type AgentStatus = 'draft' | 'published';
@@ -166,6 +191,31 @@ export interface DeliveryOutcome {
 }
 /** The Admin API client. Every method returns the parsed JSON body; failures
  *  throw AdminApiError. */
+/** Every transport the platform knows. Mirrors the server's `TransportType`
+ *  (`channels/types.ts`) — this package is standalone and cannot import it, so
+ *  `admin-sdk-channel-types.drift.test.ts` binds the two and fails CI if either
+ *  side gains a transport the other lacks. */
+export type ChannelTransportType = 'echo' | 'matrix' | 'telegram' | 'web' | 'activitypub' | 'internal-a2a' | 'discord' | 'slack' | 'nostr' | 'atproto' | 'sms' | 'email' | 'whatsapp' | 'messenger' | 'instagram' | 'line' | 'teams' | 'wechat' | 'wecom' | 'feishu' | 'dingtalk' | 'twitter' | 'xmpp' | 'qq' | 'kakao' | 'viber' | 'signal' | 'weibo' | 'alexa' | 'google-assistant' | 'voice';
+/** Transports `createChannel` accepts. `internal-a2a` is in the union but has
+ *  no adapter, so the server answers 400 — excluding it here turns a runtime
+ *  rejection into a compile error. */
+export type CreatableChannelType = Exclude<ChannelTransportType, 'internal-a2a'>;
+/** Credentials for a connector, sealed server-side as one AES-GCM blob.
+ *
+ *  `extra` is where the transports needing more than a token live — Twitter
+ *  OAuth 1.0a (`consumerKey`/`consumerSecret`/`accessToken`/`accessTokenSecret`),
+ *  Teams AAD (`appId`/`appPassword`), QQ (`appId` + Ed25519 seed), the WeChat
+ *  family's mint credentials. Per-transport field lists are documented in
+ *  https://pouchy.ai/docs/channel-setup; they are not modelled per-type here because the set
+ *  is operator-supplied and moves with each provider's own console. */
+export interface ChannelSecretInput {
+    /** Bot access token / API key used for outbound delivery. */
+    token?: string;
+    /** Inbound signing secret (e.g. Telegram `secret_token`, Matrix `hs_token`). */
+    inboundSecret?: string;
+    /** Extra named credentials for transports whose auth needs more than the pair above. */
+    extra?: Record<string, string>;
+}
 /** A durable run as the API returns it. Typed rather than `unknown` because
  *  the parked-run flow — read `status`, read `awaiting.token`, answer — is the
  *  SDK's most important interaction, and forcing a cast there would put the
@@ -511,13 +561,13 @@ export interface AdminClient {
         connectors: unknown[];
     }>;
     createChannel(input: {
-        type: string;
+        type: CreatableChannelType;
         agentId: string;
         env?: Env;
         config?: Record<string, unknown>;
         /** Connector credentials (bot token, signing secret, …) — stored
          *  encrypted, never returned. */
-        secret?: Record<string, unknown>;
+        secret?: ChannelSecretInput;
     }): Promise<{
         connector: {
             id: string;
@@ -603,7 +653,13 @@ export interface AdminClient {
      *  `awaiting.token` (also carried by the `agent.run_awaiting` webhook) and
      *  fences the decision against a stale or replayed answer. Without this call
      *  a parked run never resumes: it holds no lease and has left the platform's
-     *  due window by design. */
+     *  due window by design.
+     *
+     *  Both failures here are **409**; switch on `AdminApiError.code` to tell
+     *  them apart. `stale_token` — the run has moved on to a different question:
+     *  re-read it with `getRun` and answer the current `awaiting.token`.
+     *  `run_not_parked` — it is no longer awaiting anyone (someone else decided,
+     *  or it was cancelled): do NOT retry. */
     resumeRun(runId: string, input: {
         approved: boolean;
         token: string;
@@ -615,7 +671,13 @@ export interface AdminClient {
     }>;
     /** Deliver an external event to a run parked on one. `event` must equal the
      *  key the run is waiting for — a mismatch answers 409 `event_mismatch`, so a
-     *  webhook retry can tell "too late" from "rejected". */
+     *  webhook retry can tell "too late" from "rejected".
+     *
+     *  Read that verdict off `AdminApiError.code` (0.10.0; before that the field
+     *  was dropped and this advice was unfollowable). `event_mismatch` — the run
+     *  wants a DIFFERENT key, so your event is early or wrong: safe to retry
+     *  later. `run_not_waiting` — the run is not parked on an event at all, so
+     *  the wait already ended: stop retrying. */
     signalRun(runId: string, input: {
         event: string;
         payload?: unknown;

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.8.0';
+export const ADMIN_SDK_VERSION = '0.10.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;
@@ -55,9 +55,40 @@ export function requestDeadlineMs(method, path) {
         ? LONG_WORK_TIMEOUT_MS
         : DEFAULT_TIMEOUT_MS;
 }
+/** Machine-readable failure tags the Admin API puts on an error body, mirroring
+ *  the server's own list (`src/lib/server/platform/api-error-codes.ts`) and
+ *  drift-tested against it. APPEND-ONLY: these are documented as switchable, so
+ *  renaming or removing one breaks integrators.
+ *
+ *  Every member is a **409**. That is the whole reason this vocabulary is
+ *  published: on this plane the status line never disambiguates, so two of the
+ *  durable-run routes answer 409 for two entirely different reasons each, with
+ *  different recoveries. `code` is the only thing that tells them apart. */
+export const ADMIN_ERROR_CODES = [
+    'schedule_limit_reached',
+    'channel_limit_reached',
+    'webhook_limit_reached',
+    'run_limit_reached',
+    'reembed_required',
+    'run_terminal',
+    'run_not_parked',
+    'stale_token',
+    '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).
+ *  backoff in SECONDS on a 429 (undefined on every other failure); `code` is the
+ *  server's machine tag when it named one (undefined otherwise).
+ *
+ *  Why `code` exists: the Admin API's ten machine-readable failures are ALL on
+ *  409, so `status` cannot separate them and this package used to discard the
+ *  one field that can. Two routes are the point — `resumeRun` answers 409 for
+ *  `run_not_parked` (someone already decided; re-read, do not retry) or
+ *  `stale_token` (your token aged out; re-read for the current one and answer
+ *  again), and `signalRun` answers 409 for `run_not_waiting` or
+ *  `event_mismatch`. This package's own docs told callers to distinguish those,
+ *  which was not possible without switching on prose.
  *
  *  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
@@ -74,14 +105,27 @@ export function requestDeadlineMs(method, path) {
 export class AdminApiError extends Error {
     status;
     retryAfter;
-    constructor(message, status, retryAfter) {
+    code;
+    constructor(message, status, retryAfter, code) {
         super(message);
         this.name = 'AdminApiError';
         this.status = status;
         if (retryAfter !== undefined)
             this.retryAfter = retryAfter;
+        // Only a non-empty string. A body carrying `code: null` or `code: 42`
+        // must leave the property ABSENT rather than stamping a falsy value that
+        // a `switch (e.code)` would fall through on in a way the caller can't see.
+        if (typeof code === 'string' && code)
+            this.code = code;
     }
 }
+/** The `code` a non-2xx body named, or undefined. Kept beside `retryAfterFrom`
+ *  and equally defensive: the body is parsed with a `.catch(() => ({}))`, so
+ *  every field here is untrusted shape, not a typed response. */
+function codeFrom(body) {
+    const v = body?.code;
+    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.
  *
@@ -165,7 +209,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));
+            throw new AdminApiError(data?.error ?? `HTTP ${res.status}`, res.status, retryAfterFrom(res, data), codeFrom(data));
         return data;
     }
     return {

package/package.json

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