stock-sdk 1.4.5 → 1.6.0

package/dist/index.d.cts

@@ -625,11 +625,69 @@ interface SearchResult {
     /** 资产类别 (GP-A/GP/KJ 等) */
     type: string;
 }
+/**
+ * 分红派送详情
+ */
+interface DividendDetail {
+    /** 股票代码 */
+    code: string;
+    /** 股票名称 */
+    name: string;
+    /** 报告期 YYYY-MM-DD */
+    reportDate: string | null;
+    /** 预案公告日 YYYY-MM-DD */
+    planNoticeDate: string | null;
+    /** 业绩披露日期 YYYY-MM-DD */
+    disclosureDate: string | null;
+    /** 送转总比例（每10股送转X股） */
+    assignTransferRatio: number | null;
+    /** 送股比例（每10股送X股） */
+    bonusRatio: number | null;
+    /** 转股比例（每10股转X股） */
+    transferRatio: number | null;
+    /** 每10股派息(税前)，单位：元 */
+    dividendPretax: number | null;
+    /** 分红描述（如：10派2.36元(含税,扣税后2.124元)） */
+    dividendDesc: string | null;
+    /** 股息率 */
+    dividendYield: number | null;
+    /** 每股收益(元) */
+    eps: number | null;
+    /** 每股净资产(元) */
+    bps: number | null;
+    /** 每股公积金(元) */
+    capitalReserve: number | null;
+    /** 每股未分配利润(元) */
+    unassignedProfit: number | null;
+    /** 净利润同比增长(%) */
+    netProfitYoy: number | null;
+    /** 总股本(股) */
+    totalShares: number | null;
+    /** 股权登记日 YYYY-MM-DD */
+    equityRecordDate: string | null;
+    /** 除权除息日 YYYY-MM-DD */
+    exDividendDate: string | null;
+    /** 现金分红发放日 YYYY-MM-DD */
+    payDate: string | null;
+    /** 方案进度（如：实施分配、股东大会预案等） */
+    assignProgress: string | null;
+    /** 最新公告日期 YYYY-MM-DD */
+    noticeDate: string | null;
+}
 
 /**
  * 腾讯财经 - 批量操作
  */
 
+/**
+ * A 股市场/板块类型
+ * - sh: 上交所（6 开头）
+ * - sz: 深交所（0 和 3 开头，包含创业板）
+ * - bj: 北交所（92 开头）
+ * - kc: 科创板（688 开头）
+ * - cy: 创业板（30 开头）
+ */
+type AShareMarket = 'sh' | 'sz' | 'bj' | 'kc' | 'cy';
 /**
  * 获取全部 A 股行情的配置选项
  */
