youtube-knowledge-mcp 2.0.2 → 2.2.0

package/dist/utils/validate-youtube.js

@@ -0,0 +1,87 @@
+import { YouTubeError } from './errors.js';
+/**
+ * The identifiers and URLs this server is willing to hand to yt-dlp.
+ *
+ * A tool argument is model-controlled, and yt-dlp's generic extractor will
+ * fetch any URL it is given — including internal addresses — so anything that
+ * becomes a yt-dlp target is checked here first. Ids are also filenames, so the
+ * real formats are matched exactly rather than sanitised.
+ */
+/** YouTube video ids are 11 base64url characters. */
+export const VIDEO_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
+export function assertVideoId(videoId) {
+    if (!VIDEO_ID_PATTERN.test(videoId)) {
+        throw new YouTubeError('INVALID_INPUT', `"${clip(videoId)}" is not a valid YouTube video id.`, {
+            nextStep: 'Video ids are 11 characters, for example dQw4w9WgXcQ.',
+        });
+    }
+    return videoId;
+}
+/**
+ * YouTube channel ids are `UC` followed by 22 base64url characters.
+ *
+ * This is stricter than it looks like it needs to be. A channel id arrives from
+ * yt-dlp's output and is then used as a directory name under
+ * `~/.youtube-knowledge/brains`, so a value containing a separator or `..`
+ * would write outside that tree. Matching the real format exactly is cheaper
+ * than sanitising a value that should never have been unusual.
+ */
+export const CHANNEL_ID_PATTERN = /^UC[A-Za-z0-9_-]{22}$/;
+export function assertChannelId(channelId) {
+    if (!CHANNEL_ID_PATTERN.test(channelId)) {
+        throw new YouTubeError('INVALID_INPUT', `"${clip(channelId)}" is not a valid YouTube channel id.`, {
+            nextStep: 'Channel ids look like UCxxxxxxxxxxxxxxxxxxxxxx. Call get_channel_info or list_brains to get one.',
+        });
+    }
+    return channelId;
+}
+/** The hosts yt-dlp may be pointed at. Anything else is refused before it spawns. */
+export const YOUTUBE_HOSTS = [
+    'youtube.com',
+    'www.youtube.com',
+    'm.youtube.com',
+    'music.youtube.com',
+    'youtu.be',
+    'www.youtube-nocookie.com',
+];
+const HOST_SET = new Set(YOUTUBE_HOSTS);
+const SCHEMELESS_YOUTUBE = /^(?:www\.|m\.|music\.)?(?:youtube\.com|youtu\.be)\//i;
+/**
+ * Validate a caller-supplied URL and return it normalised to https.
+ *
+ * `http:` is upgraded rather than refused, and a URL written without a scheme
+ * but starting with a YouTube host is accepted, because both are things people
+ * paste. Everything else — other hosts, other schemes, credentials, ports — is
+ * an `INVALID_INPUT`, since the only reason to send one is to make yt-dlp fetch
+ * something that is not YouTube.
+ */
+export function assertYouTubeUrl(input) {
+    const trimmed = input.trim();
+    const candidate = SCHEMELESS_YOUTUBE.test(trimmed) ? `https://${trimmed}` : trimmed;
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch {
+        throw notYouTube(input);
+    }
+    if (url.protocol === 'http:')
+        url.protocol = 'https:';
+    const wrongScheme = url.protocol !== 'https:';
+    const wrongHost = !HOST_SET.has(url.hostname.toLowerCase());
+    const hasCredentials = url.username !== '' || url.password !== '';
+    const hasPort = url.port !== '';
+    if (wrongScheme || wrongHost || hasCredentials || hasPort)
+        throw notYouTube(input);
+    return url.toString();
+}
+function notYouTube(input) {
+    return new YouTubeError('INVALID_INPUT', `"${clip(input)}" is not a YouTube URL.`, {
+        nextStep: `Pass an https URL on one of: ${YOUTUBE_HOSTS.join(', ')}.`,
+    });
+}
+/** Keeps a rejected value from flooding the error message it is quoted in. */
+function clip(value) {
+    return value.length > 64 ? `${value.slice(0, 61)}...` : value;
+}
+//# sourceMappingURL=validate-youtube.js.map

