@kodelyth/voice-call 2026.5.39 → 2026.5.42

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

@@ -0,0 +1,84 @@
+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");
+  });
+});

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

@@ -0,0 +1,87 @@
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import type { WebhookContext } from "../../types.js";
+
+type TwimlRequestView = {
+  callStatus: string | null;
+  direction: string | null;
+  isStatusCallback: boolean;
+  callSid?: string;
+  callIdFromQuery?: string;
+};
+
+type TwimlPolicyInput = TwimlRequestView & {
+  hasStoredTwiml: boolean;
+  isNotifyCall: boolean;
+  hasActiveStreams: boolean;
+  canStream: boolean;
+};
+
+type TwimlDecision =
+  | {
+      kind: "empty" | "pause" | "queue";
+      consumeStoredTwimlCallId?: string;
+      activateStreamCallSid?: string;
+    }
+  | {
+      kind: "stored";
+      consumeStoredTwimlCallId: string;
+      activateStreamCallSid?: string;
+    }
+  | {
+      kind: "stream";
+      consumeStoredTwimlCallId?: string;
+      activateStreamCallSid?: string;
+    };
+
+function isOutboundDirection(direction: string | null): boolean {
+  return direction?.startsWith("outbound") ?? false;
+}
+
+export function readTwimlRequestView(ctx: WebhookContext): TwimlRequestView {
+  const params = new URLSearchParams(ctx.rawBody);
+  const type = normalizeOptionalString(ctx.query?.type);
+  const callIdFromQuery = normalizeOptionalString(ctx.query?.callId);
+
+  return {
+    callStatus: params.get("CallStatus"),
+    direction: params.get("Direction"),
+    isStatusCallback: type === "status",
+    callSid: params.get("CallSid") || undefined,
+    callIdFromQuery,
+  };
+}
+
+export function decideTwimlResponse(input: TwimlPolicyInput): TwimlDecision {
+  if (input.callIdFromQuery && !input.isStatusCallback) {
+    if (input.hasStoredTwiml) {
+      return { kind: "stored", consumeStoredTwimlCallId: input.callIdFromQuery };
+    }
+    if (input.isNotifyCall) {
+      return { kind: "empty" };
+    }
+
+    if (isOutboundDirection(input.direction)) {
+      return input.canStream ? { kind: "stream" } : { kind: "pause" };
+    }
+  }
+
+  if (input.isStatusCallback) {
+    return { kind: "empty" };
+  }
+
+  if (input.direction === "inbound") {
+    if (input.hasActiveStreams) {
+      return { kind: "queue" };
+    }
+    if (input.canStream && input.callSid) {
+      return { kind: "stream", activateStreamCallSid: input.callSid };
+    }
+    return { kind: "pause" };
+  }
+
+  if (input.callStatus !== "in-progress") {
+    return { kind: "empty" };
+  }
+
+  return input.canStream ? { kind: "stream" } : { kind: "pause" };
+}

package/src/providers/twilio/webhook.ts

@@ -0,0 +1,34 @@
+import type { WebhookContext, WebhookVerificationResult } from "../../types.js";
+import { verifyTwilioWebhook } from "../../webhook-security.js";
+import type { TwilioProviderOptions } from "../twilio.types.js";
+
+export function verifyTwilioProviderWebhook(params: {
+  ctx: WebhookContext;
+  authToken: string;
+  currentPublicUrl?: string | null;
+  options: TwilioProviderOptions;
+}): WebhookVerificationResult {
+  const result = verifyTwilioWebhook(params.ctx, params.authToken, {
+    publicUrl: params.currentPublicUrl || undefined,
+    allowNgrokFreeTierLoopbackBypass: params.options.allowNgrokFreeTierLoopbackBypass ?? false,
+    skipVerification: params.options.skipVerification,
+    allowedHosts: params.options.webhookSecurity?.allowedHosts,
+    trustForwardingHeaders: params.options.webhookSecurity?.trustForwardingHeaders,
+    trustedProxyIPs: params.options.webhookSecurity?.trustedProxyIPs,
+    remoteIP: params.ctx.remoteAddress,
+  });
+
+  if (!result.ok) {
+    console.warn(`[twilio] Webhook verification failed: ${result.reason}`);
+    if (result.verificationUrl) {
+      console.warn(`[twilio] Verification URL: ${result.verificationUrl}`);
+    }
+  }
+
+  return {
+    ok: result.ok,
+    reason: result.reason,
+    isReplay: result.isReplay,
+    verifiedRequestKey: result.verifiedRequestKey,
+  };
+}