cursedbelt-server 4.41.0 → 4.43.0

package/dist/server/youtube/ytdlp.js

@@ -0,0 +1,334 @@
+/**
+ * `cursedbelt-server/youtube/ytdlp` — run yt-dlp on the Mac and hand back the file it made.
+ *
+ * ── Why it is here (forge task 2349) ────────────────────────────────────────────────────
+ * Music downloads the owner's YouTube playlists as AUDIO (task 2348) and Collections downloads
+ * them as VIDEO (task 2349). Both runners were the same machine with a different `-f`: spawn
+ * yt-dlp, read its progress off a marker line, sort a failure by what fixes it, install the
+ * binary when it is missing and update it when YouTube has moved on. So that machine is here,
+ * once, and each app hands it a {@link YtDlpProfile} — the format, the size ceiling, the noun
+ * its sentences use — plus the one command that installs or updates yt-dlp from that app.
+ *
+ * What is NOT here, on purpose: where the binary lives (each app passes `binary`, normally
+ * {@link ytDlpPath} of the generation's state root), what a downloaded file becomes (Music files
+ * a track; Collections ingests a video), and any re-encode (only Collections has one, and only
+ * when no H.264 stream exists).
+ *
+ * ── The file stays on disk ──────────────────────────────────────────────────────────────
+ * A download resolves to a PATH inside a fresh temporary directory, and the caller disposes of
+ * it. A 1080p video is gigabytes, and reading it into memory to hand it over would make the
+ * agent's footprint the size of the largest video in a playlist. Music, whose files are a few
+ * MB, reads the bytes and disposes at once.
+ *
+ * ── Self-healing in the two ways that need no owner ─────────────────────────────────────
+ * A missing binary is installed before the first run, and a failure that reads as "this
+ * yt-dlp is out of date" updates it (at most once an hour) and tries again. What is left after
+ * that is a sentence that NAMES the fix — "yt-dlp is out of date … Run: cd … && bun run yt-dlp".
+ *
+ * YouTube's JS challenges need a JavaScript runtime and yt-dlp enables only Deno by default,
+ * so it is handed the Bun running this process — which it supports — rather than a second
+ * runtime installed for one tool.
+ *
+ * 🔴 Mac-only. It spawns a process and writes files; nothing a Worker mounts may import it.
+ * It imports `node:*` and nothing else, which `leafSubpathsImportNothing.spec.ts` holds it to.
+ */
+import { spawn } from "node:child_process";
+import { chmod, mkdir, mkdtemp, rename, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+/** Where the standalone build is published. `latest` always names the newest release. */
+const YTDLP_RELEASE_URL = "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos";
+/** The markers this module asks yt-dlp to print, so its own chatter can never be mistaken for them. */
+const PROGRESS_MARK = "ytprogress ";
+const INFO_MARK = "ytinfo ";
+/**
+ * A download that failed and was tried again. yt-dlp answers an intermittent `403` on the
+ * media request (measured 2026-09-30: one in three identical runs), and a retry is the fix.
+ */
+const ATTEMPTS = 3;
+/** How often a fetcher may update yt-dlp by itself. A release that does not fix it will not
+ *  start fixing it on the tenth try. */
+const SELF_UPDATE_EVERY_MS = 60 * 60_000;
+/** `$STATE/bin/yt-dlp` — one binary for every app on the Mac. `state` is the generation's state root. */
+export function ytDlpPath(state) {
+    return join(state, "bin", "yt-dlp");
+}
+/** yt-dlp's cache (the player JS it has already solved), kept with the generation's state. */
+export function ytDlpCacheDir(state) {
+    return join(state, "cache", "yt-dlp");
+}
+export class YtDlpError extends Error {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.kind = kind;
+        this.name = "YtDlpError";
+    }
+}
+/** A failure no retry and no update can change — the video's own fault, or the ceiling. */
+export const isFinalYtDlpFailure = (kind) => kind === "unavailable" || kind === "too-big";
+// ── Pure: reading what yt-dlp prints ───────────────────────────────────────────────────
+/**
+ * One progress line, as a fraction — or `null` for any other line.
+ *
+ * The template prints `downloaded total estimate`, and yt-dlp writes `NA` for a field it does
+ * not know. The exact total wins; the estimate is what a stream without a `content-length`
+ * has. With neither there is no honest fraction, so none is claimed.
+ */
+export function parseYtProgress(line) {
+    if (!line.startsWith(PROGRESS_MARK))
+        return null;
+    const [downloaded, total, estimate] = line.slice(PROGRESS_MARK.length).trim().split(/\s+/).map(Number);
+    const whole = Number.isFinite(total) && total > 0 ? total : estimate;
+    if (!Number.isFinite(downloaded) || !Number.isFinite(whole) || whole <= 0)
+        return null;
+    return Math.min(Math.max(downloaded / whole, 0), 1);
+}
+/** The info JSON printed after the file is in place, or `null` for any other line. */
+export function parseYtInfo(line) {
+    if (!line.startsWith(INFO_MARK))
+        return null;
+    try {
+        const value = JSON.parse(line.slice(INFO_MARK.length));
+        return value && typeof value === "object" && typeof value.id === "string" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** yt-dlp's last `ERROR:` line — the one that says why — or the stderr's last line. */
+function lastYtDlpError(stderr) {
+    const lines = stderr
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const errors = lines.filter((l) => l.startsWith("ERROR:"));
+    return (errors.at(-1) ?? lines.at(-1) ?? "").replace(/^ERROR:\s*/, "");
+}
+const UNAVAILABLE = /video unavailable|this video is unavailable|private video|has been removed|no longer available|account associated with this video has been terminated|not available in your country|blocked it in your country|members[- ]only|join this channel|confirm your age|age-restricted|copyright/i;
+const BLOCKED = /confirm you.?re not a bot|sign in to confirm|too many requests|http error 429/i;
+const OUTDATED = /unable to extract|nsig|n challenge|signature (extraction|function)|precondition check failed|http error 403|requested format is not available|please report this issue|js challenge|player .*(response|js)|unsupported url|jsc/i;
+const TOO_BIG = /larger than max-filesize|max-filesize/i;
+/** Sort a failure by what can be done about it — see {@link YtDlpFailure}. */
+export function classifyYtDlpFailure(stderr) {
+    const line = lastYtDlpError(stderr);
+    if (TOO_BIG.test(line))
+        return "too-big";
+    if (UNAVAILABLE.test(line))
+        return "unavailable";
+    if (BLOCKED.test(line))
+        return "blocked";
+    if (OUTDATED.test(line))
+        return "outdated";
+    return "failed";
+}
+/** The sentence a downloads table shows. Every kind that has a remedy NAMES it. */
+function describeYtDlpFailure(kind, detail, context) {
+    const fix = context.fixCommand;
+    switch (kind) {
+        case "missing":
+            return `yt-dlp is not installed on the Mac and installing it failed (${detail}). Run: ${fix}`;
+        case "outdated":
+            return (`yt-dlp could not read YouTube — it is out of date for a change YouTube made (${detail}). ` +
+                (context.updated
+                    ? `The agent already updated it and it still fails, so the fix is not released yet; try again in a day, or run: ${fix}`
+                    : `Run: ${fix}`));
+        case "blocked":
+            return `YouTube is refusing this Mac's requests as a bot (${detail}). It usually lifts within hours — try again later. If it persists, update yt-dlp: ${fix}`;
+        case "unavailable":
+            return `YouTube will not play this video to anyone signed out (${detail}), so there is nothing to download.`;
+        case "too-big":
+            return `${context.profile.noun} is over this app's ${context.profile.maxFilesize}B ceiling for one download.`;
+        default:
+            return `yt-dlp failed: ${detail || "no reason given"}. If YouTube links keep failing, update it: ${fix}`;
+    }
+}
+/** The arguments for one download. Exported so a test pins the flags that matter. */
+export function ytDlpArgs(videoId, outDir, profile, options = {}) {
+    return [
+        ...(options.jsRuntime ? ["--js-runtimes", `bun:${options.jsRuntime}`] : []),
+        ...(options.cacheDir ? ["--cache-dir", options.cacheDir] : []),
+        "--no-playlist",
+        "-f",
+        profile.format,
+        ...(profile.extraArgs ?? []),
+        "--max-filesize",
+        profile.maxFilesize,
+        "--no-part",
+        "--no-mtime",
+        "--no-colors",
+        "--newline",
+        // `--print` implies `--quiet`, which would swallow the progress lines — hence `--progress`.
+        "--progress",
+        "--progress-template",
+        `download:${PROGRESS_MARK}%(progress.downloaded_bytes)s %(progress.total_bytes)s %(progress.total_bytes_estimate)s`,
+        "--print",
+        `after_move:${INFO_MARK}%()j`,
+        "-o",
+        join(outDir, "%(id)s.%(ext)s"),
+        "--",
+        `https://www.youtube.com/watch?v=${videoId}`,
+    ];
+}
+const runLines = (binary, args, onLine) => new Promise((resolve, reject) => {
+    const child = spawn(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let buffer = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        buffer += chunk;
+        let at = buffer.indexOf("\n");
+        while (at >= 0) {
+            onLine(buffer.slice(0, at).replace(/\r$/, ""));
+            buffer = buffer.slice(at + 1);
+            at = buffer.indexOf("\n");
+        }
+    });
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+        // The tail is the part that says why; a runaway stderr must not grow without bound.
+        stderr = (stderr + chunk).slice(-16_384);
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+        if (buffer)
+            onLine(buffer);
+        resolve({ code: code ?? 1, stderr });
+    });
+});
+/**
+ * Put the newest standalone build at `binary`. Written beside it and renamed into place, so a
+ * download that dies halfway never leaves a truncated executable where a fetcher looks.
+ */
+export async function installYtDlp(binary, fetchImpl = fetch) {
+    const res = await fetchImpl(YTDLP_RELEASE_URL, { redirect: "follow", signal: AbortSignal.timeout(120_000) });
+    if (!res.ok)
+        throw new Error(`GitHub answered ${res.status} for ${YTDLP_RELEASE_URL}`);
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    // The standalone build is a Mach-O executable; anything small is an error page.
+    if (bytes.length < 1_000_000)
+        throw new Error(`the download was ${bytes.length} bytes, not a yt-dlp build`);
+    await mkdir(dirname(binary), { recursive: true });
+    const partial = `${binary}.partial`;
+    await writeFile(partial, bytes);
+    await chmod(partial, 0o755);
+    await rename(partial, binary);
+}
+/** `yt-dlp -U` — the standalone build updates itself in place. Resolves to what it printed. */
+export async function updateYtDlp(binary, run = runLines) {
+    const lines = [];
+    const { code, stderr } = await run(binary, ["-U"], (line) => lines.push(line));
+    const said = [...lines, ...stderr.split("\n")].map((l) => l.trim()).filter(Boolean);
+    if (code !== 0)
+        throw new Error(said.at(-1) ?? `yt-dlp -U exited ${code}`);
+    return said.at(-1) ?? "";
+}
+/**
+ * Install yt-dlp when it is missing, else update it — the body of each app's `bun run yt-dlp`.
+ * Resolves to the sentence to print.
+ */
+export async function installOrUpdateYtDlp(binary) {
+    if (!(await isFile(binary))) {
+        await installYtDlp(binary);
+        return `installed the latest release at ${binary}`;
+    }
+    return updateYtDlp(binary);
+}
+const isFile = async (path) => {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The fetcher an app's download agent is handed. See the header for what it heals by itself
+ * and what it leaves as a sentence.
+ */
+export function createYtDlp(options) {
+    const run = options.run ?? runLines;
+    const install = options.install ?? ((binary) => installYtDlp(binary));
+    const update = options.update ?? ((binary) => updateYtDlp(binary, run));
+    const now = options.now ?? Date.now;
+    const label = options.label ?? "[yt-dlp]";
+    const jsRuntime = options.jsRuntime ?? (process.versions.bun ? process.execPath : undefined);
+    let lastUpdate = Number.NEGATIVE_INFINITY;
+    const describe = (kind, detail, updated) => describeYtDlpFailure(kind, detail, { updated, fixCommand: options.fixCommand, profile: options.profile });
+    const ensureInstalled = async () => {
+        if (await isFile(options.binary))
+            return;
+        options.log?.(`${label} yt-dlp: not at ${options.binary} — installing the latest release`);
+        try {
+            await install(options.binary);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new YtDlpError(describe("missing", detail, false), "missing");
+        }
+    };
+    /** One yt-dlp run into a fresh directory. Throws a classified error on failure. */
+    const attempt = async (videoId, onProgress) => {
+        const dir = await mkdtemp(join(options.tmpRoot ?? tmpdir(), "ytdlp-"));
+        const dispose = () => rm(dir, { recursive: true, force: true });
+        try {
+            let info = null;
+            const { code, stderr } = await run(options.binary, ytDlpArgs(videoId, dir, options.profile, {
+                ...(options.cacheDir ? { cacheDir: options.cacheDir } : {}),
+                ...(jsRuntime ? { jsRuntime } : {}),
+            }), (line) => {
+                const fraction = parseYtProgress(line);
+                if (fraction !== null)
+                    onProgress?.(fraction);
+                info = parseYtInfo(line) ?? info;
+            });
+            const found = info;
+            if (code !== 0 || !found?.filepath) {
+                const kind = code === 0 ? "failed" : classifyYtDlpFailure(stderr);
+                throw new YtDlpError(code === 0 ? "yt-dlp finished without saying where the file went" : lastYtDlpError(stderr), kind);
+            }
+            if (!(await isFile(found.filepath)))
+                throw new YtDlpError(`yt-dlp named ${found.filepath} and it is not there`, "failed");
+            const extension = (found.ext || found.filepath.split(".").at(-1) || "bin").toLowerCase();
+            return { path: found.filepath, extension, info: found, dir, dispose };
+        }
+        catch (error) {
+            await dispose();
+            throw error;
+        }
+    };
+    return async (videoId, onProgress) => {
+        await ensureInstalled();
+        let updated = false;
+        let last = null;
+        for (let tries = 1; tries <= ATTEMPTS + 1; tries++) {
+            try {
+                return await attempt(videoId, onProgress);
+            }
+            catch (error) {
+                last =
+                    error instanceof YtDlpError ? error : new YtDlpError(error instanceof Error ? error.message : String(error), "failed");
+                if (isFinalYtDlpFailure(last.kind))
+                    break;
+                if (tries < ATTEMPTS)
+                    continue;
+                // Out of plain retries. One more, after an update, if it reads as out of date.
+                if (last.kind === "outdated" && !updated && now() - lastUpdate >= SELF_UPDATE_EVERY_MS) {
+                    lastUpdate = now();
+                    try {
+                        const said = await update(options.binary);
+                        updated = true;
+                        options.log?.(`${label} yt-dlp: updated after "${last.message}" — ${said}`);
+                        continue;
+                    }
+                    catch (updateError) {
+                        options.log?.(`${label} yt-dlp: update failed — ${updateError instanceof Error ? updateError.message : String(updateError)}`);
+                    }
+                }
+                break;
+            }
+        }
+        const failure = last ?? new YtDlpError("no attempt ran", "failed");
+        throw new YtDlpError(describe(failure.kind, failure.message, updated), failure.kind);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.41.0",
+	"version": "4.43.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -343,6 +343,18 @@
 			"source": "./src/server/sync/index.ts",
 			"import": "./dist/server/sync/index.js"
 		},
+		"./youtube": {
+			"types": "./dist/server/youtube/youtubeApi.d.ts",
+			"bun": "./src/server/youtube/youtubeApi.ts",
+			"source": "./src/server/youtube/youtubeApi.ts",
+			"import": "./dist/server/youtube/youtubeApi.js"
+		},
+		"./youtube/ytdlp": {
+			"types": "./dist/server/youtube/ytdlp.d.ts",
+			"bun": "./src/server/youtube/ytdlp.ts",
+			"source": "./src/server/youtube/ytdlp.ts",
+			"import": "./dist/server/youtube/ytdlp.js"
+		},
 		"./ws": {
 			"types": "./dist/server/ws/index.d.ts",
 			"bun": "./src/server/ws/index.ts",

package/src/leafSubpathsImportNothing.spec.ts

@@ -225,6 +225,24 @@ const LEAVES = [
     evaluates: 'argon2Cost',
     siblings: ['src/server/satellite/door.ts'],
   },
+  {
+    subpath: './youtube',
+    /**
+     * The YouTube Data API reader (4.43.0, forge task 2349) — out of Music so Collections lists
+     * the same playlists. Collections calls it from a Worker, so it may reach nothing but
+     * `fetch`; its one import is `import type` of `./google-oauth`'s `FetchLike`, which is erased.
+     */
+    evaluates: 'createYouTubeApi',
+  },
+  {
+    subpath: './youtube/ytdlp',
+    /**
+     * The yt-dlp runner (4.43.0, forge task 2349) shared by Music's audio and Collections' video
+     * agents. Mac-only, and its promise is `node:*` and nothing else — no `cursedops`, so the
+     * caller says where the binary is.
+     */
+    evaluates: 'createYtDlp',
+  },
 ] as const;
 
 /**

package/src/server/d1/http.spec.ts

@@ -124,3 +124,46 @@ describe('createHttpD1', () => {
 		expect(sent[0]?.body).toEqual({ sql: 'CREATE TABLE u (x); INSERT INTO u VALUES (1); INSERT INTO u VALUES (2)' });
 	});
 });
+
+describe('🔴 a request that never connected is retried; one that may have run is not', () => {
+	const refused = () => Object.assign(new TypeError('Unable to connect. Is the computer able to access the url?'), { code: 'ConnectionRefused' });
+	const flaky = (failures: Error[]) => {
+		let calls = 0;
+		const waits: number[] = [];
+		const fetchImpl = (async () => {
+			const fail = failures[calls++];
+			if (fail) throw fail;
+			return new Response(JSON.stringify({ success: true, errors: [], result: [{ results: [{ n: 1 }], success: true }] }));
+		}) as unknown as typeof fetch;
+		const db = createHttpD1({ accountId: 'a', databaseId: 'd', apiToken: 't', fetch: fetchImpl, sleep: async (ms) => void waits.push(ms) });
+		return { db, waits, calls: () => calls };
+	};
+
+	test('2026-10-02, family dangling-media: ConnectionRefused on a wake, then the network is back — the read answers', async () => {
+		const { db, waits, calls } = flaky([refused(), refused()]);
+		expect(await db.prepare('SELECT 1 n').first('n')).toBe(1);
+		expect(calls()).toBe(3);
+		expect(waits).toEqual([2_000, 10_000]);
+	});
+
+	test('still refused after every wait: the original error, not a swallowed one', async () => {
+		const { db, waits } = flaky(Array.from({ length: 5 }, refused));
+		await expect(db.prepare('SELECT 1').all()).rejects.toThrow('Unable to connect');
+		expect(waits).toEqual([2_000, 10_000, 30_000, 60_000]);
+	});
+
+	test('a reset after connecting may have run the write — thrown at once, never retried', async () => {
+		const reset = Object.assign(new TypeError('socket closed'), { code: 'ECONNRESET' });
+		const { db, calls } = flaky([reset]);
+		await expect(db.prepare('INSERT INTO t VALUES (1)').run()).rejects.toThrow('socket closed');
+		expect(calls()).toBe(1);
+	});
+
+	test('an unresolvable host is a never-connected failure too, and a timeout is not', async () => {
+		const dns = Object.assign(new TypeError('getaddrinfo ENOTFOUND api.cloudflare.com'), { code: 'ENOTFOUND' });
+		expect(await flaky([dns]).db.prepare('SELECT 1 n').first('n')).toBe(1);
+		const timeout = flaky([new DOMException('The operation timed out.', 'TimeoutError')]);
+		await expect(timeout.db.prepare('SELECT 1').all()).rejects.toThrow('timed out');
+		expect(timeout.calls()).toBe(1);
+	});
+});

package/src/server/d1/http.ts

@@ -53,6 +53,33 @@ export interface HttpD1Options {
 	fetch?: typeof fetch;
 	/** Defaults to `https://api.cloudflare.com/client/v4`. */
 	apiBase?: string;
+	/**
+	 * The waits, in ms, before each retry of a request that never CONNECTED — see
+	 * {@link neverConnected}. Default {@link CONNECT_RETRY_DELAYS_MS}; `[]` fails on the first.
+	 */
+	connectRetryDelaysMs?: readonly number[];
+	/** Injected for tests. Defaults to a `setTimeout` promise. */
+	sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * ~1m45s of waiting, which outlasts a Mac's network coming back after a wake. Measured
+ * 2026-10-02 16:15Z: family's once-a-day `dangling-media` job fired as the Mac woke, its first
+ * D1 read was `ConnectionRefused`, and the job exited 1 — red for a whole day over one blip.
+ */
+export const CONNECT_RETRY_DELAYS_MS: readonly number[] = [2_000, 10_000, 30_000, 60_000];
+
+/**
+ * 🔴 `true` only for a failure that happened BEFORE the request reached Cloudflare — refused,
+ * unresolvable, unroutable — so retrying it cannot run a write twice. A reset or a timeout
+ * after connecting may have executed the statement, and is thrown as it is.
+ */
+export function neverConnected(err: unknown): boolean {
+	const code = (err as { code?: unknown } | null)?.code;
+	return (
+		typeof code === 'string' &&
+		['ConnectionRefused', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'FailedToOpenSocket', 'ENETUNREACH', 'EHOSTUNREACH', 'ENETDOWN'].includes(code)
+	);
 }
 
 interface WireResult {
@@ -97,14 +124,28 @@ export function httpD1Binding(options: HttpD1Options): D1BindingLike {
 	const doFetch = options.fetch ?? fetch;
 	const base = `${options.apiBase ?? 'https://api.cloudflare.com/client/v4'}/accounts/${options.accountId}/d1/database/${options.databaseId}`;
 	const timeoutMs = options.timeoutMs ?? 30_000;
+	const retryDelays = options.connectRetryDelaysMs ?? CONNECT_RETRY_DELAYS_MS;
+	const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+	const send = async (path: '/query' | '/raw', body: unknown): Promise<Response> => {
+		for (let attempt = 0; ; attempt++) {
+			try {
+				return await doFetch(`${base}${path}`, {
+					method: 'POST',
+					headers: { authorization: `Bearer ${options.apiToken}`, 'content-type': 'application/json' },
+					body: JSON.stringify(body),
+					signal: AbortSignal.timeout(timeoutMs),
+				});
+			} catch (err) {
+				const wait = retryDelays[attempt];
+				if (wait === undefined || !neverConnected(err)) throw err;
+				await sleep(wait);
+			}
+		}
+	};
 
 	const post = async (path: '/query' | '/raw', body: unknown): Promise<WireResult[]> => {
-		const response = await doFetch(`${base}${path}`, {
-			method: 'POST',
-			headers: { authorization: `Bearer ${options.apiToken}`, 'content-type': 'application/json' },
-			body: JSON.stringify(body),
-			signal: AbortSignal.timeout(timeoutMs),
-		});
+		const response = await send(path, body);
 		const envelope = (await response.json().catch(() => null)) as Envelope | null;
 		if (!response.ok || !envelope || envelope.success === false) {
 			const message =

package/src/server/youtube/youtubeApi.spec.ts

@@ -0,0 +1,90 @@
+/**
+ * The YouTube Data API reader (forge task 2349), against a fake Google — no request leaves.
+ *
+ * What is worth pinning: a page comes out normalized (no envelope, no tombstones), every page of
+ * a playlist is walked and a cap is SAID rather than silently applied, lengths are read in
+ * batches of 50, and a refusal carries the fix rather than a bare status.
+ */
+import { describe, expect, test } from "bun:test";
+import { collectYouTubePages, createYouTubeApi, youtubeThumbnailUrl } from "./youtubeApi";
+
+type Handler = (url: URL) => { status?: number; body: unknown };
+
+const fakeGoogle = (handler: Handler) => {
+	const seen: URL[] = [];
+	const fetchImpl = async (input: string): Promise<Response> => {
+		const url = new URL(input);
+		seen.push(url);
+		const { status = 200, body } = handler(url);
+		return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+	};
+	return { seen, api: createYouTubeApi(fetchImpl) };
+};
+
+const item = (videoId: string, title = `Video ${videoId}`) => ({
+	snippet: { title, videoOwnerChannelTitle: "Chan", thumbnails: {} },
+	contentDetails: { videoId },
+});
+
+describe("createYouTubeApi", () => {
+	test("a playlist page is normalized, a tombstone is dropped, and a missing picture falls back to YouTube's", async () => {
+		const { api, seen } = fakeGoogle(() => ({
+			body: { items: [item("a1"), item("gone", "Deleted video")], nextPageToken: "p2" },
+		}));
+		const page = await api.playlistItems("tok", "PL1");
+		expect(page).toEqual({
+			status: "ok",
+			value: {
+				nextPageToken: "p2",
+				items: [
+					{
+						videoId: "a1",
+						title: "Video a1",
+						channelTitle: "Chan",
+						thumbnail: youtubeThumbnailUrl("a1"),
+						url: "https://www.youtube.com/watch?v=a1",
+					},
+				],
+			},
+		});
+		expect(seen[0]?.pathname).toBe("/youtube/v3/playlistItems");
+		expect(seen[0]?.searchParams.get("playlistId")).toBe("PL1");
+	});
+
+	test("🔴 every page is walked, and a list stopped at the cap SAYS so", async () => {
+		const { api } = fakeGoogle((url) => {
+			const at = Number(url.searchParams.get("pageToken") ?? "0");
+			return { body: { items: [item(`v${at}`)], nextPageToken: String(at + 1) } };
+		});
+		const capped = await collectYouTubePages((pt) => api.playlistItems("tok", "PL1", pt), 3);
+		expect(capped).toMatchObject({ status: "ok", truncated: true });
+		expect(capped.status === "ok" ? capped.items.map((v) => v.videoId) : []).toEqual(["v0", "v1", "v2"]);
+
+		const { api: short } = fakeGoogle(() => ({ body: { items: [item("only")] } }));
+		expect(await collectYouTubePages((pt) => short.playlistItems("tok", "PL1", pt))).toMatchObject({
+			status: "ok",
+			truncated: false,
+		});
+	});
+
+	test("lengths are read 50 ids at a time, and an ISO duration becomes seconds", async () => {
+		const { api, seen } = fakeGoogle((url) => ({
+			body: {
+				items: (url.searchParams.get("id") ?? "").split(",").map((id) => ({ id, contentDetails: { duration: "PT1H2M3S" } })),
+			},
+		}));
+		const ids = Array.from({ length: 51 }, (_, i) => `id${i}`);
+		const lengths = await api.durations("tok", ids);
+		expect(seen).toHaveLength(2);
+		expect(lengths.status === "ok" ? lengths.value.get("id50") : null).toBe(3723);
+	});
+
+	test("🔴 a refusal names the fix — a 403 says quota or API-not-enabled, a 401 says reconnect", async () => {
+		const forbidden = await fakeGoogle(() => ({ status: 403, body: { error: { message: "quotaExceeded" } } })).api.playlists("tok");
+		expect(forbidden).toMatchObject({ status: "error", reason: "YouTube refused the read: quotaExceeded" });
+		expect(forbidden.status === "error" ? forbidden.fix : "").toMatch(/quota/);
+
+		const lapsed = await fakeGoogle(() => ({ status: 401, body: {} })).api.playlists("tok");
+		expect(lapsed.status === "error" ? lapsed.fix : "").toMatch(/Connect again/);
+	});
+});