nixamp 0.28.45 → 0.30.1

package/dist/station-cli.js

@@ -0,0 +1,201 @@
+/**
+ * `nixamp station`: stations from a terminal, a script or a cron job.
+ *
+ * Talks to the daemon on this machine with its control key, or to another
+ * server with --url and --key, exactly as `nixamp admin` does. Every command
+ * takes --json for a script; without it, a line a person can read. Exit codes
+ * a script can branch on: 0 done, 1 the server said no (the reason and a
+ * stable code are printed), 2 the command was wrong, 3 the server could not
+ * be reached.
+ *
+ * Nothing here publishes as a side effect. `create` and `start` leave a
+ * station private; `publish` is its own command and says on what basis.
+ */
+import { resolveTarget } from "./admin.js";
+import { readState } from "./daemon.js";
+import { KEY_HEADER } from "./share.js";
+import { USAGE } from "./station-usage.js";
+export { USAGE };
+function flag(argv, name) {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+}
+function has(argv, name) {
+    return argv.includes(name);
+}
+class Unreachable extends Error {
+}
+export async function station(argv) {
+    const [command, id] = argv;
+    const json = has(argv, "--json");
+    if (!command || command === "help" || has(argv, "--help")) {
+        console.log(USAGE);
+        return command ? 0 : 2;
+    }
+    let target;
+    try {
+        target = resolveTarget(argv);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 3;
+    }
+    const headers = { "content-type": "application/json", ...(target.key ? { [KEY_HEADER]: target.key } : {}) };
+    const call = async (method, path, body) => {
+        let response;
+        try {
+            response = await fetch(`${target.url}${path}`, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+        }
+        catch (error) {
+            throw new Unreachable(`could not reach ${target.url}: ${error.message}`);
+        }
+        const text = await response.text();
+        let parsed = {};
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = { error: text };
+        }
+        return { status: response.status, body: parsed };
+    };
+    const needId = () => {
+        if (!id || id.startsWith("--")) {
+            console.error(`nixamp station ${command} needs a station id. \`nixamp station list\` shows them.`);
+            return null;
+        }
+        return id;
+    };
+    const show = (answer, line) => {
+        if (json) {
+            console.log(JSON.stringify(answer.body, null, 2));
+        }
+        else if (answer.status < 400) {
+            console.log(line(answer.body));
+        }
+        if (answer.status >= 400) {
+            if (!json)
+                console.error(`nixamp: ${String(answer.body["error"] ?? "refused")} (${String(answer.body["code"] ?? answer.status)})`);
+            return 1;
+        }
+        return 0;
+    };
+    const describe = (station) => {
+        const links = (station["links"] ?? {});
+        return [
+            `${String(station["name"])}  [${String(station["id"])}]`,
+            `  state       ${String(station["state"])} (wanted ${String(station["desired"])})`,
+            `  visibility  ${String(station["visibility"])}${station["listed"] ? ", listed in the directory" : ""}`,
+            `  rotation    ${station["shuffle"] ? "shuffle" : "in order"}${station["repeat"] ? ", repeating" : ", once"}; ${station["items"]?.length ?? 0} files at ${String(station["bitrate"])} kbps`,
+            ...(station["error"] ? [`  problem     ${String(station["error"])}`] : []),
+            ...(station["excluded"]?.length ? [`  left out   ${station["excluded"].length} files (nixamp station retry)`] : []),
+            ...(station["visibility"] !== "private" && links["page"] ? [`  listen      ${links["page"]}`] : []),
+        ].join("\n");
+    };
+    try {
+        switch (command) {
+            case "list": {
+                const answer = await call("GET", "/api/v1/stations?limit=200");
+                return show(answer, (body) => {
+                    const all = body["stations"] ?? [];
+                    return all.length === 0 ? "No stations yet. nixamp station create --name NAME --folder PATH" : all.map(describe).join("\n\n");
+                });
+            }
+            case "create": {
+                const name = flag(argv, "--name");
+                if (!name) {
+                    console.error("nixamp station create needs --name");
+                    return 2;
+                }
+                const items = flag(argv, "--items");
+                let folder = flag(argv, "--folder");
+                if (folder !== undefined) {
+                    // A path under the library is taken relative to it.
+                    const root = readState()?.source ?? "";
+                    if (root && folder.startsWith(root))
+                        folder = folder.slice(root.length);
+                }
+                if (items === undefined && folder === undefined) {
+                    console.error("nixamp station create needs --folder PATH or --items 0,1,2");
+                    return 2;
+                }
+                const bitrate = flag(argv, "--bitrate");
+                const answer = await call("POST", "/api/v1/stations", {
+                    name,
+                    ...(items !== undefined ? { items: items.split(",").map((one) => Number(one.trim())) } : { folder }),
+                    shuffle: has(argv, "--shuffle"),
+                    repeat: !has(argv, "--no-repeat"),
+                    ...(bitrate ? { bitrate: Number(bitrate) } : {}),
+                });
+                return show(answer, (body) => `Made (private, stopped):\n${describe(body["station"])}`);
+            }
+            case "show":
+            case "status": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                return show(await call("GET", `/api/v1/stations/${station}`), (body) => describe(body["station"]));
+            }
+            case "start":
+            case "stop":
+            case "skip":
+            case "retry": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                return show(await call("POST", `/api/v1/stations/${station}/${command}`, {}), (body) => describe(body["station"]));
+            }
+            case "publish": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                const basis = flag(argv, "--basis");
+                const unlisted = has(argv, "--unlisted");
+                const access = {
+                    visibility: unlisted ? "unlisted" : "public",
+                    listed: !unlisted && !has(argv, "--no-list"),
+                    ...(basis ? { rights: { basis, note: flag(argv, "--note") ?? "" } } : {}),
+                };
+                return show(await call("POST", `/api/v1/stations/${station}/access`, access), (body) => describe(body["station"]));
+            }
+            case "unpublish": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                const access = has(argv, "--private") ? { visibility: "private" } : { listed: false };
+                return show(await call("POST", `/api/v1/stations/${station}/access`, access), (body) => {
+                    const dropped = Number(body["dropped"] ?? 0);
+                    return `${describe(body["station"])}${dropped ? `\n  ${dropped} listener(s) disconnected; old links no longer work.` : ""}`;
+                });
+            }
+            case "link": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                const answer = has(argv, "--rotate")
+                    ? await call("POST", `/api/v1/stations/${station}/rotate-link`, {})
+                    : await call("GET", `/api/v1/stations/${station}`);
+                return show(answer, (body) => {
+                    const links = (body["station"]["links"] ?? {});
+                    return [`page    ${links["page"]}`, `stream  ${links["stream"]}`, `m3u     ${links["m3u"]}`].join("\n");
+                });
+            }
+            case "delete": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                return show(await call("DELETE", `/api/v1/stations/${station}`), () => `Deleted ${station}. Its files were not touched.`);
+            }
+            default:
+                console.error(`nixamp station: no command "${command}".\n\n${USAGE}`);
+                return 2;
+        }
+    }
+    catch (error) {
+        if (error instanceof Unreachable) {
+            console.error(`nixamp: ${error.message}`);
+            return 3;
+        }
+        throw error;
+    }
+}

