supafone-labs 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -9,9 +9,9 @@
  *
  * Works in Node 18+ (native fetch/WebSocket) and the browser.
  *
- *   npm i @supafonesupafone-labs
+ *   npm i supafone-labs
  *
- *   import { Supafone } from "@supafonesupafone-labs";
+ *   import { Supafone } from "supafone-labs";
  *   const supafone = new Supafone({ apiKey: process.env.SUPAFONE_API_KEY! });
  *   const agent = await supafone.labs.agents.createInboundWithNumber({
  *     agentKey: "northline-intake",
@@ -20,7 +20,7 @@
  *   });
  */
 export interface SupafoneLabsOptions {
-    /** Your key from https:/supafone-labs.supafone.ai/get-key.html */
+    /** Your key from https://labs.supafone.ai/get-key.html */
     apiKey: string;
     /** Override the gateway (default: the hosted cloud). */
     baseUrl?: string;
@@ -74,11 +74,39 @@ export interface UsageToday {
         cap: number;
     }>;
 }
+export interface LabsLogEntry {
+    id: number;
+    at: string;
+    endpoint: string;
+    seconds_billed: number;
+    duration_ms: number;
+    detail: string;
+    meta: Record<string, unknown>;
+}
+export interface StreamLogsOptions {
+    limit?: number;
+    afterId?: number;
+    pollMs?: number;
+    snapshot?: boolean;
+    signal?: AbortSignal;
+}
 export type LabsAgentType = "phone" | "web" | "campaign";
 export type LabsAgentStyle = "inbound" | "outbound";
 export type LabsRuntimeMode = "multi_stage" | "single_stage";
 export type LabsTelephonyMode = "supafone_managed" | "byok";
