nixamp 0.41.2 → 0.43.0

package/dist/support.js

@@ -40,6 +40,10 @@ export class Support {
     constructor(options) {
         this.options = options;
     }
+    /** For a subscription's renewals, which ask CoinPay about their payments. */
+    get key() {
+        return this.options.key;
+    }
     holder(id) {
         return this.options.holders.find((one) => one.id === id.toLowerCase());
     }
@@ -100,7 +104,7 @@ export class Support {
                 currency: coin.toLowerCase(),
                 payment_method: "crypto",
                 description: `Support ${holder.name} on nixamp`,
-                metadata: { app: "nixamp", product: "support", holder: holder.id, order, station: clean(input.station), track: clean(input.track) },
+                metadata: { app: "nixamp", product: "support", holder: holder.id, order, station: clean(input.station), track: clean(input.track), ...(input.metadata ?? {}) },
                 redirect_url: `${this.options.site}/support/${holder.id}?thanks=1`,
             }),
         });
@@ -108,7 +112,7 @@ export class Support {
         const id = typeof payment?.id === "string" ? payment.id : "";
         if (!/^[A-Za-z0-9_-]{6,80}$/.test(id))
             throw new SupportError("The checkout did not start; nothing was charged. Try again.", 502, "provider");
-        return { url: `https://coinpayportal.com/pay/${id}` };
+        return { url: `https://coinpayportal.com/pay/${id}`, paymentId: id };
     }
 }
 const STYLE = `
@@ -126,6 +130,8 @@ button.go{margin-top:18px;width:100%;padding:12px;border:0;border-radius:999px;b
 button:focus-visible,input:focus-visible,select:focus-visible{outline:3px solid var(--accent);outline-offset:2px}
 #status{min-height:1.4em;margin-top:12px;color:var(--muted)}
 .thanks{color:var(--accent);font-weight:700}
+.often{display:flex;gap:8px;margin:0 0 14px}.often label{flex:1;margin:0;display:flex;gap:8px;align-items:center;justify-content:center;padding:10px;border:1px solid var(--line);border-radius:10px;color:var(--fg);cursor:pointer}
+.often input{width:auto}
 small{display:block;margin-top:18px;color:var(--muted)}small a{color:inherit}
 `;
 const SCRIPT = `
@@ -141,6 +147,11 @@ const SCRIPT = `
       for (const o of document.querySelectorAll(".amounts button")) o.setAttribute("aria-pressed", String(o === b));
     });
   }
