@kodelyth/voice-call 2026.5.39 → 2026.5.42

package/src/webhook/stale-call-reaper.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { startStaleCallReaper } from "./stale-call-reaper.js";
+
+describe("startStaleCallReaper", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-03-22T12:00:00.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("returns null when disabled or non-positive", () => {
+    const manager = {
+      getActiveCalls: vi.fn(() => []),
+      endCall: vi.fn(),
+    };
+
+    expect(startStaleCallReaper({ manager: manager as never })).toBeNull();
+    expect(
+      startStaleCallReaper({ manager: manager as never, staleCallReaperSeconds: 0 }),
+    ).toBeNull();
+  });
+
+  it("reaps stale calls and ignores fresh ones", async () => {
+    const endCall = vi.fn(async () => {});
+    const manager = {
+      getActiveCalls: vi.fn(() => [
+        {
+          callId: "call-stale",
+          startedAt: Date.now() - 61_000,
+          state: "active",
+        },
+        {
+          callId: "call-fresh",
+          startedAt: Date.now() - 10_000,
+          state: "active",
+        },
+      ]),
+      endCall,
+    };
+
+    const stop = startStaleCallReaper({
+      manager: manager as never,
+      staleCallReaperSeconds: 60,
+    });
+
+    await vi.advanceTimersByTimeAsync(30_000);
+
+    expect(endCall).toHaveBeenCalledTimes(1);
+    expect(endCall).toHaveBeenCalledWith("call-stale");
+
+    stop?.();
+  });
+
+  it("logs and swallows endCall failures", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const endCallError = new Error("network");
+    const manager = {
+      getActiveCalls: vi.fn(() => [
+        {
+          callId: "call-stale",
+          startedAt: Date.now() - 61_000,
+          state: "active",
+        },
+      ]),
+      endCall: vi.fn(async () => {
+        throw endCallError;
+      }),
+    };
+
+    const stop = startStaleCallReaper({
+      manager: manager as never,
+      staleCallReaperSeconds: 60,
+    });
+
+    await vi.advanceTimersByTimeAsync(30_000);
+    await Promise.resolve();
+
+    expect(warn).toHaveBeenCalledWith(
+      "[voice-call] Reaper failed to end call call-stale:",
+      endCallError,
+    );
+
+    stop?.();
+  });
+});

package/src/webhook/stale-call-reaper.ts

@@ -0,0 +1,38 @@
+import type { CallManager } from "../manager.js";
+import { TerminalStates } from "../types.js";
+
+const CHECK_INTERVAL_MS = 30_000;
+
+export function startStaleCallReaper(params: {
+  manager: CallManager;
+  staleCallReaperSeconds?: number;
+}): (() => void) | null {
+  const maxAgeSeconds = params.staleCallReaperSeconds;
+  if (!maxAgeSeconds || maxAgeSeconds <= 0) {
+    return null;
+  }
+
+  const maxAgeMs = maxAgeSeconds * 1000;
+  const interval = setInterval(() => {
+    const now = Date.now();
+    for (const call of params.manager.getActiveCalls()) {
+      if (call.answeredAt || TerminalStates.has(call.state)) {
+        continue;
+      }
+
+      const age = now - call.startedAt;
+      if (age > maxAgeMs) {
+        console.log(
+          `[voice-call] Reaping stale call ${call.callId} (age: ${Math.round(age / 1000)}s, state: ${call.state})`,
+        );
+        void params.manager.endCall(call.callId).catch((err) => {
+          console.warn(`[voice-call] Reaper failed to end call ${call.callId}:`, err);
+        });
+      }
+    }
+  }, CHECK_INTERVAL_MS);
+
+  return () => {
+    clearInterval(interval);
+  };
+}

