@adaptic/utils 0.0.1001 → 0.0.1002

package/dist/index.cjs

@@ -2359,6 +2359,23 @@ class NetworkError extends AdapticUtilsError {
         this.service = service;
     }
 }
+/**
+ * Unsupported brokerage provider errors
+ * Thrown when a broker operation is requested for a provider that has no
+ * implemented integration (e.g. IBKR or COINBASE before their adapters land,
+ * or an unrecognised provider string from an untyped caller).
+ * Never retryable — the caller must route to a supported provider.
+ */
+class UnsupportedBrokerError extends AdapticUtilsError {
+    provider;
+    constructor(
+    /** The provider that was requested but is not supported. */
+    provider, cause) {
+        super(`Brokerage provider "${provider}" is not supported. Supported providers: ALPACA`, "UNSUPPORTED_BROKER", "broker", false, // Unsupported providers are never retryable
+        cause);
+        this.provider = provider;
+    }
+}
 /**
  * Data parsing and format errors
  * Used when API responses cannot be parsed or are in unexpected format
@@ -5773,9 +5790,18 @@ class AlpacaTradingAPI {
  *
  * @param auth - The authentication details for Alpaca
  * @returns Validated authentication credentials
+ * @throws UnsupportedBrokerError if `auth.provider` is set to a non-ALPACA provider
  * @throws Error if authentication details are missing or invalid
  */
 async function validateAuth(auth) {
+    // Multi-broker guard (SP2): this seam only resolves Alpaca credentials.
+    // `auth.provider` is typed as "ALPACA" on AlpacaAuth, but untyped callers
+    // (or future BrokerAuth adapters) may pass other providers at runtime —
+    // fail fast with a typed error instead of silently hitting Alpaca hosts.
+    const requestedProvider = auth.provider;
+    if (requestedProvider !== undefined && requestedProvider !== "ALPACA") {
+        throw new UnsupportedBrokerError(requestedProvider);
+    }
     const inlineKey = auth.alpacaApiKey && auth.alpacaApiKey.trim().length > 0
         ? auth.alpacaApiKey
         : undefined;
@@ -5797,26 +5823,54 @@ async function validateAuth(auth) {
         };
     }
     if (auth.adapticAccountId) {
-        const client = await getSharedApolloClient();
-        const alpacaAccount = (await adaptic$1.alpacaAccount.get({
-            id: auth.adapticAccountId,
-        }, client));
-        if (!alpacaAccount || !alpacaAccount.APIKey || !alpacaAccount.APISecret) {
-            throw new Error("Alpaca account not found or incomplete");
-        }
-        validateAlpacaCredentials({
-            apiKey: alpacaAccount.APIKey,
-            apiSecret: alpacaAccount.APISecret,
-            isPaper: alpacaAccount.type === "PAPER",
-        });
-        return {
-            APIKey: alpacaAccount.APIKey,
-            APISecret: alpacaAccount.APISecret,
-            type: alpacaAccount.type,
-        };
+        return resolveBrokerCredentials(auth.adapticAccountId);
     }
     throw new Error("Either adapticAccountId or both alpacaApiKey and alpacaApiSecret must be provided");
 }
