@kodelyth/voice-call 2026.5.39 → 2026.5.42

package/src/manager.inbound-allowlist.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import { FakeProvider, createManagerHarness } from "./manager.test-harness.js";
+
+describe("CallManager inbound allowlist", () => {
+  it("rejects inbound calls with missing caller ID when allowlist enabled", async () => {
+    const { manager, provider } = await createManagerHarness({
+      inboundPolicy: "allowlist",
+      allowFrom: ["+15550001234"],
+    });
+
+    manager.processEvent({
+      id: "evt-allowlist-missing",
+      type: "call.initiated",
+      callId: "call-missing",
+      providerCallId: "provider-missing",
+      timestamp: Date.now(),
+      direction: "inbound",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-missing")).toBeUndefined();
+    expect(provider.hangupCalls).toHaveLength(1);
+    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-missing");
+  });
+
+  it("rejects inbound calls with anonymous caller ID when allowlist enabled", async () => {
+    const { manager, provider } = await createManagerHarness({
+      inboundPolicy: "allowlist",
+      allowFrom: ["+15550001234"],
+    });
+
+    manager.processEvent({
+      id: "evt-allowlist-anon",
+      type: "call.initiated",
+      callId: "call-anon",
+      providerCallId: "provider-anon",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "anonymous",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-anon")).toBeUndefined();
+    expect(provider.hangupCalls).toHaveLength(1);
+    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-anon");
+  });
+
+  it("rejects inbound calls that only match allowlist suffixes", async () => {
+    const { manager, provider } = await createManagerHarness({
+      inboundPolicy: "allowlist",
+      allowFrom: ["+15550001234"],
+    });
+
+    manager.processEvent({
+      id: "evt-allowlist-suffix",
+      type: "call.initiated",
+      callId: "call-suffix",
+      providerCallId: "provider-suffix",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+99915550001234",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-suffix")).toBeUndefined();
+    expect(provider.hangupCalls).toHaveLength(1);
+    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-suffix");
+  });
+
+  it("rejects duplicate inbound events with a single hangup call", async () => {
+    const { manager, provider } = await createManagerHarness({
+      inboundPolicy: "disabled",
+    });
+
+    manager.processEvent({
+      id: "evt-reject-init",
+      type: "call.initiated",
+      callId: "provider-dup",
+      providerCallId: "provider-dup",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15552222222",
+      to: "+15550000000",
+    });
+
+    manager.processEvent({
+      id: "evt-reject-ring",
+      type: "call.ringing",
+      callId: "provider-dup",
+      providerCallId: "provider-dup",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15552222222",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-dup")).toBeUndefined();
+    expect(provider.hangupCalls).toHaveLength(1);
+    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-dup");
+  });
+
+  it("retries rejected inbound hangup after a transient provider failure", async () => {
+    class FlakyHangupProvider extends FakeProvider {
+      hangupFailuresRemaining = 1;
+
+      override async hangupCall(input: Parameters<FakeProvider["hangupCall"]>[0]): Promise<void> {
+        this.hangupCalls.push(input);
+        if (this.hangupFailuresRemaining > 0) {
+          this.hangupFailuresRemaining -= 1;
+          throw new Error("provider down");
+        }
+      }
+    }
+
+    const provider = new FlakyHangupProvider();
+    const { manager } = await createManagerHarness(
+      {
+        inboundPolicy: "disabled",
+      },
+      provider,
+    );
+
+    manager.processEvent({
+      id: "evt-reject-fail-init",
+      type: "call.initiated",
+      callId: "provider-flaky",
+      providerCallId: "provider-flaky",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15553333333",
+      to: "+15550000000",
+    });
+    await Promise.resolve();
+
+    manager.processEvent({
+      id: "evt-reject-fail-ring",
+      type: "call.ringing",
+      callId: "provider-flaky",
+      providerCallId: "provider-flaky",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15553333333",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-flaky")).toBeUndefined();
+    expect(provider.hangupCalls).toHaveLength(2);
+    expect(provider.hangupCalls.map((call) => call.providerCallId)).toEqual([
+      "provider-flaky",
+      "provider-flaky",
+    ]);
+  });
+
+  it("accepts inbound calls that exactly match the allowlist", async () => {
+    const { manager } = await createManagerHarness({
+      inboundPolicy: "allowlist",
+      allowFrom: ["+15550001234"],
+    });
+
+    manager.processEvent({
+      id: "evt-allowlist-exact",
+      type: "call.initiated",
+      callId: "call-exact",
+      providerCallId: "provider-exact",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15550001234",
+      to: "+15550000000",
+    });
+
+    const call = manager.getCallByProviderCallId("provider-exact");
+    if (!call) {
+      throw new Error("expected exact allowlist match to keep the inbound call");
+    }
+    expect(call.providerCallId).toBe("provider-exact");
+    expect(call.direction).toBe("inbound");
+    expect(call.from).toBe("+15550001234");
+    expect(call.to).toBe("+15550000000");
+    expect(call.callId).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    );
+  });
+});

package/src/manager.notify.test.ts

@@ -0,0 +1,390 @@
+import { describe, expect, it, vi } from "vitest";
+import { createManagerHarness, FakeProvider } from "./manager.test-harness.js";
+
+class FailFirstPlayTtsProvider extends FakeProvider {
+  private failed = false;
+
+  override async playTts(input: Parameters<FakeProvider["playTts"]>[0]): Promise<void> {
+    this.playTtsCalls.push(input);
+    if (!this.failed) {
+      this.failed = true;
+      throw new Error("synthetic tts failure");
+    }
+  }
+}
+
+class DelayedPlayTtsProvider extends FakeProvider {
+  private releasePlayTts: (() => void) | null = null;
+  private resolvePlayTtsStarted: (() => void) | null = null;
+  readonly playTtsStarted = vi.fn();
+  readonly playTtsStartedPromise = new Promise<void>((resolve) => {
+    this.resolvePlayTtsStarted = resolve;
+  });
+
+  override async playTts(input: Parameters<FakeProvider["playTts"]>[0]): Promise<void> {
+    this.playTtsCalls.push(input);
+    this.playTtsStarted();
+    this.resolvePlayTtsStarted?.();
+    this.resolvePlayTtsStarted = null;
+    await new Promise<void>((resolve) => {
+      this.releasePlayTts = resolve;
+    });
+  }
+
+  releaseCurrentPlayback(): void {
+    this.releasePlayTts?.();
+    this.releasePlayTts = null;
+  }
+}
+
+class FailStartListeningProvider extends FakeProvider {
+  override async startListening(
+    input: Parameters<FakeProvider["startListening"]>[0],
+  ): Promise<void> {
+    this.startListeningCalls.push(input);
+    throw new Error("synthetic start listening failure");
+  }
+}
+
+function requireCall(
+  manager: Awaited<ReturnType<typeof createManagerHarness>>["manager"],
+  callId: string,
+) {
+  const call = manager.getCall(callId);
+  if (!call) {
+    throw new Error(`expected active call ${callId}`);
+  }
+  return call;
+}
+
+function requireMappedCall(
+  manager: Awaited<ReturnType<typeof createManagerHarness>>["manager"],
+  providerCallId: string,
+) {
+  const call = manager.getCallByProviderCallId(providerCallId);
+  if (!call) {
+    throw new Error(`expected mapped provider call ${providerCallId}`);
+  }
+  return call;
+}
+
+function requireFirstPlayTtsCall(provider: FakeProvider) {
+  const call = provider.playTtsCalls.at(0);
+  if (!call) {
+    throw new Error("expected provider.playTts to be called once");
+  }
+  return call;
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`expected ${label} to be a record`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireSingleStartListeningCall(provider: FakeProvider) {
+  expect(provider.startListeningCalls).toHaveLength(1);
+  return requireRecord(provider.startListeningCalls.at(0), "start listening call");
+}
+
+function requireFirstMockCall(calls: readonly unknown[][], label: string): unknown[] {
+  const call = calls.at(0);
+  if (!call) {
+    throw new Error(`expected ${label} call`);
+  }
+  return call;
+}
+
+type HarnessManager = Awaited<ReturnType<typeof createManagerHarness>>["manager"];
+
+async function waitForPlaybackDispatch() {
+  await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+async function initiateCallWithMessage(
+  manager: HarnessManager,
+  to: string,
+  message: string,
+  mode: "notify" | "conversation",
+) {
+  const { callId, success } = await manager.initiateCall(to, undefined, { message, mode });
+  expect(success).toBe(true);
+  return callId;
+}
+
+async function answerCall(
+  manager: HarnessManager,
+  callId: string,
+  eventId: string,
+  providerCallId = "call-uuid",
+) {
+  manager.processEvent({
+    id: eventId,
+    type: "call.answered",
+    callId,
+    providerCallId,
+    timestamp: Date.now(),
+  });
+  await waitForPlaybackDispatch();
+}
+
+function expectFirstPlayTtsText(provider: FakeProvider, text: string) {
+  expect(provider.playTtsCalls).toHaveLength(1);
+  expect(requireFirstPlayTtsCall(provider).text).toBe(text);
+}
+
+describe("CallManager notify and mapping", () => {
+  it("upgrades providerCallId mapping when provider ID changes", async () => {
+    const { manager } = await createManagerHarness();
+
+    const { callId, success, error } = await manager.initiateCall("+15550000001");
+    expect(success).toBe(true);
+    expect(error).toBeUndefined();
+
+    expect(requireCall(manager, callId).providerCallId).toBe("request-uuid");
+    expect(requireMappedCall(manager, "request-uuid").callId).toBe(callId);
+
+    manager.processEvent({
+      id: "evt-1",
+      type: "call.answered",
+      callId,
+      providerCallId: "call-uuid",
+      timestamp: Date.now(),
+    });
+
+    expect(requireCall(manager, callId).providerCallId).toBe("call-uuid");
+    expect(requireMappedCall(manager, "call-uuid").callId).toBe(callId);
+    expect(manager.getCallByProviderCallId("request-uuid")).toBeUndefined();
+  });
+
+  it.each(["plivo", "twilio"] as const)(
+    "speaks initial message on answered for notify mode (%s)",
+    async (providerName) => {
+      const { manager, provider } = await createManagerHarness({}, new FakeProvider(providerName));
+
+      const callId = await initiateCallWithMessage(
+        manager,
+        "+15550000002",
+        "Hello there",
+        "notify",
+      );
+      await answerCall(manager, callId, `evt-2-${providerName}`);
+
+      expectFirstPlayTtsText(provider, "Hello there");
+    },
+  );
+
+  it("speaks initial message on answered for conversation mode with non-stream provider", async () => {
+    const { manager, provider } = await createManagerHarness({}, new FakeProvider("plivo"));
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000003",
+      "Hello from conversation",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-plivo");
+
+    expectFirstPlayTtsText(provider, "Hello from conversation");
+  });
+
+  it("speaks initial message on answered for conversation mode when Twilio streaming is disabled", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { streaming: { enabled: false } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000004",
+      "Twilio non-stream",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-twilio-no-stream");
+
+    expectFirstPlayTtsText(provider, "Twilio non-stream");
+  });
+
+  it("lets realtime conversations own the initial greeting instead of posting legacy TwiML", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { realtime: { enabled: true, provider: "openai" } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000010",
+      "Tell Nana dinner is at 6pm.",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-twilio-realtime");
+
+    expect(provider.playTtsCalls).toHaveLength(0);
+    const metadata = requireRecord(requireCall(manager, callId).metadata, "call metadata");
+    expect(metadata.initialMessage).toBe("Tell Nana dinner is at 6pm.");
+  });
+
+  it("still speaks initial message in notify mode when realtime is enabled", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { realtime: { enabled: true, provider: "openai" } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(manager, "+15550000011", "Notify text", "notify");
+    await answerCall(manager, callId, "evt-notify-twilio-realtime");
+
+    expectFirstPlayTtsText(provider, "Notify text");
+  });
+
+  it("waits for stream connect in conversation mode when Twilio streaming is enabled", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { streaming: { enabled: true } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000005",
+      "Twilio stream",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-twilio-stream");
+
+    expect(provider.playTtsCalls).toHaveLength(0);
+  });
+
+  it("speaks on answered when Twilio streaming is enabled but stream-connect path is unavailable", async () => {
+    const twilioProvider = new FakeProvider("twilio");
+    twilioProvider.twilioStreamConnectEnabled = false;
+    const { manager, provider } = await createManagerHarness(
+      { streaming: { enabled: true } },
+      twilioProvider,
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000009",
+      "Twilio stream unavailable",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-twilio-stream-unavailable");
+
+    expectFirstPlayTtsText(provider, "Twilio stream unavailable");
+  });
+
+  it("starts listening after the initial greeting for Telnyx conversation calls", async () => {
+    const { manager, provider } = await createManagerHarness({}, new FakeProvider("telnyx"));
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000012",
+      "Telnyx hello",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-telnyx");
+
+    expectFirstPlayTtsText(provider, "Telnyx hello");
+    const startListeningCall = requireSingleStartListeningCall(provider);
+    expect(startListeningCall.callId).toBe(callId);
+    expect(startListeningCall.providerCallId).toBe("call-uuid");
+    expect(requireCall(manager, callId).state).toBe("listening");
+  });
+
+  it("logs fire-and-forget initial-message failures instead of leaking unhandled rejections", async () => {
+    const provider = new FailStartListeningProvider("twilio");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const { manager } = await createManagerHarness({ streaming: { enabled: false } }, provider);
+
+      const callId = await initiateCallWithMessage(
+        manager,
+        "+15550000013",
+        "Twilio hello",
+        "conversation",
+      );
+      await answerCall(manager, callId, "evt-initial-message-start-listening-fails");
+
+      expectFirstPlayTtsText(provider, "Twilio hello");
+      const startListeningCall = requireSingleStartListeningCall(provider);
+      expect(startListeningCall.callId).toBe(callId);
+      expect(startListeningCall.providerCallId).toBe("call-uuid");
+      expect(warn).toHaveBeenCalledOnce();
+      expect(String(requireFirstMockCall(warn.mock.calls, "console warn")[0])).toContain(
+        `[voice-call] Failed to speak initial message for call ${callId}: synthetic start listening failure`,
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("preserves initialMessage after a failed first playback and retries on next trigger", async () => {
+    const provider = new FailFirstPlayTtsProvider("plivo");
+    const { manager } = await createManagerHarness({}, provider);
+
+    const callId = await initiateCallWithMessage(manager, "+15550000006", "Retry me", "notify");
+    await answerCall(manager, callId, "evt-retry-1");
+
+    const afterFailure = requireCall(manager, callId);
+    expect(provider.playTtsCalls).toHaveLength(1);
+    const metadata = requireRecord(afterFailure.metadata, "call metadata after failed playback");
+    expect(metadata.initialMessage).toBe("Retry me");
+    expect(afterFailure.state).toBe("listening");
+
+    await answerCall(manager, callId, "evt-retry-2");
+
+    const afterSuccess = requireCall(manager, callId);
+    expect(provider.playTtsCalls).toHaveLength(2);
+    expect(afterSuccess.metadata).not.toHaveProperty("initialMessage");
+  });
+
+  it("speaks initial message only once on repeated stream-connect triggers", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { streaming: { enabled: true } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000007",
+      "Stream hello",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-stream-answered");
+    expect(provider.playTtsCalls).toHaveLength(0);
+
+    await manager.speakInitialMessage("call-uuid");
+    await manager.speakInitialMessage("call-uuid");
+
+    expectFirstPlayTtsText(provider, "Stream hello");
+  });
+
+  it("prevents concurrent initial-message replays while first playback is in flight", async () => {
+    const provider = new DelayedPlayTtsProvider("twilio");
+    const { manager } = await createManagerHarness({ streaming: { enabled: true } }, provider);
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000008",
+      "In-flight hello",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-stream-answered-concurrent");
+    expect(provider.playTtsCalls).toHaveLength(0);
+
+    const first = manager.speakInitialMessage("call-uuid");
+    await provider.playTtsStartedPromise;
+    expect(provider.playTtsStarted).toHaveBeenCalledTimes(1);
+
+    const second = manager.speakInitialMessage("call-uuid");
+    await waitForPlaybackDispatch();
+    expect(provider.playTtsCalls).toHaveLength(1);
+
+    provider.releaseCurrentPlayback();
+    await Promise.all([first, second]);
+
+    const call = requireCall(manager, callId);
+    expect(call.metadata).not.toHaveProperty("initialMessage");
+    expectFirstPlayTtsText(provider, "In-flight hello");
+  });
+});