niahere 0.3.0 → 0.3.2

package/src/channels/twilio/rest.ts

@@ -0,0 +1,133 @@
+/**
+ * Minimal Twilio REST API helpers shared by all Twilio-based channels
+ * (voice, SMS, WhatsApp). No SDK — keeps dependency surface small and
+ * the helpers easy to read.
+ *
+ * Auth: Basic with `${authSid}:${authSecret}`. authSid can be either an
+ * Account SID (AC…) or an API Key SID (SK…); Twilio resolves both. The
+ * URL path always uses the Account SID — when using an API Key, pass
+ * `accountSid` separately.
+ */
+
+const TWILIO_BASE = "https://api.twilio.com/2010-04-01";
+
+export interface TwilioCreds {
+  /** Account SID (AC…) — required for the URL path. */
+  accountSid: string;
+  /** SID used for Basic-auth username. Can be the same Account SID or an API Key SID (SK…). */
+  authSid: string;
+  /** Basic-auth password (Account Auth Token, or API Key Secret if authSid is SK…). */
+  authSecret: string;
+}
+
+function basicAuth({ authSid, authSecret }: TwilioCreds): string {
+  return `Basic ${Buffer.from(`${authSid}:${authSecret}`).toString("base64")}`;
+}
+
+function accountUrl({ accountSid }: TwilioCreds, suffix: string): string {
+  return `${TWILIO_BASE}/Accounts/${encodeURIComponent(accountSid)}${suffix}`;
+}
+
+async function twilioPost<T = unknown>(creds: TwilioCreds, suffix: string, body: URLSearchParams): Promise<T> {
+  const resp = await fetch(accountUrl(creds, suffix), {
+    method: "POST",
+    headers: { Authorization: basicAuth(creds), "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new Error(`Twilio ${suffix} failed: ${resp.status} ${text}`);
+  }
+  return (await resp.json()) as T;
+}
+
+// --- Voice ---
+
+export interface PlaceCallOpts extends TwilioCreds {
+  to: string;
+  from: string;
+  twimlUrl: string;
+  statusCallbackUrl?: string;
+  maxDurationSec?: number;
+}
+
+export interface PlaceCallResult {
+  callSid: string;
+  status: string;
+}
+
+export async function placeCall(opts: PlaceCallOpts): Promise<PlaceCallResult> {
+  const body = new URLSearchParams({ To: opts.to, From: opts.from, Url: opts.twimlUrl, Method: "POST" });
+  if (opts.statusCallbackUrl) {
+    body.set("StatusCallback", opts.statusCallbackUrl);
+    body.set("StatusCallbackMethod", "POST");
+    body.append("StatusCallbackEvent", "initiated");
+    body.append("StatusCallbackEvent", "answered");
+    body.append("StatusCallbackEvent", "completed");
+  }
+  if (opts.maxDurationSec && opts.maxDurationSec > 0) {
+    body.set("TimeLimit", String(opts.maxDurationSec));
+  }
+  const data = await twilioPost<{ sid: string; status: string }>(opts, "/Calls.json", body);
+  return { callSid: data.sid, status: data.status };
+}
+
+export async function updateCallUrl(opts: TwilioCreds & { callSid: string; url: string }): Promise<void> {
+  const body = new URLSearchParams({ Url: opts.url, Method: "POST" });
+  await twilioPost(opts, `/Calls/${encodeURIComponent(opts.callSid)}.json`, body);
+}
+
+export async function hangupCall(opts: TwilioCreds & { callSid: string }): Promise<void> {
+  const body = new URLSearchParams({ Status: "completed" });
+  await twilioPost(opts, `/Calls/${encodeURIComponent(opts.callSid)}.json`, body);
+}
+
+// --- Messages (SMS / WhatsApp) ---
+
+export interface SendMessageOpts extends TwilioCreds {
+  /** E.164 for SMS, "whatsapp:+E164" for WhatsApp. */
+  to: string;
+  from: string;
+  body: string;
+  statusCallbackUrl?: string;
+  /** Optional MMS media URLs. */
+  mediaUrl?: string[];
+}
+
+export interface SendMessageResult {
+  messageSid: string;
+  status: string;
+}
+
+export async function sendMessage(opts: SendMessageOpts): Promise<SendMessageResult> {
+  const body = new URLSearchParams({ To: opts.to, From: opts.from, Body: opts.body });
+  if (opts.statusCallbackUrl) body.set("StatusCallback", opts.statusCallbackUrl);
+  if (opts.mediaUrl) {
+    for (const u of opts.mediaUrl) body.append("MediaUrl", u);
+  }
+  const data = await twilioPost<{ sid: string; status: string }>(opts, "/Messages.json", body);
+  return { messageSid: data.sid, status: data.status };
+}
+
+// --- Phone number config (update inbound webhook on a number) ---
+
+export async function updateIncomingPhoneNumber(
+  opts: TwilioCreds & {
+    phoneNumberSid: string;
+    voiceUrl?: string;
+    voiceMethod?: "GET" | "POST";
+    smsUrl?: string;
+    smsMethod?: "GET" | "POST";
+    statusCallback?: string;
+    statusCallbackMethod?: "GET" | "POST";
+  },
+): Promise<void> {
+  const body = new URLSearchParams();
+  if (opts.voiceUrl !== undefined) body.set("VoiceUrl", opts.voiceUrl);
+  if (opts.voiceMethod) body.set("VoiceMethod", opts.voiceMethod);
+  if (opts.smsUrl !== undefined) body.set("SmsUrl", opts.smsUrl);
+  if (opts.smsMethod) body.set("SmsMethod", opts.smsMethod);
+  if (opts.statusCallback !== undefined) body.set("StatusCallback", opts.statusCallback);
+  if (opts.statusCallbackMethod) body.set("StatusCallbackMethod", opts.statusCallbackMethod);
+  await twilioPost(opts, `/IncomingPhoneNumbers/${encodeURIComponent(opts.phoneNumberSid)}.json`, body);
+}

package/src/channels/twilio/server.ts

@@ -0,0 +1,255 @@
+/**
+ * Shared Bun HTTP + WebSocket server for all Twilio-based channels
+ * (voice, SMS, WhatsApp). Channels register routes during their start();
+ * the server lazily binds the port on first start() and stays bound until
+ * stop() is called. Idempotent in both directions.
+ *
+ * Cross-cutting features applied per route:
+ *   - X-Twilio-Signature HMAC-SHA1 validation (default on for /twilio/*).
+ *   - Dedup based on a configurable form field (e.g. MessageSid, CallSid).
+ *   - Per-key rate limit (e.g. From), to bound cost when a stranger
+ *     guesses the shared WhatsApp Sandbox join code.
+ *
+ * Channels keep their domain logic; the server keeps the wiring.
+ */
+import type { Server, ServerWebSocket } from "bun";
+import { log } from "../../utils/log";
+import { validateTwilioSignature } from "./signature";
+import { Dedup } from "./dedup";
+import { RateLimiter } from "./rate-limit";
+import { cacheMedia, readCachedMedia } from "./media-cache";
+
+export interface TwilioRequestContext {
+  /** Form-decoded body. */
+  params: Record<string, string>;
+}
+
+export type HttpHandler = (req: Request, ctx: TwilioRequestContext) => Promise<Response> | Response;
+
+export interface HttpRouteOpts {
+  /** Validate X-Twilio-Signature. Defaults to true. Set false for /healthz etc. */
+  verifySignature?: boolean;
+  /** If set, dedup based on this form field. Repeated values within the dedup window 204 silently. */
+  dedupOn?: string;
+  /** If set, rate-limit based on this form field. Over-limit 429s. */
+  rateLimitOn?: string;
+}
+
+export interface WsConnectionData {
+  path: string;
+  channel: Record<string, unknown>;
+}
+
+export interface WsRoute {
+  /** Called when a frame arrives. */
+  onMessage(ws: ServerWebSocket<WsConnectionData>, data: string): void;
+  /** Called when the connection closes. Optional. */
+  onClose?(ws: ServerWebSocket<WsConnectionData>): void;
+}
+
+export interface ServerConfig {
+  port: number;
+  /** Public base URL the server is reachable at (e.g. https://nia.example.com). No trailing slash. */
+  publicBaseUrl: string | null;
+  /** Account Auth Token used to verify X-Twilio-Signature. */
+  signingToken: string | null;
+}
+
+export interface TwilioServer {
+  configure(cfg: ServerConfig): void;
+  registerHttp(path: string, handler: HttpHandler, opts?: HttpRouteOpts): void;
+  registerWs(path: string, route: WsRoute): void;
+  /** Mark a key as exempt from rate-limiting (e.g. the owner's number). */
+  exemptFromRateLimit(key: string): void;
+  start(): Promise<void>;
+  stop(): void;
+  /** Build the WSS URL for a registered path, using publicBaseUrl. */
+  buildWssUrl(path: string): string;
+  /** Build the HTTPS URL for a registered path, using publicBaseUrl. */
+  buildHttpUrl(path: string): string;
+  /**
+   * Write a media payload to the on-disk outbound cache and return its
+   * publicly-reachable URL. Twilio fetches the URL when delivering MMS /
+   * WhatsApp media. Requires publicBaseUrl to be configured.
+   */
+  serveMedia(buffer: Uint8Array, mime: string, ext?: string): Promise<string>;
+}
+
+class TwilioServerImpl implements TwilioServer {
+  private cfg: ServerConfig | null = null;
+  private bunServer: Server<WsConnectionData> | null = null;
+  private readonly httpRoutes = new Map<string, { handler: HttpHandler; opts: HttpRouteOpts }>();
+  private readonly wsRoutes = new Map<string, WsRoute>();
+  private readonly dedup = new Dedup();
+  private readonly rateLimit = new RateLimiter();
+  private readonly rateLimitExempt = new Set<string>();
+
+  configure(cfg: ServerConfig): void {
+    this.cfg = cfg;
+  }
+
+  registerHttp(path: string, handler: HttpHandler, opts: HttpRouteOpts = {}): void {
+    if (this.httpRoutes.has(path)) {
+      log.warn({ path }, "twilio-server: overwriting existing HTTP route");
+    }
+    this.httpRoutes.set(path, { handler, opts });
+  }
+
+  registerWs(path: string, route: WsRoute): void {
+    if (this.wsRoutes.has(path)) {
+      log.warn({ path }, "twilio-server: overwriting existing WS route");
+    }
+    this.wsRoutes.set(path, route);
+  }
+
+  exemptFromRateLimit(key: string): void {
+    this.rateLimitExempt.add(key);
+    this.rateLimit.exempt(key);
+  }
+
+  async start(): Promise<void> {
+    if (this.bunServer) return;
+    if (!this.cfg) throw new Error("twilio-server: configure() must be called before start()");
+    const cfg = this.cfg;
+    const self = this;
+
+    this.bunServer = Bun.serve<WsConnectionData, never>({
+      port: cfg.port,
+      async fetch(req, server) {
+        const path = new URL(req.url).pathname;
+
+        if (path === "/healthz") return new Response("ok", { status: 200 });
+        if (path === "/twilio/health") return new Response("ok", { status: 200 });
+
+        if (req.method === "GET" && path.startsWith("/twilio/media/")) {
+          return await self.handleMedia(path.slice("/twilio/media/".length));
+        }
+
+        const wsRoute = self.wsRoutes.get(path);
+        if (wsRoute) {
+          const ok = server.upgrade(req, { data: { path, channel: {} } });
+          return ok ? undefined : new Response("expected websocket", { status: 400 });
+        }
+
+        const httpRoute = self.httpRoutes.get(path);
+        if (!httpRoute) return new Response("not found", { status: 404 });
+
+        return await self.handleHttp(req, httpRoute);
+      },
+      websocket: {
+        message(ws, message) {
+          const route = self.wsRoutes.get(ws.data.path);
+          if (!route) {
+            try {
+              ws.close();
+            } catch {}
+            return;
+          }
+          const data = typeof message === "string" ? message : new TextDecoder().decode(message);
+          route.onMessage(ws, data);
+        },
+        close(ws) {
+          const route = self.wsRoutes.get(ws.data.path);
+          route?.onClose?.(ws);
+        },
+      },
+    });
+
+    log.info({ port: cfg.port, publicBaseUrl: cfg.publicBaseUrl }, "twilio-server: started");
+  }
+
+  stop(): void {
+    if (!this.bunServer) return;
+    this.bunServer.stop(true);
+    this.bunServer = null;
+    log.info("twilio-server: stopped");
+  }
+
+  buildWssUrl(path: string): string {
+    if (!this.cfg?.publicBaseUrl) throw new Error("twilio-server: publicBaseUrl not configured");
+    return this.cfg.publicBaseUrl.replace(/^http/, "ws") + path;
+  }
+
+  buildHttpUrl(path: string): string {
+    if (!this.cfg?.publicBaseUrl) throw new Error("twilio-server: publicBaseUrl not configured");
+    return this.cfg.publicBaseUrl + path;
+  }
+
+  async serveMedia(buffer: Uint8Array, mime: string, ext?: string): Promise<string> {
+    if (!this.cfg?.publicBaseUrl) {
+      throw new Error("twilio-server: serveMedia requires channels.twilio.public_base_url to be configured");
+    }
+    const { filename } = await cacheMedia(buffer, mime, ext);
+    return `${this.cfg.publicBaseUrl}/twilio/media/${filename}`;
+  }
+
+  private async handleMedia(filename: string): Promise<Response> {
+    const hit = await readCachedMedia(filename);
+    if (!hit) return new Response("not found", { status: 404 });
+    return new Response(new Uint8Array(hit.buffer), {
+      status: 200,
+      headers: {
+        "Content-Type": hit.mime,
+        "Cache-Control": "private, max-age=300",
+      },
+    });
+  }
+
+  private async handleHttp(req: Request, route: { handler: HttpHandler; opts: HttpRouteOpts }): Promise<Response> {
+    if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+
+    const params = await this.readForm(req);
+
+    if (route.opts.verifySignature !== false) {
+      if (!this.verifySignature(req, params)) {
+        log.warn({ path: new URL(req.url).pathname }, "twilio-server: signature check failed");
+        return new Response("invalid signature", { status: 403 });
+      }
+    }
+
+    if (route.opts.rateLimitOn) {
+      const key = params[route.opts.rateLimitOn];
+      if (key && !this.rateLimitExempt.has(key) && !this.rateLimit.allow(key)) {
+        log.warn({ key, field: route.opts.rateLimitOn }, "twilio-server: rate limit exceeded");
+        return new Response("too many requests", { status: 429 });
+      }
+    }
+
+    if (route.opts.dedupOn) {
+      const id = params[route.opts.dedupOn];
+      if (id && this.dedup.check(id)) {
+        log.debug({ id, field: route.opts.dedupOn }, "twilio-server: duplicate webhook dropped");
+        return new Response("", { status: 204 });
+      }
+    }
+
+    return await route.handler(req, { params });
+  }
+
+  private async readForm(req: Request): Promise<Record<string, string>> {
+    const body = await req.text();
+    const params: Record<string, string> = {};
+    for (const [k, v] of new URLSearchParams(body)) params[k] = v;
+    return params;
+  }
+
+  private verifySignature(req: Request, params: Record<string, string>): boolean {
+    const token = this.cfg?.signingToken;
+    if (!token) return false;
+    const signature = req.headers.get("X-Twilio-Signature") || "";
+    const fullUrl = this.cfg?.publicBaseUrl ? `${this.cfg.publicBaseUrl}${new URL(req.url).pathname}` : req.url;
+    return validateTwilioSignature({ authToken: token, fullUrl, params, signature });
+  }
+}
+
+let _instance: TwilioServer | null = null;
+
+export function getTwilioServer(): TwilioServer {
+  if (!_instance) _instance = new TwilioServerImpl();
+  return _instance;
+}
+
+/** Test-only: drop the singleton so tests get a fresh server. */
+export function resetTwilioServer(): void {
+  _instance = null;
+}

package/src/channels/twilio/signature.ts

@@ -0,0 +1,36 @@
+/**
+ * Validate Twilio's X-Twilio-Signature header.
+ *
+ * Algorithm (per Twilio webhook security docs):
+ *   1. Take the full URL Twilio sent the request to (including ?query).
+ *   2. For application/x-www-form-urlencoded bodies, sort POST keys and
+ *      append each "key" + "value" to the URL string.
+ *   3. HMAC-SHA1 with the account AuthToken, base64-encode.
+ *   4. Timing-safe compare with the X-Twilio-Signature header.
+ *
+ * Signed with the account-level Auth Token, NOT the API Key Secret.
+ * When an API Key is used for REST auth, set TWILIO_AUTH_TOKEN separately.
+ */
+import { createHmac, timingSafeEqual } from "crypto";
+
+export function validateTwilioSignature(opts: {
+  authToken: string;
+  fullUrl: string;
+  params: Record<string, string>;
+  signature: string;
+}): boolean {
+  const { authToken, fullUrl, params, signature } = opts;
+  if (!signature) return false;
+
+  const sortedKeys = Object.keys(params).sort();
+  let data = fullUrl;
+  for (const key of sortedKeys) {
+    data += key + params[key];
+  }
+
+  const computed = createHmac("sha1", authToken).update(data, "utf8").digest("base64");
+  const a = Buffer.from(computed);
+  const b = Buffer.from(signature);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}

package/src/channels/twilio/transcribe.ts

@@ -0,0 +1,58 @@
+/**
+ * Transcribe a short audio clip via OpenAI's gpt-4o-mini-transcribe.
+ *
+ * Used by the WhatsApp channel for voice notes. We accept the raw bytes
+ * + MIME (Twilio's WhatsApp voice notes are typically audio/ogg with
+ * opus codec — the endpoint handles ogg natively).
+ */
+import { log } from "../../utils/log";
+
+const ENDPOINT = "https://api.openai.com/v1/audio/transcriptions";
+const MODEL = "gpt-4o-mini-transcribe";
+const TIMEOUT_MS = 30_000;
+
+const MIME_TO_FILENAME: Record<string, string> = {
+  "audio/ogg": "audio.ogg",
+  "audio/mpeg": "audio.mp3",
+  "audio/mp4": "audio.m4a",
+  "audio/wav": "audio.wav",
+  "audio/webm": "audio.webm",
+  "audio/flac": "audio.flac",
+};
+
+export interface TranscribeOpts {
+  apiKey: string;
+  data: Buffer;
+  mime: string;
+  language?: string;
+}
+
+export async function transcribeAudio(opts: TranscribeOpts): Promise<string> {
+  const filename = MIME_TO_FILENAME[opts.mime] ?? "audio.ogg";
+  const form = new FormData();
+  form.set("file", new Blob([new Uint8Array(opts.data)], { type: opts.mime }), filename);
+  form.set("model", MODEL);
+  if (opts.language) form.set("language", opts.language);
+  form.set("response_format", "json");
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const resp = await fetch(ENDPOINT, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${opts.apiKey}` },
+      body: form,
+      signal: controller.signal,
+    });
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => "");
+      throw new Error(`OpenAI transcribe failed: ${resp.status} ${text}`);
+    }
+    const json = (await resp.json()) as { text?: string };
+    const text = (json.text || "").trim();
+    log.info({ chars: text.length, mime: opts.mime }, "twilio: voice note transcribed");
+    return text;
+  } finally {
+    clearTimeout(timer);
+  }
+}