supafone-labs 0.3.2 → 0.4.1

package/README.md

@@ -297,6 +297,43 @@ const reports = await supafone.optimizer.reports("builder");
 All errors throw `SupafoneLabsError` (with `.status` and `.body`); catch it to
 inspect gateway responses.
 
+## Campaigns & real calls (account-scoped)
+
+The outbound campaign engine behind app.supafone.ai, packaged. Authenticate
+with your account (not an API key) — pass `accountToken`, or
+`accountEmail` + `accountPassword` and the client logs in lazily (and
+re-logs-in transparently when the token expires):
+
+```ts
+const sf = new Supafone({ accountEmail: "you@company.com", accountPassword: "..." });
+
+const { agents } = await sf.listVoiceAgents();
+const { campaign } = await sf.campaigns.create({ name: "Q3 win-back", goal: "reengage", agentId: agents[0].id });
+await sf.campaigns.applyPreset(campaign.id, "win_back");          // or your custom_… preset
+await sf.campaigns.addRecipients(campaign.id, [
+  { name: "Jane Doe", phone: "+15551234567", outreach_consent: "yes" },
+]);
+await sf.campaigns.launch(campaign.id);                            // real calls + emails begin
+
+const live = await sf.campaigns.live(campaign.id);                 // in-flight calls + listen links
+await sf.placeCall({ agentId: agents[0].id, toNumber: "+15551234567" }); // ring a phone right now
+```
+
+`campaigns.live()` returns a portal link (`app.supafone.ai/app/developer`) and
+a listen link per in-flight call; poll `campaigns.getCall(id)` to follow the
+live transcript while a call is in progress.
+
+## Prefer natural language? Use the MCP server
+
+The repo ships an MCP stdio server (`services/supafone-labs/mcp/supafone_mcp.py`)
+exposing this same surface — plus hosted-agent provisioning — as tools for
+Claude Desktop / Claude Code. Configure it with `SUPAFONE_EMAIL` +
+`SUPAFONE_PASSWORD` (campaigns/calls) and/or `SUPAFONE_API_KEY` (hosted
+agents), then just ask: *"create a win-back campaign, add these leads, launch
+it, and show me the calls as they happen"* — Claude replies with developer-
+portal links to watch the calls live. Full tool reference lives in the repo's
+`gitbook/mcp-server.md`.
+
 ## Module format
 
 Ships **both ESM and CommonJS**. `import { Supafone } from "supafone-labs"`

package/dist/cjs/index.d.ts