@@ -640,6 +698,62 @@ interface GetAllAShareQuotesOptions {
     concurrency?: number;
     /** 进度回调函数 */
     onProgress?: (completed: number, total: number) => void;
+    /**
+     * 筛选特定的交易所或板块
+     * - 不传或 undefined: 返回全部 A 股
+     * - 'sh': 上交所（6 开头，包含科创板）
+     * - 'sz': 深交所（0 和 3 开头，包含创业板）
+     * - 'bj': 北交所（92 开头）
+     * - 'kc': 科创板（688 开头）
+     * - 'cy': 创业板（30 开头）
+     */
+    market?: AShareMarket;
+}
+/**
+ * 获取全部美股行情的配置选项
+ */
+interface GetAllUSQuotesOptions {
+    /** 单次请求的股票数量，默认 500 */
+    batchSize?: number;
+    /** 最大并发请求数，默认 7 */
+    concurrency?: number;
+    /** 进度回调函数 */
+    onProgress?: (completed: number, total: number) => void;
+    /**
+     * 筛选特定市场
+     * - 'NASDAQ': 纳斯达克 (105)
+     * - 'NYSE': 纽交所 (106)
+     * - 'AMEX': 美交所 (107)
+     */
+    market?: USMarket;
+}
+/**
+ * 获取 A 股代码列表的配置选项
+ */
+interface GetAShareCodeListOptions {
+    /**
+     * 是否返回简化的代码（不含交易所前缀）
+     * - false（默认）: 返回带前缀的完整代码，如 'sh600000', 'sz000001'
+     * - true: 返回纯数字代码，如 '600000', '000001'
+     */
+    simple?: boolean;
+    /**
+     * 筛选特定的交易所或板块
+     * - 不传或 undefined: 返回全部 A 股
+     * - 'sh': 上交所（6 开头，包含科创板）
+     * - 'sz': 深交所（0 和 3 开头，包含创业板）
+     * - 'bj': 北交所（92 开头）
+     * - 'kc': 科创板（688 开头）
+     * - 'cy': 创业板（30 开头）
+     */
+    market?: AShareMarket;
+}
+type USMarket = 'NASDAQ' | 'NYSE' | 'AMEX';
+interface GetUSCodeListOptions {
+    /** 是否移除市场前缀，默认 false */
+    simple?: boolean;
+    /** 筛选特定市场 */
+    market?: USMarket;
 }
 
 /**
@@ -852,6 +966,80 @@ interface ATRResult {
     /** 平均真实波幅 */
     atr: number | null;
 }
+interface OBVOptions$1 {
+    /** OBV 均线周期 */
+    maPeriod?: number;
+}
+interface OBVResult$1 {
+    /** OBV 值 */
+    obv: number | null;
+    /** OBV 均线 */
+    obvMa: number | null;
+}
+interface ROCOptions$1 {
+    /** ROC 周期，默认 12 */
+    period?: number;
+    /** 信号线周期 */
+    signalPeriod?: number;
+}
+interface ROCResult$1 {
+    /** ROC 值（百分比） */
+    roc: number | null;
+    /** 信号线 */
+    signal: number | null;
+}
+interface DMIOptions$1 {
+    /** 周期，默认 14 */
+    period?: number;
+    /** ADX 平滑周期 */
+    adxPeriod?: number;
+}
+interface DMIResult$1 {
+    /** +DI 值 */
+    pdi: number | null;
+    /** -DI 值 */
+    mdi: number | null;
+    /** ADX 值 */
+    adx: number | null;
+    /** ADXR 值 */
+    adxr: number | null;
+}
+interface SAROptions$1 {
+    /** 加速因子初始值，默认 0.02 */
+    afStart?: number;
+    /** 加速因子增量，默认 0.02 */
+    afIncrement?: number;
+    /** 加速因子最大值，默认 0.2 */
+    afMax?: number;
+}
+interface SARResult$1 {
+    /** SAR 值 */
+    sar: number | null;
+    /** 趋势方向：1 上升，-1 下降 */
+    trend: 1 | -1 | null;
+    /** 极值点 */
+    ep: number | null;
+    /** 加速因子 */
+    af: number | null;
+}
+interface KCOptions$1 {
+    /** EMA 周期，默认 20 */
+    emaPeriod?: number;
+    /** ATR 周期，默认 10 */
+    atrPeriod?: number;
+    /** ATR 倍数，默认 2 */
+    multiplier?: number;
+}
+interface KCResult$1 {
+    /** 中轨（EMA） */
+    mid: number | null;
+    /** 上轨 */
+    upper: number | null;
+    /** 下轨 */
+    lower: number | null;
+    /** 通道宽度 */
+    width: number | null;
+}
 
 /**
  * 计算简单移动平均线 SMA
@@ -941,6 +1129,245 @@ declare function calcCCI(data: OHLCV[], options?: CCIOptions): CCIResult[];
  */
 declare function calcATR(data: OHLCV[], options?: ATROptions): ATRResult[];
 
