youtube-knowledge-mcp 2.0.2 → 2.2.0

package/dist/utils/thumbnail-entry.js

@@ -0,0 +1,119 @@
+import { rm } from 'node:fs/promises';
+import { imageFormatSchema, } from '../thumbnail-schemas.js';
+import { throwIfAborted } from './context.js';
+import { asYouTubeError } from './errors.js';
+import { largestThumbnail } from './flat-listing.js';
+import { MAX_IMAGE_BYTES } from './image-fetch.js';
+import { writeFileAtomic } from './json-file.js';
+import { climb, videoRungs } from './thumbnail-ladder.js';
+import { channelImagePath, relativeFile, videoThumbnailPath } from './thumbnail-paths.js';
+import { channelImageFile, entryPath, isIntact } from './thumbnail-store.js';
+const ALL_FORMATS = imageFormatSchema.options;
+/**
+ * Per-video entries, reconciled against the files actually on disk.
+ *
+ * A record that says `saved` whose file is missing or the wrong size goes back
+ * to `pending`; a video in today's listing that has no record gets one; and a
+ * record for a video not listed today is kept, since its file is still a
+ * thumbnail and the tab may simply not have been requested this time.
+ */
+export async function reconciled(channelId, existing, listings) {
+    const entries = new Map();
+    for (const [videoId, recorded] of Object.entries(existing?.videos ?? {})) {
+        const intact = await isIntact(entryPath(channelId, recorded), recorded.bytes);
+        entries.set(videoId, intact ? recorded : { ...recorded, state: 'pending' });
+    }
+    for (const { tab, videos } of listings) {
+        for (const video of videos) {
+            if (!entries.has(video.id))
+                entries.set(video.id, pendingEntry(tab, video));
+        }
+    }
+    return entries;
+}
+function pendingEntry(tab, video) {
+    const listed = largestThumbnail(video.thumbnails ?? []);
+    const portrait = listed?.width !== null &&
+        listed?.width !== undefined &&
+        listed.height !== null &&
+        listed.height !== undefined &&
+        listed.height > listed.width;
+    return {
+        videoId: video.id,
+        title: video.title,
+        url: video.url,
+        tab,
+        isShort: tab === 'shorts' || portrait,
+        durationSeconds: video.duration,
+        ...(video.liveStatus === undefined ? {} : { liveStatus: video.liveStatus }),
+        ...(listed === undefined ? {} : { listedUrl: listed.url }),
+        ...(listed?.width === null || listed?.width === undefined ? {} : { listedWidth: listed.width }),
+        ...(listed?.height === null || listed?.height === undefined
+            ? {}
+            : { listedHeight: listed.height }),
+        state: 'pending',
+    };
+}
+export async function fetchOne(channelId, entry, quality) {
+    const listed = entry.listedUrl === undefined
+        ? undefined
+        : {
+            url: entry.listedUrl,
+            ...(entry.listedWidth === undefined ? {} : { width: entry.listedWidth }),
+            ...(entry.listedHeight === undefined ? {} : { height: entry.listedHeight }),
+        };
+    try {
+        const climbed = await climb(videoRungs(entry.videoId, listed, entry.isShort, quality), MAX_IMAGE_BYTES);
+        const path = videoThumbnailPath(channelId, entry.tab, entry.videoId, climbed.probe.format);
+        await replaceFile(path, climbed, (format) => videoThumbnailPath(channelId, entry.tab, entry.videoId, format));
+        return { ...withoutSaved(entry), state: 'saved', ...saved(channelId, path, climbed) };
+    }
+    catch (error) {
+        throwIfAborted();
+        return { ...withoutSaved(entry), state: 'failed', error: asYouTubeError(error).code };
+    }
+}
+export async function channelImage(channelId, kind, url, recorded) {
+    if (url === undefined)
+        return recorded;
+    if (recorded !== undefined &&
+        (await isIntact(channelImageFile(channelId, recorded), recorded.bytes))) {
+        return recorded;
+    }
+    try {
+        const climbed = await climb([{ variant: 'uncropped', url }], MAX_IMAGE_BYTES);
+        const path = channelImagePath(channelId, kind, climbed.probe.format);
+        await replaceFile(path, climbed, (format) => channelImagePath(channelId, kind, format));
+        return { kind, state: 'saved', ...saved(channelId, path, climbed) };
+    }
+    catch (error) {
+        throwIfAborted();
+        return { kind, state: 'failed', error: asYouTubeError(error).code };
+    }
+}
+/** Write the image, and remove an earlier file of the same name in another format. */
+async function replaceFile(path, climbed, pathFor) {
+    await writeFileAtomic(path, climbed.bytes);
+    for (const format of ALL_FORMATS) {
+        if (format !== climbed.probe.format)
+            await rm(pathFor(format), { force: true });
+    }
+}
+function saved(channelId, path, climbed) {
+    return {
+        file: relativeFile(channelId, path),
+        sourceUrl: climbed.rung.url,
+        variant: climbed.rung.variant,
+        width: climbed.probe.width,
+        height: climbed.probe.height,
+        bytes: climbed.bytes.byteLength,
+        format: climbed.probe.format,
+        fetchedAt: new Date().toISOString(),
+    };
+}
+/** The entry with every field of a previous save removed, so a failure cannot keep stale sizes. */
+function withoutSaved(entry) {
+    const { file: _file, sourceUrl: _sourceUrl, variant: _variant, width: _width, height: _height, bytes: _bytes, format: _format, fetchedAt: _fetchedAt, error: _error, ...rest } = entry;
+    return rest;
+}
+//# sourceMappingURL=thumbnail-entry.js.map

