@sns-parse/core 0.3.0-alpha.1 → 0.4.0-alpha.10

package/lib/engine/runtime.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRuntime = createRuntime;
+exports.createCoreExtensions = createCoreExtensions;
+/**
+ * 运行时构建（自宿主 runtime 下沉，平台无关）。
+ *
+ * 平台定义列表（defs）由调用方传入：
+ * - koishi 兼容层传内置 BUILTIN_PLATFORMS（本地 definitions）
+ * - CLI 传 collectPlatformDefinitions()（已安装的 @sns-parse/platform-*）
+ * 默认扩展实现同样注入：koishi 传含 NSFW 的完整默认实现，CLI 传 createCoreExtensions()。
+ */
+const axios_1 = __importDefault(require("axios"));
+const https_proxy_agent_1 = require("https-proxy-agent");
+const host_1 = require("../host");
+const cache_1 = require("../utils/cache");
+const field_mapping_1 = require("../utils/field-mapping");
+const platform_config_1 = require("./platform-config");
+const gateway_1 = require("./gateway");
+const merge_1 = require("../utils/merge");
+const gif_1 = require("../utils/gif");
+const translate_1 = require("./translate");
+function createRuntime(source, config, opts = {}) {
+    const host = (0, host_1.createHost)(source);
+    const ctx = host.context;
+    const extensions = { ...(opts.defaultExtensions || {}), ...(host.extensions || {}) };
+    const dedupCache = new cache_1.SimpleLRUCache(1000, config.deduplicationInterval * 1000);
+    const cacheTTL = (config.cacheTTL || 600) * 1000;
+    const urlCacheLocal = new cache_1.SimpleLRUCache(500, cacheTTL);
+    const contentDedupCache = new cache_1.SimpleLRUCache(1000, config.deduplicationInterval * 1000);
+    const proxyConfig = config.proxy || {};
+    const customPlatforms = (config.customPlatforms || []).map((p) => ({
+        name: p.name,
+        apiUrl: p.apiUrl,
+        apiKey: p.apiKey || '',
+        authHeaderType: p.authHeaderType || 'Bearer',
+        customHeaderName: p.customHeaderName || 'X-API-Key',
+        fieldMapping: (0, field_mapping_1.parseFieldMapping)(p.fieldMapping),
+        proxy: p.proxy || null
+    }));
+    const defs = opts.defs || [];
+    const builtinRules = defs.flatMap(d => d.rules.map(pattern => ({ pattern, type: d.type })));
+    const customRules = (0, platform_config_1.buildCustomLinkRules)(config.customPlatforms || []);
+    const allRules = [...builtinRules, ...customRules];
+    const dedicatedApis = (0, gateway_1.dedicatedApisFrom)(defs);
+    const axiosConfig = {
+        timeout: config.timeout,
+        headers: {
+            'User-Agent': config.userAgent,
+            'Referer': 'https://www.baidu.com/',
+            'Content-Type': 'application/x-www-form-urlencoded'
+        }
+    };
+    if (proxyConfig.enabled && proxyConfig.host) {
+        // axios 内置 proxy 选项对 https 目标存在不做 CONNECT 隧道的经典缺陷，
+        // 改用 https-proxy-agent 显式代理（按请求生效，不污染全局 env）
+        const proxyUrl = `${proxyConfig.protocol || 'http'}://${proxyConfig.auth?.username ? `${encodeURIComponent(proxyConfig.auth.username)}:${encodeURIComponent(proxyConfig.auth.password || '')}@` : ''}${proxyConfig.host}:${proxyConfig.port || 7890}`;
+        const agent = new https_proxy_agent_1.HttpsProxyAgent(proxyUrl);
+        axiosConfig.httpAgent = agent;
+        axiosConfig.httpsAgent = agent;
+        axiosConfig.proxy = false;
+    }
+    const http = axios_1.default.create(axiosConfig);
+    return {
+        host,
+        ctx,
+        config,
+        http,
+        proxyConfig,
+        cacheTTL,
+        dedupCache,
+        urlCacheLocal,
+        contentDedupCache,
+        customPlatforms,
+        allRules,
+        dedicatedApis,
+        extensions,
+    };
+}
+/** core 自带扩展实现（无 NSFW：CLI / 嵌入式宿主用；koishi 层在其上叠加 NSFW） */
+function createCoreExtensions() {
+    return {
+        mergeImages: merge_1.mergeImages,
+        mp4ToGif: gif_1.mp4ToGif,
+        translate: translate_1.translateText,
+    };
+}

package/lib/engine/translate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 推文翻译：Google gtx 免费端点（无 Key、GET-only）。
+ *
+ * X 网页端的 Grok 翻译走私有通道（translations/show.json 已 404，GraphQL
+ * 仅返回 is_translatable 标志），无公开端点可调，故用通用翻译源兜底。
+ * 译文存入 ParsedData.translation，经 ${翻译} 模板变量展示，空值行自动隐藏。
+ */
+import type { ParserRuntime } from './runtime';
+import type { TranslateResult } from '../extensions';
+export type { TranslateResult };
+/** 判断是否需要跳过翻译（目标语系与推文语种相同 / 无语言内容） */
+export declare function shouldSkipTranslate(tweetLang: string | undefined, target: string): boolean;
+export declare function langName(code?: string): string;
+/** 翻译文本；失败返回 null（调用方保持无译文继续发送）。gtx 优先，MyMemory 兜底 */
+export declare function translateText(rt: ParserRuntime, text: string, target: string, sourceLang?: string): Promise<TranslateResult | null>;