+/**
+ * OBV - On Balance Volume（能量潮）
+ * 通过成交量的累积来判断股价走势
+ */
+
+/**
+ * OBV 配置选项
+ */
+interface OBVOptions {
+    /** OBV 均线周期，默认不计算 */
+    maPeriod?: number;
+}
+/**
+ * OBV 计算结果
+ */
+interface OBVResult {
+    /** OBV 值 */
+    obv: number | null;
+    /** OBV 均线（如果配置了 maPeriod） */
+    obvMa: number | null;
+}
+/**
+ * 计算 OBV（能量潮）
+ *
+ * @description
+ * OBV 是一个累积指标，通过比较当日收盘价与前一日收盘价来确定成交量的正负：
+ * - 当日收盘价 > 前日收盘价：OBV = 前日 OBV + 当日成交量
+ * - 当日收盘价 < 前日收盘价：OBV = 前日 OBV - 当日成交量
+ * - 当日收盘价 = 前日收盘价：OBV = 前日 OBV
+ *
+ * @param data K 线数据数组
+ * @param options 配置选项
+ * @returns OBV 结果数组
+ *
+ * @example
+ * const obv = calcOBV(klines);
+ * console.log(obv[10].obv); // OBV 值
+ */
+declare function calcOBV(data: OHLCV[], options?: OBVOptions): OBVResult[];
+
+/**
+ * ROC - Rate of Change（变动率指标）
+ * 衡量价格变化的速度和幅度
+ */
+
+/**
+ * ROC 配置选项
+ */
+interface ROCOptions {
+    /** ROC 周期，默认 12 */
+    period?: number;
+    /** 信号线周期，默认不计算 */
+    signalPeriod?: number;
+}
+/**
+ * ROC 计算结果
+ */
+interface ROCResult {
+    /** ROC 值（百分比） */
+    roc: number | null;
+    /** ROC 的 MA 信号线 */
+    signal: number | null;
+}
+/**
+ * 计算 ROC（变动率指标）
+ *
+ * @description
+ * ROC = (当日收盘价 - N 日前收盘价) / N 日前收盘价 × 100
+ *
+ * 信号解读：
+ * - ROC 由负转正：买入信号
+ * - ROC 由正转负：卖出信号
+ * - ROC 与价格背离：可能的反转信号
+ *
+ * @param data K 线数据数组
+ * @param options 配置选项
+ * @returns ROC 结果数组
+ *
+ * @example
+ * const roc = calcROC(klines, { period: 12 });
+ * console.log(roc[20].roc); // ROC 值
+ */
+declare function calcROC(data: OHLCV[], options?: ROCOptions): ROCResult[];
+
+/**
+ * DMI/ADX - Directional Movement Index（趋向指标）
+ * 判断趋势的方向和强度
+ */
+
+/**
+ * DMI 配置选项
+ */
+interface DMIOptions {
+    /** 周期，默认 14 */
+    period?: number;
+    /** ADX 平滑周期，默认与 period 相同 */
+    adxPeriod?: number;
+}
+/**
+ * DMI 计算结果
+ */
+interface DMIResult {
+    /** +DI 值 */
+    pdi: number | null;
+    /** -DI 值 */
+    mdi: number | null;
+    /** ADX 值（趋势强度） */
+    adx: number | null;
+    /** ADXR 值（ADX 的平均） */
+    adxr: number | null;
+}
+/**
+ * 计算 DMI/ADX（趋向指标）
+ *
+ * @description
+ * DMI 包含三个指标：
+ * - +DI：上升方向指标
+ * - -DI：下降方向指标
+ * - ADX：平均趋向指数，衡量趋势强度
+ *
+ * 信号解读：
+ * - +DI > -DI：上升趋势
+ * - -DI > +DI：下降趋势
+ * - ADX > 25：趋势明显
+ * - ADX < 20：横盘整理
+ *
+ * @param data K 线数据数组
+ * @param options 配置选项
+ * @returns DMI 结果数组
+ *
+ * @example
+ * const dmi = calcDMI(klines, { period: 14 });
+ * console.log(dmi[20].pdi);  // +DI
+ * console.log(dmi[20].mdi);  // -DI
+ * console.log(dmi[20].adx);  // ADX
+ */
+declare function calcDMI(data: OHLCV[], options?: DMIOptions): DMIResult[];
+
+/**
+ * SAR - Parabolic SAR（抛物线转向指标）
+ * 判断趋势反转点和止损位
+ */
+
+/**
+ * SAR 配置选项
+ */
+interface SAROptions {
+    /** 加速因子初始值，默认 0.02 */
+    afStart?: number;
+    /** 加速因子增量，默认 0.02 */
+    afIncrement?: number;
+    /** 加速因子最大值，默认 0.2 */
+    afMax?: number;
+}
+/**
+ * SAR 计算结果
+ */
+interface SARResult {
+    /** SAR 值 */
+    sar: number | null;
+    /** 当前趋势：1 为上升，-1 为下降 */
+    trend: 1 | -1 | null;
+    /** 极值点 */
+    ep: number | null;
+    /** 加速因子 */
+    af: number | null;
+}
+/**
+ * 计算 SAR（抛物线转向指标）
+ *
+ * @description
+ * Parabolic SAR 用于确定价格的趋势方向和潜在的反转点：
+ * - 当价格在 SAR 之上时，SAR 在价格下方，表示上升趋势
+ * - 当价格在 SAR 之下时，SAR 在价格上方，表示下降趋势
+ * - SAR 可用作动态止损位
+ *
+ * @param data K 线数据数组
+ * @param options 配置选项
+ * @returns SAR 结果数组
+ *
+ * @example
+ * const sar = calcSAR(klines);
+ * console.log(sar[20].sar);   // SAR 值
+ * console.log(sar[20].trend); // 趋势方向
+ */
+declare function calcSAR(data: OHLCV[], options?: SAROptions): SARResult[];
+
+/**
+ * KC - Keltner Channel（肯特纳通道）
+ * 基于 ATR 的价格通道指标
+ */
+
+/**
+ * KC 配置选项
+ */
+interface KCOptions {
+    /** EMA 周期，默认 20 */
+    emaPeriod?: number;
+    /** ATR 周期，默认 10 */
+    atrPeriod?: number;
+    /** ATR 倍数，默认 2 */
+    multiplier?: number;
+}
+/**
+ * KC 计算结果
+ */
+interface KCResult {
+    /** 中轨（EMA） */
+    mid: number | null;
+    /** 上轨 */
+    upper: number | null;
+    /** 下轨 */
+    lower: number | null;
+    /** 通道宽度 */
+    width: number | null;
+}
+/**
+ * 计算 KC（肯特纳通道）
+ *
+ * @description
+ * Keltner Channel 是一个基于 ATR 的价格通道：
+ * - 中轨 = EMA(close, period)
+ * - 上轨 = 中轨 + multiplier × ATR
+ * - 下轨 = 中轨 - multiplier × ATR
+ *
+ * 与布林带相比，KC 使用 ATR 而非标准差，对价格变化反应更平滑。
+ *
+ * @param data K 线数据数组
+ * @param options 配置选项
+ * @returns KC 结果数组
+ *
+ * @example
+ * const kc = calcKC(klines, { emaPeriod: 20, multiplier: 2 });
+ * console.log(kc[30].upper); // 上轨
+ * console.log(kc[30].mid);   // 中轨
+ * console.log(kc[30].lower); // 下轨
+ */
+declare function calcKC(data: OHLCV[], options?: KCOptions): KCResult[];
+
 /**
  * 带技术指标的 K 线数据
  */
