nixamp 0.36.4 → 0.37.0

package/dist/ai-routes.js

@@ -0,0 +1,191 @@
+import { AI_KEY_NAMES, aiKeysSet, saveAiKey } from "./ai-keys.js";
+import { SHARE_BASES, SHARE_GENRES, ownerShareView, sharerView } from "./listener-shares.js";
+import { StationError } from "./stations.js";
+const PUBLIC = /^\/api\/v1\/share(?:\/(upload|report|[a-f0-9]{12}))?$/;
+/** Whether this path is one anybody may use without the server's key. */
+export function isPublicSharePath(path) {
+    return PUBLIC.test(path);
+}
+async function jsonBody(ctx, request) {
+    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;
+}
+/** Answers the paths above; false when the path is not one of them. */
+export async function handleAiRoutes(request, response, path, url, ctx) {
+    const method = request.method ?? "GET";
+    const publicPath = PUBLIC.exec(path);
+    const ownerPath = path === "/api/v1/stations/ai" || path.startsWith("/api/v1/stations/ai/") || path === "/api/v1/stations/shares" || path.startsWith("/api/v1/stations/shares/");
+    if (!publicPath && !ownerPath)
+        return false;
+    try {
+        if (publicPath) {
+            const shares = ctx.shares;
+            if (!shares) {
+                ctx.json(response, 404, { error: "this server does not take shared tracks", code: "not_found" });
+                return true;
+            }
+            const what = publicPath[1];
+            if (what === undefined && method === "GET") {
+                const setting = shares.setting();
+                ctx.json(response, 200, { open: setting.open, bases: SHARE_BASES, genres: SHARE_GENRES, maxMb: Math.round(setting.maxBytes / 1048576), perHour: setting.perHour });
+                return true;
+            }
+            if (method !== "GET" && method !== "DELETE" && ctx.throttle) {
+                const wait = ctx.throttle();
+                if (wait) {
+                    response.setHeader("retry-after", String(wait.retryAfter));
+                    ctx.json(response, 429, { error: "too many at once; wait a moment", code: "rate_limited", retryAfter: wait.retryAfter });
+                    return true;
+                }
+            }
+            if (what === undefined && method === "POST") {
+                const share = shares.fromUrl(await jsonBody(ctx, request), ctx.caller);
+                ctx.json(response, 202, { share: sharerView(share), token: share.token, status: `/api/v1/share/${share.id}?t=${share.token}` });
+                return true;
+            }
+            if (what === "upload" && (method === "PUT" || method === "POST")) {
+                const input = Object.fromEntries(url.searchParams.entries());
+                const share = await shares.fromUpload(request, input, ctx.caller);
+                ctx.json(response, 202, { share: sharerView(share), token: share.token, status: `/api/v1/share/${share.id}?t=${share.token}` });
+                return true;
+            }
+            if (what === "report" && method === "POST") {
+                const input = await jsonBody(ctx, request);
+                ctx.json(response, 200, shares.report(input, ctx.caller));
+                return true;
+            }
+            if (what && /^[a-f0-9]{12}$/.test(what) && (method === "GET" || method === "DELETE")) {
+                const share = shares.forSharer(what, url.searchParams.get("t") ?? "");
+                if (!share) {
+                    ctx.json(response, 404, { error: "no such share, or not with that link", code: "not_found" });
+                    return true;
+                }
+                ctx.json(response, 200, { share: sharerView(method === "DELETE" ? shares.withdraw(share) : share) });
+                return true;
+            }
+            ctx.json(response, 405, { error: "not like that", code: "method_not_allowed" });
+            return true;
+        }
+        if (!ctx.canControl) {
+            ctx.json(response, 403, { error: "only this server's owner manages AI radio and shares", code: "forbidden" });
+            return true;
+        }
+        if (path === "/api/v1/stations/shares" || path.startsWith("/api/v1/stations/shares/")) {
+            const shares = ctx.shares;
+            if (!shares) {
+                ctx.json(response, 404, { error: "shares are not available here", code: "not_found" });
+                return true;
+            }
+            if (path === "/api/v1/stations/shares") {
+                if (method === "GET") {
+                    const list = shares.list(url.searchParams.get("state") ?? undefined);
+                    ctx.json(response, 200, { setting: shares.setting(), total: list.length, shares: list.slice(0, 200).map(ownerShareView) });
+                    return true;
+                }
+                if (method === "POST") {
+                    ctx.json(response, 200, { setting: shares.configure(await jsonBody(ctx, request)) });
+                    return true;
+                }
+            }
+            const match = /^\/api\/v1\/stations\/shares\/([a-f0-9]{12})(?:\/(approve|reject))?$/.exec(path);
+            if (match) {
+                const [, id, decision] = match;
+                if (!decision && method === "GET") {
+                    const share = shares.get(id);
+                    if (!share)
+                        throw new StationError("not_found", "no such share", 404);
+                    ctx.json(response, 200, { share: ownerShareView(share) });
+                    return true;
+                }
+                if (!decision && method === "DELETE") {
+                    shares.decide(id, "delete");
+                    ctx.json(response, 200, { deleted: id });
+                    return true;
+                }
+                if (decision && method === "POST") {
+                    const input = await jsonBody(ctx, request);
+                    const share = shares.decide(id, decision, typeof input["reason"] === "string" ? input["reason"].slice(0, 300) : "");
+                    ctx.json(response, 200, { share: share ? ownerShareView(share) : null });
+                    return true;
+                }
+            }
+            ctx.json(response, 404, { error: "no such share route", code: "not_found" });
+            return true;
+        }
+        const ai = ctx.ai;
+        if (!ai) {
+            ctx.json(response, 404, { error: "AI radio is not available here", code: "not_found" });
+            return true;
+        }
+        if (path === "/api/v1/stations/ai") {
+            if (method === "GET") {
+                ctx.json(response, 200, { ...ai.status(), keys: aiKeysSet() });
+                return true;
+            }
+            if (method === "POST") {
+                ctx.json(response, 200, { settings: ai.configure(await jsonBody(ctx, request)) });
+                return true;
+            }
+        }
+        if (path === "/api/v1/stations/ai/keys" && method === "POST") {
+            const input = await jsonBody(ctx, request);
+            const name = String(input["name"] ?? "");
+            if (!AI_KEY_NAMES.includes(name))
+                throw new StationError("unknown_key", `keys: ${AI_KEY_NAMES.join(", ")}`);
+            saveAiKey(name, typeof input["value"] === "string" ? input["value"] : "");
+            ctx.json(response, 200, { keys: aiKeysSet() });
+            return true;
+        }
+        if (path === "/api/v1/stations/ai/stations" && method === "POST") {
+            ctx.json(response, 201, { station: ai.create(await jsonBody(ctx, request)) });
+            return true;
+        }
+        const match = /^\/api\/v1\/stations\/ai\/stations\/([a-f0-9]{10})(?:\/(generate))?$/.exec(path);
+        if (match) {
+            const [, key, action] = match;
+            if (!action && method === "GET") {
+                const station = ai.get(key);
+                if (!station)
+                    throw new StationError("not_found", "no such AI station", 404);
+                ctx.json(response, 200, { station });
+                return true;
+            }
+            if (!action && method === "PATCH") {
+                ctx.json(response, 200, { station: ai.update(key, await jsonBody(ctx, request)) });
+                return true;
+            }
+            if (!action && method === "DELETE") {
+                ai.remove(key, url.searchParams.get("files") === "1");
+                ctx.json(response, 200, { deleted: key });
+                return true;
+            }
+            if (action === "generate" && method === "POST") {
+                // Composing takes a minute or two; answer when it is on the station.
+                ctx.json(response, 200, { track: await ai.generate(key) });
+                return true;
+            }
+        }
+        ctx.json(response, 404, { error: "no such AI radio route", code: "not_found" });
+        return true;
+    }
+    catch (error) {
+        if (error instanceof StationError) {
+            ctx.json(response, error.status, { error: error.message, code: error.code });
+        }
+        else {
+            ctx.json(response, 500, { error: error instanceof Error ? error.message : String(error), code: "internal" });
+        }
+        return true;
+    }
+}