package/dist/utils/validate-youtube.js.map

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

package/dist/utils/validate.d.ts

@@ -1,16 +1,24 @@
 /**
  * Input validation for the values that reach the filesystem or yt-dlp's
- * language negotiation. Zod already constrains shapes at the tool boundary;
+ * language negotiation. The YouTube-specific checks — ids and URLs — live in
+ * validate-youtube.ts and are re-exported here. Zod already constrains shapes at the tool boundary;
  * these are the checks Zod cannot express.
  */
 /**
- * Resolve a caller-supplied output directory.
+ * Prove that a caller-supplied path lies inside the home directory.
  *
  * A tool argument is model-controlled, so it must not be able to write outside
- * the user's home directory or reach the filesystem root through `..`.
+ * the user's home directory or reach the filesystem root through `..`. The
+ * check is made on the real path: a symlink inside home that points outside it
+ * passed a purely lexical comparison, and yt-dlp and ffmpeg then wrote through
+ * it. The nearest existing ancestor is resolved and the missing tail re-joined,
+ * so a directory that does not exist yet is judged by where it would be created.
  */
+export declare function assertInsideHome(input: string, what: string): string;
+/** Resolve a caller-supplied output directory, or the fallback when none is given. */
 export declare function resolveOutputDir(outputDir: string | undefined, fallback: string): string;
 export declare function assertLanguageTag(language: string): string;
 /** Accepts `90`, `1:30`, `01:02:03`, `1:30.5` and returns seconds. */
 export declare function parseTimestamp(value: string | number, field: string): number;
+export * from './validate-youtube.js';
 //# sourceMappingURL=validate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAyBxF;AAKD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO1D;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAoB5E"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBpE;AAkBD,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxF;AAKD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO1D;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAoB5E;AAED,cAAc,uBAAuB,CAAC"}

package/dist/utils/validate.js

@@ -1,35 +1,59 @@
+import { existsSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, normalize, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, normalize, resolve, sep } from 'node:path';
 import { YouTubeError } from './errors.js';
 /**
  * Input validation for the values that reach the filesystem or yt-dlp's
- * language negotiation. Zod already constrains shapes at the tool boundary;
+ * language negotiation. The YouTube-specific checks — ids and URLs — live in
+ * validate-youtube.ts and are re-exported here. Zod already constrains shapes at the tool boundary;
  * these are the checks Zod cannot express.
  */
 /**
- * Resolve a caller-supplied output directory.
+ * Prove that a caller-supplied path lies inside the home directory.
  *
  * A tool argument is model-controlled, so it must not be able to write outside
- * the user's home directory or reach the filesystem root through `..`.
+ * the user's home directory or reach the filesystem root through `..`. The
+ * check is made on the real path: a symlink inside home that points outside it
+ * passed a purely lexical comparison, and yt-dlp and ffmpeg then wrote through
+ * it. The nearest existing ancestor is resolved and the missing tail re-joined,
+ * so a directory that does not exist yet is judged by where it would be created.
  */
