// Tiny resolver service: candidate names -> artist/album links, for CONFIRMED names only. // // Zero npm deps; Node 18+ (built-in fetch). The "which words are real artists/albums" problem // is not guessed client-side — it is gated one of two ways: // * SPOTIFY_CLIENT_ID/SECRET set -> a candidate resolves only when Spotify has an artist OR // album whose name matches it case-insensitively (the exact-match precision lever), linking // to the DIRECT Spotify artist/album page. One search call covers both types. // * OLLAMA_URL set -> a local LLM (via ollama HTTP, still zero npm deps) classifies each // candidate as artist/album/none; the kind routes the Spotify lookup, and confirmed names // get a Spotify direct link when available, else a Google->Bandcamp search fallback. This // is the better-matching path. // The two combine: with both set, the LLM gates + routes the kind and Spotify supplies direct // links. Each result carries kind:"artist"|"album". The pure matching/link/prompt logic lives // in lib.js + llm.js (unit-tested). import { createServer } from "node:http"; import { readFileSync } from "node:fs"; import { pickArtist, pickAlbum, isHttpUrl } from "./lib.js"; import { buildClassifyMessages, parseClassification, DEFAULT_MODEL } from "./llm.js"; import { resolveAll as resolveAllCore } from "./resolve-core.js"; import { makeSpotifyToken, makeSpotifySearch } from "./spotify.js"; import { makeOdesli, shouldEnrich } from "./odesli.js"; // --- minimal .env loader (no dependency) ------------------------------------ try { const env = readFileSync(new URL("./.env", import.meta.url), "utf8"); for (const line of env.split("\n")) { const m = line.match(/^\s*([\w.-]+)\s*=\s*(.*?)\s*$/); if (m && !(m[1] in process.env)) process.env[m[1]] = m[2].replace(/^["']|["']$/g, ""); } } catch { /* no .env -> use real env / defaults */ } const PORT = Number(process.env.PORT) || 8787; const SPOTIFY_ID = process.env.SPOTIFY_CLIENT_ID; const SPOTIFY_SECRET = process.env.SPOTIFY_CLIENT_SECRET; const USE_SPOTIFY = Boolean(SPOTIFY_ID && SPOTIFY_SECRET); const OLLAMA_URL = (process.env.OLLAMA_URL || "").replace(/\/$/, ""); // presence enables the LLM gate const OLLAMA_MODEL = process.env.OLLAMA_MODEL || DEFAULT_MODEL; const USE_LLM = Boolean(OLLAMA_URL); // Optional Odesli enrichment: opt-in, default OFF (mirrors the ollama opt-in). ODESLI=1 (or any // truthy non-"0"/"false" value), or ODESLI_URL= to override the endpoint, turns it on. When // OFF, no Odesli call is made and no platform fields are added — behavior is byte-identical. const ODESLI_URL = (process.env.ODESLI_URL || "").replace(/\/$/, ""); const ODESLI_FLAG = (process.env.ODESLI || "").trim().toLowerCase(); const USE_ODESLI = Boolean(ODESLI_URL) || (ODESLI_FLAG !== "" && ODESLI_FLAG !== "0" && ODESLI_FLAG !== "false"); // Cache only the network half (the Spotify direct-url lookup); resolve-core rebuilds the final // link object per request so a name's result never depends on a stale gate decision. The key // includes the kind hint (see resolve-core's cacheKey). const spCache = new Map(); // Odesli results cached per Spotify entity URL (the input is the cache key — a stable identity for // the enrichment, independent of which candidate name resolved to it). const odCache = new Map(); // --- Spotify (optional): direct-artist-link lookup -------------------------- // The single-flight token getter: a cold/expired-cache fan-out (up to MAX_CANDIDATES concurrent // resolves) shares ONE POST /api/token instead of stampeding the rate-limited token endpoint. // fetchToken does the real POST; the cache + (expires_in-60)*1000 expiry math live in the factory. const spTokens = makeSpotifyToken({ fetchToken: async () => { const auth = Buffer.from(`${SPOTIFY_ID}:${SPOTIFY_SECRET}`).toString("base64"); const r = await fetch("https://accounts.spotify.com/api/token", { method: "POST", headers: { authorization: `Basic ${auth}`, "content-type": "application/x-www-form-urlencoded" }, body: "grant_type=client_credentials", signal: AbortSignal.timeout(5000), // fail fast on a hung upstream (caught per-candidate -> null) }); if (!r.ok) throw new Error(`spotify token http ${r.status}`); return r.json(); }, }); // One bare Spotify search (no token mgmt): returns { ok, status, headers, body } so the // search-with-retry layer can branch on 401/429 without an exception masking the status. async function doSpotifySearch(name, token) { const url = `https://api.spotify.com/v1/search?type=artist,album&limit=5&q=${encodeURIComponent(name)}`; const r = await fetch(url, { headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(5000), // fail fast on a hung upstream (caught per-candidate -> null) }); // 401/429 carry no usable body for our purposes; only parse JSON on a real hit. const body = r.ok ? await r.json() : null; return { ok: r.ok, status: r.status, headers: r.headers, body }; } // 401 -> invalidate + refresh + retry once; 429 -> bounded Retry-After + retry once; else throw. const spSearch = makeSpotifySearch({ doSearch: doSpotifySearch, tokens: spTokens }); // The injected `search` for resolve-core: one type=artist,album Spotify search per candidate, // returning the exact-name-match hits as { artist, album } where each is the external Spotify url // (string) or null. No creds -> both null (nothing links). resolve-core's pickDirect applies the // kindHint tie-break and shapes the link; the cache (spCache) is owned by resolve-core too. async function search(name) { if (!USE_SPOTIFY) return { artist: null, album: null }; const j = await spSearch(name); return { artist: pickArtist(name, j.artists?.items)?.external_urls?.spotify ?? null, album: pickAlbum(name, j.albums?.items)?.external_urls?.spotify ?? null, }; } // --- LLM gate (optional): which candidates are artists/albums? -------------- async function ollamaClassify(candidates) { const r = await fetch(`${OLLAMA_URL}/api/chat`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ model: OLLAMA_MODEL, messages: buildClassifyMessages(candidates), stream: false, format: "json", options: { temperature: 0 }, }), signal: AbortSignal.timeout(5000), // fail fast on a hung upstream (caught per-candidate -> null) }); if (!r.ok) throw new Error(`ollama http ${r.status}`); const j = await r.json(); return parseClassification(j.message?.content ?? "", candidates); } // --- Odesli (optional): direct cross-platform links for a Spotify-resolved name ---------------- // Enriches a result that already carries a DIRECT Spotify url with the album/track's direct // Bandcamp (+ Apple Music / YouTube) links. Only the Spotify-creds path produces such a url, so // the no-creds Google fallback path is never touched. Each returned platform url is re-validated // (isHttpUrl) before it is added, and the lookup is cached per Spotify url (odCache). const odesli = USE_ODESLI ? makeOdesli({ fetch, ...(ODESLI_URL ? { baseUrl: ODESLI_URL } : {}) }) : null; // Enrich one ALBUM result in place with Odesli platform links, when it has a direct Spotify url. // The added fields (bandcamp / appleMusic / youtube) are ADDITIVE — name/kind/spotify/google/ // primary are untouched, so an older extension keeps rendering exactly as before. Odesli down / // timeout / garbage -> getLinks returns {} -> the result is unchanged (graceful). Mutated + returned. async function enrichWithOdesli(result) { // shouldEnrich: an ALBUM result with a direct Spotify url. Artist results are skipped (Odesli // 405s on artist urls) so the common artist case makes no wasted round-trip. if (!shouldEnrich(result)) return result; const spUrl = result.spotify; let links; if (odCache.has(spUrl)) { links = odCache.get(spUrl); } else { links = await odesli.getLinks(spUrl); odCache.set(spUrl, links); } for (const platform of ["bandcamp", "appleMusic", "youtube"]) { const url = links[platform]; if (typeof url === "string" && isHttpUrl(url)) result[platform] = url; // validated additive field } return result; } // --- resolve -------------------------------------------------------------- // Run the pure orchestration (resolve-core) with the live clients injected: the Spotify `search`, // the ollama `classify` gate (null when no LLM is configured -> the Spotify exact-match is the // gate), and the shared spCache. When Odesli is enabled, enrich each Spotify-resolved result with // its direct cross-platform links; when disabled, the map is returned untouched (no extra calls). async function resolveAll(candidates) { const out = await resolveAllCore(candidates, { search, classify: USE_LLM ? ollamaClassify : null, cache: spCache }); if (!odesli) return out; await Promise.all(Object.values(out).map((r) => enrichWithOdesli(r))); return out; } // --- HTTP ------------------------------------------------------------------- function readBody(req) { return new Promise((resolve, reject) => { let data = ""; req.on("data", (c) => { data += c; if (data.length > 1e6) { reject(new Error("body too large")); req.destroy(); } }); req.on("end", () => resolve(data)); req.on("error", reject); }); } const json = (res, code, obj) => { res.writeHead(code, { "content-type": "application/json" }); res.end(JSON.stringify(obj)); }; // CORS scoped to the extension origin: the background script sends // `Origin: moz-extension://`; a page-context fetch (file://, sandboxed) can send // `Origin: null`. Reflect only those — never blanket `*` — so an arbitrary website the // user visits can't POST to localhost:8787 and read resolver results. const allowedOrigin = (origin) => typeof origin === "string" && (origin.startsWith("moz-extension://") || origin === "null"); const server = createServer(async (req, res) => { const origin = req.headers.origin; if (allowedOrigin(origin)) res.setHeader("access-control-allow-origin", origin); res.setHeader("vary", "origin"); // the allow-origin header varies by request Origin res.setHeader("access-control-allow-headers", "content-type"); res.setHeader("access-control-allow-methods", "GET, POST, OPTIONS"); if (req.method === "OPTIONS") { res.writeHead(204); return res.end(); } if (req.method === "GET" && req.url === "/health") { return json(res, 200, { ok: true, spotify: USE_SPOTIFY, llm: USE_LLM ? OLLAMA_MODEL : false, odesli: USE_ODESLI, cached: spCache.size }); } if (req.method === "POST" && req.url === "/resolve") { try { const { candidates } = JSON.parse((await readBody(req)) || "{}"); if (!Array.isArray(candidates)) return json(res, 400, { error: "candidates must be an array" }); return json(res, 200, await resolveAll(candidates)); } catch (e) { return json(res, 500, { error: e.message }); } } json(res, 404, { error: "not found" }); }); server.listen(PORT, () => { const sp = USE_SPOTIFY ? "on" : "off"; const llm = USE_LLM ? OLLAMA_MODEL : "off"; const od = USE_ODESLI ? "on" : "off"; console.log(`resolver listening on http://localhost:${PORT} (spotify: ${sp}, llm: ${llm}, odesli: ${od})`); if (!USE_SPOTIFY && !USE_LLM) { console.warn(" ! no gate configured: set SPOTIFY_CLIENT_ID/SECRET and/or OLLAMA_URL, or nothing will link."); } });