youtube-knowledge-mcp 2.2.0 → 3.0.0

package/dist/utils/video-stats-cache.d.ts

@@ -0,0 +1,16 @@
+import { type VideoStats } from './video-stats.js';
+export interface StatsResult {
+    stats: VideoStats;
+    /** True when served from disk rather than refetched. */
+    cached: boolean;
+}
+/**
+ * A video's stats, from disk when a fresh copy is there.
+ *
+ * A cache write that fails is not allowed to fail the read: the caller already
+ * has the answer, and a full disk should cost speed, not correctness.
+ */
+export declare function readVideoStats(urlOrId: string, options?: {
+    refresh?: boolean;
+}, now?: number): Promise<StatsResult>;
+//# sourceMappingURL=video-stats-cache.d.ts.map

package/dist/utils/video-stats-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-stats-cache.d.ts","sourceRoot":"","sources":["../../src/utils/video-stats-cache.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAqD1B,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,CAAC;IAClB,wDAAwD;IACxD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,EACnC,GAAG,SAAa,GACf,OAAO,CAAC,WAAW,CAAC,CAyBtB"}

package/dist/utils/video-stats-cache.js

@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { dataDir, ensurePrivateDir } from './paths.js';
+import { readJsonFile, writeJsonAtomic } from './json-file.js';
+import { envInt } from './env.js';
+import { assertVideoId } from './validate.js';
+import { extractVideoId } from './youtube-url.js';
+import { fetchVideoStatsRow, toVideoStats, videoStatsRowSchema, } from './video-stats.js';
+/**
+ * Keeping one video's stats on disk.
+ *
+ * Every per-video read goes through here, so get_video_info, get_chapters, a
+ * caption inventory and a catalogue detail pass share a single request rather
+ * than making one each. Requests are what gets a client throttled, so this is
+ * the largest reduction available.
+ *
+ * The cached document is the yt-dlp row, not the derived object: the row is
+ * what has a schema, and re-deriving on read means a cached video and a fresh
+ * one always come back through the same code path. Shaped after
+ * transcript-cache.ts — sharded so no directory grows to 100,000 entries,
+ * validated on read, and anything unreadable treated as absent.
+ */
+/**
+ * Resolved per call, not once at import.
+ *
+ * A module-level dataDir() reads the home directory the instant the module
+ * loads, which is before a test can point HOME anywhere — and it means the
+ * path is fixed for the process. store-paths.ts uses functions for the same
+ * reason.
+ */
+function cacheDir() {
+    return dataDir('stats');
+}
+/** Counts move constantly, so a day is already generous. */
+const VIDEO_STATS_TTL_MS = envInt('YOUTUBE_MCP_STATS_TTL_MS', 86_400_000, { min: 0 });
+/** Bumped when the stored shape changes, so old files are refetched, not misread. */
+const CACHE_VERSION = 1;
+const cachedStatsSchema = z.object({
+    version: z.literal(CACHE_VERSION),
+    fetchedAt: z.number(),
+    row: videoStatsRowSchema,
+});
+function shardDir(videoId) {
+    return join(cacheDir(), assertVideoId(videoId).slice(0, 2));
+}
+function cachePath(videoId) {
+    return join(shardDir(videoId), `${assertVideoId(videoId)}.json`);
+}
+function isFresh(fetchedAt, now) {
+    return VIDEO_STATS_TTL_MS === 0 || now - fetchedAt < VIDEO_STATS_TTL_MS;
+}
+/**
+ * A video's stats, from disk when a fresh copy is there.
+ *
+ * A cache write that fails is not allowed to fail the read: the caller already
+ * has the answer, and a full disk should cost speed, not correctness.
+ */
+export async function readVideoStats(urlOrId, options = {}, now = Date.now()) {
+    // The id comes from the URL, not from a fetch: checking the cache after
+    // fetching would be no cache at all.
+    const videoId = extractVideoId(urlOrId);
+    if (options.refresh !== true) {
+        const path = cachePath(videoId);
+        if (existsSync(path)) {
+            const parsed = await readJsonFile(path, cachedStatsSchema);
+            if (parsed !== undefined && isFresh(parsed.fetchedAt, now)) {
+                return { stats: toVideoStats(parsed.row), cached: true };
+            }
+        }
+    }
+    const row = await fetchVideoStatsRow(urlOrId);
+    await ensurePrivateDir(shardDir(videoId));
+    await writeJsonAtomic(cachePath(videoId), {
+        version: CACHE_VERSION,
+        fetchedAt: now,
+        row,
+    }).catch(() => undefined);
+    return { stats: toVideoStats(row), cached: false };
+}
+//# sourceMappingURL=video-stats-cache.js.map

package/dist/utils/video-stats-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-stats-cache.js","sourceRoot":"","sources":["../../src/utils/video-stats-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,GAEpB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,SAAS,QAAQ;IACf,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED,4DAA4D;AAC5D,MAAM,kBAAkB,GAAG,MAAM,CAAC,0BAA0B,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AAEtF,qFAAqF;AACrF,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;IACjC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,GAAG,EAAE,mBAAmB;CACzB,CAAC,CAAC;AAEH,SAAS,QAAQ,CAAC,OAAe;IAC/B,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,SAAS,CAAC,OAAe;IAChC,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,OAAO,CAAC,SAAiB,EAAE,GAAW;IAC7C,OAAO,kBAAkB,KAAK,CAAC,IAAI,GAAG,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAC1E,CAAC;AAQD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAe,EACf,UAAiC,EAAE,EACnC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAEhB,wEAAwE;IACxE,qCAAqC;IACrC,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAExC,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;YAC3D,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC;gBAC3D,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAE9C,MAAM,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1C,MAAM,eAAe,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE;QACxC,OAAO,EAAE,aAAa;QACtB,SAAS,EAAE,GAAG;QACd,GAAG;KACJ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAE1B,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACrD,CAAC"}

package/dist/utils/video-stats.d.ts

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+/**
+ * One full read of a video, serving every caller that needs part of it.
+ *
+ * `getVideoInfo` ran a narrow `--print` and `getVideoDetails` ran a full `-j`
+ * and discarded all but three fields, so a single video cost two spawns for
+ * data one already had. Requests to YouTube are the thing that gets a client
+ * throttled, so halving them is the cheapest reliability win available.
+ *
+ * What is NOT kept matters as much as what is. Measured on a 637KB payload:
+ * `automatic_captions` is 460,965 bytes (72%) of URLs that expire, `formats`
+ * another 113,601 (18%), and `heatmap` 6,589 — larger than the whole rest of
+ * the record. Stripped, a video is 4,785 bytes. Storing the raw object would
+ * cost 6.4GB per 10,000 videos instead of 48MB.
+ */
+/** A stored snapshot must stay small enough that a catalogue is not mostly URLs. */
+export declare const MAX_DETAIL_JSON_BYTES = 32768;
+/** Keys dropped before storage: expiring URLs and bulk we can re-fetch. */
+export declare const STRIPPED_KEYS: readonly ["formats", "requested_formats", "automatic_captions", "subtitles", "thumbnails", "comments", "heatmap"];
+export declare const videoStatsRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    channel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    channel_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    channel_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    channel_follower_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    upload_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    duration: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    view_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    like_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    comment_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    concurrent_view_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    categories: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    tags: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    age_limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    availability: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    live_status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    was_live: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    is_live: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    chapters: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        start_time: z.ZodNumber;
+        end_time: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        start_time: number;
+        end_time: number;
+    }, {
+        title: string;
+        start_time: number;
+        end_time: number;
+    }>, "many">>>;
+    heatmap: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        start_time: z.ZodNumber;
+        end_time: z.ZodNumber;
+        value: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        start_time: number;
+        end_time: number;
+    }, {
+        value: number;
+        start_time: number;
+        end_time: number;
+    }>, "many">>>;
+    automatic_captions: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    subtitles: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title?: string | null | undefined;
+    channel?: string | null | undefined;
+    description?: string | null | undefined;
+    tags?: string[] | null | undefined;
+    duration?: number | null | undefined;
+    upload_date?: string | null | undefined;
+    thumbnail?: string | null | undefined;
+    view_count?: number | null | undefined;
+    like_count?: number | null | undefined;
+    comment_count?: number | null | undefined;
+    availability?: string | null | undefined;
+    live_status?: string | null | undefined;
+    chapters?: {
+        title: string;
+        start_time: number;
+        end_time: number;
+    }[] | null | undefined;
+    subtitles?: Record<string, unknown> | null | undefined;
+    automatic_captions?: Record<string, unknown> | null | undefined;
+    channel_id?: string | null | undefined;
+    channel_url?: string | null | undefined;
+    channel_follower_count?: number | null | undefined;
+    heatmap?: {
+        value: number;
+        start_time: number;
+        end_time: number;
+    }[] | null | undefined;
+    concurrent_view_count?: number | null | undefined;
+    categories?: string[] | null | undefined;
+    age_limit?: number | null | undefined;
+    was_live?: boolean | null | undefined;
+    is_live?: boolean | null | undefined;
+}, {
+    id: string;
+    title?: string | null | undefined;
+    channel?: string | null | undefined;
+    description?: string | null | undefined;
+    tags?: string[] | null | undefined;
+    duration?: number | null | undefined;
+    upload_date?: string | null | undefined;
+    thumbnail?: string | null | undefined;
+    view_count?: number | null | undefined;
+    like_count?: number | null | undefined;
+    comment_count?: number | null | undefined;
+    availability?: string | null | undefined;
+    live_status?: string | null | undefined;
+    chapters?: {
+        title: string;
+        start_time: number;
+        end_time: number;
+    }[] | null | undefined;
+    subtitles?: Record<string, unknown> | null | undefined;
+    automatic_captions?: Record<string, unknown> | null | undefined;
+    channel_id?: string | null | undefined;
+    channel_url?: string | null | undefined;
+    channel_follower_count?: number | null | undefined;
+    heatmap?: {
+        value: number;
+        start_time: number;
+        end_time: number;
+    }[] | null | undefined;
+    concurrent_view_count?: number | null | undefined;
+    categories?: string[] | null | undefined;
+    age_limit?: number | null | undefined;
+    was_live?: boolean | null | undefined;
+    is_live?: boolean | null | undefined;
+}>;
+export interface VideoStats {
+    id: string;
+    title: string;
+    url: string;
+    channel: string;
+    channelId?: string;
+    channelFollowerCount?: number;
+    uploadDate: string;
+    durationSeconds: number;
+    durationFormatted: string;
+    viewCount?: number;
+    likeCount?: number;
+    /** YouTube's own count. Trustworthy here because this read has no --write-comments. */
+    commentCount?: number;
+    categories: string[];
+    tags: string[];
+    ageLimit: number;
+    availability?: string;
+    liveStatus?: string;
+    wasLive: boolean;
+    chapters: {
+        title: string;
+        startTime: number;
+        endTime: number;
+    }[];
+    /** Language tags only — never the URL arrays, which are 72% of the payload. */
+    captions: {
+        manual: string[];
+        automatic: string[];
+    };
+    hasHeatmap: boolean;
+    heatmap?: {
+        startSeconds: number;
+        endSeconds: number;
+        value: number;
+    }[];
+    descriptionChars: number;
+    description: string;
+    thumbnailUrl?: string;
+}
+export declare const CATALOG_DESCRIPTION_PREVIEW_CHARS = 500;
+/** Drops the bulk keys, so what is stored is the record rather than its attachments. */
+export declare function stripForStorage(raw: Record<string, unknown>): Record<string, unknown>;
+export declare function toVideoStats(row: z.infer<typeof videoStatsRowSchema>): VideoStats;
+/** One `-j` read, serving info, details, chapters, captions and the heatmap. */
+export declare function fetchVideoStatsRow(urlOrId: string): Promise<z.infer<typeof videoStatsRowSchema>>;
+export declare function getVideoStats(urlOrId: string): Promise<VideoStats>;
+//# sourceMappingURL=video-stats.d.ts.map

