cursedbelt-server 4.42.0 → 4.43.1

package/README.md

@@ -81,7 +81,8 @@ after typing it (task 2138). `src/server/master-lock/sessions.ts` has the why.
 
 ## Standards
 
-`docs/retention.md`, `docs/activity.md`, `docs/notifications.md`, `docs/engagement.md` — the
+`docs/retention.md`, `docs/activity.md`, `docs/notifications.md`, `docs/engagement.md`,
+`docs/ctgr.md` (the GET-tunnel, getOnly and CSRF — register routes through `buildRoutes`) — the
 contracts every app that uses those modules is agreeing to. Cite them from an app with the
 package prefix (`cursedbelt-server/docs/retention.md`).
 

package/dist/server/youtube/youtubeApi.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `cursedbelt-server/youtube` — the YouTube Data API v3, READ half only, normalized.
+ *
+ * Arrived in 4.43.0 (forge task 2349) from Music (`apps/music/src/server/tube/youtubeApi.ts`),
+ * where it was already catalog-agnostic, so Collections could list the same owner's playlists
+ * without a second copy. Worker-safe: it is `fetch` and nothing else.
+ *
+ * 🔴 **It never writes to YouTube.** The scope a consumer asks for is
+ * {@link YOUTUBE_READONLY_SCOPE}, and there is no code path here that could create, reorder or
+ * delete anything in the owner's account. The failure mode of a write-back mistake is
+ * destroying a playlist on a service no app here owns.
+ *
+ * ── Quota ────────────────────────────────────────────────────────────────────────────────
+ * Every call costs Data API quota (10,000 units/day by default; a `playlistItems` page costs 1,
+ * a `search` 100 — which is why there is no search). Playback is not the Data API, so a
+ * consumer reads once, when the owner asks, and never on a timer.
+ *
+ * Every read that fails says why AND what to do ({@link TubeApiResult}) — the same law
+ * `./google-oauth` runs on. Normalized shapes come out, so no route and no browser ever touches
+ * a Google response envelope.
+ */
+import type { FetchLike } from "../google-oauth/googleOAuth";
+/** YouTube's own still for a video — the fallback when a playlist row carries no thumbnail. */
+export declare const youtubeThumbnailUrl: (videoId: string) => string;
+/** Read-only, and nothing else. See the header. */
+export declare const YOUTUBE_READONLY_SCOPE = "https://www.googleapis.com/auth/youtube.readonly";
+export interface TubeApiVideo {
+    videoId: string;
+    title: string;
+    channelTitle: string;
+    thumbnail: string;
+    url: string;
+}
+export interface TubeApiPlaylist {
+    id: string;
+    title: string;
+    description: string;
+    thumbnail: string;
+    itemCount: number;
+}
+export interface TubeApiChannel {
+    id: string;
+    title: string;
+    thumbnail: string;
+}
+export interface TubePage<T> {
+    items: T[];
+    nextPageToken?: string;
+}
+/** A read that failed says why and what to do — the same law the token store runs on. */
+export type TubeApiResult<T> = {
+    status: "ok";
+    value: T;
+} | {
+    status: "error";
+    reason: string;
+    fix: string;
+};
+export declare function createYouTubeApi(fetchImpl?: FetchLike): {
+    /** Who this grant belongs to — the name shown beside "Connected". */
+    channel(accessToken: string): Promise<TubeApiResult<TubeApiChannel | null>>;
+    playlists(accessToken: string, pageToken?: string): Promise<TubeApiResult<TubePage<TubeApiPlaylist>>>;
+    playlistItems(accessToken: string, playlistId: string, pageToken?: string): Promise<TubeApiResult<TubePage<TubeApiVideo>>>;
+    /**
+     * How long each video is, in seconds — `playlistItems` does not say. Up to 50 ids per
+     * call (1 quota unit each call), so a 200-video playlist costs four. A video YouTube no
+     * longer returns (private since, deleted) is simply absent from the map.
+     */
+    durations(accessToken: string, videoIds: readonly string[]): Promise<TubeApiResult<Map<string, number>>>;
+    /**
+     * Liked videos. Not a playlist read: the "LL" pseudo-playlist is not reliably
+     * listable through `playlistItems`, whereas `videos?myRating=like` is the documented
+     * way to ask and costs the same.
+     */
+    liked(accessToken: string, pageToken?: string): Promise<TubeApiResult<TubePage<TubeApiVideo>>>;
+};
+export type YouTubeApi = ReturnType<typeof createYouTubeApi>;
+/**
+ * Walk every page of a paginated read, stopping at `maxPages` and SAYING SO (`truncated`).
+ *
+ * A list that quietly stops at the cap is indistinguishable from one that is exactly that long,
+ * so the cap is reported. 40 pages of 50 is 2,000 videos — larger than any real playlist, and
+ * small enough that a pathological account cannot turn one button into a thousand API calls.
+ */
+export declare function collectYouTubePages<T>(fetchPage: (pageToken?: string) => Promise<TubeApiResult<TubePage<T>>>, maxPages?: number): Promise<{
+    status: "ok";
+    items: T[];
+    truncated: boolean;
+} | {
+    status: "error";
+    reason: string;
+    fix: string;
+}>;

