@adaptic/utils 0.0.1013 → 0.0.1015

package/dist/index.cjs

@@ -2212,11 +2212,20 @@ class AdapticUtilsError extends Error {
  */
 class AlpacaApiError extends AdapticUtilsError {
     statusCode;
-    constructor(message, code, statusCode, cause) {
+    brokerError;
+    constructor(message, code, statusCode, cause, 
+    /**
+     * Normalized Alpaca broker-rejection detail (numeric code + message + raw
+     * body), when the underlying rejection carried one. Additive and optional:
+     * synthetic errors and non-broker failures omit it, and every existing
+     * consumer of `message`/`code`/`statusCode`/`cause` is unaffected.
+     */
+    brokerError) {
         // Rate limit (429) and server errors (5xx) are retryable
         const isRetryable = statusCode === 429 || (statusCode !== undefined && statusCode >= 500);
         super(message, code, "alpaca", isRetryable, cause);
         this.statusCode = statusCode;
+        this.brokerError = brokerError;
     }
 }
 /**
@@ -2412,11 +2421,261 @@ class DuplicateClientOrderIdError extends AlpacaApiError {
     clientOrderId, 
     /** Whether the colliding id was derived by the wrapper (vs caller-supplied). */
     wasDerived, cause) {
-        super(message, "DUPLICATE_CLIENT_ORDER_ID", 422, cause);
+        // Carry the normalized broker payload forward from the original rejection
+        // (the `cause`) so a consumer can read the numeric code without re-parsing.
+        super(message, "DUPLICATE_CLIENT_ORDER_ID", 422, cause, extractAlpacaBrokerError(cause));
         this.clientOrderId = clientOrderId;
         this.wasDerived = wasDerived;
     }
 }
