getpatter 0.3.0 → 0.4.1

package/dist/chunk-FMNRCP5X.mjs

@@ -0,0 +1,20 @@
+// src/logger.ts
+var defaultLogger = {
+  info: (msg, ...args) => console.log(`[PATTER] ${msg}`, ...args),
+  warn: (msg, ...args) => console.warn(`[PATTER] WARNING: ${msg}`, ...args),
+  error: (msg, ...args) => console.error(`[PATTER] ERROR: ${msg}`, ...args),
+  debug: () => {
+  }
+};
+var currentLogger = defaultLogger;
+function getLogger() {
+  return currentLogger;
+}
+function setLogger(logger) {
+  currentLogger = logger;
+}
+
+export {
+  getLogger,
+  setLogger
+};

package/dist/{chunk-KB57IV4K.mjs → chunk-TAATEHKF.mjs}

@@ -1,22 +1,10 @@
+import {
+  getLogger
+} from "./chunk-FMNRCP5X.mjs";
+
 // src/test-mode.ts
 import { createInterface } from "readline";
 
-// src/logger.ts
-var defaultLogger = {
-  info: (msg, ...args) => console.log(`[PATTER] ${msg}`, ...args),
-  warn: (msg, ...args) => console.warn(`[PATTER] WARNING: ${msg}`, ...args),
-  error: (msg, ...args) => console.error(`[PATTER] ERROR: ${msg}`, ...args),
-  debug: () => {
-  }
-};
-var currentLogger = defaultLogger;
-function getLogger() {
-  return currentLogger;
-}
-function setLogger(logger) {
-  currentLogger = logger;
-}
-
 // src/llm-loop.ts
 var OpenAILLMProvider = class {
   apiKey;
@@ -402,8 +390,6 @@ var TestSession = class {
 };
 
 export {
-  getLogger,
-  setLogger,
   OpenAILLMProvider,
   LLMLoop,
   TestSession

package/dist/chunk-VNU4GNW3.mjs

@@ -0,0 +1,45 @@
+import {
+  getLogger
+} from "./chunk-FMNRCP5X.mjs";
+
+// src/tunnel.ts
+var log = getLogger();
+async function startTunnel(port, timeoutMs = 3e4) {
+  let tunnelMod;
+  try {
+    tunnelMod = await import("cloudflared");
+  } catch {
+    throw new Error(
+      'Built-in tunnel requires the "cloudflared" package. Install it with:\n\n  npm install cloudflared\n\nOr provide your own webhookUrl instead of using tunnel: true.'
+    );
+  }
+  log.info("Starting tunnel to localhost:%d ...", port);
+  const result = tunnelMod.tunnel({
+    "--url": `http://localhost:${port}`
+  });
+  const tunnelUrl = await Promise.race([
+    result.url,
+    new Promise(
+      (_, reject) => setTimeout(() => reject(new Error(
+        `Tunnel failed to start within ${timeoutMs / 1e3}s. Check your internet connection or provide webhookUrl manually.`
+      )), timeoutMs)
+    )
+  ]);
+  const hostname = tunnelUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
+  log.info("Tunnel ready: https://%s", hostname);
+  result.connections.then(() => {
+    log.info("Tunnel connections established");
+  }).catch(() => {
+  });
+  return {
+    hostname,
+    stop: () => {
+      log.info("Stopping tunnel...");
+      result.stop();
+    }
+  };
+}
+
+export {
+  startTunnel
+};

package/dist/index.d.mts

@@ -104,7 +104,7 @@ interface LocalOptions {
     twilioToken?: string;
     openaiKey?: string;
     phoneNumber: string;
-    webhookUrl: string;
+    webhookUrl?: string;
     telephonyProvider?: 'twilio' | 'telnyx';
     telnyxKey?: string;
     telnyxConnectionId?: string;
@@ -148,6 +148,8 @@ type PipelineMessageHandler = (data: Record<string, unknown>) => Promise<string>
 interface ServeOptions {
     agent: AgentOptions;
     port?: number;
+    /** When true, start a cloudflared tunnel automatically (requires `cloudflared` npm package). */
+    tunnel?: boolean;
     onCallStart?: (data: Record<string, unknown>) => Promise<void>;
     onCallEnd?: (data: Record<string, unknown>) => Promise<void>;
     onTranscript?: (data: Record<string, unknown>) => Promise<void>;
@@ -206,6 +208,7 @@ declare class Patter {
     private readonly mode;
     private readonly localConfig;
     private embeddedServer;
+    private tunnelHandle;
     constructor(options: PatterOptions | LocalOptions);
     agent(opts: AgentOptions): AgentOptions;
     serve(opts: ServeOptions): Promise<void>;
@@ -863,4 +866,27 @@ declare function resample16kTo8k(pcm16k: Buffer): Buffer;
  */
 declare function resample24kTo16k(pcm24k: Buffer): Buffer;
 
-export { type Agent, type AgentOptions, AuthenticationError, type Call, type CallControl, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOptions, type CallRecord, type ConnectOptions, type CostBreakdown, type CreateAgentOptions, DEFAULT_PRICING, DeepgramSTT, ElevenLabsConvAIAdapter, ElevenLabsTTS, type Guardrail, type IncomingMessage, type LLMChunk, LLMLoop, type LLMProvider, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type MessageHandler, MetricsStore, OpenAILLMProvider, OpenAIRealtimeAdapter, OpenAITTS, Patter, PatterConnectionError, PatterError, type PatterOptions, type PhoneNumber, type PipelineMessageHandler, type ProviderPricing, ProvisionError, RemoteMessageHandler, type SSEEvent, type STTConfig, type ServeOptions, type TTSConfig, TestSession, type ToolDefinition, type TurnMetrics, WhisperSTT, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, deepgram, elevenlabs, getLogger, isRemoteUrl, isWebSocketUrl, makeAuthMiddleware, mergePricing, mountApi, mountDashboard, mulawToPcm16, openaiTts, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, setLogger, whisper };
+/**
+ * Built-in tunnel support via cloudflared.
+ *
+ * Spawns a Cloudflare Quick Tunnel that exposes a local port to the internet.
+ * Zero account required — uses Cloudflare's free trycloudflare.com service.
+ *
+ * Install: npm install cloudflared
+ */
+interface TunnelHandle {
+    /** Public hostname (no protocol), e.g. "random-name.trycloudflare.com" */
+    hostname: string;
+    /** Stop the tunnel process */
+    stop: () => void;
+}
+/**
+ * Start a cloudflared quick tunnel pointing to the given local port.
+ *
+ * @param port - Local port to tunnel to
+ * @param timeoutMs - How long to wait for the tunnel URL (default 30s)
+ * @returns A handle with the public hostname and a stop function
+ */
+declare function startTunnel(port: number, timeoutMs?: number): Promise<TunnelHandle>;
+
+export { type Agent, type AgentOptions, AuthenticationError, type Call, type CallControl, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOptions, type CallRecord, type ConnectOptions, type CostBreakdown, type CreateAgentOptions, DEFAULT_PRICING, DeepgramSTT, ElevenLabsConvAIAdapter, ElevenLabsTTS, type Guardrail, type IncomingMessage, type LLMChunk, LLMLoop, type LLMProvider, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type MessageHandler, MetricsStore, OpenAILLMProvider, OpenAIRealtimeAdapter, OpenAITTS, Patter, PatterConnectionError, PatterError, type PatterOptions, type PhoneNumber, type PipelineMessageHandler, type ProviderPricing, ProvisionError, RemoteMessageHandler, type SSEEvent, type STTConfig, type ServeOptions, type TTSConfig, TestSession, type ToolDefinition, type TunnelHandle, type TurnMetrics, WhisperSTT, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, deepgram, elevenlabs, getLogger, isRemoteUrl, isWebSocketUrl, makeAuthMiddleware, mergePricing, mountApi, mountDashboard, mulawToPcm16, openaiTts, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, setLogger, startTunnel, whisper };

package/dist/index.d.ts

@@ -104,7 +104,7 @@ interface LocalOptions {
     twilioToken?: string;
     openaiKey?: string;
     phoneNumber: string;
-    webhookUrl: string;
+    webhookUrl?: string;
     telephonyProvider?: 'twilio' | 'telnyx';
     telnyxKey?: string;
     telnyxConnectionId?: string;
@@ -148,6 +148,8 @@ type PipelineMessageHandler = (data: Record<string, unknown>) => Promise<string>
 interface ServeOptions {
     agent: AgentOptions;
     port?: number;
+    /** When true, start a cloudflared tunnel automatically (requires `cloudflared` npm package). */
+    tunnel?: boolean;
     onCallStart?: (data: Record<string, unknown>) => Promise<void>;
     onCallEnd?: (data: Record<string, unknown>) => Promise<void>;
     onTranscript?: (data: Record<string, unknown>) => Promise<void>;
@@ -206,6 +208,7 @@ declare class Patter {
     private readonly mode;
     private readonly localConfig;
     private embeddedServer;
+    private tunnelHandle;
     constructor(options: PatterOptions | LocalOptions);
     agent(opts: AgentOptions): AgentOptions;
     serve(opts: ServeOptions): Promise<void>;
@@ -863,4 +866,27 @@ declare function resample16kTo8k(pcm16k: Buffer): Buffer;
  */
 declare function resample24kTo16k(pcm24k: Buffer): Buffer;
 
-export { type Agent, type AgentOptions, AuthenticationError, type Call, type CallControl, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOptions, type CallRecord, type ConnectOptions, type CostBreakdown, type CreateAgentOptions, DEFAULT_PRICING, DeepgramSTT, ElevenLabsConvAIAdapter, ElevenLabsTTS, type Guardrail, type IncomingMessage, type LLMChunk, LLMLoop, type LLMProvider, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type MessageHandler, MetricsStore, OpenAILLMProvider, OpenAIRealtimeAdapter, OpenAITTS, Patter, PatterConnectionError, PatterError, type PatterOptions, type PhoneNumber, type PipelineMessageHandler, type ProviderPricing, ProvisionError, RemoteMessageHandler, type SSEEvent, type STTConfig, type ServeOptions, type TTSConfig, TestSession, type ToolDefinition, type TurnMetrics, WhisperSTT, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, deepgram, elevenlabs, getLogger, isRemoteUrl, isWebSocketUrl, makeAuthMiddleware, mergePricing, mountApi, mountDashboard, mulawToPcm16, openaiTts, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, setLogger, whisper };
+/**
+ * Built-in tunnel support via cloudflared.
+ *
+ * Spawns a Cloudflare Quick Tunnel that exposes a local port to the internet.
+ * Zero account required — uses Cloudflare's free trycloudflare.com service.
+ *
+ * Install: npm install cloudflared
+ */
+interface TunnelHandle {
+    /** Public hostname (no protocol), e.g. "random-name.trycloudflare.com" */
+    hostname: string;
+    /** Stop the tunnel process */
+    stop: () => void;
+}
+/**
+ * Start a cloudflared quick tunnel pointing to the given local port.
+ *
+ * @param port - Local port to tunnel to
+ * @param timeoutMs - How long to wait for the tunnel URL (default 30s)
+ * @returns A handle with the public hostname and a stop function
+ */
+declare function startTunnel(port: number, timeoutMs?: number): Promise<TunnelHandle>;
+
+export { type Agent, type AgentOptions, AuthenticationError, type Call, type CallControl, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOptions, type CallRecord, type ConnectOptions, type CostBreakdown, type CreateAgentOptions, DEFAULT_PRICING, DeepgramSTT, ElevenLabsConvAIAdapter, ElevenLabsTTS, type Guardrail, type IncomingMessage, type LLMChunk, LLMLoop, type LLMProvider, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type MessageHandler, MetricsStore, OpenAILLMProvider, OpenAIRealtimeAdapter, OpenAITTS, Patter, PatterConnectionError, PatterError, type PatterOptions, type PhoneNumber, type PipelineMessageHandler, type ProviderPricing, ProvisionError, RemoteMessageHandler, type SSEEvent, type STTConfig, type ServeOptions, type TTSConfig, TestSession, type ToolDefinition, type TunnelHandle, type TurnMetrics, WhisperSTT, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, deepgram, elevenlabs, getLogger, isRemoteUrl, isWebSocketUrl, makeAuthMiddleware, mergePricing, mountApi, mountDashboard, mulawToPcm16, openaiTts, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, setLogger, startTunnel, whisper };

package/dist/index.js

@@ -277,6 +277,55 @@ var init_llm_loop = __esm({
   }
 });
 
+// src/tunnel.ts
+var tunnel_exports = {};
+__export(tunnel_exports, {
+  startTunnel: () => startTunnel
+});
+async function startTunnel(port, timeoutMs = 3e4) {
+  let tunnelMod;
+  try {
+    tunnelMod = await import("cloudflared");
+  } catch {
+    throw new Error(
+      'Built-in tunnel requires the "cloudflared" package. Install it with:\n\n  npm install cloudflared\n\nOr provide your own webhookUrl instead of using tunnel: true.'
+    );
+  }
+  log.info("Starting tunnel to localhost:%d ...", port);
+  const result = tunnelMod.tunnel({
+    "--url": `http://localhost:${port}`
+  });
+  const tunnelUrl = await Promise.race([
+    result.url,
+    new Promise(
+      (_, reject) => setTimeout(() => reject(new Error(
+        `Tunnel failed to start within ${timeoutMs / 1e3}s. Check your internet connection or provide webhookUrl manually.`
+      )), timeoutMs)
+    )
+  ]);
+  const hostname = tunnelUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
+  log.info("Tunnel ready: https://%s", hostname);
+  result.connections.then(() => {
+    log.info("Tunnel connections established");
+  }).catch(() => {
+  });
+  return {
+    hostname,
+    stop: () => {
+      log.info("Stopping tunnel...");
+      result.stop();
+    }
+  };
+}
+var log;
+var init_tunnel = __esm({
+  "src/tunnel.ts"() {
+    "use strict";
+    init_logger();
+    log = getLogger();
+  }
+});
+
 // src/test-mode.ts
 var test_mode_exports = {};
 __export(test_mode_exports, {
@@ -296,19 +345,19 @@ var init_test_mode = __esm({
         const caller = "+15550000001";
         const callee = "+15550000002";
         const conversationHistory = [];
-        const log = getLogger();
-        log.info("");
-        log.info("=".repeat(60));
-        log.info("  PATTER TEST MODE");
-        log.info("=".repeat(60));
-        log.info(`  Agent: ${agent.model || "default"} / ${agent.voice || "default"}`);
-        log.info(`  Provider: ${agent.provider || "openai_realtime"}`);
-        log.info(`  Call ID: ${callId}`);
-        log.info(`  Caller: ${caller}  ->  Callee: ${callee}`);
-        log.info("-".repeat(60));
-        log.info("  Commands: /quit  /transfer <number>  /hangup  /history");
-        log.info("=".repeat(60));
-        log.info("");
+        const log2 = getLogger();
+        log2.info("");
+        log2.info("=".repeat(60));
+        log2.info("  PATTER TEST MODE");
+        log2.info("=".repeat(60));
+        log2.info(`  Agent: ${agent.model || "default"} / ${agent.voice || "default"}`);
+        log2.info(`  Provider: ${agent.provider || "openai_realtime"}`);
+        log2.info(`  Call ID: ${callId}`);
+        log2.info(`  Caller: ${caller}  ->  Callee: ${callee}`);
+        log2.info("-".repeat(60));
+        log2.info("  Commands: /quit  /transfer <number>  /hangup  /history");
+        log2.info("=".repeat(60));
+        log2.info("");
         if (onCallStart) {
           await onCallStart({
             call_id: callId,
@@ -318,8 +367,8 @@ var init_test_mode = __esm({
           });
         }
         if (agent.firstMessage) {
-          log.info(`  Agent: ${agent.firstMessage}`);
-          log.info("");
+          log2.info(`  Agent: ${agent.firstMessage}`);
+          log2.info("");
           conversationHistory.push({
             role: "assistant",
             text: agent.firstMessage,
@@ -350,11 +399,11 @@ var init_test_mode = __esm({
           callee,
           transfer: async (number) => {
             ended = true;
-            log.info(`  [Transfer -> ${number}]`);
+            log2.info(`  [Transfer -> ${number}]`);
           },
           hangup: async () => {
             ended = true;
-            log.info("  [Call ended by agent]");
+            log2.info("  [Call ended by agent]");
           }
         };
         void _callControl;
@@ -369,25 +418,25 @@ var init_test_mode = __esm({
             try {
               userInput = await askQuestion("  You: ");
             } catch {
-              log.info("\n  [Session ended]");
+              log2.info("\n  [Session ended]");
               break;
             }
             userInput = userInput.trim();
             if (!userInput) continue;
             if (userInput === "/quit") {
-              log.info("  [Session ended]");
+              log2.info("  [Session ended]");
               break;
             } else if (userInput === "/hangup") {
-              log.info("  [You hung up]");
+              log2.info("  [You hung up]");
               break;
             } else if (userInput.startsWith("/transfer ")) {
               const number = userInput.slice(10).trim();
-              log.info(`  [Transfer -> ${number}]`);
+              log2.info(`  [Transfer -> ${number}]`);
               break;
             } else if (userInput === "/history") {
               for (const entry of conversationHistory) {
                 const role = entry.role.charAt(0).toUpperCase() + entry.role.slice(1);
-                log.info(`    ${role}: ${entry.text}`);
+                log2.info(`    ${role}: ${entry.text}`);
               }
               continue;
             }
@@ -405,16 +454,16 @@ var init_test_mode = __esm({
                   history: [...conversationHistory]
                 });
                 if (responseText) {
-                  log.info(`  Agent: ${responseText}`);
+                  log2.info(`  Agent: ${responseText}`);
                   conversationHistory.push({
                     role: "assistant",
                     text: responseText,
                     timestamp: Date.now()
                   });
-                  log.info("");
+                  log2.info("");
                 }
               } catch (e) {
-                log.error(`  [Error: ${String(e)}]`);
+                log2.error(`  [Error: ${String(e)}]`);
               }
             } else if (llmLoop) {
               const callCtx = { call_id: callId, caller, callee };
@@ -424,7 +473,7 @@ var init_test_mode = __esm({
                 parts.push(token);
                 process.stdout.write(token);
               }
-              log.info("");
+              log2.info("");
               const responseText = parts.join("");
               if (responseText) {
                 conversationHistory.push({
@@ -433,9 +482,9 @@ var init_test_mode = __esm({
                   timestamp: Date.now()
                 });
               }
-              log.info("");
+              log2.info("");
             } else {
-              log.info("  [No onMessage handler or LLM loop configured]");
+              log2.info("  [No onMessage handler or LLM loop configured]");
             }
             if (ended) break;
           }
@@ -499,6 +548,7 @@ __export(index_exports, {
   resample24kTo16k: () => resample24kTo16k,
   resample8kTo16k: () => resample8kTo16k,
   setLogger: () => setLogger,
+  startTunnel: () => startTunnel,
   whisper: () => whisper
 });
 module.exports = __toCommonJS(index_exports);
@@ -1623,10 +1673,10 @@ function esc(s) {
   if (!s) return '';
   return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;').replace(/'/g,'&#39;');
 }
-function fmt\\$(v) { return v >= 0.01 ? '$'+v.toFixed(4) : v > 0 ? '$'+v.toFixed(6) : '$0.00'; }
-function fmtMs(v) { return v > 0 ? Math.round(v)+'ms' : '-'; }
+function fmt$(v) { return v >= 0.01 ? '$'+v.toFixed(4) : v > 0 ? '$'+v.toFixed(6) : '$0.00'; }
+function fmtMs(v) { return v != null && v >= 0 ? Math.round(v)+'ms' : '-'; }
 function fmtDur(s) {
-  if (!s) return '-';
+  if (s == null || s < 0) return '-';
   if (s < 60) return Math.round(s)+'s';
   return Math.floor(s/60)+'m '+Math.round(s%60)+'s';
 }
@@ -1641,10 +1691,10 @@ async function refreshAggregates() {
   const d = await fetchJSON('/api/dashboard/aggregates');
   $('#stat-total').textContent = d.total_calls;
   $('#stat-active').textContent = d.active_calls;
-  $('#stat-cost').textContent = fmt\\$(d.total_cost);
+  $('#stat-cost').textContent = fmt$(d.total_cost);
   const cb = d.cost_breakdown;
   $('#stat-cost-breakdown').textContent =
-    'STT '+fmt\\$(cb.stt)+' | LLM '+fmt\\$(cb.llm)+' | TTS '+fmt\\$(cb.tts)+' | Tel '+fmt\\$(cb.telephony);
+    'STT '+fmt$(cb.stt)+' | LLM '+fmt$(cb.llm)+' | TTS '+fmt$(cb.tts)+' | Tel '+fmt$(cb.telephony);
   $('#stat-duration').textContent = fmtDur(d.avg_duration);
   $('#stat-latency').textContent = fmtMs(d.avg_latency_ms);
 }
@@ -1669,7 +1719,7 @@ async function refreshCalls() {
       '<td>'+(esc(c.caller) || '-')+' &rarr; '+(esc(c.callee) || '-')+'</td>'+
       '<td>'+fmtDur(m.duration_seconds)+'</td>'+
       '<td><span class="badge '+modeClass+'">'+esc(mode)+'</span></td>'+
-      '<td class="cost">'+fmt\\$(cost.total || 0)+'</td>'+
+      '<td class="cost">'+fmt$(cost.total || 0)+'</td>'+
       '<td class="latency">'+fmtMs(lat.total_ms || 0)+'</td>'+
       '<td>'+turns+'</td></tr>';
   }).join('');
@@ -1723,12 +1773,12 @@ async function showCall(callId) {
     '</div>'+
     '<div class="detail-card">'+
       '<h3>Cost Breakdown</h3>'+
-      '<div class="detail-row"><span class="k">STT</span><span class="cost">'+fmt\\$(cost.stt || 0)+'</span></div>'+
-      '<div class="detail-row"><span class="k">LLM</span><span class="cost">'+fmt\\$(cost.llm || 0)+'</span></div>'+
-      '<div class="detail-row"><span class="k">TTS</span><span class="cost">'+fmt\\$(cost.tts || 0)+'</span></div>'+
-      '<div class="detail-row"><span class="k">Telephony</span><span class="cost">'+fmt\\$(cost.telephony || 0)+'</span></div>'+
+      '<div class="detail-row"><span class="k">STT</span><span class="cost">'+fmt$(cost.stt || 0)+'</span></div>'+
+      '<div class="detail-row"><span class="k">LLM</span><span class="cost">'+fmt$(cost.llm || 0)+'</span></div>'+
+      '<div class="detail-row"><span class="k">TTS</span><span class="cost">'+fmt$(cost.tts || 0)+'</span></div>'+
+      '<div class="detail-row"><span class="k">Telephony</span><span class="cost">'+fmt$(cost.telephony || 0)+'</span></div>'+
       '<div class="detail-row" style="border-top:1px solid var(--border);padding-top:6px;margin-top:4px">'+
-        '<span class="k" style="font-weight:600">Total</span><span class="cost" style="font-weight:700">'+fmt\\$(cost.total || 0)+'</span>'+
+        '<span class="k" style="font-weight:600">Total</span><span class="cost" style="font-weight:700">'+fmt$(cost.total || 0)+'</span>'+
       '</div>'+
       '<h3 style="margin-top:14px">Latency (avg / p95)</h3>'+
       '<div class="detail-row"><span class="k">STT</span><span class="latency">'+fmtMs(latAvg.stt_ms)+' / '+fmtMs(latP95.stt_ms)+'</span></div>'+
@@ -3387,7 +3437,7 @@ var TelnyxBridge = class {
 };
 var GRACEFUL_SHUTDOWN_TIMEOUT_MS = 1e4;
 var EmbeddedServer = class {
-  constructor(config, agent, onCallStart, onCallEnd, onTranscript, onMessage, recording = false, voicemailMessage = "", onMetrics, pricingOverrides, dashboard = false, dashboardToken = "") {
+  constructor(config, agent, onCallStart, onCallEnd, onTranscript, onMessage, recording = false, voicemailMessage = "", onMetrics, pricingOverrides, dashboard = true, dashboardToken = "") {
     this.config = config;
     this.agent = agent;
     this.onCallStart = onCallStart;
@@ -3795,15 +3845,13 @@ var Patter = class {
   mode;
   localConfig;
   embeddedServer = null;
+  tunnelHandle = null;
   constructor(options) {
     if ("mode" in options && options.mode === "local") {
       const local = options;
       if (!local.phoneNumber) {
         throw new Error("Local mode requires phoneNumber");
       }
-      if (!local.webhookUrl) {
-        throw new Error("Local mode requires webhookUrl (e.g., your ngrok URL)");
-      }
       if (!local.twilioSid && !local.telnyxKey) {
         throw new Error("Local mode requires twilioSid or telnyxKey");
       }
@@ -3867,13 +3915,28 @@ var Patter = class {
     if (opts.agent.provider && !validProviders.includes(opts.agent.provider)) {
       throw new Error(`agent.provider must be one of: ${validProviders.join(", ")}`);
     }
+    let webhookUrl = this.localConfig.webhookUrl ?? "";
+    const port = opts.port ?? 8e3;
+    if (opts.tunnel && webhookUrl) {
+      throw new Error("Cannot use both tunnel: true and webhookUrl. Pick one.");
+    }
+    if (opts.tunnel) {
+      const { startTunnel: startTunnel2 } = await Promise.resolve().then(() => (init_tunnel(), tunnel_exports));
+      this.tunnelHandle = await startTunnel2(port);
+      webhookUrl = this.tunnelHandle.hostname;
+    }
+    if (!webhookUrl) {
+      throw new Error(
+        "No webhookUrl configured. Either:\n  - Pass webhookUrl in the Patter constructor\n  - Use tunnel: true in serve() to auto-create a tunnel"
+      );
+    }
     this.embeddedServer = new EmbeddedServer(
       {
         twilioSid: this.localConfig.twilioSid,
         twilioToken: this.localConfig.twilioToken,
         openaiKey: this.localConfig.openaiKey,
         phoneNumber: this.localConfig.phoneNumber,
-        webhookUrl: this.localConfig.webhookUrl,
+        webhookUrl,
         telephonyProvider: this.localConfig.telephonyProvider,
         telnyxKey: this.localConfig.telnyxKey,
         telnyxConnectionId: this.localConfig.telnyxConnectionId,
@@ -3888,10 +3951,10 @@ var Patter = class {
       opts.voicemailMessage ?? "",
       opts.onMetrics,
       opts.pricing,
-      opts.dashboard ?? false,
+      opts.dashboard ?? true,
       opts.dashboardToken ?? ""
     );
-    await this.embeddedServer.start(opts.port ?? 8e3);
+    await this.embeddedServer.start(port);
   }
   async test(opts) {
     if (this.mode !== "local") {
@@ -4011,6 +4074,14 @@ var Patter = class {
     );
   }
   async disconnect() {
+    if (this.tunnelHandle) {
+      this.tunnelHandle.stop();
+      this.tunnelHandle = null;
+    }
+    if (this.embeddedServer) {
+      await this.embeddedServer.stop();
+      this.embeddedServer = null;
+    }
     await this.connection.disconnect();
   }
   // === Agent Management ===
@@ -4241,6 +4312,9 @@ function resample24kTo16k(pcm24k) {
   }
   return out;
 }
+
+// src/index.ts
+init_tunnel();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,
@@ -4283,5 +4357,6 @@ function resample24kTo16k(pcm24k) {
   resample24kTo16k,
   resample8kTo16k,
   setLogger,
+  startTunnel,
   whisper
 });

package/dist/index.mjs

@@ -1,10 +1,15 @@
+import {
+  startTunnel
+} from "./chunk-VNU4GNW3.mjs";
 import {
   LLMLoop,
   OpenAILLMProvider,
-  TestSession,
+  TestSession
+} from "./chunk-TAATEHKF.mjs";
+import {
   getLogger,
   setLogger
-} from "./chunk-KB57IV4K.mjs";
+} from "./chunk-FMNRCP5X.mjs";
 
 // src/connection.ts
 import WebSocket from "ws";
@@ -1122,10 +1127,10 @@ function esc(s) {
   if (!s) return '';
   return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;').replace(/'/g,'&#39;');
 }
-function fmt\\$(v) { return v >= 0.01 ? '$'+v.toFixed(4) : v > 0 ? '$'+v.toFixed(6) : '$0.00'; }
-function fmtMs(v) { return v > 0 ? Math.round(v)+'ms' : '-'; }
+function fmt$(v) { return v >= 0.01 ? '$'+v.toFixed(4) : v > 0 ? '$'+v.toFixed(6) : '$0.00'; }
+function fmtMs(v) { return v != null && v >= 0 ? Math.round(v)+'ms' : '-'; }
 function fmtDur(s) {
-  if (!s) return '-';
+  if (s == null || s < 0) return '-';
   if (s < 60) return Math.round(s)+'s';
   return Math.floor(s/60)+'m '+Math.round(s%60)+'s';
 }
@@ -1140,10 +1145,10 @@ async function refreshAggregates() {
   const d = await fetchJSON('/api/dashboard/aggregates');
   $('#stat-total').textContent = d.total_calls;
   $('#stat-active').textContent = d.active_calls;
-  $('#stat-cost').textContent = fmt\\$(d.total_cost);
+  $('#stat-cost').textContent = fmt$(d.total_cost);
   const cb = d.cost_breakdown;
   $('#stat-cost-breakdown').textContent =
-    'STT '+fmt\\$(cb.stt)+' | LLM '+fmt\\$(cb.llm)+' | TTS '+fmt\\$(cb.tts)+' | Tel '+fmt\\$(cb.telephony);
+    'STT '+fmt$(cb.stt)+' | LLM '+fmt$(cb.llm)+' | TTS '+fmt$(cb.tts)+' | Tel '+fmt$(cb.telephony);
   $('#stat-duration').textContent = fmtDur(d.avg_duration);
   $('#stat-latency').textContent = fmtMs(d.avg_latency_ms);
 }
@@ -1168,7 +1173,7 @@ async function refreshCalls() {
       '<td>'+(esc(c.caller) || '-')+' &rarr; '+(esc(c.callee) || '-')+'</td>'+
       '<td>'+fmtDur(m.duration_seconds)+'</td>'+
       '<td><span class="badge '+modeClass+'">'+esc(mode)+'</span></td>'+
-      '<td class="cost">'+fmt\\$(cost.total || 0)+'</td>'+
+      '<td class="cost">'+fmt$(cost.total || 0)+'</td>'+
       '<td class="latency">'+fmtMs(lat.total_ms || 0)+'</td>'+
       '<td>'+turns+'</td></tr>';
   }).join('');
@@ -1222,12 +1227,12 @@ async function showCall(callId) {
     '</div>'+
     '<div class="detail-card">'+
       '<h3>Cost Breakdown</h3>'+
-      '<div class="detail-row"><span class="k">STT</span><span class="cost">'+fmt\\$(cost.stt || 0)+'</span></div>'+
-      '<div class="detail-row"><span class="k">LLM</span><span class="cost">'+fmt\\$(cost.llm || 0)+'</span></div>'+
-      '<div class="detail-row"><span class="k">TTS</span><span class="cost">'+fmt\\$(cost.tts || 0)+'</span></div>'+
-      '<div class="detail-row"><span class="k">Telephony</span><span class="cost">'+fmt\\$(cost.telephony || 0)+'</span></div>'+
+      '<div class="detail-row"><span class="k">STT</span><span class="cost">'+fmt$(cost.stt || 0)+'</span></div>'+
+      '<div class="detail-row"><span class="k">LLM</span><span class="cost">'+fmt$(cost.llm || 0)+'</span></div>'+
+      '<div class="detail-row"><span class="k">TTS</span><span class="cost">'+fmt$(cost.tts || 0)+'</span></div>'+
+      '<div class="detail-row"><span class="k">Telephony</span><span class="cost">'+fmt$(cost.telephony || 0)+'</span></div>'+
       '<div class="detail-row" style="border-top:1px solid var(--border);padding-top:6px;margin-top:4px">'+
-        '<span class="k" style="font-weight:600">Total</span><span class="cost" style="font-weight:700">'+fmt\\$(cost.total || 0)+'</span>'+
+        '<span class="k" style="font-weight:600">Total</span><span class="cost" style="font-weight:700">'+fmt$(cost.total || 0)+'</span>'+
       '</div>'+
       '<h3 style="margin-top:14px">Latency (avg / p95)</h3>'+
       '<div class="detail-row"><span class="k">STT</span><span class="latency">'+fmtMs(latAvg.stt_ms)+' / '+fmtMs(latP95.stt_ms)+'</span></div>'+
@@ -2879,7 +2884,7 @@ var TelnyxBridge = class {
 };
 var GRACEFUL_SHUTDOWN_TIMEOUT_MS = 1e4;
 var EmbeddedServer = class {
-  constructor(config, agent, onCallStart, onCallEnd, onTranscript, onMessage, recording = false, voicemailMessage = "", onMetrics, pricingOverrides, dashboard = false, dashboardToken = "") {
+  constructor(config, agent, onCallStart, onCallEnd, onTranscript, onMessage, recording = false, voicemailMessage = "", onMetrics, pricingOverrides, dashboard = true, dashboardToken = "") {
     this.config = config;
     this.agent = agent;
     this.onCallStart = onCallStart;
@@ -3287,15 +3292,13 @@ var Patter = class {
   mode;
   localConfig;
   embeddedServer = null;
+  tunnelHandle = null;
   constructor(options) {
     if ("mode" in options && options.mode === "local") {
       const local = options;
       if (!local.phoneNumber) {
         throw new Error("Local mode requires phoneNumber");
       }
-      if (!local.webhookUrl) {
-        throw new Error("Local mode requires webhookUrl (e.g., your ngrok URL)");
-      }
       if (!local.twilioSid && !local.telnyxKey) {
         throw new Error("Local mode requires twilioSid or telnyxKey");
       }
@@ -3359,13 +3362,28 @@ var Patter = class {
     if (opts.agent.provider && !validProviders.includes(opts.agent.provider)) {
       throw new Error(`agent.provider must be one of: ${validProviders.join(", ")}`);
     }
+    let webhookUrl = this.localConfig.webhookUrl ?? "";
+    const port = opts.port ?? 8e3;
+    if (opts.tunnel && webhookUrl) {
+      throw new Error("Cannot use both tunnel: true and webhookUrl. Pick one.");
+    }
+    if (opts.tunnel) {
+      const { startTunnel: startTunnel2 } = await import("./tunnel-HYSU7EF2.mjs");
+      this.tunnelHandle = await startTunnel2(port);
+      webhookUrl = this.tunnelHandle.hostname;
+    }
+    if (!webhookUrl) {
+      throw new Error(
+        "No webhookUrl configured. Either:\n  - Pass webhookUrl in the Patter constructor\n  - Use tunnel: true in serve() to auto-create a tunnel"
+      );
+    }
     this.embeddedServer = new EmbeddedServer(
       {
         twilioSid: this.localConfig.twilioSid,
         twilioToken: this.localConfig.twilioToken,
         openaiKey: this.localConfig.openaiKey,
         phoneNumber: this.localConfig.phoneNumber,
-        webhookUrl: this.localConfig.webhookUrl,
+        webhookUrl,
         telephonyProvider: this.localConfig.telephonyProvider,
         telnyxKey: this.localConfig.telnyxKey,
         telnyxConnectionId: this.localConfig.telnyxConnectionId,
@@ -3380,16 +3398,16 @@ var Patter = class {
       opts.voicemailMessage ?? "",
       opts.onMetrics,
       opts.pricing,
-      opts.dashboard ?? false,
+      opts.dashboard ?? true,
       opts.dashboardToken ?? ""
     );
-    await this.embeddedServer.start(opts.port ?? 8e3);
+    await this.embeddedServer.start(port);
   }
   async test(opts) {
     if (this.mode !== "local") {
       throw new Error("test() is only available in local mode");
     }
-    const { TestSession: TestSession2 } = await import("./test-mode-RTQAK5CP.mjs");
+    const { TestSession: TestSession2 } = await import("./test-mode-JMXZSAJS.mjs");
     const session = new TestSession2();
     await session.run({
       agent: opts.agent,
@@ -3503,6 +3521,14 @@ var Patter = class {
     );
   }
   async disconnect() {
+    if (this.tunnelHandle) {
+      this.tunnelHandle.stop();
+      this.tunnelHandle = null;
+    }
+    if (this.embeddedServer) {
+      await this.embeddedServer.stop();
+      this.embeddedServer = null;
+    }
     await this.connection.disconnect();
   }
   // === Agent Management ===
@@ -3769,5 +3795,6 @@ export {
   resample24kTo16k,
   resample8kTo16k,
   setLogger,
+  startTunnel,
   whisper
 };

package/dist/test-mode-JMXZSAJS.mjs

@@ -0,0 +1,7 @@
+import {
+  TestSession
+} from "./chunk-TAATEHKF.mjs";
+import "./chunk-FMNRCP5X.mjs";
+export {
+  TestSession
+};

package/dist/tunnel-HYSU7EF2.mjs

@@ -0,0 +1,7 @@
+import {
+  startTunnel
+} from "./chunk-VNU4GNW3.mjs";
+import "./chunk-FMNRCP5X.mjs";
+export {
+  startTunnel
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getpatter",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Connect AI agents to phone numbers with 10 lines of code",
   "license": "MIT",
   "author": {
@@ -54,13 +54,19 @@
     "express": "^5.2.1",
     "ws": "^8.18.0"
   },
+  "optionalDependencies": {
+    "cloudflared": "^1.0.0"
+  },
   "devDependencies": {
+    "@playwright/test": "^1.59.1",
     "@types/express": "^5.0.6",
     "@types/ws": "^8.5.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "playwright": "^1.59.1",
     "tsup": "^8.0.0",
     "tsx": "^4.21.0",
     "typescript": "^5.4.0",
-    "vitest": "^2.0.0"
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=18.0.0"

package/dist/test-mode-RTQAK5CP.mjs

@@ -1,6 +0,0 @@
-import {
-  TestSession
-} from "./chunk-KB57IV4K.mjs";
-export {
-  TestSession
-};