supafone-labs 0.4.1 → 0.4.3

package/src/index.ts

@@ -44,6 +44,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 {
@@ -831,6 +840,64 @@ 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;
 }
 
@@ -849,6 +916,51 @@ export interface BuilderChatResult {
   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;
@@ -896,6 +1008,7 @@ export class SupafoneLabs {
   private readonly apiKey: string;
   private readonly supafoneApiKey: string;
   private readonly timeoutMs: number;
+  private readonly postCallAnalysis: boolean;
   private sessionToken?: string;
   private accountToken?: string;
   private accountSessionToken?: string;
@@ -921,6 +1034,7 @@ export 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;
@@ -1038,6 +1152,38 @@ export class SupafoneLabs {
     }
   }
 
+  /** @internal Multipart file POST with the same auth/re-login as requestAccountApi. */
+  async requestAccountUpload<T>(path: string, file: Uint8Array | ArrayBuffer | Blob, filename: string): Promise<T> {
+    const token = this.accountToken || this.accountSessionToken || (await this.accountLogin());
+    const send = async (bearer: string): Promise<T> => {
+      const blob = file instanceof Blob ? file : new Blob([file as BlobPart], { 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 as { detail?: string })?.detail ?? text ?? `HTTP ${res.status}`;
+        throw new SupafoneLabsError(`POST ${path}: ${detail}`, res.status, parsed);
+      }
+      return parsed as T;
+    };
+    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). */
   private async accountHttp<T>(method: string, path: string, body: unknown, token: string): Promise<T> {
     const ctrl = new AbortController();
@@ -1081,6 +1227,45 @@ export class SupafoneLabs {
     return this.requestAccountApi("GET", "/api/v1/agents");
   }
 
+  /**
+   * Scan a website for its branding: business name, brand colors, logo,
+   * favicon, Open Graph metadata, page images, and key same-domain pages.
+   */
+  async scanBrand(url: string): Promise<BrandScanResult> {
+    if (!url?.trim()) throw new SupafoneLabsError("url is required (the website to scan)");
+    return this.requestAccountApi("POST", "/api/v1/agents/brand-scan", { url: url.trim() });
+  }
+
+  /**
+   * Generate a guided intake form (IntakeConfig) from a plain-language
+   * description. Pass agentId to ground it in that agent's business, and
+   * apply:true to write it onto the agent.
+   */
+  async generateIntakeForm(opts: {
+    description: string;
+    agentId?: string;
+    industry?: string;
+    apply?: boolean;
+  }): Promise<GenerateIntakeResult> {
+    if (!opts?.description?.trim()) {
+      throw new SupafoneLabsError("description is required — what should the form collect?");
+    }
+    if (opts.apply && !opts.agentId) {
+      throw new SupafoneLabsError("apply:true needs an agentId (see listVoiceAgents())");
+    }
+    const payload: Record<string, unknown> = { description: opts.description.trim() };
+    if (opts.industry) payload.industry = opts.industry;
+    if (opts.agentId) {
+      payload.apply = Boolean(opts.apply);
+      return this.requestAccountApi(
+        "POST",
+        `/api/v1/agents/${encodeURIComponent(opts.agentId)}/generate-intake`,
+        payload,
+      );
+    }
+    return this.requestAccountApi("POST", "/api/v1/agents/generate-intake", payload);
+  }
+
   /** Raw oracle completion — full control over messages and model. */
   async oracle(req: OracleRequest): Promise<OracleResult> {
     return this.request<OracleResult>("POST", "/v1/oracle/complete", {
@@ -1248,9 +1433,59 @@ export class SupafoneLabs {
     return this.request("POST", "/v1/events/nudge", event);
   }
 
-  /** File a post-call report — the fuel optimizer.improve() learns from. */
-  reportCall(report: CallReportInput): Promise<Record<string, unknown>> {
-    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: CallReportInput): Promise<CallReportResult> {
+    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<Record<string, unknown>>("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: ClassifyCallInput): Promise<CallClassification> {
+    return this.request<CallClassification>(
+      "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). */
@@ -1400,6 +1635,48 @@ export interface CampaignUpdateInput {
   settings?: Record<string, unknown>;
 }
 
+export interface BrandScanResult {
+  url: string;
+  business_name: string;
+  colors: string[];
+  primary_color: string;
+  theme_color: string;
+  css_brand_colors: string[];
+  logo_url: string;
+  favicon_url: string;
+  og: { title: string; description: string; image: string };
+  images: string[];
+  key_urls: string[];
+  scrape_source: string;
+  fallback_used: boolean;
+  error?: string | null;
+}
+
+export interface GenerateIntakeResult {
+  intake: Record<string, unknown>;
+  /** false means the deterministic industry-workflow fallback was used. */
+  generated: boolean;
+  applied: boolean;
+  agent?: Record<string, unknown>;
+}
+
+export interface CampaignConfigReport {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  summary: Record<string, unknown>;
+}
+
+export interface CampaignConfigApplyResult {
+  campaign: CampaignSummary;
+  created: boolean;
+  added: number;
+  launched: boolean;
+  /** Branding scan / intake generation results for the doc's agent-facing blocks. */
+  extras?: Record<string, unknown> | null;
+  report: CampaignConfigReport;
+}
+
 /**
  * Typical flow:
  * ```ts
@@ -1549,6 +1826,103 @@ class CampaignsNamespace {
       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: string,
+    file: Uint8Array | ArrayBuffer | Blob,
+    filename = "document.pdf",
+  ): Promise<{ campaign: CampaignSummary; asset: Record<string, unknown>; detected_fields: Record<string, unknown>[] }> {
+    return this.sm.requestAccountUpload(
+      `/api/v1/campaigns/${encodeURIComponent(campaignId)}/signing/document`,
+      file,
+      filename,
+    );
+  }
+
+  detectSignatureFields(campaignId: string): Promise<{ fields: Record<string, unknown>[]; detected: boolean }> {
+    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: string,
+    fields: Record<string, unknown>[],
+  ): Promise<{ campaign: CampaignSummary }> {
+    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 as Record<string, unknown>) ?? {}) };
+    const native = { ...((settings.native_signing as Record<string, unknown>) ?? {}) };
+    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 } });
+  }
+
+  // -- campaign-as-code (one YAML/JSON document per campaign) ----------------
+
+  /** Pure dry-run: {valid, errors[], warnings[], summary} — no side effects. */
+  validateConfig(
+    config: string,
+    opts: { accountId?: string; launch?: boolean } = {},
+  ): Promise<CampaignConfigReport> {
+    return this.sm.requestAccountApi("POST", "/api/v1/campaigns/config/validate", {
+      config,
+      ...compact({ account_id: opts.accountId, launch: opts.launch }),
+    });
+  }
+
+  /**
+   * Upsert a campaign from a campaign-as-code YAML/JSON document (by slug).
+   * The doc's branding:/intake_form: blocks restyle the campaign's agent and
+   * generate its intake form on apply. launch:true starts REAL calls/emails.
+   */
+  applyConfig(
+    config: string,
+    opts: { accountId?: string; launch?: boolean } = {},
+  ): Promise<CampaignConfigApplyResult> {
+    return this.sm.requestAccountApi("POST", "/api/v1/campaigns/config/apply", {
+      config,
+      ...compact({ account_id: opts.accountId, launch: opts.launch }),
+    });
+  }
+
+  /** The campaign as its canonical YAML document — round-trips through applyConfig. */
+  exportConfig(campaignId: string): Promise<{ config: string; format: string; slug: string }> {
+    return this.sm.requestAccountApi("GET", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/config`);
+  }
+
+  /**
+   * Draft a campaign-as-code YAML document from a plain-language description
+   * (+ optional CSV of leads). No side effects — review, then applyConfig.
+   */
+  generateConfig(opts: {
+    prompt: string;
+    csv?: string;
+    agentId?: string;
+    accountId?: string;
+  }): Promise<{ config: string; format: string; recipients_parsed: number; generated: boolean }> {
+    if (!opts?.prompt?.trim()) {
+      throw new SupafoneLabsError("prompt is required — describe the campaign to draft");
+    }
+    return this.sm.requestAccountApi("POST", "/api/v1/campaigns/config/generate", {
+      prompt: opts.prompt.trim(),
+      ...compact({ csv: opts.csv, agent_id: opts.agentId, account_id: opts.accountId }),
+    });
+  }
 }
 
 class LabsNamespace {
@@ -1964,6 +2338,36 @@ class QANamespace {
       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: { agentPrompt: string; count?: number }): Promise<{ scenarios: QAScenario[] }> {
+    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: { count?: number; turns?: number; supervised?: boolean } = {}): Promise<QASuiteResult> {
+    return this.sm.request<QASuiteResult>(
+      "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): Promise<unknown> {
     return this.sm.request("GET", `/v1/qa/runs?agent=${encodeURIComponent(agent)}&limit=${limit}`);