@profullstack/group-call 0.1.0 → 0.3.0

package/README.md

@@ -47,6 +47,14 @@ await line.handle(JSON.parse(rawBody).data);
   `kick(code, leg)`, `list()`, `hasCallers(code)` and `callersIn(code)`.
 - **App hooks.** `onCode` can join, welcome, reject, or take the call over: `call.gather(...)`
   asks another question (nixamp's "press 1 for a text").
+- **Live transcripts.** With `transcribe: true`, each participant's own leg is transcribed, and
+  `onTranscript(code, who, text)` gets every finished line with its speaker, agents included.
+  Telnyx bills this per minute per leg, so it's off unless you ask for it.
+- **Survives restarts.** Conference names carry a keyed hash of the room code. After a restart,
+  the first caller into a room joins its running conference, not a new one.
+- **Deploy-proof rooms.** Save `participants(code)` plus each room's conference id from `onJoin`/`onLeave`,
+  and pass them to `restore()` at boot. Each conference is checked against Telnyx, and the legs still in
+  it come back with their names, so a restart neither splits a room nor forgets who is in it.
 - `telnyxSms`, `verifyTelnyx`, `newRoomCode`, `sameSecret` helpers.
 
 MIT

package/dist/index.d.ts

@@ -121,6 +121,16 @@ export interface GroupCallOptions {
     onJoin?: (code: string, who: Participant, room: RoomInfo) => void;
     /** A person or agent left a room. */
     onLeave?: (code: string, who: Participant, room: RoomInfo) => void;
+    /**
+     * Transcribe what each participant says, on their own leg, so every line has a
+     * speaker. Telnyx bills it per minute per leg; off unless asked for.
+     */
+    transcribe?: boolean | {
+        engine?: string;
+        language?: string;
+    };
+    /** A finished line somebody said in a room (needs `transcribe`). */
+    onTranscript?: (code: string, who: Participant, text: string) => void;
     /** Injected for tests. */
     now?: () => number;
     fetch?: typeof globalThis.fetch;
@@ -188,6 +198,21 @@ export declare class GroupCall {
         callers: number;
         startedAt: number;
     }[];
+    /**
+     * Put back rooms a previous process knew about: a deploy or a crash must not
+     * split a room. Each saved conference is checked against Telnyx, and only the
+     * legs still in it come back, with their names. A leg Telnyx has that the save
+     * missed comes back unnamed. Returns how many rooms and legs were restored.
+     */
+    restore(saved: {
+        code: string;
+        conferenceId: string;
+        startedAt: number;
+        participants: Participant[];
+    }[]): Promise<{
+        rooms: number;
+        legs: number;
+    }>;
     /** Who is on the line in a room, earliest first. */
     participants(code: string): Participant[];
     /**
@@ -228,6 +253,17 @@ export declare class GroupCall {
      * who else is.
      */
     join(leg: string, code: string, welcome?: string): Promise<void>;
+    /**
+     * A conference's name: findable again after a restart, but not the code itself,
+     * which would be a room's whole key sitting in somebody else's dashboard. A
+     * hash keyed with the API key, so it cannot be walked back to the code.
+     */
+    private conferenceName;
+    /**
+     * Find this room's conference on Telnyx if it is still running, and the legs
+     * already in it. True when one was found.
+     */
+    private recover;
     private enter;
     /** The name an agent registered for this number and room, used once. */
     private claimName;
@@ -264,6 +300,8 @@ export declare class GroupCall {
     private get maxParticipants();
     /** One call-control command. True when Telnyx accepted it. */
     protected command(leg: string, action: string, body: unknown): Promise<boolean>;
+    /** A GET from Telnyx, or null if it did not work. */
+    protected get(path: string): Promise<unknown | null>;
     /** A POST to Telnyx, or null if it did not work. */
     protected request(path: string, body: unknown): Promise<unknown | null>;
 }

package/dist/index.js

@@ -25,7 +25,7 @@
  * conversation with nothing to tell them they went wrong. An agent keys it
  * too, with DTMF, so a person and an agent arrive the same way.
  */
-import { createPublicKey, verify as verifySignature, timingSafeEqual } from "node:crypto";
+import { createHmac, createPublicKey, verify as verifySignature, timingSafeEqual } from "node:crypto";
 /** Where Telnyx's REST API lives. */
 export const TELNYX_API = "https://api.telnyx.com/v2";
 /**
@@ -199,6 +199,42 @@ export class GroupCall {
             .map(({ code, callers, startedAt }) => ({ code, callers, startedAt }))
             .sort((a, b) => b.callers - a.callers || a.startedAt - b.startedAt);
     }
+    /**
+     * Put back rooms a previous process knew about: a deploy or a crash must not
+     * split a room. Each saved conference is checked against Telnyx, and only the
+     * legs still in it come back, with their names. A leg Telnyx has that the save
+     * missed comes back unnamed. Returns how many rooms and legs were restored.
+     */
+    async restore(saved) {
+        let rooms = 0;
+        let legs = 0;
+        for (const r of saved) {
+            const conf = (await this.get(`/conferences/${encodeURIComponent(r.conferenceId)}`));
+            if (!conf?.data || (conf.data.status && conf.data.status !== "in_progress"))
+                continue;
+            const list = (await this.get(`/conferences/${encodeURIComponent(r.conferenceId)}/participants?page[size]=100`));
+            const present = new Set((list?.data ?? []).filter((p) => p.status !== "left" && typeof p.call_control_id === "string").map((p) => p.call_control_id));
+            if (present.size === 0)
+                continue;
+            const room = this.room(r.code);
+            room.conferenceId = r.conferenceId;
+            room.startedAt = r.startedAt;
+            const known = new Map(r.participants.map((p) => [p.leg, p]));
+            for (const leg of present) {
+                const who = known.get(leg) ?? { leg, from: "", name: "", joinedAt: r.startedAt };
+                room.legs.set(leg, who);
+                this.legRoom.set(leg, r.code);
+                if (who.from)
+                    this.legFrom.set(leg, who.from);
+                legs += 1;
+            }
+            room.callers = room.legs.size;
+            rooms += 1;
+        }
+        if (rooms)
+            this.options.onEvent?.(`  restored ${rooms} room(s) with ${legs} on the line.`);
+        return { rooms, legs };
+    }
     /** Who is on the line in a room, earliest first. */
     participants(code) {
         const room = this.rooms.get(code);
@@ -279,6 +315,17 @@ export class GroupCall {
             await this.routeCode(leg, code);
             return;
         }
+        if (type === "call.transcription") {
+            const data = (payload["transcription_data"] ?? {});
+            const text = typeof data["transcript"] === "string" ? data["transcript"].trim() : "";
+            if (!text || data["is_final"] === false)
+                return;
+            const code = this.legRoom.get(leg);
+            const who = code !== undefined ? this.rooms.get(code)?.legs.get(leg) : undefined;
+            if (code !== undefined && who)
+                this.options.onTranscript?.(code, who, text);
+            return;
+        }
         if (type === "conference.participant.left" || type === "call.hangup") {
             this.release(leg);
             this.legFrom.delete(leg);
@@ -396,8 +443,19 @@ export class GroupCall {
             // ended it, or Telnyx did. Fall through and make a new one.
             room.conferenceId = null;
         }
+        // After a restart our map is empty, but the room's conference may still be
+        // running with people in it: find it by name and join that, not a new one.
+        if (room.conferenceId === null && (await this.recover(room))) {
+            const joined = await this.request(`/conferences/${encodeURIComponent(room.conferenceId)}/actions/join`, { call_control_id: leg, start_conference_on_enter: true });
+            if (joined !== null) {
+                this.enter(room, leg);
+                await this.greet(room, leg, welcome);
+                return;
+            }
+            room.conferenceId = null;
+        }
         const created = await this.request("/conferences", {
-            name: `${this.options.conferencePrefix ?? "groupcall"}-${this.now()}-${room.legs.size}`,
+            name: `${this.conferenceName(code)}${this.now()}`,
             call_control_id: leg,
             start_conference_on_create: true,
             max_participants: this.maxParticipants,
@@ -416,6 +474,41 @@ export class GroupCall {
         this.enter(room, leg);
         await this.greet(room, leg, welcome);
     }
+    /**
+     * A conference's name: findable again after a restart, but not the code itself,
+     * which would be a room's whole key sitting in somebody else's dashboard. A
+     * hash keyed with the API key, so it cannot be walked back to the code.
+     */
+    conferenceName(code) {
+        const tag = createHmac("sha256", this.options.apiKey).update(`room:${code}`).digest("hex").slice(0, 12);
+        return `${this.options.conferencePrefix ?? "groupcall"}-${tag}-`;
+    }
+    /**
+     * Find this room's conference on Telnyx if it is still running, and the legs
+     * already in it. True when one was found.
+     */
+    async recover(room) {
+        const list = await this.get(`/conferences?filter[status]=in_progress&page[size]=250`);
+        const found = (list?.data ?? [])
+            .filter((c) => typeof c.id === "string" && String(c.name ?? "").startsWith(this.conferenceName(room.code)))
+            .sort((a, b) => String(b.created_at ?? "").localeCompare(String(a.created_at ?? "")))[0];
+        if (!found?.id)
+            return false;
+        room.conferenceId = found.id;
+        const created = Date.parse(found.created_at ?? "");
+        room.startedAt = Number.isFinite(created) ? created : this.now();
+        const people = await this.get(`/conferences/${encodeURIComponent(found.id)}/participants?page[size]=100`);
+        for (const p of people?.data ?? []) {
+            const id = p.call_control_id;
+            if (typeof id !== "string" || p.status === "left" || room.legs.has(id))
+                continue;
+            room.legs.set(id, { leg: id, from: "", name: "", joinedAt: room.startedAt });
+            this.legRoom.set(id, room.code);
+        }
+        room.callers = room.legs.size;
+        this.options.onEvent?.(`  found room ${room.code}'s conference still running (${room.callers} on the line).`);
+        return true;
+    }
     enter(room, leg) {
         if (room.legs.has(leg))
             return;
@@ -425,6 +518,16 @@ export class GroupCall {
         room.callers = room.legs.size;
         this.options.onEvent?.(`  ${who.name || "a caller"} joined a room (${room.callers} on the line).`);
         this.options.onJoin?.(room.code, who, this.info(room));
+        const t = this.options.transcribe;
+        if (t) {
+            const opts = typeof t === "object" ? t : {};
+            // Only what this participant says (their side of the leg), so each line has one speaker.
+            void this.command(leg, "transcription_start", {
+                language: opts.language ?? "en",
+                transcription_engine: opts.engine ?? "Deepgram",
+                transcription_tracks: "inbound",
+            });
+        }
     }
     /** The name an agent registered for this number and room, used once. */
     claimName(code, from) {
@@ -546,6 +649,22 @@ export class GroupCall {
         const path = `/calls/${encodeURIComponent(leg)}/actions/${action}`;
         return (await this.request(path, body)) !== null;
     }
+    /** A GET from Telnyx, or null if it did not work. */
+    async get(path) {
+        try {
+            const response = await this.fetch(`${TELNYX_API}${path}`, { headers: { authorization: `Bearer ${this.options.apiKey}` } });
+            if (!response.ok) {
+                this.options.onEvent?.(`  telnyx GET ${path} -> ${response.status}`);
+                return null;
+            }
+            const text = await response.text();
+            return text ? JSON.parse(text) : {};
+        }
+        catch (error) {
+            this.options.onEvent?.(`  telnyx GET ${path} failed: ${error.message}`);
+            return null;
+        }
+    }
     /** A POST to Telnyx, or null if it did not work. */
     async request(path, body) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/group-call",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A group call on a phone number: dial in, key a room code, talk with everyone else who did, people and AI agents alike. Telnyx Call Control state machine extracted from nixamp's party line; the engine behind nixamp live joins and group.call.pit.world.",
   "license": "MIT",
   "type": "module",