stock-sdk 1.9.2 → 1.10.0

package/dist/index.d.cts

@@ -139,6 +139,17 @@ interface CircuitBreakerOptions {
     onStateChange?: (from: CircuitState, to: CircuitState) => void;
 }
 
+interface HostHealthState {
+    host: string;
+    failureCount: number;
+    successCount: number;
+    cooldownUntil: number;
+    lastFailureAt: number;
+    lastErrorCode?: SdkErrorCode;
+}
+interface HostHealthStats extends HostHealthState {
+}
+
 /**
  * 请求客户端配置选项
  */
@@ -162,6 +173,64 @@ interface RequestClientOptions {
      */
     providerPolicies?: Partial<Record<ProviderName, ProviderRequestPolicy>>;
 }
+/**
+ * GET 请求选项
+ */
+interface GetOptions {
+    responseType?: 'text' | 'json' | 'arraybuffer';
+    provider?: ProviderName;
+}
+declare class RequestClient {
+    private readonly baseUrl;
+    private readonly defaultPolicy;
+    private readonly providerPolicies;
+    private readonly runtimeStates;
+    private readonly fallbackManager;
+    constructor(options?: RequestClientOptions);
+    /**
+     * 获取 provider 运行时状态，按需初始化限流器和熔断器。
+     */
+    private getProviderState;
+    /**
+     * 获取默认超时时间
+     */
+    getTimeout(): number;
+    /**
+     * 获取 host 健康状态
+     */
+    getHostHealth(provider?: ProviderName): HostHealthStats[];
+    /**
+     * 计算指数退避延迟时间
+     */
+    private calculateDelay;
+    /**
+     * 休眠指定毫秒
+     */
+    private sleep;
+    /**
+     * 判断是否应该重试
+     */
+    private shouldRetry;
+    /**
+     * 单 host 带重试的请求执行器
+     */
+    private executeWithRetry;
+    /**
+     * 执行单次 HTTP 请求
+     */
+    private performRequest;
+    /**
+     * 发送 GET 请求（带自动重试、限流、熔断和 fallback）
+     */
+    get<T = string>(url: string, options?: GetOptions): Promise<T>;
+    /**
+     * 腾讯财经专用请求（GBK 解码，带自动重试）
+     */
+    getTencentQuote(params: string): Promise<{
+        key: string;
+        fields: string[];
+    }[]>;
+}
 
 /**
  * 响应解析器
@@ -233,6 +302,93 @@ interface JsonpOptions {
  */
 declare function jsonpRequest<T = unknown>(url: string, options?: JsonpOptions): Promise<T>;
 
