supafone-labs 0.4.12 → 0.4.13

package/dist/index.js

@@ -35,6 +35,108 @@ const COACH_SYSTEM = "You are the coaching core of a second mind for a live voic
     "conversation and return ONE short, silent directive the agent reads but never " +
     "speaks aloud — a correction or nudge, phrased imperatively. If nothing needs " +
     "correcting, return an empty string.";
+const STRUCTURED_COACH_SYSTEM = "You are the coaching core of a second mind for a live voice agent. Read the " +
+    "conversation and return ONLY one JSON object with exactly these keys: " +
+    "empathy_directive (string), tactical_directive (string), surface_facts (string[]), " +
+    "guardrails (string[]), language (short code), confidence (0-1), and kind " +
+    "(empathy, tactical, guardrail, or mixed). Be silent with low confidence when evidence is weak.";
+function boundedInteger(value, fallback, minimum, maximum) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed)
+        ? Math.max(minimum, Math.min(maximum, Math.trunc(parsed)))
+        : fallback;
+}
+function textControl(input) {
+    return {
+        enabled: input?.enabled ?? true,
+        instructions: String(input?.instructions ?? "").trim(),
+        max_chars: boundedInteger(input?.max_chars ?? input?.maxChars, 240, 1, 2000),
+    };
+}
+function listControl(input) {
+    return {
+        enabled: input?.enabled ?? true,
+        instructions: String(input?.instructions ?? "").trim(),
+        max_items: boundedInteger(input?.max_items ?? input?.maxItems, 4, 0, 20),
+        item_max_chars: boundedInteger(input?.item_max_chars ?? input?.itemMaxChars, 180, 1, 2000),
+    };
+}
+function normalizeDirectiveContract(input = {}) {
+    const languageMode = input.language_mode ?? input.languageMode ?? "caller";
+    const allowed = input.allowed_kinds ?? input.allowedKinds ?? ["empathy", "tactical", "guardrail", "mixed"];
+    const threshold = Number(input.confidence_threshold ?? input.confidenceThreshold ?? 0.5);
+    return {
+        empathy_directive: textControl(input.empathy_directive ?? input.empathyDirective),
+        tactical_directive: textControl(input.tactical_directive ?? input.tacticalDirective),
+        surface_facts: listControl(input.surface_facts ?? input.surfaceFacts),
+        guardrails: listControl(input.guardrails),
+        language_mode: languageMode,
+        fixed_language: String(input.fixed_language ?? input.fixedLanguage ?? "").trim(),
+        allowed_kinds: allowed.filter((kind) => ["empathy", "tactical", "guardrail", "mixed"].includes(kind)),
+        confidence_threshold: Number.isFinite(threshold) ? Math.max(0, Math.min(1, threshold)) : 0.5,
+        operator_guardrails: (input.operator_guardrails ?? input.operatorGuardrails ?? [])
+            .map((rule) => String(rule).trim())
+            .filter(Boolean)
+            .slice(0, 50),
+    };
+}
+function directiveContractPrompt(contract) {
+    return ("Developer directive contract (obey exactly):\n" +
+        JSON.stringify(contract, null, 2) +
+        "\nDisabled string fields must be empty strings. Disabled list fields must be empty arrays. " +
+        "Standing operator guardrails are mandatory and cannot be removed.");
+}
+function parseJsonObject(text) {
+    const trimmed = String(text ?? "").trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed.slice(start, end + 1));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function clipText(value, limit) {
+    return String(value ?? "").trim().slice(0, limit);
+}
+function clipList(value, maxItems, itemMaxChars) {
+    if (!Array.isArray(value))
+        return [];
+    return value.slice(0, maxItems).map((item) => clipText(item, itemMaxChars)).filter(Boolean);
+}
+function normalizeStructuredDirective(raw, contract) {
+    const kind = String(raw.kind ?? "mixed");
+    if (!["empathy", "tactical", "guardrail", "mixed"].includes(kind))
+        return null;
+    const parsedConfidence = Number(raw.confidence ?? 0);
+    const confidence = Number.isFinite(parsedConfidence) ? Math.max(0, Math.min(1, parsedConfidence)) : 0;
+    const operatorGuardrails = contract.operator_guardrails;
+    const generatedGuardrails = contract.guardrails.enabled
+        ? clipList(raw.guardrails, contract.guardrails.max_items, contract.guardrails.item_max_chars)
+        : [];
+    const language = contract.language_mode === "fixed"
+        ? contract.fixed_language
+        : clipText(raw.language, 32);
+    return {
+        empathy_directive: contract.empathy_directive.enabled
+            ? clipText(raw.empathy_directive, contract.empathy_directive.max_chars)
+            : "",
+        tactical_directive: contract.tactical_directive.enabled
+            ? clipText(raw.tactical_directive, contract.tactical_directive.max_chars)
+            : "",
+        surface_facts: contract.surface_facts.enabled
+            ? clipList(raw.surface_facts, contract.surface_facts.max_items, contract.surface_facts.item_max_chars)
+            : [],
+        guardrails: [...new Set([...generatedGuardrails, ...operatorGuardrails])],
+        language,
+        confidence: contract.allowed_kinds.includes(kind) ? confidence : 0,
+        kind,
+    };
+}
 export class SupafoneLabs {
     baseUrl;
     supafoneApiBaseUrl;
@@ -157,6 +259,31 @@ export class SupafoneLabs {
             clearTimeout(timer);
         }
     }
