youtube-knowledge-mcp 2.2.0 → 3.0.0

package/dist/utils/harvest-receipts.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { coverageSchema, harvestScopeSchema } from '../harvest-schemas.js';
+import { assertCoverageConsistent } from './coverage.js';
+import { queryRow, queryRows, sqliteBoolean } from './store-rows.js';
+/**
+ * Persisting completeness receipts.
+ *
+ * Written in the same transaction as the rows they describe. That is the whole
+ * reason this store is a database: there is no interval in which a receipt can
+ * claim something the store does not hold, so the reconciliation dance that
+ * `brain-build.ts` performs between its manifest and its chunks has no
+ * analogue here.
+ */
+const receiptRowSchema = z.object({
+    scope: harvestScopeSchema,
+    target_id: z.string(),
+    state: z.string(),
+    reason: z.string(),
+    have: z.number(),
+    expected: z.number().nullable(),
+    expected_source: z.string().nullable(),
+    source: z.string(),
+    limit_applied: z.number().nullable(),
+    sort_applied: z.string().nullable(),
+    ran_to_exhaustion: sqliteBoolean.nullable(),
+    resume_token: z.string().nullable(),
+    started_at: z.number(),
+    finished_at: z.number().nullable(),
+    attempts: z.number(),
+    error_code: z.string().nullable(),
+    note: z.string().nullable(),
+});
+const UPSERT = `
+INSERT INTO harvest_receipt (
+  scope, target_id, state, reason, have, expected, expected_source, source,
+  limit_applied, sort_applied, ran_to_exhaustion, resume_token,
+  started_at, finished_at, attempts, error_code, note
+) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+ON CONFLICT(scope, target_id) DO UPDATE SET
+  state = excluded.state, reason = excluded.reason, have = excluded.have,
+  expected = excluded.expected, expected_source = excluded.expected_source,
+  source = excluded.source, limit_applied = excluded.limit_applied,
+  sort_applied = excluded.sort_applied, ran_to_exhaustion = excluded.ran_to_exhaustion,
+  resume_token = excluded.resume_token, finished_at = excluded.finished_at,
+  attempts = harvest_receipt.attempts + 1, error_code = excluded.error_code,
+  note = excluded.note`;
+/** `complete` is the receipt's own word; the rest describe how it ended. */
+function stateOf(coverage) {
+    if (coverage.complete)
+        return 'complete';
+    if (coverage.reason === 'SOURCE_REFUSED' || coverage.reason === 'TIMEOUT')
+        return 'failed';
+    if (coverage.reason === 'NOT_ATTEMPTED')
+        return 'running';
+    return 'partial';
+}
+function toRow(coverage) {
+    // Re-checked on the way to disk as well as on the way out of coverageOf: a
+    // receipt that reaches storage wrong is one that will be believed later.
+    assertCoverageConsistent(coverage);
+    return coverage;
+}
+export function saveReceipt(database, coverage, options = {}) {
+    const checked = toRow(coverage);
+    const finishedAt = Date.parse(checked.harvestedAt);
+    database
+        .prepare(UPSERT)
+        .run(checked.scope, checked.targetId, stateOf(checked), checked.reason, checked.have, checked.expected ?? null, checked.expectedSource ?? null, checked.source, checked.limitApplied ?? null, checked.sortApplied ?? null, checked.ranToExhaustion === undefined ? null : Number(checked.ranToExhaustion), checked.resumeToken ?? null, options.startedAt ?? finishedAt, finishedAt, 0, options.errorCode ?? null, checked.note ?? null);
+    database
+        .prepare('INSERT INTO harvest_event (scope, target_id, at, state, delta, note) VALUES (?,?,?,?,?,?)')
+        .run(checked.scope, checked.targetId, finishedAt, stateOf(checked), checked.have, checked.reason);
+}
+function fromRow(row) {
+    const expected = row.expected;
+    const expectedSource = row.expected_source;
+    return coverageSchema.parse({
+        scope: row.scope,
+        targetId: row.target_id,
+        complete: row.state === 'complete',
+        reason: row.reason,
+        have: row.have,
+        ...(expected === null || expectedSource === null ? {} : { expected, expectedSource }),
+        ...(row.ran_to_exhaustion === null ? {} : { ranToExhaustion: row.ran_to_exhaustion }),
+        source: row.source,
+        harvestedAt: new Date(row.finished_at ?? row.started_at).toISOString(),
+        ...(row.limit_applied === null ? {} : { limitApplied: row.limit_applied }),
+        ...(row.sort_applied === null ? {} : { sortApplied: row.sort_applied }),
+        ...(row.resume_token === null ? {} : { resumeToken: row.resume_token }),
+        ...(row.note === null ? {} : { note: row.note }),
+    });
+}
+export function readReceipt(database, scope, targetId) {
+    const row = queryRow(database.prepare('SELECT * FROM harvest_receipt WHERE scope = ? AND target_id = ?'), receiptRowSchema, scope, targetId);
+    return row === undefined ? undefined : fromRow(row);
+}
+export function listReceipts(database, options = {}) {
+    const limit = options.limit ?? 50;
+    const offset = options.offset ?? 0;
+    const rows = options.scope === undefined
+        ? queryRows(database.prepare('SELECT * FROM harvest_receipt ORDER BY finished_at DESC, target_id LIMIT ? OFFSET ?'), receiptRowSchema, limit, offset)
+        : queryRows(database.prepare('SELECT * FROM harvest_receipt WHERE scope = ? ORDER BY finished_at DESC, target_id LIMIT ? OFFSET ?'), receiptRowSchema, options.scope, limit, offset);
+    return rows.map(fromRow);
+}
+export function countReceipts(database, scope) {
+    const row = scope === undefined
+        ? queryRow(database.prepare('SELECT COUNT(*) AS n FROM harvest_receipt'), z.object({ n: z.number() }))
+        : queryRow(database.prepare('SELECT COUNT(*) AS n FROM harvest_receipt WHERE scope = ?'), z.object({ n: z.number() }), scope);
+    return row?.n ?? 0;
+}
+//# sourceMappingURL=harvest-receipts.js.map