@@ -1097,20 +1524,69 @@ declare class StockSDK {
     search(keyword: string): Promise<SearchResult[]>;
     /**
      * 从远程获取 A 股代码列表
-     * @param includeExchange 是否包含交易所前缀（如 sh、sz、bj），默认 true
+     * @param options 配置选项
+     *
+     * @example
+     * // 获取全部 A 股（带交易所前缀）
+     * const codes = await sdk.getAShareCodeList();
+     *
+     * @example
+     * // 获取全部 A 股（不带交易所前缀）
+     * const codes = await sdk.getAShareCodeList({ simple: true });
+     *
+     * @example
+     * // 获取科创板股票
+     * const codes = await sdk.getAShareCodeList({ market: 'kc' });
+     *
+     * @example
+     * // 获取创业板股票（不带前缀）
+     * const codes = await sdk.getAShareCodeList({ simple: true, market: 'cy' });
      */
-    getAShareCodeList(includeExchange?: boolean): Promise<string[]>;
+    getAShareCodeList(options?: GetAShareCodeListOptions | boolean): Promise<string[]>;
     /**
      * 从远程获取美股代码列表
-     * @param includeMarket 是否包含市场前缀（如 105.、106.），默认 true
+     * @param options 配置选项
+     *
+     * @example
+     * // 获取全部美股（带市场前缀）
+     * const codes = await sdk.getUSCodeList();
+     * // ['105.AAPL', '106.BABA', ...]
+     *
+     * @example
+     * // 获取全部美股（不带市场前缀）
+     * const codes = await sdk.getUSCodeList({ simple: true });
+     * // ['AAPL', 'BABA', ...]
+     *
+     * @example
+     * // 筛选纳斯达克股票
+     * const codes = await sdk.getUSCodeList({ market: 'NASDAQ' });
+     * // ['105.AAPL', ...]
+     *
+     * @example
+     * // 筛选纽交所股票
+     * const codes = await sdk.getUSCodeList({ market: 'NYSE' });
+     * // ['106.BABA', ...]
      */
-    getUSCodeList(includeMarket?: boolean): Promise<string[]>;
+    getUSCodeList(options?: GetUSCodeListOptions | boolean): Promise<string[]>;
     /**
      * 从远程获取港股代码列表
      */
     getHKCodeList(): Promise<string[]>;
     /**
      * 获取全部 A 股实时行情
+     * @param options 配置选项
+     *
+     * @example
+     * // 获取全部 A 股行情
+     * const quotes = await sdk.getAllAShareQuotes();
+     *
+     * @example
+     * // 获取科创板行情
+     * const kcQuotes = await sdk.getAllAShareQuotes({ market: 'kc' });
+     *
+     * @example
+     * // 获取创业板行情
+     * const cyQuotes = await sdk.getAllAShareQuotes({ market: 'cy' });
      */
     getAllAShareQuotes(options?: GetAllAShareQuotesOptions): Promise<FullQuote[]>;
     /**
@@ -1119,8 +1595,24 @@ declare class StockSDK {
     getAllHKShareQuotes(options?: GetAllAShareQuotesOptions): Promise<HKQuote[]>;
     /**
      * 获取全部美股实时行情
+     * @param options 配置选项
+     *
+     * @example
+     * // 获取全部美股行情
+     * const quotes = await sdk.getAllUSShareQuotes();
+     *
+     * @example
+     * // 获取纳斯达克股票行情
+     * const nasdaqQuotes = await sdk.getAllUSShareQuotes({ market: 'NASDAQ' });
+     *
+     * @example
+     * // 获取纽交所股票行情（带进度回调）
+     * const nyseQuotes = await sdk.getAllUSShareQuotes({
+     *   market: 'NYSE',
+     *   onProgress: (completed, total) => console.log(`${completed}/${total}`)
+     * });
      */
-    getAllUSShareQuotes(options?: GetAllAShareQuotesOptions): Promise<USQuote[]>;
+    getAllUSShareQuotes(options?: GetAllUSQuotesOptions): Promise<USQuote[]>;
     /**
      * 获取全部股票实时行情（使用自定义股票代码列表）
      */
@@ -1138,6 +1630,17 @@ declare class StockSDK {
      * @returns 交易日期字符串数组，格式如 ['1990-12-19', '1990-12-20', ...]
      */
     getTradingCalendar(): Promise<string[]>;
+    /**
+     * 获取股票分红派送详情
+     * @param symbol - 股票代码（纯数字或带交易所前缀），如 '600519' 或 'sh600519'
+     * @returns 分红派送详情列表，按报告日期降序排列
+     *
+     * @example
+     * // 获取贵州茅台的分红历史
+     * const dividends = await sdk.getDividendDetail('600519');
+     * console.log(dividends[0].dividendPretax); // 每10股派息(税前)
+     */
+    getDividendDetail(symbol: string): Promise<DividendDetail[]>;
     /**
      * 市场类型识别
      */
@@ -1189,4 +1692,4 @@ declare class StockSDK {
     }): Promise<KlineWithIndicators<HistoryKline | HKUSHistoryKline>[]>;
 }
 
