youtube-knowledge-mcp 2.2.0 → 3.0.1

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

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

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 = 2;
+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-schema.d.ts

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+/** The shape of one `yt-dlp -j` read of a video, and the small records derived from it. */
+export declare const heatmapEntrySchema: 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;
+}>;
+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>>>;
+    uploader: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    license: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    media_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    playable_in_embed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    release_timestamp: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    track: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    artist: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    album: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    release_year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    width: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    height: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    fps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title?: string | null | undefined;
+    channel?: string | null | undefined;
+    description?: string | null | undefined;
+    tags?: string[] | null | undefined;
+    fps?: number | null | undefined;
+    language?: 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;
+    width?: number | null | undefined;
+    height?: 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;
+    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;
+    heatmap?: {
+        value: number;
+        start_time: number;
+        end_time: number;
+    }[] | null | undefined;
+    uploader?: string | null | undefined;
+    license?: string | null | undefined;
+    media_type?: string | null | undefined;
+    playable_in_embed?: boolean | null | undefined;
+    release_timestamp?: number | null | undefined;
+    track?: string | null | undefined;
+    artist?: string | null | undefined;
+    album?: string | null | undefined;
+    release_year?: number | null | undefined;
+}, {
+    id: string;
+    title?: string | null | undefined;
+    channel?: string | null | undefined;
+    description?: string | null | undefined;
+    tags?: string[] | null | undefined;
+    fps?: number | null | undefined;
+    language?: 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;
+    width?: number | null | undefined;
+    height?: 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;
+    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;
+    heatmap?: {
+        value: number;
+        start_time: number;
+        end_time: number;
+    }[] | null | undefined;
+    uploader?: string | null | undefined;
+    license?: string | null | undefined;
+    media_type?: string | null | undefined;
+    playable_in_embed?: boolean | null | undefined;
+    release_timestamp?: number | null | undefined;
+    track?: string | null | undefined;
+    artist?: string | null | undefined;
+    album?: string | null | undefined;
+    release_year?: number | null | undefined;
+}>;
+/** What YouTube credits a track with, when a video carries music metadata. */
+export interface MusicCredits {
+    track?: string;
+    artist?: string;
+    album?: string;
+    releaseYear?: number;
+}
+/** The frame size and rate of the best stream, as far as yt-dlp reported them. */
+export interface VideoFormat {
+    width?: number;
+    height?: number;
+    fps?: number;
+}
+//# sourceMappingURL=video-stats-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"video-stats-schema.d.ts","sourceRoot":"","sources":["../../src/utils/video-stats-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,2FAA2F;AAE3F,eAAO,MAAM,kBAAkB;;;;;;;;;;;;EAI7B,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyC9B,CAAC;AAEH,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd"}

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

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+/** The shape of one `yt-dlp -j` read of a video, and the small records derived from it. */
+export 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(),
+    uploader: z.string().nullish(),
+    license: z.string().nullish(),
+    language: z.string().nullish(),
+    media_type: z.string().nullish(),
+    playable_in_embed: z.boolean().nullish(),
+    release_timestamp: z.number().nullish(),
+    track: z.string().nullish(),
+    artist: z.string().nullish(),
+    album: z.string().nullish(),
+    release_year: z.number().nullish(),
+    width: z.number().nullish(),
+    height: z.number().nullish(),
+    fps: z.number().nullish(),
+});
+//# sourceMappingURL=video-stats-schema.js.map

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

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

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