+/** Max depth walked along the `error.cause` chain when locating a broker payload. */
+const MAX_BROKER_ERROR_CAUSE_DEPTH = 6;
+/**
+ * Narrows an unknown value to an index-signature record so nested properties
+ * can be probed without an unsafe cast.
+ * @param value - The value to test.
+ * @returns true when the value is a non-null object.
+ */
+function isBrokerErrorRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Reads a finite number from an unknown value, accepting Alpaca's numeric
+ * `code` whether it arrives as a JSON number or a numeric string.
+ * @param value - The candidate value.
+ * @returns The number when finite, otherwise null.
+ */
+function asBrokerCode(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+/**
+ * Reads the axios/SDK-shaped broker payload from a SINGLE node's `response`
+ * field: an object `response.data` (`{ code, message }`) or a `response.data`
+ * left as an unparsed JSON string (the raw-`fetch` seams attach the body as a
+ * string). A known HTTP `response.status` is itself a broker-boundary signal —
+ * a `422` whose body carries no numeric code is still a `422` — so a
+ * status-only detail (`brokerCode: null`) is surfaced rather than discarded.
+ * Returns `undefined` only when the node carries no `response` and no status.
+ *
+ * @param node - The candidate error-like record.
+ * @returns The normalized detail, or undefined when the node has no response.
+ */
+function readResponseBrokerDetail(node) {
+    const response = node.response;
+    if (!isBrokerErrorRecord(response)) {
+        return undefined;
+    }
+    const statusCode = asBrokerCode(response.status);
+    // A known status with no structured code/message: preserve the status rather
+    // than discarding it (a code null is never fabricated into a value).
+    const statusOnly = statusCode === null
+        ? undefined
+        : { brokerCode: null, brokerMessage: null, statusCode, raw: response.data };
+    // Keep the raw body in its own const so the string narrowing survives the
+    // JSON.parse (a reassigned `let` would widen back to `unknown` in the catch).
+    const rawData = response.data;
+    let parsed = rawData;
+    if (typeof rawData === "string") {
+        try {
+            parsed = JSON.parse(rawData);
+        }
+        catch {
+            // A non-JSON string body carries a human reason but no structured code.
+            return { brokerCode: null, brokerMessage: rawData, statusCode, raw: rawData };
+        }
+    }
+    if (!isBrokerErrorRecord(parsed)) {
+        return statusOnly;
+    }
+    const brokerCode = asBrokerCode(parsed.code);
+    const brokerMessage = typeof parsed.message === "string" ? parsed.message : null;
+    if (brokerCode === null && brokerMessage === null) {
+        return statusOnly;
+    }
+    return { brokerCode, brokerMessage, statusCode, raw: rawData };
+}
+/**
+ * Reads the normalized broker detail from a SINGLE error-like node, without
+ * walking its `cause` chain. Recognizes two carriers on the node: an
+ * {@link AlpacaBrokerErrorDetail} already attached as `brokerError`, and an
+ * axios/SDK-shaped `response` body (object or unparsed JSON string). A carrier
+ * bearing a numeric code wins over a code-less one, so an enrichment that
+ * resolved no code never shadows a numeric code sitting in the same node's raw
+ * response body. Returns `undefined` when the node carries no broker payload,
+ * so absence is never converted into a fabricated code.
+ *
+ * @param node - The candidate error-like value.
+ * @returns The normalized detail, or undefined.
+ */
+function readBrokerDetailFromNode(node) {
+    if (!isBrokerErrorRecord(node)) {
+        return undefined;
+    }
+    // Carrier 1: a detail already normalized and attached by this module
+    // (e.g. AlpacaApiError.brokerError or a value enriched via enrichAlpacaError).
+    let attachedDetail;
+    const attached = node.brokerError;
+    if (isBrokerErrorRecord(attached) && "brokerCode" in attached) {
+        attachedDetail = {
+            brokerCode: asBrokerCode(attached.brokerCode),
+            brokerMessage: typeof attached.brokerMessage === "string"
+                ? attached.brokerMessage
+                : null,
+            statusCode: asBrokerCode(attached.statusCode),
+            raw: attached.raw,
+        };
+        // A numeric code on the attached detail is authoritative for this node.
+        if (attachedDetail.brokerCode !== null) {
+            return attachedDetail;
+        }
+    }
+    // Carrier 2: an axios/SDK-shaped `response` body on the same node. Prefer a
+    // numeric code found here over a code-less attached detail.
+    const responseDetail = readResponseBrokerDetail(node);
+    if (responseDetail?.brokerCode != null) {
+        return responseDetail;
+    }
+    return attachedDetail ?? responseDetail;
+}
+/**
+ * Extracts the normalized {@link AlpacaBrokerErrorDetail} from a thrown Alpaca
+ * SDK/axios error, reading the vendor payload at `error.response.data` and,
+ * failing that, walking the `error.cause` chain (the raw SDK error is preserved
+ * there once a wrapper has re-thrown). Returns `undefined` when no broker
+ * payload is present anywhere on the chain.
+ *
+ * Pure and outcome-independent: derived solely from Alpaca's documented error
+ * contract, with zero reference to realized P&L, fills, or account state.
+ *
+ * A node bearing a numeric broker code wins immediately; a code-less detail
+ * (status-only or message-only) found higher on the chain is held as a fallback
+ * while the walk continues, so a numeric code sitting deeper in the `cause`
+ * chain is never shadowed by a shallower code-less node — and when no code
+ * exists anywhere, the code-less detail is still returned rather than discarded.
+ *
+ * @param error - The thrown value.
+ * @returns The normalized broker detail, or undefined when none is present.
+ */
+function extractAlpacaBrokerError(error) {
+    let current = error;
+    let fallback;
+    for (let depth = 0; depth < MAX_BROKER_ERROR_CAUSE_DEPTH && current != null; depth++) {
+        const detail = readBrokerDetailFromNode(current);
+        if (detail !== undefined) {
+            if (detail.brokerCode !== null) {
+                return detail;
+            }
+            if (fallback === undefined) {
+                fallback = detail;
+            }
+        }
+        if (!isBrokerErrorRecord(current)) {
+            break;
+        }
+        current = current.cause;
+    }
+    return fallback;
+}
+/**
+ * Returns the normalized {@link AlpacaBrokerErrorDetail} for a thrown error, or
+ * `null` when the error carries no Alpaca broker payload. The typed
+ * vendor-boundary replacement for reaching into `err.response.data` downstream.
+ *
+ * @param error - The thrown value.
+ * @returns The normalized detail, or null.
+ */
+function getAlpacaBrokerErrorDetail(error) {
+    return extractAlpacaBrokerError(error) ?? null;
+}
+/**
+ * Returns Alpaca's machine-readable numeric broker error code from a thrown
+ * error (walking the `cause` chain), or `null` when absent. The typed
+ * replacement for `err.message.includes("42210000")`:
+ *
+ * ```typescript
+ * if (getAlpacaBrokerErrorCode(err) === 42210000) { ... } // stale-order reject
+ * ```
+ *
+ * The code resolves uniformly across every vendor seam: the SDK/axios path
+ * (where `response.data` rides along for free) and the raw-`fetch` paths — the
+ * `AlpacaTradingAPI` class `makeRequest` and the legacy order helpers, which
+ * throw via {@link alpacaHttpError} so the verbatim status + body are carried as
+ * a typed `.response`. A consumer branching on the stale-order `42210000` gets
+ * the same answer regardless of which seam produced the reject, including the
+ * dominant percent-trailing-stop tighten path where a plain `Error` previously
+ * dropped the broker payload.
+ *
+ * @param error - The thrown value.
+ * @returns The numeric broker code, or null.
+ */
+function getAlpacaBrokerErrorCode(error) {
+    return extractAlpacaBrokerError(error)?.brokerCode ?? null;
+}
+/**
+ * Additively enriches a thrown error with the normalized Alpaca broker detail
+ * extracted from `source` (the original SDK/axios rejection), WITHOUT changing
+ * the target's `message`, `name`, or prototype. It:
+ *
+ *  - sets `target.cause = source` when the target has no cause yet, so the raw
+ *    rejection (and its `response.data`) is never lost down the wrapper chain;
+ *  - attaches the normalized {@link AlpacaBrokerErrorDetail} as
+ *    `target.brokerError` when `source` carried a broker payload.
+ *
+ * Purely additive by construction: a caller writes
+ * `throw enrichAlpacaError(new Error(msg), error)` and every consumer that read
+ * `error.message` or `error instanceof Error` before reads the identical value
+ * after, while new consumers can call {@link getAlpacaBrokerErrorCode}. This is
+ * the restoration for the dropped-`response.data` defect (Alpaca `42210000` /
+ * `40310000` reaching consumers only as a lossy "status code NNN" string).
+ *
+ * @param target - The wrapper error about to be thrown.
+ * @param source - The original rejection to normalize and preserve.
+ * @returns The same `target`, typed to expose the optional `brokerError`.
+ */
+function enrichAlpacaError(target, source) {
+    const enriched = target;
+    if (enriched.cause === undefined && source !== undefined) {
+        enriched.cause = source;
+    }
+    const detail = extractAlpacaBrokerError(source);
+    if (detail !== undefined) {
+        enriched.brokerError = detail;
+    }
+    return enriched;
+}
+/**
+ * Builds a thrown-ready `Error` for a raw-`fetch` Alpaca rejection, carrying the
+ * verbatim HTTP status + body as a typed `.response` so that
+ * {@link getAlpacaBrokerErrorCode} / {@link extractAlpacaBrokerError} resolve
+ * the numeric broker code on the `fetch` seams (the `AlpacaTradingAPI` class
+ * `makeRequest` and the legacy functional order helpers) exactly as they
+ * already do on the SDK seam — where the SDK/axios error carries `response.data`
+ * for free but a hand-thrown `new Error(...)` does not.
+ *
+ * Purely additive by construction: the `.message` is caller-supplied and
+ * returned byte-identical (so message string-matching consumers are
+ * unaffected), the returned value `instanceof Error` still holds, and only the
+ * `.response` surface is added. The `data` is the raw string body exactly as
+ * `response.text()` returned it — {@link extractAlpacaBrokerError} parses a
+ * JSON-string body itself, so no vendor payload is lost or reshaped here.
+ *
+ * @param message - The error message, thrown verbatim (never rewritten).
+ * @param status - The HTTP status the rejection arrived on.
+ * @param body - The raw response body (`response.text()`), preserved verbatim.
+ * @returns An `Error` whose `.response` exposes `{ status, data: body }`.
+ */
+function alpacaHttpError(message, status, body) {
+    return Object.assign(new Error(message), {
+        response: { status, data: body },
+    });
+}
 
 const DEFAULT_RETRY_CONFIG = {
     maxRetries: 3,
@@ -5296,7 +5555,13 @@ class AlpacaTradingAPI {
                 this.log(`Alpaca API error (${response.status}): ${errorText}`, {
                     type: "error",
                 });
-                throw new Error(`Alpaca API error (${response.status}): ${errorText}`);
+                // Additive broker-error preservation: the message is byte-identical
+                // (existing "422"/"42210000" string-matching consumers are unaffected),
+                // and the verbatim status + body ride along as a typed `.response` so
+                // getAlpacaBrokerErrorCode resolves the numeric code on this fetch seam —
+                // the dominant percent-trailing-stop tighten path and the 08-20 defect
+                // site, where a plain Error dropped the broker's response.data.
+                throw alpacaHttpError(`Alpaca API error (${response.status}): ${errorText}`, response.status, errorText);
             }
             // Handle responses with no content (e.g., 204 No Content)
             if (response.status === 204 ||
@@ -5681,7 +5946,10 @@ class AlpacaTradingAPI {
                 this.log(`Order ${orderId} is not cancelable`, {
                     type: "error",
                 });
-                throw new Error(`Order ${orderId} is not cancelable`);
+                // Re-message stays byte-identical; the broker payload from makeRequest's
+                // `.response` is carried onto the new error so the numeric code survives
+                // this wrapper instead of being dropped at the re-throw.
+                throw enrichAlpacaError(new Error(`Order ${orderId} is not cancelable`), error);
             }
             // Re-throw other errors
             throw error;
@@ -6731,7 +6999,7 @@ async function makeRequest(auth, params) {
             source: "AlpacaAPI",
             type: "error",
         });
-        throw new Error(`Alpaca API error (${response.status}): ${errorText}`);
+        throw alpacaHttpError(`Alpaca API error (${response.status}): ${errorText}`, response.status, errorText);
     }
     catch (err) {
         const error = err;
@@ -6764,7 +7032,7 @@ async function createOrder$1(auth, params) {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Failed to create order: ${response.status} ${response.statusText} ${errorText}`);
+            throw alpacaHttpError(`Failed to create order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
         }
         return (await response.json());
     }
@@ -6811,7 +7079,7 @@ async function getOrders$1(auth, params = {}) {
             });
             if (!response.ok) {
                 const errorText = await response.text();
-                throw new Error(`Failed to get orders: ${response.status} ${response.statusText} ${errorText}`);
+                throw alpacaHttpError(`Failed to get orders: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
             }
             const orders = (await response.json());
             allOrders.push(...orders);
@@ -6872,7 +7140,7 @@ async function cancelAllOrders$1(auth) {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Failed to cancel orders: ${response.status} ${response.statusText} ${errorText}`);
+            throw alpacaHttpError(`Failed to cancel orders: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
         }
         return (await response.json());
     }
@@ -6905,7 +7173,7 @@ async function getOrder$1(auth, orderId, nested) {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Failed to get order: ${response.status} ${response.statusText} ${errorText}`);
+            throw alpacaHttpError(`Failed to get order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
         }
         return (await response.json());
     }
@@ -6938,7 +7206,7 @@ async function replaceOrder$1(auth, orderId, params) {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Failed to replace order: ${response.status} ${response.statusText} ${errorText}`);
+            throw alpacaHttpError(`Failed to replace order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
         }
         return (await response.json());
     }
@@ -6971,7 +7239,7 @@ async function cancelOrder$1(auth, orderId) {
                 return { success: false, message: `Order not found: ${orderId}` };
             }
             else {
-                throw new Error(`Failed to cancel order: ${response.status} ${response.statusText} ${errorText}`);
+                throw alpacaHttpError(`Failed to cancel order: ${response.status} ${response.statusText} ${errorText}`, response.status, errorText);
             }
         }
         return { success: true };
@@ -12862,6 +13130,66 @@ var strategyNs = /*#__PURE__*/Object.freeze({
     calculateRollingSortino: calculateRollingSortino
 });
 
+/**
+ * Round a PRICE-scale indicator output to a precision derived from its own
+ * magnitude, rather than a hardcoded 2 decimal places.
+ *
+ * A flat `toFixed(2)` silently destroys every sub-penny price — a $0.0003
+ * microcap's bands collapse to `0.00`, and a MACD histogram of a low-priced
+ * name rounds to nothing (F7.2). Precision must scale with the price: values at
+ * or above $1 keep the conventional 2dp, while sub-dollar values keep ~4
+ * significant figures so the number survives its own scale. Non-finite inputs
+ * pass through untouched — totality of the underlying value is the caller's
+ * responsibility, this helper only quantises.
+ *
+ * The `>= $1` branch delegates to `toFixed(2)` rather than re-deriving it as
+ * `Math.round(value * 100) / 100`. The two disagree wherever the intermediate
+ * `value * 100` rounds onto an exact `.5` that the decimal value sits just
+ * below (`1.045` → `1.05` vs `1.04`), which would make this helper shift
+ * ordinary dollar prices by a cent — a behaviour change well outside repairing
+ * sub-penny collapse. Delegating keeps the common case byte-identical to the
+ * historical output by construction, which matters because the same function
+ * computes indicators for unit tests, backtests, paper and live.
+ *
+ * @param value - A price-scale indicator output (band, EMA, MACD component).
+ * @returns The value rounded to a scale-appropriate precision.
+ */
+function roundToPriceScale(value) {
+    if (!Number.isFinite(value))
+        return value;
+    const abs = Math.abs(value);
+    if (abs === 0)
+        return 0;
+    if (abs >= 1)
+        return parseFloat(value.toFixed(2));
+    // Sub-dollar: decimals = leading zeros after the point + 4 significant figures,
+    // capped so the factor stays within safe-integer range.
+    const decimals = Math.min(12, Math.ceil(-Math.log10(abs)) + 4);
+    const factor = 10 ** decimals;
+    return Math.round(value * factor) / factor;
+}
+/**
+ * Relative Strength Index from average gain / average loss, total on the
+ * degenerate flat window.
+ *
+ * When a window has no losses the Wilder ratio `avgGain / avgLoss` is
+ * `+Infinity` (→ RSI 100); on a perfectly flat window it is `0 / 0 = NaN`,
+ * which the naive formula propagates straight into the output. A flat window
+ * carries no momentum, so its RSI is the neutral 50 — never NaN. This mirrors
+ * the engine's live RSI guards (a constant series scores neutral, an all-gains
+ * series scores 100).
+ *
+ * @param avgGain - Average gain over the period (>= 0).
+ * @param avgLoss - Average loss over the period (>= 0).
+ * @returns RSI in [0, 100]; 50 for a flat window, 100 for an all-gains window.
+ */
+function rsiFromAverages(avgGain, avgLoss) {
+    if (avgLoss === 0)
+        return avgGain === 0 ? 50 : 100;
+    const rs = avgGain / avgLoss;
+    const rsi = 100 - 100 / (1 + rs);
+    return Number.isFinite(rsi) ? rsi : 50;
+}
 /**
  * Calculates Bollinger Bands for a given set of price data.
  * Bollinger Bands consist of a middle band (SMA) and two outer bands
@@ -12894,9 +13222,9 @@ function calculateBollingerBands(priceData, { period = 20, standardDeviations =
         const lowerBand = sma - standardDeviation * standardDeviations;
         result.push({
             date: priceData[i].date,
-            middle: parseFloat(sma.toFixed(2)),
-            upper: parseFloat(upperBand.toFixed(2)),
-            lower: parseFloat(lowerBand.toFixed(2)),
+            middle: roundToPriceScale(sma),
+            upper: roundToPriceScale(upperBand),
+            lower: roundToPriceScale(lowerBand),
             close: priceData[i].close,
         });
     }
@@ -12938,11 +13266,11 @@ function calculateEMA(priceData, { period = 20, period2 = 9 } = {}) {
     // Add first EMA(s)
     const firstEntry = {
         date: priceData[Math.max(period, period2 || 0) - 1].date,
-        ema: parseFloat(prevEMA.toFixed(2)),
+        ema: roundToPriceScale(prevEMA),
         close: priceData[Math.max(period, period2 || 0) - 1].close,
     };
     if (period2) {
-        firstEntry.ema2 = parseFloat(prevEMA2.toFixed(2));
+        firstEntry.ema2 = roundToPriceScale(prevEMA2);
     }
     result.push(firstEntry);
     // Calculate EMA for remaining periods
@@ -12952,13 +13280,13 @@ function calculateEMA(priceData, { period = 20, period2 = 9 } = {}) {
         prevEMA = currentEMA;
         const entry = {
             date: priceData[i].date,
-            ema: parseFloat(currentEMA.toFixed(2)),
+            ema: roundToPriceScale(currentEMA),
             close: currentClose,
         };
         if (period2) {
             const currentEMA2 = (currentClose - prevEMA2) * multiplier2 + prevEMA2;
             prevEMA2 = currentEMA2;
-            entry.ema2 = parseFloat(currentEMA2.toFixed(2));
+            entry.ema2 = roundToPriceScale(currentEMA2);
         }
         result.push(entry);
     }
@@ -13036,7 +13364,7 @@ function calculateFibonacciLevels(priceData, { lookbackPeriod = 20, retracementL
                     : swingHigh - priceRange * level;
                 levels.push({
                     level,
-                    price: parseFloat(price.toFixed(2)),
+                    price: roundToPriceScale(price),
                     type: "retracement",
                 });
             });
@@ -13050,7 +13378,7 @@ function calculateFibonacciLevels(priceData, { lookbackPeriod = 20, retracementL
                     : swingHigh + priceRange * (level - 1); // For uptrend
                 levels.push({
                     level,
-                    price: parseFloat(price.toFixed(2)),
+                    price: roundToPriceScale(price),
                     type: "extension",
                 });
             });
@@ -13113,9 +13441,9 @@ function calculateMACD(priceData, { shortPeriod = 12, longPeriod = 26, signalPer
         const hist = macdValue - signalEMA;
         result.push({
             date: emaLong[i].date, // Use emaLong's date for alignment
-            macd: parseFloat(macdValue.toFixed(2)),
-            signal: parseFloat(signalEMA.toFixed(2)),
-            histogram: parseFloat(hist.toFixed(2)),
+            macd: roundToPriceScale(macdValue),
+            signal: roundToPriceScale(signalEMA),
+            histogram: roundToPriceScale(hist),
             close: emaLong[i].close,
         });
     }
@@ -13150,9 +13478,9 @@ function calculateRSI(priceData, { period = 14 } = {}) {
     }
     avgGain = avgGain / period;
     avgLoss = avgLoss / period;
-    // Calculate RSI for the first period
-    let rs = avgGain / avgLoss;
-    let rsi = 100 - 100 / (1 + rs);
+    // Calculate RSI for the first period (total on a flat window — see
+    // rsiFromAverages: a constant series scores the neutral 50, never NaN).
+    let rsi = rsiFromAverages(avgGain, avgLoss);
     result.push({
         date: priceData[period].date,
         rsi: parseFloat(rsi.toFixed(2)),
@@ -13166,8 +13494,7 @@ function calculateRSI(priceData, { period = 14 } = {}) {
         // Use smoothed averages
         avgGain = (avgGain * (period - 1) + gain) / period;
         avgLoss = (avgLoss * (period - 1) + loss) / period;
-        rs = avgGain / avgLoss;
-        rsi = 100 - 100 / (1 + rs);
+        rsi = rsiFromAverages(avgGain, avgLoss);
         result.push({
             date: priceData[i].date,
             rsi: parseFloat(rsi.toFixed(2)),
@@ -13188,6 +13515,20 @@ function calculateRSI(priceData, { period = 14 } = {}) {
  * @returns An array of StochData objects containing the calculated %K and %D values.
  */
 function calculateStochasticOscillator(priceData, { lookbackPeriod = 5, signalPeriod = 3, smoothingFactor = 3, } = {}) {
+    // Each period is a divisor (`kSum / min(len, smoothingFactor)`) and a slice
+    // width. A zero or fractional period therefore divides by zero or slices an
+    // empty window, producing NaN/Infinity %K and %D — an oscillator reading that
+    // is never true and never false. The periods are caller-supplied constants
+    // rather than market data, so an invalid one is a programming error and is
+    // reported as such, matching the ATR and volatility primitives.
+    if (!Number.isInteger(lookbackPeriod) ||
+        lookbackPeriod < 1 ||
+        !Number.isInteger(signalPeriod) ||
+        signalPeriod < 1 ||
+        !Number.isInteger(smoothingFactor) ||
+        smoothingFactor < 1) {
+        throw new Error("calculateStochasticOscillator: lookbackPeriod, signalPeriod and smoothingFactor must be positive integers");
+    }
     if (priceData.length < lookbackPeriod) {
         logIfDebug(`Insufficient data for Stochastic Oscillator calculation: required periods: ${lookbackPeriod}, but only received ${priceData.length} periods of data`);
         return [];
@@ -13228,6 +13569,48 @@ function calculateStochasticOscillator(priceData, { lookbackPeriod = 5, signalPe
     }
     return result;
 }
+/**
+ * Collapses a cluster of nearby pivots into one volume-weighted level, or
+ * reports that the cluster evidences no level at all.
+ *
+ * Both outputs are volume-weighted: the price is the volume-weighted mean of
+ * the cluster's pivots, and the strength is the pivot count weighted by each
+ * pivot's share of cluster volume. That weighting is undefined when the cluster
+ * transacted no volume — `0 / 0` makes both NaN. A NaN level is strictly worse
+ * than no level: every comparison against NaN is false, so a stop or target
+ * placed off one is silently never triggered, leaving the position unprotected
+ * while appearing protected.
+ *
+ * Zero cluster volume is a real market state rather than corrupt input — halted,
+ * pre-market-thin and synthetic warm-up bars all report it. A support or
+ * resistance level means price transacted enough there to turn the market, so a
+ * cluster with no volume has not evidenced one. `SupportResistanceLevel` types
+ * both fields as non-optional numbers, which leaves omitting the level as the
+ * only honest way to say so.
+ *
+ * @param cluster - The nearby pivots to collapse into a single level.
+ * @param currentPrice - The bar's close, which classifies the level's side.
+ * @returns The aggregated level, or null when the cluster evidences none.
+ */
+function aggregatePivotCluster(cluster, currentPrice) {
+    const totalVolume = cluster.reduce((sum, p) => sum + p.volume, 0);
+    // Negated `> 0` so NaN and negative totals are rejected alongside zero: no
+    // volume weighting survives any of them.
+    if (!(totalVolume > 0))
+        return null;
+    const avgPrice = cluster.reduce((sum, p) => sum + p.price * p.volume, 0) / totalVolume;
+    const strength = cluster.reduce((sum, p) => sum + p.count * (p.volume / totalVolume), 0);
+    if (!Number.isFinite(avgPrice) || !Number.isFinite(strength))
+        return null;
+    return {
+        // The level is a price, so its precision follows the price's magnitude
+        // (F7.2). Strength is a count-weighted score rather than a price and keeps
+        // the conventional 2dp.
+        price: roundToPriceScale(avgPrice),
+        strength: parseFloat(strength.toFixed(2)),
+        type: avgPrice > currentPrice ? "resistance" : "support",
+    };
+}
 /**
  * Calculates support and resistance levels based on price data.
  * Support and resistance levels are price levels at which a stock tends to stop and reverse.
@@ -13248,9 +13631,22 @@ function calculateSupportAndResistance(priceData, { maxLevels = 5, lookbackPerio
         const priceChanges = analysisWindow
             .slice(1)
             .map((bar, idx) => Math.abs(bar.close - analysisWindow[idx].close));
-        const avgPriceChange = priceChanges.reduce((sum, change) => sum + change, 0) /
-            priceChanges.length;
-        const volatility = avgPriceChange / analysisWindow[0].close; // Relative volatility
+        // A single-bar window produces no price changes to average, and a
+        // non-positive reference close cannot scale one — `0 / 0` and `x / 0` make
+        // the relative volatility NaN or Infinity. Volatility is the sole input to
+        // both the pivot sensitivity and the level-grouping gap below, so a
+        // non-finite value silently disables every comparison that depends on it
+        // (each is false against NaN). Unmeasurable volatility resolves to zero,
+        // under which each pivot stands as its own level instead of being merged on
+        // a meaningless ratio.
+        const referenceClose = analysisWindow[0].close;
+        const avgPriceChange = priceChanges.length > 0
+            ? priceChanges.reduce((sum, change) => sum + change, 0) /
+                priceChanges.length
+            : 0;
+        const volatility = referenceClose > 0 && Number.isFinite(avgPriceChange)
+            ? avgPriceChange / referenceClose
+            : 0; // Relative volatility
         // **Adjust Sensitivity and minGapBetweenLevels Dynamically**
         const sensitivity = volatility * 2; // Adjust the multiplier as needed
         const minGapBetweenLevels = volatility * 100; // Convert to percentage
@@ -13259,8 +13655,16 @@ function calculateSupportAndResistance(priceData, { maxLevels = 5, lookbackPerio
             const curr = analysisWindow[j];
             const prevBar = analysisWindow[j - 1];
             const nextBar = analysisWindow[j + 1];
+            // A pivot is matched against existing candidates by a *relative* gap
+            // measured against its own price, so a non-positive reference price makes
+            // that ratio meaningless: zero divides to NaN or Infinity (which never
+            // compares below the sensitivity, so the pivot never merges), and a
+            // negative price inverts the comparison (so everything merges). A bar
+            // without a positive high or low carries no tradeable level either way.
             // Check for high pivot
-            if (curr.high > prevBar.high && curr.high > nextBar.high) {
+            if (curr.high > 0 &&
+                curr.high > prevBar.high &&
+                curr.high > nextBar.high) {
                 const existingPivot = pivotPoints.find((p) => Math.abs(p.price - curr.high) / curr.high < sensitivity);
                 if (existingPivot) {
                     existingPivot.count++;
@@ -13271,7 +13675,7 @@ function calculateSupportAndResistance(priceData, { maxLevels = 5, lookbackPerio
                 }
             }
             // Check for low pivot
-            if (curr.low < prevBar.low && curr.low < nextBar.low) {
+            if (curr.low > 0 && curr.low < prevBar.low && curr.low < nextBar.low) {
                 const existingPivot = pivotPoints.find((p) => Math.abs(p.price - curr.low) / curr.low < sensitivity);
                 if (existingPivot) {
                     existingPivot.count++;
@@ -13301,33 +13705,17 @@ function calculateSupportAndResistance(priceData, { maxLevels = 5, lookbackPerio
                 }
                 else {
                     // Process current group
-                    if (currentGroup.length > 0) {
-                        const totalVolume = currentGroup.reduce((sum, p) => sum + p.volume, 0);
-                        const avgPrice = currentGroup.reduce((sum, p) => sum + p.price * p.volume, 0) /
-                            totalVolume;
-                        const totalStrength = currentGroup.reduce((sum, p) => sum + p.count * (p.volume / totalVolume), 0);
-                        levels.push({
-                            price: parseFloat(avgPrice.toFixed(2)),
-                            strength: parseFloat(totalStrength.toFixed(2)),
-                            type: avgPrice > currentPrice ? "resistance" : "support",
-                        });
-                    }
+                    const level = aggregatePivotCluster(currentGroup, currentPrice);
+                    if (level)
+                        levels.push(level);
                     currentGroup = [pivotPoints[j]];
                 }
             }
         }
         // Process final group
-        if (currentGroup.length > 0) {
-            const totalVolume = currentGroup.reduce((sum, p) => sum + p.volume, 0);
-            const avgPrice = currentGroup.reduce((sum, p) => sum + p.price * p.volume, 0) /
-                totalVolume;
-            const totalStrength = currentGroup.reduce((sum, p) => sum + p.count * (p.volume / totalVolume), 0);
-            levels.push({
-                price: parseFloat(avgPrice.toFixed(2)),
-                strength: parseFloat(totalStrength.toFixed(2)),
-                type: avgPrice > currentPrice ? "resistance" : "support",
-            });
-        }
+        const finalGroupLevel = aggregatePivotCluster(currentGroup, currentPrice);
+        if (finalGroupLevel)
+            levels.push(finalGroupLevel);
         // Sort by strength and limit
         const finalLevels = levels
             .sort((a, b) => b.strength - a.strength)
@@ -53774,7 +54162,7 @@ async function createTrailingStop(client, params) {
         log$g(`Trailing stop creation failed for ${params.symbol}: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to create trailing stop for ${params.symbol}: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to create trailing stop for ${params.symbol}: ${err.message}`), error);
     }
 }
 /**
@@ -53840,7 +54228,11 @@ async function updateTrailingStop(client, orderId, updates) {
         log$g(`Trailing stop update failed for ${orderId}: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to update trailing stop ${orderId}: ${err.message}`);
+        // Preserve Alpaca's `response.data` (numeric code `42210000` etc.) that the
+        // SDK reduces to a bare "status code NNN" message. This is THE trailing-stop
+        // modify path; dropping the code here left the consumer unable to tell a
+        // stale-order reject from a benign race, blind-failing the profit lock.
+        throw enrichAlpacaError(new Error(`Failed to update trailing stop ${orderId}: ${err.message}`), error);
     }
 }
 /**
@@ -53881,7 +54273,7 @@ async function getTrailingStopHWM(client, orderId) {
         log$g(`Failed to get trailing stop HWM for ${orderId}: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to get trailing stop HWM for ${orderId}: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to get trailing stop HWM for ${orderId}: ${err.message}`), error);
     }
 }
 /**
@@ -53910,12 +54302,12 @@ async function cancelTrailingStop(client, orderId) {
             log$g(`Trailing stop ${orderId} is not cancelable (may already be filled or canceled)`, {
                 type: "warn",
             });
-            throw new Error(`Trailing stop ${orderId} is not cancelable: order may already be filled or canceled`);
+            throw enrichAlpacaError(new Error(`Trailing stop ${orderId} is not cancelable: order may already be filled or canceled`), error);
         }
         log$g(`Failed to cancel trailing stop ${orderId}: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to cancel trailing stop ${orderId}: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to cancel trailing stop ${orderId}: ${err.message}`), error);
     }
 }
 /**
@@ -53999,9 +54391,14 @@ async function createPortfolioTrailingStops(client, params) {
             }
             catch (err) {
                 const errorMessage = err.message;
-                errors.push({ symbol, error: errorMessage });
+                // Preserve the broker's numeric code (e.g. 42210000) rather than
+                // reducing the swallowed per-item failure to its flattened message —
+                // this loop only logs failures, so the log is the preservation target.
+                const brokerCode = getAlpacaBrokerErrorCode(err);
+                errors.push({ symbol, error: errorMessage, brokerCode });
                 log$g(`Failed to create trailing stop for ${symbol}: ${errorMessage}`, {
                     type: "error",
+                    metadata: { brokerCode },
                 });
             }
         }
@@ -54011,7 +54408,9 @@ async function createPortfolioTrailingStops(client, params) {
         const skippedCount = positions.length - successCount - failureCount;
         log$g(`Portfolio trailing stops complete: ${successCount} created, ${failureCount} failed, ${skippedCount} skipped`, { type: "info" });
         if (errors.length > 0) {
-            log$g(`Failed symbols: ${errors.map((e) => `${e.symbol} (${e.error})`).join(", ")}`, {
+            log$g(`Failed symbols: ${errors
+                .map((e) => `${e.symbol} (${e.error}${e.brokerCode !== null ? `, code ${e.brokerCode}` : ""})`)
+                .join(", ")}`, {
                 type: "warn",
             });
         }
@@ -54022,7 +54421,7 @@ async function createPortfolioTrailingStops(client, params) {
         log$g(`Failed to create portfolio trailing stops: ${err.message}`, {
             type: "error",
         });
-        throw new Error(`Failed to create portfolio trailing stops: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to create portfolio trailing stops: ${err.message}`), error);
     }
 }
 /**
@@ -54061,7 +54460,7 @@ async function getOpenTrailingStops(client, symbol) {
     catch (error) {
         const err = error;
         log$g(`Failed to get open trailing stops: ${err.message}`, { type: "error" });
-        throw new Error(`Failed to get open trailing stops: ${err.message}`);
+        throw enrichAlpacaError(new Error(`Failed to get open trailing stops: ${err.message}`), error);
     }
 }
 /**
@@ -54109,7 +54508,10 @@ async function cancelTrailingStopsForSymbol(client, symbol) {
             canceledCount++;
         }
         catch (err) {
-            errors.push(`${order.id}: ${err.message}`);
+            // Keep the broker's numeric code alongside the message so the swallowed
+            // per-item cancel failure stays diagnosable in the summary log.
+            const brokerCode = getAlpacaBrokerErrorCode(err);
+            errors.push(`${order.id}: ${err.message}${brokerCode !== null ? ` (code ${brokerCode})` : ""}`);
         }
     }
     if (errors.length > 0) {
@@ -58346,7 +58748,12 @@ async function resolveDuplicateSubmission(client, clientOrderId, symbol, cause)
     catch (lookupError) {
         const reason = lookupError instanceof Error ? lookupError.message : String(lookupError);
         log$6(`Duplicate-order lookup failed for ${clientOrderId}; failing closed (no resubmit): ${reason}`, { type: "error", symbol, metadata: { clientOrderId } });
-        throw new DuplicateClientOrderIdError(`Duplicate client_order_id "${clientOrderId}" rejected by Alpaca and the existing-order lookup failed; refusing to resubmit (possible live duplicate)`, clientOrderId, false, lookupError);
+        // The typed error represents the ORIGINAL duplicate rejection, so its broker
+        // payload must come from `cause` (the 422), not from the lookup failure.
+        // Chain the lookup error ahead of the original 422 (and carry the 422's
+        // normalized detail onto it) so both are diagnosable and
+        // getAlpacaBrokerErrorCode still resolves the duplicate code.
+        throw new DuplicateClientOrderIdError(`Duplicate client_order_id "${clientOrderId}" rejected by Alpaca and the existing-order lookup failed; refusing to resubmit (possible live duplicate)`, clientOrderId, false, enrichAlpacaError(lookupError instanceof Error ? lookupError : new Error(reason), cause));
     }
     if (existing && !TERMINAL_DEAD_ORDER_STATUSES.has(existing.status)) {
         log$6(`client_order_id ${clientOrderId} already submitted (status=${existing.status}); returning existing order ${existing.id} as idempotent success`, {
@@ -58480,7 +58887,7 @@ async function createOrder(client, params) {
             symbol,
             metadata: { params: submission },
         });
-        throw new Error(`Failed to create ${type} order for ${symbol}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to create ${type} order for ${symbol}: ${errorMessage}`), error);
     }
 }
 /**
@@ -58509,7 +58916,7 @@ async function getOrder(client, orderId) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
         log$6(`Failed to fetch order ${orderId}: ${errorMessage}`, { type: "error" });
-        throw new Error(`Failed to fetch order ${orderId}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to fetch order ${orderId}: ${errorMessage}`), error);
     }
 }
 /**
@@ -58572,7 +58979,7 @@ async function getOrders(client, params = {}) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
         log$6(`Failed to fetch orders: ${errorMessage}`, { type: "error" });
-        throw new Error(`Failed to fetch orders: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to fetch orders: ${errorMessage}`), error);
     }
 }
 /**
@@ -58602,16 +59009,16 @@ async function cancelOrder(client, orderId) {
             log$6(`Order ${orderId} is not cancelable (may already be filled or canceled)`, {
                 type: "warn",
             });
-            throw new Error(`Order ${orderId} is not cancelable`);
+            throw enrichAlpacaError(new Error(`Order ${orderId} is not cancelable`), error);
         }
         if (errorMessage.includes("404") || errorMessage.includes("not found")) {
             log$6(`Order ${orderId} not found`, { type: "error" });
-            throw new Error(`Order ${orderId} not found`);
+            throw enrichAlpacaError(new Error(`Order ${orderId} not found`), error);
         }
         log$6(`Failed to cancel order ${orderId}: ${errorMessage}`, {
             type: "error",
         });
-        throw new Error(`Failed to cancel order ${orderId}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to cancel order ${orderId}: ${errorMessage}`), error);
     }
 }
 /**
@@ -58654,7 +59061,7 @@ async function cancelAllOrders(client) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
         log$6(`Failed to cancel all orders: ${errorMessage}`, { type: "error" });
-        throw new Error(`Failed to cancel all orders: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to cancel all orders: ${errorMessage}`), error);
     }
 }
 /**
@@ -58712,16 +59119,16 @@ async function replaceOrder(client, orderId, params) {
             log$6(`Order ${orderId} cannot be replaced (may already be filled)`, {
                 type: "error",
             });
-            throw new Error(`Order ${orderId} cannot be replaced: order may already be filled or canceled`);
+            throw enrichAlpacaError(new Error(`Order ${orderId} cannot be replaced: order may already be filled or canceled`), error);
         }
         if (errorMessage.includes("404")) {
             log$6(`Order ${orderId} not found`, { type: "error" });
-            throw new Error(`Order ${orderId} not found`);
+            throw enrichAlpacaError(new Error(`Order ${orderId} not found`), error);
         }
         log$6(`Failed to replace order ${orderId}: ${errorMessage}`, {
             type: "error",
         });
-        throw new Error(`Failed to replace order ${orderId}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to replace order ${orderId}: ${errorMessage}`), error);
     }
 }
 /**
@@ -58810,7 +59217,7 @@ async function getOrderByClientId(client, clientOrderId) {
         log$6(`Failed to fetch order by client_order_id ${clientOrderId}: ${errorMessage}`, {
             type: "error",
         });
-        throw new Error(`Failed to fetch order by client_order_id ${clientOrderId}: ${errorMessage}`);
+        throw enrichAlpacaError(new Error(`Failed to fetch order by client_order_id ${clientOrderId}: ${errorMessage}`), error);
     }
 }
 
@@ -71770,8 +72177,10 @@ exports.createTimeoutSignal = createTimeoutSignal;
 exports.createTrailingStop = createTrailingStop;
 exports.createVerticalSpread = createVerticalSpread$1;
 exports.createVerticalSpreadAdvanced = createVerticalSpread;
+exports.enrichAlpacaError = enrichAlpacaError;
 exports.entryWithPercentStopLoss = entryWithPercentStopLoss;
 exports.exerciseOption = exerciseOption;
+exports.extractAlpacaBrokerError = extractAlpacaBrokerError;
 exports.extractGreeks = extractGreeks;
 exports.filterByExpiration = filterByExpiration;
 exports.filterByStrike = filterByStrike;
@@ -71789,6 +72198,8 @@ exports.getAccountDetails = getAccountDetails;
 exports.getAccountSummary = getAccountSummary;
 exports.getAgentPoolStatus = getAgentPoolStatus;
 exports.getAllOrders = getAllOrders;
+exports.getAlpacaBrokerErrorCode = getAlpacaBrokerErrorCode;
+exports.getAlpacaBrokerErrorDetail = getAlpacaBrokerErrorDetail;
 exports.getAlpacaCalendar = getAlpacaCalendar;
 exports.getAlpacaClock = getAlpacaClock;
 exports.getAverageDailyVolume = getAverageDailyVolume;