@kodelyth/voice-call 2026.5.42 → 2026.6.1

package/src/providers/base.ts

@@ -1,99 +0,0 @@
-import type {
-  AnswerCallInput,
-  GetCallStatusInput,
-  GetCallStatusResult,
-  HangupCallInput,
-  InitiateCallInput,
-  InitiateCallResult,
-  PlayTtsInput,
-  ProviderName,
-  SendDtmfInput,
-  WebhookParseOptions,
-  ProviderWebhookParseResult,
-  StartListeningInput,
-  StopListeningInput,
-  WebhookContext,
-  WebhookVerificationResult,
-} from "../types.js";
-
-/**
- * Abstract base interface for voice call providers.
- *
- * Each provider (Telnyx, Twilio, etc.) implements this interface to provide
- * a consistent API for the call manager.
- *
- * Responsibilities:
- * - Webhook verification and event parsing
- * - Outbound call initiation and hangup
- * - Media control (TTS playback, STT listening)
- */
-export interface VoiceCallProvider {
-  /** Provider identifier */
-  readonly name: ProviderName;
-
-  setPublicUrl?(url: string): void;
-
-  /**
-   * Verify webhook signature/HMAC before processing.
-   * Must be called before parseWebhookEvent.
-   */
-  verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
-
-  /**
-   * Parse provider-specific webhook payload into normalized events.
-   * Returns events and optional response to send back to provider.
-   */
-  parseWebhookEvent(ctx: WebhookContext, options?: WebhookParseOptions): ProviderWebhookParseResult;
-
-  /**
-   * Consume one-time TwiML that must be served before shortcut handlers such as
-   * realtime media streams take over the webhook response.
-   */
-  consumeInitialTwiML?: (ctx: WebhookContext) => string | null;
-
-  /**
-   * Initiate an outbound call.
-   * @returns Provider call ID and status
-   */
-  initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
-
-  /**
-   * Answer an accepted inbound call when the provider requires an explicit
-   * answer command after the initial webhook.
-   */
-  answerCall?: (input: AnswerCallInput) => Promise<void>;
-
-  /**
-   * Hang up an active call.
-   */
-  hangupCall(input: HangupCallInput): Promise<void>;
-
-  /**
-   * Play TTS audio to the caller.
-   * The provider should handle streaming if supported.
-   */
-  playTts(input: PlayTtsInput): Promise<void>;
-
-  /**
-   * Send DTMF digits to an active call.
-   */
-  sendDtmf?: (input: SendDtmfInput) => Promise<void>;
-
-  /**
-   * Start listening for user speech (activate STT).
-   */
-  startListening(input: StartListeningInput): Promise<void>;
-
-  /**
-   * Stop listening for user speech (deactivate STT).
-   */
-  stopListening(input: StopListeningInput): Promise<void>;
-
-  /**
-   * Query provider for current call status.
-   * Used to verify persisted calls are still active on restart.
-   * Must return `isUnknown: true` for transient errors (network, 5xx)
-   * so the caller can keep the call and rely on timer-based fallback.
-   */
-  getCallStatus(input: GetCallStatusInput): Promise<GetCallStatusResult>;
-}

package/src/providers/mock.test.ts

@@ -1,86 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { WebhookContext } from "../types.js";
-import { MockProvider } from "./mock.js";
-
-function createWebhookContext(rawBody: string): WebhookContext {
-  return {
-    headers: {},
-    rawBody,
-    url: "http://localhost/voice/webhook",
-    method: "POST",
-    query: {},
-  };
-}
-
-describe("MockProvider", () => {
-  it("preserves explicit falsy event values", () => {
-    const provider = new MockProvider();
-    const beforeParse = Date.now();
-    const result = provider.parseWebhookEvent(
-      createWebhookContext(
-        JSON.stringify({
-          events: [
-            {
-              id: "evt-error",
-              type: "call.error",
-              callId: "call-1",
-              timestamp: 0,
-              error: "",
-              retryable: false,
-            },
-            {
-              id: "evt-ended",
-              type: "call.ended",
-              callId: "call-2",
-              reason: "",
-            },
-            {
-              id: "evt-speech",
-              type: "call.speech",
-              callId: "call-3",
-              transcript: "",
-              isFinal: false,
-            },
-          ],
-        }),
-      ),
-    );
-    const afterParse = Date.now();
-    const endedTimestamp = result.events[1]?.timestamp;
-    const speechTimestamp = result.events[2]?.timestamp;
-
-    expect(result.events).toEqual([
-      {
-        id: "evt-error",
-        type: "call.error",
-        callId: "call-1",
-        providerCallId: undefined,
-        timestamp: 0,
-        error: "",
-        retryable: false,
-      },
-      {
-        id: "evt-ended",
-        type: "call.ended",
-        callId: "call-2",
-        providerCallId: undefined,
-        timestamp: endedTimestamp,
-        reason: "",
-      },
-      {
-        id: "evt-speech",
-        type: "call.speech",
-        callId: "call-3",
-        providerCallId: undefined,
-        timestamp: speechTimestamp,
-        transcript: "",
-        isFinal: false,
-        confidence: undefined,
-      },
-    ]);
-    expect(endedTimestamp).toBeGreaterThanOrEqual(beforeParse);
-    expect(endedTimestamp).toBeLessThanOrEqual(afterParse);
-    expect(speechTimestamp).toBeGreaterThanOrEqual(beforeParse);
-    expect(speechTimestamp).toBeLessThanOrEqual(afterParse);
-  });
-});

