supafone-labs 0.4.14 → 0.5.0

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 |

package/dist/cjs/index.d.ts

@@ -622,6 +622,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 +795,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 +820,21 @@ 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 LabsCapabilitiesResponse {
     product: string;
     api_namespace: string;
@@ -1068,6 +1175,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 +1209,9 @@ export interface ListLabsAgentsResponse {
 }
 export interface GetLabsAgentResponse {
     agent: LabsAgentResponse;
+    runtime?: Record<string, unknown>;
+    widget?: Record<string, unknown>;
+    readiness?: LabsAgentReadiness;
 }
 export interface STTResult {
     transcript: string;
@@ -1625,6 +1737,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 +1756,7 @@ export interface CampaignUpdateInput {
         delay_hours: number;
     }[];
     settings?: Record<string, unknown>;
+    outboundCallMode?: OutboundCallModeConfig;
 }
 export interface BrandScanResult {
     url: string;
@@ -1699,12 +1820,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 +2028,14 @@ 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>;
+    /** 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>;
     /** Delete an agent. Optionally ask the backend to release assigned numbers. */
     delete(agentKey: string, opts?: DeleteLabsAgentOptions): Promise<DeleteLabsAgentResponse>;
 }

package/dist/cjs/index.js

@@ -21,8 +21,131 @@
  *   });
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Supafone = exports.SupafoneLabs = exports.SupafoneLabsError = void 0;
+exports.Supafone = exports.SupafoneLabs = exports.SupafoneLabsError = exports.OUTBOUND_CALL_MODE_PROVIDER_MATRIX = exports.OUTBOUND_CALL_MODE_DEFAULTS = exports.OUTBOUND_CALL_MODE_BOUNDS = void 0;
+exports.outboundCallModeProviderProfile = outboundCallModeProviderProfile;
+exports.outboundCallModeReadiness = outboundCallModeReadiness;
 exports.generateCallStages = generateCallStages;
