supafone-labs 0.3.2 → 0.4.0

package/src/index.ts

@@ -22,7 +22,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. */
@@ -33,6 +33,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 {
@@ -881,28 +892,44 @@ const COACH_SYSTEM =
 export class SupafoneLabs {
   readonly baseUrl: string;
   readonly supafoneApiBaseUrl: string;
+  readonly appUrl: string;
   private readonly apiKey: string;
   private readonly supafoneApiKey: string;
   private readonly timeoutMs: number;
   private sessionToken?: string;
+  private accountToken?: string;
+  private accountSessionToken?: string;
+  private readonly accountEmail?: string;
+  private readonly accountPassword?: string;
 
   readonly labs: LabsNamespace;
   readonly builder: BuilderNamespace;
   readonly qa: QANamespace;
   readonly optimizer: OptimizerNamespace;
+  readonly campaigns: CampaignsNamespace;
 
   constructor(opts: SupafoneLabsOptions) {
-    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. */
@@ -967,6 +994,93 @@ export class SupafoneLabs {
     }
   }
 
+  /**
+   * 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?: string, password?: string): Promise<string> {
+    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<{ token?: string; access_token?: string }>(
+      "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<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const token = this.accountToken || this.accountSessionToken || (await this.accountLogin());
+    try {
+      return await this.accountHttp<T>(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<T>(method, path, body, 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();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const headers: Record<string, string> = { "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 as { detail?: string })?.detail ?? text ?? `HTTP ${res.status}`;
+        throw new SupafoneLabsError(`${method} ${path}: ${detail}`, res.status, parsed);
+      }
+      return parsed as T;
+    } 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: { agentId: string; toNumber: string }): Promise<PlaceCallResult> {
+    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<PlaceCallResult>("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(): Promise<{ agents: Record<string, unknown>[] }> {
+    return this.requestAccountApi("GET", "/api/v1/agents");
+  }
+
   /** Raw oracle completion — full control over messages and model. */
   async oracle(req: OracleRequest): Promise<OracleResult> {
     return this.request<OracleResult>("POST", "/v1/oracle/complete", {
@@ -1227,6 +1341,216 @@ class LiveTranscription {
 }
 
 /** Programmatic hosted Supafone agents, inside the Supafone API. */
+// ---------------------------------------------------------------------------
+// Campaigns — the outbound AI campaign engine the app.supafone.ai builder
+// drives, packaged. Account-JWT authenticated (accountToken / accountEmail +
+// accountPassword on the client options).
+// ---------------------------------------------------------------------------
+
+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
+ * ```
+ */
+class CampaignsNamespace {
+  constructor(private sm: SupafoneLabs) {}
+
+  list(opts: { accountId?: string } = {}): Promise<{ campaigns: CampaignSummary[] }> {
+    const query = opts.accountId ? `?${new URLSearchParams({ account_id: opts.accountId })}` : "";
+    return this.sm.requestAccountApi("GET", `/api/v1/campaigns${query}`);
+  }
+
+  create(opts: { name?: string; goal?: string; agentId?: string; accountId?: string } = {}): Promise<{ campaign: CampaignSummary }> {
+    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: string): Promise<{ campaign: CampaignSummary }> {
+    return this.sm.requestAccountApi("GET", `/api/v1/campaigns/${encodeURIComponent(campaignId)}`);
+  }
+
+  update(campaignId: string, input: CampaignUpdateInput): Promise<{ campaign: CampaignSummary }> {
+    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 as Record<string, unknown>).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: string, recipients: CampaignRecipientInput[]): Promise<{ added: number; stats: Record<string, unknown> }> {
+    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: string): Promise<{ recipients: Record<string, unknown>[] }> {
+    return this.sm.requestAccountApi("GET", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/recipients`);
+  }
+
+  /** Starts REAL calls/emails on the cadence immediately. */
+  launch(campaignId: string): Promise<{ campaign: CampaignSummary }> {
+    return this.sm.requestAccountApi("POST", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/launch`, {});
+  }
+
+  pause(campaignId: string): Promise<{ campaign: CampaignSummary }> {
+    return this.sm.requestAccountApi("POST", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/pause`, {});
+  }
+
+  /** Built-in playbooks + the account's saved custom presets. */
+  async presets(): Promise<{ built_in: Record<string, unknown>[]; custom: Record<string, unknown>[] }> {
+    const builtIn = await this.sm.requestAccountApi<{ presets: Record<string, unknown>[] }>(
+      "GET",
+      "/api/v1/campaigns/outbound-presets",
+    );
+    let custom: Record<string, unknown>[] = [];
+    try {
+      const mine = await this.sm.requestAccountApi<{ presets: Record<string, unknown>[] }>(
+        "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: string, presetId: string): Promise<{ campaign: CampaignSummary }> {
+    return this.sm.requestAccountApi("POST", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/apply-preset`, {
+      preset_id: presetId,
+    });
+  }
+
+  stats(campaignId: string): Promise<{ stats: Record<string, unknown> }> {
+    return this.sm.requestAccountApi("GET", `/api/v1/campaigns/${encodeURIComponent(campaignId)}/stats`);
+  }
+
+  /** The live funnel + the campaign's most recent calls (newest first). */
+  activity(campaignId: string): Promise<{ stats?: Record<string, unknown>; calls?: Record<string, unknown>[] }> {
+    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: string): Promise<CampaignLiveView> {
+    const activity = await this.activity(campaignId);
+    const inFlight: CampaignLiveCall[] = [];
+    for (const call of activity.calls ?? []) {
+      const status = String((call as { status?: unknown }).status ?? "");
+      if (status === "initiated" || status === "dialing" || status === "in_progress") {
+        const id = String((call as { id?: unknown }).id ?? "");
+        inFlight.push({
+          ...(call as Record<string, unknown>),
+          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: string): Promise<{ call: Record<string, unknown> }> {
+    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: string,
+    recipientId: string,
+    opts: { title?: string; message?: string } = {},
+  ): Promise<{ link: Record<string, unknown> }> {
+    return this.sm.requestAccountApi(
+      "POST",
+      `/api/v1/campaigns/${encodeURIComponent(campaignId)}/recipients/${encodeURIComponent(recipientId)}/sign-link`,
+      compact({ title: opts.title, message: opts.message }),
+    );
+  }
+}
+
 class LabsNamespace {
   readonly agents: LabsAgentsNamespace;
   readonly presets: LabsPresetsNamespace;
@@ -1656,16 +1980,6 @@ class OptimizerNamespace {
   standing(agent = "builder"): Promise<{ version: number; text: string }> {
     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): Promise<{
-    agent: string; calls: number; counts: Record<string, number>;
-    mean_score: number; buckets: number[]; bucket_edges: number[];
-  }> {
-    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): Promise<{ reports: unknown[] }> {
     return this.sm.request(