package/dist/utils/harvest-receipts.js.map

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

package/dist/utils/listing-cursor.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/**
+ * The cursor `fetch_videos` hands back.
+ *
+ * YouTube's listings are continuation-paginated, so `--playlist-items 101:120`
+ * still walks from the start: paging server-side is O(n) per page and O(n^2)
+ * overall. It is also not a cursor in any useful sense — a new upload shifts
+ * every index by one, so an offset silently re-reads or skips at the seam.
+ *
+ * So the cursor carries the next index *and* the id of the last item already
+ * returned. If that id reappears on the next page the listing moved under us,
+ * and the duplicate is dropped rather than handed over twice.
+ */
+declare const cursorSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    start: z.ZodNumber;
+    anchor: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    anchor: string;
+    start: number;
+    v: 1;
+}, {
+    anchor: string;
+    start: number;
+    v: 1;
+}>;
+export type ListingCursor = z.infer<typeof cursorSchema>;
+export declare function encodeCursor(cursor: ListingCursor): string;
+export declare function decodeCursor(token: string): ListingCursor;
+export {};
+//# sourceMappingURL=listing-cursor.d.ts.map

package/dist/utils/listing-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listing-cursor.d.ts","sourceRoot":"","sources":["../../src/utils/listing-cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AAEH,QAAA,MAAM,YAAY;;;;;;;;;;;;EAIhB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE1D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAezD"}

