@crewhaus/call-session 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/call-session",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Call lifecycle state machine — idle | dialing | connected | on-hold | transferred | terminated (Section 24 VOICE)",
   "main": "src/index.ts",
@@ -12,13 +12,13 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.0.0"
+    "@crewhaus/errors": "0.1.2"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -30,12 +30,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/adapters/adapters.test.ts

@@ -57,6 +57,154 @@ describe("twilio telephony adapter", () => {
       }),
     ).toThrow(CallSessionError);
   });
+
+  test("missing authToken throws", () => {
+    expect(() =>
+      createTwilioTelephonyAdapter({ accountSid: "A", authToken: "", fromNumber: "+1" }),
+    ).toThrow(/requires authToken/);
+  });
+
+  test("missing fromNumber throws", () => {
+    expect(() =>
+      createTwilioTelephonyAdapter({ accountSid: "A", authToken: "t", fromNumber: "" }),
+    ).toThrow(/requires fromNumber/);
+  });
+
+  test("dial includes a TwiML Url and a basic auth header derived from sid:token", async () => {
+    let observedAuth = "";
+    let observedBody = "";
+    const fetchImpl = (async (_url: string, init?: RequestInit) => {
+      observedAuth = (init?.headers as Record<string, string>)?.Authorization ?? "";
+      observedBody = init?.body as string;
+      return new Response(JSON.stringify({ sid: "CA999" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "AC123",
+      authToken: "tok",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await adapter.dial("+2");
+    expect(observedBody).toContain("Url=https%3A%2F%2Fdemo.twilio.com");
+    // Base64 of "AC123:tok".
+    expect(observedAuth).toBe(`Basic ${Buffer.from("AC123:tok").toString("base64")}`);
+  });
+
+  test("answer is an adapter-level no-op", async () => {
+    const fetchImpl = (async () => {
+      throw new Error("answer must not hit the network");
+    }) as unknown as typeof fetch;
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "A",
+      authToken: "t",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await expect(adapter.answer()).resolves.toBeUndefined();
+  });
+
+  test("dial throws CallSessionError with status + body on a non-ok response", async () => {
+    const fetchImpl = (async () =>
+      new Response("nope", { status: 422 })) as unknown as typeof fetch;
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "A",
+      authToken: "t",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await expect(adapter.dial("+2")).rejects.toThrow(/Calls\.create returned 422: nope/);
+  });
+
+  test("callsUpdate throws CallSessionError on a non-ok response (via hold)", async () => {
+    let firstCall = true;
+    const fetchImpl = (async () => {
+      if (firstCall) {
+        firstCall = false;
+        return new Response(JSON.stringify({ sid: "CA1" }), { status: 200 });
+      }
+      return new Response("denied", { status: 500 });
+    }) as unknown as typeof fetch;
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "A",
+      authToken: "t",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await adapter.dial("+2");
+    await expect(adapter.hold()).rejects.toThrow(/Calls\.update returned 500: denied/);
+  });
+
+  test("hold/resume/transfer/end without an active call behave correctly", async () => {
+    const fetchImpl = (async () =>
+      new Response(JSON.stringify({ sid: "x" }), { status: 200 })) as unknown as typeof fetch;
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "A",
+      authToken: "t",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await expect(adapter.hold()).rejects.toThrow(/no active call to hold/);
+    await expect(adapter.resume()).rejects.toThrow(/no active call to resume/);
+    await expect(adapter.transfer("+2")).rejects.toThrow(/no active call to transfer/);
+    // end() with no active call is a silent no-op.
+    await expect(adapter.end("bye")).resolves.toBeUndefined();
+  });
+
+  test("transfer posts a redirect Url with the encoded destination", async () => {
+    let transferBody = "";
+    let calls = 0;
+    const fetchImpl = (async (_url: string, init?: RequestInit) => {
+      calls += 1;
+      if (calls >= 2) transferBody = init?.body as string;
+      return new Response(JSON.stringify({ sid: "CA1" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "A",
+      authToken: "t",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await adapter.dial("+2");
+    await adapter.transfer("sip:agent@x.com");
+    // The destination is encodeURIComponent-ed into the Url query string, then
+    // the whole Url is form-urlencoded again as a POST body param — so the
+    // caller-supplied URI ends up double-encoded. Decoding twice recovers it.
+    const params = new URLSearchParams(transferBody);
+    const url = new URL(params.get("Url") ?? "");
+    expect(url.searchParams.get("to")).toBe("sip:agent@x.com");
+    expect(transferBody).toContain("Method=POST");
+  });
+
+  test("end completes the active call then clears it (next end is a no-op)", async () => {
+    const seen: string[] = [];
+    const fetchImpl = (async (url: string, init?: RequestInit) => {
+      seen.push((init?.body as string) ?? "");
+      void url;
+      return new Response(JSON.stringify({ sid: "CA1" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "A",
+      authToken: "t",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await adapter.dial("+2");
+    await adapter.end("done");
+    expect(seen.some((b) => b.includes("Status=completed"))).toBe(true);
+    const before = seen.length;
+    await adapter.end("again"); // no active call → no network
+    expect(seen.length).toBe(before);
+  });
+
+  test("kind is 'twilio'", () => {
+    const adapter = createTwilioTelephonyAdapter({
+      accountSid: "A",
+      authToken: "t",
+      fromNumber: "+1",
+      fetchImpl: (async () => new Response("{}")) as unknown as typeof fetch,
+    });
+    expect(adapter.kind).toBe("twilio");
+  });
 });
 
 describe("livekit-sip telephony adapter", () => {
@@ -103,4 +251,183 @@ describe("livekit-sip telephony adapter", () => {
       }),
     ).toThrow(CallSessionError);
   });
+
+  test("each required field is validated independently", () => {
+    expect(() =>
+      createLiveKitSipAdapter({ url: "u", apiKey: "", apiSecret: "s", fromNumber: "+1" }),
+    ).toThrow(/requires apiKey/);
+    expect(() =>
+      createLiveKitSipAdapter({ url: "u", apiKey: "k", apiSecret: "", fromNumber: "+1" }),
+    ).toThrow(/requires apiSecret/);
+    expect(() =>
+      createLiveKitSipAdapter({ url: "u", apiKey: "k", apiSecret: "s", fromNumber: "" }),
+    ).toThrow(/requires fromNumber/);
+  });
+
+  test("dial sends a bearer auth header and records the participant id", async () => {
+    let observedAuth = "";
+    const fetchImpl = (async (_url: string, init?: RequestInit) => {
+      observedAuth = (init?.headers as Record<string, string>)?.Authorization ?? "";
+      return new Response(JSON.stringify({ participant_id: "p42" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    const adapter = createLiveKitSipAdapter({
+      url: "http://lk",
+      apiKey: "k",
+      apiSecret: "s",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await adapter.dial("sip:a@x.com");
+    expect(observedAuth).toBe("Bearer k:s");
+  });
+
+  test("dial without participant_id in the response falls back to 'unknown' but stays active", async () => {
+    // Response omits participant_id → activeParticipantId becomes "unknown"
+    // (truthy), so a subsequent hold proceeds to the RPC rather than throwing.
+    let holdHit = false;
+    const fetchImpl = (async (url: string) => {
+      if (String(url).includes("UpdateSIPParticipant")) holdHit = true;
+      return new Response(JSON.stringify({}), { status: 200 });
+    }) as unknown as typeof fetch;
+    const adapter = createLiveKitSipAdapter({
+      url: "http://lk",
+      apiKey: "k",
+      apiSecret: "s",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await adapter.dial("sip:a@x.com");
+    await adapter.hold();
+    expect(holdHit).toBe(true);
+  });
+
+  test("answer is an adapter-level no-op", async () => {
+    const fetchImpl = (async () => {
+      throw new Error("answer must not hit the network");
+    }) as unknown as typeof fetch;
+    const adapter = createLiveKitSipAdapter({
+      url: "http://lk",
+      apiKey: "k",
+      apiSecret: "s",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await expect(adapter.answer()).resolves.toBeUndefined();
+  });
+
+  test("rpc throws CallSessionError with method, status and body on a non-ok response", async () => {
+    const fetchImpl = (async () =>
+      new Response("upstream boom", { status: 503 })) as unknown as typeof fetch;
+    const adapter = createLiveKitSipAdapter({
+      url: "http://lk",
+      apiKey: "k",
+      apiSecret: "s",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await expect(adapter.dial("sip:a@x.com")).rejects.toThrow(
+      /CreateSIPParticipant returned 503: upstream boom/,
+    );
+  });
+
+  test("hold and resume mute/unmute the active participant", async () => {
+    const bodies: Array<Record<string, unknown>> = [];
+    const fetchImpl = (async (url: string, init?: RequestInit) => {
+      if (String(url).includes("UpdateSIPParticipant")) {
+        bodies.push(JSON.parse(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:a@x.com");
+    await adapter.hold();
+    await adapter.resume();
+    expect(bodies).toEqual([
+      { participant_id: "p1", muted: true },
+      { participant_id: "p1", muted: false },
+    ]);
+  });
+
+  test("hold/resume without an active call throw", 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.hold()).rejects.toThrow(/no active call to hold/);
+    await expect(adapter.resume()).rejects.toThrow(/no active call to resume/);
+  });
+
+  test("transfer forwards transfer_to for the active participant", async () => {
+    let transferBody: Record<string, unknown> = {};
+    const fetchImpl = (async (url: string, init?: RequestInit) => {
+      if (String(url).includes("TransferSIPParticipant")) {
+        transferBody = JSON.parse(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:a@x.com");
+    await adapter.transfer("sip:b@x.com");
+    expect(transferBody).toEqual({ participant_id: "p1", transfer_to: "sip:b@x.com" });
+  });
+
+  test("end deletes the active participant then clears it (next end is a no-op)", async () => {
+    let deletes = 0;
+    const fetchImpl = (async (url: string) => {
+      if (String(url).includes("DeleteSIPParticipant")) deletes += 1;
+      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:a@x.com");
+    await adapter.end("done");
+    await adapter.end("again"); // no active participant → no extra delete
+    expect(deletes).toBe(1);
+  });
+
+  test("end with no active call is a silent no-op", async () => {
+    const fetchImpl = (async () => {
+      throw new Error("end must not hit the network when idle");
+    }) as unknown as typeof fetch;
+    const adapter = createLiveKitSipAdapter({
+      url: "http://lk",
+      apiKey: "k",
+      apiSecret: "s",
+      fromNumber: "+1",
+      fetchImpl,
+    });
+    await expect(adapter.end("never")).resolves.toBeUndefined();
+  });
+
+  test("kind is 'livekit-sip'", () => {
+    const adapter = createLiveKitSipAdapter({
+      url: "http://lk",
+      apiKey: "k",
+      apiSecret: "s",
+      fromNumber: "+1",
+      fetchImpl: (async () => new Response("{}")) as unknown as typeof fetch,
+    });
+    expect(adapter.kind).toBe("livekit-sip");
+  });
 });

package/src/index.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import {
   CallSessionError,
   type CallTransition,
+  type TelephonyAdapter,
   createCallSession,
   createInMemoryTelephonyAdapter,
 } from "./index.js";
@@ -103,4 +104,121 @@ describe("createCallSession (T1 + T9 state machine)", () => {
     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" },
+    ]);
+  });
 });