@adaptic/utils 0.0.1011 → 0.0.1013

package/dist/index.mjs

@@ -11413,7 +11413,13 @@ async function calculateMaxDrawdown$1(tradeBars, isShort) {
             peak = positionAwareEquity[i];
         }
         else {
-            const drawdown = peak <= 0 ? 0 : (peak - positionAwareEquity[i]) / Math.abs(peak);
+            // The short branch negates equity, so its peak is legitimately negative.
+            // Scale the decline by the peak's magnitude — a sign test on the peak
+            // would discard every drawdown on one side of the book.
+            const denominator = Math.abs(peak);
+            const drawdown = denominator === 0
+                ? 0
+                : (peak - positionAwareEquity[i]) / denominator;
             if (drawdown > maxDrawdown) {
                 maxDrawdown = drawdown;
             }
@@ -11426,17 +11432,71 @@ async function calculateExpenseRatio$1(trade) {
     const totalFees = await computeTotalFees(trade);
     return totalFees ? `${totalFees.toFixed(2)}%` : "N/A";
 }
+/**
+ * Resolves whether a trade is short from its primary action.
+ *
+ * Only an outright BUY or SELL fixes whether the position's P&L runs with or
+ * against the price series. Option legs, exercises, cancels, adjustments and
+ * hedges do not, and `trade.actions` itself is curated by backend-legacy
+ * selection-set directives, so its absence is routine. Every one of those
+ * cases leaves the direction genuinely unknown, and unknown is returned as
+ * such — inferring a side would silently invert every direction-aware metric
+ * computed from it.
+ *
+ * @param trade - Trade whose direction is being resolved
+ * @returns `true` for a short, `false` for a long, `null` when unresolvable
+ */
+function resolveIsShort(trade) {
+    const primaryAction = trade.actions?.find((action) => action.primary);
+    if (!primaryAction) {
+        getLogger().warn(`Trade ${trade.id} has no primary action; position direction is unresolved.`);
+        return null;
+    }
+    switch (primaryAction.type) {
+        case "SELL":
+            return true;
+        case "BUY":
+            return false;
+        default:
+            getLogger().warn(`Trade ${trade.id} primary action type "${primaryAction.type}" does not determine a long/short direction.`);
+            return null;
+    }
+}
 // Main function to fetch and calculate all trade metrics for one trade object
 async function fetchTradeMetrics(trade, tradeBars, benchmarkBars) {
-    const isShort = trade.actions?.find((a) => a.primary)?.type === "SELL" ? true : false;
+    const isShort = resolveIsShort(trade);
+    // The Sharpe ratio and the expense ratio do not invert on direction, so they
+    // are started immediately and stay concurrent with everything below.
+    const riskAdjustedReturnPromise = calculateRiskAdjustedReturn$1(tradeBars);
+    const expenseRatioPromise = calculateExpenseRatio$1(trade);
+    if (isShort === null) {
+        // Every other metric inverts on direction. With the direction unknown
+        // there is no value to report — only a sign-ambiguous one — so they are
+        // reported as unavailable rather than resolved by assumption.
+        const [riskAdjustedReturn, expenseRatio] = await Promise.all([
+            riskAdjustedReturnPromise,
+            expenseRatioPromise,
+        ]);
+        return {
+            totalReturnYTD: "N/A",
+            alpha: "N/A",
+            beta: "N/A",
+            alphaAnnualized: "N/A",
+            informationRatio: "N/A",
+            riskAdjustedReturn,
+            expenseRatio,
+            maxDrawdown: "N/A",
+            side: "N/A",
+        };
+    }
     // Calculate metrics concurrently
-    const [totalReturnYTD, { alpha, beta, alphaAnnualized }, informationRatio, riskAdjustedReturn, expenseRatio, maxDrawdown,] = await Promise.all([
+    const [totalReturnYTD, { alpha, beta, alphaAnnualized }, informationRatio, maxDrawdown, riskAdjustedReturn, expenseRatio,] = await Promise.all([
         calculateProfitLoss(tradeBars, isShort),
         calculateAlphaAndBeta$1(tradeBars, benchmarkBars, isShort),
         calculateInformationRatio$1(tradeBars, benchmarkBars, isShort),
-        calculateRiskAdjustedReturn$1(tradeBars),
-        calculateExpenseRatio$1(trade),
         calculateMaxDrawdown$1(tradeBars, isShort),
+        riskAdjustedReturnPromise,
+        expenseRatioPromise,
     ]);
     return {
         totalReturnYTD,
@@ -12902,6 +12962,43 @@ function calculateEMA(priceData, { period = 20, period2 = 9 } = {}) {
     }
     return result;
 }
+/**
+ * Locates a window's swing extremes and derives the direction of its most
+ * recent leg from the order in which those extremes print.
+ *
+ * A Fibonacci construction is anchored to the latest leg: an up-leg runs swing
+ * low to swing high, a down-leg swing high to swing low. Whichever extreme
+ * prints last therefore identifies the leg, which makes the direction a
+ * measurement of the window rather than a caller's assumption. When both
+ * extremes land on the same bar the window contains no leg and the direction
+ * is genuinely indeterminate.
+ *
+ * @param window - The lookback slice to analyse.
+ * @returns The window's swing extremes and derived leg direction.
+ */
+function analyzeSwingWindow(window) {
+    let swingHigh = -Infinity;
+    let swingLow = Infinity;
+    let highIndex = -1;
+    let lowIndex = -1;
+    // `>=` / `<=` keep the most recent occurrence of each extreme, which is the
+    // one the current leg is measured from.
+    for (let i = 0; i < window.length; i++) {
+        if (window[i].high >= swingHigh) {
+            swingHigh = window[i].high;
+            highIndex = i;
+        }
+        if (window[i].low <= swingLow) {
+            swingLow = window[i].low;
+            lowIndex = i;
+        }
+    }
+    return {
+        swingHigh,
+        swingLow,
+        trend: highIndex === lowIndex ? null : highIndex > lowIndex ? "uptrend" : "downtrend",
+    };
+}
 /**
  * Calculates Fibonacci retracement and extension levels based on price data.
  * Fibonacci levels are used to identify potential support and resistance levels.
@@ -12911,22 +13008,28 @@ function calculateEMA(priceData, { period = 20, period2 = 9 } = {}) {
  * @param params.lookbackPeriod - The number of periods to look back for swing high/low (default is 20).
  * @param params.retracementLevels - An array of retracement levels to calculate (default is [0.236, 0.382, 0.5, 0.618, 0.786]).
  * @param params.extensionLevels - An array of extension levels to calculate (default is [1.272, 1.618, 2.618]).
- * @param params.reverseDirection - A boolean indicating if the trend is reversed (default is false).
+ * @param params.reverseDirection - Forces the leg direction: `true` for a downtrend, `false` for an uptrend. Omit it to derive the direction per bar from the swing window.
  * @returns An array of FibonacciData objects containing the calculated levels.
  */
-function calculateFibonacciLevels(priceData, { lookbackPeriod = 20, retracementLevels = [0.236, 0.382, 0.5, 0.618, 0.786], extensionLevels = [1.272, 1.618, 2.618], reverseDirection = false, } = {}) {
+function calculateFibonacciLevels(priceData, { lookbackPeriod = 20, retracementLevels = [0.236, 0.382, 0.5, 0.618, 0.786], extensionLevels = [1.272, 1.618, 2.618], reverseDirection, } = {}) {
     const result = [];
     for (let i = 0; i < priceData.length; i++) {
         const periodSlice = priceData.slice(Math.max(0, i - lookbackPeriod + 1), i + 1);
-        const swingHigh = Math.max(...periodSlice.map((d) => d.high));
-        const swingLow = Math.min(...periodSlice.map((d) => d.low));
+        const { swingHigh, swingLow, trend: derivedTrend } = analyzeSwingWindow(periodSlice);
         const priceRange = swingHigh - swingLow;
-        const trend = reverseDirection ? "downtrend" : "uptrend";
+        // An explicit `reverseDirection` is the caller stating the leg it is
+        // measuring; absent that, the leg is read off the window itself.
+        const trend = reverseDirection === undefined
+            ? derivedTrend
+            : reverseDirection
+                ? "downtrend"
+                : "uptrend";
         const levels = [];
-        if (priceRange > 0) {
+        if (priceRange > 0 && trend !== null) {
+            const isDowntrend = trend === "downtrend";
             // Calculate retracement levels
             retracementLevels.forEach((level) => {
-                const price = reverseDirection
+                const price = isDowntrend
                     ? swingLow + priceRange * level
                     : swingHigh - priceRange * level;
                 levels.push({
@@ -12935,10 +13038,13 @@ function calculateFibonacciLevels(priceData, { lookbackPeriod = 20, retracementL
                     type: "retracement",
                 });
             });
-            // Calculate extension levels
+            // Calculate extension levels — each is projected beyond the leg's
+            // terminal extreme: past the swing low for a down-leg, past the swing
+            // high for an up-leg. Anchoring both to the same extreme would place one
+            // side's targets a full swing range away from where the leg is running.
             extensionLevels.forEach((level) => {
-                const price = reverseDirection
-                    ? swingHigh - priceRange * (level - 1) // For downtrend
+                const price = isDowntrend
+                    ? swingLow - priceRange * (level - 1) // For downtrend
                     : swingHigh + priceRange * (level - 1); // For uptrend
                 levels.push({
                     level,
@@ -12947,7 +13053,10 @@ function calculateFibonacciLevels(priceData, { lookbackPeriod = 20, retracementL
                 });
             });
             // Sort levels by price
-            levels.sort((a, b) => reverseDirection ? b.price - a.price : a.price - b.price);
+            levels.sort((a, b) => isDowntrend ? b.price - a.price : a.price - b.price);
+        }
+        else if (trend === null) {
+            logIfDebug(`Swing high and low fall on the same bar on date ${priceData[i].date}; trend is indeterminate and no levels calculated.`);
         }
         else {
             logIfDebug(`Price range is zero on date ${priceData[i].date}; no levels calculated.`);
@@ -51969,7 +52078,8 @@ async function createBracketOrder(executor, params) {
  *
  * @example
  * ```typescript
- * // Add protection to an existing long position
+ * // Add protection to an existing long position (sell to close):
+ * // take profit above, stop below.
  * const result = await createProtectiveBracket(
  *   executor,
  *   {
@@ -51982,6 +52092,23 @@ async function createBracketOrder(executor, params) {
  *   }
  * );
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Add protection to an existing short position (buy to close):
+ * // take profit below, stop above.
+ * const result = await createProtectiveBracket(
+ *   executor,
+ *   {
+ *     symbol: 'TSLA',
+ *     qty: 50,
+ *     side: 'buy',
+ *     takeProfit: { limitPrice: 200.00 },
+ *     stopLoss: { stopPrice: 260.00 },
+ *     timeInForce: 'gtc',
+ *   }
+ * );
+ * ```
  */
 async function createProtectiveBracket(executor, params) {
     log$j(`Creating protective bracket for ${params.symbol}: ${params.qty} shares`, { type: "info" });
@@ -51994,15 +52121,28 @@ async function createProtectiveBracket(executor, params) {
     if (!params.qty || params.qty <= 0) {
         throw new Error("Quantity must be a positive number");
     }
+    // The closing side determines which of the two exit prices is the profit
+    // target, so it must be stated rather than inferred.
+    if (params.side !== "buy" && params.side !== "sell") {
+        throw new Error("Protective bracket requires a side of 'buy' or 'sell' matching the position being closed");
+    }
     if (!params.takeProfit?.limitPrice || params.takeProfit.limitPrice <= 0) {
         throw new Error("Take profit limit price is required and must be positive");
     }
     if (!params.stopLoss?.stopPrice || params.stopLoss.stopPrice <= 0) {
         throw new Error("Stop loss stop price is required and must be positive");
     }
-    // For a protective sell bracket, take profit should be higher than stop loss
-    if (params.takeProfit.limitPrice <= params.stopLoss.stopPrice) {
-        log$j("Warning: Take profit price should be higher than stop loss price for protective sell bracket", { type: "warn" });
+    // The take profit must sit on the profitable side of the position and the
+    // stop on the losing side. Which price is the higher one therefore depends
+    // on the closing side: selling to close a long takes profit above and stops
+    // below; buying to close a short is the exact mirror.
+    if (params.side === "sell") {
+        if (params.takeProfit.limitPrice <= params.stopLoss.stopPrice) {
+            log$j("Warning: Take profit price should be higher than stop loss price for protective sell bracket", { type: "warn" });
+        }
+    }
+    else if (params.takeProfit.limitPrice >= params.stopLoss.stopPrice) {
+        log$j("Warning: Take profit price should be lower than stop loss price for protective buy bracket", { type: "warn" });
     }
     try {
         // Build the OCO order parameters
@@ -53777,10 +53917,13 @@ async function cancelTrailingStop(client, orderId) {
     }
 }
 /**
- * Create trailing stops for all positions in a portfolio
+ * Create trailing stops for every position in a portfolio
  *
- * This function creates trailing stop orders for all long positions in the portfolio,
- * which is useful for applying blanket downside protection. Short positions are skipped.
+ * Applies blanket adverse-move protection across the book. The protective side
+ * is derived per position from the signed quantity reported by the broker — a
+ * long is protected by a trailing sell, a short by a trailing buy — so a
+ * position is never left unprotected because of the direction it happens to
+ * hold.
  *
  * @param client - AlpacaClient instance
  * @param params - Configuration for portfolio-wide trailing stops
@@ -53805,8 +53948,11 @@ async function createPortfolioTrailingStops(client, params) {
     if (params.trailPercent <= 0) {
         throw new Error("trailPercent must be greater than 0");
     }
-    if (params.trailPercent > 100) {
-        throw new Error("trailPercent cannot exceed 100");
+    // Reject against the broker's real ceiling up front. A looser outer bound
+    // lets an out-of-range value reach the per-position loop, where every single
+    // submission is rejected and the book silently ends up unprotected.
+    if (params.trailPercent > ALPACA_MAX_TRAIL_PERCENT) {
+        throw new Error(`trailPercent cannot exceed ${ALPACA_MAX_TRAIL_PERCENT} (Alpaca API limit)`);
     }
     const sdk = client.getSDK();
     const results = new Map();
@@ -53829,19 +53975,21 @@ async function createPortfolioTrailingStops(client, params) {
                 log$g(`Skipping ${symbol} (excluded)`, { type: "debug" });
                 continue;
             }
-            // Only create trailing stops for long positions
+            // Derive the protective side from the broker's signed quantity: a long
+            // (qty > 0) is closed by selling, a short (qty < 0) by buying. Direction
+            // is read from the position, never assumed — a stop on the wrong side
+            // doubles the exposure it was meant to cap.
             const qty = parseFloat(position.qty);
-            if (qty <= 0) {
-                log$g(`Skipping ${symbol} (not a long position, qty: ${qty})`, {
-                    type: "debug",
-                });
+            if (!Number.isFinite(qty) || qty === 0) {
+                log$g(`Skipping ${symbol}: position qty "${position.qty}" is not a usable non-zero number`, { type: "warn" });
                 continue;
             }
+            const side = qty > 0 ? "sell" : "buy";
             try {
                 const order = await createTrailingStop(client, {
                     symbol,
                     qty: Math.abs(qty),
-                    side: "sell",
+                    side,
                     trailPercent: params.trailPercent,
                     timeInForce: params.timeInForce || "gtc",
                 });
@@ -54779,13 +54927,25 @@ async function shortWithStopLoss(client, symbol, qty, entryPrice, stopLossPrice)
  * @param qty - Number of shares
  * @param entryPrice - Limit price for entry (null for market)
  * @param stopLossPercent - Stop loss percentage (e.g., 5 for 5%)
- * @param side - Order side ('buy' or 'sell')
+ * @param side - Order side ('buy' or 'sell'). Required: the entry direction is
+ *   the caller's decision, and a default would open a position in a direction
+ *   nobody chose.
  *
  * @example
  * // Buy AAPL at $150 with 3% stop loss (stop at $145.50)
  * const result = await entryWithPercentStopLoss(client, 'AAPL', 100, 150.00, 3, 'buy');
+ *
+ * @example
+ * // Short GOOGL at $140 with 3% stop loss (stop at $144.20)
+ * const result = await entryWithPercentStopLoss(client, 'GOOGL', 10, 140.00, 3, 'sell');
  */
-async function entryWithPercentStopLoss(client, symbol, qty, entryPrice, stopLossPercent, side = "buy") {
+async function entryWithPercentStopLoss(client, symbol, qty, entryPrice, stopLossPercent, side) {
+    // Guard the direction at runtime as well as in the signature: every price
+    // below is computed off `side`, so an unsupplied one would silently place
+    // the stop on the wrong side of the entry.
+    if (side !== "buy" && side !== "sell") {
+        throw new Error("entryWithPercentStopLoss requires an explicit side of 'buy' or 'sell'; the entry direction cannot be inferred");
+    }
     if (stopLossPercent <= 0 || stopLossPercent >= 100) {
         throw new Error("stopLossPercent must be between 0 and 100");
     }
@@ -64849,6 +65009,15 @@ class AssetAllocationEngine {
      * Assess current market condition
      */
     assessMarketCondition(metrics) {
+        // Crisis detection runs first: it is the strictly more severe reading and
+        // its volatility threshold sits above the high-volatility one, so testing
+        // volatility first would classify every crisis-level VIX as merely high
+        // and never reach this branch at all.
+        if (metrics.volatilityIndex > 40 ||
+            metrics.sentimentScore < 20 ||
+            metrics.creditSpread > 500) {
+            return "CRISIS";
+        }
         // High volatility check
         if (metrics.volatilityIndex > 30) {
             return "HIGH_VOLATILITY";
@@ -64857,12 +65026,6 @@ class AssetAllocationEngine {
         if (metrics.volatilityIndex < 12) {
             return "LOW_VOLATILITY";
         }
-        // Crisis detection
-        if (metrics.volatilityIndex > 40 ||
-            metrics.sentimentScore < 20 ||
-            metrics.creditSpread > 500) {
-            return "CRISIS";
-        }
         // Bull market
         if (metrics.trendDirection === "UP" &&
             metrics.marketStrength > 60 &&
@@ -71158,6 +71321,14 @@ const DEFAULT_TRADING_POLICY = EffectiveTradingPolicySchema.parse({
     optionsEnabled: true,
     futuresEnabled: true,
     forexEnabled: true,
+    // Shorting and margin are capability opt-ins, not a directional stance.
+    // Both require a margin agreement and locate/borrow availability the
+    // package cannot verify, so an account that has not asserted the
+    // capability defaults to the one it is known to have. This is a statement
+    // about account permissions, never a preference for long over short — the
+    // side a strategy takes is derived from live data once the capability is
+    // enabled. Resolve these from the broker account's actual margin and
+    // shorting entitlements wherever those are available.
     shortingEnabled: false,
     marginEnabled: false,
     fractionalSharesEnabled: true,