@tigeropenapi/tigeropen 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 老虎证券 OpenAPI TypeScript SDK
+ *
+ * 本 SDK 提供行情查询、交易下单、账户管理和实时推送等功能，
+ * 与 Python SDK 保持功能对等，遵循 TypeScript 最佳实践。
+ *
+ * 分层架构：
+ * - 模型层（model）：Contract、Order、Position 等数据模型和枚举
+ * - 配置层（config）：ClientConfig、ConfigParser
+ * - 认证层（signer）：RSA 签名
+ * - 传输层（client）：HttpClient、重试策略
+ * - 业务层（quote/trade）：QuoteClient、TradeClient
+ * - 推送层（push）：PushClient
+ *
+ * @packageDocumentation
+ */
+/** SDK 版本号 */
+export declare const VERSION = "0.1.0";

package/dist/types/logger/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 日志模块导出
+ */
+export * from './logger';

package/dist/types/logger/logger.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Logger - 日志接口和默认实现
+ *
+ * 定义 Logger 接口，支持注入自定义 logger 对象。
+ * 默认实现使用 console 输出。
+ */
+/** 日志级别 */
+export declare enum LogLevel {
+    Debug = 0,
+    Info = 1,
+    Warn = 2,
+    Error = 3
+}
+/** 日志接口 */
+export interface Logger {
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    setLevel(level: LogLevel): void;
+}
+/** 默认日志实现，使用 console 输出 */
+export declare class DefaultLogger implements Logger {
+    private level;
+    setLevel(level: LogLevel): void;
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+/** 空日志实现，不输出任何内容 */
+export declare class NopLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+    setLevel(): void;
+}
+/** 设置全局默认 logger */
+export declare function setDefaultLogger(logger: Logger): void;
+/** 获取全局默认 logger */
+export declare function getDefaultLogger(): Logger;

package/dist/types/model/contract-helpers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 合约构造工具函数
+ */
+import type { Contract } from './contract';
+/** 构造股票合约 */
+export declare function stockContract(symbol: string, currency: string): Contract;
+/** 通过 identifier 构造期权合约 */
+export declare function optionContract(identifier: string): Contract;
+/** 通过各字段构造期权合约 */
+export declare function optionContractBySymbol(symbol: string, expiry: string, strike: number, right: string, currency: string): Contract;
+/** 构造期货合约 */
+export declare function futureContract(symbol: string, currency: string, expiry: string): Contract;
+/** 构造外汇合约 */
+export declare function cashContract(symbol: string): Contract;
+/** 构造基金合约 */
+export declare function fundContract(symbol: string, currency: string): Contract;
+/** 构造窝轮合约 */
+export declare function warrantContract(symbol: string, currency: string, expiry: string, strike: number, right: string): Contract;

package/dist/types/model/contract.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Contract 合约接口
+ * 字段名 camelCase 与 API JSON 天然一致，不改名、不加封装层
+ */
+/** 最小报价单位价格区间 */
+export interface TickSize {
+    /** 起始价格（字符串，如 "0"、"1"） */
+    begin?: string;
+    /** 结束价格（字符串，如 "1"、"Infinity"） */
+    end?: string;
+    /** 最小报价单位 */
+    tickSize?: number;
+    /** 类型（CLOSED/OPEN） */
+    type?: string;
+}
+/** 合约模型，字段名词根保持与 API JSON 一致 */
+export interface Contract {
+    /** 合约 ID */
+    contractId?: number;
+    /** 标的代码（如 AAPL） */
+    symbol: string;
+    /** 证券类型（STK/OPT/FUT/WAR/CASH/FUND 等） */
+    secType: string;
+    /** 货币 */
+    currency?: string;
+    /** 交易所 */
+    exchange?: string;
+    /** 到期日（期权/期货） */
+    expiry?: string;
+    /** 行权价（期权） */
+    strike?: number;
+    /** 看涨/看跌（PUT/CALL），保持 API 原始名 right，不改为 putCall */
+    right?: string;
+    /** 合约乘数 */
+    multiplier?: number;
+    /** 合约标识符 */
+    identifier?: string;
+    /** 合约名称 */
+    name?: string;
+    /** 市场 */
+    market?: string;
+    /** 是否可交易，保持 API 原始名 tradeable，不改为 trade */
+    tradeable?: boolean;
+    /** 合约内部 ID，保持 API 原始名 conid，不改为 contractId */
+    conid?: number;
+    /** 做空保证金比例 */
+    shortMargin?: number;
+    /** 做空初始保证金比例 */
+    shortInitialMargin?: number;
+    /** 做空维持保证金比例 */
+    shortMaintenanceMargin?: number;
+    /** 做多初始保证金 */
+    longInitialMargin?: number;
+    /** 做多维持保证金 */
+    longMaintenanceMargin?: number;
+    /** 最小报价单位价格区间 */
+    tickSizes?: TickSize[];
+    /** 每手数量 */
+    lotSize?: number;
+}

