@tigeropenapi/tigeropen 0.5.3 → 0.5.4

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/quote/quote-client.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QuoteClient = void 0;
 exports.parseOptionIdentifier = parseOptionIdentifier;
@@ -12,6 +45,7 @@ exports.parseOptionIdentifier = parseOptionIdentifier;
 const http_client_1 = require("../client/http-client");
 const api_request_1 = require("../client/api-request");
 const api_response_1 = require("../client/api-response");
+const tokenMethods = __importStar(require("../client/token-methods"));
 /**
  * resolveOptionTimezone returns the timezone string to use for expiry conversion.
  * Explicit tz takes precedence; otherwise infer from symbol (.HK suffix → Asia/Hong_Kong, else America/New_York).
@@ -94,6 +128,25 @@ class QuoteClient {
     static fromConfig(config) {
         return new QuoteClient(new http_client_1.HttpClient(config, undefined, { useQuoteServerUrl: true }));
     }
+    // ── Token management ──────────────────────────────────────────────────────
+    /** Call the `user_token_refresh` API and return the new token. Read-only. */
+    async queryToken() {
+        return tokenMethods.queryToken(this.httpClient);
+    }
+    /** Refresh the token and update the in-memory config token. */
+    async refreshToken(tokenManager) {
+        return tokenMethods.refreshToken(this.httpClient, tokenManager);
+    }
+    /**
+     * Start background token auto-refresh. Returns a TokenManager to stop with `tm.stopAutoRefresh()`.
+     *
+     * @param refreshDurationSecs - Refresh threshold in seconds (minimum 30).
+     * @param checkIntervalMs - How often to check, in milliseconds (default 300 000 / 5 min).
+     * @param tokenWriter - Optional callback invoked after each successful refresh.
+     */
+    startTokenAutoRefresh(refreshDurationSecs, checkIntervalMs, tokenWriter) {
+        return tokenMethods.startTokenAutoRefresh(this.httpClient, refreshDurationSecs, checkIntervalMs, tokenWriter);
+    }
     async callInto(method, bizParams, version) {
         const request = (0, api_request_1.createApiRequest)(method, bizParams, version);
         const response = await this.httpClient.executeRequest(request);

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

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TradeClient = void 0;
 /**
@@ -13,6 +46,7 @@ exports.TradeClient = void 0;
 const http_client_1 = require("../client/http-client");
 const api_request_1 = require("../client/api-request");
 const api_response_1 = require("../client/api-response");
+const tokenMethods = __importStar(require("../client/token-methods"));
 const order_status_1 = require("../model/order-status");
 /** Normalize `Order.status` field in-place (handles int → string). */
 function normalizeOrderInPlace(o) {
@@ -44,6 +78,31 @@ class TradeClient {
     static fromConfig(config, account, secretKey) {
         return new TradeClient(new http_client_1.HttpClient(config), account, secretKey);
     }
+    // ── Token management ──────────────────────────────────────────────────────
+    /** Call the `user_token_refresh` API and return the new token. Read-only. */
+    async queryToken() {
+        return tokenMethods.queryToken(this.httpClient);
+    }
+    /**
+     * Refresh the token: call the API, update the in-memory config token, and
+     * optionally persist via the provided TokenManager (file + writer callback).
+     *
+     * @param tokenManager - optional TokenManager for file persistence and writer callback
+     */
+    async refreshToken(tokenManager) {
+        return tokenMethods.refreshToken(this.httpClient, tokenManager);
+    }
+    /**
+     * Start background token auto-refresh. Returns a TokenManager that can be
+     * used to stop the background task via `tm.stopAutoRefresh()`.
+     *
+     * @param refreshDurationSecs - Refresh threshold in seconds (minimum 30).
+     * @param checkIntervalMs - How often to check, in milliseconds (default 300 000 / 5 min).
+     * @param tokenWriter - Optional callback invoked after each successful refresh.
+     */
+    startTokenAutoRefresh(refreshDurationSecs, checkIntervalMs, tokenWriter) {
+        return tokenMethods.startTokenAutoRefresh(this.httpClient, refreshDurationSecs, checkIntervalMs, tokenWriter);
+    }
     async callInto(method, bizParams) {
         // Inject secretKey into every request when available (institution accounts require it).
         // Individual methods that already set secretKey will not be overwritten (|| not &&).

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

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+export 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
+ */
+export 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.
+ */
+export function startTokenAutoRefresh(httpClient, refreshDurationSecs, checkIntervalMs, tokenWriter) {
+    return httpClient.startTokenAutoRefresh(null, {
+        refreshDuration: refreshDurationSecs,
+        refreshInterval: checkIntervalMs,
+        tokenWriter,
+    });
+}

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

@@ -9,7 +9,7 @@
  * Priority: environment variables > code options (incl. config file) > defaults
  */
 import { readFileSync, existsSync, statSync } from 'fs';
-import { join } from 'path';
+import { join, dirname } from 'path';
 import { homedir, networkInterfaces } from 'os';
 import { parsePropertiesString } from './config-parser.js';
 import { queryDomains, resolveDynamicServerUrl, resolveDynamicQuoteServerUrl } from './domain.js';
@@ -108,23 +108,32 @@ export 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 (existsSync(filePath) && statSync(filePath).isDirectory()) {
+            configFileDir = filePath;
             filePath = join(filePath, CONFIG_FILE_NAME);
         }
         else if (!existsSync(filePath) && !filePath.endsWith('.properties')) {
             // Path doesn't exist as-is; try treating it as a directory
             const asDir = join(filePath, CONFIG_FILE_NAME);
-            if (existsSync(asDir))
+            if (existsSync(asDir)) {
+                configFileDir = filePath;
                 filePath = asDir;
+            }
+        }
+        else {
+            // It's a file path: derive directory from it
+            configFileDir = dirname(filePath);
         }
         fileProps = loadPropertiesFile(filePath);
     }
     else {
         const discovered = discoverConfigFile();
         if (discovered) {
+            configFileDir = dirname(discovered);
             fileProps = loadPropertiesFile(discovered);
         }
     }
@@ -184,8 +193,9 @@ export 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 ? join(configFileDir, 'tiger_openapi_token.properties') : 'tiger_openapi_token.properties');
             const tm = new TokenManager({ filePath: tokenFilePath });
             try {
                 token = tm.loadTokenSync();

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

@@ -88,26 +88,11 @@ export function algoOrder(account, symbol, secType, action, quantity, limitPrice
     };
 }
 /**
- * Iceberg order (basic) — only displaySize required.
- */
-export function icebergOrder(account, symbol, secType, action, quantity, limitPrice, displaySize) {
-    return {
-        account, symbol, secType, action,
-        orderType: OrderType.ICEBERG,
-        totalQuantity: quantity,
-        limitPrice,
-        timeInForce: TimeInForce.DAY,
-        outsideRth: false,
-        displaySize,
-        priceType: 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.
  */
-export function icebergOrderFull(account, symbol, secType, action, quantity, limitPrice, displaySize, minDisplaySize, checkIntervals, priceType, startTime, endTime) {
+export function icebergOrder(account, symbol, secType, action, quantity, limitPrice, displaySize, minDisplaySize, checkIntervals, priceType, startTime, endTime) {
     const req = {
         account, symbol, secType, action,
         orderType: OrderType.ICEBERG,
@@ -116,13 +101,12 @@ export function icebergOrderFull(account, symbol, secType, action, quantity, lim
         timeInForce: TimeInForce.DAY,
         outsideRth: false,
         displaySize,
+        priceType: priceType || 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)
@@ -133,3 +117,118 @@ export function icebergOrderFull(account, symbol, secType, action, quantity, lim
 export function orderLeg(legType, price, timeInForce) {
     return { legType, price, timeInForce };
 }
+/**
+ * Market order by cash amount (instead of quantity).
+ * Server uses `isQuantityByAmount=true` + `amount` field.
+ */
+export function marketOrderByAmount(account, symbol, secType, action, amount) {
+    return {
+        account, symbol, secType, action,
+        orderType: OrderType.MKT,
+        totalQuantity: 0,
+        cashAmount: amount,
+        timeInForce: TimeInForce.DAY,
+        outsideRth: false,
+    };
+}
+/**
+ * Limit order by cash amount (instead of quantity).
+ */
+export function limitOrderByAmount(account, symbol, secType, action, amount, limitPrice) {
+    return {
+        account, symbol, secType, action,
+        orderType: OrderType.LMT,
+        totalQuantity: 0,
+        cashAmount: amount,
+        limitPrice,
+        timeInForce: TimeInForce.DAY,
+        outsideRth: false,
+    };
+}
+/**
+ * Trailing stop order using a fixed price offset (auxPrice) instead of a percentage.
+ * Use `trailOrder()` for percentage-based trailing stops.
+ */
+export function trailOrderByPrice(account, symbol, secType, action, quantity, auxPrice) {
+    return {
+        account, symbol, secType, action,
+        orderType: OrderType.TRAIL,
+        totalQuantity: quantity,
+        auxPrice,
+        timeInForce: 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)
+ */
+export 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: OrderType.LMT,
+        totalQuantity: quantity,
+        limitPrice,
+        orderLegs,
+        timeInForce: 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'`
+ */
+export 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: 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)
+ */
+export function ocaOrder(account, symbol, secType, action, quantity, ocaOrders) {
+    return {
+        account, symbol, secType, action,
+        orderType: OrderType.OCA,
+        totalQuantity: quantity,
+        ocaOrders,
+        timeInForce: 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
+ */
+export function contractLeg(symbol, secType, action, ratio, expiry, strike, right) {
+    return { symbol, secType, action, ratio, expiry, strike, right };
+}

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

@@ -8,6 +8,7 @@
 import { HttpClient } from '../client/http-client.js';
 import { createApiRequest } from '../client/api-request.js';
 import { unmarshalData } from '../client/api-response.js';
+import * as tokenMethods from '../client/token-methods.js';
 /**
  * resolveOptionTimezone returns the timezone string to use for expiry conversion.
  * Explicit tz takes precedence; otherwise infer from symbol (.HK suffix → Asia/Hong_Kong, else America/New_York).
@@ -90,6 +91,25 @@ export class QuoteClient {
     static fromConfig(config) {
         return new QuoteClient(new HttpClient(config, undefined, { useQuoteServerUrl: true }));
     }
+    // ── Token management ──────────────────────────────────────────────────────
+    /** Call the `user_token_refresh` API and return the new token. Read-only. */
+    async queryToken() {
+        return tokenMethods.queryToken(this.httpClient);
+    }
+    /** Refresh the token and update the in-memory config token. */
+    async refreshToken(tokenManager) {
+        return tokenMethods.refreshToken(this.httpClient, tokenManager);
+    }
+    /**
+     * Start background token auto-refresh. Returns a TokenManager to stop with `tm.stopAutoRefresh()`.
+     *
+     * @param refreshDurationSecs - Refresh threshold in seconds (minimum 30).
+     * @param checkIntervalMs - How often to check, in milliseconds (default 300 000 / 5 min).
+     * @param tokenWriter - Optional callback invoked after each successful refresh.
+     */
+    startTokenAutoRefresh(refreshDurationSecs, checkIntervalMs, tokenWriter) {
+        return tokenMethods.startTokenAutoRefresh(this.httpClient, refreshDurationSecs, checkIntervalMs, tokenWriter);
+    }
     async callInto(method, bizParams, version) {
         const request = createApiRequest(method, bizParams, version);
         const response = await this.httpClient.executeRequest(request);

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

@@ -10,6 +10,7 @@
 import { HttpClient } from '../client/http-client.js';
 import { createApiRequest } from '../client/api-request.js';
 import { unmarshalData } from '../client/api-response.js';
+import * as tokenMethods from '../client/token-methods.js';
 import { normalizeOrderStatus } from '../model/order-status.js';
 /** Normalize `Order.status` field in-place (handles int → string). */
 function normalizeOrderInPlace(o) {
@@ -41,6 +42,31 @@ export class TradeClient {
     static fromConfig(config, account, secretKey) {
         return new TradeClient(new HttpClient(config), account, secretKey);
     }
+    // ── Token management ──────────────────────────────────────────────────────
+    /** Call the `user_token_refresh` API and return the new token. Read-only. */
+    async queryToken() {
+        return tokenMethods.queryToken(this.httpClient);
+    }
+    /**
+     * Refresh the token: call the API, update the in-memory config token, and
+     * optionally persist via the provided TokenManager (file + writer callback).
+     *
+     * @param tokenManager - optional TokenManager for file persistence and writer callback
+     */
+    async refreshToken(tokenManager) {
+        return tokenMethods.refreshToken(this.httpClient, tokenManager);
+    }
+    /**
+     * Start background token auto-refresh. Returns a TokenManager that can be
+     * used to stop the background task via `tm.stopAutoRefresh()`.
+     *
+     * @param refreshDurationSecs - Refresh threshold in seconds (minimum 30).
+     * @param checkIntervalMs - How often to check, in milliseconds (default 300 000 / 5 min).
+     * @param tokenWriter - Optional callback invoked after each successful refresh.
+     */
+    startTokenAutoRefresh(refreshDurationSecs, checkIntervalMs, tokenWriter) {
+        return tokenMethods.startTokenAutoRefresh(this.httpClient, refreshDurationSecs, checkIntervalMs, tokenWriter);
+    }
     async callInto(method, bizParams) {
         // Inject secretKey into every request when available (institution accounts require it).
         // Individual methods that already set secretKey will not be overwritten (|| not &&).

package/dist/types/client/token-methods.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared token management methods for TradeClient and QuoteClient.
+ * Both clients delegate to the underlying HttpClient; this module
+ * centralises the JSDoc so each client stays in sync automatically.
+ */
+import type { HttpClient } from './http-client';
+import type { TokenManager } from '../config/token-manager';
+/**
+ * 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.
+ */
+export declare function queryToken(httpClient: HttpClient): Promise<string>;
+/**
+ * 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
+ */
+export declare function refreshToken(httpClient: HttpClient, tokenManager?: TokenManager | null): Promise<void>;
+/**
+ * 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.
+ */
+export declare function startTokenAutoRefresh(httpClient: HttpClient, refreshDurationSecs: number, checkIntervalMs?: number, tokenWriter?: (token: string) => void): TokenManager;

package/dist/types/model/order-helpers.d.ts

@@ -2,7 +2,7 @@
  * Order construction helpers.
  * All helpers return an `OrderRequest` with sensible defaults.
  */
-import type { OrderRequest, OrderLegRequest, AlgoParamsRequest } from './order';
+import type { OrderRequest, OrderLegRequest, AlgoParamsRequest, ContractLegRequest } from './order';
 import { PriceType } from './enums';
 /** Market order */
 export declare function marketOrder(account: string, symbol: string, secType: string, action: string, quantity: number): OrderRequest;
@@ -21,14 +21,54 @@ export declare function auctionMarketOrder(account: string, symbol: string, secT
 /** Algo order (TWAP / VWAP) */
 export declare function algoOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number, algoType: string, params: AlgoParamsRequest): OrderRequest;
 /**
- * Iceberg order (basic) — only displaySize required.
- */
-export declare function icebergOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number, displaySize: number): OrderRequest;
-/**
- * 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.
  */
-export declare function icebergOrderFull(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number, displaySize: number, minDisplaySize?: number, checkIntervals?: number, priceType?: PriceType | string, startTime?: number, endTime?: number): OrderRequest;
+export declare function icebergOrder(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number, displaySize: number, minDisplaySize?: number, checkIntervals?: number, priceType?: PriceType | string, startTime?: number, endTime?: number): OrderRequest;
 /** Attached profit / loss leg */
 export declare function orderLeg(legType: string, price: number, timeInForce: string): OrderLegRequest;
+/**
+ * Market order by cash amount (instead of quantity).
+ * Server uses `isQuantityByAmount=true` + `amount` field.
+ */
+export declare function marketOrderByAmount(account: string, symbol: string, secType: string, action: string, amount: number): OrderRequest;
+/**
+ * Limit order by cash amount (instead of quantity).
+ */
+export declare function limitOrderByAmount(account: string, symbol: string, secType: string, action: string, amount: number, limitPrice: number): OrderRequest;
+/**
+ * Trailing stop order using a fixed price offset (auxPrice) instead of a percentage.
+ * Use `trailOrder()` for percentage-based trailing stops.
+ */
+export declare function trailOrderByPrice(account: string, symbol: string, secType: string, action: string, quantity: number, auxPrice: number): OrderRequest;
+/**
+ * Limit order with attached profit/loss legs (bracket order).
+ * At most 2 legs are supported.
+ *
+ * @param orderLegs - Array of `OrderLegRequest` (use `orderLeg()` helper)
+ */
+export declare function limitOrderWithLegs(account: string, symbol: string, secType: string, action: string, quantity: number, limitPrice: number, orderLegs: OrderLegRequest[]): OrderRequest;
+/**
+ * Multi-leg (combo/MLEG) order for options combos.
+ *
+ * @param contractLegs - Array of `ContractLegRequest` (use `contractLeg()` helper)
+ * @param comboType - e.g. `'MLEG'`
+ */
+export declare function comboOrder(account: string, action: string, quantity: number, orderType: string, contractLegs: ContractLegRequest[], comboType?: string, limitPrice?: number, auxPrice?: number, trailingPercent?: number): OrderRequest;
+/**
+ * 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)
+ */
+export declare function ocaOrder(account: string, symbol: string, secType: string, action: string, quantity: number, ocaOrders: OrderRequest[]): OrderRequest;
+/**
+ * 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
+ */
+export declare function contractLeg(symbol: string, secType: string, action: string, ratio: number, expiry?: string, strike?: string, right?: string): ContractLegRequest;

package/dist/types/model/order.d.ts

@@ -149,7 +149,12 @@ export interface OrderRequest {
     segType?: string;
     /** 按金额下单：委托金额 */
     amount?: number;
-    /** 是否按金额下单 */
+    /** 按金额下单：现金金额（wire: cash_amount，与 amount 二选一） */
+    cashAmount?: number;
+    /**
+     * @deprecated 服务端不再需要此字段，by-amount 订单直接设置 `cashAmount`。
+     * 保留仅为向前兼容，新代码勿使用。
+     */
     isQuantityByAmount?: boolean;
     /** 账户分配列表（机构账户） */
     allocAccounts?: string[];
@@ -173,6 +178,8 @@ export interface OrderRequest {
     ocaOrders?: OrderRequest[];
     /** 多腿期权各腿（MLEG） */
     contractLegs?: ContractLegRequest[];
+    /** 组合单类型（如 MLEG） */
+    comboType?: string;
 }
 /** Single leg of a multi-leg option order (MLEG) */
 export interface ContractLegRequest {

package/dist/types/quote/quote-client.d.ts

@@ -7,6 +7,7 @@
  */
 import { HttpClient } from '../client/http-client';
 import type { ClientConfig } from '../config/client-config';
+import type { TokenManager } from '../config/token-manager';
 import type { MarketState, Brief, Kline, KlineItem, Timeline, TradeTick, Depth, OptionExpiration, OptionChain, OptionChainFilter, FutureExchange, FutureContractInfo, FutureQuote, FutureKline, FutureKlineItem, FinancialDailyItem, FinancialReportItem, CorporateAction, CorporateSymbolChange, CorporateDelisting, CorporateIPO, CapitalFlow, CapitalDistribution, ScannerResult, QuotePermission, MarketScannerRequest, SymbolName, TradeMeta, StockDetail, StockBroker, StockIndustry, TradeRankItem, ShortInterest, KlineQuota, OptionAnalysis, OptionSymbol, FutureMainContractHistory, FutureTradingTime, FutureTradeTickItem, FutureDepth, WarrantBrief, WarrantFilterResult, IndustryItem, IndustryStock, TradingCalendarItem, ExchangeRate, FinancialCurrency, QuoteOvernight, MarketScannerTagGroup, FundContractInfo, FundQuote, FundHistoryQuote, FinancialDailyRequest, FinancialReportRequest, CorporateActionRequest } from '../model/quote';
 import type { BriefRequest, DepthQuoteRequest, TradeTickRequest, FutureBriefRequest, SymbolsRequest, TradeMetasRequest, StockDetailsRequest, StockDelayBriefsRequest, KlineRequest, KlineByPageRequest, TimelineHistoryRequest, TradeRankRequest, ShortInterestRequest, StockBrokerRequest, StockFundamentalRequest, StockIndustryRequest, KlineQuotaRequest, QuotePermissionRequest, OptionTradeTicksRequest, OptionTimelineRequest, OptionDepthRequest, OptionSymbolsRequest, OptionAnalysisRequest, FutureContractSingleRequest, AllFutureContractsRequest, FutureContinuousContractsRequest, FutureHistoryMainContractRequest, FutureKlineRequest, FutureKlineByPageRequest, FutureTradeTicksRequest, FutureDepthRequest, FutureTradingTimesRequest, FundSymbolsRequest, FundContractsRequest, FundQuoteRequest, FundHistoryQuoteRequest, WarrantBriefsRequest, WarrantFilterRequest, IndustryListRequest, IndustryStocksRequest, TradingCalendarRequest, FinancialExchangeRateRequest, FinancialCurrencyRequest, MarketScannerTagsRequest, QuoteOvernightRequest } from '../model/quote-requests';
 /**
@@ -28,6 +29,18 @@ export declare class QuoteClient {
     constructor(httpClient: HttpClient);
     /** Create a QuoteClient directly from a ClientConfig — no need to construct HttpClient manually. */
     static fromConfig(config: ClientConfig): QuoteClient;
+    /** Call the `user_token_refresh` API and return the new token. Read-only. */
+    queryToken(): Promise<string>;
+    /** Refresh the token and update the in-memory config token. */
+    refreshToken(tokenManager?: TokenManager | null): Promise<void>;
+    /**
+     * Start background token auto-refresh. Returns a TokenManager to stop with `tm.stopAutoRefresh()`.
+     *
+     * @param refreshDurationSecs - Refresh threshold in seconds (minimum 30).
+     * @param checkIntervalMs - How often to check, in milliseconds (default 300 000 / 5 min).
+     * @param tokenWriter - Optional callback invoked after each successful refresh.
+     */
+    startTokenAutoRefresh(refreshDurationSecs: number, checkIntervalMs?: number, tokenWriter?: (token: string) => void): TokenManager;
     private callInto;
     /**
      * Some endpoints return either a list or a single object depending on the

package/dist/types/trade/trade-client.d.ts

@@ -9,6 +9,7 @@
  */
 import { HttpClient } from '../client/http-client';
 import type { ClientConfig } from '../config/client-config';
+import type { TokenManager } from '../config/token-manager';
 import type { OrderRequest, Order } from '../model/order';
 import type { Contract } from '../model/contract';
 import type { Position } from '../model/position';
@@ -22,6 +23,24 @@ export declare class TradeClient {
     constructor(httpClient: HttpClient, account: string, secretKey?: string);
     /** Create a TradeClient directly from a ClientConfig — no need to construct HttpClient manually. */
     static fromConfig(config: ClientConfig, account: string, secretKey?: string): TradeClient;
+    /** Call the `user_token_refresh` API and return the new token. Read-only. */
+    queryToken(): Promise<string>;
+    /**
+     * Refresh the token: call the API, update the in-memory config token, and
+     * optionally persist via the provided TokenManager (file + writer callback).
+     *
+     * @param tokenManager - optional TokenManager for file persistence and writer callback
+     */
+    refreshToken(tokenManager?: TokenManager | null): Promise<void>;
+    /**
+     * Start background token auto-refresh. Returns a TokenManager that can be
+     * used to stop the background task via `tm.stopAutoRefresh()`.
+     *
+     * @param refreshDurationSecs - Refresh threshold in seconds (minimum 30).
+     * @param checkIntervalMs - How often to check, in milliseconds (default 300 000 / 5 min).
+     * @param tokenWriter - Optional callback invoked after each successful refresh.
+     */
+    startTokenAutoRefresh(refreshDurationSecs: number, checkIntervalMs?: number, tokenWriter?: (token: string) => void): TokenManager;
     private callInto;
     /** Strip `{items: [...]}` envelope used by most trade read endpoints. */
     private callIntoItems;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tigeropenapi/tigeropen",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Tiger Brokers OpenAPI TypeScript SDK for market data, trading, and real-time push",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",