@crewhaus/call-session 0.1.4 → 0.1.6

package/src/index.test.ts

@@ -1,224 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import {
-  CallSessionError,
-  type CallTransition,
-  type TelephonyAdapter,
-  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);
-  });
-
-  test("on() returns an unsubscribe that stops further notifications", async () => {
-    const adapter = createInMemoryTelephonyAdapter();
-    const session = createCallSession({ adapter });
-    let hits = 0;
-    const off = session.on(() => {
-      hits += 1;
-    });
-    await session.dial("tel:a"); // listener active → 1 hit
-    expect(hits).toBe(1);
-    off(); // exercises the unsubscribe closure
-    await session.answer(); // listener removed → still 1
-    expect(hits).toBe(1);
-  });
-
-  test("unsubscribing a never-fired listener is a harmless no-op", () => {
-    const adapter = createInMemoryTelephonyAdapter();
-    const session = createCallSession({ adapter });
-    const off = session.on(() => {
-      throw new Error("should never run");
-    });
-    // Calling unsubscribe before any transition must not throw.
-    expect(() => off()).not.toThrow();
-  });
-
-  test("reason is threaded into the transition record and omitted when absent", async () => {
-    const adapter = createInMemoryTelephonyAdapter();
-    const session = createCallSession({ adapter });
-    await session.dial("tel:a", { reason: "outbound campaign" });
-    await session.answer(); // no reason supplied
-    const log = session.history();
-    expect(log[0]?.reason).toBe("outbound campaign");
-    expect("reason" in (log[1] ?? {})).toBe(false);
-  });
-
-  test('end() defaults the adapter reason to "end" when none is given', async () => {
-    const adapter = createInMemoryTelephonyAdapter();
-    const session = createCallSession({ adapter });
-    await session.dial("tel:a");
-    await session.answer();
-    await session.end(); // no reason
-    const endCall = adapter.calls.find((c) => c.verb === "end");
-    expect(endCall?.arg).toBe("end");
-    // No transition-level reason recorded when none supplied.
-    const last = session.history().at(-1);
-    expect(last?.to).toBe("terminated");
-    expect("reason" in (last ?? {})).toBe(false);
-  });
-
-  test("end() forwards an explicit reason to the adapter", async () => {
-    const adapter = createInMemoryTelephonyAdapter();
-    const session = createCallSession({ adapter });
-    await session.dial("tel:a");
-    await session.end({ reason: "callee busy" });
-    const endCall = adapter.calls.find((c) => c.verb === "end");
-    expect(endCall?.arg).toBe("callee busy");
-    expect(session.history().at(-1)?.reason).toBe("callee busy");
-  });
-
-  test("dial failure surfaced from a non-Error rejection falls back to String()", async () => {
-    // Adapter whose dial rejects with a non-Error value — exercises the
-    // `?? String(err)` branch in the dial-failure path.
-    const adapter: TelephonyAdapter = {
-      kind: "weird",
-      async dial() {
-        throw "boom-string"; // not an Error, so `.message` is undefined
-      },
-      async answer() {},
-      async hold() {},
-      async resume() {},
-      async transfer() {},
-      async end() {},
-    };
-    const session = createCallSession({ adapter });
-    await expect(session.dial("tel:a")).rejects.toBe("boom-string");
-    expect(session.state).toBe("terminated");
-    expect(session.history().at(-1)?.reason).toContain("boom-string");
-  });
-
-  test("injected now() controls transition timestamps deterministically", async () => {
-    const adapter = createInMemoryTelephonyAdapter();
-    const fixed = new Date("2026-06-04T12:00:00.000Z");
-    const session = createCallSession({ adapter, now: () => fixed });
-    await session.dial("tel:a");
-    expect(session.history()[0]?.at).toBe("2026-06-04T12:00:00.000Z");
-  });
-
-  test("in-memory adapter: failNextDial uses its default message and resets after one dial", async () => {
-    const adapter = createInMemoryTelephonyAdapter();
-    adapter.failNextDial(); // default message branch
-    const s1 = createCallSession({ adapter });
-    await expect(s1.dial("tel:a")).rejects.toThrow(/in-memory: dial failed/);
-    // Failure is one-shot: a fresh session dials cleanly.
-    const s2 = createCallSession({ adapter });
-    await s2.dial("tel:b");
-    expect(s2.state).toBe("dialing");
-  });
-
-  test("in-memory adapter records every verb and argument in order", async () => {
-    const adapter = createInMemoryTelephonyAdapter();
-    expect(adapter.kind).toBe("in-memory");
-    const session = createCallSession({ adapter });
-    await session.dial("tel:a");
-    await session.answer();
-    await session.hold();
-    await session.resume();
-    await session.transfer("tel:b");
-    await session.end({ reason: "done" });
-    expect(adapter.calls).toEqual([
-      { verb: "dial", arg: "tel:a" },
-      { verb: "answer" },
-      { verb: "hold" },
-      { verb: "resume" },
-      { verb: "transfer", arg: "tel:b" },
-      { verb: "end", arg: "done" },
-    ]);
-  });
-});

package/src/index.ts

@@ -1,213 +0,0 @@
-/**
- * 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 });
-    },
-  };
-}