1import type {
2  ArticleBlock,
3  ArticleContentState,
4  ArticleEntity,
5  ArticleEntityMapEntry,
6  ArticleMediaInfo,
7} from "./types.js";
8 
9export type ReferencedTweetInfo = {
10  id: string;
11  url: string;
12  authorName?: string;
13  authorUsername?: string;
14  text?: string;
15};
16 
17export type FormatArticleOptions = {
18  referencedTweets?: Map<string, ReferencedTweetInfo>;
19};
20 
21type ResolvedMediaAsset =
22  | {
23      kind: "image";
24      url: string;
25    }
26  | {
27      kind: "video";
28      url: string;
29      posterUrl?: string;
30    };
31 
32function coerceArticleEntity(value: unknown): ArticleEntity | null {
33  if (!value || typeof value !== "object") return null;
34  const candidate = value as ArticleEntity;
35  if (
36    typeof candidate.title === "string" ||
37    typeof candidate.plain_text === "string" ||
38    typeof candidate.preview_text === "string" ||
39    candidate.content_state
40  ) {
41    return candidate;
42  }
43  return null;
44}
45 
46function escapeMarkdownAlt(text: string): string {
47  return text.replace(/[\[\]]/g, "\\$&");
48}
49 
50function normalizeCaption(caption?: string): string {
51  const trimmed = caption?.trim();
52  if (!trimmed) return "";
53  return trimmed.replace(/\s+/g, " ");
54}
55 
56function summarizeTweetText(text?: string): string {
57  const trimmed = text?.trim();
58  if (!trimmed) return "";
59  const normalized = trimmed
60    .split(/\r?\n+/)
61    .map((line) => line.trim())
62    .filter(Boolean)
63    .join(" ");
64  if (normalized.length <= 280) return normalized;
65  return `${normalized.slice(0, 277)}...`;
66}
67 
68function buildTweetUrl(tweetId?: string, username?: string): string | null {
69  if (!tweetId) return null;
70  if (username) {
71    return `https://x.com/${username}/status/${tweetId}`;
72  }
73  return `https://x.com/i/web/status/${tweetId}`;
74}
75 
76type EntityLookup = {
77  byIndex: Map<number, ArticleEntityMapEntry>;
78  byLogicalKey: Map<number, ArticleEntityMapEntry>;
79};
80 
81function buildEntityLookup(
82  entityMap: ArticleContentState["entityMap"] | undefined
83): EntityLookup {
84  const lookup: EntityLookup = {
85    byIndex: new Map<number, ArticleEntityMapEntry>(),
86    byLogicalKey: new Map<number, ArticleEntityMapEntry>(),
87  };
88 
89  if (!entityMap) return lookup;
90 
91  for (const [idx, entry] of Object.entries(entityMap)) {
92    const idxNum = Number(idx);
93    if (Number.isFinite(idxNum)) {
94      lookup.byIndex.set(idxNum, entry);
95    }
96 
97    const logicalKey = parseInt(entry?.key ?? "", 10);
98    if (Number.isFinite(logicalKey) && !lookup.byLogicalKey.has(logicalKey)) {
99      lookup.byLogicalKey.set(logicalKey, entry);
100    }
101  }
102 
103  return lookup;
104}
105 
106function resolveEntityEntry(
107  entityKey: number | undefined,
108  entityMap: ArticleContentState["entityMap"] | undefined,
109  lookup: EntityLookup
110): ArticleEntityMapEntry | undefined {
111  if (entityKey === undefined) return undefined;
112 
113  const byLogicalKey = lookup.byLogicalKey.get(entityKey);
114  if (byLogicalKey) return byLogicalKey;
115 
116  const byIndex = lookup.byIndex.get(entityKey);
117  if (byIndex) return byIndex;
118 
119  if (!entityMap) return undefined;
120  return entityMap[String(entityKey)];
121}
122 
123function resolveVideoUrl(info?: ArticleMediaInfo): string | undefined {
124  if (!info) return undefined;
125  const variants = info.variants ?? [];
126  const mp4 = variants
127    .filter((variant) => variant?.content_type?.includes("video"))
128    .sort((a, b) => (b.bit_rate ?? 0) - (a.bit_rate ?? 0))[0];
129  return mp4?.url ?? variants.find((variant) => typeof variant?.url === "string")?.url;
130}
131 
132function resolveMediaAsset(info?: ArticleMediaInfo): ResolvedMediaAsset | undefined {
133  if (!info) return undefined;
134 
135  const posterUrl = info.preview_image?.original_img_url ?? info.original_img_url;
136  const videoUrl = resolveVideoUrl(info);
137  if (videoUrl) {
138    return {
139      kind: "video",
140      url: videoUrl,
141      posterUrl,
142    };
143  }
144 
145  const imageUrl = info.original_img_url ?? info.preview_image?.original_img_url;
146  if (imageUrl) {
147    return {
148      kind: "image",
149      url: imageUrl,
150    };
151  }
152 
153  return undefined;
154}
155 
156function resolveFallbackMediaAsset(rawUrl?: string): ResolvedMediaAsset | undefined {
157  if (!rawUrl) return undefined;
158 
159  if (/^https:\/\/video\.twimg\.com\//i.test(rawUrl) || /\.(mp4|m4v|mov|webm)(?:$|[?#])/i.test(rawUrl)) {
160    return {
161      kind: "video",
162      url: rawUrl,
163    };
164  }
165 
166  return {
167    kind: "image",
168    url: rawUrl,
169  };
170}
171 
172function resolveCoverUrl(info?: ArticleMediaInfo): string | undefined {
173  if (!info) return undefined;
174  return info.original_img_url ?? info.preview_image?.original_img_url;
175}
176 
177function buildMediaIdentity(asset: ResolvedMediaAsset): string {
178  return asset.kind === "video"
179    ? `video:${asset.url}:${asset.posterUrl ?? ""}`
180    : `image:${asset.url}`;
181}
182 
183function renderMediaLines(
184  asset: ResolvedMediaAsset,
185  altText: string,
186  usedUrls: Set<string>
187): string[] {
188  if (asset.kind === "video") {
189    const lines: string[] = [];
190    if (asset.posterUrl && !usedUrls.has(asset.posterUrl)) {
191      usedUrls.add(asset.posterUrl);
192      lines.push(`![${altText || "video"}](${asset.posterUrl})`);
193    }
194    if (!usedUrls.has(asset.url)) {
195      usedUrls.add(asset.url);
196      lines.push(`[video](${asset.url})`);
197    }
198    return lines;
199  }
200 
201  if (usedUrls.has(asset.url)) {
202    return [];
203  }
204 
205  usedUrls.add(asset.url);
206  return [`![${altText}](${asset.url})`];
207}
208 
209function buildMediaById(article: ArticleEntity): Map<string, ResolvedMediaAsset> {
210  const map = new Map<string, ResolvedMediaAsset>();
211  for (const entity of article.media_entities ?? []) {
212    if (!entity?.media_id) continue;
213    const asset = resolveMediaAsset(entity.media_info);
214    if (asset) {
215      map.set(entity.media_id, asset);
216    }
217  }
218  return map;
219}
220 
221function collectMediaAssets(article: ArticleEntity): ResolvedMediaAsset[] {
222  const assets: ResolvedMediaAsset[] = [];
223  const seen = new Set<string>();
224  const addAsset = (asset?: ResolvedMediaAsset) => {
225    if (!asset) return;
226    const identity = buildMediaIdentity(asset);
227    if (seen.has(identity)) return;
228    seen.add(identity);
229    assets.push(asset);
230  };
231 
232  for (const entity of article.media_entities ?? []) {
233    addAsset(resolveMediaAsset(entity?.media_info));
234  }
235 
236  return assets;
237}
238 
239function resolveEntityMediaLines(
240  entityKey: number | undefined,
241  entityMap: ArticleContentState["entityMap"] | undefined,
242  entityLookup: EntityLookup,
243  mediaById: Map<string, ResolvedMediaAsset>,
244  usedUrls: Set<string>
245): string[] {
246  if (entityKey === undefined) return [];
247  const entry = resolveEntityEntry(entityKey, entityMap, entityLookup);
248  const value = entry?.value;
249  if (!value) return [];
250  const type = value.type;
251  if (type !== "MEDIA" && type !== "IMAGE") return [];
252 
253  const caption = normalizeCaption(value.data?.caption);
254  const altText = caption ? escapeMarkdownAlt(caption) : "";
255  const lines: string[] = [];
256 
257  const mediaItems = value.data?.mediaItems ?? [];
258  for (const item of mediaItems) {
259    const mediaId =
260      typeof item?.mediaId === "string"
261        ? item.mediaId
262        : typeof item?.media_id === "string"
263          ? item.media_id
264          : undefined;
265    const asset = mediaId ? mediaById.get(mediaId) : undefined;
266    if (asset) {
267      lines.push(...renderMediaLines(asset, altText, usedUrls));
268    }
269  }
270 
271  const fallbackUrl = typeof value.data?.url === "string" ? value.data.url : undefined;
272  const fallbackAsset = resolveFallbackMediaAsset(fallbackUrl);
273  if (fallbackAsset) {
274    lines.push(...renderMediaLines(fallbackAsset, altText, usedUrls));
275  }
276 
277  return lines;
278}
279 
280function resolveEntityTweetLines(
281  entityKey: number | undefined,
282  entityMap: ArticleContentState["entityMap"] | undefined,
283  entityLookup: EntityLookup,
284  referencedTweets?: Map<string, ReferencedTweetInfo>
285): string[] {
286  if (entityKey === undefined) return [];
287  const entry = resolveEntityEntry(entityKey, entityMap, entityLookup);
288  const value = entry?.value;
289  if (!value || value.type !== "TWEET") return [];
290 
291  const tweetId = typeof value.data?.tweetId === "string" ? value.data.tweetId : "";
292  if (!tweetId) return [];
293 
294  const referenced = referencedTweets?.get(tweetId);
295  const url =
296    referenced?.url ??
297    buildTweetUrl(tweetId, referenced?.authorUsername) ??
298    `https://x.com/i/web/status/${tweetId}`;
299 
300  const authorText =
301    referenced?.authorName && referenced?.authorUsername
302      ? `${referenced.authorName} (@${referenced.authorUsername})`
303      : referenced?.authorUsername
304        ? `@${referenced.authorUsername}`
305        : referenced?.authorName;
306 
307  const lines: string[] = [];
308  lines.push(`> 引用推文${authorText ? `：${authorText}` : ""}`);
309 
310  const summary = summarizeTweetText(referenced?.text);
311  if (summary) {
312    lines.push(`> ${summary}`);
313  }
314 
315  lines.push(`> ${url}`);
316  return lines;
317}
318 
319function resolveEntityMarkdownLines(
320  entityKey: number | undefined,
321  entityMap: ArticleContentState["entityMap"] | undefined,
322  entityLookup: EntityLookup
323): string[] {
324  if (entityKey === undefined) return [];
325  const entry = resolveEntityEntry(entityKey, entityMap, entityLookup);
326  const value = entry?.value;
327  if (!value || value.type !== "MARKDOWN") return [];
328 
329  const markdown = typeof value.data?.markdown === "string" ? value.data.markdown : "";
330  const normalized = markdown.replace(/\r\n/g, "\n").trimEnd();
331  if (!normalized) return [];
332  return normalized.split("\n");
333}
334 
335function buildMediaLinkMap(
336  entityMap: ArticleContentState["entityMap"] | undefined
337): Map<number, string> {
338  const map = new Map<number, string>();
339  if (!entityMap) return map;
340 
341  const mediaEntries: { idx: number; key: number }[] = [];
342  const linkEntries: { key: number; url: string }[] = [];
343 
344  for (const [idx, entry] of Object.entries(entityMap)) {
345    const value = entry?.value;
346    if (!value) continue;
347    const key = parseInt(entry?.key ?? "", 10);
348    if (isNaN(key)) continue;
349 
350    if (value.type === "MEDIA" || value.type === "IMAGE") {
351      mediaEntries.push({ idx: Number(idx), key });
352    } else if (value.type === "LINK" && typeof value.data?.url === "string") {
353      linkEntries.push({ key, url: value.data.url });
354    }
355  }
356 
357  if (mediaEntries.length === 0 || linkEntries.length === 0) return map;
358 
359  mediaEntries.sort((a, b) => a.key - b.key);
360  linkEntries.sort((a, b) => a.key - b.key);
361 
362  const pool = [...linkEntries];
363  for (const media of mediaEntries) {
364    if (pool.length === 0) break;
365    let linkIdx = pool.findIndex((l) => l.key > media.key);
366    if (linkIdx === -1) linkIdx = 0;
367    const link = pool.splice(linkIdx, 1)[0]!;
368    map.set(media.idx, link.url);
369    map.set(media.key, link.url);
370  }
371 
372  return map;
373}
374 
375function renderInlineLinks(
376  text: string,
377  entityRanges: Array<{ key?: number; offset?: number; length?: number }>,
378  entityMap: ArticleContentState["entityMap"] | undefined,
379  entityLookup: EntityLookup,
380  mediaLinkMap: Map<number, string>
381): string {
382  if (!entityMap || entityRanges.length === 0) return text;
383 
384  const valid = entityRanges.filter(
385    (r) =>
386      typeof r.key === "number" &&
387      typeof r.offset === "number" &&
388      typeof r.length === "number" &&
389      r.length > 0
390  );
391  if (valid.length === 0) return text;
392 
393  const sorted = [...valid].sort((a, b) => (b.offset ?? 0) - (a.offset ?? 0));
394 
395  let result = text;
396  for (const range of sorted) {
397    const offset = range.offset!;
398    const length = range.length!;
399    const key = range.key!;
400 
401    const entry = resolveEntityEntry(key, entityMap, entityLookup);
402    const value = entry?.value;
403    if (!value) continue;
404 
405    let url: string | undefined;
406    if (value.type === "LINK" && typeof value.data?.url === "string") {
407      url = value.data.url;
408    } else if (value.type === "MEDIA" || value.type === "IMAGE") {
409      url = mediaLinkMap.get(key);
410    }
411 
412    if (!url) continue;
413 
414    const linkText = result.slice(offset, offset + length);
415    result =
416      result.slice(0, offset) +
417      `[${linkText}](${url})` +
418      result.slice(offset + length);
419  }
420 
421  return result;
422}
423 
424function renderContentBlocks(
425  blocks: ArticleBlock[],
426  entityMap: ArticleContentState["entityMap"] | undefined,
427  entityLookup: EntityLookup,
428  mediaById: Map<string, ResolvedMediaAsset>,
429  usedUrls: Set<string>,
430  mediaLinkMap: Map<number, string>,
431  referencedTweets?: Map<string, ReferencedTweetInfo>
432): string[] {
433  const lines: string[] = [];
434  let previousKind: "list" | "quote" | "heading" | "text" | "code" | "media" | null = null;
435  let listKind: "ordered" | "unordered" | null = null;
436  let orderedIndex = 0;
437  let inCodeBlock = false;
438 
439  const pushBlock = (
440    blockLines: string[],
441    kind: "list" | "quote" | "heading" | "text" | "media"
442  ) => {
443    if (blockLines.length === 0) return;
444    if (
445      lines.length > 0 &&
446      previousKind &&
447      !(previousKind === kind && (kind === "list" || kind === "quote" || kind === "media"))
448    ) {
449      lines.push("");
450    }
451    lines.push(...blockLines);
452    previousKind = kind;
453  };
454 
455  const collectMediaLines = (block: ArticleBlock): string[] => {
456    const ranges = Array.isArray(block.entityRanges) ? block.entityRanges : [];
457    const mediaLines: string[] = [];
458    for (const range of ranges) {
459      if (typeof range?.key !== "number") continue;
460      mediaLines.push(
461        ...resolveEntityMediaLines(range.key, entityMap, entityLookup, mediaById, usedUrls)
462      );
463    }
464    return mediaLines;
465  };
466 
467  const collectTweetLines = (block: ArticleBlock): string[] => {
468    const ranges = Array.isArray(block.entityRanges) ? block.entityRanges : [];
469    const tweetLines: string[] = [];
470    for (const range of ranges) {
471      if (typeof range?.key !== "number") continue;
472      tweetLines.push(
473        ...resolveEntityTweetLines(range.key, entityMap, entityLookup, referencedTweets)
474      );
475    }
476    return tweetLines;
477  };
478 
479  const collectLinkLines = (block: ArticleBlock): string[] => {
480    const ranges = Array.isArray(block.entityRanges) ? block.entityRanges : [];
481    const linkLines: string[] = [];
482    for (const range of ranges) {
483      if (typeof range?.key !== "number") continue;
484      const entry = resolveEntityEntry(range.key, entityMap, entityLookup);
485      const value = entry?.value;
486      if (value?.type !== "LINK") continue;
487      const url = typeof value.data?.url === "string" ? value.data.url : "";
488      if (url) {
489        linkLines.push(url);
490      }
491    }
492    return [...new Set(linkLines)];
493  };
494 
495  const collectMarkdownLines = (block: ArticleBlock): string[] => {
496    const ranges = Array.isArray(block.entityRanges) ? block.entityRanges : [];
497    const markdownLines: string[] = [];
498    for (const range of ranges) {
499      if (typeof range?.key !== "number") continue;
500      markdownLines.push(...resolveEntityMarkdownLines(range.key, entityMap, entityLookup));
501    }
502    return markdownLines;
503  };
504 
505  const pushTrailingMedia = (mediaLines: string[]) => {
506    if (mediaLines.length > 0) {
507      pushBlock(mediaLines, "media");
508    }
509  };
510 
511  for (const block of blocks) {
512    const type = typeof block?.type === "string" ? block.type : "unstyled";
513    const rawText = typeof block?.text === "string" ? block.text : "";
514    const ranges = Array.isArray(block.entityRanges) ? block.entityRanges : [];
515    const text =
516      type !== "atomic" && type !== "code-block"
517        ? renderInlineLinks(rawText, ranges, entityMap, entityLookup, mediaLinkMap)
518        : rawText;
519 
520    if (type === "code-block") {
521      if (!inCodeBlock) {
522        if (lines.length > 0) {
523          lines.push("");
524        }
525        lines.push("```");
526        inCodeBlock = true;
527      }
528      lines.push(text);
529      previousKind = "code";
530      listKind = null;
531      orderedIndex = 0;
532      continue;
533    }
534 
535    if (type === "atomic") {
536      if (inCodeBlock) {
537        lines.push("```");
538        inCodeBlock = false;
539        previousKind = "code";
540      }
541      listKind = null;
542      orderedIndex = 0;
543 
544      const tweetLines = collectTweetLines(block);
545      if (tweetLines.length > 0) {
546        pushBlock(tweetLines, "quote");
547      }
548 
549      const markdownLines = collectMarkdownLines(block);
550      if (markdownLines.length > 0) {
551        pushBlock(markdownLines, "text");
552      }
553 
554      const mediaLines = collectMediaLines(block);
555      if (mediaLines.length > 0) {
556        pushBlock(mediaLines, "media");
557      }
558 
559      const linkLines = collectLinkLines(block);
560      if (linkLines.length > 0) {
561        pushBlock(linkLines, "text");
562      }
563 
564      continue;
565    }
566 
567    if (inCodeBlock) {
568      lines.push("```");
569      inCodeBlock = false;
570      previousKind = "code";
571    }
572 
573    if (type === "unordered-list-item") {
574      listKind = "unordered";
575      orderedIndex = 0;
576      pushBlock([`- ${text}`], "list");
577      pushTrailingMedia(collectMediaLines(block));
578      continue;
579    }
580 
581    if (type === "ordered-list-item") {
582      if (listKind !== "ordered") {
583        orderedIndex = 0;
584      }
585      listKind = "ordered";
586      orderedIndex += 1;
587      pushBlock([`${orderedIndex}. ${text}`], "list");
588      pushTrailingMedia(collectMediaLines(block));
589      continue;
590    }
591 
592    listKind = null;
593    orderedIndex = 0;
594 
595    switch (type) {
596      case "header-one":
597        pushBlock([`# ${text}`], "heading");
598        pushTrailingMedia(collectMediaLines(block));
599        break;
600      case "header-two":
601        pushBlock([`## ${text}`], "heading");
602        pushTrailingMedia(collectMediaLines(block));
603        break;
604      case "header-three":
605        pushBlock([`### ${text}`], "heading");
606        pushTrailingMedia(collectMediaLines(block));
607        break;
608      case "header-four":
609        pushBlock([`#### ${text}`], "heading");
610        pushTrailingMedia(collectMediaLines(block));
611        break;
612      case "header-five":
613        pushBlock([`##### ${text}`], "heading");
614        pushTrailingMedia(collectMediaLines(block));
615        break;
616      case "header-six":
617        pushBlock([`###### ${text}`], "heading");
618        pushTrailingMedia(collectMediaLines(block));
619        break;
620      case "blockquote": {
621        const quoteLines = text.length > 0 ? text.split("\n") : [""];
622        pushBlock(quoteLines.map((line) => `> ${line}`), "quote");
623        pushTrailingMedia(collectMediaLines(block));
624        break;
625      }
626      default:
627        if (/^XIMGPH_\d+$/.test(text.trim())) {
628          pushTrailingMedia(collectMediaLines(block));
629          break;
630        }
631        pushBlock([text], "text");
632        pushTrailingMedia(collectMediaLines(block));
633        break;
634    }
635  }
636 
637  if (inCodeBlock) {
638    lines.push("```");
639  }
640 
641  return lines;
642}
643 
644export type FormatArticleResult = {
645  markdown: string;
646  coverUrl: string | null;
647};
648 
649export function extractReferencedTweetIds(article: unknown): string[] {
650  const candidate = coerceArticleEntity(article);
651  const entityMap = candidate?.content_state?.entityMap;
652  if (!entityMap) return [];
653 
654  const ids: string[] = [];
655  const seen = new Set<string>();
656  for (const entry of Object.values(entityMap)) {
657    const value = entry?.value;
658    if (value?.type !== "TWEET") continue;
659    const tweetId = typeof value.data?.tweetId === "string" ? value.data.tweetId : "";
660    if (!tweetId || seen.has(tweetId)) continue;
661    seen.add(tweetId);
662    ids.push(tweetId);
663  }
664  return ids;
665}
666 
667export function formatArticleMarkdown(
668  article: unknown,
669  options: FormatArticleOptions = {}
670): FormatArticleResult {
671  const candidate = coerceArticleEntity(article);
672  if (!candidate) {
673    return { markdown: `\`\`\`json\n${JSON.stringify(article, null, 2)}\n\`\`\``, coverUrl: null };
674  }
675 
676  const lines: string[] = [];
677  const usedUrls = new Set<string>();
678  const mediaById = buildMediaById(candidate);
679  const title = typeof candidate.title === "string" ? candidate.title.trim() : "";
680  if (title) {
681    lines.push(`# ${title}`);
682  }
683 
684  const coverUrl = resolveCoverUrl(candidate.cover_media?.media_info) ?? null;
685  if (coverUrl) {
686    usedUrls.add(coverUrl);
687  }
688 
689  const blocks = candidate.content_state?.blocks;
690  const entityMap = candidate.content_state?.entityMap;
691  const entityLookup = buildEntityLookup(entityMap);
692  if (Array.isArray(blocks) && blocks.length > 0) {
693    const mediaLinkMap = buildMediaLinkMap(entityMap);
694    const rendered = renderContentBlocks(
695      blocks,
696      entityMap,
697      entityLookup,
698      mediaById,
699      usedUrls,
700      mediaLinkMap,
701      options.referencedTweets
702    );
703    if (rendered.length > 0) {
704      if (lines.length > 0) lines.push("");
705      lines.push(...rendered);
706    }
707  } else if (typeof candidate.plain_text === "string") {
708    if (lines.length > 0) lines.push("");
709    lines.push(candidate.plain_text.trim());
710  } else if (typeof candidate.preview_text === "string") {
711    if (lines.length > 0) lines.push("");
712    lines.push(candidate.preview_text.trim());
713  }
714 
715  const trailingMediaLines: string[] = [];
716  for (const asset of collectMediaAssets(candidate)) {
717    trailingMediaLines.push(...renderMediaLines(asset, "", usedUrls));
718  }
719  if (trailingMediaLines.length > 0) {
720    lines.push("", "## Media", "");
721    lines.push(...trailingMediaLines);
722  }
723 
724  return { markdown: lines.join("\n").trimEnd(), coverUrl };
725}
726