stock-sdk 1.10.0 → 2.0.0-beta.0

package/dist/adapters-C0s5bM8O.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 统一符号模型类型（v2 A1）
+ *
+ * 设计要点：
+ * - `string` 是一等公民，`SymbolRef` 是「带提示的 string」（其 code 也走 normalizeSymbol）
+ * - `NormalizedSymbol` 是 SDK 内部唯一表示，各 provider 适配器只认它
+ */
+/** 交易区域 / 体系（GLOBAL = 海外期货/商品） */
+type Market = 'CN' | 'HK' | 'US' | 'GLOBAL';
+/** 资产类型 */
+type AssetType = 'stock' | 'index' | 'fund' | 'bond' | 'futures' | 'option' | 'board';
+/**
+ * 交易所 / 市场强判别字段。
+ * 股票：SSE/SZSE/BSE/HKEX/NASDAQ/NYSE/AMEX；
+ * 国内期货：SHFE/DCE/CZCE/INE/CFFEX/GFEX；海外期货：COMEX/NYMEX/CBOT/LME。
+ * 允许 string 兜底以容纳未来扩展。
+ */
+type Exchange = 'SSE' | 'SZSE' | 'BSE' | 'HKEX' | 'NASDAQ' | 'NYSE' | 'AMEX' | 'US' | 'SHFE' | 'DCE' | 'CZCE' | 'INE' | 'CFFEX' | 'GFEX' | 'COMEX' | 'NYMEX' | 'CBOT' | 'LME' | (string & {});
+/** 用户入参：裸 string，或「带提示的 string」对象 */
+interface SymbolRef {
+    code: string;
+    market?: Market;
+    assetType?: AssetType;
+    exchange?: Exchange;
+}
+/** SDK 内部统一表示 */
+interface NormalizedSymbol {
+    market: Market;
+    assetType: AssetType;
+    exchange: Exchange;
+    /** 纯代码，无前缀（如 '600519' / '00700' / 'AAPL' / 'IF2412'） */
+    code: string;
+    /** 期货品种（如 'IF' / 'RB'） */
+    variety?: string;
+    /** 原始入参，便于报错与调试 */
+    input: string;
+}
+/** API 接受的符号入参类型 */
+type SymbolInput = string | SymbolRef;
+
+declare function normalizeSymbol(input: SymbolInput, hint?: Partial<SymbolRef>): NormalizedSymbol;
+
+/**
+ * Provider 符号适配器：NormalizedSymbol → 各数据源原生格式（纯函数）
+ *
+ * 仅覆盖股票/指数/基金/板块这类有明确 secid 体系的资产；期货/期权的 secid
+ * 体系不同（且由各自 provider 内联处理），这里对它们显式抛错而非静默兜底，
+ * 避免把海外期货误拼成美股 secid（105.xxx）这类隐蔽错误。
+ */
+
+/**
+ * → 腾讯行情格式：sh600519 / sz000001 / bj920819 / hk00700 / usAAPL
+ */
+declare function toTencentSymbol(ns: NormalizedSymbol): string;
+/**
+ * → 东财 secid：1.600519 / 0.000001 / 116.00700 / 105.AAPL / 90.BK0475（板块）
+ */
+declare function toEastmoneySecid(ns: NormalizedSymbol): string;
+/** → 纯代码（去前缀） */
+declare function toPlainCode(ns: NormalizedSymbol): string;
+
+export { type AssetType as A, type Exchange as E, type Market as M, type NormalizedSymbol as N, type SymbolRef as S, type SymbolInput as a, toEastmoneySecid as b, toPlainCode as c, normalizeSymbol as n, toTencentSymbol as t };

package/dist/addIndicators-TPEcddTW.d.cts