package/src/providers/mock.ts

@@ -1,185 +0,0 @@
-import crypto from "node:crypto";
-import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
-import type {
-  EndReason,
-  GetCallStatusInput,
-  GetCallStatusResult,
-  HangupCallInput,
-  InitiateCallInput,
-  InitiateCallResult,
-  NormalizedEvent,
-  PlayTtsInput,
-  WebhookParseOptions,
-  ProviderWebhookParseResult,
-  SendDtmfInput,
-  StartListeningInput,
-  StopListeningInput,
-  WebhookContext,
-  WebhookVerificationResult,
-} from "../types.js";
-import type { VoiceCallProvider } from "./base.js";
-
-/**
- * Mock voice call provider for local testing.
- *
- * Events are driven via webhook POST with JSON body:
- * - { events: NormalizedEvent[] } for bulk events
- * - { event: NormalizedEvent } for single event
- */
-export class MockProvider implements VoiceCallProvider {
-  readonly name = "mock" as const;
-
-  verifyWebhook(_ctx: WebhookContext): WebhookVerificationResult {
-    return { ok: true };
-  }
-
-  parseWebhookEvent(
-    ctx: WebhookContext,
-    _options?: WebhookParseOptions,
-  ): ProviderWebhookParseResult {
-    try {
-      const payload = JSON.parse(ctx.rawBody);
-      const events: NormalizedEvent[] = [];
-
-      if (Array.isArray(payload.events)) {
-        for (const evt of payload.events) {
-          const normalized = this.normalizeEvent(evt);
-          if (normalized) {
-            events.push(normalized);
-          }
-        }
-      } else if (payload.event) {
-        const normalized = this.normalizeEvent(payload.event);
-        if (normalized) {
-          events.push(normalized);
-        }
-      }
-
-      return { events, statusCode: 200 };
-    } catch {
-      return { events: [], statusCode: 400 };
-    }
-  }
-
-  private normalizeEvent(evt: Partial<NormalizedEvent>): NormalizedEvent | null {
-    if (!evt.type || !evt.callId) {
-      return null;
-    }
-
-    const base = {
-      id: evt.id ?? crypto.randomUUID(),
-      callId: evt.callId,
-      providerCallId: evt.providerCallId,
-      timestamp: evt.timestamp ?? Date.now(),
-    };
-
-    switch (evt.type) {
-      case "call.initiated":
-      case "call.ringing":
-      case "call.answered":
-      case "call.active":
-        return { ...base, type: evt.type };
-
-      case "call.speaking": {
-        const payload = evt as Partial<NormalizedEvent & { text?: string }>;
-        return {
-          ...base,
-          type: evt.type,
-          text: payload.text ?? "",
-        };
-      }
-
-      case "call.speech": {
-        const payload = evt as Partial<
-          NormalizedEvent & {
-            transcript?: string;
-            isFinal?: boolean;
-            confidence?: number;
-          }
-        >;
-        return {
-          ...base,
-          type: evt.type,
-          transcript: payload.transcript ?? "",
-          isFinal: payload.isFinal ?? true,
-          confidence: payload.confidence,
-        };
-      }
-
-      case "call.silence": {
-        const payload = evt as Partial<NormalizedEvent & { durationMs?: number }>;
-        return {
-          ...base,
-          type: evt.type,
-          durationMs: payload.durationMs ?? 0,
-        };
-      }
-
-      case "call.dtmf": {
-        const payload = evt as Partial<NormalizedEvent & { digits?: string }>;
-        return {
-          ...base,
-          type: evt.type,
-          digits: payload.digits ?? "",
-        };
-      }
-
-      case "call.ended": {
-        const payload = evt as Partial<NormalizedEvent & { reason?: EndReason }>;
-        return {
-          ...base,
-          type: evt.type,
-          reason: payload.reason ?? "completed",
-        };
-      }
-
-      case "call.error": {
-        const payload = evt as Partial<NormalizedEvent & { error?: string; retryable?: boolean }>;
-        return {
-          ...base,
-          type: evt.type,
-          error: payload.error ?? "unknown error",
-          retryable: payload.retryable,
-        };
-      }
-
-      default:
-        return null;
-    }
-  }
-
-  async initiateCall(input: InitiateCallInput): Promise<InitiateCallResult> {
-    return {
-      providerCallId: `mock-${input.callId}`,
-      status: "initiated",
-    };
-  }
-
-  async hangupCall(_input: HangupCallInput): Promise<void> {
-    // No-op for mock
-  }
-
-  async playTts(_input: PlayTtsInput): Promise<void> {
-    // No-op for mock
-  }
-
-  async sendDtmf(_input: SendDtmfInput): Promise<void> {
-    // No-op for mock
-  }
-
-  async startListening(_input: StartListeningInput): Promise<void> {
-    // No-op for mock
-  }
-
-  async stopListening(_input: StopListeningInput): Promise<void> {
-    // No-op for mock
-  }
-
-  async getCallStatus(input: GetCallStatusInput): Promise<GetCallStatusResult> {
-    const id = normalizeLowercaseStringOrEmpty(input.providerCallId);
-    if (id.includes("stale") || id.includes("ended") || id.includes("completed")) {
-      return { status: "completed", isTerminal: true };
-    }
-    return { status: "in-progress", isTerminal: false };
-  }
-}

