@shogo-ai/voice 1.4.1

package/dist/types-BKJtOUbE.d.ts

@@ -0,0 +1,352 @@
+/**
+ * ElevenLabs v3 expressive audio tags.
+ *
+ * Tags are inline markers like `[whispers]` that the TTS model interprets as
+ * performance cues. They can appear mid-sentence ("[excited] that's amazing!")
+ * or as non-verbal sounds ("[laughs]").
+ *
+ * Exposed to:
+ *   - Settings UI (chip picker, per-companion allow-list)
+ *   - Agent-driven "god mode" (tool surface)
+ *   - Server-side prompt composer (composeExpressivityBlock)
+ */
+type AudioTagGroup = 'emotion' | 'delivery' | 'reaction';
+interface AudioTag {
+    tag: string;
+    group: AudioTagGroup;
+    label: string;
+    description: string;
+    example: string;
+}
+declare const AUDIO_TAGS: AudioTag[];
+declare const AUDIO_TAG_GROUPS: {
+    id: AudioTagGroup;
+    label: string;
+    description: string;
+}[];
+type Expressivity = 'off' | 'subtle' | 'full';
+declare const EXPRESSIVITY_OPTIONS: {
+    id: Expressivity;
+    label: string;
+    description: string;
+}[];
+declare const DEFAULT_ALLOWED_TAGS: string[];
+interface VoiceSettings {
+    stability?: number;
+    similarity_boost?: number;
+    style?: number;
+    use_speaker_boost?: boolean;
+}
+declare const DEFAULT_VOICE_SETTINGS: VoiceSettings;
+declare function stripAudioTags(text: string | null | undefined): string;
+declare const EXPRESSIVITY_BLOCK_OPEN = "<!--expressivity-->";
+declare const EXPRESSIVITY_BLOCK_CLOSE = "<!--/expressivity-->";
+/**
+ * Strip any previous expressivity block from a prompt so we can re-inject a
+ * fresh one without duplicating.
+ */
+declare function stripExpressivityBlock(prompt: string): string;
+/**
+ * Compose the expressivity instruction block to inject into the system prompt.
+ * Wrapped in HTML-comment delimiters so it can be stripped and replaced
+ * idempotently across edits.
+ *
+ * Returns '' when expressivity is 'off' (caller should still strip any
+ * previous block first).
+ */
+declare function composeExpressivityBlock(expressivity: Expressivity, allowedTags: string[] | null | undefined): string;
+/**
+ * A short demo sentence built from up to 3 of the selected tags, used by the
+ * voice-preview endpoint so users can hear what their current settings sound
+ * like.
+ */
+declare function buildPreviewLine(allowedTags: string[] | null | undefined, characterName?: string): string;
+/**
+ * Normalize an arbitrary `audioTags` value from client JSON into a clean,
+ * de-duplicated list of known tags. Returns `null` if `raw` isn't an array.
+ */
+declare function normalizeAudioTags(raw: unknown): string[] | null;
+/**
+ * Returns the provided expressivity string if it's a valid {@link Expressivity},
+ * otherwise `undefined`.
+ */
+declare function normalizeExpressivity(raw: unknown): Expressivity | undefined;
+/**
+ * Clamp + pick only known voice-setting fields from arbitrary JSON. Accepts
+ * both snake_case and camelCase input keys.
+ */
+declare function normalizeVoiceSettings(raw: unknown): VoiceSettings | undefined;
+declare function readAudioTags(raw: unknown): string[];
+declare function readExpressivity(raw: unknown): Expressivity;
+declare function readVoiceSettings(raw: unknown): VoiceSettings;
+
+/**
+ * Typed ElevenLabs REST client for convai agents + TTS.
+ *
+ * Scoped to the endpoints the voice server handlers need:
+ *   - POST  /v1/convai/agents/create
+ *   - PATCH /v1/convai/agents/:id
+ *   - DELETE /v1/convai/agents/:id
+ *   - GET   /v1/convai/conversation/get-signed-url?agent_id=…
+ *   - POST  /v1/text-to-speech/:voiceId
+ *   - GET   /v1/voices/:voiceId
+ *
+ * All network calls use the global `fetch`. No module-level env reads —
+ * the API key is always supplied to the constructor.
+ */
+
+declare const DEFAULT_ELEVENLABS_BASE_URL = "https://api.elevenlabs.io";
+/** TTS models the convai runtime supports as of 2026-Q2. */
+declare const CONVAI_SUPPORTED_TTS_MODELS: Set<string>;
+declare const CONVAI_TTS_MODEL_FALLBACK = "eleven_turbo_v2_5";
+/** If `requested` isn't a convai-compatible TTS model, fall back to the default. */
+declare function resolveConvaiTtsModel(requested: string | null | undefined): string;
+interface ElevenLabsClientConfig {
+    apiKey: string;
+    /** Override for tests or self-hosted proxies. Defaults to the public API. */
+    baseUrl?: string;
+    /** Custom fetch (for tests). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** A `type: 'client'` tool entry attached to an agent's prompt config. */
+interface ConvaiClientTool {
+    type: 'client';
+    name: string;
+    description: string;
+    expects_response?: boolean;
+    parameters?: Record<string, unknown>;
+}
+interface CreateAgentParams {
+    displayName: string;
+    characterName: string;
+    voiceId: string;
+    /** Base system prompt — memory/expressivity blocks are appended before sending. */
+    systemPrompt: string;
+    firstMessage: string;
+    expressivity?: Expressivity;
+    audioTags?: string[] | null;
+    voiceSettings?: VoiceSettings;
+    ttsModelId?: string | null;
+    /**
+     * Tools the client (browser) implements. When omitted, no tools are attached.
+     * Consumers who want memory typically pass `MEMORY_CLIENT_TOOLS`.
+     */
+    tools?: ReadonlyArray<ConvaiClientTool>;
+    /** Optional memory block for the prompt composer. Default keeps the built-in block. */
+    memoryBlock?: string | null;
+    /** Language code for the conversation (default: 'en'). */
+    language?: string;
+    /** Per-user dynamic variable defaults. Merged on top of `character_name` / `user_context`. */
+    dynamicVariablePlaceholders?: Record<string, string>;
+}
+interface PatchAgentParams {
+    displayName?: string;
+    characterName?: string;
+    voiceId?: string;
+    systemPrompt?: string;
+    firstMessage?: string;
+    tools?: ReadonlyArray<ConvaiClientTool>;
+    enableUserContextOverride?: boolean;
+    expressivity?: Expressivity;
+    audioTags?: string[] | null;
+    voiceSettings?: VoiceSettings;
+    ttsModelId?: string | null;
+    memoryBlock?: string | null;
+}
+interface TextToSpeechParams {
+    voiceId: string;
+    text: string;
+    modelId?: string;
+    voiceSettings?: VoiceSettings;
+    /** Accept header; defaults to `audio/mpeg`. */
+    accept?: string;
+}
+/**
+ * An error thrown when ElevenLabs returns a non-2xx response. Preserves the
+ * status and response body so callers can decide how to surface it.
+ */
+declare class ElevenLabsApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+declare class ElevenLabsClient {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(config: ElevenLabsClientConfig);
+    private headers;
+    /** Create a new convai agent. Returns the new `agent_id`. */
+    createAgent(params: CreateAgentParams): Promise<string>;
+    /** PATCH any subset of agent settings. Idempotent; only sends the keys you supply. */
+    patchAgent(agentId: string, params: PatchAgentParams): Promise<void>;
+    /**
+     * Delete a convai agent. Best-effort: swallow errors so teardown during a
+     * 500 response doesn't cascade into a second failure.
+     */
+    deleteAgent(agentId: string): Promise<void>;
+    /** Fetch a short-lived signed URL the browser can use to start a session. */
+    getSignedUrl(agentId: string): Promise<string>;
+    /**
+     * One-shot TTS. Returns the raw audio bytes plus the model id that was
+     * actually used (some models aren't available for every account, so we
+     * fall back to `eleven_turbo_v2_5` on the first failure).
+     */
+    textToSpeech(params: TextToSpeechParams): Promise<{
+        audio: ArrayBuffer;
+        modelId: string;
+        contentType: string;
+    }>;
+    /** Probe whether a given voice id still exists on the caller's account. */
+    voiceExists(voiceId: string): Promise<boolean>;
+    /**
+     * Register a Twilio phone number with an ElevenLabs agent. EL becomes
+     * the SIP target for inbound calls to that number — Twilio bridges
+     * the call via EL's native integration and we never have to run a
+     * Media Streams ↔ convai WebSocket bridge ourselves.
+     *
+     * Returns the ElevenLabs `phone_number_id` (distinct from the Twilio
+     * `sid`) which is the handle used by `outboundCall` + `deletePhoneNumber`.
+     */
+    createPhoneNumberTwilio(params: {
+        phoneNumber: string;
+        label?: string;
+        agentId: string;
+        twilioAccountSid: string;
+        twilioAuthToken: string;
+    }): Promise<{
+        phoneNumberId: string;
+    }>;
+    /** Detach a previously-registered phone number from ElevenLabs. */
+    deletePhoneNumber(phoneNumberId: string): Promise<void>;
+    /**
+     * Place an outbound PSTN call via a previously-registered EL phone
+     * number. EL drives Twilio (or a SIP trunk) under the hood — we just
+     * hand it the destination number and the agent to bridge to. Returns
+     * the Twilio `callSid` + EL `conversationId` for metering / tracing.
+     *
+     * As of 2026-Q2 the EL API uses provider-scoped routes:
+     *   - Twilio numbers → POST /v1/convai/twilio/outbound-call
+     *   - SIP numbers    → POST /v1/convai/sip-trunk/outbound-call
+     * and `agent_phone_number_id` is a body field (no longer a path
+     * segment). The previous `/v1/convai/phone-numbers/{id}/outbound-call`
+     * route now returns 404. Callers that don't know the provider can
+     * look it up from `GET /v1/convai/phone-numbers/{id}` (`provider:
+     * "twilio" | "sip_trunk"`); most hosted setups are Twilio, so that's
+     * the default here.
+     */
+    outboundCall(params: {
+        phoneNumberId: string;
+        agentId: string;
+        toNumber: string;
+        /** EL provider route to use. Defaults to `'twilio'`. */
+        provider?: 'twilio' | 'sip-trunk';
+        dynamicVariables?: Record<string, string>;
+    }): Promise<{
+        callSid: string;
+        conversationId: string;
+    }>;
+}
+/**
+ * Canonical `add_memory` client-tool definition. Consumers can attach this to
+ * their agent's prompt so the model knows it can persist user facts.
+ */
+declare const MEMORY_CLIENT_TOOLS: ReadonlyArray<ConvaiClientTool>;
+
+/**
+ * Shared types for the voice module.
+ *
+ * The SDK does NOT own Prisma migrations. The consumer supplies their own
+ * persistence layer via {@link CompanionStore}; this interface just documents
+ * the fields we read/write.
+ */
+
+/**
+ * The persistent representation of a user's voice companion.
+ *
+ * Consumers typically back this with a Prisma model named `Companion` (or
+ * whatever they choose) with one row per user.
+ */
+interface Companion {
+    /** Stable id (matches user id in single-companion apps). */
+    id: string;
+    /** The authenticated user's id that owns this companion. */
+    userId: string;
+    /** ElevenLabs convai agent id returned by `createAgent`. */
+    agentId: string | null;
+    /** Human-facing name of the end user (used in agent greeting). */
+    displayName: string;
+    /** The companion's own name / persona. */
+    characterName: string;
+    /** ElevenLabs voice id. */
+    voiceId: string;
+    /** Base system prompt authored by the app (without memory/expressivity blocks). */
+    systemPrompt: string;
+    /** First line the agent speaks when the session starts. */
+    firstMessage: string;
+    /** `off` | `subtle` | `full` — controls whether the expressivity block is injected. */
+    expressivity: Expressivity;
+    /** Allow-list of audio tags the agent may use (empty ⇒ DEFAULT_ALLOWED_TAGS). */
+    audioTags: string[];
+    /** Optional ElevenLabs voice settings override. */
+    voiceSettings: VoiceSettings | null;
+    /** Optional TTS model override (e.g. `eleven_turbo_v2_5`). */
+    ttsModelId: string | null;
+}
+/**
+ * Consumer-supplied persistence layer. The SDK only calls these methods from
+ * the server handlers; it never reaches into a database directly.
+ */
+interface CompanionStore {
+    findByUserId(userId: string): Promise<Companion | null>;
+    create(data: Omit<Companion, 'id'> & {
+        id?: string;
+    }): Promise<Companion>;
+    update(userId: string, patch: Partial<Companion>): Promise<Companion>;
+    delete(userId: string): Promise<void>;
+}
+/**
+ * The shape required of the authenticated user. Consumers pass a `getUser`
+ * function to `createVoiceHandlers` that returns this (or `null`).
+ */
+interface VoiceUser {
+    id: string;
+}
+/**
+ * Minimal interface the voice server needs from a memory backend. Matches
+ * {@link import('../memory').MemoryStore.search} so consumers can wire the
+ * SDK's MemoryStore directly.
+ */
+interface VoiceMemoryStore {
+    search(query: string, options: {
+        limit: number;
+    }): ReadonlyArray<{
+        chunk: string;
+        matchType?: string;
+    }>;
+}
+/** Shape of the JSON body for `POST /voice/agent` (create). */
+interface CreateCompanionBody {
+    displayName: string;
+    characterName: string;
+    voiceId: string;
+    systemPrompt: string;
+    firstMessage: string;
+    expressivity?: Expressivity;
+    audioTags?: string[];
+    voiceSettings?: VoiceSettings;
+    ttsModelId?: string;
+}
+/** Shape of the JSON body for `PATCH /voice/agent`. Every field is optional. */
+type PatchCompanionBody = Partial<CreateCompanionBody>;
+/** Shape of the JSON body for `POST /voice/tts-preview`. */
+interface TtsPreviewBody {
+    voiceId: string;
+    text?: string;
+    audioTags?: string[];
+    modelId?: string;
+    voiceSettings?: VoiceSettings;
+    characterName?: string;
+}
+
+export { AUDIO_TAGS as A, readAudioTags as B, CONVAI_SUPPORTED_TTS_MODELS as C, DEFAULT_ALLOWED_TAGS as D, type Expressivity as E, readExpressivity as F, readVoiceSettings as G, resolveConvaiTtsModel as H, stripAudioTags as I, stripExpressivityBlock as J, MEMORY_CLIENT_TOOLS as M, type PatchAgentParams as P, type TextToSpeechParams as T, type VoiceMemoryStore as V, AUDIO_TAG_GROUPS as a, type AudioTag as b, type AudioTagGroup as c, CONVAI_TTS_MODEL_FALLBACK as d, type Companion as e, type CompanionStore as f, type ConvaiClientTool as g, type CreateAgentParams as h, type CreateCompanionBody as i, DEFAULT_ELEVENLABS_BASE_URL as j, DEFAULT_VOICE_SETTINGS as k, EXPRESSIVITY_BLOCK_CLOSE as l, EXPRESSIVITY_BLOCK_OPEN as m, EXPRESSIVITY_OPTIONS as n, ElevenLabsApiError as o, ElevenLabsClient as p, type ElevenLabsClientConfig as q, type PatchCompanionBody as r, type TtsPreviewBody as s, type VoiceSettings as t, type VoiceUser as u, buildPreviewLine as v, composeExpressivityBlock as w, normalizeAudioTags as x, normalizeExpressivity as y, normalizeVoiceSettings as z };

package/package.json

@@ -0,0 +1,148 @@
+{
+  "name": "@shogo-ai/voice",
+  "version": "1.4.1",
+  "description": "Shogo Voice — ElevenLabs/Twilio voice agent infrastructure with React + React Native UI primitives.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
+    },
+    "./native": {
+      "types": "./dist/native/index.d.ts",
+      "import": "./dist/native/index.js",
+      "require": "./dist/native/index.cjs"
+    },
+    "./route": {
+      "types": "./dist/route/index.d.ts",
+      "import": "./dist/route/index.js",
+      "require": "./dist/route/index.cjs"
+    },
+    "./route/signed-url": {
+      "types": "./dist/route/signed-url.d.ts",
+      "import": "./dist/route/signed-url.js",
+      "require": "./dist/route/signed-url.cjs"
+    },
+    "./route/tts-preview": {
+      "types": "./dist/route/tts-preview.d.ts",
+      "import": "./dist/route/tts-preview.js",
+      "require": "./dist/route/tts-preview.cjs"
+    },
+    "./route/agent": {
+      "types": "./dist/route/agent.d.ts",
+      "import": "./dist/route/agent.js",
+      "require": "./dist/route/agent.cjs"
+    },
+    "./route/audio-tags": {
+      "types": "./dist/route/audio-tags.d.ts",
+      "import": "./dist/route/audio-tags.js",
+      "require": "./dist/route/audio-tags.cjs"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.cjs",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.cts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "bun --no-env-file test src/"
+  },
+  "peerDependencies": {
+    "@ai-sdk/react": ">=3.0.0",
+    "@elevenlabs/react": ">=1.1.0",
+    "@elevenlabs/react-native": ">=1.1.0",
+    "ai": ">=6.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0",
+    "three": ">=0.160.0",
+    "expo-gl": ">=15.0.0",
+    "expo-three": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/react": {
+      "optional": true
+    },
+    "@elevenlabs/react": {
+      "optional": true
+    },
+    "@elevenlabs/react-native": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    },
+    "expo-gl": {
+      "optional": true
+    },
+    "expo-three": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ai-sdk/react": "^3.0.99",
+    "@elevenlabs/react": "^1.1.1",
+    "@elevenlabs/react-native": "^1.1.4",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.0.0",
+    "@types/three": "^0.180.0",
+    "ai": "^6.0.97",
+    "expo-gl": "^15.0.0",
+    "expo-three": "^8.0.0",
+    "react-native": "^0.81.0",
+    "three": "^0.180.0",
+    "tsup": "^8.0.0",
+    "typescript": "^6.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "shogo",
+    "voice",
+    "elevenlabs",
+    "twilio",
+    "tts",
+    "react",
+    "react-native",
+    "three"
+  ],
+  "author": "Shogo Labs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shogo-labs/shogo-ai.git",
+    "directory": "packages/voice"
+  },
+  "homepage": "https://github.com/shogo-labs/shogo-ai/tree/main/packages/voice#readme",
+  "bugs": {
+    "url": "https://github.com/shogo-labs/shogo-ai/issues"
+  }
+}