package/dist/utils/thumbnail-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-entry.js","sourceRoot":"","sources":["../../src/utils/thumbnail-entry.ts"],"names":[],"mappings":"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"}

package/dist/utils/thumbnail-fetch.d.ts

@@ -0,0 +1,37 @@
+import type { ThumbnailManifest, ThumbnailQuality, ThumbnailTab } from '../thumbnail-schemas.js';
+import { type TabListing } from './thumbnail-entry.js';
+export type { TabListing } from './thumbnail-entry.js';
+import type { ChannelInfo } from './youtube.js';
+/**
+ * Fetching a channel's thumbnails, resumably.
+ *
+ * Shaped like a brain build, and for the same reason: several hundred images
+ * is several hundred requests, so the job gets interrupted — cancelled by the
+ * client, throttled by YouTube, or killed with the editor. Per-image state
+ * rather than one flag, checkpoints rather than one write at the end, a
+ * failed image costing only itself, and a second call that continues.
+ */
+export declare const CHECKPOINT_EVERY_ITEMS = 20;
+export declare const RATE_LIMIT_TOLERANCE = 3;
+export interface FetchThumbnailsOptions {
+    channel: ChannelInfo;
+    listings: TabListing[];
+    existing: ThumbnailManifest | undefined;
+    quality: ThumbnailQuality;
+}
+export interface FetchThumbnailsResult {
+    manifest: ThumbnailManifest;
+    considered: number;
+    fetched: number;
+    skipped: number;
+    failed: number;
+    failures: {
+        videoId: string;
+        tab: ThumbnailTab;
+        error: string;
+    }[];
+    stoppedEarly: boolean;
+    stopReason?: string;
+}
+export declare function fetchChannelThumbnails(options: FetchThumbnailsOptions): Promise<FetchThumbnailsResult>;
+//# sourceMappingURL=thumbnail-fetch.d.ts.map

package/dist/utils/thumbnail-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-fetch.d.ts","sourceRoot":"","sources":["../../src/utils/thumbnail-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGjG,OAAO,EAAsC,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAE3F,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAOvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;GAQG;AAEH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACxC,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClE,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAiFhC"}

package/dist/utils/thumbnail-fetch.js

