@postfetch/core 0.9.1 → 0.9.2

package/README.md

@@ -13,9 +13,11 @@ 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`, `downloadBlob`, `archive` and `toResponse` materialize the result.
 
-`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
+`downloadBlob(itemOrUrl, options?)` materializes resolved media for clients that
+need an uploadable `Blob`. Prefer `downloadBlob(item, { remux: true })` to
+include separate audio, assemble HLS playlists and use the item's headers.
+Passing only `item.url` fetches that URL alone and may omit separate audio;
+for direct URLs, pass `{ headers: item.headers }` when needed. Set
 `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

package/dist/download.d.ts

@@ -50,31 +50,32 @@ export type Archive = {
  */
 export declare function download(item: MediaItem, options?: DownloadOptions): Promise<Response>;
 /**
- * Download an already-resolved media URL as a Blob.
+ * Download a resolved media item or direct 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
+ * passing its URL to a third party. Pass the full {@link MediaItem} to include
+ * separate audio, HLS playlists and required headers. A direct URL only fetches
+ * that URL; pass its required CDN headers in the options object. Set `remux: true` to
  * normalize an MP4 with an FFmpeg stream copy; if FFmpeg is unavailable or the
  * remux or metadata extraction fails, the operation throws.
  *
- * @param url A direct media URL returned by a resolver.
+ * @param input A resolved media item (recommended) or direct media URL.
  * @param options Headers, fetch implementation and opt-in remux behavior.
  * @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 video = await downloadBlob(media.url, { headers: media.headers, remux: true });
+ * const video = await downloadBlob(media, { remux: true });
  * form.append("video", video.blob, media.filename);
  * form.append("thumbnail", video.thumbnail, "thumbnail.jpg");
  * ```
  */
-export declare function downloadBlob(url: string, options: DownloadBlobOptions & {
+export declare function downloadBlob(input: string | MediaItem, options: DownloadBlobOptions & {
     remux: true;
 }): Promise<RemuxedVideo>;
 /** Download without remuxing and return the upstream media Blob. */
-export declare function downloadBlob(url: string, options?: DownloadBlobOptions & {
+export declare function downloadBlob(input: string | MediaItem, options?: DownloadBlobOptions & {
     remux?: false;
 }): Promise<Blob>;
 /** @deprecated Pass headers and fetch in a single {@link DownloadBlobOptions} object. */

package/dist/index.js

@@ -2947,12 +2947,12 @@ async function download(item, options = {}) {
   }
   return response;
 }
-async function downloadBlob(url, optionsOrHeaders = {}, legacyOptions = {}) {
+async function downloadBlob(input, optionsOrHeaders = {}, legacyOptions = {}) {
   const modern = isDownloadBlobOptions(optionsOrHeaders);
   const options = modern ? optionsOrHeaders : legacyOptions;
   const headers = modern ? optionsOrHeaders.headers ?? {} : optionsOrHeaders;
   const net = createNet(options.fetch ?? globalThis.fetch);
-  const response = await net(url, { headers });
+  const response = typeof input === "string" ? await net(input, { headers }) : await download({ ...input, headers: modern ? optionsOrHeaders.headers ?? input.headers : input.headers }, options);
   if (!response.ok || !response.body) {
     throw new PostfetchError(502, `download failed: ${response.status}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postfetch/core",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "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

@@ -77,39 +77,40 @@ export async function download(item: MediaItem, options: DownloadOptions = {}):
 }
 
 /**
- * Download an already-resolved media URL as a Blob.
+ * Download a resolved media item or direct 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
+ * passing its URL to a third party. Pass the full {@link MediaItem} to include
+ * separate audio, HLS playlists and required headers. A direct URL only fetches
+ * that URL; pass its required CDN headers in the options object. Set `remux: true` to
  * normalize an MP4 with an FFmpeg stream copy; if FFmpeg is unavailable or the
  * remux or metadata extraction fails, the operation throws.
  *
- * @param url A direct media URL returned by a resolver.
+ * @param input A resolved media item (recommended) or direct media URL.
  * @param options Headers, fetch implementation and opt-in remux behavior.
  * @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 video = await downloadBlob(media.url, { headers: media.headers, remux: true });
+ * const video = await downloadBlob(media, { remux: true });
  * form.append("video", video.blob, media.filename);
  * form.append("thumbnail", video.thumbnail, "thumbnail.jpg");
  * ```
  */
 export async function downloadBlob(
-  url: string,
+  input: string | MediaItem,
   options: DownloadBlobOptions & { remux: true },
 ): Promise<RemuxedVideo>;
 /** Download without remuxing and return the upstream media Blob. */
 export async function downloadBlob(
-  url: string,
+  input: string | MediaItem,
   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,
+  input: string | MediaItem,
   optionsOrHeaders: DownloadBlobOptions | HeadersInit = {},
   legacyOptions: DownloadOptions = {},
 ): Promise<Blob | RemuxedVideo> {
@@ -117,7 +118,9 @@ export async function downloadBlob(
   const options = modern ? optionsOrHeaders : legacyOptions;
   const headers = modern ? optionsOrHeaders.headers ?? {} : optionsOrHeaders;
   const net = createNet(options.fetch ?? globalThis.fetch);
-  const response = await net(url, { headers });
+  const response = typeof input === "string"
+    ? await net(input, { headers })
+    : await download({ ...input, headers: modern ? optionsOrHeaders.headers ?? input.headers : input.headers }, options);
   if (!response.ok || !response.body) {
     throw new PostfetchError(502, `download failed: ${response.status}`);
   }