@postfetch/core 0.10.2 → 0.12.0

package/dist/index.d.ts

@@ -23,4 +23,4 @@ export { postfetch, detect, type PostfetchOptions } from "./postfetch";
 export { buildAudioSliderVideo, type AudioSliderVideoOptions } from "./audio-slider";
 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";
+export type { InstagramExtra, MediaItem, MediaKind, PinterestExtra, Platform, PlatformResult, PostAuthor, PostComment, PostfetchReason, PostfetchResult, PostMetadata, RedditExtra, SoundcloudExtra, TiktokExtra, TwitterExtra, TwitterQuotedTweet, YoutubeExtra, } from "./internal";

package/dist/index.js

@@ -174,7 +174,7 @@ async function resolveFacebook(input) {
   const url = embed ?? watch?.url ?? null;
   if (!url) {
     if (pageMetadata?.text) {
-      return { archiveFilename: filename(`facebook_${id}.zip`), id, items: [], metadata: pageMetadata, platform: "facebook" };
+      return { archiveFilename: filename(`facebook_${id}.zip`), comments: [], id, items: [], metadata: pageMetadata, platform: "facebook" };
     }
     throw new PostfetchError(404, "Facebook video not found", "notFound");
   }
@@ -189,6 +189,7 @@ async function resolveFacebook(input) {
   };
   return {
     archiveFilename: filename(`facebook_${id}.zip`),
+    comments: [],
     id,
     items: [item],
     metadata: mergeMetadata(pageMetadata, watch?.metadata),
@@ -385,7 +386,7 @@ async function resolveInstagram(input) {
   if (items.length === 0) {
     throw new Error("Instagram media url not found");
   }
-  return { archiveFilename: filename(`instagram_${code}.zip`), id: code, items, metadata: instagramMetadata(media), platform: "instagram" };
+  return { archiveFilename: filename(`instagram_${code}.zip`), comments: [], id: code, items, metadata: instagramMetadata(media), platform: "instagram" };
 }
 async function instagramUnavailable(net, code) {
   const url = new URL("https://i.instagram.com/api/v1/oembed/");
@@ -804,6 +805,7 @@ async function resolveLinkedin(input) {
   }
   return {
     archiveFilename: filename(`linkedin_${id}.zip`),
+    comments: [],
     id,
     items,
     metadata: linkedinMetadata(post),
@@ -1323,7 +1325,7 @@ async function resolvePinterest(input) {
   if (items.length === 0) {
     throw new Error("Pinterest media not found");
   }
-  return { archiveFilename: filename(`pinterest_${id}.zip`), id, items, metadata: pinterestMetadata(pin), platform: "pinterest" };
+  return { archiveFilename: filename(`pinterest_${id}.zip`), comments: [], id, items, metadata: pinterestMetadata(pin), platform: "pinterest" };
 }
 function pinterestMetadata(pin) {
   const pinner = object(pin.pinner) ? pin.pinner : null;
@@ -1538,7 +1540,7 @@ async function resolveReddit(input) {
   const token = await appToken(input.net);
   const post = await fetchPost(input.net, token, id);
   const items = await mediaItems3(input, post, id);
-  return { archiveFilename: filename(`reddit_${id}.zip`), id, items, metadata: redditMetadata(post), platform: "reddit" };
+  return { archiveFilename: filename(`reddit_${id}.zip`), comments: await redditComments(input, token, id), id, items, metadata: redditMetadata(post), platform: "reddit" };
 }
 function redditMetadata(post) {
   const author = string(post.author);
@@ -1788,6 +1790,102 @@ function extensionOf(mime) {
   }
   return "jpg";
 }
+async function redditComments(input, token, id) {
+  const limit = input.comments;
+  if (!limit || !Number.isSafeInteger(limit) || limit < 0)
+    return [];
+  try {
+    const headers = { authorization: `Bearer ${token}`, "user-agent": browserUserAgent() };
+    const response = await input.net(`https://oauth.reddit.com/comments/${id}?raw_json=1&limit=${Math.min(limit, 100)}&depth=1&sort=top`, { headers }, 1);
+    if (!response.ok)
+      throw new Error("Reddit comments failed");
+    const payload = await response.json();
+    const listing = Array.isArray(payload) ? payload[1] : null;
+    if (!object(listing) || !object(listing.data) || !Array.isArray(listing.data.children))
+      throw new Error("Invalid Reddit comments");
+    const comments = [];
+    const seen = new Set;
+    const queued = new Set;
+    const pending = [];
+    const collect = (things) => {
+      for (const thing of things) {
+        if (!object(thing) || !object(thing.data))
+          continue;
+        const data = thing.data;
+        if (data.parent_id !== `t3_${id}`)
+          continue;
+        if (thing.kind === "more" && Array.isArray(data.children)) {
+          for (const child of data.children) {
+            if (typeof child !== "string" || !/^[a-z0-9]+$/i.test(child) || queued.has(child))
+              continue;
+            queued.add(child);
+            pending.push(child);
+          }
+        } else if (thing.kind === "t1" && comments.length < limit) {
+          const commentId = string(data.id);
+          if (!commentId || seen.has(commentId))
+            continue;
+          seen.add(commentId);
+          const body = string(data.body);
+          if (!body || body === "[deleted]" || body === "[removed]")
+            continue;
+          comments.push(redditComment(data, commentId, id, body));
+        }
+      }
+    };
+    collect(listing.data.children);
+    while (comments.length < limit && pending.length > 0) {
+      const children = pending.splice(0, Math.min(100, limit - comments.length));
+      const url = new URL("https://oauth.reddit.com/api/morechildren");
+      url.search = new URLSearchParams({ api_type: "json", raw_json: "1", link_id: `t3_${id}`, children: children.join(","), sort: "top", depth: "1", limit_children: "true" }).toString();
+      const more = await input.net(url.href, { headers }, 1);
+      if (!more.ok)
+        throw new Error("Reddit more comments failed");
+      const result = await more.json();
+      const json = object(result) && object(result.json) ? result.json : null;
+      const data = json && object(json.data) ? json.data : null;
+      if (!data || !Array.isArray(data.things) || Array.isArray(json?.errors) && json.errors.length > 0)
+        throw new Error("Invalid additional Reddit comments");
+      collect(data.things);
+    }
+    return comments;
+  } catch {
+    return [];
+  }
+}
+function redditComment(data, id, postId2, body) {
+  const metadata = object(data.media_metadata) ? data.media_metadata : {};
+  const mediaIds = Object.keys(metadata).filter((key) => object(metadata[key])).sort((left, right) => {
+    const position = (key) => {
+      const meta = metadata[key];
+      const best = object(meta) && object(meta.s) ? meta.s : {};
+      const tokens = [`![img](${key})`, `![gif](${key})`, string(best.u), string(best.gif), string(best.mp4)];
+      const positions = tokens.flatMap((token) => token && body.includes(token) ? [body.indexOf(token)] : []);
+      return Math.min(...positions);
+    };
+    return position(left) - position(right);
+  });
+  const items = galleryItems({ media_metadata: metadata, gallery_data: { items: mediaIds.map((media_id) => ({ media_id })) } }, id);
+  const text = body.replace(/!\[(?:img|gif)\]\(([^)]+)\)/g, (match, key) => {
+    const meta = metadata[key];
+    return object(meta) && object(meta.s) && (string(meta.s.u) || string(meta.s.gif) || string(meta.s.mp4)) ? "" : match;
+  }).split(`
+`).filter((line) => !items.some((item) => line.trim() === item.url)).join(`
+`).trim();
+  const author = string(data.author);
+  return {
+    id,
+    url: `https://www.reddit.com/comments/${postId2}/_/${id}/`,
+    items,
+    metadata: {
+      text,
+      author: author && author !== "[deleted]" ? { handle: author } : undefined,
+      createdAt: isoFromEpochSeconds(data.created_utc),
+      likeCount: count(data.ups),
+      nsfw: bool(data.over_18)
+    }
+  };
+}
 
 // src/soundcloud.ts
 async function resolveSoundcloud(input) {
@@ -1796,7 +1894,7 @@ async function resolveSoundcloud(input) {
   const track = await resolveTrack(input.net, url, clientId);
   const id = trackId(track);
   const item = await audioItem(input.net, track, id, clientId);
-  return { archiveFilename: filename(`soundcloud_${id}.zip`), id, items: [item], metadata: soundcloudMetadata(track), platform: "soundcloud" };
+  return { archiveFilename: filename(`soundcloud_${id}.zip`), comments: [], id, items: [item], metadata: soundcloudMetadata(track), platform: "soundcloud" };
 }
 function soundcloudMetadata(track) {
   const user = object(track.user) ? track.user : null;
@@ -1932,7 +2030,7 @@ async function resolveTiktok(input) {
   if (items.length === 0) {
     throw new Error("TikTok media not found");
   }
-  return { archiveFilename: filename(`tiktok_${user}_${id}.zip`), id, items, metadata: tiktokMetadata(page.item), platform: "tiktok" };
+  return { archiveFilename: filename(`tiktok_${user}_${id}.zip`), comments: [], id, items, metadata: tiktokMetadata(page.item), platform: "tiktok" };
 }
 async function videoPage(net, id, photo) {
   for (let attempt = 0;attempt < pageAttemptCount; attempt += 1) {
@@ -2194,7 +2292,7 @@ async function resolveTwitter(input) {
     });
   });
   const items = input.tryMaxBytes === undefined ? groups.map((group) => group[0].item) : await sizeLimitedItems(input, groups);
-  return { archiveFilename: filename(`twitter_${id}.zip`), id, items, metadata: twitterMetadata(tweet), platform: "twitter" };
+  return { archiveFilename: filename(`twitter_${id}.zip`), comments: await twitterComments(input, id), id, items, metadata: twitterMetadata(tweet), platform: "twitter" };
 }
 function twitterMetadata(tweet) {
   const user = object(tweet.user) ? tweet.user : null;
@@ -2208,6 +2306,14 @@ function twitterMetadata(tweet) {
   if (quotedTweet && quotedId) {
     extra.quotedTweet = { id: quotedId, metadata: twitterMetadata(quotedTweet) };
   }
+  const parent = object(tweet.parent) ? tweet.parent : null;
+  const parentId = parent ? string(parent.id_str) : null;
+  const replyToId = string(tweet.in_reply_to_status_id_str) ?? parentId;
+  if (replyToId)
+    extra.replyToId = replyToId;
+  if (parent && parentId) {
+    extra.parentTweet = { id: parentId, metadata: twitterMetadata(parent) };
+  }
   return {
     text: twitterText(tweet) ?? undefined,
     author: user ? {
@@ -2240,7 +2346,7 @@ function needsFullText(tweet) {
   return object(tweet.note_tweet) || bool(tweet.truncated) === true || (string(tweet.text)?.length ?? 0) >= 270;
 }
 async function expandTwitterText(net, tweet, rootId) {
-  const posts = new Map(twitterTweets(tweet, rootId).map(({ id, tweet: post }) => [id, post]));
+  const posts = new Map(twitterTweets(tweet, rootId, true).map(({ id, tweet: post }) => [id, post]));
   for (const [id, post] of posts) {
     if (!needsFullText(post)) {
       continue;
@@ -2275,21 +2381,21 @@ async function expandTwitterText(net, tweet, rootId) {
     } catch {}
   }
 }
-function twitterTweets(tweet, rootId) {
+function twitterTweets(tweet, rootId, includeParents = false) {
   const tweets = [];
   const seen = new Set;
-  let current = tweet;
-  let fallbackId = rootId;
-  while (current) {
+  const visit = (current, fallbackId) => {
     const id = string(current.id_str) ?? fallbackId;
-    if (!id || seen.has(id)) {
-      break;
-    }
-    tweets.push({ id, tweet: current });
+    if (!id || seen.has(id))
+      return;
     seen.add(id);
-    current = object(current.quoted_tweet) ? current.quoted_tweet : null;
-    fallbackId = null;
-  }
+    tweets.push({ id, tweet: current });
+    if (object(current.quoted_tweet))
+      visit(current.quoted_tweet);
+    if (includeParents && object(current.parent))
+      visit(current.parent);
+  };
+  visit(tweet, rootId);
   return tweets;
 }
 async function syndication(net, id) {
@@ -2397,6 +2503,87 @@ async function contentLength(net, item) {
 function tweetId(input) {
   return asUrl(input).pathname.match(/\/status(?:es)?\/(\d+)/)?.[1] ?? null;
 }
+async function twitterComments(input, id) {
+  const limit = input.comments;
+  if (!limit || !Number.isSafeInteger(limit) || limit < 0)
+    return [];
+  try {
+    const comments = [];
+    const seen = new Set;
+    const cursors = new Set;
+    let cursor = null;
+    do {
+      const url = new URL(`https://api.fxtwitter.com/2/conversation/${id}`);
+      if (cursor)
+        url.searchParams.set("cursor", cursor);
+      const response = await input.net(url.href, { headers: { accept: "application/json", "user-agent": browserUserAgent() } }, 1);
+      if (!response.ok)
+        throw new Error("Comment lookup failed");
+      const payload = await response.json();
+      if (!object(payload) || payload.code !== 200 || !Array.isArray(payload.replies))
+        throw new Error("Invalid comments");
+      const previousCount = comments.length;
+      for (const reply of payload.replies) {
+        if (!object(reply))
+          continue;
+        const replyId = string(reply.id);
+        const parent = object(reply.replying_to) ? string(reply.replying_to.status) : null;
+        if (!replyId || parent !== id || seen.has(replyId))
+          continue;
+        seen.add(replyId);
+        comments.push(twitterComment(reply, replyId));
+        if (comments.length >= limit)
+          return comments;
+      }
+      cursor = object(payload.cursor) ? string(payload.cursor.bottom) : null;
+      if (!cursor || cursors.has(cursor) || comments.length === previousCount)
+        break;
+      cursors.add(cursor);
+    } while (comments.length < limit);
+    return comments;
+  } catch {
+    return [];
+  }
+}
+function twitterComment(reply, id) {
+  const author2 = object(reply.author) ? reply.author : {};
+  const verification = object(author2.verification) ? author2.verification : {};
+  const media = object(reply.media) && Array.isArray(reply.media.all) ? reply.media.all.filter(object) : [];
+  const items = media.flatMap((entry, index) => {
+    const url = string(entry.url);
+    const photo = entry.type === "photo";
+    if (!url || !photo && entry.type !== "video" && entry.type !== "gif" && entry.type !== "animated_gif")
+      return [];
+    return [{
+      id,
+      platform: "twitter",
+      filename: filename(`twitter_${id}_${index + 1}.${photo ? "jpg" : "mp4"}`),
+      kind: photo ? "image" : "video",
+      mime: photo ? "image/jpeg" : "video/mp4",
+      url,
+      headers: { "user-agent": browserUserAgent() }
+    }];
+  });
+  return {
+    id,
+    url: `https://x.com/i/status/${id}`,
+    items,
+    metadata: {
+      text: string(reply.text) ?? undefined,
+      author: {
+        handle: string(author2.screen_name) ?? undefined,
+        name: string(author2.name) ?? undefined,
+        verified: bool(verification.verified)
+      },
+      createdAt: isoFromDateString(reply.created_at),
+      likeCount: count(reply.likes),
+      commentCount: count(reply.replies),
+      shareCount: count(reply.reposts),
+      viewCount: count(reply.views),
+      nsfw: bool(reply.possibly_sensitive)
+    }
+  };
+}
 
 // src/youtube.ts
 var androidVrClient = {
@@ -2470,7 +2657,7 @@ function youtubeResult(id, payload, streams, headers) {
     ...streams.hls ? { hls: true } : {},
     ...streams.audio ? { audio: { headers, url: streams.audio } } : {}
   };
-  return { archiveFilename: filename(`youtube_${id}.zip`), id, items: [media], metadata: youtubeMetadata(payload), platform: "youtube" };
+  return { archiveFilename: filename(`youtube_${id}.zip`), comments: [], id, items: [media], metadata: youtubeMetadata(payload), platform: "youtube" };
 }
 async function probeStream(net, url, headers) {
   const response = await net(url, { headers }, 1);
@@ -2702,6 +2889,7 @@ async function postfetch(url, options = {}) {
   }
   const context = {
     net: createNet(options.fetch ?? globalThis.fetch),
+    comments: options.comments,
     preferredWidth: options.preferredWidth ?? 720,
     tryMaxBytes: options.tryMaxBytes,
     url: trimmed

package/dist/internal.d.ts

@@ -97,10 +97,14 @@ export type TiktokExtra = {
 };
 /** X (Twitter)-specific metadata. */
 export type TwitterExtra = {
+    /** Parent status id when this post is a reply, even if the parent metadata is unavailable. */
+    replyToId?: string;
     /** 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;
+    /** The parent this post replies to, when included by X. Media is not collected. */
+    parentTweet?: TwitterQuotedTweet;
 };
 /** A quoted X post and its normalized metadata. */
 export type TwitterQuotedTweet = {
@@ -147,12 +151,25 @@ export type PinterestExtra = {
     /** Outbound link the pin points to, when set. */
     outboundLink?: string;
 };
+/** A reply with its own metadata and downloadable media, separate from the main post. */
+export type PostComment = {
+    /** Reply post id. */
+    id: string;
+    /** Permalink to the reply. */
+    url: string;
+    /** Normalized reply metadata. */
+    metadata: PostMetadata;
+    /** Attachments belonging to this reply. */
+    items: MediaItem[];
+};
 /** The result of resolving a post: its platform, id, media items and metadata. */
 export type PostfetchResult = PlatformResult<"facebook", never> | PlatformResult<"instagram", InstagramExtra> | PlatformResult<"linkedin", never> | PlatformResult<"pinterest", PinterestExtra> | PlatformResult<"reddit", RedditExtra> | PlatformResult<"soundcloud", SoundcloudExtra> | PlatformResult<"tiktok", TiktokExtra> | PlatformResult<"twitter", TwitterExtra> | PlatformResult<"youtube", YoutubeExtra>;
 /** One platform's variant of a {@link PostfetchResult}, carrying that platform's `extra` metadata shape. */
 export type PlatformResult<P extends Platform, Extra> = {
     /** Suggested filename when zipping every item. */
     archiveFilename: string;
+    /** Requested replies, or an empty array when not requested, unsupported or unavailable. */
+    comments: PostComment[];
     /** Platform post/media id. */
     id: string;
     /** The post's media, in order. */
@@ -169,6 +186,7 @@ export type Net = (url: string, init?: RequestInit, attempts?: number) => Promis
 export type ResolveContext = {
     net: Net;
     preferredWidth: number;
+    comments?: number;
     /** Requested soft byte cap, for resolvers that can rank exact rendition sizes. */
     tryMaxBytes?: number;
     url: string;

package/dist/postfetch.d.ts

@@ -3,6 +3,8 @@ import { type Platform, type PostfetchResult } from "./internal";
 export type PostfetchOptions = {
     /** Custom `fetch` implementation — inject one to unit-test resolvers offline. Defaults to the global `fetch`. */
     fetch?: typeof fetch;
+    /** Maximum direct comments to fetch for X and Reddit. Other platforms ignore this option. Failures return an empty array. */
+    comments?: number;
     /** Preferred media width in pixels; the closest available rendition is chosen. Defaults to `720`. */
     preferredWidth?: number;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postfetch/core",
-  "version": "0.10.2",
+  "version": "0.12.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/facebook.ts

@@ -16,7 +16,7 @@ export async function resolveFacebook(input: ResolveContext): Promise<PostfetchR
     // has no downloadable media. Require post metadata from the canonical page
     // so a missing or login-walled video does not become a false success.
     if (pageMetadata?.text) {
-      return { archiveFilename: filename(`facebook_${id}.zip`), id, items: [], metadata: pageMetadata, platform: "facebook" };
+      return { archiveFilename: filename(`facebook_${id}.zip`), comments: [], id, items: [], metadata: pageMetadata, platform: "facebook" };
     }
     throw new PostfetchError(404, "Facebook video not found", "notFound");
   }
@@ -31,6 +31,7 @@ export async function resolveFacebook(input: ResolveContext): Promise<PostfetchR
   };
   return {
     archiveFilename: filename(`facebook_${id}.zip`),
+    comments: [],
     id,
     items: [item],
     metadata: mergeMetadata(pageMetadata, watch?.metadata),

package/src/index.ts

@@ -40,6 +40,7 @@ export type {
   Platform,
   PlatformResult,
   PostAuthor,
+  PostComment,
   PostfetchReason,
   PostfetchResult,
   PostMetadata,

package/src/instagram.ts

@@ -80,7 +80,7 @@ export async function resolveInstagram(input: ResolveContext): Promise<Postfetch
   if (items.length === 0) {
     throw new Error("Instagram media url not found");
   }
-  return { archiveFilename: filename(`instagram_${code}.zip`), id: code, items, metadata: instagramMetadata(media), platform: "instagram" };
+  return { archiveFilename: filename(`instagram_${code}.zip`), comments: [], id: code, items, metadata: instagramMetadata(media), platform: "instagram" };
 }
 
 async function instagramUnavailable(net: Net, code: string): Promise<PostfetchError> {

package/src/internal.ts

@@ -101,10 +101,14 @@ export type TiktokExtra = {
 
 /** X (Twitter)-specific metadata. */
 export type TwitterExtra = {
+  /** Parent status id when this post is a reply, even if the parent metadata is unavailable. */
+  replyToId?: string;
   /** 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;
+  /** The parent this post replies to, when included by X. Media is not collected. */
+  parentTweet?: TwitterQuotedTweet;
 };
 
 /** A quoted X post and its normalized metadata. */
@@ -155,6 +159,18 @@ export type PinterestExtra = {
   outboundLink?: string;
 };
 
+/** A reply with its own metadata and downloadable media, separate from the main post. */
+export type PostComment = {
+  /** Reply post id. */
+  id: string;
+  /** Permalink to the reply. */
+  url: string;
+  /** Normalized reply metadata. */
+  metadata: PostMetadata;
+  /** Attachments belonging to this reply. */
+  items: MediaItem[];
+};
+
 /** The result of resolving a post: its platform, id, media items and metadata. */
 export type PostfetchResult =
   | PlatformResult<"facebook", never>
@@ -171,6 +187,8 @@ export type PostfetchResult =
 export type PlatformResult<P extends Platform, Extra> = {
   /** Suggested filename when zipping every item. */
   archiveFilename: string;
+  /** Requested replies, or an empty array when not requested, unsupported or unavailable. */
+  comments: PostComment[];
   /** Platform post/media id. */
   id: string;
   /** The post's media, in order. */
@@ -189,6 +207,7 @@ export type Net = (url: string, init?: RequestInit, attempts?: number) => Promis
 export type ResolveContext = {
   net: Net;
   preferredWidth: number;
+  comments?: number;
   /** Requested soft byte cap, for resolvers that can rank exact rendition sizes. */
   tryMaxBytes?: number;
   url: string;

package/src/linkedin.ts

@@ -51,6 +51,7 @@ export async function resolveLinkedin(input: ResolveContext): Promise<PostfetchR
   }
   return {
     archiveFilename: filename(`linkedin_${id}.zip`),
+    comments: [],
     id,
     items,
     metadata: linkedinMetadata(post),

package/src/pinterest.ts

@@ -24,7 +24,7 @@ export async function resolvePinterest(input: ResolveContext): Promise<Postfetch
   if (items.length === 0) {
     throw new Error("Pinterest media not found");
   }
-  return { archiveFilename: filename(`pinterest_${id}.zip`), id, items, metadata: pinterestMetadata(pin), platform: "pinterest" };
+  return { archiveFilename: filename(`pinterest_${id}.zip`), comments: [], id, items, metadata: pinterestMetadata(pin), platform: "pinterest" };
 }
 
 export function pinterestMetadata(pin: Json): PostMetadata & { extra?: PinterestExtra } {

package/src/postfetch.ts

@@ -13,6 +13,8 @@ import { resolveYoutube } from "./youtube";
 export type PostfetchOptions = {
   /** Custom `fetch` implementation — inject one to unit-test resolvers offline. Defaults to the global `fetch`. */
   fetch?: typeof fetch;
+  /** Maximum direct comments to fetch for X and Reddit. Other platforms ignore this option. Failures return an empty array. */
+  comments?: number;
   /** Preferred media width in pixels; the closest available rendition is chosen. Defaults to `720`. */
   preferredWidth?: number;
   /**
@@ -58,6 +60,7 @@ export async function postfetch(url: string, options: PostfetchOptions = {}): Pr
   }
   const context: ResolveContext = {
     net: createNet(options.fetch ?? globalThis.fetch),
+    comments: options.comments,
     preferredWidth: options.preferredWidth ?? 720,
     tryMaxBytes: options.tryMaxBytes,
     url: trimmed,

package/src/reddit.ts

@@ -8,6 +8,7 @@ import {
   object,
   string,
   type PostMetadata,
+  type PostComment,
   type RedditExtra,
   type ResolveContext,
   type Json,
@@ -31,7 +32,7 @@ export async function resolveReddit(input: ResolveContext): Promise<PostfetchRes
   // already thrown if the post itself is missing, so empty items here mean a
   // self/text post, not a failure.
   const items = await mediaItems(input, post, id);
-  return { archiveFilename: filename(`reddit_${id}.zip`), id, items, metadata: redditMetadata(post), platform: "reddit" };
+  return { archiveFilename: filename(`reddit_${id}.zip`), comments: await redditComments(input, token, id), id, items, metadata: redditMetadata(post), platform: "reddit" };
 }
 
 export function redditMetadata(post: Json): PostMetadata & { extra?: RedditExtra } {
@@ -316,3 +317,91 @@ function extensionOf(mime: string): string {
   }
   return "jpg";
 }
+
+async function redditComments(input: ResolveContext, token: string, id: string): Promise<PostComment[]> {
+  const limit = input.comments;
+  if (!limit || !Number.isSafeInteger(limit) || limit < 0) return [];
+  try {
+    const headers = { authorization: `Bearer ${token}`, "user-agent": browserUserAgent() };
+    const response = await input.net(`https://oauth.reddit.com/comments/${id}?raw_json=1&limit=${Math.min(limit, 100)}&depth=1&sort=top`, { headers }, 1);
+    if (!response.ok) throw new Error("Reddit comments failed");
+    const payload: unknown = await response.json();
+    const listing = Array.isArray(payload) ? payload[1] : null;
+    if (!object(listing) || !object(listing.data) || !Array.isArray(listing.data.children)) throw new Error("Invalid Reddit comments");
+    const comments: PostComment[] = [];
+    const seen = new Set<string>();
+    const queued = new Set<string>();
+    const pending: string[] = [];
+    const collect = (things: unknown[]) => {
+      for (const thing of things) {
+        if (!object(thing) || !object(thing.data)) continue;
+        const data = thing.data;
+        if (data.parent_id !== `t3_${id}`) continue;
+        if (thing.kind === "more" && Array.isArray(data.children)) {
+          for (const child of data.children) {
+            if (typeof child !== "string" || !/^[a-z0-9]+$/i.test(child) || queued.has(child)) continue;
+            queued.add(child);
+            pending.push(child);
+          }
+        } else if (thing.kind === "t1" && comments.length < limit) {
+          const commentId = string(data.id);
+          if (!commentId || seen.has(commentId)) continue;
+          seen.add(commentId);
+          const body = string(data.body);
+          if (!body || body === "[deleted]" || body === "[removed]") continue;
+          comments.push(redditComment(data, commentId, id, body));
+        }
+      }
+    };
+    collect(listing.data.children);
+    while (comments.length < limit && pending.length > 0) {
+      const children = pending.splice(0, Math.min(100, limit - comments.length));
+      const url = new URL("https://oauth.reddit.com/api/morechildren");
+      url.search = new URLSearchParams({ api_type: "json", raw_json: "1", link_id: `t3_${id}`, children: children.join(","), sort: "top", depth: "1", limit_children: "true" }).toString();
+      const more = await input.net(url.href, { headers }, 1);
+      if (!more.ok) throw new Error("Reddit more comments failed");
+      const result: unknown = await more.json();
+      const json = object(result) && object(result.json) ? result.json : null;
+      const data = json && object(json.data) ? json.data : null;
+      if (!data || !Array.isArray(data.things) || (Array.isArray(json?.errors) && json.errors.length > 0)) throw new Error("Invalid additional Reddit comments");
+      collect(data.things);
+    }
+    return comments;
+  } catch {
+    return [];
+  }
+}
+
+function redditComment(data: Json, id: string, postId: string, body: string): PostComment {
+  const metadata = object(data.media_metadata) ? data.media_metadata : {};
+  // Comment images/GIFs use the same rendition metadata as Reddit galleries.
+  // Keep their inline order; do not treat arbitrary links as attachments.
+  const mediaIds = Object.keys(metadata).filter((key) => object(metadata[key])).sort((left, right) => {
+    const position = (key: string) => {
+      const meta = metadata[key];
+      const best = object(meta) && object(meta.s) ? meta.s : {};
+      const tokens = [`![img](${key})`, `![gif](${key})`, string(best.u), string(best.gif), string(best.mp4)];
+      const positions = tokens.flatMap((token) => token && body.includes(token) ? [body.indexOf(token)] : []);
+      return Math.min(...positions);
+    };
+    return position(left) - position(right);
+  });
+  const items = galleryItems({ media_metadata: metadata, gallery_data: { items: mediaIds.map((media_id) => ({ media_id })) } }, id);
+  const text = body.replace(/!\[(?:img|gif)\]\(([^)]+)\)/g, (match, key: string) => {
+    const meta = metadata[key];
+    return object(meta) && object(meta.s) && (string(meta.s.u) || string(meta.s.gif) || string(meta.s.mp4)) ? "" : match;
+  }).split("\n").filter((line) => !items.some((item) => line.trim() === item.url)).join("\n").trim();
+  const author = string(data.author);
+  return {
+    id,
+    url: `https://www.reddit.com/comments/${postId}/_/${id}/`,
+    items,
+    metadata: {
+      text,
+      author: author && author !== "[deleted]" ? { handle: author } : undefined,
+      createdAt: isoFromEpochSeconds(data.created_utc),
+      likeCount: count(data.ups),
+      nsfw: bool(data.over_18),
+    },
+  };
+}

package/src/soundcloud.ts

@@ -22,7 +22,7 @@ export async function resolveSoundcloud(input: ResolveContext): Promise<Postfetc
   const track = await resolveTrack(input.net, url, clientId);
   const id = trackId(track);
   const item = await audioItem(input.net, track, id, clientId);
-  return { archiveFilename: filename(`soundcloud_${id}.zip`), id, items: [item], metadata: soundcloudMetadata(track), platform: "soundcloud" };
+  return { archiveFilename: filename(`soundcloud_${id}.zip`), comments: [], id, items: [item], metadata: soundcloudMetadata(track), platform: "soundcloud" };
 }
 
 export function soundcloudMetadata(track: Json): PostMetadata & { extra?: SoundcloudExtra } {

package/src/tiktok.ts

@@ -42,7 +42,7 @@ export async function resolveTiktok(input: ResolveContext): Promise<PostfetchRes
   if (items.length === 0) {
     throw new Error("TikTok media not found");
   }
-  return { archiveFilename: filename(`tiktok_${user}_${id}.zip`), id, items, metadata: tiktokMetadata(page.item), platform: "tiktok" };
+  return { archiveFilename: filename(`tiktok_${user}_${id}.zip`), comments: [], id, items, metadata: tiktokMetadata(page.item), platform: "tiktok" };
 }
 
 async function videoPage(

package/src/twitter.ts

@@ -9,6 +9,7 @@ import {
   string,
   type PostMetadata,
   type TwitterExtra,
+  type PostComment,
   type ResolveContext,
   type Json,
   type Net,
@@ -43,7 +44,7 @@ export async function resolveTwitter(input: ResolveContext): Promise<PostfetchRe
   // A text-only tweet is a valid result with metadata and no media. Syndication
   // has already failed or returned a tombstone when the tweet is unavailable,
   // so an empty item list here does not mean the lookup failed.
-  return { archiveFilename: filename(`twitter_${id}.zip`), id, items, metadata: twitterMetadata(tweet), platform: "twitter" };
+  return { archiveFilename: filename(`twitter_${id}.zip`), comments: await twitterComments(input, id), id, items, metadata: twitterMetadata(tweet), platform: "twitter" };
 }
 
 export function twitterMetadata(tweet: Json): PostMetadata & { extra?: TwitterExtra } {
@@ -58,6 +59,13 @@ export function twitterMetadata(tweet: Json): PostMetadata & { extra?: TwitterEx
   if (quotedTweet && quotedId) {
     extra.quotedTweet = { id: quotedId, metadata: twitterMetadata(quotedTweet) };
   }
+  const parent = object(tweet.parent) ? tweet.parent : null;
+  const parentId = parent ? string(parent.id_str) : null;
+  const replyToId = string(tweet.in_reply_to_status_id_str) ?? parentId;
+  if (replyToId) extra.replyToId = replyToId;
+  if (parent && parentId) {
+    extra.parentTweet = { id: parentId, metadata: twitterMetadata(parent) };
+  }
   return {
     text: twitterText(tweet) ?? undefined,
     author: user
@@ -98,7 +106,7 @@ function needsFullText(tweet: Json): boolean {
 }
 
 async function expandTwitterText(net: Net, tweet: Json, rootId: string): Promise<void> {
-  const posts = new Map(twitterTweets(tweet, rootId).map(({ id, tweet: post }) => [id, post]));
+  const posts = new Map(twitterTweets(tweet, rootId, true).map(({ id, tweet: post }) => [id, post]));
   for (const [id, post] of posts) {
     if (!needsFullText(post)) {
       continue;
@@ -138,21 +146,18 @@ async function expandTwitterText(net: Net, tweet: Json, rootId: string): Promise
   }
 }
 
-function twitterTweets(tweet: Json, rootId: string): Array<{ id: string; tweet: Json }> {
+function twitterTweets(tweet: Json, rootId: string, includeParents = false): 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 visit = (current: Json, fallbackId?: string): void => {
     const id = string(current.id_str) ?? fallbackId;
-    if (!id || seen.has(id)) {
-      break;
-    }
-    tweets.push({ id, tweet: current });
+    if (!id || seen.has(id)) return;
     seen.add(id);
-    current = object(current.quoted_tweet) ? current.quoted_tweet : null;
-    fallbackId = null;
-  }
+    tweets.push({ id, tweet: current });
+    if (object(current.quoted_tweet)) visit(current.quoted_tweet);
+    if (includeParents && object(current.parent)) visit(current.parent);
+  };
+  visit(tweet, rootId);
   return tweets;
 }
 
@@ -286,3 +291,77 @@ async function contentLength(net: Net, item: MediaItem): Promise<number | null>
 export function tweetId(input: string): string | null {
   return asUrl(input).pathname.match(/\/status(?:es)?\/(\d+)/)?.[1] ?? null;
 }
+
+async function twitterComments(input: ResolveContext, id: string): Promise<PostComment[]> {
+  const limit = input.comments;
+  if (!limit || !Number.isSafeInteger(limit) || limit < 0) return [];
+  try {
+    const comments: PostComment[] = [];
+    const seen = new Set<string>();
+    const cursors = new Set<string>();
+    let cursor: string | null = null;
+    do {
+      const url = new URL(`https://api.fxtwitter.com/2/conversation/${id}`);
+      if (cursor) url.searchParams.set("cursor", cursor);
+      const response = await input.net(url.href, { headers: { accept: "application/json", "user-agent": browserUserAgent() } }, 1);
+      if (!response.ok) throw new Error("Comment lookup failed");
+      const payload: unknown = await response.json();
+      if (!object(payload) || payload.code !== 200 || !Array.isArray(payload.replies)) throw new Error("Invalid comments");
+      const previousCount = comments.length;
+      for (const reply of payload.replies) {
+        if (!object(reply)) continue;
+        const replyId = string(reply.id);
+        const parent = object(reply.replying_to) ? string(reply.replying_to.status) : null;
+        if (!replyId || parent !== id || seen.has(replyId)) continue;
+        seen.add(replyId);
+        comments.push(twitterComment(reply, replyId));
+        if (comments.length >= limit) return comments;
+      }
+      cursor = object(payload.cursor) ? string(payload.cursor.bottom) : null;
+      if (!cursor || cursors.has(cursor) || comments.length === previousCount) break;
+      cursors.add(cursor);
+    } while (comments.length < limit);
+    return comments;
+  } catch {
+    return [];
+  }
+}
+
+function twitterComment(reply: Json, id: string): PostComment {
+  const author = object(reply.author) ? reply.author : {};
+  const verification = object(author.verification) ? author.verification : {};
+  const media = object(reply.media) && Array.isArray(reply.media.all) ? reply.media.all.filter(object) : [];
+  const items: MediaItem[] = media.flatMap((entry, index) => {
+    const url = string(entry.url);
+    const photo = entry.type === "photo";
+    if (!url || (!photo && entry.type !== "video" && entry.type !== "gif" && entry.type !== "animated_gif")) return [];
+    return [{
+      id,
+      platform: "twitter",
+      filename: filename(`twitter_${id}_${index + 1}.${photo ? "jpg" : "mp4"}`),
+      kind: photo ? "image" : "video",
+      mime: photo ? "image/jpeg" : "video/mp4",
+      url,
+      headers: { "user-agent": browserUserAgent() },
+    }];
+  });
+  return {
+    id,
+    url: `https://x.com/i/status/${id}`,
+    items,
+    metadata: {
+      text: string(reply.text) ?? undefined,
+      author: {
+        handle: string(author.screen_name) ?? undefined,
+        name: string(author.name) ?? undefined,
+        verified: bool(verification.verified),
+      },
+      createdAt: isoFromDateString(reply.created_at),
+      likeCount: count(reply.likes),
+      commentCount: count(reply.replies),
+      shareCount: count(reply.reposts),
+      viewCount: count(reply.views),
+      nsfw: bool(reply.possibly_sensitive),
+    },
+  };
+}

package/src/youtube.ts

@@ -105,7 +105,7 @@ function youtubeResult(
     ...(streams.hls ? { hls: true } : {}),
     ...(streams.audio ? { audio: { headers, url: streams.audio } } : {}),
   };
-  return { archiveFilename: filename(`youtube_${id}.zip`), id, items: [media], metadata: youtubeMetadata(payload), platform: "youtube" };
+  return { archiveFilename: filename(`youtube_${id}.zip`), comments: [], id, items: [media], metadata: youtubeMetadata(payload), platform: "youtube" };
 }
 
 async function probeStream(net: Net, url: string, headers: HeadersInit): Promise<void> {