@postfetch/core 0.6.0 → 0.8.0

package/README.md

@@ -3,7 +3,7 @@
 Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files. Part of [postfetch](https://github.com/chelokot/postfetch).
 
 ```ts
-import { postfetch, download, archive, toResponse, PostfetchError } from "@postfetch/core";
+import { postfetch, download, downloadBlob, archive, toResponse, PostfetchError } from "@postfetch/core";
 
 const result = await postfetch("https://vt.tiktok.com/ZSxpHvCUM/");
 for (const item of result.items) {
@@ -11,10 +11,19 @@ for (const item of result.items) {
 }
 ```
 
-`postfetch(url, options?)` detects the platform and resolves its media into a typed `PostfetchResult` (URLs plus the headers needed to fetch them). It performs no side effects beyond the lookup — `download`, `archive` and `toResponse` turn the result into bytes or an HTTP `Response`.
+`postfetch(url, options?)` detects the platform and resolves its media into a typed `PostfetchResult` (URLs plus the headers needed to fetch them). It performs no side effects beyond the lookup — `download`, `downloadBlob`, `archive` and `toResponse` materialize the result.
 
-- `PostfetchOptions` — `{ fetch?: typeof fetch; preferredWidth?: number }`. Inject `fetch` to unit-test resolvers offline.
+`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.
+
+- `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.
-- No runtime dependencies, no `ffmpeg` / `yt-dlp`, no cookies.
+- No runtime dependencies, no `yt-dlp`, no cookies. `ffmpeg` is only used when
+  the opt-in `downloadBlob(..., { remux: true })` path is requested.
 
 See the [root README](https://github.com/chelokot/postfetch#readme) for the full API table, supported inputs and the fingerprint design.

package/dist/download.d.ts

@@ -4,6 +4,15 @@ export type DownloadOptions = {
     /** Custom `fetch` implementation. Defaults to the global `fetch`. */
     fetch?: typeof fetch;
 };
+/** Options for {@link downloadBlob}. */
+export type DownloadBlobOptions = DownloadOptions & {
+    /** Command used for opt-in MP4 remuxing. Defaults to `ffmpeg` from `PATH`. */
+    ffmpegPath?: string;
+    /** Headers required by the resolved media URL. */
+    headers?: HeadersInit;
+    /** Normalize an MP4 container with FFmpeg. Defaults to `false`. */
+    remux?: boolean;
+};
 /** A zip archive produced by {@link archive}. */
 export type Archive = {
     /** The zip bytes (store mode, built in-process). */
@@ -30,6 +39,29 @@ export type Archive = {
  * ```
  */
 export declare function download(item: MediaItem, options?: DownloadOptions): Promise<Response>;
+/**
+ * Download an already-resolved media URL as a Blob.
+ *
+ * This is useful for consumers that need to upload media themselves instead of
+ * 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.
+ *
+ * @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.
+ *
+ * @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);
+ * ```
+ */
+export declare function downloadBlob(url: string, options?: DownloadBlobOptions): 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>;
 /**
  * Download every item of a result and zip them in-process (store mode).
  *

package/dist/index.d.ts

@@ -5,8 +5,8 @@
  * URLs to typed {@link MediaItem}s. Zero dependencies, only Web-standard APIs
  * (`fetch`, `Response`, `URL`, `crypto`) — so it runs on Deno, Node, Bun,
  * Cloudflare Workers and browsers alike. It only resolves the media; the
- * {@link download}, {@link archive} and {@link toResponse} helpers turn a result
- * into bytes or a `Response`.
+ * {@link download}, {@link downloadBlob}, {@link archive} and {@link toResponse}
+ * helpers turn a result into bytes, a `Blob`, or a `Response`.
  *
  * @example Resolve a reel and save the video
  * ```ts
@@ -20,6 +20,6 @@
  * @module
  */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
-export { download, archive, toResponse, type Archive, type DownloadOptions } from "./download";
+export { download, downloadBlob, archive, toResponse, type Archive, type DownloadBlobOptions, type DownloadOptions, } from "./download";
 export { PostfetchError } from "./internal";
-export type { InstagramExtra, MediaItem, MediaKind, PinterestExtra, Platform, PlatformResult, PostAuthor, PostfetchReason, PostfetchResult, PostMetadata, RedditExtra, SoundcloudExtra, TiktokExtra, TwitterExtra, YoutubeExtra, } from "./internal";
+export type { InstagramExtra, MediaItem, MediaKind, PinterestExtra, Platform, PlatformResult, PostAuthor, PostfetchReason, PostfetchResult, PostMetadata, RedditExtra, SoundcloudExtra, TiktokExtra, TwitterExtra, TwitterQuotedTweet, YoutubeExtra, } from "./internal";