@pouchy_ai/admin-sdk 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.25.0 — 2026-08-09
+
+- **`ADMIN_ERROR_CODES` gains the two schedule-PATCH refusals** (additive;
+  nothing renamed or removed): `one_shot_spent` (409 — this one-shot schedule
+  already fired; create a new one instead of re-enabling it) and `ghost_row`
+  (409 — a legacy incomplete row that can never fire; delete it and create a
+  new schedule). Both have been emitted by `updateSchedule` refusals on the
+  server (`one_shot_spent` for a long time, `ghost_row` since the ghost-row
+  guard landed) but were absent from every published vocabulary — an
+  integrator switching on `AdminApiError.code` per this package's own advice
+  fell through on codes no doc named. `updateSchedule`'s docstring now lists
+  all three 409 codes. Existing `code` handling is unaffected — the type was
+  already open (`string & {}`), so this widens autocomplete/docs, not the
+  wire.
+
+## 0.24.2 — 2026-08-08
+
+- **Docs-only: `extractJson` failure vocabulary gains `request_invalid`**
+  (server-side change; no SDK code moved — the code rides the open
+  `AdminErrorCode` string arm). The provider rejecting the REQUEST itself —
+  an unknown `model` (provider 404), or a parameter outside the provider's
+  validation (422) — now surfaces as `code: 'request_invalid'` with HTTP 400
+  and the provider's own message, instead of `unavailable`, whose documented
+  recovery ("back off and retry") sent integrators into an infinite backoff
+  loop for a request that can never succeed (e.g. a typo'd model name).
+  `schema_invalid` still covers provider-rejected schemas; `unavailable` is
+  now reliably transient. Also: `schemaName` is validated locally against the
+  provider's identifier grammar (letters/digits/underscores/dashes), so a bad
+  name is an immediate 400 naming `schemaName` rather than a provider 400
+  mislabelled `schema_invalid`.
+
 ## 0.24.1 — 2026-08-08
 
 - **Docs-only correction for `synthesizeSpeech`** (no code change): the rate

package/README.md

@@ -148,6 +148,8 @@ const { data } = await admin.extractJson<{ items: { kind: string; summary: strin
 
 Failures are typed rather than prose, so the recoveries are distinguishable:
 `schema_invalid` (400 — fix the schema; retrying verbatim cannot help),
+`request_invalid` (400 — the provider rejected the request itself: an unknown
+`model`, or a parameter outside the provider's validation; fix the request),
 `unavailable` (5xx — transient, back off), and `invalid_json` (502 — a
 completion arrived but did not parse or satisfy the schema; the error carries
 `raw`, the text actually returned). Tokens roll into the project's month usage

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.24.1";
+export declare const ADMIN_SDK_VERSION = "0.25.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
@@ -59,7 +59,7 @@ export interface AdminClientOptions {
  *  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"];
+export declare const ADMIN_ERROR_CODES: readonly ["schedule_limit_reached", "one_shot_spent", "ghost_row", "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`. */
@@ -69,7 +69,7 @@ export type AdminErrorCode = (typeof ADMIN_ERROR_CODES)[number] | (string & {});
  *  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
+ *  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
  *  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
@@ -679,9 +679,12 @@ export interface AdminClient {
      *
      *  Failures are typed rather than prose, which is the point:
      *  `schema_invalid` (400 — fix the schema, retrying verbatim cannot help),
-     *  `unavailable` (5xx — transient, back off), `invalid_json` (502 — a
-     *  completion arrived but did not parse or did not satisfy the schema; the
-     *  error carries `raw`, the text actually returned).
+     *  `request_invalid` (400 — the provider rejected the request itself:
+     *  an unknown `model`, or a parameter outside the provider's validation;
+     *  fix the request, retrying verbatim cannot help), `unavailable` (5xx —
+     *  transient, back off), `invalid_json` (502 — a completion arrived but
+     *  did not parse or did not satisfy the schema; the error carries `raw`,
+     *  the text actually returned).
      *
      *  `reasoningEffort` is the thinking budget, default `'low'`. It matters more
      *  than it sounds for extraction: the shared one-shot floor is `'minimal'`,
@@ -922,6 +925,11 @@ export interface AdminClient {
     getSchedule(scheduleId: string): Promise<{
         schedule: unknown;
     }>;
+    /** PATCH a schedule. Re-enabling can refuse with 409 — switch on
+     *  `AdminApiError.code`: `one_shot_spent` (this one-shot already fired;
+     *  create a new schedule), `ghost_row` (a legacy incomplete row that can
+     *  never fire; delete it), or `schedule_limit_reached` (the enabled-count
+     *  ceiling). */
     updateSchedule(scheduleId: string, patch: Record<string, unknown>): Promise<{
         schedule: 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.24.1';
+export const ADMIN_SDK_VERSION = '0.25.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;
@@ -71,6 +71,8 @@ export function requestDeadlineMs(method, path) {
  *  different recoveries. `code` is the only thing that tells them apart. */
 export const ADMIN_ERROR_CODES = [
     'schedule_limit_reached',
+    'one_shot_spent',
+    'ghost_row',
     'channel_limit_reached',
     'webhook_limit_reached',
     'run_limit_reached',
@@ -86,7 +88,7 @@ export const ADMIN_ERROR_CODES = [
  *  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
+ *  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
  *  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

package/package.json

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