@shogo-ai/voice 1.10.0 → 2.4.1

package/dist/index.d.cts

@@ -1,5 +1,6 @@
-import { E as Expressivity } from './types-W9y6eMj3.cjs';
-export { A as AUDIO_TAGS, a as AUDIO_TAG_GROUPS, b as AudioTag, c as AudioTagGroup, C as CONVAI_SUPPORTED_TTS_MODELS, d as CONVAI_TTS_MODEL_FALLBACK, e as Companion, f as CompanionStore, g as ComposeMusicParams, h as ConvaiClientTool, i as CreateAgentParams, j as CreateCompanionBody, D as DEFAULT_ALLOWED_TAGS, k as DEFAULT_ELEVENLABS_BASE_URL, l as DEFAULT_MUSIC_MODEL, m as DEFAULT_VOICE_SETTINGS, n as EXPRESSIVITY_BLOCK_CLOSE, o as EXPRESSIVITY_BLOCK_OPEN, p as EXPRESSIVITY_OPTIONS, q as ElevenLabsApiError, r as ElevenLabsClient, s as ElevenLabsClientConfig, t as ElevenLabsRequestOptions, u as ElevenLabsResponse, M as MEMORY_CLIENT_TOOLS, P as PatchAgentParams, v as PatchCompanionBody, T as TextToSpeechParams, w as TtsPreviewBody, V as VoiceMemoryStore, x as VoiceSettings, y as VoiceUser, z as buildPreviewLine, B as composeExpressivityBlock, F as normalizeAudioTags, G as normalizeExpressivity, H as normalizeVoiceSettings, I as readAudioTags, J as readExpressivity, K as readVoiceSettings, L as resolveConvaiTtsModel, N as stripAudioTags, O as stripExpressivityBlock } from './types-W9y6eMj3.cjs';
+import { b as Expressivity } from './types-CadjTXNH.cjs';
+export { A as AUDIO_TAGS, c as AUDIO_TAG_GROUPS, d as AudioTag, e as AudioTagGroup, f as CONVAI_SUPPORTED_TTS_MODELS, g as CONVAI_TTS_MODEL_FALLBACK, h as Companion, C as CompanionStore, i as ComposeMusicParams, j as ConvaiClientTool, k as ConvaiTtsModelResolution, l as CreateAgentParams, m as CreateCompanionBody, D as DEFAULT_ALLOWED_TAGS, n as DEFAULT_ELEVENLABS_BASE_URL, o as DEFAULT_MUSIC_MODEL, p as DEFAULT_SOUND_GENERATION_MODEL, q as DEFAULT_SPEECH_TO_TEXT_MODEL, r as DEFAULT_STS_MODEL, s as DEFAULT_TTS_MODEL, t as DEFAULT_VOICE_SETTINGS, u as EXPRESSIVITY_BLOCK_CLOSE, v as EXPRESSIVITY_BLOCK_OPEN, w as EXPRESSIVITY_OPTIONS, x as ElevenLabsApiError, E as ElevenLabsClient, y as ElevenLabsClientConfig, z as ElevenLabsRequestOptions, B as ElevenLabsResponse, M as MEMORY_CLIENT_TOOLS, P as PatchAgentParams, F as PatchCompanionBody, S as SoundEffectsParams, G as SpeechToSpeechParams, T as TTS_FALLBACK_MODEL, H as TextToSpeechParams, I as TextToSpeechResult, J as TranscribeParams, K as TranscriptionResult, L as TtsPreviewBody, N as VOICE_SOUND_GENERATION_MODEL_IDS, O as VOICE_SPEECH_TO_TEXT_MODEL_IDS, Q as VOICE_STS_MODEL_IDS, R as VOICE_TTS_MODELS, U as VOICE_TTS_MODEL_IDS, a as VoiceMemoryStore, W as VoiceSettings, X as VoiceTtsModel, V as VoiceUser, Y as buildPreviewLine, Z as composeExpressivityBlock, _ as getVoiceTtsModel, $ as isModelRelatedTtsFailure, a0 as normalizeAudioTags, a1 as normalizeExpressivity, a2 as normalizeVoiceSettings, a3 as readAudioTags, a4 as readExpressivity, a5 as readVoiceSettings, a6 as resolveConvaiTtsModel, a7 as resolveConvaiTtsModelDetailed, a8 as stripAudioTags, a9 as stripExpressivityBlock } from './types-CadjTXNH.cjs';
+export { LiveAudioConfig, LiveErrorEvent, LiveResponsesDelegation, LiveSession, LiveSessionClosedEvent, LiveSessionConfig, LiveSessionEvent, LiveSessionHandlers, LiveSessionStartedEvent, LiveSessionUsageUpdatedEvent, LiveWebRtcSession, ShogoLiveClient, ShogoLiveClientOptions } from './live/client.cjs';
 
 /**
  * System-prompt composer for the voice agent.
@@ -44,6 +45,375 @@ declare function extractBasePrompt(prompt: string): string;
  */
 declare function composeAgentPrompt(basePrompt: string, options?: ComposeAgentPromptOptions): string;
 
