@tigeropenapi/tigeropen 0.1.0 → 0.3.0

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,5 +1,5 @@
 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';
@@ -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';

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

@@ -1,58 +1,125 @@
 /**
- * ClientConfig - 客户端配置管理
+ * ClientConfig - Client configuration management
  *
- * 聚合所有配置参数，支持：
- * - 代码直接设置
- * - 从 properties 配置文件加载
- * - 环境变量覆盖
+ * Aggregates all configuration parameters with support for:
+ * - Direct code configuration
+ * - Properties file loading (explicit path or auto-discovery)
+ * - Environment variable overrides
  *
- * 优先级：环境变量 > 代码设置（含配置文件） > 默认值
+ * Priority: environment variables > code options (incl. config file) > defaults
  */
-import { readFileSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir, networkInterfaces } from 'os';
 import { parsePropertiesString } from './config-parser';
-import { queryDomains, resolveDynamicServerUrl } from './domain';
-/** 默认值 */
+import { queryDomains, resolveDynamicServerUrl, resolveDynamicQuoteServerUrl } from './domain';
+/** Default config file name */
+const CONFIG_FILE_NAME = 'tiger_openapi_config.properties';
+/** Defaults */
 const DEFAULT_LANGUAGE = 'zh_CN';
 const DEFAULT_TIMEOUT = 15;
 const DEFAULT_SERVER_URL = 'https://openapi.tigerfintech.com/gateway';
-const SANDBOX_SERVER_URL = 'https://openapi-sandbox.tigerfintech.com/gateway';
-/** 环境变量名 */
+/** Tiger public key for response signature verification (Base64-encoded) */
+const TIGER_PUBLIC_KEY = 'MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDNF3G8SoEcCZh2rshUbayDgLLrj6rKgzNMxDL2HSnKcB0+GPOsndqSv+a4IBu9+I3fyBp5hkyMMG2+AXugd9pMpy6VxJxlNjhX1MYbNTZJUT4nudki4uh+LMOkIBHOceGNXjgB+cXqmlUnjlqha/HgboeHSnSgpM3dKSJQlIOsDwIDAQAB';
+/** Environment variable names */
 const ENV_TIGER_ID = 'TIGEROPEN_TIGER_ID';
 const ENV_PRIVATE_KEY = 'TIGEROPEN_PRIVATE_KEY';
 const ENV_ACCOUNT = 'TIGEROPEN_ACCOUNT';
