@tigeropenapi/tigeropen 0.5.3 → 0.5.5

package/README.md

@@ -486,8 +486,61 @@ const chain = await qc.optionChain('AAPL', '2024-01-19');
 
 // 期货交易所
 const exchanges = await qc.futureExchange();
+
+// 逐笔成交
+const ticks = await qc.getTradeTick({ symbols: ['AAPL'] });
+// ticks[0].items[i].partCode  — 交易所短名，如 "NYSE"、"NSDQ"
+// ticks[0].items[i].partName  — 交易所全名，如 "New York Stock Exchange, LLC (NYSE)"
+// ticks[0].items[i].cond      — 已转换的成交条件，如 "US_REGULAR_SALE"，参见下方说明
 ```
 
+### 逐笔成交 `cond` 字段说明
+
+`trade_tick` 接口和 push 层返回的 `cond` 字段已由 SDK 转换为可读字符串，含义如下：
+
+**美股（US）**
+
+| 字符 | 含义 |
+|------|------|
+| ` `（空格）| 常规交易（Regular Sale） |
+| `B` | 批量交易（Bunched Trade） |
+| `C` | 现金交易（Cash Trade） |
+| `F` | 跨市场交易（Intermarket Sweep） |
+| `G` | 批量卖出（Bunched Sold Trade） |
+| `H` | 离价交易（Price Variation Trade） |
+| `I` | 碎股交易（Odd Lot Trade） |
+| `K` | 纽交所第 127/155 条交易 |
+| `L` | 延迟交易（Sold Last） |
+| `M` | 中央收市价（Market Center Close Price） |
+| `N` | 隔日交易（Next Day Trade） |
+| `O` | 中央开盘价交易（Market Center Opening Trade） |
+| `P` | 前参考价（Prior Reference Price） |
+| `Q` | 中央开盘价（Market Center Open Price） |
+| `R` | 卖方（Seller） |
+| `T` | 盘前盘后交易（Form T） |
+| `U` | 延长交易时段（Extended Trading Hours） |
+| `V` | 合单交易（Contingent Trade） |
+| `W` | 均价交易（Average Price Trade） |
+| `X` | 跨市场交易（Cross Trade） |
+| `Z` | 场外售出（Sold Out of Sequence） |
+| `4` | 衍生工具定价（Derivatively Priced） |
+| `7` | 合单交易（Qualified Contingent Trade） |
+
+**港股（HK）**
+
+| 字符 | 含义 |
+|------|------|
+| ` `（空格）| 自动对盘（Automatch Normal） |
+| `D` | 碎股交易（Odd Lot Trade） |
+| `U` | 竞价交易（Auction Trade） |
+| `*` | 场外交易（Overseas Trade） |
+| `P` | 开市前成交（Late Trade Off Exchange） |
+| `M` | 非自动对盘（Non-Direct Off Exchange Trade） |
+| `X` | 同券商自动对盘（Direct Off Exchange Trade） |
+| `Y` | 同券商非自动对盘（Automatic Internalized） |
+
+如上表所示，`cond` 值因市场（美股/港股）不同而有所区别。
+
 ## 交易
 
 ```typescript

package/dist/cjs/client/token-methods.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryToken = queryToken;
+exports.refreshToken = refreshToken;
+exports.startTokenAutoRefresh = startTokenAutoRefresh;
+/**
+ * Call the `user_token_refresh` API and return the new token string.
+ * Read-only: does NOT update the stored token.
+ * Use `refreshToken()` to also update the in-memory config and optionally persist.
+ */
+async function queryToken(httpClient) {
+    return httpClient.queryToken();
+}
+/**
+ * Refresh the token: call the API, update the in-memory config token, and
+ * optionally persist via the provided TokenManager (file + writer callback).
+ *
+ * @param httpClient - The underlying HTTP client
+ * @param tokenManager - optional TokenManager for file persistence and writer callback
+ */
+async function refreshToken(httpClient, tokenManager) {
+    return httpClient.refreshToken(tokenManager);
+}
+/**
+ * Start background token auto-refresh. Returns a TokenManager that can be
+ * used to stop the background task via `tm.stopAutoRefresh()`.
+ *
+ * @param httpClient - The underlying HTTP client
+ * @param refreshDurationSecs - Refresh threshold in seconds (minimum 30).
+ *   When the token age exceeds this value the refresh is triggered.
+ * @param checkIntervalMs - How often to check whether a refresh is needed,
+ *   in milliseconds. Defaults to 300 000 ms (5 minutes).
+ * @param tokenWriter - Optional callback invoked with the new token string
+ *   after each successful refresh.
+ */
+function startTokenAutoRefresh(httpClient, refreshDurationSecs, checkIntervalMs, tokenWriter) {
+    return httpClient.startTokenAutoRefresh(null, {
+        refreshDuration: refreshDurationSecs,
+        refreshInterval: checkIntervalMs,
+        tokenWriter,
+    });
+}

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