package/dist/ai-text.d.ts

@@ -0,0 +1,23 @@
+export interface AskOptions {
+    /** What the model is for, said once. */
+    system: string;
+    /** The question, with what it should answer from. */
+    prompt: string;
+    /** Milliseconds before giving up (default 30 s). */
+    timeoutMs?: number;
+    fetcher?: typeof fetch;
+    env?: Record<string, string | undefined>;
+}
+export interface Answer {
+    /** Which model answered, for the record ("gemini-flash-latest", ...). */
+    model: string;
+    value: Record<string, unknown>;
+}
+export declare class NoModel extends Error {
+    constructor();
+}
+/** The first JSON object in a model's answer. */
+export declare function firstObject(text: string): Record<string, unknown>;
+/** Whether any model can be asked. */
+export declare function hasModel(env?: Record<string, string | undefined>): boolean;
+export declare function askJson(options: AskOptions): Promise<Answer>;

package/dist/ai-text.js

@@ -0,0 +1,102 @@
+/**
+ * One question to a language model, one JSON answer.
+ *
+ * AI radio asks for small things: a title and a prompt for the next track, a
+ * genre and a verdict for a shared file. Whichever model has a key answers --
+ * Gemini, then OpenAI, then Anthropic -- and when none has, the caller is told
+ * so and does without (a rule of its own, or a person). The answer is parsed
+ * and handed back as an object; a model that rambles round its JSON is read
+ * for the first object in what it said.
+ */
+import { aiKey } from "./ai-keys.js";
+export class NoModel extends Error {
+    constructor() {
+        super("no language model key is set (GEMINI_API_KEY, OPENAI_API_KEY or ANTHROPIC_API_KEY)");
+    }
+}
+/** The first JSON object in a model's answer. */
+export function firstObject(text) {
+    const cleaned = text.replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/, "");
+    try {
+        const parsed = JSON.parse(cleaned);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        // Look inside it instead.
+    }
+    const start = cleaned.indexOf("{");
+    const end = cleaned.lastIndexOf("}");
+    if (start !== -1 && end > start) {
+        const parsed = JSON.parse(cleaned.slice(start, end + 1));
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed))
+            return parsed;
+    }
+    throw new Error("the model did not answer with a JSON object");
+}
+/** Whether any model can be asked. */
+export function hasModel(env = process.env) {
+    return Boolean(aiKey("GEMINI_API_KEY", env) || aiKey("OPENAI_API_KEY", env) || aiKey("ANTHROPIC_API_KEY", env));
+}
+export async function askJson(options) {
+    const env = options.env ?? process.env;
+    const send = options.fetcher ?? fetch;
+    const signal = AbortSignal.timeout(options.timeoutMs ?? 30_000);
+    const gemini = aiKey("GEMINI_API_KEY", env);
+    const openai = aiKey("OPENAI_API_KEY", env);
+    const anthropic = aiKey("ANTHROPIC_API_KEY", env);
+    if (gemini) {
+        const model = env["NIXAMP_GEMINI_MODEL"] || "gemini-flash-latest";
+        const response = await send(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`, {
+            method: "POST",
+            signal,
+            headers: { "content-type": "application/json", "x-goog-api-key": gemini },
+            body: JSON.stringify({
+                systemInstruction: { parts: [{ text: options.system }] },
+                contents: [{ role: "user", parts: [{ text: options.prompt }] }],
+                generationConfig: { responseMimeType: "application/json", temperature: 0.9 },
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`gemini answered HTTP ${response.status}`);
+        const body = (await response.json());
+        const text = body.candidates?.[0]?.content?.parts?.map((one) => one.text ?? "").join("") ?? "";
+        return { model, value: firstObject(text) };
+    }
+    if (openai) {
+        const model = env["NIXAMP_OPENAI_MODEL"] || "gpt-4.1-mini";
+        const response = await send("https://api.openai.com/v1/chat/completions", {
+            method: "POST",
+            signal,
+            headers: { "content-type": "application/json", authorization: `Bearer ${openai}` },
+            body: JSON.stringify({
+                model,
+                response_format: { type: "json_object" },
+                messages: [{ role: "system", content: options.system }, { role: "user", content: options.prompt }],
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`openai answered HTTP ${response.status}`);
+        const body = (await response.json());
+        return { model, value: firstObject(body.choices?.[0]?.message?.content ?? "") };
+    }
+    if (anthropic) {
+        const model = env["NIXAMP_ANTHROPIC_MODEL"] || "claude-haiku-5-5";
+        const response = await send("https://api.anthropic.com/v1/messages", {
+            method: "POST",
+            signal,
+            headers: { "content-type": "application/json", "x-api-key": anthropic, "anthropic-version": "2023-06-01" },
+            body: JSON.stringify({
+                model,
+                max_tokens: 1024,
+                system: `${options.system}\nAnswer with one JSON object and nothing else.`,
+                messages: [{ role: "user", content: options.prompt }],
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`anthropic answered HTTP ${response.status}`);
+        const body = (await response.json());
+        return { model, value: firstObject(body.content?.filter((one) => one.type === "text").map((one) => one.text ?? "").join("") ?? "") };
+    }
+    throw new NoModel();
+}

package/dist/library.d.ts

@@ -9,6 +9,8 @@ export interface Config {
     guideHosts?: string[];
     /** Station limits kept across restarts (station-metering.ts). */
     limits?: Record<string, unknown>;
+    /** Proxies whose X-Forwarded-For is believed for listener shares (`nixamp station shares trust ADDRESS`). */
+    trustedProxies?: string[];
 }
 export declare function configPath(): string;
 export declare function readConfig(): Config;

package/dist/library.js

@@ -33,6 +33,7 @@ export function readConfig() {
             ...(typeof record["publish"] === "boolean" ? { publish: record["publish"] } : {}),
             ...(typeof record["autoStations"] === "object" && record["autoStations"] !== null ? { autoStations: record["autoStations"] } : {}),
             ...(typeof record["limits"] === "object" && record["limits"] !== null ? { limits: record["limits"] } : {}),
+            ...(Array.isArray(record["trustedProxies"]) ? { trustedProxies: record["trustedProxies"].filter((one) => typeof one === "string") } : {}),
             ...(Array.isArray(record["guideHosts"]) ? { guideHosts: record["guideHosts"].filter((one) => typeof one === "string") } : {}),
         };
     }

package/dist/listener-shares.d.ts

@@ -0,0 +1,136 @@
+import type { IncomingMessage } from "node:http";
+import { askJson } from "./ai-text.ts";
+import type { LibraryIndex, Probed } from "./library-index.ts";
+import type { StationRunner } from "./station-runner.ts";
+import { type StationStore } from "./stations.ts";
+export type ShareState = "fetching" | "checking" | "held" | "approved" | "rejected" | "failed" | "reported" | "withdrawn";
+export type ShareBasis = "owned" | "permission" | "licensed" | "creative-commons" | "public-domain";
+export declare const SHARE_BASES: readonly ShareBasis[];
+export declare const SHARE_GENRES: string[];
+export interface Share {
+    id: string;
+    /** Lets the sharer see how it went, and withdraw it. Never shown to anybody else. */
+    token: string;
+    via: "url" | "upload";
+    /** Where it came from, for the owner. */
+    url: string;
+    name: string;
+    file: string;
+    bytes: number;
+    sha256: string;
+    state: ShareState;
+    /** Why it is held, refused, failed or reported, in words. */
+    reason: string;
+    title: string;
+    artist: string;
+    genre: string;
+    duration: number;
+    rights: {
+        basis: ShareBasis;
+        note: string;
+    };
+    /** A name the sharer chose to be credited with, or "". */
+    by: string;
+    /** Who shared it, as a salted hash: enough to count, not to find them. */
+    from: string;
+    check: {
+        model: string;
+        verdict: "clear" | "doubt" | "refuse" | "";
+        reason: string;
+    };
+    reports: Array<{
+        at: number;
+        reason: string;
+        from: string;
+    }>;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ShareSettings {
+    /** Whether anybody may share at all. */
+    open: boolean;
+    /** "ai": a clear verdict goes on the air; "owner": everything waits. */
+    moderation: "ai" | "owner";
+    /** Shared stations are public and on the guide. */
+    publish: boolean;
+    maxBytes: number;
+    /** Shares an hour from one sharer. */
+    perHour: number;
+}
+export declare const SHARE_DEFAULTS: ShareSettings;
+export interface SharesDeps {
+    index: LibraryIndex;
+    store: StationStore;
+    runner: StationRunner;
+    probe: (path: string) => Promise<Probed>;
+    /** "" when this address may be fetched, else why not (destinations.ts). */
+    guard: (url: string) => Promise<string>;
+    /** The folder shared files go in: a managed library source. */
+    root: string;
+    owner: string;
+    mayStart: () => boolean;
+    /** The file a station is playing now, "" when none. */
+    nowPlaying: (stationId: string) => string;
+    fetcher?: typeof fetch;
+    ask?: typeof askJson;
+    canAsk?: () => boolean;
+    now?: () => number;
+    log?: (line: string) => void;
+}
+/** What a sharer may see of their share. */
+export declare function sharerView(share: Share): Record<string, unknown>;
+/** What the owner sees: all of it but the sharer's token. */
+export declare function ownerShareView(share: Share): Record<string, unknown>;
+export declare class ListenerShares {
+    private readonly file;
+    private readonly deps;
+    private shares;
+    private settings;
+    private salt;
+    private sourceId;
+    private recent;
+    private syncing;
+    constructor(file: string, deps: SharesDeps);
+    static fileFor(stateDir: string, port: number): string;
+    private now;
+    private save;
+    private source;
+    setting(): ShareSettings & {
+        model: boolean;
+    };
+    configure(input: Record<string, unknown>): ShareSettings;
+    list(state?: string): Share[];
+    get(id: string): Share | undefined;
+    /** The share, if this token is the one its sharer was given. */
+    forSharer(id: string, token: string): Share | undefined;
+    private fromOf;
+    /** Throws when shares are closed or this sharer has shared enough for the hour. */
+    private admit;
+    private declared;
+    private blank;
+    /** A link to a music file. Answers at once; the fetch and the check carry on. */
+    fromUrl(input: Record<string, unknown>, caller: string): Share;
+    /** The file itself, as the request body. Resolves once it is all here; the check carries on. */
+    fromUpload(request: IncomingMessage, input: Record<string, unknown>, caller: string): Promise<Share>;
+    /** The sharer takes it back: off the air and its copy gone. */
+    withdraw(share: Share): Share;
+    /** A listener says what is playing should not be: off the air at once, for the owner to look at. */
+    report(input: {
+        station?: unknown;
+        share?: unknown;
+        reason?: unknown;
+    }, caller: string): {
+        reported: boolean;
+        title: string;
+    };
+    /** The owner's decision. */
+    decide(id: string, decision: "approve" | "reject" | "delete", reason?: string): Share | null;
+    private fail;
+    /** Bytes to the share's file, counted, capped and hashed. */
+    private write;
+    private fetchAndCheck;
+    /** ffprobe, then the model: on the air, waiting, or turned away. */
+    private check;
+    /** Each genre's shared station, with exactly the approved tracks; one with none goes quiet. */
+    sync(): Promise<void>;
+}