@sns-parse/core 0.4.0-alpha.6 → 0.4.0-alpha.8

package/lib/engine/twitter-user.d.ts

@@ -0,0 +1,67 @@
+/**
+ * X 用户维度查询：时间线（推文/回复/点赞）与关注/粉丝列表。
+ *
+ * 全部走鉴权 GraphQL（auth_token + ct0，TLS 指纹由 tlsget-rs 提供）。
+ * queryId 与特性集等公共件见 ./twitter（DEFAULT_QUERY_IDS 可被调用方覆盖）。
+ */
+import type { ParsedData } from '../types';
+import { categorizeTweetResult, DEFAULT_QUERY_IDS, TIMELINE_FEATURES, type GraphqlGetter, type TwitterCreds, type TwitterQueryIds } from './twitter';
+export { categorizeTweetResult, DEFAULT_QUERY_IDS, TIMELINE_FEATURES };
+export type { TwitterQueryIds };
+export interface TwitterUserInfo {
+    userId: string;
+    name: string;
+    screenName: string;
+    description: string;
+    followers: number;
+    friends: number;
+}
+export declare function resolveTwitterUser(screenName: string, creds: TwitterCreds, get?: GraphqlGetter, queryIds?: TwitterQueryIds): Promise<TwitterUserInfo>;
+export type TimelineTab = 'tweets' | 'replies' | 'likes';
+export interface TimelineEntry {
+    id: string;
+    tweet: ParsedData;
+    /** 文字/视频/图片/转推/回复 中的若干类 */
+    kinds: ('text' | 'video' | 'image' | 'retweet' | 'reply')[];
+    isRetweet: boolean;
+    isReply: boolean;
+    replyToId?: string;
+    url: string;
+}
+/** 兼容别名：timeline instructions → 推文结果 + 底部游标 */
+export declare function parseTimeline(instructions: any[]): {
+    results: any[];
+    bottomCursor?: string;
+};
+/** 用户时间线（tab：tweets=推文/转推；replies=含回复；likes=当前登录用户的点赞） */
+export declare function fetchUserTimeline(opts: {
+    screenName?: string;
+    userId?: string;
+    tab?: TimelineTab;
+    limit?: number;
+    creds: TwitterCreds;
+    get?: GraphqlGetter;
+    queryIds?: TwitterQueryIds;
+}): Promise<TimelineEntry[]>;
+export interface TwitterConnectionUser {
+    name: string;
+    screenName: string;
+    description: string;
+    followers: number;
+    verified: boolean;
+    followedBy: boolean;
+}
+/** 纯函数：从 Followers/Following instructions 抽取用户与底部游标 */
+export declare function parseConnections(instructions: any[]): {
+    users: TwitterConnectionUser[];
+    bottomCursor?: string;
+};
+/** 关注列表（following）或粉丝列表（followers） */
+export declare function fetchUserConnections(opts: {
+    screenName: string;
+    type: 'followers' | 'following';
+    limit?: number;
+    creds: TwitterCreds;
+    get?: GraphqlGetter;
+    queryIds?: TwitterQueryIds;
+}): Promise<TwitterConnectionUser[]>;

