voicecc 1.0.7

package/services/browser-call-manager.ts

@@ -0,0 +1,106 @@
+/**
+ * Browser call server process management.
+ *
+ * Manages the lifecycle of the browser-server child process.
+ * Analogous to twilio-manager.ts but simpler -- no TwiML app updates,
+ * no Twilio SDK dependency.
+ *
+ * Responsibilities:
+ * - Spawn browser-server.ts as a child process with DASHBOARD_PORT env var
+ * - Stop the server via SIGTERM
+ * - Report running status
+ */
+
+import { spawn, ChildProcess } from "child_process";
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+/** Browser call server status for the dashboard UI */
+export interface BrowserCallStatus {
+  /** Whether the browser-server process is alive */
+  running: boolean;
+}
+
+// ============================================================================
+// STATE
+// ============================================================================
+
+/** Browser server child process handle */
+let browserProcess: ChildProcess | null = null;
+
+/** Whether the browser call server is running */
+let browserRunning = false;
+
+// ============================================================================
+// MAIN HANDLERS
+// ============================================================================
+
+/**
+ * Start the browser call server.
+ * Spawns browser-server.ts as a child process with DASHBOARD_PORT env var.
+ * Uses TWILIO_PORT from .env (default 8080).
+ *
+ * @param dashboardPort - The dashboard server port (for proxying)
+ * @throws Error if the server is already running
+ */
+export async function startBrowserCallServer(dashboardPort: number): Promise<void> {
+  if (browserRunning) {
+    throw new Error("Browser call server is already running");
+  }
+
+  browserProcess = spawn("npx", ["tsx", "sidecar/browser-server.ts"], {
+    cwd: process.cwd(),
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, DASHBOARD_PORT: String(dashboardPort) },
+  });
+
+  browserProcess.stdout?.on("data", (chunk: Buffer) => {
+    process.stdout.write(`[browser-server] ${chunk.toString()}`);
+  });
+  browserProcess.stderr?.on("data", (chunk: Buffer) => {
+    process.stderr.write(`[browser-server] ${chunk.toString()}`);
+  });
+
+  browserProcess.on("exit", (code) => {
+    if (browserRunning) {
+      console.error(`Browser call server exited unexpectedly (code ${code})`);
+    }
+    browserRunning = false;
+    browserProcess = null;
+  });
+
+  browserRunning = true;
+  console.log("Browser call server started.");
+}
+
+/**
+ * Stop the browser call server.
+ * Sends SIGTERM to the child process and clears state.
+ */
+export function stopBrowserCallServer(): void {
+  if (browserProcess && !browserProcess.killed) {
+    browserProcess.kill("SIGTERM");
+  }
+  browserProcess = null;
+  browserRunning = false;
+}
+
+/**
+ * Get the status of the browser call server.
+ *
+ * @returns Status with running state
+ */
+export function getBrowserCallStatus(): BrowserCallStatus {
+  return { running: browserRunning };
+}
+
+/**
+ * Check whether the browser call server process is currently alive.
+ *
+ * @returns True if the server is running
+ */
+export function isBrowserCallRunning(): boolean {
+  return browserRunning;
+}

package/services/device-pairing.ts