package/dist/server/youtube/youtubeApi.js

@@ -0,0 +1,219 @@
+const API_BASE = "https://www.googleapis.com/youtube/v3";
+/** YouTube's own still for a video — the fallback when a playlist row carries no thumbnail. */
+export const youtubeThumbnailUrl = (videoId) => videoId ? `https://i.ytimg.com/vi/${videoId}/mqdefault.jpg` : "";
+/** Read-only, and nothing else. See the header. */
+export const YOUTUBE_READONLY_SCOPE = "https://www.googleapis.com/auth/youtube.readonly";
+/**
+ * `medium` first, deliberately. `default` is 120×90 and looks like a thumbnail from 2009 on
+ * a retina phone; `maxres` does not exist for most videos, so preferring it would leave
+ * half a list with no picture at all.
+ */
+const pickThumb = (thumbs) => thumbs?.medium?.url || thumbs?.high?.url || thumbs?.standard?.url || thumbs?.default?.url || "";
+const watchUrl = (videoId) => `https://www.youtube.com/watch?v=${videoId}`;
+/**
+ * A playlist keeps a tombstone for a video the uploader deleted or made private. It has a
+ * title and a thumbnail and NOTHING that will ever play, so importing it would put dead
+ * rows in the owner's list that look exactly like live ones until pressed.
+ */
+const UNPLAYABLE_TITLES = new Set(["Private video", "Deleted video"]);
+async function get(accessToken, path, params, fetchImpl) {
+    let res;
+    try {
+        res = await fetchImpl(`${API_BASE}/${path}?${new URLSearchParams(params).toString()}`, {
+            headers: { authorization: `Bearer ${accessToken}` },
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (err) {
+        return {
+            status: "error",
+            reason: `could not reach YouTube: ${err instanceof Error ? err.message : String(err)}`,
+            fix: "check this machine's internet connection and try again",
+        };
+    }
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        const detail = body.error?.message || `HTTP ${res.status}`;
+        // 403 is overwhelmingly one of two things and they have different fixes, so the
+        // message says both rather than making the owner guess which.
+        if (res.status === 403) {
+            return {
+                status: "error",
+                reason: `YouTube refused the read: ${detail}`,
+                fix: "this is either the daily Data API quota (it resets at midnight Pacific) or the YouTube Data API v3 not being enabled for this Google Cloud project",
+            };
+        }
+        return {
+            status: "error",
+            reason: `YouTube refused the read: ${detail}`,
+            fix: res.status === 401
+                ? "the connection has lapsed — press Disconnect and Connect again"
+                : "try again; if it persists, check the YouTube API status",
+        };
+    }
+    return { status: "ok", value: body };
+}
+const rows = (body) => (Array.isArray(body.items) ? body.items : []);
+const nextToken = (body) => typeof body.nextPageToken === "string" ? { nextPageToken: body.nextPageToken } : {};
+/** `PT1H2M3S` → 3723. YouTube's ISO 8601 durations never carry years or months. */
+function parseIsoDuration(value) {
+    const m = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/.exec(value);
+    if (!m || value === "P" || value.endsWith("T"))
+        return null;
+    const [, d, h, min, s] = m.map((x) => Number(x ?? 0));
+    return d * 86_400 + h * 3600 + min * 60 + s;
+}
+export function createYouTubeApi(fetchImpl = fetch) {
+    return {
+        /** Who this grant belongs to — the name shown beside "Connected". */
+        async channel(accessToken) {
+            const res = await get(accessToken, "channels", { part: "snippet", mine: "true" }, fetchImpl);
+            if (res.status !== "ok")
+                return res;
+            const first = rows(res.value)[0];
+            if (!first)
+                return { status: "ok", value: null };
+            const snippet = first.snippet ?? {};
+            return {
+                status: "ok",
+                value: {
+                    id: String(first.id ?? ""),
+                    title: String(snippet.title ?? ""),
+                    thumbnail: pickThumb(snippet.thumbnails),
+                },
+            };
+        },
+        async playlists(accessToken, pageToken) {
+            const res = await get(accessToken, "playlists", {
+                part: "snippet,contentDetails",
+                mine: "true",
+                maxResults: "50",
+                ...(pageToken ? { pageToken } : {}),
+            }, fetchImpl);
+            if (res.status !== "ok")
+                return res;
+            return {
+                status: "ok",
+                value: {
+                    ...nextToken(res.value),
+                    items: rows(res.value).map((p) => {
+                        const snippet = p.snippet ?? {};
+                        const details = p.contentDetails ?? {};
+                        return {
+                            id: String(p.id ?? ""),
+                            title: String(snippet.title ?? ""),
+                            description: String(snippet.description ?? ""),
+                            thumbnail: pickThumb(snippet.thumbnails),
+                            itemCount: typeof details.itemCount === "number" ? details.itemCount : 0,
+                        };
+                    }),
+                },
+            };
+        },
+        async playlistItems(accessToken, playlistId, pageToken) {
+            const res = await get(accessToken, "playlistItems", {
+                part: "snippet,contentDetails",
+                playlistId,
+                maxResults: "50",
+                ...(pageToken ? { pageToken } : {}),
+            }, fetchImpl);
+            if (res.status !== "ok")
+                return res;
+            return {
+                status: "ok",
+                value: {
+                    ...nextToken(res.value),
+                    items: rows(res.value)
+                        .map((item) => {
+                        const snippet = item.snippet ?? {};
+                        const details = item.contentDetails ?? {};
+                        const resource = snippet.resourceId;
+                        const videoId = String(details.videoId ?? resource?.videoId ?? "");
+                        return {
+                            videoId,
+                            title: String(snippet.title ?? ""),
+                            channelTitle: String(snippet.videoOwnerChannelTitle ?? ""),
+                            thumbnail: pickThumb(snippet.thumbnails) || youtubeThumbnailUrl(videoId),
+                            url: watchUrl(videoId),
+                        };
+                    })
+                        .filter((v) => v.videoId && !UNPLAYABLE_TITLES.has(v.title)),
+                },
+            };
+        },
+        /**
+         * How long each video is, in seconds — `playlistItems` does not say. Up to 50 ids per
+         * call (1 quota unit each call), so a 200-video playlist costs four. A video YouTube no
+         * longer returns (private since, deleted) is simply absent from the map.
+         */
+        async durations(accessToken, videoIds) {
+            const out = new Map();
+            for (let at = 0; at < videoIds.length; at += 50) {
+                const res = await get(accessToken, "videos", { part: "contentDetails", id: videoIds.slice(at, at + 50).join(","), maxResults: "50" }, fetchImpl);
+                if (res.status !== "ok")
+                    return res;
+                for (const v of rows(res.value)) {
+                    const seconds = parseIsoDuration(String(v.contentDetails?.duration ?? ""));
+                    if (seconds !== null)
+                        out.set(String(v.id ?? ""), seconds);
+                }
+            }
+            return { status: "ok", value: out };
+        },
+        /**
+         * Liked videos. Not a playlist read: the "LL" pseudo-playlist is not reliably
+         * listable through `playlistItems`, whereas `videos?myRating=like` is the documented
+         * way to ask and costs the same.
+         */
+        async liked(accessToken, pageToken) {
+            const res = await get(accessToken, "videos", {
+                part: "snippet",
+                myRating: "like",
+                maxResults: "50",
+                ...(pageToken ? { pageToken } : {}),
+            }, fetchImpl);
+            if (res.status !== "ok")
+                return res;
+            return {
+                status: "ok",
+                value: {
+                    ...nextToken(res.value),
+                    items: rows(res.value)
+                        .map((v) => {
+                        const snippet = v.snippet ?? {};
+                        const videoId = String(v.id ?? "");
+                        return {
+                            videoId,
+                            title: String(snippet.title ?? ""),
+                            channelTitle: String(snippet.channelTitle ?? ""),
+                            thumbnail: pickThumb(snippet.thumbnails) || youtubeThumbnailUrl(videoId),
+                            url: watchUrl(videoId),
+                        };
+                    })
+                        .filter((v) => v.videoId),
+                },
+            };
+        },
+    };
+}
+/**
+ * Walk every page of a paginated read, stopping at `maxPages` and SAYING SO (`truncated`).
+ *
+ * A list that quietly stops at the cap is indistinguishable from one that is exactly that long,
+ * so the cap is reported. 40 pages of 50 is 2,000 videos — larger than any real playlist, and
+ * small enough that a pathological account cannot turn one button into a thousand API calls.
+ */
+export async function collectYouTubePages(fetchPage, maxPages = 40) {
+    const items = [];
+    let pageToken;
+    let pages = 0;
+    do {
+        const page = await fetchPage(pageToken);
+        if (page.status !== "ok")
+            return page;
+        items.push(...page.value.items);
+        pageToken = page.value.nextPageToken;
+        pages += 1;
+    } while (pageToken && pages < maxPages);
+    return { status: "ok", items, truncated: Boolean(pageToken) };
+}

package/dist/server/youtube/ytdlp.d.ts

@@ -0,0 +1,129 @@
+/** `$STATE/bin/yt-dlp` — one binary for every app on the Mac. `state` is the generation's state root. */
+export declare function ytDlpPath(state: string): string;
+/** yt-dlp's cache (the player JS it has already solved), kept with the generation's state. */
+export declare function ytDlpCacheDir(state: string): string;
+/**
+ * What one app downloads. Music's is audio as YouTube serves it; Collections' is H.264 + AAC
+ * in MP4. Everything else about a run is the same.
+ */
+export interface YtDlpProfile {
+    /** yt-dlp's `-f` selector. */
+    format: string;
+    /** Arguments placed after the format — e.g. `--merge-output-format mp4`. */
+    extraArgs?: readonly string[];
+    /** `--max-filesize`, in yt-dlp's own notation (`200M`, `4G`). */
+    maxFilesize: string;
+    /** What a file is called in a sentence: "That video's audio …", "That video …". */
+    noun: string;
+}
+/** What yt-dlp says about a video — the fields an app reads. */
+export interface YtInfo {
+    id: string;
+    title?: string;
+    /** Set for YouTube Music tracks (the "Topic" channels): the song, not the video title. */
+    track?: string;
+    artist?: string;
+    creator?: string;
+    channel?: string;
+    uploader?: string;
+    album?: string;
+    release_year?: number;
+    /** `YYYYMMDD`. */
+    upload_date?: string;
+    duration?: number;
+    thumbnail?: string;
+    ext?: string;
+    filepath?: string;
+    /** The chosen video stream's codec — `avc1.640028`, `vp09…`, `none` for audio. */
+    vcodec?: string;
+    acodec?: string;
+    width?: number;
+    height?: number;
+}
+/** One finished download. `path` is inside `dir`; {@link dispose} removes both. */
+export interface YtDownload {
+    path: string;
+    /** `webm`, `m4a`, `mp4` — what the file IS, for its name and its MIME type. */
+    extension: string;
+    info: YtInfo;
+    /** The temporary directory the file is in — a caller may write a re-encode beside it. */
+    dir: string;
+    dispose(): Promise<void>;
+}
+/** Fetch one video. `onProgress` gets the fraction of the file received, 0–1. */
+export type YtDlpFetch = (videoId: string, onProgress?: (fraction: number) => void) => Promise<YtDownload>;
+/**
+ * Why a download failed, sorted by what the owner can do about it.
+ *
+ *  · `missing`     — no binary, and installing one failed.
+ *  · `outdated`    — YouTube changed and this yt-dlp has not caught up. Update fixes it.
+ *  · `blocked`     — YouTube is refusing this Mac as a bot. Time fixes it, usually.
+ *  · `unavailable` — the video itself: private, deleted, region-locked, members-only.
+ *  · `too-big`     — over the one-download ceiling.
+ *  · `failed`      — anything else, with yt-dlp's own last error line.
+ */
+export type YtDlpFailure = "missing" | "outdated" | "blocked" | "unavailable" | "too-big" | "failed";
+export declare class YtDlpError extends Error {
+    readonly kind: YtDlpFailure;
+    constructor(message: string, kind: YtDlpFailure);
+}
+/** A failure no retry and no update can change — the video's own fault, or the ceiling. */
+export declare const isFinalYtDlpFailure: (kind: YtDlpFailure) => boolean;
+/**
+ * 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 declare function parseYtProgress(line: string): number | null;
+/** The info JSON printed after the file is in place, or `null` for any other line. */
+export declare function parseYtInfo(line: string): YtInfo | null;
+/** Sort a failure by what can be done about it — see {@link YtDlpFailure}. */
+export declare function classifyYtDlpFailure(stderr: string): YtDlpFailure;
+/** The arguments for one download. Exported so a test pins the flags that matter. */
+export declare function ytDlpArgs(videoId: string, outDir: string, profile: Pick<YtDlpProfile, "format" | "extraArgs" | "maxFilesize">, options?: {
+    cacheDir?: string;
+    jsRuntime?: string;
+}): string[];
+/** Run a program, handing each stdout line over as it arrives. Injected in tests. */
+export type RunLines = (binary: string, args: string[], onLine: (line: string) => void) => Promise<{
+    code: number;
+    stderr: string;
+}>;
+/**
+ * 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 declare function installYtDlp(binary: string, fetchImpl?: typeof fetch): Promise<void>;
+/** `yt-dlp -U` — the standalone build updates itself in place. Resolves to what it printed. */
+export declare function updateYtDlp(binary: string, run?: RunLines): Promise<string>;
+/**
+ * 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 declare function installOrUpdateYtDlp(binary: string): Promise<string>;
+export interface YtDlpOptions {
+    binary: string;
+    profile: YtDlpProfile;
+    /** The ONE command, runnable from any directory, that installs or updates yt-dlp for this app. */
+    fixCommand: string;
+    /** The prefix of every log line — `[music]`, `[collections]`. */
+    label?: string;
+    cacheDir?: string;
+    /** The Bun binary yt-dlp may use for YouTube's JS challenges. Defaults to this process's. */
+    jsRuntime?: string;
+    /** Where each download's temporary directory is made. Defaults to the OS temp dir. */
+    tmpRoot?: string;
+    /** Injected in tests — the process, the installer, the updater, the clock. */
+    run?: RunLines;
+    install?: (binary: string) => Promise<void>;
+    update?: (binary: string) => Promise<string>;
+    now?: () => number;
+    log?: (line: string) => void;
+}
+/**
+ * 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 declare function createYtDlp(options: YtDlpOptions): YtDlpFetch;