package/lib/engine/twitter-user.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIMELINE_FEATURES = exports.DEFAULT_QUERY_IDS = exports.categorizeTweetResult = void 0;
+exports.resolveTwitterUser = resolveTwitterUser;
+exports.parseTimeline = parseTimeline;
+exports.fetchUserTimeline = fetchUserTimeline;
+exports.parseConnections = parseConnections;
+exports.fetchUserConnections = fetchUserConnections;
+const tls_client_1 = require("../utils/tls-client");
+const twitter_1 = require("./twitter");
+Object.defineProperty(exports, "categorizeTweetResult", { enumerable: true, get: function () { return twitter_1.categorizeTweetResult; } });
+Object.defineProperty(exports, "DEFAULT_QUERY_IDS", { enumerable: true, get: function () { return twitter_1.DEFAULT_QUERY_IDS; } });
+Object.defineProperty(exports, "TIMELINE_FEATURES", { enumerable: true, get: function () { return twitter_1.TIMELINE_FEATURES; } });
+async function resolveTwitterUser(screenName, creds, get = tls_client_1.tlsGet, queryIds = {}) {
+    const ids = { ...twitter_1.DEFAULT_QUERY_IDS, ...queryIds };
+    const variables = {
+        screen_name: screenName.replace(/^@/, ''),
+        withSafetyModeUserFields: true,
+        withSuperFollowsUserFields: true,
+    };
+    const data = await (0, twitter_1.twitterGraphql)('UserByScreenName', ids.UserByScreenName, variables, creds, get);
+    const user = data?.data?.user?.result;
+    if (!user || user.__typename === 'UserUnavailable') {
+        throw new Error(`用户 @${screenName} 不可访问（不存在、被封或需登录）`);
+    }
+    const legacy = user.legacy || user.core || {};
+    return {
+        userId: String(user.rest_id ?? legacy.id_str ?? ''),
+        name: String(legacy.name ?? ''),
+        screenName: String(legacy.screen_name ?? screenName.replace(/^@/, '')),
+        description: String(user.profile_bio?.description ?? legacy.description ?? ''),
+        followers: Number(legacy.followers_count ?? 0) || 0,
+        friends: Number(legacy.friends_count ?? 0) || 0,
+    };
+}
+/** 兼容别名：timeline instructions → 推文结果 + 底部游标 */
+function parseTimeline(instructions) {
+    return (0, twitter_1.walkTimelineResults)(instructions);
+}
+/** 用户时间线（tab：tweets=推文/转推；replies=含回复；likes=当前登录用户的点赞） */
+async function fetchUserTimeline(opts) {
+    const tab = opts.tab || 'tweets';
+    const limit = Math.max(1, Math.min(200, opts.limit ?? 20));
+    const get = opts.get || tls_client_1.tlsGet;
+    const ids = { ...twitter_1.DEFAULT_QUERY_IDS, ...opts.queryIds };
+    let userId = opts.userId;
+    if (!userId) {
+        const u = await resolveTwitterUser(opts.screenName, opts.creds, get, opts.queryIds);
+        userId = u.userId;
+    }
+    const [opName, queryId] = tab === 'likes'
+        ? ['Likes', ids.Likes]
+        : tab === 'replies'
+            ? ['UserTweetsAndReplies', ids.UserTweetsAndReplies]
+            : ['UserTweets', ids.UserTweets];
+    const out = [];
+    const seen = new Set();
+    let cursor;
+    let pages = 0;
+    while (out.length < limit && pages < 20) {
+        pages++;
+        const variables = {
+            userId,
+            count: 20,
+            includePromotedContent: false,
+            withQuickPromoteEligibilityTweetQuery: false,
+            withVoice: true,
+            withV2Timeline: true,
+        };
+        if (cursor)
+            variables.cursor = cursor;
+        const data = await (0, twitter_1.twitterGraphql)(opName, queryId, variables, opts.creds, get);
+        const instructions = (() => {
+            const user = data?.data?.user?.result;
+            return (user?.timeline_v2?.timeline || user?.timeline?.timeline)?.instructions || [];
+        })();
+        const { results, bottomCursor } = (0, twitter_1.walkTimelineResults)(instructions);
+        for (const r of results) {
+            const cat = (0, twitter_1.categorizeTweetResult)(r);
+            if (!cat.id || seen.has(cat.id))
+                continue;
+            seen.add(cat.id);
+            const kinds = [];
+            if (cat.isRetweet)
+                kinds.push('retweet');
+            if (cat.isReply)
+                kinds.push('reply');
+            if (cat.hasVideo)
+                kinds.push('video');
+            else if (cat.hasImage)
+                kinds.push('image');
+            else if (!cat.isRetweet)
+                kinds.push('text');
+            out.push({
+                id: cat.id,
+                tweet: (0, twitter_1.mapGraphql)(cat.inner),
+                kinds,
+                isRetweet: cat.isRetweet,
+                isReply: cat.isReply,
+                replyToId: cat.replyToId,
+                url: `https://x.com/i/web/status/${cat.id}`,
+            });
+            if (out.length >= limit)
+                break;
+        }
+        if (!bottomCursor || !results.length)
+            break;
+        cursor = bottomCursor;
+    }
+    return out;
+}
+function userOfEntry(itemContent) {
+    const user = itemContent?.user_results?.result;
+    if (!user || user.__typename === 'UserUnavailable')
+        return null;
+    const legacy = user.legacy || {};
+    return {
+        name: String(legacy.name ?? user.core?.name ?? ''),
+        screenName: String(legacy.screen_name ?? user.core?.screen_name ?? ''),
+        description: String(user.profile_bio?.description ?? legacy.description ?? ''),
+        followers: Number(legacy.followers_count ?? 0) || 0,
+        verified: !!user.is_blue_verified || !!legacy.verified,
+        followedBy: !!legacy.followed_by,
+    };
+}
+/** 纯函数：从 Followers/Following instructions 抽取用户与底部游标 */
+function parseConnections(instructions) {
+    const users = [];
+    let bottomCursor;
+    for (const ins of instructions || []) {
+        for (const entry of ins?.entries || []) {
+            const content = entry?.content;
+            if (!content)
+                continue;
+            if (content.entryType === 'TimelineTimelineCursor' && content.contentType === 'Bottom') {
+                bottomCursor = String(content.value || bottomCursor || '');
+                continue;
+            }
+            if (content.entryType === 'TimelineTimelineItem' && content.itemContent) {
+                const u = userOfEntry(content.itemContent);
+                if (u && u.screenName)
+                    users.push(u);
+            }
+        }
+    }
+    return { users, bottomCursor };
+}
+/** 关注列表（following）或粉丝列表（followers） */
+async function fetchUserConnections(opts) {
+    const limit = Math.max(1, Math.min(1000, opts.limit ?? 50));
+    const get = opts.get || tls_client_1.tlsGet;
+    const ids = { ...twitter_1.DEFAULT_QUERY_IDS, ...opts.queryIds };
+    const u = await resolveTwitterUser(opts.screenName, opts.creds, get, opts.queryIds);
+    const [opName, queryId] = opts.type === 'following'
+        ? ['Following', ids.Following]
+        : ['Followers', ids.Followers];
+    const out = [];
+    const seen = new Set();
+    let cursor;
+    let pages = 0;
+    while (out.length < limit && pages < 50) {
+        pages++;
+        const variables = { userId: u.userId, count: 50, includePromotedContent: false };
+        if (cursor)
+            variables.cursor = cursor;
+        const data = await (0, twitter_1.twitterGraphql)(opName, queryId, variables, opts.creds, get);
+        const instructions = (() => {
+            const user = data?.data?.user?.result;
+            return (user?.timeline_v2?.timeline || user?.timeline?.timeline)?.instructions || [];
+        })();
+        const { users, bottomCursor } = parseConnections(instructions);
+        for (const user of users) {
+            if (seen.has(user.screenName))
+                continue;
+            seen.add(user.screenName);
+            out.push(user);
+            if (out.length >= limit)
+                break;
+        }
+        if (!bottomCursor || !users.length)
+            break;
+        cursor = bottomCursor;
+    }
+    return out;
+}

