supafone-labs 0.4.10 → 0.4.12

package/README.md

@@ -468,6 +468,7 @@ and `const { Supafone } = require("supafone-labs")` both work, with full types.
 | `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.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` |
 | `labs.presets.list()` · `labs.tools.list()` · `labs.voices.list()` | Supafone hosted-agent discovery |
 | `whisper(transcript, opts?)` | convenience over the oracle |
@@ -483,6 +484,12 @@ and `const { Supafone } = require("supafone-labs")` both work, with full types.
 
 Get a key (5 free minutes, no card): <https://labs.supafone.ai/get-key.html>
 
+For `dedicated` or `premium`, `labs.phoneNumbers.buy()` first returns a public
+`checkout_url`. Open it, poll `labs.billing.status()`, then call `buy()` again
+with `billingCheckoutSessionId`. The server verifies and consumes the paid
+entitlement before carrier provisioning; Stripe secrets and card data never
+enter the SDK.
+
 The runtime, all provider adapters, and the offline (bring-your-own-keys) mode
 are open source and MIT-licensed — the Python package `pip install supafone-labs`
 is the full harness. This client is the thin cloud SDK.

package/dist/cjs/index.d.ts

@@ -131,13 +131,29 @@ export interface LabsCallStage {
     key?: string;
     id?: string;
     name: string;
+    /** Plain-English job description used by the hosted call-plan generator. */
+    description?: string;
     goal?: string;
     instructions?: string;
     exitCriteria?: string[];
     exit_criteria?: string[];
     tools?: string[];
+    temperature?: number;
+    nextStages?: string[];
+    next_stages?: string[];
     metadata?: Record<string, unknown>;
 }
