1type ThreadLike = {
2  requestedId?: string;
3  rootId?: string;
4  tweets?: unknown[];
5  totalTweets?: number;
6  user?: any;
7};
8 
9type TweetPhoto = {
10  src: string;
11  alt?: string;
12};
13 
14type TweetVideo = {
15  url: string;
16  poster?: string;
17  alt?: string;
18  type?: string;
19};
20 
21export type ThreadTweetsMarkdownOptions = {
22  username?: string;
23  headingLevel?: number;
24  startIndex?: number;
25  includeTweetUrls?: boolean;
26};
27 
28export type ThreadMarkdownOptions = ThreadTweetsMarkdownOptions & {
29  includeHeader?: boolean;
30  title?: string;
31  sourceUrl?: string;
32};
33 
34function coerceThread(value: unknown): ThreadLike | null {
35  if (!value || typeof value !== "object") return null;
36  const candidate = value as ThreadLike;
37  if (!Array.isArray(candidate.tweets)) return null;
38  return candidate;
39}
40 
41function escapeMarkdownAlt(text: string): string {
42  return text.replace(/[\[\]]/g, "\\$&");
43}
44 
45function normalizeAlt(text?: string | null): string {
46  const trimmed = text?.trim();
47  if (!trimmed) return "";
48  return trimmed.replace(/\s+/g, " ");
49}
50 
51function parseTweetText(tweet: any): string {
52  const noteText = tweet?.note_tweet?.note_tweet_results?.result?.text;
53  const legacyText = tweet?.legacy?.full_text ?? tweet?.legacy?.text ?? "";
54  return (noteText ?? legacyText ?? "").trim();
55}
56 
57function parsePhotos(tweet: any): TweetPhoto[] {
58  const media = tweet?.legacy?.extended_entities?.media ?? [];
59  return media
60    .reduce((acc: TweetPhoto[], item: any) => {
61      if (item?.type !== "photo") {
62        return acc;
63      }
64      const src = item.media_url_https ?? item.media_url;
65      if (!src) {
66        return acc;
67      }
68      const alt = normalizeAlt(item.ext_alt_text);
69      acc.push({ src, alt });
70      return acc;
71    }, [])
72    .filter((photo) => Boolean(photo.src));
73}
74 
75function parseVideos(tweet: any): TweetVideo[] {
76  const media = tweet?.legacy?.extended_entities?.media ?? [];
77  return media
78    .reduce((acc: TweetVideo[], item: any) => {
79      if (!item?.type || !["animated_gif", "video"].includes(item.type)) {
80        return acc;
81      }
82      const variants = item?.video_info?.variants ?? [];
83      const sources = variants
84        .map((variant: any) => ({
85          contentType: variant?.content_type,
86          url: variant?.url,
87          bitrate: variant?.bitrate ?? 0,
88        }))
89        .filter((variant: any) => Boolean(variant.url));
90 
91      const videoSources = sources.filter((variant: any) =>
92        String(variant.contentType ?? "").includes("video")
93      );
94      const sorted = (videoSources.length > 0 ? videoSources : sources).sort(
95        (a: any, b: any) => (b.bitrate ?? 0) - (a.bitrate ?? 0)
96      );
97      const best = sorted[0];
98      if (!best?.url) {
99        return acc;
100      }
101      const alt = normalizeAlt(item.ext_alt_text);
102      acc.push({
103        url: best.url,
104        poster: item.media_url_https ?? item.media_url ?? undefined,
105        alt,
106        type: item.type,
107      });
108      return acc;
109    }, [])
110    .filter((video) => Boolean(video.url));
111}
112 
113function unwrapTweetResult(result: any): any {
114  if (!result) return null;
115  if (result.__typename === "TweetWithVisibilityResults" && result.tweet) {
116    return result.tweet;
117  }
118  return result;
119}
120 
121function resolveTweetId(tweet: any): string | undefined {
122  return tweet?.legacy?.id_str ?? tweet?.rest_id;
123}
124 
125function buildTweetUrl(username: string | undefined, tweetId: string | undefined): string | null {
126  if (!tweetId) return null;
127  if (username) {
128    return `https://x.com/${username}/status/${tweetId}`;
129  }
130  return `https://x.com/i/web/status/${tweetId}`;
131}
132 
133function formatTweetMarkdown(
134  tweet: any,
135  index: number,
136  options: ThreadTweetsMarkdownOptions
137): string[] {
138  const headingLevel = options.headingLevel ?? 2;
139  const includeTweetUrls = options.includeTweetUrls ?? true;
140  const headingPrefix = "#".repeat(Math.min(Math.max(headingLevel, 1), 6));
141  const tweetId = resolveTweetId(tweet);
142  const tweetUrl = includeTweetUrls ? buildTweetUrl(options.username, tweetId) : null;
143 
144  const lines: string[] = [];
145  lines.push(`${headingPrefix} ${index}`);
146  if (tweetUrl) {
147    lines.push(tweetUrl);
148  }
149  lines.push("");
150 
151  const text = parseTweetText(tweet);
152  const photos = parsePhotos(tweet);
153  const videos = parseVideos(tweet);
154  const quoted = unwrapTweetResult(tweet?.quoted_status_result?.result);
155 
156  const bodyLines: string[] = [];
157  if (text) {
158    bodyLines.push(...text.split(/\r?\n/));
159  }
160 
161  const quotedLines = formatQuotedTweetMarkdown(quoted);
162  if (quotedLines.length > 0) {
163    if (bodyLines.length > 0) bodyLines.push("");
164    bodyLines.push(...quotedLines);
165  }
166 
167  const photoLines = photos.map((photo) => {
168    const alt = photo.alt ? escapeMarkdownAlt(photo.alt) : "";
169    return `![${alt}](${photo.src})`;
170  });
171  if (photoLines.length > 0) {
172    if (bodyLines.length > 0) bodyLines.push("");
173    bodyLines.push(...photoLines);
174  }
175 
176  const videoLines: string[] = [];
177  for (const video of videos) {
178    if (video.poster) {
179      const alt = video.alt ? escapeMarkdownAlt(video.alt) : "video";
180      videoLines.push(`![${alt}](${video.poster})`);
181    }
182    videoLines.push(`[${video.type ?? "video"}](${video.url})`);
183  }
184  if (videoLines.length > 0) {
185    if (bodyLines.length > 0) bodyLines.push("");
186    bodyLines.push(...videoLines);
187  }
188 
189  if (bodyLines.length === 0) {
190    bodyLines.push("_No text or media._");
191  }
192 
193  lines.push(...bodyLines);
194  return lines;
195}
196 
197function formatQuotedTweetMarkdown(quoted: any): string[] {
198  if (!quoted) return [];
199  const quotedUser = quoted?.core?.user_results?.result?.legacy;
200  const quotedUsername = quotedUser?.screen_name;
201  const quotedName = quotedUser?.name;
202  const quotedAuthor =
203    quotedUsername && quotedName
204      ? `${quotedName} (@${quotedUsername})`
205      : quotedUsername
206        ? `@${quotedUsername}`
207        : quotedName ?? "Unknown";
208 
209  const quotedId = resolveTweetId(quoted);
210  const quotedUrl =
211    buildTweetUrl(quotedUsername, quotedId) ??
212    (quotedId ? `https://x.com/i/web/status/${quotedId}` : "unavailable");
213 
214  const quotedText = parseTweetText(quoted);
215  const lines: string[] = [];
216  lines.push(`Author: ${quotedAuthor}`);
217  lines.push(`URL: ${quotedUrl}`);
218  if (quotedText) {
219    lines.push("", ...quotedText.split(/\r?\n/));
220  } else {
221    lines.push("", "(no content)");
222  }
223 
224  return lines.map((line) => `> ${line}`.trimEnd());
225}
226 
227export function formatThreadTweetsMarkdown(
228  tweets: unknown[],
229  options: ThreadTweetsMarkdownOptions = {}
230): string {
231  const lines: string[] = [];
232  const startIndex = options.startIndex ?? 1;
233  if (!Array.isArray(tweets) || tweets.length === 0) {
234    return "";
235  }
236 
237  tweets.forEach((tweet, index) => {
238    if (lines.length > 0) {
239      lines.push("");
240    }
241    lines.push(...formatTweetMarkdown(tweet, startIndex + index, options));
242  });
243 
244  return lines.join("\n").trimEnd();
245}
246 
247export function formatThreadMarkdown(
248  thread: unknown,
249  options: ThreadMarkdownOptions = {}
250): string {
251  const candidate = coerceThread(thread);
252  if (!candidate) {
253    return `\`\`\`json\n${JSON.stringify(thread, null, 2)}\n\`\`\``;
254  }
255 
256  const tweets = candidate.tweets ?? [];
257  const firstTweet = tweets[0] as any;
258  const user = candidate.user ?? firstTweet?.core?.user_results?.result?.legacy;
259  const username = user?.screen_name;
260  const name = user?.name;
261 
262  const includeHeader = options.includeHeader ?? true;
263  const lines: string[] = [];
264  if (includeHeader) {
265    if (options.title) {
266      lines.push(`# ${options.title}`);
267    } else if (username) {
268      lines.push(`# Thread by @${username}${name ? ` (${name})` : ""}`);
269    } else {
270      lines.push("# Thread");
271    }
272 
273    const sourceUrl = options.sourceUrl ?? buildTweetUrl(username, candidate.rootId ?? candidate.requestedId);
274    if (sourceUrl) {
275      lines.push(`Source: ${sourceUrl}`);
276    }
277    if (typeof candidate.totalTweets === "number") {
278      lines.push(`Tweets: ${candidate.totalTweets}`);
279    }
280  }
281 
282  const tweetMarkdown = formatThreadTweetsMarkdown(tweets, {
283    ...options,
284    username,
285  });
286 
287  if (tweetMarkdown) {
288    if (lines.length > 0) {
289      lines.push("");
290    }
291    lines.push(tweetMarkdown);
292  }
293 
294  return lines.join("\n").trimEnd();
295}
296