@tigeropenapi/tigeropen 0.1.0 → 0.3.0

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

@@ -1,22 +1,26 @@
 /**
- * HttpClient - HTTP 客户端
+ * HttpClient - HTTP client
  *
- * 封装 HTTP 请求、签名、重试、超时。
- * 使用 Node.js 内置 fetch（Node 18+）。
+ * Handles HTTP requests, signing, retry, and timeout.
+ * Uses Node.js built-in fetch (Node 18+).
  */
 import type { ClientConfig } from '../config/client-config';
 import { RetryPolicy } from './retry';
 import { type ApiResponse } from './api-response';
 import type { ApiRequest } from './api-request';
 /**
- * HttpClient 封装 HTTP 请求、签名、重试、超时
+ * HttpClient handles HTTP requests, signing, retry, and timeout
  */
 export declare class HttpClient {
     private config;
     private retryPolicy;
-    constructor(config: ClientConfig, retryPolicy?: RetryPolicy);
+    /** Override the target URL (used by quote client to hit quote server) */
+    private targetUrl;
+    constructor(config: ClientConfig, retryPolicy?: RetryPolicy, options?: {
+        useQuoteServerUrl?: boolean;
+    });
     /**
-     * 构造公共请求参数
+     * Build common request parameters
      */
     private buildCommonParams;
     /**
@@ -24,22 +28,30 @@ export declare class HttpClient {
      */
     private signParams;
     /**
-     * 发送 HTTP POST 请求
+     * Send HTTP POST request
      */
     private doHttpPost;
     /**
-     * 执行结构化 API 请求，返回解析后的 ApiResponse。
-     * 供 QuoteClient/TradeClient 内部使用。
+     * Execute a structured API request, returning a parsed ApiResponse.
+     * Used internally by QuoteClient/TradeClient.
      */
     executeRequest(request: ApiRequest): Promise<ApiResponse>;
     /**
-     * 通用 API 调用方法。
+     * General-purpose API call method.
      *
-     * @param apiMethod - API 方法名（如 "market_state"、"place_order"）
-     * @param requestJson - 原始 biz_content JSON 字符串
-     * @returns 原始 response JSON 字符串，不做任何解析
+     * @param apiMethod - API method name (e.g. "market_state", "place_order")
+     * @param requestJson - Raw biz_content JSON string
+     * @returns Raw response JSON string, unparsed
      */
     execute(apiMethod: string, requestJson: string): Promise<string>;
-    /** 延迟指定毫秒 */
+    /** Delay for the specified milliseconds */
     private sleep;
+    /**
+     * Verify the response signature using the tiger public key.
+     *
+     * @param timestamp - The timestamp sent in the request params
+     * @param signBase64 - The `sign` field from the response body
+     * @throws TigerError if the signature is missing or invalid
+     */
+    private verifyResponseSign;
 }

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

@@ -1,8 +1,9 @@
 /**
- * 传输层模块导出
+ * Transport layer exports.
  */
 export { HttpClient } from './http-client';
 export { TigerError, classifyErrorCode, type ErrorCategory } from './errors';
 export { RetryPolicy, defaultRetryPolicy, isTradeOperation } from './retry';
 export { type ApiRequest, createApiRequest } from './api-request';
-export { type ApiResponse, parseApiResponse } from './api-response';
+export { type ApiResponse, parseApiResponse, unmarshalData } from './api-response';
+export { camelToSnake, keysToSnakeCase } from './case-convert';

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