+/**
+ * JS 变量声明文件双端解析工具
+ *
+ * 解决：东方财富等数据源返回的不是 JSONP 而是 `var X = ...; var Y = ...;` 形式
+ * 的 JS 变量声明文件（如 pingzhongdata、funddataIndex_Interface），且响应通常没有
+ * CORS 头，浏览器侧无法用 fetch 直接拿到。本工具双端实现：
+ *
+ * - 浏览器端：动态 `<script>` 注入，从 `window` 读全局变量，读完立即删除
+ * - Node.js 端：fetch 文本 + 括号配对扫描 + `JSON.parse`；若传入 `client`，走
+ *   `RequestClient` 享受 SDK 重试 / 限流 / 熔断 / fallback host 治理
+ *
+ * 仅支持值是合法 JSON 字面量的变量（数组 / 对象 / 数字 / 字符串 / 布尔 / null）。
+ *
+ * 浏览器端并发安全：内部用 `withScriptMutex` 做全局串行化（key 为
+ * `BROWSER_JSVARS_MUTEX_KEY`），任意两个浏览器 fetchJsVars 调用都按提交顺序
+ * 串行执行，避免不同接口的全局变量名集合交集（如 pingzhongdata 系列共享
+ * `fS_code` / `fS_name`）导致的相互覆盖。
+ *
+ * ⚠️ 浏览器端限制：
+ * - 通过 `<script>` 注入加载，`options.client` / `options.headers` 都不会生效；
+ *   SDK 治理（retry / rateLimit / circuitBreaker / providerPolicies）仅 Node 端生效
+ * - 数据源若把字面量改成 JS 表达式（如带函数引用、未引号 key），解析失败的字段将
+ *   返回 `undefined`，但不会抛错
+ */
+
+/**
+ * 浏览器端所有 fetchJsVars 调用共享的 mutex 键。
+ *
+ * 用全局键（而非按变量名集合算 key）的原因：不同接口的变量名集合常有交集
+ * （如 pingzhongdata 的 `fS_code` / `fS_name` 同时被多个接口写入）。按集合
+ * 分组的 key 会让"集合不同但有交集"的并发请求互相覆盖全局变量。
+ *
+ * 代价：浏览器端任意两个 fetchJsVars 调用都串行；收益：彻底消除变量交集漏洞。
+ *
+ * Node 端不走 mutex，不受影响。
+ */
+declare const BROWSER_JSVARS_MUTEX_KEY = "jsVars";
+interface FetchJsVarsOptions {
+    /** 超时毫秒数，默认 15000（仅在裸 fetch 路径生效；走 client 时由 client 治理） */
+    timeout?: number;
+    /** 额外的 fetch headers（仅 Node 端裸 fetch 路径生效；client 路径请通过 client 配置） */
+    headers?: Record<string, string>;
+    /**
+     * 可选的 SDK 请求客户端。
+     * - 传入：Node 端走 `client.get<string>(url, { responseType: 'text' })`，享受 SDK 重试 /
+     *   限流 / 熔断 / fallback host / providerPolicies 全套治理
+     * - 不传：Node 端用裸 `fetch`（兼容直接用工具的高级用户）
+     * - 浏览器端始终走 `<script>` 注入，此参数不生效
+     */
+    client?: RequestClient;
+}
+/**
+ * 从一个 JS 变量声明文件中提取指定变量的值。
+ *
+ * @param url 目标 URL
+ * @param varNames 要提取的变量名列表
+ * @param options 选项（timeout / headers）
+ * @returns 一个对象；键是变量名，值是解析后的 JS 值；变量不存在或解析失败时键不出现
+ */
+declare function fetchJsVars<T extends object>(url: string, varNames: (keyof T & string)[], options?: FetchJsVarsOptions): Promise<Partial<T>>;
+/**
+ * 从给定 JS 文本中提取多个变量（暴露用于单测 / 高级用户）。
+ */
+declare function parseJsVars<T extends object>(text: string, varNames: (keyof T & string)[]): Partial<T>;
+
+/**
+ * 浏览器全局名级互斥锁
+ *
+ * 用于"通过 `<script>` 注入读固定全局变量 / 固定 callback 名"这种本质上无法并发的
+ * 接口（典型：东方财富 pingzhongdata.js 的固定 `Data_netWorthTrend` 等变量，
+ * 天天基金 fundgz 的固定 `jsonpgz` callback）。
+ *
+ * 工作方式：每个 key 维护一个 promise 队列，同 key 的请求串行执行；不同 key
+ * 的请求互不阻塞。前一次任务无论成功失败都会释放队列，不阻断后续。
+ *
+ * 注意：这是浏览器端的并发安全兜底。Node 端不存在全局污染问题（用 fetch + 文本
+ * 解析），不需要 mutex。
+ */
+/**
+ * 在 `key` 对应的串行队列中执行 `fn`。
+ *
+ * @param key 互斥分组键（通常是固定全局变量名集合或 callback 名）
+ * @param fn 需要串行执行的异步任务
+ * @returns `fn` 的返回值（透传 resolve / reject）
+ */
+declare function withScriptMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;
+
 /**
  * 时间元信息工具
  *
@@ -258,6 +414,59 @@ declare const MARKET_TZ: {
     readonly US: "America/New_York";
 };
 type MarketTz = (typeof MARKET_TZ)[keyof typeof MARKET_TZ];
+/**
+ * 时间元信息:与原始 `time`/`date` 字符串配套使用。
+ */
+interface TimeMeta {
+    /** UTC unix 毫秒时间戳。原始字符串无法解析时为 `NaN`。 */
+    timestamp: number;
+    /** 原始字符串对应的市场时区 (IANA name)。 */
+    tz: MarketTz;
+}
+/**
+ * 解析"市场本地时间字符串"为 UTC unix ms。失败返回 `NaN`。
+ *
+ * 支持的格式:
+ * - `'YYYY-MM-DD HH:mm:ss'` / `'YYYY-MM-DDTHH:mm:ss'`
+ * - `'YYYY-MM-DD HH:mm'`
+ * - `'YYYY-MM-DD'` (按当日 00:00 计)
+ * - `'yyyyMMddHHmmss'` (腾讯接口 14 位无分隔)
+ * - `'yyyyMMdd'` (8 位日期)
+ *
+ * @param local 市场本地时间字符串
+ * @param tz    市场时区 (使用 `MARKET_TZ`)
+ */
+declare function parseMarketTime(local: string, tz: MarketTz): number;
+/**
+ * 构造 `TimeMeta`。原始字符串无法解析时 `timestamp` 为 `NaN`。
+ *
+ * @param local 市场本地时间字符串
+ * @param tz    市场时区
+ */
+declare function buildTimeMeta(local: string, tz: MarketTz): TimeMeta;
+/**
+ * 将"基础日期 (YYYY-MM-DD) + HH:mm 时间片"组合后构造 `TimeMeta`。
+ *
+ * 用于"当日分时"等只返回 `HH:mm` 的接口。
+ *
+ * @param baseDate 形如 `'2024-05-12'` 的日期字符串
+ * @param hhmm     形如 `'09:30'` 或 `'09:30:00'` 的时间片
+ * @param tz       市场时区
+ */
+declare function buildTimeMetaFromDateAndTime(baseDate: string, hhmm: string, tz: MarketTz): TimeMeta;
+/**
+ * 把 UTC 毫秒时间戳格式化为指定时区的 `YYYY-MM-DD HH:mm` 本地壁钟字符串。
+ *
+ * 与 {@link parseMarketTime} 互逆：`formatInTz(parseMarketTime(s, tz), tz) === s`
+ * （只要 `s` 是 `YYYY-MM-DD HH:mm` 格式）。
+ *
+ * 用途：当上游接口返回的时间字符串使用 A 处时区表示，但业务需要在 B 处时区显示时
+ * （典型：东方财富的美股分时返回北京时间字符串，但用户需要美东时间），先用
+ * `parseMarketTime(s, MARKET_TZ.CN)` 拿到正确 epoch，再用本函数转成目标时区字符串。
+ *
+ * 使用 `Intl.DateTimeFormat` 处理夏令时；epoch 为 `NaN` 时返回空串。
+ */
+declare function formatInTz(epoch: number, tz: MarketTz): string;
 
 /**
  * A 股 / 指数 全量行情
@@ -711,6 +920,48 @@ interface USHistoryKline extends ForeignHistoryKlineBase {
  * 老代码无需立即迁移;新代码请直接用具体类型以获得更好的类型推断。
  */
 type HKUSHistoryKline = HKHistoryKline | USHistoryKline;
