youtube-knowledge-mcp 2.1.0 → 2.2.0

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

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import type { VideoListItem } from './youtube-channel.js';
+/**
+ * Reading a flat channel or playlist listing.
+ *
+ * `--flat-playlist` lists a channel in one request instead of one per video,
+ * and each entry carries its thumbnail URLs — which is what makes a channel's
+ * thumbnails reachable without extracting every video. Printed as one JSON
+ * object per line with exactly these fields, so a title containing a delimiter
+ * cannot shift the others, and the parser checks each field's type.
+ *
+ * Verified against yt-dlp 2026.07.04: a flat entry carries `thumbnails` but no
+ * `upload_date`, so the date stays empty here and is resolved per video by the
+ * callers that need it.
+ */
+export declare const FLAT_PRINT_TEMPLATE = "%(.{id,title,duration,upload_date,timestamp,view_count,live_status,availability,thumbnails})j";
+/** One entry of a thumbnails array; sizes are absent for some channel images. */
+export declare const listedImageSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodString;
+    width: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    height: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    id?: string | null | undefined;
+    width?: number | null | undefined;
+    height?: number | null | undefined;
+}, {
+    url: string;
+    id?: string | null | undefined;
+    width?: number | null | undefined;
+    height?: number | null | undefined;
+}>;
+export type ListedImage = z.infer<typeof listedImageSchema>;
+export declare const flatEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    duration: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    upload_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    view_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    live_status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    thumbnails: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        url: z.ZodString;
+        width: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        height: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        id?: string | null | undefined;
+        width?: number | null | undefined;
+        height?: number | null | undefined;
+    }, {
+        url: string;
+        id?: string | null | undefined;
+        width?: number | null | undefined;
+        height?: number | null | undefined;
+    }>, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title?: string | null | undefined;
+    duration?: number | null | undefined;
+    upload_date?: string | null | undefined;
+    view_count?: number | null | undefined;
+    live_status?: string | null | undefined;
+    thumbnails?: {
+        url: string;
+        id?: string | null | undefined;
+        width?: number | null | undefined;
+        height?: number | null | undefined;
+    }[] | null | undefined;
+}, {
+    id: string;
+    title?: string | null | undefined;
+    duration?: number | null | undefined;
+    upload_date?: string | null | undefined;
+    view_count?: number | null | undefined;
+    live_status?: string | null | undefined;
+    thumbnails?: {
+        url: string;
+        id?: string | null | undefined;
+        width?: number | null | undefined;
+        height?: number | null | undefined;
+    }[] | null | undefined;
+}>;
+export type FlatEntry = z.infer<typeof flatEntrySchema>;
+/** The largest image by area, then by width; `undefined` for an empty list. */
+export declare function largestThumbnail(thumbnails: ListedImage[]): ListedImage | undefined;
+export declare function toVideoListItem(entry: FlatEntry): VideoListItem;
+//# sourceMappingURL=flat-listing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flat-listing.d.ts","sourceRoot":"","sources":["../../src/utils/flat-listing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,mBAAmB,kGACiE,CAAC;AAElG,iFAAiF;AACjF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;EAK5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQ1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,WAAW,GAAG,SAAS,CAQnF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,aAAa,CAqB/D"}

