supafone-labs 0.4.14 → 0.5.2

package/README.md

@@ -132,6 +132,26 @@ The first configured language owns the opening, and a non-English primary
 greeting is translated during provisioning. See
 [Live Language and Voice Routing](../gitbook/live-language-voice-routing.md).
 
+Outbound agents can opt into temporary, bounded phone-tree navigation without
+changing their normal campaign objective:
+
+```ts
+await supafone.labs.agents.createOutbound({
+  name: "Benefits verification",
+  outboundCallMode: {
+    enabled: true,
+    maxDurationSeconds: 180,
+    maxKeypresses: 12,
+  },
+});
+```
+
+The SDK stores this provider-neutral contract and exposes fail-closed adapter
+readiness checks. Supafone-managed, Twilio, Telnyx, Plivo, SignalWire, and
+SIP/BYOC use the same public shape; private detection and DTMF execution stay in
+the managed runtime. See
+[Outbound IVR Call Mode](../docs/outbound-ivr-call-mode.md).
+
 BYOK is advanced and split into three independent lanes:
 
 | Lane | Examples |
@@ -515,6 +535,10 @@ and `const { Supafone } = require("supafone-labs")` both work, with full types.
 | `labs.capabilities()` | `GET /api/v1/labs/capabilities` on the Supafone API |
 | `labs.agents.create/createInbound/createOutbound/list/get` | `/api/v1/labs/agents*` on the Supafone API |
 | `labs.agents.createInboundWithNumber/createOutboundWithNumber` | Agent creation plus Supafone-managed number buy/assign |
+| `labs.agents.update/readiness/activate/pause/delete` | Durable agent lifecycle using `agent_key` |
+| `labs.agents.startWebRtcCall` | Browser voice test using the durable `agent.id` |
+| `labs.agents.syncKnowledge/detachWebsiteKnowledge/reindexKnowledge` | Managed website corpus lifecycle using `agent.id` |
+| `labs.agents.uploadKnowledgeDocument/deleteKnowledgeDocument/chatKnowledge` | Account-isolated document and grounded-query methods |
 | `labs.phoneNumbers.search/buy/assign/list/buyAndAssign` | `/api/v1/labs/phone-numbers*` |
 | `labs.billing.checkout/status/portal` | Stripe-hosted Checkout, payment polling, and Customer Portal |
 | `labs.telephony.get/configure/useSupafoneManaged` | `/api/v1/labs/telephony` |

package/dist/cjs/index.d.ts

@@ -257,16 +257,37 @@ export interface LabsVoiceProviderTraits {
     is_public?: boolean | null;
     is_owner?: boolean | null;
 }