package/dist/utils/listing-cursor.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { YouTubeError } from './errors.js';
+/**
+ * The cursor `fetch_videos` hands back.
+ *
+ * YouTube's listings are continuation-paginated, so `--playlist-items 101:120`
+ * still walks from the start: paging server-side is O(n) per page and O(n^2)
+ * overall. It is also not a cursor in any useful sense — a new upload shifts
+ * every index by one, so an offset silently re-reads or skips at the seam.
+ *
+ * So the cursor carries the next index *and* the id of the last item already
+ * returned. If that id reappears on the next page the listing moved under us,
+ * and the duplicate is dropped rather than handed over twice.
+ */
+const cursorSchema = z.object({
+    v: z.literal(1),
+    start: z.number().int().min(1),
+    anchor: z.string(),
+});
+export function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');
+}
+export function decodeCursor(token) {
+    const parsed = (() => {
+        try {
+            return JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const result = cursorSchema.safeParse(parsed);
+    if (result.success)
+        return result.data;
+    throw new YouTubeError('INVALID_INPUT', 'That cursor is not one this server issued.', {
+        nextStep: 'Omit `cursor` to start from the first page.',
+    });
+}
+//# sourceMappingURL=listing-cursor.js.map

package/dist/utils/listing-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listing-cursor.js","sourceRoot":"","sources":["../../src/utils/listing-cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;GAWG;AAEH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AAIH,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,MAAM,GAAG,CAAC,GAAY,EAAE;QAC5B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAEL,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAEvC,MAAM,IAAI,YAAY,CAAC,eAAe,EAAE,4CAA4C,EAAE;QACpF,QAAQ,EAAE,6CAA6C;KACxD,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/pot-preflight.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Session preflight: what yt-dlp can prove about itself before we ask YouTube
+ * anything.
+ *
+ * Measured on 2026-09-06: with no PO token provider installed, every *player*
+ * request from this host failed with "Sign in to confirm you're not a bot",
+ * while flat listings were never affected. Rotating `player_client` across six
+ * clients and waiting out a 15-minute cooldown both failed. The cause was not
+ * rate limiting and not the address alone — `yt-dlp -v` reported
+ * `PO Token Providers: none`, so every player request went out without the
+ * integrity token a browser attaches.
+ *
+ * That diagnosis is only useful if the server can see it, so this module reads
+ * it out of yt-dlp's own debug output rather than guessing. It is deliberately
+ * provider-agnostic: it reports what yt-dlp says it has, and never looks for a
+ * particular plugin by name.
+ */
+export interface ProviderStatus {
+    name: string;
+    available: boolean;
+    /** Flags yt-dlp printed in parentheses, e.g. "external". */
+    flags: string[];
+}
+export interface SessionReport {
+    /** False when yt-dlp reports no usable PO token provider. */
+    potAvailable: boolean;
+    potProviders: ProviderStatus[];
+    jsRuntimes: ProviderStatus[];
+    impersonateTargets: string[];
+    /** Set when the probe itself could not run; the report is then unknown, not empty. */
+    probeFailed?: string;
+}
+/**
+ * Split on commas that separate entries, not the ones inside a parenthesised
+ * flag list. yt-dlp prints `bgutil:http-1.3.2 (external, unavailable)` — a
+ * plain `split(',')` tears that entry in half and loses the flag that matters.
+ */
+export declare function splitTopLevel(value: string): string[];
+/** Parses one `Providers: ...` payload. `none` is an empty list, not a provider. */
+export declare function parseProviderList(payload: string): ProviderStatus[];
+/**
+ * Reads `yt-dlp --list-impersonate-targets`, keeping only rows that are
+ * actually usable. Every target is unavailable without curl_cffi, and passing
+ * `--impersonate` to a build that lacks it fails every spawn — so an
+ * unavailable target must be visible here rather than discovered per request.
+ */
+export declare function parseImpersonateTargets(stdout: string): string[];
+export declare function runSessionPreflight(options?: {
+    force?: boolean;
+}): Promise<SessionReport>;
+/** Test seam — the report is cached for the process lifetime in normal use. */
+export declare function resetSessionPreflightCache(): void;
+//# sourceMappingURL=pot-preflight.d.ts.map

package/dist/utils/pot-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pot-preflight.d.ts","sourceRoot":"","sources":["../../src/utils/pot-preflight.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAyBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBrD;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAenE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBhE;AAqBD,wBAAsB,mBAAmB,CACvC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,aAAa,CAAC,CAwCxB;AAED,+EAA+E;AAC/E,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD"}

package/dist/utils/pot-preflight.js

@@ -0,0 +1,146 @@
+import { execa } from 'execa';
+const PROBE_TIMEOUT_MS = 30_000;
+const FAILED_REPORT_TTL_MS = 60_000;
+/**
+ * The `[youtube] [pot]` and `[youtube] [jsc]` debug lines are emitted only when
+ * the *video* extractor initialises. Measured 2026-09-06: `--version`,
+ * `ytsearch0:` and a `--flat-playlist` channel walk all produce neither line —
+ * the listing plane never touches either subsystem.
+ *
+ * So the probe uses a syntactically valid but nonexistent video id. yt-dlp
+ * initialises the extractor, prints both lines, then fails the lookup. That
+ * failure is expected and ignored: it costs one request, depends on no real
+ * video continuing to exist, and needs no fixture to be kept up to date.
+ */
+const PROBE_VIDEO_URL = 'https://www.youtube.com/watch?v=00000000000';
+const PROBE_ARGS = ['-v', '--simulate', '--skip-download', PROBE_VIDEO_URL];
+const POT_LINE = /PO Token Providers:\s*(.+)$/;
+const JSC_LINE = /JS Challenge Providers:\s*(.+)$/;
+let cached;
+let cachedAt = 0;
+/**
+ * Split on commas that separate entries, not the ones inside a parenthesised
+ * flag list. yt-dlp prints `bgutil:http-1.3.2 (external, unavailable)` — a
+ * plain `split(',')` tears that entry in half and loses the flag that matters.
+ */
+export function splitTopLevel(value) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < value.length; i += 1) {
+        const char = value[i];
+        if (char === '(')
+            depth += 1;
+        else if (char === ')')
+            depth = Math.max(0, depth - 1);
+        else if (char === ',' && depth === 0) {
+            parts.push(value.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(value.slice(start));
+    return parts.map((part) => part.trim()).filter((part) => part.length > 0);
+}
+/** Parses one `Providers: ...` payload. `none` is an empty list, not a provider. */
+export function parseProviderList(payload) {
+    const trimmed = payload.trim();
+    if (trimmed === '' || trimmed.toLowerCase() === 'none')
+        return [];
+    return splitTopLevel(trimmed).map((entry) => {
+        const match = /^(.*?)\s*\((.*)\)$/.exec(entry);
+        if (match === null)
+            return { name: entry, available: true, flags: [] };
+        const flags = splitTopLevel(match[2] ?? '').map((flag) => flag.toLowerCase());
+        return {
+            name: (match[1] ?? '').trim(),
+            available: !flags.includes('unavailable'),
+            flags,
+        };
+    });
+}
+/**
+ * Reads `yt-dlp --list-impersonate-targets`, keeping only rows that are
+ * actually usable. Every target is unavailable without curl_cffi, and passing
+ * `--impersonate` to a build that lacks it fails every spawn — so an
+ * unavailable target must be visible here rather than discovered per request.
+ */
+export function parseImpersonateTargets(stdout) {
+    const targets = [];
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('[') || line.startsWith('-'))
+            continue;
+        if (line.toLowerCase().startsWith('client'))
+            continue;
+        if (line.toLowerCase().includes('(unavailable)'))
+            continue;
+        const columns = line.split(/\s{2,}/).filter((column) => column.length > 0);
+        const client = columns[0]?.trim();
+        if (client === undefined || client === '')
+            continue;
+        const os = columns[1]?.trim();
+        targets.push(os === undefined || os === '' || os === '-' ? client : `${client}:${os}`);
+    }
+    return targets;
+}
+async function probe(args) {
+    try {
+        // yt-dlp writes debug lines to stderr and exits non-zero on some probes;
+        // `reject: false` keeps both streams instead of throwing them away.
+        const result = await execa('yt-dlp', args, { timeout: PROBE_TIMEOUT_MS, reject: false });
+        return { stdout: result.stdout, stderr: result.stderr };
+    }
+    catch {
+        return undefined;
+    }
+}
+function readProviders(output, pattern) {
+    for (const line of output.split('\n')) {
+        const match = pattern.exec(line);
+        if (match !== null)
+            return parseProviderList(match[1] ?? '');
+    }
+    return [];
+}
+export async function runSessionPreflight(options = {}) {
+    // Mirrors runPreflight: a good answer holds for the process, a bad one gets a
+    // short life so one slow spawn does not pin the diagnosis for good.
+    if (cached !== undefined && !options.force) {
+        if (cached.probeFailed === undefined || Date.now() - cachedAt < FAILED_REPORT_TTL_MS) {
+            return cached;
+        }
+    }
+    const [session, impersonate] = await Promise.all([
+        probe(PROBE_ARGS),
+        probe(['--list-impersonate-targets']),
+    ]);
+    if (session === undefined) {
+        cached = {
+            potAvailable: false,
+            potProviders: [],
+            jsRuntimes: [],
+            impersonateTargets: [],
+            probeFailed: 'yt-dlp could not be probed for session capabilities.',
+        };
+        cachedAt = Date.now();
+        return cached;
+    }
+    const output = `${session.stderr}\n${session.stdout}`;
+    const potProviders = readProviders(output, POT_LINE);
+    cached = {
+        potAvailable: potProviders.some((provider) => provider.available),
+        potProviders,
+        jsRuntimes: readProviders(output, JSC_LINE),
+        impersonateTargets: impersonate === undefined
+            ? []
+            : parseImpersonateTargets(`${impersonate.stdout}\n${impersonate.stderr}`),
+    };
+    cachedAt = Date.now();
+    return cached;
+}
+/** Test seam — the report is cached for the process lifetime in normal use. */
+export function resetSessionPreflightCache() {
+    cached = undefined;
+    cachedAt = 0;
+}
+//# sourceMappingURL=pot-preflight.js.map

package/dist/utils/pot-preflight.js.map

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

package/dist/utils/sleep.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A cancellable pause.
+ *
+ * Shared by the retry loop and the pacer so a cooling-down server still
+ * answers a client that gives up: an uncancellable sleep is how a cooldown
+ * turns into a wedge.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../src/utils/sleep.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB3E"}

package/dist/utils/sleep.js

@@ -0,0 +1,25 @@
+import { YouTubeError } from './errors.js';
+/**
+ * A cancellable pause.
+ *
+ * Shared by the retry loop and the pacer so a cooling-down server still
+ * answers a client that gives up: an uncancellable sleep is how a cooldown
+ * turns into a wedge.
+ */
+export async function sleep(ms, signal) {
+    if (signal?.aborted === true) {
+        throw new YouTubeError('CANCELLED', 'The request was cancelled.');
+    }
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new YouTubeError('CANCELLED', 'The request was cancelled.'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=sleep.js.map

package/dist/utils/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../../src/utils/sleep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC1D,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,YAAY,CAAC,WAAW,EAAE,4BAA4B,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,IAAI,YAAY,CAAC,WAAW,EAAE,4BAA4B,CAAC,CAAC,CAAC;QACtE,CAAC,CAAC;QACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,37 @@
+/**
+ * What can be said about the store without harvesting anything.
+ *
+ * Integrity is checked here and nowhere else on the hot path: `quick_check` is
+ * bounded and catches the realistic failures, while the full `integrity_check`
+ * is O(database) and would add seconds to every server start on a store that
+ * is measured in gigabytes.
+ */
+export interface StoreHealth {
+    enabled: boolean;
+    path: string;
+    exists: boolean;
+    storeVersion?: number;
+    sizeBytes: number;
+    walBytes: number;
+    integrity: 'ok' | 'failed' | 'unchecked';
+    channels: number;
+    videos: number;
+    comments: number;
+    receipts: {
+        complete: number;
+        partial: number;
+        running: number;
+        failed: number;
+    };
+    error?: string;
+}
+export declare function readStoreHealth(): Promise<StoreHealth>;
+/**
+ * Whether the store should make an overall health report say "not ready".
+ *
+ * A missing store must not: a fresh install has none, and check_health's job
+ * is diagnosing the external binaries. A store that fails its integrity check,
+ * or claims a version this build does not understand, must.
+ */
+export declare function storeFailsHealth(health: StoreHealth): boolean;
+//# sourceMappingURL=store-health.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store-health.d.ts","sourceRoot":"","sources":["../../src/utils/store-health.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AAEH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,IAAI,GAAG,QAAQ,GAAG,WAAW,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAiBD,wBAAsB,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CA0D5D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAG7D"}

package/dist/utils/store-health.js

@@ -0,0 +1,92 @@
+import { stat } from 'node:fs/promises';
+import { z } from 'zod';
+import { countRows, queryRow } from './store-rows.js';
+import { getStore, readUserVersion } from './store.js';
+import { storeDatabasePath } from './store-paths.js';
+import { STORE_VERSION } from './store-schema.js';
+const quickCheckSchema = z.object({ quick_check: z.string() }).passthrough();
+const stateCountSchema = z.object({ state: z.string(), n: z.number() }).passthrough();
+async function sizeOf(path) {
+    try {
+        return (await stat(path)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function emptyReceipts() {
+    return { complete: 0, partial: 0, running: 0, failed: 0 };
+}
+export async function readStoreHealth() {
+    const path = storeDatabasePath();
+    const [sizeBytes, walBytes] = await Promise.all([sizeOf(path), sizeOf(`${path}-wal`)]);
+    const base = {
+        enabled: true,
+        path,
+        exists: sizeBytes > 0,
+        sizeBytes,
+        // A -wal file that never shrinks means a reader is pinning it, which is
+        // worth seeing before it becomes a disk-space surprise.
+        walBytes,
+        integrity: 'unchecked',
+        channels: 0,
+        videos: 0,
+        comments: 0,
+        receipts: emptyReceipts(),
+    };
+    try {
+        const store = await getStore();
+        const quick = queryRow(store.prepare('PRAGMA quick_check'), quickCheckSchema);
+        const receipts = emptyReceipts();
+        for (const row of store
+            .prepare('SELECT state, COUNT(*) AS n FROM harvest_receipt GROUP BY state')
+            .all()) {
+            const parsed = stateCountSchema.safeParse(row);
+            if (!parsed.success)
+                continue;
+            // A `state` this build does not know about is counted nowhere rather
+            // than crashing: the enum is allowed to grow ahead of this reader.
+            const { state, n } = parsed.data;
+            if (state === 'complete')
+                receipts.complete = n;
+            else if (state === 'partial')
+                receipts.partial = n;
+            else if (state === 'running')
+                receipts.running = n;
+            else if (state === 'failed')
+                receipts.failed = n;
+        }
+        return {
+            ...base,
+            storeVersion: readUserVersion(store),
+            integrity: quick?.quick_check === 'ok' ? 'ok' : 'failed',
+            channels: countRows(store.prepare('SELECT COUNT(*) FROM channel')),
+            videos: countRows(store.prepare('SELECT COUNT(*) FROM video')),
+            comments: countRows(store.prepare('SELECT COUNT(*) FROM comment')),
+            receipts,
+        };
+    }
+    catch (error) {
+        // A store that cannot be opened is a reportable condition, not a reason
+        // for check_health itself to fail: the binaries it exists to diagnose are
+        // unaffected.
+        return {
+            ...base,
+            enabled: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Whether the store should make an overall health report say "not ready".
+ *
+ * A missing store must not: a fresh install has none, and check_health's job
+ * is diagnosing the external binaries. A store that fails its integrity check,
+ * or claims a version this build does not understand, must.
+ */
+export function storeFailsHealth(health) {
+    if (health.integrity === 'failed')
+        return true;
+    return health.storeVersion !== undefined && health.storeVersion > STORE_VERSION;
+}
+//# sourceMappingURL=store-health.js.map

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

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

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

@@ -0,0 +1,33 @@
+import type { DatabaseSync } from 'node:sqlite';
+/**
+ * Ordered schema migrations for the harvested store.
+ *
+ * `PRAGMA user_version` carries the store's version, deliberately independent
+ * of the server's semver: the schema changes far less often than the code, and
+ * tying them together would force an empty migration on every release.
+ *
+ * Version 0 means "no store yet". Creating the tables is `STORE_SCHEMA`'s job,
+ * not a migration's, so the first run only stamps the version.
+ */
+export interface StoreMigration {
+    /** The version this migration produces. */
+    to: number;
+    apply: (database: DatabaseSync) => void;
+}
+/**
+ * Empty on purpose at v1: `STORE_SCHEMA` is `CREATE TABLE IF NOT EXISTS`
+ * throughout, so a fresh database and an existing v1 database converge without
+ * one. The list exists so the second schema change is a one-line addition
+ * rather than a retrofit.
+ */
+export declare const STORE_MIGRATIONS: readonly StoreMigration[];
+/**
+ * Brings a database up to STORE_VERSION.
+ *
+ * Each migration runs inside its own transaction so a failure leaves the
+ * store at the last version that fully applied, rather than half-way through
+ * one. A newer-than-known version is rejected before this is reached, in
+ * `store.ts`.
+ */
+export declare function runStoreMigrations(database: DatabaseSync, fromVersion: number): number;
+//# sourceMappingURL=store-migrations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store-migrations.d.ts","sourceRoot":"","sources":["../../src/utils/store-migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;CACzC;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAAO,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAwBtF"}