@tigeropenapi/tigeropen 0.1.0 → 0.4.0

package/dist/esm/trade/trade-client.js

@@ -1,95 +1,230 @@
 import { createApiRequest } from '../client/api-request';
-/**
- * 交易客户端，封装所有交易相关 API。
- */
+import { unmarshalData } from '../client/api-response';
+import { normalizeOrderStatus } from '../model/order-status';
+/** Normalize `Order.status` field in-place (handles int → string). */
+function normalizeOrderInPlace(o) {
+    if (o && o.status !== undefined && o.status !== null) {
+        o.status = normalizeOrderStatus(o.status);
+    }
+}
+/** Normalize every Order in a list in-place. */
+function normalizeOrders(orders) {
+    for (const o of orders)
+        normalizeOrderInPlace(o);
+    return orders;
+}
+/** Shallow-copy a request object and fill account if empty. */
+function withAccount(req, account) {
+    const r = { ...(req ?? {}) };
+    if (!r.account)
+        r.account = account;
+    return r;
+}
+/** Trading client wrapping all trade-related APIs. */
 export class TradeClient {
     constructor(httpClient, account) {
         this.httpClient = httpClient;
         this.account = account;
     }
-    /**
-     * 内部通用方法：构造请求、发送、返回 data 字段
-     */
-    async execute(method, bizParams) {
+    async callInto(method, bizParams) {
         const request = createApiRequest(method, bizParams);
         const response = await this.httpClient.executeRequest(request);
-        return response.data;
-    }
-    // === 合约查询方法 ===
-    /** 查询单个合约 */
-    async contract(symbol, secType) {
-        return this.execute('contract', {
+        return unmarshalData(response.data);
+    }
+    /** Strip `{items: [...]}` envelope used by most trade read endpoints. */
+    async callIntoItems(method, bizParams) {
+        const wrap = await this.callInto(method, bizParams);
+        if (Array.isArray(wrap))
+            return wrap;
+        return wrap?.items ?? [];
+    }
+    // === Contracts ===
+    async getContract(symbol, secType) {
+        return this.callIntoItems('contract', {
             account: this.account, symbol, secType,
         });
     }
-    /** 批量查询合约 */
-    async contracts(symbols, secType) {
-        return this.execute('contracts', {
+    async getContracts(symbols, secType) {
+        return this.callIntoItems('contracts', {
             account: this.account, symbols, secType,
         });
     }
-    /** 查询衍生品合约 */
-    async quoteContract(symbol, secType) {
-        return this.execute('quote_contract', {
-            account: this.account, symbol, secType,
+    /**
+     * Derivative contracts (OPT / WAR / IOPT only).
+     * `symbol` is the underlying (e.g. "AAPL"); `expiry` is "YYYYMMDD".
+     */
+    async getQuoteContract(symbol, secType, expiry) {
+        return this.callIntoItems('quote_contract', {
+            account: this.account, symbols: [symbol], secType, expiry,
         });
     }
-    // === 订单操作方法 ===
-    /** 下单 */
+    // === Order operations ===
     async placeOrder(order) {
-        const params = { ...order, account: this.account };
-        return this.execute('place_order', params);
+        return this.callInto('place_order', { ...order, account: this.account });
     }
-    /** 预览订单 */
     async previewOrder(order) {
-        const params = { ...order, account: this.account };
-        return this.execute('preview_order', params);
+        return this.callInto('preview_order', { ...order, account: this.account });
     }
-    /** 修改订单 */
     async modifyOrder(id, order) {
-        const params = { ...order, account: this.account, id };
-        return this.execute('modify_order', params);
+        return this.callInto('modify_order', { ...order, account: this.account, id });
     }
-    /** 取消订单 */
     async cancelOrder(id) {
-        return this.execute('cancel_order', {
-            account: this.account, id,
-        });
+        return this.callInto('cancel_order', { account: this.account, id });
     }
-    // === 订单查询方法 ===
-    /** 查询全部订单 */
-    async orders() {
-        return this.execute('orders', { account: this.account });
+    // === Order queries (BREAKING v0.4.0) ===
+    /**
+     * Query all historical orders. v0.4.0: optional OrdersRequest for filtering.
+     *
+     * @example
+     * // Default (unfiltered)
+     * await tc.getOrders();
+     * // Filter by status
+     * await tc.getOrders({ states: ['Filled'], limit: 100 });
+     */
+    async getOrders(req) {
+        return normalizeOrders(await this.callIntoItems('orders', withAccount(req, this.account)));
     }
-    /** 查询待成交订单 */
-    async activeOrders() {
-        return this.execute('active_orders', { account: this.account });
+    /** Query active (open) orders. v0.4.0: supports ParentId to filter attached legs. */
+    async getActiveOrders(req) {
+        return normalizeOrders(await this.callIntoItems('active_orders', withAccount(req, this.account)));
     }
-    /** 查询已撤销订单 */
-    async inactiveOrders() {
-        return this.execute('inactive_orders', { account: this.account });
+    /** Query inactive/cancelled orders. */
+    async getInactiveOrders(req) {
+        return normalizeOrders(await this.callIntoItems('inactive_orders', withAccount(req, this.account)));
     }
-    /** 查询已成交订单 */
-    async filledOrders() {
-        return this.execute('filled_orders', { account: this.account });
+    /**
+     * Query filled orders. v0.4.0 BREAKING: signature changed from positional
+     * (startDateMs, endDateMs) to OrdersRequest object.
+     *
+     * @example
+     * // Last 30 days
+     * const now = Date.now();
+     * await tc.getFilledOrders({ startDate: now - 30*24*3600*1000, endDate: now });
+     */
+    async getFilledOrders(req) {
+        return normalizeOrders(await this.callIntoItems('filled_orders', withAccount(req, this.account)));
     }
-    // === 持仓和资产查询方法 ===
-    /** 查询持仓 */
-    async positions() {
-        return this.execute('positions', { account: this.account });
+    /**
+     * Get a single order by ID (v0.4.0 new).
+     * Wire method: `orders` with id/order_id param; server returns a single Order object
+     * (not `{items:[]}` envelope).
+     *
+     * Returns `undefined` if no match.
+     */
+    async getOrder(req) {
+        const merged = withAccount(req, this.account);
+        const out = await this.callInto('orders', merged);
+        if (!out || (!out.id && !out.orderId))
+            return undefined;
+        normalizeOrderInPlace(out);
+        return out;
     }
-    /** 查询资产 */
-    async assets() {
-        return this.execute('assets', { account: this.account });
+    /**
+     * Query order transaction details. v0.4.0 BREAKING: all fields now optional
+     * (previously symbol/secType required).
+     */
+    async getOrderTransactions(req) {
+        return this.callIntoItems('order_transactions', withAccount(req, this.account));
     }
-    /** 查询综合账户资产 */
-    async primeAssets() {
-        return this.execute('prime_assets', { account: this.account });
+    // === Positions & assets (BREAKING v0.4.0) ===
+    /** Query positions. v0.4.0: supports Symbol / SecType / Currency / Market filters. */
+    async getPositions(req) {
+        return this.callIntoItems('positions', withAccount(req, this.account));
     }
-    /** 查询订单成交明细 */
-    async orderTransactions(id) {
-        return this.execute('order_transactions', {
-            account: this.account, id,
-        });
+    /** Query assets. v0.4.0: supports sub-account list and aggregation options. */
+    async getAssets(req) {
+        return this.callIntoItems('assets', withAccount(req, this.account));
+    }
+    /** Query prime assets. v0.4.0: takes AssetsRequest for filters. */
+    async getPrimeAssets(req) {
+        return this.callInto('prime_assets', withAccount(req, this.account));
+    }
+    // ===== v0.4.0 NEW: Account management =====
+    /** Query managed sub-accounts (institutional). */
+    async getManagedAccounts(req) {
+        return this.callIntoItems('accounts', withAccount(req, this.account));
+    }
+    /**
+     * Query derivative contracts list. Same wire as getQuoteContract but accepts
+     * full request struct. Python: `get_derivative_contracts`.
+     */
+    async getDerivativeContracts(req) {
+        return this.callIntoItems('quote_contract', withAccount(req, this.account));
+    }
+    // ===== v0.4.0 NEW: Asset analytics =====
+    /** Daily P&L / net-value / holding-value analytics. */
+    async getAnalyticsAsset(req) {
+        return this.callIntoItems('analytics_asset', withAccount(req, this.account));
+    }
+    /** Aggregate assets (prime) by base currency. */
+    async getAggregateAssets(req) {
+        return this.callInto('aggregate_assets', withAccount(req, this.account));
+    }
+    /** Estimate tradable quantity given order parameters. */
+    async getEstimateTradableQuantity(req) {
+        return this.callInto('estimate_tradable_quantity', withAccount(req, this.account));
+    }
+    // ===== v0.4.0 NEW: Forex =====
+    /** Place forex order (sub-account base-currency swap). */
+    async placeForexOrder(req) {
+        return this.callInto('place_forex_order', withAccount(req, this.account));
+    }
+    // ===== v0.4.0 NEW: Segment fund transfer =====
+    /** Query amount available for inter-segment transfer. Returns array. */
+    async getSegmentFundAvailable(req) {
+        return this.callInto('segment_fund_available', withAccount(req, this.account));
+    }
+    /** Query segment fund transfer history. Server returns plain array (no items wrapper). */
+    async getSegmentFundHistory(req) {
+        return this.callInto('segment_fund_history', withAccount(req, this.account));
+    }
+    /** Execute an inter-segment fund transfer. */
+    async transferSegmentFund(req) {
+        return this.callInto('transfer_segment_fund', withAccount(req, this.account));
+    }
+    /** Cancel a pending inter-segment transfer. */
+    async cancelSegmentFund(req) {
+        return this.callInto('cancel_segment_fund', withAccount(req, this.account));
+    }
+    // ===== v0.4.0 NEW: Fund details / history =====
+    /** Fund-movement details (by segment / currency / fund-type). */
+    async getFundDetails(req) {
+        return this.callIntoItems('fund_details', withAccount(req, this.account));
+    }
+    /** Funding history (wire method: `transfer_fund`). */
+    async getFundingHistory(req) {
+        return this.callIntoItems('transfer_fund', withAccount(req, this.account));
+    }
+    // ===== v0.4.0 NEW: Internal / external position transfer =====
+    /**
+     * Internal position transfer (cross sub-account).
+     * @note Uses `fromAccount` / `toAccount` (not `account`).
+     */
+    async transferPosition(req) {
+        const merged = { ...req };
+        if (!merged.fromAccount)
+            merged.fromAccount = this.account;
+        return this.callInto('position_transfer', merged);
+    }
+    /** Query internal position transfer records. Uses `accountId` (wire: `account_id`). */
+    async getPositionTransferRecords(req) {
+        const merged = { ...req };
+        if (!merged.accountId)
+            merged.accountId = this.account;
+        return this.callIntoItems('position_transfer_records', merged);
+    }
+    /** Query single internal position transfer detail by ID. */
+    async getPositionTransferDetail(req) {
+        const merged = { ...req };
+        if (!merged.accountId)
+            merged.accountId = this.account;
+        return this.callInto('position_transfer_detail', merged);
+    }
+    /** Query external position transfer records (DWAC / FOP / etc.). */
+    async getPositionTransferExternalRecords(req) {
+        const merged = { ...req };
+        if (!merged.accountId)
+            merged.accountId = this.account;
+        return this.callIntoItems('position_transfer_external_records', merged);
     }
 }

package/dist/types/client/api-request.d.ts

@@ -1,18 +1,19 @@
-/**
- * API 请求构造模块
- */
-/** API 请求接口 */
+/** API request interface */
 export interface ApiRequest {
-    /** API 方法名（如 "market_state"、"place_order"） */
+    /** API method name (e.g. "market_state", "place_order") */
     method: string;
-    /** 业务参数 JSON 字符串 */
+    /** Business parameters as JSON string (already snake_case) */
     bizContent: string;
+    /** Optional API version override (default: "2.0") */
+    version?: string;
 }
 /**
- * 创建 API 请求，将业务参数序列化为 JSON 字符串作为 bizContent。
+ * Create an API request, serializing business parameters to JSON as bizContent.
+ * camelCase keys are automatically converted to snake_case to match the server.
  *
- * @param method - API 方法名
- * @param bizParams - 业务参数（对象、字符串或 null）
- * @returns ApiRequest 对象
+ * @param method - API method name
+ * @param bizParams - Business parameters (object, string, or null); objects are converted recursively
+ * @param version - Optional API version override
+ * @returns ApiRequest object
  */
-export declare function createApiRequest(method: string, bizParams: unknown): ApiRequest;
+export declare function createApiRequest(method: string, bizParams: unknown, version?: string): ApiRequest;

package/dist/types/client/api-response.d.ts

@@ -1,16 +1,24 @@
-/** API 响应接口 */
+/** API response envelope */
 export interface ApiResponse {
-    /** 状态码（0=成功） */
+    /** Result code (0 = success) */
     code: number;
-    /** 状态描述 */
+    /** Human-readable message */
     message: string;
-    /** 业务数据 */
+    /** Business payload */
     data: unknown;
-    /** 服务器时间戳 */
+    /** Server timestamp */
     timestamp: number;
+    /** Response signature for verification */
+    sign?: string;
 }
 /**
- * 解析 API 响应 JSON 字符串。
- * code 为 0 时返回 ApiResponse；code 不为 0 时抛出 TigerError。
+ * Parse the raw HTTP response body.
+ * Throws TigerError when code != 0.
  */
 export declare function parseApiResponse(body: string): ApiResponse;
+/**
+ * Decode an ApiResponse.data payload into a typed value.
+ * Handles the server's occasional double-encoded JSON (where `data` is a
+ * JSON string that itself wraps JSON), seen on some trade endpoints.
+ */
+export declare function unmarshalData<T>(data: unknown): T | undefined;

package/dist/types/client/case-convert.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Case conversion utilities.
+ *
+ * TypeScript SDK uses camelCase idiomatically. The server expects
+ * snake_case for request field names and returns camelCase for responses.
+ * These helpers convert camelCase objects to snake_case before
+ * serialization; response side needs no conversion.
+ */
+/** Convert a single camelCase key to snake_case. */
+export declare function camelToSnake(key: string): string;
+/**
+ * Recursively convert all object keys from camelCase to snake_case.
+ * Preserves arrays, primitives, and Date/null/undefined.
+ * Keys already containing an underscore are kept as-is (already snake_case).
+ */
+export declare function keysToSnakeCase(value: unknown): unknown;

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.4.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;
 }