package/dist/station-page.d.ts

@@ -0,0 +1,5 @@
+/** A station page's path: /station/<id>. */
+export declare const STATION_PAGE: RegExp;
+export declare const STATION_PAGE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<meta name=\"robots\" content=\"noindex\">\n<title>Station \u00B7 nixamp</title>\n<style>\n:root{--bg:#f6f5f2;--fg:#17171a;--muted:#5d5d66;--card:#fff;--line:#dedcd6;--accent:#1f6feb;--live:#0b7a3b;--warn:#9a6700;--off:#8c2f39}\n@media (prefers-color-scheme:dark){:root{--bg:#121214;--fg:#ececf1;--muted:#a4a4b0;--card:#1c1c20;--line:#2c2c33;--accent:#6aa7ff;--live:#3fbf7f;--warn:#e3b341;--off:#f0838f}}\n*{box-sizing:border-box}html,body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,-apple-system,\"Segoe UI\",sans-serif}\nmain{max-width:560px;margin:0 auto;padding:48px 16px}\n.card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:24px}\nh1{font-size:1.6rem;line-height:1.2;margin:0 0 4px}\n.about{color:var(--muted);margin:0 0 20px}\n.chip{display:inline-flex;align-items:center;gap:8px;font-size:.85rem;font-weight:600;padding:4px 10px;border-radius:999px;border:1px solid var(--line)}\n.chip::before{content:\"\";width:8px;height:8px;border-radius:50%;background:currentColor}\n.live{color:var(--live)}.reconnecting{color:var(--warn)}.unavailable,.stopped{color:var(--off)}\n.now{margin:20px 0;min-height:3em}.now .title{font-weight:600}.now .by{color:var(--muted)}\n.controls{display:flex;align-items:center;gap:16px;flex-wrap:wrap}\nbutton{font:inherit;font-weight:600;border:0;border-radius:999px;padding:12px 28px;background:var(--accent);color:#fff;cursor:pointer;min-width:120px}\nbutton:disabled{opacity:.5;cursor:not-allowed}\nbutton:focus-visible,input:focus-visible,a:focus-visible{outline:3px solid var(--accent);outline-offset:3px}\nlabel{display:flex;align-items:center;gap:8px;color:var(--muted);font-size:.9rem}\ninput[type=range]{width:120px;accent-color:var(--accent)}\n.small{margin-top:20px;font-size:.85rem;color:var(--muted)}.small a{color:inherit}\n.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}\n@media (prefers-reduced-motion:no-preference){.live::before{animation:pulse 2s ease-in-out infinite}}\n@keyframes pulse{50%{opacity:.35}}\n</style>\n</head>\n<body>\n<main>\n  <div class=\"card\">\n    <span id=\"state\" class=\"chip unavailable\" role=\"status\">Loading</span>\n    <h1 id=\"name\">&nbsp;</h1>\n    <p id=\"about\" class=\"about\" hidden></p>\n    <div class=\"now\" aria-live=\"polite\"><div id=\"title\" class=\"title\"></div><div id=\"by\" class=\"by\"></div></div>\n    <div class=\"controls\">\n      <button id=\"play\" type=\"button\" aria-pressed=\"false\" disabled>Play</button>\n      <label>Volume <input id=\"volume\" type=\"range\" min=\"0\" max=\"1\" step=\"0.05\" value=\"1\"></label>\n    </div>\n    <p class=\"small\"><a id=\"m3u\" href=\"#\">Open in another player (.m3u)</a> \u00B7 Pausing here does not pause the station.</p>\n  </div>\n  <p class=\"small\">Played by <a href=\"https://nixamp.com\">nixamp</a>.</p>\n  <div id=\"announce\" class=\"sr\" aria-live=\"assertive\"></div>\n</main>\n<script>\n(() => {\n  const id = location.pathname.split(\"/\").filter(Boolean)[1] || \"\";\n  const token = new URLSearchParams(location.search).get(\"t\") || \"\";\n  const q = \"?t=\" + encodeURIComponent(token);\n  const api = \"/api/v1/stations/\" + encodeURIComponent(id);\n  const $ = (s) => document.querySelector(s);\n  const audio = new Audio();\n  audio.preload = \"none\";\n  let wanted = false, retry = 0, timer = 0, last = null;\n  const chip = (state, text) => { const c = $(\"#state\"); c.className = \"chip \" + state; c.textContent = text; };\n  const say = (text) => { $(\"#announce\").textContent = text; };\n  const draw = (s) => {\n    last = s;\n    document.title = s.name + \" \u00B7 nixamp\";\n    $(\"#name\").textContent = s.name;\n    $(\"#about\").textContent = s.description || \"\";\n    $(\"#about\").hidden = !s.description;\n    const playing = s.nowPlaying;\n    $(\"#title\").textContent = playing ? (playing.title || \"Untitled\") : (s.state === \"live\" ? \"On the air\" : \"\");\n    $(\"#by\").textContent = playing ? [playing.artist, playing.album].filter(Boolean).join(\" \u00B7 \") : \"\";\n    if (wanted && retry > 0) chip(\"reconnecting\", \"Reconnecting\");\n    else if (s.state === \"live\") chip(\"live\", \"Live\");\n    else if (s.state === \"starting\" || s.state === \"recovering\") chip(\"reconnecting\", \"Coming back\");\n    else if (s.state === \"stopped\") chip(\"stopped\", \"Off the air\");\n    else chip(\"unavailable\", \"Unavailable\");\n    $(\"#play\").disabled = !(s.state === \"live\" || s.state === \"recovering\" || s.state === \"starting\");\n    $(\"#m3u\").href = api + \"/listen.m3u\" + q;\n  };\n  const poll = async () => {\n    try {\n      const r = await fetch(api + \"/state\" + q, { cache: \"no-store\" });\n      if (r.status === 404) { $(\"#name\").textContent = \"This station is not available\"; chip(\"unavailable\", \"Unavailable\"); $(\"#play\").disabled = true; stop(); return; }\n      if (r.ok) draw(await r.json());\n    } catch {}\n  };\n  // Always the live edge: a fresh request, never a cached or paused one.\n  const join = () => { audio.src = api + \"/stream\" + q + \"&n=\" + Date.now(); audio.play().catch(() => { wanted = false; button(); }); };\n  const stop = () => { wanted = false; clearTimeout(timer); audio.pause(); audio.removeAttribute(\"src\"); audio.load(); button(); };\n  const button = () => { const b = $(\"#play\"); b.textContent = wanted ? \"Stop\" : \"Play\"; b.setAttribute(\"aria-pressed\", String(wanted)); };\n  const again = () => {\n    if (!wanted) return;\n    retry += 1;\n    if (last) draw(last);\n    clearTimeout(timer);\n    timer = setTimeout(join, Math.min(15000, 1000 * 2 ** Math.min(retry, 4)));\n  };\n  audio.addEventListener(\"playing\", () => { if (retry) say(\"Back on\"); retry = 0; if (last) draw(last); });\n  audio.addEventListener(\"error\", again);\n  audio.addEventListener(\"ended\", again);\n  audio.addEventListener(\"stalled\", () => { if (wanted && audio.readyState < 3) again(); });\n  $(\"#play\").addEventListener(\"click\", () => { if (wanted) { stop(); say(\"Stopped\"); } else { wanted = true; retry = 0; button(); join(); say(\"Playing\"); } });\n  $(\"#volume\").addEventListener(\"input\", (e) => { audio.volume = Number(e.target.value); });\n  poll();\n  setInterval(poll, 5000);\n})();\n</script>\n</body>\n</html>\n";
+/** Only its own script and style, only its own server, never framed. */
+export declare const STATION_PAGE_CSP: string;