package/dist/types/model/enums.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 枚举类型定义
+ * 所有枚举值与 API JSON 保持一致
+ */
+/** 市场枚举 */
+export declare enum Market {
+    All = "ALL",
+    US = "US",
+    HK = "HK",
+    CN = "CN",
+    SG = "SG"
+}
+/** 证券类型枚举 */
+export declare enum SecurityType {
+    All = "ALL",
+    STK = "STK",
+    OPT = "OPT",
+    WAR = "WAR",
+    IOPT = "IOPT",
+    FUT = "FUT",
+    FOP = "FOP",
+    CASH = "CASH",
+    MLEG = "MLEG",
+    FUND = "FUND"
+}
+/** 货币枚举 */
+export declare enum Currency {
+    All = "ALL",
+    USD = "USD",
+    HKD = "HKD",
+    CNH = "CNH",
+    SGD = "SGD"
+}
+/** 订单类型枚举 */
+export declare enum OrderType {
+    MKT = "MKT",
+    LMT = "LMT",
+    STP = "STP",
+    STP_LMT = "STP_LMT",
+    TRAIL = "TRAIL",
+    AM = "AM",
+    AL = "AL",
+    TWAP = "TWAP",
+    VWAP = "VWAP",
+    OCA = "OCA"
+}
+/** 订单状态枚举 */
+export declare enum OrderStatus {
+    PendingNew = "PendingNew",
+    Initial = "Initial",
+    Submitted = "Submitted",
+    PartiallyFilled = "PartiallyFilled",
+    Filled = "Filled",
+    Cancelled = "Cancelled",
+    PendingCancel = "PendingCancel",
+    Inactive = "Inactive",
+    Invalid = "Invalid"
+}
+/** K 线周期枚举 */
+export declare enum BarPeriod {
+    Day = "day",
+    Week = "week",
+    Month = "month",
+    Year = "year",
+    Min1 = "1min",
+    Min5 = "5min",
+    Min15 = "15min",
+    Min30 = "30min",
+    Min60 = "60min"
+}
+/** 语言枚举 */
+export declare enum Language {
+    ZhCN = "zh_CN",
+    ZhTW = "zh_TW",
+    EnUS = "en_US"
+}
+/** 复权类型枚举 */
+export declare enum QuoteRight {
+    /** 前复权 */
+    Br = "br",
+    /** 不复权 */
+    Nr = "nr"
+}
+/** 牌照类型枚举 */
+export declare enum License {
+    TBNZ = "TBNZ",
+    TBSG = "TBSG",
+    TBHK = "TBHK",
+    TBAU = "TBAU",
+    TBUS = "TBUS"
+}
+/** 订单有效期枚举 */
+export declare enum TimeInForce {
+    DAY = "DAY",
+    GTC = "GTC",
+    OPG = "OPG"
+}

