@openclaw/voice-call 2026.5.2 → 2026.5.3-beta.2

package/src/providers/telnyx.ts

@@ -1,394 +0,0 @@
-import crypto from "node:crypto";
-import type { TelnyxConfig } from "../config.js";
-import type {
-  AnswerCallInput,
-  EndReason,
-  GetCallStatusInput,
-  GetCallStatusResult,
-  HangupCallInput,
-  InitiateCallInput,
-  InitiateCallResult,
-  NormalizedEvent,
-  PlayTtsInput,
-  ProviderWebhookParseResult,
-  StartListeningInput,
-  StopListeningInput,
-  WebhookContext,
-  WebhookParseOptions,
-  WebhookVerificationResult,
-} from "../types.js";
-import { verifyTelnyxWebhook } from "../webhook-security.js";
-import type { VoiceCallProvider } from "./base.js";
-import { guardedJsonApiRequest } from "./shared/guarded-json-api.js";
-
-/**
- * Telnyx Voice API provider implementation.
- *
- * Uses Telnyx Call Control API v2 for managing calls.
- * @see https://developers.telnyx.com/docs/api/v2/call-control
- */
-export interface TelnyxProviderOptions {
-  /** Skip webhook signature verification (development only, NOT for production) */
-  skipVerification?: boolean;
-}
-
-function normalizeTelnyxDirection(
-  direction: string | undefined,
-): "inbound" | "outbound" | undefined {
-  switch (direction) {
-    case "incoming":
-    case "inbound":
-      return "inbound";
-    case "outgoing":
-    case "outbound":
-      return "outbound";
-    default:
-      return undefined;
-  }
-}
-
-export class TelnyxProvider implements VoiceCallProvider {
-  readonly name = "telnyx" as const;
-
-  private readonly apiKey: string;
-  private readonly connectionId: string;
-  private readonly publicKey: string | undefined;
-  private readonly options: TelnyxProviderOptions;
-  private readonly baseUrl = "https://api.telnyx.com/v2";
-  private readonly apiHost = "api.telnyx.com";
-
-  constructor(config: TelnyxConfig, options: TelnyxProviderOptions = {}) {
-    if (!config.apiKey) {
-      throw new Error("Telnyx API key is required");
-    }
-    if (!config.connectionId) {
-      throw new Error("Telnyx connection ID is required");
-    }
-
-    this.apiKey = config.apiKey;
-    this.connectionId = config.connectionId;
-    this.publicKey = config.publicKey;
-    this.options = options;
-  }
-
-  /**
-   * Make an authenticated request to the Telnyx API.
-   */
-  private async apiRequest<T = unknown>(
-    endpoint: string,
-    body: Record<string, unknown>,
-    options?: { allowNotFound?: boolean },
-  ): Promise<T> {
-    return await guardedJsonApiRequest<T>({
-      url: `${this.baseUrl}${endpoint}`,
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${this.apiKey}`,
-        "Content-Type": "application/json",
-      },
-      body,
-      allowNotFound: options?.allowNotFound,
-      allowedHostnames: [this.apiHost],
-      auditContext: "voice-call.telnyx.api",
-      errorPrefix: "Telnyx API error",
-    });
-  }
-
-  /**
-   * Verify Telnyx webhook signature using Ed25519.
-   */
-  verifyWebhook(ctx: WebhookContext): WebhookVerificationResult {
-    const result = verifyTelnyxWebhook(ctx, this.publicKey, {
-      skipVerification: this.options.skipVerification,
-    });
-
-    return {
-      ok: result.ok,
-      reason: result.reason,
-      isReplay: result.isReplay,
-      verifiedRequestKey: result.verifiedRequestKey,
-    };
-  }
-
-  /**
-   * Parse Telnyx webhook event into normalized format.
-   */
-  parseWebhookEvent(
-    ctx: WebhookContext,
-    options?: WebhookParseOptions,
-  ): ProviderWebhookParseResult {
-    try {
-      const payload = JSON.parse(ctx.rawBody);
-      const data = payload.data;
-
-      if (!data || !data.event_type) {
-        return { events: [], statusCode: 200 };
-      }
-
-      const event = this.normalizeEvent(data, options?.verifiedRequestKey);
-      return {
-        events: event ? [event] : [],
-        statusCode: 200,
-      };
-    } catch {
-      return { events: [], statusCode: 400 };
-    }
-  }
-
-  /**
-   * Convert Telnyx event to normalized event format.
-   */
-  private normalizeEvent(data: TelnyxEvent, dedupeKey?: string): NormalizedEvent | null {
-    // Decode client_state from Base64 (we encode it in initiateCall)
-    let callId = "";
-    if (data.payload?.client_state) {
-      try {
-        callId = Buffer.from(data.payload.client_state, "base64").toString("utf8");
-      } catch {
-        // Fallback if not valid Base64
-        callId = data.payload.client_state;
-      }
-    }
-    if (!callId) {
-      callId = data.payload?.call_control_id || "";
-    }
-
-    const baseEvent = {
-      id: data.id || crypto.randomUUID(),
-      dedupeKey,
-      callId,
-      providerCallId: data.payload?.call_control_id,
-      timestamp: Date.now(),
-      direction: normalizeTelnyxDirection(data.payload?.direction),
-      from: data.payload?.from,
-      to: data.payload?.to,
-    };
-
-    switch (data.event_type) {
-      case "call.initiated":
-        return { ...baseEvent, type: "call.initiated" };
-
-      case "call.ringing":
-        return { ...baseEvent, type: "call.ringing" };
-
-      case "call.answered":
-        return { ...baseEvent, type: "call.answered" };
-
-      case "call.bridged":
-        return { ...baseEvent, type: "call.active" };
-
-      case "call.speak.started":
-        return {
-          ...baseEvent,
-          type: "call.speaking",
-          text: data.payload?.text || "",
-        };
-
-      case "call.transcription":
-        return {
-          ...baseEvent,
-          type: "call.speech",
-          transcript:
-            data.payload?.transcription_data?.transcript ?? data.payload?.transcription ?? "",
-          isFinal: data.payload?.transcription_data?.is_final ?? data.payload?.is_final ?? true,
-          confidence: data.payload?.transcription_data?.confidence ?? data.payload?.confidence,
-        };
-
-      case "call.hangup":
-        return {
-          ...baseEvent,
-          type: "call.ended",
-          reason: this.mapHangupCause(data.payload?.hangup_cause),
-        };
-
-      case "call.dtmf.received":
-        return {
-          ...baseEvent,
-          type: "call.dtmf",
-          digits: data.payload?.digit || "",
-        };
-
-      default:
-        return null;
-    }
-  }
-
-  /**
-   * Map Telnyx hangup cause to normalized end reason.
-   * @see https://developers.telnyx.com/docs/api/v2/call-control/Call-Commands#hangup-causes
-   */
-  private mapHangupCause(cause?: string): EndReason {
-    switch (cause) {
-      case "normal_clearing":
-      case "normal_unspecified":
-        return "completed";
-      case "originator_cancel":
-        return "hangup-bot";
-      case "call_rejected":
-      case "user_busy":
-        return "busy";
-      case "no_answer":
-      case "no_user_response":
-        return "no-answer";
-      case "destination_out_of_order":
-      case "network_out_of_order":
-      case "service_unavailable":
-      case "recovery_on_timer_expire":
-        return "failed";
-      case "machine_detected":
-      case "fax_detected":
-        return "voicemail";
-      case "user_hangup":
-      case "subscriber_absent":
-        return "hangup-user";
-      default:
-        // Unknown cause - log it for debugging and return completed
-        if (cause) {
-          console.warn(`[telnyx] Unknown hangup cause: ${cause}`);
-        }
-        return "completed";
-    }
-  }
-
-  /**
-   * Initiate an outbound call via Telnyx API.
-   */
-  async initiateCall(input: InitiateCallInput): Promise<InitiateCallResult> {
-    const result = await this.apiRequest<TelnyxCallResponse>("/calls", {
-      connection_id: this.connectionId,
-      to: input.to,
-      from: input.from,
-      webhook_url: input.webhookUrl,
-      webhook_url_method: "POST",
-      client_state: Buffer.from(input.callId).toString("base64"),
-      timeout_secs: 30,
-    });
-
-    return {
-      providerCallId: result.data.call_control_id,
-      status: "initiated",
-    };
-  }
-
-  /**
-   * Hang up a call via Telnyx API.
-   */
-  async hangupCall(input: HangupCallInput): Promise<void> {
-    await this.apiRequest(
-      `/calls/${input.providerCallId}/actions/hangup`,
-      { command_id: crypto.randomUUID() },
-      { allowNotFound: true },
-    );
-  }
-
-  /**
-   * Answer an inbound Telnyx Call Control leg.
-   */
-  async answerCall(input: AnswerCallInput): Promise<void> {
-    await this.apiRequest(`/calls/${input.providerCallId}/actions/answer`, {
-      command_id: `openclaw-answer-${input.callId}`,
-    });
-  }
-
-  /**
-   * Play TTS audio via Telnyx speak action.
-   */
-  async playTts(input: PlayTtsInput): Promise<void> {
-    await this.apiRequest(`/calls/${input.providerCallId}/actions/speak`, {
-      command_id: crypto.randomUUID(),
-      payload: input.text,
-      voice: input.voice || "female",
-      language: input.locale || "en-US",
-    });
-  }
-
-  /**
-   * Start transcription (STT) via Telnyx.
-   */
-  async startListening(input: StartListeningInput): Promise<void> {
-    await this.apiRequest(`/calls/${input.providerCallId}/actions/transcription_start`, {
-      command_id: crypto.randomUUID(),
-      language: input.language || "en",
-    });
-  }
-
-  /**
-   * Stop transcription via Telnyx.
-   */
-  async stopListening(input: StopListeningInput): Promise<void> {
-    await this.apiRequest(
-      `/calls/${input.providerCallId}/actions/transcription_stop`,
-      { command_id: crypto.randomUUID() },
-      { allowNotFound: true },
-    );
-  }
-
-  async getCallStatus(input: GetCallStatusInput): Promise<GetCallStatusResult> {
-    try {
-      const data = await guardedJsonApiRequest<{ data?: { state?: string; is_alive?: boolean } }>({
-        url: `${this.baseUrl}/calls/${input.providerCallId}`,
-        method: "GET",
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-        },
-        allowNotFound: true,
-        allowedHostnames: [this.apiHost],
-        auditContext: "telnyx-get-call-status",
-        errorPrefix: "Telnyx get call status error",
-      });
-
-      if (!data) {
-        return { status: "not-found", isTerminal: true };
-      }
-
-      const state = data.data?.state ?? "unknown";
-      const isAlive = data.data?.is_alive;
-      // If is_alive is missing, treat as unknown rather than terminal (P1 fix)
-      if (isAlive === undefined) {
-        return { status: state, isTerminal: false, isUnknown: true };
-      }
-      return { status: state, isTerminal: !isAlive };
-    } catch {
-      return { status: "error", isTerminal: false, isUnknown: true };
-    }
-  }
-}
-
-// -----------------------------------------------------------------------------
-// Telnyx-specific types
-// -----------------------------------------------------------------------------
-
-interface TelnyxEvent {
-  id?: string;
-  event_type: string;
-  payload?: {
-    call_control_id?: string;
-    client_state?: string;
-    direction?: string;
-    from?: string;
-    to?: string;
-    text?: string;
-    transcription?: string;
-    is_final?: boolean;
-    confidence?: number;
-    transcription_data?: {
-      transcript?: string;
-      is_final?: boolean;
-      confidence?: number;
-    };
-    hangup_cause?: string;
-    digit?: string;
-    [key: string]: unknown;
-  };
-}
-
-interface TelnyxCallResponse {
-  data: {
-    call_control_id: string;
-    call_leg_id: string;
-    call_session_id: string;
-    is_alive: boolean;
-    record_type: string;
-  };
-}

package/src/providers/twilio/api.test.ts

@@ -1,145 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-const { fetchWithSsrFGuardMock } = vi.hoisted(() => ({
-  fetchWithSsrFGuardMock: vi.fn(),
-}));
-
-vi.mock("../../../api.js", () => ({
-  fetchWithSsrFGuard: fetchWithSsrFGuardMock,
-}));
-
-import { TwilioApiError, twilioApiRequest } from "./api.js";
-
-describe("twilioApiRequest", () => {
-  afterEach(() => {
-    fetchWithSsrFGuardMock.mockReset();
-  });
-
-  it("posts form bodies with basic auth and parses json", async () => {
-    const release = vi.fn(async () => {});
-    fetchWithSsrFGuardMock.mockResolvedValue({
-      response: new Response(JSON.stringify({ sid: "CA123" }), { status: 200 }),
-      release,
-    });
-
-    await expect(
-      twilioApiRequest({
-        baseUrl: "https://api.twilio.com",
-        accountSid: "AC123",
-        authToken: "secret",
-        endpoint: "/Calls.json",
-        body: {
-          To: "+14155550123",
-          StatusCallbackEvent: ["initiated", "completed"],
-        },
-      }),
-    ).resolves.toEqual({ sid: "CA123" });
-
-    const [{ url, init, auditContext, policy, timeoutMs }] =
-      fetchWithSsrFGuardMock.mock.calls[0] ?? [];
-    expect(url).toBe("https://api.twilio.com/Calls.json");
-    expect(auditContext).toBe("voice-call.twilio.api");
-    expect(policy).toEqual({ allowedHostnames: ["api.twilio.com"] });
-    expect(timeoutMs).toBe(30_000);
-    expect(init).toEqual(
-      expect.objectContaining({
-        method: "POST",
-        headers: {
-          Authorization: `Basic ${Buffer.from("AC123:secret").toString("base64")}`,
-          "Content-Type": "application/x-www-form-urlencoded",
-        },
-      }),
-    );
-    const requestBody = init?.body;
-    if (!(requestBody instanceof URLSearchParams)) {
-      throw new Error("expected URLSearchParams request body");
-    }
-    expect(requestBody.toString()).toBe(
-      "To=%2B14155550123&StatusCallbackEvent=initiated&StatusCallbackEvent=completed",
-    );
-    expect(release).toHaveBeenCalledTimes(1);
-  });
-
-  it("passes through URLSearchParams, allows 404s, and returns undefined for empty bodies", async () => {
-    const responses = [
-      new Response(null, { status: 204 }),
-      new Response("missing", { status: 404 }),
-    ];
-    const release = vi.fn(async () => {});
-    fetchWithSsrFGuardMock.mockImplementation(async () => ({
-      response: responses.shift()!,
-      release,
-    }));
-
-    await expect(
-      twilioApiRequest({
-        baseUrl: "https://api.twilio.com",
-        accountSid: "AC123",
-        authToken: "secret",
-        endpoint: "/Calls.json",
-        body: new URLSearchParams({ To: "+14155550123" }),
-      }),
-    ).resolves.toBeUndefined();
-
-    await expect(
-      twilioApiRequest({
-        baseUrl: "https://api.twilio.com",
-        accountSid: "AC123",
-        authToken: "secret",
-        endpoint: "/Calls/missing.json",
-        body: {},
-        allowNotFound: true,
-      }),
-    ).resolves.toBeUndefined();
-    expect(release).toHaveBeenCalledTimes(2);
-  });
-
-  it("throws twilio api errors for non-ok responses", async () => {
-    const release = vi.fn(async () => {});
-    fetchWithSsrFGuardMock.mockResolvedValue({
-      response: new Response("bad request", { status: 400 }),
-      release,
-    });
-
-    await expect(
-      twilioApiRequest({
-        baseUrl: "https://api.twilio.com",
-        accountSid: "AC123",
-        authToken: "secret",
-        endpoint: "/Calls.json",
-        body: {},
-      }),
-    ).rejects.toThrow("Twilio API error: 400 bad request");
-    expect(release).toHaveBeenCalledTimes(1);
-  });
-
-  it("exposes structured Twilio error codes from json error bodies", async () => {
-    const release = vi.fn(async () => {});
-    fetchWithSsrFGuardMock.mockResolvedValue({
-      response: new Response(
-        JSON.stringify({
-          code: 21220,
-          message: "Call is not in-progress. Cannot redirect.",
-        }),
-        { status: 400 },
-      ),
-      release,
-    });
-
-    await expect(
-      twilioApiRequest({
-        baseUrl: "https://api.twilio.com",
-        accountSid: "AC123",
-        authToken: "secret",
-        endpoint: "/Calls/CA123.json",
-        body: {},
-      }),
-    ).rejects.toMatchObject({
-      name: "TwilioApiError",
-      httpStatus: 400,
-      twilioCode: 21220,
-      message: "Twilio API error: 400 Call is not in-progress. Cannot redirect.",
-    } satisfies Partial<TwilioApiError>);
-    expect(release).toHaveBeenCalledTimes(1);
-  });
-});

package/src/providers/twilio/api.ts

@@ -1,93 +0,0 @@
-import { fetchWithSsrFGuard } from "../../../api.js";
-
-type ParsedTwilioApiError = {
-  code?: number;
-  message?: string;
-};
-
-const TWILIO_API_TIMEOUT_MS = 30_000;
-
-function parseTwilioApiError(text: string): ParsedTwilioApiError {
-  try {
-    const parsed: unknown = JSON.parse(text);
-    if (!parsed || typeof parsed !== "object") {
-      return {};
-    }
-    const record = parsed as Record<string, unknown>;
-    return {
-      code: typeof record.code === "number" ? record.code : undefined,
-      message: typeof record.message === "string" ? record.message : undefined,
-    };
-  } catch {
-    return {};
-  }
-}
-
-export class TwilioApiError extends Error {
-  readonly httpStatus: number;
-  readonly responseText: string;
-  readonly twilioCode?: number;
-
-  constructor(httpStatus: number, responseText: string) {
-    const parsed = parseTwilioApiError(responseText);
-    const detail = parsed.message ?? responseText;
-    super(`Twilio API error: ${httpStatus} ${detail}`);
-    this.name = "TwilioApiError";
-    this.httpStatus = httpStatus;
-    this.responseText = responseText;
-    this.twilioCode = parsed.code;
-  }
-}
-
-export async function twilioApiRequest<T = unknown>(params: {
-  baseUrl: string;
-  accountSid: string;
-  authToken: string;
-  endpoint: string;
-  body: URLSearchParams | Record<string, string | string[]>;
-  allowNotFound?: boolean;
-}): Promise<T> {
-  const bodyParams =
-    params.body instanceof URLSearchParams
-      ? params.body
-      : Object.entries(params.body).reduce((acc, [key, value]) => {
-          if (Array.isArray(value)) {
-            for (const entry of value) {
-              acc.append(key, entry);
-            }
-          } else if (typeof value === "string") {
-            acc.append(key, value);
-          }
-          return acc;
-        }, new URLSearchParams());
-
-  const requestUrl = `${params.baseUrl}${params.endpoint}`;
-  const { response, release } = await fetchWithSsrFGuard({
-    url: requestUrl,
-    init: {
-      method: "POST",
-      headers: {
-        Authorization: `Basic ${Buffer.from(`${params.accountSid}:${params.authToken}`).toString("base64")}`,
-        "Content-Type": "application/x-www-form-urlencoded",
-      },
-      body: bodyParams,
-    },
-    policy: { allowedHostnames: ["api.twilio.com"] },
-    timeoutMs: TWILIO_API_TIMEOUT_MS,
-    auditContext: "voice-call.twilio.api",
-  });
-  try {
-    if (!response.ok) {
-      if (params.allowNotFound && response.status === 404) {
-        return undefined as T;
-      }
-      const errorText = await response.text();
-      throw new TwilioApiError(response.status, errorText);
-    }
-
-    const text = await response.text();
-    return text ? (JSON.parse(text) as T) : (undefined as T);
-  } finally {
-    await release();
-  }
-}

package/src/providers/twilio/twiml-policy.test.ts

@@ -1,84 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { WebhookContext } from "../../types.js";
-import { decideTwimlResponse, readTwimlRequestView } from "./twiml-policy.js";
-
-function createContext(rawBody: string, query?: WebhookContext["query"]): WebhookContext {
-  return {
-    headers: {},
-    rawBody,
-    url: "https://example.ngrok.app/voice/twilio",
-    method: "POST",
-    query,
-  };
-}
-
-describe("twiml policy", () => {
-  it("returns stored twiml decision for initial notify callback", () => {
-    const view = readTwimlRequestView(
-      createContext("CallStatus=initiated&Direction=outbound-api&CallSid=CA123", {
-        callId: "call-1",
-      }),
-    );
-
-    const decision = decideTwimlResponse({
-      ...view,
-      hasStoredTwiml: true,
-      isNotifyCall: true,
-      hasActiveStreams: false,
-      canStream: true,
-    });
-
-    expect(decision.kind).toBe("stored");
-  });
-
-  it("returns queue for inbound when another stream is active", () => {
-    const view = readTwimlRequestView(
-      createContext("CallStatus=ringing&Direction=inbound&CallSid=CA456"),
-    );
-
-    const decision = decideTwimlResponse({
-      ...view,
-      hasStoredTwiml: false,
-      isNotifyCall: false,
-      hasActiveStreams: true,
-      canStream: true,
-    });
-
-    expect(decision.kind).toBe("queue");
-  });
-
-  it("returns stream + activation for inbound call when available", () => {
-    const view = readTwimlRequestView(
-      createContext("CallStatus=ringing&Direction=inbound&CallSid=CA789"),
-    );
-
-    const decision = decideTwimlResponse({
-      ...view,
-      hasStoredTwiml: false,
-      isNotifyCall: false,
-      hasActiveStreams: false,
-      canStream: true,
-    });
-
-    expect(decision.kind).toBe("stream");
-    expect(decision.activateStreamCallSid).toBe("CA789");
-  });
-
-  it("returns empty for status callbacks", () => {
-    const view = readTwimlRequestView(
-      createContext("CallStatus=completed&Direction=inbound&CallSid=CA123", {
-        type: "status",
-      }),
-    );
-
-    const decision = decideTwimlResponse({
-      ...view,
-      hasStoredTwiml: false,
-      isNotifyCall: false,
-      hasActiveStreams: false,
-      canStream: true,
-    });
-
-    expect(decision.kind).toBe("empty");
-  });
-});