+/**
+ * 港股分钟 K 线（5/15/30/60；v1.10.0+）
+ *
+ * 字段与 A 股 {@link MinuteKline} 同结构，额外携带 `currency` / `code`。
+ * `tz` 固定为 `'Asia/Hong_Kong'`。
+ */
+interface HKMinuteKline extends Omit<MinuteKline, 'tz'> {
+    tz: MarketTz;
+    currency: 'HKD';
+    code: string;
+}
+/**
+ * 港股当日分时（1 分钟；v1.10.0+）
+ *
+ * `tz` 固定为 `'Asia/Hong_Kong'`。
+ */
+interface HKMinuteTimeline extends Omit<MinuteTimeline, 'tz'> {
+    tz: MarketTz;
+    currency: 'HKD';
+    code: string;
+}
+/**
+ * 美股分钟 K 线（5/15/30/60；v1.10.0+）
+ *
+ * `tz` 固定为 `'America/New_York'`（含夏令时切换）。
+ * 不含盘前 / 盘后数据，仅常规交易时段。
+ */
+interface USMinuteKline extends Omit<MinuteKline, 'tz'> {
+    tz: MarketTz;
+    currency: 'USD';
+    code: string;
+}
+/**
+ * 美股当日分时（1 分钟；v1.10.0+）
+ *
+ * `tz` 固定为 `'America/New_York'`。
+ */
+interface USMinuteTimeline extends Omit<MinuteTimeline, 'tz'> {
+    tz: MarketTz;
+    currency: 'USD';
+    code: string;
+}
 
 /**
  * 行业板块列表项
@@ -1777,6 +2028,145 @@ interface MarginTargetItem {
     loanRepayVolume: number | null;
 }
 
+/**
+ * 公募基金扩展数据类型
+ *
+ * 对应数据源：天天基金 / 东方财富的基金数据频道
+ * （https://fund.eastmoney.com/data/fundfenhong.html 等）。
+ */
+/** 分红查询排序字段（与东方财富接口 `rank` 参数一一对应） */
+type FundDividendRank = 'BZDM' | 'ABBNAME' | 'DJR' | 'FSRQ' | 'FHFCZ' | 'FFR';
+/** 通用排序方向（升序 / 降序） */
+type FundSortDirection = 'asc' | 'desc';
+/** 基金分红查询选项 */
+interface FundDividendListOptions {
+    /** 查询年份；默认当前年（Asia/Shanghai） */
+    year?: number | string;
+    /**
+     * 页码：从 1 开始；默认 `1`。
+     * 设为 `'all'` 时自动翻完该年份所有页面并聚合结果。
+     */
+    page?: number | 'all';
+    /**
+     * 基金类型筛选，空 / undefined 表示全部。
+     * 例如 `'股票型'`、`'指数型-股票'`、`'混合型-偏股'`、`'REITs'` 等
+     * （字符串与东方财富接口 `ftype` 参数原样对应）。
+     */
+    fundType?: string;
+    /** 排序字段，默认 `'FSRQ'`（除息日期） */
+    rank?: FundDividendRank;
+    /** 排序方向，默认 `'desc'` */
+    sort?: FundSortDirection;
+    /**
+     * 按基金代码过滤（客户端过滤，因为接口本身不支持按代码精确查）。
+     * 一般搭配 `page: 'all'` 使用，否则可能因目标记录不在当前页而无结果。
+     */
+    code?: string;
+}
+/** 一条基金分红记录 */
+interface FundDividend {
+    /** 基金代码 */
+    code: string;
+    /** 基金简称 */
+    name: string;
+    /** 权益登记日（`YYYY-MM-DD`），无则 `null` */
+    equityRecordDate: string | null;
+    /** 除息日期（`YYYY-MM-DD`），无则 `null` */
+    exDividendDate: string | null;
+    /** 分红金额（元/份），无则 `null` */
+    dividendPerShare: number | null;
+    /** 分红发放日（`YYYY-MM-DD`），无则 `null` */
+    payDate: string | null;
+    /**
+     * 原始字段数组（含 7 项）：
+     * `[code, name, 权益登记日, 除息日, 分红元/份, 发放日, 类型代码]`
+     */
+    raw: string[];
+}
+/** 基金分红查询结果 */
+interface FundDividendListResult {
+    /** 当前页（或聚合后）的分红记录 */
+    items: FundDividend[];
+    /** 数据源汇报的总页数 */
+    totalPages: number;
+    /** 数据源汇报的每页条数 */
+    pageSize: number;
+    /** 当前页码；`page: 'all'` 模式下为 `-1` 表示已聚合 */
+    currentPage: number;
+}
+/** 单条历史净值点 */
+interface FundNavPoint {
+    /** 净值日期 `YYYY-MM-DD`（与时间戳的 UTC 日期一致，对应 A 股交易日） */
+    date: string;
+    /** 净值日期对应的毫秒时间戳（数据源原值，UTC 当日 00:00） */
+    timestamp: number;
+    /** 单位净值 */
+    nav: number;
+    /** 累计净值；与单位净值数组按 timestamp 对齐，无法对齐时为 `null` */
+    accNav: number | null;
+    /** 日增长率（%）；无值时为 `null` */
+    dailyReturn: number | null;
+    /** 每万份收益（货币 / 短债基金有意义，其余通常为空串） */
+    unitMoney: string;
+}
+/** 基金历史净值查询结果 */
+interface FundNavHistory {
+    /** 基金代码（来自 pingzhongdata 的 `fS_code`，若缺失则回填入参） */
+    code: string;
+    /** 基金简称（来自 pingzhongdata 的 `fS_name`，无则 `null`） */
+    name: string | null;
+    /** 历史净值序列；按日期升序（与数据源一致） */
+    items: FundNavPoint[];
+}
+/**
+ * 基金当日实时估值（来自天天基金 fundgz 接口）。
+ *
+ * 含两类净值：
+ * - `nav` / `navDate`：最新已结算的单位净值（T-1 或当日盘后）
+ * - `estimatedNav` / `estimatedChangePercent` / `estimateTime`：盘中实时估值
+ */
+interface FundEstimate {
+    /** 基金代码 */
+    code: string;
+    /** 基金简称 */
+    name: string | null;
+    /** 最新已结算单位净值的日期 `YYYY-MM-DD`，无则 `null` */
+    navDate: string | null;
+    /** 最新已结算单位净值，无则 `null` */
+    nav: number | null;
+    /** 当日实时估值（盘中刷新），无则 `null`（如非交易日、QDII 等） */
+    estimatedNav: number | null;
+    /** 估算涨跌幅 `%`，无则 `null` */
+    estimatedChangePercent: number | null;
+    /** 估算时间原始字符串（如 `"2026-05-26 15:00"`，A 股时区），无则 `null` */
+    estimateTime: string | null;
+}
+/** 单条同类排名点（与 `Data_rateInSimilarType` 一一对应） */
+interface FundRankPoint {
+    /** 报告日期 `YYYY-MM-DD` */
+    date: string;
+    /** 报告日期对应的毫秒时间戳（数据源原值） */
+    timestamp: number;
+    /** 同类近三月排名（数字越小越靠前），无值时为 `null` */
+    rank: number | null;
+    /** 同类基金总数，无值时为 `null` */
+    total: number | null;
+    /**
+     * 同类近三月排名百分位（%，越小越好），按 timestamp 与 rank 对齐；
+     * 无对应数据时为 `null`
+     */
+    percentile: number | null;
+}
+/** 基金同类排名走势查询结果 */
+interface FundRankHistory {
+    /** 基金代码（来自 pingzhongdata 的 `fS_code`，若缺失则回填入参） */
+    code: string;
+    /** 基金简称（来自 pingzhongdata 的 `fS_name`，无则 `null`） */
+    name: string | null;
+    /** 排名走势序列；按日期升序 */
+    items: FundRankPoint[];
+}
+
 /**
  * 腾讯财经 - 批量操作
  */