@@ -0,0 +1,89 @@
+import { inBatches } from './batches.js';
+import { reportProgress, throwIfAborted } from './context.js';
+import { channelImage, fetchOne, reconciled } from './thumbnail-entry.js';
+import { THUMBNAIL_MANIFEST_VERSION, computeThumbnailStats, writeThumbnailManifest, } from './thumbnail-store.js';
+import { concurrencyState } from './ytdlp.js';
+/**
+ * Fetching a channel's thumbnails, resumably.
+ *
+ * Shaped like a brain build, and for the same reason: several hundred images
+ * is several hundred requests, so the job gets interrupted — cancelled by the
+ * client, throttled by YouTube, or killed with the editor. Per-image state
+ * rather than one flag, checkpoints rather than one write at the end, a
+ * failed image costing only itself, and a second call that continues.
+ */
+export const CHECKPOINT_EVERY_ITEMS = 20;
+export const RATE_LIMIT_TOLERANCE = 3;
+export async function fetchChannelThumbnails(options) {
+    const { channel, listings, existing, quality } = options;
+    const { channelId } = channel;
+    const createdAt = existing?.createdAt ?? new Date().toISOString();
+    const tabs = [...new Set([...(existing?.tabs ?? []), ...listings.map((l) => l.tab)])];
+    const entries = await reconciled(channelId, existing, listings);
+    const images = { avatar: existing?.avatar, banner: existing?.banner };
+    const save = async () => {
+        const manifest = {
+            version: THUMBNAIL_MANIFEST_VERSION,
+            channel,
+            tabs,
+            quality,
+            createdAt,
+            updatedAt: new Date().toISOString(),
+            ...(images.avatar === undefined ? {} : { avatar: images.avatar }),
+            ...(images.banner === undefined ? {} : { banner: images.banner }),
+            videos: Object.fromEntries(entries),
+            stats: computeThumbnailStats([...entries.values()]),
+        };
+        await writeThumbnailManifest(manifest);
+        return manifest;
+    };
+    images.avatar = await channelImage(channelId, 'avatar', channel.avatarUrl, images.avatar);
+    images.banner = await channelImage(channelId, 'banner', channel.bannerUrl, images.banner);
+    const outstanding = [...entries.values()].filter((e) => e.state !== 'saved');
+    const failures = [];
+    let attempted = 0;
+    let fetched = 0;
+    let consecutiveThrottles = 0;
+    let stopReason;
+    try {
+        await inBatches(outstanding, concurrencyState().limit, async (entry) => {
+            if (stopReason !== undefined)
+                return;
+            throwIfAborted();
+            const updated = await fetchOne(channelId, entry, quality);
+            entries.set(entry.videoId, updated);
+            attempted++;
+            if (updated.state === 'saved')
+                fetched++;
+            else
+                failures.push({
+                    videoId: entry.videoId,
+                    tab: entry.tab,
+                    error: updated.error ?? 'FETCH_FAILED',
+                });
+            consecutiveThrottles = updated.error === 'RATE_LIMITED' ? consecutiveThrottles + 1 : 0;
+            if (consecutiveThrottles >= RATE_LIMIT_TOLERANCE)
+                stopReason = 'YouTube is rate limiting image downloads.';
+            reportProgress(attempted, outstanding.length, `Fetched ${attempted} of ${outstanding.length}`);
+            if (attempted % CHECKPOINT_EVERY_ITEMS === 0)
+                await save();
+        });
+    }
+    catch (error) {
+        // A cancelled job keeps what it fetched since the last checkpoint.
+        await save();
+        throw error;
+    }
+    const manifest = await save();
+    return {
+        manifest,
+        considered: entries.size,
+        fetched,
+        skipped: entries.size - outstanding.length,
+        failed: failures.length,
+        failures,
+        stoppedEarly: stopReason !== undefined,
+        ...(stopReason === undefined ? {} : { stopReason }),
+    };
+}
+//# sourceMappingURL=thumbnail-fetch.js.map

package/dist/utils/thumbnail-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-fetch.js","sourceRoot":"","sources":["../../src/utils/thumbnail-fetch.ts"],"names":[],"mappings":"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"}

package/dist/utils/thumbnail-ladder.d.ts

@@ -0,0 +1,44 @@
+import { type ImageProbe } from './image-dimensions.js';
+import type { ListedImage } from './flat-listing.js';
+import type { ThumbnailQuality } from '../thumbnail-schemas.js';
+/**
+ * Getting the best thumbnail YouTube will serve for one video.
+ *
+ * A flat channel listing offers each video's thumbnail at up to 720 pixels
+ * wide (verified against yt-dlp 2026.07.04). YouTube also serves a larger
+ * `maxresdefault.jpg` for many videos — the probed video returned one at
+ * 1280 wide — but not, as far as this code knows, for every video, and a
+ * missing one is not guaranteed to be a 404. So the ladder tries it and then
+ * checks what came back: an image is accepted only if it decodes and is wider
+ * than the listed one. Anything else falls through to the next rung. No
+ * behaviour of YouTube's is assumed that a rung could not verify for itself.
+ */
+export interface Rung {
+    variant: string;
+    url: string;
+    /** Accept the image only if it decodes wider than this. */
+    mustExceedWidth?: number;
+}
+export interface Climbed {
+    bytes: Buffer;
+    probe: ImageProbe;
+    rung: Rung;
+}
+/**
+ * The rungs for one video, best first.
+ *
+ * Shorts are listed with portrait thumbnails; whether `maxresdefault` exists
+ * for a short, or is portrait when it does, is not verified, so a short uses
+ * its listed image and the small landscape fallback only.
+ */
+export declare function videoRungs(videoId: string, listed: ListedImage | undefined, isShort: boolean, quality: ThumbnailQuality): Rung[];
+/**
+ * Fetch rungs in order and return the first acceptable image.
+ *
+ * A rung is accepted when it downloads, decodes as an image this server reads,
+ * and — where the rung demands it — is wider than the listed image. A 404 or
+ * an unacceptable image moves to the next rung; rate limiting, a timeout or a
+ * cancelled request stops the climb immediately.
+ */
+export declare function climb(rungs: Rung[], maxBytes: number): Promise<Climbed>;
+//# sourceMappingURL=thumbnail-ladder.d.ts.map

