nixamp 0.30.3 → 0.33.0

package/dist/library-usage.js

@@ -0,0 +1,20 @@
+/** `nixamp library` subcommands and usage, apart so help does not load the client. */
+export const LIBRARY_COMMANDS = new Set(["status", "sources", "add", "scan", "search", "show", "fix", "remove", "playlists", "playlist"]);
+export const LIBRARY_USAGE = `nixamp library — what this server has, indexed
+
+  nixamp library PATH                 the folder the daemon serves (set once)
+  nixamp library status               items by state, sources, last scans
+  nixamp library sources
+  nixamp library add PATH             index another folder (inside your home, not hidden)
+  nixamp library scan [SOURCE] [--force] [--wait]
+  nixamp library search WORDS [--artist A] [--album A] [--state failed] [--limit 20]
+  nixamp library show ITEM
+  nixamp library fix ITEM --title T [--artist A] [--album A] [--genre G] [--track N] [--year N]
+  nixamp library remove SOURCE        forget a folder; its files are not touched
+  nixamp library playlists
+  nixamp library playlist new NAME [ITEM...]
+  nixamp library playlist show|delete PLAYLIST
+  nixamp library playlist add PLAYLIST ITEM...
+
+  --json        machine-readable output
+  --url, --key  another server, as with \`nixamp admin\``;

package/dist/library-user.d.ts

