@shogo-ai/voice 1.10.0 → 2.4.1

package/README.md

@@ -17,6 +17,95 @@ Native UI primitives.
 | `@shogo-ai/voice/native` | React Native equivalents (Expo). |
 | `@shogo-ai/voice/route/*` | Standard `(Request) => Response` route handlers. |
 
+## Media ops: one registry, no per-endpoint code
+
+`VOICE_OPS` (from `@shogo-ai/voice`) is the registry of every ElevenLabs media
+endpoint the SDK exposes. A row carries the upstream path, the transport
+(`json-binary`, `json-json`, `multipart-binary`, `multipart-json`), the project
+permission, the body limit, the model list and the metering unit. Handlers read
+that table — there is no hand-written route per endpoint.
+
+| Op | Transport | Upstream |
+| --- | --- | --- |
+| `text-to-speech` | JSON → audio | `POST /v1/text-to-speech/{voiceId}` |
+| `text-to-speech-with-timestamps` | JSON → JSON | `POST /v1/text-to-speech/{voiceId}/with-timestamps` |
+| `speech-to-speech` | multipart → audio | `POST /v1/speech-to-speech/{voiceId}` |
+| `speech-to-text` | multipart → JSON | `POST /v1/speech-to-text` |
+| `sound-generation` | JSON → audio | `POST /v1/sound-generation` |
+| `music` | JSON → audio | `POST /v1/music` |
+| `voices` | JSON → JSON | `GET /v1/voices` |
+| `models` | JSON → JSON | `GET /v1/models` |
+
+One route file serves all of them, present and future:
+
+```ts
+// app/api/voice/op/[opId]+api.ts
+export { GET, POST } from '@shogo-ai/sdk/voice/route/op'
+```
+
+`handlers.op(req, opId)` is the same thing without a file convention. In proxy
+mode every op is hosted on the Shogo API; the two legacy paths
+(`/api/voice/tts`, `/api/voice/music`) still work because a row may keep a
+`legacyHostedPath` for clients already in the field.
+
+### Adding an op
+
+1. Append a row to `VOICE_OPS` (`packages/voice/src/ops.ts`).
+2. Add one row to `packages/voice/src/__tests__/ops.test.ts` if it needs
+   validation the declarative fields cannot express.
+
+That is the whole change. No route file, no handler, no proxy branch, no
+per-op test file: `handlers.op`, the `route/op` modules and the hosted
+`/api/voice/op/:opId` executor all pick it up.
+
+Two things a row has to state, because the code cannot infer them: a body
+field goes in `forward` (caller name → upstream name), while an upstream
+**query** param goes in `queryForward` under its upstream name — ElevenLabs
+ignores a body field that belongs in the query (`sound-generation`'s
+`output_format`), so putting it in the wrong one is a silent no-op. A path
+param in `pathParams` may be sent by the caller as a body field or a query
+param; the multipart rebuild drops it from the upload either way.
+
+
+## TTS models
+
+`VOICE_TTS_MODELS` (from `@shogo-ai/voice`) is the single source of truth for
+model ids, per-request character caps and which models a convai agent can run
+on (`realtime`). It covers `eleven_v4`, `eleven_v4_turbo`, `eleven_v3`,
+`eleven_v3_conversational`, `eleven_multilingual_v2`, `eleven_flash_v2_5`,
+`eleven_flash_v2`, `eleven_turbo_v2_5` and `eleven_turbo_v2`.
+
+- `textToSpeech()` defaults to `eleven_v4`; convai agents default to
+  `eleven_v4_turbo` (`CONVAI_TTS_MODEL_FALLBACK`).
+- `resolveConvaiTtsModelDetailed(requested)` returns
+  `{ modelId, requested, downgraded, reason }`; a downgrade is logged once per
+  distinct model instead of silently swapping it.
+- `textToSpeech()` only falls back when the upstream failure is model-related
+  (402, or 400/403/404/422 mentioning model/plan/permission) and reports
+  `requestedModel` / `fellBack` / `fallbackReason`. The retry target is
+  `TTS_FALLBACK_MODEL` (`eleven_flash_v2_5`, the widest-available model) —
+  deliberately *not* `CONVAI_TTS_MODEL_FALLBACK`, so a BYO account without v4
+  entitlement still gets audio. The `tts` handler adds `x-tts-model-used`,
+  `x-tts-model-requested` and a `Warning: 199` header when they differ.
+
+## Proxy mode (Shogo pods)
+
+With `RUNTIME_AUTH_SECRET` + `PROJECT_ID` in env and no `apiKey`,
+`createVoiceHandlers({})` forwards to the Shogo API (`SHOGO_API_URL`, else
+`SHOGO_CLOUD_URL`) using the runtime token:
+
+- `signedUrl`, `tts`, `music`, `op`, `audioTags` — hosted.
+- `elevenLabs.textToSpeech()`, `.composeMusic()`, `.speechToSpeech()`,
+  `.soundEffects()`, `.transcribe()` — hosted.
+- `agent.*` and the other paired-account `elevenLabs` methods (cloning,
+  dubbing, voice design) — not available; they throw and need a BYO key.
+
+An explicit `apiKey` wins over the ambient runtime token. `mode: 'proxy'`
+forces the runtime token, `mode: 'byo'` forces your key, `'auto'` (default)
+prefers the key. `tts` and `music` need only `apiKey`; `getUser` and
+`companionStore` are required only for the user-scoped handlers
+(`signedUrl`, `agent.*`).
+
 ## Peers (all optional)
 
 Install only the peers you actually use:

