@crewhaus/call-session 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/call-session",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Call lifecycle state machine — idle | dialing | connected | on-hold | transferred | terminated (Section 24 VOICE)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/call-session"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/call-session#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/adapters/adapters.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Section 30 — telephony adapter contract tests.
+ */
+import { describe, expect, test } from "bun:test";
+import { CallSessionError } from "../index";
+import { createLiveKitSipAdapter } from "./livekit-sip";
+import { createTwilioTelephonyAdapter } from "./twilio";
+
+describe("twilio telephony adapter", () => {
+  test("dial POSTs to Calls.json with from/to params", async () => {
+    let observedUrl = "";
+    let observedAuth = "";
+    let observedBody = "";
+    const fetchImpl = (async (url: string, init?: RequestInit) => {
+      observedUrl = url;
+      observedAuth = (init?.headers as Record<string, string>)?.Authorization ?? "";
+      observedBody = init?.body as string;
+      return new Response(JSON.stringify({ sid: "CA123" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "AC123",
+      authToken: "tok",
+      fromNumber: "+15551234567",
+      fetchImpl,
+    });
+    await adapter.dial("+15559876543");
+    expect(observedUrl).toContain("/Accounts/AC123/Calls.json");
+    expect(observedAuth.startsWith("Basic ")).toBe(true);
+    expect(observedBody).toContain("From=%2B15551234567");
+    expect(observedBody).toContain("To=%2B15559876543");
+  });
+
+  test("hold/resume update the active call", async () => {
+    let updates = 0;
+    const fetchImpl = (async (_url: string, init?: RequestInit) => {
+      if (init?.method === "POST" && (init.body as string).includes("Status=")) updates++;
+      return new Response(JSON.stringify({ sid: "CA123" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "A",
+      authToken: "t",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await adapter.dial("+2");
+    await adapter.hold();
+    await adapter.resume();
+    expect(updates).toBe(2);
+  });
+
+  test("missing config throws", () => {
+    expect(() =>
+      createTwilioTelephonyAdapter({
+        accountSid: "",
+        authToken: "t",
+        fromNumber: "+1",
+      }),
+    ).toThrow(CallSessionError);
+  });
+});
+
+describe("livekit-sip telephony adapter", () => {
+  test("dial POSTs to CreateSIPParticipant", async () => {
+    let observedUrl = "";
+    let observedBody = "";
+    const fetchImpl = (async (url: string, init?: RequestInit) => {
+      observedUrl = url;
+      observedBody = init?.body as string;
+      return new Response(JSON.stringify({ participant_id: "p1" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    const adapter = createLiveKitSipAdapter({
+      url: "http://lk",
+      apiKey: "k",
+      apiSecret: "s",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await adapter.dial("sip:test@example.com");
+    expect(observedUrl).toContain("/twirp/livekit.SIP/CreateSIPParticipant");
+    const parsed = JSON.parse(observedBody) as { sip_call_to: string };
+    expect(parsed.sip_call_to).toBe("sip:test@example.com");
+  });
+
+  test("transfer requires active call", async () => {
+    const fetchImpl = (async () => new Response("{}", { status: 200 })) as unknown as typeof fetch;
+    const adapter = createLiveKitSipAdapter({
+      url: "http://lk",
+      apiKey: "k",
+      apiSecret: "s",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await expect(adapter.transfer("sip:other@x.com")).rejects.toBeInstanceOf(CallSessionError);
+  });
+
+  test("missing config throws", () => {
+    expect(() =>
+      createLiveKitSipAdapter({
+        url: "",
+        apiKey: "k",
+        apiSecret: "s",
+        fromNumber: "+1",
+      }),
+    ).toThrow(CallSessionError);
+  });
+});

package/src/adapters/livekit-sip.ts

@@ -0,0 +1,81 @@
+/**
+ * Section 30 — LiveKit SIP telephony adapter for `@crewhaus/call-session`.
+ * LiveKit Cloud's SIP gateway provides outbound + inbound SIP trunks; this
+ * adapter targets their REST/RPC API for call control.
+ */
+import { CallSessionError, type TelephonyAdapter } from "../index";
+
+export type LiveKitSipAdapterOptions = {
+  readonly url: string;
+  readonly apiKey: string;
+  readonly apiSecret: string;
+  readonly fromNumber: string;
+  readonly fetchImpl?: typeof fetch;
+};
+
+export function createLiveKitSipAdapter(opts: LiveKitSipAdapterOptions): TelephonyAdapter {
+  if (!opts.url) throw new CallSessionError("livekit-sip adapter requires url");
+  if (!opts.apiKey) throw new CallSessionError("livekit-sip adapter requires apiKey");
+  if (!opts.apiSecret) throw new CallSessionError("livekit-sip adapter requires apiSecret");
+  if (!opts.fromNumber) throw new CallSessionError("livekit-sip adapter requires fromNumber");
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  let activeParticipantId: string | undefined;
+
+  async function rpc(method: string, body: Record<string, unknown>): Promise<unknown> {
+    const res = await fetchImpl(`${opts.url}/twirp/livekit.SIP/${method}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${opts.apiKey}:${opts.apiSecret}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      throw new CallSessionError(
+        `livekit-sip ${method} returned ${res.status}: ${await res.text()}`,
+      );
+    }
+    return await res.json();
+  }
+
+  return {
+    kind: "livekit-sip",
+    async dial(toUri: string): Promise<void> {
+      const result = (await rpc("CreateSIPParticipant", {
+        sip_call_to: toUri,
+        sip_number: opts.fromNumber,
+      })) as { participant_id?: string };
+      activeParticipantId = result.participant_id ?? "unknown";
+    },
+    async answer(): Promise<void> {
+      // LiveKit dispatches answer via the room agent — adapter-level no-op.
+    },
+    async hold(): Promise<void> {
+      if (!activeParticipantId) throw new CallSessionError("livekit-sip: no active call to hold");
+      await rpc("UpdateSIPParticipant", {
+        participant_id: activeParticipantId,
+        muted: true,
+      });
+    },
+    async resume(): Promise<void> {
+      if (!activeParticipantId) throw new CallSessionError("livekit-sip: no active call to resume");
+      await rpc("UpdateSIPParticipant", {
+        participant_id: activeParticipantId,
+        muted: false,
+      });
+    },
+    async transfer(toUri: string): Promise<void> {
+      if (!activeParticipantId)
+        throw new CallSessionError("livekit-sip: no active call to transfer");
+      await rpc("TransferSIPParticipant", {
+        participant_id: activeParticipantId,
+        transfer_to: toUri,
+      });
+    },
+    async end(_reason: string): Promise<void> {
+      if (!activeParticipantId) return;
+      await rpc("DeleteSIPParticipant", { participant_id: activeParticipantId });
+      activeParticipantId = undefined;
+    },
+  };
+}

package/src/adapters/twilio.ts

@@ -0,0 +1,104 @@
+/**
+ * Section 30 — Twilio telephony adapter for `@crewhaus/call-session`.
+ * Routes through the Twilio REST API (via fetch — no SDK dependency).
+ * Webhook signature verification lives outside this module (the daemon's
+ * inbound HTTP handler does that with `X-Twilio-Signature`).
+ */
+import { CallSessionError, type TelephonyAdapter } from "../index";
+
+export type TwilioAdapterOptions = {
+  readonly accountSid: string;
+  readonly authToken: string;
+  readonly fromNumber: string;
+  /** Test override: inject a fake fetch. */
+  readonly fetchImpl?: typeof fetch;
+  /** Override base URL (defaults to https://api.twilio.com/2010-04-01). */
+  readonly baseUrl?: string;
+};
+
+export function createTwilioTelephonyAdapter(opts: TwilioAdapterOptions): TelephonyAdapter {
+  if (!opts.accountSid) throw new CallSessionError("twilio adapter requires accountSid");
+  if (!opts.authToken) throw new CallSessionError("twilio adapter requires authToken");
+  if (!opts.fromNumber) throw new CallSessionError("twilio adapter requires fromNumber");
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const baseUrl = opts.baseUrl ?? "https://api.twilio.com/2010-04-01";
+  let activeCallSid: string | undefined;
+
+  function authHeader(): string {
+    const token = Buffer.from(`${opts.accountSid}:${opts.authToken}`).toString("base64");
+    return `Basic ${token}`;
+  }
+
+  async function callsPost(body: Record<string, string>): Promise<{ sid: string }> {
+    const params = new URLSearchParams(body).toString();
+    const res = await fetchImpl(`${baseUrl}/Accounts/${opts.accountSid}/Calls.json`, {
+      method: "POST",
+      headers: {
+        Authorization: authHeader(),
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: params,
+    });
+    if (!res.ok) {
+      throw new CallSessionError(`twilio Calls.create returned ${res.status}: ${await res.text()}`);
+    }
+    return (await res.json()) as { sid: string };
+  }
+
+  async function callsUpdate(callSid: string, body: Record<string, string>): Promise<void> {
+    const params = new URLSearchParams(body).toString();
+    const res = await fetchImpl(`${baseUrl}/Accounts/${opts.accountSid}/Calls/${callSid}.json`, {
+      method: "POST",
+      headers: {
+        Authorization: authHeader(),
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: params,
+    });
+    if (!res.ok) {
+      throw new CallSessionError(`twilio Calls.update returned ${res.status}: ${await res.text()}`);
+    }
+  }
+
+  return {
+    kind: "twilio",
+    async dial(toUri: string): Promise<void> {
+      const result = await callsPost({
+        From: opts.fromNumber,
+        To: toUri,
+        // Twilio requires a TwiML URL or instructions; v0 expects callers
+        // to wire the actual TwiML elsewhere. The empty Url makes the call
+        // fail loudly rather than silently dial.
+        Url: "https://demo.twilio.com/docs/voice.xml",
+      });
+      activeCallSid = result.sid;
+    },
+    async answer(): Promise<void> {
+      // Inbound calls answer via TwiML <Say>/<Connect> on the webhook —
+      // adapter-level answer is a no-op.
+    },
+    async hold(): Promise<void> {
+      if (!activeCallSid) throw new CallSessionError("twilio: no active call to hold");
+      await callsUpdate(activeCallSid, { Status: "queued" });
+    },
+    async resume(): Promise<void> {
+      if (!activeCallSid) throw new CallSessionError("twilio: no active call to resume");
+      await callsUpdate(activeCallSid, { Status: "in-progress" });
+    },
+    async transfer(toUri: string): Promise<void> {
+      if (!activeCallSid) throw new CallSessionError("twilio: no active call to transfer");
+      // Twilio transfer = update the active call to redirect to a TwiML
+      // <Dial> for the new endpoint. Caller's TwiML supplies the verb;
+      // here we POST the redirect URL.
+      await callsUpdate(activeCallSid, {
+        Url: `https://demo.twilio.com/docs/voice.xml?to=${encodeURIComponent(toUri)}`,
+        Method: "POST",
+      });
+    },
+    async end(_reason: string): Promise<void> {
+      if (!activeCallSid) return;
+      await callsUpdate(activeCallSid, { Status: "completed" });
+      activeCallSid = undefined;
+    },
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from "bun:test";
+import {
+  CallSessionError,
+  type CallTransition,
+  createCallSession,
+  createInMemoryTelephonyAdapter,
+} from "./index.js";
+
+describe("createCallSession (T1 + T9 state machine)", () => {
+  test("happy path: idle → dialing → connected → on-hold → connected → terminated", async () => {
+    const adapter = createInMemoryTelephonyAdapter();
+    const transitions: CallTransition[] = [];
+    const session = createCallSession({ adapter });
+    session.on((t) => transitions.push(t));
+
+    await session.dial("tel:+15555550100");
+    expect(session.state).toBe("dialing");
+    await session.answer();
+    expect(session.state).toBe("connected");
+    await session.hold();
+    expect(session.state).toBe("on-hold");
+    await session.resume();
+    expect(session.state).toBe("connected");
+    await session.end({ reason: "user hangup" });
+    expect(session.state).toBe("terminated");
+
+    expect(transitions.map((t) => `${t.from}→${t.to}`)).toEqual([
+      "idle→dialing",
+      "dialing→connected",
+      "connected→on-hold",
+      "on-hold→connected",
+      "connected→terminated",
+    ]);
+    expect(adapter.calls.map((c) => c.verb)).toEqual(["dial", "answer", "hold", "resume", "end"]);
+  });
+
+  test("transfer path: idle → dialing → connected → transferred → terminated", async () => {
+    const adapter = createInMemoryTelephonyAdapter();
+    const session = createCallSession({ adapter });
+    await session.dial("tel:a");
+    await session.answer();
+    await session.transfer("tel:b");
+    expect(session.state).toBe("transferred");
+    await session.end();
+    expect(session.state).toBe("terminated");
+  });
+
+  test("illegal transitions throw CallSessionError without changing state", async () => {
+    const adapter = createInMemoryTelephonyAdapter();
+    const session = createCallSession({ adapter });
+    await expect(session.answer()).rejects.toThrow(CallSessionError); // idle → connected illegal
+    expect(session.state).toBe("idle");
+    await expect(session.hold()).rejects.toThrow(CallSessionError);
+    expect(session.state).toBe("idle");
+  });
+
+  test("dial failure auto-transitions to terminated", async () => {
+    const adapter = createInMemoryTelephonyAdapter();
+    adapter.failNextDial("network down");
+    const session = createCallSession({ adapter });
+    await expect(session.dial("tel:a")).rejects.toThrow(/network down/);
+    expect(session.state).toBe("terminated");
+  });
+
+  test("listener errors are isolated and do not block transitions", async () => {
+    const adapter = createInMemoryTelephonyAdapter();
+    const session = createCallSession({ adapter });
+    session.on(() => {
+      throw new Error("listener oops");
+    });
+    let okListenerHits = 0;
+    session.on(() => {
+      okListenerHits += 1;
+    });
+    await session.dial("tel:a");
+    expect(okListenerHits).toBe(1);
+    expect(session.state).toBe("dialing");
+  });
+
+  test("history returns transitions in order with timestamps", async () => {
+    const adapter = createInMemoryTelephonyAdapter();
+    const session = createCallSession({ adapter });
+    await session.dial("tel:a");
+    await session.answer();
+    const log = session.history();
+    expect(log.length).toBe(2);
+    expect(log[0]?.from).toBe("idle");
+    expect(log[0]?.to).toBe("dialing");
+    expect(typeof log[0]?.at).toBe("string");
+    expect(log[1]?.to).toBe("connected");
+  });
+
+  test("T9 property: every state's outgoing transitions are exactly the configured set", async () => {
+    // The state-machine definition is encoded as a constant; ensure
+    // illegal transitions are rejected uniformly.
+    const adapter = createInMemoryTelephonyAdapter();
+    const session = createCallSession({ adapter });
+    await session.dial("a");
+    await session.answer();
+    await session.end();
+    // Once terminated, every verb throws.
+    await expect(session.dial("b")).rejects.toThrow(CallSessionError);
+    await expect(session.hold()).rejects.toThrow(CallSessionError);
+    await expect(session.transfer("c")).rejects.toThrow(CallSessionError);
+  });
+});

package/src/index.ts

@@ -0,0 +1,213 @@
+/**
+ * Catalog R16 `call-session` — Section 24 VOICE.
+ *
+ * Call lifecycle state machine with pluggable telephony adapter slots.
+ *
+ *   idle ─dial()→ dialing ─answer()→ connected ─hold()→ on-hold
+ *                                   │              │
+ *                                   │              └─resume()→ connected
+ *                                   ├─transfer()→ transferred ─end()→ terminated
+ *                                   └─end()─────────────────────→ terminated
+ *
+ * Telephony adapters (Twilio, LiveKit SIP, Vonage) are STUBS in v0 —
+ * the interface is exercised by an in-memory adapter the tests + the
+ * smoke harness use to drive transitions deterministically. Real
+ * telephony lands in follow-up PRs (the kickoff explicitly defers it).
+ *
+ * Per-state hooks fire on transitions — the daemon uses them to log
+ * trace events, measure connect-time, etc. Hook errors are isolated:
+ * a misbehaving listener is logged but cannot wedge the state machine.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+
+export class CallSessionError extends CrewhausError {
+  override readonly name = "CallSessionError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+// Section 30 — additional telephony adapters
+export {
+  createTwilioTelephonyAdapter,
+  type TwilioAdapterOptions,
+} from "./adapters/twilio";
+export {
+  createLiveKitSipAdapter,
+  type LiveKitSipAdapterOptions,
+} from "./adapters/livekit-sip";
+
+export type CallState = "idle" | "dialing" | "connected" | "on-hold" | "transferred" | "terminated";
+
+export type CallTransition = {
+  readonly from: CallState;
+  readonly to: CallState;
+  readonly at: string;
+  readonly reason?: string;
+};
+
+export type CallStateListener = (transition: CallTransition) => void;
+
+export interface TelephonyAdapter {
+  readonly kind: string;
+  /** Begin the outbound dial — promise resolves on adapter ack. */
+  dial(toUri: string): Promise<void>;
+  /** Answer an incoming call (no-op for outbound flows). */
+  answer(): Promise<void>;
+  /** Briefly suspend the bidirectional audio path. */
+  hold(): Promise<void>;
+  resume(): Promise<void>;
+  /** Hand the call off to another agent / number. */
+  transfer(toUri: string): Promise<void>;
+  /** Hang up. */
+  end(reason: string): Promise<void>;
+}
+
+export interface CallSession {
+  readonly state: CallState;
+  dial(toUri: string, opts?: { reason?: string }): Promise<void>;
+  answer(opts?: { reason?: string }): Promise<void>;
+  hold(opts?: { reason?: string }): Promise<void>;
+  resume(opts?: { reason?: string }): Promise<void>;
+  transfer(toUri: string, opts?: { reason?: string }): Promise<void>;
+  end(opts?: { reason?: string }): Promise<void>;
+  on(listener: CallStateListener): () => void;
+  /** Diagnostic — full transition history (newest last). */
+  history(): ReadonlyArray<CallTransition>;
+}
+
+export type CreateCallSessionOptions = {
+  readonly adapter: TelephonyAdapter;
+  readonly now?: () => Date;
+};
+
+const TRANSITIONS: Readonly<Record<CallState, ReadonlyArray<CallState>>> = {
+  idle: ["dialing"],
+  dialing: ["connected", "terminated"],
+  connected: ["on-hold", "transferred", "terminated"],
+  "on-hold": ["connected", "terminated"],
+  transferred: ["terminated"],
+  terminated: [],
+};
+
+export function createCallSession(opts: CreateCallSessionOptions): CallSession {
+  const now = opts.now ?? (() => new Date());
+  const listeners = new Set<CallStateListener>();
+  const log: CallTransition[] = [];
+  let state: CallState = "idle";
+
+  function transitionTo(target: CallState, reason?: string): void {
+    const allowed = TRANSITIONS[state];
+    if (!allowed.includes(target)) {
+      throw new CallSessionError(
+        `illegal transition ${state} → ${target}${reason ? ` (reason: ${reason})` : ""}`,
+      );
+    }
+    const t: CallTransition = {
+      from: state,
+      to: target,
+      at: now().toISOString(),
+      ...(reason !== undefined ? { reason } : {}),
+    };
+    state = target;
+    log.push(t);
+    for (const l of listeners) {
+      try {
+        l(t);
+      } catch {
+        // Isolate listener errors.
+      }
+    }
+  }
+
+  return {
+    get state() {
+      return state;
+    },
+    async dial(toUri, callOpts = {}) {
+      transitionTo("dialing", callOpts.reason);
+      try {
+        await opts.adapter.dial(toUri);
+      } catch (err) {
+        transitionTo("terminated", `dial failed: ${(err as Error).message ?? String(err)}`);
+        throw err;
+      }
+    },
+    async answer(callOpts = {}) {
+      await opts.adapter.answer();
+      transitionTo("connected", callOpts.reason);
+    },
+    async hold(callOpts = {}) {
+      await opts.adapter.hold();
+      transitionTo("on-hold", callOpts.reason);
+    },
+    async resume(callOpts = {}) {
+      await opts.adapter.resume();
+      transitionTo("connected", callOpts.reason);
+    },
+    async transfer(toUri, callOpts = {}) {
+      await opts.adapter.transfer(toUri);
+      transitionTo("transferred", callOpts.reason);
+    },
+    async end(callOpts = {}) {
+      await opts.adapter.end(callOpts.reason ?? "end");
+      transitionTo("terminated", callOpts.reason);
+    },
+    on(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    history() {
+      return [...log];
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// In-memory adapter — for tests + the smoke harness.
+// ---------------------------------------------------------------------------
+
+export interface InMemoryTelephonyAdapter extends TelephonyAdapter {
+  readonly kind: "in-memory";
+  /** Test seam — every adapter call is recorded here in order. */
+  readonly calls: ReadonlyArray<{ readonly verb: string; readonly arg?: string }>;
+  /** Inject a failure on the next `dial(...)` call. */
+  failNextDial(message?: string): void;
+}
+
+export function createInMemoryTelephonyAdapter(): InMemoryTelephonyAdapter {
+  const calls: { verb: string; arg?: string }[] = [];
+  let nextDialFailure: string | undefined;
+  return {
+    kind: "in-memory",
+    calls,
+    failNextDial(message = "in-memory: dial failed") {
+      nextDialFailure = message;
+    },
+    async dial(toUri) {
+      calls.push({ verb: "dial", arg: toUri });
+      if (nextDialFailure !== undefined) {
+        const m = nextDialFailure;
+        nextDialFailure = undefined;
+        throw new CallSessionError(m);
+      }
+    },
+    async answer() {
+      calls.push({ verb: "answer" });
+    },
+    async hold() {
+      calls.push({ verb: "hold" });
+    },
+    async resume() {
+      calls.push({ verb: "resume" });
+    },
+    async transfer(toUri) {
+      calls.push({ verb: "transfer", arg: toUri });
+    },
+    async end(reason) {
+      calls.push({ verb: "end", arg: reason });
+    },
+  };
+}