stock-sdk 1.9.1 → 1.9.3

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,72 @@ interface JsonpOptions {
  */
 declare function jsonpRequest<T = unknown>(url: string, options?: JsonpOptions): Promise<T>;
 
+/**
+ * 时间元信息工具
+ *
+ * 给行情/K线/分时等含时间字段的数据补充统一的 `timestamp` (UTC unix ms)
+ * 与 `tz` (IANA 时区名)，让消费者无需自己根据各数据源的字符串格式做时区换算。
+ *
+ * 设计要点:
+ * - 不引入第三方时区库 (SDK 零依赖),通过 `Intl.DateTimeFormat` 计算时区偏移。
+ * - 兼容多种本地时间字符串格式 (yyyyMMddHHmmss / YYYY-MM-DD HH:mm:ss / YYYY-MM-DD HH:mm /
+ *   YYYY-MM-DD / yyyyMMdd / HH:mm 配 baseDate)。
+ * - 解析失败/输入为空时 `timestamp` 为 `NaN`,调用方可用 `Number.isNaN` 检测。
+ */
+/**
+ * 已支持的市场时区。沿用 IANA 时区名。
+ *
+ * - `Asia/Shanghai`: A 股 (沪深北)
+ * - `Asia/Hong_Kong`: 港股
+ * - `America/New_York`: 美股 (含夏令时切换)
+ */
+declare const MARKET_TZ: {
+    readonly CN: "Asia/Shanghai";
+    readonly HK: "Asia/Hong_Kong";
+    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;
+
 /**
  * A 股 / 指数 全量行情
  */
@@ -265,8 +400,12 @@ interface FullQuote {
         price: number;
         volume: number;
     }[];
-    /** 时间戳 yyyyMMddHHmmss */
+    /** 行情时间(原始字符串,腾讯接口格式 `yyyyMMddHHmmss`,市场时区) */
     time: string;
+    /** 行情时间对应的 UTC unix 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number;
+    /** 行情时间所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
     /** 涨跌额 */
     change: number;
     /** 涨跌幅% */
@@ -356,7 +495,12 @@ interface FundFlow {
     /** 总资金流 */
     totalFlow: number;
     name: string;
+    /** 数据日期(原始字符串,A 股时区) */
     date: string;
+    /** 数据日期对应当日 00:00 (`Asia/Shanghai`) 的 UTC 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number;
+    /** 数据日期所属时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
     raw: string[];
 }
 /**
@@ -384,7 +528,12 @@ interface HKQuote {
     prevClose: number;
     open: number;
     volume: number;
+    /** 行情时间(原始字符串,腾讯接口格式 `yyyyMMddHHmmss`,港股时区) */
     time: string;
+    /** UTC unix 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number;
+    /** 行情时间所属市场时区 (`Asia/Hong_Kong`) */
+    tz: MarketTz;
     change: number;
     changePercent: number;
     high: number;
@@ -414,8 +563,12 @@ interface USQuote {
     open: number;
     /** 成交量 */
     volume: number;
-    /** 时间 */
+    /** 行情时间(原始字符串,腾讯接口格式 `yyyyMMddHHmmss`,美东时区) */
     time: string;
+    /** UTC unix 毫秒时间戳(自动处理美东夏令时);无法解析时为 `NaN` */
+    timestamp: number;
+    /** 行情时间所属市场时区 (`America/New_York`) */
+    tz: MarketTz;
     /** 涨跌额 */
     change: number;
     /** 涨跌幅% */
@@ -455,8 +608,12 @@ interface FundQuote {
     accNav: number;
     /** 当日涨跌额 */
     change: number;
-    /** 净值日期 */
+    /** 净值日期(原始字符串,如 `'2024-05-12'`,A 股时区) */
     navDate: string;
+    /** 净值日期对应当日 00:00 (`Asia/Shanghai`) 的 UTC 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number;
+    /** 净值日期所属时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
     raw: string[];
 }
 
@@ -464,8 +621,12 @@ interface FundQuote {
  * A 股历史 K 线（日/周/月）
  */
 interface HistoryKline {
-    /** 日期 YYYY-MM-DD */
+    /** 日期 YYYY-MM-DD (A 股时区) */
     date: string;
+    /** 当日 00:00 (`Asia/Shanghai`) 的 UTC 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number;
+    /** 日期所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
     /** 股票代码 */
     code: string;
     /** 开盘价 */
@@ -493,8 +654,12 @@ interface HistoryKline {
  * A 股分时数据（1 分钟）
  */
 interface MinuteTimeline {
-    /** 时间 YYYY-MM-DD HH:mm */
+    /** 时间 YYYY-MM-DD HH:mm (A 股时区) */
     time: string;
+    /** UTC 毫秒时间戳 (`Asia/Shanghai` 解释);无法解析时为 `NaN` */
+    timestamp: number;
+    /** 时间所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
     /** 开盘价 */
     open: number | null;
     /** 收盘价 */
@@ -514,8 +679,12 @@ interface MinuteTimeline {
  * A 股分钟 K 线（5/15/30/60）
  */
 interface MinuteKline {
-    /** 时间 YYYY-MM-DD HH:mm */
+    /** 时间 YYYY-MM-DD HH:mm (A 股时区) */
     time: string;
+    /** UTC 毫秒时间戳 (`Asia/Shanghai` 解释);无法解析时为 `NaN` */
+    timestamp: number;
+    /** 时间所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
     /** 开盘价 */
     open: number | null;
     /** 收盘价 */
@@ -541,8 +710,15 @@ interface MinuteKline {
  * 当日分时项
  */
 interface TodayTimeline {
-    /** 时间 HH:mm */
+    /** 时间 HH:mm (A 股时区) */
     time: string;
+    /**
+     * UTC 毫秒时间戳。由所属 `TodayTimelineResponse.date` 与 `time` 拼接后,
+     * 按 `Asia/Shanghai` 解释得到;无法解析时为 `NaN`。
+     */
+    timestamp: number;
+    /** 时间所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
     /** 当前价 */
     price: number;
     /** 均价 */
@@ -558,8 +734,12 @@ interface TodayTimeline {
 interface TodayTimelineResponse {
     /** 股票代码 */
     code: string;
-    /** 交易日期 YYYY-MM-DD */
+    /** 交易日期 YYYY-MM-DD (A 股时区) */
     date: string;
+    /** 交易日 00:00 (`Asia/Shanghai`) 的 UTC 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number;
+    /** 日期所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
     /**
      * 昨收价
      * - 由 SDK 解析腾讯接口的 `quoteFields[4]` 得到
@@ -570,11 +750,16 @@ interface TodayTimelineResponse {
     data: TodayTimeline[];
 }
 /**
- * 港股 / 美股历史 K 线
+ * 港股 / 美股历史 K 线公共字段。
+ *
+ * 内部基类,通常不直接使用。请用具体的 `HKHistoryKline` 或 `USHistoryKline`,
+ * 它们各自带本地化字段 (`currency` / `lotSize`)。
  */
-interface HKUSHistoryKline {
-    /** 日期 YYYY-MM-DD */
+interface ForeignHistoryKlineBase {
+    /** 日期 YYYY-MM-DD (市场本地时区) */
     date: string;
+    /** UTC 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number;
     /** 股票代码 */
     code: string;
     /** 股票名称 */
@@ -600,6 +785,41 @@ interface HKUSHistoryKline {
     /** 换手率% */
     turnoverRate: number | null;
 }
+/**
+ * 港股历史 K 线
+ *
+ * `currency` 固定 `'HKD'`,`tz` 固定 `'Asia/Hong_Kong'`。
+ * `lotSize`(每手股数)由 K 线接口本身不直接返回,目前为 `null`,
+ * 后续若数据源补齐再填充;如需港股每手股数请用 `getHKQuotes` 的 `lotSize` 字段。
+ */
+interface HKHistoryKline extends ForeignHistoryKlineBase {
+    /** 时区 (`Asia/Hong_Kong`) */
+    tz: MarketTz;
+    /** 计价币种 (固定 `'HKD'`) */
+    currency: 'HKD';
+    /** 港股每手股数;K 线接口暂不返回,固定 `null` */
+    lotSize: number | null;
+}
+/**
+ * 美股历史 K 线
+ *
+ * `currency` 固定 `'USD'`,`tz` 固定 `'America/New_York'`(自动处理夏令时切换)。
+ * 不含盘前/盘后(extended hours)数据,仅常规交易时段。
+ */
+interface USHistoryKline extends ForeignHistoryKlineBase {
+    /** 时区 (`America/New_York`,含夏令时) */
+    tz: MarketTz;
+    /** 计价币种 (固定 `'USD'`) */
+    currency: 'USD';
+}
+/**
+ * 港股 / 美股历史 K 线 (兼容别名)
+ *
+ * @deprecated 自 v1.9.1 起拆分为 {@link HKHistoryKline} 与 {@link USHistoryKline},
+ * 各自带本地化字段 (currency / lotSize)。本别名仍是它们的 union,
+ * 老代码无需立即迁移;新代码请直接用具体类型以获得更好的类型推断。
+ */
+type HKUSHistoryKline = HKHistoryKline | USHistoryKline;
 
 /**
  * 行业板块列表项
@@ -1752,9 +1972,19 @@ interface GetUSCodeListOptions {
  */
 
 interface HistoryKlineOptions {
-    /** K 线周期 */
+    /** K 线周期 @default 'daily' */
     period?: 'daily' | 'weekly' | 'monthly';
-    /** 复权类型 */
+    /**
+     * 复权类型
+     *
+     * - `'qfq'` 前复权(默认):用最新一次分红送股调整历史价格,适合看走势
+     * - `'hfq'` 后复权:固定历史价格,把分红送股摊到当下,适合长期收益率/复利计算
+     * - `''` 不复权:返回交易所原始价格
+     *
+     * **未传时默认使用 `'qfq'`**。如果做回测、计算分红再投资收益,请显式传 `'hfq'` 或 `''`。
+     *
+     * @default 'qfq'
+     */
     adjust?: '' | 'qfq' | 'hfq';
     /** 开始日期 YYYYMMDD */
     startDate?: string;
@@ -1762,9 +1992,17 @@ interface HistoryKlineOptions {
     endDate?: string;
 }
 interface MinuteKlineOptions {
-    /** K 线周期 */
+    /** K 线周期 @default '1' */
     period?: '1' | '5' | '15' | '30' | '60';
-    /** 复权类型（仅 5/15/30/60 分钟有效） */
+    /**
+     * 复权类型(仅 5/15/30/60 分钟有效;1 分钟分时不支持复权)
+     *
+     * - `'qfq'` 前复权(默认)
+     * - `'hfq'` 后复权
+     * - `''` 不复权
+     *
+     * @default 'qfq'
+     */
     adjust?: '' | 'qfq' | 'hfq';
     /** 开始时间 */
     startDate?: string;
@@ -1780,9 +2018,19 @@ interface MinuteKlineOptions {
  * 通用历史 K 线请求选项
  */
 interface HistoryKlineRequestOptions {
-    /** K 线周期 */
+    /** K 线周期 @default 'daily' */
     period?: 'daily' | 'weekly' | 'monthly';
-    /** 复权类型 */
+    /**
+     * 复权类型
+     *
+     * - `'qfq'` 前复权(默认)
+     * - `'hfq'` 后复权
+     * - `''` 不复权
+     *
+     * 详见 [复权说明](https://stock-sdk.linkdiary.cn/guide/dividend-adjustment.html)。
+     *
+     * @default 'qfq'
+     */
     adjust?: '' | 'qfq' | 'hfq';
     /** 开始日期 YYYYMMDD */
     startDate?: string;
@@ -2580,6 +2828,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` 的请求参数
@@ -2610,6 +2890,78 @@ interface KlineWithIndicatorsOptions {
     indicators?: IndicatorOptions;
 }
 
+/**
+ * 交易日历 / 市场状态工具
+ *
+ * 在原有 `getTradingCalendar()` 字符串数组之外,提供更高层的便利方法:
+ * - `isTradingDay(date?)`:判断是否交易日 (A 股,基于上游日历)
+ * - `nextTradingDay(date?)` / `prevTradingDay(date?)`:跳转最近的交易日
+ * - `getMarketStatus(market?)`:返回当前市场是开盘/午休/盘前/盘后/休市等状态
+ *
+ * 港股 / 美股没有官方日历数据源,`getMarketStatus('HK' | 'US')` 退化为
+ * "周一-周五 + 已知交易时段"判断。法定假日不会被识别。
+ */
+
+/**
+ * 市场实时状态。
+ *
+ * - `'pre_market'` 盘前(含集合竞价)
+ * - `'open'` 连续竞价交易中
+ * - `'lunch_break'` 午间休市(港股 12:00-13:00,A 股 11:30-13:00;美股无)
+ * - `'after_hours'` 盘后
+ * - `'closed'` 非交易日 / 周末 / 凌晨等远离交易时段的时间
+ */
+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 StockSDK {
     private readonly client;
     private readonly quoteService;
@@ -2623,6 +2975,7 @@ declare class StockSDK {
     private readonly marketEventService;
     private readonly dragonTigerService;
     private readonly dataService;
+    private readonly tradingCalendarService;
     /**
      * 创建 Stock SDK 实例。
      * 旧的全局 `timeout` / `retry` / `rateLimit` / `circuitBreaker` 配置继续有效，
@@ -2641,12 +2994,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[]>;
     /**
@@ -2722,29 +3075,50 @@ declare class StockSDK {
      */
     getConceptMinuteKline(symbol: string, options?: ConceptBoardMinuteKlineOptions): Promise<ConceptBoardMinuteTimeline[] | ConceptBoardMinuteKline[]>;
     /**
-     * 获取 A 股历史 K 线（日/周/月，含复权）
+     * 获取 A 股历史 K 线(日/周/月,含复权)。
+     *
+     * **复权默认值:`adjust='qfq'`(前复权)。**
+     * - 前复权适合看走势/做技术分析
+     * - 后复权 `'hfq'` 适合算长期收益率/复利
+     * - 不复权 `''` 是交易所原始价
+     *
+     * 不显式传 `adjust` 时返回的是已经被前复权调整过的价格,
+     * 做回测/收益计算时务必显式传值,详见
+     * [复权说明](https://stock-sdk.linkdiary.cn/guide/dividend-adjustment.html)。
+     *
      * @param symbol 股票代码
      * @param options K 线参数
      */
     getHistoryKline(symbol: string, options?: HistoryKlineOptions): Promise<HistoryKline[]>;
     /**
-     * 获取 A 股分时/分钟 K 线
+     * 获取 A 股分时/分钟 K 线。
+     *
+     * **复权默认值:`adjust='qfq'`(前复权,仅 5/15/30/60 分钟有效)。** 1 分钟分时不支持复权。
+     *
      * @param symbol 股票代码
-     * @param options 周期参数（不传周期则返回当日分时）
+     * @param options 周期参数(不传周期则返回当日分时)
      */
     getMinuteKline(symbol: string, options?: MinuteKlineOptions): Promise<MinuteTimeline[] | MinuteKline[]>;
     /**
-     * 获取港股历史 K 线
+     * 获取港股历史 K 线。
+     *
+     * **复权默认值:`adjust='qfq'`(前复权)。** 详见
+     * [复权说明](https://stock-sdk.linkdiary.cn/guide/dividend-adjustment.html)。
+     *
      * @param symbol 港股代码
      * @param options K 线参数
      */
-    getHKHistoryKline(symbol: string, options?: HKKlineOptions): Promise<HKUSHistoryKline[]>;
+    getHKHistoryKline(symbol: string, options?: HKKlineOptions): Promise<HKHistoryKline[]>;
     /**
-     * 获取美股历史 K 线
+     * 获取美股历史 K 线。
+     *
+     * **复权默认值:`adjust='qfq'`(前复权)。** 详见
+     * [复权说明](https://stock-sdk.linkdiary.cn/guide/dividend-adjustment.html)。
+     *
      * @param symbol 美股代码
      * @param options K 线参数
      */
-    getUSHistoryKline(symbol: string, options?: USKlineOptions): Promise<HKUSHistoryKline[]>;
+    getUSHistoryKline(symbol: string, options?: USKlineOptions): Promise<USHistoryKline[]>;
     /**
      * 模糊搜索股票/指数/基金等
      * @param keyword 关键词（代码 / 名称 / 拼音）
@@ -2801,6 +3175,53 @@ declare class StockSDK {
      * 获取交易日历（A 股）
      */
     getTradingCalendar(): Promise<string[]>;
+    /**
+     * 判断给定日期是否为 A 股交易日。
+     *
+     * 数据源:`getTradingCalendar()` (腾讯接口,带 12 小时缓存)。
+     * 第一次调用会拉取全量交易日列表,后续命中缓存。
+     *
+     * @param date 不传则取"现在 `Asia/Shanghai` 的当日"。
+     *             支持 `'YYYY-MM-DD'` / `'YYYYMMDD'` / `Date` 对象。
+     * @example
+     * ```ts
+     * await sdk.isTradingDay();              // 今天是否交易日
+     * await sdk.isTradingDay('2024-10-01');  // false (国庆)
+     * ```
+     */
+    isTradingDay(date?: string | Date): Promise<boolean>;
+    /**
+     * 返回 A 股下一个交易日 (`'YYYY-MM-DD'`)。
+     *
+     * 如果 `date` 本身是交易日,返回它**之后**的下一个;否则返回大于它的第一个交易日。
+     *
+     * @param date 不传则取"现在 `Asia/Shanghai` 的当日"
+     * @throws RangeError 当 `date` 已超过日历范围时
+     */
+    nextTradingDay(date?: string | Date): Promise<string>;
+    /**
+     * 返回 A 股上一个交易日 (`'YYYY-MM-DD'`)。
+     *
+     * 如果 `date` 本身是交易日,返回它**之前**的上一个;否则返回小于它的最后一个交易日。
+     *
+     * @param date 不传则取"现在 `Asia/Shanghai` 的当日"
+     * @throws RangeError 当 `date` 早于日历最早日期时
+     */
+    prevTradingDay(date?: string | Date): Promise<string>;
+    /**
+     * 返回当前市场实时状态 (同步,不发请求)。
+     *
+     * 状态包括:`'pre_market'`(盘前)/ `'open'`(交易中)/ `'lunch_break'`(午休) /
+     * `'after_hours'`(盘后)/ `'closed'`(休市/周末)。
+     *
+     * **注意:此方法仅按交易时段判断,不识别法定假日**。如需精确判断"今天是否交易日",
+     * 请用 `await isTradingDay()` (会发请求)。
+     *
+     * 港股 / 美股没有官方日历,只按 "周一-周五 + 已知交易时段" 判断,假日不会被识别。
+     *
+     * @param market `'A'`(默认) / `'HK'` / `'US'`
+     */
+    getMarketStatus(market?: SupportedMarket): MarketStatus;
     /**
      * 获取分红配股明细
      * @param symbol 股票代码
@@ -3020,4 +3441,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 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 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, 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 GetAllUSQuotesOptions, type GetUSCodeListOptions, 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, MARKET_TZ, type MarginAccountItem, type MarginTargetItem, type MarketFundFlow, type MarketStatus, type MarketType, type MarketTz, 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 SupportedMarket, type TimeMeta, type TodayTimeline, type TodayTimelineResponse, TradingCalendarService, type USHistoryKline, type USMarket, 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, generateSearchExternalLinks, getEnabledIndicatorKeys, getSdkErrorCode, jsonpRequest, parseMarketTime, parseResponse, safeNumber, safeNumberOrNull };