+exports.OUTBOUND_CALL_MODE_BOUNDS = {
+    maxDurationSeconds: { default: 180, min: 30, max: 900 },
+    maxKeypresses: { default: 12, min: 1, max: 64 },
+    repeatedMenuLimit: { default: 3, min: 1, max: 10 },
+    noProgressTimeoutSeconds: { default: 30, min: 5, max: 120 },
+};
+exports.OUTBOUND_CALL_MODE_DEFAULTS = {
+    enabled: false,
+    autoDetect: true,
+    dtmfToolEnabled: true,
+    maxDurationSeconds: 180,
+    maxKeypresses: 12,
+    repeatedMenuLimit: 3,
+    noProgressTimeoutSeconds: 30,
+    humanDetectionEnabled: true,
+    resumeOnHuman: true,
+    observability: {
+        enabled: true,
+        includeTrigger: true,
+        includeTransitions: true,
+        includeTerminationReason: true,
+    },
+};
+const OUTBOUND_PROVIDER_PROFILE_BASE = {
+    contractSupported: true,
+    execution: "adapter_runtime_dependent",
+    capabilityPolicy: "fail_closed",
+    requiredCapabilities: ["dtmf", "state_persistence", "human_detection"],
+};
+exports.OUTBOUND_CALL_MODE_PROVIDER_MATRIX = {
+    supafoneManaged: {
+        ...OUTBOUND_PROVIDER_PROFILE_BASE,
+        transportFamily: "supafone_managed",
+        providers: ["supafone", "supafone_managed", "managed"],
+    },
+    twilio: {
+        ...OUTBOUND_PROVIDER_PROFILE_BASE,
+        transportFamily: "twilio",
+        providers: ["twilio", "byo_twilio"],
+    },
+    telnyx: {
+        ...OUTBOUND_PROVIDER_PROFILE_BASE,
+        transportFamily: "telnyx",
+        providers: ["telnyx", "byo_telnyx"],
+    },
+    plivo: {
+        ...OUTBOUND_PROVIDER_PROFILE_BASE,
+        transportFamily: "plivo",
+        providers: ["plivo", "byo_plivo"],
+    },
+    signalWire: {
+        ...OUTBOUND_PROVIDER_PROFILE_BASE,
+        transportFamily: "signalwire",
+        providers: ["signalwire", "signal_wire", "byo_signalwire"],
+    },
+    sipByoc: {
+        ...OUTBOUND_PROVIDER_PROFILE_BASE,
+        transportFamily: "sip_byoc",
+        providers: ["sip", "custom_sip", "byo_sip", "byoc", "sip_byoc"],
+    },
+};
+function outboundCallModeProviderProfile(provider) {
+    const normalized = String(provider ?? "").trim().toLowerCase();
+    for (const profile of Object.values(exports.OUTBOUND_CALL_MODE_PROVIDER_MATRIX)) {
+        if (profile.providers.includes(normalized)) {
+            return { ...profile, providers: [...profile.providers] };
+        }
+    }
+    return {
+        contractSupported: false,
+        execution: "adapter_runtime_dependent",
+        capabilityPolicy: "fail_closed",
+        transportFamily: "unknown",
+        providers: normalized ? [normalized] : [],
+        requiredCapabilities: ["dtmf", "state_persistence", "human_detection"],
+    };
+}
+function outboundCallModeReadiness(config, capabilities) {
+    const provider = String(capabilities?.provider ?? "");
+    const profile = outboundCallModeProviderProfile(provider);
+    const normalized = outboundCallModePayload(config ?? {});
+    if (normalized.enabled !== true) {
+        return {
+            ready: true,
+            status: "disabled",
+            provider,
+            transportFamily: profile.transportFamily,
+            requiredCapabilities: [],
+            missingCapabilities: [],
+            unsupportedCapabilities: [],
+            reasons: [],
+        };
+    }
+    const requiredCapabilities = [...normalized.required_capabilities];
+    const reported = {
+        dtmf: capabilities?.dtmf,
+        state_persistence: capabilities?.statePersistence,
+        human_detection: capabilities?.humanDetection,
+        observability: capabilities?.observability,
+    };
+    const missingCapabilities = requiredCapabilities.filter((key) => reported[key] === undefined);
+    const unsupportedCapabilities = requiredCapabilities.filter((key) => reported[key] === false);
+    const status = unsupportedCapabilities.length
+        ? "unsupported"
+        : missingCapabilities.length
+            ? "unknown"
+            : "ready";
+    const reasons = unsupportedCapabilities.length
+        ? unsupportedCapabilities.map((key) => `Adapter reports ${key} is unsupported.`)
+        : missingCapabilities.map((key) => `Adapter did not report ${key} support.`);
+    return {
+        ready: status === "ready",
+        status,
+        provider,
+        transportFamily: profile.transportFamily,
+        requiredCapabilities,
+        missingCapabilities,
+        unsupportedCapabilities,
+        reasons,
+    };
+}
 class SupafoneLabsError extends Error {
     status;
     body;
@@ -770,18 +893,26 @@ class CampaignsNamespace {
         const query = opts.accountId ? `?${new URLSearchParams({ account_id: opts.accountId })}` : "";
         return this.sm.requestAccountApi("GET", `/api/v1/campaigns${query}`);
     }
-    create(opts = {}) {
-        return this.sm.requestAccountApi("POST", "/api/v1/campaigns", compact({
+    async create(opts = {}) {
+        const created = await this.sm.requestAccountApi("POST", "/api/v1/campaigns", compact({
             name: opts.name ?? "New campaign",
             goal: opts.goal ?? "book",
             agent_id: opts.agentId,
             account_id: opts.accountId,
         }));
+        const settings = campaignSettingsPayload(opts.settings, opts.outboundCallMode);
+        if (!Object.keys(settings).length)
+            return created;
+        if (!created.campaign?.id) {
+            throw new SupafoneLabsError("Campaign was created but no campaign id was returned; outbound call mode was not saved.");
+        }
+        return this.update(created.campaign.id, { settings });
     }
     get(campaignId) {
         return this.sm.requestAccountApi("GET", `/api/v1/campaigns/${encodeURIComponent(campaignId)}`);
     }
     update(campaignId, input) {
+        const settings = campaignSettingsPayload(input.settings, input.outboundCallMode);
         const payload = compact({
             name: input.name,
             goal: input.goal,
@@ -789,10 +920,10 @@ class CampaignsNamespace {
             email_subject: input.emailSubject,
             email_body: input.emailBody,
             cadence: input.cadence,
-            settings: input.settings,
+            settings: Object.keys(settings).length ? settings : undefined,
         });
         if (!Object.keys(payload).length) {
-            throw new SupafoneLabsError("Nothing to update — pass name, goal, agentId, emailSubject, emailBody, cadence, or settings");
+            throw new SupafoneLabsError("Nothing to update — pass name, goal, agentId, emailSubject, emailBody, cadence, settings, or outboundCallMode");
         }
         return this.sm.requestAccountApi("PUT", `/api/v1/campaigns/${encodeURIComponent(campaignId)}`, payload);
     }
@@ -1119,6 +1250,38 @@ class LabsAgentsNamespace {
         const suffix = q.toString() ? `?${q}` : "";
         return this.sm.requestSupafoneApi("GET", `/api/v1/labs/agents/${encodeURIComponent(agentKey)}${suffix}`);
     }
+    /** Update an existing durable agent without changing omitted fields. */
+    update(agentKey, input, opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.agencyId)
+            q.set("agency_id", opts.agencyId);
+        const suffix = q.toString() ? `?${q}` : "";
+        return this.sm.requestSupafoneApi("PATCH", `/api/v1/labs/agents/${encodeURIComponent(agentKey)}${suffix}`, labsAgentUpdatePayload(input));
+    }
+    /** Ask the managed server whether this agent is ready to activate. */
+    readiness(agentKey, opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.agencyId)
+            q.set("agency_id", opts.agencyId);
+        const suffix = q.toString() ? `?${q}` : "";
+        return this.sm.requestSupafoneApi("GET", `/api/v1/labs/agents/${encodeURIComponent(agentKey)}/readiness${suffix}`);
+    }
+    /** Activate a ready hosted agent. */
+    activate(agentKey, opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.agencyId)
+            q.set("agency_id", opts.agencyId);
+        const suffix = q.toString() ? `?${q}` : "";
+        return this.sm.requestSupafoneApi("POST", `/api/v1/labs/agents/${encodeURIComponent(agentKey)}/activate${suffix}`);
+    }
+    /** Pause a hosted agent without deleting it. */
+    pause(agentKey, opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.agencyId)
+            q.set("agency_id", opts.agencyId);
+        const suffix = q.toString() ? `?${q}` : "";
+        return this.sm.requestSupafoneApi("POST", `/api/v1/labs/agents/${encodeURIComponent(agentKey)}/pause${suffix}`);
+    }
     /** Delete an agent. Optionally ask the backend to release assigned numbers. */
     delete(agentKey, opts = {}) {
         const q = new URLSearchParams();
@@ -1664,6 +1827,94 @@ class OptimizerNamespace {
         return this.sm.request("GET", `/v1/optimizer/reports?agent=${encodeURIComponent(agent)}&limit=${limit}`);
     }
 }
+function outboundCallModePayload(config) {
+    const enabled = outboundModeBoolean(config.enabled, false, "enabled");
+    if (!enabled)
+        return { version: 1, enabled: false };
+    const observabilityInput = config.observability ?? {};
+    if (typeof observabilityInput !== "object" || Array.isArray(observabilityInput)) {
+        throw new SupafoneLabsError("outboundCallMode.observability must be an object");
+    }
+    if (observabilityInput.metadata !== undefined
+        && (typeof observabilityInput.metadata !== "object"
+            || observabilityInput.metadata === null
+            || Array.isArray(observabilityInput.metadata))) {
+        throw new SupafoneLabsError("outboundCallMode.observability.metadata must be an object");
+    }
+    const observability = compact({
+        enabled: outboundModeBoolean(observabilityInput.enabled, true, "observability.enabled"),
+        include_trigger: outboundModeBoolean(observabilityInput.includeTrigger, true, "observability.includeTrigger"),
+        include_transitions: outboundModeBoolean(observabilityInput.includeTransitions, true, "observability.includeTransitions"),
+        include_termination_reason: outboundModeBoolean(observabilityInput.includeTerminationReason, true, "observability.includeTerminationReason"),
+        metadata: observabilityInput.metadata,
+    });
+    const payload = {
+        version: 1,
+        enabled: true,
+        initial_mode: "mission",
+        ivr_mode: "dynamic",
+        transport_scope: "provider_agnostic",
+        capability_policy: "fail_closed",
+        auto_detect: outboundModeBoolean(config.autoDetect, true, "autoDetect"),
+        dtmf_tool_enabled: outboundModeBoolean(config.dtmfToolEnabled, true, "dtmfToolEnabled"),
+        max_duration_seconds: outboundModeInteger(config.maxDurationSeconds, "maxDurationSeconds"),
+        max_keypresses: outboundModeInteger(config.maxKeypresses, "maxKeypresses"),
+        repeated_menu_limit: outboundModeInteger(config.repeatedMenuLimit, "repeatedMenuLimit"),
+        no_progress_timeout_seconds: outboundModeInteger(config.noProgressTimeoutSeconds, "noProgressTimeoutSeconds"),
+        human_detection_enabled: outboundModeBoolean(config.humanDetectionEnabled, true, "humanDetectionEnabled"),
+        resume_on_human: outboundModeBoolean(config.resumeOnHuman, true, "resumeOnHuman"),
+        observability,
+    };
+    payload.required_capabilities = outboundCallModeRequiredCapabilities(payload);
+    return payload;
+}
+function outboundModeBoolean(value, fallback, key) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "boolean") {
+        throw new SupafoneLabsError(`outboundCallMode.${key} must be a boolean`);
+    }
+    return value;
+}
+function outboundModeInteger(value, key) {
+    const bounds = exports.OUTBOUND_CALL_MODE_BOUNDS[key];
+    const normalized = value ?? bounds.default;
+    if (!Number.isInteger(normalized)) {
+        throw new SupafoneLabsError(`outboundCallMode.${key} must be an integer`);
+    }
+    if (normalized < bounds.min || normalized > bounds.max) {
+        throw new SupafoneLabsError(`outboundCallMode.${key} must be between ${bounds.min} and ${bounds.max}`);
+    }
+    return normalized;
+}
+function outboundCallModeRequiredCapabilities(payload) {
+    const required = ["state_persistence"];
+    if (payload.dtmf_tool_enabled !== false)
+        required.unshift("dtmf");
+    if (payload.human_detection_enabled !== false || payload.resume_on_human !== false) {
+        required.push("human_detection");
+    }
+    const observability = payload.observability;
+    if (observability?.enabled === true)
+        required.push("observability");
+    return required;
+}
+function labsAgentMetadataPayload(input) {
+    const metadata = { ...(input.metadata ?? {}) };
+    const mode = input.outboundCallMode ?? input.outbound_call_mode;
+    if (mode !== undefined)
+        metadata.outbound_call_mode = outboundCallModePayload(mode);
+    return Object.keys(metadata).length ? metadata : undefined;
+}
+function labsAgentUpdatePayload(input) {
+    return labsAgentPayload(input);
+}
+function campaignSettingsPayload(settings, mode) {
+    const payload = { ...(settings ?? {}) };
+    if (mode !== undefined)
+        payload.outbound_call_mode = outboundCallModePayload(mode);
+    return payload;
+}
 function labsAgentPayload(input) {
     const fixedLanguage = input.preferred_language ?? input.preferredLanguage ?? input.language;
     return compact({
@@ -1710,7 +1961,7 @@ function labsAgentPayload(input) {
         ultravox: input.ultravox ? ultravoxPayload(input.ultravox) : undefined,
         voice_watcher: input.voice_watcher ?? input.voiceWatcher,
         voice_watcher_model: input.voice_watcher_model ?? input.voiceWatcherModel,
-        metadata: input.metadata,
+        metadata: labsAgentMetadataPayload(input),
     });
 }
 function hostedListQuery(opts) {