@@ -21,7 +21,7 @@
  */
 export interface SupafoneLabsOptions {
     /** Your key from https://labs.supafone.ai/get-key.html */
-    apiKey: string;
+    apiKey?: string;
     /** Override the gateway (default: the hosted cloud). */
     baseUrl?: string;
     /** Supafone app/API key for hosted agent provisioning. Defaults to apiKey. */
@@ -32,6 +32,17 @@ export interface SupafoneLabsOptions {
     timeoutMs?: number;
     /** Optional pre-obtained session token (else use login()). */
     sessionToken?: string;
+    /**
+     * Account (app.supafone.ai) auth — powers campaigns + real calls. Pass a
+     * JWT directly, or accountEmail + accountPassword and the client logs in
+     * lazily (and re-logs-in once when the token expires). With account auth
+     * present, apiKey becomes optional.
+     */
+    accountToken?: string;
+    accountEmail?: string;
+    accountPassword?: string;
+    /** Portal base for listen/monitor links (default https://app.supafone.ai). */
+    appUrl?: string;
 }
 export interface ChatMessage {
     role: "system" | "user" | "assistant";
@@ -807,14 +818,20 @@ export declare class SupafoneLabsError extends Error {
 export declare class SupafoneLabs {
     readonly baseUrl: string;
     readonly supafoneApiBaseUrl: string;
+    readonly appUrl: string;
     private readonly apiKey;
     private readonly supafoneApiKey;
     private readonly timeoutMs;
     private sessionToken?;
+    private accountToken?;
+    private accountSessionToken?;
+    private readonly accountEmail?;
+    private readonly accountPassword?;
     readonly labs: LabsNamespace;
     readonly builder: BuilderNamespace;
     readonly qa: QANamespace;
     readonly optimizer: OptimizerNamespace;
+    readonly campaigns: CampaignsNamespace;
     constructor(opts: SupafoneLabsOptions);
     /** True once login() (or a passed sessionToken) is in effect. */
     get isLoggedIn(): boolean;
@@ -827,6 +844,32 @@ export declare class SupafoneLabs {
     request<T>(method: string, path: string, body?: unknown, useSession?: boolean): Promise<T>;
     /** @internal Authenticated JSON request to the Supafone app API (`/api/v1/labs/*`). */
     requestSupafoneApi<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /**
+     * 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
+     * to fail fast.
+     */
+    accountLogin(email?: string, password?: string): Promise<string>;
+    /**
+     * @internal JSON request to the Supafone product API with the ACCOUNT JWT
+     * (campaigns + real calls). A minted token that expires gets one transparent
+     * re-login; an explicit accountToken is the caller's to refresh.
+     */
+    requestAccountApi<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** @internal Raw product-API request with an explicit bearer ("" = none). */
+    private accountHttp;
+    /**
+     * PLACE A REAL OUTBOUND PHONE CALL: dials toNumber from the account's
+     * calling provider and bridges the voice agent onto the line.
+     */
+    placeCall(opts: {
+        agentId: string;
+        toNumber: string;
+    }): Promise<PlaceCallResult>;
+    /** The account's voice agents — pick an agent id for campaigns/calls. */
+    listVoiceAgents(): Promise<{
+        agents: Record<string, unknown>[];
+    }>;
     /** Raw oracle completion — full control over messages and model. */
     oracle(req: OracleRequest): Promise<OracleResult>;
     /**
@@ -905,6 +948,139 @@ declare class LiveTranscription {
     get socket(): WebSocket;
 }
 /** Programmatic hosted Supafone agents, inside the Supafone API. */
+export interface PlaceCallResult {
+    success: boolean;
+    simulated?: boolean;
+    call_sid?: string | null;
+    provider?: string;
+}
+export interface CampaignRecipientInput {
+    name?: string;
+    phone?: string;
+    email?: string;
+    /** Warm-outreach consent — required before any voice/email touch. */
+    outreach_consent?: string;
+    [field: string]: unknown;
+}
+export interface CampaignSummary {
+    id: string;
+    name: string;
+    goal: string;
+    status: string;
+    agent_id?: string | null;
+    stats?: Record<string, unknown>;
+    settings?: Record<string, unknown>;
+    [field: string]: unknown;
+}
+export interface CampaignLiveCall {
+    id: string;
+    status: string;
+    /** Portal deep link to watch this call (live transcript while in flight). */
+    listen_url: string;
+    [field: string]: unknown;
+}
+export interface CampaignLiveView {
+    campaign_id: string;
+    in_flight: CampaignLiveCall[];
+    /** Developer-portal link showing this campaign's agents/calls live. */
+    portal_url: string;
+    stats?: Record<string, unknown> | null;
+}
+export interface CampaignUpdateInput {
+    name?: string;
+    goal?: string;
+    agentId?: string;
+    emailSubject?: string;
+    emailBody?: string;
+    cadence?: {
+        channel: "voice" | "email";
+        delay_hours: number;
+    }[];
+    settings?: Record<string, unknown>;
+}
+/**
+ * Typical flow:
+ * ```ts
+ * const sf = new Supafone({ accountEmail, accountPassword });
+ * const { agents } = await sf.listVoiceAgents();
+ * const { campaign } = await sf.campaigns.create({ name: "Q3 win-back", goal: "reengage", agentId: agents[0].id });
+ * await sf.campaigns.applyPreset(campaign.id, "win_back");
+ * await sf.campaigns.addRecipients(campaign.id, [{ name: "Jane", phone: "+15551234567", outreach_consent: "yes" }]);
+ * await sf.campaigns.launch(campaign.id);
+ * const live = await sf.campaigns.live(campaign.id); // in-flight calls + portal links
+ * ```
+ */
+declare class CampaignsNamespace {
+    private sm;
+    constructor(sm: SupafoneLabs);
+    list(opts?: {
+        accountId?: string;
+    }): Promise<{
+        campaigns: CampaignSummary[];
+    }>;
+    create(opts?: {
+        name?: string;
+        goal?: string;
+        agentId?: string;
+        accountId?: string;
+    }): Promise<{
+        campaign: CampaignSummary;
+    }>;
+    get(campaignId: string): Promise<{
+        campaign: CampaignSummary;
+    }>;
+    update(campaignId: string, input: CampaignUpdateInput): Promise<{
+        campaign: CampaignSummary;
+    }>;
+    /** Add consented leads: [{name, phone, email, outreach_consent: "yes"}]. */
+    addRecipients(campaignId: string, recipients: CampaignRecipientInput[]): Promise<{
+        added: number;
+        stats: Record<string, unknown>;
+    }>;
+    recipients(campaignId: string): Promise<{
+        recipients: Record<string, unknown>[];
+    }>;
+    /** Starts REAL calls/emails on the cadence immediately. */
+    launch(campaignId: string): Promise<{
+        campaign: CampaignSummary;
+    }>;
+    pause(campaignId: string): Promise<{
+        campaign: CampaignSummary;
+    }>;
+    /** Built-in playbooks + the account's saved custom presets. */
+    presets(): Promise<{
+        built_in: Record<string, unknown>[];
+        custom: Record<string, unknown>[];
+    }>;
+    /** Materialize a preset (goal, questions, scripts, signing doc) in one write. */
+    applyPreset(campaignId: string, presetId: string): Promise<{
+        campaign: CampaignSummary;
+    }>;
+    stats(campaignId: string): Promise<{
+        stats: Record<string, unknown>;
+    }>;
+    /** The live funnel + the campaign's most recent calls (newest first). */
+    activity(campaignId: string): Promise<{
+        stats?: Record<string, unknown>;
+        calls?: Record<string, unknown>[];
+    }>;
+    /**
+     * In-flight calls right now, each with a portal link to watch/listen. Poll
+     * getCall(callId) (or open the link) for the transcript as it grows.
+     */
+    live(campaignId: string): Promise<CampaignLiveView>;
+    /** One call — while in_progress the transcript grows on each poll. */
+    getCall(callId: string): Promise<{
+        call: Record<string, unknown>;
+    }>;
+    /** Mint a recipient's tracked tap-to-sign link (inherits the campaign's signing PDF). */
+    createSignLink(campaignId: string, recipientId: string, opts?: {
+        title?: string;
+        message?: string;
+    }): Promise<{
+        link: Record<string, unknown>;
+    }>;
+}
 declare class LabsNamespace {
     private sm;
     readonly agents: LabsAgentsNamespace;
@@ -1075,15 +1251,6 @@ declare class OptimizerNamespace {
         version: number;
         text: string;
     }>;
-    /** SSR grade distribution: five nominal levels folded into a real score distribution. */
-    distribution(agent?: string, limit?: number): Promise<{
-        agent: string;
-        calls: number;
-        counts: Record<string, number>;
-        mean_score: number;
-        buckets: number[];
-        bucket_edges: number[];
-    }>;
     /** List the post-call reports behind the optimizer. */
     reports(agent?: string, limit?: number): Promise<{
         reports: unknown[];

package/dist/cjs/index.js

@@ -43,27 +43,40 @@ const COACH_SYSTEM = "You are the coaching core of a second mind for a live voic
 class SupafoneLabs {
     baseUrl;
     supafoneApiBaseUrl;
+    appUrl;
     apiKey;
     supafoneApiKey;
     timeoutMs;
     sessionToken;
+    accountToken;
+    accountSessionToken;
+    accountEmail;
+    accountPassword;
     labs;
     builder;
     qa;
     optimizer;
+    campaigns;
     constructor(opts) {
-        if (!opts?.apiKey)
-            throw new SupafoneLabsError("apiKey is required");
-        this.apiKey = opts.apiKey;
+        const hasAccountAuth = !!(opts?.accountToken || (opts?.accountEmail && opts?.accountPassword));
+        if (!opts?.apiKey && !hasAccountAuth) {
+            throw new SupafoneLabsError("apiKey is required — or, for campaigns/calls, pass accountToken or accountEmail + accountPassword");
+        }
+        this.apiKey = opts.apiKey ?? "";
         this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
-        this.supafoneApiKey = opts.supafoneApiKey ?? opts.apiKey;
+        this.supafoneApiKey = opts.supafoneApiKey ?? this.apiKey;
         this.supafoneApiBaseUrl = (opts.supafoneApiBaseUrl ?? DEFAULT_SUPAFONE_API_BASE).replace(/\/$/, "");
+        this.appUrl = (opts.appUrl ?? "https://app.supafone.ai").replace(/\/$/, "");
         this.timeoutMs = opts.timeoutMs ?? 30_000;
         this.sessionToken = opts.sessionToken;
+        this.accountToken = opts.accountToken;
+        this.accountEmail = opts.accountEmail;
+        this.accountPassword = opts.accountPassword;
         this.labs = new LabsNamespace(this);
         this.builder = new BuilderNamespace(this);
         this.qa = new QANamespace(this);
         this.optimizer = new OptimizerNamespace(this);
+        this.campaigns = new CampaignsNamespace(this);
     }
     /** True once login() (or a passed sessionToken) is in effect. */
     get isLoggedIn() {
@@ -126,6 +139,87 @@ class SupafoneLabs {
             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
+     * to fail fast.
+     */
+    async accountLogin(email, password) {
+        const useEmail = email ?? this.accountEmail;
+        const usePassword = password ?? this.accountPassword;
+        if (!useEmail || !usePassword) {
+            throw new SupafoneLabsError("Not authenticated: pass accountToken, or accountEmail + accountPassword");
+        }
+        const body = await this.accountHttp("POST", "/api/v1/auth/login", { email: useEmail, password: usePassword }, "");
+        const token = body.access_token || body.token;
+        if (!token)
+            throw new SupafoneLabsError("Login succeeded but returned no token");
+        this.accountSessionToken = token;
+        return token;
+    }
+    /**
+     * @internal JSON request to the Supafone product API with the ACCOUNT JWT
+     * (campaigns + real calls). A minted token that expires gets one transparent
+     * re-login; an explicit accountToken is the caller's to refresh.
+     */
+    async requestAccountApi(method, path, body) {
+        const token = this.accountToken || this.accountSessionToken || (await this.accountLogin());
+        try {
+            return await this.accountHttp(method, path, body, token);
+        }
+        catch (err) {
+            const expired = err instanceof SupafoneLabsError && err.status === 401;
+            if (expired && !this.accountToken && this.accountEmail && this.accountPassword) {
+                this.accountSessionToken = undefined;
+                return this.accountHttp(method, path, body, await this.accountLogin());
+            }
+            throw err;
+        }
+    }
+    /** @internal Raw product-API request with an explicit bearer ("" = none). */
+    async accountHttp(method, path, body, token) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        try {
+            const headers = { "Content-Type": "application/json" };
+            if (token)
+                headers.Authorization = `Bearer ${token}`;
+            const res = await fetch(this.supafoneApiBaseUrl + path, {
+                method,
+                signal: ctrl.signal,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+            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);
+            }
+            return parsed;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * PLACE A REAL OUTBOUND PHONE CALL: dials toNumber from the account's
+     * calling provider and bridges the voice agent onto the line.
+     */
+    async placeCall(opts) {
+        if (!opts?.agentId)
+            throw new SupafoneLabsError("agentId is required (see listVoiceAgents())");
+        if (!opts?.toNumber)
+            throw new SupafoneLabsError("toNumber is required (E.164, e.g. +15551234567)");
+        return this.requestAccountApi("POST", "/api/v1/phone/test-call", {
+            agent_id: opts.agentId,
+            to_number: opts.toNumber,
+        });
+    }
+    /** The account's voice agents — pick an agent id for campaigns/calls. */
+    async listVoiceAgents() {
+        return this.requestAccountApi("GET", "/api/v1/agents");
+    }
     /** Raw oracle completion — full control over messages and model. */
     async oracle(req) {
         return this.request("POST", "/v1/oracle/complete", {
@@ -341,7 +435,131 @@ class LiveTranscription {
         return this.ws;
     }
 }
-/** Programmatic hosted Supafone agents, inside the Supafone API. */
+/**
+ * Typical flow:
+ * ```ts
+ * const sf = new Supafone({ accountEmail, accountPassword });
+ * const { agents } = await sf.listVoiceAgents();
+ * const { campaign } = await sf.campaigns.create({ name: "Q3 win-back", goal: "reengage", agentId: agents[0].id });
+ * await sf.campaigns.applyPreset(campaign.id, "win_back");
+ * await sf.campaigns.addRecipients(campaign.id, [{ name: "Jane", phone: "+15551234567", outreach_consent: "yes" }]);
+ * await sf.campaigns.launch(campaign.id);
+ * const live = await sf.campaigns.live(campaign.id); // in-flight calls + portal links
+ * ```
+ */
+class CampaignsNamespace {
+    sm;
+    constructor(sm) {
+        this.sm = sm;
+    }
+    list(opts = {}) {
+        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({
+            name: opts.name ?? "New campaign",
+            goal: opts.goal ?? "book",
+            agent_id: opts.agentId,
+            account_id: opts.accountId,
+        }));
+    }
+    get(campaignId) {
+        return this.sm.requestAccountApi("GET", `/api/v1/campaigns/${encodeURIComponent(campaignId)}`);
+    }
+    update(campaignId, input) {
+        const payload = compact({
+            name: input.name,
+            goal: input.goal,
+            agent_id: input.agentId,
+            email_subject: input.emailSubject,
+            email_body: input.emailBody,
+            cadence: input.cadence,
+            settings: input.settings,
+        });
+        if (!Object.keys(payload).length) {
+            throw new SupafoneLabsError("Nothing to update — pass name, goal, agentId, emailSubject, emailBody, cadence, or settings");
+        }
+        return this.sm.requestAccountApi("PUT", `/api/v1/campaigns/${encodeURIComponent(campaignId)}`, payload);
+    }
+    /** Add consented leads: [{name, phone, email, outreach_consent: "yes"}]. */
+    addRecipients(campaignId, recipients) {
+        if (!Array.isArray(recipients) || !recipients.length) {
+            throw new SupafoneLabsError("recipients must be a non-empty array of lead rows");
+        }
+        return this.sm.requestAccountApi("POST", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/recipients`, { recipients });
+    }
+    recipients(campaignId) {
+        return this.sm.requestAccountApi("GET", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/recipients`);
+    }
+    /** Starts REAL calls/emails on the cadence immediately. */
+    launch(campaignId) {
+        return this.sm.requestAccountApi("POST", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/launch`, {});
+    }
+    pause(campaignId) {
+        return this.sm.requestAccountApi("POST", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/pause`, {});
+    }
+    /** Built-in playbooks + the account's saved custom presets. */
+    async presets() {
+        const builtIn = await this.sm.requestAccountApi("GET", "/api/v1/campaigns/outbound-presets");
+        let custom = [];
+        try {
+            const mine = await this.sm.requestAccountApi("GET", "/api/v1/campaigns/custom-presets");
+            custom = mine.presets ?? [];
+        }
+        catch {
+            /* custom presets need account scope — built-ins still return */
+        }
+        return { built_in: builtIn.presets ?? [], custom };
+    }
+    /** Materialize a preset (goal, questions, scripts, signing doc) in one write. */
+    applyPreset(campaignId, presetId) {
+        return this.sm.requestAccountApi("POST", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/apply-preset`, {
+            preset_id: presetId,
+        });
+    }
+    stats(campaignId) {
+        return this.sm.requestAccountApi("GET", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/stats`);
+    }
+    /** The live funnel + the campaign's most recent calls (newest first). */
+    activity(campaignId) {
+        return this.sm.requestAccountApi("GET", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/activity`);
+    }
+    /**
+     * In-flight calls right now, each with a portal link to watch/listen. Poll
+     * getCall(callId) (or open the link) for the transcript as it grows.
+     */
+    async live(campaignId) {
+        const activity = await this.activity(campaignId);
+        const inFlight = [];
+        for (const call of activity.calls ?? []) {
+            const status = String(call.status ?? "");
+            if (status === "initiated" || status === "dialing" || status === "in_progress") {
+                const id = String(call.id ?? "");
+                inFlight.push({
+                    ...call,
+                    id,
+                    status,
+                    listen_url: `${this.sm.appUrl}/app/calls?call=${encodeURIComponent(id)}`,
+                });
+            }
+        }
+        return {
+            campaign_id: campaignId,
+            in_flight: inFlight,
+            portal_url: `${this.sm.appUrl}/app/developer?campaign=${encodeURIComponent(campaignId)}`,
+            stats: activity.stats ?? null,
+        };
+    }
+    /** One call — while in_progress the transcript grows on each poll. */
+    getCall(callId) {
+        return this.sm.requestAccountApi("GET", `/api/v1/calls/${encodeURIComponent(callId)}`);
+    }
+    /** Mint a recipient's tracked tap-to-sign link (inherits the campaign's signing PDF). */
+    createSignLink(campaignId, recipientId, opts = {}) {
+        return this.sm.requestAccountApi("POST", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/recipients/${encodeURIComponent(recipientId)}/sign-link`, compact({ title: opts.title, message: opts.message }));
+    }
+}
 class LabsNamespace {
     sm;
     agents;
@@ -726,10 +944,6 @@ class OptimizerNamespace {
     standing(agent = "builder") {
         return this.sm.request("GET", `/v1/optimizer/standing?agent=${encodeURIComponent(agent)}`);
     }
-    /** SSR grade distribution: five nominal levels folded into a real score distribution. */
-    distribution(agent = "builder", limit = 500) {
-        return this.sm.request("GET", `/v1/objective/distribution?agent=${encodeURIComponent(agent)}&limit=${limit}`);
-    }
     /** List the post-call reports behind the optimizer. */
     reports(agent = "builder", limit = 40) {
         return this.sm.request("GET", `/v1/optimizer/reports?agent=${encodeURIComponent(agent)}&limit=${limit}`);