supafone-labs 0.5.4 → 0.6.1

package/dist/cjs/index.js

@@ -5,7 +5,7 @@
  * A dependency-free TypeScript client for creating hosted Supafone agents
  * through the Supafone API, including managed phone numbers, voices, stages,
  * tools, recordings, transcripts, widgets, and Supafone Supervisor. It also
- * includes the Labs cloud sidecar oracle, hosted TTS/STT, live multilingual
+ * includes Supafone Supervisor, hosted TTS/STT, live multilingual
  * transcription, telemetry, agent builder, and objective-driven optimizer.
  *
  * Works in Node 18+ (native fetch/WebSocket) and the browser.
@@ -157,6 +157,19 @@ class SupafoneLabsError extends Error {
     }
 }
 exports.SupafoneLabsError = SupafoneLabsError;
+function errorDetailMessage(detail, fallback) {
+    if (detail && typeof detail === "object" && !Array.isArray(detail)) {
+        const value = detail;
+        for (const key of ["message", "detail", "error", "code"]) {
+            const candidate = value[key];
+            if (typeof candidate === "string" && candidate.trim())
+                return candidate.trim();
+        }
+    }
+    if (typeof detail === "string" && detail.trim())
+        return detail.trim();
+    return fallback;
+}
 const DEFAULT_BASE = "https://api.labs.supafone.ai";
 const DEFAULT_SUPAFONE_API_BASE = "https://api.supafone.ai";
 const COACH_SYSTEM = "You are the coaching core of a supervisor for a live voice agent. Read the " +
@@ -358,8 +371,8 @@ class SupafoneLabs {
             const text = await res.text();
             const parsed = text ? safeJson(text) : {};
             if (!res.ok) {
-                const detail = parsed?.detail ?? text ?? `HTTP ${res.status}`;
-                throw new SupafoneLabsError(`${method} ${path}: ${detail}`, res.status, parsed);
+                const detail = parsed?.detail ?? text;
+                throw new SupafoneLabsError(`${method} ${path}: ${errorDetailMessage(detail, `HTTP ${res.status}`)}`, res.status, parsed);
             }
             return parsed;
         }
@@ -381,8 +394,8 @@ class SupafoneLabs {
             const text = await res.text();
             const parsed = text ? safeJson(text) : {};
             if (!res.ok) {
-                const detail = parsed?.detail ?? text ?? `HTTP ${res.status}`;
-                throw new SupafoneLabsError(`${method} ${path}: ${detail}`, res.status, parsed);
+                const detail = parsed?.detail ?? text;
+                throw new SupafoneLabsError(`${method} ${path}: ${errorDetailMessage(detail, `HTTP ${res.status}`)}`, res.status, parsed);
             }
             return parsed;
         }
@@ -408,8 +421,8 @@ class SupafoneLabs {
             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);
+                const detail = parsed?.detail ?? text;
+                throw new SupafoneLabsError(`POST ${path}: ${errorDetailMessage(detail, `HTTP ${res.status}`)}`, res.status, parsed);
             }
             return parsed;
         }
@@ -430,8 +443,8 @@ class SupafoneLabs {
             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);
+                const detail = parsed?.detail ?? text;
+                throw new SupafoneLabsError(`GET ${path}: ${errorDetailMessage(detail, `HTTP ${res.status}`)}`, res.status, parsed);
             }
             return {
                 content: await res.arrayBuffer(),
@@ -494,8 +507,8 @@ class SupafoneLabs {
             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);
+                const detail = parsed?.detail ?? text;
+                throw new SupafoneLabsError(`POST ${path}: ${errorDetailMessage(detail, `HTTP ${res.status}`)}`, res.status, parsed);
             }
             return parsed;
         };
@@ -528,8 +541,8 @@ class SupafoneLabs {
             const text = await res.text();
             const parsed = text ? safeJson(text) : {};
             if (!res.ok) {
-                const detail = parsed?.detail ?? text ?? `HTTP ${res.status}`;
-                throw new SupafoneLabsError(`${method} ${path}: ${detail}`, res.status, parsed);
+                const detail = parsed?.detail ?? text;
+                throw new SupafoneLabsError(`${method} ${path}: ${errorDetailMessage(detail, `HTTP ${res.status}`)}`, res.status, parsed);
             }
             return parsed;
         }
@@ -604,22 +617,26 @@ class SupafoneLabs {
         }
         return this.requestAccountApi("POST", "/api/v1/agents/generate-intake", payload);
     }