@@ -0,0 +1,176 @@
+/**
+ * Device pairing and token management for WebRTC browser calling.
+ *
+ * Handles the pairing flow between the dashboard and remote devices:
+ * - Generate 6-digit pairing codes with 5-minute TTL
+ * - Validate codes and issue persistent device tokens
+ * - Persist device tokens to disk across restarts
+ * - Purge expired pairing codes automatically
+ */
+
+import { readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { randomUUID } from "crypto";
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+/** Internal pairing code entry */
+interface PairingCode {
+  expiresAt: number;
+  attempts: number;
+}
+
+/** Stored device token info */
+interface DeviceTokenInfo {
+  pairedAt: number;
+  userAgent: string;
+}
+
+/** Result of generating a new pairing code */
+export interface PairingResult {
+  code: string;
+  expiresAt: number;
+}
+
+/** Result of validating a pairing code */
+export interface PairingValidation {
+  ok: boolean;
+  token?: string;
+  error?: string;
+}
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+const PAIRING_CODE_TTL_MS = 5 * 60 * 1000;
+const PAIRING_MAX_ATTEMPTS = 5;
+const DEVICE_TOKENS_PATH = join(process.cwd(), ".device-tokens.json");
+
+// ============================================================================
+// STATE
+// ============================================================================
+
+/** Active pairing codes: code -> { expiresAt, attempts } */
+const pairingCodes = new Map<string, PairingCode>();
+
+/** Paired device tokens: token -> { pairedAt, userAgent } */
+const deviceTokens = new Map<string, DeviceTokenInfo>();
+
+// Purge expired pairing codes every 60s
+setInterval(() => {
+  const now = Date.now();
+  for (const [code, data] of pairingCodes) {
+    if (now > data.expiresAt) pairingCodes.delete(code);
+  }
+}, 60_000);
+
+// ============================================================================
+// MAIN HANDLERS
+// ============================================================================
+
+/**
+ * Generate a 6-digit pairing code with a 5-minute TTL.
+ *
+ * @returns The generated code and its expiration timestamp
+ */
+export function generatePairingCode(): PairingResult {
+  const code = String(Math.floor(100000 + Math.random() * 900000));
+  const expiresAt = Date.now() + PAIRING_CODE_TTL_MS;
+  pairingCodes.set(code, { expiresAt, attempts: 0 });
+  return { code, expiresAt };
+}
+
+/**
+ * Validate a pairing code and issue a device token on success.
+ * Enforces max attempts and single-use consumption.
+ *
+ * @param code - The 6-digit pairing code to validate
+ * @param userAgent - The device's user-agent string
+ * @returns Validation result with token on success or error on failure
+ */
+export function validateAndConsumeCode(code: string, userAgent: string): PairingValidation {
+  const entry = pairingCodes.get(code);
+
+  if (!entry) {
+    return { ok: false, error: "Invalid pairing code" };
+  }
+
+  if (Date.now() > entry.expiresAt) {
+    pairingCodes.delete(code);
+    return { ok: false, error: "Pairing code expired" };
+  }
+
+  entry.attempts++;
+  if (entry.attempts > PAIRING_MAX_ATTEMPTS) {
+    pairingCodes.delete(code);
+    return { ok: false, error: "Too many attempts, code invalidated" };
+  }
+
+  // Code is valid -- delete it (single-use) and issue a device token
+  pairingCodes.delete(code);
+  const token = randomUUID();
+  deviceTokens.set(token, { pairedAt: Date.now(), userAgent });
+  saveDeviceTokens().catch(() => {});
+
+  return { ok: true, token };
+}
+
+/**
+ * Check if a device token exists in the store.
+ *
+ * @param token - The device token to validate
+ * @returns True if the token is valid
+ */
+/**
+ * Check if a pairing code is still active (not yet consumed or expired).
+ *
+ * @param code - The 6-digit pairing code
+ * @returns True if the code is still waiting to be used
+ */
+export function isPairingCodeActive(code: string): boolean {
+  const entry = pairingCodes.get(code);
+  if (!entry) return false;
+  if (Date.now() > entry.expiresAt) {
+    pairingCodes.delete(code);
+    return false;
+  }
+  return true;
+}
+
+export function isValidDeviceToken(token: string): boolean {
+  return deviceTokens.has(token);
+}
+
+/**
+ * Load persisted device tokens from disk on startup.
+ * Call this before mounting routes.
+ */
+export async function loadDeviceTokens(): Promise<void> {
+  try {
+    const data = JSON.parse(await readFile(DEVICE_TOKENS_PATH, "utf-8"));
+    for (const [token, info] of Object.entries(data)) {
+      deviceTokens.set(token, info as DeviceTokenInfo);
+    }
+  } catch {
+    // File doesn't exist or is invalid -- start fresh
+  }
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Persist device tokens to disk.
+ * Called internally by validateAndConsumeCode on success.
+ */
+async function saveDeviceTokens(): Promise<void> {
+  const data: Record<string, DeviceTokenInfo> = {};
+  for (const [token, info] of deviceTokens) {
+    data[token] = info;
+  }
+  await writeFile(DEVICE_TOKENS_PATH, JSON.stringify(data), "utf-8");
+}

package/services/env.ts

@@ -0,0 +1,88 @@
+/**
+ * Environment file (.env) read/write service.
+ *
+ * Shared utility for all services that need to read or write .env configuration:
+ * - Parse raw .env content into key-value records
+ * - Read .env from disk with a configurable path
+ * - Write a single key or full record back to disk
+ */
+
+import { readFile, writeFile } from "fs/promises";
+import { join } from "path";
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+/** Key-value record representing parsed .env contents */
+export type EnvRecord = Record<string, string>;
+
+// ============================================================================
+// MAIN HANDLERS
+// ============================================================================
+
+/**
+ * Read and parse a .env file from disk.
+ * Returns an empty record if the file does not exist.
+ *
+ * @param envPath - Absolute path to the .env file. Defaults to process.cwd()/.env
+ * @returns Parsed key-value pairs from the .env file
+ */
+export async function readEnv(envPath?: string): Promise<EnvRecord> {
+  const filePath = envPath ?? join(process.cwd(), ".env");
+  const content = await readFile(filePath, "utf-8").catch(() => "");
+  return parseEnvFile(content);
+}
+
+/**
+ * Update a single key in the .env file, preserving all other values.
+ * Creates the file if it does not exist.
+ *
+ * @param key - The env variable name to set
+ * @param value - The value to write
+ * @param envPath - Absolute path to the .env file. Defaults to process.cwd()/.env
+ */
+export async function writeEnvKey(key: string, value: string, envPath?: string): Promise<void> {
+  const settings = await readEnv(envPath);
+  settings[key] = value;
+  await writeEnvFile(settings, envPath);
+}
+
+/**
+ * Write a full key-value record to a .env file.
+ * Overwrites the entire file contents. Each entry becomes a KEY=VALUE line.
+ *
+ * @param settings - Key-value pairs to write
+ * @param envPath - Absolute path to the .env file. Defaults to process.cwd()/.env
+ */
+export async function writeEnvFile(settings: EnvRecord, envPath?: string): Promise<void> {
+  const filePath = envPath ?? join(process.cwd(), ".env");
+  const lines = Object.entries(settings).map(([k, v]) => `${k}=${v}`);
+  await writeFile(filePath, lines.join("\n") + "\n", "utf-8");
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Parse a .env file string into a key-value record.
+ * Handles lines in the format KEY=VALUE, ignores empty lines and comments.
+ * Keeps empty values (KEY= produces { KEY: "" }). Does NOT strip quotes.
+ *
+ * @param content - Raw .env file content
+ * @returns Parsed key-value pairs
+ */
+export function parseEnvFile(content: string): EnvRecord {
+  const result: EnvRecord = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = trimmed.slice(0, eqIndex).trim();
+    const value = trimmed.slice(eqIndex + 1).trim();
+    result[key] = value;
+  }
+  return result;
+}

package/services/tunnel.ts

@@ -0,0 +1,204 @@
+/**
+ * Cloudflare quick tunnel process lifecycle management.
+ *
+ * Manages spawning and stopping the cloudflared tunnel process:
+ * - Start cloudflared on a given port and parse the public HTTPS URL from stderr
+ * - Stop cloudflared and clear state
+ * - Check if cloudflared is installed
+ */
+
+import { spawn, execFile, ChildProcess } from "child_process";
+import { writeEnvKey } from "./env.js";
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Timeout for waiting for the tunnel URL to appear in stderr */
+const TUNNEL_URL_TIMEOUT_MS = 30000;
+
+// ============================================================================
+// STATE
+// ============================================================================
+
+/** cloudflared child process handle */
+let tunnelProcess: ChildProcess | null = null;
+
+/** Current public tunnel URL */
+let tunnelUrl: string | null = null;
+
+/** Timestamp when tunnel URL was obtained */
+let tunnelStartedAt: number | null = null;
+
+// ============================================================================
+// MAIN HANDLERS
+// ============================================================================
+
+/**
+ * Start a Cloudflare quick tunnel on the given port.
+ * Parses the public HTTPS URL from cloudflared's stderr output,
+ * writes it to .env as TWILIO_WEBHOOK_URL, and returns it.
+ *
+ * @param port - Local port to tunnel
+ * @returns The public HTTPS URL
+ */
+export async function startTunnel(port: number): Promise<string> {
+  if (tunnelProcess) {
+    throw new Error("Tunnel is already running");
+  }
+
+  let tunnelStderr = "";
+
+  tunnelProcess = spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`, "--protocol", "http2"], {
+    cwd: process.cwd(),
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+
+  tunnelProcess.stderr?.on("data", (chunk: Buffer) => {
+    const text = chunk.toString();
+    tunnelStderr += text;
+    for (const line of text.split("\n")) {
+      if (line.trim() && (line.includes("WRN") || line.includes("ERR"))) {
+        console.log(`[tunnel] ${line}`);
+      }
+    }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    tunnelProcess!.on("error", (err: NodeJS.ErrnoException) => {
+      tunnelProcess = null;
+      if (err.code === "ENOENT") {
+        reject(new Error(
+          "cloudflared is not installed. Install it from https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ or: brew install cloudflared"
+        ));
+      } else {
+        reject(new Error(`Failed to start cloudflared: ${err.message}`));
+      }
+    });
+    tunnelProcess!.on("spawn", () => resolve());
+  });
+
+  tunnelProcess.on("exit", (code) => {
+    console.log(`cloudflared exited (code ${code})`);
+    tunnelProcess = null;
+    tunnelUrl = null;
+  });
+
+  // Parse the tunnel URL from stderr
+  const url = await parseTunnelUrl(() => {
+    if (tunnelProcess === null || tunnelProcess.exitCode !== null) {
+      return tunnelStderr.trim() || "cloudflared exited immediately. Run 'cloudflared tunnel --url http://localhost:8080' manually to see the error.";
+    }
+    return null;
+  });
+
+  tunnelUrl = url;
+  tunnelStartedAt = Date.now();
+  await writeEnvKey("TWILIO_WEBHOOK_URL", url);
+  console.log(`Tunnel URL: ${url}`);
+  return url;
+}
+
+/**
+ * Stop the tunnel and clear state.
+ */
+export function stopTunnel(): void {
+  if (tunnelProcess && !tunnelProcess.killed) {
+    tunnelProcess.kill("SIGTERM");
+  }
+  tunnelProcess = null;
+  tunnelUrl = null;
+  tunnelStartedAt = null;
+}
+
+/**
+ * Return the current public tunnel URL, or null if not running.
+ *
+ * @returns The public HTTPS URL or null
+ */
+export function getTunnelUrl(): string | null {
+  return tunnelUrl;
+}
+
+/**
+ * Return the timestamp when the tunnel URL was obtained, or null.
+ *
+ * @returns Unix ms timestamp or null
+ */
+export function getTunnelStartedAt(): number | null {
+  return tunnelStartedAt;
+}
+
+/**
+ * Check whether the tunnel process is currently alive.
+ *
+ * @returns True if tunnel is running
+ */
+export function isTunnelRunning(): boolean {
+  return tunnelProcess !== null && !tunnelProcess.killed;
+}
+
+/**
+ * Check if cloudflared is installed by running `cloudflared version`.
+ *
+ * @returns True if cloudflared is installed
+ */
+export async function checkCloudflaredInstalled(): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    try {
+      const child = execFile("cloudflared", ["version"], (err) => resolve(!err));
+      child.on("error", () => {}); // Suppress duplicate error event
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Wait for and parse the tunnel URL from cloudflared's stderr output.
+ * cloudflared prints the URL as: https://<random>.trycloudflare.com
+ *
+ * @param checkEarlyExit - Returns an error message if cloudflared exited, null otherwise
+ * @returns The public HTTPS URL
+ */
+async function parseTunnelUrl(checkEarlyExit: () => string | null): Promise<string> {
+  const deadline = Date.now() + TUNNEL_URL_TIMEOUT_MS;
+
+  return new Promise<string>((resolve, reject) => {
+    // Listen for the URL in stderr output
+    const onData = (chunk: Buffer) => {
+      const text = chunk.toString();
+      const match = text.match(/https:\/\/[a-zA-Z0-9-]+\.trycloudflare\.com/);
+      if (match) {
+        tunnelProcess?.stderr?.off("data", onData);
+        clearInterval(checkInterval);
+        clearTimeout(timeout);
+        resolve(match[0]);
+      }
+    };
+
+    tunnelProcess?.stderr?.on("data", onData);
+
+    // Periodically check for early exit
+    const checkInterval = setInterval(() => {
+      const earlyExitError = checkEarlyExit();
+      if (earlyExitError) {
+        tunnelProcess?.stderr?.off("data", onData);
+        clearInterval(checkInterval);
+        clearTimeout(timeout);
+        reject(new Error(earlyExitError));
+      }
+    }, 500);
+
+    // Timeout
+    const timeout = setTimeout(() => {
+      tunnelProcess?.stderr?.off("data", onData);
+      clearInterval(checkInterval);
+      reject(new Error("Timed out waiting for tunnel URL"));
+    }, TUNNEL_URL_TIMEOUT_MS);
+  });
+}

package/services/twilio-manager.ts

@@ -0,0 +1,126 @@
+/**
+ * Twilio voice server process management.
+ *
+ * Manages the lifecycle of the twilio-server child process:
+ * - Start the server with dashboard port and optional tunnel URL
+ * - Stop the server
+ * - Report running status
+ */
+
+import { spawn, ChildProcess } from "child_process";
+import { readEnv } from "./env.js";
+import twilioSdk from "twilio";
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+/** Twilio server status for the dashboard UI */
+export interface TwilioStatus {
+  running: boolean;
+}
+
+// ============================================================================
+// STATE
+// ============================================================================
+
+/** Twilio server child process handle */
+let twilioProcess: ChildProcess | null = null;
+
+/** Whether the Twilio voice server is running */
+let twilioRunning = false;
+
+// ============================================================================
+// MAIN HANDLERS
+// ============================================================================
+
+/**
+ * Start the Twilio voice server.
+ * Reads .env for TWILIO_AUTH_TOKEN. If tunnelUrl and TwiML app SID exist,
+ * updates the TwiML app voice URL via Twilio SDK.
+ * Spawns twilio-server.ts as a child process with DASHBOARD_PORT env var.
+ *
+ * @param dashboardPort - The dashboard server port (for proxying)
+ * @param tunnelUrl - Optional tunnel public URL for webhook configuration
+ */
+export async function startTwilioServer(dashboardPort: number, tunnelUrl?: string): Promise<void> {
+  if (twilioRunning) {
+    throw new Error("Twilio server is already running");
+  }
+
+  const envVars = await readEnv();
+
+  if (!envVars.TWILIO_AUTH_TOKEN) {
+    throw new Error("TWILIO_AUTH_TOKEN is not set in .env");
+  }
+
+  // Update TwiML App voice URL if configured
+  const twimlAppSid = envVars.TWILIO_TWIML_APP_SID;
+  const accountSid = envVars.TWILIO_ACCOUNT_SID;
+  if (tunnelUrl && twimlAppSid && accountSid && envVars.TWILIO_AUTH_TOKEN) {
+    try {
+      const client = twilioSdk(accountSid, envVars.TWILIO_AUTH_TOKEN);
+      await client.applications(twimlAppSid).update({
+        voiceUrl: `${tunnelUrl}/twilio/incoming-call`,
+        voiceMethod: "POST",
+      });
+      console.log(`Updated TwiML App voice URL to ${tunnelUrl}/twilio/incoming-call`);
+    } catch (err) {
+      console.error(`Failed to update TwiML App voice URL: ${err}`);
+    }
+  }
+
+  // Start the Twilio server (pass dashboard port so it can proxy non-Twilio requests)
+  twilioProcess = spawn("npx", ["tsx", "sidecar/twilio-server.ts"], {
+    cwd: process.cwd(),
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, DASHBOARD_PORT: String(dashboardPort) },
+  });
+
+  twilioProcess.stdout?.on("data", (chunk: Buffer) => {
+    process.stdout.write(`[twilio-server] ${chunk.toString()}`);
+  });
+  twilioProcess.stderr?.on("data", (chunk: Buffer) => {
+    process.stderr.write(`[twilio-server] ${chunk.toString()}`);
+  });
+
+  twilioProcess.on("exit", (code) => {
+    if (twilioRunning) {
+      console.error(`Twilio server exited unexpectedly (code ${code})`);
+    }
+    twilioRunning = false;
+    twilioProcess = null;
+  });
+
+  twilioRunning = true;
+  console.log("Twilio server started.");
+}
+
+/**
+ * Stop the Twilio voice server.
+ */
+export function stopTwilioServer(): void {
+  if (twilioProcess && !twilioProcess.killed) {
+    twilioProcess.kill("SIGTERM");
+  }
+  twilioProcess = null;
+  twilioRunning = false;
+}
+
+/**
+ * Get the status of the Twilio server.
+ *
+ * @returns Status with running state
+ */
+export async function getStatus(): Promise<TwilioStatus> {
+  return { running: twilioRunning };
+}
+
+/**
+ * Check whether the Twilio server process is currently alive.
+ *
+ * @returns True if the server is running
+ */
+export function isRunning(): boolean {
+  return twilioRunning;
+}