package/dist/station-page.js

@@ -0,0 +1,137 @@
+/**
+ * The page a station's link opens: its name, what is on, and Play.
+ *
+ * Served by the station's own server, without the server's key, because the
+ * link is the key: the page reads `t` from its own address and asks the
+ * station's state and stream with it. Nothing about the station is written
+ * into the HTML, so the page is the same bytes for every station and can be
+ * locked down with a content security policy naming its script and style by
+ * hash. A private station, or a wrong link, shows "not available" -- the
+ * same answer, so the page cannot be used to find out which stations exist.
+ */
+import { createHash } from "node:crypto";
+const STYLE = `
+:root{--bg:#f6f5f2;--fg:#17171a;--muted:#5d5d66;--card:#fff;--line:#dedcd6;--accent:#1f6feb;--live:#0b7a3b;--warn:#9a6700;--off:#8c2f39}
+@media (prefers-color-scheme:dark){:root{--bg:#121214;--fg:#ececf1;--muted:#a4a4b0;--card:#1c1c20;--line:#2c2c33;--accent:#6aa7ff;--live:#3fbf7f;--warn:#e3b341;--off:#f0838f}}
+*{box-sizing:border-box}html,body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:560px;margin:0 auto;padding:48px 16px}
+.card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:24px}
+h1{font-size:1.6rem;line-height:1.2;margin:0 0 4px}
+.about{color:var(--muted);margin:0 0 20px}
+.chip{display:inline-flex;align-items:center;gap:8px;font-size:.85rem;font-weight:600;padding:4px 10px;border-radius:999px;border:1px solid var(--line)}
+.chip::before{content:"";width:8px;height:8px;border-radius:50%;background:currentColor}
+.live{color:var(--live)}.reconnecting{color:var(--warn)}.unavailable,.stopped{color:var(--off)}
+.now{margin:20px 0;min-height:3em}.now .title{font-weight:600}.now .by{color:var(--muted)}
+.controls{display:flex;align-items:center;gap:16px;flex-wrap:wrap}
+button{font:inherit;font-weight:600;border:0;border-radius:999px;padding:12px 28px;background:var(--accent);color:#fff;cursor:pointer;min-width:120px}
+button:disabled{opacity:.5;cursor:not-allowed}
+button:focus-visible,input:focus-visible,a:focus-visible{outline:3px solid var(--accent);outline-offset:3px}
+label{display:flex;align-items:center;gap:8px;color:var(--muted);font-size:.9rem}
+input[type=range]{width:120px;accent-color:var(--accent)}
+.small{margin-top:20px;font-size:.85rem;color:var(--muted)}.small a{color:inherit}
+.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
+@media (prefers-reduced-motion:no-preference){.live::before{animation:pulse 2s ease-in-out infinite}}
+@keyframes pulse{50%{opacity:.35}}
+`;
+const SCRIPT = `
+(() => {
+  const id = location.pathname.split("/").filter(Boolean)[1] || "";
+  const token = new URLSearchParams(location.search).get("t") || "";
+  const q = "?t=" + encodeURIComponent(token);
+  const api = "/api/v1/stations/" + encodeURIComponent(id);
+  const $ = (s) => document.querySelector(s);
+  const audio = new Audio();
+  audio.preload = "none";
+  let wanted = false, retry = 0, timer = 0, last = null;
+  const chip = (state, text) => { const c = $("#state"); c.className = "chip " + state; c.textContent = text; };
+  const say = (text) => { $("#announce").textContent = text; };
+  const draw = (s) => {
+    last = s;
+    document.title = s.name + " · nixamp";
+    $("#name").textContent = s.name;
+    $("#about").textContent = s.description || "";
+    $("#about").hidden = !s.description;
+    const playing = s.nowPlaying;
+    $("#title").textContent = playing ? (playing.title || "Untitled") : (s.state === "live" ? "On the air" : "");
+    $("#by").textContent = playing ? [playing.artist, playing.album].filter(Boolean).join(" · ") : "";
+    if (wanted && retry > 0) chip("reconnecting", "Reconnecting");
+    else if (s.state === "live") chip("live", "Live");
+    else if (s.state === "starting" || s.state === "recovering") chip("reconnecting", "Coming back");
+    else if (s.state === "stopped") chip("stopped", "Off the air");
+    else chip("unavailable", "Unavailable");
+    $("#play").disabled = !(s.state === "live" || s.state === "recovering" || s.state === "starting");
+    $("#m3u").href = api + "/listen.m3u" + q;
+  };
+  const poll = async () => {
+    try {
+      const r = await fetch(api + "/state" + q, { cache: "no-store" });
+      if (r.status === 404) { $("#name").textContent = "This station is not available"; chip("unavailable", "Unavailable"); $("#play").disabled = true; stop(); return; }
+      if (r.ok) draw(await r.json());
+    } catch {}
+  };
+  // Always the live edge: a fresh request, never a cached or paused one.
+  const join = () => { audio.src = api + "/stream" + q + "&n=" + Date.now(); audio.play().catch(() => { wanted = false; button(); }); };
+  const stop = () => { wanted = false; clearTimeout(timer); audio.pause(); audio.removeAttribute("src"); audio.load(); button(); };
+  const button = () => { const b = $("#play"); b.textContent = wanted ? "Stop" : "Play"; b.setAttribute("aria-pressed", String(wanted)); };
+  const again = () => {
+    if (!wanted) return;
+    retry += 1;
+    if (last) draw(last);
+    clearTimeout(timer);
+    timer = setTimeout(join, Math.min(15000, 1000 * 2 ** Math.min(retry, 4)));
+  };
+  audio.addEventListener("playing", () => { if (retry) say("Back on"); retry = 0; if (last) draw(last); });
+  audio.addEventListener("error", again);
+  audio.addEventListener("ended", again);
+  audio.addEventListener("stalled", () => { if (wanted && audio.readyState < 3) again(); });
+  $("#play").addEventListener("click", () => { if (wanted) { stop(); say("Stopped"); } else { wanted = true; retry = 0; button(); join(); say("Playing"); } });
+  $("#volume").addEventListener("input", (e) => { audio.volume = Number(e.target.value); });
+  poll();
+  setInterval(poll, 5000);
+})();
+`;
+const hash = (text) => `'sha256-${createHash("sha256").update(text).digest("base64")}'`;
+const PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>Station · nixamp</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<main>
+  <div class="card">
+    <span id="state" class="chip unavailable" role="status">Loading</span>
+    <h1 id="name">&nbsp;</h1>
+    <p id="about" class="about" hidden></p>
+    <div class="now" aria-live="polite"><div id="title" class="title"></div><div id="by" class="by"></div></div>
+    <div class="controls">
+      <button id="play" type="button" aria-pressed="false" disabled>Play</button>
+      <label>Volume <input id="volume" type="range" min="0" max="1" step="0.05" value="1"></label>
+    </div>
+    <p class="small"><a id="m3u" href="#">Open in another player (.m3u)</a> · Pausing here does not pause the station.</p>
+  </div>
+  <p class="small">Played by <a href="https://nixamp.com">nixamp</a>.</p>
+  <div id="announce" class="sr" aria-live="assertive"></div>
+</main>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+/** A station page's path: /station/<id>. */
+export const STATION_PAGE = /^\/station\/([a-z0-9]{10})\/?$/;
+export const STATION_PAGE_HTML = PAGE;
+/** Only its own script and style, only its own server, never framed. */
+export const STATION_PAGE_CSP = [
+    "default-src 'none'",
+    `script-src ${hash(SCRIPT)}`,
+    `style-src ${hash(STYLE)}`,
+    "connect-src 'self'",
+    "media-src 'self'",
+    "img-src 'self'",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'none'",
+].join("; ");