package/dist/utils/video-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-stats.d.ts","sourceRoot":"","sources":["../../src/utils/video-stats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;GAaG;AAEH,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,2EAA2E;AAC3E,eAAO,MAAM,aAAa,mHAQhB,CAAC;AAQX,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4B9B,CAAC;AAEH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClE,+EAA+E;IAC/E,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACpD,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxE,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAcrF;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,GAAG,UAAU,CA0EjF;AAED,gFAAgF;AAChF,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAS9C;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAExE"}

package/dist/utils/video-stats.js

@@ -0,0 +1,168 @@
+import { z } from 'zod';
+import { TIMEOUTS, parseYtDlpJson, runYtDlp } from './ytdlp.js';
+import { extractVideoId, formatDuration, watchUrl } from './youtube-url.js';
+import { classifyPlayability } from './errors.js';
+/**
+ * One full read of a video, serving every caller that needs part of it.
+ *
+ * `getVideoInfo` ran a narrow `--print` and `getVideoDetails` ran a full `-j`
+ * and discarded all but three fields, so a single video cost two spawns for
+ * data one already had. Requests to YouTube are the thing that gets a client
+ * throttled, so halving them is the cheapest reliability win available.
+ *
+ * What is NOT kept matters as much as what is. Measured on a 637KB payload:
+ * `automatic_captions` is 460,965 bytes (72%) of URLs that expire, `formats`
+ * another 113,601 (18%), and `heatmap` 6,589 — larger than the whole rest of
+ * the record. Stripped, a video is 4,785 bytes. Storing the raw object would
+ * cost 6.4GB per 10,000 videos instead of 48MB.
+ */
+/** A stored snapshot must stay small enough that a catalogue is not mostly URLs. */
+export const MAX_DETAIL_JSON_BYTES = 32_768;
+/** Keys dropped before storage: expiring URLs and bulk we can re-fetch. */
+export const STRIPPED_KEYS = [
+    'formats',
+    'requested_formats',
+    'automatic_captions',
+    'subtitles',
+    'thumbnails',
+    'comments',
+    'heatmap',
+];
+const heatmapEntrySchema = z.object({
+    start_time: z.number(),
+    end_time: z.number(),
+    value: z.number(),
+});
+export const videoStatsRowSchema = z.object({
+    id: z.string(),
+    title: z.string().nullish(),
+    channel: z.string().nullish(),
+    channel_id: z.string().nullish(),
+    channel_url: z.string().nullish(),
+    channel_follower_count: z.number().nullish(),
+    upload_date: z.string().nullish(),
+    duration: z.number().nullish(),
+    view_count: z.number().nullish(),
+    like_count: z.number().nullish(),
+    comment_count: z.number().nullish(),
+    concurrent_view_count: z.number().nullish(),
+    categories: z.array(z.string()).nullish(),
+    tags: z.array(z.string()).nullish(),
+    age_limit: z.number().nullish(),
+    availability: z.string().nullish(),
+    live_status: z.string().nullish(),
+    was_live: z.boolean().nullish(),
+    is_live: z.boolean().nullish(),
+    description: z.string().nullish(),
+    thumbnail: z.string().nullish(),
+    chapters: z
+        .array(z.object({ title: z.string(), start_time: z.number(), end_time: z.number() }))
+        .nullish(),
+    heatmap: z.array(heatmapEntrySchema).nullish(),
+    automatic_captions: z.record(z.string(), z.unknown()).nullish(),
+    subtitles: z.record(z.string(), z.unknown()).nullish(),
+});
+export const CATALOG_DESCRIPTION_PREVIEW_CHARS = 500;
+/** Drops the bulk keys, so what is stored is the record rather than its attachments. */
+export function stripForStorage(raw) {
+    const kept = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (STRIPPED_KEYS.some((stripped) => stripped === key))
+            continue;
+        kept[key] = value;
+    }
+    const description = kept.description;
+    if (typeof description === 'string' && description.length > CATALOG_DESCRIPTION_PREVIEW_CHARS) {
+        kept.description = description.slice(0, CATALOG_DESCRIPTION_PREVIEW_CHARS);
+        kept.description_truncated = true;
+    }
+    return kept;
+}
+export function toVideoStats(row) {
+    // classifyPlayability RETURNS the error rather than throwing it, so ignoring
+    // the result would hand back ordinary-looking stats for a private or
+    // members-only video.
+    const unplayable = classifyPlayability({
+        availability: row.availability ?? undefined,
+        liveStatus: row.live_status ?? undefined,
+    });
+    if (unplayable !== undefined)
+        throw unplayable;
+    const duration = row.duration ?? 0;
+    const heatmap = row.heatmap ?? undefined;
+    const description = row.description ?? '';
+    return {
+        id: row.id,
+        title: row.title ?? 'Unknown',
+        url: watchUrl(row.id),
+        channel: row.channel ?? 'Unknown',
+        ...(row.channel_id === null || row.channel_id === undefined
+            ? {}
+            : { channelId: row.channel_id }),
+        ...(row.channel_follower_count === null || row.channel_follower_count === undefined
+            ? {}
+            : { channelFollowerCount: row.channel_follower_count }),
+        uploadDate: row.upload_date ?? '',
+        durationSeconds: duration,
+        durationFormatted: formatDuration(Math.floor(duration)),
+        ...(row.view_count === null || row.view_count === undefined
+            ? {}
+            : { viewCount: row.view_count }),
+        ...(row.like_count === null || row.like_count === undefined
+            ? {}
+            : { likeCount: row.like_count }),
+        ...(row.comment_count === null || row.comment_count === undefined
+            ? {}
+            : { commentCount: row.comment_count }),
+        categories: row.categories ?? [],
+        tags: row.tags ?? [],
+        ageLimit: row.age_limit ?? 0,
+        ...(row.availability === null || row.availability === undefined
+            ? {}
+            : { availability: row.availability }),
+        ...(row.live_status === null || row.live_status === undefined
+            ? {}
+            : { liveStatus: row.live_status }),
+        wasLive: row.was_live ?? false,
+        chapters: (row.chapters ?? []).map((chapter) => ({
+            title: chapter.title,
+            startTime: chapter.start_time,
+            endTime: chapter.end_time,
+        })),
+        // Keys only: the values are arrays of expiring URLs, and the inventory is
+        // what a caller actually asks about.
+        captions: {
+            manual: Object.keys(row.subtitles ?? {}),
+            automatic: Object.keys(row.automatic_captions ?? {}),
+        },
+        hasHeatmap: heatmap !== undefined && heatmap.length > 0,
+        ...(heatmap === undefined
+            ? {}
+            : {
+                heatmap: heatmap.map((entry) => ({
+                    startSeconds: entry.start_time,
+                    endSeconds: entry.end_time,
+                    value: entry.value,
+                })),
+            }),
+        descriptionChars: description.length,
+        description,
+        ...(row.thumbnail === null || row.thumbnail === undefined
+            ? {}
+            : { thumbnailUrl: row.thumbnail }),
+    };
+}
+/** One `-j` read, serving info, details, chapters, captions and the heatmap. */
+export async function fetchVideoStatsRow(urlOrId) {
+    const videoId = extractVideoId(urlOrId);
+    const stdout = await runYtDlp(['-j', '--skip-download'], {
+        label: 'get_video_stats',
+        timeoutMs: TIMEOUTS.metadata,
+        target: watchUrl(videoId),
+    });
+    return parseYtDlpJson(stdout, videoStatsRowSchema, 'video stats');
+}
+export async function getVideoStats(urlOrId) {
+    return toVideoStats(await fetchVideoStatsRow(urlOrId));
+}
+//# sourceMappingURL=video-stats.js.map