@@ -1935,6 +2325,24 @@ interface HistoryKlineRequestOptions {
 
 interface HKKlineOptions extends HistoryKlineRequestOptions {
 }
+interface HKMinuteKlineOptions {
+    /** K 线周期 @default '1' */
+    period?: '1' | '5' | '15' | '30' | '60';
+    /**
+     * 复权类型（仅 5/15/30/60 分钟有效；1 分钟分时不支持复权）
+     * @default 'qfq'
+     */
+    adjust?: '' | 'qfq' | 'hfq';
+    /** 开始时间 `YYYY-MM-DD HH:mm`（港股本地时区 `Asia/Hong_Kong`） */
+    startDate?: string;
+    /** 结束时间 `YYYY-MM-DD HH:mm`（港股本地时区） */
+    endDate?: string;
+    /**
+     * 仅 `period='1'` 生效：返回最近 N 个交易日的分时。
+     * 默认 `1`（当日分时）。可设为 `5` 拿近 5 日分时。
+     */
+    ndays?: number;
+}
 
 /**
  * 东方财富 - 美股 K 线
@@ -1942,6 +2350,24 @@ interface HKKlineOptions extends HistoryKlineRequestOptions {
 
 interface USKlineOptions extends HistoryKlineRequestOptions {
 }
+interface USMinuteKlineOptions {
+    /** K 线周期 @default '1' */
+    period?: '1' | '5' | '15' | '30' | '60';
+    /**
+     * 复权类型（仅 5/15/30/60 分钟有效；1 分钟分时不支持复权）
+     * @default 'qfq'
+     */
+    adjust?: '' | 'qfq' | 'hfq';
+    /** 开始时间 `YYYY-MM-DD HH:mm`（美东时区 `America/New_York`，自动 DST） */
+    startDate?: string;
+    /** 结束时间 `YYYY-MM-DD HH:mm`（美东时区） */
+    endDate?: string;
+    /**
+     * 仅 `period='1'` 生效：返回最近 N 个交易日的分时。
+     * 默认 `1`（当日分时）。可设为 `5` 拿近 5 日分时。
+     */
+    ndays?: number;
+}
 
 /**
  * 东方财富 - 板块通用逻辑
@@ -2719,6 +3145,38 @@ declare global {
     }
 }
 
+declare abstract class BaseService {
+    protected readonly client: RequestClient;
+    constructor(client: RequestClient);
+}
+
+declare class QuoteService extends BaseService {
+    constructor(client: RequestClient);
+    getFullQuotes(codes: string[]): Promise<FullQuote[]>;
+    getSimpleQuotes(codes: string[]): Promise<SimpleQuote[]>;
+    getHKQuotes(codes: string[]): Promise<HKQuote[]>;
+    getUSQuotes(codes: string[]): Promise<USQuote[]>;
+    getFundQuotes(codes: string[]): Promise<FundQuote[]>;
+    getFundFlow(codes: string[]): Promise<FundFlow[]>;
+    getPanelLargeOrder(codes: string[]): Promise<PanelLargeOrder[]>;
+    getTodayTimeline(code: string): Promise<TodayTimelineResponse>;
+    search(keyword: string): Promise<SearchResult[]>;
+    getAShareCodeList(options?: GetAShareCodeListOptions | boolean): Promise<string[]>;
+    getUSCodeList(options?: GetUSCodeListOptions | boolean): Promise<string[]>;
+    getHKCodeList(): Promise<string[]>;
+    getFundCodeList(): Promise<string[]>;
+    getAllAShareQuotes(options?: GetAllAShareQuotesOptions): Promise<FullQuote[]>;
+    getAllHKShareQuotes(options?: GetAllAShareQuotesOptions): Promise<HKQuote[]>;
+    getAllUSShareQuotes(options?: GetAllUSQuotesOptions): Promise<USQuote[]>;
+    getAllQuotesByCodes(codes: string[], options?: GetAllAShareQuotesOptions): Promise<FullQuote[]>;
+    batchRaw(params: string): Promise<{
+        key: string;
+        fields: string[];
+    }[]>;
+    getTradingCalendar(): Promise<string[]>;
+    getDividendDetail(symbol: string): Promise<DividendDetail[]>;
+}
+
 type MarketType = 'A' | 'HK' | 'US';
 /**
  * `getKlineWithIndicators` 的请求参数
@@ -2773,6 +3231,65 @@ interface KlineWithIndicatorsOptions {
 type MarketStatus = 'pre_market' | 'open' | 'lunch_break' | 'after_hours' | 'closed';
 /** 支持的市场枚举,用于 `getMarketStatus`。 */
 type SupportedMarket = 'A' | 'HK' | 'US';
