supafone-labs 0.4.12 → 0.4.13

package/README.md

@@ -107,6 +107,13 @@ Supafone Labs has two main features:
 - **Self-healing watcher**: enable `labs.enabled` to attach the Supafone Labs
   second mind to a hosted or BYOK agent.
 
+The daily developer workflow is documented in
+[Developer Workflows](../gitbook/developer-workflows.md): one normalized live
+voice catalog, fixed BCP-47 language selection, automatic voice compatibility
+filtering, structured SecondMind directives, and the same configuration model
+across TypeScript and Python. Fixed language selection does not enable
+mid-call language or voice switching.
+
 BYOK is advanced and split into three independent lanes:
 
 | Lane | Examples |
@@ -279,6 +286,29 @@ required); and prints the returned widget snippet.
 
 ## Hosted voices
 
+Select a current provider voice from plain-language intent:
+
+```ts
+const matches = await supafone.labs.voices.recommend({
+  description: "calm Spanish customer-support voice",
+  language: "es-MX",
+  configuredOnly: true,
+});
+
+const voice = matches.matches[0].voice;
+await supafone.labs.agents.createInbound({
+  name: "Spanish support",
+  voice: supafone.labs.voices.selection(voice),
+});
+```
+
+The hosted catalog refreshes Ultravox, Cartesia, ElevenLabs, and Inworld and
+normalizes names, languages, gender, accent, voice type, model limits, and the
+Ultravox-compatible language intersection. Full reference:
+[Dynamic Voice Catalog and Selection](../gitbook/voice-catalog-and-selection.md).
+
+Labs Cloud also exposes direct hosted TTS and STT:
+
 ```ts
 const wav = await supafone.tts("You're all set — talk soon!", "supafone-labs-calm-en");
 // wav: Uint8Array

package/dist/cjs/index.d.ts

@@ -87,6 +87,56 @@ export interface WhisperOptions {
     maxTokens?: number;
     temperature?: number;
 }
+export type SecondMindDirectiveKind = "empathy" | "tactical" | "guardrail" | "mixed";
+export interface DirectiveTextControl {
+    enabled?: boolean;
+    instructions?: string;
+    maxChars?: number;
+    max_chars?: number;
+}
+export interface DirectiveListControl {
+    enabled?: boolean;
+    instructions?: string;
+    maxItems?: number;
+    max_items?: number;
+    itemMaxChars?: number;
+    item_max_chars?: number;
+}
+/** Serializable controls for each field generated by SecondMind. */
+export interface DirectiveContract {
+    empathyDirective?: DirectiveTextControl;
+    empathy_directive?: DirectiveTextControl;
+    tacticalDirective?: DirectiveTextControl;
+    tactical_directive?: DirectiveTextControl;
+    surfaceFacts?: DirectiveListControl;
+    surface_facts?: DirectiveListControl;
+    guardrails?: DirectiveListControl;
+    languageMode?: "caller" | "model" | "fixed";
+    language_mode?: "caller" | "model" | "fixed";
+    fixedLanguage?: string;
+    fixed_language?: string;
+    allowedKinds?: SecondMindDirectiveKind[];
+    allowed_kinds?: SecondMindDirectiveKind[];
+    confidenceThreshold?: number;
+    confidence_threshold?: number;
+    operatorGuardrails?: string[];
+    operator_guardrails?: string[];
+}
+export interface SecondMindDirective {
+    empathy_directive: string;
+    tactical_directive: string;
+    surface_facts: string[];
+    guardrails: string[];
+    language: string;
+    confidence: number;
+    kind: SecondMindDirectiveKind;
+}
+export interface StructuredWhisperOptions extends WhisperOptions {
+    directiveContract?: DirectiveContract;
+    directive_contract?: DirectiveContract;
+    /** Local final say: revise or suppress the generated directive before use. */
+    transform?: (directive: SecondMindDirective) => SecondMindDirective | null | Promise<SecondMindDirective | null>;
+}
 export interface Balance {
     plan: string;
     seconds_remaining: number;
@@ -160,6 +210,113 @@ export interface LabsVoiceSelection {
     voice_id?: string;
     model?: string;
 }
+export type LabsVoiceGender = "female" | "male" | "neutral";
+export interface LabsVoiceLanguage {
+    code: string;
+    locale: string;
+    name: string;
+    native_name: string;
+    aliases?: string[];
+    routing_supported?: boolean;
+}
+export interface LabsVoiceLanguageSupport {
+    provider: string;
+    model?: string | null;
+    known: boolean;
+    language_codes: string[];
+    /** Number of language codes Supafone can enumerate from provider docs. */
+    enumerated_language_count: number;
+    generally_available_language_codes: string[];
+    experimental_language_codes: string[];
+    documented_language_count: number;
+    documented_language_count_is_minimum: boolean;
+    support_tier: string;
+    cross_lingual: boolean | null;
+    documentation_url?: string | null;
+    verified_at: string;
+    native_language_codes: string[];
+    ultravox_routing_language_codes: string[];
+    primary_language_support_tier: "generally_available" | "experimental" | "unknown";
+}
+export interface LabsVoiceProviderTraits {
+    countries: string[];
+    accents: string[];
+    age_groups: string[];
+    categories: string[];
+    use_cases: string[];
+    descriptors: string[];
+    native_locales: string[];
+    created_at?: string | number | null;
+    is_public?: boolean | null;
+    is_owner?: boolean | null;
+}
+export interface LabsVoiceCatalogItem {
+    /** Stable runtime reference, including provider prefix when required. */
+    id: string;
+    voice_id: string;
+    /** Human-readable provider display name. */
+    provider: string;
+    /** Canonical SDK/runtime provider key. */
+    provider_key: string;
+    /** Runtime adapter used to place the voice on an Ultravox call. */
+    runtime_provider_key: string;
+    /** Actual TTS engine behind the voice (can differ for Ultravox built-ins). */
+    synthesis_provider_key: string;
+    /** Raw identifier used by the provider API. */
+    provider_voice_id: string;
+    name: string;
+    label: string;
+    description: string;
+    style: string;
+    model?: string | null;
+    language: string;
+    language_code: string;
+    language_locale: string;
+    language_name: string;
+    native_language_name: string;
+    languages: LabsVoiceLanguage[];
+    native_language_codes: string[];
+    model_language_codes: string[];
+    runtime_supported_language_codes: string[];
+    routing_supported: boolean;
+    language_support: LabsVoiceLanguageSupport;
+    gender: LabsVoiceGender;
+    accent: string;
+    age: string;
+    provider_traits: LabsVoiceProviderTraits;
+    voice_types: string[];
+    primary_voice_type: string;
+    tags: string[];
+    /** Sanitized provider-native fields retained for forward-compatible filtering. */
+    provider_metadata: Record<string, unknown>;
+    provider_metadata_fields: string[];
+    preview_url?: string | null;
+    preview_available: boolean;
+    source: string;
+    ownership?: string | null;
+    configured: boolean;
+    recommended: boolean;
+    premium?: boolean;
+    is_custom: boolean;
+    runtime: {
+        provider: string;
+        voice_id: string;
+        model?: string;
+    };
+    [extra: string]: unknown;
+}
+export interface LabsVoicePreference {
+    description: string;
+    language?: string;
+    provider?: string;
+    gender?: LabsVoiceGender;
+    voiceType?: string;
+    voice_type?: string;
+    model?: string;
+    configuredOnly?: boolean;
+    configured_only?: boolean;
+    premium?: boolean;
+}
 export interface LabsProviderKeys {
     /** Agent runtime/platform providers. */
     ultravox?: string;
@@ -507,8 +664,14 @@ export interface CreateLabsAgentRequest {
     greeting?: string;
     systemPrompt?: string;
     system_prompt?: string;
+    /** Fixed language for the full call. Does not enable mid-call switching. */
     language?: string;
+    preferredLanguage?: string;
+    preferred_language?: string;
     voice?: LabsVoiceSelection;
+    /** Resolve a real current catalog voice from this plain-language preference. */
+    voicePreference?: LabsVoicePreference;
+    voice_preference?: LabsVoicePreference;
     providerKeys?: LabsProviderKeys;
     provider_keys?: LabsProviderKeys;
     byok?: LabsProviderKeys | LabsByokConfig;
@@ -569,16 +732,98 @@ export interface LabsToolListResponse {
 export interface LabsVoiceListOptions {
     provider?: string;
     search?: string;
+    /** Native/accent language advertised for the individual voice. */
     language?: string;
+    /** Language that the provider model and Ultravox can both run live. */
+    compatibleLanguage?: string;
+    compatible_language?: string;
+    gender?: LabsVoiceGender;
+    voiceType?: string;
+    voice_type?: string;
+    model?: string;
+    runtimeProvider?: string;
+    runtime_provider?: string;
+    configuredOnly?: boolean;
+    configured_only?: boolean;
     cursor?: number;
     limit?: number;
+    agencyId?: string;
+    agency_id?: string;
 }
 export interface LabsVoiceListResponse {
-    voices: Array<Record<string, unknown>>;
+    account_id?: string;
+    voices: LabsVoiceCatalogItem[];
     total: number;
-    providers: Array<Record<string, unknown>>;
+    cursor?: number;
+    next_cursor?: number | null;
+    providers: Array<{
+        id: string;
+        label: string;
+        configured: boolean;
+        voice_count: number;
+        error?: string | null;
+    }>;
     provider_accounts?: Record<string, unknown>;
     errors?: Record<string, string>;
+    catalog?: {
+        dynamic: boolean;
+        source: string;
+        normalization_schema_version: number;
+        cache_ttl_seconds: number;
+        capabilities_url?: string;
+    };
+}
+export interface LabsVoiceModelCapability {
+    provider: string;
+    model?: string | null;
+    known: boolean;
+    language_codes: string[];
+    enumerated_language_count: number;
+    generally_available_language_codes: string[];
+    experimental_language_codes: string[];
+    documented_language_count: number;
+    documented_language_count_is_minimum: boolean;
+    support_tier: string;
+    cross_lingual: boolean | null;
+    documentation_url?: string | null;
+    verified_at: string;
+    ultravox_routing_language_codes: string[];
+    ultravox_routing_language_count: number;
+}
+export interface LabsVoiceProviderCapability {
+    provider: string;
+    label: string;
+    ultravox_integration: "native" | "named_external" | string;
+    default_model?: string | null;
+    models: LabsVoiceModelCapability[];
+}
+export interface LabsVoiceCapabilitiesResponse {
+    runtime: "ultravox" | string;
+    runtime_spoken_languages: LabsVoiceLanguage[];
+    runtime_spoken_language_count: number;
+    providers: LabsVoiceProviderCapability[];
+    selection_rule: Record<string, string>;
+    normalization_schema_version: number;
+}
+export interface LabsVoiceRecommendOptions extends LabsVoicePreference {
+    limit?: number;
+    agencyId?: string;
+    agency_id?: string;
+}
+export interface LabsVoiceRecommendation {
+    voice: LabsVoiceCatalogItem;
+    score: number;
+    reasons: string[];
+}
+export interface LabsVoiceRecommendResponse {
+    account_id?: string;
+    description: string;
+    matches: LabsVoiceRecommendation[];
+    total_considered: number;
+}
+export interface LabsVoicePreview {
+    content: ArrayBuffer;
+    mediaType: string;
 }
 export interface LabsRuntimeResponse {
     account_id: string;
@@ -590,9 +835,11 @@ export interface LabsRuntimeResponse {
 }
 export interface LabsCallListOptions {
     agencyId?: string;
+    agency_id?: string;
     agentKey?: string;
     agent_key?: string;
     limit?: number;
+    offset?: number;
 }
 export interface LabsCallArtifact {
     id?: string;
@@ -602,7 +849,11 @@ export interface LabsCallArtifact {
     started_at?: string;
     duration_seconds?: number;
     recording_url?: string;
+    recording_download_url?: string;
+    recording_archived?: boolean;
     transcript_url?: string;
+    watcher_events?: LabsDeveloperActivityEvent[];
+    watcher_event_count?: number;
     [extra: string]: unknown;
 }
 export interface LabsCallListResponse {
@@ -625,6 +876,37 @@ export interface LabsTranscriptListResponse {
     transcripts: Array<Record<string, unknown>>;
     [extra: string]: unknown;
 }
+export interface LabsDeveloperActivityEvent {
+    id: string;
+    account_id: string;
+    event_type: string;
+    resource_type: string;
+    resource_id: string;
+    source?: string;
+    detail?: Record<string, unknown>;
+    created_at: string;
+    [extra: string]: unknown;
+}
+export interface LabsActivityListOptions {
+    accountId?: string;
+    account_id?: string;
+    agencyId?: string;
+    agency_id?: string;
+    eventType?: string;
+    event_type?: string;
+    resourceType?: string;
+    resource_type?: string;
+    resourceId?: string;
+    resource_id?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface LabsActivityListResponse {
+    events: LabsDeveloperActivityEvent[];
+    count: number;
+    next_offset?: number | null;
+    account_id?: string;
+}
 export interface LabsPhoneNumberSearchOptions {
     agencyId?: string;
     agency_id?: string;
@@ -1086,6 +1368,8 @@ export declare class SupafoneLabs {
     request<T>(method: string, path: string, body?: unknown, useSession?: boolean): Promise<T>;
     /** @internal Authenticated JSON request to the Supafone app API (`/api/v1/labs/*`). */
     requestSupafoneApi<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** @internal Authenticated binary request to the Supafone app API. */