-    /** Raw oracle completion — full control over messages and model. */
-    async oracle(req) {
-        return this.request("POST", "/v1/oracle/complete", {
+    /** Raw Supervisor completion with either Supafone-managed or BYOK inference. */
+    async completeWithSupervisor(req) {
+        return this.request("POST", "/v1/supervisor/complete", {
             messages: req.messages,
-            model: req.model ?? "supafone-labs-oracle",
+            model: req.model ?? "supafone-supervisor",
             max_tokens: req.maxTokens ?? 256,
             ...(req.temperature !== undefined ? { temperature: req.temperature } : {}),
         });
     }
+    /** @deprecated Use completeWithSupervisor(). */
+    async oracle(req) {
+        return this.completeWithSupervisor(req);
+    }
     /**
      * The one-liner: hand it the running transcript, get back a silent directive
      * (empty string when the agent is doing fine).
      */
     async whisper(transcript, opts = {}) {
         const system = opts.guardrails ? `${COACH_SYSTEM}\n\nOperator rules:\n${opts.guardrails}` : COACH_SYSTEM;
-        const out = await this.oracle({
+        const out = await this.completeWithSupervisor({
             model: opts.model,
             maxTokens: opts.maxTokens ?? 120,
             ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
@@ -645,7 +662,7 @@ class SupafoneLabs {
             directiveContractPrompt(contract),
             operatorRules.length ? `Operator rules:\n${operatorRules.join("\n")}` : "",
         ].filter(Boolean).join("\n\n");
-        const out = await this.oracle({
+        const out = await this.completeWithSupervisor({
             model: opts.model,
             maxTokens: opts.maxTokens ?? 320,
             ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
@@ -728,7 +745,7 @@ class SupafoneLabs {
     balance() {
         return this.request("GET", "/v1/billing/balance");
     }
-    /** Today's usage against your plan caps (oracle/tts/stt/…). */
+    /** Today's usage across Supervisor, TTS, STT, and managed runtime meters. */
     usage() {
         return this.request("GET", "/v1/usage");
     }
@@ -795,7 +812,7 @@ class SupafoneLabs {
      *
      * With `postCallAnalysis: true` on the client and a transcript (or
      * messages) present, the call is automatically classified first: the
-     * oracle labels it against the agent's objective (achieved/missed,
+     * Supervisor labels it against the agent's objective (achieved/missed,
      * per-criterion verdicts, failure reasons) and files the enriched report
      * server-side. The generated labels come back on `analysis`. Analysis is
      * best-effort — on any failure the plain zero-billed report still lands.
@@ -828,7 +845,7 @@ class SupafoneLabs {
      * objective and get labels back — achieved/missed, per-criterion verdicts,
      * failure reasons, and the blended objective value. Files an enriched call
      * report server-side (feeding optimizer.improve() and objective stats).
-     * Billed one oracle call.
+     * Billed one Supervisor inference.
      */
     classifyCall(input) {
         return this.request("POST", "/v1/calls/classify", compact({
@@ -840,7 +857,7 @@ class SupafoneLabs {
             nudges: input.nudges,
         }));
     }
-    /** Available oracle model ids (live vendor catalog). */
+    /** Available managed and BYOK Supervisor model ids. */
     async models() {
         const d = await this.request("GET", "/v1/models");
         return d.models.map((m) => (typeof m === "string" ? m : m.id));
@@ -1145,6 +1162,10 @@ class LabsBillingNamespace {
     }
     /** Start hosted Stripe Checkout. MCP callers should render checkout_url as a link. */
     checkout(input = {}) {
+        const sku = input.sku ?? input.packageSku ?? input.package_sku;
+        if (sku) {
+            return this.sm.request("POST", "/v1/billing/checkout", { sku });
+        }
         return this.sm.request("POST", "/v1/billing/checkout", compact({
             kind: input.kind ?? "plan",
             plan_key: input.plan_key ?? input.planKey,
@@ -1155,6 +1176,12 @@ class LabsBillingNamespace {
             cancel_url: input.cancel_url ?? input.cancelUrl,
         }));
     }
+    /** Start Stripe Checkout for one prepaid managed-minute package. */
+    topUp(sku = "sf_voice_minutes_400_v1") {
+        if (!sku.trim())
+            return Promise.reject(new SupafoneLabsError("sku is required"));
+        return this.checkout({ sku });
+    }
     status(checkoutSessionId) {
         if (!checkoutSessionId?.trim())
             throw new SupafoneLabsError("checkoutSessionId is required");
@@ -1269,6 +1296,11 @@ class LabsAgentsNamespace {
         const suffix = q.toString() ? `?${q}` : "";
         return this.sm.requestSupafoneApi("GET", `/api/v1/labs/agents${suffix}`);
     }
+    /** Start a rate-limited authenticated browser preview for this hosted agent. */
+    testCall(agentKey, opts = {}) {
+        const query = opts.agencyId ? `?agency_id=${encodeURIComponent(opts.agencyId)}` : "";
+        return this.sm.requestSupafoneApi("POST", `/api/v1/labs/agents/${encodeURIComponent(agentKey)}/test-call${query}`);
+    }
     /** Fetch one durable agent by key. */
     get(agentKey, opts = {}) {
         const q = new URLSearchParams();
@@ -1644,6 +1676,37 @@ class LabsPhoneNumbersNamespace {
         const suffix = q.toString() ? `?${q}` : "";
         return this.sm.requestSupafoneApi("GET", `/api/v1/labs/phone-numbers${suffix}`);
     }
+    /**
+     * Read the explicitly enrolled shared developer-number pool. This inventory
+     * never infers customer or merely-unassigned numbers into the response.
+     */
+    pool() {
+        return this.sm.requestSupafoneApi("GET", "/api/v1/labs/phone-numbers/pool");
+    }
+    /**
+     * Connect to realtime pool state using a short-lived pool-only token. The
+     * Supafone API key is never placed in the WebSocket URL.
+     */
+    async connectPool(opts = {}) {
+        const snapshot = await this.pool();
+        const stream = snapshot.stream;
+        if (!stream?.url || !stream.token) {
+            throw new SupafoneLabsError("Phone-pool response did not include stream metadata");
+        }
+        const WS = opts.WebSocketImpl ?? globalThis.WebSocket;
+        if (!WS) {
+            throw new SupafoneLabsError("No WebSocket available - pass opts.WebSocketImpl (for example, the ws package)");
+        }
+        const url = new URL(stream.url, `${this.sm.supafoneApiBaseUrl}/`);
+        url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        url.searchParams.set("token", stream.token);
+        const socket = new WS(url.toString(), stream.protocol || "developer_phone_pool_v1");
+        await new Promise((resolve, reject) => {
+            socket.addEventListener("open", () => resolve(), { once: true });
+            socket.addEventListener("error", () => reject(new SupafoneLabsError("Could not connect to the phone-pool stream")), { once: true });
+        });
+        return socket;
+    }
     /** Search Supafone-managed inventory. This uses Supafone's master telephony account. */
     search(opts = {}) {
         return this.sm.requestSupafoneApi("POST", "/api/v1/labs/phone-numbers/search", phoneNumberSearchPayload(opts));
@@ -1702,21 +1765,31 @@ class LabsPhoneNumbersNamespace {
      * it to the supplied agent. This is the zero-Twilio-account happy path.
      */
     async buyAndAssign(input) {
+        const strategy = input.number_strategy ?? input.numberStrategy ?? (input.premium ? "premium" : "default_pool");
         let phoneNumber = input.phoneNumber ?? input.phone_number ?? "";
         if (!phoneNumber) {
-            const found = await this.search({
-                ...(input.search ?? {}),
-                agencyId: input.agencyId ?? input.agency_id ?? input.search?.agencyId,
-                limit: input.search?.limit ?? 1,
-            });
-            phoneNumber = found.numbers[0]?.phone_number ?? "";
+            if (strategy === "default_pool") {
+                const found = await this.pool();
+                const areaCode = String(input.search?.areaCode ?? input.search?.area_code ?? "");
+                phoneNumber = found.numbers.find((number) => number.available && (!areaCode || number.phone_number.startsWith(`+1${areaCode}`)))?.phone_number ?? "";
+            }
+            else {
+                const found = await this.search({
+                    ...(input.search ?? {}),
+                    agencyId: input.agencyId ?? input.agency_id ?? input.search?.agencyId,
+                    limit: input.search?.limit ?? 1,
+                });
+                phoneNumber = found.numbers[0]?.phone_number ?? "";
+            }
             if (!phoneNumber) {
-                throw new SupafoneLabsError("No Supafone-managed phone numbers matched the search");
+                const source = strategy === "default_pool" ? "shared developer" : "Supafone-managed";
+                throw new SupafoneLabsError(`No ${source} phone numbers matched the request`);
             }
         }
         return this.buy({
             ...input,
             phoneNumber,
+            numberStrategy: strategy,
             telephony: input.telephony ?? { mode: "supafone_managed", provider: "supafone" },
         });
     }
@@ -1974,6 +2047,7 @@ function campaignSettingsPayload(settings, mode) {
 }
 function labsAgentPayload(input) {
     const fixedLanguage = input.preferred_language ?? input.preferredLanguage ?? input.language;
+    const supervisor = input.supervisor;
     return compact({
         agency_id: input.agency_id ?? input.agencyId,
         agent_key: input.agent_key ?? input.agentKey,
@@ -1992,6 +2066,7 @@ function labsAgentPayload(input) {
         direction: input.direction,
         preset_key: input.preset_key ?? input.presetKey,
         runtime_mode: input.runtime_mode ?? input.runtimeMode,
+        realtime: input.realtime,
         call_stages: callStagesPayload(input),
         stage_generation: input.stage_generation ?? input.stageGeneration,
         stage_count: input.stage_count ?? input.stageCount,
@@ -2017,7 +2092,12 @@ function labsAgentPayload(input) {
         email: input.email ? emailPayload(input.email) : undefined,
         labs: input.labs ? labsPayload(input.labs) : undefined,
         ultravox: input.ultravox ? ultravoxPayload(input.ultravox) : undefined,
-        voice_watcher: input.supervisor ?? input.voice_watcher ?? input.voiceWatcher,
+        supervisor: supervisor && typeof supervisor === "object" ? supervisorPayload(supervisor) : undefined,
+        voice_watcher: typeof supervisor === "boolean"
+            ? supervisor
+            : supervisor && typeof supervisor === "object"
+                ? supervisor.enabled ?? true
+                : input.voice_watcher ?? input.voiceWatcher,
         voice_watcher_model: input.voice_watcher_model ?? input.voiceWatcherModel,
         metadata: labsAgentMetadataPayload(input),
     });
@@ -2144,8 +2224,13 @@ function callStagesPayload(input) {
         return explicit.map(callStagePayload);
     if (explicit === false || auto === false)
         return false;
-    if (explicit === "oracle" || explicit === "template" || explicit === "off")
+    if (explicit === "managed" || explicit === "template" || explicit === "off")
         return explicit;
+    if (explicit === "oracle")
+        return "managed";
+    // The S2S backend owns its validated intake → booking → confirmation flow.
+    if (input.realtime)
+        return undefined;
     // Omitted means the private Supafone API generates and compiles the plan.
     return undefined;
 }
@@ -2312,6 +2397,10 @@ function providerKeysPayload(input) {
         deepgram_api_key: input.deepgram_api_key ?? input.deepgramApiKey,
         anthropic: input.anthropic,
         anthropic_api_key: input.anthropic_api_key ?? input.anthropicApiKey,
+        google: input.google,
+        google_api_key: input.google_api_key ?? input.googleApiKey,
+        gemini: input.gemini,
+        gemini_api_key: input.gemini_api_key ?? input.geminiApiKey,
         openai: input.openai,
         openai_api_key: input.openai_api_key ?? input.openaiApiKey,
         xai: input.xai,
@@ -2427,9 +2516,19 @@ function artifactsPayload(input) {
     });
 }
 function labsPayload(input) {
+    const nestedSupervisor = input.supervisor && typeof input.supervisor === "object"
+        ? input.supervisor
+        : input.provider
+            ? input
+            : undefined;
     return compact({
         enabled: input.enabled,
-        voice_watcher: input.supervisor ?? input.voice_watcher ?? input.voiceWatcher,
+        supervisor: nestedSupervisor ? supervisorPayload(nestedSupervisor) : undefined,
+        voice_watcher: typeof input.supervisor === "boolean"
+            ? input.supervisor
+            : nestedSupervisor
+                ? nestedSupervisor.enabled ?? true
+                : input.voice_watcher ?? input.voiceWatcher,
         api_key: input.api_key ?? input.apiKey,
         model: input.model,
         mode: input.mode,
@@ -2441,6 +2540,16 @@ function labsPayload(input) {
         label: input.label,
     });
 }
+function supervisorPayload(input) {
+    return compact({
+        enabled: input.enabled,
+        mode: input.mode,
+        provider: input.provider,
+        model: input.model,
+        api_key: input.api_key ?? input.apiKey,
+        api_key_configured: input.api_key_configured ?? input.apiKeyConfigured,
+    });
+}
 function ultravoxPayload(input) {
     return compact({
         model: input.model,