@adaptic/utils 0.1.46 → 0.1.48

package/dist/index.cjs

@@ -17328,6 +17328,198 @@ var index = /*#__PURE__*/Object.freeze({
     getUtilsTunedTradingPolicy: getUtilsTunedTradingPolicy
 });
 
+/**
+ * API credential validation utilities
+ * Provides fast, synchronous validation of API credentials before making requests
+ */
+/**
+ * Validates Alpaca API credentials
+ * @param auth - Authentication object containing API key and secret
+ * @param options - Validation options
+ * @param options.throwOnMissing - If false, missing credentials will log a warning instead of throwing (default: true)
+ * @throws {Error} If credentials are invalid (when throwOnMissing is true)
+ * @returns {boolean} True if credentials are valid, false if missing (when throwOnMissing is false)
+ */
+function validateAlpacaCredentials(auth, options = { throwOnMissing: true }) {
+    const { throwOnMissing = true } = options;
+    // Check for missing or empty API key
+    if (!auth.apiKey ||
+        typeof auth.apiKey !== "string" ||
+        auth.apiKey.trim().length === 0) {
+        if (throwOnMissing) {
+            throw new Error("Invalid Alpaca API key: must be a non-empty string");
+        }
+        console.warn("[AlpacaAPI] API key not configured. Market data features will be unavailable.");
+        return false;
+    }
+    // Check for missing or empty API secret
+    if (!auth.apiSecret ||
+        typeof auth.apiSecret !== "string" ||
+        auth.apiSecret.trim().length === 0) {
+        if (throwOnMissing) {
+            throw new Error("Invalid Alpaca API secret: must be a non-empty string");
+        }
+        console.warn("[AlpacaAPI] API secret not configured. Market data features will be unavailable.");
+        return false;
+    }
+    // Alpaca keys are typically 20+ characters
+    if (auth.apiKey.length < 10) {
+        if (throwOnMissing) {
+            throw new Error("Alpaca API key appears to be too short");
+        }
+        console.warn("[AlpacaAPI] API key appears to be too short.");
+        return false;
+    }
+    return true;
+}
+/**
+ * Validates Massive API key
+ * @param apiKey - Massive API key
+ * @throws {Error} If API key is invalid or missing
+ */
+function validateMassiveApiKey(apiKey) {
+    if (!apiKey || typeof apiKey !== "string" || apiKey.trim().length === 0) {
+        throw new Error("Invalid Massive API key: must be a non-empty string");
+    }
+}
+/**
+ * Validates Alpha Vantage API key
+ * @param apiKey - Alpha Vantage API key
+ * @throws {Error} If API key is invalid or missing
+ */
+function validateAlphaVantageApiKey(apiKey) {
+    if (!apiKey || typeof apiKey !== "string" || apiKey.trim().length === 0) {
+        throw new Error("Invalid Alpha Vantage API key: must be a non-empty string");
+    }
+}
+
+/**
+ * HTTP connection pooling and keep-alive configuration.
+ *
+ * Node.js (>=20) uses undici as its built-in fetch implementation, which
+ * automatically maintains an internal connection pool with keep-alive enabled
+ * by default. This module provides:
+ *
+ * 1. Explicit documentation of the connection pooling behavior
+ * 2. A configured HTTP Agent for use with node:http/node:https if needed
+ * 3. Verification utilities to confirm keep-alive is active
+ *
+ * ## Connection Pooling Behavior
+ *
+ * **Native fetch (undici):** The global `fetch()` used throughout this package
+ * uses Node.js built-in undici which maintains persistent connections by default.
+ * Connections are kept alive and reused across requests to the same origin.
+ * No additional configuration is needed for fetch-based API calls.
+ *
+ * **Alpaca SDK (@alpacahq/alpaca-trade-api):** The SDK uses its own internal
+ * HTTP client with connection reuse. The SDK is configured through `AlpacaClient`
+ * in `src/alpaca/client.ts` via the `createAlpacaClient()` factory which caches
+ * client instances by API key + account type.
+ *
+ * **WebSocket connections:** Trading API and market data WebSocket connections
+ * are long-lived persistent connections managed by `AlpacaTradingAPI` and
+ * `AlpacaMarketDataAPI` respectively.
+ *
+ * ## API Client Summary
+ *
+ * | API Client | Transport | Keep-Alive | Connection Reuse |
+ * |------------|-----------|------------|------------------|
+ * | Alpaca Trading (direct) | fetch() | Built-in | Undici pool |
+ * | Alpaca Market Data | fetch() | Built-in | Undici pool |
+ * | Alpaca SDK | internal | Built-in | SDK managed |
+ * | Massive.com | fetch() via fetchWithRetry | Built-in | Undici pool |
+ * | Alpha Vantage | fetch() | Built-in | Undici pool |
+ * | WebSocket (Trading) | ws | Persistent | Long-lived |
+ * | WebSocket (Market Data) | ws | Persistent | Long-lived |
+ */
+/**
+ * Default keep-alive configuration values.
+ * These are applied when creating explicit HTTP agents for non-fetch use cases.
+ */
+const KEEP_ALIVE_DEFAULTS = {
+    /** Enable keep-alive connections */
+    keepAlive: true,
+    /** Initial delay before sending keep-alive probes (in milliseconds) */
+    keepAliveMsecs: 60000,
+    /** Maximum number of sockets per host */
+    maxSockets: 50,
+    /** Maximum total number of sockets */
+    maxTotalSockets: 256,
+    /** Maximum number of free (idle) sockets per host */
+    maxFreeSockets: 10,
+    /** Socket timeout for idle connections (in milliseconds) */
+    timeout: 60000,
+};
+/**
+ * Pre-configured HTTP agent with keep-alive enabled.
+ * Use this when making requests through node:http (not needed for fetch).
+ */
+const httpAgent = new require$$2.Agent({
+    keepAlive: KEEP_ALIVE_DEFAULTS.keepAlive,
+    keepAliveMsecs: KEEP_ALIVE_DEFAULTS.keepAliveMsecs,
+    maxSockets: KEEP_ALIVE_DEFAULTS.maxSockets,
+    maxTotalSockets: KEEP_ALIVE_DEFAULTS.maxTotalSockets,
+    maxFreeSockets: KEEP_ALIVE_DEFAULTS.maxFreeSockets,
+    timeout: KEEP_ALIVE_DEFAULTS.timeout,
+});
+/**
+ * Pre-configured HTTPS agent with keep-alive enabled.
+ * Use this when making requests through node:https (not needed for fetch).
+ */
+const httpsAgent = new require$$1$1.Agent({
+    keepAlive: KEEP_ALIVE_DEFAULTS.keepAlive,
+    keepAliveMsecs: KEEP_ALIVE_DEFAULTS.keepAliveMsecs,
+    maxSockets: KEEP_ALIVE_DEFAULTS.maxSockets,
+    maxTotalSockets: KEEP_ALIVE_DEFAULTS.maxTotalSockets,
+    maxFreeSockets: KEEP_ALIVE_DEFAULTS.maxFreeSockets,
+    timeout: KEEP_ALIVE_DEFAULTS.timeout,
+});
+/**
+ * Get the connection pool status for an HTTP/HTTPS agent.
+ * Useful for monitoring and debugging connection reuse.
+ *
+ * @param agent - The HTTP/HTTPS agent to inspect
+ * @param name - A human-readable name for the agent
+ * @returns Connection pool status information
+ */
+function getAgentPoolStatus(agent, name = "default") {
+    const sockets = agent.sockets || {};
+    const freeSockets = agent.freeSockets || {};
+    const requests = agent.requests || {};
+    const activeSockets = Object.values(sockets).reduce((sum, arr) => sum + (arr ? arr.length : 0), 0);
+    const freeSocketCount = Object.values(freeSockets).reduce((sum, arr) => sum + (arr ? arr.length : 0), 0);
+    const pendingRequests = Object.values(requests).reduce((sum, arr) => sum + (arr ? arr.length : 0), 0);
+    return {
+        name,
+        keepAlive: agent.keepAlive ?? false,
+        activeSockets,
+        freeSockets: freeSocketCount,
+        pendingRequests,
+        maxSockets: agent.maxSockets,
+        maxFreeSockets: agent.maxFreeSockets,
+    };
+}
+/**
+ * Verifies that keep-alive is properly configured for the Node.js built-in fetch.
+ * Node.js >= 20 uses undici internally, which has keep-alive enabled by default.
+ *
+ * @returns Object indicating whether keep-alive is expected to be active
+ */
+function verifyFetchKeepAlive() {
+    const nodeVersion = process.version;
+    const majorVersion = parseInt(nodeVersion.slice(1).split(".")[0], 10);
+    // Node.js >= 18 has built-in fetch via undici
+    // Node.js >= 20 has mature undici with connection pooling
+    const undiciBuiltIn = majorVersion >= 18;
+    const keepAliveExpected = majorVersion >= 18;
+    return {
+        supported: true,
+        nodeVersion,
+        undiciBuiltIn,
+        keepAliveExpected,
+    };
+}
+
 // Export factory functions for easier instantiation
 const createAlpacaTradingAPI = (credentials) => {
     return new AlpacaTradingAPI(credentials);
@@ -17485,6 +17677,7 @@ exports.AlpacaTradingAPI = AlpacaTradingAPI;
 exports.AssetAllocationEngine = AssetAllocationEngine;
 exports.DEFAULT_CACHE_OPTIONS = DEFAULT_CACHE_OPTIONS;
 exports.DEFAULT_TRADING_POLICY_UTILS_TUNED = DEFAULT_TRADING_POLICY_UTILS_TUNED;
+exports.KEEP_ALIVE_DEFAULTS = KEEP_ALIVE_DEFAULTS;
 exports.StampedeProtectedCache = StampedeProtectedCache;
 exports.adaptic = adaptic;
 exports.adptc = adptc;
@@ -17492,7 +17685,14 @@ exports.createAlpacaMarketDataAPI = createAlpacaMarketDataAPI;
 exports.createAlpacaTradingAPI = createAlpacaTradingAPI;
 exports.createStampedeProtectedCache = createStampedeProtectedCache;
 exports.generateOptimalAllocation = generateOptimalAllocation;
+exports.getAgentPoolStatus = getAgentPoolStatus;
 exports.getDefaultRiskProfile = getDefaultRiskProfile;
 exports.getUtilsTunedTradingPolicy = getUtilsTunedTradingPolicy;
+exports.httpAgent = httpAgent;
+exports.httpsAgent = httpsAgent;
 exports.tradingPolicy = index;
+exports.validateAlpacaCredentials = validateAlpacaCredentials;
+exports.validateAlphaVantageApiKey = validateAlphaVantageApiKey;
+exports.validateMassiveApiKey = validateMassiveApiKey;
+exports.verifyFetchKeepAlive = verifyFetchKeepAlive;
 //# sourceMappingURL=index.cjs.map