supafone-labs 0.3.1 → 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 {
@@ -75,11 +86,51 @@ export interface UsageToday {
   usage: Record<string, { used: number; cap: number }>;
 }
 
+export interface LabsLogEntry {
+  id: number;
+  at: string;
+  endpoint: string;
+  seconds_billed: number;
+  duration_ms: number;
+  detail: string;
+  meta: Record<string, unknown>;
+}
+
+export interface StreamLogsOptions {
+  limit?: number;
+  afterId?: number;
+  pollMs?: number;
+  snapshot?: boolean;
+  signal?: AbortSignal;
+}
+
 export type LabsAgentType = "phone" | "web" | "campaign";
 export type LabsAgentStyle = "inbound" | "outbound";
 export type LabsRuntimeMode = "multi_stage" | "single_stage";
 export type LabsTelephonyMode = "supafone_managed" | "byok";
-export type LabsTelephonyProvider = "supafone" | "twilio" | "telnyx" | "plivo" | "sip" | string;
+export type LabsTelephonyProvider =
+  | "supafone"
+  | "twilio"
+  | "telnyx"
+  | "plivo"
+  | "signalwire"
+  | "sip"
+  | "custom_sip"
+  | "custom"
+  | string;
+export type LabsNumberStrategy = "default_pool" | "dedicated" | "premium" | "byok" | string;
+
+export interface LabsCallStage {
+  key?: string;
+  id?: string;
+  name: string;
+  goal?: string;
+  instructions?: string;
+  exitCriteria?: string[];
+  exit_criteria?: string[];
+  tools?: string[];
+  metadata?: Record<string, unknown>;
+}
 
 export interface LabsVoiceSelection {
   provider?: string;
@@ -89,9 +140,51 @@ export interface LabsVoiceSelection {
 }
 
 export interface LabsProviderKeys {
+  /** Agent runtime/platform providers. */
   ultravox?: string;
   ultravoxApiKey?: string;
   ultravox_api_key?: string;
+  retell?: string;
+  retellApiKey?: string;
+  retell_api_key?: string;
+  vapi?: string;
+  vapiApiKey?: string;
+  vapi_api_key?: string;
+  bland?: string;
+  blandApiKey?: string;
+  bland_api_key?: string;
+  livekit?: string;
+  livekitApiKey?: string;
+  livekit_api_key?: string;
+  livekitApiSecret?: string;
+  livekit_api_secret?: string;
+  pipecat?: string;
+  pipecatApiKey?: string;
+  pipecat_api_key?: string;
+  /** Telephony/carrier providers. */
+  twilio?: string;
+  twilioAccountSid?: string;
+  twilio_account_sid?: string;
+  twilioAuthToken?: string;
+  twilio_auth_token?: string;
+  twilioApiKeySid?: string;
+  twilio_api_key_sid?: string;
+  twilioApiKeySecret?: string;
+  twilio_api_key_secret?: string;
+  telnyx?: string;
+  telnyxApiKey?: string;
+  telnyx_api_key?: string;
+  plivo?: string;
+  plivoAuthId?: string;
+  plivo_auth_id?: string;
+  plivoAuthToken?: string;
+  plivo_auth_token?: string;
+  signalwire?: string;
+  signalwireApiToken?: string;
+  signalwire_api_token?: string;
+  signalwireProjectId?: string;
+  signalwire_project_id?: string;
+  /** TTS providers. */
   elevenlabs?: string;
   elevenlabsApiKey?: string;
   elevenlabs_api_key?: string;
@@ -104,6 +197,65 @@ export interface LabsProviderKeys {
   deepgram?: string;
   deepgramApiKey?: string;
   deepgram_api_key?: string;
+  /** Brain/STT providers used by Labs watcher or customer BYOK stacks. */
+  anthropic?: string;
+  anthropicApiKey?: string;
+  anthropic_api_key?: string;
+  openai?: string;
+  openaiApiKey?: string;
+  openai_api_key?: string;
+  xai?: string;
+  xaiApiKey?: string;
+  xai_api_key?: string;
+  [extra: string]: unknown;
+}
+
+export interface LabsCustomSipConfig {
+  sipTrunkUri?: string;
+  sip_trunk_uri?: string;
+  trunkUri?: string;
+  trunk_uri?: string;
+  sipHost?: string;
+  sip_host?: string;
+  fromNumber?: string;
+  from_number?: string;
+  username?: string;
+  password?: string;
+  transport?: string;
+  headers?: Record<string, string>;
+  codecs?: string[];
+  dtmfMode?: string;
+  dtmf_mode?: string;
+  metadata?: Record<string, unknown>;
+  [extra: string]: unknown;
+}
+
+export interface LabsProviderByokConfig {
+  provider?: string;
+  apiKey?: string;
+  api_key?: string;
+  credentials?: Record<string, unknown>;
+  settings?: Record<string, unknown>;
+  model?: string;
+  voiceId?: string;
+  voice_id?: string;
+  [extra: string]: unknown;
+}
+
+export interface LabsByokConfig {
+  providerKeys?: LabsProviderKeys;
+  provider_keys?: LabsProviderKeys;
+  agentProvider?: LabsProviderByokConfig;
+  agent_provider?: LabsProviderByokConfig;
+  runtime?: LabsProviderByokConfig;
+  telephony?: LabsTelephonyConfig;
+  tts?: LabsProviderByokConfig;
+  stt?: LabsProviderByokConfig;
+  llm?: LabsProviderByokConfig;
+  customSip?: LabsCustomSipConfig;
+  custom_sip?: LabsCustomSipConfig;
+  sip?: LabsCustomSipConfig;
+  [extra: string]: unknown;
 }
 
 export interface LabsTelephonyCredentials {
@@ -119,6 +271,20 @@ export interface LabsTelephonyCredentials {
   auth_id?: string;
   connectionId?: string;
   connection_id?: string;
+  telnyxConnectionId?: string;
+  telnyx_connection_id?: string;
+  signalwireSpaceUrl?: string;
+  signalwire_space_url?: string;
+  projectId?: string;
+  project_id?: string;
+  applicationId?: string;
+  application_id?: string;
+  trunkId?: string;
+  trunk_id?: string;
+  endpointId?: string;
+  endpoint_id?: string;
+  token?: string;
+  secret?: string;
   fromNumber?: string;
   from_number?: string;
   sipTrunkUri?: string;
@@ -129,6 +295,9 @@ export interface LabsTelephonyCredentials {
   password?: string;
   webhookSecret?: string;
   webhook_secret?: string;
+  customSip?: LabsCustomSipConfig;
+  custom_sip?: LabsCustomSipConfig;
+  [extra: string]: unknown;
 }
 
 export interface LabsTelephonyConfig {
@@ -137,9 +306,22 @@ export interface LabsTelephonyConfig {
   /** Default is Supafone-managed; developers do not need Twilio for this path. */
   mode?: LabsTelephonyMode;
   provider?: LabsTelephonyProvider;
+  /** default_pool reuses idle Supafone numbers; dedicated/premium reserve a number-month. */
+  numberStrategy?: LabsNumberStrategy;
+  number_strategy?: LabsNumberStrategy;
+  numberPool?: string;
+  number_pool?: string;
+  numberId?: string;
+  number_id?: string;
+  premium?: boolean;
   label?: string;
   credentials?: LabsTelephonyCredentials;
+  providerSettings?: Record<string, unknown>;
+  provider_settings?: Record<string, unknown>;
+  customSip?: LabsCustomSipConfig;
+  custom_sip?: LabsCustomSipConfig;
   metadata?: Record<string, unknown>;
+  [extra: string]: unknown;
 }
 
 export interface LabsToolsConfig {
@@ -161,11 +343,61 @@ export interface LabsToolsConfig {
   custom_tools?: Array<Record<string, unknown>>;
 }
 
+export interface LabsRecordingConfig {
+  enabled?: boolean;
+  recordAudio?: boolean;
+  record_audio?: boolean;
+  consentRequired?: boolean;
+  consent_required?: boolean;
+  announcement?: string;
+  retentionDays?: number;
+  retention_days?: number;
+  storage?: "supafone_managed" | "byok" | string;
+  redactPii?: boolean;
+  redact_pii?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface LabsTranscriptionConfig {
+  enabled?: boolean;
+  provider?: string;
+  model?: string;
+  language?: string;
+  redactPii?: boolean;
+  redact_pii?: boolean;
+  diarization?: boolean;
+  timestamps?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface LabsArtifactsConfig {
+  recordings?: boolean;
+  transcripts?: boolean;
+  summaries?: boolean;
+  qaReports?: boolean;
+  qa_reports?: boolean;
+  logs?: boolean;
+  webhooks?: boolean;
+  retentionDays?: number;
+  retention_days?: number;
+  metadata?: Record<string, unknown>;
+}
+
 export interface LabsWatcherConfig {
   enabled?: boolean;
   voiceWatcher?: boolean;
   voice_watcher?: boolean;
+  apiKey?: string;
+  api_key?: string;
   model?: string;
+  mode?: "supafone_managed" | "byok" | string;
+  managedInfrastructure?: boolean;
+  managed_infrastructure?: boolean;
+  stt?: Record<string, unknown>;
+  llm?: Record<string, unknown>;
+  tts?: Record<string, unknown>;
+  providerKeys?: Record<string, unknown>;
+  provider_keys?: Record<string, unknown>;
   label?: string;
 }
 
@@ -211,6 +443,10 @@ export interface LabsUltravoxRuntime {
   retention_policy?: string;
   callTemplate?: Record<string, unknown>;
   call_template?: Record<string, unknown>;
+  customSip?: LabsCustomSipConfig;
+  custom_sip?: LabsCustomSipConfig;
+  sip?: LabsCustomSipConfig;
+  [extra: string]: unknown;
 }
 
 export interface CreateLabsAgentRequest {
@@ -234,11 +470,22 @@ export interface CreateLabsAgentRequest {
   website_url?: string;
   phoneNumber?: string;
   phone_number?: string;
+  numberStrategy?: LabsNumberStrategy;
+  number_strategy?: LabsNumberStrategy;
+  numberPool?: string;
+  number_pool?: string;
+  premium?: boolean;
   direction?: string;
   presetKey?: string;
   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[];
+  stages?: LabsCallStage[];
+  autoCallStages?: boolean;
+  auto_call_stages?: boolean;
   goal?: string;
   greeting?: string;
   systemPrompt?: string;
@@ -247,8 +494,15 @@ export interface CreateLabsAgentRequest {
   voice?: LabsVoiceSelection;
   providerKeys?: LabsProviderKeys;
   provider_keys?: LabsProviderKeys;
-  byok?: LabsProviderKeys;
+  byok?: LabsProviderKeys | LabsByokConfig;
   telephony?: LabsTelephonyConfig;
+  customSip?: LabsCustomSipConfig;
+  custom_sip?: LabsCustomSipConfig;
+  sip?: LabsCustomSipConfig;
+  recording?: LabsRecordingConfig;
+  transcription?: LabsTranscriptionConfig;
+  artifacts?: LabsArtifactsConfig;
+  compliance?: Record<string, unknown>;
   tools?: LabsToolsConfig;
   labs?: LabsWatcherConfig;
   ultravox?: LabsUltravoxRuntime;
@@ -267,6 +521,21 @@ export interface ListLabsAgentsOptions {
 
 export interface GetLabsAgentOptions extends ListLabsAgentsOptions {}
 
+export interface DeleteLabsAgentOptions {
+  agencyId?: string;
+  agency_id?: string;
+  releaseNumbers?: boolean;
+  release_numbers?: boolean;
+}
+
+export interface DeleteLabsAgentResponse {
+  success?: boolean;
+  deleted?: boolean;
+  agent_key?: string;
+  released_numbers?: unknown[];
+  [extra: string]: unknown;
+}
+
 export interface LabsCapabilitiesResponse {
   product: string;
   api_namespace: string;
@@ -299,9 +568,57 @@ export interface LabsVoiceListResponse {
   errors?: Record<string, string>;
 }
 
+export interface LabsCallListOptions {
+  agencyId?: string;
+  agentKey?: string;
+  agent_key?: string;
+  limit?: number;
+}
+
+export interface LabsCallArtifact {
+  id?: string;
+  call_id?: string;
+  agent_key?: string;
+  status?: string;
+  started_at?: string;
+  duration_seconds?: number;
+  recording_url?: string;
+  transcript_url?: string;
+  [extra: string]: unknown;
+}
+
+export interface LabsCallListResponse {
+  calls: LabsCallArtifact[];
+  [extra: string]: unknown;
+}
+
+export interface LabsRecordingListOptions extends LabsCallListOptions {
+  callId?: string;
+  call_id?: string;
+}
+
+export interface LabsRecordingListResponse {
+  recordings: Array<Record<string, unknown>>;
+  [extra: string]: unknown;
+}
+
+export interface LabsTranscriptListOptions extends LabsCallListOptions {
+  callId?: string;
+  call_id?: string;
+}
+
+export interface LabsTranscriptListResponse {
+  transcripts: Array<Record<string, unknown>>;
+  [extra: string]: unknown;
+}
+
 export interface LabsPhoneNumberSearchOptions {
   agencyId?: string;
   agency_id?: string;
+  numberPool?: string;
+  number_pool?: string;
+  numberStrategy?: LabsNumberStrategy;
+  number_strategy?: LabsNumberStrategy;
   countryCode?: string;
   country_code?: string;
   areaCode?: string;
@@ -376,6 +693,11 @@ export interface LabsPhoneNumberProvisionRequest {
   agent_name?: string;
   presetKey?: string;
   preset_key?: string;
+  numberStrategy?: LabsNumberStrategy;
+  number_strategy?: LabsNumberStrategy;
+  numberPool?: string;
+  number_pool?: string;
+  premium?: boolean;
   style?: LabsAgentStyle;
   agentStyle?: LabsAgentStyle;
   agent_style?: LabsAgentStyle;
@@ -386,6 +708,15 @@ export interface LabsPhoneNumberProvisionRequest {
 
 export interface LabsPhoneNumberAssignRequest extends Omit<LabsPhoneNumberProvisionRequest, "phoneNumber" | "phone_number" | "departmentId" | "department_id"> {}
 
+export interface LabsPhoneNumberReleaseRequest {
+  agencyId?: string;
+  agency_id?: string;
+  reason?: string;
+  returnToPool?: boolean;
+  return_to_pool?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
 export interface LabsPhoneNumberProvisionResponse {
   success: boolean;
   number: LabsPhoneNumberRecord;
@@ -400,6 +731,14 @@ export interface LabsPhoneNumberAssignResponse {
   assignment?: Record<string, unknown>;
 }
 
+export interface LabsPhoneNumberReleaseResponse {
+  success: boolean;
+  number?: LabsPhoneNumberRecord;
+  released?: boolean;
+  returned_to_pool?: boolean;
+  [extra: string]: unknown;
+}
+
 export interface LabsPhoneNumberBuyAndAssignRequest extends LabsPhoneNumberProvisionRequest {
   search?: LabsPhoneNumberSearchOptions;
 }
@@ -553,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. */
@@ -639,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", {
@@ -685,6 +1127,14 @@ export class SupafoneLabs {
     }
   }
 
+  /** Convenience alias for voice preview UI/buttons. */
+  previewVoice(
+    voice = "supafone-labs-calm-en",
+    text = "Hi, this is your Supafone agent voice preview.",
+  ): Promise<Uint8Array> {
+    return this.tts(text, voice);
+  }
+
   /** Hosted STT for a finished audio clip — returns transcript + language tags. */
   async stt(
     audio: Uint8Array | ArrayBuffer,
@@ -742,10 +1192,47 @@ export class SupafoneLabs {
   }
 
   /** The auditable whisper/billing log. */
-  logs(limit = 100): Promise<{ logs: unknown[] }> {
+  logs(limit = 100): Promise<{ logs: LabsLogEntry[] }> {
     return this.request("GET", `/v1/logs?limit=${limit}`);
   }
 
+  /** Live audit-log stream. Works in Node 18+ and browsers via fetch streaming. */
+  async *streamLogs(opts: StreamLogsOptions = {}): AsyncGenerator<LabsLogEntry> {
+    const q = new URLSearchParams({
+      limit: String(opts.limit ?? 100),
+      poll_ms: String(opts.pollMs ?? 1000),
+      snapshot: String(opts.snapshot ?? true),
+    });
+    if (opts.afterId !== undefined) q.set("after_id", String(opts.afterId));
+    const res = await fetch(`${this.baseUrl}/v1/logs/stream?${q}`, {
+      method: "GET",
+      signal: opts.signal,
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    if (!res.ok) throw new SupafoneLabsError(`streamLogs: ${await res.text()}`, res.status);
+    if (!res.body) throw new SupafoneLabsError("streamLogs: response body is not readable");
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let split = buffer.indexOf("\n\n");
+        while (split >= 0) {
+          const raw = buffer.slice(0, split);
+          buffer = buffer.slice(split + 2);
+          const parsed = parseSseLog(raw);
+          if (parsed) yield parsed;
+          split = buffer.indexOf("\n\n");
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
   /** The structured whisper feed (what the console shows). */
   nudges(limit = 50): Promise<{ nudges: unknown[] }> {
     return this.request("GET", `/v1/nudges?limit=${limit}`);
@@ -780,6 +1267,11 @@ export class SupafoneLabs {
     );
     return d.voices.map((v) => (typeof v === "string" ? v : (v.voice ?? v.id ?? ""))).filter(Boolean);
   }
+
+  /** Full hosted voice catalog with provider live/configured flags. */
+  voiceCatalog(): Promise<{ voices: Array<Record<string, unknown>> }> {
+    return this.request("GET", "/v1/voices");
+  }
 }
 
 export interface LiveTranscribeOptions {
@@ -849,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;
@@ -856,6 +1558,9 @@ class LabsNamespace {
   readonly voices: LabsVoicesNamespace;
   readonly phoneNumbers: LabsPhoneNumbersNamespace;
   readonly telephony: LabsTelephonyNamespace;
+  readonly calls: LabsCallsNamespace;
+  readonly recordings: LabsRecordingsNamespace;
+  readonly transcripts: LabsTranscriptsNamespace;
 
   constructor(private sm: SupafoneLabs) {
     this.agents = new LabsAgentsNamespace(sm);
@@ -864,6 +1569,9 @@ class LabsNamespace {
     this.voices = new LabsVoicesNamespace(sm);
     this.phoneNumbers = new LabsPhoneNumbersNamespace(sm);
     this.telephony = new LabsTelephonyNamespace(sm);
+    this.calls = new LabsCallsNamespace(sm);
+    this.recordings = new LabsRecordingsNamespace(sm);
+    this.transcripts = new LabsTranscriptsNamespace(sm);
   }
 
   /** Discover the Supafone convenience layer over Ultravox. */
@@ -971,6 +1679,20 @@ class LabsAgentsNamespace {
       `/api/v1/labs/agents/${encodeURIComponent(agentKey)}${suffix}`,
     );
   }
+
+  /** Delete an agent. Optionally ask the backend to release assigned numbers. */
+  delete(agentKey: string, opts: DeleteLabsAgentOptions = {}): Promise<DeleteLabsAgentResponse> {
+    const q = new URLSearchParams();
+    const agencyId = opts.agency_id ?? opts.agencyId;
+    const releaseNumbers = opts.release_numbers ?? opts.releaseNumbers;
+    if (agencyId) q.set("agency_id", agencyId);
+    if (releaseNumbers !== undefined) q.set("release_numbers", String(releaseNumbers));
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi<DeleteLabsAgentResponse>(
+      "DELETE",
+      `/api/v1/labs/agents/${encodeURIComponent(agentKey)}${suffix}`,
+    );
+  }
 }
 
 class LabsPresetsNamespace {
@@ -1003,6 +1725,69 @@ class LabsVoicesNamespace {
   }
 }
 
+class LabsCallsNamespace {
+  constructor(private sm: SupafoneLabs) {}
+
+  list(opts: LabsCallListOptions = {}): Promise<LabsCallListResponse> {
+    const q = hostedListQuery(opts);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi<LabsCallListResponse>("GET", `/api/v1/labs/calls${suffix}`);
+  }
+
+  get(callId: string, opts: { agencyId?: string } = {}): Promise<Record<string, unknown>> {
+    const q = new URLSearchParams();
+    if (opts.agencyId) q.set("agency_id", opts.agencyId);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi("GET", `/api/v1/labs/calls/${encodeURIComponent(callId)}${suffix}`);
+  }
+}
+
+class LabsRecordingsNamespace {
+  constructor(private sm: SupafoneLabs) {}
+
+  list(opts: LabsRecordingListOptions = {}): Promise<LabsRecordingListResponse> {
+    const q = hostedListQuery(opts);
+    const callId = opts.call_id ?? opts.callId;
+    if (callId) q.set("call_id", callId);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi<LabsRecordingListResponse>("GET", `/api/v1/labs/recordings${suffix}`);
+  }
+
+  get(recordingId: string, opts: { agencyId?: string } = {}): Promise<Record<string, unknown>> {
+    const q = new URLSearchParams();
+    if (opts.agencyId) q.set("agency_id", opts.agencyId);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi("GET", `/api/v1/labs/recordings/${encodeURIComponent(recordingId)}${suffix}`);
+  }
+
+  delete(recordingId: string, opts: { agencyId?: string; reason?: string } = {}): Promise<Record<string, unknown>> {
+    const q = new URLSearchParams();
+    if (opts.agencyId) q.set("agency_id", opts.agencyId);
+    if (opts.reason) q.set("reason", opts.reason);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi("DELETE", `/api/v1/labs/recordings/${encodeURIComponent(recordingId)}${suffix}`);
+  }
+}
+
+class LabsTranscriptsNamespace {
+  constructor(private sm: SupafoneLabs) {}
+
+  list(opts: LabsTranscriptListOptions = {}): Promise<LabsTranscriptListResponse> {
+    const q = hostedListQuery(opts);
+    const callId = opts.call_id ?? opts.callId;
+    if (callId) q.set("call_id", callId);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi<LabsTranscriptListResponse>("GET", `/api/v1/labs/transcripts${suffix}`);
+  }
+
+  get(transcriptId: string, opts: { agencyId?: string } = {}): Promise<Record<string, unknown>> {
+    const q = new URLSearchParams();
+    if (opts.agencyId) q.set("agency_id", opts.agencyId);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi("GET", `/api/v1/labs/transcripts/${encodeURIComponent(transcriptId)}${suffix}`);
+  }
+}
+
 class LabsPhoneNumbersNamespace {
   constructor(private sm: SupafoneLabs) {}
 
@@ -1048,6 +1833,42 @@ class LabsPhoneNumbersNamespace {
     );
   }
 
+  /** Unassign a number from an agent but keep it reserved on the account. */
+  unassign(numberId: string, input: LabsPhoneNumberReleaseRequest = {}): Promise<LabsPhoneNumberReleaseResponse> {
+    return this.sm.requestSupafoneApi<LabsPhoneNumberReleaseResponse>(
+      "POST",
+      `/api/v1/labs/phone-numbers/${encodeURIComponent(numberId)}/unassign`,
+      phoneNumberReleasePayload(input),
+    );
+  }
+
+  /** Give a number back to the shared pool or release the reservation. */
+  release(numberId: string, input: LabsPhoneNumberReleaseRequest = {}): Promise<LabsPhoneNumberReleaseResponse> {
+    return this.sm.requestSupafoneApi<LabsPhoneNumberReleaseResponse>(
+      "POST",
+      `/api/v1/labs/phone-numbers/${encodeURIComponent(numberId)}/release`,
+      phoneNumberReleasePayload({ ...input, returnToPool: input.returnToPool ?? input.return_to_pool ?? true }),
+    );
+  }
+
+  /** Alias for release(numberId, { returnToPool: true }). */
+  returnToPool(numberId: string, input: LabsPhoneNumberReleaseRequest = {}): Promise<LabsPhoneNumberReleaseResponse> {
+    return this.release(numberId, { ...input, returnToPool: true });
+  }
+
+  /** Delete/release a number reservation. Backend policy decides whether this is allowed. */
+  delete(numberId: string, input: LabsPhoneNumberReleaseRequest = {}): Promise<LabsPhoneNumberReleaseResponse> {
+    const q = new URLSearchParams();
+    const agencyId = input.agency_id ?? input.agencyId;
+    if (agencyId) q.set("agency_id", agencyId);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi<LabsPhoneNumberReleaseResponse>(
+      "DELETE",
+      `/api/v1/labs/phone-numbers/${encodeURIComponent(numberId)}${suffix}`,
+      phoneNumberReleasePayload(input),
+    );
+  }
+
   /**
    * 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.
@@ -1180,17 +2001,26 @@ function labsAgentPayload(input: CreateLabsAgentRequest): Record<string, unknown
     industry: input.industry,
     website_url: input.website_url ?? input.websiteUrl,
     phone_number: input.phone_number ?? input.phoneNumber,
+    number_strategy: input.number_strategy ?? input.numberStrategy,
+    number_pool: input.number_pool ?? input.numberPool,
+    premium: input.premium,
     direction: input.direction,
     preset_key: input.preset_key ?? input.presetKey,
     runtime_mode: input.runtime_mode ?? input.runtimeMode,
+    call_stages: callStagesPayload(input),
     goal: input.goal,
     greeting: input.greeting,
     system_prompt: input.system_prompt ?? input.systemPrompt,
     language: input.language,
     voice: input.voice ? voicePayload(input.voice) : undefined,
     provider_keys: input.provider_keys ?? (input.providerKeys ? providerKeysPayload(input.providerKeys) : undefined),
-    byok: input.byok ? providerKeysPayload(input.byok) : undefined,
+    byok: input.byok ? byokPayload(input.byok) : undefined,
     telephony: input.telephony ? telephonyPayload(input.telephony) : undefined,
+    custom_sip: customSipPayload(input.custom_sip ?? input.customSip ?? input.sip),
+    recording: input.recording ? recordingPayload(input.recording) : undefined,
+    transcription: input.transcription ? transcriptionPayload(input.transcription) : undefined,
+    artifacts: input.artifacts ? artifactsPayload(input.artifacts) : undefined,
+    compliance: input.compliance,
     tools: input.tools ? toolsPayload(input.tools) : undefined,
     labs: input.labs ? labsPayload(input.labs) : undefined,
     ultravox: input.ultravox ? ultravoxPayload(input.ultravox) : undefined,
@@ -1200,13 +2030,28 @@ function labsAgentPayload(input: CreateLabsAgentRequest): Record<string, unknown
   });
 }
 
+function hostedListQuery(opts: LabsCallListOptions): URLSearchParams {
+  const q = new URLSearchParams();
+  if (opts.agencyId) q.set("agency_id", opts.agencyId);
+  const agentKey = opts.agent_key ?? opts.agentKey;
+  if (agentKey) q.set("agent_key", agentKey);
+  if (opts.limit !== undefined) q.set("limit", String(opts.limit));
+  return q;
+}
+
 function telephonyPayload(input: LabsTelephonyConfig): Record<string, unknown> {
   return compact({
     agency_id: input.agency_id ?? input.agencyId,
     mode: input.mode,
     provider: input.provider,
+    number_strategy: input.number_strategy ?? input.numberStrategy,
+    number_pool: input.number_pool ?? input.numberPool,
+    number_id: input.number_id ?? input.numberId,
+    premium: input.premium,
     label: input.label,
     credentials: input.credentials ? telephonyCredentialsPayload(input.credentials) : undefined,
+    provider_settings: input.provider_settings ?? input.providerSettings,
+    custom_sip: customSipPayload(input.custom_sip ?? input.customSip),
     metadata: input.metadata,
   });
 }
@@ -1225,12 +2070,23 @@ function telephonyCredentialsPayload(input: LabsTelephonyCredentials): Record<st
     username: input.username,
     password: input.password,
     webhook_secret: input.webhook_secret ?? input.webhookSecret,
+    telnyx_connection_id: input.telnyx_connection_id ?? input.telnyxConnectionId,
+    signalwire_space_url: input.signalwire_space_url ?? input.signalwireSpaceUrl,
+    project_id: input.project_id ?? input.projectId,
+    application_id: input.application_id ?? input.applicationId,
+    trunk_id: input.trunk_id ?? input.trunkId,
+    endpoint_id: input.endpoint_id ?? input.endpointId,
+    token: input.token,
+    secret: input.secret,
+    custom_sip: customSipPayload(input.custom_sip ?? input.customSip),
   });
 }
 
 function phoneNumberSearchPayload(input: LabsPhoneNumberSearchOptions): Record<string, unknown> {
   return compact({
     agency_id: input.agency_id ?? input.agencyId,
+    number_pool: input.number_pool ?? input.numberPool,
+    number_strategy: input.number_strategy ?? input.numberStrategy,
     country_code: input.country_code ?? input.countryCode,
     area_code: input.area_code ?? input.areaCode,
     postal_code: input.postal_code ?? input.postalCode,
@@ -1252,6 +2108,9 @@ function phoneNumberProvisionPayload(input: LabsPhoneNumberProvisionRequest): Re
     agent_id: input.agent_id ?? input.agentId,
     agent_name: input.agent_name ?? input.agentName,
     preset_key: input.preset_key ?? input.presetKey,
+    number_strategy: input.number_strategy ?? input.numberStrategy,
+    number_pool: input.number_pool ?? input.numberPool,
+    premium: input.premium,
     style: input.agent_style ?? input.agentStyle ?? input.style,
     direction: input.direction,
     telephony: input.telephony ? telephonyPayload(input.telephony) : undefined,
@@ -1267,6 +2126,9 @@ function phoneNumberAssignPayload(input: LabsPhoneNumberAssignRequest): Record<s
     agent_name: input.agent_name ?? input.agentName,
     friendly_name: input.friendly_name ?? input.friendlyName,
     preset_key: input.preset_key ?? input.presetKey,
+    number_strategy: input.number_strategy ?? input.numberStrategy,
+    number_pool: input.number_pool ?? input.numberPool,
+    premium: input.premium,
     style: input.agent_style ?? input.agentStyle ?? input.style,
     direction: input.direction,
     telephony: input.telephony ? telephonyPayload(input.telephony) : undefined,
@@ -1274,6 +2136,103 @@ function phoneNumberAssignPayload(input: LabsPhoneNumberAssignRequest): Record<s
   });
 }
 
+function phoneNumberReleasePayload(input: LabsPhoneNumberReleaseRequest): Record<string, unknown> {
+  return compact({
+    agency_id: input.agency_id ?? input.agencyId,
+    reason: input.reason,
+    return_to_pool: input.return_to_pool ?? input.returnToPool,
+    metadata: input.metadata,
+  });
+}
+
+function callStagesPayload(input: CreateLabsAgentRequest): Record<string, unknown>[] | undefined {
+  const explicit = input.call_stages ?? input.callStages ?? input.stages;
+  const auto = input.auto_call_stages ?? input.autoCallStages;
+  if (Array.isArray(explicit)) return explicit.map(callStagePayload);
+  if (explicit === false || auto === false) return undefined;
+  return generateCallStages(input).map(callStagePayload);
+}
+
+function callStagePayload(input: LabsCallStage): Record<string, unknown> {
+  return compact({
+    key: input.key ?? input.id,
+    name: input.name,
+    goal: input.goal,
+    instructions: input.instructions,
+    exit_criteria: input.exit_criteria ?? input.exitCriteria,
+    tools: input.tools,
+    metadata: input.metadata,
+  });
+}
+
+export function generateCallStages(input: CreateLabsAgentRequest): LabsCallStage[] {
+  const direction = String(input.direction ?? input.agent_style ?? input.agentStyle ?? input.style ?? "inbound").toLowerCase();
+  const haystack = [
+    input.name,
+    input.assistant_name ?? input.assistantName,
+    input.business_name ?? input.businessName,
+    input.industry,
+    input.goal,
+    input.system_prompt ?? input.systemPrompt,
+    input.preset_key ?? input.presetKey,
+  ].filter(Boolean).join(" ").toLowerCase();
+  const meta = { auto_generated: true, source: "supafone-labs-sdk" };
+
+  if (direction === "outbound" || haystack.includes("sales") || haystack.includes("lead")) {
+    return [
+      stage("intro_consent", "Intro and consent", "State who you are, why you are calling, and offer an immediate opt-out.", ["Caller understands purpose", "Opt-out is honored"], meta),
+      stage("qualification", "Qualification", "Confirm fit, urgency, decision process, and the best next step.", ["Need and timeline are clear"], meta),
+      stage("offer", "Offer", "Explain the next step in plain language without unsupported claims.", ["Caller understands the next step"], meta),
+      stage("booking", "Booking", "Book or route the caller only after confirming required details.", ["Next step is confirmed by a tool or human handoff"], meta),
+      stage("close", "Close", "Summarize what will happen next and end politely.", ["Caller knows the follow-up path"], meta),
+    ];
+  }
+
+  if (haystack.includes("legal") || haystack.includes("law") || haystack.includes("injury") || haystack.includes("intake")) {
+    return [
+      stage("greeting", "Greeting", "Open warmly and acknowledge the caller before logistics.", ["Caller need is understood"], meta),
+      stage("incident", "Incident details", "Collect what happened, when it happened, injuries, insurance, and contact details.", ["Core facts are collected"], meta),
+      stage("screening", "Screening", "Identify urgency, jurisdiction, conflicts, and whether human escalation is required.", ["Escalation decision is clear"], meta),
+      stage("booking", "Consult booking", "Book the right next step without quoting fees or inventing availability.", ["Booking or handoff is tool-confirmed"], meta),
+      stage("close", "Close", "Summarize the next step and set expectations accurately.", ["Caller knows exactly what happens next"], meta),
+    ];
+  }
+
+  if (haystack.includes("medical") || haystack.includes("clinic") || haystack.includes("patient") || haystack.includes("health")) {
+    return [
+      stage("greeting", "Greeting", "Identify the caller need and keep the tone calm and concise.", ["Caller need is understood"], meta),
+      stage("patient_context", "Patient context", "Collect non-sensitive scheduling context and avoid medical advice.", ["Required scheduling context is collected"], meta),
+      stage("routing", "Routing", "Route urgent, billing, clinical, and scheduling requests correctly.", ["Correct route is selected"], meta),
+      stage("appointment", "Appointment", "Book or request the appointment only after confirming details.", ["Appointment path is confirmed"], meta),
+      stage("close", "Close", "Recap next steps and any confirmed timing.", ["Caller knows the next step"], meta),
+    ];
+  }
+
+  return [
+    stage("greeting", "Greeting", "Open naturally, identify the caller need, and set a helpful tone.", ["Caller need is understood"], meta),
+    stage("discovery", "Discovery", "Ask one question at a time until the key details are clear.", ["Required details are collected"], meta),
+    stage("resolution", "Resolution", "Answer approved questions or route to the right workflow.", ["Resolution path is selected"], meta),
+    stage("action", "Action", "Use tools for booking, routing, messaging, or handoff before claiming success.", ["Action is confirmed by a tool or handoff"], meta),
+    stage("close", "Close", "Summarize the outcome and next step accurately.", ["Caller knows what happens next"], meta),
+  ];
+}
+
+function stage(
+  key: string,
+  name: string,
+  instructions: string,
+  exitCriteria: string[],
+  metadata: Record<string, unknown>,
+): LabsCallStage {
+  return {
+    key,
+    name,
+    instructions,
+    exitCriteria,
+    metadata,
+  };
+}
+
 function voicePayload(input: LabsVoiceSelection): Record<string, unknown> {
   return compact({
     provider: input.provider,
@@ -1286,6 +2245,30 @@ function providerKeysPayload(input: LabsProviderKeys): Record<string, unknown> {
   return compact({
     ultravox: input.ultravox,
     ultravox_api_key: input.ultravox_api_key ?? input.ultravoxApiKey,
+    retell: input.retell,
+    retell_api_key: input.retell_api_key ?? input.retellApiKey,
+    vapi: input.vapi,
+    vapi_api_key: input.vapi_api_key ?? input.vapiApiKey,
+    bland: input.bland,
+    bland_api_key: input.bland_api_key ?? input.blandApiKey,
+    livekit: input.livekit,
+    livekit_api_key: input.livekit_api_key ?? input.livekitApiKey,
+    livekit_api_secret: input.livekit_api_secret ?? input.livekitApiSecret,
+    pipecat: input.pipecat,
+    pipecat_api_key: input.pipecat_api_key ?? input.pipecatApiKey,
+    twilio: input.twilio,
+    twilio_account_sid: input.twilio_account_sid ?? input.twilioAccountSid,
+    twilio_auth_token: input.twilio_auth_token ?? input.twilioAuthToken,
+    twilio_api_key_sid: input.twilio_api_key_sid ?? input.twilioApiKeySid,
+    twilio_api_key_secret: input.twilio_api_key_secret ?? input.twilioApiKeySecret,
+    telnyx: input.telnyx,
+    telnyx_api_key: input.telnyx_api_key ?? input.telnyxApiKey,
+    plivo: input.plivo,
+    plivo_auth_id: input.plivo_auth_id ?? input.plivoAuthId,
+    plivo_auth_token: input.plivo_auth_token ?? input.plivoAuthToken,
+    signalwire: input.signalwire,
+    signalwire_api_token: input.signalwire_api_token ?? input.signalwireApiToken,
+    signalwire_project_id: input.signalwire_project_id ?? input.signalwireProjectId,
     elevenlabs: input.elevenlabs,
     elevenlabs_api_key: input.elevenlabs_api_key ?? input.elevenlabsApiKey,
     cartesia: input.cartesia,
@@ -1294,6 +2277,59 @@ function providerKeysPayload(input: LabsProviderKeys): Record<string, unknown> {
     inworld_api_key: input.inworld_api_key ?? input.inworldApiKey,
     deepgram: input.deepgram,
     deepgram_api_key: input.deepgram_api_key ?? input.deepgramApiKey,
+    anthropic: input.anthropic,
+    anthropic_api_key: input.anthropic_api_key ?? input.anthropicApiKey,
+    openai: input.openai,
+    openai_api_key: input.openai_api_key ?? input.openaiApiKey,
+    xai: input.xai,
+    xai_api_key: input.xai_api_key ?? input.xaiApiKey,
+  });
+}
+
+function byokPayload(input: LabsProviderKeys | LabsByokConfig): Record<string, unknown> {
+  const structured = input as LabsByokConfig;
+  if (
+    structured.agentProvider ||
+    structured.agent_provider ||
+    structured.runtime ||
+    structured.telephony ||
+    structured.tts ||
+    structured.stt ||
+    structured.llm ||
+    structured.providerKeys ||
+    structured.provider_keys ||
+    structured.customSip ||
+    structured.custom_sip ||
+    structured.sip
+  ) {
+    return compact({
+      provider_keys: providerKeysPayload(structured.provider_keys ?? structured.providerKeys ?? {}),
+      agent_provider: providerConfigPayload(structured.agent_provider ?? structured.agentProvider ?? structured.runtime),
+      telephony: structured.telephony ? telephonyPayload(structured.telephony) : undefined,
+      tts: providerConfigPayload(structured.tts),
+      stt: providerConfigPayload(structured.stt),
+      llm: providerConfigPayload(structured.llm),
+      custom_sip: customSipPayload(structured.custom_sip ?? structured.customSip ?? structured.sip),
+    });
+  }
+  return providerKeysPayload(input as LabsProviderKeys);
+}
+
+function providerConfigPayload(input?: LabsProviderByokConfig): Record<string, unknown> | undefined {
+  if (!input) return undefined;
+  const out: Record<string, unknown> = { ...input };
+  delete out.apiKey;
+  delete out.api_key;
+  delete out.voiceId;
+  delete out.voice_id;
+  return compact({
+    ...out,
+    provider: input.provider,
+    api_key: input.api_key ?? input.apiKey,
+    credentials: input.credentials,
+    settings: input.settings,
+    model: input.model,
+    voice_id: input.voice_id ?? input.voiceId,
   });
 }
 
@@ -1312,11 +2348,57 @@ function toolsPayload(input: LabsToolsConfig): Record<string, unknown> {
   });
 }
 
+function recordingPayload(input: LabsRecordingConfig): Record<string, unknown> {
+  return compact({
+    enabled: input.enabled,
+    record_audio: input.record_audio ?? input.recordAudio,
+    consent_required: input.consent_required ?? input.consentRequired,
+    announcement: input.announcement,
+    retention_days: input.retention_days ?? input.retentionDays,
+    storage: input.storage,
+    redact_pii: input.redact_pii ?? input.redactPii,
+    metadata: input.metadata,
+  });
+}
+
+function transcriptionPayload(input: LabsTranscriptionConfig): Record<string, unknown> {
+  return compact({
+    enabled: input.enabled,
+    provider: input.provider,
+    model: input.model,
+    language: input.language,
+    redact_pii: input.redact_pii ?? input.redactPii,
+    diarization: input.diarization,
+    timestamps: input.timestamps,
+    metadata: input.metadata,
+  });
+}
+
+function artifactsPayload(input: LabsArtifactsConfig): Record<string, unknown> {
+  return compact({
+    recordings: input.recordings,
+    transcripts: input.transcripts,
+    summaries: input.summaries,
+    qa_reports: input.qa_reports ?? input.qaReports,
+    logs: input.logs,
+    webhooks: input.webhooks,
+    retention_days: input.retention_days ?? input.retentionDays,
+    metadata: input.metadata,
+  });
+}
+
 function labsPayload(input: LabsWatcherConfig): Record<string, unknown> {
   return compact({
     enabled: input.enabled,
     voice_watcher: input.voice_watcher ?? input.voiceWatcher,
+    api_key: input.api_key ?? input.apiKey,
     model: input.model,
+    mode: input.mode,
+    managed_infrastructure: input.managed_infrastructure ?? input.managedInfrastructure,
+    stt: input.stt,
+    llm: input.llm,
+    tts: input.tts,
+    provider_keys: input.provider_keys ?? input.providerKeys,
     label: input.label,
   });
 }
@@ -1346,6 +2428,24 @@ function ultravoxPayload(input: LabsUltravoxRuntime): Record<string, unknown> {
     voiceOverrides: input.voiceOverrides ?? input.voice_overrides,
     retentionPolicy: input.retentionPolicy ?? input.retention_policy,
     callTemplate: input.callTemplate ?? input.call_template,
+    custom_sip: customSipPayload(input.custom_sip ?? input.customSip ?? input.sip),
+  });
+}
+
+function customSipPayload(input?: LabsCustomSipConfig): Record<string, unknown> | undefined {
+  if (!input) return undefined;
+  return compact({
+    sip_trunk_uri: input.sip_trunk_uri ?? input.sipTrunkUri,
+    trunk_uri: input.trunk_uri ?? input.trunkUri,
+    sip_host: input.sip_host ?? input.sipHost,
+    from_number: input.from_number ?? input.fromNumber,
+    username: input.username,
+    password: input.password,
+    transport: input.transport,
+    headers: input.headers,
+    codecs: input.codecs,
+    dtmf_mode: input.dtmf_mode ?? input.dtmfMode,
+    metadata: input.metadata,
   });
 }
 
@@ -1357,6 +2457,18 @@ function compact(input: Record<string, unknown>): Record<string, unknown> {
   return out;
 }
 
+function parseSseLog(raw: string): LabsLogEntry | null {
+  const data: string[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line || line.startsWith(":")) continue;
+    if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
+  }
+  if (!data.length) return null;
+  const parsed = safeJson(data.join("\n"));
+  if (!parsed || typeof parsed !== "object") return null;
+  return parsed as LabsLogEntry;
+}
+
 function safeJson(text: string): unknown {
   try {
     return JSON.parse(text);