-export type LabsTelephonyProvider = "supafone" | "twilio" | "telnyx" | "plivo" | "sip" | string;
+export type LabsTelephonyProvider = "supafone" | "twilio" | "telnyx" | "plivo" | "signalwire" | "sip" | "custom_sip" | "custom" | string;
+export type LabsNumberStrategy = "default_pool" | "dedicated" | "premium" | "byok" | string;
+export interface LabsCallStage {
+    key?: string;
+    id?: string;
+    name: string;
+    goal?: string;
+    instructions?: string;
+    exitCriteria?: string[];
+    exit_criteria?: string[];
+    tools?: string[];
+    metadata?: Record<string, unknown>;
+}
 export interface LabsVoiceSelection {
     provider?: string;
     voiceId?: string;
@@ -86,9 +114,51 @@ export interface LabsVoiceSelection {
     model?: string;
 }
 export interface LabsProviderKeys {
+    /** Agent runtime/platform providers. */
     ultravox?: string;
     ultravoxApiKey?: string;
     ultravox_api_key?: string;
+    retell?: string;
+    retellApiKey?: string;
+    retell_api_key?: string;
+    vapi?: string;
+    vapiApiKey?: string;
+    vapi_api_key?: string;
+    bland?: string;
+    blandApiKey?: string;
+    bland_api_key?: string;
+    livekit?: string;
+    livekitApiKey?: string;
+    livekit_api_key?: string;
+    livekitApiSecret?: string;
+    livekit_api_secret?: string;
+    pipecat?: string;
+    pipecatApiKey?: string;
+    pipecat_api_key?: string;
+    /** Telephony/carrier providers. */
+    twilio?: string;
+    twilioAccountSid?: string;
+    twilio_account_sid?: string;
+    twilioAuthToken?: string;
+    twilio_auth_token?: string;
+    twilioApiKeySid?: string;
+    twilio_api_key_sid?: string;
+    twilioApiKeySecret?: string;
+    twilio_api_key_secret?: string;
+    telnyx?: string;
+    telnyxApiKey?: string;
+    telnyx_api_key?: string;
+    plivo?: string;
+    plivoAuthId?: string;
+    plivo_auth_id?: string;
+    plivoAuthToken?: string;
+    plivo_auth_token?: string;
+    signalwire?: string;
+    signalwireApiToken?: string;
+    signalwire_api_token?: string;
+    signalwireProjectId?: string;
+    signalwire_project_id?: string;
+    /** TTS providers. */
     elevenlabs?: string;
     elevenlabsApiKey?: string;
     elevenlabs_api_key?: string;
@@ -101,6 +171,62 @@ export interface LabsProviderKeys {
     deepgram?: string;
     deepgramApiKey?: string;
     deepgram_api_key?: string;
+    /** Brain/STT providers used by Labs watcher or customer BYOK stacks. */
+    anthropic?: string;
+    anthropicApiKey?: string;
+    anthropic_api_key?: string;
+    openai?: string;
+    openaiApiKey?: string;
+    openai_api_key?: string;
+    xai?: string;
+    xaiApiKey?: string;
+    xai_api_key?: string;
+    [extra: string]: unknown;
+}
+export interface LabsCustomSipConfig {
+    sipTrunkUri?: string;
+    sip_trunk_uri?: string;
+    trunkUri?: string;
+    trunk_uri?: string;
+    sipHost?: string;
+    sip_host?: string;
+    fromNumber?: string;
+    from_number?: string;
+    username?: string;
+    password?: string;
+    transport?: string;
+    headers?: Record<string, string>;
+    codecs?: string[];
+    dtmfMode?: string;
+    dtmf_mode?: string;
+    metadata?: Record<string, unknown>;
+    [extra: string]: unknown;
+}
+export interface LabsProviderByokConfig {
+    provider?: string;
+    apiKey?: string;
+    api_key?: string;
+    credentials?: Record<string, unknown>;
+    settings?: Record<string, unknown>;
+    model?: string;
+    voiceId?: string;
+    voice_id?: string;
+    [extra: string]: unknown;
+}
+export interface LabsByokConfig {
+    providerKeys?: LabsProviderKeys;
+    provider_keys?: LabsProviderKeys;
+    agentProvider?: LabsProviderByokConfig;
+    agent_provider?: LabsProviderByokConfig;
+    runtime?: LabsProviderByokConfig;
+    telephony?: LabsTelephonyConfig;
+    tts?: LabsProviderByokConfig;
+    stt?: LabsProviderByokConfig;
+    llm?: LabsProviderByokConfig;
+    customSip?: LabsCustomSipConfig;
+    custom_sip?: LabsCustomSipConfig;
+    sip?: LabsCustomSipConfig;
+    [extra: string]: unknown;
 }
 export interface LabsTelephonyCredentials {
     accountSid?: string;
@@ -115,6 +241,20 @@ export interface LabsTelephonyCredentials {
     auth_id?: string;
     connectionId?: string;
     connection_id?: string;
+    telnyxConnectionId?: string;
+    telnyx_connection_id?: string;
+    signalwireSpaceUrl?: string;
+    signalwire_space_url?: string;
+    projectId?: string;
+    project_id?: string;
+    applicationId?: string;
+    application_id?: string;
+    trunkId?: string;
+    trunk_id?: string;
+    endpointId?: string;
+    endpoint_id?: string;
+    token?: string;
+    secret?: string;
     fromNumber?: string;
     from_number?: string;
     sipTrunkUri?: string;
@@ -125,6 +265,9 @@ export interface LabsTelephonyCredentials {
     password?: string;
     webhookSecret?: string;
     webhook_secret?: string;
+    customSip?: LabsCustomSipConfig;
+    custom_sip?: LabsCustomSipConfig;
+    [extra: string]: unknown;
 }
 export interface LabsTelephonyConfig {
     agencyId?: string;
@@ -132,9 +275,22 @@ export interface LabsTelephonyConfig {
     /** Default is Supafone-managed; developers do not need Twilio for this path. */
     mode?: LabsTelephonyMode;
     provider?: LabsTelephonyProvider;
+    /** default_pool reuses idle Supafone numbers; dedicated/premium reserve a number-month. */
+    numberStrategy?: LabsNumberStrategy;
+    number_strategy?: LabsNumberStrategy;
+    numberPool?: string;
+    number_pool?: string;
+    numberId?: string;
+    number_id?: string;
+    premium?: boolean;
     label?: string;
     credentials?: LabsTelephonyCredentials;
+    providerSettings?: Record<string, unknown>;
+    provider_settings?: Record<string, unknown>;
+    customSip?: LabsCustomSipConfig;
+    custom_sip?: LabsCustomSipConfig;
     metadata?: Record<string, unknown>;
+    [extra: string]: unknown;
 }
 export interface LabsToolsConfig {
     callRouting?: boolean;
@@ -154,11 +310,58 @@ export interface LabsToolsConfig {
     customTools?: Array<Record<string, unknown>>;
     custom_tools?: Array<Record<string, unknown>>;
 }
+export interface LabsRecordingConfig {
+    enabled?: boolean;
+    recordAudio?: boolean;
+    record_audio?: boolean;
+    consentRequired?: boolean;
+    consent_required?: boolean;
+    announcement?: string;
+    retentionDays?: number;
+    retention_days?: number;
+    storage?: "supafone_managed" | "byok" | string;
+    redactPii?: boolean;
+    redact_pii?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface LabsTranscriptionConfig {
+    enabled?: boolean;
+    provider?: string;
+    model?: string;
+    language?: string;
+    redactPii?: boolean;
+    redact_pii?: boolean;
+    diarization?: boolean;
+    timestamps?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface LabsArtifactsConfig {
+    recordings?: boolean;
+    transcripts?: boolean;
+    summaries?: boolean;
+    qaReports?: boolean;
+    qa_reports?: boolean;
+    logs?: boolean;
+    webhooks?: boolean;
+    retentionDays?: number;
+    retention_days?: number;
+    metadata?: Record<string, unknown>;
+}
 export interface LabsWatcherConfig {
     enabled?: boolean;
     voiceWatcher?: boolean;
     voice_watcher?: boolean;
+    apiKey?: string;
+    api_key?: string;
     model?: string;
+    mode?: "supafone_managed" | "byok" | string;
+    managedInfrastructure?: boolean;
+    managed_infrastructure?: boolean;
+    stt?: Record<string, unknown>;
+    llm?: Record<string, unknown>;
+    tts?: Record<string, unknown>;
+    providerKeys?: Record<string, unknown>;
+    provider_keys?: Record<string, unknown>;
     label?: string;
 }
 export interface LabsUltravoxRuntime {
@@ -203,6 +406,10 @@ export interface LabsUltravoxRuntime {
     retention_policy?: string;
     callTemplate?: Record<string, unknown>;
     call_template?: Record<string, unknown>;
+    customSip?: LabsCustomSipConfig;
+    custom_sip?: LabsCustomSipConfig;
+    sip?: LabsCustomSipConfig;
+    [extra: string]: unknown;
 }
 export interface CreateLabsAgentRequest {
     agencyId?: string;
@@ -225,11 +432,22 @@ export interface CreateLabsAgentRequest {
     website_url?: string;
     phoneNumber?: string;
     phone_number?: string;
+    numberStrategy?: LabsNumberStrategy;
+    number_strategy?: LabsNumberStrategy;
+    numberPool?: string;
+    number_pool?: string;
+    premium?: boolean;
     direction?: string;
     presetKey?: string;
     preset_key?: string;
     runtimeMode?: LabsRuntimeMode;
     runtime_mode?: LabsRuntimeMode;
+    /** Default true. When true, the SDK creates sensible call stages from prompt metadata. */
+    callStages?: boolean | LabsCallStage[];
+    call_stages?: boolean | LabsCallStage[];
+    stages?: LabsCallStage[];
+    autoCallStages?: boolean;
+    auto_call_stages?: boolean;
     goal?: string;
     greeting?: string;
     systemPrompt?: string;
@@ -238,8 +456,15 @@ export interface CreateLabsAgentRequest {
     voice?: LabsVoiceSelection;
     providerKeys?: LabsProviderKeys;
     provider_keys?: LabsProviderKeys;
-    byok?: LabsProviderKeys;
+    byok?: LabsProviderKeys | LabsByokConfig;
     telephony?: LabsTelephonyConfig;
+    customSip?: LabsCustomSipConfig;
+    custom_sip?: LabsCustomSipConfig;
+    sip?: LabsCustomSipConfig;
+    recording?: LabsRecordingConfig;
+    transcription?: LabsTranscriptionConfig;
+    artifacts?: LabsArtifactsConfig;
+    compliance?: Record<string, unknown>;
     tools?: LabsToolsConfig;
     labs?: LabsWatcherConfig;
     ultravox?: LabsUltravoxRuntime;
@@ -256,6 +481,19 @@ export interface ListLabsAgentsOptions {
 }
 export interface GetLabsAgentOptions extends ListLabsAgentsOptions {
 }
+export interface DeleteLabsAgentOptions {
+    agencyId?: string;
+    agency_id?: string;
+    releaseNumbers?: boolean;
+    release_numbers?: boolean;
+}
+export interface DeleteLabsAgentResponse {
+    success?: boolean;
+    deleted?: boolean;
+    agent_key?: string;
+    released_numbers?: unknown[];
+    [extra: string]: unknown;
+}
 export interface LabsCapabilitiesResponse {
     product: string;
     api_namespace: string;
@@ -283,9 +521,50 @@ export interface LabsVoiceListResponse {
     provider_accounts?: Record<string, unknown>;
     errors?: Record<string, string>;
 }
+export interface LabsCallListOptions {
+    agencyId?: string;
+    agentKey?: string;
+    agent_key?: string;
+    limit?: number;
+}
+export interface LabsCallArtifact {
+    id?: string;
+    call_id?: string;
+    agent_key?: string;
+    status?: string;
+    started_at?: string;
+    duration_seconds?: number;
+    recording_url?: string;
+    transcript_url?: string;
+    [extra: string]: unknown;
+}
+export interface LabsCallListResponse {
+    calls: LabsCallArtifact[];
+    [extra: string]: unknown;
+}
+export interface LabsRecordingListOptions extends LabsCallListOptions {
+    callId?: string;
+    call_id?: string;
+}
+export interface LabsRecordingListResponse {
+    recordings: Array<Record<string, unknown>>;
+    [extra: string]: unknown;
+}
+export interface LabsTranscriptListOptions extends LabsCallListOptions {
+    callId?: string;
+    call_id?: string;
+}
+export interface LabsTranscriptListResponse {
+    transcripts: Array<Record<string, unknown>>;
+    [extra: string]: unknown;
+}
 export interface LabsPhoneNumberSearchOptions {
     agencyId?: string;
     agency_id?: string;
+    numberPool?: string;
+    number_pool?: string;
+    numberStrategy?: LabsNumberStrategy;
+    number_strategy?: LabsNumberStrategy;
     countryCode?: string;
     country_code?: string;
     areaCode?: string;
@@ -354,6 +633,11 @@ export interface LabsPhoneNumberProvisionRequest {
     agent_name?: string;
     presetKey?: string;
     preset_key?: string;
+    numberStrategy?: LabsNumberStrategy;
+    number_strategy?: LabsNumberStrategy;
+    numberPool?: string;
+    number_pool?: string;
+    premium?: boolean;
     style?: LabsAgentStyle;
     agentStyle?: LabsAgentStyle;
     agent_style?: LabsAgentStyle;
@@ -363,6 +647,14 @@ export interface LabsPhoneNumberProvisionRequest {
 }
 export interface LabsPhoneNumberAssignRequest extends Omit<LabsPhoneNumberProvisionRequest, "phoneNumber" | "phone_number" | "departmentId" | "department_id"> {
 }
+export interface LabsPhoneNumberReleaseRequest {
+    agencyId?: string;
+    agency_id?: string;
+    reason?: string;
+    returnToPool?: boolean;
+    return_to_pool?: boolean;
+    metadata?: Record<string, unknown>;
+}
 export interface LabsPhoneNumberProvisionResponse {
     success: boolean;
     number: LabsPhoneNumberRecord;
@@ -375,6 +667,13 @@ export interface LabsPhoneNumberAssignResponse {
     number: LabsPhoneNumberRecord;
     assignment?: Record<string, unknown>;
 }
+export interface LabsPhoneNumberReleaseResponse {
+    success: boolean;
+    number?: LabsPhoneNumberRecord;
+    released?: boolean;
+    returned_to_pool?: boolean;
+    [extra: string]: unknown;
+}
 export interface LabsPhoneNumberBuyAndAssignRequest extends LabsPhoneNumberProvisionRequest {
     search?: LabsPhoneNumberSearchOptions;
 }
@@ -526,7 +825,7 @@ export declare class SupafoneLabs {
     login(email: string, password: string): Promise<void>;
     /** @internal Authenticated JSON request. `useSession` prefers the login token. */
     request<T>(method: string, path: string, body?: unknown, useSession?: boolean): Promise<T>;
-    /** @internal Authenticated JSON request to the Supafone app API (`/api/v1supafone-labs/*`). */
+    /** @internal Authenticated JSON request to the Supafone app API (`/api/v1/labs/*`). */
     requestSupafoneApi<T>(method: string, path: string, body?: unknown): Promise<T>;
     /** Raw oracle completion — full control over messages and model. */
     oracle(req: OracleRequest): Promise<OracleResult>;
@@ -537,6 +836,8 @@ export declare class SupafoneLabs {
     whisper(transcript: string, opts?: WhisperOptions): Promise<string>;
     /** Hosted TTS — returns raw audio bytes (WAV/PCM per voice). */
     tts(text: string, voice?: string): Promise<Uint8Array>;
+    /** Convenience alias for voice preview UI/buttons. */
+    previewVoice(voice?: string, text?: string): Promise<Uint8Array>;
     /** Hosted STT for a finished audio clip — returns transcript + language tags. */
     stt(audio: Uint8Array | ArrayBuffer, opts?: {
         language?: string;
@@ -554,8 +855,10 @@ export declare class SupafoneLabs {
     usage(): Promise<UsageToday>;
     /** The auditable whisper/billing log. */
     logs(limit?: number): Promise<{
-        logs: unknown[];
+        logs: LabsLogEntry[];
     }>;
+    /** Live audit-log stream. Works in Node 18+ and browsers via fetch streaming. */
+    streamLogs(opts?: StreamLogsOptions): AsyncGenerator<LabsLogEntry>;
     /** The structured whisper feed (what the console shows). */
     nudges(limit?: number): Promise<{
         nudges: unknown[];
@@ -572,6 +875,10 @@ export declare class SupafoneLabs {
     models(): Promise<string[]>;
     /** Available TTS voice ids. */
     voices(): Promise<string[]>;
+    /** Full hosted voice catalog with provider live/configured flags. */
+    voiceCatalog(): Promise<{
+        voices: Array<Record<string, unknown>>;
+    }>;
 }
 export interface LiveTranscribeOptions {
     language?: string;
@@ -606,6 +913,9 @@ declare class LabsNamespace {
     readonly voices: LabsVoicesNamespace;
     readonly phoneNumbers: LabsPhoneNumbersNamespace;
     readonly telephony: LabsTelephonyNamespace;
+    readonly calls: LabsCallsNamespace;
+    readonly recordings: LabsRecordingsNamespace;
+    readonly transcripts: LabsTranscriptsNamespace;
     constructor(sm: SupafoneLabs);
     /** Discover the Supafone convenience layer over Ultravox. */
     capabilities(): Promise<LabsCapabilitiesResponse>;
@@ -633,6 +943,8 @@ declare class LabsAgentsNamespace {
     list(opts?: ListLabsAgentsOptions): Promise<ListLabsAgentsResponse>;
     /** Fetch one durable agent by key. */
     get(agentKey: string, opts?: GetLabsAgentOptions): Promise<GetLabsAgentResponse>;
+    /** Delete an agent. Optionally ask the backend to release assigned numbers. */
+    delete(agentKey: string, opts?: DeleteLabsAgentOptions): Promise<DeleteLabsAgentResponse>;
 }
 declare class LabsPresetsNamespace {
     private sm;
@@ -652,6 +964,34 @@ declare class LabsVoicesNamespace {
     /** Supafone-managed Ultravox, Cartesia, Inworld, and ElevenLabs-compatible voices. */
     list(opts?: LabsVoiceListOptions): Promise<LabsVoiceListResponse>;
 }
+declare class LabsCallsNamespace {
+    private sm;
+    constructor(sm: SupafoneLabs);
+    list(opts?: LabsCallListOptions): Promise<LabsCallListResponse>;
+    get(callId: string, opts?: {
+        agencyId?: string;
+    }): Promise<Record<string, unknown>>;
+}
+declare class LabsRecordingsNamespace {
+    private sm;
+    constructor(sm: SupafoneLabs);
+    list(opts?: LabsRecordingListOptions): Promise<LabsRecordingListResponse>;
+    get(recordingId: string, opts?: {
+        agencyId?: string;
+    }): Promise<Record<string, unknown>>;
+    delete(recordingId: string, opts?: {
+        agencyId?: string;
+        reason?: string;
+    }): Promise<Record<string, unknown>>;
+}
+declare class LabsTranscriptsNamespace {
+    private sm;
+    constructor(sm: SupafoneLabs);
+    list(opts?: LabsTranscriptListOptions): Promise<LabsTranscriptListResponse>;
+    get(transcriptId: string, opts?: {
+        agencyId?: string;
+    }): Promise<Record<string, unknown>>;
+}
 declare class LabsPhoneNumbersNamespace {
     private sm;
     constructor(sm: SupafoneLabs);
@@ -663,6 +1003,14 @@ declare class LabsPhoneNumbersNamespace {
     buy(input: LabsPhoneNumberProvisionRequest): Promise<LabsPhoneNumberProvisionResponse>;
     /** Attach an existing Supafone number to an inbound or outbound agent. */
     assign(numberId: string, input?: LabsPhoneNumberAssignRequest): Promise<LabsPhoneNumberAssignResponse>;
+    /** Unassign a number from an agent but keep it reserved on the account. */
+    unassign(numberId: string, input?: LabsPhoneNumberReleaseRequest): Promise<LabsPhoneNumberReleaseResponse>;
+    /** Give a number back to the shared pool or release the reservation. */
+    release(numberId: string, input?: LabsPhoneNumberReleaseRequest): Promise<LabsPhoneNumberReleaseResponse>;
+    /** Alias for release(numberId, { returnToPool: true }). */
+    returnToPool(numberId: string, input?: LabsPhoneNumberReleaseRequest): Promise<LabsPhoneNumberReleaseResponse>;
+    /** Delete/release a number reservation. Backend policy decides whether this is allowed. */
+    delete(numberId: string, input?: LabsPhoneNumberReleaseRequest): Promise<LabsPhoneNumberReleaseResponse>;
     /**
      * Search if needed, buy the first matching Supafone-managed number, and assign
      * it to the supplied agent. This is the zero-Twilio-account happy path.
@@ -727,11 +1075,21 @@ declare class OptimizerNamespace {
         version: number;
         text: string;
     }>;
+    /** SSR grade distribution: five nominal levels folded into a real score distribution. */
+    distribution(agent?: string, limit?: number): Promise<{
+        agent: string;
+        calls: number;
+        counts: Record<string, number>;
+        mean_score: number;
+        buckets: number[];
+        bucket_edges: number[];
+    }>;
     /** List the post-call reports behind the optimizer. */
     reports(agent?: string, limit?: number): Promise<{
         reports: unknown[];
     }>;
 }
+export declare function generateCallStages(input: CreateLabsAgentRequest): LabsCallStage[];
 export { SupafoneLabs as Supafone };
 export default SupafoneLabs;
 //# sourceMappingURL=index.d.ts.map