package/dist/types/model/order-helpers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 订单构造工具函数
+ */
+import type { Order, OrderLeg, AlgoParams } from './order';
+/** 构造市价单 */
+export declare function marketOrder(account: string, symbol: string, secType: string, action: string, quantity: number): Order;
+/** 构造限价单 */
+export declare function limitOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number): Order;
+/** 构造止损单 */
+export declare function stopOrder(account: string, symbol: string, secType: string, action: string, quantity: number, auxPrice: number): Order;
+/** 构造止损限价单 */
+export declare function stopLimitOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number, auxPrice: number): Order;
+/** 构造跟踪止损单 */
+export declare function trailOrder(account: string, symbol: string, secType: string, action: string, quantity: number, trailingPercent: number): Order;
+/** 构造竞价限价单 */
+export declare function auctionLimitOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number): Order;
+/** 构造竞价市价单 */
+export declare function auctionMarketOrder(account: string, symbol: string, secType: string, action: string, quantity: number): Order;
+/** 构造算法订单（TWAP/VWAP） */
+export declare function algoOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number, algoType: string, params: AlgoParams): Order;
+/** 构造附加订单（止盈/止损） */
+export declare function orderLeg(legType: string, price: number, timeInForce: string): OrderLeg;

package/dist/types/model/order.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Order 订单接口
+ * 字段名 camelCase 与 API JSON 天然一致，不改名、不加封装层
+ */
+/** 附加订单（止盈/止损） */
+export interface OrderLeg {
+    /** 附加订单类型（PROFIT/LOSS） */
+    legType?: string;
+    /** 价格 */
+    price?: number;
+    /** 有效期 */
+    timeInForce?: string;
+    /** 数量 */
+    quantity?: number;
+}
+/** 算法订单参数 */
+export interface AlgoParams {
+    /** 算法策略（TWAP/VWAP） */
+    algoStrategy?: string;
+    /** 开始时间 */
+    startTime?: string;
+    /** 结束时间 */
+    endTime?: string;
+    /** 参与率 */
+    participationRate?: number;
+}
+/** 订单模型，字段名词根保持与 API JSON 一致 */
+export interface Order {
+    /** 交易账户 */
+    account: string;
+    /** 全局订单 ID */
+    id?: number;
+    /** 账户自增订单号 */
+    orderId?: number;
+    /** 买卖方向（BUY/SELL） */
+    action: string;
+    /** 订单类型（MKT/LMT/STP/STP_LMT/TRAIL 等） */
+    orderType: string;
+    /** 总数量（API 返回字段名为 totalQuantity） */
+    totalQuantity: number;
+    /** 限价 */
+    limitPrice?: number;
+    /** 辅助价格（止损价） */
+    auxPrice?: number;
+    /** 跟踪止损百分比 */
+    trailingPercent?: number;
+    /** 订单状态 */
+    status?: string;
+    /** 已成交数量（API 返回字段名为 filledQuantity） */
+    filledQuantity?: number;
+    /** 平均成交价 */
+    avgFillPrice?: number;
+    /** 有效期（DAY/GTC/OPG） */
+    timeInForce: string;
+    /** 是否允许盘前盘后 */
+    outsideRth: boolean;
+    /** 附加订单（止盈/止损） */
+    orderLegs?: OrderLeg[];
+    /** 算法参数 */
+    algoParams?: AlgoParams;
+    /** 股票代码 */
+    symbol: string;
+    /** 合约类型 */
+    secType: string;
+    /** 市场 */
+    market?: string;
+    /** 货币 */
+    currency?: string;
+    /** 到期日（期权/期货） */
+    expiry?: string;
+    /** 行权价（期权），API 返回为字符串 */
+    strike?: string;
+    /** 看涨/看跌（PUT/CALL），保持 API 原始名 right */
+    right?: string;
+    /** 合约标识符 */
+    identifier?: string;
+    /** 合约名称 */
+    name?: string;
+    /** 佣金 */
+    commission?: number;
+    /** 已实现盈亏 */
+    realizedPnl?: number;
+    /** 开仓时间（毫秒时间戳） */
+    openTime?: number;
+    /** 更新时间（毫秒时间戳） */
+    updateTime?: number;
+    /** 最新时间（毫秒时间戳） */
+    latestTime?: number;
+    /** 备注 */
+    remark?: string;
+    /** 订单来源 */
+    source?: string;
+    /** 用户标记 */
+    userMark?: string;
+}

