@tigeropenapi/tigeropen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tiger Fintech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# Tiger OpenAPI TypeScript SDK
+
+老虎证券 OpenAPI 的 TypeScript SDK，提供行情查询、交易下单、账户管理和实时推送等功能。
+
+[![npm version](https://img.shields.io/npm/v/@tigeropenapi/tigeropen.svg)](https://www.npmjs.com/package/@tigeropenapi/tigeropen)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 安装
+
+```bash
+npm install @tigeropenapi/tigeropen
+# 或
+yarn add @tigeropenapi/tigeropen
+# 或
+pnpm add @tigeropenapi/tigeropen
+```
+
+要求 Node.js >= 16.0.0。
+
+## Quick Start
+
+以下是一个完整的示例，从配置到查询行情：
+
+```typescript
+import { createClientConfig } from '@tigeropenapi/tigeropen';
+import { HttpClient } from '@tigeropenapi/tigeropen/client/http-client';
+import { QuoteClient } from '@tigeropenapi/tigeropen/quote/quote-client';
+
+// 1. 创建配置（从 properties 文件加载）
+const config = createClientConfig({
+  propertiesFilePath: 'tiger_openapi_config.properties',
+});
+
+// 2. 创建 HTTP 客户端
+const httpClient = new HttpClient(config);
+
+// 3. 创建行情客户端并查询
+const qc = new QuoteClient(httpClient);
+const states = await qc.getMarketState('US');
+console.log('美股市场状态:', states);
+```
+
+## 配置
+
+SDK 支持三种配置方式，优先级：**环境变量 > 代码设置（含配置文件） > 默认值**。
+
+### 方式一：代码直接设置
+
+```typescript
+import { createClientConfig } from '@tigeropenapi/tigeropen';
+
+const config = createClientConfig({
+  tigerId: '你的 tiger_id',
+  privateKey: '你的 RSA 私钥',
+  account: '你的交易账户',
+});
+```
+
+### 方式二：从 properties 配置文件加载
+
+```typescript
+const config = createClientConfig({
+  propertiesFilePath: 'tiger_openapi_config.properties',
+});
+```
+
+配置文件格式：
+
+```properties
+tiger_id=你的开发者ID
+private_key=你的RSA私钥
+account=你的交易账户
+```
+
+### 方式三：环境变量
+
+```bash
+export TIGEROPEN_TIGER_ID=你的开发者ID
+export TIGEROPEN_PRIVATE_KEY=你的RSA私钥
+export TIGEROPEN_ACCOUNT=你的交易账户
+```
+
+### 配置项说明
+
+| 配置项 | 说明 | 必填 | 默认值 |
+|--------|------|------|--------|
+| tigerId | 开发者 ID | 是 | - |
+| privateKey | RSA 私钥 | 是 | - |
+| account | 交易账户 | 否 | - |
+| language | 语言（zh_CN/en_US） | 否 | zh_CN |
+| timeout | 请求超时（秒） | 否 | 15 |
+| sandboxDebug | 是否使用沙箱环境 | 否 | false |
+
+## 行情查询
+
+```typescript
+import { HttpClient } from '@tigeropenapi/tigeropen/client/http-client';
+import { QuoteClient } from '@tigeropenapi/tigeropen/quote/quote-client';
+
+const httpClient = new HttpClient(config);
+const qc = new QuoteClient(httpClient);
+
+// 获取市场状态
+const states = await qc.getMarketState('US');
+
+// 获取实时报价
+const briefs = await qc.getBrief(['AAPL', 'TSLA']);
+
+// 获取 K 线数据
+const klines = await qc.getKline('AAPL', 'day');
+
+// 获取分时数据
+const timeline = await qc.getTimeline(['AAPL']);
+
+// 获取深度行情
+const depth = await qc.getQuoteDepth('AAPL');
+
+// 获取期权到期日
+const expiry = await qc.getOptionExpiration('AAPL');
+
+// 获取期权链
+const chain = await qc.getOptionChain('AAPL', '2024-01-19');
+
+// 获取期货交易所列表
+const exchanges = await qc.getFutureExchange();
+```
+
+## 交易操作
+
+```typescript
+import { HttpClient } from '@tigeropenapi/tigeropen/client/http-client';
+import { TradeClient } from '@tigeropenapi/tigeropen/trade/trade-client';
+
+const httpClient = new HttpClient(config);
+const tc = new TradeClient(httpClient, config.account);
+
+// 构造限价单
+const order = {
+  symbol: 'AAPL',
+  secType: 'STK',
+  action: 'BUY',
+  orderType: 'LMT',
+  totalQuantity: 100,
+  limitPrice: 150.0,
+  timeInForce: 'DAY',
+};
+
+// 下单
+const result = await tc.placeOrder(order);
+
+// 预览订单（不实际下单）
+const preview = await tc.previewOrder(order);
+
+// 修改订单
+const modifiedOrder = { ...order, limitPrice: 155.0 };
+await tc.modifyOrder(orderId, modifiedOrder);
+
+// 取消订单
+await tc.cancelOrder(orderId);
+
+// 查询全部订单
+const orders = await tc.getOrders();
+
+// 查询持仓
+const positions = await tc.getPositions();
+
+// 查询资产
+const assets = await tc.getAssets();
+```
+
+## 通用方法（execute）
+
+当 SDK 尚未封装某个 API 时，可以使用 `HttpClient.execute` 直接调用：
+
+```typescript
+const httpClient = new HttpClient(config);
+
+// 直接传入 API 方法名和 JSON 参数
+const resp = await httpClient.execute('market_state', JSON.stringify({ market: 'US' }));
+console.log('原始响应:', resp);
+```
+
+## 实时推送
+
+通过 WebSocket 长连接接收实时行情和账户推送，支持自动重连和心跳保活：
+
+```typescript
+import { PushClient } from '@tigeropenapi/tigeropen/push/push-client';
+
+const pc = new PushClient(config);
+
+// 设置回调
+pc.setCallbacks({
+  onQuote: (data) => {
+    console.log(`行情推送: ${data.symbol} 最新价: ${data.latestPrice}`);
+  },
+  onOrder: (data) => {
+    console.log(`订单推送: ${data.symbol} 状态: ${data.status}`);
+  },
+  onAsset: (data) => {
+    console.log('资产变动推送');
+  },
+  onPosition: (data) => {
+    console.log('持仓变动推送');
+  },
+  onConnect: () => {
+    console.log('推送连接成功');
+  },
+  onDisconnect: () => {
+    console.log('推送连接断开');
+  },
+  onError: (err) => {
+    console.error('推送错误:', err);
+  },
+});
+
+// 连接
+await pc.connect();
+
+// 订阅行情
+pc.subscribeQuote(['AAPL', 'TSLA']);
+
+// 订阅账户推送
+pc.subscribeAsset();
+pc.subscribeOrder();
+pc.subscribePosition();
+
+// 退订
+pc.unsubscribeQuote(['TSLA']);
+
+// 断开连接
+pc.disconnect();
+```
+
+## 项目结构
+
+```
+openapi-typescript-sdk/
+├── src/
+│   ├── config/    # 配置管理（ClientConfig、ConfigParser、动态域名）
+│   ├── signer/    # RSA 签名
+│   ├── client/    # HTTP 客户端（请求/响应、重试策略、execute）
+│   ├── model/     # 数据模型（Order、Contract、Position、枚举）
+│   ├── quote/     # 行情查询客户端
+│   ├── trade/     # 交易客户端
+│   ├── push/      # WebSocket 实时推送客户端
+│   ├── logger/    # 日志模块
+│   └── index.ts   # 统一导出
+├── examples/      # 示例代码
+└── tests/         # 测试
+```
+
+## ESM 和 CommonJS
+
+本 SDK 同时支持 ESM 和 CommonJS：
+
+```typescript
+// ESM
+import { createClientConfig } from '@tigeropenapi/tigeropen';
+
+// CommonJS
+const { createClientConfig } = require('@tigeropenapi/tigeropen');
+```
+
+## API 参考
+
+- [老虎证券 OpenAPI 文档](https://quant.itigerup.com/openapi/zh/python/overview/introduction.html)
+- [npm 包主页](https://www.npmjs.com/package/@tigeropenapi/tigeropen)
+
+## 许可证
+
+[MIT License](LICENSE)

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

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * API 请求构造模块
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiRequest = createApiRequest;
+/**
+ * 创建 API 请求，将业务参数序列化为 JSON 字符串作为 bizContent。
+ *
+ * @param method - API 方法名
+ * @param bizParams - 业务参数（对象、字符串或 null）
+ * @returns ApiRequest 对象
+ */
+function createApiRequest(method, bizParams) {
+    let bizContent;
+    if (typeof bizParams === 'string') {
+        bizContent = bizParams;
+    }
+    else if (bizParams == null) {
+        bizContent = '{}';
+    }
+    else {
+        bizContent = JSON.stringify(bizParams);
+    }
+    return { method, bizContent };
+}

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseApiResponse = parseApiResponse;
+/**
+ * API 响应解析模块
+ */
+const errors_1 = require("./errors");
+/**
+ * 解析 API 响应 JSON 字符串。
+ * code 为 0 时返回 ApiResponse；code 不为 0 时抛出 TigerError。
+ */
+function parseApiResponse(body) {
+    const resp = JSON.parse(body);
+    if (resp.code !== 0) {
+        throw new errors_1.TigerError(resp.code, resp.message);
+    }
+    return resp;
+}

package/dist/cjs/client/errors.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * 错误类型定义模块
+ *
+ * 定义 TigerError 及错误码分类逻辑。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TigerError = void 0;
+exports.classifyErrorCode = classifyErrorCode;
+/**
+ * 根据错误码返回对应的错误分类
+ */
+function classifyErrorCode(code) {
+    if (code === 0)
+        return 'success';
+    if (code === 5)
+        return 'rate_limit';
+    if (code >= 1000 && code < 1010)
+        return 'common_param_error';
+    if (code >= 1010 && code < 1100)
+        return 'biz_param_error';
+    if (code >= 1100 && code < 1200)
+        return 'trade_global_error';
+    if (code >= 1200 && code < 1300)
+        return 'trade_prime_error';
+    if (code >= 1300 && code < 2100)
+        return 'trade_simulation_error';
+    if (code >= 2100 && code < 2200)
+        return 'quote_stock_error';
+    if (code >= 2200 && code < 2300)
+        return 'quote_option_error';
+    if (code >= 2300 && code < 2400)
+        return 'quote_future_error';
+    if (code >= 2400 && code < 4000)
+        return 'token_error';
+    if (code >= 4000 && code < 5000)
+        return 'permission_error';
+    return 'unknown_error';
+}
+/**
+ * TigerError - 统一错误类型
+ */
+class TigerError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'TigerError';
+        this.code = code;
+        this.category = classifyErrorCode(code);
+    }
+}
+exports.TigerError = TigerError;

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

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const sign_content_1 = require("../signer/sign-content");
+const signer_1 = require("../signer/signer");
+const errors_1 = require("./errors");
+const retry_1 = require("./retry");
+const api_response_1 = require("./api-response");
+/** SDK 版本号 */
+const SDK_VERSION = '0.1.0';
+/** User-Agent 字符串 */
+const USER_AGENT = `openapi-typescript-sdk-${SDK_VERSION}`;
+/** 默认字符集 */
+const DEFAULT_CHARSET = 'UTF-8';
+/** 默认签名类型 */
+const DEFAULT_SIGN_TYPE = 'RSA';
+/** 默认 API 版本 */
+const DEFAULT_VERSION = '2.0';
+/**
+ * HttpClient 封装 HTTP 请求、签名、重试、超时
+ */
+class HttpClient {
+    constructor(config, retryPolicy) {
+        this.config = config;
+        this.retryPolicy = retryPolicy ?? (0, retry_1.defaultRetryPolicy)();
+    }
+    /**
+     * 构造公共请求参数
+     */
+    buildCommonParams(apiMethod, bizContent) {
+        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,
+            biz_content: bizContent,
+        };
+        if (this.config.language) {
+            params['language'] = this.config.language;
+        }
+        return params;
+    }
+    /**
+     * 对参数进行签名
+     */
+    signParams(params) {
+        const content = (0, sign_content_1.getSignContent)(params);
+        return (0, signer_1.signWithRSA)(this.config.privateKey, content);
+    }
+    /**
+     * 发送 HTTP POST 请求
+     */
+    async doHttpPost(params) {
+        const body = JSON.stringify(params);
+        const headers = {
+            'Content-Type': 'application/json;charset=UTF-8',
+            'User-Agent': USER_AGENT,
+        };
+        if (this.config.token) {
+            headers['Authorization'] = this.config.token;
+        }
+        const response = await fetch(this.config.serverUrl, {
+            method: 'POST',
+            headers,
+            body,
+            signal: AbortSignal.timeout(this.config.timeout * 1000),
+        });
+        return response.text();
+    }
+    /**
+     * 执行结构化 API 请求，返回解析后的 ApiResponse。
+     * 供 QuoteClient/TradeClient 内部使用。
+     */
+    async executeRequest(request) {
+        const params = this.buildCommonParams(request.method, request.bizContent);
+        const sign = this.signParams(params);
+        params['sign'] = sign;
+        let lastErr;
+        const maxAttempts = this.retryPolicy.shouldRetry(request.method)
+            ? this.retryPolicy.maxRetries + 1
+            : 1;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (attempt > 0) {
+                const backoff = this.retryPolicy.calculateBackoff(attempt - 1);
+                await this.sleep(backoff);
+            }
+            try {
+                const body = await this.doHttpPost(params);
+                return (0, api_response_1.parseApiResponse)(body);
+            }
+            catch (err) {
+                lastErr = err;
+                if (!this.retryPolicy.shouldRetry(request.method)) {
+                    throw err;
+                }
+            }
+        }
+        throw lastErr;
+    }
+    /**
+     * 通用 API 调用方法。
+     *
+     * @param apiMethod - API 方法名（如 "market_state"、"place_order"）
+     * @param requestJson - 原始 biz_content JSON 字符串
+     * @returns 原始 response JSON 字符串，不做任何解析
+     */
+    async execute(apiMethod, requestJson) {
+        // 参数校验
+        if (!apiMethod) {
+            throw new errors_1.TigerError(-1, 'api_method 不能为空');
+        }
+        try {
+            JSON.parse(requestJson);
+        }
+        catch {
+            throw new errors_1.TigerError(-1, 'request_json 不是有效的 JSON');
+        }
+        const params = this.buildCommonParams(apiMethod, requestJson);
+        const sign = this.signParams(params);
+        params['sign'] = sign;
+        let lastErr;
+        const maxAttempts = this.retryPolicy.shouldRetry(apiMethod)
+            ? this.retryPolicy.maxRetries + 1
+            : 1;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (attempt > 0) {
+                const backoff = this.retryPolicy.calculateBackoff(attempt - 1);
+                await this.sleep(backoff);
+            }
+            try {
+                return await this.doHttpPost(params);
+            }
+            catch (err) {
+                lastErr = err;
+                if (!this.retryPolicy.shouldRetry(apiMethod)) {
+                    throw err;
+                }
+            }
+        }
+        throw lastErr;
+    }
+    /** 延迟指定毫秒 */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/cjs/client/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseApiResponse = exports.createApiRequest = exports.isTradeOperation = exports.defaultRetryPolicy = exports.RetryPolicy = exports.classifyErrorCode = exports.TigerError = exports.HttpClient = void 0;
+/**
+ * 传输层模块导出
+ */
+var http_client_1 = require("./http-client");
+Object.defineProperty(exports, "HttpClient", { enumerable: true, get: function () { return http_client_1.HttpClient; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "TigerError", { enumerable: true, get: function () { return errors_1.TigerError; } });
+Object.defineProperty(exports, "classifyErrorCode", { enumerable: true, get: function () { return errors_1.classifyErrorCode; } });
+var retry_1 = require("./retry");
+Object.defineProperty(exports, "RetryPolicy", { enumerable: true, get: function () { return retry_1.RetryPolicy; } });
+Object.defineProperty(exports, "defaultRetryPolicy", { enumerable: true, get: function () { return retry_1.defaultRetryPolicy; } });
+Object.defineProperty(exports, "isTradeOperation", { enumerable: true, get: function () { return retry_1.isTradeOperation; } });
+var api_request_1 = require("./api-request");
+Object.defineProperty(exports, "createApiRequest", { enumerable: true, get: function () { return api_request_1.createApiRequest; } });
+var api_response_1 = require("./api-response");
+Object.defineProperty(exports, "parseApiResponse", { enumerable: true, get: function () { return api_response_1.parseApiResponse; } });

package/dist/cjs/client/retry.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * 重试策略模块
+ *
+ * 提供指数退避重试策略，交易操作（place_order/modify_order/cancel_order）跳过重试。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryPolicy = void 0;
+exports.isTradeOperation = isTradeOperation;
+exports.defaultRetryPolicy = defaultRetryPolicy;
+/** 交易操作方法名集合 */
+const TRADE_OPERATIONS = new Set(['place_order', 'modify_order', 'cancel_order']);
+/**
+ * 判断是否为交易操作
+ */
+function isTradeOperation(apiMethod) {
+    return TRADE_OPERATIONS.has(apiMethod);
+}
+/**
+ * 重试策略
+ */
+class RetryPolicy {
+    constructor(options) {
+        this.maxRetries = options?.maxRetries ?? 5;
+        this.maxRetryTime = options?.maxRetryTime ?? 60000;
+        this.baseDelay = options?.baseDelay ?? 1000;
+        this.maxDelay = options?.maxDelay ?? 16000;
+    }
+    /**
+     * 判断指定的 API 方法是否应该重试。
+     * 交易操作跳过重试。
+     */
+    shouldRetry(apiMethod) {
+        return !isTradeOperation(apiMethod);
+    }
+    /**
+     * 计算第 n 次重试的退避等待时间（毫秒，从 0 开始计数）。
+     * 退避公式：min(2^n * baseDelay, maxDelay)
+     */
+    calculateBackoff(retryCount) {
+        if (retryCount < 0) {
+            return this.baseDelay;
+        }
+        const delay = Math.pow(2, retryCount) * this.baseDelay;
+        return Math.min(delay, this.maxDelay);
+    }
+}
+exports.RetryPolicy = RetryPolicy;
+/**
+ * 返回默认重试策略
+ */
+function defaultRetryPolicy() {
+    return new RetryPolicy();
+}