package/dist/utils/flat-listing.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { formatYouTubeDate } from './format.js';
+import { formatDuration, watchUrl } from './youtube-url.js';
+/**
+ * Reading a flat channel or playlist listing.
+ *
+ * `--flat-playlist` lists a channel in one request instead of one per video,
+ * and each entry carries its thumbnail URLs — which is what makes a channel's
+ * thumbnails reachable without extracting every video. Printed as one JSON
+ * object per line with exactly these fields, so a title containing a delimiter
+ * cannot shift the others, and the parser checks each field's type.
+ *
+ * Verified against yt-dlp 2026.07.04: a flat entry carries `thumbnails` but no
+ * `upload_date`, so the date stays empty here and is resolved per video by the
+ * callers that need it.
+ */
+export const FLAT_PRINT_TEMPLATE = '%(.{id,title,duration,upload_date,timestamp,view_count,live_status,availability,thumbnails})j';
+/** One entry of a thumbnails array; sizes are absent for some channel images. */
+export const listedImageSchema = z.object({
+    id: z.string().nullish(),
+    url: z.string(),
+    width: z.number().nullish(),
+    height: z.number().nullish(),
+});
+export const flatEntrySchema = z.object({
+    id: z.string(),
+    title: z.string().nullish(),
+    duration: z.number().nullish(),
+    upload_date: z.string().nullish(),
+    view_count: z.number().nullish(),
+    live_status: z.string().nullish(),
+    thumbnails: z.array(listedImageSchema).nullish(),
+});
+/** The largest image by area, then by width; `undefined` for an empty list. */
+export function largestThumbnail(thumbnails) {
+    const area = (image) => (image.width ?? 0) * (image.height ?? 0);
+    return thumbnails.reduce((best, image) => {
+        if (best === undefined)
+            return image;
+        if (area(image) > area(best))
+            return image;
+        if (area(image) === area(best) && (image.width ?? 0) > (best.width ?? 0))
+            return image;
+        return best;
+    }, undefined);
+}
+export function toVideoListItem(entry) {
+    const duration = entry.duration ?? 0;
+    const thumbnails = entry.thumbnails ?? [];
+    const largest = largestThumbnail(thumbnails);
+    return {
+        id: entry.id,
+        title: entry.title ?? 'Unknown title',
+        duration,
+        durationFormatted: formatDuration(duration),
+        uploadDate: formatYouTubeDate(entry.upload_date ?? ''),
+        url: watchUrl(entry.id),
+        ...(largest === undefined ? {} : { thumbnailUrl: largest.url }),
+        ...(thumbnails.length === 0 ? {} : { thumbnails }),
+        ...(entry.view_count === null || entry.view_count === undefined
+            ? {}
+            : { viewCount: entry.view_count }),
+        ...(entry.live_status === null || entry.live_status === undefined
+            ? {}
+            : { liveStatus: entry.live_status }),
+    };
+}
+//# sourceMappingURL=flat-listing.js.map

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

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

package/dist/utils/format.d.ts

@@ -2,13 +2,11 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 export declare function formatCount(count: number): string;
 export declare function formatYouTubeDate(yyyymmdd: string): string;
 export declare function formatFilesize(bytes?: number): string;
-export declare function textContent(text: string): CallToolResult;
 /**
  * A tool result carrying both a human-readable rendering and machine-readable
  * data.
  *
- * The text block is byte-identical to what `textContent` produced before, so
- * nothing a client already displays changes; `structuredContent` is additive and
+ * The text block is what a client displays; `structuredContent` is additive and
  * is what the tool's `outputSchema` describes. Every tool that declares an
  * output schema must return this, because the SDK validates the two against
  * each other.

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

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKjD;AAOD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAK5F;AAED,wEAAwE;AACxE,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,QAAQ,CAS3E;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAOzE;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,cAAc,CAQhB"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKjD;AAOD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAK5F;AAED,wEAAwE;AACxE,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,QAAQ,CAS3E;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAOzE;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,cAAc,CAQhB"}

package/dist/utils/format.js

@@ -25,15 +25,11 @@ export function formatFilesize(bytes) {
         return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
     return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
 }
-export function textContent(text) {
-    return { content: [{ type: 'text', text }] };
-}
 /**
  * A tool result carrying both a human-readable rendering and machine-readable
  * data.
  *
- * The text block is byte-identical to what `textContent` produced before, so
- * nothing a client already displays changes; `structuredContent` is additive and
+ * The text block is what a client displays; `structuredContent` is additive and
  * is what the tool's `outputSchema` describes. Every tool that declares an
  * output schema must return this, because the SDK validates the two against
  * each other.

package/dist/utils/format.js.map

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

package/dist/utils/guard.d.ts

@@ -0,0 +1,21 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/** Any tool handler: whatever it takes, it answers with a tool result. */
+type ToolLike = (...args: never[]) => CallToolResult | Promise<CallToolResult>;
+/**
+ * Wrap a tool handler, keeping its exact type.
+ *
+ * A Proxy rather than an arrow function because the SDK's `registerTool` is
+ * generic over the input schema and demands a callback of the precise type it
+ * derives from it; a new function would need a cast to claim that type, while
+ * a Proxy over the original *is* that type.
+ */
+export declare function guarded<F extends ToolLike>(handler: F): F;
+/**
+ * The resource counterpart. A read that fails used to propagate whatever was
+ * thrown — an `ENOENT` carrying an absolute local path, for instance — as the
+ * JSON-RPC error message. It now carries the same `[CODE] message` a tool
+ * would show, and nothing else.
+ */
+export declare function guardedResource<A extends unknown[], R>(handler: (...args: A) => Promise<R>): (...args: A) => Promise<R>;
+export {};
+//# sourceMappingURL=guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/utils/guard.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAoEzE,0EAA0E;AAC1E,KAAK,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAE/E;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,QAAQ,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAazD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EACpD,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAc5B"}