@@ -1,4 +1,4 @@
-/** 客户端配置接口 */
+/** Client configuration interface */
 export interface ClientConfig {
     tigerId: string;
     privateKey: string;
@@ -7,12 +7,16 @@ export interface ClientConfig {
     language: string;
     timezone?: string;
     timeout: number;
-    sandboxDebug: boolean;
     token?: string;
     tokenRefreshDuration?: number;
     serverUrl: string;
+    /** Quote server URL for quote-specific requests; falls back to serverUrl */
+    quoteServerUrl: string;
+    /** Device identifier (auto-detected MAC address) */
+    deviceId: string;
+    tigerPublicKey: string;
 }
-/** 创建配置时的选项参数 */
+/** Options for creating a client configuration */
 export interface ClientConfigOptions {
     tigerId?: string;
     privateKey?: string;
@@ -21,23 +25,35 @@ export interface ClientConfigOptions {
     language?: string;
     timezone?: string;
     timeout?: number;
-    sandboxDebug?: boolean;
     token?: string;
     tokenRefreshDuration?: number;
     serverUrl?: string;
-    /** 是否启用动态域名获取（默认 true） */
+    /** Explicit quote server URL; resolved dynamically if not set */
+    quoteServerUrl?: string;
+    /** Enable dynamic domain resolution (default: true) */
     enableDynamicDomain?: boolean;
-    /** properties 配置文件路径（同步读取） */
+    /** Explicit properties file path (synchronous read) */
     propertiesFilePath?: string;
 }
 /**
- * 创建客户端配置。
+ * Load and parse a Java-style properties file.
  *
- * 优先级：环境变量 > 代码设置（含配置文件） > 默认值。
- * 必填字段 tigerId 和 privateKey 为空时抛出错误。
+ * @param filePath - Absolute or relative path to the properties file
+ * @returns Parsed key-value pairs, or empty object if the file cannot be read
+ */
+export declare function loadPropertiesFile(filePath: string): Record<string, string>;
+/**
+ * Create a client configuration.
+ *
+ * When called with no arguments (or without `propertiesFilePath`), the function
+ * automatically searches for `tiger_openapi_config.properties` in the current
+ * directory and `~/.tigeropen/`. Discovered values serve as defaults; explicit
+ * options and environment variables take precedence.
+ *
+ * Priority: environment variables > code options > config file > defaults
  *
- * @param options - 配置选项
- * @returns 完整的客户端配置对象
- * @throws tigerId 或 privateKey 为空时抛出错误
+ * @param options - Configuration options (optional)
+ * @returns Complete client configuration object
+ * @throws When tigerId or privateKey is empty after all resolution
  */
-export declare function createClientConfig(options: ClientConfigOptions): ClientConfig;
+export declare function createClientConfig(options?: ClientConfigOptions): ClientConfig;

package/dist/types/config/domain.d.ts

@@ -16,3 +16,12 @@ export declare function queryDomains(license?: string): Record<string, unknown>;
  * 返回空字符串表示无法解析（应使用默认地址）。
  */
 export declare function resolveDynamicServerUrl(domainConf: Record<string, unknown>, license?: string): string;
+/**
+ * Resolve the quote server URL from dynamic domain configuration.
+ * Uses the `{LICENSE}-QUOTE` key, falling back to empty string.
+ *
+ * @param domainConf - Domain configuration map from queryDomains
+ * @param license - License type (e.g. "TBNZ")
+ * @returns Quote server URL with gateway suffix, or empty string
+ */
+export declare function resolveDynamicQuoteServerUrl(domainConf: Record<string, unknown>, license?: string): string;

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

@@ -2,6 +2,6 @@
  * 配置层导出
  */
 export { parsePropertiesFile, parsePropertiesString } from './config-parser';
-export { createClientConfig } from './client-config';
+export { createClientConfig, loadPropertiesFile } from './client-config';
 export type { ClientConfig, ClientConfigOptions } from './client-config';
-export { queryDomains, resolveDynamicServerUrl } from './domain';
+export { queryDomains, resolveDynamicServerUrl, resolveDynamicQuoteServerUrl } from './domain';

package/dist/types/index.d.ts

@@ -15,4 +15,4 @@
  * @packageDocumentation
  */
 /** SDK 版本号 */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.3.0";

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

@@ -1,60 +1,44 @@
 /**
- * Contract 合约接口
- * 字段名 camelCase 与 API JSON 天然一致，不改名、不加封装层
+ * Contract / TickSize models.
  */
-/** 最小报价单位价格区间 */
+/** Tick size tier */
 export interface TickSize {
-    /** 起始价格（字符串，如 "0"、"1"） */
     begin?: string;
-    /** 结束价格（字符串，如 "1"、"Infinity"） */
     end?: string;
-    /** 最小报价单位 */
     tickSize?: number;
-    /** 类型（CLOSED/OPEN） */
     type?: string;
 }
-/** 合约模型，字段名词根保持与 API JSON 一致 */
+/** Contract model (returned by contract / contracts / quoteContract / derivative queries) */
 export interface Contract {
-    /** 合约 ID */
     contractId?: number;
-    /** 标的代码（如 AAPL） */
     symbol: string;
-    /** 证券类型（STK/OPT/FUT/WAR/CASH/FUND 等） */
     secType: string;
-    /** 货币 */
     currency?: string;
-    /** 交易所 */
     exchange?: string;
-    /** 到期日（期权/期货） */
+    primaryExchange?: string;
+    localSymbol?: string;
+    tradingClass?: 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;
-    /** 做空保证金比例 */
+    status?: number;
+    marginable?: boolean;
+    shortable?: boolean;
+    closeOnly?: boolean;
+    isEtf?: boolean;
+    supportOvernightTrading?: boolean;
+    supportFractionalShare?: boolean;
     shortMargin?: number;
-    /** 做空初始保证金比例 */
     shortInitialMargin?: number;
-    /** 做空维持保证金比例 */
     shortMaintenanceMargin?: number;
-    /** 做多初始保证金 */
     longInitialMargin?: number;
-    /** 做多维持保证金 */
     longMaintenanceMargin?: number;
-    /** 最小报价单位价格区间 */
     tickSizes?: TickSize[];
-    /** 每手数量 */
     lotSize?: number;
 }

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

@@ -1,22 +1,23 @@
 /**
- * 订单构造工具函数
+ * Order construction helpers.
+ * All helpers return an `OrderRequest` with sensible defaults.
  */
-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;
+import type { OrderRequest, OrderLegRequest, AlgoParamsRequest } from './order';
+/** Market order */
+export declare function marketOrder(account: string, symbol: string, secType: string, action: string, quantity: number): OrderRequest;
+/** Limit order */
+export declare function limitOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number): OrderRequest;
+/** Stop order */
+export declare function stopOrder(account: string, symbol: string, secType: string, action: string, quantity: number, auxPrice: number): OrderRequest;
+/** Stop limit order */
+export declare function stopLimitOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number, auxPrice: number): OrderRequest;
+/** Trailing stop order */
+export declare function trailOrder(account: string, symbol: string, secType: string, action: string, quantity: number, trailingPercent: number): OrderRequest;
+/** Auction limit order */
+export declare function auctionLimitOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number): OrderRequest;
+/** Auction market order */
+export declare function auctionMarketOrder(account: string, symbol: string, secType: string, action: string, quantity: number): OrderRequest;
+/** Algo order (TWAP / VWAP) */
+export declare function algoOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number, algoType: string, params: AlgoParamsRequest): OrderRequest;
+/** Attached profit / loss leg */
+export declare function orderLeg(legType: string, price: number, timeInForce: string): OrderLegRequest;

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