@@ -113,23 +113,32 @@ function createClientConfig(options) {
     const opts = options ?? {};
     // Load properties: explicit path > auto-discovery
     let fileProps = {};
+    let configFileDir;
     if (opts.propertiesFilePath) {
         // Support both directory path and full file path
         let filePath = opts.propertiesFilePath;
         if ((0, fs_1.existsSync)(filePath) && (0, fs_1.statSync)(filePath).isDirectory()) {
+            configFileDir = filePath;
             filePath = (0, path_1.join)(filePath, CONFIG_FILE_NAME);
         }
         else if (!(0, fs_1.existsSync)(filePath) && !filePath.endsWith('.properties')) {
             // Path doesn't exist as-is; try treating it as a directory
             const asDir = (0, path_1.join)(filePath, CONFIG_FILE_NAME);
-            if ((0, fs_1.existsSync)(asDir))
+            if ((0, fs_1.existsSync)(asDir)) {
+                configFileDir = filePath;
                 filePath = asDir;
+            }
+        }
+        else {
+            // It's a file path: derive directory from it
+            configFileDir = (0, path_1.dirname)(filePath);
         }
         fileProps = loadPropertiesFile(filePath);
     }
     else {
         const discovered = discoverConfigFile();
         if (discovered) {
+            configFileDir = (0, path_1.dirname)(discovered);
             fileProps = loadPropertiesFile(discovered);
         }
     }
@@ -189,8 +198,9 @@ function createClientConfig(options) {
             }
         }
         else {
-            // Load from token file: TIGEROPEN_TOKEN_FILE env var > default file
-            const tokenFilePath = process.env[ENV_TOKEN_FILE] || 'tiger_openapi_token.properties';
+            // Load from token file: TIGEROPEN_TOKEN_FILE env var > config dir > default
+            const tokenFilePath = process.env[ENV_TOKEN_FILE]
+                || (configFileDir ? (0, path_1.join)(configFileDir, 'tiger_openapi_token.properties') : 'tiger_openapi_token.properties');
             const tm = new token_manager_1.TokenManager({ filePath: tokenFilePath });
             try {
                 token = tm.loadTokenSync();

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

@@ -9,8 +9,14 @@ exports.auctionLimitOrder = auctionLimitOrder;
 exports.auctionMarketOrder = auctionMarketOrder;
 exports.algoOrder = algoOrder;
 exports.icebergOrder = icebergOrder;
-exports.icebergOrderFull = icebergOrderFull;
 exports.orderLeg = orderLeg;
+exports.marketOrderByAmount = marketOrderByAmount;
+exports.limitOrderByAmount = limitOrderByAmount;
+exports.trailOrderByPrice = trailOrderByPrice;
+exports.limitOrderWithLegs = limitOrderWithLegs;
+exports.comboOrder = comboOrder;
+exports.ocaOrder = ocaOrder;
+exports.contractLeg = contractLeg;
 const enums_1 = require("./enums");
 /** Market order */
 function marketOrder(account, symbol, secType, action, quantity) {
@@ -101,26 +107,11 @@ function algoOrder(account, symbol, secType, action, quantity, limitPrice, algoT
     };
 }
 /**
- * Iceberg order (basic) — only displaySize required.
- */
-function icebergOrder(account, symbol, secType, action, quantity, limitPrice, displaySize) {
-    return {
-        account, symbol, secType, action,
-        orderType: enums_1.OrderType.ICEBERG,
-        totalQuantity: quantity,
-        limitPrice,
-        timeInForce: enums_1.TimeInForce.DAY,
-        outsideRth: false,
-        displaySize,
-        priceType: enums_1.PriceType.LIMIT_PRICE,
-    };
-}
-/**
- * Iceberg order (full params).
- * Pass `priceType` as empty string to use server default (LIMIT_PRICE).
+ * Iceberg order. `displaySize` is required; all other parameters are optional.
+ * Pass `priceType` as empty string to use the server default (LIMIT_PRICE).
  * Pass `startTime` / `endTime` as 0 to omit the time window.
  */
-function icebergOrderFull(account, symbol, secType, action, quantity, limitPrice, displaySize, minDisplaySize, checkIntervals, priceType, startTime, endTime) {
+function icebergOrder(account, symbol, secType, action, quantity, limitPrice, displaySize, minDisplaySize, checkIntervals, priceType, startTime, endTime) {
     const req = {
         account, symbol, secType, action,
         orderType: enums_1.OrderType.ICEBERG,
@@ -129,13 +120,12 @@ function icebergOrderFull(account, symbol, secType, action, quantity, limitPrice
         timeInForce: enums_1.TimeInForce.DAY,
         outsideRth: false,
         displaySize,
+        priceType: priceType || enums_1.PriceType.LIMIT_PRICE,
     };
     if (minDisplaySize !== undefined && minDisplaySize > 0)
         req.minDisplaySize = minDisplaySize;
     if (checkIntervals !== undefined && checkIntervals > 0)
         req.checkIntervals = checkIntervals;
-    if (priceType)
-        req.priceType = priceType;
     if (startTime && startTime > 0)
         req.startTime = startTime;
     if (endTime && endTime > 0)
@@ -146,3 +136,118 @@ function icebergOrderFull(account, symbol, secType, action, quantity, limitPrice
 function orderLeg(legType, price, timeInForce) {
     return { legType, price, timeInForce };
 }
+/**
+ * Market order by cash amount (instead of quantity).
+ * Server uses `isQuantityByAmount=true` + `amount` field.
+ */
+function marketOrderByAmount(account, symbol, secType, action, amount) {
+    return {
+        account, symbol, secType, action,
+        orderType: enums_1.OrderType.MKT,
+        totalQuantity: 0,
+        cashAmount: amount,
+        timeInForce: enums_1.TimeInForce.DAY,
+        outsideRth: false,
+    };
+}
+/**
+ * Limit order by cash amount (instead of quantity).
+ */
+function limitOrderByAmount(account, symbol, secType, action, amount, limitPrice) {
+    return {
+        account, symbol, secType, action,
+        orderType: enums_1.OrderType.LMT,
+        totalQuantity: 0,
+        cashAmount: amount,
+        limitPrice,
+        timeInForce: enums_1.TimeInForce.DAY,
+        outsideRth: false,
+    };
+}
+/**
+ * Trailing stop order using a fixed price offset (auxPrice) instead of a percentage.
+ * Use `trailOrder()` for percentage-based trailing stops.
+ */
+function trailOrderByPrice(account, symbol, secType, action, quantity, auxPrice) {
+    return {
+        account, symbol, secType, action,
+        orderType: enums_1.OrderType.TRAIL,
+        totalQuantity: quantity,
+        auxPrice,
+        timeInForce: enums_1.TimeInForce.DAY,
+        outsideRth: false,
+    };
+}
+/**
+ * Limit order with attached profit/loss legs (bracket order).
+ * At most 2 legs are supported.
+ *
+ * @param orderLegs - Array of `OrderLegRequest` (use `orderLeg()` helper)
+ */
+function limitOrderWithLegs(account, symbol, secType, action, quantity, limitPrice, orderLegs) {
+    if (orderLegs.length === 0) {
+        throw new Error('At least 1 order leg is required for a bracket order');
+    }
+    if (orderLegs.length > 2) {
+        throw new Error('At most 2 order legs are supported');
+    }
+    return {
+        account, symbol, secType, action,
+        orderType: enums_1.OrderType.LMT,
+        totalQuantity: quantity,
+        limitPrice,
+        orderLegs,
+        timeInForce: enums_1.TimeInForce.DAY,
+        outsideRth: false,
+    };
+}
+/**
+ * Multi-leg (combo/MLEG) order for options combos.
+ *
+ * @param contractLegs - Array of `ContractLegRequest` (use `contractLeg()` helper)
+ * @param comboType - e.g. `'MLEG'`
+ */
+function comboOrder(account, action, quantity, orderType, contractLegs, comboType = 'MLEG', limitPrice, auxPrice, trailingPercent) {
+    return {
+        account,
+        symbol: '', // not used for combo orders
+        secType: 'MLEG',
+        action,
+        orderType,
+        totalQuantity: quantity,
+        limitPrice,
+        auxPrice,
+        trailingPercent,
+        contractLegs,
+        comboType,
+        timeInForce: enums_1.TimeInForce.DAY,
+        outsideRth: false,
+    };
+}
+/**
+ * OCA (One-Cancels-All) order.
+ * Server expects `orderType: 'OCA'` and an `ocaOrders` list.
+ *
+ * @param ocaOrders - The contained orders (use any order helper to build each)
+ */
+function ocaOrder(account, symbol, secType, action, quantity, ocaOrders) {
+    return {
+        account, symbol, secType, action,
+        orderType: enums_1.OrderType.OCA,
+        totalQuantity: quantity,
+        ocaOrders,
+        timeInForce: enums_1.TimeInForce.DAY,
+        outsideRth: false,
+    };
+}
+/**
+ * Build a single leg for a multi-leg (MLEG / combo) order.
+ *
+ * @param symbol   - Underlying symbol
+ * @param secType  - Security type (e.g. `'OPT'`)
+ * @param action   - `'BUY'` or `'SELL'`
+ * @param ratio    - Number of contracts for this leg
+ */
+function contractLeg(symbol, secType, action, ratio, expiry, strike, right) {
+    return { symbol, secType, action, ratio, expiry, strike, right };
+}

package/dist/cjs/push/index.js

@@ -22,6 +22,7 @@ var push_message_1 = require("./push-message");
 Object.defineProperty(exports, "SubjectType", { enumerable: true, get: function () { return push_message_1.SubjectType; } });
 __exportStar(require("./callbacks"), exports);
 __exportStar(require("./varint"), exports);
+__exportStar(require("./tick-util"), exports);
 __exportStar(require("./proto-message"), exports);
 var push_client_1 = require("./push-client");
 Object.defineProperty(exports, "PushClient", { enumerable: true, get: function () { return push_client_1.PushClient; } });

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

@@ -47,6 +47,7 @@ exports.PushClient = exports.ConnectionState = void 0;
 const tls = __importStar(require("tls"));
 const signer_1 = require("../signer/signer");
 const push_message_1 = require("./push-message");
+const tick_util_1 = require("./tick-util");
 const Request_1 = require("./pb/Request");
 const Response_1 = require("./pb/Response");
 const SocketCommon_1 = require("./pb/SocketCommon");
@@ -378,8 +379,10 @@ class PushClient {
                     cb.onDepth?.(pushData.quoteDepthData);
                 break;
             case SocketCommon_1.SocketCommon_DataType.TradeTick:
+                if (pushData.tickData)
+                    cb.onFullTick?.(pushData.tickData);
                 if (pushData.tradeTickData)
-                    cb.onTick?.(pushData.tradeTickData);
+                    cb.onTick?.((0, tick_util_1.convertTradeTick)(pushData.tradeTickData));
                 break;
             case SocketCommon_1.SocketCommon_DataType.Asset:
                 if (pushData.assetData)
@@ -415,8 +418,7 @@ class PushClient {
                     cb.onQuote?.(pushData.quoteData);
                 break;
             default:
-                // FullTick and QuoteBBO use TradeTick/Quote dataType
-                // TickData (fullTick) via tickData field
+                // QuoteBBO and some full-tick payloads reuse an existing dataType.
                 if (pushData.tickData)
                     cb.onFullTick?.(pushData.tickData);
                 break;

package/dist/cjs/push/tick-util.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPartNameByCode = getPartNameByCode;
+exports.getPartShortNameByCode = getPartShortNameByCode;
+exports.getTradeCondByCode = getTradeCondByCode;
+exports.isUsStockSymbol = isUsStockSymbol;
+exports.convertTradeTick = convertTradeTick;
+const PART_CODE_NAME_MAP = {
+    a: 'NYSE American, LLC (NYSE American)',
+    b: 'NASDAQ OMX BX, Inc. (NASDAQ OMX BX)',
+    c: 'NYSE National, Inc. (NYSE National)',
+    d: 'FINRA Alternative Display Facility (ADF)',
+    h: 'MIAX Pearl Exchange, LLC (MIAX)',
+    i: 'International Securities Exchange, LLC (ISE)',
+    j: 'Cboe EDGA Exchange, Inc. (Cboe EDGA)',
+    k: 'Cboe EDGX Exchange, Inc. (Cboe EDGX)',
+    l: 'Long-Term Stock Exchange, Inc. (LTSE)',
+    m: 'NYSE Chicago, Inc. (NYSE Chicago)',
+    n: 'New York Stock Exchange, LLC (NYSE)',
+    p: 'NYSE Arca, Inc. (NYSE Arca)',
+    s: 'Consolidated Tape System (CTS)',
+    t: 'NASDAQ Stock Market, LLC (NASDAQ)',
+    u: 'Members Exchange, LLC (MEMX)',
+    v: "Investors' Exchange, LLC. (IEX)",
+    w: 'CBOE Stock Exchange, Inc. (CBSX)',
+    x: 'NASDAQ OMX PSX, Inc. (NASDAQ OMX PSX)',
+    y: 'Cboe BYX Exchange, Inc. (Cboe BYX)',
+    z: 'Cboe BZX Exchange, Inc. (Cboe BZX)',
+};
+const PART_CODE_SHORT_NAME_MAP = {
+    a: 'AMEX',
+    b: 'BX',
+    c: 'NSX',
+    d: 'ADF',
+    h: 'MIAX',
+    i: 'ISE',
+    j: 'EDGA',
+    k: 'EDGX',
+    l: 'LTSE',
+    m: 'CHO',
+    n: 'NYSE',
+    p: 'ARCA',
+    s: 'CTS',
+    t: 'NSDQ',
+    u: 'MEMX',
+    v: 'IEX',
+    w: 'CBSX',
+    x: 'PSX',
+    y: 'BYX',
+    z: 'BZX',
+};
+const US_TRADE_COND = {
+    ' ': 'US_REGULAR_SALE',
+    B: 'US_BUNCHED_TRADE',
+    C: 'US_CASH_TRADE',
+    F: 'US_INTERMARKET_SWEEP',
+    G: 'US_BUNCHED_SOLD_TRADE',
+    H: 'US_PRICE_VARIATION_TRADE',
+    I: 'US_ODD_LOT_TRADE',
+    K: 'US_RULE_127_OR_155_TRADE',
+    L: 'US_SOLD_LAST',
+    M: 'US_MARKET_CENTER_CLOSE_PRICE',
+    N: 'US_NEXT_DAY_TRADE',
+    O: 'US_MARKET_CENTER_OPENING_TRADE',
+    P: 'US_PRIOR_REFERENCE_PRICE',
+    Q: 'US_MARKET_CENTER_OPEN_PRICE',
+    R: 'US_SELLER',
+    T: 'US_FORM_T',
+    U: 'US_EXTENDED_TRADING_HOURS',
+    V: 'US_CONTINGENT_TRADE',
+    W: 'US_AVERAGE_PRICE_TRADE',
+    X: 'US_CROSS_TRADE',
+    Z: 'US_SOLD_OUT_OF_SEQUENCE',
+    '0': 'US_ODD_LOST_CROSS_TRADE',
+    '4': 'US_DERIVATIVELY_PRICED',
+    '5': 'US_MARKET_CENTER_RE_OPENING_TRADE',
+    '6': 'US_MARKET_CENTER_CLOSING_TRADE',
+    '7': 'US_QUALIFIED_CONTINGENT_TRADE',
+    '9': 'US_CONSOLIDATED_LAST_PRICE_PER_LISTING_PACKET',
+};
+const HK_TRADE_COND = {
+    ' ': 'HK_AUTOMATCH_NORMAL',
+    D: 'HK_ODD_LOT_TRADE',
+    U: 'HK_AUCTION_TRADE',
+    '*': 'HK_OVERSEAS_TRADE',
+    P: 'HK_LATE_TRADE_OFF_EXCHG',
+    M: 'HK_NON_DIRECT_OFF_EXCHG_TRADE',
+    X: 'HK_DIRECT_OFF_EXCHG_TRADE',
+    Y: 'HK_AUTOMATIC_INTERNALIZED',
+};
+/** Returns the full exchange name for a partCode letter, or the raw code if unknown. */
+function getPartNameByCode(code) {
+    if (!code)
+        return code;
+    return PART_CODE_NAME_MAP[code] ?? code;
+}
+/** Returns the short exchange name for a partCode letter, or the raw code if unknown. */
+function getPartShortNameByCode(code) {
+    if (!code)
+        return code;
+    return PART_CODE_SHORT_NAME_MAP[code] ?? code;
+}
+/** Resolves a raw cond character to a readable string. */
+function getTradeCondByCode(isUs, ch) {
+    const map = isUs ? US_TRADE_COND : HK_TRADE_COND;
+    return map[ch] ?? ch;
+}
+const US_SYMBOL_RE = /^[A-Z]+(\.[A-Z0-9]+)?$/;
+/** Reports whether symbol is a US stock (uppercase letters, optional dot suffix). */
+function isUsStockSymbol(symbol) {
+    return US_SYMBOL_RE.test(symbol);
+}
+function isUsSymbol(symbol) {
+    return US_SYMBOL_RE.test(symbol);
+}
+function getTradeCond(isUs, ch) {
+    const map = isUs ? US_TRADE_COND : HK_TRADE_COND;
+    return map[ch] ?? ch;
+}
+/** Decodes a TradeTickData pb message into a PushTradeTick with resolved partCode/partName. */
+function convertTradeTick(src) {
+    if (src.secType === 'FUT')
+        return convertFutureTick(src);
+    return convertStockTick(src);
+}
+function convertStockTick(src) {
+    const isUs = isUsSymbol(src.symbol);
+    const denominator = Math.pow(10, src.priceOffset);
+    const ticks = [];
+    let currentTime = 0;
+    for (let i = 0; i < src.time.length; i++) {
+        currentTime += src.time[i];
+        const condCh = src.cond.length > i ? src.cond[i] : ' ';
+        const rawCode = i < src.partCode.length ? src.partCode[i] : '';
+        ticks.push({
+            sn: src.sn + i,
+            time: currentTime,
+            price: (src.priceBase + src.price[i]) / denominator,
+            volume: src.volume[i],
+            tickType: src.type.length > i ? src.type[i] : '',
+            cond: getTradeCond(isUs, condCh),
+            partCode: getPartShortNameByCode(rawCode),
+            partName: getPartNameByCode(rawCode),
+        });
+    }
+    return { symbol: src.symbol, secType: src.secType, quoteLevel: src.quoteLevel, timestamp: src.timestamp, ticks };
+}
+function convertFutureTick(src) {
+    const denominator = Math.pow(10, src.priceOffset);
+    const ticks = [];
+    let currentTime = 0;
+    let startSn = src.sn;
+    for (let i = 0; i < src.time.length; i++) {
+        currentTime += src.time[i];
+        const curPrice = (src.priceBase + src.price[i]) / denominator;
+        const mv = src.mergedVols[i];
+        for (let j = 0; j < mv.vol.length; j++) {
+            ticks.push({
+                sn: startSn * 10 + j,
+                time: currentTime,
+                price: curPrice,
+                volume: mv.vol[j],
+                tickType: '',
+                cond: '',
+                partCode: '',
+                partName: '',
+            });
+        }
+        startSn++;
+    }
+    return { symbol: src.symbol, secType: src.secType, quoteLevel: '', timestamp: src.timestamp, ticks };
+}