nixamp 0.1.0 → 0.3.0

package/dist/manage.js

@@ -9,13 +9,16 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 const SITE = "https://nixamp.com";
+/** Windows has its own installer, its own shim and its own removal script. */
+const windows = process.platform === "win32";
 /**
  * Where the installer put things. `NIXAMP_HOME` is exported by the shim it
  * wrote, which is the only thing that knows for certain; the walk up from this
  * file covers a shim from an older install that did not set it.
  */
-export function installRoot(from = new URL(".", import.meta.url).pathname) {
+export function installRoot(from = fileURLToPath(new URL(".", import.meta.url))) {
     const declared = process.env["NIXAMP_HOME"];
     if (declared && existsSync(join(declared, "manifest.json")))
         return declared;
@@ -53,7 +56,9 @@ function notInstalled(what) {
     console.error("");
     console.error("  Installed with npm or bun:  npm uninstall -g nixamp");
     console.error("  Running from a checkout:    delete the checkout");
-    console.error(`  Wanted the installed one:   curl -fsSL ${SITE}/install.sh | sh`);
+    console.error(windows
+        ? `  Wanted the installed one:   irm ${SITE}/install.ps1 | iex`
+        : `  Wanted the installed one:   curl -fsSL ${SITE}/install.sh | sh`);
     return 69;
 }
 /**
@@ -66,12 +71,24 @@ export function update(argv) {
     const manifest = root ? readManifest(root) : null;
     if (!root || !manifest)
         return notInstalled("update");
-    const installer = manifest.installer || `${SITE}/install.sh`;
-    const args = ["-s", "--", manifest.desktop ? "--desktop" : "--cli-only", "--prefix", manifest.prefix];
+    const installer = manifest.installer || `${SITE}/${windows ? "install.ps1" : "install.sh"}`;
     const wanted = argv.find((a) => !a.startsWith("-"));
+    console.log(`nixamp ${manifest.version} is installed. Fetching the installer...`);
+    if (windows) {
+        // PowerShell fetches and runs it in one expression, which is also the
+        // documented install line, so an update takes a fresh install's path.
+        const flags = [manifest.desktop ? "" : "-CliOnly", "-Prefix", quote(manifest.prefix)];
+        if (wanted)
+            flags.push("-Version", quote(wanted));
+        const expression = `& ([scriptblock]::Create((irm ${installer}))) ${flags.filter(Boolean).join(" ")}`;
+        const run = spawnSync("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", expression], {
+            stdio: "inherit",
+        });
+        return run.status ?? 1;
+    }
+    const args = ["-s", "--", manifest.desktop ? "--desktop" : "--cli-only", "--prefix", manifest.prefix];
     if (wanted)
         args.push("--version", wanted);
-    console.log(`nixamp ${manifest.version} is installed. Fetching the installer...`);
     const fetcher = which("curl") ? ["curl", "-fsSL", installer] : which("wget") ? ["wget", "-qO-", installer] : null;
     if (!fetcher) {
         console.error("nixamp: curl or wget is required to update.");
@@ -103,15 +120,21 @@ export function uninstall(argv) {
         console.log("Your music is not touched. Run `nixamp uninstall --yes` to go ahead.");
         return 0;
     }
-    const script = join(root, "uninstall.sh");
+    const script = join(root, windows ? "uninstall.ps1" : "uninstall.sh");
     if (!existsSync(script)) {
         console.error(`nixamp: ${script} is missing, so removal cannot be exact.`);
         console.error(`  The manifest lists: ${manifest.paths.join(", ")}`);
         return 1;
     }
-    const run = spawnSync("sh", [script], { stdio: "inherit" });
+    const run = windows
+        ? spawnSync("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script], { stdio: "inherit" })
+        : spawnSync("sh", [script], { stdio: "inherit" });
     return run.status ?? 1;
 }
+/** A PowerShell single-quoted string: the only escape inside one is a doubled quote. */
+function quote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
 function which(command) {
     return spawnSync("sh", ["-c", `command -v ${command}`], { stdio: "ignore" }).status === 0;
 }

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;
+}

package/dist/paywall.d.ts

@@ -0,0 +1,60 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** Listeners who get in for nothing. The sixth is the one who pays. */
+export declare const FREE_LISTENERS = 5;
+export interface PaywallConfig {
+    enabled: boolean;
+    /** EVM address that receives the USDC. Without one there is nothing to pay to. */
+    payTo: string;
+    /** A scoped CoinPay key with payments:create. */
+    coinpayKey: string;
+    priceCents: number;
+    /** What one price buys. 1440 is a day. */
+    passMinutes: number;
+}
+export declare const DEFAULT_PAYWALL: PaywallConfig;
+/** Only the audio is behind the gate. */
+export declare const GATED: string[];
+export declare function isGated(path: string): boolean;
+/**
+ * Whether this request should be charged at all. Configuration first, because
+ * a disabled paywall must never answer 402; then the path, then how busy the
+ * stream is.
+ */
+export declare function shouldCharge(config: PaywallConfig, path: string, liveListeners: number): boolean;
+export interface PaywallOptions {
+    config: () => PaywallConfig;
+    /** How many listeners are on the audio routes right now. */
+    liveListeners: () => number;
+    /**
+     * The origin a payer is quoted, which has to be one they can reach. A
+     * function because the port is not known until the socket is bound.
+     */
+    siteUrl: () => string;
+    /** True for the operator's own browser, which never pays to hear its own music. */
+    exempt: (request: IncomingMessage) => boolean;
+}
+/**
+ * A node http shim over the gateway's Fetch-API handler. Returns true when it
+ * answered the request, so the server's own routing can stop.
+ */
+export declare function createPaywall(options: PaywallOptions): (request: IncomingMessage, response: ServerResponse, path: string) => Promise<boolean>;
+/**
+ * The gateway sells crawl access, and says so: its 402 tells the caller that
+ * "payment is required for training crawlers". Someone trying to hear a song
+ * is not a crawler, so the sentence is replaced on the way out. The offer
+ * itself is untouched -- only the words are ours.
+ */
+export declare function rewrite(answer: Response, siteUrl: string): Promise<Buffer>;
+/**
+ * Enough of a Fetch Request for the gateway: it reads the URL, the method and
+ * headers. A body would need streaming, and nothing it gates has one.
+ */
+export declare function toRequest(request: IncomingMessage, siteUrl: string): Request;
+/** Read a paywall out of the environment, for an operator who runs one by hand. */
+export declare function paywallFromEnv(env?: NodeJS.ProcessEnv): PaywallConfig;
+/**
+ * The directory's answer may carry a configuration, which is how a server is
+ * turned on and off from nixamp.com. Anything missing keeps what it had, and
+ * a payTo the operator did not set is never invented here.
+ */
+export declare function applyRemoteConfig(current: PaywallConfig, remote: unknown): PaywallConfig;

package/dist/paywall.js

@@ -0,0 +1,162 @@
+/**
+ * Paying to listen, once a stream is busy.
+ *
+ * A nixamp serving a handful of friends should cost nothing and ask nothing.
+ * Past that it is bandwidth someone is paying for, so the gate opens: over the
+ * free listener count, a new listener is answered 402 with an x402 offer and a
+ * dollar buys a day.
+ *
+ * Three things are deliberate. The count is of *live* listeners, so a stream
+ * quietens back to free on its own. Only the audio is gated, because a 402 on
+ * /api/state would break the page that has to render the offer. And nobody is
+ * ever cut off mid-track: the gate is asked once, when a request arrives, and
+ * a listener who got in stays in.
+ */
+import { createGateway } from "@profullstack/x402-gateway";
+/** Listeners who get in for nothing. The sixth is the one who pays. */
+export const FREE_LISTENERS = 5;
+export const DEFAULT_PAYWALL = {
+    enabled: false,
+    payTo: "",
+    coinpayKey: "",
+    priceCents: 100,
+    passMinutes: 1440,
+};
+/** Only the audio is behind the gate. */
+export const GATED = ["/api/stream/", "/api/media/"];
+export function isGated(path) {
+    return GATED.some((prefix) => path.startsWith(prefix));
+}
+/**
+ * Whether this request should be charged at all. Configuration first, because
+ * a disabled paywall must never answer 402; then the path, then how busy the
+ * stream is.
+ */
+export function shouldCharge(config, path, liveListeners) {
+    if (!config.enabled || !config.payTo)
+        return false;
+    if (!isGated(path))
+        return false;
+    return liveListeners > FREE_LISTENERS;
+}
+/**
+ * A node http shim over the gateway's Fetch-API handler. Returns true when it
+ * answered the request, so the server's own routing can stop.
+ */
+export function createPaywall(options) {
+    let built = null;
+    /** Rebuilt when the configuration changes, because it can change at runtime. */
+    const gateway = (config, siteUrl) => {
+        const key = `${siteUrl} ${JSON.stringify(config)}`;
+        if (built?.key === key)
+            return built.handle;
+        const gate = createGateway({
+            siteUrl,
+            siteName: "nixamp",
+            payTo: config.payTo,
+            priceCents: config.priceCents,
+            passMinutes: config.passMinutes,
+            coinpay: { apiKey: config.coinpayKey },
+            header: "x-nixamp-pass",
+            path: "/listen/pay",
+            // Whether to charge is about how busy this stream is, not about who is
+            // asking, so the agent lists play no part.
+            isPaidAgent: () => true,
+            benefits: ["Listen to this stream for a day, as many tracks as you like."],
+        });
+        built = { key, handle: (request) => gate.handle(request) };
+        return built.handle;
+    };
+    return async function paywall(request, response, path) {
+        const config = options.config();
+        // The sales page answers whenever the paywall is configured, so a listener
+        // can buy a pass before the stream is busy enough to need one.
+        const selling = config.enabled && config.payTo !== "" && path.startsWith("/listen/pay");
+        if (!selling && !shouldCharge(config, path, options.liveListeners()))
+            return false;
+        if (options.exempt(request))
+            return false;
+        const siteUrl = options.siteUrl();
+        const answer = await gateway(config, siteUrl)(toRequest(request, siteUrl));
+        if (answer === null)
+            return false;
+        const body = await rewrite(answer, siteUrl);
+        response.writeHead(answer.status, {
+            ...Object.fromEntries(answer.headers),
+            "content-length": String(body.byteLength),
+        });
+        response.end(body);
+        return true;
+    };
+}
+/**
+ * The gateway sells crawl access, and says so: its 402 tells the caller that
+ * "payment is required for training crawlers". Someone trying to hear a song
+ * is not a crawler, so the sentence is replaced on the way out. The offer
+ * itself is untouched -- only the words are ours.
+ */
+export async function rewrite(answer, siteUrl) {
+    const raw = Buffer.from(await answer.arrayBuffer());
+    if (answer.status !== 402 || !(answer.headers.get("content-type") ?? "").includes("json"))
+        return raw;
+    try {
+        const parsed = JSON.parse(raw.toString("utf8"));
+        parsed["error"] =
+            `This stream has more than ${FREE_LISTENERS} people listening. ` +
+                `A pass is ${parsed.pass?.price ?? "$1"} for a day: ${siteUrl}/listen/pay`;
+        return Buffer.from(JSON.stringify(parsed));
+    }
+    catch {
+        // Not JSON after all: send exactly what the gateway produced.
+        return raw;
+    }
+}
+/**
+ * Enough of a Fetch Request for the gateway: it reads the URL, the method and
+ * headers. A body would need streaming, and nothing it gates has one.
+ */
+export function toRequest(request, siteUrl) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (value === undefined)
+            continue;
+        headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+    }
+    return new Request(new URL(request.url ?? "/", siteUrl), {
+        method: request.method ?? "GET",
+        headers,
+    });
+}
+/** Read a paywall out of the environment, for an operator who runs one by hand. */
+export function paywallFromEnv(env = process.env) {
+    const price = Number(env["NIXAMP_PRICE_CENTS"]);
+    const minutes = Number(env["NIXAMP_PASS_MINUTES"]);
+    return {
+        enabled: env["NIXAMP_X402"] === "1",
+        payTo: env["NIXAMP_PAY_TO"] ?? "",
+        coinpayKey: env["COINPAY_X402_KEY"] ?? "",
+        priceCents: Number.isFinite(price) && price > 0 ? Math.floor(price) : DEFAULT_PAYWALL.priceCents,
+        passMinutes: Number.isFinite(minutes) && minutes > 0 ? Math.floor(minutes) : DEFAULT_PAYWALL.passMinutes,
+    };
+}
+/**
+ * The directory's answer may carry a configuration, which is how a server is
+ * turned on and off from nixamp.com. Anything missing keeps what it had, and
+ * a payTo the operator did not set is never invented here.
+ */
+export function applyRemoteConfig(current, remote) {
+    if (typeof remote !== "object" || remote === null)
+        return current;
+    const record = remote;
+    const price = Number(record["priceCents"]);
+    const minutes = Number(record["passMinutes"]);
+    return {
+        enabled: typeof record["enabled"] === "boolean" ? record["enabled"] : current.enabled,
+        payTo: typeof record["payTo"] === "string" && record["payTo"] ? record["payTo"] : current.payTo,
+        coinpayKey: typeof record["coinpayKey"] === "string" && record["coinpayKey"]
+            ? record["coinpayKey"]
+            : current.coinpayKey,
+        priceCents: Number.isFinite(price) && price > 0 ? Math.floor(price) : current.priceCents,
+        passMinutes: Number.isFinite(minutes) && minutes > 0 ? Math.floor(minutes) : current.passMinutes,
+    };
+}