package/dist/{chunk-S3S2RNO6.js → chunk-BI6SL35K.js}

@@ -1,7 +1,3 @@
-import {
-  stripAudioTags
-} from "./chunk-Q3TJAJ54.js";
-
 // src/react/shaders/organicSphereShaders.ts
 var PERLIN_4D = (
   /* glsl */
@@ -478,186 +474,7 @@ function resolveOrganicParticlesConfig(partial) {
   };
 }
 
-// src/shared/postJson.ts
-function createPostJson({
-  authHeaders,
-  fetchCredentials
-}) {
-  return async function postJson(path, body) {
-    return fetch(path, {
-      method: "POST",
-      headers: { "content-type": "application/json", ...authHeaders() },
-      credentials: fetchCredentials,
-      body: JSON.stringify(body)
-    });
-  };
-}
-
-// src/shared/memory.ts
-function createMemoryAddTool({
-  postJson,
-  memoryAddPath
-}) {
-  return async (params) => {
-    const fact = typeof params.fact === "string" ? params.fact : "";
-    if (!fact.trim()) return "Memory save failed: empty fact.";
-    try {
-      const res = await postJson(memoryAddPath, { fact });
-      if (!res.ok) return "Failed to save memory.";
-      return "Memory saved.";
-    } catch {
-      return "Memory save failed.";
-    }
-  };
-}
-function createMemoryContextInjector({
-  postJson,
-  memoryRetrievePath,
-  conversationRef,
-  enabled,
-  lastInjectedRef
-}) {
-  return async function inject(userText) {
-    if (!enabled) return;
-    try {
-      const res = await postJson(memoryRetrievePath, { query: userText, limit: 4 });
-      if (!res.ok) return;
-      const data = await res.json();
-      const results = data.results ?? [];
-      if (!results.length) return;
-      const lines = results.map((r) => `- ${r.chunk.trim().replace(/\s+/g, " ").slice(0, 200)}`).join("\n");
-      if (lines === lastInjectedRef.current) return;
-      lastInjectedRef.current = lines;
-      const payload = `Relevant memory about this user:
-${lines}`;
-      conversationRef.current?.sendContextualUpdate(payload);
-    } catch {
-    }
-  };
-}
-
-// src/shared/transcript.ts
-function createTranscriptDisconnectHandler({
-  isRestartingRef,
-  weStartedSessionRef,
-  transcriptRef,
-  onTranscript,
-  transcriptIngestPath,
-  postJson
-}) {
-  return function handleTranscriptOnDisconnect() {
-    if (isRestartingRef.current) {
-      return;
-    }
-    if (!weStartedSessionRef.current) {
-      transcriptRef.current = [];
-      return;
-    }
-    weStartedSessionRef.current = false;
-    const transcript = transcriptRef.current.join("\n");
-    transcriptRef.current = [];
-    if (onTranscript) {
-      void onTranscript(transcript);
-      return;
-    }
-    const trimmed = transcript.trim();
-    if (trimmed.length < 20) return;
-    void postJson(transcriptIngestPath, { transcript: trimmed }).catch(() => {
-    });
-  };
-}
-function appendTranscriptLine(msg, { transcriptRef, weStartedSessionRef }) {
-  if (!msg?.message || !msg?.source) return;
-  if (!weStartedSessionRef.current) return;
-  const speaker = msg.source === "user" ? "User" : "Agent";
-  const cleaned = msg.source === "user" ? msg.message : stripAudioTags(msg.message);
-  if (!cleaned) return;
-  transcriptRef.current.push(`${speaker}: ${cleaned}`);
-}
-
-// src/shared/sessionPayload.ts
-function sanitizeDynamicVariables(raw) {
-  if (raw == null) return {};
-  const out = {};
-  for (const [k, v] of Object.entries(raw)) {
-    if (v == null) continue;
-    out[k] = typeof v === "string" ? v : String(v);
-  }
-  return out;
-}
-function buildSessionPayload(opts) {
-  const dynamicVariables = {
-    ...sanitizeDynamicVariables(opts.dynamicVariables),
-    character_name: opts.characterName,
-    user_context: opts.userContext
-  };
-  if (typeof opts.conversationId === "string" && opts.conversationId.length > 0) {
-    dynamicVariables.conversation_id = opts.conversationId;
-  }
-  const payload = {
-    signedUrl: opts.signedUrl,
-    dynamicVariables
-  };
-  const agentOverrides = {};
-  if (opts.suppressFirstMessage) {
-    agentOverrides.firstMessage = "";
-  }
-  if (typeof opts.agentPromptOverride === "string" && opts.agentPromptOverride.length > 0) {
-    agentOverrides.prompt = { prompt: opts.agentPromptOverride };
-  }
-  if (Object.keys(agentOverrides).length > 0) {
-    payload.overrides = { agent: agentOverrides };
-  }
-  return payload;
-}
-async function fetchSignedUrl({
-  path,
-  fetchCredentials,
-  authHeaders
-}) {
-  const res = await fetch(path, {
-    credentials: fetchCredentials,
-    headers: authHeaders()
-  });
-  if (!res.ok) throw new Error(`Signed URL request failed: ${res.status}`);
-  return await res.json();
-}
-function withProjectQuery(signedUrlPath, params) {
-  const tail = [];
-  if (typeof params.projectId === "string" && params.projectId.length > 0) {
-    tail.push(`projectId=${encodeURIComponent(params.projectId)}`);
-  }
-  if (typeof params.agentName === "string" && params.agentName.length > 0) {
-    tail.push(`agentName=${encodeURIComponent(params.agentName)}`);
-  }
-  if (tail.length === 0) return signedUrlPath;
-  const sep = signedUrlPath.includes("?") ? "&" : "?";
-  return `${signedUrlPath}${sep}${tail.join("&")}`;
-}
-
-// src/shared/chatUrl.ts
-function appendChatQuery(basePath, params) {
-  const tail = [];
-  for (const [k, v] of Object.entries(params)) {
-    if (typeof v === "string" && v.length > 0) {
-      tail.push(`${k}=${encodeURIComponent(v)}`);
-    }
-  }
-  if (tail.length === 0) return basePath;
-  const sep = basePath.includes("?") ? "&" : "?";
-  return `${basePath}${sep}${tail.join("&")}`;
-}
-
 export {
-  createPostJson,
-  createMemoryAddTool,
-  createMemoryContextInjector,
-  createTranscriptDisconnectHandler,
-  appendTranscriptLine,
-  buildSessionPayload,
-  fetchSignedUrl,
-  withProjectQuery,
-  appendChatQuery,
   PERLIN_4D,
   ORGANIC_SPHERE_VERTEX_SHADER,
   ORGANIC_SPHERE_FRAGMENT_SHADER,
@@ -668,4 +485,4 @@ export {
   DEFAULT_ORGANIC_PARTICLES_CONFIG,
   resolveOrganicParticlesConfig
 };
-//# sourceMappingURL=chunk-S3S2RNO6.js.map
+//# sourceMappingURL=chunk-BI6SL35K.js.map