supafone-labs 0.4.0 → 0.4.2

package/README.md

@@ -269,6 +269,37 @@ await supafone.nudges();           // structured whisper feed
 await supafone.metrics(7);         // injection rate, latency, by-dimension
 ```
 
+### Automatic post-call analysis (`postCallAnalysis: true`)
+
+Turn on `postCallAnalysis` and every `reportCall()` that carries a transcript
+(or structured `messages`) is automatically classified against the agent's
+objective before the report is filed — generating labels: achieved/missed,
+per-criterion verdicts, failure reasons, and the blended objective value.
+
+```ts
+const supafone = new Supafone({
+  apiKey: process.env.SUPAFONE_LABS_API_KEY!,
+  postCallAnalysis: true,
+});
+
+const { analysis } = await supafone.reportCall({
+  session_id: "call-1",
+  agent: "intake",
+  transcript: "agent: Hi, how can I help?\ncaller: I want to book...\nagent: Booked for 3pm.",
+  ground_truth: { booking_requested: true, booking_verified: true },
+});
+// analysis.achieved            -> true
+// analysis.criteria            -> { intent_satisfied: true, actions_verified: true, … }
+// analysis.failure_reasons     -> []
+// analysis.objective_value     -> 0.93 (LLM score blended with ground truth)
+```
+
+The enriched report is filed server-side (feeding `optimizer.improve()` and
+`/v1/optimizer/objective/stats`); billed one oracle call per analyzed call.
+Reports without a transcript — or any analysis failure — fall back to the
+plain zero-billed report. You can also classify explicitly with
+`supafone.classifyCall({ transcript, agent })`.
+
 ## Agent builder & QA (session-scoped — call `login()` first)
 
 The builder and `qa.run` are account features, so authenticate with a console
@@ -289,14 +320,65 @@ await supafone.builder.saveConfig({ agent_prompt: "…", agent_label: "intake" }
 const qa = await supafone.qa.run({ turns: 2 });
 console.log(`+${Math.round(qa.summary.avg_lift * 100)} avg lift`);
 
+// One-call auto suite: scenarios generated from the agent's OWN objective,
+// each played as a mock call vs the real config, judged twice — pass/fail on
+// the scenario's assertion AND an SSR grade (poorly/ok/good/great/perfectly).
+const suite = await supafone.qa.suite({ count: 4, turns: 2 });
+console.log(suite.summary.ssr_histogram);   // { poorly: 0, ok: 1, good: 2, great: 1, perfectly: 0 }
+console.log(suite.summary.avg_ssr_score);   // 0.57
+
+// Or just generate scenarios from any prompt (key-scoped, no login needed).
+const { scenarios } = await supafone.qa.generate({ agentPrompt: "You are…", count: 5 });
+
 // Improve the standing directive from graded calls (OPRO-style).
 const better = await supafone.optimizer.improve("builder");
 const reports = await supafone.optimizer.reports("builder");
 ```
 
+How this compares to Hamming, Coval, Roark, Cekura, and the rest of the 2026
+voice-QA field — and the roadmap it drives — lives in the docs:
+[Testing Voice Agents (QA)](../gitbook/voice-qa-landscape.md).
+
 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"`
@@ -318,8 +400,9 @@ and `const { Supafone } = require("supafone-labs")` both work, with full types.
 | `stt(audio, opts?)` | `POST /v1/stt` |
 | `liveTranscribe(opts?)` | `WS /v1/stt/live` |
 | `balance()` · `models()` · `voices()` · `usage()` | reads |
+| `reportCall(report)` · `classifyCall(input)` | `/v1/events/call_report` · `/v1/calls/classify` (auto with `postCallAnalysis: true`) |
 | `builder.chat/finish/config` | `/v1/builder/*` |
-| `qa.run/history` | `/v1/qa/*` |
+| `qa.run/generate/suite/history` | `/v1/qa/*` |
 | `optimizer.improve/standing` | `/v1/optimizer/*` |
 
 Get a key (5 free minutes, no card): <https://labs.supafone.ai/get-key.html>

package/dist/cjs/index.d.ts