package/dist/playlist.d.ts

@@ -1,8 +1,24 @@
 import { type Tools, type Track } from "./audio.ts";
+import { type Entry } from "./sources.ts";
 export declare const AUDIO_EXTENSIONS: Set<string>;
 export declare function isAudio(path: string): boolean;
 /** Every audio file under `root`, depth first. A single file is a playlist of one. */
 export declare function findAudio(root: string): string[];
+/**
+ * Read a playlist, from disk or over the network. An HLS playlist is not a list
+ * of tracks but one stream in segments, so it comes back as a single entry and
+ * ffmpeg is left to do what it is good at.
+ */
+export declare function readPlaylist(source: string): Promise<Entry[]>;
+/**
+ * Everything `nixamp <thing>` can be handed: a directory, a file, a playlist,
+ * or a URL to any of those.
+ *
+ * Reading tags means an ffprobe per file, which is slow for a large library and
+ * slower still over the network, so it is only done for local files the caller
+ * asked about.
+ */
+export declare function loadSource(tools: Tools, source: string, probeTags?: boolean): Promise<Track[]>;
 /**
  * Reading tags means an ffprobe per file, which is slow for a large library, so
  * the caller decides when to pay for it. Untagged entries still play.

package/dist/playlist.js

@@ -1,7 +1,8 @@
-/** The playlist: audio files found on disk, in a stable order. */
-import { readdirSync, statSync } from "node:fs";
+/** The playlist: audio found on disk or named by a playlist, in a stable order. */
+import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { probe } from "./audio.js";
+import { isHls, isPlaylistFile, isRemote, nameOf, parseM3u, parsePls, } from "./sources.js";
 export const AUDIO_EXTENSIONS = new Set([
     ".mp3", ".flac", ".ogg", ".oga", ".opus", ".m4a", ".aac",
     ".wav", ".wma", ".aiff", ".aif", ".alac", ".mp4", ".webm",
@@ -50,6 +51,60 @@ export function findAudio(root) {
     walk(root);
     return out;
 }
+/** An entry that was never probed: playable, just not described. */
+function bare(entry) {
+    return { path: entry.source, title: entry.title, artist: "", album: "", duration: entry.duration };
+}
+/**
+ * Read a playlist, from disk or over the network. An HLS playlist is not a list
+ * of tracks but one stream in segments, so it comes back as a single entry and
+ * ffmpeg is left to do what it is good at.
+ */
+export async function readPlaylist(source) {
+    let text;
+    if (isRemote(source)) {
+        const response = await fetch(source, { redirect: "follow" });
+        if (!response.ok)
+            throw new Error(`nixamp: ${source} answered ${response.status}`);
+        text = await response.text();
+    }
+    else {
+        text = readFileSync(source, "utf8");
+    }
+    if (isHls(text))
+        return [{ source, title: nameOf(source), duration: 0 }];
+    const entries = /\.pls$/i.test(source) ? parsePls(text, source) : parseM3u(text, source);
+    return entries;
+}
+/**
+ * Everything `nixamp <thing>` can be handed: a directory, a file, a playlist,
+ * or a URL to any of those.
+ *
+ * Reading tags means an ffprobe per file, which is slow for a large library and
+ * slower still over the network, so it is only done for local files the caller
+ * asked about.
+ */
+export async function loadSource(tools, source, probeTags = true) {
+    if (isPlaylistFile(source)) {
+        let entries;
+        try {
+            entries = await readPlaylist(source);
+        }
+        catch (error) {
+            // The playlist is the whole argument, so failing to read it is fatal --
+            // but it is fatal with a sentence, not a stack.
+            throw new Error(`nixamp: could not read ${source}: ${error.message.replace(/^nixamp: /, "")}`);
+        }
+        return entries.map((entry) => probeTags && !isRemote(entry.source) && entry.duration === 0
+            ? { ...probe(tools, entry.source), title: entry.title || probe(tools, entry.source).title }
+            : bare(entry));
+    }
+    // A bare URL is one remote thing to play. Whether it is a song or a live
+    // stream is ffmpeg's problem, and it is good at it.
+    if (isRemote(source))
+        return [bare({ source, title: nameOf(source), duration: 0 })];
+    return loadPlaylist(tools, source, probeTags);
+}
 /**
  * Reading tags means an ffprobe per file, which is slow for a large library, so
  * the caller decides when to pay for it. Untagged entries still play.

package/dist/publish.d.ts

@@ -0,0 +1,36 @@
+import { DEFAULT_DIRECTORY, type Listing } from "./directory.ts";
+export interface PublishTarget {
+    directory: string;
+    name: string;
+    /** The listen link: what a stranger opens. Never the control key. */
+    url: string;
+    tracks: number;
+    nowPlaying: () => string;
+    /**
+     * Called with whatever configuration the directory sent back. This is how
+     * nixamp.com turns x402 on and off for a server without it restarting.
+     */
+    onConfig?: (config: unknown) => void;
+}
+/**
+ * Ask, with yes as the default. Returns false without asking when there is no
+ * terminal on the other end, which is the case for the daemon and for CI.
+ */
+export declare function confirm(question: string, tty?: boolean): Promise<boolean>;
+/**
+ * Announce, then keep announcing. The directory forgets an entry that stops
+ * renewing, so stopping the heartbeat is how a stream leaves the list even if
+ * the process dies without saying goodbye.
+ */
+export declare class Publisher {
+    private readonly target;
+    private readonly fetcher;
+    private id;
+    private timer;
+    constructor(target: PublishTarget, fetcher?: typeof fetch);
+    start(): Promise<Listing | null>;
+    announce(): Promise<Listing | null>;
+    /** Leave the list now rather than waiting to be forgotten. */
+    stop(): Promise<void>;
+}
+export { DEFAULT_DIRECTORY };

package/dist/publish.js

@@ -0,0 +1,90 @@
+/**
+ * Publishing to the directory, and asking first.
+ *
+ * Listing a stream tells the world an address it can reach you on, so it is
+ * never done silently. The prompt defaults to yes; a terminal that cannot ask
+ * defaults to no, because "there was nobody to ask" is not consent.
+ */
+import { createInterface } from "node:readline/promises";
+import { DEFAULT_DIRECTORY, HEARTBEAT_MS } from "./directory.js";
+/**
+ * Ask, with yes as the default. Returns false without asking when there is no
+ * terminal on the other end, which is the case for the daemon and for CI.
+ */
+export async function confirm(question, tty = process.stdin.isTTY === true) {
+    if (!tty)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+        return answer === "" || answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Announce, then keep announcing. The directory forgets an entry that stops
+ * renewing, so stopping the heartbeat is how a stream leaves the list even if
+ * the process dies without saying goodbye.
+ */
+export class Publisher {
+    target;
+    fetcher;
+    id = null;
+    timer = null;
+    constructor(target, fetcher = fetch) {
+        this.target = target;
+        this.fetcher = fetcher;
+    }
+    async start() {
+        const first = await this.announce();
+        this.timer = setInterval(() => void this.announce(), HEARTBEAT_MS);
+        this.timer.unref?.();
+        return first;
+    }
+    async announce() {
+        try {
+            const response = await this.fetcher(`${this.target.directory}/api/directory`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    ...(this.id ? { id: this.id } : {}),
+                    name: this.target.name,
+                    url: this.target.url,
+                    tracks: this.target.tracks,
+                    nowPlaying: this.target.nowPlaying(),
+                }),
+            });
+            if (!response.ok)
+                return null;
+            const listing = (await response.json());
+            this.id = listing.id;
+            if (listing.config !== undefined)
+                this.target.onConfig?.(listing.config);
+            return listing;
+        }
+        catch {
+            // The directory being down is not a reason for a player to stop playing.
+            return null;
+        }
+    }
+    /** Leave the list now rather than waiting to be forgotten. */
+    async stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        if (this.id === null)
+            return;
+        try {
+            await this.fetcher(`${this.target.directory}/api/directory?id=${encodeURIComponent(this.id)}`, {
+                method: "DELETE",
+            });
+        }
+        catch {
+            // It expires on its own within the TTL, which is the point of the TTL.
+        }
+        this.id = null;
+    }
+}
+export { DEFAULT_DIRECTORY };