youtube-knowledge-mcp 2.1.0 → 3.0.0

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"}

package/dist/utils/thumbnail-store.js

@@ -0,0 +1,125 @@
+import { existsSync } from 'node:fs';
+import { readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { thumbnailManifestSchema, } from '../thumbnail-schemas.js';
+import { findByChannel } from './channel-lookup.js';
+import { YouTubeError } from './errors.js';
+import { readJsonFile, writeJsonAtomic } from './json-file.js';
+import { ensurePrivateDir } from './paths.js';
+import { channelImagePath, thumbnailDir, thumbnailManifestPath, thumbnailsDir, videoThumbnailPath, } from './thumbnail-paths.js';
+/** The manifest of a channel's thumbnails: reading, writing, finding and forgetting it. */
+export const THUMBNAIL_MANIFEST_VERSION = 1;
+export async function ensureThumbnailDirs(channelId, tabs) {
+    const directory = await ensurePrivateDir(thumbnailDir(channelId));
+    await ensurePrivateDir(join(directory, 'channel'));
+    for (const tab of tabs)
+        await ensurePrivateDir(join(directory, tab));
+    return directory;
+}
+export async function readThumbnailManifest(channelId) {
+    return readJsonFile(thumbnailManifestPath(channelId), thumbnailManifestSchema);
+}
+export async function requireThumbnailManifest(channelId) {
+    const manifest = await readThumbnailManifest(channelId);
+    if (manifest === undefined) {
+        throw new YouTubeError('NOT_FOUND', `No thumbnails have been fetched for channel ${channelId}.`, {
+            nextStep: 'Call fetch_channel_thumbnails with the channel URL or handle.',
+        });
+    }
+    return manifest;
+}
+export async function writeThumbnailManifest(manifest) {
+    await ensurePrivateDir(thumbnailDir(manifest.channel.channelId));
+    await writeJsonAtomic(thumbnailManifestPath(manifest.channel.channelId), manifest);
+}
+/** Every thumbnail set on disk, newest first. Unreadable directories are skipped. */
+export async function listThumbnailManifests() {
+    if (!existsSync(thumbnailsDir()))
+        return [];
+    const manifests = [];
+    for (const entry of await readdir(thumbnailsDir(), { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const manifest = await readJsonFile(join(thumbnailsDir(), entry.name, 'manifest.json'), thumbnailManifestSchema);
+        if (manifest !== undefined)
+            manifests.push(manifest);
+    }
+    return manifests.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+/** The thumbnail set for a channel named any way the caller likes, from disk alone. */
+export async function resolveThumbnails(channel) {
+    const manifests = await listThumbnailManifests();
+    const [first, second] = findByChannel(manifests, channel);
+    if (first === undefined) {
+        const fetched = manifests.map((m) => m.channel.handle || m.channel.name);
+        throw new YouTubeError('NOT_FOUND', `No thumbnails have been fetched for "${channel}".`, {
+            nextStep: fetched.length === 0
+                ? 'Call fetch_channel_thumbnails with the channel URL or handle.'
+                : `Call fetch_channel_thumbnails to fetch them. Channels with thumbnails: ${fetched.join(', ')}.`,
+        });
+    }
+    if (second !== undefined) {
+        throw new YouTubeError('INVALID_INPUT', `"${channel}" matches more than one channel.`, {
+            nextStep: `Use the channel id instead: ${[first, second].map((m) => m.channel.channelId).join(', ')}.`,
+        });
+    }
+    return first;
+}
+export async function deleteThumbnails(channelId) {
+    const directory = thumbnailDir(channelId);
+    const existed = existsSync(directory);
+    await rm(directory, { recursive: true, force: true });
+    return existed;
+}
+/** Where a saved entry's file is, recomputed from validated parts; never read from the manifest. */
+export function entryPath(channelId, entry) {
+    if (entry.state !== 'saved' || entry.format === undefined)
+        return undefined;
+    return videoThumbnailPath(channelId, entry.tab, entry.videoId, entry.format);
+}
+export function channelImageFile(channelId, image) {
+    if (image.state !== 'saved' || image.format === undefined)
+        return undefined;
+    return channelImagePath(channelId, image.kind, image.format);
+}
+/** True when the file a saved record describes is on disk at the recorded size. */
+export async function isIntact(path, bytes) {
+    if (path === undefined)
+        return false;
+    try {
+        return (await stat(path)).size === bytes;
+    }
+    catch {
+        return false;
+    }
+}
+export function computeThumbnailStats(entries) {
+    const tabs = new Map();
+    let saved = 0;
+    let failed = 0;
+    let pending = 0;
+    let totalBytes = 0;
+    for (const entry of entries) {
+        const tab = tabs.get(entry.tab) ?? { videoCount: 0, savedCount: 0 };
+        tab.videoCount++;
+        if (entry.state === 'saved') {
+            saved++;
+            tab.savedCount++;
+            totalBytes += entry.bytes ?? 0;
+        }
+        else if (entry.state === 'failed')
+            failed++;
+        else
+            pending++;
+        tabs.set(entry.tab, tab);
+    }
+    return {
+        videoCount: entries.length,
+        savedCount: saved,
+        failedCount: failed,
+        pendingCount: pending,
+        totalBytes,
+        tabs: [...tabs.entries()].map(([tab, counts]) => ({ tab, ...counts })),
+    };
+}
+//# sourceMappingURL=thumbnail-store.js.map

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

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

package/dist/utils/transcript-cache.d.ts

@@ -0,0 +1,20 @@
+import { type TranscriptSegment } from './transcript.js';
+export interface TranscriptResult {
+    /** The whole transcript as plain text, unchanged from previous releases. */
+    transcript: string;
+    /** The same content with cue timings preserved. */
+    segments: TranscriptSegment[];
+    language: string;
+    videoId: string;
+    /** True when served from the local cache rather than refetched. */
+    cached: boolean;
+}
+export interface GetTranscriptOptions {
+    language?: string;
+    /** Ignore any cached copy and refetch from YouTube. */
+    refresh?: boolean;
+}
+/** True when a usable transcript is already on disk, in any language. */
+export declare function hasCachedTranscript(videoId: string): boolean;
+export declare function getTranscript(urlOrId: string, options?: GetTranscriptOptions): Promise<TranscriptResult>;
+//# sourceMappingURL=transcript-cache.d.ts.map

package/dist/utils/transcript-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-cache.d.ts","sourceRoot":"","sources":["../../src/utils/transcript-cache.ts"],"names":[],"mappings":"AAUA,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AAOzB,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAqCD,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,gBAAgB,CAAC,CAqF3B"}