+/**
+ * The voice op registry.
+ *
+ * Every ElevenLabs media endpoint we expose is one row here: its upstream
+ * path, its transport, who may call it, how big a body it may take, and what
+ * it costs. Route handlers, proxy handlers and the SDK all read this table
+ * instead of being hand-written per endpoint — adding an op is a row and a
+ * test, never a new route file.
+ *
+ * Three consumers:
+ *   - `@shogo-ai/sdk/voice/server` (`handlers.op`) — BYO mode + proxy mode
+ *   - `@shogo-ai/sdk/voice/route/op` — the drop-in route modules
+ *   - `apps/api/src/routes/voice-media.ts` — the hosted `/api/voice/op/:opId`
+ *
+ * Deliberately free of Node and DOM-only APIs: this module is imported by
+ * the browser-safe entry point.
+ */
+/**
+ * How a request body travels in and a response body travels out:
+ *   - `json-binary`      JSON in, audio bytes out (TTS, music, sound effects)
+ *   - `json-json`        JSON in, JSON out (TTS with timestamps, listings)
+ *   - `multipart-binary` multipart in, audio bytes out (speech-to-speech)
+ *   - `multipart-json`   multipart in, JSON out (speech-to-text)
+ *
+ * The adapters live next to the executor; a row only names its transport.
+ */
+type VoiceOpTransport = 'json-binary' | 'json-json' | 'multipart-binary' | 'multipart-json';
+/**
+ * Project permission the caller needs. Kept as a literal union rather than an
+ * import from `@shogo/authz` so this package stays free of server deps; the
+ * hosted route widens it to `Permission` where it authorizes.
+ */
+type VoiceOpPermission = 'project:read' | 'project:update';
+/** What one unit of an op's cost is measured in. */
+type VoiceOpCostUnit = 'character' | 'second' | 'request';
+interface VoiceOpCost {
+    /** Metering unit. */
+    unit: VoiceOpCostUnit;
+    /** How many units one `character` / `second` / `request` is worth. */
+    per: number;
+}
+interface VoiceOp {
+    id: string;
+    method: 'GET' | 'POST';
+    /** Canonical hosted path: `/voice/op/<id>`. */
+    hostedPath: `/voice/${string}`;
+    /**
+     * A path a shipped client already calls. Proxy mode forwards here instead
+     * of {@link hostedPath} so an SDK upgrade never breaks a running pod.
+     */
+    legacyHostedPath?: `/voice/${string}`;
+    /** Upstream ElevenLabs path, `{name}` filled from {@link pathParams}. */
+    upstreamPath: string;
+    /** Path params the caller supplies (body field or query param). */
+    pathParams?: readonly string[];
+    transport: VoiceOpTransport;
+    permission: VoiceOpPermission;
+    /** Plan gate name, when the op is not on every plan. */
+    planGate?: string;
+    /** Request body cap; larger → 413. */
+    maxBodyBytes: number;
+    /**
+     * Metering unit. A row without `cost` must be `byoOnly` — you cannot add an
+     * op without deciding who pays for it.
+     */
+    cost?: VoiceOpCost;
+    /**
+     * Never runs on Shogo's pooled key (cloning, dubbing — they write state onto
+     * the account and need a per-project voice registry).
+     */
+    byoOnly?: boolean;
+    /**
+     * Use a typed {@link ElevenLabsClient} method instead of the generic
+     * `request()` passthrough. Only the ops that need model fallback (TTS) or
+     * body composition (music) set this.
+     */
+    call?: 'textToSpeech' | 'composeMusic';
+    /** Accepted model ids; an unknown one is a 400, never a silent clamp. */
+    models?: readonly string[];
+    /** Model used for the upstream call when the caller sends none. */
+    defaultModel?: string;
+    /** Fall back to the project's default agent voice when none is given. */
+    defaultVoiceId?: boolean;
+    /** Caller field → upstream field. Anything absent here is not forwarded. */
+    forward?: Readonly<Record<string, string>>;
+    /** Caller fields that must be present (before mapping). */
+    required?: readonly string[];
+    /** Query params forwarded upstream. */
+    queryForward?: readonly string[];
+    /** Upstream response headers worth passing through. */
+    responseHeaders?: readonly string[];
+    /** `Accept` sent upstream (and used when ElevenLabs sends no content-type). */
+    accept?: string;
+    /** Error label for an upstream failure; defaults to `${id} failed`. */
+    errorLabel?: string;
+    /**
+     * Extra body check the declarative fields cannot express (e.g. music's
+     * prompt XOR compositionPlan). Returns an error message or `null`.
+     */
+    validate?: (fields: Record<string, unknown>) => string | null;
+}
+/**
+ * The registry. Order is the order unknown-op errors list ids in.
+ *
+ * `as const satisfies` is what makes an op cost exactly one row: the ids are
+ * derived from the table ({@link VoiceOpId}, {@link VOICE_OP_IDS}) instead of
+ * being listed a second time, while `satisfies` still type-checks every field.
+ */
+declare const VOICE_OPS: readonly [{
+    readonly id: "text-to-speech";
+    readonly method: "POST";
+    readonly hostedPath: "/voice/op/text-to-speech";
+    readonly legacyHostedPath: "/voice/tts";
+    readonly upstreamPath: "/v1/text-to-speech/{voiceId}";
+    readonly pathParams: readonly ["voiceId"];
+    readonly transport: "json-binary";
+    readonly call: "textToSpeech";
+    readonly permission: "project:read";
+    readonly maxBodyBytes: number;
+    readonly cost: {
+        readonly unit: "character";
+        readonly per: 1;
+    };
+    readonly models: readonly string[];
+    readonly defaultModel: "eleven_v4_turbo";
+    readonly defaultVoiceId: true;
+    readonly forward: {
+        readonly text: "text";
+        readonly voiceId: "voice_id";
+        readonly modelId: "model_id";
+        readonly voiceSettings: "voice_settings";
+    };
+    readonly required: readonly ["text"];
+    readonly responseHeaders: readonly ["x-tts-model-used", "x-tts-model-requested", "warning"];
+    readonly accept: "audio/mpeg";
+    readonly errorLabel: "TTS failed";
+}, {
+    readonly id: "text-to-speech-with-timestamps";
+    readonly method: "POST";
+    readonly hostedPath: "/voice/op/text-to-speech-with-timestamps";
+    readonly upstreamPath: "/v1/text-to-speech/{voiceId}/with-timestamps";
+    readonly pathParams: readonly ["voiceId"];
+    readonly transport: "json-json";
+    readonly permission: "project:read";
+    readonly maxBodyBytes: number;
+    readonly cost: {
+        readonly unit: "character";
+        readonly per: 1;
+    };
+    readonly models: readonly string[];
+    readonly defaultModel: "eleven_v4_turbo";
+    readonly defaultVoiceId: true;
+    readonly forward: {
+        readonly text: "text";
+        readonly voiceId: "voice_id";
+        readonly modelId: "model_id";
+        readonly voiceSettings: "voice_settings";
+        readonly outputFormat: "output_format";
+    };
+    readonly required: readonly ["text"];
+    readonly accept: "application/json";
+}, {
+    readonly id: "speech-to-speech";
+    readonly method: "POST";
+    readonly hostedPath: "/voice/op/speech-to-speech";
+    readonly upstreamPath: "/v1/speech-to-speech/{voiceId}";
+    readonly pathParams: readonly ["voiceId"];
+    readonly transport: "multipart-binary";
+    readonly permission: "project:read";
+    readonly maxBodyBytes: number;
+    readonly cost: {
+        readonly unit: "second";
+        readonly per: 1;
+    };
+    readonly models: readonly string[];
+    readonly defaultModel: "eleven_multilingual_sts_v2";
+    readonly defaultVoiceId: true;
+    readonly forward: {
+        readonly audio: "audio";
+        readonly voiceId: "voice_id";
+        readonly modelId: "model_id";
+        readonly voiceSettings: "voice_settings";
+        readonly outputFormat: "output_format";
+        readonly fileFormat: "file_format";
+        readonly seed: "seed";
+        readonly removeBackgroundNoise: "remove_background_noise";
+    };
+    readonly required: readonly ["audio"];
+    readonly accept: "audio/mpeg";
+}, {
+    readonly id: "speech-to-text";
+    readonly method: "POST";
+    readonly hostedPath: "/voice/op/speech-to-text";
+    readonly upstreamPath: "/v1/speech-to-text";
+    readonly transport: "multipart-json";
+    readonly permission: "project:read";
+    readonly maxBodyBytes: number;
+    readonly cost: {
+        readonly unit: "second";
+        readonly per: 1;
+    };
+    readonly models: readonly string[];
+    readonly defaultModel: "scribe_v1";
+    readonly forward: {
+        readonly file: "file";
+        readonly modelId: "model_id";
+        readonly languageCode: "language_code";
+        readonly diarize: "diarize";
+        readonly tagAudioEvents: "tag_audio_events";
+        readonly numSpeakers: "num_speakers";
+    };
+    readonly required: readonly ["file"];
+    readonly accept: "application/json";
+}, {
+    readonly id: "sound-generation";
+    readonly method: "POST";
+    readonly hostedPath: "/voice/op/sound-generation";
+    readonly upstreamPath: "/v1/sound-generation";
+    readonly transport: "json-binary";
+    readonly permission: "project:read";
+    readonly maxBodyBytes: number;
+    readonly cost: {
+        readonly unit: "second";
+        readonly per: 1;
+    };
+    readonly models: readonly string[];
+    readonly defaultModel: "eleven_text_to_sound_v2";
+    readonly forward: {
+        readonly text: "text";
+        readonly durationSeconds: "duration_seconds";
+        readonly promptInfluence: "prompt_influence";
+        readonly loop: "loop";
+        readonly modelId: "model_id";
+    };
+    readonly queryForward: readonly ["output_format"];
+    readonly required: readonly ["text"];
+    readonly accept: "audio/mpeg";
+}, {
+    readonly id: "music";
+    readonly method: "POST";
+    readonly hostedPath: "/voice/op/music";
+    readonly legacyHostedPath: "/voice/music";
+    readonly upstreamPath: "/v1/music";
+    readonly transport: "json-binary";
+    readonly call: "composeMusic";
+    readonly permission: "project:read";
+    readonly maxBodyBytes: number;
+    readonly cost: {
+        readonly unit: "second";
+        readonly per: 1;
+    };
+    readonly models: readonly ["music_v1"];
+    readonly defaultModel: "music_v1";
+    readonly forward: {
+        readonly prompt: "prompt";
+        readonly compositionPlan: "composition_plan";
+        readonly musicLengthMs: "music_length_ms";
+        readonly modelId: "model_id";
+        readonly forceInstrumental: "force_instrumental";
+        readonly outputFormat: "output_format";
+    };
+    readonly accept: "audio/mpeg";
+    readonly errorLabel: "Music generation failed";
+    readonly validate: (fields: Record<string, unknown>) => "Provide exactly one of `prompt` or `compositionPlan`" | null;
+}, {
+    readonly id: "voices";
+    readonly method: "GET";
+    readonly hostedPath: "/voice/op/voices";
+    readonly upstreamPath: "/v1/voices";
+    readonly transport: "json-json";
+    readonly permission: "project:read";
+    readonly maxBodyBytes: 0;
+    readonly cost: {
+        readonly unit: "request";
+        readonly per: 1;
+    };
+    readonly queryForward: readonly ["page_size", "search", "voice_type", "category", "next_page_token"];
+    readonly accept: "application/json";
+}, {
+    readonly id: "models";
+    readonly method: "GET";
+    readonly hostedPath: "/voice/op/models";
+    readonly upstreamPath: "/v1/models";
+    readonly transport: "json-json";
+    readonly permission: "project:read";
+    readonly maxBodyBytes: 0;
+    readonly cost: {
+        readonly unit: "request";
+        readonly per: 1;
+    };
+    readonly accept: "application/json";
+}];
+/** Every op id, in registry order. */
+declare const VOICE_OP_IDS: readonly string[];
+/** The literal union of registry ids. */
+type VoiceOpId = (typeof VOICE_OPS)[number]['id'];
+/** Look up a row by id. */
+declare function getVoiceOp(id: string | null | undefined): VoiceOp | undefined;
+/**
+ * The hosted path a client should call for this op. Proxy mode uses
+ * {@link VoiceOp.legacyHostedPath} when a client may already be pinned to it.
+ */
+declare function voiceOpForwardPath(op: VoiceOp): string;
+/** Which body adapter a row uses. */
+declare function voiceOpIsMultipart(op: VoiceOp): boolean;
+/** Whether the op's response is audio bytes. */
+declare function voiceOpReturnsAudio(op: VoiceOp): boolean;
+/** Fill `{param}` placeholders in {@link VoiceOp.upstreamPath}. */
+declare function voiceOpUpstreamPath(op: VoiceOp, params: Readonly<Record<string, string>>): string | {
+    error: string;
+};
+/**
+ * Reject a caller who has no key for this op. A `byoOnly` row never runs on
+ * the pooled key; `credential` says which key the request would have used.
+ */
+declare function voiceOpCredentialError(op: VoiceOp, credential: 'pooled' | 'byo'): {
+    status: number;
+    error: string;
+    detail: string;
+} | null;
+/**
+ * Validate + normalize a JSON body against a row: whitelist `forward`, check
+ * `required`, resolve the model, run the row's own `validate`.
+ *
+ * Returns the **caller-shaped** fields (camelCase), not the upstream body —
+ * mapping happens in {@link voiceOpUpstreamBody}.
+ */
+declare function parseVoiceOpJsonBody(op: VoiceOp, raw: unknown): {
+    ok: true;
+    fields: Record<string, unknown>;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+    detail?: string;
+    allowed?: readonly string[];
+};
+/**
+ * Validate + normalize a multipart body: the same whitelist/required rules,
+ * plus a `File` check on every required part (an `audio` part that is really
+ * a text field is the caller's bug, not ElevenLabs').
+ *
+ * `fields` carries the caller-shaped values the parser read — the path params
+ * among them. They are dropped from the rebuilt form (repeating them makes
+ * ElevenLabs reject the upload), so this is the only way a `voiceId` form part
+ * reaches {@link voiceOpPathParams}; ignoring it would send the request to
+ * the project default voice and come back 200 with the wrong voice.
+ */
+declare function parseVoiceOpForm(op: VoiceOp, form: FormData): {
+    ok: true;
+    form: FormData;
+    fields: Record<string, unknown>;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+    detail?: string;
+    allowed?: readonly string[];
+};
+/**
+ * Map caller fields onto the upstream JSON body (camelCase → snake_case) and
+ * drop the path params, which travel in the URL.
+ */
+declare function voiceOpUpstreamBody(op: VoiceOp, fields: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/** Path params for a row, taken from the body first and the query second. */
+declare function voiceOpPathParams(op: VoiceOp, fields: Readonly<Record<string, unknown>>, query: {
+    get(name: string): string | null;
+}): Record<string, string>;
+
 /**
  * Thin `fetch`-based Twilio REST client used by Mode A of the SDK's
  * `TelephonyClient` (self-hosted / BYO keys). Intentionally duplicates
@@ -429,4 +799,4 @@ declare class MockTelephonyClient implements TelephonyClient {
  */
 declare function isVoiceMockEnv(): boolean;
 
-export { type AvailableNumber, type ComposeAgentPromptOptions, type CreateTelephonyOptions, DEFAULT_MEMORY_BLOCK, DEFAULT_TWILIO_BASE_URL, DirectTelephonyClient, type DirectTelephonyOptions, Expressivity, HostedRuntimeTokenClient, type HostedRuntimeTokenOptions, HostedTelephonyClient, type HostedTelephonyOptions, type IncomingNumber, MockTelephonyClient, type OutboundCallOptions, type OutboundCallResult, type ProvisionNumberOptions, type ProvisionNumberResult, type ReleaseNumberResult, TelephonyApiError, type TelephonyClient, TelephonyConfigError, TwilioApiError, TwilioClient, type TwilioClientConfig, type VoiceUsageRange, type VoiceUsageSummary, composeAgentPrompt, createTelephonyClient, extractBasePrompt, isVoiceMockEnv, stripMemoryBlock };
+export { type AvailableNumber, type ComposeAgentPromptOptions, type CreateTelephonyOptions, DEFAULT_MEMORY_BLOCK, DEFAULT_TWILIO_BASE_URL, DirectTelephonyClient, type DirectTelephonyOptions, Expressivity, HostedRuntimeTokenClient, type HostedRuntimeTokenOptions, HostedTelephonyClient, type HostedTelephonyOptions, type IncomingNumber, MockTelephonyClient, type OutboundCallOptions, type OutboundCallResult, type ProvisionNumberOptions, type ProvisionNumberResult, type ReleaseNumberResult, TelephonyApiError, type TelephonyClient, TelephonyConfigError, TwilioApiError, TwilioClient, type TwilioClientConfig, VOICE_OPS, VOICE_OP_IDS, type VoiceOp, type VoiceOpCost, type VoiceOpCostUnit, type VoiceOpId, type VoiceOpPermission, type VoiceOpTransport, type VoiceUsageRange, type VoiceUsageSummary, composeAgentPrompt, createTelephonyClient, extractBasePrompt, getVoiceOp, isVoiceMockEnv, parseVoiceOpForm, parseVoiceOpJsonBody, stripMemoryBlock, voiceOpCredentialError, voiceOpForwardPath, voiceOpIsMultipart, voiceOpPathParams, voiceOpReturnsAudio, voiceOpUpstreamBody, voiceOpUpstreamPath };