nixamp 0.2.0 → 0.4.0

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;

package/dist/optin.js

@@ -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/owner.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Who may administer this server.
+ *
+ * Two ways to be allowed, and they answer different questions:
+ *
+ * - You hold the control key. That is possession of the share link the server
+ *   printed, which means you are at the machine or someone at it told you.
+ * - You are signed in to nixamp.com as the account that owns this server. That
+ *   is identity, and it works from a phone on the other side of the world.
+ *
+ * The server cannot check a nixamp.com token itself -- it has no part of that
+ * secret, and it should not. So it asks nixamp.com who the token belongs to and
+ * compares the answer to the owner it recorded at startup. Delegating identity
+ * and keeping authorisation local is what lets a nixamp on a laptop trust an
+ * account it has never seen.
+ */
+/** How long an answer from nixamp.com is trusted before asking again. */
+export declare const CACHE_MS = 60000;
+export interface OwnerOptions {
+    /** The account id that owns this server, from the CLI session at startup. */
+    ownerId: string;
+    /** Where to ask about a token. */
+    site: string;
+    fetcher?: typeof fetch;
+    now?: () => number;
+}
+export interface AdminCheck {
+    /** May this caller administer the server? */
+    allowed: boolean;
+    /** How they proved it, for the admin view to show. */
+    as: "key" | "owner" | null;
+}
+/**
+ * Ask nixamp.com who a token belongs to, and remember the answer briefly.
+ *
+ * Briefly, because an admin request should not cost a round trip to another
+ * host every time, and not for long, because a revoked session should stop
+ * working in about a minute rather than whenever the process restarts.
+ */
+export declare class Owner {
+    private readonly options;
+    private readonly cache;
+    constructor(options: OwnerOptions);
+    get claimed(): boolean;
+    /** The account a token belongs to, or "" for one nixamp.com does not accept. */
+    accountFor(token: string): Promise<string>;
+    check(hasControlKey: boolean, token: string): Promise<AdminCheck>;
+    /** Forget everything remembered, so a sign-out takes effect at once. */
+    forget(): void;
+}
+/** Paths only an administrator may reach. */
+export declare const ADMIN_PATHS: string[];
+export declare function needsAdmin(path: string, method?: string): boolean;

package/dist/owner.js

@@ -0,0 +1,96 @@
+/**
+ * Who may administer this server.
+ *
+ * Two ways to be allowed, and they answer different questions:
+ *
+ * - You hold the control key. That is possession of the share link the server
+ *   printed, which means you are at the machine or someone at it told you.
+ * - You are signed in to nixamp.com as the account that owns this server. That
+ *   is identity, and it works from a phone on the other side of the world.
+ *
+ * The server cannot check a nixamp.com token itself -- it has no part of that
+ * secret, and it should not. So it asks nixamp.com who the token belongs to and
+ * compares the answer to the owner it recorded at startup. Delegating identity
+ * and keeping authorisation local is what lets a nixamp on a laptop trust an
+ * account it has never seen.
+ */
+/** How long an answer from nixamp.com is trusted before asking again. */
+export const CACHE_MS = 60_000;
+/**
+ * Ask nixamp.com who a token belongs to, and remember the answer briefly.
+ *
+ * Briefly, because an admin request should not cost a round trip to another
+ * host every time, and not for long, because a revoked session should stop
+ * working in about a minute rather than whenever the process restarts.
+ */
+export class Owner {
+    options;
+    cache = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    get claimed() {
+        return this.options.ownerId !== "";
+    }
+    /** The account a token belongs to, or "" for one nixamp.com does not accept. */
+    async accountFor(token) {
+        if (!token)
+            return "";
+        const now = (this.options.now ?? Date.now)();
+        const remembered = this.cache.get(token);
+        if (remembered && now - remembered.at < CACHE_MS)
+            return remembered.id;
+        const send = this.options.fetcher ?? fetch;
+        try {
+            const answer = await send(`${this.options.site}/api/v1/auth/me`, {
+                headers: { authorization: `Bearer ${token}` },
+            });
+            if (!answer.ok) {
+                // Remember the refusal too, or a wrong token costs a round trip on
+                // every request it is presented with.
+                this.cache.set(token, { id: "", at: now });
+                return "";
+            }
+            const body = (await answer.json());
+            const id = typeof body.account?.id === "string" ? body.account.id : "";
+            this.cache.set(token, { id, at: now });
+            return id;
+        }
+        catch {
+            // nixamp.com being unreachable must not turn into "everyone is the
+            // owner". It turns into "nobody is", and the control key still works.
+            return "";
+        }
+    }
+    async check(hasControlKey, token) {
+        if (hasControlKey)
+            return { allowed: true, as: "key" };
+        if (!this.claimed)
+            return { allowed: false, as: null };
+        const account = await this.accountFor(token);
+        return account !== "" && account === this.options.ownerId
+            ? { allowed: true, as: "owner" }
+            : { allowed: false, as: null };
+    }
+    /** Forget everything remembered, so a sign-out takes effect at once. */
+    forget() {
+        this.cache.clear();
+    }
+}
+/** Paths only an administrator may reach. */
+export const ADMIN_PATHS = [
+    "/api/connections",
+    "/api/source",
+    "/api/broadcast",
+    "/api/ingest",
+    "/api/admin",
+];
+export function needsAdmin(path, method = "GET") {
+    if (ADMIN_PATHS.some((prefix) => path === prefix || path.startsWith(`${prefix}/`)))
+        return true;
+    // Publishing to a channel, or ending one, is administering the server.
+    // Listening to a channel is not: that is what the share link is for.
+    if (path.startsWith("/api/channels/") && method !== "GET")
+        return true;
+    return false;
+}