nixamp 0.68.1 → 0.69.0

package/dist/ai-label.d.ts

@@ -96,9 +96,9 @@ export interface LabelSettings {
     videos: boolean;
     /** Each album's single (song 1) is filmed with Veo, while the month's Veo budget lasts. */
     veo: boolean;
-    /** How many 8 s Veo shots of the band playing (never the singer) a single is cut from. */
+    /** How many 4 s Veo shots of the band playing (never the singer) a single is cut from. */
     veoShots: number;
-    /** How many 8 s Veo story scenes (a short film from the song's words, nobody singing) a single gets. */
+    /** How many 4 s Veo story scenes (a short film from the song's words, nobody singing) a single gets. */
     storyShots: number;
     /** How many close-ups of the singer a single gets, lip-synced to the song (0: none, the band only). */
     lipsyncShots: number;
@@ -107,6 +107,8 @@ export interface LabelSettings {
      * length (shotPlan) and the three above are not used. Setting any of them turns this off.
      */
     coverSong: boolean;
+    /** With coverSong: what one music video may cost in dollars, the shots planned to fit (shotPlan). */
+    videoUsd: number;
     /** Public, listed and owned, so the genre stations are on the guide. */
     publish: boolean;
     /** Songs made at the same time (ElevenLabs takes several requests at once on a paid plan). */
@@ -208,16 +210,32 @@ export declare function renderStoryVideo(ffmpeg: string[], input: {
         seconds: number;
     }>;
 }): Promise<void>;
+/** What a second of Veo and of lip sync is counted at on nixamp.com (veo-studio.ts), and the shots' lengths. */
+export declare const VEO_USD_PER_SECOND = 0.15;
+export declare const LIPSYNC_USD_PER_SECOND = 0.1;
+/** Story and band shots: the cut takes 4 s at a time, so a 4 s shot is used whole at half an 8 s one's price. */
+export declare const SHOT_SECONDS = 4;
+/** The singer's close-ups stay 8 s: each is lip-synced to 8 s of the song. */
+export declare const SINGER_SECONDS = 8;
+/** What one music video may cost (Anthony, 2026-10-21: "$5-10"); videoUsd in the settings. */
+export declare const VIDEO_USD = 8;
 /**
- * How many shots a single needs so that its footage covers the whole song with
- * nothing shown twice (8 s a shot, the singer's close-ups whole, the rest cut in
- * 4 s halves): about a quarter the singer, a fifth the band, the rest the story.
+ * The shots a single gets for its budget: two lip-synced close-ups of the singer,
+ * then as many 4 s shots as the rest buys, a third the band and the rest the
+ * story. Footage shorter than the song is cut in turn and shown again.
+ * $8 with a singer: 2 close-ups ($4.00 with their sync) and 6 shots ($3.60).
  */
-export declare function shotPlan(seconds: number, singing: boolean): {
+export declare function shotPlan(_seconds: number, singing: boolean, usd?: number): {
     story: number;
     band: number;
     singer: number;
 };
+/** What a plan costs on nixamp.com, in dollars. */
+export declare function planUsd(plan: {
+    story: number;
+    band: number;
+    singer: number;
+}): number;
 /**
  * Where a single's lip-synced close-ups go: the start of a sung line (its .lrc)
  * nearest a quarter and three quarters in (one: a third in), each `length`

package/dist/ai-label.js

@@ -277,6 +277,7 @@ export const DEFAULTS = {
     storyShots: 4,
     lipsyncShots: 2,
     coverSong: true,
+    videoUsd: 8, // VIDEO_USD
     parallel: 1,
     genreOrder: ["Punk", "Blues", "Country", "Jazz", "Classic Rock", "Metal", "Hip-Hop", "Pop", "R&B"],
 };
@@ -655,16 +656,33 @@ export function renderStoryVideo(ffmpeg, input) {
         "-movflags", "+faststart+use_metadata_tags", input.out];
     return runLow(ffmpeg, [...ffmpeg.slice(1), ...args], 60 * 60_000, "the video failed");
 }
+/** What a second of Veo and of lip sync is counted at on nixamp.com (veo-studio.ts), and the shots' lengths. */
+export const VEO_USD_PER_SECOND = 0.15;
+export const LIPSYNC_USD_PER_SECOND = 0.1;
+/** Story and band shots: the cut takes 4 s at a time, so a 4 s shot is used whole at half an 8 s one's price. */
+export const SHOT_SECONDS = 4;
+/** The singer's close-ups stay 8 s: each is lip-synced to 8 s of the song. */
+export const SINGER_SECONDS = 8;
+/** What one music video may cost (Anthony, 2026-10-21: "$5-10"); videoUsd in the settings. */
+export const VIDEO_USD = 8;
 /**
- * How many shots a single needs so that its footage covers the whole song with
- * nothing shown twice (8 s a shot, the singer's close-ups whole, the rest cut in
- * 4 s halves): about a quarter the singer, a fifth the band, the rest the story.
+ * The shots a single gets for its budget: two lip-synced close-ups of the singer,
+ * then as many 4 s shots as the rest buys, a third the band and the rest the
+ * story. Footage shorter than the song is cut in turn and shown again.
+ * $8 with a singer: 2 close-ups ($4.00 with their sync) and 6 shots ($3.60).
  */
-export function shotPlan(seconds, singing) {
-    const total = Math.ceil(Math.max(30, seconds) / 8) + 1;
-    const singer = singing ? Math.max(2, Math.round(total / 4)) : 0;
-    const band = Math.max(2, Math.round(total / 5));
-    return { story: Math.max(2, total - singer - band), band, singer };
+export function shotPlan(_seconds, singing, usd = VIDEO_USD) {
+    const closeUp = SINGER_SECONDS * (VEO_USD_PER_SECOND + LIPSYNC_USD_PER_SECOND), shot = SHOT_SECONDS * VEO_USD_PER_SECOND;
+    // Two close-ups when they leave room for at least two shots; one when the budget is tight.
+    const singer = !singing ? 0 : usd >= 2 * closeUp + 2 * shot ? 2 : 1;
+    const left = usd - singer * SINGER_SECONDS * (VEO_USD_PER_SECOND + LIPSYNC_USD_PER_SECOND);
+    const shots = Math.max(2, Math.floor(left / (SHOT_SECONDS * VEO_USD_PER_SECOND) + 1e-9));
+    const band = Math.max(1, Math.round(shots / 3));
+    return { story: Math.max(1, shots - band), band, singer };
+}
+/** What a plan costs on nixamp.com, in dollars. */
+export function planUsd(plan) {
+    return (plan.story + plan.band) * SHOT_SECONDS * VEO_USD_PER_SECOND + plan.singer * SINGER_SECONDS * (VEO_USD_PER_SECOND + LIPSYNC_USD_PER_SECOND);
 }
 /**
  * Where a single's lip-synced close-ups go: the start of a sung line (its .lrc)
@@ -1017,6 +1035,9 @@ export class AiLabel {
             this.settings.coverSong = false;
         if (input["coverSong"] !== undefined)
             this.settings.coverSong = input["coverSong"] === true;
+        const usd = Number(input["videoUsd"]);
+        if (input["videoUsd"] !== undefined && Number.isFinite(usd))
+            this.settings.videoUsd = Math.min(40, Math.max(2, usd));
         const perDay = whole("albumsPerDay", 0, 24);
         if (perDay !== undefined)
             this.settings.albumsPerDay = perDay;
@@ -1287,7 +1308,7 @@ export class AiLabel {
         // Paid-for shots live beside the album until the video is cut, so nothing filmed is filmed twice.
         const shots = join(_album.folder, `.veo-${song.n}`);
         const plan = this.settings.coverSong
-            ? shotPlan(seconds, Boolean(this.deps.lipsync))
+            ? shotPlan(seconds, Boolean(this.deps.lipsync), this.settings.videoUsd ?? VIDEO_USD)
             : { story: this.settings.storyShots, band: this.settings.veoShots, singer: this.settings.lipsyncShots };
         const { band: clips, singer } = await this.filmShots(artist, _album, song, shots, scenes, plan);
         const wanted = plan.band + plan.story;
@@ -1299,7 +1320,9 @@ export class AiLabel {
             throw new Error("the singer's close-ups are not filmed yet");
         const pinned = await this.syncCloseUps(song, singer, seconds, shots);
         await (this.deps.filmedVideo ?? ((input) => renderFilmedVideo(this.deps.ffmpeg, input)))({ audio: song.file, clips, seconds, artist: artist.name, title: song.title, out, ...(pinned.length ? { pinned } : {}) });
-        rmSync(shots, { recursive: true, force: true });
+        // Paid shots are kept until the video is whole (every close-up synced): a re-cut films only what is missing.
+        if (!singing || pinned.length >= plan.singer)
+            rmSync(shots, { recursive: true, force: true });
         return { version: FILMED, ...(singing ? { singer: pinned.length ? "synced" : "unsynced" } : {}) };
     }
     /**
@@ -1422,14 +1445,14 @@ export class AiLabel {
         // the portraits: they would pull the whole band into every scene.
         // The singer first: a day's few Veo requests go to what the video is for, then the story and the band.
         const plan = [
-            ...(this.deps.lipsync ? veoPrompts(artist, song, singers, counts.singer, "singer").map((prompt, i) => ({ prompt, file: join(keep, `singer-${i}.mp4`), into: singer, refs: singerRefs })) : []),
-            ...storyFiles.map((file, i) => ({ prompt: storyPrompts[i] ?? "", file, into: story, refs: [] })),
-            ...veoPrompts(artist, song, players, counts.band).map((prompt, i) => ({ prompt, file: join(keep, `shot-${i}.mp4`), into: band, refs: playerRefs })),
+            ...(this.deps.lipsync ? veoPrompts(artist, song, singers, counts.singer, "singer").map((prompt, i) => ({ prompt, file: join(keep, `singer-${i}.mp4`), into: singer, refs: singerRefs, seconds: SINGER_SECONDS })) : []),
+            ...storyFiles.map((file, i) => ({ prompt: storyPrompts[i] ?? "", file, into: story, refs: [], seconds: SHOT_SECONDS })),
+            ...veoPrompts(artist, song, players, counts.band).map((prompt, i) => ({ prompt, file: join(keep, `shot-${i}.mp4`), into: band, refs: playerRefs, seconds: SHOT_SECONDS })),
         ];
-        for (const [i, { prompt, file, into, refs }] of plan.entries()) {
+        for (const [i, { prompt, file, into, refs, seconds }] of plan.entries()) {
             try {
                 if (statSync(file).size > 10_000) {
-                    into.push({ path: file, seconds: 8 });
+                    into.push({ path: file, seconds });
                     continue;
                 }
             }
@@ -1441,7 +1464,7 @@ export class AiLabel {
                 let bytes = null;
                 for (let attempt = 0;; attempt++) {
                     try {
-                        bytes = await veo({ prompt, seconds: 8, references: refs });
+                        bytes = await veo({ prompt, seconds, references: refs });
                         break;
                     }
                     catch (error) {
@@ -1453,7 +1476,7 @@ export class AiLabel {
                 const partial = `${file}.part`;
                 writeFileSync(partial, bytes);
                 renameSync(partial, file);
-                into.push({ path: file, seconds: 8 });
+                into.push({ path: file, seconds });
             }
             catch (error) {
                 if (error instanceof VeoUnavailable) {

package/dist/main.js

@@ -10,6 +10,7 @@ import { t as uiMessage, i18n, terminalUiLanguage, uiLanguage } from "./i18n.js"
 import { USAGE as STATION_USAGE } from "./station-usage.js";
 import { LIBRARY_COMMANDS, LIBRARY_USAGE } from "./library-usage.js";
 import { MUSIC_USAGE } from "./music-cli.js";
+import { SCHOOL_USAGE } from "./school-cli.js";
 import { createApp, themes } from "@profullstack/hqtui";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
@@ -211,6 +212,7 @@ keeps serving its browser remote. One per user.
   nixamp admin    who is connected, and re-stream to them
   nixamp station  make a folder into a station others can join (see: nixamp station help)
   nixamp music    the AI label's songs as files: catalog, buy (10¢, $1, $2), what you bought (nixamp music help)
+  nixamp school   classes on backtoschool.help: teach a station live, check, prune (nixamp school help)
 
 From inside the player, d hands the music to a daemon without stopping it.
 `,
@@ -378,6 +380,8 @@ export function helpFor(topic) {
         return LIBRARY_USAGE;
     if (topic === "music")
         return MUSIC_USAGE;
+    if (topic === "school")
+        return SCHOOL_USAGE;
     return (topic ? TOPICS[topic] : undefined) ?? HELP;
 }
 /**
@@ -540,6 +544,11 @@ export async function main() {
         process.exitCode = await music(rest);
         return;
     }
+    if (first === "school" || first === "class" || first === "classes") {
+        const { school } = await import("./school-cli.js");
+        process.exitCode = await school(rest);
+        return;
+    }
     if (first === "station" || first === "stations") {
         const { station } = await import("./station-cli.js");
         process.exitCode = await station(rest);

package/dist/mcp.d.ts

@@ -37,6 +37,8 @@ export interface McpOptions {
     /** How a file is described for its record; the tests hand in a fake. */
     describe?: (path: string) => Promise<Described>;
     say?: (line: string) => void;
+    /** Where the class tools go; backtoschool.help (or NIXAMP_SCHOOL_URL) otherwise. */
+    school?: string;
 }
 /** A tool answer, in the shape MCP wants: content blocks, and a flag for failure. */
 export interface ToolResult {

package/dist/mcp.js

@@ -33,6 +33,7 @@ import { personaLines, readPersona, readVoices, writePersona } from "./profile.j
 import { STATION_TOOLS, callStationTool, isStationTool } from "./station-mcp.js";
 import { PUBLIC_TOOLS, callPublicTool, isPublicTool } from "./directory-mcp.js";
 import { LIBRARY_TOOLS, callLibraryTool, isLibraryTool } from "./library-mcp.js";
+import { SCHOOL_TOOLS, callSchoolTool, isSchoolTool } from "./school-mcp.js";
 export const PROTOCOL_VERSION = "2025-06-18";
 const STRING = { type: "string" };
 export const TOOLS = [
@@ -244,6 +245,7 @@ export const TOOLS = [
     ...STATION_TOOLS,
     ...PUBLIC_TOOLS,
     ...LIBRARY_TOOLS,
+    ...SCHOOL_TOOLS,
 ];
 function said(line) {
     return `${line.createdAt}  ${line.handle}: ${line.body}`;
@@ -302,6 +304,14 @@ export async function callTool(name, args, options = {}) {
             return failed(error.message);
         }
     }
+    // backtoschool.help classes: the same token, sent to the school's host.
+    if (isSchoolTool(name)) {
+        return callSchoolTool(name, args, {
+            ...(options.fetcher ? { fetcher: options.fetcher } : {}),
+            ...(options.session !== undefined ? { token: options.session?.token ?? null } : {}),
+            ...(options.school ? { site: options.school } : {}),
+        });
+    }
     // Stations first: on this machine they need the daemon, not a sign-in.
     if (isStationTool(name) || isLibraryTool(name)) {
         const local = { ...(options.fetcher ? { fetcher: options.fetcher } : {}), ...(options.session !== undefined ? { session: options.session } : {}), ...(options.stations ?? {}) };
@@ -612,8 +622,8 @@ export async function handleMessage(message, options = {}) {
         return reply({
             protocolVersion: PROTOCOL_VERSION,
             capabilities: { tools: { listChanged: false } },
-            serverInfo: { name: "nixamp", title: "nixamp: stations, watch parties, rooms and transcripts", version: "2" },
-            instructions: "Watch parties on nixamp: a party lives on the site hosting the film and is bridged here as a room every nixamp client can join; codes are the ones that site shows, positions are seconds into the film. Rooms: say and read trollbox lines, hear a recording. Transcripts: a file, a link or a live is written down once by nixamp.com's own ear and kept under what it is; ask for it in another language and it is translated once and kept too.",
+            serverInfo: { name: "nixamp", title: "nixamp: stations, classes, watch parties, rooms and transcripts", version: "2" },
+            instructions: "Watch parties on nixamp: a party lives on the site hosting the film and is bridged here as a room every nixamp client can join; codes are the ones that site shows, positions are seconds into the film. Rooms: say and read trollbox lines, hear a recording. Classes on backtoschool.help: classes_list and class_get for anybody; class_teach puts a station link on the air as a class in one call, classes_check finds live classes whose broadcast stopped playing. Transcripts: a file, a link or a live is written down once by nixamp.com's own ear and kept under what it is; ask for it in another language and it is translated once and kept too.",
         });
     }
     // Notifications carry no id and are answered with silence, which is what

package/dist/school-cli.d.ts

@@ -0,0 +1,2 @@
+export declare const SCHOOL_USAGE = "nixamp school: classes on backtoschool.help (sign in with `nixamp login`)\n\n  nixamp school [list] [--status live|scheduled|draft|ended] [--mine]\n  nixamp school show SLUG                 one class, and whether its broadcast plays\n  nixamp school teach LINK --title T [--description D] [--topic T] [--unlisted|--private]\n                                          make a class of a broadcast and start it now\n  nixamp school create --title T [LINK] [--starts 2026-11-01T17:00:00Z] [--description D] [--topic T]\n  nixamp school update SLUG [--title T] [--description D] [--topic T] [--link URL] [--public|--unlisted|--private]\n  nixamp school start SLUG\n  nixamp school end SLUG\n  nixamp school delete SLUG\n  nixamp school check                     your live classes, and which ones no longer play\n  nixamp school prune [--end|--delete]    end or delete the ones that no longer play (prints them without a flag)\n\nLINK is what plays: a station link (`nixamp station show ID`), a nixamp.com share link, a\nPairux room, or an https .m3u8/.mp4/.mp3. SLUG is the class's slug or its /live/ link.\n  --json   machine-readable      NIXAMP_SCHOOL_URL   another site (backtoschool.help by default)\n";
+export declare function school(argv: string[]): Promise<number>;

package/dist/school-cli.js

@@ -0,0 +1,151 @@
+/**
+ * `nixamp school`: classes on backtoschool.help from the terminal.
+ *
+ * A class is a live event on nixamp's accounts, so `nixamp login` is the
+ * sign-in here too. `teach` is the short path: a station link in, a class on
+ * the air out. `check` and `prune` exist because a class stays live after
+ * its broadcast is gone, and the page then shows a player that never plays.
+ */
+import { broadcastHealth, checkClasses, classUrl, createClass, deleteClass, getClass, listClasses, moveClass, teach, updateClass, } from "./school-client.js";
+export const SCHOOL_USAGE = `nixamp school: classes on backtoschool.help (sign in with \`nixamp login\`)
+
+  nixamp school [list] [--status live|scheduled|draft|ended] [--mine]
+  nixamp school show SLUG                 one class, and whether its broadcast plays
+  nixamp school teach LINK --title T [--description D] [--topic T] [--unlisted|--private]
+                                          make a class of a broadcast and start it now
+  nixamp school create --title T [LINK] [--starts 2026-11-01T17:00:00Z] [--description D] [--topic T]
+  nixamp school update SLUG [--title T] [--description D] [--topic T] [--link URL] [--public|--unlisted|--private]
+  nixamp school start SLUG
+  nixamp school end SLUG
+  nixamp school delete SLUG
+  nixamp school check                     your live classes, and which ones no longer play
+  nixamp school prune [--end|--delete]    end or delete the ones that no longer play (prints them without a flag)
+
+LINK is what plays: a station link (\`nixamp station show ID\`), a nixamp.com share link, a
+Pairux room, or an https .m3u8/.mp4/.mp3. SLUG is the class's slug or its /live/ link.
+  --json   machine-readable      NIXAMP_SCHOOL_URL   another site (backtoschool.help by default)
+`;
+function flag(argv, name) {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+}
+/** The first argument after the command that is not a flag or a flag's value. */
+function positional(argv) {
+    const valued = new Set(["--title", "--description", "--topic", "--starts", "--link", "--status"]);
+    for (let at = 1; at < argv.length; at += 1) {
+        const one = argv[at];
+        if (valued.has(one)) {
+            at += 1;
+            continue;
+        }
+        if (!one.startsWith("--"))
+            return one;
+    }
+    return undefined;
+}
+function fields(argv) {
+    const out = {};
+    for (const [name, key] of [["--title", "title"], ["--description", "description"], ["--topic", "topic"], ["--starts", "startsAt"], ["--link", "broadcastUrl"]]) {
+        const value = flag(argv, name);
+        if (value !== undefined)
+            out[key] = value;
+    }
+    for (const visibility of ["public", "unlisted", "private"])
+        if (argv.includes(`--${visibility}`))
+            out["visibility"] = visibility;
+    return out;
+}
+function print(item) {
+    console.log(`${item.status.padEnd(9)} ${item.title}\n          ${classUrl(item)}${item.broadcastUrl ? `\n          plays ${item.broadcastUrl}` : ""}`);
+}
+export async function school(argv) {
+    const [sub = "list"] = argv;
+    const json = argv.includes("--json");
+    const slug = positional(argv);
+    const out = (value, human) => { if (json)
+        console.log(JSON.stringify(value, null, 2));
+    else
+        human(); };
+    try {
+        if (sub === "help" || argv.includes("--help")) {
+            console.log(SCHOOL_USAGE);
+            return 0;
+        }
+        if (sub === "list") {
+            const status = flag(argv, "--status");
+            const items = await listClasses({ ...(status ? { status } : {}), mine: argv.includes("--mine") });
+            out(items, () => { if (items.length === 0)
+                console.log("No classes match."); for (const one of items)
+                print(one); });
+            return 0;
+        }
+        if (sub === "check" || sub === "prune") {
+            const checked = await checkClasses();
+            const broken = checked.filter((one) => one.health.ok === false);
+            const act = sub === "prune" ? (argv.includes("--delete") ? "delete" : argv.includes("--end") ? "end" : "") : "";
+            for (const { item } of act ? broken : []) {
+                if (act === "delete")
+                    await deleteClass(item.id);
+                else
+                    await moveClass(item.id, "end");
+            }
+            out(checked.map(({ item, health }) => ({ slug: item.slug, ok: health.ok, reason: health.reason, ...(act && health.ok === false ? { done: act } : {}) })), () => {
+                if (checked.length === 0)
+                    console.log("You have no live classes.");
+                for (const { item, health } of checked)
+                    console.log(`${health.ok === true ? "plays " : health.ok === false ? "BROKEN" : "  ?   "}  ${item.slug}  (${health.reason})`);
+                if (sub === "prune" && broken.length > 0)
+                    console.log(act ? `\n${act === "delete" ? "Deleted" : "Ended"} ${broken.length}.` : `\n${broken.length} no longer play. --end or --delete them.`);
+            });
+            return 0;
+        }
+        if (sub === "teach" || sub === "create") {
+            const input = fields(argv);
+            if (slug)
+                input["broadcastUrl"] = slug;
+            if (!input["title"]) {
+                console.error(`nixamp school ${sub} needs --title`);
+                return 2;
+            }
+            if (sub === "teach" && !input["broadcastUrl"]) {
+                console.error("nixamp school teach needs the LINK that plays");
+                return 2;
+            }
+            const item = sub === "teach" ? await teach(input) : await createClass(input);
+            out(item, () => { print(item); if (sub === "create")
+                console.log(`\nnixamp school start ${item.slug} puts it on the air.`); });
+            return 0;
+        }
+        if (!slug) {
+            console.error(`nixamp school ${sub} needs a class (its slug or /live/ link)\n\n${SCHOOL_USAGE}`);
+            return 2;
+        }
+        if (sub === "show") {
+            const item = await getClass(slug);
+            const health = await broadcastHealth(item.broadcastUrl);
+            out({ ...item, broadcast: health }, () => { print(item); console.log(`          broadcast: ${health.ok === true ? "playing" : health.ok === false ? "NOT playing" : "unknown"} (${health.reason})`); });
+            return 0;
+        }
+        if (sub === "update") {
+            const item = await updateClass(slug, fields(argv));
+            out(item, () => print(item));
+            return 0;
+        }
+        if (sub === "start" || sub === "end") {
+            const item = await moveClass(slug, sub);
+            out(item, () => print(item));
+            return 0;
+        }
+        if (sub === "delete" || sub === "rm") {
+            await deleteClass(slug);
+            out({ ok: true, slug }, () => console.log(`Deleted ${slug}.`));
+            return 0;
+        }
+        console.error(`nixamp school: no command "${sub}".\n\n${SCHOOL_USAGE}`);
+        return 2;
+    }
+    catch (error) {
+        console.error(`nixamp school: ${error.message}`);
+        return 1;
+    }
+}

package/dist/school-client.d.ts

@@ -0,0 +1,61 @@
+export declare const SCHOOL_SITE = "https://backtoschool.help";
+type Fetcher = typeof fetch;
+export interface SchoolOptions {
+    /** backtoschool.help unless NIXAMP_SCHOOL_URL says otherwise; the tests hand in a local server. */
+    site?: string;
+    /** The session on disk (or NIXAMP_TOKEN) unless given; null means signed out. */
+    token?: string | null;
+    fetcher?: Fetcher;
+}
+export interface SchoolClass {
+    id: string;
+    slug: string;
+    title: string;
+    status: string;
+    visibility: string;
+    kind: string;
+    version: number;
+    ownerId: string;
+    broadcastUrl?: string | null;
+    description?: string;
+    topic?: string;
+    hostName?: string;
+    startsAt?: string | null;
+    [key: string]: unknown;
+}
+export declare class SchoolError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export declare function schoolSite(options?: SchoolOptions): string;
+export declare function classUrl(item: Pick<SchoolClass, "slug">, options?: SchoolOptions): string;
+export declare function listClasses(query?: {
+    status?: string;
+    kind?: string;
+    mine?: boolean;
+    limit?: number;
+}, options?: SchoolOptions): Promise<SchoolClass[]>;
+/** A class by its slug, id, or the /live/<slug> link. */
+export declare function getClass(slug: string, options?: SchoolOptions): Promise<SchoolClass>;
+export declare function createClass(input: Record<string, unknown>, options?: SchoolOptions): Promise<SchoolClass>;
+export declare function updateClass(slug: string, patch: Record<string, unknown>, options?: SchoolOptions): Promise<SchoolClass>;
+/** start, end, doors, encore, cancel or archive. Each wants the version it saw, so it is read first. */
+export declare function moveClass(slug: string, action: "start" | "end" | "doors" | "encore" | "cancel" | "archive", options?: SchoolOptions): Promise<SchoolClass>;
+export declare function deleteClass(slug: string, options?: SchoolOptions): Promise<void>;
+/** Make a class of a broadcast and put it on the air in one go. */
+export declare function teach(input: Record<string, unknown>, options?: SchoolOptions): Promise<SchoolClass>;
+export interface Health {
+    ok: boolean | null;
+    reason: string;
+}
+/**
+ * Does this broadcast play? true and false are answers; null is "cannot tell
+ * from here" (a Pairux room), which a prune must leave alone.
+ */
+export declare function broadcastHealth(link: string | null | undefined, fetcher?: Fetcher, timeoutMs?: number): Promise<Health>;
+/** Your live classes, each with whether its broadcast plays. */
+export declare function checkClasses(options?: SchoolOptions, status?: string): Promise<Array<{
+    item: SchoolClass;
+    health: Health;
+}>>;
+export {};

package/dist/school-client.js

@@ -0,0 +1,148 @@
+/**
+ * backtoschool.help as a client: its classes are nixamp's live events, served
+ * by the same process on another host, so one nixamp token signs in to both.
+ *
+ * The CLI (school-cli.ts) and the MCP tools (school-mcp.ts) are both this
+ * file; neither talks HTTP itself.
+ *
+ * `broadcastHealth` is the reason this exists as much as the CRUD: a class
+ * stays "live" until somebody ends it, long after the channel it points at
+ * was stopped, and the page then shows a player that never plays. It asks the
+ * broadcast itself, with only what the public link already carries.
+ */
+import { readSession } from "./session.js";
+export const SCHOOL_SITE = "https://backtoschool.help";
+export class SchoolError extends Error {
+    status;
+    constructor(message, status = 0) {
+        super(message);
+        this.status = status;
+    }
+}
+export function schoolSite(options = {}) {
+    return (options.site ?? process.env["NIXAMP_SCHOOL_URL"] ?? SCHOOL_SITE).replace(/\/+$/, "");
+}
+export function classUrl(item, options = {}) {
+    return `${schoolSite(options)}/live/${item.slug}`;
+}
+function tokenOf(options) {
+    if (options.token !== undefined)
+        return options.token;
+    return readSession()?.token ?? null;
+}
+async function call(path, init = {}, options = {}) {
+    const token = tokenOf(options);
+    if (init.auth && !token)
+        throw new SchoolError("Not signed in. Run `nixamp login`, or set NIXAMP_TOKEN.", 401);
+    const headers = { accept: "application/json" };
+    if (token)
+        headers["authorization"] = `Bearer ${token}`;
+    if (init.body !== undefined)
+        headers["content-type"] = "application/json";
+    const response = await (options.fetcher ?? fetch)(`${schoolSite(options)}${path}`, {
+        method: init.method ?? "GET",
+        headers,
+        ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+    });
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        throw new SchoolError(String(body["error"] ?? `backtoschool.help answered ${response.status}`), response.status);
+    return body;
+}
+const eventOf = (body) => (body["event"] ?? body);
+const ref = (value) => encodeURIComponent(value.replace(/^.*\/live\//, "").replace(/[?#].*$/, ""));
+export async function listClasses(query = {}, options = {}) {
+    const params = new URLSearchParams();
+    if (query.status)
+        params.set("status", query.status);
+    if (query.kind)
+        params.set("kind", query.kind);
+    if (query.mine)
+        params.set("mine", "true");
+    params.set("limit", String(query.limit ?? 60));
+    const body = await call(`/api/v1/events?${params}`, { auth: query.mine === true }, options);
+    return body["events"] ?? [];
+}
+/** A class by its slug, id, or the /live/<slug> link. */
+export async function getClass(slug, options = {}) {
+    return eventOf(await call(`/api/v1/events/${ref(slug)}`, {}, options));
+}
+export async function createClass(input, options = {}) {
+    return eventOf(await call("/api/v1/events", { method: "POST", body: { kind: "class", visibility: "public", ...input }, auth: true }, options));
+}
+export async function updateClass(slug, patch, options = {}) {
+    const current = await getClass(slug, options);
+    return eventOf(await call(`/api/v1/events/${ref(current.id)}`, { method: "PATCH", body: { ...patch, version: current.version }, auth: true }, options));
+}
+/** start, end, doors, encore, cancel or archive. Each wants the version it saw, so it is read first. */
+export async function moveClass(slug, action, options = {}) {
+    const current = await getClass(slug, options);
+    return eventOf(await call(`/api/v1/events/${ref(current.id)}/${action}`, { method: "POST", body: { version: current.version }, auth: true }, options));
+}
+export async function deleteClass(slug, options = {}) {
+    await call(`/api/v1/events/${ref(slug)}`, { method: "DELETE", auth: true }, options);
+}
+/** Make a class of a broadcast and put it on the air in one go. */
+export async function teach(input, options = {}) {
+    const made = await createClass(input, options);
+    return moveClass(made.slug, "start", options);
+}
+/**
+ * Does this broadcast play? true and false are answers; null is "cannot tell
+ * from here" (a Pairux room), which a prune must leave alone.
+ */
+export async function broadcastHealth(link, fetcher = fetch, timeoutMs = 8000) {
+    if (!link)
+        return { ok: false, reason: "no broadcast link" };
+    let url;
+    try {
+        url = new URL(link);
+    }
+    catch {
+        return { ok: false, reason: "not a link" };
+    }
+    const get = (target, headers = {}) => fetcher(target, { headers, signal: AbortSignal.timeout(timeoutMs) });
+    try {
+        // A station page: its own token opens its state.
+        const station = /^\/station\/([a-z0-9]{10})\/?$/.exec(url.pathname)?.[1];
+        if (station && url.hostname.endsWith(".nixamp.com")) {
+            const response = await get(`${url.origin}/api/v1/stations/${station}/state?t=${encodeURIComponent(url.searchParams.get("t") ?? "")}`);
+            if (!response.ok)
+                return { ok: false, reason: `station ${station} answered ${response.status}` };
+            const state = (await response.json());
+            return state.state === "live" ? { ok: true, reason: `station ${station} is live` } : { ok: false, reason: `station ${station} is ${state.state ?? "not live"}` };
+        }
+        // nixamp.com/?url=<server>/view/<listen key>&play=channel:<id>: the listen key reads the server's channels.
+        if ((url.hostname === "nixamp.com" || url.hostname === "www.nixamp.com") && url.searchParams.get("url")) {
+            const server = new URL(url.searchParams.get("url"));
+            const key = /\/view\/([^/?#]+)/.exec(server.pathname)?.[1] ?? "";
+            const play = url.searchParams.get("play") ?? "live";
+            const response = await get(`${server.origin}/api/streams?k=${encodeURIComponent(key)}`);
+            if (!response.ok)
+                return { ok: false, reason: `${server.host} answered ${response.status}` };
+            const streams = (await response.json());
+            if (play.startsWith("channel:")) {
+                const id = play.slice("channel:".length);
+                return (streams.channels ?? []).some((one) => one.id === id)
+                    ? { ok: true, reason: `channel ${id} is on ${server.hostname}` }
+                    : { ok: false, reason: `channel ${id} is no longer on ${server.hostname}` };
+            }
+            if (play === "live")
+                return streams.server?.live ? { ok: true, reason: `${server.hostname} is live` } : { ok: false, reason: `${server.hostname} is not live` };
+            return { ok: true, reason: `${server.hostname} is up` };
+        }
+        if (url.hostname === "pairux.com" || url.hostname === "www.pairux.com")
+            return { ok: null, reason: "a Pairux room; cannot tell from here" };
+        // Direct media: one byte is enough to know it is there.
+        const response = await get(url.href, { range: "bytes=0-0" });
+        return response.ok ? { ok: true, reason: `${url.hostname} serves it` } : { ok: false, reason: `${url.hostname} answered ${response.status}` };
+    }
+    catch (error) {
+        return { ok: false, reason: `unreachable: ${error.message}` };
+    }
+}
+/** Your live classes, each with whether its broadcast plays. */
+export async function checkClasses(options = {}, status = "live") {
+    const items = await listClasses({ mine: true, status }, options);
+    return Promise.all(items.map(async (item) => ({ item, health: await broadcastHealth(item.broadcastUrl, options.fetcher ?? fetch) })));
+}