-export { type ATROptions, type BIASOptions, type BOLLOptions, type CCIOptions, type ConceptBoard, type ConceptBoardConstituent, type ConceptBoardKline, type ConceptBoardKlineOptions, type ConceptBoardMinuteKline, type ConceptBoardMinuteKlineOptions, type ConceptBoardMinuteTimeline, type ConceptBoardSpot, type FullQuote, type FundFlow, type FundQuote, type GetAllAShareQuotesOptions, type HKQuote, type HKUSHistoryKline, type HistoryKline, HttpError, type IndicatorOptions, type IndustryBoard, type IndustryBoardConstituent, type IndustryBoardKline, type IndustryBoardKlineOptions, type IndustryBoardMinuteKline, type IndustryBoardMinuteKlineOptions, type IndustryBoardMinuteTimeline, type IndustryBoardSpot, type KDJOptions, type KlineWithIndicators, type MACDOptions, type MAOptions, type MarketType, type MinuteKline, type MinuteTimeline, type PanelLargeOrder, type RSIOptions, type RequestClientOptions, type RetryOptions, type SearchResult, 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 };
+export { type AShareMarket, type ATROptions, type BIASOptions, type BOLLOptions, type CCIOptions, 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 DividendDetail, type FullQuote, type FundFlow, type FundQuote, type GetAShareCodeListOptions, type GetAllAShareQuotesOptions, type HKQuote, type HKUSHistoryKline, type HistoryKline, HttpError, type IndicatorOptions, type IndustryBoard, type IndustryBoardConstituent, type IndustryBoardKline, type IndustryBoardKlineOptions, type IndustryBoardMinuteKline, type IndustryBoardMinuteKlineOptions, type IndustryBoardMinuteTimeline, type IndustryBoardSpot, type KCOptions$1 as KCOptions, type KCResult$1 as KCResult, type KDJOptions, type KlineWithIndicators, type MACDOptions, type MAOptions, type MarketType, type MinuteKline, type MinuteTimeline, type OBVOptions$1 as OBVOptions, type OBVResult$1 as OBVResult, type PanelLargeOrder, type ROCOptions$1 as ROCOptions, type ROCResult$1 as ROCResult, type RSIOptions, type RequestClientOptions, type RetryOptions, type SAROptions$1 as SAROptions, type SARResult$1 as SARResult, type SearchResult, type SimpleQuote, StockSDK, type TodayTimeline, type TodayTimelineResponse, type USQuote, type WROptions, addIndicators, asyncPool, calcATR, calcBIAS, calcBOLL, calcCCI, calcDMI, calcEMA, calcKC, calcKDJ, calcMA, calcMACD, calcOBV, calcROC, calcRSI, calcSAR, calcSMA, calcWMA, calcWR, chunkArray, decodeGBK, StockSDK as default, parseResponse, safeNumber, safeNumberOrNull };