nixamp 0.9.6 → 0.9.8

package/dist/partyline.d.ts

@@ -99,6 +99,23 @@ export declare function roomCodeFrom(entered: unknown): string;
 export declare function pacificTime(at: number): string;
 /** How a code is read back: one digit at a time, because 482917 is not a number. */
 export declare function spokenCode(code: string): string;
+/**
+ * A track's name as it should be read out.
+ *
+ * What is playing is a filename more often than a title: "02 - ...And Justice
+ * For All.mp3" read aloud is "zero two dash dot dot dot", and the extension is
+ * a noise the caller does not need. The track number and extension go; what
+ * is left is close enough to a title to say.
+ */
+export declare function spokenTitle(nowPlaying: string): string;
+/**
+ * How many people are in a room, said to the one who just walked in.
+ *
+ * The count includes them: "there are 3 people in here" is what you say to the
+ * third person, and "you are the first one here" is what you say to the first,
+ * who would otherwise be told there is one person in an empty room.
+ */
+export declare function peopleHere(callers: number): string;
 export interface TelnyxEvent {
     event_type?: string;
     payload?: Record<string, unknown>;
@@ -119,6 +136,10 @@ export declare class PartyLine {
     private readonly legFrom;
     /** Legs that heard "press 1", and which stream they would be reminded about. */
     private readonly pendingReminder;
+    /** 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. */
+    private readonly plainVoice;
     /** Who to text when a stream returns, by stream code. */
     private readonly reminders;
     /**
@@ -216,9 +237,24 @@ export declare class PartyLine {
     }): Promise<number>;
     /** How many numbers are waiting to hear that a code is live. */
     waitingOn(code: string): number;
-    /** Put a leg into a room, making the conference if it is the first one there. */
+    /**
+     * Put a leg into a room, making the conference if it is the first one there.
+     *
+     * `welcome` is what the caller hears once they are in, before the count of
+     * who else is; a stream's room names the stream, an ordinary room reads its
+     * code back.
+     */
     private join;
     private enter;
+    /**
+     * Say hello to somebody who just joined, and only to them.
+     *
+     * Spoken into the conference rather than at the leg, because the leg is in
+     * the conference now and a speak on it is what the join interrupts. Telnyx
+     * addresses conference speech to particular participants, so the others in
+     * the room do not hear every arrival welcomed.
+     */
+    private greet;
     /**
      * How many people are on the phone for a stream.
      *
@@ -239,6 +275,8 @@ export declare class PartyLine {
      */
     private room;
     private get voice();
+    /** The voice for this leg: the good one, unless it has already failed them. */
+    private voiceFor;
     private get maxParticipants();
     /** One call-control command. True when Telnyx accepted it. */
     private command;

package/dist/partyline.js

@@ -40,6 +40,33 @@ const TELNYX_API = "https://api.telnyx.com/v2";
  * configuration rather than a constant for exactly that reason.
  */
 const DEFAULT_VOICE = "Telnyx.KokoroTTS.af";
+/**
+ * The voice a leg falls back to when the good one fails.
+ *
+ * Telnyx's Kokoro voice answered a prompt with a 500 once (2026-09-09), and
+ * what the caller got was a gather with no speech in it, ended at once with
+ * no digits, and asked again -- a line that "just repeats itself", silently,
+ * every ninety seconds. The plain Telnyx voice is older and worse and has not
+ * been seen to fail, which is the quality that matters on the second try.
+ */
+const FALLBACK_VOICE = "female";
+/**
+ * How long a caller has between digits before the code is treated as done.
+ *
+ * Telnyx's default is five seconds and did not fire: a caller who keyed five
+ * digits (one was lost in the keypad tone over the prompt) waited ten seconds
+ * in silence and hung up. Set explicitly so the partial code comes back to us
+ * quickly and we can say how many digits we got.
+ */
+const INTER_DIGIT_MS = 4000;
+/**
+ * How many times a caller is asked for a code before being let go.
+ *
+ * A gather that ends with nothing three times is a caller who cannot or will
+ * not key a code -- or a voice that is not being heard at all. Asking a
+ * fourth time is the loop that was reported; saying goodbye is not.
+ */
+const MAX_ASKS = 3;
 /** How long a signed webhook stays acceptable. Telnyx's own SDKs use five minutes. */
 const SIGNATURE_TOLERANCE_MS = 5 * 60 * 1000;
 /** A conference Telnyx will discard on its own, so we stop trusting ours first. */
@@ -92,6 +119,35 @@ export function pacificTime(at) {
 export function spokenCode(code) {
     return code.split("").join(", ");
 }
+/**
+ * A track's name as it should be read out.
+ *
+ * What is playing is a filename more often than a title: "02 - ...And Justice
+ * For All.mp3" read aloud is "zero two dash dot dot dot", and the extension is
+ * a noise the caller does not need. The track number and extension go; what
+ * is left is close enough to a title to say.
+ */
+export function spokenTitle(nowPlaying) {
+    return nowPlaying
+        .replace(/\.[a-z0-9]{2,4}$/i, "")
+        .replace(/^\s*\d{1,3}\s*[-._]\s*/, "")
+        .replace(/^[\s.]+/, "")
+        .trim();
+}
+/**
+ * How many people are in a room, said to the one who just walked in.
+ *
+ * The count includes them: "there are 3 people in here" is what you say to the
+ * third person, and "you are the first one here" is what you say to the first,
+ * who would otherwise be told there is one person in an empty room.
+ */
+export function peopleHere(callers) {
+    if (callers <= 1)
+        return "You are the first one here. Say hello when somebody joins.";
+    if (callers === 2)
+        return "There is one other person in here. Say hello.";
+    return `There are ${callers} people in here. Say hello.`;
+}
 /**
  * Telnyx signs `${timestamp}|${body}` with ed25519 and sends both back in
  * headers. Node will not take a bare 32-byte key, so it is wrapped in the
@@ -135,6 +191,10 @@ export class PartyLine {
     legFrom = new Map();
     /** Legs that heard "press 1", and which stream they would be reminded about. */
     pendingReminder = 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. */
+    plainVoice = new Set();
     /** Who to text when a stream returns, by stream code. */
     reminders = new Map();
     /**
@@ -244,8 +304,20 @@ export class PartyLine {
             await this.ask(leg);
             return;
         }
+        if (type === "call.speak.failed") {
+            // The voice, not the caller, failed. Everything this leg hears from now
+            // on is in the plain voice; the gather this speech belonged to ends on
+            // its own and is asked again, audibly this time.
+            this.plainVoice.add(leg);
+            this.options.onEvent?.("  a prompt could not be spoken; using the plain voice.");
+            return;
+        }
         if (type === "call.gather.ended") {
             const digits = typeof payload["digits"] === "string" ? payload["digits"] : "";
+            // A gather that ended because the caller hung up is not an answer, and
+            // anything sent to that leg now is a 422 for the log.
+            if (payload["status"] === "call_hangup")
+                return;
             // A leg that was just offered a reminder is answering that, not keying a
             // room code -- the same event carries both, so the question we asked is
             // what decides how to read it.
@@ -259,9 +331,14 @@ export class PartyLine {
             if (!code) {
                 // Re-ask rather than guess. Anything that is not six digits is not a
                 // room, and picking the nearest one would be picking a stranger's.
-                await this.ask(leg, "That is not a six digit code. ");
+                // Say what we got: five digits and silence is a caller who thinks
+                // the line is broken, and a caller who keyed nothing does not need
+                // telling their nothing was not six digits.
+                const got = digits.replace(/\D/g, "").length;
+                await this.ask(leg, got > 0 ? `I only got ${got} digits. ` : "I did not get a code. ");
                 return;
             }
+            this.asks.delete(leg);
             // A code that belongs to a stream is answered as a stream. Anything else
             // is an ordinary room, which is what this line was before.
             if (await this.stream(leg, code))
@@ -273,6 +350,8 @@ export class PartyLine {
             this.release(leg);
             this.legFrom.delete(leg);
             this.pendingReminder.delete(leg);
+            this.asks.delete(leg);
+            this.plainVoice.delete(leg);
             return;
         }
     }
@@ -290,16 +369,33 @@ export class PartyLine {
      * to press anything after; # is there for the ones who do it anyway.
      */
     async ask(leg, prefix = "") {
-        const greeting = this.options.greeting ??
-            "Welcome to the party line. Enter a six digit room code. Anyone who enters the same code will be on the line with you.";
+        const asked = (this.asks.get(leg) ?? 0) + 1;
+        this.asks.set(leg, asked);
+        if (asked > MAX_ASKS) {
+            // Three gathers with no code in them is not a caller who needs a fourth
+            // prompt. Whatever is wrong -- their keypad, our voice -- repeating
+            // ourselves is the failure that was reported, so this ends instead.
+            await this.command(leg, "speak", {
+                payload: "I did not get a room code. Goodbye.",
+                voice: this.voiceFor(leg),
+            });
+            await this.command(leg, "hangup", {});
+            return;
+        }
+        // Short, because callers key the code over the prompt and a long one
+        // costs digits: a tone pressed as the speech starts was not heard. The
+        // first time gets the welcome; a re-ask has already been welcomed.
+        const greeting = this.options.greeting ?? "Welcome to the nixamp party line. Enter the six digit room code.";
+        const payload = asked === 1 ? `${prefix}${greeting}` : `${prefix}Enter the six digit room code.`;
         await this.command(leg, "gather_using_speak", {
-            payload: `${prefix}${greeting}`,
-            voice: this.voice,
+            payload,
+            voice: this.voiceFor(leg),
             valid_digits: "0123456789",
             minimum_digits: CODE_LENGTH,
             maximum_digits: CODE_LENGTH,
             terminating_digit: "#",
             timeout_millis: 20000,
+            inter_digit_timeout_millis: INTER_DIGIT_MS,
         });
     }
     /**
@@ -324,13 +420,13 @@ export class PartyLine {
             return false;
         const live = streams.liveByCode(code);
         if (live !== undefined) {
-            const what = live.nowPlaying ? ` of ${live.nowPlaying}` : "";
-            await this.command(leg, "speak", {
-                payload: `You're on the line for ${live.name}${what}. ` +
-                    "Everyone here is watching it too. Say hello.",
-                voice: this.voice,
-            });
-            await this.join(leg, code);
+            // The welcome is said once they are in the room, not before: a speak
+            // on the leg followed by the conference join was cut off by the join --
+            // Telnyx reported it started and ended in the same millisecond -- and
+            // the caller heard twenty seconds of nothing and hung up.
+            const title = spokenTitle(live.nowPlaying);
+            const what = title ? `, playing ${title}` : "";
+            await this.join(leg, code, `Welcome to the live room for ${live.name}${what}. `);
             return true;
         }
         const ended = streams.endedByCode(code);
@@ -345,7 +441,7 @@ export class PartyLine {
                 `The live stream ended at ${pacificTime(ended.endedAt)}. ` +
                 "Call back later when they stream again. " +
                 "Press 1 to get a text message when they do.",
-            voice: this.voice,
+            voice: this.voiceFor(leg),
             valid_digits: "1",
             minimum_digits: 1,
             maximum_digits: 1,
@@ -370,7 +466,7 @@ export class PartyLine {
         this.options.onEvent?.(`  a caller asked to be told when ${code} is live again.`);
         await this.command(leg, "speak", {
             payload: "Got it. We will text you when they are live again. Goodbye.",
-            voice: this.voice,
+            voice: this.voiceFor(leg),
         });
         await this.command(leg, "hangup", {});
     }
@@ -408,13 +504,19 @@ export class PartyLine {
     waitingOn(code) {
         return this.reminders.get(code)?.size ?? 0;
     }
-    /** Put a leg into a room, making the conference if it is the first one there. */
-    async join(leg, code) {
+    /**
+     * Put a leg into a room, making the conference if it is the first one there.
+     *
+     * `welcome` is what the caller hears once they are in, before the count of
+     * who else is; a stream's room names the stream, an ordinary room reads its
+     * code back.
+     */
+    async join(leg, code, welcome = `Welcome to room ${spokenCode(code)}. `) {
         const room = this.room(code);
         if (room.callers >= this.maxParticipants) {
             await this.command(leg, "speak", {
                 payload: "That room is full. Goodbye.",
-                voice: this.voice,
+                voice: this.voiceFor(leg),
             });
             await this.command(leg, "hangup", {});
             return;
@@ -427,6 +529,7 @@ export class PartyLine {
             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;
             }
             // The id was stale in a way the clock did not predict -- an operator
@@ -445,7 +548,7 @@ export class PartyLine {
         if (typeof id !== "string") {
             await this.command(leg, "speak", {
                 payload: "Sorry, that room could not be opened. Goodbye.",
-                voice: this.voice,
+                voice: this.voiceFor(leg),
             });
             await this.command(leg, "hangup", {});
             this.legRoom.delete(leg);
@@ -454,6 +557,7 @@ export class PartyLine {
         room.conferenceId = id;
         room.startedAt = this.now();
         this.enter(room, leg);
+        await this.greet(room, leg, welcome);
     }
     enter(room, leg) {
         if (room.legs.has(leg))
@@ -462,6 +566,23 @@ export class PartyLine {
         room.callers = room.legs.size;
         this.options.onEvent?.(`  a caller joined a room (${room.callers} on the line).`);
     }
+    /**
+     * Say hello to somebody who just joined, and only to them.
+     *
+     * Spoken into the conference rather than at the leg, because the leg is in
+     * the conference now and a speak on it is what the join interrupts. Telnyx
+     * addresses conference speech to particular participants, so the others in
+     * the room do not hear every arrival welcomed.
+     */
+    async greet(room, leg, welcome) {
+        if (room.conferenceId === null)
+            return;
+        await this.request(`/conferences/${encodeURIComponent(room.conferenceId)}/actions/speak`, {
+            payload: `${welcome}${peopleHere(room.callers)}`,
+            voice: this.voiceFor(leg),
+            call_control_ids: [leg],
+        });
+    }
     /**
      * How many people are on the phone for a stream.
      *
@@ -515,6 +636,10 @@ export class PartyLine {
     get voice() {
         return this.options.voice ?? DEFAULT_VOICE;
     }
+    /** The voice for this leg: the good one, unless it has already failed them. */
+    voiceFor(leg) {
+        return this.plainVoice.has(leg) ? FALLBACK_VOICE : this.voice;
+    }
     get maxParticipants() {
         return this.options.maxParticipants ?? 50;
     }

package/dist/server.d.ts

@@ -17,6 +17,7 @@ import { Catalogs } from "./catalogs.ts";
 import { Names } from "./names.ts";
 import { Certs } from "./certs.ts";
 import { type Throttle } from "@profullstack/throttle";
+import { type Notification } from "./notify.ts";
 import { type Tools, type Track } from "./audio.ts";
 import { type Command, type RemoteTrack, type Snapshot } from "./protocol.ts";
 export declare const SERVE_BAND_COUNT = 24;
@@ -536,6 +537,17 @@ export interface HandlerOptions {
     follows?: Follows;
     /** The servers an account hearted. nixamp.com only, like follows. */
     favorites?: Favorites;
+    /**
+     * How an invite is sent: by email, by text, and the site the watch link is
+     * built on. nixamp.com only; a personal nixamp has no mail to send from.
+     */
+    invites?: {
+        email?: (to: string, note: Notification) => Promise<boolean>;
+        sms?: {
+            send(to: string, text: string): Promise<boolean>;
+        };
+        site: string;
+    };
     /** Names under `<handle>.<zone>` for an account's servers. nixamp.com only. */
     names?: Names;
     /** One wildcard certificate per handle, issued and renewed here. nixamp.com only. */

package/dist/server.js

@@ -47,6 +47,7 @@ import { forbiddenLibrary, readLibrary } from "./library.js";
 import { createThrottle, presentedCredential } from "@profullstack/throttle";
 import { Durable } from "./durable.js";
 import { notifyAll, resendEmail, webPush } from "./notify.js";
+import { inviteSubject, inviteText, isEmail, isPhone, watchLink } from "./invite.js";
 import { confirm, DEFAULT_DIRECTORY, Publisher } from "./publish.js";
 import { applyRemoteConfig, createPaywall, FREE_LISTENERS, paywallFromEnv, } from "./paywall.js";
 import { isRemote, playsInBrowser, sourceLabel } from "./sources.js";
@@ -1066,6 +1067,80 @@ export function createHandler(engine, options) {
             json(response, 202, { status: "issuing", host });
             return;
         }
+        // --- an invite: "so-and-so is streaming", by text or by email ------------
+        //
+        // The page had a Send button and nothing answered it: the message was
+        // written (invite.ts) and never given a route. Sending needs an account,
+        // because a text costs money and lands on somebody's phone, and the link
+        // sent is always the listen link -- an admin link handed out by mistake
+        // would hand out the server.
+        if (path === "/api/v1/invite" && options.invites && options.accounts) {
+            if (request.method !== "POST") {
+                json(response, 405, { error: "POST only" });
+                return;
+            }
+            const me = await options.accounts.whoIs(tokenFrom(request.headers));
+            if (me === null) {
+                json(response, 401, { error: "sign in to send an invite" });
+                return;
+            }
+            let body = {};
+            try {
+                body = JSON.parse(await readBody(request));
+            }
+            catch {
+                json(response, 400, { error: "bad JSON" });
+                return;
+            }
+            const to = String(body.to ?? "").trim();
+            const stream = String(body.stream ?? "").trim();
+            const byEmail = isEmail(to);
+            const bySms = !byEmail && isPhone(to);
+            if (!byEmail && !bySms) {
+                json(response, 400, { error: "give a phone number or an email address" });
+                return;
+            }
+            let origin = "";
+            try {
+                origin = new URL(stream).origin;
+            }
+            catch {
+                json(response, 400, { error: "that is not a stream link" });
+                return;
+            }
+            // What the directory knows about this server names it and gives the
+            // listen link and the phone code. An unlisted server is still sendable,
+            // as long as the link given is not the one that drives it.
+            const listed = options.directory?.list().find((one) => {
+                try {
+                    return new URL(one.url).origin === origin;
+                }
+                catch {
+                    return false;
+                }
+            });
+            const link = listed?.url ?? stream;
+            if (/\/admin\//.test(link) || /[?&]k=/.test(link) && !listed) {
+                json(response, 400, { error: "send the view link, not the admin link" });
+                return;
+            }
+            const invite = {
+                name: listed?.name ?? new URL(link).hostname,
+                link: watchLink(link, options.invites.site),
+                phone: listed ? CALL_IN_NUMBER : "",
+                code: listed?.code ?? "",
+            };
+            const sender = byEmail ? options.invites.email : options.invites.sms;
+            if (!sender) {
+                json(response, 503, { error: byEmail ? "this site cannot send email yet" : "this site cannot send texts yet" });
+                return;
+            }
+            const ok = byEmail
+                ? await options.invites.email(to, { title: inviteSubject(invite), body: inviteText(invite), url: invite.link })
+                : await options.invites.sms.send(to, inviteText(invite));
+            json(response, ok ? 200 : 502, ok ? { sent: to } : { error: "the message did not go" });
+            return;
+        }
         // Favourites: the servers you hearted, kept against your account. Reading
         // the directory and listening need no account; remembering where you
         // listened does, because there has to be somebody to remember it for.
@@ -3266,6 +3341,8 @@ export async function serve(argv, version = "0.1.0") {
                 // a guess with an Authorization header buys itself the bigger budget.
                 { path: "/api/v1/auth/", limit: 20, credential: false },
                 { path: "/api/v1/dns/", limit: 30 },
+                // A text costs money and lands on a phone: ten a minute is plenty.
+                { path: "/api/v1/invite", limit: 10 },
                 { path: "/api/v1/dns", limit: 30 },
                 { path: "/api/v1/certs", limit: 30 },
                 { path: "/api/health", open: true },
@@ -3538,6 +3615,33 @@ export async function serve(argv, version = "0.1.0") {
         ...(directory ? { directory } : {}),
         ...(follows ? { follows, vapidPublicKey } : {}),
         ...(favorites ? { favorites } : {}),
+        // Invites go out the same way follow notifications do, and only from a
+        // site that has somebody to send them for.
+        ...(pool
+            ? {
+                invites: {
+                    site: (process.env["NIXAMP_SITE"] ?? DEFAULT_DIRECTORY).replace(/\/+$/, ""),
+                    ...(process.env["RESEND_API_KEY"]
+                        ? {
+                            email: resendEmail({
+                                apiKey: process.env["RESEND_API_KEY"],
+                                from: process.env["NIXAMP_MAIL_FROM"] ?? "nixamp <notifications@nixamp.com>",
+                                onEvent: (message) => console.log(message),
+                            }),
+                        }
+                        : {}),
+                    ...(process.env["TELNYX_API_KEY"] && process.env["PARTYLINE_SMS_FROM"]
+                        ? {
+                            sms: telnyxSms({
+                                apiKey: process.env["TELNYX_API_KEY"],
+                                from: process.env["PARTYLINE_SMS_FROM"],
+                                onEvent: (message) => console.log(message),
+                            }),
+                        }
+                        : {}),
+                },
+            }
+            : {}),
         ...(names ? { names } : {}),
         ...(certs ? { certs } : {}),
         dnsZone: zoneName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",