+/** Stable provider presentation metadata returned by the hosted catalog. */
+export interface LabsVoiceProviderBrand {
+    /** Canonical provider key used for filtering and grouping. */
+    key: string;
+    /** Human-readable provider/company name. */
+    name: string;
+    /** Stable local asset slug when Supafone has an official provider mark. */
+    logo_slug?: string | null;
+    /** Absolute, browser-ready provider logo URL. */
+    logo_url?: string | null;
+    /** Provider's official product or company website. */
+    website_url?: string | 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 brand display name for the synthesis provider. */
+    provider_label?: string;
+    /** Browser-ready official provider mark, or null for an unknown provider. */
+    provider_logo_url?: string | null;
+    /** Branding for the provider that renders the voice. */
+    provider_brand?: LabsVoiceProviderBrand;
     /** Canonical SDK/runtime provider key. */
     provider_key: string;
     /** Runtime adapter used to place the voice on an Ultravox call. */
     runtime_provider_key: string;
+    /** Branding for the realtime runtime, which can differ from synthesis. */
+    runtime_provider_brand?: LabsVoiceProviderBrand;
     /** Actual TTS engine behind the voice (can differ for Ultravox built-ins). */
     synthesis_provider_key: string;
     /** Raw identifier used by the provider API. */
@@ -622,6 +643,95 @@ export interface LabsUltravoxRuntime {
     sip?: LabsCustomSipConfig;
     [extra: string]: unknown;
 }
+export interface OutboundCallModeObservability {
+    enabled?: boolean;
+    includeTrigger?: boolean;
+    includeTransitions?: boolean;
+    includeTerminationReason?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Public, provider-neutral controls for temporary outbound IVR navigation. */
+export interface OutboundCallModeConfig {
+    enabled?: boolean;
+    autoDetect?: boolean;
+    dtmfToolEnabled?: boolean;
+    maxDurationSeconds?: number;
+    maxKeypresses?: number;
+    repeatedMenuLimit?: number;
+    noProgressTimeoutSeconds?: number;
+    humanDetectionEnabled?: boolean;
+    resumeOnHuman?: boolean;
+    observability?: OutboundCallModeObservability;
+}
+/** Capabilities positively reported by the active telephony/runtime adapter. */
+export interface OutboundCallModeCapabilities {
+    provider?: string;
+    dtmf?: boolean;
+    statePersistence?: boolean;
+    humanDetection?: boolean;
+    observability?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface OutboundCallModeReadiness {
+    ready: boolean;
+    status: "disabled" | "ready" | "unknown" | "unsupported";
+    provider: string;
+    transportFamily: string;
+    requiredCapabilities: string[];
+    missingCapabilities: string[];
+    unsupportedCapabilities: string[];
+    reasons: string[];
+}
+export declare const OUTBOUND_CALL_MODE_BOUNDS: {
+    readonly maxDurationSeconds: {
+        readonly default: 180;
+        readonly min: 30;
+        readonly max: 900;
+    };
+    readonly maxKeypresses: {
+        readonly default: 12;
+        readonly min: 1;
+        readonly max: 64;
+    };
+    readonly repeatedMenuLimit: {
+        readonly default: 3;
+        readonly min: 1;
+        readonly max: 10;
+    };
+    readonly noProgressTimeoutSeconds: {
+        readonly default: 30;
+        readonly min: 5;
+        readonly max: 120;
+    };
+};
+export declare const OUTBOUND_CALL_MODE_DEFAULTS: {
+    readonly enabled: false;
+    readonly autoDetect: true;
+    readonly dtmfToolEnabled: true;
+    readonly maxDurationSeconds: 180;
+    readonly maxKeypresses: 12;
+    readonly repeatedMenuLimit: 3;
+    readonly noProgressTimeoutSeconds: 30;
+    readonly humanDetectionEnabled: true;
+    readonly resumeOnHuman: true;
+    readonly observability: {
+        readonly enabled: true;
+        readonly includeTrigger: true;
+        readonly includeTransitions: true;
+        readonly includeTerminationReason: true;
+    };
+};
+export interface OutboundCallModeProviderProfile {
+    contractSupported: boolean;
+    execution: "adapter_runtime_dependent";
+    capabilityPolicy: "fail_closed";
+    transportFamily: string;
+    providers: readonly string[];
+    requiredCapabilities: readonly string[];
+}
+export declare const OUTBOUND_CALL_MODE_PROVIDER_MATRIX: Record<string, OutboundCallModeProviderProfile>;
+export declare function outboundCallModeProviderProfile(provider: string): OutboundCallModeProviderProfile;
+export declare function outboundCallModeReadiness(config?: OutboundCallModeConfig, capabilities?: OutboundCallModeCapabilities): OutboundCallModeReadiness;
 export interface CreateLabsAgentRequest {
     agencyId?: string;
     agency_id?: string;
@@ -706,6 +816,9 @@ export interface CreateLabsAgentRequest {
     voice_watcher?: boolean;
     voiceWatcherModel?: string;
     voice_watcher_model?: string;
+    /** Opt-in outbound IVR mode. Execution depends on adapter-reported readiness. */
+    outboundCallMode?: OutboundCallModeConfig;
+    outbound_call_mode?: OutboundCallModeConfig;
     metadata?: Record<string, unknown>;
 }
 export interface ListLabsAgentsOptions {
@@ -728,6 +841,41 @@ export interface DeleteLabsAgentResponse {
     released_numbers?: unknown[];
     [extra: string]: unknown;
 }
+export type LabsAgentLifecycle = "draft" | "active" | "paused" | "archived" | string;
+export interface LabsAgentReadiness {
+    ready: boolean;
+    status?: string;
+    checks?: Array<Record<string, unknown>>;
+    [extra: string]: unknown;
+}
+export type UpdateLabsAgentRequest = Partial<CreateLabsAgentRequest>;
+export interface LabsAgentLifecycleResponse {
+    success?: boolean;
+    agent?: LabsAgentResponse;
+    lifecycle?: LabsAgentLifecycle;
+    readiness?: LabsAgentReadiness;
+    [extra: string]: unknown;
+}
+export interface LabsKnowledgeSyncRequest {
+    websiteUrl?: string;
+    website_url?: string;
+    url?: string;
+}
+export interface LabsKnowledgeSyncResponse {
+    agent: LabsAgentResponse;
+    chunks_indexed?: number;
+    scraped_ok?: boolean;
+    last_error?: string | null;
+    website_detached?: boolean;
+}
+export interface LabsKnowledgeChatTurn {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface LabsKnowledgeChatResponse {
+    reply: string;
+    sources: string[];
+}
 export interface LabsCapabilitiesResponse {
     product: string;
     api_namespace: string;
@@ -778,7 +926,10 @@ export interface LabsVoiceListResponse {
         configured: boolean;
         voice_count: number;
         error?: string | null;
+        brand?: LabsVoiceProviderBrand;
     }>;
+    /** Distinct synthesis-provider brands represented in the complete result. */
+    provider_brands?: LabsVoiceProviderBrand[];
     provider_accounts?: Record<string, unknown>;
     errors?: Record<string, string>;
     catalog?: {
@@ -1068,6 +1219,8 @@ export interface LabsAgentResponse {
     display_name?: string;
     runtime_mode?: string;
     preset_key?: string;
+    status?: string;
+    lifecycle?: LabsAgentLifecycle;
     profile?: Record<string, unknown>;
     runtime?: Record<string, unknown>;
     [extra: string]: unknown;
@@ -1100,6 +1253,9 @@ export interface ListLabsAgentsResponse {
 }
 export interface GetLabsAgentResponse {
     agent: LabsAgentResponse;
+    runtime?: Record<string, unknown>;
+    widget?: Record<string, unknown>;
+    readiness?: LabsAgentReadiness;
 }
 export interface STTResult {
     transcript: string;
@@ -1394,6 +1550,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 Multipart upload to the Supafone product API with the Labs key. */
+    requestSupafoneUpload<T>(path: string, file: Uint8Array | ArrayBuffer | Blob, filename: string): Promise<T>;
     /** @internal Authenticated binary request to the Supafone app API. */
     requestSupafoneBinary(path: string): Promise<LabsVoicePreview>;
     /**
@@ -1625,6 +1783,14 @@ export interface CampaignLiveView {
     portal_url: string;
     stats?: Record<string, unknown> | null;
 }
+export interface CampaignCreateInput {
+    name?: string;
+    goal?: string;
+    agentId?: string;
+    accountId?: string;
+    settings?: Record<string, unknown>;
+    outboundCallMode?: OutboundCallModeConfig;
+}
 export interface CampaignUpdateInput {
     name?: string;
     goal?: string;
@@ -1636,6 +1802,7 @@ export interface CampaignUpdateInput {
         delay_hours: number;
     }[];
     settings?: Record<string, unknown>;
+    outboundCallMode?: OutboundCallModeConfig;
 }
 export interface BrandScanResult {
     url: string;
@@ -1699,12 +1866,7 @@ declare class CampaignsNamespace {
     }): Promise<{
         campaigns: CampaignSummary[];
     }>;
-    create(opts?: {
-        name?: string;
-        goal?: string;
-        agentId?: string;
-        accountId?: string;
-    }): Promise<{
+    create(opts?: CampaignCreateInput): Promise<{
         campaign: CampaignSummary;
     }>;
     get(campaignId: string): Promise<{
@@ -1912,6 +2074,32 @@ declare class LabsAgentsNamespace {
     list(opts?: ListLabsAgentsOptions): Promise<ListLabsAgentsResponse>;
     /** Fetch one durable agent by key. */
     get(agentKey: string, opts?: GetLabsAgentOptions): Promise<GetLabsAgentResponse>;
+    /** Update an existing durable agent without changing omitted fields. */
+    update(agentKey: string, input: UpdateLabsAgentRequest, opts?: GetLabsAgentOptions): Promise<LabsAgentLifecycleResponse>;
+    /** Scrape a website and rebuild this agent's managed knowledge corpus. */
+    syncKnowledge(agentId: string, input?: LabsKnowledgeSyncRequest): Promise<LabsKnowledgeSyncResponse>;
+    /** Remove website knowledge while preserving uploaded documents and notes. */
+    detachWebsiteKnowledge(agentId: string): Promise<LabsKnowledgeSyncResponse>;
+    /** Ask the managed server whether this agent is ready to activate. */
+    readiness(agentKey: string, opts?: GetLabsAgentOptions): Promise<LabsAgentReadiness>;
+    /** Activate a ready hosted agent. */
+    activate(agentKey: string, opts?: GetLabsAgentOptions): Promise<LabsAgentLifecycleResponse>;
+    /** Pause a hosted agent without deleting it. */
+    pause(agentKey: string, opts?: GetLabsAgentOptions): Promise<LabsAgentLifecycleResponse>;
+    /** Start the native provider-neutral browser voice session for this agent. */
+    startWebRtcCall(agentId: string): Promise<WebRtcCallResult>;
+    /** Rebuild retrieval data from the agent's already saved knowledge sources. */
+    reindexKnowledge(agentId: string): Promise<Record<string, unknown>>;
+    /** Upload and index a txt, md, csv, or PDF knowledge document. */
+    uploadKnowledgeDocument(agentId: string, file: Uint8Array | ArrayBuffer | Blob, filename: string): Promise<{
+        agent: LabsAgentResponse;
+    }>;
+    /** Delete one document and rebuild the agent's managed corpus. */
+    deleteKnowledgeDocument(agentId: string, documentId: string): Promise<{
+        agent: LabsAgentResponse;
+    }>;
+    /** Ask a grounded question against the same corpus used during calls. */
+    chatKnowledge(agentId: string, message: string, history?: LabsKnowledgeChatTurn[]): Promise<LabsKnowledgeChatResponse>;
     /** Delete an agent. Optionally ask the backend to release assigned numbers. */
     delete(agentKey: string, opts?: DeleteLabsAgentOptions): Promise<DeleteLabsAgentResponse>;
 }