@postfetch/core 0.5.2 → 0.7.0

package/src/linkedin.ts

@@ -0,0 +1,243 @@
+import {
+  count,
+  filename,
+  isoFromDateString,
+  object,
+  PostfetchError,
+  string,
+  type Json,
+  type MediaItem,
+  type PostMetadata,
+  type PostfetchResult,
+  type ResolveContext,
+} from "./internal";
+import { browserUserAgent, navigationHeaders } from "./fingerprint";
+
+type LinkedinPostKind = "activity" | "share" | "ugcPost";
+
+type LinkedinPostReference = {
+  id: string;
+  kind: LinkedinPostKind;
+};
+
+export async function resolveLinkedin(input: ResolveContext): Promise<PostfetchResult> {
+  const reference = postReference(input.url);
+  const pageUrl = `https://www.linkedin.com/feed/update/urn:li:${reference.kind}:${reference.id}`;
+  const response = await input.net(pageUrl, { headers: navigationHeaders() });
+  if (response.status === 404) {
+    throw new PostfetchError(404, "LinkedIn post not found", "notFound");
+  }
+  if (response.status === 429 || response.status === 999) {
+    throw new PostfetchError(429, "LinkedIn rate limit reached", "rateLimited");
+  }
+  if (!response.ok) {
+    throw new PostfetchError(response.status, "LinkedIn post unavailable", "unavailable");
+  }
+  if (response.url.includes("/signup/") || response.url.includes("/login")) {
+    throw new PostfetchError(401, "LinkedIn login required", "loginRequired");
+  }
+
+  const html = await response.text();
+  const post = linkedinPost(html);
+  if (!post) {
+    throw new PostfetchError(404, "LinkedIn post unavailable", "unavailable");
+  }
+  const canonical = string(post["@id"]);
+  const canonicalReference = canonical ? postReferenceOrNull(canonical) : null;
+  const id = canonicalReference?.id ?? reference.id;
+  const items = linkedinItems(post, html, id, pageUrl);
+  if (items.length === 0) {
+    throw new Error("LinkedIn media url not found");
+  }
+  return {
+    archiveFilename: filename(`linkedin_${id}.zip`),
+    id,
+    items,
+    metadata: linkedinMetadata(post),
+    platform: "linkedin",
+  };
+}
+
+export function linkedinMetadata(post: Json): PostMetadata {
+  const author = linkedinAuthor(post);
+  return {
+    title: string(post.text) ?? string(post.name) ?? string(post.headline) ?? undefined,
+    text: string(post.description) ?? string(post.articleBody) ?? string(post.text) ?? undefined,
+    author: author
+      ? {
+          handle: linkedinHandle(string(author.url)) ?? undefined,
+          name: string(author.name) ?? undefined,
+        }
+      : undefined,
+    createdAt: isoFromDateString(post.datePublished ?? post.uploadDate),
+    likeCount: interactionCount(post.interactionStatistic, "LikeAction"),
+    commentCount: count(post.commentCount) ?? interactionCount(post.interactionStatistic, "CommentAction"),
+  };
+}
+
+function postReference(input: string): LinkedinPostReference {
+  const reference = postReferenceOrNull(input);
+  if (!reference) {
+    throw new PostfetchError(400, "LinkedIn post id not found");
+  }
+  return reference;
+}
+
+function postReferenceOrNull(input: string): LinkedinPostReference | null {
+  let pathname: string;
+  try {
+    pathname = new URL(input).pathname.replace(/%3A/gi, ":");
+  } catch {
+    return null;
+  }
+  const urn = pathname.match(/\/(?:embed\/)?feed\/update\/urn:li:(activity|share|ugcpost):(\d+)\/?$/i);
+  const post = pathname.match(/\/posts\/[^/]*-(activity|share|ugcpost)-(\d+)(?:-[^/]*)?\/?$/i);
+  const match = urn ?? post;
+  if (!match) {
+    return null;
+  }
+  switch (match[1].toLowerCase()) {
+    case "activity":
+      return { id: match[2], kind: "activity" };
+    case "share":
+      return { id: match[2], kind: "share" };
+    case "ugcpost":
+      return { id: match[2], kind: "ugcPost" };
+    default:
+      return null;
+  }
+}
+
+function linkedinAuthor(post: Json): Json | null {
+  if (object(post.creator)) {
+    return post.creator;
+  }
+  if (object(post.author)) {
+    return post.author;
+  }
+  return null;
+}
+
+function linkedinPost(html: string): Json | null {
+  for (const match of html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
+    if (!/\btype=["']application\/ld\+json["']/i.test(match[1])) {
+      continue;
+    }
+    const parsed = parseJson(match[2]);
+    for (const entry of jsonLdEntries(parsed)) {
+      if (hasSchemaType(entry, "VideoObject") || hasSchemaType(entry, "SocialMediaPosting")) {
+        return entry;
+      }
+    }
+  }
+  return null;
+}
+
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    try {
+      return JSON.parse(decodeHtml(value));
+    } catch {
+      return null;
+    }
+  }
+}
+
+function jsonLdEntries(value: unknown): Json[] {
+  if (Array.isArray(value)) {
+    return value.filter(object);
+  }
+  if (!object(value)) {
+    return [];
+  }
+  return Array.isArray(value["@graph"]) ? value["@graph"].filter(object) : [value];
+}
+
+function hasSchemaType(value: Json, expected: string): boolean {
+  const type = value["@type"];
+  return type === expected || (Array.isArray(type) && type.includes(expected));
+}
+
+function linkedinItems(post: Json, html: string, id: string, referer: string): MediaItem[] {
+  const headers = { referer, "user-agent": browserUserAgent() };
+  if (hasSchemaType(post, "VideoObject")) {
+    const url = bestVideoUrl(html) ?? string(post.contentUrl);
+    return url
+      ? [{ filename: filename(`linkedin_${id}.mp4`), headers, id, kind: "video", mime: "video/mp4", platform: "linkedin", url }]
+      : [];
+  }
+  const url = imageUrl(post.image);
+  return url
+    ? [{ filename: filename(`linkedin_${id}.jpg`), headers, id, kind: "image", mime: "image/jpeg", platform: "linkedin", url }]
+    : [];
+}
+
+function bestVideoUrl(html: string): string | null {
+  const encoded = html.match(/<video\b[^>]*\bdata-sources=(["'])(.*?)\1[^>]*>/is)?.[2];
+  if (!encoded) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decodeHtml(encoded));
+  } catch {
+    return null;
+  }
+  const sources = Array.isArray(parsed) ? parsed.filter(object) : [];
+  const videos = sources.filter((source) => string(source.type) === "video/mp4" && string(source.src));
+  const selected = videos.reduce<Json | null>((best, candidate) => {
+    const bitrate = count(candidate["data-bitrate"]) ?? 0;
+    const bestBitrate = best ? count(best["data-bitrate"]) ?? 0 : -1;
+    return bitrate > bestBitrate ? candidate : best;
+  }, null);
+  return selected ? string(selected.src) : null;
+}
+
+function imageUrl(value: unknown): string | null {
+  if (typeof value === "string") {
+    return string(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(imageUrl).find((url): url is string => Boolean(url)) ?? null;
+  }
+  return object(value) ? string(value.url) : null;
+}
+
+function interactionCount(value: unknown, action: string): number | undefined {
+  const statistics = Array.isArray(value) ? value.filter(object) : object(value) ? [value] : [];
+  const statistic = statistics.find((entry) => string(entry.interactionType)?.endsWith(`/${action}`));
+  return statistic ? count(statistic.userInteractionCount) : undefined;
+}
+
+function linkedinHandle(value: string | null): string | null {
+  if (!value) {
+    return null;
+  }
+  try {
+    return new URL(value).pathname.match(/^\/(?:company|in|showcase)\/([^/]+)/)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function decodeHtml(value: string): string {
+  return value.replace(/&(quot|amp|lt|gt|#39|#x27|#(\d+)|#x([0-9a-f]+));/gi, (_entity, name: string, decimal: string, hex: string) => {
+    switch (name.toLowerCase()) {
+      case "quot":
+        return '"';
+      case "amp":
+        return "&";
+      case "lt":
+        return "<";
+      case "gt":
+        return ">";
+      case "#39":
+      case "#x27":
+        return "'";
+      default:
+        return String.fromCodePoint(decimal ? Number.parseInt(decimal, 10) : Number.parseInt(hex, 16));
+    }
+  });
+}

package/src/postfetch.ts

@@ -1,6 +1,7 @@
-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";
 import { resolvePinterest } from "./pinterest";
 import { resolveReddit } from "./reddit";
 import { resolveSoundcloud } from "./soundcloud";
@@ -14,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;
 };
 
 /**
@@ -21,10 +29,11 @@ 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 Instagram, TikTok, YouTube, Facebook or X.
+ * @param url A post URL from a supported platform.
  * @param options See {@link PostfetchOptions}.
  * @returns The resolved post and its media items.
  * @throws {PostfetchError} If the URL is empty or its host is unsupported.
@@ -42,16 +51,26 @@ 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":
       return resolveInstagram(context);
+    case "linkedin":
+      return resolveLinkedin(context);
     case "pinterest":
       return resolvePinterest(context);
     case "reddit":
@@ -67,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.
  *
@@ -82,6 +160,9 @@ export function detect(url: string): Platform {
   if (host.includes("instagram.com")) {
     return "instagram";
   }
+  if (host === "linkedin.com" || host.endsWith(".linkedin.com")) {
+    return "linkedin";
+  }
   if (host.includes("pinterest.") || host === "pin.it") {
     return "pinterest";
   }
@@ -100,5 +181,5 @@ export function detect(url: string): Platform {
   if (host === "x.com" || host.endsWith(".x.com") || host.includes("twitter.com")) {
     return "twitter";
   }
-  throw new PostfetchError(400, "only Facebook, Instagram, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube URLs are supported");
+  throw new PostfetchError(400, "only Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube URLs are supported");
 }

package/src/tiktok.ts

@@ -14,27 +14,26 @@ import {
   type PostfetchResult,
   type MediaItem,
 } from "./internal";
-import { browserUserAgent, firefoxUserAgent } from "./fingerprint";
+import {
+  browserUserAgent,
+  firefoxNavigationHeaders,
+  navigationHeaders,
+} from "./fingerprint";
 
 const marker = '<script id="__UNIVERSAL_DATA_FOR_REHYDRATION__" type="application/json">';
+const pageAttemptCount = 12;
 
 export async function resolveTiktok(input: ResolveContext): Promise<PostfetchResult> {
-  const userAgent = browserUserAgent();
-  const pageUrl = await followShortlink(input.net, userAgent, input.url);
+  const pageUrl = await followShortlink(input.net, browserUserAgent(), input.url);
   const id = videoId(pageUrl);
   if (!id) {
     throw new Error("TikTok video id not found");
   }
-  const page = await fetchVideoPage(input.net, id, userAgent).catch((error: unknown) => {
-    if (!recoverablePageError(error)) {
-      throw error;
-    }
-    return fetchVideoPage(input.net, id, firefoxUserAgent());
-  });
+  const page = await videoPage(input.net, id, asUrl(pageUrl).pathname.includes("/photo/"));
   const user = author(page.item) ?? username(pageUrl) ?? "i";
   const headers: Record<string, string> = {
     referer: `https://www.tiktok.com/@${encodeURIComponent(user)}/video/${encodeURIComponent(id)}`,
-    "user-agent": userAgent,
+    "user-agent": page.userAgent,
   };
   if (page.cookie) {
     headers.cookie = page.cookie;
@@ -46,6 +45,41 @@ export async function resolveTiktok(input: ResolveContext): Promise<PostfetchRes
   return { archiveFilename: filename(`tiktok_${user}_${id}.zip`), id, items, metadata: tiktokMetadata(page.item), platform: "tiktok" };
 }
 
+async function videoPage(
+  net: Net,
+  id: string,
+  photo: boolean,
+): Promise<{ item: Json; cookie: string | null; userAgent: string }> {
+  for (let attempt = 0; attempt < pageAttemptCount; attempt += 1) {
+    const baseHeaders = attempt % 2 === 0 ? navigationHeaders() : firefoxNavigationHeaders();
+    const userAgent = baseHeaders["user-agent"];
+    const headers = {
+      ...baseHeaders,
+      referer: "https://www.tiktok.com/",
+      "sec-fetch-site": "same-origin",
+    };
+    try {
+      return { ...(await fetchVideoPage(net, id, headers)), userAgent };
+    } catch (error) {
+      if (!recoverablePageError(error)) {
+        throw error;
+      }
+    }
+  }
+
+  if (!photo) {
+    throw new Error("TikTok hydration not found");
+  }
+  const baseHeaders = navigationHeaders();
+  const userAgent = baseHeaders["user-agent"];
+  const headers = {
+    ...baseHeaders,
+    referer: "https://www.tiktok.com/",
+    "sec-fetch-site": "same-origin",
+  };
+  return { ...(await fetchEmbedPage(net, id, headers)), userAgent };
+}
+
 export function tiktokMetadata(item: Json): PostMetadata & { extra?: TiktokExtra } {
   const user = object(item.author) ? item.author : null;
   const stats = object(item.stats) ? item.stats : null;
@@ -78,18 +112,25 @@ export function tiktokMetadata(item: Json): PostMetadata & { extra?: TiktokExtra
 async function fetchVideoPage(
   net: Net,
   id: string,
-  userAgent: string,
+  headers: Record<string, string>,
 ): Promise<{ item: Json; cookie: string | null }> {
   const page = await net(`https://www.tiktok.com/@i/video/${id}`, {
-    headers: {
-      accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
-      referer: "https://www.tiktok.com/",
-      "user-agent": userAgent,
-    },
+    headers,
   });
   return { cookie: cookieHeader(page.headers), item: itemStruct(await page.text()) };
 }
 
+async function fetchEmbedPage(
+  net: Net,
+  id: string,
+  headers: Record<string, string>,
+): Promise<{ item: Json; cookie: string | null }> {
+  const page = await net(`https://www.tiktok.com/embed/v2/${id}`, {
+    headers,
+  });
+  return { cookie: cookieHeader(page.headers), item: embedItemStruct(await page.text(), id) };
+}
+
 export function isShortlinkHost(hostname: string): boolean {
   return hostname === "vm.tiktok.com" || hostname === "vt.tiktok.com";
 }
@@ -134,11 +175,75 @@ function itemStruct(html: string): Json {
   return item;
 }
 
+function embedItemStruct(html: string, id: string): Json {
+  const raw = html.match(/<script\b[^>]*\bid=["']__FRONTITY_CONNECT_STATE__["'][^>]*>([\s\S]*?)<\/script>/i)?.[1];
+  if (!raw) {
+    throw new Error("TikTok embed state not found");
+  }
+  const parsed: unknown = JSON.parse(raw);
+  const source = object(parsed) && object(parsed.source) ? parsed.source : null;
+  const data = source && object(source.data) ? source.data : null;
+  const rawRoute = data ? data[`/embed/v2/${id}`] : null;
+  const route = object(rawRoute) ? rawRoute : null;
+  const videoData = route && object(route.videoData) ? route.videoData : null;
+  const item = videoData && object(videoData.itemInfos) ? videoData.itemInfos : null;
+  if (!videoData || !item) {
+    throw new Error("TikTok embed item not found");
+  }
+
+  const authorInfo = object(videoData.authorInfos) ? videoData.authorInfos : {};
+  const musicInfo = object(videoData.musicInfos) ? videoData.musicInfos : {};
+  const video = object(item.video) ? item.video : {};
+  const videoMeta = object(video.videoMeta) ? video.videoMeta : {};
+  const imagePost = object(videoData.imagePostInfo) ? videoData.imagePostInfo : null;
+  const displayImages = imagePost && Array.isArray(imagePost.displayImages) ? imagePost.displayImages.filter(object) : [];
+  if (displayImages.length === 0) {
+    throw new Error("TikTok video hydration not found");
+  }
+
+  return {
+    ...item,
+    author: {
+      nickname: string(authorInfo.nickName),
+      uniqueId: string(authorInfo.uniqueId),
+      verified: bool(authorInfo.verified),
+    },
+    desc: string(item.text),
+    imagePost: {
+      images: displayImages.map((image) => ({
+        imageURL: {
+          urlList: Array.isArray(image.urlList) ? image.urlList.map(string).filter((url): url is string => Boolean(url)) : [],
+        },
+      })),
+    },
+    music: {
+      authorName: string(musicInfo.authorName),
+      playUrl: firstString(musicInfo.playUrl),
+      title: string(musicInfo.musicName),
+    },
+    stats: {
+      commentCount: item.commentCount,
+      diggCount: item.diggCount,
+      playCount: item.playCount,
+      shareCount: item.shareCount,
+    },
+    video: {
+      duration: videoMeta.duration,
+    },
+  };
+}
+
 function recoverablePageError(error: unknown): boolean {
   const message = error instanceof Error ? error.message : "";
   return message === "TikTok WAF challenge" || message === "TikTok hydration not found";
 }
 
+function firstString(value: unknown): string | null {
+  return Array.isArray(value)
+    ? value.map(string).find((candidate): candidate is string => candidate !== null) ?? null
+    : string(value);
+}
+
 function downloadUrl(item: Json): string | null {
   const video = object(item.video) ? item.video : null;
   return video ? string(video.playAddr) ?? string(video.downloadAddr) : null;

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> {