nixamp 0.3.0 → 0.4.1

package/dist/follows.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Following a broadcaster, and where to reach the people who do.
+ *
+ * The phone line got here first, and its reminder is a different thing: you
+ * key a code, press 1, and are told once when that particular stream comes
+ * back. It is per-stream, one-shot, and tied to the handset you called from.
+ * That is right for somebody who dialled a number, and useless for somebody
+ * who wants to know whenever a person they like goes live, on whatever device
+ * they happen to be holding.
+ *
+ * So a follow is account to account, and delivery is a set of addresses rather
+ * than a phone number: an email, a phone if they gave one, and any number of
+ * browsers that have granted permission. One person with a laptop, a phone and
+ * a desktop app is three push subscriptions and one account.
+ *
+ * Unlike the rest of nixamp this is durable. The directory can afford to be a
+ * four-minute TTL because a stream that stops is a stream nobody is listening
+ * to; a follow has to outlive the stream by definition -- the whole point is
+ * to be told about a broadcast that is not happening yet.
+ *
+ * The query function is injected rather than a Pool being constructed here, so
+ * a test can describe a database instead of running one.
+ */
+/** The slice of `pg` this needs. Postgres in production, a fake in tests. */
+export interface Queryable {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/** A browser, desktop app or phone that has granted notification permission. */
+export interface PushTarget {
+    endpoint: string;
+    p256dh: string;
+    auth: string;
+}
+/** Everywhere one follower can be reached. */
+export interface Reachable {
+    accountId: string;
+    email: string;
+    /** E.164, if they gave one. Empty when they never did. */
+    phone: string;
+    /** Whether each channel is on. A follower who wants none is still a follower. */
+    wantsEmail: boolean;
+    wantsSms: boolean;
+    wantsWeb: boolean;
+    push: PushTarget[];
+}
+/** E.164, or nothing. A number we cannot dial is not a number worth storing. */
+export declare function phoneFrom(value: unknown): string;
+export declare class Follows {
+    private readonly db;
+    private ready;
+    constructor(db: Queryable);
+    /** Make the tables, once per process, on first use. */
+    private ensure;
+    follow(followerId: string, streamerId: string): Promise<boolean>;
+    unfollow(followerId: string, streamerId: string): Promise<void>;
+    /** Who this account follows. */
+    following(followerId: string): Promise<string[]>;
+    isFollowing(followerId: string, streamerId: string): Promise<boolean>;
+    followerCount(streamerId: string): Promise<number>;
+    /** Remember a browser that has granted permission. */
+    addPush(accountId: string, target: PushTarget): Promise<void>;
+    /**
+     * Forget a browser.
+     *
+     * Called when somebody turns notifications off, and again when a push is
+     * rejected as gone: a subscription outlives the browser that made it, and
+     * pushing to a dead endpoint forever is how a table becomes mostly rubbish.
+     */
+    removePush(endpoint: string): Promise<void>;
+    setPrefs(accountId: string, prefs: {
+        phone?: string;
+        wantsEmail?: boolean;
+        wantsSms?: boolean;
+        wantsWeb?: boolean;
+    }): Promise<void>;
+    prefs(accountId: string): Promise<{
+        phone: string;
+        wantsEmail: boolean;
+        wantsSms: boolean;
+        wantsWeb: boolean;
+    }>;
+    /**
+     * Everyone following this broadcaster, and every way to reach them.
+     *
+     * One query rather than one per follower. A broadcaster with a thousand
+     * followers going live should not be a thousand round trips while the
+     * publisher's heartbeat waits on the response.
+     */
+    audience(streamerId: string): Promise<Reachable[]>;
+}

package/dist/follows.js

@@ -0,0 +1,248 @@
+/**
+ * Following a broadcaster, and where to reach the people who do.
+ *
+ * The phone line got here first, and its reminder is a different thing: you
+ * key a code, press 1, and are told once when that particular stream comes
+ * back. It is per-stream, one-shot, and tied to the handset you called from.
+ * That is right for somebody who dialled a number, and useless for somebody
+ * who wants to know whenever a person they like goes live, on whatever device
+ * they happen to be holding.
+ *
+ * So a follow is account to account, and delivery is a set of addresses rather
+ * than a phone number: an email, a phone if they gave one, and any number of
+ * browsers that have granted permission. One person with a laptop, a phone and
+ * a desktop app is three push subscriptions and one account.
+ *
+ * Unlike the rest of nixamp this is durable. The directory can afford to be a
+ * four-minute TTL because a stream that stops is a stream nobody is listening
+ * to; a follow has to outlive the stream by definition -- the whole point is
+ * to be told about a broadcast that is not happening yet.
+ *
+ * The query function is injected rather than a Pool being constructed here, so
+ * a test can describe a database instead of running one.
+ */
+/**
+ * The tables.
+ *
+ * Created on demand rather than in a migration because the auth module owns
+ * the schema this sits beside and there is no migration runner to hook into.
+ * `IF NOT EXISTS` throughout, so starting a second instance is not a race that
+ * takes the first one down.
+ *
+ * `follows` is keyed on the pair, which makes following twice a no-op rather
+ * than a duplicate to deduplicate later. `push_subscriptions` is keyed on the
+ * endpoint alone: an endpoint is issued by the browser vendor and is already
+ * unique, and the same browser re-subscribing should replace its row rather
+ * than accumulate one per sign-in.
+ */
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS follows (
+    follower_id  TEXT NOT NULL,
+    streamer_id  TEXT NOT NULL,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (follower_id, streamer_id)
+  );
+  CREATE INDEX IF NOT EXISTS follows_streamer ON follows (streamer_id);
+
+  CREATE TABLE IF NOT EXISTS push_subscriptions (
+    endpoint    TEXT PRIMARY KEY,
+    account_id  TEXT NOT NULL,
+    p256dh      TEXT NOT NULL,
+    auth        TEXT NOT NULL,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+  );
+  CREATE INDEX IF NOT EXISTS push_account ON push_subscriptions (account_id);
+
+  CREATE TABLE IF NOT EXISTS notify_prefs (
+    account_id  TEXT PRIMARY KEY,
+    phone       TEXT NOT NULL DEFAULT '',
+    want_email  BOOLEAN NOT NULL DEFAULT TRUE,
+    want_sms    BOOLEAN NOT NULL DEFAULT FALSE,
+    want_web    BOOLEAN NOT NULL DEFAULT TRUE
+  );
+`;
+/** E.164, or nothing. A number we cannot dial is not a number worth storing. */
+export function phoneFrom(value) {
+    if (typeof value !== "string")
+        return "";
+    const digits = value.replace(/[^\d+]/g, "");
+    if (/^\+[1-9]\d{7,14}$/.test(digits))
+        return digits;
+    // A bare US ten-digit number is the common case and is unambiguous.
+    if (/^\d{10}$/.test(digits))
+        return `+1${digits}`;
+    if (/^1\d{10}$/.test(digits))
+        return `+${digits}`;
+    return "";
+}
+export class Follows {
+    db;
+    ready = null;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Make the tables, once per process, on first use. */
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    async follow(followerId, streamerId) {
+        // Following yourself is not an error worth an error, but it is not a
+        // follow either: you do not need telling that you went live.
+        if (!followerId || !streamerId || followerId === streamerId)
+            return false;
+        await this.ensure();
+        await this.db.query(`INSERT INTO follows (follower_id, streamer_id) VALUES ($1, $2)
+       ON CONFLICT DO NOTHING`, [followerId, streamerId]);
+        return true;
+    }
+    async unfollow(followerId, streamerId) {
+        await this.ensure();
+        await this.db.query("DELETE FROM follows WHERE follower_id = $1 AND streamer_id = $2", [followerId, streamerId]);
+    }
+    /** Who this account follows. */
+    async following(followerId) {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT streamer_id FROM follows WHERE follower_id = $1 ORDER BY created_at", [followerId]);
+        return rows.map((r) => String(r["streamer_id"]));
+    }
+    async isFollowing(followerId, streamerId) {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT 1 FROM follows WHERE follower_id = $1 AND streamer_id = $2", [followerId, streamerId]);
+        return rows.length > 0;
+    }
+    async followerCount(streamerId) {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT COUNT(*)::int AS n FROM follows WHERE streamer_id = $1", [streamerId]);
+        return Number(rows[0]?.["n"] ?? 0);
+    }
+    /** Remember a browser that has granted permission. */
+    async addPush(accountId, target) {
+        if (!accountId || !target.endpoint)
+            return;
+        await this.ensure();
+        await this.db.query(`INSERT INTO push_subscriptions (endpoint, account_id, p256dh, auth)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (endpoint) DO UPDATE
+         SET account_id = EXCLUDED.account_id,
+             p256dh = EXCLUDED.p256dh,
+             auth = EXCLUDED.auth`, [target.endpoint, accountId, target.p256dh, target.auth]);
+    }
+    /**
+     * Forget a browser.
+     *
+     * Called when somebody turns notifications off, and again when a push is
+     * rejected as gone: a subscription outlives the browser that made it, and
+     * pushing to a dead endpoint forever is how a table becomes mostly rubbish.
+     */
+    async removePush(endpoint) {
+        if (!endpoint)
+            return;
+        await this.ensure();
+        await this.db.query("DELETE FROM push_subscriptions WHERE endpoint = $1", [endpoint]);
+    }
+    async setPrefs(accountId, prefs) {
+        if (!accountId)
+            return;
+        await this.ensure();
+        // Every column is COALESCEd on the way IN as well as on conflict. A caller
+        // setting only the switches sends no phone, and an unset field arrives as
+        // null -- which the ON CONFLICT branch handles fine and the INSERT branch
+        // does not, because these columns are NOT NULL. Saving preferences for the
+        // first time was a 500 until this said so.
+        //
+        // The casts are not decoration either: Postgres cannot infer the type of a
+        // parameter that is only ever seen inside COALESCE against a null.
+        await this.db.query(`INSERT INTO notify_prefs (account_id, phone, want_email, want_sms, want_web)
+       VALUES ($1,
+               COALESCE($2::text, ''),
+               COALESCE($3::boolean, TRUE),
+               COALESCE($4::boolean, FALSE),
+               COALESCE($5::boolean, TRUE))
+       ON CONFLICT (account_id) DO UPDATE
+         SET phone = COALESCE($2::text, notify_prefs.phone),
+             want_email = COALESCE($3::boolean, notify_prefs.want_email),
+             want_sms = COALESCE($4::boolean, notify_prefs.want_sms),
+             want_web = COALESCE($5::boolean, notify_prefs.want_web)`, [
+            accountId,
+            prefs.phone === undefined ? null : phoneFrom(prefs.phone),
+            prefs.wantsEmail ?? null,
+            prefs.wantsSms ?? null,
+            prefs.wantsWeb ?? null,
+        ]);
+    }
+    async prefs(accountId) {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT phone, want_email, want_sms, want_web FROM notify_prefs WHERE account_id = $1", [accountId]);
+        const row = rows[0];
+        // Defaults for somebody who has never opened the settings: mail yes, web
+        // yes, texts no. A text costs them nothing but is the most intrusive of
+        // the three, so it is the one you have to ask for.
+        return {
+            phone: String(row?.["phone"] ?? ""),
+            wantsEmail: row === undefined ? true : row["want_email"] !== false,
+            wantsSms: row === undefined ? false : row["want_sms"] === true,
+            wantsWeb: row === undefined ? true : row["want_web"] !== false,
+        };
+    }
+    /**
+     * Everyone following this broadcaster, and every way to reach them.
+     *
+     * One query rather than one per follower. A broadcaster with a thousand
+     * followers going live should not be a thousand round trips while the
+     * publisher's heartbeat waits on the response.
+     */
+    async audience(streamerId) {
+        if (!streamerId)
+            return [];
+        await this.ensure();
+        const { rows } = await this.db.query(`SELECT f.follower_id                     AS account_id,
+              COALESCE(u.email, '')             AS email,
+              COALESCE(p.phone, '')             AS phone,
+              COALESCE(p.want_email, TRUE)      AS want_email,
+              COALESCE(p.want_sms, FALSE)       AS want_sms,
+              COALESCE(p.want_web, TRUE)        AS want_web,
+              COALESCE(
+                json_agg(json_build_object('endpoint', s.endpoint, 'p256dh', s.p256dh, 'auth', s.auth))
+                  FILTER (WHERE s.endpoint IS NOT NULL),
+                '[]'
+              )                                 AS push
+         FROM follows f
+         LEFT JOIN users u              ON u.id = f.follower_id
+         LEFT JOIN notify_prefs p       ON p.account_id = f.follower_id
+         LEFT JOIN push_subscriptions s ON s.account_id = f.follower_id
+        WHERE f.streamer_id = $1
+        GROUP BY f.follower_id, u.email, p.phone, p.want_email, p.want_sms, p.want_web`, [streamerId]);
+        return rows.map((r) => ({
+            accountId: String(r["account_id"] ?? ""),
+            email: String(r["email"] ?? ""),
+            phone: String(r["phone"] ?? ""),
+            wantsEmail: r["want_email"] !== false,
+            wantsSms: r["want_sms"] === true,
+            wantsWeb: r["want_web"] !== false,
+            push: readPush(r["push"]),
+        }));
+    }
+}
+/** json_agg comes back as an array or as a string, depending on the driver. */
+function readPush(value) {
+    const list = typeof value === "string" ? safeParse(value) : value;
+    if (!Array.isArray(list))
+        return [];
+    return list
+        .map((item) => (item ?? {}))
+        .filter((item) => typeof item["endpoint"] === "string" && item["endpoint"] !== "")
+        .map((item) => ({
+        endpoint: String(item["endpoint"]),
+        p256dh: String(item["p256dh"] ?? ""),
+        auth: String(item["auth"] ?? ""),
+    }));
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/notify.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Telling followers a broadcaster went live, wherever they are.
+ *
+ * Three channels, because "any device" is not one thing. A browser that has
+ * granted permission gets a push -- which is also how the desktop app and a
+ * phone with the PWA installed hear about it, since all three are the same
+ * subscription under different chrome. An inbox gets mail. A handset that gave
+ * us a number gets a text.
+ *
+ * Every channel is optional at both ends. The operator may configure none of
+ * them, in which case nothing is sent and nothing throws; and a follower may
+ * want mail but not texts, which is the default because a text is the most
+ * intrusive of the three and the one you should have to ask for.
+ *
+ * Nothing here retries. A missed "so-and-so is live" is worth very little an
+ * hour later, and a retry queue for a message with that shelf life is machinery
+ * that will outlive its usefulness. What it does do is notice a push endpoint
+ * the browser vendor has retired, and say so, so the row can be dropped rather
+ * than pushed at forever.
+ */
+import type { PushTarget, Reachable } from "./follows.ts";
+import type { Sms } from "./partyline.ts";
+export interface Notification {
+    /** "Chovy is live" */
+    title: string;
+    /** "Playing Top Gun: Maverick. Call 408-357-2326 and key 482917." */
+    body: string;
+    /** Where a click should land. */
+    url: string;
+}
+/** What happened to one push. `gone` means the subscription should be dropped. */
+export type PushResult = "sent" | "gone" | "failed";
+export interface NotifyChannels {
+    email?: (to: string, note: Notification) => Promise<boolean>;
+    sms?: Sms;
+    push?: (target: PushTarget, note: Notification) => Promise<PushResult>;
+    /** Called with an endpoint the vendor has retired, so it can be forgotten. */
+    onGone?: (endpoint: string) => Promise<void>;
+    onEvent?: (message: string) => void;
+}
+export interface NotifyReport {
+    email: number;
+    sms: number;
+    push: number;
+    dropped: number;
+}
+/**
+ * Tell an audience, on every channel each of them wants.
+ *
+ * Sent in parallel across people and channels. A thousand followers is a
+ * thousand independent HTTP calls, and doing them in sequence would mean the
+ * last person hears about a stream that has already finished.
+ */
+export declare function notifyAll(audience: readonly Reachable[], note: Notification, channels: NotifyChannels): Promise<NotifyReport>;
+/**
+ * Mail, over Resend's HTTP API.
+ *
+ * HTTP rather than SMTP so there is no connection to hold, no port to be
+ * blocked, and no dependency: a fetch is the whole client.
+ */
+export declare function resendEmail({ apiKey, from, fetch, onEvent }: {
+    apiKey: string;
+    from: string;
+    fetch?: typeof globalThis.fetch;
+    onEvent?: (message: string) => void;
+}): (to: string, note: Notification) => Promise<boolean>;
+/**
+ * Web push, to a browser, a desktop app or an installed PWA.
+ *
+ * The library is imported lazily because it is only needed on the instance
+ * that has VAPID keys -- which is nixamp.com and nowhere else. A laptop
+ * running `nixamp serve` should not pay to load it.
+ *
+ * 404 and 410 mean the vendor has retired the subscription. That is not a
+ * failure to retry; it is a row to delete.
+ */
+export declare function webPush({ publicKey, privateKey, subject, onEvent }: {
+    publicKey: string;
+    privateKey: string;
+    /** A mailto: or https: URL identifying us to the push service. */
+    subject: string;
+    onEvent?: (message: string) => void;
+}): (target: PushTarget, note: Notification) => Promise<PushResult>;

package/dist/notify.js

@@ -0,0 +1,126 @@
+/**
+ * Tell an audience, on every channel each of them wants.
+ *
+ * Sent in parallel across people and channels. A thousand followers is a
+ * thousand independent HTTP calls, and doing them in sequence would mean the
+ * last person hears about a stream that has already finished.
+ */
+export async function notifyAll(audience, note, channels) {
+    const report = { email: 0, sms: 0, push: 0, dropped: 0 };
+    const gone = [];
+    const jobs = [];
+    for (const person of audience) {
+        if (person.wantsEmail && person.email && channels.email) {
+            jobs.push(channels.email(person.email, note).then((ok) => {
+                if (ok)
+                    report.email += 1;
+            }));
+        }
+        if (person.wantsSms && person.phone && channels.sms) {
+            // The text carries the same words, plus how to stop getting them --
+            // which is not optional on an automated message to a US number.
+            const text = `${note.title}. ${note.body} Reply STOP to opt out.`;
+            jobs.push(channels.sms.send(person.phone, text).then((ok) => {
+                if (ok)
+                    report.sms += 1;
+            }));
+        }
+        if (person.wantsWeb && channels.push) {
+            for (const target of person.push) {
+                jobs.push(channels.push(target, note).then((result) => {
+                    if (result === "sent")
+                        report.push += 1;
+                    else if (result === "gone")
+                        gone.push(target.endpoint);
+                }));
+            }
+        }
+    }
+    // allSettled, not all: one bad address must not cancel everybody else's.
+    await Promise.allSettled(jobs);
+    if (channels.onGone) {
+        await Promise.allSettled(gone.map((endpoint) => channels.onGone(endpoint)));
+        report.dropped = gone.length;
+    }
+    channels.onEvent?.(`  told followers: ${report.push} push, ${report.email} email, ${report.sms} sms` +
+        (report.dropped ? `, dropped ${report.dropped} dead subscription(s)` : ""));
+    return report;
+}
+/**
+ * Mail, over Resend's HTTP API.
+ *
+ * HTTP rather than SMTP so there is no connection to hold, no port to be
+ * blocked, and no dependency: a fetch is the whole client.
+ */
+export function resendEmail({ apiKey, from, fetch = globalThis.fetch, onEvent }) {
+    return async (to, note) => {
+        try {
+            const response = await fetch("https://api.resend.com/emails", {
+                method: "POST",
+                headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
+                body: JSON.stringify({
+                    from,
+                    to: [to],
+                    subject: note.title,
+                    text: `${note.body}\n\n${note.url}\n\nYou are getting this because you follow them on nixamp.`,
+                    html: `<p>${escapeHtml(note.body)}</p>` +
+                        `<p><a href="${escapeHtml(note.url)}">${escapeHtml(note.url)}</a></p>` +
+                        `<p style="color:#666;font-size:12px">You are getting this because you follow them on nixamp.</p>`,
+                }),
+            });
+            if (!response.ok) {
+                onEvent?.(`  email to ${to} -> ${response.status}`);
+                return false;
+            }
+            return true;
+        }
+        catch (error) {
+            onEvent?.(`  email to ${to} failed: ${error.message}`);
+            return false;
+        }
+    };
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * Web push, to a browser, a desktop app or an installed PWA.
+ *
+ * The library is imported lazily because it is only needed on the instance
+ * that has VAPID keys -- which is nixamp.com and nowhere else. A laptop
+ * running `nixamp serve` should not pay to load it.
+ *
+ * 404 and 410 mean the vendor has retired the subscription. That is not a
+ * failure to retry; it is a row to delete.
+ */
+export function webPush({ publicKey, privateKey, subject, onEvent }) {
+    let library = null;
+    const load = async () => {
+        library ??= import("web-push").then((mod) => {
+            const wp = (mod["default"] ?? mod);
+            wp.setVapidDetails(subject, publicKey, privateKey);
+            return wp;
+        });
+        return library;
+    };
+    return async (target, note) => {
+        try {
+            const wp = await load();
+            await wp.sendNotification({ endpoint: target.endpoint, keys: { p256dh: target.p256dh, auth: target.auth } }, JSON.stringify({ title: note.title, body: note.body, url: note.url }), { TTL: 60 * 30 });
+            return "sent";
+        }
+        catch (error) {
+            const status = error.statusCode;
+            if (status === 404 || status === 410) {
+                onEvent?.(`  push endpoint retired by the vendor, dropping it`);
+                return "gone";
+            }
+            onEvent?.(`  push failed: ${status ?? error.message}`);
+            return "failed";
+        }
+    };
+}

package/dist/optin.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare 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 declare const CALL_IN_NUMBER = "408-357-2326";
+/** The number a reminder is sent from. Not the one above; see partyline.ts. */
+export declare const SMS_FROM_NUMBER = "408-426-9127";
+export declare function optInPage({ callIn, smsFrom }?: {
+    callIn?: string | undefined;
+    smsFrom?: string | undefined;
+}): string;