-export function resolveOutputDir(outputDir, fallback) {
-    if (outputDir === undefined || outputDir.trim() === '')
-        return fallback;
-    const expanded = outputDir.startsWith('~')
-        ? resolve(homedir(), outputDir.slice(1).replace(/^[/\\]/, ''))
-        : resolve(normalize(outputDir));
-    if (expanded.includes('\0')) {
-        throw new YouTubeError('INVALID_INPUT', 'The output directory path is not valid.', {
-            nextStep: 'Provide a plain directory path, for example ~/Videos.',
+export function assertInsideHome(input, what) {
+    if (input.includes('\0')) {
+        throw new YouTubeError('INVALID_INPUT', `The ${what} path is not valid.`, {
+            nextStep: 'Provide a plain path, for example ~/Videos.',
         });
     }
-    const home = resolve(homedir());
-    if (!isAbsolute(expanded) || !(expanded === home || expanded.startsWith(home + sep))) {
-        throw new YouTubeError('INVALID_INPUT', 'Downloads must be written inside your home directory.', {
-            nextStep: `Choose a path under ${home}, or omit outputDir to use the default location.`,
+    const expanded = input.startsWith('~')
+        ? resolve(homedir(), input.slice(1).replace(/^[/\\]/, ''))
+        : resolve(normalize(input));
+    const home = realpathSync(homedir());
+    const real = realpathOfNearestAncestor(expanded);
+    if (!isAbsolute(real) || !(real === home || real.startsWith(home + sep))) {
+        throw new YouTubeError('INVALID_INPUT', `The ${what} must be inside your home directory.`, {
+            nextStep: `Choose a path under ${home}, or omit it to use the default location.`,
         });
     }
-    return expanded;
+    return real;
+}
+/**
+ * The real path of `target`, resolving symlinks in whichever prefix of it
+ * exists. The walk stops at the filesystem root, which always exists.
+ */
+function realpathOfNearestAncestor(target) {
+    const missing = [];
+    let probe = target;
+    while (dirname(probe) !== probe && !existsSync(probe)) {
+        missing.unshift(basename(probe));
+        probe = dirname(probe);
+    }
+    return join(realpathSync(probe), ...missing);
+}
+/** Resolve a caller-supplied output directory, or the fallback when none is given. */
+export function resolveOutputDir(outputDir, fallback) {
+    if (outputDir === undefined || outputDir.trim() === '')
+        return fallback;
+    return assertInsideHome(outputDir, 'output directory');
 }
 /** BCP-47-ish: `en`, `pt-BR`, `zh-Hans`, plus yt-dlp's `-orig` suffix. */
 const LANGUAGE_PATTERN = /^[a-zA-Z]{2,8}(?:-[a-zA-Z0-9]{2,8})*$/;
@@ -61,4 +85,5 @@ export function parseTimestamp(value, field) {
     // The hours group is optional, so it is genuinely absent for "MM:SS" input.
     return Number(match[1] ?? 0) * 3600 + Number(match[2] ?? 0) * 60 + Number(match[3] ?? 0);
 }
+export * from './validate-youtube.js';
 //# sourceMappingURL=validate.js.map

package/dist/utils/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAA6B,EAAE,QAAgB;IAC9E,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAExE,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC;QACxC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC9D,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;IAElC,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CAAC,eAAe,EAAE,yCAAyC,EAAE;YACjF,QAAQ,EAAE,uDAAuD;SAClE,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAChC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,YAAY,CACpB,eAAe,EACf,uDAAuD,EACvD;YACE,QAAQ,EAAE,uBAAuB,IAAI,kDAAkD;SACxF,CACF,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,0EAA0E;AAC1E,MAAM,gBAAgB,GAAG,uCAAuC,CAAC;AAEjE,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,YAAY,CAAC,eAAe,EAAE,IAAI,QAAQ,iCAAiC,EAAE;YACrF,QAAQ,EAAE,wDAAwD;SACnE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,cAAc,CAAC,KAAsB,EAAE,KAAa;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,YAAY,CAAC,eAAe,EAAE,GAAG,KAAK,4CAA4C,CAAC,CAAC;QAChG,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IAE1D,MAAM,KAAK,GAAG,8CAA8C,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,YAAY,CAAC,eAAe,EAAE,GAAG,KAAK,MAAM,KAAK,8BAA8B,EAAE;YACzF,QAAQ,EAAE,yDAAyD;SACpE,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3F,CAAC"}
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"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"}

package/dist/utils/version.d.ts

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

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

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

package/dist/utils/version.js

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

package/dist/utils/version.js.map

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

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

@@ -0,0 +1,44 @@
+import { type ListedImage } from './flat-listing.js';
+/** Listings and metadata for channels and playlists. */
+export interface VideoListItem {
+    id: string;
+    title: string;
+    duration: number;
+    durationFormatted: string;
+    /** Empty for a flat listing, which carries no publication date. */
+    uploadDate: string;
+    url: string;
+    /** The largest thumbnail the listing offered. */
+    thumbnailUrl?: string;
+    /** Every thumbnail the listing offered, with sizes where known. */
+    thumbnails?: ListedImage[];
+    viewCount?: number;
+    liveStatus?: string;
+}
+export interface ChannelInfo {
+    name: string;
+    channelId: string;
+    handle: string;
+    subscriberCount: number;
+    channelUrl: string;
+    description: string;
+    /** The channel's uncropped avatar, when yt-dlp listed one. */
+    avatarUrl?: string;
+    /** The channel's uncropped banner, when yt-dlp listed one. */
+    bannerUrl?: string;
+}
+export interface PlaylistInfo {
+    id: string;
+    title: string;
+    channel: string;
+    handle: string;
+    channelUrl: string;
+    videoCount: number;
+    lastModified: string;
+    url: string;
+    description: string;
+}
+export declare function listVideos(urlOrChannel: string, limit?: number): Promise<VideoListItem[]>;
+export declare function getPlaylistInfo(playlistUrl: string): Promise<PlaylistInfo>;
+export declare function getChannelInfo(channel: string): Promise<ChannelInfo>;
+//# sourceMappingURL=youtube-channel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"youtube-channel.d.ts","sourceRoot":"","sources":["../../src/utils/youtube-channel.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAK3B,wDAAwD;AAExD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,UAAU,CAAC,EAAE,WAAW,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAkB3F;AAED,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAwBhF;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAwB1E"}

package/dist/utils/youtube-channel.js

@@ -0,0 +1,61 @@
+import { formatYouTubeDate } from './format.js';
+import { TIMEOUTS, parseYtDlpJson, parseYtDlpJsonLines, runYtDlp } from './ytdlp.js';
+import { FLAT_PRINT_TEMPLATE, flatEntrySchema, toVideoListItem, } from './flat-listing.js';
+import { selectChannelImages } from './channel-images.js';
+import { channelMetaSchema, playlistMetaSchema } from './youtube-schemas.js';
+import { channelUrlFor, resolveListTarget } from './youtube-url.js';
+export async function listVideos(urlOrChannel, limit = 20) {
+    const stdout = await runYtDlp([
+        '--skip-download',
+        '--flat-playlist',
+        '--print',
+        FLAT_PRINT_TEMPLATE,
+        '--playlist-end',
+        limit.toString(),
+    ], {
+        label: 'fetch_videos',
+        timeoutMs: TIMEOUTS.transcript,
+        target: resolveListTarget(urlOrChannel),
+    });
+    return parseYtDlpJsonLines(stdout, flatEntrySchema).map(toVideoListItem);
+}
+export async function getPlaylistInfo(playlistUrl) {
+    const target = resolveListTarget(playlistUrl);
+    const stdout = await runYtDlp(['--dump-single-json', '--flat-playlist', '--playlist-items', '0'], {
+        label: 'get_playlist_info',
+        target,
+    });
+    const data = parseYtDlpJson(stdout, playlistMetaSchema, 'playlist metadata');
+    const modDate = data.modified_date ?? '';
+    return {
+        id: data.id ?? '',
+        title: data.title ?? 'Unknown',
+        channel: data.channel ?? '',
+        handle: data.uploader_id ?? '',
+        channelUrl: data.channel_url ?? '',
+        videoCount: data.playlist_count ?? 0,
+        lastModified: formatYouTubeDate(modDate),
+        url: data.webpage_url ?? playlistUrl,
+        description: data.description ?? '',
+    };
+}
+export async function getChannelInfo(channel) {
+    const channelUrl = channelUrlFor(channel);
+    const stdout = await runYtDlp(['--dump-single-json', '--flat-playlist', '--playlist-items', '0'], {
+        label: 'get_channel_info',
+        target: channelUrl,
+    });
+    const data = parseYtDlpJson(stdout, channelMetaSchema, 'channel metadata');
+    return {
+        name: data.channel ?? 'Unknown',
+        channelId: data.channel_id ?? '',
+        handle: data.uploader_id ?? '',
+        subscriberCount: data.channel_follower_count ?? 0,
+        channelUrl: data.channel_url ?? channelUrl,
+        description: data.description ?? '',
+        // The same listing carries the avatar and banner; they were discarded here
+        // for two releases.
+        ...selectChannelImages(data.thumbnails),
+    };
+}
+//# sourceMappingURL=youtube-channel.js.map

package/dist/utils/youtube-channel.js.map

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

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

@@ -0,0 +1,27 @@
+export interface VideoFormat {
+    formatId: string;
+    ext: string;
+    resolution: string;
+    fps?: number;
+    vcodec: string;
+    acodec: string;
+    filesize?: number;
+    note: string;
+}
+export interface DownloadResult {
+    videoId: string;
+    title: string;
+    filePath: string;
+    format: string;
+}
+export declare function listFormats(urlOrId: string): Promise<VideoFormat[]>;
+export type VideoQuality = 'best' | '2160p' | '1440p' | '1080p' | '720p' | '480p' | '360p' | 'audio';
+export declare const QUALITY_FORMAT_SELECTORS: Record<VideoQuality, string>;
+export declare function downloadVideo(urlOrId: string, formatId: string, outputDir?: string, quality?: VideoQuality): Promise<DownloadResult>;
+/** The after_move print: the last JSON line yt-dlp wrote, with the path it wrote to. */
+export declare const AFTER_MOVE_TEMPLATE = "after_move:%(.{title,filepath})j";
+export declare function readAfterMove(stdout: string): {
+    title: string | undefined;
+    filepath: string;
+};
+//# sourceMappingURL=youtube-download.d.ts.map

package/dist/utils/youtube-download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"youtube-download.d.ts","sourceRoot":"","sources":["../../src/utils/youtube-download.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAyBzE;AAED,MAAM,MAAM,YAAY,GACtB,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAG5E,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAejE,CAAC;AAEF,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,cAAc,CAAC,CA+DzB;AAED,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,qCAAqC,CAAC;AAEtE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAa7F"}

package/dist/utils/youtube-download.js

@@ -0,0 +1,118 @@
+import { join } from 'path';
+import { mkdir } from 'fs/promises';
+import { TIMEOUTS, parseYtDlpJson, runYtDlp } from './ytdlp.js';
+import { YouTubeError } from './errors.js';
+import { afterMoveRowSchema, formatsRowSchema } from './youtube-schemas.js';
+import { resolveOutputDir } from './validate.js';
+import { log } from './context.js';
+import { dataDir } from './paths.js';
+import { extractVideoId, watchUrl } from './youtube-url.js';
+/** Format listing and whole-video downloads. */
+const DOWNLOADS_DIR = dataDir('downloads');
+export async function listFormats(urlOrId) {
+    const videoId = extractVideoId(urlOrId);
+    const url = watchUrl(videoId);
+    const stdout = await runYtDlp(['-j', '--skip-download'], { label: 'list_formats', target: url });
+    const data = parseYtDlpJson(stdout, formatsRowSchema, 'video formats');
+    const formats = data.formats ?? [];
+    return formats
+        .filter((f) => !f.format_id.startsWith('sb')) // skip storyboards
+        .map((f) => {
+        const resolution = f.resolution ?? (f.width && f.height ? `${f.width}x${f.height}` : 'audio only');
+        return {
+            formatId: f.format_id,
+            ext: f.ext,
+            resolution,
+            fps: f.fps ?? undefined,
+            vcodec: f.vcodec ?? 'none',
+            acodec: f.acodec ?? 'none',
+            filesize: f.filesize ?? f.filesize_approx ?? undefined,
+            note: f.format_note ?? '',
+        };
+    });
+}
+// Smart format selectors that use yt-dlp's fallback syntax
+export const QUALITY_FORMAT_SELECTORS = {
+    best: 'bestvideo*+bestaudio/best',
+    '2160p': 'bestvideo[height<=2160]+bestaudio/bestvideo*[height<=2160]+bestaudio/best[height<=2160]/bestvideo+bestaudio/best',
+    '1440p': 'bestvideo[height<=1440]+bestaudio/bestvideo*[height<=1440]+bestaudio/best[height<=1440]/bestvideo+bestaudio/best',
+    '1080p': 'bestvideo[height<=1080]+bestaudio/bestvideo*[height<=1080]+bestaudio/best[height<=1080]/bestvideo+bestaudio/best',
+    '720p': 'bestvideo[height<=720]+bestaudio/bestvideo*[height<=720]+bestaudio/best[height<=720]/bestvideo+bestaudio/best',
+    '480p': 'bestvideo[height<=480]+bestaudio/bestvideo*[height<=480]+bestaudio/best[height<=480]/bestvideo+bestaudio/best',
+    '360p': 'bestvideo[height<=360]+bestaudio/bestvideo*[height<=360]+bestaudio/best[height<=360]/bestvideo+bestaudio/best',
+    audio: 'bestaudio/best',
+};
+export async function downloadVideo(urlOrId, formatId, outputDir, quality) {
+    const videoId = extractVideoId(urlOrId);
+    const url = watchUrl(videoId);
+    const targetDir = resolveOutputDir(outputDir, DOWNLOADS_DIR);
+    // Ensure download directory exists
+    await mkdir(targetDir, { recursive: true });
+    // Download with specified format
+    const outputTemplate = join(targetDir, '%(title)s.%(ext)s');
+    // A quality preset always wins over formatId; that is what the tool schema
+    // promises, and the two are resolved in exactly one place.
+    const formatSelector = quality ? QUALITY_FORMAT_SELECTORS[quality] : formatId;
+    // -S vcodec:h264,acodec:m4a prefers H.264+AAC, which merge cleanly into MP4.
+    // The after_move print reports the title and the final path from the same
+    // run, once the merge has produced the file, so nothing is spawned twice.
+    const commonArgs = (selector) => [
+        '-f',
+        selector,
+        '-S',
+        'vcodec:h264,acodec:m4a',
+        '-o',
+        outputTemplate,
+        '--no-playlist',
+        '--merge-output-format',
+        'mp4',
+        '--print',
+        AFTER_MOVE_TEMPLATE,
+    ];
+    // Transfers are not retried automatically: a partial file on disk plus a
+    // silent second attempt is worse than one clear failure.
+    const downloadOptions = {
+        label: 'download_video',
+        timeoutMs: TIMEOUTS.download,
+        retry: false,
+        target: url,
+    };
+    let stdout;
+    try {
+        stdout = await runYtDlp(commonArgs(formatSelector), downloadOptions);
+    }
+    catch (error) {
+        // An explicitly requested format may simply not exist for this video, so
+        // falling back to "best" is worth one attempt. A preset failing is not:
+        // presets already encode their own fallback chain, and "best" failing
+        // leaves nothing to fall back to.
+        const alreadyBroadest = quality !== undefined || formatId === 'best';
+        if (alreadyBroadest)
+            throw error;
+        log('warning', `format ${formatId} unavailable, falling back to best`);
+        stdout = await runYtDlp(commonArgs(QUALITY_FORMAT_SELECTORS.best), downloadOptions);
+    }
+    const moved = readAfterMove(stdout);
+    return {
+        videoId,
+        title: moved.title ?? '',
+        filePath: moved.filepath,
+        format: quality ?? formatId,
+    };
+}
+/** The after_move print: the last JSON line yt-dlp wrote, with the path it wrote to. */
+export const AFTER_MOVE_TEMPLATE = 'after_move:%(.{title,filepath})j';
+export function readAfterMove(stdout) {
+    const line = stdout.trim().split('\n').filter(Boolean).at(-1) ?? '';
+    const row = line === '' ? { title: undefined, filepath: undefined } : parseAfterMove(line);
+    if (typeof row.filepath !== 'string' || row.filepath === '') {
+        throw new YouTubeError('YTDLP_FAILED', 'yt-dlp finished without reporting where it wrote the file.', {
+            nextStep: 'Run `yt-dlp -U`; older versions do not print the after_move stage.',
+        });
+    }
+    return { title: row.title ?? undefined, filepath: row.filepath };
+}
+function parseAfterMove(line) {
+    return parseYtDlpJson(line, afterMoveRowSchema, 'download result');
+}
+//# sourceMappingURL=youtube-download.js.map

package/dist/utils/youtube-download.js.map

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