nixamp 0.77.0 → 0.78.1

package/dist/partyline.d.ts

@@ -1,12 +1,31 @@
-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;
-}
+/**
+ * The party line.
+ *
+ * A phone number, a six-digit code, and everybody who keyed the same code
+ * talking to each other. You call 408-357-2326, key 482917, and you are on the
+ * line with whoever else keyed 482917.
+ *
+ * The phone half -- answering, asking for the code on the keypad, the voices,
+ * Telnyx conferences and their four-hour expiry, who is in which room -- is
+ * @profullstack/group-call, which started life as this file and is shared with
+ * group.call.pit.world. What stays here is what a code means to nixamp: a code
+ * that belongs to a live stream is that stream's room, a code whose stream has
+ * ended offers a text for when it is back, and anything else is an ordinary
+ * room nobody had to create first.
+ */
+import { GroupCall, peopleHere, sameSecret, spokenCode, telnyxSms, type RoomInfo, type Sms, type TelnyxEvent } from "@profullstack/group-call";
+export { peopleHere, sameSecret, spokenCode, telnyxSms };
+export type { RoomInfo, Sms, TelnyxEvent };
+/**
+ * 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. 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 six-digit room code from whatever the caller keyed, or "". */
+export declare function roomCodeFrom(entered: unknown): string;
 /**
  * What the party line needs to know about a stream.
  *
@@ -29,10 +48,6 @@ export interface StreamLookup {
         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;
@@ -43,15 +58,10 @@ export interface PartyLineOptions {
      *
      * 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.
+     * long code that already has a messaging profile sends today.
      */
     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.
-     */
+    /** The account's ed25519 public key, base64, from the portal. */
     publicKey: string;
     /** What the caller hears before being asked for a room. */
     greeting?: string;
@@ -65,28 +75,6 @@ export interface PartyLineOptions {
     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.
  *
@@ -97,49 +85,19 @@ export declare function roomCodeFrom(entered: unknown): string;
  * 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;
 /**
  * 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.
+ * a noise the caller does not need.
  */
 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>;
-}
-/**
- * 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.
+ * The party line, as a thing that answers webhooks: a group call whose codes
+ * can also be streams.
  */
-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;
-    /** 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;
+export declare class PartyLine extends GroupCall {
     /** Who to text when a stream returns, by stream code. */
     private readonly reminders;
     /**
@@ -150,75 +108,20 @@ export declare class PartyLine {
      * break a promise made to somebody on a telephone.
      */
     private reminderStore;
+    private readonly party;
+    constructor(options: PartyLineOptions);
     /** 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;
-    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.
-     *
      * Keying a stream's code puts you in a room with the other people watching
-     * it. It does not play the stream at you, which is what it used to do: this
-     * is the phone line beside a broadcast, the way a podcast has an 800 number
-     * -- the show is on your screen and the phone is where you talk about it.
-     * Playing the audio down the phone was both the worse half of the idea and
-     * the one that kept failing, because a share link answers a 302 and a cookie
-     * rather than an MP3.
+     * it. It does not play the stream at you: this is the phone line beside a
+     * broadcast, the way a podcast has an 800 number -- the show is on your
+     * screen and the phone is where you talk about it.
      */
     private stream;
     /** Whether the caller took the reminder that was offered. */
@@ -237,77 +140,14 @@ 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.
-     *
-     * `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;
     /**
      * A line said into a room, to everybody on the phone in it. What the
      * trollbox becomes on the party line: the handle and the words, in the
-     * voice of whoever typed them. False when nobody is on the phone there,
-     * which is most of the time and costs nothing.
+     * voice of whoever typed them.
      */
     say(code: string, text: string, voice: string, settings?: {
         api_key_ref: string;
     }): Promise<boolean>;
-    /** Whether anybody is on the phone in a room, before a line is worth reading. */
-    hasCallers(code: string): boolean;
-    /**
-     * How many people are on the phone for a stream.
-     *
-     * The room's own count, now that a stream's code is a room like any other.
-     * It used to count legs with an MP3 playing into them, which is a thing that
-     * no longer happens.
-     */
+    /** How many people are on the phone for a stream: the room's own count. */
     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();
-    /** 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;
-    /** 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;