package/lib/engine/translate.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldSkipTranslate = shouldSkipTranslate;
+exports.langName = langName;
+exports.translateText = translateText;
+const logger_1 = require("../logger");
+/** 判断是否需要跳过翻译（目标语系与推文语种相同 / 无语言内容） */
+function shouldSkipTranslate(tweetLang, target) {
+    if (!tweetLang)
+        return false;
+    const l = tweetLang.toLowerCase();
+    if (l === 'zxx' || l === 'und')
+        return l === 'zxx'; // zxx=无语言内容；und=未定则仍尝试
+    const t = target.toLowerCase();
+    if (t === 'zh')
+        return l === 'zh' || l.startsWith('zh-');
+    if (t === 'zh-tw')
+        return l === 'zh-tw' || l === 'zh-hant' || (l.startsWith('zh') && l !== 'zh-cn');
+    if (t === 'en')
+        return l === 'en';
+    return l === t;
+}
+/** 常见语种代码 → 中文名（未知代码原样展示） */
+const LANG_NAMES = {
+    fr: '法语', ja: '日语', ko: '韩语', en: '英语', zh: '中文', es: '西班牙语', pt: '葡萄牙语',
+    de: '德语', ru: '俄语', ar: '阿拉伯语', it: '意大利语', th: '泰语', vi: '越南语',
+    id: '印尼语', tr: '土耳其语', nl: '荷兰语', pl: '波兰语', hi: '印地语', uk: '乌克兰语',
+    sv: '瑞典语', no: '挪威语', fi: '芬兰语', da: '丹麦语', cs: '捷克语', ro: '罗马尼亚语',
+    hu: '匈牙利语', el: '希腊语', he: '希伯来语', fa: '波斯语', ur: '乌尔都语', ms: '马来语',
+    tl: '菲律宾语', ca: '加泰罗尼亚语', bg: '保加利亚语', hr: '克罗地亚语', sr: '塞尔维亚语',
+};
+function langName(code) {
+    if (!code)
+        return '';
+    const base = code.toLowerCase().split('-')[0];
+    if (base === 'und')
+        return '';
+    return LANG_NAMES[base] || code;
+}
+/** 翻译文本；失败返回 null（调用方保持无译文继续发送）。gtx 优先，MyMemory 兜底 */
+async function translateText(rt, text, target, sourceLang) {
+    if (!text)
+        return null;
+    const out = await viaGtx(rt, text, target);
+    if (out)
+        return { text: out, provider: 'Google' };
+    const backup = await viaMyMemory(rt, text, target, sourceLang);
+    if (backup)
+        return { text: backup, provider: 'MyMemory' };
+    return null;
+}
+/** Google gtx 免费端点（无 Key；sl=auto 自动检测源语种） */
+async function viaGtx(rt, text, target) {
+    const url = 'https://translate.googleapis.com/translate_a/single' +
+        `?client=gtx&sl=auto&dt=t&tl=${encodeURIComponent(target)}` +
+        `&q=${encodeURIComponent(text.slice(0, 2000))}`;
+    try {
+        const res = await rt.http.get(url, {
+            timeout: 15000,
+            headers: { 'User-Agent': rt.config.userAgent },
+        });
+        const data = res.data;
+        // gtx 响应形如 [[["译文","原文",null,null,10]],null,"fr",...]
+        if (Array.isArray(data?.[0])) {
+            const out = data[0].map((seg) => (typeof seg?.[0] === 'string' ? seg[0] : '')).join('').trim();
+            if (out)
+                return out;
+        }
+        (0, logger_1.debugLog)('gtx 翻译响应结构异常，尝试备用通道');
+        return null;
+    }
+    catch (e) {
+        (0, logger_1.debugLog)(`gtx 翻译失败：${e?.message || e}`);
+        return null;
+    }
+}
+/** MyMemory 备用（免费无 Key；需已知源语种，不支持 auto） */
+async function viaMyMemory(rt, text, target, sourceLang) {
+    const sl = normalizeLang(sourceLang);
+    if (!sl)
+        return null;
+    const tl = target.toLowerCase();
+    const url = 'https://api.mymemory.translated.net/get' +
+        `?q=${encodeURIComponent(text.slice(0, 500))}&langpair=${encodeURIComponent(sl + '|' + tl)}`;
+    try {
+        const res = await rt.http.get(url, { timeout: 15000, headers: { 'User-Agent': rt.config.userAgent } });
+        const out = res.data?.responseData?.translatedText;
+        if (typeof out === 'string' && out.trim() && !/^MYMEMORY WARNING/i.test(out))
+            return out.trim();
+        (0, logger_1.debugLog)('MyMemory 翻译响应异常，放弃译文');
+        return null;
+    }
+    catch (e) {
+        logger_1.logger.info(`推文翻译失败（跳过译文继续发送）：${e?.message || e}`);
+        return null;
+    }
+}
+function normalizeLang(lang) {
+    if (!lang)
+        return null;
+    const l = lang.toLowerCase();
+    if (l === 'und' || l === 'zxx')
+        return null;
+    if (l.startsWith('zh'))
+        return 'zh-CN';
+    return l.split('-')[0];
+}

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

@@ -0,0 +1,102 @@
+import type { AxiosInstance } from 'axios';
+import type { ParsedData } from '../types';
+/** GraphQL GET 器：可注入（生产用 tlsGet，测试用 mock） */
+export type GraphqlGetter = (url: string, opts: {
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    timeout?: number;
+}) => Promise<{
+    status: number;
+    data: any;
+}>;
+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;
+}
+/**
+ * X 原生 Grok 翻译（与网页"翻译推文"同源）。
+ * 需登录态；网页抓包实证：grok 特性开关 + client-language 头即可，无需
+ * 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>;