package/dist/types/model/position.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Position 持仓接口
+ * 字段名 camelCase 与 API JSON 天然一致，不改名、不加封装层
+ */
+/** 持仓模型，字段名词根保持与 API JSON 一致 */
+export interface Position {
+    /** 交易账户 */
+    account: string;
+    /** 标的代码 */
+    symbol: string;
+    /** 证券类型 */
+    secType: string;
+    /** 市场 */
+    market?: string;
+    /** 货币 */
+    currency?: string;
+    /** 持仓数量（API 返回字段名为 position） */
+    position: number;
+    /** 平均成本 */
+    averageCost: number;
+    /** 市值 */
+    marketValue?: number;
+    /** 已实现盈亏 */
+    realizedPnl?: number;
+    /** 未实现盈亏 */
+    unrealizedPnl?: number;
+    /** 未实现盈亏百分比 */
+    unrealizedPnlPercent?: number;
+    /** 合约 ID */
+    contractId?: number;
+    /** 合约标识符 */
+    identifier?: string;
+    /** 合约名称 */
+    name?: string;
+    /** 最新价格 */
+    latestPrice?: number;
+    /** 合约乘数 */
+    multiplier?: number;
+}

package/dist/types/push/callbacks.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 推送回调函数类型定义
+ *
+ * 每种推送类型独立回调，连接状态回调独立管理。
+ */
+import type { QuoteData, TickData, DepthData, KlineData, AssetData, PositionData, OrderData, TransactionData, SubjectType } from './push-message';
+/** 行情推送回调 */
+export type QuoteCallback = (data: QuoteData) => void;
+/** 逐笔成交推送回调 */
+export type TickCallback = (data: TickData) => void;
+/** 深度行情推送回调 */
+export type DepthCallback = (data: DepthData) => void;
+/** K 线推送回调 */
+export type KlineCallback = (data: KlineData) => void;
+/** 资产变动推送回调 */
+export type AssetCallback = (data: AssetData) => void;
+/** 持仓变动推送回调 */
+export type PositionCallback = (data: PositionData) => void;
+/** 订单状态推送回调 */
+export type OrderCallback = (data: OrderData) => void;
+/** 成交明细推送回调 */
+export type TransactionCallback = (data: TransactionData) => void;
+/** 连接成功回调 */
+export type ConnectCallback = () => void;
+/** 断开连接回调 */
+export type DisconnectCallback = () => void;
+/** 错误回调 */
+export type ErrorCallback = (err: Error) => void;
+/** 被踢出回调 */
+export type KickoutCallback = (message: string) => void;
+/** 订阅成功回调 */
+export type SubscribeCallback = (subject: SubjectType, symbols: string[]) => void;
+/** 退订成功回调 */
+export type UnsubscribeCallback = (subject: SubjectType, symbols: string[]) => void;
+/** 所有回调函数的集合 */
+export interface Callbacks {
+    onQuote?: QuoteCallback;
+    onTick?: TickCallback;
+    onDepth?: DepthCallback;
+    onOption?: QuoteCallback;
+    onFuture?: QuoteCallback;
+    onKline?: KlineCallback;
+    onStockTop?: QuoteCallback;
+    onOptionTop?: QuoteCallback;
+    onFullTick?: TickCallback;
+    onQuoteBBO?: QuoteCallback;
+    onAsset?: AssetCallback;
+    onPosition?: PositionCallback;
+    onOrder?: OrderCallback;
+    onTransaction?: TransactionCallback;
+    onConnect?: ConnectCallback;
+    onDisconnect?: DisconnectCallback;
+    onError?: ErrorCallback;
+    onKickout?: KickoutCallback;
+    onSubscribe?: SubscribeCallback;
+    onUnsubscribe?: UnsubscribeCallback;
+}

package/dist/types/push/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 推送模块导出
+ */
+export * from './push-message';
+export * from './callbacks';
+export { PushClient, ConnectionState } from './push-client';
+export type { PushClientOptions, WebSocketLike, WebSocketFactory } from './push-client';

package/dist/types/push/push-client.d.ts

