@adaptic/utils 0.0.1002 → 0.0.1003

package/dist/index.cjs

@@ -5,6 +5,7 @@ var dateFns = require('date-fns');
 var dateFnsTz = require('date-fns-tz');
 var require$$0$1 = require('events');
 var WebSocket = require('ws');
+var node_crypto = require('node:crypto');
 var ms = require('ms');
 var require$$0$2 = require('fs');
 var require$$1 = require('path');
@@ -2405,6 +2406,19 @@ class DataFormatError extends AdapticUtilsError {
  * const result = await makeAlpacaApiCall();
  * ```
  */
+/** Number of milliseconds in one second, used for token-refill timing math. */
+const MS_PER_SECOND$1 = 1000;
+/**
+ * Minimum delay (ms) for a scheduled queue wake-up. Guards against a `0`/`NaN`
+ * delay when the token deficit rounds down, ensuring the timer always makes
+ * forward progress rather than busy-looping on the event loop.
+ */
+const MIN_WAKE_DELAY_MS = 1;
+/**
+ * Number of whole tokens required to release a single queued request. The token
+ * bucket consumes exactly one token per admitted request.
+ */
+const TOKENS_PER_REQUEST = 1;
 /**
  * Token bucket rate limiter implementation
  *
@@ -2420,6 +2434,13 @@ class TokenBucketRateLimiter {
     queue = [];
     timeoutMs;
     processingQueue = false;
+    /**
+     * Single pending timer that wakes the limiter to refill tokens and drain the
+     * queue. Without this, a queued request would only be released by a
+     * subsequent {@link acquire} call and would otherwise stall until its own
+     * timeout fired. `null` means no wake-up is currently scheduled.
+     */
+    wakeTimer = null;
     /**
      * Creates a new rate limiter instance
      *
@@ -2493,8 +2514,48 @@ class TokenBucketRateLimiter {
                 reject(error);
             }, this.timeoutMs);
             this.queue.push({ resolve, reject, timeoutHandle });
+            // Ensure the queue is actively drained even if no further acquire() calls
+            // arrive: schedule a wake-up to refill tokens and release this request.
+            this.scheduleQueueWake();
         });
     }
+    /**
+     * Schedules a single wake-up timer that refills tokens and drains the queue.
+     *
+     * The delay is the time required to accrue the tokens still needed to release
+     * the next queued request at the configured refill rate. Only one timer is
+     * ever outstanding (guarded by {@link wakeTimer}); the timer is `unref`'d so
+     * it never keeps the Node.js process alive on its own. When it fires it
+     * refills, drains what it can, and re-arms itself if work remains.
+     */
+    scheduleQueueWake() {
+        // A wake-up is already pending, or there is nothing to wake for.
+        if (this.wakeTimer !== null || this.queue.length === 0) {
+            return;
+        }
+        const tokensNeeded = Math.max(0, TOKENS_PER_REQUEST - this.tokens);
+        const deficitMs = Math.max(MIN_WAKE_DELAY_MS, Math.ceil((tokensNeeded / this.config.refillRate) * MS_PER_SECOND$1));
+        const timer = setTimeout(() => {
+            this.wakeTimer = null;
+            // refill() drains the queue via processQueue(); if requests remain
+            // afterwards, processQueue() re-arms the wake-up.
+            this.refill();
+        }, deficitMs);
+        // Do not let a pending rate-limiter wake-up keep the process alive.
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+        this.wakeTimer = timer;
+    }
+    /**
+     * Clears any pending wake-up timer.
+     */
+    clearWakeTimer() {
+        if (this.wakeTimer !== null) {
+            clearTimeout(this.wakeTimer);
+            this.wakeTimer = null;
+        }
+    }
     /**
      * Refills tokens based on elapsed time and processes queued requests
      *
@@ -2539,6 +2600,15 @@ class TokenBucketRateLimiter {
         finally {
             this.processingQueue = false;
         }
+        // Keep the wake-up state consistent with the queue: if requests are still
+        // waiting (tokens ran out mid-drain), ensure a wake-up is armed; otherwise
+        // release any pending timer so it cannot fire needlessly.
+        if (this.queue.length > 0) {
+            this.scheduleQueueWake();
+        }
+        else {
+            this.clearWakeTimer();
+        }
     }
     /**
      * Gets the current number of available tokens
@@ -2570,6 +2640,7 @@ class TokenBucketRateLimiter {
             clearTimeout(request.timeoutHandle);
             request.reject(new RateLimitError(`Rate limiter reset for ${this.config.label}`, this.config.label, undefined));
         }
+        this.clearWakeTimer();
         this.queue = [];
         this.tokens = this.config.maxTokens;
         this.lastRefill = Date.now();
@@ -4319,6 +4390,46 @@ const limitPriceSlippagePercent100 = 0.1; // 0.1%
 const ORDER_PAGE_LIMIT = 500;
 /** Delay between order pagination pages to stay clear of rate limits. */
 const ORDER_PAGINATION_DELAY_MS = 300;
+/**
+ * HTTP status at or above which a Multi-Status (207) sub-result is a failure.
+ * Alpaca's bulk `DELETE /orders` and `DELETE /positions` endpoints return a 207
+ * envelope whose top-level status is 2xx even when individual orders/positions
+ * failed to cancel or close; each element carries its own per-item HTTP status.
+ * Treating >= 300 as a failure lets the engine failsafe see partial failures
+ * instead of recording a false success.
+ */
+const HTTP_STATUS_MIN_ERROR = 300;
+/**
+ * Prefix applied to engine-derived `client_order_id` idempotency keys so they
+ * are visibly attributable in Alpaca's dashboard and can never collide with a
+ * caller-supplied identifier.
+ */
+const CLIENT_ORDER_ID_PREFIX = "adaptic-";
+/**
+ * Number of leading hex characters of the SHA-256 digest retained in a derived
+ * `client_order_id`. 32 hex chars = 128 bits of entropy (collision-negligible),
+ * and keeps the full id (prefix + digest = 40 chars) within Alpaca's identifier
+ * length limit.
+ */
+const CLIENT_ORDER_ID_HASH_LENGTH = 32;
+/**
+ * Idempotency window (ms) used when deriving a default `client_order_id`.
+ *
+ * A client request timeout followed by an automatic retry re-submits the SAME
+ * logical order. Deriving the id from the order's semantic parameters plus the
+ * current time-window bucket makes Alpaca reject the retried duplicate
+ * (`client_order_id must be unique`) instead of double-filling. The window is
+ * deliberately much larger than the 30s Alpaca request timeout so a full
+ * timeout+retry sequence lands in the same bucket, while a genuinely new but
+ * otherwise-identical order placed in a later window still receives a distinct
+ * id.
+ *
+ * This derived default is a best-effort safety net; the guaranteed-idempotent
+ * path is for the caller to pass an explicit `clientOrderId` tied to the
+ * originating signal/decision id (which also permits legitimately-repeated
+ * identical orders inside a single window).
+ */
+const CLIENT_ORDER_ID_WINDOW_MS = 300_000;
 /**
 Websocket example
   const alpacaAPI = createAlpacaTradingAPI(credentials); // type AlpacaCredentials
@@ -4399,6 +4510,114 @@ class AlpacaTradingAPI {
             ? Math.round(price * 100) / 100
             : Math.round(price * 10000) / 10000;
     };
+    /**
+     * Derive a deterministic `client_order_id` from an order's semantic
+     * parameters so that a client-timeout-triggered retry re-submits the SAME id
+     * and Alpaca rejects the duplicate broker-side instead of double-filling.
+     *
+     * The id is stable for identical parameters within a single
+     * {@link CLIENT_ORDER_ID_WINDOW_MS} bucket and scoped per account. Callers
+     * that must place genuinely distinct yet otherwise-identical orders should
+     * pass an explicit `clientOrderId` rather than relying on this default.
+     *
+     * @param parts - Ordered, stringifiable components uniquely describing the
+     *   order (e.g. order kind, symbol, side, quantity, price, intent).
+     * @returns An Alpaca-safe `client_order_id` (prefix + truncated SHA-256 hex).
+     */
+    deriveClientOrderId(parts) {
+        const windowBucket = Math.floor(Date.now() / CLIENT_ORDER_ID_WINDOW_MS);
+        const material = [
+            this.credentials.accountName,
+            windowBucket,
+            ...parts.map((part) => (part === undefined ? "" : String(part))),
+        ].join("|");
+        const digest = node_crypto.createHash("sha256")
+            .update(material)
+            .digest("hex")
+            .slice(0, CLIENT_ORDER_ID_HASH_LENGTH);
+        return `${CLIENT_ORDER_ID_PREFIX}${digest}`;
+    }
+    /**
+     * Collect the human-readable failure entries from a bulk Multi-Status (207)
+     * response body (`DELETE /orders`, `DELETE /positions`). Each element carries
+     * its own per-item HTTP status; any element with status >=
+     * {@link HTTP_STATUS_MIN_ERROR} is a failure the caller must be able to see.
+     *
+     * @param entries - Parsed 207 response array.
+     * @returns One `"<identifier>:<status>"` string per failed entry.
+     */
+    collectMultiStatusFailures(entries) {
+        return entries
+            .filter((entry) => typeof entry.status === "number" &&
+            entry.status >= HTTP_STATUS_MIN_ERROR)
+            .map((entry) => `${entry.symbol ?? entry.id ?? "unknown"}:${entry.status}`);
+    }
+    /**
+     * Flatten a single position with a marketable limit order, deriving the
+     * closing side, intent, and slippage-adjusted limit price from the latest
+     * quote. Throws when no usable quote/price is available for the symbol so the
+     * caller can record a per-position failure via {@link Promise.allSettled}
+     * without aborting the flatten of the remaining positions.
+     *
+     * @param position - The position to close.
+     * @param quotesResponse - Latest quotes keyed by symbol.
+     * @param extendedHours - Whether the closing order is an extended-hours order.
+     */
+    async closePositionWithLimitOrder(position, quotesResponse, extendedHours) {
+        const quote = quotesResponse.quotes[position.symbol];
+        if (!quote) {
+            throw new Error(`No quote available for ${position.symbol}`);
+        }
+        const qty = Math.abs(parseFloat(position.qty));
+        const side = position.side === "long" ? "sell" : "buy";
+        const positionIntent = side === "sell" ? "sell_to_close" : "buy_to_close";
+        // Use bid for sells, ask for buys.
+        const currentPrice = side === "sell" ? quote.bp : quote.ap;
+        if (!currentPrice) {
+            throw new Error(`No valid price available for ${position.symbol}`);
+        }
+        const limitSlippagePercent1 = limitPriceSlippagePercent100 / 100;
+        const limitPrice = side === "sell"
+            ? this.roundPriceForAlpaca(currentPrice * (1 - limitSlippagePercent1)) // Sell slightly lower
+            : this.roundPriceForAlpaca(currentPrice * (1 + limitSlippagePercent1)); // Buy slightly higher
+        this.log(`Creating ${extendedHours ? "extended hours " : ""}limit order to close ${position.symbol} position: ${side} ${qty} shares at $${limitPrice.toFixed(2)}`, {
+            symbol: position.symbol,
+        });
+        await this.createLimitOrder(position.symbol, qty, side, limitPrice, positionIntent, extendedHours);
+    }
+    /**
+     * Flatten every supplied position independently and surface an aggregate
+     * failure if any could not be closed. Positions are attempted concurrently
+     * with {@link Promise.allSettled} so a data gap or broker rejection on one
+     * symbol never silently prevents the others from being flattened.
+     *
+     * @param positions - Positions to flatten.
+     * @param extendedHours - Whether the closing orders are extended-hours orders.
+     * @throws Error listing every symbol that failed to flatten.
+     */
+    async flattenPositionsWithLimitOrders(positions, extendedHours) {
+        const symbols = positions.map((position) => position.symbol);
+        const quotesResponse = await marketDataAPI.getLatestQuotes(symbols);
+        const results = await Promise.allSettled(positions.map((position) => this.closePositionWithLimitOrder(position, quotesResponse, extendedHours)));
+        const failures = [];
+        results.forEach((result, index) => {
+            if (result.status === "rejected") {
+                const symbol = positions[index]?.symbol ?? "unknown";
+                const reason = result.reason instanceof Error
+                    ? result.reason.message
+                    : String(result.reason);
+                failures.push(`${symbol}: ${reason}`);
+                this.log(`Failed to close position ${symbol}: ${reason}`, {
+                    symbol,
+                    type: "error",
+                });
+            }
+        });
+        if (failures.length > 0) {
+            throw new Error(`Failed to close ${failures.length} of ${positions.length} positions: ${failures.join("; ")}`);
+        }
+        this.log(`All positions closed: ${symbols.join(", ")}`);
+    }
     handleAuthMessage(data) {
         if (data.status === "authorized") {
             this.authenticated = true;
@@ -4770,21 +4989,31 @@ class AlpacaTradingAPI {
      * @param position_intent (string) - the position intent of the order
      * @returns The created AlpacaOrder with order ID and details
      */
-    async createTrailingStop(symbol, qty, side, trailPercent100, position_intent) {
+    async createTrailingStop(symbol, qty, side, trailPercent100, position_intent, clientOrderId) {
         this.log(`Creating trailing stop ${side.toUpperCase()} ${qty} shares for ${symbol} with trail percent ${trailPercent100}%`, {
             symbol,
         });
+        const body = {
+            symbol,
+            qty: Math.abs(qty).toString(),
+            side,
+            position_intent,
+            order_class: "simple",
+            type: "trailing_stop",
+            trail_percent: trailPercent100.toString(), // Already in decimal form (e.g., 4 for 4%)
+            time_in_force: "gtc",
+            client_order_id: clientOrderId ??
+                this.deriveClientOrderId([
+                    "trailing_stop",
+                    symbol,
+                    side,
+                    position_intent,
+                    Math.abs(qty),
+                    trailPercent100,
+                ]),
+        };
         try {
-            const order = await this.makeRequest(`/orders`, "POST", {
-                symbol,
-                qty: Math.abs(qty),
-                side,
-                position_intent,
-                order_class: "simple",
-                type: "trailing_stop",
-                trail_percent: trailPercent100, // Already in decimal form (e.g., 4 for 4%)
-                time_in_force: "gtc",
-            });
+            const order = await this.makeRequest(`/orders`, "POST", body);
             this.log(`Trailing stop order created for ${symbol}: orderId=${order.id}, trailPercent=${trailPercent100}%`, { symbol });
             return order;
         }
@@ -4816,9 +5045,15 @@ class AlpacaTradingAPI {
             time_in_force: "day",
             order_class: "simple",
         };
-        if (client_order_id !== undefined) {
-            body.client_order_id = client_order_id;
-        }
+        body.client_order_id =
+            client_order_id ??
+                this.deriveClientOrderId([
+                    "market",
+                    symbol,
+                    side,
+                    position_intent,
+                    Math.abs(qty),
+                ]);
         try {
             return await this.makeRequest("/orders", "POST", body);
         }
@@ -4919,16 +5154,31 @@ class AlpacaTradingAPI {
         }
     }
     /**
-     * Cancel all open orders
+     * Cancel all open orders.
+     *
+     * Alpaca's bulk cancel returns a 207 Multi-Status body whose top-level status
+     * is 2xx even when individual orders failed to cancel; this method inspects
+     * the per-order statuses and throws if any order could not be canceled, so a
+     * caller acting as a live-stop failsafe cannot record success while orders
+     * remain live. Transport/HTTP errors propagate unchanged (matching the
+     * throw-on-failure contract of {@link cancelOrder}).
+     *
+     * @throws Error if the bulk cancel request fails or any individual order
+     *   could not be canceled.
      */
     async cancelAllOrders() {
         this.log(`Canceling all open orders`);
-        try {
-            await this.makeRequest("/orders", "DELETE");
+        const results = await this.makeRequest("/orders", "DELETE");
+        if (!Array.isArray(results)) {
+            return;
         }
-        catch (error) {
-            this.log(`Error canceling all orders: ${error}`, { type: "error" });
+        const failures = this.collectMultiStatusFailures(results);
+        if (failures.length > 0) {
+            const detail = failures.join(", ");
+            this.log(`Error canceling all orders: ${failures.length}/${results.length} orders failed to cancel (${detail})`, { type: "error" });
+            throw new Error(`Failed to cancel ${failures.length} of ${results.length} orders: ${detail}`);
         }
+        this.log(`Successfully canceled ${results.length} open orders`);
     }
     /**
      * Cancel a specific order by its ID
@@ -4979,9 +5229,17 @@ class AlpacaTradingAPI {
             order_class: "simple",
             extended_hours,
         };
-        if (client_order_id !== undefined) {
-            body.client_order_id = client_order_id;
-        }
+        body.client_order_id =
+            client_order_id ??
+                this.deriveClientOrderId([
+                    "limit",
+                    symbol,
+                    side,
+                    position_intent,
+                    Math.abs(qty),
+                    this.roundPriceForAlpaca(limitPrice),
+                    extended_hours,
+                ]);
         try {
             return await this.makeRequest("/orders", "POST", body);
         }
@@ -5009,55 +5267,21 @@ class AlpacaTradingAPI {
                 return;
             }
             this.log(`Found ${positions.length} positions to close`);
-            // Get latest quotes for all positions
-            const symbols = positions.map((position) => position.symbol);
-            const quotesResponse = await marketDataAPI.getLatestQuotes(symbols);
-            const lengthOfQuotes = Object.keys(quotesResponse.quotes).length;
-            if (lengthOfQuotes === 0) {
-                this.log("No quotes available for positions, received 0 quotes", {
-                    type: "error",
-                });
-                return;
-            }
-            if (lengthOfQuotes !== positions.length) {
-                this.log(`Received ${lengthOfQuotes} quotes for ${positions.length} positions, expected ${positions.length} quotes`, { type: "warn" });
-                return;
-            }
-            // Create limit orders to close each position
-            for (const position of positions) {
-                const quote = quotesResponse.quotes[position.symbol];
-                if (!quote) {
-                    this.log(`No quote available for ${position.symbol}, skipping limit order`, {
-                        symbol: position.symbol,
-                        type: "warn",
-                    });
-                    continue;
-                }
-                const qty = Math.abs(parseFloat(position.qty));
-                const side = position.side === "long" ? "sell" : "buy";
-                const positionIntent = side === "sell" ? "sell_to_close" : "buy_to_close";
-                // Get the current price from the quote
-                const currentPrice = side === "sell" ? quote.bp : quote.ap; // Use bid for sells, ask for buys
-                if (!currentPrice) {
-                    this.log(`No valid price available for ${position.symbol}, skipping limit order`, {
-                        symbol: position.symbol,
-                        type: "warn",
-                    });
-                    continue;
-                }
-                // Apply slippage from config
-                const limitSlippagePercent1 = limitPriceSlippagePercent100 / 100;
-                const limitPrice = side === "sell"
-                    ? this.roundPriceForAlpaca(currentPrice * (1 - limitSlippagePercent1)) // Sell slightly lower
-                    : this.roundPriceForAlpaca(currentPrice * (1 + limitSlippagePercent1)); // Buy slightly higher
-                this.log(`Creating limit order to close ${position.symbol} position: ${side} ${qty} shares at $${limitPrice.toFixed(2)}`, {
-                    symbol: position.symbol,
-                });
-                await this.createLimitOrder(position.symbol, qty, side, limitPrice, positionIntent);
-            }
+            // Flatten each position independently. A missing quote or broker
+            // rejection on one symbol must never abort the flatten of the others; any
+            // per-position failure is surfaced as an aggregate error.
+            await this.flattenPositionsWithLimitOrders(positions, false);
         }
         else {
-            await this.makeRequest("/positions", "DELETE", undefined, options.cancel_orders ? "?cancel_orders=true" : "");
+            const results = await this.makeRequest("/positions", "DELETE", undefined, options.cancel_orders ? "?cancel_orders=true" : "");
+            if (Array.isArray(results)) {
+                const failures = this.collectMultiStatusFailures(results);
+                if (failures.length > 0) {
+                    const detail = failures.join(", ");
+                    this.log(`Error closing all positions: ${failures.length}/${results.length} positions failed to close (${detail})`, { type: "error" });
+                    throw new Error(`Failed to close ${failures.length} of ${results.length} positions: ${detail}`);
+                }
+            }
         }
     }
     /**
@@ -5074,44 +5298,22 @@ class AlpacaTradingAPI {
             this.log("No positions to close");
             return;
         }
-        await this.cancelAllOrders();
-        this.log(`Cancelled all open orders`);
-        // Get latest quotes for all positions
-        const symbols = positions.map((position) => position.symbol);
-        const quotesResponse = await marketDataAPI.getLatestQuotes(symbols);
-        // Create limit orders to close each position
-        for (const position of positions) {
-            const quote = quotesResponse.quotes[position.symbol];
-            if (!quote) {
-                this.log(`No quote available for ${position.symbol}, skipping limit order`, {
-                    symbol: position.symbol,
-                    type: "warn",
-                });
-                continue;
-            }
-            const qty = Math.abs(parseFloat(position.qty));
-            const side = position.side === "long" ? "sell" : "buy";
-            const positionIntent = side === "sell" ? "sell_to_close" : "buy_to_close";
-            // Get the current price from the quote
-            const currentPrice = side === "sell" ? quote.bp : quote.ap; // Use bid for sells, ask for buys
-            if (!currentPrice) {
-                this.log(`No valid price available for ${position.symbol}, skipping limit order`, {
-                    symbol: position.symbol,
-                    type: "warn",
-                });
-                continue;
-            }
-            // Apply slippage from config
-            const limitSlippagePercent1 = limitPriceSlippagePercent100 / 100;
-            const limitPrice = side === "sell"
-                ? this.roundPriceForAlpaca(currentPrice * (1 - limitSlippagePercent1)) // Sell slightly lower
-                : this.roundPriceForAlpaca(currentPrice * (1 + limitSlippagePercent1)); // Buy slightly higher
-            this.log(`Creating extended hours limit order to close ${position.symbol} position: ${side} ${qty} shares at $${limitPrice.toFixed(2)}`, {
-                symbol: position.symbol,
-            });
-            await this.createLimitOrder(position.symbol, qty, side, limitPrice, positionIntent, true);
+        // Cancelling stale open orders is secondary to the primary failsafe goal of
+        // flattening positions. A cancel failure is logged but must not abort the
+        // flatten, otherwise a single un-cancelable order would leave every position
+        // open. The flatten step below surfaces its own aggregate failure.
+        try {
+            await this.cancelAllOrders();
+            this.log(`Cancelled all open orders`);
+        }
+        catch (error) {
+            this.log(`Proceeding to flatten despite cancelAllOrders failure: ${error instanceof Error ? error.message : String(error)}`, { type: "error" });
         }
-        this.log(`All positions closed: ${positions.map((p) => p.symbol).join(", ")}`);
+        // Flatten each position independently with extended-hours limit orders. A
+        // missing quote or broker rejection on one symbol must never silently leave
+        // the remaining positions open; per-position failures are surfaced as an
+        // aggregate error.
+        await this.flattenPositionsWithLimitOrders(positions, true);
     }
     onTradeUpdate(callback) {
         this.tradeUpdateCallback = callback;
@@ -5190,9 +5392,12 @@ class AlpacaTradingAPI {
      * @param position_intent Position intent (buy_to_open, buy_to_close, sell_to_open, sell_to_close)
      * @param type Order type (market or limit)
      * @param limitPrice Limit price (required for limit orders)
+     * @param clientOrderId Optional idempotency key; a deterministic one is
+     *   derived from the order parameters when omitted so a client-timeout retry
+     *   is de-duplicated broker-side.
      * @returns The created order
      */
-    async createOptionOrder(symbol, qty, side, position_intent, type, limitPrice) {
+    async createOptionOrder(symbol, qty, side, position_intent, type, limitPrice, clientOrderId) {
         if (!Number.isInteger(qty) || qty <= 0) {
             this.log("Quantity must be a positive whole number for option orders", {
                 type: "error",
@@ -5217,6 +5422,19 @@ class AlpacaTradingAPI {
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
         }
+        orderData.client_order_id =
+            clientOrderId ??
+                this.deriveClientOrderId([
+                    "option",
+                    type,
+                    symbol,
+                    side,
+                    position_intent,
+                    qty,
+                    type === "limit" && limitPrice !== undefined
+                        ? this.roundPriceForAlpaca(limitPrice)
+                        : undefined,
+                ]);
         return this.makeRequest("/orders", "POST", orderData);
     }
     /**
@@ -5225,9 +5443,12 @@ class AlpacaTradingAPI {
      * @param qty Quantity of the multi-leg order (must be a whole number)
      * @param type Order type (market or limit)
      * @param limitPrice Limit price (required for limit orders)
+     * @param clientOrderId Optional idempotency key; a deterministic one is
+     *   derived from the legs and order parameters when omitted so a
+     *   client-timeout retry is de-duplicated broker-side.
      * @returns The created multi-leg order
      */
-    async createMultiLegOptionOrder(legs, qty, type, limitPrice) {
+    async createMultiLegOptionOrder(legs, qty, type, limitPrice, clientOrderId) {
         if (!Number.isInteger(qty) || qty <= 0) {
             this.log("Quantity must be a positive whole number for option orders", {
                 type: "error",
@@ -5253,6 +5474,17 @@ class AlpacaTradingAPI {
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
         }
+        orderData.client_order_id =
+            clientOrderId ??
+                this.deriveClientOrderId([
+                    "mleg",
+                    type,
+                    qty,
+                    type === "limit" && limitPrice !== undefined
+                        ? this.roundPriceForAlpaca(limitPrice)
+                        : undefined,
+                    ...legs.map((leg) => `${leg.symbol}:${leg.side}:${leg.ratio_qty}:${leg.position_intent}`),
+                ]);
         return this.makeRequest("/orders", "POST", orderData);
     }
     /**
@@ -5730,9 +5962,26 @@ class AlpacaTradingAPI {
             extended_hours: extendedHours,
             position_intent: side === "buy" ? "buy_to_open" : "sell_to_open",
         };
-        if (clientOrderId) {
-            orderData.client_order_id = clientOrderId;
-        }
+        orderData.client_order_id =
+            clientOrderId ??
+                this.deriveClientOrderId([
+                    "equities",
+                    orderClass,
+                    type,
+                    symbol,
+                    side,
+                    Math.abs(qty),
+                    type === "limit" && limitPrice !== undefined
+                        ? this.roundPriceForAlpaca(limitPrice)
+                        : undefined,
+                    extendedHours,
+                    useStopLoss && calculatedStopPrice !== undefined
+                        ? this.roundPriceForAlpaca(calculatedStopPrice)
+                        : undefined,
+                    useTakeProfit && calculatedTakeProfitPrice !== undefined
+                        ? this.roundPriceForAlpaca(calculatedTakeProfitPrice)
+                        : undefined,
+                ]);
         // Add limit price for limit orders
         if (type === "limit" && limitPrice !== undefined) {
             orderData.limit_price = this.roundPriceForAlpaca(limitPrice).toString();
@@ -8408,6 +8657,13 @@ var atrNs = /*#__PURE__*/Object.freeze({
 });
 
 const ALPACA_API_BASE = MARKET_DATA_API.CRYPTO;
+/**
+ * Hard upper bound on the number of paginated news pages fetched in a single
+ * {@link fetchNews} call. Acts as a runaway-loop backstop that is independent of
+ * the caller-supplied `limit`, mirroring the max-page guard the equities
+ * paginator already enforces.
+ */
+const MAX_NEWS_PAGES = 100;
 /**
  * Fetches cryptocurrency bars for the specified parameters.
  * This function retrieves historical price data for multiple cryptocurrencies.
@@ -8507,17 +8763,25 @@ async function fetchNews(params, auth) {
         include_content: includeContent.toString(),
         limit: limit.toString(),
     });
-    const url = `${ALPACA_API_BASE}/news?${queryParams}`;
-    logIfDebug(`Fetching news from: ${url}`);
-    let newsArticles = [];
+    const authHeaders = {
+        "APCA-API-KEY-ID": auth.APIKey,
+        "APCA-API-SECRET-KEY": auth.APISecret,
+    };
+    const newsArticles = [];
     let pageToken = null;
-    let hasMorePages = true;
-    while (hasMorePages) {
+    let pageCount = 0;
+    while (pageCount < MAX_NEWS_PAGES) {
+        // Rebuild the request URL on every iteration so the pagination cursor is
+        // actually applied. Using `set` (not `append`) overwrites the previous
+        // cursor instead of accumulating stale `page_token` values across pages.
         if (pageToken) {
-            queryParams.append("page_token", pageToken);
+            queryParams.set("page_token", pageToken);
         }
+        const url = `${ALPACA_API_BASE}/news?${queryParams.toString()}`;
+        logIfDebug(`Fetching news from: ${url}`);
         await withRetry(async () => {
             const response = await fetch(url, {
+                headers: authHeaders,
                 signal: createTimeoutSignal(DEFAULT_TIMEOUTS.ALPACA_API),
             });
             if (!response.ok) {
@@ -8525,7 +8789,7 @@ async function fetchNews(params, auth) {
                 throw new Error(`Alpaca API error (${response.status}): ${errorText}`);
             }
             const data = await response.json();
-            newsArticles = newsArticles.concat(data.news.map((article) => ({
+            const pageArticles = (data.news ?? []).map((article) => ({
                 id: article.id,
                 author: article.author,
                 content: article.content,
@@ -8537,11 +8801,17 @@ async function fetchNews(params, auth) {
                 url: article.url,
                 symbols: article.symbols,
                 images: article.images,
-            })));
+            }));
+            newsArticles.push(...pageArticles);
             pageToken = data.next_page_token ?? null;
-            hasMorePages = !!pageToken;
-            logIfDebug(`Received ${data.news.length} news articles. More pages: ${hasMorePages}`);
+            logIfDebug(`Received ${pageArticles.length} news articles. Next page token: ${pageToken ? "present" : "none"}`);
         }, API_RETRY_CONFIGS.CRYPTO, `Crypto.fetchNews(${symbol})`);
+        pageCount++;
+        // Terminate once the API reports no further pages or once we have
+        // accumulated at least the requested number of articles.
+        if (!pageToken || newsArticles.length >= limit) {
+            break;
+        }
     }
     // If sort is "asc" and limit is 10, return only the 10 most recent articles
     if (sort === "asc" && limit === 10) {
@@ -9758,33 +10028,138 @@ const formatIndicesBarData = (data) => {
 };
 
 // price-utils.ts
+// ---------------------------------------------------------------------------
+// Transaction-cost (fee) model
+//
+// Alpaca's REST order object does not expose the realized per-order fee, so the
+// transaction cost is reconstructed from the published fee schedules, branching
+// on the order's ACTUAL asset class (never a hardcoded STOCK). Every rate is a
+// named constant sourced from Alpaca / SEC / FINRA public schedules (2024-2025)
+// so it can be audited and updated in one place.
+// ---------------------------------------------------------------------------
+/** Basis points in one whole unit (1 = 10,000 bps). */
+const BPS_PER_UNIT = 10_000;
+/** Shares represented by one US listed option contract. */
+const OPTIONS_CONTRACT_MULTIPLIER = 100;
+/**
+ * SEC Section 31 fee, charged on the principal of SELL orders for equities and
+ * options. FY2024+ rate: USD 8.00 per USD 1,000,000 of principal.
+ */
+const SEC_SECTION31_FEE_PER_USD = 8.0 / 1_000_000;
+/** FINRA Trading Activity Fee (TAF) for equity sells: USD per share sold. */
+const FINRA_TAF_EQUITY_PER_SHARE = 0.000166;
+/** FINRA TAF for option sells: USD per contract sold. */
+const FINRA_TAF_OPTIONS_PER_CONTRACT = 0.00279;
+/** FINRA TAF is capped per trade regardless of size. */
+const FINRA_TAF_MAX_PER_TRADE = 8.3;
+/** OCC clearing fee per option contract, capped per trade. */
+const OCC_CLEARING_FEE_PER_CONTRACT = 0.02;
+const OCC_CLEARING_FEE_MAX_PER_TRADE = 55.0;
+/**
+ * Options Regulatory Fee (ORF) pass-through, charged on both sides, USD per
+ * contract. Published, exchange-set pass-through rate.
+ */
+const OPTIONS_REGULATORY_FEE_PER_CONTRACT = 0.02685;
+/**
+ * Alpaca crypto TAKER fee schedule as `[minTrailing30dVolumeUsd, takerBps]`,
+ * ordered ascending by volume threshold. Market orders are takers; absent a
+ * known trailing-30-day volume we conservatively select the tier-1 (highest)
+ * taker rate. Source: Alpaca Crypto fee schedule.
+ */
+const ALPACA_CRYPTO_TAKER_FEE_TIERS_BPS = [
+    [0, 25],
+    [100_000, 22],
+    [500_000, 20],
+    [1_000_000, 18],
+    [10_000_000, 15],
+    [25_000_000, 13],
+    [50_000_000, 12],
+    [100_000_000, 10],
+];
+/**
+ * Resolve the applicable Alpaca crypto taker fee (in bps) for a trailing
+ * 30-day USD volume. Defaults to the tier-1 rate when the volume is unknown.
+ * @param trailing30dVolumeUsd - Trailing 30-day traded notional in USD.
+ * @returns The taker fee in basis points.
+ */
+function resolveCryptoTakerBps(trailing30dVolumeUsd) {
+    let bps = ALPACA_CRYPTO_TAKER_FEE_TIERS_BPS[0][1];
+    for (const [threshold, tierBps] of ALPACA_CRYPTO_TAKER_FEE_TIERS_BPS) {
+        if (trailing30dVolumeUsd >= threshold) {
+            bps = tierBps;
+        }
+        else {
+            break;
+        }
+    }
+    return bps;
+}
+/**
+ * Computes the realized transaction cost (fees + regulatory charges) for the
+ * Alpaca order backing a single {@link types.Action}, branching on the order's
+ * actual asset class. Returns 0 only when there is genuinely no order to price
+ * (no linked order id, order not found, or nothing filled) — never as a
+ * fabricated success.
+ * @param action - The action whose linked Alpaca order should be priced.
+ * @param trade - The parent trade (supplies the Alpaca account id).
+ * @param alpacaAccount - The Alpaca account supplying broker credentials.
+ * @returns The total fee in account currency (USD).
+ */
 const calculateFees = async (action, trade, alpacaAccount) => {
-    let fee = 0;
     const alpacaOrderId = action.alpacaOrderId;
     if (!alpacaOrderId)
-        return fee;
+        return 0;
     const order = await getOrder$1({
         adapticAccountId: trade.alpacaAccountId,
         alpacaApiKey: alpacaAccount.APIKey,
         alpacaApiSecret: alpacaAccount.APISecret,
     }, alpacaOrderId);
     if (!order)
-        return fee;
-    const assetType = "STOCK";
-    Number(order.qty) || 0;
-    order.notional || 0;
-    Number(order.filled_avg_price || order.limit_price || order.stop_price) ||
+        return 0;
+    const filledQty = Number(order.filled_qty) || 0;
+    const filledPrice = Number(order.filled_avg_price ?? order.limit_price ?? order.stop_price) ||
         0;
-    switch (assetType) {
-        case "STOCK":
-            // Currently zero fees for stocks via Alpaca
-            fee = 0;
-            break;
-        default:
-            fee = 0;
-            break;
+    // Realized notional prefers the actual fill (qty * avg price); it falls back
+    // to the order's notional field for dollar-notional (fractional) orders.
+    const notional = filledQty > 0 && filledPrice > 0
+        ? filledQty * filledPrice
+        : Number(order.notional ?? 0) || 0;
+    if (notional <= 0)
+        return 0;
+    const isSell = order.side === "sell";
+    switch (order.asset_class) {
+        case "crypto": {
+            // Crypto fees are bps of notional. Without a known 30-day volume we use
+            // the conservative tier-1 taker rate.
+            const takerBps = resolveCryptoTakerBps(0);
+            return (notional * takerBps) / BPS_PER_UNIT;
+        }
+        case "us_option": {
+            const contracts = filledQty > 0 ? filledQty : Number(order.qty) || 0;
+            const occFee = Math.min(contracts * OCC_CLEARING_FEE_PER_CONTRACT, OCC_CLEARING_FEE_MAX_PER_TRADE);
+            const orfFee = contracts * OPTIONS_REGULATORY_FEE_PER_CONTRACT;
+            let fee = occFee + orfFee;
+            if (isSell) {
+                // Option premium is quoted per share; SEC fee applies to the full
+                // principal (premium * contract multiplier).
+                const optionPrincipal = notional * OPTIONS_CONTRACT_MULTIPLIER;
+                const secFee = optionPrincipal * SEC_SECTION31_FEE_PER_USD;
+                const taf = Math.min(contracts * FINRA_TAF_OPTIONS_PER_CONTRACT, FINRA_TAF_MAX_PER_TRADE);
+                fee += secFee + taf;
+            }
+            return fee;
+        }
+        case "us_equity":
+        default: {
+            // Alpaca charges USD 0 commission on US equities; only sell-side
+            // regulatory charges (SEC Section 31 + FINRA TAF) apply.
+            if (!isSell)
+                return 0;
+            const secFee = notional * SEC_SECTION31_FEE_PER_USD;
+            const taf = Math.min(filledQty * FINRA_TAF_EQUITY_PER_SHARE, FINRA_TAF_MAX_PER_TRADE);
+            return secFee + taf;
+        }
     }
-    return fee;
 };
 const computeTotalFees = async (trade) => {
     let totalFees = 0;
@@ -10653,16 +11028,76 @@ async function calculateExpenseRatio({ accountId, client, alpacaAccount, }) {
         return "N/A";
     }
     const equity = parseFloat(accountDetails.equity);
-    // Fetch portfolio expenses from your system (Assuming you have this data)
-    const expenses = await getPortfolioExpensesFromYourSystem();
-    // Calculate expense ratio
+    // Fetch the account's real trailing fee expenses from Alpaca account
+    // activities. A genuine data-source failure yields "N/A" (unknown) rather
+    // than a fabricated 0.00%.
+    const auth = {
+        adapticAccountId: alpacaAccountId,
+        alpacaApiKey: alpacaAccount?.APIKey,
+        alpacaApiSecret: alpacaAccount?.APISecret,
+    };
+    let expenses;
+    try {
+        expenses = await fetchTrailingFeeExpenses(auth);
+    }
+    catch (error) {
+        getLogger().warn("Failed to fetch Alpaca account fee activities for expense ratio.", { error });
+        return "N/A";
+    }
+    // Calculate expense ratio (trailing fees as a percentage of current equity).
     const expenseRatio = (expenses / equity) * 100;
     return `${expenseRatio.toFixed(2)}%`;
 }
-// Mock function to represent fetching expenses from your system
-async function getPortfolioExpensesFromYourSystem(_accountId) {
-    // Implement this function based on your data storage
-    return 0; // Placeholder
+/** Trailing window over which account fees are aggregated for the expense ratio. */
+const EXPENSE_TRAILING_WINDOW_DAYS = 365;
+/** Milliseconds in one day. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Alpaca account-activity types that represent fees/regulatory charges. */
+const FEE_ACTIVITY_TYPES = "FEE,REG,CFEE";
+/** Page size for the paginated Alpaca account-activities endpoint. */
+const ACTIVITIES_PAGE_SIZE = 100;
+/** Hard cap on activity pages to bound pagination on unexpected responses. */
+const ACTIVITIES_MAX_PAGES = 1000;
+/**
+ * Aggregates the account's fee/regulatory charges over the trailing window from
+ * the Alpaca account-activities endpoint, following id-based pagination.
+ * @param auth - Alpaca authentication (account id and/or direct API keys).
+ * @returns Total fees in account currency (USD) as a positive number.
+ */
+async function fetchTrailingFeeExpenses(auth) {
+    const after = new Date(Date.now() - EXPENSE_TRAILING_WINDOW_DAYS * MS_PER_DAY).toISOString();
+    let total = 0;
+    let pageToken;
+    for (let page = 0; page < ACTIVITIES_MAX_PAGES; page++) {
+        const queryParams = new URLSearchParams({
+            activity_types: FEE_ACTIVITY_TYPES,
+            after,
+            page_size: String(ACTIVITIES_PAGE_SIZE),
+        });
+        if (pageToken) {
+            queryParams.append("page_token", pageToken);
+        }
+        const activities = await makeRequest(auth, {
+            endpoint: "/account/activities",
+            method: "GET",
+            queryString: `?${queryParams.toString()}`,
+        });
+        if (!Array.isArray(activities) || activities.length === 0) {
+            break;
+        }
+        for (const activity of activities) {
+            const amount = parseFloat(activity.net_amount ?? "");
+            if (Number.isFinite(amount)) {
+                // Fee entries are debits (negative net_amount); accumulate magnitude.
+                total += Math.abs(amount);
+            }
+        }
+        if (activities.length < ACTIVITIES_PAGE_SIZE) {
+            break;
+        }
+        pageToken = activities[activities.length - 1].id;
+    }
+    return total;
 }
 /**
  * Calculates the liquidity ratio for a given Alpaca account.
@@ -11322,6 +11757,58 @@ async function calculateInformationRatio(portfolioHistory, benchmarkBars) {
     }
     return informationRatio.toFixed(4);
 }
+/**
+ * Maps a portfolio-history timeframe token to the Alpaca market-data
+ * {@link TimeFrame} accepted by the historical-bars endpoint. Benchmark
+ * comparison is daily by default when no timeframe is supplied.
+ * @param timeframe - The portfolio-history timeframe token.
+ * @returns The equivalent Alpaca market-data timeframe.
+ */
+function toAlpacaTimeFrame(timeframe) {
+    switch (timeframe) {
+        case "1Min":
+            return "1Min";
+        case "5Min":
+            return "5Min";
+        case "15Min":
+            return "15Min";
+        case "1H":
+            return "1Hour";
+        case "1D":
+            return "1Day";
+        default:
+            return "1Day";
+    }
+}
+/** Milliseconds per second, for RFC-3339 → Unix-second conversion. */
+const MS_PER_SECOND = 1000;
+/**
+ * Fetches benchmark OHLCV bars from the wrapped Alpaca market-data vendor and
+ * maps them into {@link BenchmarkBar}s (Unix-second timestamp + close price)
+ * expected by the alpha/beta/information-ratio calculators.
+ * @param request - Benchmark symbol, RFC-3339 start/end, and timeframe token.
+ * @returns The benchmark bars, sorted ascending by time; empty if none.
+ */
+async function fetchBenchmarkBars(request) {
+    const { symbol, start, end, timeframe } = request;
+    const response = await marketDataAPI.getHistoricalBars({
+        symbols: [symbol],
+        timeframe: toAlpacaTimeFrame(timeframe),
+        start,
+        end,
+        sort: "asc",
+    });
+    const bars = response.bars[symbol];
+    if (!Array.isArray(bars) || bars.length === 0) {
+        return [];
+    }
+    return bars
+        .map((bar) => ({
+        t: Math.floor(new Date(bar.t).getTime() / MS_PER_SECOND),
+        c: bar.c,
+    }))
+        .filter((bar) => Number.isFinite(bar.t) && Number.isFinite(bar.c));
+}
 /**
  * Fetches performance metrics for a given Alpaca account.
  * @param params - The parameters for fetching performance metrics.
@@ -11386,7 +11873,10 @@ async function fetchPerformanceMetrics({ params, client, accountId, alpacaAccoun
             getLogger().error("[fetchPerformanceMetrics] Error fetching portfolio history:", error);
             throw new Error("Failed to retrieve portfolio history data");
         }
-        // Fetch benchmark data with enhanced error handling
+        // Fetch benchmark data directly from the wrapped Alpaca market-data vendor.
+        // (Previously this hit a relative "/api/market-data/historical-prices"
+        // Next.js route that only resolves in a browser; in a Node/engine runtime
+        // the relative fetch always threw, silently zeroing out alpha/beta/IR.)
         const benchmarkSymbol = "SPY";
         let benchmarkBars = [];
         try {
@@ -11397,24 +11887,16 @@ async function fetchPerformanceMetrics({ params, client, accountId, alpacaAccoun
                     : params?.period
                         ? params?.period
                         : "1Y",
-                outputFormat: "unix-ms",
+                outputFormat: "iso",
                 intraday_reporting: params?.intraday_reporting,
             });
-            const response = await fetch(`/api/market-data/historical-prices?symbol=${benchmarkSymbol}&start=${start.toString()}&end=${end.toString()}&timeframe=${params.timeframe}`, {
-                method: "GET",
-                headers: {
-                    "Content-Type": "application/json",
-                },
-                signal: createTimeoutSignal(DEFAULT_TIMEOUTS.GENERAL),
+            benchmarkBars = await fetchBenchmarkBars({
+                symbol: benchmarkSymbol,
+                start: String(start),
+                end: String(end),
+                timeframe: params.timeframe,
             });
-            if (!response.ok) {
-                const errorText = await response.text();
-                throw new Error(`Failed to fetch benchmark data: ${response.statusText} - ${errorText}`);
-            }
-            benchmarkBars = await response.json();
-            if (!benchmarkBars ||
-                !Array.isArray(benchmarkBars) ||
-                benchmarkBars.length === 0) {
+            if (benchmarkBars.length === 0) {
                 throw new Error("Received empty or invalid benchmark data");
             }
         }