supafone-labs 0.4.14 → 0.5.2

package/dist/index.js

@@ -19,6 +19,127 @@
  *     number: { search: { areaCode: "415" } },
  *   });
  */
+export const 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 },
+};
+export const 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"],
+};
+export const 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"],
+    },
+};
+export function outboundCallModeProviderProfile(provider) {
+    const normalized = String(provider ?? "").trim().toLowerCase();
+    for (const profile of Object.values(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"],
+    };
+}
+export 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,
+    };
+}
 export class SupafoneLabsError extends Error {
     status;
     body;
@@ -259,6 +380,33 @@ export class SupafoneLabs {
             clearTimeout(timer);
         }
     }
+    /** @internal Multipart upload to the Supafone product API with the Labs key. */
+    async requestSupafoneUpload(path, file, filename) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), Math.max(this.timeoutMs, 120_000));
+        try {
+            const safeFilename = filename.replace(/["\\\r\n]/g, "").slice(0, 120) || "document.txt";
+            const blob = file instanceof Blob ? file : new Blob([file]);
+            const form = new FormData();
+            form.append("file", blob, safeFilename);
+            const res = await fetch(this.supafoneApiBaseUrl + path, {
+                method: "POST",
+                signal: ctrl.signal,
+                headers: { Authorization: `Bearer ${this.supafoneApiKey}` },
+                body: form,
+            });
+            const text = await res.text();
+            const parsed = text ? safeJson(text) : {};
+            if (!res.ok) {
+                const detail = parsed?.detail ?? text ?? `HTTP ${res.status}`;
+                throw new SupafoneLabsError(`POST ${path}: ${detail}`, res.status, parsed);
+            }
+            return parsed;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     /** @internal Authenticated binary request to the Supafone app API. */
     async requestSupafoneBinary(path) {
         const ctrl = new AbortController();
@@ -763,18 +911,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,
@@ -782,10 +938,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);
     }
@@ -1112,6 +1268,66 @@ 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));
+    }
+    /** Scrape a website and rebuild this agent's managed knowledge corpus. */
+    syncKnowledge(agentId, input = {}) {
+        return this.sm.requestSupafoneApi("POST", `/api/v1/agents/${encodeURIComponent(agentId)}/sync-knowledge`, { url: input.url ?? input.website_url ?? input.websiteUrl ?? "" });
+    }
+    /** Remove website knowledge while preserving uploaded documents and notes. */
+    detachWebsiteKnowledge(agentId) {
+        return this.sm.requestSupafoneApi("DELETE", `/api/v1/agents/${encodeURIComponent(agentId)}/knowledge/website`);
+    }
+    /** 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}`);
+    }
+    /** Start the native provider-neutral browser voice session for this agent. */
+    startWebRtcCall(agentId) {
+        return this.sm.startWebRtcCall({ agentId });
+    }
+    /** Rebuild retrieval data from the agent's already saved knowledge sources. */
+    reindexKnowledge(agentId) {
+        return this.sm.requestSupafoneApi("POST", `/api/v1/agents/${encodeURIComponent(agentId)}/knowledge/reindex`);
+    }
+    /** Upload and index a txt, md, csv, or PDF knowledge document. */
+    uploadKnowledgeDocument(agentId, file, filename) {
+        return this.sm.requestSupafoneUpload(`/api/v1/agents/${encodeURIComponent(agentId)}/knowledge/upload`, file, filename);
+    }
+    /** Delete one document and rebuild the agent's managed corpus. */
+    deleteKnowledgeDocument(agentId, documentId) {
+        return this.sm.requestSupafoneApi("DELETE", `/api/v1/agents/${encodeURIComponent(agentId)}/knowledge/docs/${encodeURIComponent(documentId)}`);
+    }
+    /** Ask a grounded question against the same corpus used during calls. */
+    chatKnowledge(agentId, message, history = []) {
+        return this.sm.requestSupafoneApi("POST", `/api/v1/agents/${encodeURIComponent(agentId)}/knowledge-chat`, { message, history });
+    }
     /** Delete an agent. Optionally ask the backend to release assigned numbers. */
     delete(agentKey, opts = {}) {
         const q = new URLSearchParams();
@@ -1657,6 +1873,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 = 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({
@@ -1703,7 +2007,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) {
@@ -1934,6 +2238,9 @@ function voicePayload(input) {
 function languageProfilesPayload(input) {
     if (!Array.isArray(input))
         return undefined;
+    if (input.length > 4) {
+        throw new SupafoneLabsError("languageProfiles supports at most four profiles");
+    }
     const profiles = input.map((profile) => compact({
         language: profile.language,
         language_hint: profile.language_hint ?? profile.languageHint,