nixamp 0.2.0 → 0.4.0

package/dist/partyline.d.ts

@@ -0,0 +1,259 @@
+export interface RoomInfo {
+    /** The six-digit code, which is the room's whole identity. */
+    code: string;
+    /** Telnyx's id for the conference, once a first caller has made one. */
+    conferenceId: string | null;
+    /** How many legs we have put in, less the ones we have seen leave. */
+    callers: number;
+    startedAt: number;
+}
+/**
+ * What the party line needs to know about a stream.
+ *
+ * A narrow view of the Directory rather than the Directory itself, so this
+ * module stays a function of its inputs and a test can describe a stream
+ * without standing one up.
+ */
+export interface StreamLookup {
+    liveByCode(code: string): {
+        name: string;
+        url: string;
+        audio: string;
+        nowPlaying: string;
+        startedAt: number;
+    } | undefined;
+    endedByCode(code: string): {
+        name: string;
+        nowPlaying: string;
+        startedAt: number;
+        endedAt: number;
+    } | undefined;
+}
+/** Sending a text. Injected because the number that sends is not this one. */
+export interface Sms {
+    send(to: string, text: string): Promise<boolean>;
+}
+export interface PartyLineOptions {
+    /** A Telnyx API key with call-control rights. */
+    apiKey: string;
+    /** The directory, on the instance that hosts one. */
+    streams?: StreamLookup;
+    /**
+     * How to text somebody when a stream comes back.
+     *
+     * Not from the toll-free number the call arrived on: toll-free A2P messaging
+     * is filtered by carriers until the number is verified, and ours is not. A
+     * long code that already has a messaging profile sends today, so reminders
+     * go out from there and the verification can land whenever it lands.
+     */
+    sms?: Sms;
+    /**
+     * The account's ed25519 public key, base64, from the portal. Without it
+     * every webhook is refused: an unauthenticated call-control webhook lets a
+     * stranger drive calls we are paying for.
+     */
+    publicKey: string;
+    /** What the caller hears before being asked for a room. */
+    greeting?: string;
+    voice?: string;
+    /** A ceiling per room, so one room cannot spend the whole balance. */
+    maxParticipants?: number;
+    /** The number to tell people to call back on. Injected, not hardcoded. */
+    callIn?: string;
+    /** Injected for tests. */
+    now?: () => number;
+    fetch?: typeof globalThis.fetch;
+    onEvent?: (message: string) => void;
+}
+/**
+ * How long a room code is.
+ *
+ * Six digits, because the code has to survive being read down a phone line and
+ * typed into a URL. The generated ids this replaces were long enough that
+ * nobody could say one out loud, which is the whole failure being fixed: a
+ * room code is something you tell somebody, so it has to be short enough to
+ * hold in your head between hearing it and dialling it.
+ */
+export declare const CODE_LENGTH = 6;
+/**
+ * A room code, from whatever the caller keyed.
+ *
+ * Digits only, and exactly six of them. Five is not a near miss to be
+ * charitable about -- it is a different room, and guessing which one they
+ * meant would drop somebody into a stranger's conversation.
+ *
+ * Nothing here is case-sensitive because nothing here has a case. That is the
+ * point of digits over letters: a phone keypad has one way to type a 4, and no
+ * two people disagree about how to say it.
+ */
+export declare function roomCodeFrom(entered: unknown): string;
+/**
+ * A time as a caller should hear it.
+ *
+ * Pacific, spelled out, because that is the clock the streams are announced on
+ * and a bare "9:27" down a phone line is a time in somebody's head rather than
+ * a time. Built with Intl rather than arithmetic: the offset changes twice a
+ * year and hand-rolled zone maths is how you end up an hour out for three
+ * weeks every spring.
+ */
+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;
+export interface TelnyxEvent {
+    event_type?: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * The party line, as a thing that answers webhooks.
+ *
+ * It owns no socket and no timer. The server hands it a verified event and it
+ * issues whatever call-control commands that event calls for, which makes the
+ * whole state machine testable with a fetch that records what it was asked.
+ */
+export declare class PartyLine {
+    private readonly options;
+    private readonly rooms;
+    /** Which room a leg is heading for, between asking and being answered. */
+    private readonly legRoom;
+    /** The number each caller is calling from, for a reminder they ask for. */
+    private readonly legFrom;
+    /** Legs that heard "press 1", and which stream they would be reminded about. */
+    private readonly pendingReminder;
+    /** Who to text when a stream returns, by stream code. */
+    private readonly reminders;
+    /**
+     * The same list, somewhere that survives a deploy.
+     *
+     * A caller who pressed 1 was told they would be texted. Keeping that promise
+     * only in a Map meant a restart broke it silently, which is the worst way to
+     * break a promise made to somebody on a telephone.
+     */
+    private reminderStore;
+    /** Start echoing reminders somewhere durable, and put back what was there. */
+    persistRemindersTo(store: {
+        add: (code: string, phone: string) => void;
+        take: (code: string) => Promise<string[]>;
+    }, waiting?: ReadonlyMap<string, ReadonlySet<string>>): void;
+    /**
+     * Legs listening to a stream, by its code.
+     *
+     * Separate from the rooms because a stream listener is not in a conference:
+     * they are a leg with an MP3 playing into it. Nothing else was counting
+     * them, so the directory had no way to say how many people were on the
+     * phone for a broadcast.
+     */
+    private readonly streamLegs;
+    private readonly key;
+    private readonly fetch;
+    private readonly now;
+    constructor(options: PartyLineOptions);
+    /** True when this instance can actually check a signature. */
+    get armed(): boolean;
+    /**
+     * Whether a webhook really came from Telnyx.
+     *
+     * The body has to be the bytes that arrived. Parsing and reserialising JSON
+     * changes key order and whitespace, and the signature is over the original.
+     */
+    verify(rawBody: string, signature: string | undefined, timestamp: string | undefined): boolean;
+    /**
+     * The rooms with someone in them, busiest first, with their codes.
+     *
+     * The code is published on purpose. An earlier version withheld it on the
+     * reasoning that a code is the only thing between a stranger and a
+     * conversation -- true of a private room, and wrong here: this is a public
+     * call-in line, and a listing you cannot dial is a listing of nothing. The
+     * code is how you join, so it is what the list is for.
+     */
+    list(): {
+        code: string;
+        callers: number;
+        startedAt: number;
+    }[];
+    /**
+     * Drive one call-control event.
+     *
+     * Every branch returns rather than falling through, because an event we do
+     * not handle is the normal case -- Telnyx sends a dozen kinds per call and
+     * this cares about four.
+     */
+    handle(event: TelnyxEvent): Promise<void>;
+    /**
+     * Ask for a room code, on the keypad.
+     *
+     * Not by voice, which is the one thing here that changed its mind. Speech
+     * suited a room *name* -- "blue" misheard is still recognisably a word, and
+     * a person can say it differently the second time. A six-digit code has no
+     * such slack: one digit misheard is a different room that also exists, and
+     * the caller lands in a stranger's conversation with nothing to tell them
+     * they went wrong. A keypad cannot mishear a 4.
+     *
+     * Six digits terminates the gather on its own, so the caller does not have
+     * to press anything after; # is there for the ones who do it anyway.
+     */
+    private ask;
+    /**
+     * Answer a code that belongs to a stream, rather than a room.
+     *
+     * Returns false when the code is nobody's stream, which is how an ordinary
+     * room code still works: this line was a party line before it was a way into
+     * a broadcast, and a code that means nothing to the directory should still
+     * mean a room.
+     */
+    private stream;
+    /** Whether the caller took the reminder that was offered. */
+    private reminder;
+    /**
+     * A stream came back: text whoever asked to be told.
+     *
+     * The list is cleared as it is sent. A reminder is a thing somebody asked
+     * for once, and texting them every time that stream starts for the rest of
+     * the week is how a useful message becomes the reason they block the number.
+     */
+    wentLive(stream: {
+        code: string;
+        name: string;
+        nowPlaying: string;
+    }): 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. */
+    private join;
+    private enter;
+    /** How many people are listening to a stream by phone. */
+    listenersOn(code: string): number;
+    /** A leg that hung up or was dropped, wherever it was. */
+    private release;
+    /**
+     * The room on this code, made if nobody is using it.
+     *
+     * Entering a code nobody is in opens that room rather than failing. The code
+     * is a rendezvous, not a credential: two people who agree on 482917
+     * beforehand should both be able to dial in, and neither of them should have
+     * had to create it first.
+     */
+    private room;
+    private get voice();
+    private get maxParticipants();
+    /** One call-control command. True when Telnyx accepted it. */
+    private command;
+    /** A POST to Telnyx, or null if it did not work. */
+    private request;
+}
+/**
+ * Texting, over Telnyx.
+ *
+ * A separate `from` because it is a different number: the call arrives on the
+ * toll-free line, but toll-free A2P messaging is filtered by carriers until
+ * that number is verified and ours is not yet. The long code already carries a
+ * messaging profile, so it can send today -- and when verification lands, this
+ * becomes a one-line change rather than a redesign.
+ */
+export declare function telnyxSms({ apiKey, from, fetch, onEvent }: {
+    apiKey: string;
+    from: string;
+    fetch?: typeof globalThis.fetch;
+    onEvent?: (message: string) => void;
+}): Sms;
+/** Constant-time compare, for the places a token is checked rather than signed. */
+export declare function sameSecret(a: string, b: string): boolean;