@@ -0,0 +1,67 @@
+export interface Playlist {
+    id: string;
+    owner: string;
+    name: string;
+    items: string[];
+    revision: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export type Repeat = "off" | "all" | "one";
+export interface Queue {
+    owner: string;
+    items: string[];
+    /** Index into items of what is on. */
+    at: number;
+    /** Seconds into it. */
+    position: number;
+    shuffle: boolean;
+    repeat: Repeat;
+    /** Which device moved it last, as it named itself. */
+    device: string;
+    revision: number;
+    updatedAt: number;
+}
+export declare class ListenerStore {
+    private readonly file;
+    private readonly io;
+    private readonly now;
+    private playlists;
+    private queues;
+    private timer;
+    constructor(file: string, io?: {
+        read: (path: string) => string | null;
+        write: (path: string, body: string) => void;
+    }, now?: () => number);
+    static fileFor(stateDir: string, port: number): string;
+    private touch;
+    flush(): void;
+    playlistsOf(owner: string): Playlist[];
+    /** Somebody's own playlist; anybody else's is the same "not found". */
+    playlist(owner: string, id: string): Playlist;
+    private items;
+    private name;
+    create(owner: string, input: {
+        name?: unknown;
+        items?: unknown;
+    }, known: (id: string) => boolean): Playlist;
+    /** Rename, reorder or replace the items; `revision` must be the one the caller saw. */
+    update(owner: string, id: string, input: {
+        name?: unknown;
+        items?: unknown;
+        revision?: unknown;
+    }, known: (id: string) => boolean): Playlist;
+    /** Items added, at the end or at a place. */
+    add(owner: string, id: string, input: {
+        items?: unknown;
+        at?: unknown;
+    }, known: (id: string) => boolean): Playlist;
+    remove(owner: string, id: string): void;
+    queueOf(owner: string): Queue;
+    /**
+     * A new queue (items given) or where playback has got to (at/position).
+     * Last writer wins for where you are -- that is what moving to another
+     * device means -- but a whole new list names the revision it replaces.
+     */
+    setQueue(owner: string, input: Record<string, unknown>, known: (id: string) => boolean): Queue;
+}

package/dist/library-user.js

@@ -0,0 +1,204 @@
+/**
+ * What belongs to one listener of a library: their playlists, and where
+ * they are in what they were playing.
+ *
+ * A listener here is somebody this server can recognise next time from
+ * another device: a nixamp.com account, or the owner holding the control key
+ * (who is "owner"). Somebody with only the listen link is not anybody in
+ * particular, so they get a player and no memory, which is what the PRD means
+ * by resuming "after authentication".
+ *
+ * Playlists hold item ids, not paths: a playlist survives a rescan, and an
+ * item that went missing stays in it, shown as unavailable, until somebody
+ * takes it out. Every change bumps a revision; an edit that names an older
+ * revision is refused rather than quietly overwriting what another device
+ * just did.
+ *
+ * The queue is one per listener, written whenever playback moves on, so a
+ * phone picks up where the laptop stopped.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { LibraryError } from "./library-index.js";
+const MAX_PLAYLISTS = 500;
+const MAX_ITEMS = 10_000;
+export class ListenerStore {
+    file;
+    io;
+    now;
+    playlists = new Map();
+    queues = new Map();
+    timer = null;
+    constructor(file, io = {
+        read: (path) => { try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return null;
+        } },
+        write: (path, body) => {
+            mkdirSync(dirname(path), { recursive: true });
+            const temporary = `${path}.${process.pid}.tmp`;
+            writeFileSync(temporary, body, { mode: 0o600 });
+            renameSync(temporary, path);
+        },
+    }, now = Date.now) {
+        this.file = file;
+        this.io = io;
+        this.now = now;
+        const body = io.read(file);
+        if (body === null)
+            return;
+        try {
+            const parsed = JSON.parse(body);
+            for (const one of parsed.playlists ?? [])
+                if (one?.id)
+                    this.playlists.set(one.id, one);
+            for (const one of parsed.queues ?? [])
+                if (one?.owner)
+                    this.queues.set(one.owner, one);
+        }
+        catch {
+            // Started over.
+        }
+    }
+    static fileFor(stateDir, port) {
+        return join(stateDir, `listeners-${port}.json`);
+    }
+    touch() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => this.flush(), 1_000);
+        this.timer.unref?.();
+    }
+    flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.io.write(this.file, JSON.stringify({ version: 1, playlists: [...this.playlists.values()], queues: [...this.queues.values()] }));
+    }
+    playlistsOf(owner) {
+        return [...this.playlists.values()].filter((one) => one.owner === owner).sort((a, b) => a.createdAt - b.createdAt);
+    }
+    /** Somebody's own playlist; anybody else's is the same "not found". */
+    playlist(owner, id) {
+        const found = this.playlists.get(id);
+        if (!found || found.owner !== owner)
+            throw new LibraryError("not_found", "no such playlist", 404);
+        return found;
+    }
+    items(value, known) {
+        if (!Array.isArray(value) || value.some((one) => typeof one !== "string"))
+            throw new LibraryError("invalid_items", "items is a list of item ids");
+        if (value.length > MAX_ITEMS)
+            throw new LibraryError("too_many_items", `a list holds at most ${MAX_ITEMS} items`);
+        const unknown = value.filter((one) => !known(one));
+        if (unknown.length)
+            throw new LibraryError("unknown_items", `${unknown.length} of those items are not in this library`);
+        return value;
+    }
+    name(value) {
+        const name = typeof value === "string" ? value.trim().replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, 120) : "";
+        if (!name)
+            throw new LibraryError("name_required", "a playlist needs a name");
+        return name;
+    }
+    create(owner, input, known) {
+        if (this.playlistsOf(owner).length >= MAX_PLAYLISTS)
+            throw new LibraryError("too_many_playlists", `at most ${MAX_PLAYLISTS} playlists each`, 409);
+        const now = this.now();
+        const playlist = {
+            id: randomBytes(8).toString("hex"),
+            owner,
+            name: this.name(input.name),
+            items: input.items === undefined ? [] : this.items(input.items, known),
+            revision: 1,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.playlists.set(playlist.id, playlist);
+        this.touch();
+        return playlist;
+    }
+    /** Rename, reorder or replace the items; `revision` must be the one the caller saw. */
+    update(owner, id, input, known) {
+        const playlist = this.playlist(owner, id);
+        if (input.revision !== undefined && input.revision !== playlist.revision) {
+            throw new LibraryError("stale_revision", `the playlist changed (revision ${playlist.revision}); fetch it and try again`, 409);
+        }
+        if (input.name !== undefined)
+            playlist.name = this.name(input.name);
+        if (input.items !== undefined)
+            playlist.items = this.items(input.items, known);
+        playlist.revision += 1;
+        playlist.updatedAt = this.now();
+        this.touch();
+        return playlist;
+    }
+    /** Items added, at the end or at a place. */
+    add(owner, id, input, known) {
+        const playlist = this.playlist(owner, id);
+        const added = this.items(input.items, known);
+        const at = typeof input.at === "number" && Number.isInteger(input.at) ? Math.max(0, Math.min(playlist.items.length, input.at)) : playlist.items.length;
+        if (playlist.items.length + added.length > MAX_ITEMS)
+            throw new LibraryError("too_many_items", `a list holds at most ${MAX_ITEMS} items`);
+        playlist.items.splice(at, 0, ...added);
+        playlist.revision += 1;
+        playlist.updatedAt = this.now();
+        this.touch();
+        return playlist;
+    }
+    remove(owner, id) {
+        this.playlist(owner, id);
+        this.playlists.delete(id);
+        this.touch();
+    }
+    queueOf(owner) {
+        return this.queues.get(owner) ?? { owner, items: [], at: 0, position: 0, shuffle: false, repeat: "off", device: "", revision: 0, updatedAt: 0 };
+    }
+    /**
+     * A new queue (items given) or where playback has got to (at/position).
+     * Last writer wins for where you are -- that is what moving to another
+     * device means -- but a whole new list names the revision it replaces.
+     */
+    setQueue(owner, input, known) {
+        const queue = { ...this.queueOf(owner) };
+        if (input["items"] !== undefined) {
+            if (input["revision"] !== undefined && input["revision"] !== queue.revision) {
+                throw new LibraryError("stale_revision", `the queue changed on another device (revision ${queue.revision})`, 409);
+            }
+            queue.items = this.items(input["items"], known);
+            queue.at = 0;
+            queue.position = 0;
+        }
+        if (input["at"] !== undefined) {
+            if (!Number.isInteger(input["at"]) || input["at"] < 0 || input["at"] >= Math.max(1, queue.items.length)) {
+                throw new LibraryError("invalid_value", "at is a place in the queue");
+            }
+            queue.at = input["at"];
+            if (input["position"] === undefined)
+                queue.position = 0;
+        }
+        if (input["position"] !== undefined) {
+            const position = Number(input["position"]);
+            if (!Number.isFinite(position) || position < 0)
+                throw new LibraryError("invalid_value", "position is seconds into the item");
+            queue.position = Math.round(position * 10) / 10;
+        }
+        if (input["shuffle"] !== undefined)
+            queue.shuffle = input["shuffle"] === true;
+        if (input["repeat"] !== undefined) {
+            if (!["off", "all", "one"].includes(String(input["repeat"])))
+                throw new LibraryError("invalid_value", "repeat is off, all or one");
+            queue.repeat = input["repeat"];
+        }
+        if (typeof input["device"] === "string")
+            queue.device = input["device"].slice(0, 80);
+        queue.revision += 1;
+        queue.updatedAt = this.now();
+        this.queues.set(owner, queue);
+        this.touch();
+        return queue;
+    }
+}

