@clawdbot/voice-call 0.1.0

package/src/types.ts

@@ -0,0 +1,272 @@
+import { z } from "zod";
+
+import type { CallMode } from "./config.js";
+
+// -----------------------------------------------------------------------------
+// Provider Identifiers
+// -----------------------------------------------------------------------------
+
+export const ProviderNameSchema = z.enum(["telnyx", "twilio", "mock"]);
+export type ProviderName = z.infer<typeof ProviderNameSchema>;
+
+// -----------------------------------------------------------------------------
+// Core Call Identifiers
+// -----------------------------------------------------------------------------
+
+/** Internal call identifier (UUID) */
+export type CallId = string;
+
+/** Provider-specific call identifier */
+export type ProviderCallId = string;
+
+// -----------------------------------------------------------------------------
+// Call Lifecycle States
+// -----------------------------------------------------------------------------
+
+export const CallStateSchema = z.enum([
+  // Non-terminal states
+  "initiated",
+  "ringing",
+  "answered",
+  "active",
+  "speaking",
+  "listening",
+  // Terminal states
+  "completed",
+  "hangup-user",
+  "hangup-bot",
+  "timeout",
+  "error",
+  "failed",
+  "no-answer",
+  "busy",
+  "voicemail",
+]);
+export type CallState = z.infer<typeof CallStateSchema>;
+
+export const TerminalStates = new Set<CallState>([
+  "completed",
+  "hangup-user",
+  "hangup-bot",
+  "timeout",
+  "error",
+  "failed",
+  "no-answer",
+  "busy",
+  "voicemail",
+]);
+
+export const EndReasonSchema = z.enum([
+  "completed",
+  "hangup-user",
+  "hangup-bot",
+  "timeout",
+  "error",
+  "failed",
+  "no-answer",
+  "busy",
+  "voicemail",
+]);
+export type EndReason = z.infer<typeof EndReasonSchema>;
+
+// -----------------------------------------------------------------------------
+// Normalized Call Events
+// -----------------------------------------------------------------------------
+
+const BaseEventSchema = z.object({
+  id: z.string(),
+  callId: z.string(),
+  providerCallId: z.string().optional(),
+  timestamp: z.number(),
+  // Optional fields for inbound call detection
+  direction: z.enum(["inbound", "outbound"]).optional(),
+  from: z.string().optional(),
+  to: z.string().optional(),
+});
+
+export const NormalizedEventSchema = z.discriminatedUnion("type", [
+  BaseEventSchema.extend({
+    type: z.literal("call.initiated"),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.ringing"),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.answered"),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.active"),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.speaking"),
+    text: z.string(),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.speech"),
+    transcript: z.string(),
+    isFinal: z.boolean(),
+    confidence: z.number().min(0).max(1).optional(),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.silence"),
+    durationMs: z.number(),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.dtmf"),
+    digits: z.string(),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.ended"),
+    reason: EndReasonSchema,
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.error"),
+    error: z.string(),
+    retryable: z.boolean().optional(),
+  }),
+]);
+export type NormalizedEvent = z.infer<typeof NormalizedEventSchema>;
+
+// -----------------------------------------------------------------------------
+// Call Direction
+// -----------------------------------------------------------------------------
+
+export const CallDirectionSchema = z.enum(["outbound", "inbound"]);
+export type CallDirection = z.infer<typeof CallDirectionSchema>;
+
+// -----------------------------------------------------------------------------
+// Call Record
+// -----------------------------------------------------------------------------
+
+export const TranscriptEntrySchema = z.object({
+  timestamp: z.number(),
+  speaker: z.enum(["bot", "user"]),
+  text: z.string(),
+  isFinal: z.boolean().default(true),
+});
+export type TranscriptEntry = z.infer<typeof TranscriptEntrySchema>;
+
+export const CallRecordSchema = z.object({
+  callId: z.string(),
+  providerCallId: z.string().optional(),
+  provider: ProviderNameSchema,
+  direction: CallDirectionSchema,
+  state: CallStateSchema,
+  from: z.string(),
+  to: z.string(),
+  sessionKey: z.string().optional(),
+  startedAt: z.number(),
+  answeredAt: z.number().optional(),
+  endedAt: z.number().optional(),
+  endReason: EndReasonSchema.optional(),
+  transcript: z.array(TranscriptEntrySchema).default([]),
+  processedEventIds: z.array(z.string()).default([]),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type CallRecord = z.infer<typeof CallRecordSchema>;
+
+// -----------------------------------------------------------------------------
+// Webhook Types
+// -----------------------------------------------------------------------------
+
+export type WebhookVerificationResult = {
+  ok: boolean;
+  reason?: string;
+};
+
+export type WebhookContext = {
+  headers: Record<string, string | string[] | undefined>;
+  rawBody: string;
+  url: string;
+  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+  query?: Record<string, string | string[] | undefined>;
+};
+
+export type ProviderWebhookParseResult = {
+  events: NormalizedEvent[];
+  providerResponseBody?: string;
+  providerResponseHeaders?: Record<string, string>;
+  statusCode?: number;
+};
+
+// -----------------------------------------------------------------------------
+// Provider Method Types
+// -----------------------------------------------------------------------------
+
+export type InitiateCallInput = {
+  callId: CallId;
+  from: string;
+  to: string;
+  webhookUrl: string;
+  clientState?: Record<string, string>;
+  /** Inline TwiML to execute (skips webhook, used for notify mode) */
+  inlineTwiml?: string;
+};
+
+export type InitiateCallResult = {
+  providerCallId: ProviderCallId;
+  status: "initiated" | "queued";
+};
+
+export type HangupCallInput = {
+  callId: CallId;
+  providerCallId: ProviderCallId;
+  reason: EndReason;
+};
+
+export type PlayTtsInput = {
+  callId: CallId;
+  providerCallId: ProviderCallId;
+  text: string;
+  voice?: string;
+  locale?: string;
+};
+
+export type StartListeningInput = {
+  callId: CallId;
+  providerCallId: ProviderCallId;
+  language?: string;
+};
+
+export type StopListeningInput = {
+  callId: CallId;
+  providerCallId: ProviderCallId;
+};
+
+// -----------------------------------------------------------------------------
+// Outbound Call Options
+// -----------------------------------------------------------------------------
+
+export type OutboundCallOptions = {
+  /** Message to speak when call connects */
+  message?: string;
+  /** Call mode (overrides config default) */
+  mode?: CallMode;
+};
+
+// -----------------------------------------------------------------------------
+// Tool Result Types
+// -----------------------------------------------------------------------------
+
+export type InitiateCallToolResult = {
+  success: boolean;
+  callId?: string;
+  status?: "initiated" | "queued" | "no-answer" | "busy" | "failed";
+  error?: string;
+};
+
+export type ContinueCallToolResult = {
+  success: boolean;
+  transcript?: string;
+  error?: string;
+};
+
+export type SpeakToUserToolResult = {
+  success: boolean;
+  error?: string;
+};
+
+export type EndCallToolResult = {
+  success: boolean;
+  error?: string;
+};

package/src/utils.ts

@@ -0,0 +1,12 @@
+import os from "node:os";
+import path from "node:path";
+
+export function resolveUserPath(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return trimmed;
+  if (trimmed.startsWith("~")) {
+    const expanded = trimmed.replace(/^~(?=$|[\\/])/, os.homedir());
+    return path.resolve(expanded);
+  }
+  return path.resolve(trimmed);
+}

package/src/voice-mapping.ts

@@ -0,0 +1,65 @@
+/**
+ * Voice mapping and XML utilities for voice call providers.
+ */
+
+/**
+ * Escape XML special characters for TwiML and other XML responses.
+ */
+export function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Map of OpenAI voice names to similar Twilio Polly voices.
+ */
+const OPENAI_TO_POLLY_MAP: Record<string, string> = {
+  alloy: "Polly.Joanna", // neutral, warm
+  echo: "Polly.Matthew", // male, warm
+  fable: "Polly.Amy", // British, expressive
+  onyx: "Polly.Brian", // deep male
+  nova: "Polly.Salli", // female, friendly
+  shimmer: "Polly.Kimberly", // female, clear
+};
+
+/**
+ * Default Polly voice when no mapping is found.
+ */
+export const DEFAULT_POLLY_VOICE = "Polly.Joanna";
+
+/**
+ * Map OpenAI voice names to Twilio Polly equivalents.
+ * Falls through if already a valid Polly/Google voice.
+ *
+ * @param voice - OpenAI voice name (alloy, echo, etc.) or Polly voice name
+ * @returns Polly voice name suitable for Twilio TwiML
+ */
+export function mapVoiceToPolly(voice: string | undefined): string {
+  if (!voice) return DEFAULT_POLLY_VOICE;
+
+  // Already a Polly/Google voice - pass through
+  if (voice.startsWith("Polly.") || voice.startsWith("Google.")) {
+    return voice;
+  }
+
+  // Map OpenAI voices to Polly equivalents
+  return OPENAI_TO_POLLY_MAP[voice.toLowerCase()] || DEFAULT_POLLY_VOICE;
+}
+
+/**
+ * Check if a voice name is a known OpenAI voice.
+ */
+export function isOpenAiVoice(voice: string): boolean {
+  return voice.toLowerCase() in OPENAI_TO_POLLY_MAP;
+}
+
+/**
+ * Get all supported OpenAI voice names.
+ */
+export function getOpenAiVoiceNames(): string[] {
+  return Object.keys(OPENAI_TO_POLLY_MAP);
+}

package/src/webhook-security.ts

@@ -0,0 +1,197 @@
+import crypto from "node:crypto";
+
+import type { WebhookContext } from "./types.js";
+
+/**
+ * Validate Twilio webhook signature using HMAC-SHA1.
+ *
+ * Twilio signs requests by concatenating the URL with sorted POST params,
+ * then computing HMAC-SHA1 with the auth token.
+ *
+ * @see https://www.twilio.com/docs/usage/webhooks/webhooks-security
+ */
+export function validateTwilioSignature(
+  authToken: string,
+  signature: string | undefined,
+  url: string,
+  params: URLSearchParams,
+): boolean {
+  if (!signature) {
+    return false;
+  }
+
+  // Build the string to sign: URL + sorted params (key+value pairs)
+  let dataToSign = url;
+
+  // Sort params alphabetically and append key+value
+  const sortedParams = Array.from(params.entries()).sort((a, b) =>
+    a[0].localeCompare(b[0]),
+  );
+
+  for (const [key, value] of sortedParams) {
+    dataToSign += key + value;
+  }
+
+  // HMAC-SHA1 with auth token, then base64 encode
+  const expectedSignature = crypto
+    .createHmac("sha1", authToken)
+    .update(dataToSign)
+    .digest("base64");
+
+  // Use timing-safe comparison to prevent timing attacks
+  return timingSafeEqual(signature, expectedSignature);
+}
+
+/**
+ * Timing-safe string comparison to prevent timing attacks.
+ */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    // Still do comparison to maintain constant time
+    const dummy = Buffer.from(a);
+    crypto.timingSafeEqual(dummy, dummy);
+    return false;
+  }
+
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Reconstruct the public webhook URL from request headers.
+ *
+ * When behind a reverse proxy (Tailscale, nginx, ngrok), the original URL
+ * used by Twilio differs from the local request URL. We use standard
+ * forwarding headers to reconstruct it.
+ *
+ * Priority order:
+ * 1. X-Forwarded-Proto + X-Forwarded-Host (standard proxy headers)
+ * 2. X-Original-Host (nginx)
+ * 3. Ngrok-Forwarded-Host (ngrok specific)
+ * 4. Host header (direct connection)
+ */
+export function reconstructWebhookUrl(ctx: WebhookContext): string {
+  const { headers } = ctx;
+
+  const proto = getHeader(headers, "x-forwarded-proto") || "https";
+
+  const forwardedHost =
+    getHeader(headers, "x-forwarded-host") ||
+    getHeader(headers, "x-original-host") ||
+    getHeader(headers, "ngrok-forwarded-host") ||
+    getHeader(headers, "host") ||
+    "";
+
+  // Extract path from the context URL (fallback to "/" on parse failure)
+  let path = "/";
+  try {
+    const parsed = new URL(ctx.url);
+    path = parsed.pathname + parsed.search;
+  } catch {
+    // URL parsing failed
+  }
+
+  // Remove port from host (ngrok URLs don't have ports)
+  const host = forwardedHost.split(":")[0] || forwardedHost;
+
+  return `${proto}://${host}${path}`;
+}
+
+/**
+ * Get a header value, handling both string and string[] types.
+ */
+function getHeader(
+  headers: Record<string, string | string[] | undefined>,
+  name: string,
+): string | undefined {
+  const value = headers[name.toLowerCase()];
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+}
+
+/**
+ * Result of Twilio webhook verification with detailed info.
+ */
+export interface TwilioVerificationResult {
+  ok: boolean;
+  reason?: string;
+  /** The URL that was used for verification (for debugging) */
+  verificationUrl?: string;
+  /** Whether we're running behind ngrok free tier */
+  isNgrokFreeTier?: boolean;
+}
+
+/**
+ * Verify Twilio webhook with full context and detailed result.
+ *
+ * Handles the special case of ngrok free tier where signature validation
+ * may fail due to URL discrepancies (ngrok adds interstitial page handling).
+ */
+export function verifyTwilioWebhook(
+  ctx: WebhookContext,
+  authToken: string,
+  options?: {
+    /** Override the public URL (e.g., from config) */
+    publicUrl?: string;
+    /** Allow ngrok free tier compatibility mode (less secure) */
+    allowNgrokFreeTier?: boolean;
+    /** Skip verification entirely (only for development) */
+    skipVerification?: boolean;
+  },
+): TwilioVerificationResult {
+  // Allow skipping verification for development/testing
+  if (options?.skipVerification) {
+    return { ok: true, reason: "verification skipped (dev mode)" };
+  }
+
+  const signature = getHeader(ctx.headers, "x-twilio-signature");
+
+  if (!signature) {
+    return { ok: false, reason: "Missing X-Twilio-Signature header" };
+  }
+
+  // Reconstruct the URL Twilio used
+  const verificationUrl = options?.publicUrl || reconstructWebhookUrl(ctx);
+
+  // Parse the body as URL-encoded params
+  const params = new URLSearchParams(ctx.rawBody);
+
+  // Validate signature
+  const isValid = validateTwilioSignature(
+    authToken,
+    signature,
+    verificationUrl,
+    params,
+  );
+
+  if (isValid) {
+    return { ok: true, verificationUrl };
+  }
+
+  // Check if this is ngrok free tier - the URL might have different format
+  const isNgrokFreeTier =
+    verificationUrl.includes(".ngrok-free.app") ||
+    verificationUrl.includes(".ngrok.io");
+
+  if (isNgrokFreeTier && options?.allowNgrokFreeTier) {
+    console.warn(
+      "[voice-call] Twilio signature validation failed (proceeding for ngrok free tier compatibility)",
+    );
+    return {
+      ok: true,
+      reason: "ngrok free tier compatibility mode",
+      verificationUrl,
+      isNgrokFreeTier: true,
+    };
+  }
+
+  return {
+    ok: false,
+    reason: `Invalid signature for URL: ${verificationUrl}`,
+    verificationUrl,
+    isNgrokFreeTier,
+  };
+}