@@ -43,6 +43,15 @@ export interface SupafoneLabsOptions {
     accountPassword?: string;
     /** Portal base for listen/monitor links (default https://app.supafone.ai). */
     appUrl?: string;
+    /**
+     * Automatic post-call analysis. When true, reportCall() with a transcript
+     * (or structured messages) first classifies the finished call against the
+     * agent's objective — generating labels (achieved/missed, per-criterion
+     * verdicts, failure reasons) — and files the enriched report server-side.
+     * Billed one oracle call per analyzed call; reports without a transcript
+     * fall back to the plain zero-billed report.
+     */
+    postCallAnalysis?: boolean;
 }
 export interface ChatMessage {
     role: "system" | "user" | "assistant";
@@ -766,6 +775,59 @@ export interface CallReportInput {
     nudges?: number;
     turns?: number;
     language?: string;
+    /** Full "role: text" transcript — enables automatic post-call analysis. */
+    transcript?: string;
+    /** Structured turns (alternative to transcript) for post-call analysis. */
+    messages?: ClassifyMessage[];
+    /** Deterministic runtime signals blended into the objective value. */
+    ground_truth?: GroundTruthInput;
+    [extra: string]: unknown;
+}
+/** One turn of a finished call handed to the classifier. */
+export interface ClassifyMessage {
+    role: "caller" | "agent" | "whisper" | string;
+    text: string;
+}
+/** Deterministic runtime ground truth (the same signals postcall scoring reads). */
+export interface GroundTruthInput {
+    booking_requested?: boolean;
+    booking_verified?: boolean;
+    delivery_requested?: boolean;
+    delivery_verified?: boolean;
+    end_call_claims_verified?: boolean;
+    unverified_claims?: string[];
+}
+export interface ClassifyCallInput {
+    sessionId?: string;
+    agent?: string;
+    transcript?: string;
+    messages?: ClassifyMessage[];
+    groundTruth?: GroundTruthInput;
+    nudges?: number;
+}
+/** The labels post-call analysis generates for one finished call. */
+export interface CallClassification {
+    /** Did the call achieve the agent's objective? */
+    achieved: boolean;
+    objective_achieved: boolean;
+    /** LLM objective score in [0,1] (before ground-truth blending). */
+    objective_score: number;
+    /** Blended objective value: (1-w)*LLM + w*ground-truth when supplied. */
+    objective_value: number;
+    ground_truth_score: number | null;
+    /** Per-criterion verdicts keyed by the objective's criterion names. */
+    criteria: Record<string, boolean | string>;
+    failure_reasons: string[];
+    summary: string;
+    /** Standing-directive version in force during the call (for A/B trends). */
+    directive_version: number;
+    agent: string;
+    [extra: string]: unknown;
+}
+export interface CallReportResult {
+    recorded: boolean;
+    /** Present when automatic post-call analysis ran — the generated labels. */
+    analysis?: CallClassification;
     [extra: string]: unknown;
 }
 export interface BuilderTurn {
@@ -781,6 +843,47 @@ export interface BuilderChatResult {
     oracle_ms?: number;
     standing_version?: number;
 }
+/** One auto-generated adversarial scenario (from the agent's own prompt). */
+export interface QAScenario {
+    title: string;
+    persona: string;
+    opener: string;
+    assertion: string;
+}
+/** The 5-level SSR nominal scale. */
+export type SSRLabel = "poorly" | "ok" | "good" | "great" | "perfectly";
+/** An SSR grade: nominal label -> deterministic score + bucket distribution. */
+export interface SSRGrade {
+    label: SSRLabel;
+    score: number;
+    /** Probability mass over 10 score buckets [0-0.1, ..., 0.9-1.0]. */
+    distribution: number[];
+    rationale: string;
+}
+/** Result of qa.suite(): generated scenarios played vs the real agent config. */
+export interface QASuiteResult {
+    agent: string;
+    objective: string;
+    supervised: boolean;
+    turns: number;
+    results: Array<{
+        scenario: string;
+        title: string;
+        persona: string;
+        assertion: string;
+        passed: boolean;
+        evidence: string;
+        ssr: SSRGrade;
+        transcript: BuilderTurn[];
+    }>;
+    summary: {
+        tests: number;
+        passed: number;
+        avg_ssr_score: number;
+        ssr_histogram: Record<SSRLabel, number>;
+        oracle_calls_billed: number;
+    };
+}
 export interface QAResult {
     agent: string;
     turns: number;
@@ -822,6 +925,7 @@ export declare class SupafoneLabs {
     private readonly apiKey;
     private readonly supafoneApiKey;
     private readonly timeoutMs;
+    private readonly postCallAnalysis;
     private sessionToken?;
     private accountToken?;
     private accountSessionToken?;
@@ -856,6 +960,8 @@ export declare class SupafoneLabs {
      * re-login; an explicit accountToken is the caller's to refresh.
      */
     requestAccountApi<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** @internal Multipart file POST with the same auth/re-login as requestAccountApi. */
+    requestAccountUpload<T>(path: string, file: Uint8Array | ArrayBuffer | Blob, filename: string): Promise<T>;
     /** @internal Raw product-API request with an explicit bearer ("" = none). */
     private accountHttp;
     /**
@@ -912,8 +1018,25 @@ export declare class SupafoneLabs {
     reportNudge(event: NudgeEvent): Promise<{
         ok?: boolean;
     }>;
-    /** File a post-call report — the fuel optimizer.improve() learns from. */
-    reportCall(report: CallReportInput): Promise<Record<string, unknown>>;
+    /**
+     * File a post-call report — the fuel optimizer.improve() learns from.
+     *
+     * 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,
+     * 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.
+     */
+    reportCall(report: CallReportInput): Promise<CallReportResult>;
+    /**
+     * Post-call analysis for one finished call: classify it against the agent's
+     * 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.
+     */
+    classifyCall(input: ClassifyCallInput): Promise<CallClassification>;
     /** Available oracle model ids (live vendor catalog). */
     models(): Promise<string[]>;
     /** Available TTS voice ids. */
@@ -1080,6 +1203,29 @@ declare class CampaignsNamespace {
     }): Promise<{
         link: Record<string, unknown>;
     }>;
+    /**
+     * Upload the PDF this campaign sends for e-signature. Pass raw bytes
+     * (Uint8Array/ArrayBuffer/Blob — in Node: fs.readFileSync(path)). The server
+     * auto-detects signature/date/initials lines and returns their placements —
+     * apply them with setSignatureFields.
+     */
+    uploadSigningDocument(campaignId: string, file: Uint8Array | ArrayBuffer | Blob, filename?: string): Promise<{
+        campaign: CampaignSummary;
+        asset: Record<string, unknown>;
+        detected_fields: Record<string, unknown>[];
+    }>;
+    detectSignatureFields(campaignId: string): Promise<{
+        fields: Record<string, unknown>[];
+        detected: boolean;
+    }>;
+    /**
+     * Place the signing fields: [{key, type: "signature"|"date"|"initials"|"text",
+     * label, required, placement: {page, x, y, width, height}}] in PDF points
+     * (origin bottom-left, 612x792 page). Merges onto the stored doc config.
+     */
+    setSignatureFields(campaignId: string, fields: Record<string, unknown>[]): Promise<{
+        campaign: CampaignSummary;
+    }>;
 }
 declare class LabsNamespace {
     private sm;
@@ -1234,6 +1380,29 @@ declare class QANamespace {
         scenarios?: string[];
         turns?: number;
     }): Promise<QAResult>;
+    /**
+     * Auto-generate adversarial test scenarios from the agent's own prompt
+     * (key-scoped). Each scenario carries a persona, an opener, and the one
+     * assertion the agent must (or must not) satisfy.
+     */
+    generate(opts: {
+        agentPrompt: string;
+        count?: number;
+    }): Promise<{
+        scenarios: QAScenario[];
+    }>;
+    /**
+     * Build + run a bespoke adversarial suite in one call: scenarios are
+     * generated from the agent's own objective, each is played as a mock call
+     * against the REAL configured agent, and every call is judged twice —
+     * pass/fail on the scenario's assertion AND an SSR grade (poorly/ok/good/
+     * great/perfectly) against the objective. Session-scoped — login() first.
+     */
+    suite(opts?: {
+        count?: number;
+        turns?: number;
+        supervised?: boolean;
+    }): Promise<QASuiteResult>;
     /** Past QA runs (works with the API key). */
     history(agent?: string, limit?: number): Promise<unknown>;
 }

package/dist/cjs/index.js

@@ -47,6 +47,7 @@ class SupafoneLabs {
     apiKey;
     supafoneApiKey;
     timeoutMs;
+    postCallAnalysis;
     sessionToken;
     accountToken;
     accountSessionToken;
@@ -68,6 +69,7 @@ class SupafoneLabs {
         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.postCallAnalysis = opts.postCallAnalysis ?? false;
         this.sessionToken = opts.sessionToken;
         this.accountToken = opts.accountToken;
         this.accountEmail = opts.accountEmail;
@@ -176,6 +178,38 @@ class SupafoneLabs {
             throw err;
         }
     }
+    /** @internal Multipart file POST with the same auth/re-login as requestAccountApi. */
+    async requestAccountUpload(path, file, filename) {
+        const token = this.accountToken || this.accountSessionToken || (await this.accountLogin());
+        const send = async (bearer) => {
+            const blob = file instanceof Blob ? file : new Blob([file], { type: "application/pdf" });
+            const form = new FormData();
+            form.append("file", blob, filename);
+            const res = await fetch(this.supafoneApiBaseUrl + path, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${bearer}` },
+                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;
+        };
+        try {
+            return await send(token);
+        }
+        catch (err) {
+            const expired = err instanceof SupafoneLabsError && err.status === 401;
+            if (expired && !this.accountToken && this.accountEmail && this.accountPassword) {
+                this.accountSessionToken = undefined;
+                return send(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();
@@ -369,9 +403,55 @@ class SupafoneLabs {
     reportNudge(event) {
         return this.request("POST", "/v1/events/nudge", event);
     }
-    /** File a post-call report — the fuel optimizer.improve() learns from. */
-    reportCall(report) {
-        return this.request("POST", "/v1/events/call_report", report);
+    /**
+     * File a post-call report — the fuel optimizer.improve() learns from.
+     *
+     * 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,
+     * 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.
+     */
+    async reportCall(report) {
+        const { transcript, messages, ground_truth, ...plain } = report;
+        const analyzable = !!transcript || !!(messages && messages.length);
+        if (this.postCallAnalysis && analyzable) {
+            try {
+                const analysis = await this.classifyCall({
+                    sessionId: report.session_id,
+                    agent: report.agent,
+                    transcript,
+                    messages,
+                    groundTruth: ground_truth,
+                    nudges: report.nudges,
+                });
+                // classifyCall files the enriched report server-side — don't double-file.
+                return { recorded: true, analysis };
+            }
+            catch {
+                /* analysis is best-effort — fall through to the plain report */
+            }
+        }
+        const out = await this.request("POST", "/v1/events/call_report", plain);
+        return { recorded: true, ...out };
+    }
+    /**
+     * Post-call analysis for one finished call: classify it against the agent's
+     * 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.
+     */
+    classifyCall(input) {
+        return this.request("POST", "/v1/calls/classify", compact({
+            session_id: input.sessionId,
+            agent: input.agent ?? "builder",
+            transcript: input.transcript,
+            messages: input.messages,
+            ground_truth: input.groundTruth,
+            nudges: input.nudges,
+        }));
     }
     /** Available oracle model ids (live vendor catalog). */
     async models() {
@@ -559,6 +639,37 @@ class CampaignsNamespace {
     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 }));
     }
+    /**
+     * Upload the PDF this campaign sends for e-signature. Pass raw bytes
+     * (Uint8Array/ArrayBuffer/Blob — in Node: fs.readFileSync(path)). The server
+     * auto-detects signature/date/initials lines and returns their placements —
+     * apply them with setSignatureFields.
+     */
+    uploadSigningDocument(campaignId, file, filename = "document.pdf") {
+        return this.sm.requestAccountUpload(`/api/v1/campaigns/${encodeURIComponent(campaignId)}/signing/document`, file, filename);
+    }
+    detectSignatureFields(campaignId) {
+        return this.sm.requestAccountApi("POST", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/signing/detect-fields`, {});
+    }
+    /**
+     * Place the signing fields: [{key, type: "signature"|"date"|"initials"|"text",
+     * label, required, placement: {page, x, y, width, height}}] in PDF points
+     * (origin bottom-left, 612x792 page). Merges onto the stored doc config.
+     */
+    async setSignatureFields(campaignId, fields) {
+        if (!Array.isArray(fields) || !fields.length) {
+            throw new SupafoneLabsError("fields must be a non-empty array of placed fields");
+        }
+        const { campaign } = await this.get(campaignId);
+        const settings = { ...(campaign.settings ?? {}) };
+        const native = { ...(settings.native_signing ?? {}) };
+        if (!native.pdfUrl && !native.storedName) {
+            throw new SupafoneLabsError("Upload the signing PDF first (uploadSigningDocument)");
+        }
+        native.enabled = true;
+        native.fields = fields;
+        return this.update(campaignId, { settings: { ...settings, native_signing: native } });
+    }
 }
 class LabsNamespace {
     sm;
@@ -926,6 +1037,31 @@ class QANamespace {
     run(opts = {}) {
         return this.sm.request("POST", "/v1/qa/run", { scenarios: opts.scenarios ?? [], turns: opts.turns ?? 2 }, true);
     }
+    /**
+     * Auto-generate adversarial test scenarios from the agent's own prompt
+     * (key-scoped). Each scenario carries a persona, an opener, and the one
+     * assertion the agent must (or must not) satisfy.
+     */
+    generate(opts) {
+        return this.sm.request("POST", "/v1/qa/generate", {
+            agent_prompt: opts.agentPrompt,
+            count: opts.count ?? 5,
+        });
+    }
+    /**
+     * Build + run a bespoke adversarial suite in one call: scenarios are
+     * generated from the agent's own objective, each is played as a mock call
+     * against the REAL configured agent, and every call is judged twice —
+     * pass/fail on the scenario's assertion AND an SSR grade (poorly/ok/good/
+     * great/perfectly) against the objective. Session-scoped — login() first.
+     */
+    suite(opts = {}) {
+        return this.sm.request("POST", "/v1/qa/suite", {
+            count: opts.count ?? 4,
+            turns: opts.turns ?? 2,
+            supervised: opts.supervised ?? false,
+        }, true);
+    }
     /** Past QA runs (works with the API key). */
     history(agent = "builder", limit = 40) {
         return this.sm.request("GET", `/v1/qa/runs?agent=${encodeURIComponent(agent)}&limit=${limit}`);