@@ -0,0 +1,139 @@
+/**
+ * PushClient - WebSocket 推送客户端
+ *
+ * 通过 WebSocket 长连接接收实时行情和账户推送。
+ * 支持连接认证、订阅/退订、回调机制、心跳保活和自动重连。
+ */
+import type { ClientConfig } from '../config/client-config';
+import type { Callbacks } from './callbacks';
+import { SubjectType } from './push-message';
+/** 连接状态 */
+export declare enum ConnectionState {
+    Disconnected = 0,
+    Connecting = 1,
+    Connected = 2
+}
+/** PushClient 配置选项 */
+export interface PushClientOptions {
+    pushUrl?: string;
+    heartbeatInterval?: number;
+    reconnectInterval?: number;
+    autoReconnect?: boolean;
+    connectTimeout?: number;
+}
+/**
+ * WebSocket 接口，方便测试注入
+ */
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(): void;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev: unknown) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+}
+/** WebSocket 工厂函数类型 */
+export type WebSocketFactory = (url: string) => WebSocketLike;
+/**
+ * PushClient WebSocket 推送客户端
+ */
+export declare class PushClient {
+    private config;
+    private pushUrl;
+    private heartbeatInterval;
+    private reconnectInterval;
+    private autoReconnect;
+    private connectTimeout;
+    private ws;
+    private _state;
+    private callbacks;
+    /** 订阅状态管理：subject -> Set<symbol> */
+    private subscriptions;
+    /** 账户级别订阅 */
+    private accountSubs;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private stopped;
+    /** 可注入的 WebSocket 工厂（用于测试） */
+    wsFactory: WebSocketFactory | null;
+    constructor(config: ClientConfig, options?: PushClientOptions);
+    /** 获取当前连接状态 */
+    get state(): ConnectionState;
+    /** 设置回调函数集合 */
+    setCallbacks(cb: Callbacks): void;
+    /** 连接到推送服务器并进行认证 */
+    connect(): Promise<void>;
+    /** 断开连接 */
+    disconnect(): void;
+    /** 发送认证消息 */
+    private authenticate;
+    /** 发送消息 */
+    private sendMessage;
+    /** 创建 WebSocket 实例 */
+    private createWebSocket;
+    /** 心跳保活 */
+    private startHeartbeat;
+    private stopHeartbeat;
+    /** 自动重连 */
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    /** 重连后恢复订阅 */
+    private resubscribe;
+    /** 处理收到的消息 */
+    private handleMessage;
+    /** 内部订阅方法 */
+    private doSubscribe;
+    /** 内部退订方法 */
+    private doUnsubscribe;
+    /** 添加订阅记录 */
+    private addSubscription;
+    /** 移除订阅记录 */
+    private removeSubscription;
+    /** 订阅行情 */
+    subscribeQuote(symbols: string[]): void;
+    /** 退订行情 */
+    unsubscribeQuote(symbols?: string[]): void;
+    /** 订阅逐笔成交 */
+    subscribeTick(symbols: string[]): void;
+    /** 退订逐笔成交 */
+    unsubscribeTick(symbols?: string[]): void;
+    /** 订阅深度行情 */
+    subscribeDepth(symbols: string[]): void;
+    /** 退订深度行情 */
+    unsubscribeDepth(symbols?: string[]): void;
+    /** 订阅期权行情 */
+    subscribeOption(symbols: string[]): void;
+    /** 退订期权行情 */
+    unsubscribeOption(symbols?: string[]): void;
+    /** 订阅期货行情 */
+    subscribeFuture(symbols: string[]): void;
+    /** 退订期货行情 */
+    unsubscribeFuture(symbols?: string[]): void;
+    /** 订阅 K 线 */
+    subscribeKline(symbols: string[]): void;
+    /** 退订 K 线 */
+    unsubscribeKline(symbols?: string[]): void;
+    /** 订阅资产变动 */
+    subscribeAsset(account?: string): void;
+    /** 退订资产变动 */
+    unsubscribeAsset(): void;
+    /** 订阅持仓变动 */
+    subscribePosition(account?: string): void;
+    /** 退订持仓变动 */
+    unsubscribePosition(): void;
+    /** 订阅订单状态 */
+    subscribeOrder(account?: string): void;
+    /** 退订订单状态 */
+    unsubscribeOrder(): void;
+    /** 订阅成交明细 */
+    subscribeTransaction(account?: string): void;
+    /** 退订成交明细 */
+    unsubscribeTransaction(): void;
+    /** 获取当前行情订阅状态 */
+    getSubscriptions(): Map<SubjectType, string[]>;
+    /** 获取账户级别订阅状态 */
+    getAccountSubscriptions(): SubjectType[];
+}