package/dist/utils/thumbnail-ladder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-ladder.d.ts","sourceRoot":"","sources":["../../src/utils/thumbnail-ladder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,IAAI;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,IAAI,CAAC;CACZ;AAQD;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,gBAAgB,GACxB,IAAI,EAAE,CAaR;AAKD;;;;;;;GAOG;AACH,wBAAsB,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgC7E"}

package/dist/utils/thumbnail-ladder.js

@@ -0,0 +1,68 @@
+import { probeImage } from './image-dimensions.js';
+import { fetchImage } from './image-fetch.js';
+import { YouTubeError } from './errors.js';
+const named = (videoId, variant, mustExceedWidth) => ({
+    variant,
+    url: `https://i.ytimg.com/vi/${videoId}/${variant}.jpg`,
+    ...(mustExceedWidth === undefined ? {} : { mustExceedWidth }),
+});
+/**
+ * The rungs for one video, best first.
+ *
+ * Shorts are listed with portrait thumbnails; whether `maxresdefault` exists
+ * for a short, or is portrait when it does, is not verified, so a short uses
+ * its listed image and the small landscape fallback only.
+ */
+export function videoRungs(videoId, listed, isShort, quality) {
+    const listedRung = listed === undefined ? [] : [{ variant: 'listed', url: listed.url }];
+    const fallback = named(videoId, 'hqdefault');
+    if (isShort)
+        return [...listedRung, fallback];
+    if (quality === 'listed')
+        return [...listedRung, fallback];
+    const best = named(videoId, 'maxresdefault', listed?.width ?? 200);
+    // With no listing to beat, the smaller named sizes are worth trying too.
+    return listed === undefined
+        ? [best, named(videoId, 'sddefault'), fallback]
+        : [best, ...listedRung, fallback];
+}
+/** The reasons to stop climbing: they are about the client, not the rung. */
+const ABORTING = new Set(['RATE_LIMITED', 'TIMEOUT', 'CANCELLED']);
+/**
+ * Fetch rungs in order and return the first acceptable image.
+ *
+ * A rung is accepted when it downloads, decodes as an image this server reads,
+ * and — where the rung demands it — is wider than the listed image. A 404 or
+ * an unacceptable image moves to the next rung; rate limiting, a timeout or a
+ * cancelled request stops the climb immediately.
+ */
+export async function climb(rungs, maxBytes) {
+    let last;
+    for (const rung of rungs) {
+        try {
+            const { bytes } = await fetchImage(rung.url, { maxBytes });
+            const probe = probeImage(bytes);
+            if (probe === undefined) {
+                last = new YouTubeError('FETCH_FAILED', 'The response was not an image this server can read.');
+                continue;
+            }
+            if (rung.mustExceedWidth !== undefined && probe.width <= rung.mustExceedWidth) {
+                last = new YouTubeError('NOT_FOUND', 'No larger image is available at that address.');
+                continue;
+            }
+            return { bytes, probe, rung };
+        }
+        catch (error) {
+            if (!(error instanceof YouTubeError))
+                throw error;
+            if (ABORTING.has(error.code))
+                throw error;
+            last = error;
+        }
+    }
+    throw (last ??
+        new YouTubeError('NOT_FOUND', 'No thumbnail address was available for this video.', {
+            nextStep: 'The listing carried no thumbnail; try again later.',
+        }));
+}
+//# sourceMappingURL=thumbnail-ladder.js.map

package/dist/utils/thumbnail-ladder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-ladder.js","sourceRoot":"","sources":["../../src/utils/thumbnail-ladder.ts"],"names":[],"mappings":"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"}

package/dist/utils/thumbnail-listing.d.ts

@@ -0,0 +1,16 @@
+import type { ThumbnailTab } from '../thumbnail-schemas.js';
+import type { TabListing } from './thumbnail-entry.js';
+/**
+ * List each tab. The uploads tab must list — every channel has one, so a
+ * failure there is worth reporting. Whether yt-dlp lists an empty shorts or
+ * streams tab or refuses it is not verified, so those failures are recorded
+ * per tab and the run continues.
+ */
+export declare function listTabs(channelUrl: string, tabs: ThumbnailTab[], maxVideos: number): Promise<{
+    listings: TabListing[];
+    tabErrors: {
+        tab: ThumbnailTab;
+        error: string;
+    }[];
+}>;
+//# sourceMappingURL=thumbnail-listing.d.ts.map

package/dist/utils/thumbnail-listing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-listing.d.ts","sourceRoot":"","sources":["../../src/utils/thumbnail-listing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,YAAY,EAAE,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;IAAC,SAAS,EAAE;QAAE,GAAG,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,CAAC,CAkBxF"}

package/dist/utils/thumbnail-listing.js

@@ -0,0 +1,26 @@
+import { asYouTubeError } from './errors.js';
+import { listVideos } from './youtube.js';
+/**
+ * List each tab. The uploads tab must list — every channel has one, so a
+ * failure there is worth reporting. Whether yt-dlp lists an empty shorts or
+ * streams tab or refuses it is not verified, so those failures are recorded
+ * per tab and the run continues.
+ */
+export async function listTabs(channelUrl, tabs, maxVideos) {
+    const base = channelUrl.replace(/\/+$/, '');
+    const listings = [];
+    const tabErrors = [];
+    for (const tab of tabs) {
+        try {
+            const videos = (await listVideos(`${base}/${tab}`, maxVideos)).slice(0, maxVideos);
+            listings.push({ tab, videos });
+        }
+        catch (error) {
+            if (tab === 'videos')
+                throw error;
+            tabErrors.push({ tab, error: asYouTubeError(error).code });
+        }
+    }
+    return { listings, tabErrors };
+}
+//# sourceMappingURL=thumbnail-listing.js.map

package/dist/utils/thumbnail-listing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-listing.js","sourceRoot":"","sources":["../../src/utils/thumbnail-listing.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,UAAU,EAAsB,MAAM,cAAc,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,UAAkB,EAClB,IAAoB,EACpB,SAAiB;IAEjB,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAiB,EAAE,CAAC;IAClC,MAAM,SAAS,GAA2C,EAAE,CAAC;IAE7D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,MAAM,GAAoB,CAAC,MAAM,UAAU,CAAC,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CACnF,CAAC,EACD,SAAS,CACV,CAAC;YACF,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,GAAG,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAC;YAClC,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}

package/dist/utils/thumbnail-paths.d.ts

@@ -0,0 +1,20 @@
+import type { ImageFormat } from './image-dimensions.js';
+import type { ThumbnailTab } from '../thumbnail-schemas.js';
+/**
+ * Every file a channel's thumbnails are made of.
+ *
+ * A sibling of the brains rather than inside them: deleting a brain removes
+ * its whole directory, and a channel's images should outlive its corpus. Keyed
+ * on the channel id, validated once here; a filename is the video id, also
+ * validated here; and the tab and format are closed enums. Nothing a caller or
+ * a hand-edited manifest supplies reaches a path unchecked.
+ */
+export declare function thumbnailsDir(): string;
+export declare function thumbnailDir(channelId: string): string;
+export declare function thumbnailManifestPath(channelId: string): string;
+export declare function thumbnailLockPath(channelId: string): string;
+export declare function channelImagePath(channelId: string, kind: 'avatar' | 'banner', format: ImageFormat): string;
+export declare function videoThumbnailPath(channelId: string, tab: ThumbnailTab, videoId: string, format: ImageFormat): string;
+/** The informational `file` field: where a file sits inside the channel directory. */
+export declare function relativeFile(channelId: string, absolute: string): string;
+//# sourceMappingURL=thumbnail-paths.d.ts.map

package/dist/utils/thumbnail-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-paths.d.ts","sourceRoot":"","sources":["../../src/utils/thumbnail-paths.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;;;;GAQG;AAEH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,MAAM,EAAE,WAAW,GAClB,MAAM,CAER;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,MAAM,CAER;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/utils/thumbnail-paths.js

