@profullstack/group-call 0.2.0 → 0.4.0

package/README.md

@@ -43,6 +43,9 @@ await line.handle(JSON.parse(rawBody).data);
 - **ElevenLabs voices** with `voiceSettings: { api_key_ref }`.
 - **Agents with names.** `line.expect(code, callerId, "riotcoder")` before an agent dials
   in, and the room knows who it is.
+- **Call people in.** `dial(code, phone, { from, connectionId, name?, prompt? })` rings a phone
+  from your number. Whoever answers presses 1 and is in the room, so voicemail never joins.
+  The room rides in the call's `client_state`, so an answer after a restart still lands right.
 - **Room API.** `say(code, text, voice?)` speaks into a room. Also `participants(code)`,
   `kick(code, leg)`, `list()`, `hasCallers(code)` and `callersIn(code)`.
 - **App hooks.** `onCode` can join, welcome, reject, or take the call over: `call.gather(...)`
@@ -52,6 +55,9 @@ await line.handle(JSON.parse(rawBody).data);
   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

@@ -176,6 +176,8 @@ export declare class GroupCall {
     protected readonly legFrom: Map<string, string>;
     /** Legs answering a question an `onCode` hook asked, and what to do with the answer. */
     private readonly pendingGather;
+    /** Phones `dial` is ringing, and the room each is wanted in, until they pick up. */
+    private readonly dialled;
     /** How many times each leg has been asked for a code, so it is not forever. */
     private readonly asks;
     /** Legs whose voice failed once, which hear the plain one from then on. */
@@ -198,6 +200,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[];
     /**
@@ -217,6 +234,30 @@ export declare class GroupCall {
      * this cares about five.
      */
     handle(event: TelnyxEvent): Promise<void>;
+    /**
+     * Ring a phone and bring whoever answers into the room on `code`, so a person
+     * can be called in rather than having to dial in.
+     *
+     * The call goes out on `connectionId` (the call-control app whose webhooks
+     * reach this instance) from `from`, best the room's own dial-in number, so a
+     * missed call rings back into the line. Whoever picks up is asked to press 1
+     * before joining: a voicemail greeting or a wrong number never lands in the
+     * room. The room is carried in the call's client_state too, so an answer
+     * that arrives after a restart still knows where it was going. Returns the
+     * new leg, or null when Telnyx would not place the call.
+     */
+    dial(code: string, to: string, opts: {
+        from: string;
+        connectionId: string;
+        name?: string;
+        prompt?: string;
+        welcome?: string;
+        timeoutSecs?: number;
+    }): Promise<{
+        leg: string;
+    } | null>;
+    /** A dialled phone was picked up: press 1 to join, so voicemail never does. */
+    private offer;
     /** Hand a well-formed code to the app, and act on what it says the code is. */
     private routeCode;
     /** A caller, as a hook sees them. */

package/dist/index.js

@@ -61,6 +61,24 @@ const NUMBER_WORDS = ["zero", "one", "two", "three", "four", "five", "six", "sev
 export function digitWords(length) {
     return `${NUMBER_WORDS[length] ?? String(length)} digit`;
 }
+/** The room a dialled leg's client_state names, or null when the call is not one `dial` placed. */
+function dialState(raw) {
+    if (typeof raw !== "string" || raw === "")
+        return null;
+    try {
+        const s = JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
+        if (s["gc"] !== "dial" || typeof s["code"] !== "string" || !/^\d+$/.test(s["code"]))
+            return null;
+        return {
+            code: s["code"],
+            ...(typeof s["prompt"] === "string" ? { prompt: s["prompt"] } : {}),
+            ...(typeof s["welcome"] === "string" ? { welcome: s["welcome"] } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * A room code, from whatever the caller keyed.
  *
@@ -165,6 +183,8 @@ export class GroupCall {
     legFrom = new Map();
     /** Legs answering a question an `onCode` hook asked, and what to do with the answer. */
     pendingGather = new Map();
+    /** Phones `dial` is ringing, and the room each is wanted in, until they pick up. */
+    dialled = new Map();
     /** How many times each leg has been asked for a code, so it is not forever. */
     asks = new Map();
     /** Legs whose voice failed once, which hear the plain one from then on. */
@@ -199,6 +219,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);
@@ -239,9 +295,14 @@ export class GroupCall {
             return;
         }
         if (type === "call.answered") {
-            // An answered outbound leg is somebody else's business.
-            if (payload["direction"] === "outgoing")
+            // An answered outbound leg is somebody else's business, unless it is one
+            // `dial` rang: then it is a person picking up, to be asked in.
+            if (payload["direction"] === "outgoing") {
+                const dialled = this.dialled.get(leg) ?? dialState(payload["client_state"]);
+                if (dialled)
+                    await this.offer(leg, dialled);
                 return;
+            }
             await this.ask(leg);
             return;
         }
@@ -293,12 +354,60 @@ export class GroupCall {
         if (type === "conference.participant.left" || type === "call.hangup") {
             this.release(leg);
             this.legFrom.delete(leg);
+            this.dialled.delete(leg);
             this.pendingGather.delete(leg);
             this.asks.delete(leg);
             this.plainVoice.delete(leg);
             return;
         }
     }
+    /**
+     * Ring a phone and bring whoever answers into the room on `code`, so a person
+     * can be called in rather than having to dial in.
+     *
+     * The call goes out on `connectionId` (the call-control app whose webhooks
+     * reach this instance) from `from`, best the room's own dial-in number, so a
+     * missed call rings back into the line. Whoever picks up is asked to press 1
+     * before joining: a voicemail greeting or a wrong number never lands in the
+     * room. The room is carried in the call's client_state too, so an answer
+     * that arrives after a restart still knows where it was going. Returns the
+     * new leg, or null when Telnyx would not place the call.
+     */
+    async dial(code, to, opts) {
+        const number = normalNumber(to);
+        if (!number || !opts.connectionId || !opts.from)
+            return null;
+        const state = { code, ...(opts.prompt ? { prompt: opts.prompt.slice(0, 300) } : {}), ...(opts.welcome ? { welcome: opts.welcome.slice(0, 200) } : {}) };
+        const placed = (await this.request("/calls", {
+            connection_id: opts.connectionId,
+            to: number,
+            from: normalNumber(opts.from),
+            timeout_secs: opts.timeoutSecs ?? 30,
+            client_state: Buffer.from(JSON.stringify({ gc: "dial", ...state }), "utf8").toString("base64"),
+        }));
+        const leg = placed?.data?.call_control_id;
+        if (typeof leg !== "string")
+            return null;
+        this.dialled.set(leg, state);
+        this.legFrom.set(leg, number);
+        if (opts.name)
+            this.expect(code, number, opts.name, 5 * 60 * 1000);
+        this.options.onEvent?.(`  ringing a phone into a room.`);
+        return { leg };
+    }
+    /** A dialled phone was picked up: press 1 to join, so voicemail never does. */
+    async offer(leg, dialled, tries = 1) {
+        this.dialled.delete(leg);
+        const prompt = dialled.prompt ?? "This is group call, calling you into a room.";
+        await this.gather(leg, `${tries > 1 ? "" : `${prompt} `}Press 1 to join.`, { validDigits: "0123456789", maximumDigits: 1, timeoutMillis: 10000 }, async (digits) => {
+            if (digits === "1")
+                return this.join(leg, dialled.code, dialled.welcome);
+            if (tries < 2)
+                return this.offer(leg, dialled, tries + 1);
+            await this.command(leg, "speak", { payload: "Okay, not joining. Goodbye.", ...this.voiceBody(leg) });
+            await this.command(leg, "hangup", {});
+        });
+    }
     /** Hand a well-formed code to the app, and act on what it says the code is. */
     async routeCode(leg, code) {
         const answer = this.options.onCode ? await this.options.onCode(code, this.callHandle(leg)) : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/group-call",
-  "version": "0.2.0",
+  "version": "0.4.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",