+const ENV_TOKEN = 'TIGEROPEN_TOKEN';
 /**
- * 创建客户端配置。
+ * 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 function loadPropertiesFile(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        return parsePropertiesString(content);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Discover the config file by searching well-known locations.
+ *
+ * Search order:
+ * 1. `./tiger_openapi_config.properties` (current working directory)
+ * 2. `~/.tigeropen/tiger_openapi_config.properties` (home directory)
+ *
+ * @returns The resolved file path, or `undefined` if not found
+ */
+function discoverConfigFile() {
+    const candidates = [
+        join(process.cwd(), CONFIG_FILE_NAME),
+        join(homedir(), '.tigeropen', CONFIG_FILE_NAME),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Auto-detect device identifier from the first non-internal MAC address.
  *
- * @param options - 配置选项
- * @returns 完整的客户端配置对象
- * @throws tigerId 或 privateKey 为空时抛出错误
+ * @returns MAC address string, or empty string if none found
+ */
+function detectDeviceId() {
+    const interfaces = networkInterfaces();
+    for (const [, addrs] of Object.entries(interfaces)) {
+        if (!addrs)
+            continue;
+        for (const addr of addrs) {
+            if (!addr.internal && addr.mac && addr.mac !== '00:00:00:00:00:00') {
+                return addr.mac;
+            }
+        }
+    }
+    return '';
+}
+/**
+ * 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 - Configuration options (optional)
+ * @returns Complete client configuration object
+ * @throws When tigerId or privateKey is empty after all resolution
  */
 export function createClientConfig(options) {
-    // 从配置文件加载（如果指定了路径）
+    const opts = options ?? {};
+    // Load properties: explicit path > auto-discovery
     let fileProps = {};
-    if (options.propertiesFilePath) {
-        try {
-            const content = readFileSync(options.propertiesFilePath, 'utf-8');
-            fileProps = parsePropertiesString(content);
-        }
-        catch {
-            // 文件加载失败时静默跳过，后续校验会捕获必填字段缺失
+    if (opts.propertiesFilePath) {
+        fileProps = loadPropertiesFile(opts.propertiesFilePath);
+    }
+    else {
+        const discovered = discoverConfigFile();
+        if (discovered) {
+            fileProps = loadPropertiesFile(discovered);
         }
     }
-    // 从配置文件提取值（代码设置优先于配置文件）
-    let tigerId = options.tigerId || fileProps['tiger_id'] || '';
-    let privateKey = options.privateKey || resolvePrivateKey(fileProps) || '';
-    let account = options.account || fileProps['account'] || '';
-    const license = options.license || fileProps['license'];
-    const language = options.language || fileProps['language'] || DEFAULT_LANGUAGE;
-    const timezone = options.timezone || fileProps['timezone'];
-    // 环境变量覆盖（最高优先级）
+    // Merge values (code options override config file)
+    let tigerId = opts.tigerId || fileProps['tiger_id'] || '';
+    let privateKey = opts.privateKey || resolvePrivateKey(fileProps) || '';
+    let account = opts.account || fileProps['account'] || '';
+    let token = opts.token || fileProps['token'];
+    const license = opts.license || fileProps['license'];
+    const language = opts.language || fileProps['language'] || DEFAULT_LANGUAGE;
+    const timezone = opts.timezone || fileProps['timezone'];
+    // Environment variables override everything
     const envTigerId = process.env[ENV_TIGER_ID];
     const envPrivateKey = process.env[ENV_PRIVATE_KEY];
     const envAccount = process.env[ENV_ACCOUNT];
+    const envToken = process.env[ENV_TOKEN];
     if (envTigerId) {
         tigerId = envTigerId;
     }
@@ -62,25 +129,24 @@ export function createClientConfig(options) {
     if (envAccount) {
         account = envAccount;
     }
-    // 校验必填字段
+    if (envToken) {
+        token = envToken;
+    }
+    // Validate required fields
     if (!tigerId) {
-        throw new Error(`tigerId 不能为空，请通过 options.tigerId 或环境变量 ${ENV_TIGER_ID} 设置`);
+        throw new Error(`tigerId is required. Set it via options.tigerId, a config file, or the ${ENV_TIGER_ID} environment variable.`);
     }
     if (!privateKey) {
-        throw new Error(`privateKey 不能为空，请通过 options.privateKey 或环境变量 ${ENV_PRIVATE_KEY} 设置`);
+        throw new Error(`privateKey is required. Set it via options.privateKey, a config file, or the ${ENV_PRIVATE_KEY} environment variable.`);
     }
-    // 确定服务器 URL：sandbox > 动态域名 > 默认
-    const sandboxDebug = options.sandboxDebug ?? false;
-    const enableDynamicDomain = options.enableDynamicDomain ?? true;
+    // Resolve server URL: explicit > dynamic domain > default
+    const enableDynamicDomain = opts.enableDynamicDomain ?? true;
     let serverUrl;
-    if (sandboxDebug) {
-        serverUrl = SANDBOX_SERVER_URL;
-    }
-    else if (options.serverUrl) {
-        serverUrl = options.serverUrl;
+    let quoteServerUrl;
+    if (opts.serverUrl) {
+        serverUrl = opts.serverUrl;
     }
     else {
-        // 尝试动态域名获取
         let dynamicUrl = '';
         if (enableDynamicDomain) {
             const domainConf = queryDomains(license);
@@ -88,6 +154,18 @@ export function createClientConfig(options) {
         }
         serverUrl = dynamicUrl || DEFAULT_SERVER_URL;
     }
+    // Resolve quote server URL: explicit > dynamic domain > serverUrl fallback
+    if (opts.quoteServerUrl) {
+        quoteServerUrl = opts.quoteServerUrl;
+    }
+    else {
+        let dynamicQuoteUrl = '';
+        if (enableDynamicDomain) {
+            const domainConf = queryDomains(license);
+            dynamicQuoteUrl = resolveDynamicQuoteServerUrl(domainConf, license);
+        }
+        quoteServerUrl = dynamicQuoteUrl || serverUrl;
+    }
     return {
         tigerId,
         privateKey,
@@ -95,16 +173,18 @@ export function createClientConfig(options) {
         license,
         language,
         timezone,
-        timeout: options.timeout ?? DEFAULT_TIMEOUT,
-        sandboxDebug,
-        token: options.token,
-        tokenRefreshDuration: options.tokenRefreshDuration,
+        timeout: opts.timeout ?? DEFAULT_TIMEOUT,
+        token,
+        tokenRefreshDuration: opts.tokenRefreshDuration,
         serverUrl,
+        quoteServerUrl,
+        deviceId: detectDeviceId(),
+        tigerPublicKey: TIGER_PUBLIC_KEY,
     };
 }
 /**
- * 从 properties 键值对中解析私钥。
- * 优先级：private_key > private_key_pk8 > private_key_pk1
+ * Resolve private key from properties.
+ * Priority: private_key > private_key_pk8 > private_key_pk1
  */
 function resolvePrivateKey(props) {
     return props['private_key'] || props['private_key_pk8'] || props['private_key_pk1'] || '';

package/dist/esm/config/domain.js

@@ -63,8 +63,26 @@ export function resolveDynamicServerUrl(domainConf, license) {
     return '';
 }
 /**
- * 同步 HTTP GET 请求（Node.js 环境）。
- * 使用 child_process.execSync 实现同步请求，超时快速失败。
+ * 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 function resolveDynamicQuoteServerUrl(domainConf, license) {
+    if (!domainConf || Object.keys(domainConf).length === 0) {
+        return '';
+    }
+    const key = license ? `${license}-QUOTE` : `${DOMAIN_KEY_COMMON}-QUOTE`;
+    if (typeof domainConf[key] === 'string') {
+        return domainConf[key] + GATEWAY_SUFFIX;
+    }
+    return '';
+}
+/**
+ * Synchronous HTTP GET request (Node.js environment).
+ * Uses child_process.execSync for synchronous requests with fast timeout.
  */
 function syncHttpGet(url, timeoutMs) {
     try {

package/dist/esm/config/index.js

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

package/dist/esm/index.js

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

package/dist/esm/model/contract.js

@@ -1,5 +1,4 @@
 /**
- * Contract 合约接口
- * 字段名 camelCase 与 API JSON 天然一致，不改名、不加封装层
+ * Contract / TickSize models.
  */
 export {};

package/dist/esm/model/order-helpers.js

@@ -1,5 +1,5 @@
 import { OrderType, TimeInForce } from './enums';
-/** 构造市价单 */
+/** Market order */
 export function marketOrder(account, symbol, secType, action, quantity) {
     return {
         account, symbol, secType, action,
@@ -9,7 +9,7 @@ export function marketOrder(account, symbol, secType, action, quantity) {
         outsideRth: false,
     };
 }
-/** 构造限价单 */
+/** Limit order */
 export function limitOrder(account, symbol, secType, action, quantity, limitPrice) {
     return {
         account, symbol, secType, action,
@@ -20,7 +20,7 @@ export function limitOrder(account, symbol, secType, action, quantity, limitPric
         outsideRth: false,
     };
 }
-/** 构造止损单 */
+/** Stop order */
 export function stopOrder(account, symbol, secType, action, quantity, auxPrice) {
     return {
         account, symbol, secType, action,
@@ -31,7 +31,7 @@ export function stopOrder(account, symbol, secType, action, quantity, auxPrice)
         outsideRth: false,
     };
 }
-/** 构造止损限价单 */
+/** Stop limit order */
 export function stopLimitOrder(account, symbol, secType, action, quantity, limitPrice, auxPrice) {
     return {
         account, symbol, secType, action,
@@ -43,7 +43,7 @@ export function stopLimitOrder(account, symbol, secType, action, quantity, limit
         outsideRth: false,
     };
 }
-/** 构造跟踪止损单 */
+/** Trailing stop order */
 export function trailOrder(account, symbol, secType, action, quantity, trailingPercent) {
     return {
         account, symbol, secType, action,
@@ -54,7 +54,7 @@ export function trailOrder(account, symbol, secType, action, quantity, trailingP
         outsideRth: false,
     };
 }
-/** 构造竞价限价单 */
+/** Auction limit order */
 export function auctionLimitOrder(account, symbol, secType, action, quantity, limitPrice) {
     return {
         account, symbol, secType, action,
@@ -65,7 +65,7 @@ export function auctionLimitOrder(account, symbol, secType, action, quantity, li
         outsideRth: false,
     };
 }
-/** 构造竞价市价单 */
+/** Auction market order */
 export function auctionMarketOrder(account, symbol, secType, action, quantity) {
     return {
         account, symbol, secType, action,
@@ -75,7 +75,7 @@ export function auctionMarketOrder(account, symbol, secType, action, quantity) {
         outsideRth: false,
     };
 }
-/** 构造算法订单（TWAP/VWAP） */
+/** Algo order (TWAP / VWAP) */
 export function algoOrder(account, symbol, secType, action, quantity, limitPrice, algoType, params) {
     return {
         account, symbol, secType, action,
@@ -87,7 +87,7 @@ export function algoOrder(account, symbol, secType, action, quantity, limitPrice
         outsideRth: false,
     };
 }
-/** 构造附加订单（止盈/止损） */
+/** Attached profit / loss leg */
 export function orderLeg(legType, price, timeInForce) {
     return { legType, price, timeInForce };
 }

package/dist/esm/model/order.js

@@ -1,5 +1,8 @@
 /**
- * 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.
  */
 export {};

package/dist/esm/model/position.js

@@ -1,5 +1,4 @@
 /**
- * Position 持仓接口
- * 字段名 camelCase 与 API JSON 天然一致，不改名、不加封装层
+ * Position model.
  */
 export {};

package/dist/esm/model/quote.js

@@ -0,0 +1,6 @@
+/**
+ * Quote response & request models.
+ * All field names are camelCase (TypeScript idiom); request fields are
+ * converted to snake_case on the wire by the client layer.
+ */
+export {};

package/dist/esm/model/trade.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/push/index.js

@@ -1,6 +1,8 @@
 /**
- * 推送模块导出
+ * Push module exports
  */
-export * from './push-message';
+export { SubjectType } from './push-message';
 export * from './callbacks';
+export * from './varint';
+export * from './proto-message';
 export { PushClient, ConnectionState } from './push-client';