@@ -1,95 +1,141 @@
 /**
- * Order 订单接口
- * 字段名 camelCase 与 API JSON 天然一致，不改名、不加封装层
+ * Order response / request models.
+ *
+ * TypeScript uses camelCase field names idiomatically. The client layer
+ * transparently converts request camelCase to snake_case before sending;
+ * server responses are already camelCase so they decode directly.
  */
-/** 附加订单（止盈/止损） */
+/** Attached leg order (profit / loss) — response side */
 export interface OrderLeg {
-    /** 附加订单类型（PROFIT/LOSS） */
     legType?: string;
-    /** 价格 */
     price?: number;
-    /** 有效期 */
     timeInForce?: string;
-    /** 数量 */
     quantity?: number;
 }
-/** 算法订单参数 */
+/** Algo order parameters — response side */
 export interface AlgoParams {
-    /** 算法策略（TWAP/VWAP） */
     algoStrategy?: string;
-    /** 开始时间 */
     startTime?: string;
-    /** 结束时间 */
     endTime?: string;
-    /** 参与率 */
     participationRate?: number;
 }
-/** 订单模型，字段名词根保持与 API JSON 一致 */
+/** Order response model (returned by order query methods). */
 export interface Order {
-    /** 交易账户 */
-    account: string;
-    /** 全局订单 ID */
+    account?: string;
     id?: number;
-    /** 账户自增订单号 */
     orderId?: number;
-    /** 买卖方向（BUY/SELL） */
-    action: string;
-    /** 订单类型（MKT/LMT/STP/STP_LMT/TRAIL 等） */
-    orderType: string;
-    /** 总数量（API 返回字段名为 totalQuantity） */
-    totalQuantity: number;
-    /** 限价 */
+    externalId?: string;
+    action?: string;
+    orderType?: string;
+    totalQuantity?: number;
+    totalQuantityScale?: number;
+    filledQuantity?: number;
+    filledQuantityScale?: number;
+    filledCashAmount?: number;
     limitPrice?: number;
-    /** 辅助价格（止损价） */
     auxPrice?: number;
-    /** 跟踪止损百分比 */
     trailingPercent?: number;
-    /** 订单状态 */
     status?: string;
-    /** 已成交数量（API 返回字段名为 filledQuantity） */
-    filledQuantity?: number;
-    /** 平均成交价 */
     avgFillPrice?: number;
-    /** 有效期（DAY/GTC/OPG） */
-    timeInForce: string;
-    /** 是否允许盘前盘后 */
-    outsideRth: boolean;
-    /** 附加订单（止盈/止损） */
+    timeInForce?: string;
+    outsideRth?: boolean;
     orderLegs?: OrderLeg[];
-    /** 算法参数 */
     algoParams?: AlgoParams;
-    /** 股票代码 */
-    symbol: string;
-    /** 合约类型 */
-    secType: string;
-    /** 市场 */
+    algoStrategy?: string;
+    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;
-    /** 已实现盈亏 */
+    gst?: number;
     realizedPnl?: number;
-    /** 开仓时间（毫秒时间戳） */
     openTime?: number;
-    /** 更新时间（毫秒时间戳） */
     updateTime?: number;
-    /** 最新时间（毫秒时间戳） */
     latestTime?: number;
-    /** 备注 */
+    latestPrice?: number;
     remark?: string;
-    /** 订单来源 */
     source?: string;
-    /** 用户标记 */
     userMark?: string;
+    liquidation?: boolean;
+    discount?: number;
+    replaceStatus?: string;
+    cancelStatus?: string;
+    canModify?: boolean;
+    canCancel?: boolean;
+    isOpen?: boolean;
+    orderDiscount?: number;
+    tradingSessionType?: string;
+    attrDesc?: string;
+    attrList?: string[];
+}
+/**
+ * OrderRequest — order request model used by placeOrder / previewOrder / modifyOrder.
+ * Fields are camelCase in TypeScript; the client converts them to snake_case on the wire.
+ */
+export interface OrderRequest {
+    /** Account ID (client fills it in automatically) */
+    account?: string;
+    /** Global order ID (required for modify) */
+    id?: number;
+    /** Account-level order ID */
+    orderId?: number;
+    /** BUY / SELL */
+    action: string;
+    /** Order type: MKT / LMT / STP / STP_LMT / TRAIL / AM / AL / TWAP / VWAP / OCA */
+    orderType: string;
+    /** Total quantity */
+    totalQuantity: number;
+    /** Limit price (required for LMT / STP_LMT) */
+    limitPrice?: number;
+    /** Stop / trigger price (required for STP / STP_LMT / TRAIL) */
+    auxPrice?: number;
+    /** Trailing stop percent */
+    trailingPercent?: number;
+    /** DAY / GTC / GTD / OPG */
+    timeInForce: string;
+    /** Allow extended-hours trading */
+    outsideRth?: boolean;
+    /** Attached legs (profit / loss) */
+    orderLegs?: OrderLegRequest[];
+    /** Algo parameters */
+    algoParams?: AlgoParamsRequest;
+    /** Contract symbol */
+    symbol: string;
+    /** STK / OPT / FUT / WAR / IOPT */
+    secType: string;
+    /** Market */
+    market?: string;
+    /** Currency */
+    currency?: string;
+    /** Option expiry */
+    expiry?: string;
+    /** Option strike */
+    strike?: string;
+    /** CALL / PUT */
+    right?: string;
+    /** Contract identifier */
+    identifier?: string;
+    /** Remark */
+    remark?: string;
+    /** User mark */
+    userMark?: string;
+}
+/** Attached leg for request side */
+export interface OrderLegRequest {
+    legType: string;
+    price?: number;
+    timeInForce?: string;
+    quantity?: number;
+}
+/** Algo parameters for request side */
+export interface AlgoParamsRequest {
+    algoStrategy?: string;
+    startTime?: string;
+    endTime?: string;
+    participationRate?: number;
 }

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