package/dist/utils/guard.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { runWithRequestContext } from './context.js';
+import { asYouTubeError, toToolError } from './errors.js';
+/**
+ * Wrapping every handler the server registers, once, so that each call gets a
+ * request context and no call can throw out of the server.
+ *
+ * The MCP request's AbortSignal is published to the request context so an
+ * in-flight yt-dlp is killed when the client cancels, and anything thrown is
+ * rendered as an actionable message rather than a raw stack trace, a yt-dlp
+ * command line, or a local path. Tools report failures inside the result with
+ * `isError`; resources have no such envelope, so theirs become protocol errors
+ * carrying the same normalised text.
+ */
+/**
+ * The parts of the SDK's `RequestHandlerExtra` this server uses.
+ *
+ * `sendNotification` is described with `z.custom` because a function is not
+ * something Zod can take apart structurally — the predicate is a real runtime
+ * check, and it is what lets the property be called without asserting a type
+ * over it.
+ */
+const requestExtraSchema = z.object({
+    signal: z.instanceof(AbortSignal).optional(),
+    sendNotification: z
+        .custom((value) => typeof value === 'function')
+        .optional(),
+    _meta: z.object({ progressToken: z.union([z.string(), z.number()]).optional() }).optional(),
+});
+/** The request context for a call, read from the SDK extra that arrives last. */
+function contextOf(args) {
+    // Handlers declare only their own parameters; the SDK appends
+    // RequestHandlerExtra to every call, so it is whatever arrived last.
+    const parsed = requestExtraSchema.safeParse(args[args.length - 1]);
+    const extra = parsed.success ? parsed.data : undefined;
+    return {
+        signal: extra?.signal,
+        // Progress is only meaningful when the client asked for it by sending a
+        // token; without one the notification would be dropped anyway.
+        reportProgress: extra?.sendNotification && extra._meta?.progressToken !== undefined
+            ? (progress, total, message) => {
+                void extra.sendNotification?.({
+                    method: 'notifications/progress',
+                    params: {
+                        progressToken: extra._meta?.progressToken,
+                        progress,
+                        ...(total === undefined ? {} : { total }),
+                        ...(message === undefined ? {} : { message }),
+                    },
+                });
+            }
+            : undefined,
+        log: extra?.sendNotification
+            ? (level, message) => {
+                void extra.sendNotification?.({
+                    method: 'notifications/message',
+                    params: { level, logger: 'youtube-knowledge-mcp', data: message },
+                });
+            }
+            : undefined,
+    };
+}
+/**
+ * Wrap a tool handler, keeping its exact type.
+ *
+ * A Proxy rather than an arrow function because the SDK's `registerTool` is
+ * generic over the input schema and demands a callback of the precise type it
+ * derives from it; a new function would need a cast to claim that type, while
+ * a Proxy over the original *is* that type.
+ */
+export function guarded(handler) {
+    const run = (args) => runWithRequestContext(contextOf(args), async () => {
+        try {
+            return await handler(...args);
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    return new Proxy(handler, {
+        apply: (_target, _thisArg, args) => run(args),
+    });
+}
+/**
+ * The resource counterpart. A read that fails used to propagate whatever was
+ * thrown — an `ENOENT` carrying an absolute local path, for instance — as the
+ * JSON-RPC error message. It now carries the same `[CODE] message` a tool
+ * would show, and nothing else.
+ */
+export function guardedResource(handler) {
+    return async (...args) => runWithRequestContext(contextOf(args), async () => {
+        try {
+            return await handler(...args);
+        }
+        catch (error) {
+            const failure = asYouTubeError(error);
+            const code = failure.code === 'INVALID_INPUT' || failure.code === 'NOT_FOUND'
+                ? ErrorCode.InvalidParams
+                : ErrorCode.InternalError;
+            throw new McpError(code, `[${failure.code}] ${failure.toToolMessage()}`);
+        }
+    });
+}
+//# sourceMappingURL=guard.js.map

package/dist/utils/guard.js.map

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

package/dist/utils/image-dimensions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reading an image's format and size from its first bytes.
+ *
+ * The manifest a thumbnail job writes records what was actually saved — a
+ * JPEG of 1280 by 720, say — and it must not take that from the URL's name or
+ * the server's Content-Type, both of which describe what was asked for rather
+ * than what arrived. Three container formats cover what YouTube's image hosts
+ * serve; anything else is reported as unknown rather than guessed.
+ */
+export type ImageFormat = 'jpg' | 'png' | 'webp';
+export interface ImageProbe {
+    format: ImageFormat;
+    width: number;
+    height: number;
+    mimeType: string;
+}
+/** The format and pixel size of an image, or `undefined` when the bytes are not one this reads. */
+export declare function probeImage(bytes: Uint8Array): ImageProbe | undefined;
+//# sourceMappingURL=image-dimensions.d.ts.map

package/dist/utils/image-dimensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-dimensions.d.ts","sourceRoot":"","sources":["../../src/utils/image-dimensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AA4FD,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAKpE"}

package/dist/utils/image-dimensions.js

@@ -0,0 +1,93 @@
+/**
+ * Reading an image's format and size from its first bytes.
+ *
+ * The manifest a thumbnail job writes records what was actually saved — a
+ * JPEG of 1280 by 720, say — and it must not take that from the URL's name or
+ * the server's Content-Type, both of which describe what was asked for rather
+ * than what arrived. Three container formats cover what YouTube's image hosts
+ * serve; anything else is reported as unknown rather than guessed.
+ */
+const JPEG_SIGNATURE = [0xff, 0xd8, 0xff];
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+function startsWith(bytes, signature, at = 0) {
+    return signature.every((byte, index) => bytes[at + index] === byte);
+}
+function ascii(bytes, from, length) {
+    return String.fromCharCode(...bytes.subarray(from, from + length));
+}
+/** Every caller checks the length first, so a read here is always in range. */
+function view(bytes) {
+    return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+function be16(bytes, at) {
+    return view(bytes).getUint16(at);
+}
+function be32(bytes, at) {
+    return view(bytes).getUint32(at);
+}
+function le16(bytes, at) {
+    return view(bytes).getUint16(at, true);
+}
+function le24(bytes, at) {
+    return le16(bytes, at) | (view(bytes).getUint8(at + 2) << 16);
+}
+/** Start-of-frame markers carry the dimensions; C4, C8 and CC are other things. */
+function isStartOfFrame(marker) {
+    return marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+}
+function probeJpeg(bytes) {
+    let at = 2;
+    while (at + 9 < bytes.length) {
+        if (bytes[at] !== 0xff)
+            return undefined;
+        const marker = view(bytes).getUint8(at + 1);
+        // Standalone markers have no length field.
+        if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            at += 2;
+            continue;
+        }
+        // Scan data or end of image: no frame header was found before it.
+        if (marker === 0xda || marker === 0xd9)
+            return undefined;
+        if (isStartOfFrame(marker)) {
+            return sized('jpg', 'image/jpeg', be16(bytes, at + 7), be16(bytes, at + 5));
+        }
+        at += 2 + be16(bytes, at + 2);
+    }
+    return undefined;
+}
+function probePng(bytes) {
+    if (bytes.length < 24 || ascii(bytes, 12, 4) !== 'IHDR')
+        return undefined;
+    return sized('png', 'image/png', be32(bytes, 16), be32(bytes, 20));
+}
+function probeWebp(bytes) {
+    if (bytes.length < 30 || ascii(bytes, 8, 4) !== 'WEBP')
+        return undefined;
+    switch (ascii(bytes, 12, 4)) {
+        case 'VP8 ':
+            return sized('webp', 'image/webp', le16(bytes, 26) & 0x3fff, le16(bytes, 28) & 0x3fff);
+        case 'VP8L': {
+            const bits = view(bytes).getUint32(21, true);
+            return sized('webp', 'image/webp', (bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1);
+        }
+        case 'VP8X':
+            return sized('webp', 'image/webp', le24(bytes, 24) + 1, le24(bytes, 27) + 1);
+        default:
+            return undefined;
+    }
+}
+function sized(format, mimeType, width, height) {
+    return width > 0 && height > 0 ? { format, mimeType, width, height } : undefined;
+}
+/** The format and pixel size of an image, or `undefined` when the bytes are not one this reads. */
+export function probeImage(bytes) {
+    if (startsWith(bytes, JPEG_SIGNATURE))
+        return probeJpeg(bytes);
+    if (startsWith(bytes, PNG_SIGNATURE))
+        return probePng(bytes);
+    if (bytes.length >= 12 && ascii(bytes, 0, 4) === 'RIFF')
+        return probeWebp(bytes);
+    return undefined;
+}
+//# sourceMappingURL=image-dimensions.js.map

package/dist/utils/image-dimensions.js.map

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

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

@@ -0,0 +1,31 @@
+/**
+ * The one place this server fetches anything over HTTP itself.
+ *
+ * Everything else goes through yt-dlp. Thumbnails are the exception because
+ * their URLs are known from a single channel listing, and asking yt-dlp to
+ * extract each video just to download its image would multiply the requests
+ * YouTube sees by the size of the channel. The fetch is deliberately narrow:
+ * an allowlist of image hosts, https only, redirects re-checked hop by hop, a
+ * timeout, a byte cap enforced while reading, and an image content type.
+ */
+export declare const IMAGE_HOSTS: readonly ["i.ytimg.com", "yt3.googleusercontent.com", "yt3.ggpht.com"];
+export declare const IMAGE_TIMEOUT_MS = 20000;
+/** Cap for images written to disk. */
+export declare const MAX_IMAGE_BYTES: number;
+/** Cap for images returned inline as base64; a 1280x720 JPEG is about 140 KB. */
+export declare const MAX_INLINE_IMAGE_BYTES: number;
+export interface FetchImageOptions {
+    maxBytes?: number;
+    timeoutMs?: number;
+}
+export interface FetchedImage {
+    bytes: Buffer;
+    contentType: string;
+    /** The URL the bytes came from, after any redirects. */
+    url: string;
+}
+/** Validate an image URL against the allowlist, returning it parsed. */
+export declare function assertImageUrl(input: string): URL;
+/** Fetch one image into memory, or throw a typed error saying why not. */
+export declare function fetchImage(input: string, options?: FetchImageOptions): Promise<FetchedImage>;
+//# sourceMappingURL=image-fetch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"image-fetch.d.ts","sourceRoot":"","sources":["../../src/utils/image-fetch.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,eAAO,MAAM,WAAW,wEAAyE,CAAC;AAClG,eAAO,MAAM,gBAAgB,QAAS,CAAC;AACvC,sCAAsC;AACtC,eAAO,MAAM,eAAe,QAAkB,CAAC;AAC/C,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,QAAkB,CAAC;AAKtD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAcjD;AAgBD,0EAA0E;AAC1E,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,YAAY,CAAC,CA0CvB"}