youtube-knowledge-mcp 2.1.0 → 3.0.0

package/dist/utils/store-schema.js

@@ -0,0 +1,168 @@
+/**
+ * The shape of the harvested store, as one reviewable unit.
+ *
+ * Kept apart from the module that opens the database so the schema can be read
+ * end to end without the connection handling in the way.
+ *
+ * `STRICT` on every table: SQLite's default type affinity would silently accept
+ * a string where a count belongs, and this store exists to make claims about
+ * counts. It has no BOOLEAN, so flags are 0/1 integers decoded explicitly on
+ * the way out (see store-rows.ts) rather than cast.
+ */
+/** Bumped only by a migration in store-migrations.ts. Independent of the server's semver. */
+export const STORE_VERSION = 1;
+export const STORE_PRAGMAS = [
+    // One writer and many readers across processes, which rollback journalling
+    // cannot do. Required for the "kill the server mid-harvest" guarantee.
+    'PRAGMA journal_mode = WAL',
+    // A crash loses at most the last committed transaction and can never corrupt
+    // the file. FULL would fsync per commit for a store whose worst case is
+    // re-fetching one video.
+    'PRAGMA synchronous = NORMAL',
+    'PRAGMA foreign_keys = ON',
+    'PRAGMA temp_store = MEMORY',
+];
+export const STORE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS channel (
+  channel_id       TEXT PRIMARY KEY,
+  handle           TEXT    NOT NULL DEFAULT '',
+  name             TEXT    NOT NULL DEFAULT '',
+  channel_url      TEXT    NOT NULL DEFAULT '',
+  subscriber_count INTEGER,
+  description      TEXT    NOT NULL DEFAULT '',
+  avatar_url       TEXT,
+  banner_url       TEXT,
+  first_seen_at    INTEGER NOT NULL,
+  updated_at       INTEGER NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS video (
+  video_id      TEXT PRIMARY KEY,
+  channel_id    TEXT REFERENCES channel(channel_id) ON DELETE CASCADE,
+  title         TEXT    NOT NULL DEFAULT '',
+  duration_s    INTEGER,
+  -- 'YYYY-MM-DD'. NULL, never '', when a flat listing carried none: a date
+  -- filter must be able to tell "not known yet" from "known to be empty".
+  upload_date   TEXT,
+  view_count    INTEGER,
+  like_count    INTEGER,
+  -- YouTube's own claim, read WITHOUT --write-comments, which overwrites it
+  -- with the number extracted. This is the denominator every comment receipt
+  -- is measured against, so it may only ever come from a metadata pass.
+  comment_count INTEGER,
+  live_status   TEXT,
+  availability  TEXT,
+  thumbnail_url TEXT,
+  tab           TEXT,
+  also_in_tabs  TEXT    NOT NULL DEFAULT '[]',
+  catalog_rank  INTEGER,
+  listed_at     INTEGER,
+  detail_at     INTEGER,
+  -- Stripped before storage: formats, automatic_captions, subtitles,
+  -- thumbnails and comments are 96% of a raw -j payload and are mostly
+  -- expiring URLs. See MAX_DETAIL_JSON_BYTES.
+  detail_json   TEXT,
+  heatmap_json  TEXT
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS video_by_channel ON video(channel_id, catalog_rank);
+CREATE INDEX IF NOT EXISTS video_by_date    ON video(channel_id, upload_date DESC);
+
+CREATE TABLE IF NOT EXISTS comment (
+  comment_id         TEXT PRIMARY KEY,
+  video_id           TEXT    NOT NULL REFERENCES video(video_id) ON DELETE CASCADE,
+  -- NULL for a top-level comment. yt-dlp writes the string 'root'; normalising
+  -- it here means a reply count is a COUNT(parent_id) rather than a filter
+  -- everyone has to remember.
+  parent_id          TEXT,
+  text               TEXT    NOT NULL DEFAULT '',
+  like_count         INTEGER NOT NULL DEFAULT 0,
+  author             TEXT    NOT NULL DEFAULT '',
+  author_id          TEXT,
+  author_url         TEXT,
+  author_thumbnail   TEXT,
+  author_is_uploader INTEGER NOT NULL DEFAULT 0,
+  author_is_verified INTEGER NOT NULL DEFAULT 0,
+  is_pinned          INTEGER NOT NULL DEFAULT 0,
+  is_favorited       INTEGER NOT NULL DEFAULT 0,
+  time_text          TEXT,
+  published_at       INTEGER,
+  harvested_at       INTEGER NOT NULL
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS comment_by_video  ON comment(video_id, parent_id, like_count DESC);
+CREATE INDEX IF NOT EXISTS comment_by_parent ON comment(parent_id);
+CREATE INDEX IF NOT EXISTS comment_by_author ON comment(author_id);
+CREATE INDEX IF NOT EXISTS comment_by_time   ON comment(video_id, published_at);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS comment_fts USING fts5(
+  text,
+  content       = 'comment',
+  content_rowid = 'rowid',
+  tokenize      = "unicode61 remove_diacritics 2"
+);
+
+-- Triggers rather than a periodic 'rebuild'. Measured: triggers cost 6.2x on
+-- bulk insert (2.3s vs 366ms per 200k rows) while 'rebuild' is O(whole table)
+-- and would take seconds per checkpoint at millions of rows. Against a network
+-- that delivers ~17 comments/second, the trigger cost is noise, and there is no
+-- "did we remember to rebuild" failure mode.
+CREATE TRIGGER IF NOT EXISTS comment_ai AFTER INSERT ON comment BEGIN
+  INSERT INTO comment_fts(rowid, text) VALUES (new.rowid, new.text);
+END;
+CREATE TRIGGER IF NOT EXISTS comment_ad AFTER DELETE ON comment BEGIN
+  INSERT INTO comment_fts(comment_fts, rowid, text) VALUES ('delete', old.rowid, old.text);
+END;
+CREATE TRIGGER IF NOT EXISTS comment_au AFTER UPDATE ON comment BEGIN
+  INSERT INTO comment_fts(comment_fts, rowid, text) VALUES ('delete', old.rowid, old.text);
+  INSERT INTO comment_fts(rowid, text) VALUES (new.rowid, new.text);
+END;
+
+-- What this store can prove about one target. Written in the SAME transaction
+-- as the rows it describes, so there is no interval in which a receipt can
+-- claim something the store does not hold.
+CREATE TABLE IF NOT EXISTS harvest_receipt (
+  scope             TEXT    NOT NULL,
+  target_id         TEXT    NOT NULL,
+  state             TEXT    NOT NULL,
+  reason            TEXT    NOT NULL,
+  have              INTEGER NOT NULL DEFAULT 0,
+  -- What the SOURCE stated. NULL when it stated nothing; never derived from
+  -- 'have', which would turn "we stopped" into "there was nothing more".
+  expected          INTEGER,
+  expected_source   TEXT,
+  source            TEXT    NOT NULL,
+  limit_applied     INTEGER,
+  sort_applied      TEXT,
+  ran_to_exhaustion INTEGER,
+  resume_token      TEXT,
+  started_at        INTEGER NOT NULL,
+  finished_at       INTEGER,
+  attempts          INTEGER NOT NULL DEFAULT 0,
+  error_code        TEXT,
+  note              TEXT,
+  PRIMARY KEY (scope, target_id)
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS receipt_by_state ON harvest_receipt(state, finished_at DESC);
+
+-- Append-only audit trail: cheap, and it is what makes a receipt defensible
+-- after the fact rather than merely asserted.
+CREATE TABLE IF NOT EXISTS harvest_event (
+  event_id  INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope     TEXT    NOT NULL,
+  target_id TEXT    NOT NULL,
+  at        INTEGER NOT NULL,
+  state     TEXT    NOT NULL,
+  delta     INTEGER NOT NULL DEFAULT 0,
+  note      TEXT
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS event_by_target ON harvest_event(scope, target_id, at DESC);
+`;
+//# sourceMappingURL=store-schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store-schema.js","sourceRoot":"","sources":["../../src/utils/store-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAE/B,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,2EAA2E;IAC3E,uEAAuE;IACvE,2BAA2B;IAC3B,6EAA6E;IAC7E,wEAAwE;IACxE,yBAAyB;IACzB,6BAA6B;IAC7B,0BAA0B;IAC1B,4BAA4B;CACpB,CAAC;AAEX,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8I3B,CAAC"}

package/dist/utils/store.d.ts

@@ -0,0 +1,34 @@
+import type { DatabaseSync } from 'node:sqlite';
+/**
+ * The one connection to the harvested store.
+ *
+ * `node:sqlite` is a runtime builtin, so this adds nothing to package.json —
+ * the same category as `node:fs`. It is reached through a dynamic import
+ * behind an async accessor so that a Node without it still loads every module
+ * and still serves the tools that do not touch the store; only the harvest
+ * tools fail, with a sentence naming the version to install.
+ *
+ * The reason for a database rather than more JSON files is transactional
+ * receipts. `brain-build.ts` carries a long comment explaining that its
+ * manifest and its chunks are two documents, only one can be written first,
+ * and a crash in between strands a brain. Here the rows and the receipt that
+ * describes them commit together, so that failure is not representable.
+ */
+/** The exact Node where `node:sqlite` is unflagged and `StatementSync.iterate()` exists. */
+export declare const MIN_NODE_VERSION = "22.13.0";
+export declare function readUserVersion(database: DatabaseSync): number;
+export declare function writeUserVersion(database: DatabaseSync, version: number): void;
+/** The process-wide store connection, opened on first use. */
+export declare function getStore(): Promise<DatabaseSync>;
+export declare function closeStore(): void;
+/**
+ * Moves a damaged database aside and starts a fresh one.
+ *
+ * Renames rather than deletes. Unlike `search-index.json`, which is derivable
+ * and is correctly rebuilt from disk, a harvest costs hours of network that no
+ * local cache can replay — so nothing here removes one without being asked.
+ */
+export declare function quarantineStore(now?: number): Promise<string>;
+/** Runs `work` in a transaction, rolling back if it throws. */
+export declare function inTransaction<T>(database: DatabaseSync, work: () => T): T;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/utils/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQhD;;;;;;;;;;;;;;GAcG;AAEH,4FAA4F;AAC5F,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAsG1C,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAI9D;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAI9E;AAED,8DAA8D;AAC9D,wBAAsB,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC,CAGtD;AAED,wBAAgB,UAAU,IAAI,IAAI,CAGjC;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,GAAG,SAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAKvE;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAUzE"}

package/dist/utils/store.js

@@ -0,0 +1,157 @@
+import { chmod, rename } from 'node:fs/promises';
+import { YouTubeError } from './errors.js';
+import { ensurePrivateDir } from './paths.js';
+import { corruptStorePath, storeDatabasePath, storeDir } from './store-paths.js';
+import { STORE_PRAGMAS, STORE_SCHEMA, STORE_VERSION } from './store-schema.js';
+import { runStoreMigrations } from './store-migrations.js';
+/**
+ * The one connection to the harvested store.
+ *
+ * `node:sqlite` is a runtime builtin, so this adds nothing to package.json —
+ * the same category as `node:fs`. It is reached through a dynamic import
+ * behind an async accessor so that a Node without it still loads every module
+ * and still serves the tools that do not touch the store; only the harvest
+ * tools fail, with a sentence naming the version to install.
+ *
+ * The reason for a database rather than more JSON files is transactional
+ * receipts. `brain-build.ts` carries a long comment explaining that its
+ * manifest and its chunks are two documents, only one can be written first,
+ * and a crash in between strands a brain. Here the rows and the receipt that
+ * describes them commit together, so that failure is not representable.
+ */
+/** The exact Node where `node:sqlite` is unflagged and `StatementSync.iterate()` exists. */
+export const MIN_NODE_VERSION = '22.13.0';
+const BUSY_TIMEOUT_MS = 5_000;
+const PRIVATE_FILE_MODE = 0o600;
+let db;
+let warningFilterInstalled = false;
+/**
+ * Silence only Node's own "SQLite is experimental" notice.
+ *
+ * It goes to stderr, so it cannot corrupt the stdio protocol, but it is noise
+ * in every client's log. Matched on both the name and the message so that an
+ * unrelated ExperimentalWarning still reaches whoever was listening for it.
+ *
+ * Only listeners registered before the first store open are wrapped — which is
+ * the one that matters, Node's own default printer. A listener added later
+ * sees every warning, including this one, and that is the right trade: this
+ * exists to quieten a default, not to hide a warning from someone who went
+ * looking for it.
+ */
+function installWarningFilter() {
+    if (warningFilterInstalled)
+        return;
+    warningFilterInstalled = true;
+    const existing = process.listeners('warning');
+    for (const listener of existing)
+        process.removeListener('warning', listener);
+    process.on('warning', (warning) => {
+        if (warning.name === 'ExperimentalWarning' && warning.message.includes('SQLite'))
+            return;
+        for (const listener of existing)
+            listener(warning);
+    });
+}
+async function loadSqlite() {
+    try {
+        installWarningFilter();
+        // Annotated rather than inferred: a bare dynamic import widens to `any`,
+        // which would let every later misuse of the module through unchecked.
+        const sqlite = await import('node:sqlite');
+        return sqlite;
+    }
+    catch {
+        throw new YouTubeError('STORE_UNAVAILABLE', 'This Node build has no node:sqlite, which the harvest tools need.', {
+            nextStep: `Install Node ${MIN_NODE_VERSION} or newer (this process is ${process.version}). Every other tool works without it.`,
+        });
+    }
+}
+function isCorruption(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /malformed|not a database|SQLITE_CORRUPT|SQLITE_NOTADB/i.test(message);
+}
+function assertUsableVersion(found) {
+    if (found <= STORE_VERSION)
+        return;
+    // Operating on a schema written by a newer server is how data gets
+    // destroyed. Refusing is the only safe move, and naming both versions is
+    // what makes the refusal actionable.
+    throw new YouTubeError('STORE_CORRUPT', `This store was written by a newer version of the server (store v${String(found)}; this build understands v${String(STORE_VERSION)}).`, { nextStep: 'Upgrade youtube-knowledge-mcp, or point HOME at a different data directory.' });
+}
+async function openDatabase() {
+    const sqlite = await loadSqlite();
+    await ensurePrivateDir(storeDir());
+    const path = storeDatabasePath();
+    let opened;
+    try {
+        opened = new sqlite.DatabaseSync(path, {
+            timeout: BUSY_TIMEOUT_MS,
+            enableForeignKeyConstraints: true,
+        });
+        for (const pragma of STORE_PRAGMAS)
+            opened.exec(pragma);
+    }
+    catch (error) {
+        if (!isCorruption(error))
+            throw error;
+        throw new YouTubeError('STORE_CORRUPT', 'The harvested store could not be opened.', {
+            nextStep: 'Call repair_store to move the damaged file aside and start a fresh store.',
+            cause: error,
+        });
+    }
+    const version = readUserVersion(opened);
+    assertUsableVersion(version);
+    opened.exec(STORE_SCHEMA);
+    runStoreMigrations(opened, version);
+    // The database holds harvested personal data — commenter names, ids and
+    // free text — so it gets the same bits as the transcript cache rather than
+    // the umask default.
+    await chmod(path, PRIVATE_FILE_MODE).catch(() => undefined);
+    return opened;
+}
+export function readUserVersion(database) {
+    const row = database.prepare('PRAGMA user_version').get();
+    const value = row?.user_version;
+    return typeof value === 'number' ? value : 0;
+}
+export function writeUserVersion(database, version) {
+    // PRAGMA does not accept a bound parameter, so the value is constrained to an
+    // integer here rather than interpolated from anything a caller controls.
+    database.exec(`PRAGMA user_version = ${String(Math.trunc(version))}`);
+}
+/** The process-wide store connection, opened on first use. */
+export async function getStore() {
+    db ??= await openDatabase();
+    return db;
+}
+export function closeStore() {
+    db?.close();
+    db = undefined;
+}
+/**
+ * Moves a damaged database aside and starts a fresh one.
+ *
+ * Renames rather than deletes. Unlike `search-index.json`, which is derivable
+ * and is correctly rebuilt from disk, a harvest costs hours of network that no
+ * local cache can replay — so nothing here removes one without being asked.
+ */
+export async function quarantineStore(now = Date.now()) {
+    closeStore();
+    const target = corruptStorePath(now);
+    await rename(storeDatabasePath(), target);
+    return target;
+}
+/** Runs `work` in a transaction, rolling back if it throws. */
+export function inTransaction(database, work) {
+    database.exec('BEGIN');
+    try {
+        const result = work();
+        database.exec('COMMIT');
+        return result;
+    }
+    catch (error) {
+        database.exec('ROLLBACK');
+        throw error;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/utils/store.js.map

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

package/dist/utils/subtitles.d.ts

@@ -0,0 +1,7 @@
+import type { TranscriptSegment } from './transcript.js';
+/** Subtitle export: SRT and WebVTT for editors. */
+/** 3723.5 -> "01:02:03,500" — the SRT wire format. */
+export declare function formatSrtTimestamp(totalSeconds: number): string;
+export declare function toSrt(segments: TranscriptSegment[]): string;
+export declare function toVtt(segments: TranscriptSegment[]): string;
+//# sourceMappingURL=subtitles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subtitles.d.ts","sourceRoot":"","sources":["../../src/utils/subtitles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,mDAAmD;AAEnD,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED,wBAAgB,KAAK,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAY3D;AAED,wBAAgB,KAAK,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAW3D"}

package/dist/utils/subtitles.js

@@ -0,0 +1,30 @@
+/** Subtitle export: SRT and WebVTT for editors. */
+/** 3723.5 -> "01:02:03,500" — the SRT wire format. */
+export function formatSrtTimestamp(totalSeconds) {
+    const clamped = Math.max(0, totalSeconds);
+    const hours = Math.floor(clamped / 3600);
+    const minutes = Math.floor((clamped % 3600) / 60);
+    const seconds = Math.floor(clamped % 60);
+    const millis = Math.round((clamped - Math.floor(clamped)) * 1000);
+    const pad = (value, width = 2) => value.toString().padStart(width, '0');
+    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)},${pad(millis, 3)}`;
+}
+export function toSrt(segments) {
+    return (segments
+        .map((segment, index) => [
+        index + 1,
+        `${formatSrtTimestamp(segment.start)} --> ${formatSrtTimestamp(segment.end)}`,
+        segment.text,
+    ].join('\n'))
+        .join('\n\n') + '\n');
+}
+export function toVtt(segments) {
+    const body = segments
+        .map((segment) => [
+        `${formatSrtTimestamp(segment.start).replace(',', '.')} --> ${formatSrtTimestamp(segment.end).replace(',', '.')}`,
+        segment.text,
+    ].join('\n'))
+        .join('\n\n');
+    return `WEBVTT\n\n${body}\n`;
+}
+//# sourceMappingURL=subtitles.js.map

package/dist/utils/subtitles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtitles.js","sourceRoot":"","sources":["../../src/utils/subtitles.ts"],"names":[],"mappings":"AAEA,mDAAmD;AAEnD,sDAAsD;AACtD,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAElE,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,KAAK,GAAG,CAAC,EAAU,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACxF,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,QAA6B;IACjD,OAAO,CACL,QAAQ;SACL,GAAG,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CACtB;QACE,KAAK,GAAG,CAAC;QACT,GAAG,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;QAC7E,OAAO,CAAC,IAAI;KACb,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;SACA,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CACvB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,QAA6B;IACjD,MAAM,IAAI,GAAG,QAAQ;SAClB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACf;QACE,GAAG,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE;QACjH,OAAO,CAAC,IAAI;KACb,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;SACA,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,OAAO,aAAa,IAAI,IAAI,CAAC;AAC/B,CAAC"}

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

@@ -0,0 +1,19 @@
+import { type ChannelImage, type ThumbnailEntry, type ThumbnailManifest, type ThumbnailQuality, type ThumbnailTab } from '../thumbnail-schemas.js';
+import type { VideoListItem } from './youtube.js';
+/** One thumbnail at a time: what is recorded about it, and how it is fetched and saved. */
+export interface TabListing {
+    tab: ThumbnailTab;
+    videos: VideoListItem[];
+}
+/**
+ * Per-video entries, reconciled against the files actually on disk.
+ *
+ * A record that says `saved` whose file is missing or the wrong size goes back
+ * to `pending`; a video in today's listing that has no record gets one; and a
+ * record for a video not listed today is kept, since its file is still a
+ * thumbnail and the tab may simply not have been requested this time.
+ */
+export declare function reconciled(channelId: string, existing: ThumbnailManifest | undefined, listings: TabListing[]): Promise<Map<string, ThumbnailEntry>>;
+export declare function fetchOne(channelId: string, entry: ThumbnailEntry, quality: ThumbnailQuality): Promise<ThumbnailEntry>;
+export declare function channelImage(channelId: string, kind: 'avatar' | 'banner', url: string | undefined, recorded: ChannelImage | undefined): Promise<ChannelImage | undefined>;
+//# sourceMappingURL=thumbnail-entry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-entry.d.ts","sourceRoot":"","sources":["../../src/utils/thumbnail-entry.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AASjC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,2FAA2F;AAE3F,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,YAAY,CAAC;IAClB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAID;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,QAAQ,EAAE,UAAU,EAAE,GACrB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAetC;AA4BD,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,cAAc,CAAC,CAwBzB;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,YAAY,GAAG,SAAS,GACjC,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAkBnC"}

package/dist/utils/thumbnail-entry.js

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

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

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

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

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

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

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