@crewhaus/call-session 0.1.3 → 0.1.5

package/dist/adapters/livekit-sip.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { type TelephonyAdapter } from "../index";
+export type LiveKitSipAdapterOptions = {
+    readonly url: string;
+    readonly apiKey: string;
+    readonly apiSecret: string;
+    readonly fromNumber: string;
+    readonly fetchImpl?: typeof fetch;
+};
+export declare function createLiveKitSipAdapter(opts: LiveKitSipAdapterOptions): TelephonyAdapter;

package/dist/adapters/livekit-sip.js

@@ -0,0 +1,75 @@
+/**
+ * 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 } from "../index";
+export function createLiveKitSipAdapter(opts) {
+    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;
+    async function rpc(method, body) {
+        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) {
+            const result = (await rpc("CreateSIPParticipant", {
+                sip_call_to: toUri,
+                sip_number: opts.fromNumber,
+            }));
+            activeParticipantId = result.participant_id ?? "unknown";
+        },
+        async answer() {
+            // LiveKit dispatches answer via the room agent — adapter-level no-op.
+        },
+        async hold() {
+            if (!activeParticipantId)
+                throw new CallSessionError("livekit-sip: no active call to hold");
+            await rpc("UpdateSIPParticipant", {
+                participant_id: activeParticipantId,
+                muted: true,
+            });
+        },
+        async resume() {
+            if (!activeParticipantId)
+                throw new CallSessionError("livekit-sip: no active call to resume");
+            await rpc("UpdateSIPParticipant", {
+                participant_id: activeParticipantId,
+                muted: false,
+            });
+        },
+        async transfer(toUri) {
+            if (!activeParticipantId)
+                throw new CallSessionError("livekit-sip: no active call to transfer");
+            await rpc("TransferSIPParticipant", {
+                participant_id: activeParticipantId,
+                transfer_to: toUri,
+            });
+        },
+        async end(_reason) {
+            if (!activeParticipantId)
+                return;
+            await rpc("DeleteSIPParticipant", { participant_id: activeParticipantId });
+            activeParticipantId = undefined;
+        },
+    };
+}

package/dist/adapters/twilio.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 { 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 declare function createTwilioTelephonyAdapter(opts: TwilioAdapterOptions): TelephonyAdapter;

package/dist/adapters/twilio.js

@@ -0,0 +1,96 @@
+/**
+ * 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 } from "../index";
+export function createTwilioTelephonyAdapter(opts) {
+    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;
+    function authHeader() {
+        const token = Buffer.from(`${opts.accountSid}:${opts.authToken}`).toString("base64");
+        return `Basic ${token}`;
+    }
+    async function callsPost(body) {
+        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());
+    }
+    async function callsUpdate(callSid, body) {
+        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) {
+            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() {
+            // Inbound calls answer via TwiML <Say>/<Connect> on the webhook —
+            // adapter-level answer is a no-op.
+        },
+        async hold() {
+            if (!activeCallSid)
+                throw new CallSessionError("twilio: no active call to hold");
+            await callsUpdate(activeCallSid, { Status: "queued" });
+        },
+        async resume() {
+            if (!activeCallSid)
+                throw new CallSessionError("twilio: no active call to resume");
+            await callsUpdate(activeCallSid, { Status: "in-progress" });
+        },
+        async transfer(toUri) {
+            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) {
+            if (!activeCallSid)
+                return;
+            await callsUpdate(activeCallSid, { Status: "completed" });
+            activeCallSid = undefined;
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 declare class CallSessionError extends CrewhausError {
+    readonly name = "CallSessionError";
+    constructor(message: string, cause?: unknown);
+}
+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;
+};
+export declare function createCallSession(opts: CreateCallSessionOptions): CallSession;
+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 declare function createInMemoryTelephonyAdapter(): InMemoryTelephonyAdapter;

package/dist/index.js

@@ -0,0 +1,144 @@
+/**
+ * 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 {
+    name = "CallSessionError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+// Section 30 — additional telephony adapters
+export { createTwilioTelephonyAdapter, } from "./adapters/twilio";
+export { createLiveKitSipAdapter, } from "./adapters/livekit-sip";
+const TRANSITIONS = {
+    idle: ["dialing"],
+    dialing: ["connected", "terminated"],
+    connected: ["on-hold", "transferred", "terminated"],
+    "on-hold": ["connected", "terminated"],
+    transferred: ["terminated"],
+    terminated: [],
+};
+export function createCallSession(opts) {
+    const now = opts.now ?? (() => new Date());
+    const listeners = new Set();
+    const log = [];
+    let state = "idle";
+    function transitionTo(target, reason) {
+        const allowed = TRANSITIONS[state];
+        if (!allowed.includes(target)) {
+            throw new CallSessionError(`illegal transition ${state} → ${target}${reason ? ` (reason: ${reason})` : ""}`);
+        }
+        const t = {
+            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.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];
+        },
+    };
+}
+export function createInMemoryTelephonyAdapter() {
+    const calls = [];
+    let nextDialFailure;
+    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 });
+        },
+    };
+}

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/call-session",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.3"
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -32,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }