heyhank 0.1.0 → 0.2.0

package/server/telephony/call-types.ts

@@ -25,6 +25,8 @@ export interface CallConfig {
   trunkId?: string; // Which SIP trunk to use
   callerId?: string; // Override caller ID
   maxDurationSeconds?: number; // Auto-hangup after N seconds (safety)
+  listen?: boolean; // Stream live audio to browser (listen mode)
+  useSavedScript?: boolean; // If true, inject contact.script/callFlow as PRIMARY OBJECTIVE. Default: false.
 }
 
 export type CallStatus =
@@ -49,6 +51,7 @@ export interface CallState {
   prompt: string;
   voice: string;
   status: CallStatus;
+  direction: "outbound" | "inbound";
   trunkId: string;
   callerId: string;
   transcript: TranscriptEntry[];
@@ -58,6 +61,8 @@ export interface CallState {
   connectedAt: number | null;
   endedAt: number | null;
   error: string | null;
+  listenMode: boolean;
+  audioFile?: string | null; // Path to WAV recording (stereo: caller L, AI R)
 }
 
 /** Message from FreeSWITCH audio fork WebSocket (PCM audio chunks) */
@@ -79,6 +84,49 @@ export interface TelephonyContact {
   name: string; // Display name (e.g. "Mama", "Restaurant Steirereck")
   phone: string; // E.164 format (e.g. "+4366412345")
   notes?: string; // Optional context (e.g. "Mon-Sat 10-18 Uhr")
+  language?: string; // Call language (e.g. "de", "en") — default: "en"
+  script?: string; // Simple call script (markdown prompt)
+  callFlow?: CallFlow; // Enterprise: state machine call flow
+}
+
+// ─── Call Flow (State Machine) ────────────────────────────────────────────────
+
+/** A node in the call flow graph */
+export interface CallFlowNode {
+  id: string;
+  type: "start" | "say" | "ask" | "condition" | "action" | "end";
+  label: string; // Short label for UI display
+  prompt?: string; // What the AI should say/do at this node
+  /** For "ask" nodes: what to listen for */
+  expectedResponses?: string[];
+  /** For "condition" nodes: variable to evaluate */
+  conditionVariable?: string;
+  /** For "action" nodes: tool to call (e.g. "save_note", "end_call") */
+  actionTool?: string;
+  actionArgs?: Record<string, unknown>;
+  /** Position in visual editor (pixels) */
+  position?: { x: number; y: number };
+}
+
+/** An edge connecting two nodes in the call flow */
+export interface CallFlowEdge {
+  id: string;
+  from: string; // source node ID
+  to: string; // target node ID
+  label?: string; // condition label (e.g. "yes", "no", "timeout", "default")
+  condition?: string; // optional match condition (regex or keyword)
+}
+
+/** A complete call flow definition (state machine) */
+export interface CallFlow {
+  id: string;
+  name: string;
+  description?: string;
+  nodes: CallFlowNode[];
+  edges: CallFlowEdge[];
+  variables?: Record<string, string>; // template variables (e.g. {{companyName}})
+  createdAt?: string;
+  updatedAt?: string;
 }
 
 /** Telephony settings stored in ~/.heyhank/telephony.json */
@@ -89,8 +137,23 @@ export interface TelephonySettings {
   contacts: TelephonyContact[];
   defaultTrunkId: string | null;
   defaultVoice: string;
+  defaultLanguage: string; // e.g. "de", "en" — used when contact has no language set
   maxCallDurationSeconds: number;
   geminiApiKey?: string; // Override; falls back to main Gemini key
+  geminiBackend?: "aistudio" | "vertexai"; // Default: aistudio
+  gcpProjectId?: string; // Required for Vertex AI
+  gcpLocation?: string; // e.g. "europe-west4" (default for Vertex AI)
+  gcpServiceAccountKey?: string; // Path to service account JSON key file
+  // Inbound call handling
+  inboundEnabled?: boolean;
+  defaultInboundPrompt?: string; // System prompt for answering calls
+  defaultInboundVoice?: string; // Voice for inbound (default: same as defaultVoice)
+  inboundKnowledgeBase?: string; // Business info, FAQs, etc. injected into every inbound call
+  /**
+   * Country-code digits (no `+`) used to convert national-format inbound caller-IDs
+   * to E.164 for contact lookup. If empty, the first enabled trunk's callerId is parsed.
+   */
+  defaultCountryCode?: string;
 }
 
 export const DEFAULT_TELEPHONY_SETTINGS: TelephonySettings = {
@@ -98,11 +161,14 @@ export const DEFAULT_TELEPHONY_SETTINGS: TelephonySettings = {
   freeswitch: {
     eslHost: "localhost",
     eslPort: 8021,
-    eslPassword: "ClueCon",
+    eslPassword: "heyhank_esl_secret",
   },
   trunks: [],
   contacts: [],
   defaultTrunkId: null,
   defaultVoice: "Kore",
+  defaultLanguage: "de",
   maxCallDurationSeconds: 600, // 10 min safety limit
+  inboundEnabled: false,
+  defaultInboundPrompt: "You are Hank, a helpful AI assistant answering the phone. Be friendly, concise, and helpful. Ask the caller how you can help them.",
 };

package/server/telephony/esl-client.ts

@@ -0,0 +1,319 @@
+// ─── FreeSWITCH ESL TCP Client ───────────────────────────────────────────────
+// Lightweight ESL (Event Socket Layer) client for sending commands to FreeSWITCH.
+// Uses TCP socket protocol (mod_event_socket) instead of HTTP (mod_xml_rpc).
+//
+// Protocol: Connect → receive "Content-Type: auth/request" → send "auth <pw>" →
+// receive "Reply-Text: +OK" → send "api <cmd>" → read response.
+
+import { connect, type Socket } from "node:net";
+import type { FreeSwitchConfig } from "./call-types.js";
+
+/**
+ * Send a single FreeSWITCH API command via ESL TCP and return the response.
+ * Opens a connection, authenticates, sends the command, then closes.
+ * Use background=true for long-running commands like originate (uses bgapi).
+ */
+export async function eslCommand(
+  command: string,
+  config: FreeSwitchConfig,
+  timeoutMs = 5000,
+  background = false,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    let authenticated = false;
+    let commandSent = false;
+    let responseBody = "";
+    let expectedContentLength = 0;
+    let resolved = false;
+
+    const done = (result: string) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(result);
+    };
+
+    const fail = (err: Error) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      socket.destroy();
+      reject(err);
+    };
+
+    const timer = setTimeout(() => {
+      fail(new Error(`ESL timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const socket: Socket = connect(config.eslPort, config.eslHost, () => {
+      // Connection established — wait for auth/request
+    });
+
+    socket.setEncoding("utf-8");
+
+    socket.on("data", (chunk: string) => {
+      buffer += chunk;
+
+      // Parse ESL protocol messages (header + body separated by \n\n)
+      while (buffer.includes("\n\n")) {
+        const delimIdx = buffer.indexOf("\n\n");
+        const block = buffer.slice(0, delimIdx);
+        buffer = buffer.slice(delimIdx + 2);
+
+        const headers = parseHeaders(block);
+
+        if (!authenticated) {
+          if (headers["Content-Type"] === "auth/request") {
+            socket.write(`auth ${config.eslPassword}\n\n`);
+          } else if (headers["Reply-Text"]?.startsWith("+OK")) {
+            authenticated = true;
+            // Use bgapi for background commands (non-blocking), api for regular
+            const prefix = background ? "bgapi" : "api";
+            socket.write(`${prefix} ${command}\n\n`);
+            commandSent = true;
+          } else if (headers["Reply-Text"]?.startsWith("-ERR")) {
+            fail(new Error(`ESL auth failed: ${headers["Reply-Text"]}`));
+            return;
+          }
+        } else if (commandSent) {
+          // bgapi returns Reply-Text with Job-UUID immediately
+          if (background && headers["Reply-Text"]) {
+            const reply = headers["Reply-Text"];
+            if (reply.startsWith("+OK")) {
+              // Extract Job-UUID: "+OK Job-UUID: xxxx"
+              const jobId = reply.replace("+OK Job-UUID: ", "").trim();
+              done(jobId || "+OK");
+              return;
+            } else if (reply.startsWith("-ERR")) {
+              fail(new Error(`FreeSWITCH error: ${reply}`));
+              return;
+            }
+          }
+
+          // Regular api response
+          if (headers["Content-Type"] === "api/response") {
+            expectedContentLength = parseInt(headers["Content-Length"] || "0", 10);
+            if (expectedContentLength > 0) {
+              if (buffer.length >= expectedContentLength) {
+                done(buffer.slice(0, expectedContentLength));
+                return;
+              }
+              // Wait for more data
+            } else {
+              done("");
+              return;
+            }
+          }
+        }
+      }
+
+      // If we're waiting for body content after headers
+      if (expectedContentLength > 0 && buffer.length >= expectedContentLength) {
+        done(buffer.slice(0, expectedContentLength));
+      }
+    });
+
+    socket.on("error", (err) => {
+      fail(new Error(`ESL connection error: ${err.message}`));
+    });
+
+    socket.on("close", () => {
+      if (!resolved && !commandSent) {
+        fail(new Error("ESL connection closed before command sent"));
+      }
+    });
+  });
+}
+
+function parseHeaders(block: string): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const line of block.split("\n")) {
+    const idx = line.indexOf(": ");
+    if (idx > 0) {
+      headers[line.slice(0, idx)] = line.slice(idx + 2);
+    }
+  }
+  return headers;
+}
+
+/**
+ * Subscribe to FreeSWITCH events for inbound call detection + hangup cleanup.
+ * Maintains a persistent ESL connection that listens for CHANNEL_CREATE and
+ * CHANNEL_HANGUP_COMPLETE events. Auto-reconnects on disconnect.
+ */
+export function eslSubscribe(
+  config: FreeSwitchConfig,
+  onInboundCall: (info: { uuid: string; callerNumber: string }) => void,
+  onHangup?: (info: { uuid: string }) => void,
+): { stop: () => void } {
+  let stopped = false;
+  let socket: Socket | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let reconnectDelay = 5000; // Start at 5s, exponential backoff up to 60s
+  let authFailed = false;
+
+  function connectAndSubscribe() {
+    if (stopped) return;
+
+    let buffer = "";
+    let authenticated = false;
+    let subscribed = false;
+    authFailed = false;
+
+    socket = connect(config.eslPort, config.eslHost, () => {
+      console.log("[esl-subscribe] Connected to FreeSWITCH for inbound events");
+    });
+
+    socket.setEncoding("utf-8");
+
+    socket.on("data", (chunk: string) => {
+      buffer += chunk;
+
+      while (buffer.includes("\n\n")) {
+        const delimIdx = buffer.indexOf("\n\n");
+        const block = buffer.slice(0, delimIdx);
+        buffer = buffer.slice(delimIdx + 2);
+
+        const headers = parseHeaders(block);
+
+        if (!authenticated) {
+          if (headers["Content-Type"] === "auth/request") {
+            socket!.write(`auth ${config.eslPassword}\n\n`);
+          } else if (headers["Reply-Text"]?.startsWith("+OK")) {
+            authenticated = true;
+            // Reset backoff on successful auth
+            reconnectDelay = 5000;
+            // Subscribe to channel create (inbound detection) + hangup (cleanup).
+            socket!.write("event plain CHANNEL_CREATE CHANNEL_HANGUP_COMPLETE\n\n");
+          } else if (headers["Reply-Text"]?.startsWith("-ERR")) {
+            authFailed = true;
+            console.error("[esl-subscribe] Authentication failed:", headers["Reply-Text"]);
+            socket!.destroy();
+            return;
+          }
+        } else if (!subscribed) {
+          if (headers["Reply-Text"]?.startsWith("+OK")) {
+            subscribed = true;
+            console.log("[esl-subscribe] Subscribed to CHANNEL_CREATE + CHANNEL_HANGUP_COMPLETE events");
+          }
+        } else {
+          // Parse events — look for inbound calls + hangups
+          if (headers["Content-Type"] === "text/event-plain") {
+            const contentLength = parseInt(headers["Content-Length"] || "0", 10);
+            // Read the event body
+            let eventBody = "";
+            if (contentLength > 0 && buffer.length >= contentLength) {
+              eventBody = buffer.slice(0, contentLength);
+              buffer = buffer.slice(contentLength);
+            } else if (contentLength > 0) {
+              // Body incomplete — restore the full original buffer (headers + delimiter + remaining)
+              // so the next data event can parse the complete message
+              buffer = block + "\n\n" + buffer;
+              break;
+            }
+
+            // Parse event headers from the body
+            const eventHeaders = parseHeaders(eventBody || block);
+            const allHeaders = { ...headers, ...eventHeaders };
+            const eventName = allHeaders["Event-Name"] || "";
+            const uuid = allHeaders["Unique-ID"] || allHeaders["Channel-Call-UUID"] || "";
+
+            if (eventName === "CHANNEL_CREATE") {
+              const direction = allHeaders["Call-Direction"] || allHeaders["variable_call_direction"] || "";
+              const callerNumber = allHeaders["Caller-Caller-ID-Number"] || allHeaders["variable_sip_from_user"] || "";
+              const destNumber = allHeaders["Caller-Destination-Number"] || allHeaders["variable_destination_number"] || "";
+              // Filter out SIP scanner probes / keepalive INVITEs (destination "0",
+              // empty, or anything that doesn't match our DID pattern). Only real
+              // inbound calls to 43… reach the heyhank dialplan, but CHANNEL_CREATE
+              // fires for every INVITE even when NO_ROUTE_DESTINATION rejects it.
+              const isRealDid = /^\+?43\d+$/.test(destNumber);
+              if (direction === "inbound" && uuid && isRealDid) {
+                console.log(`[esl-subscribe] Inbound call detected: UUID=${uuid}, caller=${callerNumber}, dest=${destNumber}`);
+                try {
+                  onInboundCall({ uuid, callerNumber: callerNumber || "unknown" });
+                } catch (err) {
+                  console.error("[esl-subscribe] onInboundCall error:", err);
+                }
+              }
+            } else if (eventName === "CHANNEL_HANGUP_COMPLETE" && uuid && onHangup) {
+              try {
+                onHangup({ uuid });
+              } catch (err) {
+                console.error("[esl-subscribe] onHangup error:", err);
+              }
+            }
+          }
+        }
+      }
+    });
+
+    socket.on("error", (err) => {
+      console.error("[esl-subscribe] Connection error:", err.message);
+    });
+
+    socket.on("close", () => {
+      console.log(`[esl-subscribe] Connection closed, reconnecting in ${reconnectDelay / 1000}s`);
+      if (!stopped) {
+        reconnectTimer = setTimeout(connectAndSubscribe, reconnectDelay);
+        // Exponential backoff: 5s → 10s → 20s → 40s → 60s (max)
+        if (authFailed) {
+          reconnectDelay = Math.min(reconnectDelay * 2, 60000);
+        }
+      }
+    });
+  }
+
+  connectAndSubscribe();
+
+  return {
+    stop: () => {
+      stopped = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      if (socket) socket.destroy();
+    },
+  };
+}
+
+/**
+ * Check if FreeSWITCH is reachable and authenticated.
+ */
+export async function eslStatus(config: FreeSwitchConfig): Promise<{ connected: boolean; status: string }> {
+  try {
+    const result = await eslCommand("status", config);
+    return { connected: true, status: result.trim().slice(0, 300) };
+  } catch (err) {
+    return { connected: false, status: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Rescan external SIP profiles (picks up new/changed gateway XML files).
+ */
+export async function eslRescanGateways(config: FreeSwitchConfig): Promise<boolean> {
+  try {
+    const result = await eslCommand("sofia profile external rescan", config);
+    console.log(`[telephony] ESL rescan result: ${result.trim()}`);
+    return true;
+  } catch (err) {
+    console.error(`[telephony] ESL rescan error:`, err);
+    return false;
+  }
+}
+
+/**
+ * Check registration status of a specific gateway.
+ */
+export async function eslGatewayStatus(
+  gatewayName: string,
+  config: FreeSwitchConfig,
+): Promise<{ registered: boolean; status: string }> {
+  try {
+    const result = await eslCommand(`sofia status gateway ${gatewayName}`, config);
+    const registered = result.includes("REGED") || result.includes("REGISTER");
+    return { registered, status: result.trim().slice(0, 300) };
+  } catch (err) {
+    return { registered: false, status: err instanceof Error ? err.message : String(err) };
+  }
+}

package/server/telephony/freeswitch-sync.ts

@@ -0,0 +1,155 @@
+// ─── FreeSWITCH Config Sync ──────────────────────────────────────────────────
+// Generates FreeSWITCH gateway XML from HeyHank trunk settings and triggers reload.
+// This is the bridge between "user enters SIP credentials in UI" and "FreeSWITCH registers with provider".
+
+import { writeFileSync, mkdirSync, existsSync, unlinkSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { SipTrunkConfig } from "./call-types.js";
+import { getSettings } from "./telephony-store.js";
+import { eslRescanGateways, eslGatewayStatus } from "./esl-client.js";
+
+// The Docker volume mount maps this directory into the FreeSWITCH container
+const GATEWAY_DIR = join(process.cwd(), "..", "freeswitch", "conf", "sip_profiles", "external");
+
+// Known SIP provider defaults
+const PROVIDER_DEFAULTS: Record<string, { realm: string; proxy: string; tls?: boolean }> = {
+  peoplefone: { realm: "sips.peoplefone.at", proxy: "sips.peoplefone.at", tls: true },
+  sipgate: { realm: "sipgate.de", proxy: "sipgate.de" },
+  easybell: { realm: "sip.easybell.de", proxy: "sip.easybell.de" },
+};
+
+/**
+ * Generate FreeSWITCH gateway XML for a single SIP trunk.
+ */
+function generateGatewayXml(trunk: SipTrunkConfig): string {
+  const defaults = PROVIDER_DEFAULTS[trunk.provider];
+  const realm = trunk.server || defaults?.realm || trunk.server;
+  const proxy = trunk.server || defaults?.proxy || trunk.server;
+  const useTls = defaults?.tls || trunk.server?.startsWith("sips.");
+
+  // Sanitize the gateway name for FreeSWITCH (alphanumeric + underscore + hyphen)
+  // Prefix with "heyhank_" to match what call-manager.ts expects
+  const gatewayName = `heyhank_${trunk.name.replace(/[^a-zA-Z0-9_-]/g, "_").toLowerCase()}`;
+
+  const tlsParams = useTls ? `
+    <param name="register-transport" value="tls"/>
+    <param name="contact-params" value="transport=tls"/>` : "";
+
+  return `<!-- Auto-generated by HeyHank — trunk: ${trunk.name} (${trunk.provider}) -->
+<!-- DO NOT EDIT: This file is regenerated when trunk settings change in HeyHank UI -->
+<include>
+  <gateway name="${gatewayName}">
+    <param name="username" value="${escapeXml(trunk.username)}"/>
+    <param name="password" value="${escapeXml(trunk.password)}"/>
+    <param name="realm" value="${escapeXml(realm)}"/>
+    <param name="proxy" value="${escapeXml(proxy)}"/>
+    <param name="register" value="${trunk.enabled ? "true" : "false"}"/>
+    <param name="expire-seconds" value="600"/>
+    <param name="caller-id-in-from" value="true"/>
+    <param name="codec-prefs" value="PCMA,PCMU"/>${tlsParams}
+  </gateway>
+</include>
+`;
+}
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Write all trunk configs as FreeSWITCH gateway XML files.
+ * Old auto-generated files are cleaned up first.
+ */
+export function syncGatewayConfigs(trunks: SipTrunkConfig[]): { written: string[]; errors: string[] } {
+  const written: string[] = [];
+  const errors: string[] = [];
+
+  if (!existsSync(GATEWAY_DIR)) {
+    try {
+      mkdirSync(GATEWAY_DIR, { recursive: true });
+    } catch (err) {
+      errors.push(`Cannot create gateway dir: ${err}`);
+      return { written, errors };
+    }
+  }
+
+  // Remove old auto-generated gateway files (identified by "heyhank_" prefix)
+  try {
+    const existing = readdirSync(GATEWAY_DIR).filter((f) => f.startsWith("heyhank_") && f.endsWith(".xml"));
+    for (const file of existing) {
+      try {
+        unlinkSync(join(GATEWAY_DIR, file));
+      } catch { /* ignore */ }
+    }
+  } catch { /* dir might not exist yet */ }
+
+  // Write new gateway files
+  for (const trunk of trunks) {
+    if (!trunk.username || !trunk.password || !trunk.server) {
+      errors.push(`Trunk "${trunk.name}" skipped: missing credentials`);
+      continue;
+    }
+
+    const gatewayName = trunk.name.replace(/[^a-zA-Z0-9_-]/g, "_").toLowerCase();
+    const filename = `heyhank_${gatewayName}.xml`;
+    const filepath = join(GATEWAY_DIR, filename);
+
+    try {
+      const xml = generateGatewayXml(trunk);
+      writeFileSync(filepath, xml, "utf-8");
+      written.push(filename);
+    } catch (err) {
+      errors.push(`Failed to write ${filename}: ${err}`);
+    }
+  }
+
+  return { written, errors };
+}
+
+/**
+ * Sync gateway configs AND tell FreeSWITCH to reload them.
+ * This is the main function called when trunk settings change in the UI.
+ */
+export async function syncAndReload(): Promise<{
+  synced: boolean;
+  reloaded: boolean;
+  written: string[];
+  errors: string[];
+}> {
+  const settings = getSettings();
+  const { written, errors } = syncGatewayConfigs(settings.trunks);
+
+  let reloaded = false;
+
+  // Try to reload FreeSWITCH gateway profiles via ESL TCP
+  if (written.length > 0) {
+    try {
+      reloaded = await eslRescanGateways(settings.freeswitch);
+    } catch (err) {
+      errors.push(`FreeSWITCH reload failed: ${err}`);
+    }
+  }
+
+  return { synced: written.length > 0, reloaded, written, errors };
+}
+
+/**
+ * Check if a specific gateway is registered with FreeSWITCH.
+ * Accepts either a trunk ID (UUID) or a gateway name.
+ */
+export async function checkGatewayStatus(
+  trunkIdOrName: string,
+): Promise<{ registered: boolean; status: string }> {
+  const settings = getSettings();
+  // Resolve trunk ID to gateway name
+  const trunk = settings.trunks.find((t) => t.id === trunkIdOrName);
+  const gwName = trunk
+    ? `heyhank_${trunk.name.replace(/[^a-zA-Z0-9_-]/g, "_").toLowerCase()}`
+    : trunkIdOrName;
+  return eslGatewayStatus(gwName, settings.freeswitch);
+}

package/server/telephony/phone-utils.ts

@@ -0,0 +1,63 @@
+// ─── Phone number normalization ──────────────────────────────────────────────
+// Inbound SIP providers vary in how they present the caller number:
+//   peoplefone (AT): "06508920611"           → national format with leading 0
+//   sipgate (DE):    "+4915112345678"        → already E.164
+//   some legacy:     "004915112345678"       → "00" international prefix
+// Contacts are stored in E.164 (e.g. "+436508920611"). Without normalization,
+// the inbound caller-ID lookup fails to match a known contact, and Hank treats
+// the caller as anonymous.
+
+/**
+ * Normalize a phone number to E.164 (`+<country><subscriber>`).
+ * `defaultCountryCode` is the digit-only country code to assume when the input
+ * uses national format (leading "0"). If empty, leading "0" is preserved and
+ * the function returns the raw digits — callers should treat that as best-effort.
+ */
+export function normalizePhoneE164(num: string, defaultCountryCode: string = ""): string {
+  if (!num) return "";
+  // Keep digits and a leading + only
+  const stripped = num.trim().replace(/[^\d+]/g, "");
+  if (!stripped) return "";
+  // Already E.164
+  if (stripped.startsWith("+")) return stripped;
+  // International prefix "00…" → "+…"
+  if (stripped.startsWith("00")) return "+" + stripped.slice(2);
+  // National format "0…" → "+<cc>…" if we know the country code
+  if (stripped.startsWith("0") && defaultCountryCode) {
+    return "+" + defaultCountryCode + stripped.slice(1);
+  }
+  // Bare digits — assume the caller already included the country code (e.g. peoplefone
+  // sometimes sends "43720271025" without the +).
+  return "+" + stripped;
+}
+
+/**
+ * Pull the country-code digits ("43") out of a configured caller-ID like "+43720271025".
+ * E.164 country codes are 1-3 digits; we match against a known prefix list (longest-first)
+ * because a naive `\d{1,3}` regex is greedy and would return "437" for "+43720271025".
+ */
+const KNOWN_COUNTRY_CODES = [
+  // 3-digit
+  "350", "351", "352", "353", "354", "355", "356", "357", "358", "359",
+  "370", "371", "372", "373", "374", "375", "376", "377", "378", "380",
+  "381", "382", "383", "385", "386", "387", "389",
+  "420", "421", "423",
+  // 2-digit
+  "20", "27", "30", "31", "32", "33", "34", "36", "39", "40", "41", "43", "44",
+  "45", "46", "47", "48", "49", "51", "52", "53", "54", "55", "56", "57", "58",
+  "60", "61", "62", "63", "64", "65", "66", "81", "82", "84", "86", "90", "91",
+  "92", "93", "94", "95", "98",
+  // 1-digit
+  "1", "7",
+];
+export function extractCountryCode(callerId: string | undefined | null): string {
+  if (!callerId) return "";
+  const m = callerId.trim().match(/^\+(\d+)/);
+  if (!m) return "";
+  const digits = m[1];
+  // Match longest known prefix first (3 → 2 → 1)
+  for (const cc of KNOWN_COUNTRY_CODES) {
+    if (digits.startsWith(cc)) return cc;
+  }
+  return "";
+}