+declare class TradingCalendarService {
+    private readonly quoteService;
+    constructor(quoteService: QuoteService);
+    /**
+     * 判断给定日期是否为 A 股交易日。
+     *
+     * 数据源:`getTradingCalendar()` (腾讯接口,带 12 小时缓存)。
+     * 因此第一次调用会拉取全量交易日列表,后续命中缓存。
+     *
+     * @param date 不传则取"现在 `Asia/Shanghai` 的当日"。可传 `'YYYY-MM-DD'` /
+     *             `'YYYYMMDD'` / `Date` 对象。
+     * @returns `true` 表示是交易日;`false` 表示节假日 / 周末。
+     */
+    isTradingDay(date?: string | Date): Promise<boolean>;
+    /**
+     * 返回 A 股下一个交易日 (`'YYYY-MM-DD'`)。
+     *
+     * - 如果 `date` 本身是交易日,返回它**之后**的下一个交易日
+     * - 如果 `date` 是节假日,返回大于它的第一个交易日
+     * - 如果在已知日历范围之外,抛 `RangeError`
+     *
+     * @param date 不传则取"现在 `Asia/Shanghai` 的当日"
+     */
+    nextTradingDay(date?: string | Date): Promise<string>;
+    /**
+     * 返回 A 股上一个交易日 (`'YYYY-MM-DD'`)。
+     *
+     * - 如果 `date` 本身是交易日,返回它**之前**的上一个交易日
+     * - 如果 `date` 是节假日,返回小于它的最后一个交易日
+     * - 如果在已知日历范围之外,抛 `RangeError`
+     *
+     * @param date 不传则取"现在 `Asia/Shanghai` 的当日"
+     */
+    prevTradingDay(date?: string | Date): Promise<string>;
+    /**
+     * 返回当前市场状态 (同步,不发请求)。
+     *
+     * - **A 股**:仅按交易时段判断,**不识别法定假日**(SDK 不会为此发请求)。
+     *   如需精确判断"今天是否真的是交易日",请用 `await isTradingDay()`。
+     *   返回 `'closed'` 时表示"周末或非交易时段",可能是节假日 / 凌晨 / 深夜。
+     * - **港股 / 美股**:同样按"周一-周五 + 已知时段"判断,不识别假日。
+     *
+     * @param market `'A'`(默认) / `'HK'` / `'US'`
+     * @param now    用于测试注入"当前时间";生产代码不需要传
+     */
+    getMarketStatus(market?: SupportedMarket, now?: Date): MarketStatus;
+}
+
+declare class FundService extends BaseService {
+    constructor(client: RequestClient);
+    /** 获取基金分红明细（全市场，按年份分页） */
+    getFundDividendList(options?: FundDividendListOptions): Promise<FundDividendListResult>;
+    /** 获取基金历史净值（单位 + 累计，全历史一次返回） */
+    getFundNavHistory(code: string): Promise<FundNavHistory>;
+    /** 获取基金当日实时估值（含 T-1 单位净值 + 盘中估算） */
+    getFundEstimate(code: string): Promise<FundEstimate>;
+    /** 获取基金同类排名走势（每日近三月排名 + 百分位） */
+    getFundRankHistory(code: string): Promise<FundRankHistory>;
+}
 
 declare class StockSDK {
     private readonly client;
@@ -2788,6 +3305,7 @@ declare class StockSDK {
     private readonly dragonTigerService;
     private readonly dataService;
     private readonly tradingCalendarService;
+    private readonly fundService;
     /**
      * 创建 Stock SDK 实例。
      * 旧的全局 `timeout` / `retry` / `rateLimit` / `circuitBreaker` 配置继续有效，
@@ -2806,12 +3324,12 @@ declare class StockSDK {
     getSimpleQuotes(codes: string[]): Promise<SimpleQuote[]>;
     /**
      * 获取港股行情
-     * @param codes 港股代码数组（如 `['hk00700']`）
+     * @param codes 港股代码数组（5 位数字，无需 `hk` 前缀，如 `['00700', '09988']`）
      */
     getHKQuotes(codes: string[]): Promise<HKQuote[]>;
     /**
      * 获取美股行情
-     * @param codes 美股代码数组（如 `['usAAPL']`）
+     * @param codes 美股代码数组（无需 `us` 前缀，如 `['AAPL', 'BABA']`）
      */
     getUSQuotes(codes: string[]): Promise<USQuote[]>;
     /**
@@ -2921,6 +3439,17 @@ declare class StockSDK {
      * @param options K 线参数
      */
     getHKHistoryKline(symbol: string, options?: HKKlineOptions): Promise<HKHistoryKline[]>;
+    /**
+     * 获取港股分钟 K 线（5/15/30/60 分钟）或当日分时（1 分钟）。
+     *
+     * `options.period='1'` 时走 `trends2/get`，返回 `HKMinuteTimeline[]`；
+     * `options.period='5'|'15'|'30'|'60'` 时走 `kline/get`，返回 `HKMinuteKline[]`。
+     *
+     * @param symbol 港股代码，纯数字或带 `hk` 前缀均可（如 `'00700'`、`'hk00700'`）
+     * @param options 周期 / 复权 / 起止时间
+     * @since v1.10.0
+     */
+    getHKMinuteKline(symbol: string, options?: HKMinuteKlineOptions): Promise<HKMinuteTimeline[] | HKMinuteKline[]>;
     /**
      * 获取美股历史 K 线。
      *
@@ -2931,6 +3460,16 @@ declare class StockSDK {
      * @param options K 线参数
      */
     getUSHistoryKline(symbol: string, options?: USKlineOptions): Promise<USHistoryKline[]>;
+    /**
+     * 获取美股分钟 K 线（5/15/30/60 分钟）或当日分时（1 分钟）。
+     *
+     * 不含盘前 / 盘后数据，仅常规交易时段。
+     *
+     * @param symbol 美股代码，格式 `{market}.{ticker}`（如 `'105.AAPL'`、`'106.BABA'`）
+     * @param options 周期 / 复权 / 起止时间
+     * @since v1.10.0
+     */
+    getUSMinuteKline(symbol: string, options?: USMinuteKlineOptions): Promise<USMinuteTimeline[] | USMinuteKline[]>;
     /**
      * 模糊搜索股票/指数/基金等
      * @param keyword 关键词（代码 / 名称 / 拼音）
@@ -3244,6 +3783,48 @@ declare class StockSDK {
      * @param date 指定交易日 YYYY-MM-DD（默认服务端最新交易日）
      */
     getMarginTargetList(date?: string): Promise<MarginTargetItem[]>;
+    /**
+     * 获取基金分红明细列表（来自东方财富 / 天天基金分红送配频道）。
+     *
+     * 接口本身只支持「年份 + 全市场 + 翻页」查询，不支持服务端按代码精确查；
+     * 要拿单只基金完整分红记录，请同时设置 `page: 'all'` 与 `code`。
+     *
+     * @param options 查询选项；默认拉当前年第 1 页、按除息日倒序
+     */
+    getFundDividendList(options?: FundDividendListOptions): Promise<FundDividendListResult>;
+    /**
+     * 获取基金历史净值（单位净值 + 累计净值，全历史一次返回）。
+     *
+     * 数据源：`fund.eastmoney.com/pingzhongdata/{code}.js`
+     * 一次请求即可拿到该基金从成立日到最新交易日的全部净值（数千条）。
+     * 开放式 / ETF / LOF / 货币 / QDII 均通用。
+     *
+     * 注意：响应体较大（约 600KB / gzip 后约 120KB），建议在应用层做缓存。
+     *
+     * @param code 基金代码，如 `'110011'`
+     */
+    getFundNavHistory(code: string): Promise<FundNavHistory>;
+    /**
+     * 获取基金当日实时估值（来自天天基金 fundgz 接口）。
+     *
+     * 同时返回最新已结算的单位净值（`nav` / `navDate`）和盘中估算
+     * （`estimatedNav` / `estimatedChangePercent` / `estimateTime`），
+     * 方便前端做"当日实时表现 vs 上一收盘"对比。
+     *
+     * QDII / 非交易日 / 部分小众基金的盘中估算字段可能为空，将返回 `null`。
+     *
+     * @param code 基金代码（纯数字，如 `'005827'`）
+     */
+    getFundEstimate(code: string): Promise<FundEstimate>;
+    /**
+     * 获取基金同类排名走势（每日近三月排名 + 百分位）。
+     *
+     * 数据源与 `getFundNavHistory` 相同（`pingzhongdata/{code}.js`），
+     * 适合做"该基金在同类基金里的相对表现"折线图。
+     *
+     * @param code 基金代码
+     */
+    getFundRankHistory(code: string): Promise<FundRankHistory>;
 }
 
 /**
@@ -3253,4 +3834,4 @@ declare class StockSDK {
  */
 declare function generateSearchExternalLinks(result: SearchResult): ExternalLink[];
 
-export { type AShareMarket, type ATROptions, type BIASOptions, type BOLLOptions, type BlockTradeDailyStatItem, type BlockTradeDateOptions, type BlockTradeDetailItem, type BlockTradeMarketStatItem, type BoardChangeItem, type CCIOptions, type CFFEXOptionQuote, type CFFEXOptionQuotesOptions, type ComexInventory, type ComexInventoryOptions, type ConceptBoard, type ConceptBoardConstituent, type ConceptBoardKline, type ConceptBoardKlineOptions, type ConceptBoardMinuteKline, type ConceptBoardMinuteKlineOptions, type ConceptBoardMinuteTimeline, type ConceptBoardSpot, type DMIOptions$1 as DMIOptions, type DMIResult$1 as DMIResult, type DatacenterQuery, type DatacenterResult, type DividendDetail, type DragonTigerBranchItem, type DragonTigerDateOptions, type DragonTigerDetailItem, type DragonTigerInstitutionItem, type DragonTigerPeriod, type DragonTigerSeatItem, type DragonTigerStockStatItem, type ETFOptionCate, type ETFOptionExpireDay, type ETFOptionMonth, type ExternalLink, type FullQuote, type FundFlow, type FundFlowOptions, type FundFlowRankItem, type FundFlowRankOptions, type FundQuote, type FuturesExchange, type FuturesInventory, type FuturesInventoryOptions, type FuturesInventorySymbol, type FuturesKline, type FuturesKlineOptions, type GetAShareCodeListOptions, type GetAllAShareQuotesOptions, type GlobalFuturesKlineOptions, type GlobalFuturesQuote, type GlobalFuturesSpotOptions, type HKHistoryKline, type HKQuote, type HKUSHistoryKline, type HistoryKline, HttpError, INDICATOR_REGISTRY, type IndexOptionProduct, type IndicatorKey, type IndicatorOptions, type IndustryBoard, type IndustryBoardConstituent, type IndustryBoardKline, type IndustryBoardKlineOptions, type IndustryBoardMinuteKline, type IndustryBoardMinuteKlineOptions, type IndustryBoardMinuteTimeline, type IndustryBoardSpot, type JsonpOptions, type KCOptions$1 as KCOptions, type KCResult$1 as KCResult, type KDJOptions, type KlineWithIndicators, type MACDOptions, type MAOptions, type MarginAccountItem, type MarginTargetItem, type MarketFundFlow, type MarketType, type MinuteKline, type MinuteTimeline, type NorthboundDirection, type NorthboundFlowSummary, type NorthboundHistoryItem, type NorthboundHistoryOptions, type NorthboundHoldingRankItem, type NorthboundHoldingRankOptions, type NorthboundIndividualItem, type NorthboundMarket, type NorthboundMinuteItem, type NorthboundRankPeriod, type OBVOptions$1 as OBVOptions, type OBVResult$1 as OBVResult, type OptionKline, type OptionLHBItem, type OptionMinute, type OptionTQuote, type OptionTQuoteResult, type PanelLargeOrder, type ProviderName, type ProviderRequestPolicy, type ROCOptions$1 as ROCOptions, type ROCResult$1 as ROCResult, type RSIOptions, type RequestClientOptions, type RequestError, type RetryOptions, type SAROptions$1 as SAROptions, type SARResult$1 as SARResult, SdkError, type SearchResult, type SearchResultType, type SectorFundFlowItem, type SimpleQuote, type StockChangeItem, type StockChangeType, type StockFundFlowDaily, StockSDK, type TodayTimeline, type TodayTimelineResponse, type USHistoryKline, type USQuote, type WROptions, type ZTPoolItem, type ZTPoolType, addIndicators, asyncPool, buildIndicatorContext, calcATR, calcBIAS, calcBOLL, calcCCI, calcDMI, calcEMA, calcKC, calcKDJ, calcMA, calcMACD, calcOBV, calcROC, calcRSI, calcSAR, calcSMA, calcWMA, calcWR, chunkArray, decodeGBK, StockSDK as default, estimateIndicatorLookback, extractJsonFromJsonp, generateSearchExternalLinks, getEnabledIndicatorKeys, getSdkErrorCode, jsonpRequest, parseResponse, safeNumber, safeNumberOrNull };
+export { type AShareMarket, type ATROptions, type BIASOptions, type BOLLOptions, BROWSER_JSVARS_MUTEX_KEY, type BlockTradeDailyStatItem, type BlockTradeDateOptions, type BlockTradeDetailItem, type BlockTradeMarketStatItem, type BoardChangeItem, type CCIOptions, type CFFEXOptionQuote, type CFFEXOptionQuotesOptions, type ComexInventory, type ComexInventoryOptions, type ConceptBoard, type ConceptBoardConstituent, type ConceptBoardKline, type ConceptBoardKlineOptions, type ConceptBoardMinuteKline, type ConceptBoardMinuteKlineOptions, type ConceptBoardMinuteTimeline, type ConceptBoardSpot, type DMIOptions$1 as DMIOptions, type DMIResult$1 as DMIResult, type DatacenterQuery, type DatacenterResult, type DividendDetail, type DragonTigerBranchItem, type DragonTigerDateOptions, type DragonTigerDetailItem, type DragonTigerInstitutionItem, type DragonTigerPeriod, type DragonTigerSeatItem, type DragonTigerStockStatItem, type ETFOptionCate, type ETFOptionExpireDay, type ETFOptionMonth, type ExternalLink, type FetchJsVarsOptions, type FullQuote, type FundDividend, type FundDividendListOptions, type FundDividendListResult, type FundDividendRank, type FundEstimate, type FundFlow, type FundFlowOptions, type FundFlowRankItem, type FundFlowRankOptions, type FundNavHistory, type FundNavPoint, type FundQuote, type FundRankHistory, type FundRankPoint, FundService, type FundSortDirection, type FuturesExchange, type FuturesInventory, type FuturesInventoryOptions, type FuturesInventorySymbol, type FuturesKline, type FuturesKlineOptions, type GetAShareCodeListOptions, type GetAllAShareQuotesOptions, type GetAllUSQuotesOptions, type GetUSCodeListOptions, type GlobalFuturesKlineOptions, type GlobalFuturesQuote, type GlobalFuturesSpotOptions, type HKHistoryKline, type HKKlineOptions, type HKMinuteKline, type HKMinuteKlineOptions, type HKMinuteTimeline, type HKQuote, type HKUSHistoryKline, type HistoryKline, type HistoryKlineOptions, HttpError, INDICATOR_REGISTRY, type IndexOptionProduct, type IndicatorKey, type IndicatorOptions, type IndustryBoard, type IndustryBoardConstituent, type IndustryBoardKline, type IndustryBoardKlineOptions, type IndustryBoardMinuteKline, type IndustryBoardMinuteKlineOptions, type IndustryBoardMinuteTimeline, type IndustryBoardSpot, type JsonpOptions, type KCOptions$1 as KCOptions, type KCResult$1 as KCResult, type KDJOptions, type KlineWithIndicators, type MACDOptions, type MAOptions, MARKET_TZ, type MarginAccountItem, type MarginTargetItem, type MarketFundFlow, type MarketStatus, type MarketType, type MarketTz, type MinuteKline, type MinuteKlineOptions, type MinuteTimeline, type NorthboundDirection, type NorthboundFlowSummary, type NorthboundHistoryItem, type NorthboundHistoryOptions, type NorthboundHoldingRankItem, type NorthboundHoldingRankOptions, type NorthboundIndividualItem, type NorthboundMarket, type NorthboundMinuteItem, type NorthboundRankPeriod, type OBVOptions$1 as OBVOptions, type OBVResult$1 as OBVResult, type OptionKline, type OptionLHBItem, type OptionMinute, type OptionTQuote, type OptionTQuoteResult, type PanelLargeOrder, type ProviderName, type ProviderRequestPolicy, type ROCOptions$1 as ROCOptions, type ROCResult$1 as ROCResult, type RSIOptions, type RequestClientOptions, type RequestError, type RetryOptions, type SAROptions$1 as SAROptions, type SARResult$1 as SARResult, SdkError, type SearchResult, type SearchResultType, type SectorFundFlowItem, type SimpleQuote, type StockChangeItem, type StockChangeType, type StockFundFlowDaily, StockSDK, type SupportedMarket, type TimeMeta, type TodayTimeline, type TodayTimelineResponse, TradingCalendarService, type USHistoryKline, type USKlineOptions, type USMarket, type USMinuteKline, type USMinuteKlineOptions, type USMinuteTimeline, type USQuote, type WROptions, type ZTPoolItem, type ZTPoolType, addIndicators, asyncPool, buildIndicatorContext, buildTimeMeta, buildTimeMetaFromDateAndTime, calcATR, calcBIAS, calcBOLL, calcCCI, calcDMI, calcEMA, calcKC, calcKDJ, calcMA, calcMACD, calcOBV, calcROC, calcRSI, calcSAR, calcSMA, calcWMA, calcWR, chunkArray, decodeGBK, StockSDK as default, estimateIndicatorLookback, extractJsonFromJsonp, fetchJsVars, formatInTz, generateSearchExternalLinks, getEnabledIndicatorKeys, getSdkErrorCode, jsonpRequest, parseJsVars, parseMarketTime, parseResponse, safeNumber, safeNumberOrNull, withScriptMutex };