package/dist/main.js

@@ -8,6 +8,7 @@ import { t as uiMessage, i18n, terminalUiLanguage, uiLanguage } from "./i18n.js"
  * ffmpeg decodes; we read every sample on its way to the speakers and draw it.
  */
 import { USAGE as STATION_USAGE } from "./station-usage.js";
+import { LIBRARY_COMMANDS, LIBRARY_USAGE } from "./library-usage.js";
 import { createApp, themes } from "@profullstack/hqtui";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
@@ -371,6 +372,8 @@ q or d leaves; neither stops anything. \`nixamp daemon stop\` is what stops it.
 export function helpFor(topic) {
     if (topic === "station" || topic === "stations")
         return STATION_USAGE;
+    if (topic === "library")
+        return LIBRARY_USAGE;
     return (topic ? TOPICS[topic] : undefined) ?? HELP;
 }
 /**
@@ -621,6 +624,11 @@ export async function main() {
         process.exitCode = await syncCommand(rest);
         return;
     }
+    if (first === "library" && LIBRARY_COMMANDS.has(rest[0] ?? "")) {
+        const { libraryTool } = await import("./library-cli.js");
+        process.exitCode = await libraryTool(rest);
+        return;
+    }
     if (first === "library") {
         const { libraryCommand } = await import("./library.js");
         process.exitCode = await libraryCommand(rest);

package/dist/mcp.js

@@ -31,6 +31,7 @@ import { describeFile, keepFile } from "./media-local.js";
 import { fileFingerprint, idFrom, languageCode, mediaOfUrl, transcriptIdOf } from "./transcripts.js";
 import { personaLines, readPersona, readVoices, writePersona } from "./profile.js";
 import { STATION_TOOLS, callStationTool, isStationTool } from "./station-mcp.js";
+import { LIBRARY_TOOLS, callLibraryTool, isLibraryTool } from "./library-mcp.js";
 export const PROTOCOL_VERSION = "2025-06-18";
 const STRING = { type: "string" };
 export const TOOLS = [
@@ -217,6 +218,7 @@ export const TOOLS = [
         },
     },
     ...STATION_TOOLS,
+    ...LIBRARY_TOOLS,
 ];
 function said(line) {
     return `${line.createdAt}  ${line.handle}: ${line.body}`;
@@ -249,8 +251,9 @@ function describe(row) {
  */
 export async function callTool(name, args, options = {}) {
     // Stations first: on this machine they need the daemon, not a sign-in.
-    if (isStationTool(name)) {
-        return callStationTool(name, args, { ...(options.fetcher ? { fetcher: options.fetcher } : {}), ...(options.session !== undefined ? { session: options.session } : {}), ...(options.stations ?? {}) });
+    if (isStationTool(name) || isLibraryTool(name)) {
+        const local = { ...(options.fetcher ? { fetcher: options.fetcher } : {}), ...(options.session !== undefined ? { session: options.session } : {}), ...(options.stations ?? {}) };
+        return isStationTool(name) ? callStationTool(name, args, local) : callLibraryTool(name, args, local);
     }
     const session = options.session === undefined ? readSession() : options.session;
     if (!session) {

package/dist/server.d.ts

@@ -21,6 +21,8 @@ import { Directory, type LineupEntry } from "./directory.ts";
 import { ArtCache } from "./art.ts";
 import { PartyLine } from "./partyline.ts";
 import { HlsPackagers } from "./hls.ts";
+import { LibraryIndex, type Probed } from "./library-index.ts";
+import { ListenerStore } from "./library-user.ts";
 import { StationRunner } from "./station-runner.ts";
 import { StationStore } from "./stations.ts";
 import { CompressionService } from "./compression/service.ts";
@@ -566,6 +568,13 @@ export declare function joinSubject(url: URL, options: Pick<HandlerOptions, "dir
 /** The shell, titled for what a join link opens, with its picture on the card. */
 export declare function joinDocument(shell: string, subject: JoinSubject, site: string): string;
 export interface HandlerOptions {
+    /** The library as an index: sources, items, search. */
+    library?: {
+        index: LibraryIndex;
+        probe: (path: string) => Promise<Probed>;
+        retag: (tracks: Track[]) => void;
+        listeners?: ListenerStore;
+    };
     /** This server's stations and what keeps them on the air. */
     stations?: {
         store: StationStore;

package/dist/server.js

@@ -55,6 +55,9 @@ import { PartyLine, telnyxSms } from "./partyline.js";
 import { HlsPackagers, segmentType, withKey } from "./hls.js";
 import { refusedDestination } from "./destinations.js";
 import { handleStations, isStationListenPath } from "./station-routes.js";
+import { handleLibrary } from "./library-routes.js";
+import { LibraryIndex, probeItem, trackOf } from "./library-index.js";
+import { ListenerStore } from "./library-user.js";
 import { STATION_PAGE, STATION_PAGE_CSP, STATION_PAGE_HTML } from "./station-page.js";
 import { StationRunner } from "./station-runner.js";
 import { StationError, StationStore, stationOfChannel } from "./stations.js";
@@ -2201,6 +2204,29 @@ export function createHandler(engine, options) {
             response.end(request.method === "HEAD" ? undefined : STATION_PAGE_HTML);
             return;
         }
+        // Past the key gate is past it: the owner, or somebody given the listen
+        // link, may read the library; only the owner may change it.
+        if (options.library && (path === "/api/v1/library" || path.startsWith("/api/v1/library/"))) {
+            const control = await controlOf();
+            // Who this is: the owner's account, "owner" for the control key, or
+            // any other signed-in nixamp.com account that has the link.
+            const session = tokenFrom(request.headers) || url.searchParams.get("session") || "";
+            const principal = control.account || (control.allowed ? "owner" : (session && options.owner ? (await options.owner.accountFor(session)) || null : null));
+            await handleLibrary(request, response, path, url, {
+                index: options.library.index,
+                canRead: true,
+                canWrite: control.allowed,
+                account: control.account,
+                principal,
+                ...(options.library.listeners ? { listeners: options.library.listeners } : {}),
+                probe: options.library.probe,
+                retag: options.library.retag,
+                sendFile,
+                json,
+                readBody,
+            });
+            return;
+        }
         if (options.stations && (path === "/api/v1/stations" || path.startsWith("/api/v1/stations/"))) {
             const control = await controlOf();
             const encrypted = request.socket.encrypted === true;
@@ -2212,7 +2238,24 @@ export function createHandler(engine, options) {
                 channels: options.channels,
                 canControl: control.allowed,
                 account: control.account,
-                select: (body) => selectStationFiles(engine, body),
+                select: (body) => {
+                    // A playlist of the owner's, as the station's files: its ready items, in its order.
+                    if (typeof body.playlist === "string" && options.library?.listeners) {
+                        const owner = control.account || "owner";
+                        let list;
+                        try {
+                            list = options.library.listeners.playlist(owner, body.playlist);
+                        }
+                        catch (error) {
+                            throw new StationError("playlist_not_found", error.message, 404);
+                        }
+                        const files = list.items.map((id) => options.library.index.item(id)).filter((one) => one?.state === "ready").map((one) => one.path);
+                        if (files.length === 0)
+                            throw new StationError("empty_playlist", "none of that playlist's items are ready to play");
+                        return files;
+                    }
+                    return selectStationFiles(engine, body);
+                },
                 trackFor: (file) => trackFor(engine, file),
                 base: `${scheme}://${request.headers.host ?? "localhost"}`,
                 json,
