@postfetch/core 0.6.0 → 0.7.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,9 +11,13 @@ 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, headers?, 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, item.headers)`.
+
+- `PostfetchOptions` — `{ fetch?: typeof fetch; preferredWidth?: number; tryMaxBytes?: number }`. `tryMaxBytes` is a soft byte cap: when the normal media is larger, a smaller available rendition is returned; if its size cannot be discovered or no smaller rendition is available, the normal result is kept. 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.
 

package/dist/download.d.ts

@@ -30,6 +30,26 @@ 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 as the second argument.
+ *
+ * @param url A direct media URL returned by a resolver.
+ * @param headers Headers required by the resolved media URL.
+ * @param options Fetch options.
+ * @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, media.headers);
+ * form.append("video", blob, media.filename);
+ * ```
+ */
+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 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";

package/dist/index.js

@@ -162,13 +162,13 @@ function instagramAppUserAgent() {
 
 // src/facebook.ts
 async function resolveFacebook(input) {
-  const canonical = await canonicalUrl(input.net, input.url);
+  const canonical = await canonicalUrl(input.net, normalizedInputUrl(input.url));
   const id = facebookId(canonical) ?? facebookId(input.url) ?? "video";
-  const embed = await embedVideo(input.net, canonical);
-  const watch = !embed && /^\d+$/.test(id) ? await watchVideo(input.net, id) : null;
+  const embed = await embedVideo(input.net, canonical, input.preferredWidth);
+  const watch = !embed && /^\d+$/.test(id) ? await watchVideo(input.net, id, input.preferredWidth) : null;
   const url = embed ?? watch?.url ?? null;
   if (!url) {
-    throw new Error("Facebook video not found");
+    throw new PostfetchError(404, "Facebook video not found", "notFound");
   }
   const item = {
     filename: filename(`facebook_${id}.mp4`),
@@ -181,6 +181,11 @@ async function resolveFacebook(input) {
   };
   return { archiveFilename: filename(`facebook_${id}.zip`), id, items: [item], metadata: watch?.metadata, platform: "facebook" };
 }
+function normalizedInputUrl(input) {
+  const url = asUrl(input);
+  const share = url.pathname.match(/^\/share\/([a-z])\/([A-Za-z0-9]+)/i);
+  return share ? `${url.origin}/share/${share[1]}/${share[2]}/` : input;
+}
 function navigationHeaders2() {
   return {
     "accept-language": "en-US,en;q=0.9",
@@ -193,25 +198,30 @@ async function canonicalUrl(net, input) {
   const resolved = asUrl(response.url);
   return `${resolved.origin}${resolved.pathname}`;
 }
-async function embedVideo(net, canonical) {
+async function embedVideo(net, canonical, preferredWidth) {
   const embed = `https://www.facebook.com/plugins/video.php?href=${encodeURIComponent(canonical)}`;
   const response = await net(embed, { headers: navigationHeaders2() });
   if (!response.ok) {
     return null;
   }
   const html = await response.text();
-  return source(html, "hd_src") ?? source(html, "sd_src");
+  return preferredSource(preferredWidth, source(html, "hd_src"), source(html, "sd_src"));
 }
-async function watchVideo(net, id) {
+async function watchVideo(net, id, preferredWidth) {
   const headers = { ...navigationHeaders2(), accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8" };
   const response = await net(`https://www.facebook.com/watch/?v=${id}&_rdr`, { headers });
   if (!response.ok) {
     return null;
   }
   const html = await response.text();
-  const url = source(html, "playable_url_quality_hd") ?? source(html, "browser_native_hd_url") ?? source(html, "playable_url") ?? source(html, "browser_native_sd_url");
+  const hd = source(html, "playable_url_quality_hd") ?? source(html, "browser_native_hd_url");
+  const sd = source(html, "playable_url") ?? source(html, "browser_native_sd_url");
+  const url = preferredSource(preferredWidth, hd, sd);
   return url ? { url, metadata: watchMetadata(html) } : null;
 }
+function preferredSource(preferredWidth, hd, sd) {
+  return preferredWidth >= 540 ? hd ?? sd : sd ?? hd;
+}
 function watchMetadata(html) {
   const owner = html.match(/"name":("(?:\\.|[^"\\])*"),"__isVideoOwner"/);
   const name = owner ? JSON.parse(owner[1]) : undefined;
@@ -1925,8 +1935,10 @@ async function resolveTwitter(input) {
   if (string(tweet.__typename) === "TweetTombstone") {
     throw new Error("Tweet is unavailable or age-restricted");
   }
-  const media = Array.isArray(tweet.mediaDetails) ? tweet.mediaDetails.filter(object) : [];
-  const items = media.flatMap((entry, index) => twitterItem(entry, id, index + 1));
+  const items = twitterTweets(tweet, id).flatMap(({ id: postId2, tweet: post }) => {
+    const media = Array.isArray(post.mediaDetails) ? post.mediaDetails.filter(object) : [];
+    return media.flatMap((entry, index) => twitterItem(entry, postId2, index + 1));
+  });
   if (items.length === 0) {
     throw new Error("Twitter media not found");
   }
@@ -1934,6 +1946,16 @@ async function resolveTwitter(input) {
 }
 function twitterMetadata(tweet) {
   const user = object(tweet.user) ? tweet.user : null;
+  const extra = {};
+  const lang = string(tweet.lang);
+  if (lang) {
+    extra.lang = lang;
+  }
+  const quotedTweet = object(tweet.quoted_tweet) ? tweet.quoted_tweet : null;
+  const quotedId = quotedTweet ? string(quotedTweet.id_str) : null;
+  if (quotedTweet && quotedId) {
+    extra.quotedTweet = { id: quotedId, metadata: twitterMetadata(quotedTweet) };
+  }
   return {
     text: string(tweet.text) ?? string(tweet.full_text) ?? undefined,
     author: user ? {
@@ -1947,9 +1969,26 @@ function twitterMetadata(tweet) {
     shareCount: count(tweet.retweet_count),
     viewCount: count(tweet.view_count),
     nsfw: bool(tweet.possibly_sensitive),
-    extra: { lang: string(tweet.lang) ?? undefined }
+    extra
   };
 }
+function twitterTweets(tweet, rootId) {
+  const tweets = [];
+  const seen = new Set;
+  let current = tweet;
+  let fallbackId = rootId;
+  while (current) {
+    const id = string(current.id_str) ?? fallbackId;
+    if (!id || seen.has(id)) {
+      break;
+    }
+    tweets.push({ id, tweet: current });
+    seen.add(id);
+    current = object(current.quoted_tweet) ? current.quoted_tweet : null;
+    fallbackId = null;
+  }
+  return tweets;
+}
 async function syndication(net, id) {
   const url = `https://cdn.syndication.twimg.com/tweet-result?id=${id}&lang=en&token=${syndicationToken(id)}`;
   const response = await net(url, { headers: { accept: "application/json", "user-agent": browserUserAgent() } });
@@ -2215,12 +2254,19 @@ async function postfetch(url, options = {}) {
   if (trimmed.length === 0) {
     throw new PostfetchError(400, "url is required");
   }
+  if (options.tryMaxBytes !== undefined && (!Number.isSafeInteger(options.tryMaxBytes) || options.tryMaxBytes <= 0)) {
+    throw new PostfetchError(400, "tryMaxBytes must be a positive integer");
+  }
   const context = {
     net: createNet(options.fetch ?? globalThis.fetch),
     preferredWidth: options.preferredWidth ?? 720,
     url: trimmed
   };
-  switch (detect(trimmed)) {
+  const result = await resolve(context);
+  return options.tryMaxBytes === undefined ? result : trySmaller(context, result, options.tryMaxBytes);
+}
+async function resolve(context) {
+  switch (detect(context.url)) {
     case "facebook":
       return resolveFacebook(context);
     case "instagram":
@@ -2241,6 +2287,58 @@ async function postfetch(url, options = {}) {
       return resolveYoutube(context);
   }
 }
+async function trySmaller(context, result, maxBytes) {
+  const originalBytes = await resultBytes(context, result);
+  if (originalBytes === null || originalBytes <= maxBytes) {
+    return result;
+  }
+  try {
+    const smaller = await resolve({ ...context, preferredWidth: 1 });
+    if (sameMedia(result, smaller)) {
+      return result;
+    }
+    const smallerBytes = await resultBytes(context, smaller);
+    return smallerBytes !== null && smallerBytes < originalBytes ? smaller : result;
+  } catch {
+    return result;
+  }
+}
+async function resultBytes(context, result) {
+  const sizes = await Promise.all(result.items.map((item) => itemBytes(context, item)));
+  if (sizes.some((size) => size === null)) {
+    return null;
+  }
+  return sizes.reduce((total, size) => total + (size ?? 0), 0);
+}
+async function itemBytes(context, item) {
+  if (item.hls) {
+    return null;
+  }
+  const [video, audio] = await Promise.all([
+    contentLength(context, item.url, item.headers),
+    item.audio ? contentLength(context, item.audio.url, item.audio.headers) : Promise.resolve(0)
+  ]);
+  return video === null || audio === null ? null : video + audio;
+}
+async function contentLength(context, url, headers) {
+  try {
+    const response = await context.net(url, { headers, method: "HEAD" }, 1);
+    const raw = response.ok ? response.headers.get("content-length") : null;
+    if (!raw || !/^\d+$/.test(raw)) {
+      return null;
+    }
+    const bytes = Number(raw);
+    return Number.isSafeInteger(bytes) ? bytes : null;
+  } catch {
+    return null;
+  }
+}
+function sameMedia(left, right) {
+  return left.items.length === right.items.length && left.items.every((item, index) => {
+    const other = right.items[index];
+    return item.url === other?.url && item.audio?.url === other.audio?.url;
+  });
+}
 function detect(url) {
   const host = asUrl(url).hostname;
   if (host.includes("tiktok.com")) {
@@ -2498,7 +2596,7 @@ function buffered(item) {
 async function download(item, options = {}) {
   const net = createNet(options.fetch ?? globalThis.fetch);
   if (buffered(item)) {
-    const bytes = await itemBytes(net, item);
+    const bytes = await itemBytes2(net, item);
     return new Response(toArrayBuffer(bytes), { headers: { "content-length": String(bytes.length), "content-type": item.mime } });
   }
   const response = await net(item.url, { headers: item.headers });
@@ -2507,9 +2605,17 @@ async function download(item, options = {}) {
   }
   return response;
 }
+async function downloadBlob(url, headers = {}, options = {}) {
+  const net = createNet(options.fetch ?? globalThis.fetch);
+  const response = await net(url, { headers });
+  if (!response.ok || !response.body) {
+    throw new PostfetchError(502, `download failed: ${response.status}`);
+  }
+  return response.blob();
+}
 async function archive(result, options = {}) {
   const net = createNet(options.fetch ?? globalThis.fetch);
-  const files = await Promise.all(result.items.map(async (item) => ({ data: await itemBytes(net, item), name: item.filename })));
+  const files = await Promise.all(result.items.map(async (item) => ({ data: await itemBytes2(net, item), name: item.filename })));
   return { bytes: zip(files), filename: result.archiveFilename, mime: "application/zip" };
 }
 async function toResponse(result, options = {}) {
@@ -2521,7 +2627,7 @@ async function toResponse(result, options = {}) {
 async function singleResponse(item, options) {
   if (buffered(item)) {
     const net = createNet(options.fetch ?? globalThis.fetch);
-    const bytes = await itemBytes(net, item);
+    const bytes = await itemBytes2(net, item);
     return new Response(toArrayBuffer(bytes), {
       headers: {
         "content-disposition": `attachment; filename="${item.filename}"`,
@@ -2562,7 +2668,7 @@ async function archiveResponse(result, options) {
     }
   });
 }
-async function itemBytes(net, item) {
+async function itemBytes2(net, item) {
   if (item.hls) {
     const video = await assembleHls(net, item.url, item.headers);
     if (item.audio) {
@@ -2595,6 +2701,7 @@ function toArrayBuffer(bytes) {
 export {
   toResponse,
   postfetch,
+  downloadBlob,
   download,
   detect,
   archive,

package/dist/internal.d.ts

@@ -99,6 +99,17 @@ export type TiktokExtra = {
 export type TwitterExtra = {
     /** BCP 47 language tag detected for the tweet. */
     lang?: string;
+    /** The post quoted by this post, when X includes it in the resolved payload. */
+    quotedTweet?: TwitterQuotedTweet;
+};
+/** A quoted X post and its normalized metadata. */
+export type TwitterQuotedTweet = {
+    /** Status id of the quoted post. */
+    id: string;
+    /** Metadata belonging to the quoted post rather than the outer post. */
+    metadata: PostMetadata & {
+        extra?: TwitterExtra;
+    };
 };
 /** Instagram-specific metadata. */
 export type InstagramExtra = {

package/dist/postfetch.d.ts

@@ -5,14 +5,22 @@ export type PostfetchOptions = {
     fetch?: typeof fetch;
     /** Preferred media width in pixels; the closest available rendition is chosen. Defaults to `720`. */
     preferredWidth?: number;
+    /**
+     * Soft file-size cap in bytes. The normal rendition is resolved and probed
+     * with HEAD; when it exceeds the cap, a smaller available rendition is
+     * returned. If size discovery or the smaller rendition is unavailable, the
+     * normal result is returned unchanged.
+     */
+    tryMaxBytes?: number;
 };
 /**
  * Resolve a public social post URL to its media.
  *
  * Detects the platform from the URL host, then returns the post's media as typed
  * {@link MediaItem}s — direct CDN URLs plus the headers needed to fetch them. It
- * performs no side effects beyond the lookup; use {@link download}, {@link archive}
- * or {@link toResponse} to turn the result into bytes or a `Response`.
+ * performs no side effects beyond the lookup; use {@link download},
+ * {@link downloadBlob}, {@link archive} or {@link toResponse} to turn the result
+ * into bytes, a `Blob` or a `Response`.
  *
  * @param url A post URL from a supported platform.
  * @param options See {@link PostfetchOptions}.

package/package.json

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

@@ -54,6 +54,38 @@ export async function download(item: MediaItem, options: DownloadOptions = {}):
   return 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 as the second argument.
+ *
+ * @param url A direct media URL returned by a resolver.
+ * @param headers Headers required by the resolved media URL.
+ * @param options Fetch options.
+ * @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, media.headers);
+ * form.append("video", blob, media.filename);
+ * ```
+ */
+export async function downloadBlob(
+  url: string,
+  headers: HeadersInit = {},
+  options: DownloadOptions = {},
+): Promise<Blob> {
+  const net = createNet(options.fetch ?? globalThis.fetch);
+  const response = await net(url, { headers });
+  if (!response.ok || !response.body) {
+    throw new PostfetchError(502, `download failed: ${response.status}`);
+  }
+  return response.blob();
+}
+
 /**
  * Download every item of a result and zip them in-process (store mode).
  *

package/src/facebook.ts

@@ -1,16 +1,16 @@
-import { asUrl, count, filename, isoFromEpochSeconds, type PostMetadata, type ResolveContext, type Json, type Net, type PostfetchResult, type MediaItem } from "./internal";
+import { asUrl, count, filename, isoFromEpochSeconds, PostfetchError, type PostMetadata, type ResolveContext, type Json, type Net, type PostfetchResult, type MediaItem } from "./internal";
 import { browserUserAgent } from "./fingerprint";
 
 export async function resolveFacebook(input: ResolveContext): Promise<PostfetchResult> {
-  const canonical = await canonicalUrl(input.net, input.url);
+  const canonical = await canonicalUrl(input.net, normalizedInputUrl(input.url));
   const id = facebookId(canonical) ?? facebookId(input.url) ?? "video";
   // The embed player only exposes /share/v/ videos; reels (and anything it
   // misses) come from the watch page, which the &_rdr flag serves logged-out.
-  const embed = await embedVideo(input.net, canonical);
-  const watch = !embed && /^\d+$/.test(id) ? await watchVideo(input.net, id) : null;
+  const embed = await embedVideo(input.net, canonical, input.preferredWidth);
+  const watch = !embed && /^\d+$/.test(id) ? await watchVideo(input.net, id, input.preferredWidth) : null;
   const url = embed ?? watch?.url ?? null;
   if (!url) {
-    throw new Error("Facebook video not found");
+    throw new PostfetchError(404, "Facebook video not found", "notFound");
   }
   const item: MediaItem = {
     filename: filename(`facebook_${id}.mp4`),
@@ -24,6 +24,16 @@ export async function resolveFacebook(input: ResolveContext): Promise<PostfetchR
   return { archiveFilename: filename(`facebook_${id}.zip`), id, items: [item], metadata: watch?.metadata, platform: "facebook" };
 }
 
+// Facebook share links are opaque shortlinks. Messaging apps sometimes append
+// selected text to the copied URL as another path segment; Facebook returns 404
+// for that form even though the share token is still intact. Strip everything
+// after the token before following the redirect.
+function normalizedInputUrl(input: string): string {
+  const url = asUrl(input);
+  const share = url.pathname.match(/^\/share\/([a-z])\/([A-Za-z0-9]+)/i);
+  return share ? `${url.origin}/share/${share[1]}/${share[2]}/` : input;
+}
+
 function navigationHeaders(): Record<string, string> {
   return {
     "accept-language": "en-US,en;q=0.9",
@@ -43,19 +53,19 @@ async function canonicalUrl(net: Net, input: string): Promise<string> {
 
 // The logged-out watch page is fingerprint-walled, but the public embed player
 // (plugins/video.php) still exposes the progressive hd_src/sd_src URLs.
-async function embedVideo(net: Net, canonical: string): Promise<string | null> {
+async function embedVideo(net: Net, canonical: string, preferredWidth: number): Promise<string | null> {
   const embed = `https://www.facebook.com/plugins/video.php?href=${encodeURIComponent(canonical)}`;
   const response = await net(embed, { headers: navigationHeaders() });
   if (!response.ok) {
     return null;
   }
   const html = await response.text();
-  return source(html, "hd_src") ?? source(html, "sd_src");
+  return preferredSource(preferredWidth, source(html, "hd_src"), source(html, "sd_src"));
 }
 
 // The logged-out watch page (with &_rdr) embeds the progressive video URLs in
 // its ScheduledServerJS blocks; these are the same fields yt-dlp reads.
-async function watchVideo(net: Net, id: string): Promise<{ url: string; metadata: PostMetadata } | null> {
+async function watchVideo(net: Net, id: string, preferredWidth: number): Promise<{ url: string; metadata: PostMetadata } | null> {
   // Without the document Accept header Facebook serves a JS shell without the
   // media JSON, so ask for HTML explicitly here.
   const headers = { ...navigationHeaders(), accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8" };
@@ -64,14 +74,18 @@ async function watchVideo(net: Net, id: string): Promise<{ url: string; metadata
     return null;
   }
   const html = await response.text();
-  const url =
-    source(html, "playable_url_quality_hd") ??
-    source(html, "browser_native_hd_url") ??
-    source(html, "playable_url") ??
-    source(html, "browser_native_sd_url");
+  const hd = source(html, "playable_url_quality_hd") ?? source(html, "browser_native_hd_url");
+  const sd = source(html, "playable_url") ?? source(html, "browser_native_sd_url");
+  const url = preferredSource(preferredWidth, hd, sd);
   return url ? { url, metadata: watchMetadata(html) } : null;
 }
 
+// Facebook labels its two progressive renditions as 720p HD and 360p SD. Pick
+// the one closest to the requested width, preferring HD on the 540px midpoint.
+function preferredSource(preferredWidth: number, hd: string | null, sd: string | null): string | null {
+  return preferredWidth >= 540 ? hd ?? sd : sd ?? hd;
+}
+
 // Only the fields that can be read unambiguously from the flat page: the
 // caption (creation_story) and the reaction/comment/share counts appear in
 // shapes shared with related videos and comment threads, so they are skipped

package/src/index.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,7 +20,14 @@
  * @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 DownloadOptions,
+} from "./download";
 export { PostfetchError } from "./internal";
 export type {
   InstagramExtra,
@@ -37,5 +44,6 @@ export type {
   SoundcloudExtra,
   TiktokExtra,
   TwitterExtra,
+  TwitterQuotedTweet,
   YoutubeExtra,
 } from "./internal";

package/src/internal.ts

@@ -103,6 +103,16 @@ export type TiktokExtra = {
 export type TwitterExtra = {
   /** BCP 47 language tag detected for the tweet. */
   lang?: string;
+  /** The post quoted by this post, when X includes it in the resolved payload. */
+  quotedTweet?: TwitterQuotedTweet;
+};
+
+/** A quoted X post and its normalized metadata. */
+export type TwitterQuotedTweet = {
+  /** Status id of the quoted post. */
+  id: string;
+  /** Metadata belonging to the quoted post rather than the outer post. */
+  metadata: PostMetadata & { extra?: TwitterExtra };
 };
 
 /** Instagram-specific metadata. */

package/src/postfetch.ts

@@ -1,4 +1,4 @@
-import { asUrl, createNet, PostfetchError, type Platform, type PostfetchResult } from "./internal";
+import { asUrl, createNet, PostfetchError, type MediaItem, type Platform, type PostfetchResult, type ResolveContext } from "./internal";
 import { resolveFacebook } from "./facebook";
 import { resolveInstagram } from "./instagram";
 import { resolveLinkedin } from "./linkedin";
@@ -15,6 +15,13 @@ export type PostfetchOptions = {
   fetch?: typeof fetch;
   /** Preferred media width in pixels; the closest available rendition is chosen. Defaults to `720`. */
   preferredWidth?: number;
+  /**
+   * Soft file-size cap in bytes. The normal rendition is resolved and probed
+   * with HEAD; when it exceeds the cap, a smaller available rendition is
+   * returned. If size discovery or the smaller rendition is unavailable, the
+   * normal result is returned unchanged.
+   */
+  tryMaxBytes?: number;
 };
 
 /**
@@ -22,8 +29,9 @@ export type PostfetchOptions = {
  *
  * Detects the platform from the URL host, then returns the post's media as typed
  * {@link MediaItem}s — direct CDN URLs plus the headers needed to fetch them. It
- * performs no side effects beyond the lookup; use {@link download}, {@link archive}
- * or {@link toResponse} to turn the result into bytes or a `Response`.
+ * performs no side effects beyond the lookup; use {@link download},
+ * {@link downloadBlob}, {@link archive} or {@link toResponse} to turn the result
+ * into bytes, a `Blob` or a `Response`.
  *
  * @param url A post URL from a supported platform.
  * @param options See {@link PostfetchOptions}.
@@ -43,12 +51,20 @@ export async function postfetch(url: string, options: PostfetchOptions = {}): Pr
   if (trimmed.length === 0) {
     throw new PostfetchError(400, "url is required");
   }
-  const context = {
+  if (options.tryMaxBytes !== undefined && (!Number.isSafeInteger(options.tryMaxBytes) || options.tryMaxBytes <= 0)) {
+    throw new PostfetchError(400, "tryMaxBytes must be a positive integer");
+  }
+  const context: ResolveContext = {
     net: createNet(options.fetch ?? globalThis.fetch),
     preferredWidth: options.preferredWidth ?? 720,
     url: trimmed,
   };
-  switch (detect(trimmed)) {
+  const result = await resolve(context);
+  return options.tryMaxBytes === undefined ? result : trySmaller(context, result, options.tryMaxBytes);
+}
+
+async function resolve(context: ResolveContext): Promise<PostfetchResult> {
+  switch (detect(context.url)) {
     case "facebook":
       return resolveFacebook(context);
     case "instagram":
@@ -70,6 +86,65 @@ export async function postfetch(url: string, options: PostfetchOptions = {}): Pr
   }
 }
 
+async function trySmaller(context: ResolveContext, result: PostfetchResult, maxBytes: number): Promise<PostfetchResult> {
+  const originalBytes = await resultBytes(context, result);
+  if (originalBytes === null || originalBytes <= maxBytes) {
+    return result;
+  }
+  try {
+    // Width-aware resolvers interpret 1px as "pick the smallest available".
+    // Resolvers without a smaller rendition return the same media unchanged.
+    const smaller = await resolve({ ...context, preferredWidth: 1 });
+    if (sameMedia(result, smaller)) {
+      return result;
+    }
+    const smallerBytes = await resultBytes(context, smaller);
+    return smallerBytes !== null && smallerBytes < originalBytes ? smaller : result;
+  } catch {
+    return result;
+  }
+}
+
+async function resultBytes(context: ResolveContext, result: PostfetchResult): Promise<number | null> {
+  const sizes = await Promise.all(result.items.map((item) => itemBytes(context, item)));
+  if (sizes.some((size) => size === null)) {
+    return null;
+  }
+  return sizes.reduce<number>((total, size) => total + (size ?? 0), 0);
+}
+
+async function itemBytes(context: ResolveContext, item: MediaItem): Promise<number | null> {
+  if (item.hls) {
+    return null;
+  }
+  const [video, audio] = await Promise.all([
+    contentLength(context, item.url, item.headers),
+    item.audio ? contentLength(context, item.audio.url, item.audio.headers) : Promise.resolve(0),
+  ]);
+  return video === null || audio === null ? null : video + audio;
+}
+
+async function contentLength(context: ResolveContext, url: string, headers: HeadersInit): Promise<number | null> {
+  try {
+    const response = await context.net(url, { headers, method: "HEAD" }, 1);
+    const raw = response.ok ? response.headers.get("content-length") : null;
+    if (!raw || !/^\d+$/.test(raw)) {
+      return null;
+    }
+    const bytes = Number(raw);
+    return Number.isSafeInteger(bytes) ? bytes : null;
+  } catch {
+    return null;
+  }
+}
+
+function sameMedia(left: PostfetchResult, right: PostfetchResult): boolean {
+  return left.items.length === right.items.length && left.items.every((item, index) => {
+    const other = right.items[index];
+    return item.url === other?.url && item.audio?.url === other.audio?.url;
+  });
+}
+
 /**
  * Detect which platform a URL belongs to, from its host.
  *

package/src/twitter.ts

@@ -26,8 +26,10 @@ export async function resolveTwitter(input: ResolveContext): Promise<PostfetchRe
   if (string(tweet.__typename) === "TweetTombstone") {
     throw new Error("Tweet is unavailable or age-restricted");
   }
-  const media = Array.isArray(tweet.mediaDetails) ? tweet.mediaDetails.filter(object) : [];
-  const items = media.flatMap((entry, index) => twitterItem(entry, id, index + 1));
+  const items = twitterTweets(tweet, id).flatMap(({ id: postId, tweet: post }) => {
+    const media = Array.isArray(post.mediaDetails) ? post.mediaDetails.filter(object) : [];
+    return media.flatMap((entry, index) => twitterItem(entry, postId, index + 1));
+  });
   if (items.length === 0) {
     throw new Error("Twitter media not found");
   }
@@ -36,6 +38,16 @@ export async function resolveTwitter(input: ResolveContext): Promise<PostfetchRe
 
 export function twitterMetadata(tweet: Json): PostMetadata & { extra?: TwitterExtra } {
   const user = object(tweet.user) ? tweet.user : null;
+  const extra: TwitterExtra = {};
+  const lang = string(tweet.lang);
+  if (lang) {
+    extra.lang = lang;
+  }
+  const quotedTweet = object(tweet.quoted_tweet) ? tweet.quoted_tweet : null;
+  const quotedId = quotedTweet ? string(quotedTweet.id_str) : null;
+  if (quotedTweet && quotedId) {
+    extra.quotedTweet = { id: quotedId, metadata: twitterMetadata(quotedTweet) };
+  }
   return {
     text: (string(tweet.text) ?? string(tweet.full_text)) ?? undefined,
     author: user
@@ -51,10 +63,28 @@ export function twitterMetadata(tweet: Json): PostMetadata & { extra?: TwitterEx
     shareCount: count(tweet.retweet_count),
     viewCount: count(tweet.view_count),
     nsfw: bool(tweet.possibly_sensitive),
-    extra: { lang: string(tweet.lang) ?? undefined },
+    extra,
   };
 }
 
+function twitterTweets(tweet: Json, rootId: string): Array<{ id: string; tweet: Json }> {
+  const tweets: Array<{ id: string; tweet: Json }> = [];
+  const seen = new Set<string>();
+  let current: Json | null = tweet;
+  let fallbackId: string | null = rootId;
+  while (current) {
+    const id = string(current.id_str) ?? fallbackId;
+    if (!id || seen.has(id)) {
+      break;
+    }
+    tweets.push({ id, tweet: current });
+    seen.add(id);
+    current = object(current.quoted_tweet) ? current.quoted_tweet : null;
+    fallbackId = null;
+  }
+  return tweets;
+}
+
 // The public syndication endpoint returns tweet media (video variants + photos)
 // without a guest token or bearer; the token is a non-validated cache key.
 async function syndication(net: Net, id: string): Promise<Json> {