+  const monthly = () => document.querySelector("input[name=often]:checked").value === "monthly";
+  for (const r of document.querySelectorAll("input[name=often]")) r.addEventListener("change", () => {
+    $("#email-box").hidden = !monthly();
+    $("#go").textContent = monthly() ? "Pay the first month" : "Continue to payment";
+  });
   if (params.get("thanks")) { $("#status").className = "thanks"; $("#status").textContent = "Thank you. Your payment is on its way."; }
   try {
     const info = await (await fetch("/api/v1/support/" + encodeURIComponent(holder), { cache: "no-store" })).json();
@@ -157,7 +168,8 @@ const SCRIPT = `
     $("#status").textContent = "Starting the checkout…";
     try {
       const r = await fetch("/api/v1/support/" + encodeURIComponent(holder), { method: "POST", headers: { "content-type": "application/json" },
-        body: JSON.stringify({ amountUsd: usd, coin: $("#coin").value, station: params.get("station") || "", track: params.get("track") || "" }) });
+        body: JSON.stringify({ amountUsd: usd, coin: $("#coin").value, station: params.get("station") || "", track: params.get("track") || "",
+          ...(monthly() ? { monthly: true, email: $("#email").value } : {}) }) });
       const body = await r.json();
       if (r.ok && body.url) { location.href = body.url; return; }
       $("#status").textContent = body.error || "That did not work.";
@@ -180,17 +192,22 @@ export const SUPPORT_PAGE = `<!doctype html>
 <main>
   <div class="card">
     <h1>Support <span id="who">the artist</span></h1>
-    <p>Pay the copyright holder of the music you are listening to, directly. One payment, in crypto, through CoinPay.</p>
+    <p>Pay the copyright holder of the music you are listening to, directly, in crypto through CoinPay. Once, or every month.</p>
     <form id="form">
+      <div class="often"><label><input type="radio" name="often" value="once" checked> One time</label><label><input type="radio" name="often" value="monthly"> Monthly</label></div>
       <div class="amounts">${AMOUNTS.map((usd, at) => `<button type="button" data-usd="${usd}" aria-pressed="${at === 1}">$${usd}</button>`).join("")}</div>
       <label for="other">Or another amount (US$)</label>
       <input id="other" type="number" min="1" max="1000" step="1" inputmode="numeric">
+      <div id="email-box" hidden>
+        <label for="email">Email, for each month's payment link (and the cancel link)</label>
+        <input id="email" type="email" autocomplete="email" maxlength="254">
+      </div>
       <label for="coin">Pay with</label>
       <select id="coin"></select>
       <button id="go" class="go" type="submit">Continue to payment</button>
       <div id="status" role="status" aria-live="polite"></div>
     </form>
-    <small>Payments go through <a href="https://coinpayportal.com">CoinPay</a> to nixamp.com, which pays the holder. Nothing recurs.</small>
+    <small>Payments go through <a href="https://coinpayportal.com">CoinPay</a> to nixamp.com, which pays the holder. Monthly: each month we email a new payment link; nothing is taken until you pay it, and every email has a one-click cancel.</small>
   </div>
 </main>
 <script>${SCRIPT}</script>
@@ -201,3 +218,168 @@ export const SUPPORT_CSP = [
     "default-src 'none'", `script-src ${hash(SCRIPT)}`, `style-src ${hash(STYLE)}`, "connect-src 'self'",
     "img-src 'self' data:", "base-uri 'none'", "form-action 'none'", "frame-ancestors 'none'",
 ].join("; ");
+/** What CoinPay calls a payment that has been made. */
+const PAID = new Set(["confirmed", "forwarding", "forwarded", "forwarding_failed", "completed"]);
+const EMAIL = /^[^\s@<>"]{1,64}@[^\s@<>"]{1,190}\.[a-z]{2,24}$/i;
+/** One month on from a time, on the same day where the month has it. */
+export function nextMonth(at) {
+    const date = new Date(at);
+    const day = date.getUTCDate();
+    date.setUTCDate(1);
+    date.setUTCMonth(date.getUTCMonth() + 1);
+    const last = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 0)).getUTCDate();
+    date.setUTCDate(Math.min(day, last));
+    return date.getTime();
+}
+/**
+ * Monthly support, run here rather than by CoinPay: CoinPay's only merchant
+ * subscriptions are Stripe's, and its recurring invoices refuse a scoped key.
+ * A subscription is an email, an amount, a coin and a holder. Month one is
+ * paid at once on CoinPay's checkout; each month after, a new payment is made
+ * and its link emailed, with a one-click cancel. A month left unpaid ends it
+ * (lapsed) rather than emailing forever.
+ */
+export class SupportSubscriptions {
+    options;
+    schema = null;
+    timer = null;
+    constructor(options) {
+        this.options = options;
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    ready() {
+        this.schema ??= (async () => {
+            await this.options.db.query(`CREATE TABLE IF NOT EXISTS support_subscriptions (
+        id TEXT PRIMARY KEY, token TEXT NOT NULL, holder TEXT NOT NULL, email TEXT NOT NULL,
+        amount_cents INTEGER NOT NULL, coin TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'active',
+        cycles INTEGER NOT NULL DEFAULT 0, last_payment_id TEXT, next_due TIMESTAMPTZ NOT NULL,
+        station TEXT NOT NULL DEFAULT '', created_at TIMESTAMPTZ NOT NULL, canceled_at TIMESTAMPTZ)`);
+            await this.options.db.query("CREATE INDEX IF NOT EXISTS support_subscriptions_due ON support_subscriptions (status, next_due)");
+        })().catch((error) => { this.schema = null; throw error; });
+        return this.schema;
+    }
+    /** Month one: a subscription and its first checkout. */
+    async start(input) {
+        const email = typeof input.email === "string" ? input.email.trim().toLowerCase() : "";
+        if (!EMAIL.test(email))
+            throw new SupportError("Give an email for the monthly payment links.", 400, "invalid_email");
+        const holder = typeof input.holder === "string" ? this.options.support.holder(input.holder) : undefined;
+        if (!holder)
+            throw new SupportError("Nobody by that name is supported here.", 404, "not_found");
+        await this.ready();
+        const live = await this.options.db.query("SELECT count(*)::int AS n FROM support_subscriptions WHERE email = $1 AND status = 'active'", [email]);
+        if (Number(live.rows[0]?.["n"] ?? 0) >= 10)
+            throw new SupportError("That email already has ten monthly supports.", 409, "too_many");
+        const id = randomUUID();
+        const token = randomUUID().replace(/-/g, "");
+        const checkout = await this.options.support.checkout({ ...input, holder: holder.id, metadata: { subscription: id, cycle: 1 } });
+        const now = this.now();
+        await this.options.db.query(`INSERT INTO support_subscriptions (id, token, holder, email, amount_cents, coin, cycles, last_payment_id, next_due, station, created_at)
+      VALUES ($1,$2,$3,$4,$5,$6,1,$7,$8,$9,$10)`, [id, token, holder.id, email, Math.round(Number(input.amountUsd) * 100), String(input.coin).toUpperCase(), checkout.paymentId, new Date(nextMonth(now)), typeof input.station === "string" ? input.station.slice(0, 20) : "", new Date(now)]);
+        await this.mail(email, `Your monthly support for ${holder.name}`, [
+            `Thank you for supporting ${holder.name} on nixamp, $${Number(input.amountUsd).toFixed(2)} a month in ${String(input.coin).toUpperCase()}.`,
+            `This month: ${checkout.url}`,
+            `Each month we email you a new payment link like this one. Nothing is taken without you paying it.`,
+            `Stop at any time: ${this.cancelLink(id, token)}`,
+        ]);
+        return { url: checkout.url, id };
+    }
+    cancelLink(id, token) {
+        return `${this.options.site}/support/cancel?s=${encodeURIComponent(id)}&t=${encodeURIComponent(token)}`;
+    }
+    async cancel(id, token) {
+        await this.ready();
+        const found = await this.options.db.query("UPDATE support_subscriptions SET status = 'canceled', canceled_at = $3 WHERE id = $1 AND token = $2 AND status <> 'canceled' RETURNING holder", [id, token, new Date(this.now())]);
+        const row = found.rows[0];
+        if (!row) {
+            const known = await this.options.db.query("SELECT holder FROM support_subscriptions WHERE id = $1 AND token = $2", [id, token]);
+            if (!known.rows[0])
+                throw new SupportError("That cancel link is not one of ours.", 404, "not_found");
+            return { canceled: true, holder: String(known.rows[0]["holder"]) };
+        }
+        return { canceled: true, holder: String(row["holder"]) };
+    }
+    async paid(paymentId) {
+        try {
+            const response = await (this.options.fetcher ?? fetch)(`https://coinpayportal.com/api/payments/${encodeURIComponent(paymentId)}`, {
+                signal: AbortSignal.timeout(15_000),
+                headers: { authorization: `Bearer ${this.options.support.key}` },
+            });
+            if (!response.ok)
+                return null;
+            const body = (await response.json());
+            return PAID.has(String(body.payment?.status ?? ""));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Every subscription now due: a new month's payment and its link, or lapsed when last month went unpaid. */
+    async renew() {
+        await this.ready();
+        const due = await this.options.db.query("SELECT * FROM support_subscriptions WHERE status = 'active' AND next_due <= $1 ORDER BY next_due LIMIT 200", [new Date(this.now())]);
+        let renewed = 0;
+        let lapsed = 0;
+        for (const row of due.rows) {
+            const id = String(row["id"]);
+            const last = String(row["last_payment_id"] ?? "");
+            const paid = last ? await this.paid(last) : false;
+            if (paid === null)
+                continue; // CoinPay did not answer: ask again next time.
+            const holder = this.options.support.holder(String(row["holder"]));
+            if (!paid || !holder) {
+                await this.options.db.query("UPDATE support_subscriptions SET status = 'lapsed' WHERE id = $1 AND status = 'active'", [id]);
+                lapsed += 1;
+                if (holder)
+                    await this.mail(String(row["email"]), `Your monthly support for ${holder.name} has stopped`, [
+                        `Last month's payment was not made, so we have stopped sending payment links. Nothing more will be asked.`,
+                        `Start again any time: ${this.options.site}/support/${holder.id}`,
+                    ]);
+                continue;
+            }
+            const amountUsd = Number(row["amount_cents"]) / 100;
+            const cycle = Number(row["cycles"]) + 1;
+            let checkout;
+            try {
+                checkout = await this.options.support.checkout({ holder: holder.id, amountUsd, coin: String(row["coin"]), station: String(row["station"] ?? ""), metadata: { subscription: id, cycle } });
+            }
+            catch (error) {
+                this.options.log?.(`  support: renewal ${id} could not start a payment: ${error.message}`);
+                continue;
+            }
+            await this.options.db.query("UPDATE support_subscriptions SET cycles = $2, last_payment_id = $3, next_due = $4 WHERE id = $1", [id, cycle, checkout.paymentId, new Date(nextMonth(new Date(String(row["next_due"])).getTime()))]);
+            await this.mail(String(row["email"]), `This month's support for ${holder.name}`, [
+                `Your monthly support for ${holder.name}: $${amountUsd.toFixed(2)} in ${String(row["coin"])}.`,
+                `Pay this month: ${checkout.url}`,
+                `Stop at any time: ${this.cancelLink(id, String(row["token"]))}`,
+            ]);
+            renewed += 1;
+        }
+        return { renewed, lapsed };
+    }
+    startSchedule(everyMs = 3600_000) {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.renew().catch((error) => this.options.log?.(`  support: renewals failed: ${error.message}`)), everyMs);
+        this.timer.unref?.();
+    }
+    async mail(to, subject, lines) {
+        if (!this.options.mail) {
+            this.options.log?.(`  support: no RESEND_API_KEY, so "${subject}" to ${to} was not sent`);
+            return;
+        }
+        try {
+            await (this.options.fetcher ?? fetch)("https://api.resend.com/emails", {
+                method: "POST",
+                signal: AbortSignal.timeout(15_000),
+                headers: { authorization: `Bearer ${this.options.mail.apiKey}`, "content-type": "application/json" },
+                body: JSON.stringify({ from: this.options.mail.from, to: [to], subject, text: `${lines.join("\n\n")}\n\nnixamp.com` }),
+            });
+        }
+        catch (error) {
+            this.options.log?.(`  support: mail to ${to} failed: ${error.message}`);
+        }
+    }
+}

package/dist/track-facts.d.ts

@@ -24,6 +24,8 @@ export interface TrackFacts {
     } | null;
     /** The track's own cover, on this station's link (it changes with the track); "" when it has none. */
     art: string;
+    /** Where the track's words are, on this station's link; "" when none are known. */
+    lyrics: string;
 }
 export interface Holder {
     id: string;
@@ -76,6 +78,8 @@ export interface FactSources {
     } | null;
     /** Where its cover is served, when it has one. */
     art?: string;
+    /** Where its words are served, when it has them. */
+    lyrics?: string;
 }
 export declare function factsFor(input: FactSources): TrackFacts;
 /** The copyright holders this server's owner registered. */

package/dist/track-facts.js

@@ -57,9 +57,13 @@ export class TagReader {
                 try {
                     const parsed = JSON.parse(out);
                     for (const source of [...(parsed.streams ?? []).map((one) => one.tags ?? {}), parsed.format?.tags ?? {}]) {
-                        for (const [name, value] of Object.entries(source))
-                            if (typeof value === "string")
-                                tags[name.toLowerCase()] = value.slice(0, 2000);
+                        for (const [name, value] of Object.entries(source)) {
+                            if (typeof value !== "string")
+                                continue;
+                            const lower = name.toLowerCase();
+                            // A song's words run longer than any other tag (lyrics.ts).
+                            tags[lower] = value.slice(0, /lyrics/.test(lower) ? 20_000 : 2000);
+                        }
                     }
                 }
                 catch {
@@ -144,7 +148,7 @@ export function factsFor(input) {
         rights = { holder: "", basis: "", note: "", license: "", source: "" };
     }
     const support = holder && holder.support ? { holder: holder.name, url: holder.support, label: holder.label || "Support" } : null;
-    return { title, artist, album, year, genre, ai, rights, support, art: input.art ?? "" };
+    return { title, artist, album, year, genre, ai, rights, support, art: input.art ?? "", lyrics: input.lyrics ?? "" };
 }
 function slug(text) {
     return text.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "holder";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.41.2",
+  "version": "0.43.0",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/ai-keys.ts

@@ -14,6 +14,8 @@ export const AI_KEY_NAMES = [
   "ELEVENLABS_API_KEY", "GEMINI_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY",
   // Any OpenAI-compatible endpoint in OpenAI's place (Cloudflare Workers AI, Ollama, ...) and its model.
   "NIXAMP_OPENAI_URL", "NIXAMP_OPENAI_MODEL",
+  // nichedb.dev's key for publishing our own songs' words (lyrics-publish.ts).
+  "NIXAMP_LYRICS_KEY",
 ] as const;
 export type AiKeyName = (typeof AI_KEY_NAMES)[number];
 

package/src/lyrics-publish.ts

@@ -0,0 +1,203 @@
+/**
+ * Our own songs' words, published back to nichedb.dev.
+ *
+ * A station whose owner declared the music theirs (basis "owned") and put it
+ * on the public guide (public and listed) is music we may publish the words
+ * of. For each of its files whose own tags carry lyrics (lyrics.ts), the
+ * words go to nichedb's POST /api/v1/lyrics with the key the owner set
+ * (NIXAMP_LYRICS_KEY, or `nixamp station lyrics key` into ai.json), once per
+ * text: what was sent is remembered by a hash of the words, so a file is sent
+ * again only when its words change. One at a time, a second apart, and a
+ * refusal of the key (401/403) or a 429 stops the run.
+ *
+ * Nothing is published without a key, and nothing for a station that is not
+ * owned, whatever else is true of it.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { lyricsFromTags, NICHEDB_LYRICS } from "./lyrics.ts";
+import type { Station } from "./stations.ts";
+
+type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
+
+/** Whether a station's lyrics may be published: owned, public and listed. */
+export function mayPublishLyrics(station: Pick<Station, "visibility" | "listed" | "rights">): boolean {
+  return station.rights?.basis === "owned" && station.visibility === "public" && station.listed === true;
+}
+
+/** Why not, in words, or "" when it may. */
+export function whyNotPublish(station: Pick<Station, "visibility" | "listed" | "rights">): string {
+  if (station.rights?.basis !== "owned") return "its music is not declared owned (nixamp station publish ID --basis owned)";
+  if (station.visibility !== "public") return "it is not public";
+  if (!station.listed) return "it is not listed on the guide";
+  return "";
+}
+
+export interface PublishReport {
+  station: string;
+  published: number;
+  unchanged: number;
+  /** Files with no words in their tags, or no artist or title to file them under. */
+  without: number;
+  failed: number;
+  stopped: string;
+}
+
+export interface LyricsPublisherOptions {
+  file: string;
+  /** The key nichedb takes, read each run (it may be set while the server runs); "" when unset. */
+  key: () => string;
+  stations: () => Station[];
+  tags: (file: string) => Promise<Record<string, string>>;
+  known?: (file: string) => { title: string; artist: string; album: string } | null;
+  base?: string;
+  fetcher?: Fetcher;
+  /** Between two posts. */
+  gapMs?: number;
+  /** After a change, before a run (changes come in bursts). */
+  debounceMs?: number;
+  log?: (line: string) => void;
+}
+
+interface Sent { hash: string; at: number; artist: string; title: string }
+
+export class LyricsPublisher {
+  private sent: Record<string, Sent> = {};
+  private running: Promise<PublishReport[]> | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private last: { at: number; reports: PublishReport[] } | null = null;
+  private lastError = "";
+  private readonly base: string;
+  private readonly fetcher: Fetcher;
+
+  constructor(private readonly options: LyricsPublisherOptions) {
+    this.base = (options.base ?? process.env["NIXAMP_LYRICS_URL"] ?? NICHEDB_LYRICS).replace(/\/+$/, "");
+    this.fetcher = options.fetcher ?? ((url, init) => fetch(url, init));
+    try {
+      const parsed = JSON.parse(readFileSync(options.file, "utf8")) as { sent?: Record<string, Sent> };
+      this.sent = parsed.sent ?? {};
+    } catch {
+      this.sent = {};
+    }
+  }
+
+  static fileFor(stateDir: string, port: number): string {
+    return join(stateDir, `lyrics-published-${port}.json`);
+  }
+
+  private save(): void {
+    mkdirSync(dirname(this.options.file), { recursive: true });
+    const temporary = `${this.options.file}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify({ version: 1, sent: this.sent }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, this.options.file);
+  }
+
+  /** Something changed (a station, the library): publish what is new, shortly. Nothing without a key. */
+  soon(): void {
+    // A run is already due: changes in a burst ride on it (a busy store saves often).
+    if (!this.options.key() || this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.publishAll().catch(() => undefined);
+    }, this.options.debounceMs ?? 30_000);
+    this.timer.unref?.();
+  }
+
+  status(): Record<string, unknown> {
+    const eligible = this.options.stations().filter(mayPublishLyrics);
+    return {
+      key: this.options.key() !== "",
+      target: this.base,
+      published: Object.keys(this.sent).length,
+      running: this.running !== null,
+      last: this.last,
+      lastError: this.lastError,
+      stations: this.options.stations().map((one) => ({
+        id: one.id,
+        name: one.name,
+        eligible: mayPublishLyrics(one),
+        why: whyNotPublish(one),
+        files: one.items.length,
+        published: one.items.filter((file) => this.sent[file]).length,
+      })),
+      eligible: eligible.length,
+    };
+  }
+
+  /** Every eligible station, one after another; a run already going is joined, not doubled. */
+  publishAll(): Promise<PublishReport[]> {
+    if (this.running) return this.running;
+    this.running = (async () => {
+      const reports: PublishReport[] = [];
+      for (const station of this.options.stations().filter(mayPublishLyrics)) {
+        const report = await this.publishOne(station);
+        reports.push(report);
+        if (report.stopped) break;
+      }
+      this.last = { at: Date.now(), reports };
+      const sent = reports.reduce((sum, one) => sum + one.published, 0);
+      if (sent > 0) this.options.log?.(`  lyrics: published ${sent} to ${this.base}.`);
+      return reports;
+    })().finally(() => { this.running = null; });
+    return this.running;
+  }
+
+  /** One station, now. Refused (stopped says why) when it may not be published or there is no key. */
+  async publish(station: Station): Promise<PublishReport> {
+    if (this.running) await this.running.catch(() => undefined);
+    return this.publishOne(station);
+  }
+
+  private async publishOne(station: Station): Promise<PublishReport> {
+    const report: PublishReport = { station: station.id, published: 0, unchanged: 0, without: 0, failed: 0, stopped: "" };
+    const why = whyNotPublish(station);
+    if (why) { report.stopped = `not published: ${why}`; return report; }
+    const key = this.options.key();
+    if (!key) { report.stopped = "no key: set NIXAMP_LYRICS_KEY or `nixamp station lyrics key`"; return report; }
+    if (!this.base) { report.stopped = "no target: NIXAMP_LYRICS_URL is empty"; return report; }
+    let first = true;
+    for (const file of station.items) {
+      let tags: Record<string, string> = {};
+      try { tags = await this.options.tags(file); } catch { tags = {}; }
+      const words = lyricsFromTags(tags);
+      const known = this.options.known?.(file) ?? null;
+      const title = tags["title"] || known?.title || "";
+      const artist = tags["artist"] || tags["album_artist"] || known?.artist || "";
+      const album = tags["album"] || known?.album || "";
+      if (!words || !title || !artist) { report.without += 1; continue; }
+      const hash = createHash("sha256").update(`${artist}\n${title}\n${words.text}`).digest("hex");
+      if (this.sent[file]?.hash === hash) { report.unchanged += 1; continue; }
+      if (!first) await new Promise((done) => setTimeout(done, this.options.gapMs ?? 1_000));
+      first = false;
+      let response: Response;
+      try {
+        response = await this.fetcher(`${this.base}/api/v1/lyrics`, {
+          method: "POST",
+          headers: { "content-type": "application/json", accept: "application/json", authorization: `Bearer ${key}` },
+          body: JSON.stringify({ artist, title, album, language: words.language, text: words.text, source: "embedded" }),
+          signal: AbortSignal.timeout(15_000),
+        });
+      } catch (error) {
+        report.failed += 1;
+        this.lastError = `could not reach ${this.base}: ${(error as Error).message}`;
+        report.stopped = this.lastError;
+        break;
+      }
+      if (response.ok) {
+        this.sent[file] = { hash, at: Date.now(), artist, title };
+        this.save();
+        report.published += 1;
+        continue;
+      }
+      report.failed += 1;
+      const detail = (await response.text().catch(() => "")).slice(0, 200);
+      this.lastError = `nichedb answered ${response.status} for "${title}"${detail ? `: ${detail}` : ""}`;
+      if (response.status === 401 || response.status === 403 || response.status === 429 || response.status >= 500) {
+        report.stopped = this.lastError;
+        break;
+      }
+    }
+    return report;
+  }
+}