@@ -5547,7 +5590,10 @@ export function createHandler(engine, options) {
                 return;
             }
             let file = null;
-            if (isFile(direct))
+            // The library and radio console is a page of its own, at its own names.
+            if (/^\/(radio|library)\/?$/.test(path) && isFile(join(web, "radio.html")))
+                file = join(web, "radio.html");
+            else if (isFile(direct))
                 file = direct;
             else if (isFile(join(direct, "index.html")))
                 file = join(direct, "index.html");
@@ -5910,7 +5956,7 @@ function isFile(path) {
         return false;
     }
 }
-function sendFile(request, response, file) {
+function sendFile(request, response, file, cache) {
     let size;
     try {
         size = statSync(file).size;
@@ -5928,7 +5974,7 @@ function sendFile(request, response, file) {
     };
     // The shell must never be cached by a service worker's fetch fallback, but
     // hashed assets and audio can be.
-    headers["cache-control"] = type.startsWith("text/html") ? "no-cache" : "public, max-age=3600";
+    headers["cache-control"] = cache ?? (type.startsWith("text/html") ? "no-cache" : "public, max-age=3600");
     if (range) {
         headers["content-range"] = `bytes ${range.start}-${range.end}/${size}`;
         headers["content-length"] = String(range.end - range.start + 1);
@@ -6067,6 +6113,25 @@ export async function serve(argv, version = "0.1.0") {
             stationRunner?.onChannelEnd(info);
         },
     });
+    // The library as an index kept beside the keys: what each file is, learned
+    // once and asked about again only when it changes. The folder this server
+    // was started on is its first source.
+    const libraryIndex = new LibraryIndex(LibraryIndex.fileFor(stateDir(), options.port));
+    const homeSource = (() => {
+        try {
+            return !isRemote(root) && statSync(root).isDirectory() ? libraryIndex.ensureSource(root, options.owner || "") : null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    const probeFile = (path) => probeItem(tools, path);
+    const retagPlayer = (tracks) => {
+        if (tracks.length > 0)
+            engine.retag(tracks, root);
+    };
+    const listeners = new ListenerStore(ListenerStore.fileFor(stateDir(), options.port));
+    const library = { index: libraryIndex, probe: probeFile, retag: retagPlayer, listeners };
     const stationStore = new StationStore(StationStore.fileFor(stateDir(), options.port));
     stationRunner = new StationRunner({
         store: stationStore,
@@ -6078,7 +6143,7 @@ export async function serve(argv, version = "0.1.0") {
             audioBitrate: known.audioBitrate,
         })),
         // The library as it is now, or as it was chosen while it is still being read.
-        roots: () => [engine.snapshot(false).root || chosen].filter((one) => one !== ""),
+        roots: () => [...new Set([engine.snapshot(false).root || chosen, ...libraryIndex.roots()])].filter((one) => one !== ""),
         log: (line) => console.log(line),
     });
     const stations = { store: stationStore, runner: stationRunner };
@@ -6661,6 +6726,7 @@ export async function serve(argv, version = "0.1.0") {
         owner,
         channels,
         stations,
+        library,
         rememberChannels: remembering,
         catalogs,
         publishUrls: () => publishUrls,
@@ -6939,14 +7005,22 @@ export async function serve(argv, version = "0.1.0") {
         console.log(`nixamp serve — ${found.length} tracks under ${root}`);
         if (isRemote(root))
             return;
-        // Handed the files we already found. Tagging used to walk the whole
-        // library a second time to discover the same paths, and that second walk
-        // was the one that ran with the port already open.
-        return loadTagged(tools, root, probeAsync, found.map((track) => track.path))
-            .then((tagged) => engine.retag(tagged, root))
-            .catch(() => {
-            // Filenames are a working player. A failure here is worth nothing
-            // but titles that stay as they are.
+        if (!homeSource) {
+            // A playlist file or a single file: tagged as it always was.
+            return loadTagged(tools, root, probeAsync, found.map((track) => track.path))
+                .then((tagged) => engine.retag(tagged, root))
+                .catch(() => undefined);
+        }
+        // What is already known, at once: a restart has its tags before the
+        // first listener arrives. Then only new and changed files are asked
+        // about, and their tags reach the player a couple of hundred at a time
+        // rather than all at the end.
+        retagPlayer(libraryIndex.tracksFor(found.map((track) => track.path)));
+        const { done } = libraryIndex.scan(homeSource.id, probeFile, {
+            onProgress: (changed) => retagPlayer(changed.filter((one) => one.state === "ready").map(trackOf)),
+        });
+        return done.then((report) => {
+            console.log(`nixamp serve — library: ${report.unchanged} unchanged, ${report.probed} read${report.failed ? `, ${report.failed} would not read` : ""}${report.missing ? `, ${report.missing} gone` : ""}${report.outside ? `, ${report.outside} links outside left out` : ""}.`);
         });
     })
         .catch((error) => {

package/dist/station-cli.js

@@ -115,14 +115,15 @@ export async function station(argv) {
                     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");
+                const playlist = flag(argv, "--playlist");
+                if (items === undefined && folder === undefined && playlist === undefined) {
+                    console.error("nixamp station create needs --folder PATH, --playlist ID 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 }),
+                    ...(playlist !== undefined ? { playlist } : items !== undefined ? { items: items.split(",").map((one) => Number(one.trim())) } : { folder }),
                     shuffle: has(argv, "--shuffle"),
                     repeat: !has(argv, "--no-repeat"),
                     ...(bitrate ? { bitrate: Number(bitrate) } : {}),

package/dist/station-mcp.d.ts

@@ -8,6 +8,7 @@ export declare const STATION_TOOLS: ({
                 type: "string";
                 description: string;
             };
+            playlist?: undefined;
             idempotencyKey?: undefined;
             name?: undefined;
             description?: undefined;
@@ -40,6 +41,7 @@ export declare const STATION_TOOLS: ({
                 type: "string";
                 description: string;
             };
+            playlist?: undefined;
             idempotencyKey?: undefined;
             name?: undefined;
             description?: undefined;
@@ -81,6 +83,10 @@ export declare const STATION_TOOLS: ({
                 };
                 description: string;
             };
+            playlist: {
+                type: "string";
+                description: string;
+            };
             description: {
                 readonly type: "string";
             };
@@ -115,6 +121,7 @@ export declare const STATION_TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            playlist?: undefined;
             idempotencyKey?: undefined;
             server: {
                 type: "string";
@@ -166,6 +173,7 @@ export declare const STATION_TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            playlist?: undefined;
             idempotencyKey?: undefined;
             name?: undefined;
             description?: undefined;
@@ -200,6 +208,7 @@ export declare const STATION_TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            playlist?: undefined;
             idempotencyKey?: undefined;
             name?: undefined;
             description?: undefined;
@@ -242,6 +251,7 @@ export declare const STATION_TOOLS: ({
     inputSchema: {
         type: string;
         properties: {
+            playlist?: undefined;
             idempotencyKey?: undefined;
             name?: undefined;
             description?: undefined;
@@ -289,6 +299,13 @@ export interface StationToolOptions {
         token: string;
     } | null;
 }
+/** Where to send a tool's request, and with which credential. */
+export declare function connect(args: Record<string, unknown>, options: StationToolOptions): {
+    base: string;
+    headers: Record<string, string>;
+} | {
+    error: string;
+};
 export declare function isStationTool(name: string): boolean;
 export declare function callStationTool(name: string, args: Record<string, unknown>, options?: StationToolOptions): Promise<Result>;
 export {};