@shogo-ai/voice 1.4.1

package/dist/index.d.cts

@@ -0,0 +1,432 @@
+import { E as Expressivity } from './types-BKJtOUbE.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 ConvaiClientTool, h as CreateAgentParams, i as CreateCompanionBody, D as DEFAULT_ALLOWED_TAGS, j as DEFAULT_ELEVENLABS_BASE_URL, k as DEFAULT_VOICE_SETTINGS, l as EXPRESSIVITY_BLOCK_CLOSE, m as EXPRESSIVITY_BLOCK_OPEN, n as EXPRESSIVITY_OPTIONS, o as ElevenLabsApiError, p as ElevenLabsClient, q as ElevenLabsClientConfig, M as MEMORY_CLIENT_TOOLS, P as PatchAgentParams, r as PatchCompanionBody, T as TextToSpeechParams, s as TtsPreviewBody, V as VoiceMemoryStore, t as VoiceSettings, u as VoiceUser, v as buildPreviewLine, w as composeExpressivityBlock, x as normalizeAudioTags, y as normalizeExpressivity, z as normalizeVoiceSettings, B as readAudioTags, F as readExpressivity, G as readVoiceSettings, H as resolveConvaiTtsModel, I as stripAudioTags, J as stripExpressivityBlock } from './types-BKJtOUbE.cjs';
+
+/**
+ * System-prompt composer for the voice agent.
+ *
+ * Layers three concerns on top of the caller's base prompt:
+ *   1. Expressivity block   (audio tags allow-list + usage rules)
+ *   2. Memory block         (`{{user_context}}` placeholder + `add_memory` tool doc)
+ *
+ * Each block is wrapped in a delimiter comment so repeated calls remain
+ * idempotent — calling `composeAgentPrompt` on an already-composed prompt
+ * produces the same output because the old blocks are stripped first.
+ */
+
+/** Default memory guidance appended when memory tools are enabled. */
+declare const DEFAULT_MEMORY_BLOCK = "# Memory\n\nKnown context about this user from past conversations:\n{{user_context}}\n\nMemory retrieval is automatic \u2014 the top matching facts are already injected above. Never say \"let me check my memory\" or \"searching memories.\"\n\nYou have one tool:\n- add_memory(fact): save a concise, canonical fact about the user \u2014 preferences, decisions, personal details, follow-ups. Use short normalized phrasings like \"favorite color: green\" or \"lives in Honolulu\". Always call it when the user explicitly asks you to remember something.";
+/**
+ * Strip a previously-appended memory block from a prompt so we can re-append
+ * cleanly. Handles both the exact heading we emit and the older `<!-- zix-memory-vN -->`
+ * marker for backwards compatibility.
+ */
+declare function stripMemoryBlock(prompt: string): string;
+interface ComposeAgentPromptOptions {
+    /** `off` disables the expressivity block entirely. Default: `subtle`. */
+    expressivity?: Expressivity;
+    /** Allowed audio tags. `null` ⇒ use DEFAULT_ALLOWED_TAGS. */
+    audioTags?: string[] | null;
+    /**
+     * Memory guidance appended to the end of the prompt. Pass `null` to omit
+     * the memory block entirely (useful for agents that don't use memory tools).
+     * Default: {@link DEFAULT_MEMORY_BLOCK}.
+     */
+    memoryBlock?: string | null;
+}
+/**
+ * Strip the expressivity + memory blocks from an arbitrary prompt, returning
+ * the base prompt the app originally supplied.
+ */
+declare function extractBasePrompt(prompt: string): string;
+/**
+ * Compose the final system prompt that gets sent to ElevenLabs. Idempotent:
+ * passing an already-composed prompt back in produces the same output.
+ */
+declare function composeAgentPrompt(basePrompt: string, options?: ComposeAgentPromptOptions): string;
+
+/**
+ * Thin `fetch`-based Twilio REST client used by Mode A of the SDK's
+ * `TelephonyClient` (self-hosted / BYO keys). Intentionally duplicates
+ * the essential pieces of the server-side client in
+ * `apps/api/src/lib/twilio.ts` instead of importing it — the SDK must
+ * remain server-independent and have zero dependency on the Shogo API
+ * or the `twilio` npm package.
+ *
+ * Only the endpoints currently needed by the SDK are modelled:
+ *   - AvailablePhoneNumbers/{country}/Local → search
+ *   - IncomingPhoneNumbers                  → purchase
+ *   - IncomingPhoneNumbers/{sid}            → release
+ */
+declare const DEFAULT_TWILIO_BASE_URL = "https://api.twilio.com";
+declare class TwilioApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+interface TwilioClientConfig {
+    accountSid: string;
+    authToken: string;
+    /** Override for tests. Defaults to the public API. */
+    baseUrl?: string;
+    /** Custom fetch (for tests). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+interface AvailableNumber {
+    phoneNumber: string;
+    friendlyName: string;
+    region?: string;
+    locality?: string;
+    isoCountry?: string;
+}
+interface IncomingNumber {
+    sid: string;
+    phoneNumber: string;
+    friendlyName: string;
+    voiceUrl?: string;
+}
+declare class TwilioClient {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly basicAuth;
+    constructor(config: TwilioClientConfig);
+    private accountUrl;
+    private headers;
+    searchAvailable(params?: {
+        country?: string;
+        areaCode?: string;
+        contains?: string;
+        limit?: number;
+    }): Promise<AvailableNumber[]>;
+    purchaseNumber(params: {
+        phoneNumber: string;
+        friendlyName?: string;
+        voiceUrl?: string;
+    }): Promise<IncomingNumber>;
+    releaseNumber(sid: string): Promise<void>;
+}
+
+/**
+ * Dual-mode telephony client.
+ *
+ * The SDK exposes a single `TelephonyClient` interface with two
+ * implementations behind it:
+ *
+ *   - `HostedTelephonyClient` (Mode B) — proxies every call through
+ *     Shogo's API using a `shogo_sk_*` bearer. Shogo owns the EL +
+ *     Twilio accounts, provisions resources per project, and meters
+ *     usage against the workspace's USD usage wallet (raw provider
+ *     cost + 20% markup).
+ *
+ *   - `DirectTelephonyClient` (Mode A) — talks directly to Twilio REST
+ *     and ElevenLabs REST using developer-provided credentials. Shogo's
+ *     API is not involved; the developer pays EL + Twilio directly.
+ *
+ * Consumers never construct these directly; `createTelephonyClient()`
+ * (called by `createClient()`) picks the right implementation based on
+ * the supplied options.
+ */
+interface ProvisionNumberOptions {
+    /** US area code preference (e.g. '415'). Hosted + Direct. */
+    areaCode?: string;
+    /** ISO country code (defaults to US). */
+    country?: string;
+    /** Human-friendly label stored with the number. */
+    friendlyName?: string;
+}
+interface ProvisionNumberResult {
+    phoneNumber: string;
+    twilioPhoneSid: string;
+    elevenlabsPhoneId: string;
+    /** USD billed (raw provider cost + 20% markup) for setup (Mode B only). */
+    setupBilledUsd?: number;
+    /** USD billed for the first monthly number fee (Mode B only). */
+    monthlyBilledUsd?: number;
+    /** Whether each debit succeeded against the workspace's usage wallet. */
+    usageDebited?: {
+        setup: boolean;
+        monthly: boolean;
+    };
+}
+interface OutboundCallOptions {
+    to: string;
+    dynamicVariables?: Record<string, string>;
+}
+interface OutboundCallResult {
+    callSid: string;
+    conversationId: string;
+    /** Pre-flight USD estimate for one minute outbound (Mode B only). */
+    estimatedBilledUsd?: number;
+    /** USD per minute outbound, billed rate (raw + markup). */
+    billedUsdPerMinute?: number;
+}
+interface VoiceUsageRange {
+    from?: string;
+    to?: string;
+}
+/**
+ * Aggregated voice usage for a project. Shape mirrors
+ * `GET /api/voice/usage/:projectId`. `events` is the underlying raw
+ * `UsageEvent` list (capped at 1000) for consumers that want to build
+ * a per-day chart themselves.
+ */
+interface VoiceUsageSummary {
+    projectId: string;
+    range: {
+        from: string | null;
+        to: string | null;
+    };
+    totals: {
+        minutesInbound: number;
+        minutesOutbound: number;
+        /** USD billed (raw + markup) for inbound minutes. */
+        billedUsdInbound: number;
+        /** USD billed for outbound minutes. */
+        billedUsdOutbound: number;
+        /** USD billed for number setup + monthly fees. */
+        billedUsdNumbers: number;
+        /** Grand total USD billed across all voice usage. */
+        billedUsd: number;
+        calls: number;
+        inboundCalls: number;
+        outboundCalls: number;
+    };
+    events: Array<{
+        id: string;
+        actionType: string;
+        actionMetadata: unknown;
+        /** Raw provider cost in USD, before markup. */
+        rawUsd: number;
+        /** Amount billed to the workspace in USD (raw + markup). */
+        billedUsd: number;
+        createdAt: string;
+    }>;
+}
+interface ReleaseNumberResult {
+    released: boolean;
+}
+/**
+ * Single turn of an ElevenLabs post-call transcript.
+ * Mirrors the `transcript` array items in the `post_call_transcription`
+ * webhook payload. Extra provider-specific fields are preserved on the
+ * index signature so consumers can surface them if needed.
+ */
+interface VoiceTranscriptTurn {
+    role: 'agent' | 'user' | string;
+    message?: string | null;
+    time_in_call_secs?: number;
+    [key: string]: unknown;
+}
+/**
+ * Summary row returned by `GET /api/voice/calls/:projectId`. When
+ * `includeTranscript=true` is passed to `listCalls`, each row also
+ * includes the full `transcript` array.
+ */
+interface VoiceCallSummary {
+    id: string;
+    conversationId: string | null;
+    callSid: string | null;
+    direction: 'inbound' | 'outbound' | string;
+    durationSeconds: number;
+    billedMinutes: number;
+    startedAt: string | null;
+    endedAt: string | null;
+    createdAt: string;
+    billed: boolean;
+    hasTranscript: boolean;
+    transcriptSummary: string | null;
+    transcript?: VoiceTranscriptTurn[] | null;
+}
+/**
+ * Detailed single-call row from `GET /api/voice/calls/:projectId/:callId`
+ * — always includes the full transcript when EL has delivered one.
+ */
+interface VoiceCallDetail extends Omit<VoiceCallSummary, 'hasTranscript'> {
+    transcript: VoiceTranscriptTurn[] | null;
+}
+interface ListCallsOptions {
+    limit?: number;
+    includeTranscript?: boolean;
+}
+interface TelephonyClient {
+    readonly mode: 'hosted' | 'direct' | 'mock';
+    provisionNumber(opts?: ProvisionNumberOptions): Promise<ProvisionNumberResult>;
+    outboundCall(opts: OutboundCallOptions): Promise<OutboundCallResult>;
+    releaseNumber(): Promise<ReleaseNumberResult>;
+    /** Mode A throws; usage is not tracked on Shogo's side. */
+    getUsage(range?: VoiceUsageRange): Promise<VoiceUsageSummary>;
+    /**
+     * List recent calls for this project with optional transcripts.
+     * Mode A throws — Shogo's API doesn't see these calls.
+     */
+    listCalls(opts?: ListCallsOptions): Promise<VoiceCallSummary[]>;
+    /**
+     * Fetch a single call (by VoiceCallMeter id, EL conversation id, or
+     * Twilio CallSid) including the full transcript. Mode A throws.
+     */
+    getCall(callId: string): Promise<VoiceCallDetail>;
+}
+declare class TelephonyConfigError extends Error {
+    constructor(message: string);
+}
+declare class TelephonyApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+interface HostedTelephonyOptions {
+    shogoApiKey: string;
+    projectId: string;
+    apiUrl: string;
+    fetch?: typeof fetch;
+}
+declare class HostedTelephonyClient implements TelephonyClient {
+    private readonly opts;
+    readonly mode = "hosted";
+    private readonly fetchImpl;
+    constructor(opts: HostedTelephonyOptions);
+    private url;
+    private request;
+    provisionNumber(opts?: ProvisionNumberOptions): Promise<ProvisionNumberResult>;
+    outboundCall(opts: OutboundCallOptions): Promise<OutboundCallResult>;
+    releaseNumber(): Promise<ReleaseNumberResult>;
+    getUsage(range?: VoiceUsageRange): Promise<VoiceUsageSummary>;
+    listCalls(opts?: ListCallsOptions): Promise<VoiceCallSummary[]>;
+    getCall(callId: string): Promise<VoiceCallDetail>;
+}
+interface HostedRuntimeTokenOptions {
+    /**
+     * Per-project runtime token — the value of `process.env.RUNTIME_AUTH_SECRET`
+     * injected into every Shogo-managed pod. This is **not** a user API key;
+     * it's a deterministic HMAC-derived capability scoped to exactly one
+     * `projectId`. Never ship this value to the browser bundle.
+     */
+    runtimeToken: string;
+    projectId: string;
+    apiUrl: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Hosted telephony client that authenticates via `x-runtime-token` instead
+ * of a `shogo_sk_*` bearer. Used by generated pod apps: every pod already
+ * has `RUNTIME_AUTH_SECRET` + `PROJECT_ID` in env, so `createClient()` can
+ * pick this implementation automatically — the developer never mints a key.
+ *
+ * Wire-compat with {@link HostedTelephonyClient}: same endpoints, same
+ * response shapes. The only differences are:
+ *
+ *   1. `Authorization` is replaced with `x-runtime-token`.
+ *   2. Every request URL carries `?projectId=<pid>` so the Shogo API's
+ *      `authMiddleware` can re-derive and validate the token.
+ */
+declare class HostedRuntimeTokenClient implements TelephonyClient {
+    private readonly opts;
+    readonly mode = "hosted";
+    private readonly fetchImpl;
+    constructor(opts: HostedRuntimeTokenOptions);
+    private url;
+    private request;
+    provisionNumber(opts?: ProvisionNumberOptions): Promise<ProvisionNumberResult>;
+    outboundCall(opts: OutboundCallOptions): Promise<OutboundCallResult>;
+    releaseNumber(): Promise<ReleaseNumberResult>;
+    getUsage(range?: VoiceUsageRange): Promise<VoiceUsageSummary>;
+    listCalls(opts?: ListCallsOptions): Promise<VoiceCallSummary[]>;
+    getCall(callId: string): Promise<VoiceCallDetail>;
+}
+interface DirectTelephonyOptions {
+    projectId?: string;
+    elevenlabs: {
+        apiKey: string;
+        agentId: string;
+        /** Existing EL phone-number resource id. If omitted, `provisionNumber`
+         *  will create one; `outboundCall` / `releaseNumber` will 409 until
+         *  one exists. */
+        phoneNumberId?: string;
+        baseUrl?: string;
+    };
+    twilio: {
+        accountSid: string;
+        authToken: string;
+        /**
+         * E.164 number to use as the caller id. Required for
+         * `outboundCall`. If you want `provisionNumber` to buy a new
+         * number, leave this unset.
+         */
+        fromNumber?: string;
+        /** Optional pre-existing Twilio IncomingPhoneNumber sid. */
+        phoneSid?: string;
+        baseUrl?: string;
+    };
+    fetch?: typeof fetch;
+}
+declare class DirectTelephonyClient implements TelephonyClient {
+    private readonly opts;
+    readonly mode = "direct";
+    private readonly el;
+    private readonly tw;
+    private state;
+    constructor(opts: DirectTelephonyOptions);
+    provisionNumber(opts?: ProvisionNumberOptions): Promise<ProvisionNumberResult>;
+    outboundCall(opts: OutboundCallOptions): Promise<OutboundCallResult>;
+    releaseNumber(): Promise<ReleaseNumberResult>;
+    getUsage(): Promise<VoiceUsageSummary>;
+    listCalls(): Promise<VoiceCallSummary[]>;
+    getCall(): Promise<VoiceCallDetail>;
+}
+type CreateTelephonyOptions = ({
+    mode: 'hosted';
+} & HostedTelephonyOptions) | ({
+    mode: 'runtime-token';
+} & HostedRuntimeTokenOptions) | ({
+    mode: 'direct';
+} & DirectTelephonyOptions);
+declare function createTelephonyClient(opts: CreateTelephonyOptions): TelephonyClient;
+
+/**
+ * MockTelephonyClient
+ *
+ * In-process telephony stub used by demo recordings (Playwright) and
+ * any environment that sets `process.env.SHOGO_VOICE_MODE=mock`.
+ *
+ * Returns deterministic, hand-crafted fixture data for every method on
+ * the {@link TelephonyClient} interface. Performs zero network I/O — no
+ * Shogo API call, no Twilio call, no ElevenLabs call. Calling
+ * `outboundCall()` is therefore safe in any context (no real phones
+ * ring, no usage wallet is debited).
+ *
+ * Wire-compat with the real clients: same method shapes, same return
+ * types. Generated app code that uses
+ * `shogo.voice.telephony.outboundCall(...)` does not need to know it's
+ * running against the mock.
+ */
+
+interface MockTelephonyOptions {
+    /** Project the mock pretends to belong to. Defaults to 'demo-project'. */
+    projectId?: string;
+    /** Override the placeholder outbound number. */
+    phoneNumber?: string;
+    /** Override the rotating call fixtures (advanced). */
+    callFixtures?: VoiceCallSummary[];
+}
+declare class MockTelephonyClient implements TelephonyClient {
+    readonly mode: "mock";
+    private readonly projectId;
+    private readonly phoneNumber;
+    private readonly fixtures;
+    private callCounter;
+    constructor(opts?: MockTelephonyOptions);
+    provisionNumber(_opts?: ProvisionNumberOptions): Promise<ProvisionNumberResult>;
+    outboundCall(_opts: OutboundCallOptions): Promise<OutboundCallResult>;
+    releaseNumber(): Promise<ReleaseNumberResult>;
+    getUsage(_range?: VoiceUsageRange): Promise<VoiceUsageSummary>;
+    listCalls(opts?: ListCallsOptions): Promise<VoiceCallSummary[]>;
+    getCall(callId: string): Promise<VoiceCallDetail>;
+}
+/**
+ * Convenience: returns true when SHOGO_VOICE_MODE is set to one of the
+ * recognized mock-mode aliases. Other modules in the SDK use this to
+ * branch their telephony selection.
+ */
+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 };