+    requestSupafoneBinary(path: string): Promise<LabsVoicePreview>;
     /**
      * Exchange the account email/password for a product-API JWT (the same login
      * as app.supafone.ai). Called lazily by campaigns/calls — call directly only
@@ -1154,6 +1438,14 @@ export declare class SupafoneLabs {
      * (empty string when the agent is doing fine).
      */
     whisper(transcript: string, opts?: WhisperOptions): Promise<string>;
+    /**
+     * Structured SecondMind guidance with developer-controlled field policy.
+     * Returns null when JSON is invalid, evidence misses the confidence gate,
+     * the generated kind is disallowed, or the local transform suppresses it.
+     */
+    whisperStructured(transcript: string, opts?: StructuredWhisperOptions): Promise<SecondMindDirective | null>;
+    /** Alias that reads naturally in applications building their own watcher loop. */
+    directive(transcript: string, opts?: StructuredWhisperOptions): Promise<SecondMindDirective | null>;
     /** Hosted TTS — returns raw audio bytes (WAV/PCM per voice). */
     tts(text: string, voice?: string): Promise<Uint8Array>;
     /** Convenience alias for voice preview UI/buttons. */
@@ -1513,6 +1805,8 @@ declare class LabsNamespace {
     readonly phoneNumbers: LabsPhoneNumbersNamespace;
     readonly telephony: LabsTelephonyNamespace;
     readonly calls: LabsCallsNamespace;
+    readonly activity: LabsActivityNamespace;
+    readonly plans: LabsPlansNamespace;
     readonly recordings: LabsRecordingsNamespace;
     readonly transcripts: LabsTranscriptsNamespace;
     constructor(sm: SupafoneLabs);
@@ -1610,8 +1904,24 @@ declare class LabsToolsNamespace {
 declare class LabsVoicesNamespace {
     private sm;
     constructor(sm: SupafoneLabs);
-    /** Supafone-managed Cartesia voices. Other TTS engines remain explicit BYOK choices. */
+    /** Live normalized catalog from every connected/managed TTS provider. */
     list(opts?: LabsVoiceListOptions): Promise<LabsVoiceListResponse>;
+    /** Provider/model language limits and their Ultravox-compatible intersection. */
+    capabilities(): Promise<LabsVoiceCapabilitiesResponse>;
+    /** Page through the complete normalized catalog. */
+    listAll(opts?: Omit<LabsVoiceListOptions, "cursor" | "limit"> & {
+        pageSize?: number;
+        maxPages?: number;
+    }): Promise<LabsVoiceListResponse>;
+    /** Rank real current voices from a plain-language description. */
+    recommend(opts: LabsVoiceRecommendOptions): Promise<LabsVoiceRecommendResponse>;
+    /** Download an authenticated voice preview. */
+    preview(voiceId: string, opts?: {
+        agencyId?: string;
+        agency_id?: string;
+    }): Promise<LabsVoicePreview>;
+    /** Convert a catalog row into the exact Agent Factory voice field. */
+    selection(voice: LabsVoiceCatalogItem): LabsVoiceSelection;
 }
 declare class LabsRuntimeNamespace {
     private sm;
@@ -1638,8 +1948,25 @@ declare class LabsCallsNamespace {
     list(opts?: LabsCallListOptions): Promise<LabsCallListResponse>;
     get(callId: string, opts?: {
         agencyId?: string;
+        agency_id?: string;
+    }): Promise<{
+        call: LabsCallArtifact;
+    }>;
+    delete(callId: string, opts?: {
+        agencyId?: string;
+        agency_id?: string;
     }): Promise<Record<string, unknown>>;
 }
+declare class LabsActivityNamespace {
+    private sm;
+    constructor(sm: SupafoneLabs);
+    list(opts?: LabsActivityListOptions): Promise<LabsActivityListResponse>;
+}
+declare class LabsPlansNamespace {
+    private sm;
+    constructor(sm: SupafoneLabs);
+    list(opts?: Omit<LabsActivityListOptions, "eventType" | "event_type" | "resourceType" | "resource_type">): Promise<LabsActivityListResponse>;
+}
 declare class LabsRecordingsNamespace {
     private sm;
     constructor(sm: SupafoneLabs);