package/src/webhook/stream-frame-adapter.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it } from "vitest";
+import { TelnyxStreamFrameAdapter, TwilioStreamFrameAdapter } from "./stream-frame-adapter.js";
+
+describe("TwilioStreamFrameAdapter", () => {
+  it("parses Twilio start, media, mark, stop, and ignores junk", () => {
+    const adapter = new TwilioStreamFrameAdapter();
+
+    expect(
+      adapter.parseInbound(
+        JSON.stringify({
+          event: "start",
+          start: { streamSid: "MZ-stream", callSid: "CA-call" },
+        }),
+      ),
+    ).toEqual({ kind: "start", streamId: "MZ-stream", providerCallId: "CA-call" });
+
+    expect(
+      adapter.parseInbound(
+        JSON.stringify({
+          event: "media",
+          media: { payload: "AAA=", timestamp: "20", track: "inbound" },
+        }),
+      ),
+    ).toEqual({
+      kind: "media",
+      payloadBase64: "AAA=",
+      timestampMs: 20,
+      track: "inbound",
+    });
+
+    expect(
+      adapter.parseInbound(JSON.stringify({ event: "mark", mark: { name: "audio-1" } })),
+    ).toEqual({ kind: "mark", name: "audio-1" });
+
+    expect(adapter.parseInbound(JSON.stringify({ event: "stop" }))).toEqual({ kind: "stop" });
+
+    expect(adapter.parseInbound("not json")).toEqual({ kind: "ignored" });
+    expect(adapter.parseInbound(JSON.stringify({ event: "media" }))).toEqual({ kind: "ignored" });
+    expect(
+      adapter.parseInbound(JSON.stringify({ event: "start", start: { streamSid: "MZ-only" } })),
+    ).toEqual({ kind: "ignored" });
+    expect(
+      adapter.parseInbound(JSON.stringify({ event: "media", media: { payload: "AAA@@@" } })),
+    ).toEqual({ kind: "ignored" });
+  });
+
+  it("serializes outbound frames with the streamSid captured at start", () => {
+    const adapter = new TwilioStreamFrameAdapter();
+    adapter.parseInbound(
+      JSON.stringify({
+        event: "start",
+        start: { streamSid: "MZ-stream", callSid: "CA-call" },
+      }),
+    );
+
+    expect(JSON.parse(adapter.serializeMedia("payload-b64"))).toEqual({
+      event: "media",
+      streamSid: "MZ-stream",
+      media: { payload: "payload-b64" },
+    });
+    expect(JSON.parse(adapter.serializeClear())).toEqual({
+      event: "clear",
+      streamSid: "MZ-stream",
+    });
+    expect(JSON.parse(adapter.serializeMark("audio-1"))).toEqual({
+      event: "mark",
+      streamSid: "MZ-stream",
+      mark: { name: "audio-1" },
+    });
+  });
+});
+
+describe("TelnyxStreamFrameAdapter", () => {
+  it("parses Telnyx start with top-level stream_id and start.call_control_id", () => {
+    const adapter = new TelnyxStreamFrameAdapter();
+
+    expect(
+      adapter.parseInbound(
+        JSON.stringify({
+          event: "start",
+          sequence_number: "1",
+          stream_id: "telnyx-stream-7",
+          start: {
+            call_control_id: "v3:carrier-call-id",
+            call_session_id: "session-1",
+            media_format: { encoding: "PCMU", sample_rate: 8000, channels: 1 },
+          },
+        }),
+      ),
+    ).toEqual({
+      kind: "start",
+      streamId: "telnyx-stream-7",
+      providerCallId: "v3:carrier-call-id",
+    });
+  });
+
+  it("ignores Telnyx start frames without stream_id or call_control_id", () => {
+    const adapter = new TelnyxStreamFrameAdapter();
+
+    expect(adapter.parseInbound(JSON.stringify({ event: "start", start: {} }))).toEqual({
+      kind: "ignored",
+    });
+    expect(
+      adapter.parseInbound(
+        JSON.stringify({
+          event: "start",
+          stream_id: "telnyx-stream-7",
+          start: {},
+        }),
+      ),
+    ).toEqual({ kind: "ignored" });
+  });
+
+  it("parses media, mark, and stop with no streamSid", () => {
+    const adapter = new TelnyxStreamFrameAdapter();
+
+    expect(
+      adapter.parseInbound(
+        JSON.stringify({
+          event: "media",
+          stream_id: "telnyx-stream-7",
+          media: { payload: "AAA=", timestamp: 40, track: "inbound_track" },
+        }),
+      ),
+    ).toEqual({
+      kind: "media",
+      payloadBase64: "AAA=",
+      timestampMs: 40,
+      track: "inbound_track",
+    });
+
+    expect(
+      adapter.parseInbound(JSON.stringify({ event: "mark", mark: { name: "audio-1" } })),
+    ).toEqual({ kind: "mark", name: "audio-1" });
+
+    expect(adapter.parseInbound(JSON.stringify({ event: "stop" }))).toEqual({ kind: "stop" });
+  });
+
+  it("surfaces Telnyx WS error frames so failures don't get swallowed", () => {
+    const adapter = new TelnyxStreamFrameAdapter();
+
+    expect(
+      adapter.parseInbound(
+        JSON.stringify({
+          event: "error",
+          stream_id: "telnyx-stream-7",
+          payload: {
+            code: 100002,
+            title: "WebSocket error",
+            detail: "Unable to decode payload",
+          },
+        }),
+      ),
+    ).toEqual({
+      kind: "error",
+      code: "100002",
+      title: "WebSocket error",
+      detail: "Unable to decode payload",
+    });
+  });
+
+  it("serializes outbound frames without streamSid", () => {
+    const adapter = new TelnyxStreamFrameAdapter();
+
+    expect(JSON.parse(adapter.serializeMedia("payload-b64"))).toEqual({
+      event: "media",
+      media: { payload: "payload-b64" },
+    });
+    expect(JSON.parse(adapter.serializeClear())).toEqual({ event: "clear" });
+    expect(JSON.parse(adapter.serializeMark("audio-1"))).toEqual({
+      event: "mark",
+      mark: { name: "audio-1" },
+    });
+  });
+
+  it("ignores junk and unknown events", () => {
+    const adapter = new TelnyxStreamFrameAdapter();
+    expect(adapter.parseInbound("not json")).toEqual({ kind: "ignored" });
+    expect(adapter.parseInbound(JSON.stringify({ event: "media" }))).toEqual({ kind: "ignored" });
+    expect(
+      adapter.parseInbound(JSON.stringify({ event: "media", media: { payload: "AAA@@@" } })),
+    ).toEqual({ kind: "ignored" });
+    expect(adapter.parseInbound(JSON.stringify({ event: "something-else" }))).toEqual({
+      kind: "ignored",
+    });
+  });
+});

