stock-sdk 1.2.2 → 1.3.0-beta.2

package/dist/index.d.ts

@@ -1,3 +1,44 @@
+interface RequestClientOptions {
+    baseUrl?: string;
+    timeout?: number;
+}
+
+/**
+ * 响应解析器
+ */
+/**
+ * 将 ArrayBuffer 解码为 GBK 字符串
+ * 使用原生 TextDecoder（浏览器和 Node.js 18+ 均支持 GBK）
+ */
+declare function decodeGBK(data: ArrayBuffer): string;
+/**
+ * 解析腾讯财经响应文本
+ * 按 `;` 拆行，提取 `v_xxx="..."` 里的内容，返回 { key, fields }[]
+ */
+declare function parseResponse(text: string): {
+    key: string;
+    fields: string[];
+}[];
+/**
+ * 安全转换为数字，空值返回 0
+ */
+declare function safeNumber(val: string | undefined): number;
+/**
+ * 安全转换为数字，空值返回 null
+ */
+declare function safeNumberOrNull(val: string | undefined): number | null;
+
+/**
+ * 将数组分割成指定大小的块
+ */
+declare function chunkArray<T>(array: T[], chunkSize: number): T[][];
+/**
+ * 并发控制执行异步任务
+ * @param tasks 任务函数数组
+ * @param concurrency 最大并发数
+ */
+declare function asyncPool<T>(tasks: (() => Promise<T>)[], concurrency: number): Promise<T[]>;
+
 /**
  * A 股 / 指数 全量行情
  */
@@ -162,18 +203,50 @@ interface HKQuote {
     raw: string[];
 }
 /**
- * 美股简要行情
+ * 美股行情
  */
 interface USQuote {
+    /** 市场标识 */
     marketId: string;
+    /** 名称 */
     name: string;
+    /** 股票代码 */
     code: string;
+    /** 最新价 */
     price: number;
+    /** 昨收 */
+    prevClose: number;
+    /** 今开 */
+    open: number;
+    /** 成交量 */
+    volume: number;
+    /** 时间 */
+    time: string;
+    /** 涨跌额 */
     change: number;
+    /** 涨跌幅% */
     changePercent: number;
-    volume: number;
+    /** 最高 */
+    high: number;
+    /** 最低 */
+    low: number;
+    /** 成交额 */
     amount: number;
-    marketCap: number | null;
+    /** 换手率% */
+    turnoverRate: number | null;
+    /** 市盈率 */
+    pe: number | null;
+    /** 振幅% */
+    amplitude: number | null;
+    /** 总市值(亿) */
+    totalMarketCap: number | null;
+    /** 市净率 */
+    pb: number | null;
+    /** 52周最高价 */
+    high52w: number | null;
+    /** 52周最低价 */
+    low52w: number | null;
+    /** 原始字段数组 */
     raw: string[];
 }
 /**
@@ -295,6 +368,41 @@ interface TodayTimelineResponse {
     /** 分时数据列表 */
     data: TodayTimeline[];
 }
+/**
+ * 港股/美股历史 K 线
+ */
+interface HKUSHistoryKline {
+    /** 日期 YYYY-MM-DD */
+    date: string;
+    /** 股票代码 */
+    code: string;
+    /** 股票名称 */
+    name: string;
+    /** 开盘价 */
+    open: number | null;
+    /** 收盘价 */
+    close: number | null;
+    /** 最高价 */
+    high: number | null;
+    /** 最低价 */
+    low: number | null;
+    /** 成交量 */
+    volume: number | null;
+    /** 成交额 */
+    amount: number | null;
+    /** 振幅% */
+    amplitude: number | null;
+    /** 涨跌幅% */
+    changePercent: number | null;
+    /** 涨跌额 */
+    change: number | null;
+    /** 换手率% */
+    turnoverRate: number | null;
+}
+
+/**
+ * 腾讯财经 - 批量操作
+ */
 
 /**
  * 获取全部 A 股行情的配置选项
@@ -307,123 +415,416 @@ interface GetAllAShareQuotesOptions {
     /** 进度回调函数 */
     onProgress?: (completed: number, total: number) => void;
 }