@@ -0,0 +1,35 @@
+import { join, relative } from 'node:path';
+import { dataDir } from './paths.js';
+import { assertChannelId, assertVideoId } from './validate.js';
+/**
+ * Every file a channel's thumbnails are made of.
+ *
+ * A sibling of the brains rather than inside them: deleting a brain removes
+ * its whole directory, and a channel's images should outlive its corpus. Keyed
+ * on the channel id, validated once here; a filename is the video id, also
+ * validated here; and the tab and format are closed enums. Nothing a caller or
+ * a hand-edited manifest supplies reaches a path unchecked.
+ */
+export function thumbnailsDir() {
+    return dataDir('thumbnails');
+}
+export function thumbnailDir(channelId) {
+    return join(thumbnailsDir(), assertChannelId(channelId));
+}
+export function thumbnailManifestPath(channelId) {
+    return join(thumbnailDir(channelId), 'manifest.json');
+}
+export function thumbnailLockPath(channelId) {
+    return join(thumbnailDir(channelId), 'fetch.lock');
+}
+export function channelImagePath(channelId, kind, format) {
+    return join(thumbnailDir(channelId), 'channel', `${kind}.${format}`);
+}
+export function videoThumbnailPath(channelId, tab, videoId, format) {
+    return join(thumbnailDir(channelId), tab, `${assertVideoId(videoId)}.${format}`);
+}
+/** The informational `file` field: where a file sits inside the channel directory. */
+export function relativeFile(channelId, absolute) {
+    return relative(thumbnailDir(channelId), absolute);
+}
+//# sourceMappingURL=thumbnail-paths.js.map

package/dist/utils/thumbnail-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-paths.js","sourceRoot":"","sources":["../../src/utils/thumbnail-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG/D;;;;;;;;GAQG;AAEH,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,SAAiB;IACrD,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,IAAyB,EACzB,MAAmB;IAEnB,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,SAAiB,EACjB,GAAiB,EACjB,OAAe,EACf,MAAmB;IAEnB,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC;AACnF,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,QAAgB;IAC9D,OAAO,QAAQ,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,CAAC;AACrD,CAAC"}

package/dist/utils/thumbnail-store.d.ts

@@ -0,0 +1,19 @@
+import { type ChannelImage, type ThumbnailEntry, type ThumbnailManifest, type ThumbnailStats, type ThumbnailTab } from '../thumbnail-schemas.js';
+/** The manifest of a channel's thumbnails: reading, writing, finding and forgetting it. */
+export declare const THUMBNAIL_MANIFEST_VERSION = 1;
+export declare function ensureThumbnailDirs(channelId: string, tabs: ThumbnailTab[]): Promise<string>;
+export declare function readThumbnailManifest(channelId: string): Promise<ThumbnailManifest | undefined>;
+export declare function requireThumbnailManifest(channelId: string): Promise<ThumbnailManifest>;
+export declare function writeThumbnailManifest(manifest: ThumbnailManifest): Promise<void>;
+/** Every thumbnail set on disk, newest first. Unreadable directories are skipped. */
+export declare function listThumbnailManifests(): Promise<ThumbnailManifest[]>;
+/** The thumbnail set for a channel named any way the caller likes, from disk alone. */
+export declare function resolveThumbnails(channel: string): Promise<ThumbnailManifest>;
+export declare function deleteThumbnails(channelId: string): Promise<boolean>;
+/** Where a saved entry's file is, recomputed from validated parts; never read from the manifest. */
+export declare function entryPath(channelId: string, entry: ThumbnailEntry): string | undefined;
+export declare function channelImageFile(channelId: string, image: ChannelImage): string | undefined;
+/** True when the file a saved record describes is on disk at the recorded size. */
+export declare function isIntact(path: string | undefined, bytes: number | undefined): Promise<boolean>;
+export declare function computeThumbnailStats(entries: ThumbnailEntry[]): ThumbnailStats;
+//# sourceMappingURL=thumbnail-store.d.ts.map

package/dist/utils/thumbnail-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-store.d.ts","sourceRoot":"","sources":["../../src/utils/thumbnail-store.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AAajC,2FAA2F;AAE3F,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,YAAY,EAAE,GACnB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAExC;AAED,wBAAsB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAY5F;AAED,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvF;AAED,qFAAqF;AACrF,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAa3E;AAED,uFAAuF;AACvF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmBnF;AAED,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK1E;AAED,oGAAoG;AACpG,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAGtF;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED,mFAAmF;AACnF,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,cAAc,CA2B/E"}