@pouchy_ai/admin-sdk 0.24.0 → 0.24.2

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 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
+  limit on `/v1/admin/utility/tts` is the shared **per-IP** utility bucket,
+  not per-project — the 0.24.0 notes (and the README/docstring) claimed
+  per-project keying the server never had (CR-404). Also documents that
+  `unavailable` (503) now additionally covers a temporarily unreachable voice
+  catalog (retry), and that a `model` from the other provider's namespace is
+  silently ignored in favour of the provider default (server-side CR-404/
+  CR-410 fixes; an unknown model within the right namespace still surfaces as
+  `provider_error` 502).
+
 ## 0.24.0 — 2026-08-08
 
 - **New method `synthesizeSpeech`** (additive; nothing renamed or removed):
@@ -15,7 +43,8 @@ All notable changes to `@pouchy_ai/admin-sdk` are documented here.
   (`voice_not_found`, `text_too_long`, `unsupported_format`, `unavailable`,
   `provider_error`). Synthesis bills on your provider account like the other
   voice planes — no separate platform credit rate; bounded by an input cap +
-  a per-project rate limit.
+  a rate limit (documented at release as per-project; corrected in 0.24.1 —
+  the bucket keys per client IP).
 
 ## 0.23.0 — 2026-08-08
 

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
@@ -177,9 +179,10 @@ restricted to enabled catalog rows plus the built-in OpenAI roster — so the Op
 sample and the live call use one authoritative voice. Only `mp3` is produced in
 v1. Failures are typed: `voice_not_found` (404), `text_too_long` (413),
 `unsupported_format` (400), `unavailable` (503 — no TTS provider configured for
-that voice), `provider_error` (502). Synthesis bills on your provider account
+that voice, or the voice catalog is temporarily unreachable; retry),
+`provider_error` (502). Synthesis bills on your provider account
 like the other voice planes — there is no separate platform credit rate; it is
-bounded by an input cap and a per-project rate limit.
+bounded by an input cap and the shared per-IP utility rate limit.
 
 Every skill knob (`setSkillRate`, `setSkillDailyCap`, `grantSkill`) returns
 `SkillKnobResult<T>` — the knob you set plus `reprovisioned` (instances the new
@@ -335,6 +338,7 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | Data capabilities | `listCapabilities` (heads + MASKED signing status) · `publishCapability` (TYPED `CapabilityDeclaration`; immutable next version, idempotent on content) · `setCapabilityDisabled` (per-capability live revoke) · `listCapabilityVersions` (history; rollback = republish an old declaration) · `testReadCapability` · `testActionCapability({ confirmDuplicates: true, … })` (REAL deliveries incl. intentional duplicates — 428 without consent) · `listActionExecutions` (the durable Action journal, incl. `authorizedBy: 'automation'`) · `listEventReceipts` (receipts + wake trail) |
 | Webhooks | `listWebhooks` · `createWebhook` · `updateWebhook` · `rotateWebhookSecret` · `deleteWebhook` · `testWebhook` · `redeliverWebhook` |
 | Reporting | `getUsage` · `getUsageHistory` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
+| Utilities | `extractJson` (structured JSON from prose, schema-shaped) · `synthesizeSpeech` (short TTS clip in a catalog voice, base64 mp3) |
 | Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |
 
 Channel types are checked at compile time: `createChannel` takes a

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.24.0";
+export declare const ADMIN_SDK_VERSION = "0.24.2";
 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
@@ -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'`,
@@ -725,11 +728,12 @@ export interface AdminClient {
      *
      *  Failures are typed, not audio: `voice_not_found` (404),
      *  `text_too_long` (413), `unsupported_format` (400), `unavailable` (503 —
-     *  no TTS provider configured for that voice), `provider_error` (502).
+     *  no TTS provider configured for that voice, or the voice catalog is
+     *  temporarily unreachable; retry), `provider_error` (502).
      *
      *  Synthesis bills on your provider account (like the platform voice
-     *  planes), bounded by an input cap and a per-project rate limit — there is
-     *  no separate platform credit rate. */
+     *  planes), bounded by an input cap and the shared per-IP utility rate
+     *  limit — there is no separate platform credit rate. */
     synthesizeSpeech(input: {
         text: string;
         voice: string;

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.0';
+export const ADMIN_SDK_VERSION = '0.24.2';
 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;

package/package.json

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