package/dist/utils/video-stats.js.map

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

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

@@ -0,0 +1,69 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { z } from 'zod';
+/**
+ * Reading the catalogued videos back.
+ *
+ * `upload_date` is NULL, never '', for a video only ever seen in a flat
+ * listing — flat entries carry no publication date. A date filter therefore
+ * excludes those rows rather than silently treating them as ancient.
+ */
+declare const videoRowSchema: z.ZodObject<{
+    video_id: z.ZodString;
+    channel_id: z.ZodNullable<z.ZodString>;
+    title: z.ZodString;
+    duration_s: z.ZodNullable<z.ZodNumber>;
+    upload_date: z.ZodNullable<z.ZodString>;
+    view_count: z.ZodNullable<z.ZodNumber>;
+    comment_count: z.ZodNullable<z.ZodNumber>;
+    live_status: z.ZodNullable<z.ZodString>;
+    thumbnail_url: z.ZodNullable<z.ZodString>;
+    tab: z.ZodNullable<z.ZodString>;
+    also_in_tabs: z.ZodString;
+    detail_at: z.ZodNullable<z.ZodNumber>;
+    stored_comments: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    upload_date: string | null;
+    view_count: number | null;
+    comment_count: number | null;
+    live_status: string | null;
+    channel_id: string | null;
+    tab: string | null;
+    video_id: string;
+    duration_s: number | null;
+    thumbnail_url: string | null;
+    also_in_tabs: string;
+    detail_at: number | null;
+    stored_comments: number;
+}, {
+    title: string;
+    upload_date: string | null;
+    view_count: number | null;
+    comment_count: number | null;
+    live_status: string | null;
+    channel_id: string | null;
+    tab: string | null;
+    video_id: string;
+    duration_s: number | null;
+    thumbnail_url: string | null;
+    also_in_tabs: string;
+    detail_at: number | null;
+    stored_comments: number;
+}>;
+export type StoredVideo = z.infer<typeof videoRowSchema>;
+export interface VideoQuery {
+    channelId?: string;
+    match?: string;
+    since?: string;
+    until?: string;
+    minDurationSeconds?: number;
+    detailedOnly?: boolean;
+    withComments?: boolean;
+    order?: 'newest' | 'oldest' | 'views' | 'comments' | 'catalog';
+    limit?: number;
+    offset?: number;
+}
+export declare function queryVideos(database: DatabaseSync, query: VideoQuery): StoredVideo[];
+export declare function countVideos(database: DatabaseSync, query: VideoQuery): number;
+export {};
+//# sourceMappingURL=video-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"video-store.d.ts","sourceRoot":"","sources":["../../src/utils/video-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AAEH,QAAA,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAclB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiDD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,GAAG,WAAW,EAAE,CAYpF;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAQ7E"}