@@ -0,0 +1,524 @@
+/**
+ * 时间元信息工具
+ *
+ * 给行情/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 毫秒时间戳。原始字符串无法解析时为 `null`。 */
+    timestamp: number | null;
+    /** 原始字符串对应的市场时区 (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;
+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 | null, tz: MarketTz): string;
+
+/**
+ * A 股历史 K 线（日/周/月）
+ */
+interface HistoryKline {
+    /** 日期 YYYY-MM-DD (A 股时区) */
+    date: string;
+    /** 当日 00:00 (`Asia/Shanghai`) 的 UTC 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number | null;
+    /** 日期所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
+    /** 股票代码 */
+    code: 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 股分时数据（1 分钟）
+ */
+interface MinuteTimeline {
+    /** 时间 YYYY-MM-DD HH:mm (A 股时区) */
+    time: string;
+    /** UTC 毫秒时间戳 (`Asia/Shanghai` 解释);无法解析时为 `NaN` */
+    timestamp: number | null;
+    /** 时间所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
+    /** 开盘价 */
+    open: number | null;
+    /** 收盘价 */
+    close: number | null;
+    /** 最高价 */
+    high: number | null;
+    /** 最低价 */
+    low: number | null;
+    /** 成交量 */
+    volume: number | null;
+    /** 成交额 */
+    amount: number | null;
+    /** 均价 */
+    avgPrice: number | null;
+}
+/**
+ * A 股分钟 K 线（5/15/30/60）
+ */
+interface MinuteKline {
+    /** 时间 YYYY-MM-DD HH:mm (A 股时区) */
+    time: string;
+    /** UTC 毫秒时间戳 (`Asia/Shanghai` 解释);无法解析时为 `NaN` */
+    timestamp: number | null;
+    /** 时间所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
+    /** 开盘价 */
+    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;
+}
+/**
+ * 当日分时项
+ */
+interface TodayTimeline {
+    /** 时间 HH:mm (A 股时区) */
+    time: string;
+    /**
+     * UTC 毫秒时间戳。由所属 `TodayTimelineResponse.date` 与 `time` 拼接后,
+     * 按 `Asia/Shanghai` 解释得到;无法解析时为 `NaN`。
+     */
+    timestamp: number | null;
+    /** 时间所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
+    /** 当前价 */
+    price: number;
+    /** 均价 */
+    avgPrice: number;
+    /** 累计成交量(股) */
+    volume: number;
+    /** 累计成交额(元) */
+    amount: number;
+}
+/**
+ * 当日分时响应
+ */
+interface TodayTimelineResponse {
+    /** 股票代码 */
+    code: string;
+    /** 交易日期 YYYY-MM-DD (A 股时区) */
+    date: string;
+    /** 交易日 00:00 (`Asia/Shanghai`) 的 UTC 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number | null;
+    /** 日期所属市场时区 (`Asia/Shanghai`) */
+    tz: MarketTz;
+    /**
+     * 昨收价
+     * - 由 SDK 解析腾讯接口的 `quoteFields[4]` 得到
+     * - 上游异常或接口未返回时可能为 `0` 或 `undefined`
+     */
+    preClose?: number;
+    /** 当日分时序列 */
+    data: TodayTimeline[];
+}
+/**
+ * 港股 / 美股历史 K 线公共字段。
+ *
+ * 内部基类,通常不直接使用。请用具体的 `HKHistoryKline` 或 `USHistoryKline`,
+ * 它们各自带本地化字段 (`currency` / `lotSize`)。
+ */
+interface ForeignHistoryKlineBase {
+    /** 日期 YYYY-MM-DD (市场本地时区) */
+    date: string;
+    /** UTC 毫秒时间戳;无法解析时为 `NaN` */
+    timestamp: number | null;
+    /** 股票代码 */
+    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;
+}
+/**
+ * 港股历史 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';
+}
+/**
+ * A 股 / 港股 / 美股历史 K 线的联合类型。
+ * 供指标计算等需要统一约束「任意市场历史 K 线」的通用逻辑使用。
+ */
+type AnyHistoryKline = HistoryKline | 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;
+}
+
+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;
+    obv?: OBVOptions | boolean;
+    roc?: ROCOptions | boolean;
+    dmi?: DMIOptions | boolean;
+    sar?: SAROptions | boolean;
+    kc?: KCOptions | 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;
+}
+interface OBVOptions {
+    /** OBV 均线周期 */
+    maPeriod?: number;
+}
+interface OBVResult {
+    /** OBV 值 */
+    obv: number | null;
+    /** OBV 均线 */
+    obvMa: number | null;
+}
+interface ROCOptions {
+    /** ROC 周期，默认 12 */
+    period?: number;
+    /** 信号线周期 */
+    signalPeriod?: number;
+}
+interface ROCResult {
+    /** ROC 值（百分比） */
+    roc: number | null;
+    /** 信号线 */
+    signal: number | null;
+}
+interface DMIOptions {
+    /** 周期，默认 14 */
+    period?: number;
+    /** ADX 平滑周期 */
+    adxPeriod?: number;
+}
+interface DMIResult {
+    /** +DI 值 */
+    pdi: number | null;
+    /** -DI 值 */
+    mdi: number | null;
+    /** ADX 值 */
+    adx: number | null;
+    /** ADXR 值 */
+    adxr: number | null;
+}
+interface SAROptions {
+    /** 加速因子初始值，默认 0.02 */
+    afStart?: number;
+    /** 加速因子增量，默认 0.02 */
+    afIncrement?: number;
+    /** 加速因子最大值，默认 0.2 */
+    afMax?: number;
+}
+interface SARResult {
+    /** SAR 值 */
+    sar: number | null;
+    /** 趋势方向：1 上升，-1 下降 */
+    trend: 1 | -1 | null;
+    /** 极值点 */
+    ep: number | null;
+    /** 加速因子 */
+    af: number | null;
+}
+interface KCOptions {
+    /** EMA 周期，默认 20 */
+    emaPeriod?: number;
+    /** ATR 周期，默认 10 */
+    atrPeriod?: number;
+    /** ATR 倍数，默认 2 */
+    multiplier?: number;
+}
+interface KCResult {
+    /** 中轨（EMA） */
+    mid: number | null;
+    /** 上轨 */
+    upper: number | null;
+    /** 下轨 */
+    lower: number | null;
+    /** 通道宽度 */
+    width: number | null;
+}
+
+/**
+ * 带技术指标的 K 线数据
+ */
+type KlineWithIndicators<T extends AnyHistoryKline> = T & {
+    ma?: MAResult;
+    macd?: MACDResult;
+    boll?: BOLLResult;
+    kdj?: KDJResult;
+    rsi?: RSIResult;
+    wr?: WRResult;
+    bias?: BIASResult;
+    cci?: CCIResult;
+    atr?: ATRResult;
+    obv?: OBVResult;
+    roc?: ROCResult;
+    dmi?: DMIResult;
+    sar?: SARResult;
+    kc?: KCResult;
+};
+/**
+ * 为 K 线数据添加技术指标
+ */
+declare function addIndicators<T extends AnyHistoryKline>(klines: T[], options?: IndicatorOptions): KlineWithIndicators<T>[];
+
+export { type AnyHistoryKline as A, type BOLLOptions as B, type CCIOptions as C, type DMIOptions as D, type USMinuteTimeline as E, type MAResult as F, type MACDResult as G, type HistoryKline as H, type IndicatorOptions as I, type BOLLResult as J, type KlineWithIndicators as K, type OHLCV as L, type MAOptions as M, type KDJResult as N, type OBVOptions as O, type RSIResult as P, type WRResult as Q, type RSIOptions as R, type SAROptions as S, type TimeMeta as T, type USHistoryKline as U, type BIASResult as V, type WROptions as W, type CCIResult as X, type ATRResult as Y, addIndicators as a, type MACDOptions as b, type KDJOptions as c, type BIASOptions as d, type ATROptions as e, type OBVResult as f, type ROCOptions as g, type ROCResult as h, type DMIResult as i, type SARResult as j, type KCOptions as k, type KCResult as l, MARKET_TZ as m, type MarketTz as n, buildTimeMeta as o, parseMarketTime as p, buildTimeMetaFromDateAndTime as q, formatInTz as r, type MinuteTimeline as s, type MinuteKline as t, type TodayTimeline as u, type TodayTimelineResponse as v, type HKHistoryKline as w, type HKMinuteKline as x, type HKMinuteTimeline as y, type USMinuteKline as z };