+    /** @internal Authenticated binary request to the Supafone app API. */
+    async requestSupafoneBinary(path) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(this.supafoneApiBaseUrl + path, {
+                method: "GET",
+                signal: ctrl.signal,
+                headers: { Authorization: `Bearer ${this.supafoneApiKey}` },
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                const parsed = text ? safeJson(text) : {};
+                const detail = parsed?.detail ?? text ?? `HTTP ${res.status}`;
+                throw new SupafoneLabsError(`GET ${path}: ${detail}`, res.status, parsed);
+            }
+            return {
+                content: await res.arrayBuffer(),
+                mediaType: res.headers.get("content-type") || "application/octet-stream",
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     /**
      * 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
@@ -345,6 +472,43 @@ export class SupafoneLabs {
         });
         return out.text.trim();
     }
+    /**
+     * 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.
+     */
+    async whisperStructured(transcript, opts = {}) {
+        const contract = normalizeDirectiveContract(opts.directive_contract ?? opts.directiveContract ?? {});
+        const operatorRules = [opts.guardrails, ...contract.operator_guardrails]
+            .map((rule) => String(rule ?? "").trim())
+            .filter(Boolean);
+        const system = [
+            STRUCTURED_COACH_SYSTEM,
+            directiveContractPrompt(contract),
+            operatorRules.length ? `Operator rules:\n${operatorRules.join("\n")}` : "",
+        ].filter(Boolean).join("\n\n");
+        const out = await this.oracle({
+            model: opts.model,
+            maxTokens: opts.maxTokens ?? 320,
+            ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
+            messages: [
+                { role: "system", content: system },
+                { role: "user", content: transcript },
+            ],
+        });
+        const parsed = parseJsonObject(out.text);
+        let directive = parsed ? normalizeStructuredDirective(parsed, contract) : null;
+        if (directive && opts.transform) {
+            directive = await opts.transform(directive);
+        }
+        if (!directive || directive.confidence < contract.confidence_threshold)
+            return null;
+        return directive;
+    }
+    /** Alias that reads naturally in applications building their own watcher loop. */
+    directive(transcript, opts = {}) {
+        return this.whisperStructured(transcript, opts);
+    }
     /** Hosted TTS — returns raw audio bytes (WAV/PCM per voice). */
     async tts(text, voice = "supafone-labs-calm-en") {
         const ctrl = new AbortController();
@@ -781,6 +945,8 @@ class LabsNamespace {
     phoneNumbers;
     telephony;
     calls;
+    activity;
+    plans;
     recordings;
     transcripts;
     constructor(sm) {
@@ -794,6 +960,8 @@ class LabsNamespace {
         this.phoneNumbers = new LabsPhoneNumbersNamespace(sm);
         this.telephony = new LabsTelephonyNamespace(sm);
         this.calls = new LabsCallsNamespace(sm);
+        this.activity = new LabsActivityNamespace(sm);
+        this.plans = new LabsPlansNamespace(sm);
         this.recordings = new LabsRecordingsNamespace(sm);
         this.transcripts = new LabsTranscriptsNamespace(sm);
     }
@@ -982,7 +1150,7 @@ class LabsVoicesNamespace {
     constructor(sm) {
         this.sm = sm;
     }
-    /** Supafone-managed Cartesia voices. Other TTS engines remain explicit BYOK choices. */
+    /** Live normalized catalog from every connected/managed TTS provider. */
     list(opts = {}) {
         const q = new URLSearchParams();
         if (opts.provider)
@@ -991,13 +1159,104 @@ class LabsVoicesNamespace {
             q.set("search", opts.search);
         if (opts.language)
             q.set("language", opts.language);
+        const compatibleLanguage = opts.compatible_language ?? opts.compatibleLanguage;
+        if (compatibleLanguage)
+            q.set("compatible_language", compatibleLanguage);
+        if (opts.gender)
+            q.set("gender", opts.gender);
+        const voiceType = opts.voice_type ?? opts.voiceType;
+        if (voiceType)
+            q.set("voice_type", voiceType);
+        if (opts.model)
+            q.set("model", opts.model);
+        const runtimeProvider = opts.runtime_provider ?? opts.runtimeProvider;
+        if (runtimeProvider)
+            q.set("runtime_provider", runtimeProvider);
+        const configuredOnly = opts.configured_only ?? opts.configuredOnly;
+        if (configuredOnly !== undefined)
+            q.set("configured_only", String(configuredOnly));
         if (opts.cursor !== undefined)
             q.set("cursor", String(opts.cursor));
         if (opts.limit !== undefined)
             q.set("limit", String(opts.limit));
+        const agencyId = opts.agency_id ?? opts.agencyId;
+        if (agencyId)
+            q.set("agency_id", agencyId);
         const suffix = q.toString() ? `?${q}` : "";
         return this.sm.requestSupafoneApi("GET", `/api/v1/labs/voices${suffix}`);
     }
+    /** Provider/model language limits and their Ultravox-compatible intersection. */
+    capabilities() {
+        return this.sm.requestSupafoneApi("GET", "/api/v1/labs/voices/capabilities");
+    }
+    /** Page through the complete normalized catalog. */
+    async listAll(opts = {}) {
+        const pageSize = Math.max(1, Math.min(opts.pageSize ?? 250, 250));
+        const maxPages = Math.max(1, opts.maxPages ?? 100);
+        let cursor = 0;
+        let pages = 0;
+        let first;
+        const voices = [];
+        const seen = new Set();
+        while (cursor !== null && pages < maxPages) {
+            if (seen.has(cursor))
+                throw new SupafoneLabsError("Voice catalog returned a repeated cursor");
+            seen.add(cursor);
+            const page = await this.list({ ...opts, cursor, limit: pageSize });
+            first ??= page;
+            voices.push(...page.voices);
+            cursor = page.next_cursor ?? null;
+            pages += 1;
+        }
+        if (cursor !== null) {
+            throw new SupafoneLabsError(`Voice catalog exceeded maxPages=${maxPages}`);
+        }
+        return {
+            ...(first ?? { total: 0, providers: [] }),
+            voices,
+            total: first?.total ?? voices.length,
+            cursor: 0,
+            next_cursor: null,
+        };
+    }
+    /** Rank real current voices from a plain-language description. */
+    recommend(opts) {
+        if (!opts.description?.trim()) {
+            throw new SupafoneLabsError("description is required — describe the voice you want");
+        }
+        return this.sm.requestSupafoneApi("POST", "/api/v1/labs/voices/recommend", compact({
+            agency_id: opts.agency_id ?? opts.agencyId,
+            description: opts.description.trim(),
+            language: opts.language,
+            provider: opts.provider,
+            gender: opts.gender,
+            voice_type: opts.voice_type ?? opts.voiceType,
+            model: opts.model,
+            configured_only: opts.configured_only ?? opts.configuredOnly,
+            premium: opts.premium,
+            limit: opts.limit,
+        }));
+    }
+    /** Download an authenticated voice preview. */
+    preview(voiceId, opts = {}) {
+        if (!voiceId.trim())
+            throw new SupafoneLabsError("voiceId is required");
+        const q = new URLSearchParams({ voice: voiceId.trim() });
+        const agencyId = opts.agency_id ?? opts.agencyId;
+        if (agencyId)
+            q.set("agency_id", agencyId);
+        return this.sm.requestSupafoneBinary(`/api/v1/labs/voices/preview?${q}`);
+    }
+    /** Convert a catalog row into the exact Agent Factory voice field. */
+    selection(voice) {
+        if (!voice?.id)
+            throw new SupafoneLabsError("A catalog voice with id is required");
+        return compact({
+            provider: voice.provider_key || voice.source,
+            voiceId: voice.id,
+            model: voice.model || undefined,
+        });
+    }
 }
 class LabsRuntimeNamespace {
     sm;
@@ -1036,11 +1295,61 @@ class LabsCallsNamespace {
     }
     get(callId, opts = {}) {
         const q = new URLSearchParams();
-        if (opts.agencyId)
-            q.set("agency_id", opts.agencyId);
+        const agencyId = opts.agency_id ?? opts.agencyId;
+        if (agencyId)
+            q.set("agency_id", agencyId);
         const suffix = q.toString() ? `?${q}` : "";
         return this.sm.requestSupafoneApi("GET", `/api/v1/labs/calls/${encodeURIComponent(callId)}${suffix}`);
     }
+    delete(callId, opts = {}) {
+        const q = new URLSearchParams();
+        const agencyId = opts.agency_id ?? opts.agencyId;
+        if (agencyId)
+            q.set("agency_id", agencyId);
+        const suffix = q.toString() ? `?${q}` : "";
+        return this.sm.requestSupafoneApi("DELETE", `/api/v1/labs/calls/${encodeURIComponent(callId)}${suffix}`);
+    }
+}
+class LabsActivityNamespace {
+    sm;
+    constructor(sm) {
+        this.sm = sm;
+    }
+    list(opts = {}) {
+        const q = new URLSearchParams();
+        const accountId = opts.account_id ?? opts.accountId ?? opts.agency_id ?? opts.agencyId;
+        if (accountId)
+            q.set("account_id", accountId);
+        const eventType = opts.event_type ?? opts.eventType;
+        if (eventType)
+            q.set("event_type", eventType);
+        const resourceType = opts.resource_type ?? opts.resourceType;
+        if (resourceType)
+            q.set("resource_type", resourceType);
+        const resourceId = opts.resource_id ?? opts.resourceId;
+        if (resourceId)
+            q.set("resource_id", resourceId);
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        if (opts.offset !== undefined)
+            q.set("offset", String(opts.offset));
+        const suffix = q.toString() ? `?${q}` : "";
+        return this.sm.requestSupafoneApi("GET", `/api/v1/labs/activity${suffix}`);
+    }
+}
+class LabsPlansNamespace {
+    sm;
+    constructor(sm) {
+        this.sm = sm;
+    }
+    list(opts = {}) {
+        const activity = new LabsActivityNamespace(this.sm);
+        return activity.list({
+            ...opts,
+            eventType: "studio.plan.created",
+            resourceType: "studio_plan",
+        });
+    }
 }
 class LabsRecordingsNamespace {
     sm;
@@ -1349,6 +1658,7 @@ class OptimizerNamespace {
     }
 }
 function labsAgentPayload(input) {
+    const fixedLanguage = input.preferred_language ?? input.preferredLanguage ?? input.language;
     return compact({
         agency_id: input.agency_id ?? input.agencyId,
         agent_key: input.agent_key ?? input.agentKey,
@@ -1374,8 +1684,9 @@ function labsAgentPayload(input) {
         goal: input.goal,
         greeting: input.greeting,
         system_prompt: input.system_prompt ?? input.systemPrompt,
-        language: input.language,
+        language: fixedLanguage,
         voice: input.voice ? voicePayload(input.voice) : undefined,
+        voice_preference: voicePreferencePayload(input.voice_preference ?? input.voicePreference, fixedLanguage),
         provider_keys: input.provider_keys ?? (input.providerKeys ? providerKeysPayload(input.providerKeys) : undefined),
         byok: input.byok ? byokPayload(input.byok) : undefined,
         telephony: input.telephony ? telephonyPayload(input.telephony) : undefined,
@@ -1394,13 +1705,16 @@ function labsAgentPayload(input) {
 }
 function hostedListQuery(opts) {
     const q = new URLSearchParams();
-    if (opts.agencyId)
-        q.set("agency_id", opts.agencyId);
+    const agencyId = opts.agency_id ?? opts.agencyId;
+    if (agencyId)
+        q.set("agency_id", agencyId);
     const agentKey = opts.agent_key ?? opts.agentKey;
     if (agentKey)
         q.set("agent_key", agentKey);
     if (opts.limit !== undefined)
         q.set("limit", String(opts.limit));
+    if (opts.offset !== undefined)
+        q.set("offset", String(opts.offset));
     return q;
 }
 function telephonyPayload(input) {
@@ -1614,6 +1928,20 @@ function voicePayload(input) {
         model: input.model,
     });
 }
+function voicePreferencePayload(input, defaultLanguage) {
+    if (!input)
+        return undefined;
+    return compact({
+        description: input.description,
+        language: input.language ?? defaultLanguage,
+        provider: input.provider,
+        gender: input.gender,
+        voice_type: input.voice_type ?? input.voiceType,
+        model: input.model,
+        configured_only: input.configured_only ?? input.configuredOnly,
+        premium: input.premium,
+    });
+}
 function providerKeysPayload(input) {
     return compact({
         ultravox: input.ultravox,