package/src/providers/plivo.test.ts

@@ -1,93 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PlivoProvider } from "./plivo.js";
-
-function requireEvent<T>(event: T | undefined, message: string): T {
-  if (!event) {
-    throw new Error(message);
-  }
-  return event;
-}
-
-function requireResponseBody(body: string | undefined): string {
-  if (!body) {
-    throw new Error("Plivo provider did not return a response body");
-  }
-  return body;
-}
-
-describe("PlivoProvider", () => {
-  it("parses answer callback into call.answered and returns keep-alive XML", () => {
-    const provider = new PlivoProvider({
-      authId: "MA000000000000000000",
-      authToken: "test-token",
-    });
-
-    const result = provider.parseWebhookEvent({
-      headers: { host: "example.com" },
-      rawBody:
-        "CallUUID=call-uuid&CallStatus=in-progress&Direction=outbound&From=%2B15550000000&To=%2B15550000001&Event=StartApp",
-      url: "https://example.com/voice/webhook?provider=plivo&flow=answer&callId=internal-call-id",
-      method: "POST",
-      query: { provider: "plivo", flow: "answer", callId: "internal-call-id" },
-    });
-
-    expect(result.events).toHaveLength(1);
-    const event = requireEvent(result.events[0], "expected Plivo answer event");
-    expect(event.type).toBe("call.answered");
-    expect(event.callId).toBe("internal-call-id");
-    expect(event.providerCallId).toBe("call-uuid");
-    const responseBody = requireResponseBody(result.providerResponseBody);
-    expect(responseBody).toContain("<Wait");
-    expect(responseBody).toContain('length="300"');
-  });
-
-  it("uses verified request key when provided", () => {
-    const provider = new PlivoProvider({
-      authId: "MA000000000000000000",
-      authToken: "test-token",
-    });
-
-    const result = provider.parseWebhookEvent(
-      {
-        headers: { host: "example.com", "x-plivo-signature-v3-nonce": "nonce-1" },
-        rawBody:
-          "CallUUID=call-uuid&CallStatus=in-progress&Direction=outbound&From=%2B15550000000&To=%2B15550000001&Event=StartApp",
-        url: "https://example.com/voice/webhook?provider=plivo&flow=answer&callId=internal-call-id",
-        method: "POST",
-        query: { provider: "plivo", flow: "answer", callId: "internal-call-id" },
-      },
-      { verifiedRequestKey: "plivo:v3:verified" },
-    );
-
-    expect(result.events).toHaveLength(1);
-    expect(requireEvent(result.events[0], "expected verified Plivo event").dedupeKey).toBe(
-      "plivo:v3:verified",
-    );
-  });
-
-  it("pins stored callback bases to publicUrl instead of request Host", () => {
-    const provider = new PlivoProvider(
-      {
-        authId: "MA000000000000000000",
-        authToken: "test-token",
-      },
-      {
-        publicUrl: "https://voice.kodelyth.com/voice/webhook?provider=plivo",
-      },
-    );
-
-    provider.parseWebhookEvent({
-      headers: { host: "attacker.example" },
-      rawBody:
-        "CallUUID=call-uuid&CallStatus=in-progress&Direction=outbound&From=%2B15550000000&To=%2B15550000001&Event=StartApp",
-      url: "https://attacker.example/voice/webhook?provider=plivo&flow=answer&callId=internal-call-id",
-      method: "POST",
-      query: { provider: "plivo", flow: "answer", callId: "internal-call-id" },
-    });
-
-    const callbackMap = (provider as unknown as { callUuidToWebhookUrl: Map<string, string> })
-      .callUuidToWebhookUrl;
-
-    expect(callbackMap.get("call-uuid")).toBe("https://voice.kodelyth.com/voice/webhook");
-  });
-});