@pouchy_ai/admin-sdk 0.23.0 → 0.24.1

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 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):
+  `POST /v1/admin/utility/tts`. Text → a spoken-audio mp3 FILE, OUTSIDE the
+  companion and OUTSIDE a realtime `/call` — the audio sibling of `extractJson`.
+  Stateless (no session, no persona, no memory); the voice is a catalog id
+  (`std_…` / `hd_…`) or `providerVoiceId` from `listVoices()`, the same id used
+  for a call's voice, restricted to enabled catalog rows + the built-in OpenAI
+  roster. Returns `{ data: { audioBase64, mimeType, format, voiceId, provider,
+  model }, usage: { characterCount } }`; failures are typed
+  (`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 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
 
 - **`ChannelTransportType` grows 6 members** (additive; nothing renamed or

package/README.md

@@ -153,6 +153,35 @@ 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
 like any other model call.
 
+### Spoken audio — use `synthesizeSpeech`, not `/call`
+
+The audio sibling of `extractJson`: text → a downloadable **mp3 file**, OUTSIDE
+the companion and OUTSIDE a realtime call. `/call` is live ConvAI (a WebRTC
+session); when you need an audio **file** for a headless / Ops job — a reference
+clip for a downstream video / lip-sync API, a pre-rendered notification — this
+is the stateless path.
+
+```ts
+const { data, usage } = await admin.synthesizeSpeech({
+  text: 'Hey — just wanted to share this moment with you.',
+  voice: 'hd_ByhETIclHirOlWnWKhHc' // a catalog id OR providerVoiceId from listVoices()
+});
+// data.audioBase64 is the mp3 — decode and persist it (never hand a provider URL
+// to a client). In Node: Buffer.from(data.audioBase64, 'base64'); in a browser:
+// Uint8Array.from(atob(data.audioBase64), (c) => c.charCodeAt(0)).
+console.log(data.mimeType, data.voiceId, data.provider, usage.characterCount);
+```
+
+`voice` is the **same id you pass to a call's voice** (from `listVoices()`),
+restricted to enabled catalog rows plus the built-in OpenAI roster — so the Ops
+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, 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 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
 def reached) and `truncated`. A knob only binds a running agent once the def
@@ -307,6 +336,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.23.0";
+export declare const ADMIN_SDK_VERSION = "0.24.1";
 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
@@ -711,6 +711,44 @@ export interface AdminClient {
             completionTokens: number;
         };
     }>;
+    /** Text → a spoken-audio FILE, OUTSIDE the companion and OUTSIDE a realtime
+     *  call. The audio sibling of `extractJson`: stateless (no session, no
+     *  persona, no memory), one synthesis call, a downloadable clip back. Use it
+     *  for headless / Ops audio — e.g. a reference clip for a downstream
+     *  video / lip-sync API — where `/call` (live ConvAI) does not fit.
+     *
+     *  `voice` is a catalog id (`std_…` / `hd_…`) or a `providerVoiceId` from
+     *  `listVoices()` — the SAME id you pass to a call's voice — restricted to
+     *  enabled catalog rows plus the built-in OpenAI roster. `data.audioBase64`
+     *  is the mp3 bytes; decode and persist them (never hand a provider URL to a
+     *  client). Only `mp3` is produced in v1.
+     *
+     *  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, 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 the shared per-IP utility rate
+     *  limit — there is no separate platform credit rate. */
+    synthesizeSpeech(input: {
+        text: string;
+        voice: string;
+        format?: 'mp3';
+        model?: string;
+    }): Promise<{
+        data: {
+            audioBase64: string;
+            mimeType: string;
+            format: 'mp3';
+            voiceId: string;
+            provider: 'openAI' | 'elevenLabs';
+            model: string;
+        };
+        usage: {
+            characterCount: number;
+        };
+    }>;
     deleteKnowledge(docId: string): Promise<{
         deleted: boolean;
     }>;

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.23.0';
+export const ADMIN_SDK_VERSION = '0.24.1';
 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;
@@ -248,6 +248,7 @@ export function createAdminClient(opts) {
         ingestKnowledgeUrl: (input) => request('POST', '/knowledge/url', input),
         searchKnowledge: (query) => request('POST', '/knowledge/search', { query }),
         extractJson: (input) => request('POST', '/utility/json', input),
+        synthesizeSpeech: (input) => request('POST', '/utility/tts', input),
         deleteKnowledge: (id) => request('DELETE', `/knowledge/${encodeURIComponent(id)}`),
         listSkills: () => request('GET', '/skills'),
         installSkill: (input) => request('POST', '/skills', input),

package/package.json

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