package/dist/station-routes.d.ts

@@ -0,0 +1,60 @@
+/**
+ * /api/v1/stations: making, running and sharing stations.
+ *
+ * Two kinds of caller, kept apart. The owner -- the control key, or the
+ * nixamp.com account that owns this server -- manages: create, edit, start,
+ * stop, skip, share. A listener holds one station's link and may do three
+ * things with it: hear the stream, ask what is on, and fetch an .m3u for
+ * another player. A listener's link never opens the library, another station,
+ * or anything that changes what is playing.
+ *
+ * Errors carry a stable `code` beside the sentence, so the page, the CLI and
+ * an agent over MCP can each tell "rights_required" from "not_found" without
+ * reading English.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Channels } from "./channels.ts";
+import type { StationRunner } from "./station-runner.ts";
+import { type OwnerStation, type PublicStation, type Station, type StationStore } from "./stations.ts";
+/** Whether this path is one a station's own link may open, without the server's key. */
+export declare function isStationListenPath(path: string): boolean;
+export interface StationContext {
+    store: StationStore;
+    runner: StationRunner;
+    channels: Channels;
+    /** Holds the control key, or is signed in as this server's owner. */
+    canControl: boolean;
+    /** The nixamp.com account asking, "" when it is the control key. */
+    account: string;
+    /** Files chosen by track index or by folder; null when neither was given. */
+    select: (body: {
+        items?: unknown;
+        folder?: unknown;
+    }) => string[] | null;
+    /** What the library knows about a file, for now playing. */
+    trackFor: (file: string) => {
+        title: string;
+        artist: string;
+        album: string;
+    } | null;
+    /** This server's address as the asker reached it, for links. */
+    base: string;
+    json: (response: ServerResponse, status: number, body: unknown) => void;
+    readBody: (request: IncomingMessage) => Promise<string>;
+    /** Headers every answer carries (CORS). */
+    headers: Record<string, string>;
+}
+declare function links(ctx: StationContext, station: Station): {
+    page: string;
+    stream: string;
+    m3u: string;
+    state: string;
+};
+export declare function publicView(ctx: StationContext, station: Station): PublicStation;
+export declare function ownerView(ctx: StationContext, station: Station): OwnerStation & {
+    links: ReturnType<typeof links>;
+    nowPlaying: string;
+};
+/** Answers anything under /api/v1/stations; false when the path is not one. */
+export declare function handleStations(request: IncomingMessage, response: ServerResponse, path: string, url: URL, ctx: StationContext): Promise<boolean>;
+export {};