@@ -0,0 +1,16 @@
+/**
+ * What of a video's record is kept in the store.
+ *
+ * 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, so it has its own column. 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 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>;
+//# sourceMappingURL=video-stats-storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"video-stats-storage.d.ts","sourceRoot":"","sources":["../../src/utils/video-stats-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,2EAA2E;AAC3E,eAAO,MAAM,aAAa,mHAQhB,CAAC;AAEX,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"}

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

@@ -0,0 +1,37 @@
+/**
+ * What of a video's record is kept in the store.
+ *
+ * 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, so it has its own column. 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',
+];
+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;
+}
+//# sourceMappingURL=video-stats-storage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"video-stats-storage.js","sourceRoot":"","sources":["../../src/utils/video-stats-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C,2EAA2E;AAC3E,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,SAAS;IACT,mBAAmB;IACnB,oBAAoB;IACpB,WAAW;IACX,YAAY;IACZ,UAAU;IACV,SAAS;CACD,CAAC;AAEX,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,CAAC;AAErD,wFAAwF;AACxF,MAAM,UAAU,eAAe,CAAC,GAA4B;IAC1D,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,GAAG,CAAC;YAAE,SAAS;QACjE,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IACrC,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,GAAG,iCAAiC,EAAE,CAAC;QAC9F,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,iCAAiC,CAAC,CAAC;QAC3E,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC;IACpC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { videoStatsRowSchema, type MusicCredits, type VideoFormat } from './video-stats-schema.js';
+export { videoStatsRowSchema } from './video-stats-schema.js';
+export { CATALOG_DESCRIPTION_PREVIEW_CHARS, MAX_DETAIL_JSON_BYTES, STRIPPED_KEYS, stripForStorage, } from './video-stats-storage.js';
+export type { MusicCredits, VideoFormat } from './video-stats-schema.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.
+ */
+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;
+    channelUrl?: string;
+    uploader?: string;
+    license?: string;
+    language?: string;
+    /** yt-dlp's own label, such as `video`, `short` or `livestream`. */
+    mediaType?: string;
+    playableInEmbed?: boolean;
+    /** Unix seconds a premiere or scheduled video goes live. */
+    releaseTimestamp?: number;
+    music?: MusicCredits;
+    video?: VideoFormat;
+}
+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, options?: {
+    /**
+     * Have yt-dlp return a video YouTube refuses to serve as a row, with `availability`
+     * filled in, instead of failing. Without it a private video fails with a message that
+     * asks to sign in, which reads as a session problem rather than as that one video.
+     */
+    tolerateRefusal?: boolean;
+}): 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;AAIxB,OAAO,EAAE,mBAAmB,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEnG,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EACL,iCAAiC,EACjC,qBAAqB,EACrB,aAAa,EACb,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEzE;;;;;;;;;;;;;GAaG;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;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AASD,wBAAgB,YAAY,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,GAAG,UAAU,CA+EjF;AAED,gFAAgF;AAChF,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CACtB,GACL,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAY9C;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAExE"}

package/dist/utils/video-stats.js