package/dist/utils/video-store.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { queryRows } from './store-rows.js';
+/**
+ * Reading the catalogued videos back.
+ *
+ * `upload_date` is NULL, never '', for a video only ever seen in a flat
+ * listing — flat entries carry no publication date. A date filter therefore
+ * excludes those rows rather than silently treating them as ancient.
+ */
+const videoRowSchema = z.object({
+    video_id: z.string(),
+    channel_id: z.string().nullable(),
+    title: z.string(),
+    duration_s: z.number().nullable(),
+    upload_date: z.string().nullable(),
+    view_count: z.number().nullable(),
+    comment_count: z.number().nullable(),
+    live_status: z.string().nullable(),
+    thumbnail_url: z.string().nullable(),
+    tab: z.string().nullable(),
+    also_in_tabs: z.string(),
+    detail_at: z.number().nullable(),
+    stored_comments: z.number(),
+});
+function buildWhere(query) {
+    const clauses = [];
+    const params = [];
+    if (query.channelId !== undefined) {
+        clauses.push('v.channel_id = ?');
+        params.push(query.channelId);
+    }
+    if (query.match !== undefined && query.match !== '') {
+        clauses.push('lower(v.title) LIKE ?');
+        params.push(`%${query.match.toLowerCase()}%`);
+    }
+    if (query.since !== undefined) {
+        clauses.push('v.upload_date IS NOT NULL AND v.upload_date >= ?');
+        params.push(query.since.replace(/-/g, ''));
+    }
+    if (query.until !== undefined) {
+        clauses.push('v.upload_date IS NOT NULL AND v.upload_date <= ?');
+        params.push(query.until.replace(/-/g, ''));
+    }
+    if (query.minDurationSeconds !== undefined && query.minDurationSeconds > 0) {
+        clauses.push('v.duration_s >= ?');
+        params.push(query.minDurationSeconds);
+    }
+    if (query.detailedOnly === true)
+        clauses.push('v.detail_at IS NOT NULL');
+    if (query.withComments === true) {
+        clauses.push('EXISTS (SELECT 1 FROM comment c WHERE c.video_id = v.video_id)');
+    }
+    return { sql: clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`, params };
+}
+const ORDER = {
+    // NULLS LAST so an un-dated video sorts as unknown rather than oldest.
+    newest: 'v.upload_date DESC NULLS LAST, v.video_id',
+    oldest: 'v.upload_date ASC NULLS LAST, v.video_id',
+    views: 'v.view_count DESC NULLS LAST, v.video_id',
+    comments: 'stored_comments DESC, v.video_id',
+    catalog: 'v.catalog_rank ASC NULLS LAST, v.video_id',
+};
+const SELECT = `
+SELECT v.video_id, v.channel_id, v.title, v.duration_s, v.upload_date, v.view_count,
+       v.comment_count, v.live_status, v.thumbnail_url, v.tab, v.also_in_tabs, v.detail_at,
+       (SELECT COUNT(*) FROM comment c WHERE c.video_id = v.video_id) AS stored_comments
+FROM video v`;
+export function queryVideos(database, query) {
+    const where = buildWhere(query);
+    return queryRows(database.prepare(`${SELECT}${where.sql} ORDER BY ${ORDER[query.order ?? 'newest']} LIMIT ? OFFSET ?`), videoRowSchema, ...where.params, query.limit ?? 25, query.offset ?? 0);
+}
+export function countVideos(database, query) {
+    const where = buildWhere(query);
+    const rows = queryRows(database.prepare(`SELECT COUNT(*) AS n FROM video v${where.sql}`), z.object({ n: z.number() }), ...where.params);
+    return rows[0]?.n ?? 0;
+}
+//# sourceMappingURL=video-store.js.map

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

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

package/dist/utils/youtube-channel.d.ts

@@ -1,5 +1,4 @@
 import { type ListedImage } from './flat-listing.js';
-/** Listings and metadata for channels and playlists. */
 export interface VideoListItem {
     id: string;
     title: string;
@@ -38,7 +37,15 @@ export interface PlaylistInfo {
     url: string;
     description: string;
 }
-export declare function listVideos(urlOrChannel: string, limit?: number): Promise<VideoListItem[]>;
+export declare function listVideos(urlOrChannel: string, limit?: number, start?: number): Promise<VideoListItem[]>;
+/**
+ * How many videos a listing says it has, when it says anything.
+ *
+ * `playlist_count` is populated for playlists and routinely null for channel
+ * tabs, so this returns undefined rather than a guess. One extra cheap call —
+ * the same `--playlist-items 0` metadata read getPlaylistInfo already does.
+ */
+export declare function playlistTotal(urlOrChannel: string): Promise<number | undefined>;
 export declare function getPlaylistInfo(playlistUrl: string): Promise<PlaylistInfo>;
 export declare function getChannelInfo(channel: string): Promise<ChannelInfo>;
 //# sourceMappingURL=youtube-channel.d.ts.map