@@ -1,39 +1,41 @@
 /**
- * Position 持仓接口
- * 字段名 camelCase 与 API JSON 天然一致，不改名、不加封装层
+ * Position model.
  */
-/** 持仓模型，字段名词根保持与 API JSON 一致 */
+/** Position (returned by positions query) */
 export interface Position {
-    /** 交易账户 */
-    account: string;
-    /** 标的代码 */
-    symbol: string;
-    /** 证券类型 */
-    secType: string;
-    /** 市场 */
+    account?: string;
+    symbol?: string;
+    secType?: string;
     market?: string;
-    /** 货币 */
     currency?: string;
-    /** 持仓数量（API 返回字段名为 position） */
-    position: number;
-    /** 平均成本 */
-    averageCost: number;
-    /** 市值 */
+    position?: number;
+    positionScale?: number;
+    positionQty?: number;
+    salableQty?: number;
+    averageCost?: number;
+    averageCostByAverage?: number;
+    averageCostOfCarry?: number;
     marketValue?: number;
-    /** 已实现盈亏 */
     realizedPnl?: number;
-    /** 未实现盈亏 */
+    realizedPnlByAverage?: number;
     unrealizedPnl?: number;
-    /** 未实现盈亏百分比 */
+    unrealizedPnlByAverage?: number;
+    unrealizedPnlByCostOfCarry?: number;
     unrealizedPnlPercent?: number;
-    /** 合约 ID */
+    unrealizedPnlPercentByAverage?: number;
+    unrealizedPnlPercentByCostOfCarry?: number;
     contractId?: number;
-    /** 合约标识符 */
     identifier?: string;
-    /** 合约名称 */
     name?: string;
-    /** 最新价格 */
     latestPrice?: number;
-    /** 合约乘数 */
+    lastClosePrice?: number;
     multiplier?: number;
+    status?: number;
+    updateTimestamp?: number;
+    mmPercent?: number;
+    mmValue?: number;
+    todayPnl?: number;
+    todayPnlPercent?: number;
+    comboTypes?: string[];
+    categories?: string[];
 }