youtube-knowledge-mcp 2.1.0 → 3.0.0

package/dist/utils/validate.js

@@ -1,35 +1,59 @@
+import { existsSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, normalize, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, normalize, resolve, sep } from 'node:path';
 import { YouTubeError } from './errors.js';
 /**
  * Input validation for the values that reach the filesystem or yt-dlp's
- * language negotiation. Zod already constrains shapes at the tool boundary;
+ * language negotiation. The YouTube-specific checks — ids and URLs — live in
+ * validate-youtube.ts and are re-exported here. Zod already constrains shapes at the tool boundary;
  * these are the checks Zod cannot express.
  */
 /**
- * Resolve a caller-supplied output directory.
+ * Prove that a caller-supplied path lies inside the home directory.
  *
  * A tool argument is model-controlled, so it must not be able to write outside
- * the user's home directory or reach the filesystem root through `..`.
+ * the user's home directory or reach the filesystem root through `..`. The
+ * check is made on the real path: a symlink inside home that points outside it
+ * passed a purely lexical comparison, and yt-dlp and ffmpeg then wrote through
+ * it. The nearest existing ancestor is resolved and the missing tail re-joined,
+ * so a directory that does not exist yet is judged by where it would be created.
  */
-export function resolveOutputDir(outputDir, fallback) {
-    if (outputDir === undefined || outputDir.trim() === '')
-        return fallback;
-    const expanded = outputDir.startsWith('~')
-        ? resolve(homedir(), outputDir.slice(1).replace(/^[/\\]/, ''))
-        : resolve(normalize(outputDir));
-    if (expanded.includes('\0')) {
-        throw new YouTubeError('INVALID_INPUT', 'The output directory path is not valid.', {
-            nextStep: 'Provide a plain directory path, for example ~/Videos.',
+export function assertInsideHome(input, what) {
+    if (input.includes('\0')) {
+        throw new YouTubeError('INVALID_INPUT', `The ${what} path is not valid.`, {
+            nextStep: 'Provide a plain path, for example ~/Videos.',
         });
     }
-    const home = resolve(homedir());
-    if (!isAbsolute(expanded) || !(expanded === home || expanded.startsWith(home + sep))) {
-        throw new YouTubeError('INVALID_INPUT', 'Downloads must be written inside your home directory.', {
-            nextStep: `Choose a path under ${home}, or omit outputDir to use the default location.`,
+    const expanded = input.startsWith('~')
+        ? resolve(homedir(), input.slice(1).replace(/^[/\\]/, ''))
+        : resolve(normalize(input));
+    const home = realpathSync(homedir());
+    const real = realpathOfNearestAncestor(expanded);
+    if (!isAbsolute(real) || !(real === home || real.startsWith(home + sep))) {
+        throw new YouTubeError('INVALID_INPUT', `The ${what} must be inside your home directory.`, {
+            nextStep: `Choose a path under ${home}, or omit it to use the default location.`,
         });
     }
-    return expanded;
+    return real;
+}
+/**
+ * The real path of `target`, resolving symlinks in whichever prefix of it
+ * exists. The walk stops at the filesystem root, which always exists.
+ */
+function realpathOfNearestAncestor(target) {
+    const missing = [];
+    let probe = target;
+    while (dirname(probe) !== probe && !existsSync(probe)) {
+        missing.unshift(basename(probe));
+        probe = dirname(probe);
+    }
+    return join(realpathSync(probe), ...missing);
+}
+/** Resolve a caller-supplied output directory, or the fallback when none is given. */
+export function resolveOutputDir(outputDir, fallback) {
+    if (outputDir === undefined || outputDir.trim() === '')
+        return fallback;
+    return assertInsideHome(outputDir, 'output directory');
 }
 /** BCP-47-ish: `en`, `pt-BR`, `zh-Hans`, plus yt-dlp's `-orig` suffix. */
 const LANGUAGE_PATTERN = /^[a-zA-Z]{2,8}(?:-[a-zA-Z0-9]{2,8})*$/;
@@ -41,24 +65,6 @@ export function assertLanguageTag(language) {
     }
     return language;
 }
-/**
- * YouTube channel ids are `UC` followed by 22 base64url characters.
- *
- * This is stricter than it looks like it needs to be. A channel id arrives from
- * yt-dlp's output and is then used as a directory name under
- * `~/.youtube-knowledge/brains`, so a value containing a separator or `..`
- * would write outside that tree. Matching the real format exactly is cheaper
- * than sanitising a value that should never have been unusual.
- */
-const CHANNEL_ID_PATTERN = /^UC[A-Za-z0-9_-]{22}$/;
-export function assertChannelId(channelId) {
-    if (!CHANNEL_ID_PATTERN.test(channelId)) {
-        throw new YouTubeError('INVALID_INPUT', `"${channelId}" is not a valid YouTube channel id.`, {
-            nextStep: 'Channel ids look like UCxxxxxxxxxxxxxxxxxxxxxx. Call get_channel_info or list_brains to get one.',
-        });
-    }
-    return channelId;
-}
 /** Accepts `90`, `1:30`, `01:02:03`, `1:30.5` and returns seconds. */
 export function parseTimestamp(value, field) {
     if (typeof value === 'number') {
@@ -79,4 +85,5 @@ export function parseTimestamp(value, field) {
     // The hours group is optional, so it is genuinely absent for "MM:SS" input.
     return Number(match[1] ?? 0) * 3600 + Number(match[2] ?? 0) * 60 + Number(match[3] ?? 0);
 }
+export * from './validate-youtube.js';
 //# sourceMappingURL=validate.js.map

package/dist/utils/validate.js.map

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

package/dist/utils/version.d.ts

@@ -0,0 +1,2 @@
+export declare function serverVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/utils/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAkBA,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/utils/version.js

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+/**
+ * The version this build reports.
+ *
+ * Advertised in the MCP initialize response and on the authenticated health
+ * endpoint, so a package.json that has lost it should fail loudly at startup
+ * rather than telling every client the server is version `undefined`.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = z
+    .object({ version: z.string() })
+    .parse(JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf-8')));
+export function serverVersion() {
+    return pkg.version;
+}
+//# sourceMappingURL=version.js.map

package/dist/utils/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAErD,MAAM,GAAG,GAAG,CAAC;KACV,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;KAC/B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAEpF,MAAM,UAAU,aAAa;IAC3B,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC"}

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

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