+/**
+ * Resolves broker credentials for a backend brokerage-account id.
+ *
+ * This is the SINGLE backend-coupled credential lookup in this package —
+ * every account-id-based credential resolution must flow through here so
+ * that backend model changes touch exactly one function.
+ *
+ * SP2 transition note: today the id is an `AlpacaAccount.id` resolved via
+ * `adaptic.alpacaAccount.get`. When backend-legacy publishes the
+ * `BrokerageAccount` model (backfilled with `id = AlpacaAccount.id`, so the
+ * id space is identical), the switch to `adaptic.brokerageAccount.get`
+ * happens INSIDE this function only, following the sequencing rule in
+ * CLAUDE.md ("Multi-Broker Sequencing Rule"): backend-legacy publishes →
+ * utils bumps the dependency and switches this helper → utils publishes →
+ * engine bumps its pin. Do not reference `brokerageAccount` anywhere in
+ * this package before the pinned backend-legacy version exports it.
+ *
+ * The lookup is a no-cache GraphQL round trip to backend-legacy; callers
+ * holding inline credentials should never reach it (see `validateAuth`
+ * precedence).
+ *
+ * @param brokerageAccountId - Backend brokerage-account id (currently the AlpacaAccount id)
+ * @returns Validated authentication credentials
+ * @throws Error if the account is not found or its credentials are incomplete
+ */
+async function resolveBrokerCredentials(brokerageAccountId) {
+    const client = await getSharedApolloClient();
+    const alpacaAccount = (await adaptic$1.alpacaAccount.get({
+        id: brokerageAccountId,
+    }, client));
+    if (!alpacaAccount || !alpacaAccount.APIKey || !alpacaAccount.APISecret) {
+        throw new Error("Alpaca account not found or incomplete");
+    }
+    validateAlpacaCredentials({
+        apiKey: alpacaAccount.APIKey,
+        apiSecret: alpacaAccount.APISecret,
+        isPaper: alpacaAccount.type === "PAPER",
+    });
+    return {
+        APIKey: alpacaAccount.APIKey,
+        APISecret: alpacaAccount.APISecret,
+        type: alpacaAccount.type,
+    };
+}
 
 /**
  * Legacy Alpaca Utility Functions
@@ -7946,6 +8000,7 @@ var index$1 = /*#__PURE__*/Object.freeze({
     getOrders: getOrders$1,
     makeRequest: makeRequest,
     replaceOrder: replaceOrder$1,
+    resolveBrokerCredentials: resolveBrokerCredentials,
     roundPriceForAlpaca: roundPriceForAlpaca$5,
     updateConfiguration: updateConfiguration,
     validateAuth: validateAuth
@@ -11168,9 +11223,16 @@ function calculateBetaFromReturns(portfolioReturns, benchmarkReturns) {
     const denom = n > 1 ? n - 1 : 1;
     covariance /= denom;
     variance /= denom;
-    // Handle zero variance
-    if (variance === 0) {
-        getLogger().warn("Benchmark variance is zero. Setting beta to 0.");
+    // Handle zero (or numerically-degenerate) variance. A constant benchmark
+    // series can still produce a tiny nonzero variance because the computed
+    // mean differs from the constant by an ulp; dividing covariance by that
+    // rounding noise yields a meaningless beta. Treat any variance at or
+    // below the summation noise floor — (n * eps * |mean|)^2, the square of
+    // the worst-case naive-summation error — as zero. When the mean is
+    // exactly 0 this reduces to the exact zero check.
+    const varianceNoiseFloor = (n * Number.EPSILON * Math.abs(averageBenchmarkReturn)) ** 2;
+    if (variance <= varianceNoiseFloor) {
+        getLogger().warn("Benchmark variance is zero or below the floating-point noise floor. Setting beta to 0.");
         return {
             beta: 0,
             covariance,
@@ -12349,8 +12411,33 @@ const timeDiffString = (milliseconds) => {
     return parts.join(", ");
 };
 
+/**
+ * Multi-broker foundation types
+ *
+ * Provider-agnostic brokerage types for the org → fund → brokerageAccount →
+ * broker alignment (SP2). These are strictly ADDITIVE: the existing
+ * Alpaca-specific types (`AlpacaAuth`, `AlpacaCredentials`,
+ * `AlpacaClientConfig`) remain the canonical shapes consumed by the engine
+ * and are unchanged. New provider-aware call sites should prefer these
+ * types; only ALPACA is implemented today — IBKR and COINBASE arms are
+ * typed placeholders that resolve to `UnsupportedBrokerError` at runtime.
+ *
+ * @module @adaptic/utils/types/broker-types
+ */
+/**
+ * Type guard narrowing {@link BrokerCredentials} to the implemented
+ * ALPACA arm.
+ *
+ * @param credentials - Any broker credentials union member
+ * @returns True when the credentials belong to the ALPACA provider
+ */
+function isAlpacaBrokerCredentials(credentials) {
+    return credentials.provider === "ALPACA";
+}
+
 var Types = /*#__PURE__*/Object.freeze({
-    __proto__: null
+    __proto__: null,
+    isAlpacaBrokerCredentials: isAlpacaBrokerCredentials
 });
 
 /**
@@ -50663,12 +50750,16 @@ class AlpacaClient {
 }
 // Client cache for connection pooling
 const clientCache = new Map();
+// Provider discriminant for cache-key scoping (multi-broker SP2 seam):
+// keeps Alpaca pool entries disjoint from future providers that might
+// reuse an identical apiKey string.
+const ALPACA_PROVIDER = "ALPACA";
 /**
  * Create or get a cached Alpaca client
- * Uses apiKey as cache key for connection pooling
+ * Uses provider + apiKey + accountType as cache key for connection pooling
  */
 function createAlpacaClient(config) {
-    const cacheKey = `${config.apiKey}-${config.accountType}`;
+    const cacheKey = `${ALPACA_PROVIDER}-${config.apiKey}-${config.accountType}`;
     if (clientCache.has(cacheKey)) {
         log$k(`Returning cached client for ${config.accountType}`, { type: "debug" });
         return clientCache.get(cacheKey);
@@ -68788,6 +68879,49 @@ function verifyFetchKeepAlive() {
     };
 }
 
+/**
+ * Broker Client Factory
+ *
+ * Provider-agnostic entry point for broker trading clients (SP2 multi-broker
+ * seam). Strictly ADDITIVE: `createAlpacaClient`, `createAlpacaTradingAPI`,
+ * and `createAlpacaMarketDataAPI` remain the canonical Alpaca factories and
+ * are unchanged. Only ALPACA is implemented — all other providers throw a
+ * typed {@link UnsupportedBrokerError}.
+ *
+ * @module @adaptic/utils/broker
+ */
+/**
+ * Create (or reuse from cache) a broker trading client for the given
+ * credentials.
+ *
+ * ALPACA delegates to `createAlpacaClient`, whose connection-pool cache key
+ * is provider-scoped (`ALPACA-<apiKey>-<accountType>`), so a future
+ * provider reusing an identical apiKey string can never collide with an
+ * Alpaca client. All other providers — including unknown provider strings
+ * from untyped callers — throw {@link UnsupportedBrokerError}.
+ *
+ * @param credentials - Discriminated broker credentials union
+ * @returns A provider-appropriate {@link BrokerTradingClient}
+ * @throws UnsupportedBrokerError for any provider other than ALPACA
+ */
+function createBrokerClient(credentials) {
+    switch (credentials.provider) {
+        case "ALPACA":
+            return createAlpacaClient({
+                apiKey: credentials.apiKey,
+                apiSecret: credentials.apiSecret,
+                accountType: credentials.type,
+            });
+        case "IBKR":
+        case "COINBASE":
+            throw new UnsupportedBrokerError(credentials.provider);
+    }
+    // Unreachable for typed callers (the switch above is exhaustive), but
+    // untyped runtime callers may pass an unrecognised provider string —
+    // fail fast with the same typed error rather than undefined behaviour.
+    throw new UnsupportedBrokerError(String(credentials.provider));
+}
+
 /**
  * Mirror enums for the trading policy preference system.
  * These enums are used by both the trading engine and the frontend app
@@ -69937,6 +70071,7 @@ exports.TrailingStopValidationError = TrailingStopValidationError;
 exports.USDC_PAIRS = USDC_PAIRS;
 exports.USDT_PAIRS = USDT_PAIRS;
 exports.USD_PAIRS = USD_PAIRS;
+exports.UnsupportedBrokerError = UnsupportedBrokerError;
 exports.ValidationError = ValidationError;
 exports.ValidationResponseError = ValidationResponseError;
 exports.WEBSOCKET_STREAMS = WEBSOCKET_STREAMS;
@@ -69975,6 +70110,7 @@ exports.createAlpacaClient = createAlpacaClient;
 exports.createAlpacaMarketDataAPI = createAlpacaMarketDataAPI;
 exports.createAlpacaTradingAPI = createAlpacaTradingAPI;
 exports.createBracketOrder = createBracketOrder;
+exports.createBrokerClient = createBrokerClient;
 exports.createButterflySpread = createButterflySpread;
 exports.createClientFromEnv = createClientFromEnv;
 exports.createCoveredCall = createCoveredCall;
@@ -70105,6 +70241,7 @@ exports.hasStockLiquidity = hasGoodLiquidity$1;
 exports.hasSufficientVolume = hasSufficientVolume;
 exports.httpAgent = httpAgent;
 exports.httpsAgent = httpsAgent;
+exports.isAlpacaBrokerCredentials = isAlpacaBrokerCredentials;
 exports.isContractTradable = isContractTradable;
 exports.isCryptoPair = isCryptoPair;
 exports.isExpiringWithin = isExpiringWithin;