+
+/**
+ * 东方财富 - A 股 K 线
+ */
+
+interface HistoryKlineOptions {
+    /** K 线周期 */
+    period?: 'daily' | 'weekly' | 'monthly';
+    /** 复权类型 */
+    adjust?: '' | 'qfq' | 'hfq';
+    /** 开始日期 YYYYMMDD */
+    startDate?: string;
+    /** 结束日期 YYYYMMDD */
+    endDate?: string;
+}
+interface MinuteKlineOptions {
+    /** K 线周期 */
+    period?: '1' | '5' | '15' | '30' | '60';
+    /** 复权类型（仅 5/15/30/60 分钟有效） */
+    adjust?: '' | 'qfq' | 'hfq';
+    /** 开始时间 */
+    startDate?: string;
+    /** 结束时间 */
+    endDate?: string;
+}
+
+/**
+ * 东方财富 - 港股 K 线
+ */
+
+interface HKKlineOptions {
+    /** K 线周期 */
+    period?: 'daily' | 'weekly' | 'monthly';
+    /** 复权类型 */
+    adjust?: '' | 'qfq' | 'hfq';
+    /** 开始日期 YYYYMMDD */
+    startDate?: string;
+    /** 结束日期 YYYYMMDD */
+    endDate?: string;
+}
+
+/**
+ * 东方财富 - 美股 K 线
+ */
+
+interface USKlineOptions {
+    /** K 线周期 */
+    period?: 'daily' | 'weekly' | 'monthly';
+    /** 复权类型 */
+    adjust?: '' | 'qfq' | 'hfq';
+    /** 开始日期 YYYYMMDD */
+    startDate?: string;
+    /** 结束日期 YYYYMMDD */
+    endDate?: string;
+}
+
+interface OHLCV {
+    open: number | null;
+    high: number | null;
+    low: number | null;
+    close: number | null;
+    volume?: number | null;
+}
+interface MAOptions {
+    /** 均线周期数组，默认 [5, 10, 20, 30, 60, 120, 250] */
+    periods?: number[];
+    /** 均线类型：'sma'(简单) | 'ema'(指数) | 'wma'(加权)，默认 'sma' */
+    type?: 'sma' | 'ema' | 'wma';
+}
+interface MACDOptions {
+    /** 短期 EMA 周期，默认 12 */
+    short?: number;
+    /** 长期 EMA 周期，默认 26 */
+    long?: number;
+    /** 信号线 EMA 周期，默认 9 */
+    signal?: number;
+}
+interface BOLLOptions {
+    /** 均线周期，默认 20 */
+    period?: number;
+    /** 标准差倍数，默认 2 */
+    stdDev?: number;
+}
+interface KDJOptions {
+    /** RSV 周期，默认 9 */
+    period?: number;
+    /** K 值平滑周期，默认 3 */
+    kPeriod?: number;
+    /** D 值平滑周期，默认 3 */
+    dPeriod?: number;
+}
+interface RSIOptions {
+    /** RSI 周期数组，默认 [6, 12, 24] */
+    periods?: number[];
+}
+interface WROptions {
+    /** WR 周期数组，默认 [6, 10] */
+    periods?: number[];
+}
+interface BIASOptions {
+    /** BIAS 周期数组，默认 [6, 12, 24] */
+    periods?: number[];
+}
+interface CCIOptions {
+    /** CCI 周期，默认 14 */
+    period?: number;
+}
+interface ATROptions {
+    /** ATR 周期，默认 14 */
+    period?: number;
+}
+interface IndicatorOptions {
+    ma?: MAOptions | boolean;
+    macd?: MACDOptions | boolean;
+    boll?: BOLLOptions | boolean;
+    kdj?: KDJOptions | boolean;
+    rsi?: RSIOptions | boolean;
+    wr?: WROptions | boolean;
+    bias?: BIASOptions | boolean;
+    cci?: CCIOptions | boolean;
+    atr?: ATROptions | boolean;
+}
+interface MAResult {
+    [key: string]: number | null;
+}
+interface MACDResult {
+    dif: number | null;
+    dea: number | null;
+    macd: number | null;
+}
+interface BOLLResult {
+    mid: number | null;
+    upper: number | null;
+    lower: number | null;
+    bandwidth: number | null;
+}
+interface KDJResult {
+    k: number | null;
+    d: number | null;
+    j: number | null;
+}
+interface RSIResult {
+    [key: string]: number | null;
+}
+interface WRResult {
+    [key: string]: number | null;
+}
+interface BIASResult {
+    [key: string]: number | null;
+}
+interface CCIResult {
+    cci: number | null;
+}
+interface ATRResult {
+    /** 真实波幅 */
+    tr: number | null;
+    /** 平均真实波幅 */
+    atr: number | null;
+}
+
+/**
+ * 计算简单移动平均线 SMA
+ */
+declare function calcSMA(data: (number | null)[], period: number): (number | null)[];
+/**
+ * 计算指数移动平均线 EMA
+ * 使用前 N 天的 SMA 作为 EMA 初始值，避免首日偏差
+ */
+declare function calcEMA(data: (number | null)[], period: number): (number | null)[];
+/**
+ * 计算加权移动平均线 WMA
+ */
+declare function calcWMA(data: (number | null)[], period: number): (number | null)[];
+/**
+ * 批量计算均线
+ */
+declare function calcMA(closes: (number | null)[], options?: MAOptions): MAResult[];
+
+/**
+ * 计算 MACD 指标
+ */
+declare function calcMACD(closes: (number | null)[], options?: MACDOptions): MACDResult[];
+
+/**
+ * 计算布林带
+ */
+declare function calcBOLL(closes: (number | null)[], options?: BOLLOptions): BOLLResult[];
+
+/**
+ * 计算 KDJ 指标
+ */
+declare function calcKDJ(data: OHLCV[], options?: KDJOptions): KDJResult[];
+
+/**
+ * 计算 RSI 指标
+ */
+declare function calcRSI(closes: (number | null)[], options?: RSIOptions): RSIResult[];
+
+/**
+ * 计算威廉指标 WR
+ */
+declare function calcWR(data: OHLCV[], options?: WROptions): WRResult[];
+
+/**
+ * 计算乖离率 BIAS
+ *
+ * 公式：BIAS = (收盘价 - MA) / MA × 100
+ *
+ * 乖离率表示股价与移动平均线之间的偏离程度
+ * - 正乖离：股价在均线上方，可能超买
+ * - 负乖离：股价在均线下方，可能超卖
+ */
+declare function calcBIAS(closes: (number | null)[], options?: BIASOptions): BIASResult[];
+
+/**
+ * 计算商品通道指数 CCI
+ *
+ * 公式：
+ * TP（典型价格）= (最高价 + 最低价 + 收盘价) / 3
+ * MA = TP 的 N 日简单移动平均
+ * MD = TP 与 MA 的平均绝对偏差
+ * CCI = (TP - MA) / (0.015 × MD)
+ *
+ * CCI 用于判断超买超卖：
+ * - CCI > 100：超买区域
+ * - CCI < -100：超卖区域
+ * - CCI 在 -100 ~ 100 之间：正常区域
+ */
+declare function calcCCI(data: OHLCV[], options?: CCIOptions): CCIResult[];
+
+/**
+ * 计算平均真实波幅 ATR (Average True Range)
+ *
+ * 公式：
+ * TR（真实波幅）= max(
+ *   最高价 - 最低价,
+ *   |最高价 - 昨收|,
+ *   |最低价 - 昨收|
+ * )
+ * ATR = TR 的 N 日移动平均
+ *
+ * ATR 用于衡量市场波动性：
+ * - ATR 越大，市场波动越大
+ * - ATR 越小，市场波动越小
+ * - 常用于止损位设置（如 2 倍 ATR）
+ */
+declare function calcATR(data: OHLCV[], options?: ATROptions): ATRResult[];
+
+/**
+ * 带技术指标的 K 线数据
+ */
+type KlineWithIndicators<T extends HistoryKline | HKUSHistoryKline> = T & {
+    ma?: MAResult;
+    macd?: MACDResult;
+    boll?: BOLLResult;
+    kdj?: KDJResult;
+    rsi?: RSIResult;
+    wr?: WRResult;
+    bias?: BIASResult;
+    cci?: CCIResult;
+    atr?: ATRResult;
+};
+/**
+ * 为 K 线数据添加技术指标
+ */
+declare function addIndicators<T extends HistoryKline | HKUSHistoryKline>(klines: T[], options?: IndicatorOptions): KlineWithIndicators<T>[];
+
+/**
+ * Stock SDK - 门面类
+ * 统一对外接口，组合各模块
+ */
+
+/**
+ * 市场类型
+ */
+type MarketType = 'A' | 'HK' | 'US';
 declare class StockSDK {
-    private baseUrl;
-    private timeout;
-    constructor(options?: {
-        baseUrl?: string;
-        timeout?: number;
-    });
-    private request;
+    private client;
+    constructor(options?: RequestClientOptions);
     /**
      * 获取 A 股 / 指数 全量行情
-     * @param codes 如 ['sz000858', 'sh600000']
+     * @param codes 股票代码数组，如 ['sz000858', 'sh600000']
      */
     getFullQuotes(codes: string[]): Promise<FullQuote[]>;
-    private parseFullQuote;
     /**
      * 获取简要行情
-     * @param codes 如 ['sz000858', 'sh000001']（自动添加 s_ 前缀）
+     * @param codes 股票代码数组，如 ['sz000858', 'sh000001']
      */
     getSimpleQuotes(codes: string[]): Promise<SimpleQuote[]>;
-    private parseSimpleQuote;
-    /**
-     * 获取资金流向
-     * @param codes 股票代码数组，如 ['sz000858', 'sh600000']（自动添加 ff_ 前缀）
-     */
-    getFundFlow(codes: string[]): Promise<FundFlow[]>;
-    private parseFundFlow;
-    /**
-     * 获取盘口大单占比
-     * @param codes 股票代码数组，如 ['sz000858', 'sh600000']（自动添加 s_pk 前缀）
-     */
-    getPanelLargeOrder(codes: string[]): Promise<PanelLargeOrder[]>;
-    private parsePanelLargeOrder;
     /**
      * 获取港股扩展行情
-     * @param codes 港股代码数组，如 ['09988', '00700']（自动添加 r_hk 前缀）
+     * @param codes 港股代码数组，如 ['09988', '00700']
      */
     getHKQuotes(codes: string[]): Promise<HKQuote[]>;
-    private parseHKQuote;
     /**
      * 获取美股简要行情
-     * @param codes 美股代码数组，如 ['BABA', 'AAPL']（自动添加 s_us 前缀）
+     * @param codes 美股代码数组，如 ['BABA', 'AAPL']
      */
     getUSQuotes(codes: string[]): Promise<USQuote[]>;
-    private parseUSQuote;
     /**
      * 获取公募基金行情
-     * @param codes 基金代码数组，如 ['000001', '110011']（自动添加 jj 前缀）
+     * @param codes 基金代码数组，如 ['000001', '110011']
      */
     getFundQuotes(codes: string[]): Promise<FundQuote[]>;
-    private parseFundQuote;
     /**
-     * 批量混合查询，返回原始解析结果（key + fields）
-     * @param params 如 'sz000858,s_sh000001,jj000001'
+     * 获取资金流向
+     * @param codes 股票代码数组，如 ['sz000858', 'sh600000']
      */
-    batchRaw(params: string): Promise<{
-        key: string;
-        fields: string[];
-    }[]>;
+    getFundFlow(codes: string[]): Promise<FundFlow[]>;
+    /**
+     * 获取盘口大单占比
+     * @param codes 股票代码数组，如 ['sz000858', 'sh600000']
+     */
+    getPanelLargeOrder(codes: string[]): Promise<PanelLargeOrder[]>;
     /**
      * 获取当日分时走势数据
      * @param code 股票代码，如 'sz000001' 或 'sh600000'
-     * @returns 当日分时数据
      */
     getTodayTimeline(code: string): Promise<TodayTimelineResponse>;
+    /**
+     * 获取 A 股历史 K 线（日/周/月）
+     */
+    getHistoryKline(symbol: string, options?: HistoryKlineOptions): Promise<HistoryKline[]>;
+    /**
+     * 获取 A 股分钟 K 线或分时数据
+     */
+    getMinuteKline(symbol: string, options?: MinuteKlineOptions): Promise<MinuteTimeline[] | MinuteKline[]>;
+    /**
+     * 获取港股历史 K 线（日/周/月）
+     */
+    getHKHistoryKline(symbol: string, options?: HKKlineOptions): Promise<HKUSHistoryKline[]>;
+    /**
+     * 获取美股历史 K 线（日/周/月）
+     */
+    getUSHistoryKline(symbol: string, options?: USKlineOptions): Promise<HKUSHistoryKline[]>;
     /**
      * 从远程获取 A 股代码列表
      * @param includeExchange 是否包含交易所前缀（如 sh、sz、bj），默认 true
-     * @returns A 股代码数组
      */
     getAShareCodeList(includeExchange?: boolean): Promise<string[]>;
     /**
-     * 获取全部 A 股实时行情（从远程获取股票代码列表）
-     * @param options 配置选项
-     * @param options.batchSize 单次请求的股票数量，默认 500
-     * @param options.concurrency 最大并发请求数，默认 7
-     * @param options.onProgress 进度回调函数
-     * @returns 全部 A 股的实时行情数据
+     * 从远程获取美股代码列表
+     * @param includeMarket 是否包含市场前缀（如 105.、106.），默认 true
+     */
+    getUSCodeList(includeMarket?: boolean): Promise<string[]>;
+    /**
+     * 从远程获取港股代码列表
+     */
+    getHKCodeList(): Promise<string[]>;
+    /**
+     * 获取全部 A 股实时行情
      */
     getAllAShareQuotes(options?: GetAllAShareQuotesOptions): Promise<FullQuote[]>;
     /**
-     * 获取全部 A 股实时行情（使用自定义股票代码列表）
-     * @param codes 股票代码列表
-     * @param options 配置选项
+     * 获取全部港股实时行情
+     */
+    getAllHKShareQuotes(options?: GetAllAShareQuotesOptions): Promise<HKQuote[]>;
+    /**
+     * 获取全部美股实时行情
+     */
+    getAllUSShareQuotes(options?: GetAllAShareQuotesOptions): Promise<USQuote[]>;
+    /**
+     * 获取全部股票实时行情（使用自定义股票代码列表）
      */
     getAllQuotesByCodes(codes: string[], options?: GetAllAShareQuotesOptions): Promise<FullQuote[]>;
     /**
-     * 获取 A 股历史 K 线（日/周/月）
-     * @param symbol 股票代码（6位纯数字，如 '000001'，或带前缀如 'sz000001'）
-     * @param options 配置选项
-     * @param options.period K线周期：'daily' | 'weekly' | 'monthly'，默认 'daily'
-     * @param options.adjust 复权类型：'' (不复权) | 'qfq' (前复权) | 'hfq' (后复权)，默认 'hfq'
-     * @param options.startDate 开始日期 YYYYMMDD，默认 '19700101'
-     * @param options.endDate 结束日期 YYYYMMDD，默认 '20500101'
-     * @returns 历史 K 线数据
+     * 批量混合查询，返回原始解析结果（key + fields）
+     * @param params 如 'sz000858,s_sh000001,jj000001'
      */
-    getHistoryKline(symbol: string, options?: {
-        period?: 'daily' | 'weekly' | 'monthly';
-        adjust?: '' | 'qfq' | 'hfq';
-        startDate?: string;
-        endDate?: string;
-    }): Promise<HistoryKline[]>;
+    batchRaw(params: string): Promise<{
+        key: string;
+        fields: string[];
+    }[]>;
     /**
-     * 获取 A 股分钟 K 线或分时数据
-     * @param symbol 股票代码（6位纯数字，如 '000001'，或带前缀如 'sz000001'）
-     * @param options 配置选项
-     * @param options.period K线周期：'1' (分时) | '5' | '15' | '30' | '60'，默认 '1'
-     * @param options.adjust 复权类型（仅 5/15/30/60 分钟有效）：'' | 'qfq' | 'hfq'，默认 'hfq'
-     * @param options.startDate 开始时间 'YYYY-MM-DD HH:mm:ss'
-     * @param options.endDate 结束时间 'YYYY-MM-DD HH:mm:ss'
-     * @returns 分钟 K 线或分时数据
+     * 市场类型识别
+     */
+    private detectMarket;
+    /**
+     * 安全获取数组最大值
+     */
+    private safeMax;
+    /**
+     * 计算各指标所需的最大前置天数
      */
-    getMinuteKline(symbol: string, options?: {
-        period?: '1' | '5' | '15' | '30' | '60';
+    private calcRequiredLookback;
+    /**
+     * 计算实际请求的开始日期
+     */
+    private calcActualStartDate;
+    /**
+     * 日期字符串转时间戳
+     */
+    private dateToTimestamp;
+    /**
+     * 获取带技术指标的历史 K 线
+     */
+    getKlineWithIndicators(symbol: string, options?: {
+        /** 市场类型，不传则自动识别 */
+        market?: MarketType;
+        /** K 线周期 */
+        period?: 'daily' | 'weekly' | 'monthly';
+        /** 复权类型 */
         adjust?: '' | 'qfq' | 'hfq';
+        /** 开始日期 YYYYMMDD */
         startDate?: string;
+        /** 结束日期 YYYYMMDD */
         endDate?: string;
-    }): Promise<MinuteTimeline[] | MinuteKline[]>;
+        /** 技术指标配置 */
+        indicators?: IndicatorOptions;
+    }): Promise<KlineWithIndicators<HistoryKline | HKUSHistoryKline>[]>;
 }
 
-export { type FullQuote, type FundFlow, type FundQuote, type GetAllAShareQuotesOptions, type HKQuote, type HistoryKline, type MinuteKline, type MinuteTimeline, type PanelLargeOrder, type SimpleQuote, StockSDK, type TodayTimeline, type TodayTimelineResponse, type USQuote, StockSDK as default };
+export { type ATROptions, type BIASOptions, type BOLLOptions, type CCIOptions, type FullQuote, type FundFlow, type FundQuote, type GetAllAShareQuotesOptions, type HKQuote, type HKUSHistoryKline, type HistoryKline, type IndicatorOptions, type KDJOptions, type KlineWithIndicators, type MACDOptions, type MAOptions, type MarketType, type MinuteKline, type MinuteTimeline, type PanelLargeOrder, type RSIOptions, type SimpleQuote, StockSDK, type TodayTimeline, type TodayTimelineResponse, type USQuote, type WROptions, addIndicators, asyncPool, calcATR, calcBIAS, calcBOLL, calcCCI, calcEMA, calcKDJ, calcMA, calcMACD, calcRSI, calcSMA, calcWMA, calcWR, chunkArray, decodeGBK, StockSDK as default, parseResponse, safeNumber, safeNumberOrNull };