package/lib/engine/twitter.d.ts

@@ -13,6 +13,37 @@ export interface TwitterCreds {
     authToken: string;
     ct0: string;
 }
+export interface TwitterQueryIds {
+    UserByScreenName?: string;
+    UserTweets?: string;
+    UserTweetsAndReplies?: string;
+    Likes?: string;
+    Followers?: string;
+    Following?: string;
+    TweetDetail?: string;
+}
+/** 默认 queryId 清单（随 x.com web 版本漂移；调用方可整体覆盖） */
+export declare const DEFAULT_QUERY_IDS: Required<TwitterQueryIds>;
+/** 时间线类查询的特性集（UserTweets/Likes/Followers/TweetDetail 共用） */
+export declare const TIMELINE_FEATURES: Record<string, boolean>;
+/** 鉴权 GraphQL 通用请求（headers/cookie 与 TweetResultByRestId 同源） */
+export declare function twitterGraphql(opName: string, queryId: string, variables: Record<string, any>, creds: TwitterCreds, get: GraphqlGetter, features?: Record<string, boolean>): Promise<any>;
+/** 纯函数：把单条 tweet result 归类（含转推解包） */
+export declare function categorizeTweetResult(result: any): {
+    inner: any;
+    isRetweet: boolean;
+    isReply: boolean;
+    hasVideo: boolean;
+    hasImage: boolean;
+    isText: boolean;
+    id: string;
+    replyToId?: string;
+};
+/** 纯函数：从 timeline instructions 抽取推文结果与底部游标（Item/Module 均收） */
+export declare function walkTimelineResults(instructions: any[]): {
+    results: any[];
+    bottomCursor?: string;
+};
 export interface GrokTranslation {
     text: string;
     sourceLang?: string;
@@ -23,4 +54,49 @@ export interface GrokTranslation {
  * x-client-transaction-id / cf_clearance。任何失败返回 null 由调用方回落通用翻译。
  */
 export declare function fetchGrokTranslation(url: string, targetLang: string, creds: TwitterCreds, get?: GraphqlGetter): Promise<GrokTranslation | null>;
+export declare function extractTweetId(url: string): string | null;
+/** 把 GraphQL TweetResultByRestId 响应映射为 ParsedData */
+export declare function mapGraphql(rawResult: any): ParsedData;
+/** 解除 TweetWithVisibilityResults 包裹（NSFW/受限推文） */
+export declare function unwrapTweetResult(result: any): any;
+/** 鉴权 GraphQL 原始获取：返回未映射的 tweet result 节点（树构建复用） */
+export declare function fetchGraphqlRaw(id: string, creds: TwitterCreds, get: GraphqlGetter): Promise<any>;
 export declare function parseTwitter(url: string, http: AxiosInstance, creds?: TwitterCreds, getGraphql?: GraphqlGetter): Promise<ParsedData>;
+/**
+ * 推文树节点：
+ * - quoted = 本推引用的推文（递归）
+ * - replyTo = 本推回复的目标（向根方向递归）
+ * - replies = 本推收到的回复（评论，向下递归；withReplies 时填充）
+ */
+export interface TweetTree {
+    id: string;
+    tweet: ParsedData;
+    quoted?: TweetTree;
+    replyTo?: TweetTree;
+    replies?: TweetTree[];
+}
+/** 游客态（syndication）取被引用推文 ID：显式字段优先；否则启发式——引用链的
+ *  t.co 短链由 X 追加在正文末尾，expanded_url 为推文永久链。 */
+export declare function guestQuoteId(tw: any): string | undefined;
+/** 游客态（syndication）取回复目标推文 ID */
+export declare function guestReplyToId(tw: any): string | undefined;
+export interface FetchTweetTreeOptions {
+    /** 拉取会话回复树（TweetDetail；需登录态） */
+    withReplies?: boolean;
+    /** 回复条数上限（默认 100） */
+    repliesLimit?: number;
+    /** queryId 覆盖 */
+    queryIds?: TwitterQueryIds;
+}
+/**
+ * 纯函数：由会话内的全部 tweet result 装配回复树（挂在 focal 节点下）。
+ * 依据 in_reply_to_status_id_str 建父子边；父不在集合内的孤儿回复跳过。
+ */
+export declare function assembleReplies(focalId: string, results: any[], limit: number, makeNode: (raw: any) => TweetTree): TweetTree[];
+/**
+ * 拉取推文树：引用链（quoted，向下递归）+ 回复链（replyTo，向根递归）
+ * + 可选会话回复树（replies，向下递归，TweetDetail 装配）。
+ * - 有登录态：GraphQL 单次响应自带嵌套 quoted_status_result；父级逐次拉取
+ * - 无登录态：syndication 逐节点拉取（引用 ID 走启发式）；不可达分支静默截断
+ */
+export declare function fetchTweetTree(url: string, http: AxiosInstance, creds?: TwitterCreds, getGraphql?: GraphqlGetter, opts?: FetchTweetTreeOptions): Promise<TweetTree>;

package/lib/engine/twitter.js

@@ -1,7 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIMELINE_FEATURES = exports.DEFAULT_QUERY_IDS = void 0;
+exports.twitterGraphql = twitterGraphql;
+exports.categorizeTweetResult = categorizeTweetResult;
+exports.walkTimelineResults = walkTimelineResults;
 exports.fetchGrokTranslation = fetchGrokTranslation;
+exports.extractTweetId = extractTweetId;
+exports.mapGraphql = mapGraphql;
+exports.unwrapTweetResult = unwrapTweetResult;
+exports.fetchGraphqlRaw = fetchGraphqlRaw;
 exports.parseTwitter = parseTwitter;
+exports.guestQuoteId = guestQuoteId;
+exports.guestReplyToId = guestReplyToId;
+exports.assembleReplies = assembleReplies;
+exports.fetchTweetTree = fetchTweetTree;
 const tls_client_1 = require("../utils/tls-client");
 /**
  * X / Twitter 原生解析器。
@@ -33,6 +45,138 @@ const GRAPHQL_FEATURES = {
     longform_notetweets_rich_text_read_enabled: true,
     responsive_web_graphql_timeline_navigation_enabled: true,
 };
+/** 默认 queryId 清单（随 x.com web 版本漂移；调用方可整体覆盖） */
+exports.DEFAULT_QUERY_IDS = {
+    UserByScreenName: 'sLVLhk0bGj3MVFEKTdax1w',
+    UserTweets: 'HuTx74BxAnezK1gWvYY7zg',
+    UserTweetsAndReplies: 'RIWc55YCNyUJ-U3HHGYkdg',
+    Likes: 'nXEl0lfN_XSznVMlprThgQ',
+    Followers: 'pd8Tt1qUz1YWrICegqZ8cw',
+    Following: 'wjvx62Hye2dGVvnvVco0xA',
+    TweetDetail: 'zXaXQgfyR4GxE21uwYQSyA',
+};
+/** 时间线类查询的特性集（UserTweets/Likes/Followers/TweetDetail 共用） */
+exports.TIMELINE_FEATURES = {
+    blue_business_profile_image_shape_enabled: true,
+    creator_subscriptions_tweet_preview_api_enabled: true,
+    freedom_of_speech_not_reach_fetch_enabled: true,
+    graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+    graphql_timeline_v2_bookmark_timeline: true,
+    hidden_profile_likes_enabled: true,
+    highlights_tweets_tab_ui_enabled: true,
+    interactive_text_enabled: true,
+    longform_notetweets_consumption_enabled: true,
+    longform_notetweets_inline_media_enabled: true,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_richtext_consumption_enabled: true,
+    profile_foundations_tweet_stats_enabled: true,
+    profile_foundations_tweet_stats_tweet_frequency: true,
+    responsive_web_birdwatch_note_limit_enabled: true,
+    responsive_web_edit_tweet_api_enabled: true,
+    responsive_web_enhance_cards_enabled: false,
+    responsive_web_graphql_exclude_directive_enabled: true,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+    responsive_web_media_download_video_enabled: false,
+    responsive_web_text_conversations_enabled: false,
+    responsive_web_twitter_article_data_v2_enabled: true,
+    responsive_web_twitter_article_tweet_consumption_enabled: false,
+    responsive_web_twitter_blue_verified_badge_is_enabled: true,
+    rweb_lists_timeline_redesign_enabled: true,
+    spaces_2022_h2_clipping: true,
+    spaces_2022_h2_spaces_communities: true,
+    standardized_nudges_misinfo: true,
+    subscriptions_verification_info_verified_since_enabled: true,
+    tweet_awards_web_tipping_enabled: false,
+    tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+    tweetypie_unmention_optimization_enabled: true,
+    verified_phone_label_enabled: false,
+    vibe_api_enabled: true,
+    view_counts_everywhere_api_enabled: true,
+};
+/** 鉴权 GraphQL 通用请求（headers/cookie 与 TweetResultByRestId 同源） */
+async function twitterGraphql(opName, queryId, variables, creds, get, features = exports.TIMELINE_FEATURES) {
+    const url = `https://x.com/i/api/graphql/${queryId}/${opName}` +
+        `?variables=${encodeURIComponent(JSON.stringify(variables))}&features=${encodeURIComponent(JSON.stringify(features))}`;
+    let res;
+    try {
+        res = await get(url, {
+            headers: {
+                authorization: `Bearer ${WEB_BEARER}`,
+                'x-csrf-token': creds.ct0,
+                'x-twitter-auth-type': 'OAuth2Session',
+                'x-twitter-active-user': 'yes',
+                'x-twitter-client-language': 'en',
+            },
+            cookies: { auth_token: creds.authToken, ct0: creds.ct0 },
+            timeout: 30000,
+        });
+    }
+    catch (e) {
+        throw new Error(`X GraphQL 请求失败：${e?.message || e}`);
+    }
+    if (res.status === 403 || res.status === 429) {
+        throw new Error(`X GraphQL 被 Cloudflare 拦截 (HTTP ${res.status})：TLS 指纹校验未通过。` +
+            `请确认已安装可选依赖 @char46/tlsget-rs（npm i @char46/tlsget-rs），它提供浏览器级 TLS 指纹。`);
+    }
+    if (res.status !== 200) {
+        throw new Error(`X GraphQL ${opName} 返回 HTTP ${res.status}：${typeof res.data === 'string' ? res.data.slice(0, 120) : JSON.stringify(res.data || {}).slice(0, 120)}`);
+    }
+    return res.data;
+}
+/** 纯函数：把单条 tweet result 归类（含转推解包） */
+function categorizeTweetResult(result) {
+    const raw = unwrapTweetResult(result);
+    const rtInner = raw?.legacy?.retweeted_status_result?.result;
+    const inner = rtInner ? unwrapTweetResult(rtInner) : raw;
+    const legacy = inner?.legacy || {};
+    const media = Array.isArray(legacy.extended_entities?.media) ? legacy.extended_entities.media : [];
+    const hasImage = media.some((m) => m?.type === 'photo');
+    const hasVideo = media.some((m) => m?.type === 'video' || m?.type === 'animated_gif');
+    const isRetweet = !!rtInner;
+    const replyToId = typeof legacy.in_reply_to_status_id_str === 'string' ? legacy.in_reply_to_status_id_str : undefined;
+    const isReply = !!replyToId;
+    const isText = !hasImage && !hasVideo && !isRetweet;
+    return {
+        inner,
+        isRetweet,
+        isReply,
+        hasVideo,
+        hasImage,
+        isText,
+        id: String(inner?.rest_id ?? legacy.id_str ?? ''),
+        replyToId,
+    };
+}
+/** 纯函数：从 timeline instructions 抽取推文结果与底部游标（Item/Module 均收） */
+function walkTimelineResults(instructions) {
+    const results = [];
+    let bottomCursor;
+    for (const ins of instructions || []) {
+        const entries = ins?.entries || ins?.entry ? [].concat(ins.entry, ins.entries).filter(Boolean) : [];
+        for (const entry of entries) {
+            const content = entry?.content;
+            if (!content)
+                continue;
+            if (content.entryType === 'TimelineTimelineCursor' && content.contentType === 'Bottom') {
+                bottomCursor = String(content.value || bottomCursor || '');
+                continue;
+            }
+            if (content.entryType === 'TimelineTimelineItem' && content.itemContent?.tweet_results?.result) {
+                results.push(content.itemContent.tweet_results.result);
+                continue;
+            }
+            if (content.entryType === 'TimelineTimelineModule') {
+                for (const item of content.items || []) {
+                    const r = item?.itemContent?.tweet_results?.result;
+                    if (r)
+                        results.push(r);
+                }
+            }
+        }
+    }
+    return { results, bottomCursor };
+}
 /** Grok 翻译特性集（与网页端抓包一致；关键是 grok_show_grok_translated_post 开关） */
 const GROK_FEATURES = {
     creator_subscriptions_tweet_preview_api_enabled: true,
@@ -370,8 +514,12 @@ function mapGraphql(rawResult) {
         p.title = '';
     return p;
 }
-/** 鉴权 GraphQL：仅用 auth_token + ct0，回退取登录受限推文 */
-async function fetchGraphqlTweet(id, creds, get) {
+/** 解除 TweetWithVisibilityResults 包裹（NSFW/受限推文） */
+function unwrapTweetResult(result) {
+    return result && result.__typename === 'TweetWithVisibilityResults' && result.tweet ? result.tweet : result;
+}
+/** 鉴权 GraphQL 原始获取：返回未映射的 tweet result 节点（树构建复用） */
+async function fetchGraphqlRaw(id, creds, get) {
     const variables = { tweetId: id, includePromotedContent: true, withBirdwatchNotes: true, withVoice: true, withCommunity: true };
     const url = `https://x.com/i/api/graphql/${TWEET_RESULT_QUERY_ID}/TweetResultByRestId` +
         `?variables=${encodeURIComponent(JSON.stringify(variables))}&features=${encodeURIComponent(JSON.stringify(GRAPHQL_FEATURES))}`;
@@ -406,7 +554,11 @@ async function fetchGraphqlTweet(id, creds, get) {
         const tb = result?.tombstone?.text?.text || result?.tombstone?.text;
         throw new Error(`推文不可访问（可能需要登录、已被删除或为非公开内容）${tb ? '：' + tb : ''}`);
     }
-    return mapGraphql(result);
+    return unwrapTweetResult(result);
+}
+/** 鉴权 GraphQL：仅用 auth_token + ct0，回退取登录受限推文 */
+async function fetchGraphqlTweet(id, creds, get) {
+    return mapGraphql(await fetchGraphqlRaw(id, creds, get));
 }
 async function parseTwitter(url, http, creds, getGraphql) {
     const id = extractTweetId(url);
@@ -441,3 +593,199 @@ async function parseTwitter(url, http, creds, getGraphql) {
     const reasonRaw = pick(tw?.tombstone?.text, tw?.tombstone?.name);
     throw new Error(`推文不可访问（可能需要登录、已被删除或为非公开内容）${reasonRaw ? '：' + reasonRaw : ''}`);
 }
+const TREE_QUOTE_DEPTH = 6;
+const TREE_REPLY_DEPTH = 12;
+const TREE_REPLIES_LIMIT = 100;
+/** 游客态（syndication）取被引用推文 ID：显式字段优先；否则启发式——引用链的
+ *  t.co 短链由 X 追加在正文末尾，expanded_url 为推文永久链。 */
+function guestQuoteId(tw) {
+    const q = tw?.quoted_tweet || tw?.quoted_status_result;
+    if (q) {
+        const id = String(pick(q.id_str, q.rest_id, ''));
+        if (/^\d+$/.test(id))
+            return id;
+    }
+    const urls = Array.isArray(tw?.entities?.urls) ? tw.entities.urls : [];
+    const rawText = String(tw?.text || '');
+    const textEnd = rawText.trimEnd();
+    for (const u of urls) {
+        if (!u?.url || !textEnd.endsWith(u.url))
+            continue;
+        const m = /(?:x|twitter)\.com\/[^/]+\/status(?:es)?\/(\d+)/.exec(String(u.expanded_url || ''));
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+/** 游客态（syndication）取回复目标推文 ID */
+function guestReplyToId(tw) {
+    const id = pick(tw?.in_reply_to_status_id_str, tw?.in_reply_to_status_id);
+    if (typeof id === 'string' && /^\d+$/.test(id))
+        return id;
+    if (typeof id === 'number')
+        return String(id);
+    return undefined;
+}
+async function fetchSyndicationRaw(tweetId, http) {
+    const res = await http.get(SYNDICATION_URL, {
+        params: { id: tweetId, token: 'a' },
+        timeout: 30000,
+        headers: { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36' },
+    });
+    const tw = res.data;
+    return tw && tw.__typename === 'Tweet' && tw.user ? tw : null;
+}
+/**
+ * 纯函数：由会话内的全部 tweet result 装配回复树（挂在 focal 节点下）。
+ * 依据 in_reply_to_status_id_str 建父子边；父不在集合内的孤儿回复跳过。
+ */
+function assembleReplies(focalId, results, limit, makeNode) {
+    const byId = new Map();
+    for (const r of results) {
+        const cat = categorizeTweetResult(r);
+        if (!cat.id || byId.has(cat.id) || cat.id === focalId)
+            continue;
+        byId.set(cat.id, { node: makeNode(cat.inner), replyToId: cat.replyToId });
+    }
+    const childrenOf = new Map();
+    const roots = [];
+    for (const { node, replyToId } of byId.values()) {
+        if (replyToId && byId.has(replyToId)) {
+            ;
+            (childrenOf.get(replyToId) || childrenOf.set(replyToId, []).get(replyToId)).push(node);
+        }
+        else if (replyToId === focalId) {
+            roots.push(node);
+        }
+        /* 父不在集合内（祖先线程外）→ 跳过 */
+    }
+    let budget = limit;
+    const attach = (nodes) => {
+        const out = [];
+        for (const n of nodes) {
+            if (budget <= 0)
+                break;
+            budget--;
+            n.replies = attach(childrenOf.get(n.id) || []);
+            out.push(n);
+        }
+        return out;
+    };
+    return attach(roots);
+}
+/**
+ * 拉取推文树：引用链（quoted，向下递归）+ 回复链（replyTo，向根递归）
+ * + 可选会话回复树（replies，向下递归，TweetDetail 装配）。
+ * - 有登录态：GraphQL 单次响应自带嵌套 quoted_status_result；父级逐次拉取
+ * - 无登录态：syndication 逐节点拉取（引用 ID 走启发式）；不可达分支静默截断
+ */
+async function fetchTweetTree(url, http, creds, getGraphql, opts = {}) {
+    const id = extractTweetId(url);
+    if (!id)
+        throw new Error('无法从 X 链接提取推文 ID');
+    const visited = new Set();
+    async function buildGuest(tweetId, depth) {
+        visited.add(tweetId);
+        const tw = await fetchSyndicationRaw(tweetId, http);
+        if (!tw)
+            throw new Error(`推文 ${tweetId} 不可访问（可能需要登录或已删除）`);
+        const node = { id: tweetId, tweet: mapSyndication(tw) };
+        const qid = guestQuoteId(tw);
+        if (qid && !visited.has(qid) && depth < TREE_QUOTE_DEPTH) {
+            try {
+                node.quoted = await buildGuest(qid, depth + 1);
+            }
+            catch { /* 引用不可达则截断 */ }
+        }
+        const rid = guestReplyToId(tw);
+        if (rid && !visited.has(rid) && depth < TREE_REPLY_DEPTH) {
+            try {
+                node.replyTo = await buildGuest(rid, depth + 1);
+            }
+            catch { /* 父推不可达则截断 */ }
+        }
+        return node;
+    }
+    async function buildFromGraphqlResult(raw, depth) {
+        raw = unwrapTweetResult(raw);
+        const rid0 = String(pick(raw?.rest_id, raw?.legacy?.id_str, ''));
+        if (rid0)
+            visited.add(rid0);
+        const node = { id: rid0, tweet: mapGraphql(raw) };
+        const q = unwrapTweetResult(raw?.quoted_status_result?.result);
+        if (q && q.legacy && q.__typename !== 'TweetTombstone' && depth < TREE_QUOTE_DEPTH) {
+            const qid = String(pick(q.rest_id, q.legacy?.id_str, ''));
+            if (!qid || !visited.has(qid))
+                node.quoted = await buildFromGraphqlResult(q, depth + 1);
+        }
+        const rid = raw?.legacy?.in_reply_to_status_id_str;
+        if (typeof rid === 'string' && /^\d+$/.test(rid) && !visited.has(rid) && depth < TREE_REPLY_DEPTH) {
+            try {
+                node.replyTo = await buildGraphqlById(rid, depth + 1);
+            }
+            catch { /* 父推不可达则截断 */ }
+        }
+        return node;
+    }
+    async function buildGraphqlById(tweetId, depth) {
+        if (visited.has(tweetId))
+            throw new Error('引用环');
+        const raw = await fetchGraphqlRaw(tweetId, creds, getGraphql || tls_client_1.tlsGet);
+        return buildFromGraphqlResult(raw, depth);
+    }
+    /** 同步构建会话回复节点：嵌套引用链照常递归（无需网络），父链不拉（由会话集合装配） */
+    function nodeFromResultSync(raw) {
+        raw = unwrapTweetResult(raw);
+        const rid0 = String(pick(raw?.rest_id, raw?.legacy?.id_str, ''));
+        if (rid0)
+            visited.add(rid0);
+        const node = { id: rid0, tweet: mapGraphql(raw) };
+        const q = unwrapTweetResult(raw?.quoted_status_result?.result);
+        if (q && q.legacy && q.__typename !== 'TweetTombstone') {
+            const qid = String(pick(q.rest_id, q.legacy?.id_str, ''));
+            if (!qid || !visited.has(qid))
+                node.quoted = nodeFromResultSync(q);
+        }
+        return node;
+    }
+    async function attachConversation(node) {
+        if (!node)
+            return;
+        const qids = { ...exports.DEFAULT_QUERY_IDS, ...opts.queryIds };
+        const variables = {
+            focalTweetId: node.id,
+            with_rux_injections: false,
+            rankingMode: 'Relevance',
+            includePromotedContent: true,
+            withCommunity: true,
+            withQuickPromoteEligibilityTweetQuery: false,
+            withBirdwatchNotes: true,
+            withVoice: true,
+        };
+        const data = await twitterGraphql('TweetDetail', qids.TweetDetail, variables, creds, getGraphql || tls_client_1.tlsGet);
+        const instructions = data?.data?.threaded_conversation_with_injections_v2?.timeline?.instructions;
+        const { results } = walkTimelineResults(instructions || []);
+        node.replies = assembleReplies(node.id, results, opts.repliesLimit ?? TREE_REPLIES_LIMIT, nodeFromResultSync);
+    }
+    const usedGraphql = !!(creds && creds.authToken && creds.ct0);
+    let tree;
+    if (usedGraphql) {
+        try {
+            tree = await buildGraphqlById(id, 0);
+        }
+        catch {
+            /* 登录态失败（如 Cloudflare）回退游客路径 */
+            tree = await buildGuest(id, 0);
+        }
+    }
+    else {
+        tree = await buildGuest(id, 0);
+    }
+    if (opts.withReplies && usedGraphql && tree) {
+        try {
+            await attachConversation(tree);
+        }
+        catch { /* 会话不可达则保留无回复树 */ }
+    }
+    return tree;
+}

package/lib/index.d.ts

@@ -23,6 +23,7 @@ export * from './engine/config';
 export * from './engine/platform-config';
 export * from './engine/translate';
 export * from './engine/twitter';
+export * from './engine/twitter-user';
 export * from './engine/parser';
 export * from './engine/fetcher';
 export * from './engine/runtime';

package/lib/index.js

@@ -39,6 +39,7 @@ __exportStar(require("./engine/config"), exports);
 __exportStar(require("./engine/platform-config"), exports);
 __exportStar(require("./engine/translate"), exports);
 __exportStar(require("./engine/twitter"), exports);
+__exportStar(require("./engine/twitter-user"), exports);
 __exportStar(require("./engine/parser"), exports);
 __exportStar(require("./engine/fetcher"), exports);
 __exportStar(require("./engine/runtime"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sns-parse/core",
-  "version": "0.4.0-alpha.6+upstream.1.6.7",
+  "version": "0.4.0-alpha.8+upstream.1.6.7",
   "description": "sns-parse 核心：契约、宿主抽象、配置 DSL 与解析引擎（fetcher/parser/翻译/X 原生解析/合并/GIF/TLS 指纹客户端）",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",