package/src/webhook/stream-frame-adapter.ts

@@ -0,0 +1,219 @@
+export type StreamFrame =
+  | { kind: "start"; streamId: string; providerCallId: string }
+  | {
+      kind: "media";
+      payloadBase64: string;
+      timestampMs?: number;
+      track?: string;
+    }
+  | { kind: "mark"; name?: string }
+  | { kind: "stop" }
+  | { kind: "error"; code?: string; title?: string; detail?: string }
+  | { kind: "ignored" };
+
+export interface StreamFrameAdapter {
+  readonly providerName: "twilio" | "telnyx";
+  parseInbound(rawMessage: string): StreamFrame;
+  serializeMedia(payloadBase64: string): string;
+  serializeClear(): string;
+  serializeMark(name: string): string;
+}
+
+function parseTimestampMs(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+function tryParseJson(rawMessage: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(rawMessage) as unknown;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+function normalizeBase64ForCompare(value: string): string {
+  return value.replace(/=+$/u, "").replace(/-/gu, "+").replace(/_/gu, "/");
+}
+
+function isValidBase64Payload(value: string): boolean {
+  const buffer = Buffer.from(value, "base64");
+  return normalizeBase64ForCompare(buffer.toString("base64")) === normalizeBase64ForCompare(value);
+}
+
+export class TwilioStreamFrameAdapter implements StreamFrameAdapter {
+  readonly providerName = "twilio" as const;
+  private streamSid = "";
+
+  parseInbound(rawMessage: string): StreamFrame {
+    const msg = tryParseJson(rawMessage);
+    if (!msg) {
+      return { kind: "ignored" };
+    }
+    const event = msg.event;
+    if (event === "start") {
+      const startData =
+        typeof msg.start === "object" && msg.start !== null
+          ? (msg.start as Record<string, unknown>)
+          : undefined;
+      const streamSid = typeof startData?.streamSid === "string" ? startData.streamSid : "";
+      const callSid = typeof startData?.callSid === "string" ? startData.callSid : "";
+      if (!streamSid || !callSid) {
+        return { kind: "ignored" };
+      }
+      this.streamSid = streamSid;
+      return { kind: "start", streamId: streamSid, providerCallId: callSid };
+    }
+    if (event === "media") {
+      const mediaData =
+        typeof msg.media === "object" && msg.media !== null
+          ? (msg.media as Record<string, unknown>)
+          : undefined;
+      const payload = typeof mediaData?.payload === "string" ? mediaData.payload : undefined;
+      if (!payload || !isValidBase64Payload(payload)) {
+        return { kind: "ignored" };
+      }
+      return {
+        kind: "media",
+        payloadBase64: payload,
+        timestampMs: parseTimestampMs(mediaData?.timestamp),
+        track: typeof mediaData?.track === "string" ? mediaData.track : undefined,
+      };
+    }
+    if (event === "mark") {
+      const markData =
+        typeof msg.mark === "object" && msg.mark !== null
+          ? (msg.mark as Record<string, unknown>)
+          : undefined;
+      const name = typeof markData?.name === "string" ? markData.name : undefined;
+      return { kind: "mark", name };
+    }
+    if (event === "stop") {
+      return { kind: "stop" };
+    }
+    return { kind: "ignored" };
+  }
+
+  serializeMedia(payloadBase64: string): string {
+    return JSON.stringify({
+      event: "media",
+      streamSid: this.streamSid,
+      media: { payload: payloadBase64 },
+    });
+  }
+
+  serializeClear(): string {
+    return JSON.stringify({ event: "clear", streamSid: this.streamSid });
+  }
+
+  serializeMark(name: string): string {
+    return JSON.stringify({
+      event: "mark",
+      streamSid: this.streamSid,
+      mark: { name },
+    });
+  }
+}
+
+export class TelnyxStreamFrameAdapter implements StreamFrameAdapter {
+  readonly providerName = "telnyx" as const;
+
+  parseInbound(rawMessage: string): StreamFrame {
+    const msg = tryParseJson(rawMessage);
+    if (!msg) {
+      return { kind: "ignored" };
+    }
+    const event = msg.event;
+    const topLevelStreamId =
+      typeof msg.stream_id === "string" && msg.stream_id ? msg.stream_id : undefined;
+    if (event === "start") {
+      const startData =
+        typeof msg.start === "object" && msg.start !== null
+          ? (msg.start as Record<string, unknown>)
+          : undefined;
+      const providerCallId =
+        typeof startData?.call_control_id === "string" && startData.call_control_id
+          ? startData.call_control_id
+          : undefined;
+      if (!topLevelStreamId || !providerCallId) {
+        return { kind: "ignored" };
+      }
+      return {
+        kind: "start",
+        streamId: topLevelStreamId,
+        providerCallId,
+      };
+    }
+    if (event === "media") {
+      const mediaData =
+        typeof msg.media === "object" && msg.media !== null
+          ? (msg.media as Record<string, unknown>)
+          : undefined;
+      const payload = typeof mediaData?.payload === "string" ? mediaData.payload : undefined;
+      if (!payload || !isValidBase64Payload(payload)) {
+        return { kind: "ignored" };
+      }
+      return {
+        kind: "media",
+        payloadBase64: payload,
+        timestampMs: parseTimestampMs(mediaData?.timestamp),
+        track: typeof mediaData?.track === "string" ? mediaData.track : undefined,
+      };
+    }
+    if (event === "mark") {
+      const markData =
+        typeof msg.mark === "object" && msg.mark !== null
+          ? (msg.mark as Record<string, unknown>)
+          : undefined;
+      const name = typeof markData?.name === "string" ? markData.name : undefined;
+      return { kind: "mark", name };
+    }
+    if (event === "stop") {
+      return { kind: "stop" };
+    }
+    if (event === "error") {
+      const errorData =
+        typeof msg.payload === "object" && msg.payload !== null
+          ? (msg.payload as Record<string, unknown>)
+          : undefined;
+      return {
+        kind: "error",
+        code:
+          typeof errorData?.code === "string" || typeof errorData?.code === "number"
+            ? String(errorData.code)
+            : undefined,
+        title: typeof errorData?.title === "string" ? errorData.title : undefined,
+        detail: typeof errorData?.detail === "string" ? errorData.detail : undefined,
+      };
+    }
+    return { kind: "ignored" };
+  }
+
+  serializeMedia(payloadBase64: string): string {
+    return JSON.stringify({
+      event: "media",
+      media: { payload: payloadBase64 },
+    });
+  }
+
+  serializeClear(): string {
+    return JSON.stringify({ event: "clear" });
+  }
+
+  serializeMark(name: string): string {
+    return JSON.stringify({
+      event: "mark",
+      mark: { name },
+    });
+  }
+}