npm - nixamp - Versions diffs - 0.3.0 → 0.4.0 - Mend

nixamp 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/dist/directory.d.ts +126 -3
package/dist/directory.js +171 -7
package/dist/durable.d.ts +70 -0
package/dist/durable.js +156 -0
package/dist/follows.d.ts +92 -0
package/dist/follows.js +248 -0
package/dist/notify.d.ts +83 -0
package/dist/notify.js +126 -0
package/dist/optin.d.ts +37 -0
package/dist/optin.js +122 -0
package/dist/partyline.d.ts +259 -0
package/dist/partyline.js +616 -0
package/dist/paywall.js +1 -1
package/dist/playlist.js +5 -0
package/dist/publish.d.ts +21 -0
package/dist/publish.js +18 -2
package/dist/server.d.ts +15 -0
package/dist/server.js +558 -11
package/dist/share.d.ts +10 -0
package/dist/share.js +12 -0
package/package.json +5 -2
package/src/directory.ts +232 -5
package/src/durable.ts +215 -0
package/src/follows.ts +307 -0
package/src/notify.ts +217 -0
package/src/optin.ts +128 -0
package/src/partyline.ts +742 -0
package/src/paywall.ts +1 -1
package/src/playlist.ts +5 -0
package/src/publish.ts +38 -2
package/src/server.ts +610 -10
package/src/share.ts +13 -0
package/web/dist/assets/{index-0wAv50Ay.css → index-DSIDSSPF.css} +1 -1
package/web/dist/assets/index-qRguFskX.js +1 -0
package/web/dist/index.html +27 -2
package/web/dist/install.sh +82 -0
package/web/dist/sw.js +45 -3
package/web/dist/assets/index-WYJ6R4uF.js +0 -1

package/dist/optin.js ADDED Viewed

@@ -0,0 +1,122 @@
+/**
+ * The page that explains the text messages.
+ *
+ * Not decoration and not marketing. A carrier reviewing a toll-free number for
+ * A2P messaging asks to see where the consent comes from, and answers "a
+ * screenshot" -- which is awkward when the consent is somebody pressing 1 on a
+ * telephone and there is no screen to shoot. This page is that evidence: the
+ * exact prompt the caller hears, what they get, how often, and how to stop.
+ *
+ * It is also the honest thing to publish regardless of who is asking. Anyone
+ * who gets a text from us can find out here why, and stop it, without having
+ * to reply to a number they do not recognise.
+ *
+ * Served as a page of its own rather than a route in the app, because it has
+ * to be readable by someone with no JavaScript and no account -- a reviewer,
+ * or a person holding a phone that just buzzed.
+ */
+export const OPT_IN_PATH = "/sms";
+/**
+ * The number a caller dials.
+ *
+ * Local, not the toll-free one, and the reason is billing rather than taste.
+ * Only standard DIDs are eligible for channel billing -- a flat fee for
+ * unlimited inbound minutes -- while toll-free is pay-per-minute forever, at
+ * roughly five times the rate. On a line people stay on for hours that is the
+ * whole cost of the product, so the number we print is the cheap one.
+ *
+ * 888-ROOM-818 still answers, for anyone who has it. It is a vanity alias, not
+ * the number to publish, and it cannot reach the cheap tier at any volume.
+ */
+export const CALL_IN_NUMBER = "408-357-2326";
+/** The number a reminder is sent from. Not the one above; see partyline.ts. */
+export const SMS_FROM_NUMBER = "408-426-9127";
+export function optInPage({ callIn = CALL_IN_NUMBER, smsFrom = SMS_FROM_NUMBER } = {}) {
+    return `<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Stream reminders by text &mdash; nixamp</title>
+<style>
+  :root { color-scheme: light dark; }
+  body {
+    margin: 0 auto; padding: 2rem 1.25rem 4rem; max-width: 42rem;
+    font: 16px/1.65 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  }
+  h1 { font-size: 1.5rem; margin: 0 0 .25rem; }
+  h2 { font-size: 1.05rem; margin: 2rem 0 .5rem; }
+  .sub { opacity: .7; margin: 0 0 2rem; }
+  dt { font-weight: 600; margin-top: .9rem; }
+  dd { margin: .15rem 0 0; }
+  ol { padding-left: 1.25rem; }
+  li { margin: .4rem 0; }
+  code, .n { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+  blockquote {
+    margin: .75rem 0; padding: .75rem 1rem; border-left: 3px solid currentColor;
+    opacity: .85; font-style: italic;
+  }
+  footer { margin-top: 3rem; font-size: .9rem; opacity: .7; }
+</style>
+<h1>Stream reminders by text</h1>
+<p class="sub">What these messages are, and how to stop them.</p>
+<h2>How you sign up</h2>
+<p>
+  There is one way, and it happens on the phone. Call
+  <strong class="n">${callIn}</strong> and key the six-digit code of a stream.
+  If that stream has finished, you hear this:
+</p>
+<blockquote>
+  Welcome to &lt;name&gt;&rsquo;s live stream of &lt;what they were playing&gt;.
+  The live stream ended at &lt;time&gt; Pacific. Call back later when they
+  stream again. Press&nbsp;1 to get a text message when they do.
+</blockquote>
+<ol>
+  <li>You press <strong>1</strong>.</li>
+  <li>We keep the number you called from, and nothing else.</li>
+  <li>When that stream goes live again, you get one text.</li>
+</ol>
+<p>
+  Pressing anything else, or hanging up, signs you up for nothing. We never add
+  a number that did not press&nbsp;1 on that prompt.
+</p>
+<h2>What you get</h2>
+<dl>
+  <dt>Message</dt>
+  <dd class="n">&lt;name&gt; is live now of &lt;what&gt; on nixamp. Call ${callIn} and key &lt;code&gt; to listen. Reply STOP to opt out.</dd>
+  <dt>How often</dt>
+  <dd>
+    Once per stream you asked about. Asking is a one-time thing: after that
+    text is sent you are off the list, and you would have to call and press 1
+    again to be told about the next one. There is no schedule and no marketing.
+  </dd>
+  <dt>Sent from</dt>
+  <dd class="n">${smsFrom}</dd>
+</dl>
+<h2>How to stop</h2>
+<p>
+  Reply <strong>STOP</strong> to any message and you will get no more.
+  Reply <strong>HELP</strong> for help. You can also simply never press 1.
+</p>
+<p>Message and data rates may apply.</p>
+<h2>What we keep</h2>
+<p>
+  The phone number you called from, tied to the stream you asked about, until
+  that text is sent &mdash; then it is deleted. Nothing is sold, and nothing is
+  shared with anyone but the carrier that has to deliver the message.
+</p>
+<footer>
+  ProFullStack, Inc. &middot;
+  <a href="mailto:anthony@profullstack.com">anthony@profullstack.com</a> &middot;
+  <a href="/">nixamp</a>
+</footer>
+</html>
+`;
+}

package/dist/partyline.d.ts ADDED Viewed

@@ -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;