@tigeropenapi/tigeropen 0.1.0 → 0.4.0

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

@@ -2,98 +2,233 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TradeClient = void 0;
 const api_request_1 = require("../client/api-request");
-/**
- * 交易客户端，封装所有交易相关 API。
- */
+const api_response_1 = require("../client/api-response");
+const order_status_1 = require("../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 = (0, order_status_1.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. */
 class TradeClient {
     constructor(httpClient, account) {
         this.httpClient = httpClient;
         this.account = account;
     }
-    /**
-     * 内部通用方法：构造请求、发送、返回 data 字段
-     */
-    async execute(method, bizParams) {
+    async callInto(method, bizParams) {
         const request = (0, api_request_1.createApiRequest)(method, bizParams);
         const response = await this.httpClient.executeRequest(request);
-        return response.data;
-    }
-    // === 合约查询方法 ===
-    /** 查询单个合约 */
-    async contract(symbol, secType) {
-        return this.execute('contract', {
+        return (0, api_response_1.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);
     }
 }
 exports.TradeClient = TradeClient;

package/dist/esm/client/api-request.js

@@ -1,14 +1,20 @@
 /**
- * API 请求构造模块
+ * API request builder.
+ *
+ * Requests use camelCase parameters in TypeScript (idiomatic), but the
+ * server wire format is snake_case, so we convert keys before serializing.
  */
+import { keysToSnakeCase } from './case-convert';
 /**
- * 创建 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 function createApiRequest(method, bizParams) {
+export function createApiRequest(method, bizParams, version) {
     let bizContent;
     if (typeof bizParams === 'string') {
         bizContent = bizParams;
@@ -17,7 +23,7 @@ export function createApiRequest(method, bizParams) {
         bizContent = '{}';
     }
     else {
-        bizContent = JSON.stringify(bizParams);
+        bizContent = JSON.stringify(keysToSnakeCase(bizParams));
     }
-    return { method, bizContent };
+    return { method, bizContent, version };
 }

package/dist/esm/client/api-response.js

@@ -1,10 +1,10 @@
 /**
- * API 响应解析模块
+ * API response parsing.
  */
 import { TigerError } from './errors';
 /**
- * 解析 API 响应 JSON 字符串。
- * code 为 0 时返回 ApiResponse；code 不为 0 时抛出 TigerError。
+ * Parse the raw HTTP response body.
+ * Throws TigerError when code != 0.
  */
 export function parseApiResponse(body) {
     const resp = JSON.parse(body);
@@ -13,3 +13,22 @@ export function parseApiResponse(body) {
     }
     return resp;
 }
+/**
+ * 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 function unmarshalData(data) {
+    if (data == null)
+        return undefined;
+    if (typeof data === 'string') {
+        // Attempt to parse JSON string (double-encoded case)
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return data;
+        }
+    }
+    return data;
+}

package/dist/esm/client/case-convert.js

@@ -0,0 +1,31 @@
+/**
+ * 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 function camelToSnake(key) {
+    return key.replace(/[A-Z]/g, (c) => '_' + c.toLowerCase());
+}
+/**
+ * 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 function keysToSnakeCase(value) {
+    if (Array.isArray(value)) {
+        return value.map((v) => keysToSnakeCase(v));
+    }
+    if (value && typeof value === 'object' && value.constructor === Object) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            const newKey = k.includes('_') ? k : camelToSnake(k);
+            out[newKey] = keysToSnakeCase(v);
+        }
+        return out;
+    }
+    return value;
+}

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

@@ -1,10 +1,10 @@
 import { getSignContent } from '../signer/sign-content';
-import { signWithRSA } from '../signer/signer';
+import { signWithRSA, verifyWithRSA } from '../signer/signer';
 import { TigerError } from './errors';
 import { defaultRetryPolicy } from './retry';
 import { parseApiResponse } from './api-response';
 /** SDK 版本号 */
-const SDK_VERSION = '0.1.0';
+const SDK_VERSION = '0.4.0';
 /** User-Agent 字符串 */
 const USER_AGENT = `openapi-typescript-sdk-${SDK_VERSION}`;
 /** 默认字符集 */
@@ -14,29 +14,33 @@ const DEFAULT_SIGN_TYPE = 'RSA';
 /** 默认 API 版本 */
 const DEFAULT_VERSION = '2.0';
 /**
- * HttpClient 封装 HTTP 请求、签名、重试、超时
+ * HttpClient handles HTTP requests, signing, retry, and timeout
  */
 export class HttpClient {
-    constructor(config, retryPolicy) {
+    constructor(config, retryPolicy, options) {
         this.config = config;
         this.retryPolicy = retryPolicy ?? defaultRetryPolicy();
+        this.targetUrl = options?.useQuoteServerUrl ? config.quoteServerUrl : config.serverUrl;
     }
     /**
-     * 构造公共请求参数
+     * Build common request parameters
      */
-    buildCommonParams(apiMethod, bizContent) {
+    buildCommonParams(apiMethod, bizContent, version) {
         const params = {
             tiger_id: this.config.tigerId,
             method: apiMethod,
             charset: DEFAULT_CHARSET,
             sign_type: DEFAULT_SIGN_TYPE,
             timestamp: new Date().toISOString().replace('T', ' ').substring(0, 19),
-            version: DEFAULT_VERSION,
+            version: version || DEFAULT_VERSION,
             biz_content: bizContent,
         };
         if (this.config.language) {
             params['language'] = this.config.language;
         }
+        if (this.config.deviceId) {
+            params['device_id'] = this.config.deviceId;
+        }
         return params;
     }
     /**
@@ -47,7 +51,7 @@ export class HttpClient {
         return signWithRSA(this.config.privateKey, content);
     }
     /**
-     * 发送 HTTP POST 请求
+     * Send HTTP POST request
      */
     async doHttpPost(params) {
         const body = JSON.stringify(params);
@@ -58,7 +62,7 @@ export class HttpClient {
         if (this.config.token) {
             headers['Authorization'] = this.config.token;
         }
-        const response = await fetch(this.config.serverUrl, {
+        const response = await fetch(this.targetUrl, {
             method: 'POST',
             headers,
             body,
@@ -67,11 +71,11 @@ export class HttpClient {
         return response.text();
     }
     /**
-     * 执行结构化 API 请求，返回解析后的 ApiResponse。
-     * 供 QuoteClient/TradeClient 内部使用。
+     * Execute a structured API request, returning a parsed ApiResponse.
+     * Used internally by QuoteClient/TradeClient.
      */
     async executeRequest(request) {
-        const params = this.buildCommonParams(request.method, request.bizContent);
+        const params = this.buildCommonParams(request.method, request.bizContent, request.version);
         const sign = this.signParams(params);
         params['sign'] = sign;
         let lastErr;
@@ -85,7 +89,9 @@ export class HttpClient {
             }
             try {
                 const body = await this.doHttpPost(params);
-                return parseApiResponse(body);
+                const response = parseApiResponse(body);
+                this.verifyResponseSign(params['timestamp'], response.sign);
+                return response;
             }
             catch (err) {
                 lastErr = err;
@@ -97,22 +103,22 @@ export class HttpClient {
         throw lastErr;
     }
     /**
-     * 通用 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
      */
     async execute(apiMethod, requestJson) {
-        // 参数校验
+        // Parameter validation
         if (!apiMethod) {
-            throw new TigerError(-1, 'api_method 不能为空');
+            throw new TigerError(-1, 'api_method must not be empty');
         }
         try {
             JSON.parse(requestJson);
         }
         catch {
-            throw new TigerError(-1, 'request_json 不是有效的 JSON');
+            throw new TigerError(-1, 'request_json is not valid JSON');
         }
         const params = this.buildCommonParams(apiMethod, requestJson);
         const sign = this.signParams(params);
@@ -127,7 +133,11 @@ export class HttpClient {
                 await this.sleep(backoff);
             }
             try {
-                return await this.doHttpPost(params);
+                const body = await this.doHttpPost(params);
+                // Verify response signature even for raw responses
+                const parsed = JSON.parse(body);
+                this.verifyResponseSign(params['timestamp'], parsed.sign);
+                return body;
             }
             catch (err) {
                 lastErr = err;
@@ -138,8 +148,24 @@ export class HttpClient {
         }
         throw lastErr;
     }
-    /** 延迟指定毫秒 */
+    /** Delay for the specified milliseconds */
     sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
+    /**
+     * 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
+     */
+    verifyResponseSign(timestamp, signBase64) {
+        if (!signBase64) {
+            throw new TigerError(-1, 'Response signature is missing');
+        }
+        const valid = verifyWithRSA(this.config.tigerPublicKey, timestamp, signBase64);
+        if (!valid) {
+            throw new TigerError(-1, 'Response signature verification failed');
+        }
+    }
 }

package/dist/esm/client/index.js

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