+export type LabsStageGeneration = "oracle" | "template" | "off";
+export interface LabsCallPlan {
+    version: "supafone_call_plan_v1" | string;
+    summary: string;
+    base_system_prompt: string;
+    call_stages: LabsCallStage[];
+    generated_by: "supafone_hosted_haiku" | "deterministic_template" | "deterministic_fallback" | "developer" | string;
+    model: string;
+    fallback: boolean;
+    warnings?: string[];
+}
 export interface LabsVoiceSelection {
     provider?: string;
     voiceId?: string;
@@ -454,6 +470,8 @@ export interface CreateLabsAgentRequest {
     agentStyle?: LabsAgentStyle;
     agent_style?: LabsAgentStyle;
     name: string;
+    /** Plain-language job description used by the hosted call-plan generator. */
+    description?: string;
     assistantName?: string;
     assistant_name?: string;
     businessName?: string;
@@ -473,12 +491,18 @@ export interface CreateLabsAgentRequest {
     preset_key?: string;
     runtimeMode?: LabsRuntimeMode;
     runtime_mode?: LabsRuntimeMode;
-    /** Default true. When true, the SDK creates sensible call stages from prompt metadata. */
-    callStages?: boolean | LabsCallStage[];
-    call_stages?: boolean | LabsCallStage[];
+    /** Defaults to Supafone's hosted planner; model credentials remain server-side. */
+    callStages?: boolean | LabsStageGeneration | LabsCallStage[];
+    call_stages?: boolean | LabsStageGeneration | LabsCallStage[];
     stages?: LabsCallStage[];
     autoCallStages?: boolean;
     auto_call_stages?: boolean;
+    stageGeneration?: LabsStageGeneration;
+    stage_generation?: LabsStageGeneration;
+    stageCount?: number;
+    stage_count?: number;
+    stageDetail?: "compact" | "standard" | "detailed";
+    stage_detail?: "compact" | "standard" | "detailed";
     goal?: string;
     greeting?: string;
     systemPrompt?: string;
@@ -544,6 +568,10 @@ export interface LabsToolListResponse {
 }
 export interface LabsVoiceListOptions {
     provider?: string;
+    search?: string;
+    language?: string;
+    cursor?: number;
+    limit?: number;
 }
 export interface LabsVoiceListResponse {
     voices: Array<Record<string, unknown>>;
@@ -552,6 +580,14 @@ export interface LabsVoiceListResponse {
     provider_accounts?: Record<string, unknown>;
     errors?: Record<string, string>;
 }
+export interface LabsRuntimeResponse {
+    account_id: string;
+    provider: "ultravox" | string;
+    managed: boolean;
+    byok_connected: boolean;
+    base_url?: string;
+    updated_at?: string;
+}
 export interface LabsCallListOptions {
     agencyId?: string;
     agentKey?: string;
@@ -669,6 +705,8 @@ export interface LabsPhoneNumberProvisionRequest {
     numberPool?: string;
     number_pool?: string;
     premium?: boolean;
+    billingCheckoutSessionId?: string;
+    billing_checkout_session_id?: string;
     style?: LabsAgentStyle;
     agentStyle?: LabsAgentStyle;
     agent_style?: LabsAgentStyle;
@@ -721,7 +759,7 @@ export interface CreateLabsAgentWithNumberRequest extends CreateLabsAgentRequest
     number?: LabsPhoneNumberBuyAndAssignRequest;
 }
 export interface CreateLabsAgentWithNumberResponse extends CreateLabsAgentResponse {
-    number?: LabsPhoneNumberProvisionResponse;
+    number?: LabsPhoneNumberProvisionResponse | LabsBillingCheckoutResponse;
 }
 export interface LabsAgentResponse {
     id?: string;
@@ -745,6 +783,7 @@ export interface CreateLabsAgentResponse {
         snippet?: string;
         [extra: string]: unknown;
     };
+    call_plan?: LabsCallPlan;
     [extra: string]: unknown;
 }
 export interface ListLabsAgentsResponse {
@@ -1029,6 +1068,13 @@ export declare class SupafoneLabs {
     readonly optimizer: OptimizerNamespace;
     readonly campaigns: CampaignsNamespace;
     constructor(opts: SupafoneLabsOptions);
+    /** Build a complete hosted plan with the same Supafone key used to create agents. */
+    generateCallStages(input: CreateLabsAgentRequest & {
+        description?: string;
+    }): Promise<LabsCallPlan>;
+    generate_call_stages(input: CreateLabsAgentRequest & {
+        description?: string;
+    }): Promise<LabsCallPlan>;
     /** True once login() (or a passed sessionToken) is in effect. */
     get isLoggedIn(): boolean;
     /**
@@ -1459,9 +1505,11 @@ declare class CampaignsNamespace {
 declare class LabsNamespace {
     private sm;
     readonly agents: LabsAgentsNamespace;
+    readonly billing: LabsBillingNamespace;
     readonly presets: LabsPresetsNamespace;
     readonly tools: LabsToolsNamespace;
     readonly voices: LabsVoicesNamespace;
+    readonly runtime: LabsRuntimeNamespace;
     readonly phoneNumbers: LabsPhoneNumbersNamespace;
     readonly telephony: LabsTelephonyNamespace;
     readonly calls: LabsCallsNamespace;
@@ -1471,11 +1519,57 @@ declare class LabsNamespace {
     /** Discover the Supafone convenience layer over Ultravox. */
     capabilities(): Promise<LabsCapabilitiesResponse>;
 }
+export type LabsBillingCheckoutKind = "plan" | "credits" | "number_addon";
+export interface LabsBillingCheckoutInput {
+    kind?: LabsBillingCheckoutKind;
+    planKey?: "developer" | "growth" | "scale" | string;
+    plan_key?: string;
+    numberStrategy?: "dedicated" | "premium" | string;
+    number_strategy?: string;
+    phoneNumber?: string;
+    phone_number?: string;
+    quantity?: number;
+    successUrl?: string;
+    success_url?: string;
+    cancelUrl?: string;
+    cancel_url?: string;
+}
+export interface LabsBillingCheckoutResponse {
+    status: "requires_payment" | "pending" | "paid" | string;
+    checkout_session_id: string;
+    checkout_url?: string;
+    kind: LabsBillingCheckoutKind | string;
+    plan_key?: string | null;
+    number_strategy?: string | null;
+    phone_number?: string | null;
+    stripe_subscription_id?: string | null;
+    ready_to_provision?: boolean;
+    next_step?: string;
+}
+declare class LabsBillingNamespace {
+    private sm;
+    constructor(sm: SupafoneLabs);
+    /** Start hosted Stripe Checkout. MCP callers should render checkout_url as a link. */
+    checkout(input?: LabsBillingCheckoutInput): Promise<LabsBillingCheckoutResponse>;
+    status(checkoutSessionId: string): Promise<LabsBillingCheckoutResponse>;
+    portal(): Promise<{
+        url: string;
+    }>;
+    createCheckout(input?: LabsBillingCheckoutInput): Promise<LabsBillingCheckoutResponse>;
+    getCheckout(checkoutSessionId: string): Promise<LabsBillingCheckoutResponse>;
+}
 declare class LabsAgentsNamespace {
     private sm;
     constructor(sm: SupafoneLabs);
     /** Spawn a durable hosted Supafone agent backed by Ultravox and Supafone-managed providers. */
     create(input: CreateLabsAgentRequest): Promise<CreateLabsAgentResponse>;
+    /** Preview the exact validated call-plan contract the Supafone runtime executes. */
+    plan(input: CreateLabsAgentRequest & {
+        description?: string;
+    }): Promise<LabsCallPlan>;
+    generateCallStages(input: CreateLabsAgentRequest & {
+        description?: string;
+    }): Promise<LabsCallPlan>;
     /** Default the agent onto the client's Voice Watcher setting (live supervision
      * + QA + scoring) unless the caller set it explicitly; mirror into
      * labs.voice_watcher when a labs block exists. Never overwrites a caller value. */
@@ -1519,6 +1613,25 @@ declare class LabsVoicesNamespace {
     /** Supafone-managed Cartesia voices. Other TTS engines remain explicit BYOK choices. */
     list(opts?: LabsVoiceListOptions): Promise<LabsVoiceListResponse>;
 }
+declare class LabsRuntimeNamespace {
+    private sm;
+    constructor(sm: SupafoneLabs);
+    get(opts?: {
+        agencyId?: string;
+        agency_id?: string;
+    }): Promise<LabsRuntimeResponse>;
+    configure(input: {
+        agencyId?: string;
+        agency_id?: string;
+        provider?: "ultravox" | string;
+        credentials?: {
+            apiKey?: string;
+            api_key?: string;
+            baseUrl?: string;
+            base_url?: string;
+        };
+    }): Promise<LabsRuntimeResponse>;
+}
 declare class LabsCallsNamespace {
     private sm;
     constructor(sm: SupafoneLabs);
@@ -1554,8 +1667,11 @@ declare class LabsPhoneNumbersNamespace {
     list(opts?: LabsPhoneNumberListOptions): Promise<LabsPhoneNumberListResponse>;
     /** Search Supafone-managed inventory. This uses Supafone's master telephony account. */
     search(opts?: LabsPhoneNumberSearchOptions): Promise<LabsPhoneNumberSearchResponse>;
-    /** Buy a Supafone-managed number. Developers do not need a Twilio account. */
-    buy(input: LabsPhoneNumberProvisionRequest): Promise<LabsPhoneNumberProvisionResponse>;
+    /**
+     * Buy a managed number. Paid strategies return a hosted Checkout link first;
+     * call again with billingCheckoutSessionId after Checkout reports paid.
+     */
+    buy(input: LabsPhoneNumberProvisionRequest): Promise<LabsPhoneNumberProvisionResponse | LabsBillingCheckoutResponse>;
     /** Attach an existing Supafone number to an inbound or outbound agent. */
     assign(numberId: string, input?: LabsPhoneNumberAssignRequest): Promise<LabsPhoneNumberAssignResponse>;
     /** Unassign a number from an agent but keep it reserved on the account. */
@@ -1570,7 +1686,7 @@ declare class LabsPhoneNumbersNamespace {
      * Search if needed, buy the first matching Supafone-managed number, and assign
      * it to the supplied agent. This is the zero-Twilio-account happy path.
      */
-    buyAndAssign(input: LabsPhoneNumberBuyAndAssignRequest): Promise<LabsPhoneNumberProvisionResponse>;
+    buyAndAssign(input: LabsPhoneNumberBuyAndAssignRequest): Promise<LabsPhoneNumberProvisionResponse | LabsBillingCheckoutResponse>;
 }
 declare class LabsTelephonyNamespace {
     private sm;

package/dist/cjs/index.js

@@ -94,6 +94,13 @@ class SupafoneLabs {
         this.optimizer = new OptimizerNamespace(this);
         this.campaigns = new CampaignsNamespace(this);
     }
+    /** Build a complete hosted plan with the same Supafone key used to create agents. */
+    generateCallStages(input) {
+        return this.labs.agents.plan(input);
+    }
+    generate_call_stages(input) {
+        return this.generateCallStages(input);
+    }
     /** True once login() (or a passed sessionToken) is in effect. */
     get isLoggedIn() {
         return !!this.sessionToken;
@@ -773,9 +780,11 @@ class CampaignsNamespace {
 class LabsNamespace {
     sm;
     agents;
+    billing;
     presets;
     tools;
     voices;
+    runtime;
     phoneNumbers;
     telephony;
     calls;
@@ -784,9 +793,11 @@ class LabsNamespace {
     constructor(sm) {
         this.sm = sm;
         this.agents = new LabsAgentsNamespace(sm);
+        this.billing = new LabsBillingNamespace(sm);
         this.presets = new LabsPresetsNamespace(sm);
         this.tools = new LabsToolsNamespace(sm);
         this.voices = new LabsVoicesNamespace(sm);
+        this.runtime = new LabsRuntimeNamespace(sm);
         this.phoneNumbers = new LabsPhoneNumbersNamespace(sm);
         this.telephony = new LabsTelephonyNamespace(sm);
         this.calls = new LabsCallsNamespace(sm);
@@ -798,6 +809,38 @@ class LabsNamespace {
         return this.sm.requestSupafoneApi("GET", "/api/v1/labs/capabilities");
     }
 }
+class LabsBillingNamespace {
+    sm;
+    constructor(sm) {
+        this.sm = sm;
+    }
+    /** Start hosted Stripe Checkout. MCP callers should render checkout_url as a link. */
+    checkout(input = {}) {
+        return this.sm.request("POST", "/v1/billing/checkout", compact({
+            kind: input.kind ?? "plan",
+            plan_key: input.plan_key ?? input.planKey,
+            number_strategy: input.number_strategy ?? input.numberStrategy,
+            phone_number: input.phone_number ?? input.phoneNumber,
+            quantity: input.quantity,
+            success_url: input.success_url ?? input.successUrl,
+            cancel_url: input.cancel_url ?? input.cancelUrl,
+        }));
+    }
+    status(checkoutSessionId) {
+        if (!checkoutSessionId?.trim())
+            throw new SupafoneLabsError("checkoutSessionId is required");
+        return this.sm.request("GET", `/v1/billing/checkout/${encodeURIComponent(checkoutSessionId)}`);
+    }
+    portal() {
+        return this.sm.request("POST", "/v1/billing/portal", {});
+    }
+    createCheckout(input = {}) {
+        return this.checkout(input);
+    }
+    getCheckout(checkoutSessionId) {
+        return this.status(checkoutSessionId);
+    }
+}
 class LabsAgentsNamespace {
     sm;
     constructor(sm) {
@@ -807,6 +850,13 @@ class LabsAgentsNamespace {
     create(input) {
         return this.sm.requestSupafoneApi("POST", "/api/v1/labs/agents", labsAgentPayload(this.withVoiceWatcher(input)));
     }
+    /** Preview the exact validated call-plan contract the Supafone runtime executes. */
+    plan(input) {
+        return this.sm.requestSupafoneApi("POST", "/api/v1/labs/agent-plans", stagePlanPayload(input));
+    }
+    generateCallStages(input) {
+        return this.plan(input);
+    }
     /** Default the agent onto the client's Voice Watcher setting (live supervision
      * + QA + scoring) unless the caller set it explicitly; mirror into
      * labs.voice_watcher when a labs block exists. Never overwrites a caller value. */
@@ -944,10 +994,43 @@ class LabsVoicesNamespace {
         const q = new URLSearchParams();
         if (opts.provider)
             q.set("provider", opts.provider);
+        if (opts.search)
+            q.set("search", opts.search);
+        if (opts.language)
+            q.set("language", opts.language);
+        if (opts.cursor !== undefined)
+            q.set("cursor", String(opts.cursor));
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
         const suffix = q.toString() ? `?${q}` : "";
         return this.sm.requestSupafoneApi("GET", `/api/v1/labs/voices${suffix}`);
     }
 }
+class LabsRuntimeNamespace {
+    sm;
+    constructor(sm) {
+        this.sm = sm;
+    }
+    get(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("GET", `/api/v1/labs/runtime${suffix}`);
+    }
+    configure(input) {
+        const credentials = input.credentials ?? {};
+        return this.sm.requestSupafoneApi("PUT", "/api/v1/labs/runtime", compact({
+            agency_id: input.agency_id ?? input.agencyId,
+            provider: input.provider ?? "ultravox",
+            credentials: compact({
+                api_key: credentials.api_key ?? credentials.apiKey,
+                base_url: credentials.base_url ?? credentials.baseUrl,
+            }),
+        }));
+    }
+}
 class LabsCallsNamespace {
     sm;
     constructor(sm) {
@@ -1036,10 +1119,27 @@ class LabsPhoneNumbersNamespace {
     search(opts = {}) {
         return this.sm.requestSupafoneApi("POST", "/api/v1/labs/phone-numbers/search", phoneNumberSearchPayload(opts));
     }
-    /** Buy a Supafone-managed number. Developers do not need a Twilio account. */
+    /**
+     * Buy a managed number. Paid strategies return a hosted Checkout link first;
+     * call again with billingCheckoutSessionId after Checkout reports paid.
+     */
     buy(input) {
+        const strategy = input.number_strategy ?? input.numberStrategy ?? (input.premium ? "premium" : "default_pool");
+        const checkoutSessionId = input.billing_checkout_session_id ?? input.billingCheckoutSessionId;
+        if ((strategy === "dedicated" || strategy === "premium") && !checkoutSessionId) {
+            const phoneNumber = input.phone_number ?? input.phoneNumber;
+            if (!phoneNumber) {
+                return Promise.reject(new SupafoneLabsError("phoneNumber is required before starting number Checkout"));
+            }
+            return this.sm.labs.billing.checkout({
+                kind: "number_addon",
+                numberStrategy: strategy,
+                phoneNumber,
+            });
+        }
         return this.sm.requestSupafoneApi("POST", "/api/v1/labs/phone-numbers", phoneNumberProvisionPayload({
             ...input,
+            numberStrategy: strategy,
             telephony: input.telephony ?? { mode: "supafone_managed", provider: "supafone" },
         }));
     }
@@ -1262,6 +1362,7 @@ function labsAgentPayload(input) {
         agent_type: input.agent_type ?? input.agentType,
         style: input.agent_style ?? input.agentStyle ?? input.style,
         name: input.name,
+        description: input.description,
         assistant_name: input.assistant_name ?? input.assistantName,
         business_name: input.business_name ?? input.businessName,
         industry: input.industry,
@@ -1274,6 +1375,9 @@ function labsAgentPayload(input) {
         preset_key: input.preset_key ?? input.presetKey,
         runtime_mode: input.runtime_mode ?? input.runtimeMode,
         call_stages: callStagesPayload(input),
+        stage_generation: input.stage_generation ?? input.stageGeneration,
+        stage_count: input.stage_count ?? input.stageCount,
+        stage_detail: input.stage_detail ?? input.stageDetail,
         goal: input.goal,
         greeting: input.greeting,
         system_prompt: input.system_prompt ?? input.systemPrompt,
@@ -1375,6 +1479,7 @@ function phoneNumberProvisionPayload(input) {
         number_strategy: input.number_strategy ?? input.numberStrategy,
         number_pool: input.number_pool ?? input.numberPool,
         premium: input.premium,
+        billing_checkout_session_id: input.billing_checkout_session_id ?? input.billingCheckoutSessionId,
         style: input.agent_style ?? input.agentStyle ?? input.style,
         direction: input.direction,
         telephony: input.telephony ? telephonyPayload(input.telephony) : undefined,
@@ -1412,8 +1517,31 @@ function callStagesPayload(input) {
     if (Array.isArray(explicit))
         return explicit.map(callStagePayload);
     if (explicit === false || auto === false)
-        return undefined;
-    return generateCallStages(input).map(callStagePayload);
+        return false;
+    if (explicit === "oracle" || explicit === "template" || explicit === "off")
+        return explicit;
+    // Omitted means the private Supafone API generates and compiles the plan.
+    return undefined;
+}
+function stagePlanPayload(input) {
+    return compact({
+        agency_id: input.agency_id ?? input.agencyId,
+        description: input.description,
+        name: input.name,
+        assistant_name: input.assistant_name ?? input.assistantName,
+        business_name: input.business_name ?? input.businessName,
+        industry: input.industry,
+        direction: input.direction ?? input.agent_style ?? input.agentStyle ?? input.style,
+        goal: input.goal,
+        system_prompt: input.system_prompt ?? input.systemPrompt,
+        tools: input.tools ? toolsPayload(input.tools) : undefined,
+        call_stages: Array.isArray(input.call_stages ?? input.callStages ?? input.stages)
+            ? (input.call_stages ?? input.callStages ?? input.stages)
+            : undefined,
+        stage_generation: input.stage_generation ?? input.stageGeneration,
+        stage_count: input.stage_count ?? input.stageCount,
+        stage_detail: input.stage_detail ?? input.stageDetail,
+    });
 }
 function callStagePayload(input) {
     return compact({
@@ -1423,10 +1551,14 @@ function callStagePayload(input) {
         instructions: input.instructions,
         exit_criteria: input.exit_criteria ?? input.exitCriteria,
         tools: input.tools,
+        temperature: input.temperature,
+        next_stages: input.next_stages ?? input.nextStages,
         metadata: input.metadata,
     });
 }
 function generateCallStages(input) {
+    // Offline compatibility template. New code should use
+    // client.generateCallStages(...) for the hosted, executable plan.
     const direction = String(input.direction ?? input.agent_style ?? input.agentStyle ?? input.style ?? "inbound").toLowerCase();
     const haystack = [
         input.name,