@postfetch/core 0.8.0 → 0.9.0

package/README.md

@@ -16,10 +16,11 @@ for (const item of result.items) {
 `downloadBlob(url, options?)` materializes an already-resolved media URL for
 clients that need an uploadable `Blob`. Pass the resolved item's headers for
 protected CDN URLs: `downloadBlob(item.url, { headers: item.headers })`. Set
-`remux: true` to normalize an MP4 with an FFmpeg stream copy (fast-start,
-non-negative timestamps, no edit list). Remuxing defaults to off, uses `ffmpeg`
-from `PATH` unless `ffmpegPath` is set, and falls back to the original Blob on
-failure. The legacy `(url, headers?, options?)` overload remains supported.
+`remux: true` to return `{ blob, thumbnail, width, height, duration }`: a
+normalized MP4, upload thumbnail and calculated presentation metadata. Remuxing
+defaults to off, uses `ffmpeg` and `ffprobe` from `PATH` unless their paths are
+set, and throws if the complete result cannot be produced. The legacy
+`(url, headers?, options?)` overload remains supported for non-remux downloads.
 
 - `PostfetchOptions` — `{ fetch?: typeof fetch; preferredWidth?: number; tryMaxBytes?: number }`. `tryMaxBytes` is a soft byte cap. X probes every MP4 variant and selects the highest-quality complete result that fits, falling back to its smallest variants when none do. Other platforms return a smaller available rendition when possible and otherwise keep the normal result. Inject `fetch` to unit-test resolvers offline.
 - Every request rotates a consistent browser/app fingerprint, so a fixed user-agent never gets the whole fleet blocked.

package/dist/download.d.ts

@@ -8,11 +8,21 @@ export type DownloadOptions = {
 export type DownloadBlobOptions = DownloadOptions & {
     /** Command used for opt-in MP4 remuxing. Defaults to `ffmpeg` from `PATH`. */
     ffmpegPath?: string;
+    /** Command used to inspect remuxed MP4s. Defaults to `ffprobe` from `PATH`. */
+    ffprobePath?: string;
     /** Headers required by the resolved media URL. */
     headers?: HeadersInit;
     /** Normalize an MP4 container with FFmpeg. Defaults to `false`. */
     remux?: boolean;
 };
+/** A normalized video and upload metadata produced by `remux: true`. */
+export type RemuxedVideo = {
+    blob: Blob;
+    duration: number;
+    height: number;
+    thumbnail: Blob;
+    width: number;
+};
 /** A zip archive produced by {@link archive}. */
 export type Archive = {
     /** The zip bytes (store mode, built in-process). */
@@ -46,20 +56,26 @@ export declare function download(item: MediaItem, options?: DownloadOptions): Pr
  * passing its URL to a third party. When the resolved {@link MediaItem} carries
  * required CDN headers, pass them in the options object. Set `remux: true` to
  * normalize an MP4 with an FFmpeg stream copy; if FFmpeg is unavailable or the
- * remux fails, the original Blob is returned.
+ * remux or metadata extraction fails, the operation throws.
  *
  * @param url A direct media URL returned by a resolver.
  * @param options Headers, fetch implementation and opt-in remux behavior.
- * @returns The downloaded media as a Blob.
+ * @returns A Blob, or with `remux: true`, the normalized video and its metadata.
  *
  * @example Upload a video with FormData
  * ```ts
  * const [media] = (await postfetch(sourceUrl)).items;
- * const blob = await downloadBlob(media.url, { headers: media.headers, remux: true });
- * form.append("video", blob, media.filename);
+ * const video = await downloadBlob(media.url, { headers: media.headers, remux: true });
+ * form.append("video", video.blob, media.filename);
+ * form.append("thumbnail", video.thumbnail, "thumbnail.jpg");
  * ```
  */
-export declare function downloadBlob(url: string, options?: DownloadBlobOptions): Promise<Blob>;
+export declare function downloadBlob(url: string, options: DownloadBlobOptions & {
+    remux: true;
+}): Promise<RemuxedVideo>;
+export declare function downloadBlob(url: string, options?: DownloadBlobOptions & {
+    remux?: false;
+}): Promise<Blob>;
 /** @deprecated Pass headers and fetch in a single {@link DownloadBlobOptions} object. */
 export declare function downloadBlob(url: string, headers?: HeadersInit, options?: DownloadOptions): Promise<Blob>;
 /**

package/dist/index.d.ts

@@ -20,6 +20,6 @@
  * @module
  */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
-export { download, downloadBlob, archive, toResponse, type Archive, type DownloadBlobOptions, type DownloadOptions, } from "./download";
+export { download, downloadBlob, archive, toResponse, type Archive, type DownloadBlobOptions, type DownloadOptions, type RemuxedVideo, } from "./download";
 export { PostfetchError } from "./internal";
 export type { InstagramExtra, MediaItem, MediaKind, PinterestExtra, Platform, PlatformResult, PostAuthor, PostfetchReason, PostfetchResult, PostMetadata, RedditExtra, SoundcloudExtra, TiktokExtra, TwitterExtra, TwitterQuotedTweet, YoutubeExtra, } from "./internal";

package/dist/index.js

@@ -2514,7 +2514,7 @@ function detect(url) {
   throw new PostfetchError(400, "only Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube URLs are supported");
 }
 // src/mp4-remux.ts
-async function remuxMp4(bytes, ffmpegPath = "ffmpeg", runtime) {
+async function prepareMp4(bytes, ffmpegPath = "ffmpeg", ffprobePath = "ffprobe", runtime) {
   let directory;
   let io;
   try {
@@ -2549,7 +2549,53 @@ async function remuxMp4(bytes, ffmpegPath = "ffmpeg", runtime) {
       return null;
     }
     const output = await io.readFile(outputPath);
-    return output.length > 0 ? output : null;
+    if (output.length === 0) {
+      return null;
+    }
+    const thumbnailPath = `${directory}/thumbnail.jpg`;
+    const thumbnailResult = await io.run(ffmpegPath, [
+      "-nostdin",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-y",
+      "-i",
+      outputPath,
+      "-map",
+      "0:v:0",
+      "-frames:v",
+      "1",
+      "-vf",
+      "scale=320:320:force_original_aspect_ratio=decrease",
+      "-c:v",
+      "mjpeg",
+      "-q:v",
+      "5",
+      thumbnailPath
+    ]);
+    if (!thumbnailResult.success) {
+      return null;
+    }
+    const thumbnail = await io.readFile(thumbnailPath);
+    if (!validThumbnail(thumbnail)) {
+      return null;
+    }
+    const probe = await io.run(ffprobePath, [
+      "-v",
+      "error",
+      "-select_streams",
+      "v:0",
+      "-show_entries",
+      "stream=width,height,duration:stream_side_data=rotation:format=duration",
+      "-of",
+      "json",
+      outputPath
+    ]);
+    if (!probe.success) {
+      return null;
+    }
+    const metadata = parseVideoMetadata(probe.stdout);
+    return metadata ? { bytes: output, thumbnail, ...metadata } : null;
   } catch {
     return null;
   } finally {
@@ -2560,6 +2606,26 @@ async function remuxMp4(bytes, ffmpegPath = "ffmpeg", runtime) {
     }
   }
 }
+function validThumbnail(bytes) {
+  return bytes.length >= 4 && bytes.length < 200000 && bytes[0] === 255 && bytes[1] === 216 && bytes[bytes.length - 2] === 255 && bytes[bytes.length - 1] === 217;
+}
+function parseVideoMetadata(value) {
+  const parsed = JSON.parse(value);
+  const stream = parsed.streams?.[0];
+  const duration = Number(parsed.format?.duration ?? stream?.duration);
+  const width = stream?.width ?? 0;
+  const height2 = stream?.height ?? 0;
+  if (!stream || !(duration > 0 && Number.isFinite(duration) && width > 0 && height2 > 0)) {
+    return null;
+  }
+  const rotation = stream.side_data_list?.find((item) => item.rotation !== undefined)?.rotation ?? 0;
+  const sideways = Math.abs(rotation) % 180 === 90;
+  return {
+    duration: Math.ceil(duration),
+    height: sideways ? width : height2,
+    width: sideways ? height2 : width
+  };
+}
 async function nodeRuntime() {
   const [{ spawn }, { mkdtemp, readFile, rm, writeFile }, { tmpdir }, { join }] = await Promise.all([
     import("node:child_process"),
@@ -2574,15 +2640,19 @@ async function nodeRuntime() {
       await rm(path, { force: true, recursive: true });
     },
     run: (command, args) => new Promise((resolve2) => {
-      const child = spawn(command, args, { stdio: ["ignore", "ignore", "pipe"] });
+      const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
       let stderr = "";
+      let stdout = "";
+      child.stdout?.on("data", (chunk) => {
+        stdout += new TextDecoder().decode(chunk);
+      });
       child.stderr?.on("data", (chunk) => {
         if (stderr.length < 4096) {
           stderr += new TextDecoder().decode(chunk).slice(0, 4096 - stderr.length);
         }
       });
-      child.once("error", (error) => resolve2({ stderr: error.message, success: false }));
-      child.once("close", (code) => resolve2({ stderr, success: code === 0 }));
+      child.once("error", (error) => resolve2({ stderr: error.message, stdout, success: false }));
+      child.once("close", (code) => resolve2({ stderr, stdout, success: code === 0 }));
     }),
     writeFile: async (path, value) => {
       await writeFile(path, value);
@@ -2838,15 +2908,24 @@ async function downloadBlob(url, optionsOrHeaders = {}, legacyOptions = {}) {
   if (!modern || optionsOrHeaders.remux !== true) {
     return blob;
   }
-  const remuxed = await remuxMp4(new Uint8Array(await blob.arrayBuffer()), optionsOrHeaders.ffmpegPath);
-  return remuxed ? new Blob([toArrayBuffer(remuxed)], { type: blob.type || "video/mp4" }) : blob;
+  const prepared = await prepareMp4(new Uint8Array(await blob.arrayBuffer()), optionsOrHeaders.ffmpegPath, optionsOrHeaders.ffprobePath);
+  if (!prepared) {
+    throw new PostfetchError(500, "MP4 remux or metadata extraction failed");
+  }
+  return {
+    blob: new Blob([toArrayBuffer(prepared.bytes)], { type: blob.type || "video/mp4" }),
+    duration: prepared.duration,
+    height: prepared.height,
+    thumbnail: new Blob([toArrayBuffer(prepared.thumbnail)], { type: "image/jpeg" }),
+    width: prepared.width
+  };
 }
 function isDownloadBlobOptions(value) {
   if (value instanceof Headers || Array.isArray(value)) {
     return false;
   }
   const candidate = value;
-  return "headers" in candidate && typeof candidate.headers !== "string" || typeof candidate.remux === "boolean" || typeof candidate.ffmpegPath === "string" || typeof candidate.fetch === "function";
+  return "headers" in candidate && typeof candidate.headers !== "string" || typeof candidate.remux === "boolean" || typeof candidate.ffmpegPath === "string" || typeof candidate.ffprobePath === "string" || typeof candidate.fetch === "function";
 }
 async function archive(result, options = {}) {
   const net = createNet(options.fetch ?? globalThis.fetch);

package/dist/mp4-remux.d.ts

@@ -1,7 +1,15 @@
 type CommandResult = {
     stderr: string;
+    stdout: string;
     success: boolean;
 };
+export type PreparedMp4 = {
+    bytes: Uint8Array;
+    duration: number;
+    height: number;
+    thumbnail: Uint8Array;
+    width: number;
+};
 export type Mp4RemuxRuntime = {
     makeTempDir(prefix: string): Promise<string>;
     readFile(path: string): Promise<Uint8Array>;
@@ -10,9 +18,9 @@ export type Mp4RemuxRuntime = {
     writeFile(path: string, bytes: Uint8Array): Promise<void>;
 };
 /**
- * Normalize an MP4 with the same stream-copy remux used by UMMR. Encoded media
- * is left untouched; FFmpeg only rebuilds the container and timing tables.
- * Returns `null` when FFmpeg is unavailable or the input cannot be remuxed.
+ * Normalize an MP4, extract a Telegram-compatible JPEG thumbnail, and calculate
+ * the presentation dimensions and duration. Encoded media is left untouched;
+ * FFmpeg only rebuilds the container and timing tables.
  */
-export declare function remuxMp4(bytes: Uint8Array, ffmpegPath?: string, runtime?: Mp4RemuxRuntime): Promise<Uint8Array | null>;
+export declare function prepareMp4(bytes: Uint8Array, ffmpegPath?: string, ffprobePath?: string, runtime?: Mp4RemuxRuntime): Promise<PreparedMp4 | null>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postfetch/core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files.",
   "license": "MIT",
   "type": "module",

package/src/download.ts

@@ -1,6 +1,6 @@
 import { assembleHls } from "./hls";
 import { createNet, PostfetchError, type MediaItem, type Net, type PostfetchResult } from "./internal";
-import { remuxMp4 } from "./mp4-remux";
+import { prepareMp4 } from "./mp4-remux";
 import { mergeAudioVideo } from "./remux";
 import { zip } from "./zip";
 
@@ -20,12 +20,23 @@ export type DownloadOptions = {
 export type DownloadBlobOptions = DownloadOptions & {
   /** Command used for opt-in MP4 remuxing. Defaults to `ffmpeg` from `PATH`. */
   ffmpegPath?: string;
+  /** Command used to inspect remuxed MP4s. Defaults to `ffprobe` from `PATH`. */
+  ffprobePath?: string;
   /** Headers required by the resolved media URL. */
   headers?: HeadersInit;
   /** Normalize an MP4 container with FFmpeg. Defaults to `false`. */
   remux?: boolean;
 };
 
+/** A normalized video and upload metadata produced by `remux: true`. */
+export type RemuxedVideo = {
+  blob: Blob;
+  duration: number;
+  height: number;
+  thumbnail: Blob;
+  width: number;
+};
+
 /** A zip archive produced by {@link archive}. */
 export type Archive = {
   /** The zip bytes (store mode, built in-process). */
@@ -72,27 +83,35 @@ export async function download(item: MediaItem, options: DownloadOptions = {}):
  * passing its URL to a third party. When the resolved {@link MediaItem} carries
  * required CDN headers, pass them in the options object. Set `remux: true` to
  * normalize an MP4 with an FFmpeg stream copy; if FFmpeg is unavailable or the
- * remux fails, the original Blob is returned.
+ * remux or metadata extraction fails, the operation throws.
  *
  * @param url A direct media URL returned by a resolver.
  * @param options Headers, fetch implementation and opt-in remux behavior.
- * @returns The downloaded media as a Blob.
+ * @returns A Blob, or with `remux: true`, the normalized video and its metadata.
  *
  * @example Upload a video with FormData
  * ```ts
  * const [media] = (await postfetch(sourceUrl)).items;
- * const blob = await downloadBlob(media.url, { headers: media.headers, remux: true });
- * form.append("video", blob, media.filename);
+ * const video = await downloadBlob(media.url, { headers: media.headers, remux: true });
+ * form.append("video", video.blob, media.filename);
+ * form.append("thumbnail", video.thumbnail, "thumbnail.jpg");
  * ```
  */
-export async function downloadBlob(url: string, options?: DownloadBlobOptions): Promise<Blob>;
+export async function downloadBlob(
+  url: string,
+  options: DownloadBlobOptions & { remux: true },
+): Promise<RemuxedVideo>;
+export async function downloadBlob(
+  url: string,
+  options?: DownloadBlobOptions & { remux?: false },
+): Promise<Blob>;
 /** @deprecated Pass headers and fetch in a single {@link DownloadBlobOptions} object. */
 export async function downloadBlob(url: string, headers?: HeadersInit, options?: DownloadOptions): Promise<Blob>;
 export async function downloadBlob(
   url: string,
   optionsOrHeaders: DownloadBlobOptions | HeadersInit = {},
   legacyOptions: DownloadOptions = {},
-): Promise<Blob> {
+): Promise<Blob | RemuxedVideo> {
   const modern = isDownloadBlobOptions(optionsOrHeaders);
   const options = modern ? optionsOrHeaders : legacyOptions;
   const headers = modern ? optionsOrHeaders.headers ?? {} : optionsOrHeaders;
@@ -105,8 +124,21 @@ export async function downloadBlob(
   if (!modern || optionsOrHeaders.remux !== true) {
     return blob;
   }
-  const remuxed = await remuxMp4(new Uint8Array(await blob.arrayBuffer()), optionsOrHeaders.ffmpegPath);
-  return remuxed ? new Blob([toArrayBuffer(remuxed)], { type: blob.type || "video/mp4" }) : blob;
+  const prepared = await prepareMp4(
+    new Uint8Array(await blob.arrayBuffer()),
+    optionsOrHeaders.ffmpegPath,
+    optionsOrHeaders.ffprobePath,
+  );
+  if (!prepared) {
+    throw new PostfetchError(500, "MP4 remux or metadata extraction failed");
+  }
+  return {
+    blob: new Blob([toArrayBuffer(prepared.bytes)], { type: blob.type || "video/mp4" }),
+    duration: prepared.duration,
+    height: prepared.height,
+    thumbnail: new Blob([toArrayBuffer(prepared.thumbnail)], { type: "image/jpeg" }),
+    width: prepared.width,
+  };
 }
 
 function isDownloadBlobOptions(value: DownloadBlobOptions | HeadersInit): value is DownloadBlobOptions {
@@ -118,6 +150,7 @@ function isDownloadBlobOptions(value: DownloadBlobOptions | HeadersInit): value
     ("headers" in candidate && typeof candidate.headers !== "string") ||
     typeof candidate.remux === "boolean" ||
     typeof candidate.ffmpegPath === "string" ||
+    typeof candidate.ffprobePath === "string" ||
     typeof candidate.fetch === "function"
   );
 }

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   type Archive,
   type DownloadBlobOptions,
   type DownloadOptions,
+  type RemuxedVideo,
 } from "./download";
 export { PostfetchError } from "./internal";
 export type {

package/src/mp4-remux.ts

@@ -1,8 +1,17 @@
 type CommandResult = {
   stderr: string;
+  stdout: string;
   success: boolean;
 };
 
+export type PreparedMp4 = {
+  bytes: Uint8Array;
+  duration: number;
+  height: number;
+  thumbnail: Uint8Array;
+  width: number;
+};
+
 export type Mp4RemuxRuntime = {
   makeTempDir(prefix: string): Promise<string>;
   readFile(path: string): Promise<Uint8Array>;
@@ -12,15 +21,16 @@ export type Mp4RemuxRuntime = {
 };
 
 /**
- * Normalize an MP4 with the same stream-copy remux used by UMMR. Encoded media
- * is left untouched; FFmpeg only rebuilds the container and timing tables.
- * Returns `null` when FFmpeg is unavailable or the input cannot be remuxed.
+ * Normalize an MP4, extract a Telegram-compatible JPEG thumbnail, and calculate
+ * the presentation dimensions and duration. Encoded media is left untouched;
+ * FFmpeg only rebuilds the container and timing tables.
  */
-export async function remuxMp4(
+export async function prepareMp4(
   bytes: Uint8Array,
   ffmpegPath = "ffmpeg",
+  ffprobePath = "ffprobe",
   runtime?: Mp4RemuxRuntime,
-): Promise<Uint8Array | null> {
+): Promise<PreparedMp4 | null> {
   let directory: string | undefined;
   let io: Mp4RemuxRuntime | undefined;
   try {
@@ -55,7 +65,53 @@ export async function remuxMp4(
       return null;
     }
     const output = await io.readFile(outputPath);
-    return output.length > 0 ? output : null;
+    if (output.length === 0) {
+      return null;
+    }
+    const thumbnailPath = `${directory}/thumbnail.jpg`;
+    const thumbnailResult = await io.run(ffmpegPath, [
+      "-nostdin",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-y",
+      "-i",
+      outputPath,
+      "-map",
+      "0:v:0",
+      "-frames:v",
+      "1",
+      "-vf",
+      "scale=320:320:force_original_aspect_ratio=decrease",
+      "-c:v",
+      "mjpeg",
+      "-q:v",
+      "5",
+      thumbnailPath,
+    ]);
+    if (!thumbnailResult.success) {
+      return null;
+    }
+    const thumbnail = await io.readFile(thumbnailPath);
+    if (!validThumbnail(thumbnail)) {
+      return null;
+    }
+    const probe = await io.run(ffprobePath, [
+      "-v",
+      "error",
+      "-select_streams",
+      "v:0",
+      "-show_entries",
+      "stream=width,height,duration:stream_side_data=rotation:format=duration",
+      "-of",
+      "json",
+      outputPath,
+    ]);
+    if (!probe.success) {
+      return null;
+    }
+    const metadata = parseVideoMetadata(probe.stdout);
+    return metadata ? { bytes: output, thumbnail, ...metadata } : null;
   } catch {
     return null;
   } finally {
@@ -65,6 +121,43 @@ export async function remuxMp4(
   }
 }
 
+function validThumbnail(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 4 &&
+    bytes.length < 200_000 &&
+    bytes[0] === 0xff &&
+    bytes[1] === 0xd8 &&
+    bytes[bytes.length - 2] === 0xff &&
+    bytes[bytes.length - 1] === 0xd9
+  );
+}
+
+function parseVideoMetadata(value: string): Pick<PreparedMp4, "duration" | "height" | "width"> | null {
+  const parsed = JSON.parse(value) as {
+    format?: { duration?: string };
+    streams?: Array<{
+      duration?: string;
+      height?: number;
+      side_data_list?: Array<{ rotation?: number }>;
+      width?: number;
+    }>;
+  };
+  const stream = parsed.streams?.[0];
+  const duration = Number(parsed.format?.duration ?? stream?.duration);
+  const width = stream?.width ?? 0;
+  const height = stream?.height ?? 0;
+  if (!stream || !(duration > 0 && Number.isFinite(duration) && width > 0 && height > 0)) {
+    return null;
+  }
+  const rotation = stream.side_data_list?.find((item) => item.rotation !== undefined)?.rotation ?? 0;
+  const sideways = Math.abs(rotation) % 180 === 90;
+  return {
+    duration: Math.ceil(duration),
+    height: sideways ? width : height,
+    width: sideways ? height : width,
+  };
+}
+
 // Deno, Bun and Node all expose the Node compatibility modules used here. They
 // stay behind dynamic imports so browser/edge consumers that leave remux off do
 // not load or execute any process/filesystem code.
@@ -83,15 +176,19 @@ async function nodeRuntime(): Promise<Mp4RemuxRuntime> {
     },
     run: (command, args) =>
       new Promise((resolve) => {
-        const child = spawn(command, args, { stdio: ["ignore", "ignore", "pipe"] });
+        const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
         let stderr = "";
+        let stdout = "";
+        child.stdout?.on("data", (chunk: Uint8Array) => {
+          stdout += new TextDecoder().decode(chunk);
+        });
         child.stderr?.on("data", (chunk: Uint8Array) => {
           if (stderr.length < 4096) {
             stderr += new TextDecoder().decode(chunk).slice(0, 4096 - stderr.length);
           }
         });
-        child.once("error", (error) => resolve({ stderr: error.message, success: false }));
-        child.once("close", (code) => resolve({ stderr, success: code === 0 }));
+        child.once("error", (error) => resolve({ stderr: error.message, stdout, success: false }));
+        child.once("close", (code) => resolve({ stderr, stdout, success: code === 0 }));
       }),
     writeFile: async (path, value) => {
       await writeFile(path, value);