stock-sdk 1.9.2 → 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[];
+    }[]>;
+}
 
 /**
  * 响应解析器
@@ -258,6 +327,46 @@ 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;
 
 /**
  * A 股 / 指数 全量行情
@@ -2719,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` 的请求参数
@@ -2773,6 +2914,53 @@ 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 StockSDK {
     private readonly client;
@@ -2806,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[]>;
     /**
@@ -3253,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 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, 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 };

package/dist/index.d.ts

@@ -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[];
+    }[]>;
+}
 
 /**
  * 响应解析器
@@ -258,6 +327,46 @@ 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;
 
 /**
  * A 股 / 指数 全量行情
@@ -2719,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` 的请求参数
@@ -2773,6 +2914,53 @@ 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 StockSDK {
     private readonly client;
@@ -2806,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[]>;
     /**
@@ -3253,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 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, 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 };