package/dist/station-routes.js

@@ -0,0 +1,249 @@
+import { StationError, channelOf, tokensMatch, } from "./stations.js";
+/** The three things a station's link opens. */
+const LISTEN = /^\/api\/v1\/stations\/([a-z0-9]{10})\/(stream|state|listen\.m3u)$/;
+/** Whether this path is one a station's own link may open, without the server's key. */
+export function isStationListenPath(path) {
+    return LISTEN.test(path);
+}
+function fail(ctx, response, error) {
+    if (error instanceof StationError) {
+        ctx.json(response, error.status, { error: error.message, code: error.code });
+        return;
+    }
+    ctx.json(response, 500, { error: error instanceof Error ? error.message : String(error), code: "internal" });
+}
+function links(ctx, station) {
+    const query = `t=${encodeURIComponent(station.listenToken)}`;
+    const at = `${ctx.base}/api/v1/stations/${station.id}`;
+    return {
+        page: `${ctx.base}/station/${station.id}?${query}`,
+        stream: `${at}/stream?${query}`,
+        m3u: `${at}/listen.m3u?${query}`,
+        state: `${at}/state?${query}`,
+    };
+}
+/** The file on the air now, as the channel's own encoder last reported it. */
+function nowPlayingFile(ctx, station) {
+    const info = ctx.channels.info(channelOf(station.id));
+    if (!info?.playlist?.length)
+        return "";
+    return info.playlist[info.playlistAt ?? 0] ?? "";
+}
+export function publicView(ctx, station) {
+    const state = ctx.runner.observed(station.id);
+    const file = state === "live" || state === "recovering" ? nowPlayingFile(ctx, station) : "";
+    const track = file ? ctx.trackFor(file) : null;
+    return {
+        id: station.id,
+        name: station.name,
+        description: station.description,
+        visibility: station.visibility,
+        state,
+        // Tags, or nothing: a bare file name is the owner's, not the public's.
+        nowPlaying: track && (track.title || track.artist) ? track : null,
+        format: state === "stopped" || state === "offline" ? null : { codec: "mp3", bitrateKbps: station.bitrate, sampleRate: 48_000, channels: 2 },
+        listeners: ctx.runner.listeners(station.id),
+    };
+}
+export function ownerView(ctx, station) {
+    const { failures, idempotencyKey: _key, ...rest } = station;
+    return {
+        ...rest,
+        state: ctx.runner.observed(station.id),
+        excluded: Object.entries(failures).filter(([, count]) => count >= 3).map(([file]) => file),
+        listeners: ctx.runner.listeners(station.id),
+        error: ctx.runner.error(station.id),
+        links: links(ctx, station),
+        nowPlaying: nowPlayingFile(ctx, station),
+    };
+}
+/** Answers anything under /api/v1/stations; false when the path is not one. */
+export async function handleStations(request, response, path, url, ctx) {
+    if (path !== "/api/v1/stations" && !path.startsWith("/api/v1/stations/"))
+        return false;
+    const method = request.method ?? "GET";
+    const listen = LISTEN.exec(path);
+    if (listen) {
+        const station = ctx.store.get(listen[1]);
+        const token = url.searchParams.get("t") ?? "";
+        // The same answer for "no such station" and "not with that link", so a
+        // link cannot be used to find out which stations exist.
+        const allowed = station !== undefined &&
+            (ctx.canControl || (station.visibility !== "private" && token !== "" && tokensMatch(token, station.listenToken)));
+        if (!station || !allowed) {
+            ctx.json(response, 404, { error: "no such station, or not with that link", code: "not_found" });
+            return true;
+        }
+        if (method !== "GET" && method !== "HEAD") {
+            ctx.json(response, 405, { error: "a station's link can listen, not drive", code: "method_not_allowed" });
+            return true;
+        }
+        const what = listen[2];
+        if (what === "state") {
+            ctx.json(response, 200, publicView(ctx, station));
+            return true;
+        }
+        if (what === "listen.m3u") {
+            const stream = links(ctx, station).stream;
+            response.writeHead(200, {
+                ...ctx.headers,
+                "content-type": "audio/x-mpegurl; charset=utf-8",
+                "content-disposition": `inline; filename="${station.id}.m3u"`,
+                "cache-control": "no-store",
+            });
+            response.end(`#EXTM3U\n#EXTINF:-1,${station.name.replace(/[\r\n]/g, " ")}\n${stream}\n`);
+            return true;
+        }
+        const channelId = channelOf(station.id);
+        if (!ctx.channels.has(channelId)) {
+            ctx.json(response, 503, { error: "the station is not on the air", code: "not_live", state: ctx.runner.observed(station.id) });
+            return true;
+        }
+        response.writeHead(200, { ...ctx.headers, "content-type": ctx.channels.contentType(channelId), "cache-control": "no-store" });
+        if (method === "HEAD") {
+            response.end();
+            return true;
+        }
+        const detach = ctx.channels.listen(channelId, response);
+        if (detach === null) {
+            response.end();
+            return true;
+        }
+        const untrack = ctx.runner.track(station.id, { end: () => response.destroy() });
+        const leave = () => {
+            detach();
+            untrack();
+        };
+        request.on("close", leave);
+        response.on("close", leave);
+        return true;
+    }
+    // Everything else is the owner's.
+    if (!ctx.canControl) {
+        ctx.json(response, 403, { error: "only this server's owner manages its stations", code: "forbidden" });
+        return true;
+    }
+    const body = async () => {
+        if (method === "GET" || method === "DELETE")
+            return {};
+        const raw = await ctx.readBody(request);
+        if (raw.trim() === "")
+            return {};
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new StationError("bad_json", "the body is not JSON");
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new StationError("bad_json", "the body is not a JSON object");
+        return parsed;
+    };
+    try {
+        if (path === "/api/v1/stations") {
+            if (method === "GET") {
+                const all = ctx.store.list();
+                const limit = Math.min(200, Math.max(1, Number(url.searchParams.get("limit")) || 50));
+                const offset = Math.max(0, Number(url.searchParams.get("offset")) || 0);
+                ctx.json(response, 200, { stations: all.slice(offset, offset + limit).map((one) => ownerView(ctx, one)), total: all.length, limit, offset });
+                return true;
+            }
+            if (method === "POST") {
+                const input = await body();
+                const key = String(request.headers["idempotency-key"] ?? input["idempotencyKey"] ?? "").trim();
+                const again = ctx.store.byIdempotencyKey(key);
+                if (again) {
+                    ctx.json(response, 200, { station: ownerView(ctx, again), created: false });
+                    return true;
+                }
+                const items = ctx.select(input);
+                if (items === null)
+                    throw new StationError("items_required", "choose files by track index (items) or a folder");
+                const station = ctx.store.create(input, items, ctx.account, Date.now(), key);
+                ctx.json(response, 201, { station: ownerView(ctx, station), created: true });
+                return true;
+            }
+            ctx.json(response, 405, { error: "GET or POST", code: "method_not_allowed" });
+            return true;
+        }
+        const match = /^\/api\/v1\/stations\/([a-z0-9]{10})(?:\/([a-z-]+))?$/.exec(path);
+        if (!match) {
+            ctx.json(response, 404, { error: "no such station", code: "not_found" });
+            return true;
+        }
+        const id = match[1];
+        const action = match[2];
+        const station = ctx.store.get(id);
+        if (!station) {
+            ctx.json(response, 404, { error: "no such station", code: "not_found" });
+            return true;
+        }
+        if (action === undefined) {
+            if (method === "GET") {
+                ctx.json(response, 200, { station: ownerView(ctx, station) });
+                return true;
+            }
+            if (method === "PATCH") {
+                const input = await body();
+                const items = ctx.select(input);
+                const updated = ctx.store.update(id, input, items);
+                ctx.json(response, 200, { station: ownerView(ctx, updated) });
+                return true;
+            }
+            if (method === "DELETE") {
+                ctx.runner.remove(id);
+                ctx.json(response, 200, { deleted: id });
+                return true;
+            }
+            ctx.json(response, 405, { error: "GET, PATCH or DELETE", code: "method_not_allowed" });
+            return true;
+        }
+        if (method !== "POST") {
+            ctx.json(response, 405, { error: "POST", code: "method_not_allowed" });
+            return true;
+        }
+        if (action === "start") {
+            const started = await ctx.runner.start(id);
+            ctx.json(response, 200, { station: ownerView(ctx, started) });
+            return true;
+        }
+        if (action === "stop") {
+            ctx.json(response, 200, { station: ownerView(ctx, ctx.runner.stop(id)) });
+            return true;
+        }
+        if (action === "skip") {
+            ctx.runner.skip(id);
+            ctx.json(response, 200, { station: ownerView(ctx, station) });
+            return true;
+        }
+        if (action === "retry") {
+            ctx.json(response, 200, { station: ownerView(ctx, ctx.store.clearFailures(id)) });
+            return true;
+        }
+        if (action === "rotate-link") {
+            const rotated = ctx.store.rotateToken(id);
+            const dropped = ctx.runner.revoke(id);
+            ctx.json(response, 200, { station: ownerView(ctx, rotated), dropped });
+            return true;
+        }
+        if (action === "access") {
+            const input = await body();
+            const rights = input["rights"];
+            const { station: changed, revoked } = ctx.store.setAccess(id, {
+                visibility: input["visibility"],
+                listed: input["listed"],
+                rights: typeof rights === "object" && rights !== null ? rights : null,
+            }, ctx.account || "control-key");
+            const dropped = revoked ? ctx.runner.revoke(id) : 0;
+            ctx.json(response, 200, { station: ownerView(ctx, changed), dropped });
+            return true;
+        }
+        ctx.json(response, 404, { error: "no such action", code: "not_found" });
+        return true;
+    }
+    catch (error) {
+        fail(ctx, response, error);
+        return true;
+    }
+}