@@ -0,0 +1,108 @@
+import { TIMEOUTS, parseYtDlpJson, runYtDlp } from './ytdlp.js';
+import { extractVideoId, formatDuration, watchUrl } from './youtube-url.js';
+import { classifyPlayability } from './errors.js';
+import { videoStatsRowSchema } from './video-stats-schema.js';
+export { videoStatsRowSchema } from './video-stats-schema.js';
+export { CATALOG_DESCRIPTION_PREVIEW_CHARS, MAX_DETAIL_JSON_BYTES, STRIPPED_KEYS, stripForStorage, } from './video-stats-storage.js';
+/** `{ [key]: value }` when yt-dlp told us something, `{}` when it said null or nothing. */
+function present(key, value) {
+    const field = {};
+    if (value !== null && value !== undefined)
+        field[key] = value;
+    return field;
+}
+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 ?? '';
+    const music = {
+        ...present('track', row.track),
+        ...present('artist', row.artist),
+        ...present('album', row.album),
+        ...present('releaseYear', row.release_year),
+    };
+    const format = {
+        ...present('width', row.width),
+        ...present('height', row.height),
+        ...present('fps', row.fps),
+    };
+    return {
+        id: row.id,
+        title: row.title ?? 'Unknown',
+        url: watchUrl(row.id),
+        channel: row.channel ?? 'Unknown',
+        ...present('channelId', row.channel_id),
+        ...present('channelFollowerCount', row.channel_follower_count),
+        ...present('channelUrl', row.channel_url),
+        ...present('uploader', row.uploader),
+        uploadDate: row.upload_date ?? '',
+        durationSeconds: duration,
+        durationFormatted: formatDuration(Math.floor(duration)),
+        ...present('viewCount', row.view_count),
+        ...present('likeCount', row.like_count),
+        ...present('commentCount', row.comment_count),
+        categories: row.categories ?? [],
+        tags: row.tags ?? [],
+        ageLimit: row.age_limit ?? 0,
+        ...present('availability', row.availability),
+        ...present('liveStatus', row.live_status),
+        ...present('license', row.license),
+        ...present('language', row.language),
+        ...present('mediaType', row.media_type),
+        ...present('playableInEmbed', row.playable_in_embed),
+        ...present('releaseTimestamp', row.release_timestamp),
+        ...(Object.keys(music).length === 0 ? {} : { music }),
+        ...(Object.keys(format).length === 0 ? {} : { video: format }),
+        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,
+        ...present('thumbnailUrl', row.thumbnail),
+    };
+}
+/** One `-j` read, serving info, details, chapters, captions and the heatmap. */
+export async function fetchVideoStatsRow(urlOrId, options = {}) {
+    const videoId = extractVideoId(urlOrId);
+    const args = ['-j', '--skip-download'];
+    if (options.tolerateRefusal === true)
+        args.push('--ignore-no-formats-error');
+    const stdout = await runYtDlp(args, {
+        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":"AACA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAuC,MAAM,yBAAyB,CAAC;AAEnG,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EACL,iCAAiC,EACjC,qBAAqB,EACrB,aAAa,EACb,eAAe,GAChB,MAAM,0BAA0B,CAAC;AA2DlC,2FAA2F;AAC3F,SAAS,OAAO,CAAsB,GAAM,EAAE,KAA2B;IACvE,MAAM,KAAK,GAA0B,EAAE,CAAC;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC9D,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAwC;IACnE,6EAA6E;IAC7E,qEAAqE;IACrE,sBAAsB;IACtB,MAAM,UAAU,GAAG,mBAAmB,CAAC;QACrC,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,SAAS;QAC3C,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;KACzC,CAAC,CAAC;IACH,IAAI,UAAU,KAAK,SAAS;QAAE,MAAM,UAAU,CAAC;IAE/C,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC;IACzC,MAAM,WAAW,GAAG,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC;IAE1C,MAAM,KAAK,GAAiB;QAC1B,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC;QAC9B,GAAG,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC;QAChC,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC;QAC9B,GAAG,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,YAAY,CAAC;KAC5C,CAAC;IACF,MAAM,MAAM,GAAgB;QAC1B,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC;QAC9B,GAAG,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC;QAChC,GAAG,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC;KAC3B,CAAC;IAEF,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,SAAS;QAC7B,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,SAAS;QACjC,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC;QACvC,GAAG,OAAO,CAAC,sBAAsB,EAAE,GAAG,CAAC,sBAAsB,CAAC;QAC9D,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,WAAW,CAAC;QACzC,GAAG,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC;QACpC,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE;QACjC,eAAe,EAAE,QAAQ;QACzB,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACvD,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC;QACvC,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC;QACvC,GAAG,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,aAAa,CAAC;QAC7C,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,EAAE;QAChC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;QACpB,QAAQ,EAAE,GAAG,CAAC,SAAS,IAAI,CAAC;QAC5B,GAAG,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,YAAY,CAAC;QAC5C,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,WAAW,CAAC;QACzC,GAAG,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC;QAClC,GAAG,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC;QACpC,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC;QACvC,GAAG,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,CAAC;QACpD,GAAG,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,iBAAiB,CAAC;QACrD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;QACrD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAC9D,OAAO,EAAE,GAAG,CAAC,QAAQ,IAAI,KAAK;QAC9B,QAAQ,EAAE,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC/C,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,SAAS,EAAE,OAAO,CAAC,UAAU;YAC7B,OAAO,EAAE,OAAO,CAAC,QAAQ;SAC1B,CAAC,CAAC;QACH,0EAA0E;QAC1E,qCAAqC;QACrC,QAAQ,EAAE;YACR,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC;YACxC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC;SACrD;QACD,UAAU,EAAE,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QACvD,GAAG,CAAC,OAAO,KAAK,SAAS;YACvB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBAC/B,YAAY,EAAE,KAAK,CAAC,UAAU;oBAC9B,UAAU,EAAE,KAAK,CAAC,QAAQ;oBAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;iBACnB,CAAC,CAAC;aACJ,CAAC;QACN,gBAAgB,EAAE,WAAW,CAAC,MAAM;QACpC,WAAW;QACX,GAAG,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,SAAS,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAe,EACf,UAOI,EAAE;IAEN,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;IACvC,IAAI,OAAO,CAAC,eAAe,KAAK,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAE7E,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE;QAClC,KAAK,EAAE,iBAAiB;QACxB,SAAS,EAAE,QAAQ,CAAC,QAAQ;QAC5B,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC;KAC1B,CAAC,CAAC;IAEH,OAAO,cAAc,CAAC,MAAM,EAAE,mBAAmB,EAAE,aAAa,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe;IACjD,OAAO,YAAY,CAAC,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;AACzD,CAAC"}