@adaptic/utils 0.1.49 → 0.1.50

package/dist/types/massive.d.ts

@@ -0,0 +1,167 @@
+/**********************************************************************************
+ * Massive.com calls
+ **********************************************************************************/
+import { MassiveDailyOpenClose, MassiveGroupedDailyResponse, MassivePriceData, MassiveQuote, MassiveResult, MassiveSpreadInfo, MassiveTickerInfo, MassiveTradesResponse } from "./types";
+/**
+ * Fetches general information about a stock ticker.
+ * @param {string} symbol - The stock ticker symbol to fetch information for.
+ * @param {Object} [options] - Optional parameters.
+ * @param {string} [options.apiKey] - The API key to use for the request.
+ * @returns {Promise<MassiveTickerInfo | null>} The ticker information or null if not found.
+ */
+export declare const fetchTickerInfo: (symbol: string, options?: {
+    apiKey?: string;
+}) => Promise<MassiveTickerInfo | null>;
+/**
+ * Fetches the last trade for a given stock ticker.
+ * @param {string} symbol - The stock ticker symbol to fetch the last trade for.
+ * @param {Object} [options] - Optional parameters.
+ * @param {string} [options.apiKey] - The API key to use for the request.
+ * @returns {Promise<MassiveQuote>} The last trade information.
+ */
+export declare const fetchLastTrade: (symbol: string, options?: {
+    apiKey?: string;
+}) => Promise<MassiveQuote>;
+/**
+ * Fetches the latest NBBO quote for a given stock ticker using the Massive v3 API.
+ * Returns processed spread information including bid, ask, spread, and mid price.
+ *
+ * @param symbol - The stock ticker symbol.
+ * @param options - Optional parameters including API key override.
+ * @returns Processed quote data with spread metrics.
+ */
+export declare const fetchLastQuote: (symbol: string, options?: {
+    apiKey?: string;
+}) => Promise<MassiveSpreadInfo>;
+/**
+ * Fetches price data for a given stock ticker.
+ * @param {Object} params - The parameters for fetching price data.
+ * @param {string} params.ticker - The stock ticker symbol.
+ * @param {number} params.start - The start timestamp for fetching price data.
+ * @param {number} [params.end] - The end timestamp for fetching price data.
+ * @param {number} params.multiplier - The multiplier for the price data.
+ * @param {string} params.timespan - The timespan for the price data.
+ * @param {number} [params.limit] - The maximum number of price data points to fetch.
+ * @param {Object} [options] - Optional parameters.
+ * @param {string} [options.apiKey] - The API key to use for the request.
+ * @returns {Promise<MassivePriceData[]>} The fetched price data.
+ */
+export declare const fetchPrices: (params: {
+    ticker: string;
+    start: number;
+    end?: number;
+    multiplier: number;
+    timespan: string;
+    limit?: number;
+    adjusted?: boolean;
+}, options?: {
+    apiKey?: string;
+}) => Promise<MassivePriceData[]>;
+/**
+ * Variant of {@link fetchPrices} that returns a discriminated
+ * {@link MassiveResult} wrapper, surfacing the upstream feed status (`OK` vs
+ * `DELAYED`) at the result level. This is the preferred entry point for new
+ * code that needs to gate latency-sensitive decisions on freshness.
+ *
+ * The underlying bars are still stamped with `_freshness` so consumers that
+ * already destructure the array can branch per-bar; the wrapper simply
+ * promotes that information to the top of the result for clarity.
+ *
+ * DE-006: closes the loop for callers that need to know when the Massive feed
+ * is on a delayed plan (e.g. free tier, market-data outage downgrade).
+ *
+ * @param params - Same parameters accepted by {@link fetchPrices}.
+ * @param options - Same options accepted by {@link fetchPrices}.
+ * @returns A {@link MassiveResult} carrying the bar array plus freshness
+ *          metadata.
+ */
+export declare const fetchPricesWithFreshness: (params: {
+    ticker: string;
+    start: number;
+    end?: number;
+    multiplier: number;
+    timespan: string;
+    limit?: number;
+    adjusted?: boolean;
+}, options?: {
+    apiKey?: string;
+}) => Promise<MassiveResult<MassivePriceData[]>>;
+/**
+ * Analyzes the price data for a given stock.
+ * @param {MassivePriceData[]} priceData - The price data to analyze.
+ * @returns {string} The analysis report.
+ */
+export declare function analyseMassivePriceData(priceData: MassivePriceData[]): string;
+/**
+ * Fetches grouped daily price data for a specific date.
+ * @param {string} date - The date to fetch grouped daily data for.
+ * @param {Object} [options] - Optional parameters.
+ * @param {string} [options.apiKey] - The API key to use for the request.
+ * @param {boolean} [options.adjusted] - Whether to adjust the data.
+ * @param {boolean} [options.includeOTC] - Whether to include OTC data.
+ * @returns {Promise<MassiveGroupedDailyResponse>} The grouped daily response.
+ */
+export declare const fetchGroupedDaily: (date: string, options?: {
+    apiKey?: string;
+    adjusted?: boolean;
+    includeOTC?: boolean;
+}) => Promise<MassiveGroupedDailyResponse>;
+/**
+ * Formats the price data into a readable string.
+ * @param {MassivePriceData[]} priceData - The price data to format.
+ * @returns {string} The formatted price data.
+ */
+export declare function formatPriceData(priceData: MassivePriceData[]): string;
+export declare const fetchDailyOpenClose: (
+/**
+ * Fetches the daily open and close data for a given stock ticker.
+ * @param {string} symbol - The stock ticker symbol to fetch data for.
+ * @param {Date} [date=new Date()] - The date to fetch data for.
+ * @param {Object} [options] - Optional parameters.
+ * @param {string} [options.apiKey] - The API key to use for the request.
+ * @param {boolean} [options.adjusted] - Whether to adjust the data.
+ * @returns {Promise<MassiveDailyOpenClose>} The daily open and close data.
+ */
+symbol: string, date?: Date, options?: {
+    apiKey?: string;
+    adjusted?: boolean;
+}) => Promise<MassiveDailyOpenClose>;
+/**
+ * Gets the previous close price for a given stock ticker.
+ * @param {string} symbol - The stock ticker symbol to fetch the previous close for.
+ * @param {Date} [referenceDate] - The reference date to use for fetching the previous close.
+ * @returns {Promise<{ close: number; date: Date }>} The previous close price and date.
+ */
+export declare function getPreviousClose(symbol: string, referenceDate?: Date, options?: {
+    apiKey?: string;
+}): Promise<{
+    close: number;
+    date: Date;
+}>;
+/**
+ * Fetches trade data for a given stock ticker.
+ * @param {string} symbol - The stock ticker symbol to fetch trades for.
+ * @param {Object} [options] - Optional parameters.
+ * @param {string} [options.apiKey] - The API key to use for the request.
+ * @param {string | number} [options.timestamp] - The timestamp for fetching trades.
+ * @param {string | number} [options.timestampgt] - Greater than timestamp for fetching trades.
+ * @param {string | number} [options.timestampgte] - Greater than or equal to timestamp for fetching trades.
+ * @param {string | number} [options.timestamplt] - Less than timestamp for fetching trades.
+ * @param {string | number} [options.timestamplte] - Less than or equal to timestamp for fetching trades.
+ * @param {'asc' | 'desc'} [options.order] - The order of the trades.
+ * @param {number} [options.limit] - The maximum number of trades to fetch.
+ * @param {string} [options.sort] - The sort order for the trades.
+ * @returns {Promise<MassiveTradesResponse>} The fetched trades response.
+ */
+export declare const fetchTrades: (symbol: string, options?: {
+    apiKey?: string;
+    timestamp?: string | number;
+    timestampgt?: string | number;
+    timestampgte?: string | number;
+    timestamplt?: string | number;
+    timestamplte?: string | number;
+    order?: "asc" | "desc";
+    limit?: number;
+    sort?: string;
+}) => Promise<MassiveTradesResponse>;
+//# sourceMappingURL=massive.d.ts.map

package/dist/types/massive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"massive.d.ts","sourceRoot":"","sources":["../../src/massive.ts"],"names":[],"mappings":"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"}

package/dist/types/rate-limiter.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Token bucket rate limiter for external API integrations
+ *
+ * Implements client-side rate limiting to prevent exceeding API quotas
+ * and ensure fair usage of external services like Alpaca, Massive, and AlphaVantage.
+ *
+ * @example
+ * ```typescript
+ * import { rateLimiters } from '@adaptic/utils';
+ *
+ * // Before making an API call
+ * await rateLimiters.alpaca.acquire();
+ * const result = await makeAlpacaApiCall();
+ * ```
+ */
+import { RateLimitError } from "./errors";
+export { RateLimitError };
+/**
+ * Configuration for a rate limiter instance
+ */
+export interface RateLimiterConfig {
+    /** Maximum number of tokens (requests) that can be accumulated */
+    maxTokens: number;
+    /** Rate at which tokens are refilled (tokens per second) */
+    refillRate: number;
+    /** Human-readable label for logging and error messages */
+    label: string;
+    /** Maximum time to wait for a token before timing out (milliseconds) */
+    timeoutMs?: number;
+}
+/**
+ * Token bucket rate limiter implementation
+ *
+ * Uses the token bucket algorithm to control the rate of API requests.
+ * Tokens are consumed on each request and refilled at a constant rate.
+ * Requests that exceed the available tokens are queued and processed
+ * when tokens become available.
+ */
+export declare class TokenBucketRateLimiter {
+    private readonly config;
+    private tokens;
+    private lastRefill;
+    private queue;
+    private readonly timeoutMs;
+    private processingQueue;
+    /**
+     * Creates a new rate limiter instance
+     *
+     * @param config - Rate limiter configuration
+     *
+     * @example
+     * ```typescript
+     * // Alpaca: 200 requests per minute
+     * const alpacaLimiter = new TokenBucketRateLimiter({
+     *   maxTokens: 200,
+     *   refillRate: 200 / 60, // ~3.33 per second
+     *   label: 'alpaca',
+     *   timeoutMs: 60000
+     * });
+     * ```
+     */
+    constructor(config: RateLimiterConfig);
+    /**
+     * Acquires a token for making an API request
+     *
+     * If a token is available, it is consumed immediately.
+     * If no tokens are available, the request is queued and will resolve
+     * when a token becomes available or reject if it times out.
+     *
+     * @throws {RateLimitError} If the request times out waiting for a token
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await limiter.acquire();
+     *   // Make API call
+     * } catch (error) {
+     *   if (error instanceof RateLimitError) {
+     *     // Handle rate limit timeout
+     *   }
+     * }
+     * ```
+     */
+    acquire(): Promise<void>;
+    /**
+     * Refills tokens based on elapsed time and processes queued requests
+     *
+     * Tokens are refilled at the configured rate up to the maximum capacity.
+     * If tokens are available after refilling, queued requests are processed.
+     */
+    private refill;
+    /**
+     * Processes queued requests when tokens are available
+     *
+     * Prevents concurrent queue processing to ensure FIFO order.
+     */
+    private processQueue;
+    /**
+     * Gets the current number of available tokens
+     *
+     * @returns Number of tokens currently available
+     */
+    getAvailableTokens(): number;
+    /**
+     * Gets the current queue length
+     *
+     * @returns Number of requests waiting for tokens
+     */
+    getQueueLength(): number;
+    /**
+     * Clears all queued requests and resets the token bucket
+     *
+     * All queued requests will be rejected with a RateLimitError.
+     * Useful for cleanup or when changing rate limit configurations.
+     */
+    reset(): void;
+}
+/**
+ * Pre-configured rate limiters for common external APIs
+ *
+ * These limiters are configured based on the documented rate limits
+ * for each service. Adjust the configurations if you have different
+ * tier access or if limits change.
+ *
+ * @example
+ * ```typescript
+ * import { rateLimiters } from '@adaptic/utils';
+ *
+ * // Use before making API calls
+ * await rateLimiters.alpaca.acquire();
+ * await rateLimiters.massive.acquire();
+ * await rateLimiters.alphaVantage.acquire();
+ * ```
+ */
+export declare const rateLimiters: {
+    /**
+     * Alpaca API rate limiter
+     *
+     * Configured for 1000 requests per minute (paid tier).
+     * The token bucket allows burst up to maxTokens, then refills at the steady rate.
+     * See: https://alpaca.markets/docs/api-references/trading-api/#rate-limit
+     */
+    alpaca: TokenBucketRateLimiter;
+    /**
+     * Massive.com API rate limiter
+     *
+     * Configured generously for paid unlimited tier. The bucket exists only as a
+     * safety net against runaway loops — the 1000 token burst and 500/sec refill
+     * should never be hit under normal operation. If the paid plan truly has no
+     * hard limit, this just prevents accidental self-DDoS.
+     */
+    massive: TokenBucketRateLimiter;
+    /**
+     * AlphaVantage API rate limiter
+     *
+     * Configured for 5 requests per minute (free tier).
+     * For premium tier (75/min), create a custom limiter:
+     *
+     * @example
+     * ```typescript
+     * const premiumAV = new TokenBucketRateLimiter({
+     *   maxTokens: 75,
+     *   refillRate: 75 / 60,
+     *   label: 'alphaVantage-premium',
+     *   timeoutMs: 60000,
+     * });
+     * ```
+     *
+     * See: https://www.alphavantage.co/premium/
+     */
+    alphaVantage: TokenBucketRateLimiter;
+};
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/types/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;;GAOG;AACH,qBAAa,sBAAsB;IAuBrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAtBnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,eAAe,CAAkB;IAEzC;;;;;;;;;;;;;;;OAeG;gBAC0B,MAAM,EAAE,iBAAiB;IAMtD;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD9B;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IAYd;;;;OAIG;IACH,OAAO,CAAC,YAAY;IA6BpB;;;;OAIG;IACH,kBAAkB,IAAI,MAAM;IAK5B;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;CAwBd;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY;IACvB;;;;;;OAMG;;IAQH;;;;;;;OAOG;;IAQH;;;;;;;;;;;;;;;;;OAiBG;;CAOJ,CAAC"}

package/dist/types/risk-free-rate.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Conservative fallback annual risk-free rate used when no live rate has been
+ * fetched yet AND the remote source is unreachable. Chosen to roughly match the
+ * longer-run (post-2000) average of the 3-month US Treasury bill yield.
+ *
+ * This is the rate of LAST resort. Callers that need a live number should
+ * prefer {@link getRiskFreeRate} (async) and only rely on
+ * {@link getCachedRiskFreeRateSync} for hot paths that cannot be made async.
+ */
+export declare const DEFAULT_RISK_FREE_RATE = 0.02;
+/**
+ * Provenance describing where a risk-free rate value came from.
+ *
+ * - `"live"`: Just fetched successfully from the Treasury Fiscal Data API.
+ * - `"cached"`: Returned from the in-process cache. May be from an earlier
+ *               successful fetch (the common case) OR from a stale cache that
+ *               survived a failed refresh attempt — callers that want to
+ *               distinguish these cases should compare `fetchedAt` against
+ *               {@link RISK_FREE_RATE_TTL_MS}.
+ * - `"default"`: The Treasury fetch failed AND no usable cached value was
+ *               available, so {@link DEFAULT_RISK_FREE_RATE} was returned.
+ *               Performance metrics computed against a `"default"` rate are
+ *               using a fictional 2% baseline and should be flagged in
+ *               downstream reporting.
+ *
+ * DE-029: previously the function returned only the numeric rate, so a fall
+ * back to the 2% default propagated through Sharpe/alpha/Sortino computations
+ * indistinguishable from a live observation. The provenance field closes that
+ * loop.
+ */
+export type RiskFreeRateSource = "live" | "cached" | "default";
+/**
+ * Result shape returned by the provenance-aware accessors.
+ *
+ * @see RiskFreeRateSource
+ */
+export interface RiskFreeRateResult {
+    /** Annualized decimal rate (e.g. 0.0452 for 4.52%). */
+    rate: number;
+    /** Where the rate value came from. See {@link RiskFreeRateSource}. */
+    source: RiskFreeRateSource;
+    /**
+     * Wall-clock time the rate was last sourced. For `"live"` this is the
+     * moment the fetch resolved. For `"cached"` this is the original fetch
+     * time. For `"default"` this is the time the fallback was selected.
+     */
+    fetchedAt: Date;
+}
+/**
+ * Cache TTL for the risk-free rate: 24 hours. Treasury yields update daily
+ * (auction + close), so refreshing more aggressively provides no useful signal
+ * and risks rate-limiting the public endpoint.
+ */
+export declare const RISK_FREE_RATE_TTL_MS: number;
+/**
+ * Clears the cached risk-free rate. Exported for tests and for callers that
+ * want to force a re-fetch (e.g., at the start of a backtest run with a
+ * different asOf date).
+ */
+export declare function resetRiskFreeRateCache(): void;
+/**
+ * Explicitly sets the cached risk-free rate. Useful for deterministic tests,
+ * backtests (where rf should be pinned to the asOf date), and environments
+ * where an upstream service already provides the rate.
+ *
+ * @param rate - Annualized decimal rate (e.g. 0.0452 for 4.52%).
+ */
+export declare function setRiskFreeRate(rate: number): void;
+/**
+ * Provenance-aware variant of {@link getRiskFreeRate} that returns the rate
+ * AND tells the caller where it came from. Use this in any code path that
+ * publishes performance metrics (Sharpe, alpha, Sortino) so downstream
+ * reports can flag computations made against a fictional fallback rate.
+ *
+ * Behavior is identical to {@link getRiskFreeRate} for the cache and
+ * deduplication semantics; only the return shape differs:
+ *
+ * - Fresh cache hit: `{ source: "cached", fetchedAt: <original fetch time> }`
+ * - Cold or stale cache + successful fetch: `{ source: "live", fetchedAt: <now> }`
+ * - Cold or stale cache + failed fetch but cached value present:
+ *   `{ source: "cached", fetchedAt: <original fetch time> }` — the stale
+ *   value is reused so existing alpha calculations keep working through a
+ *   transient outage. The provenance still says `cached`, not `live`.
+ * - Cold cache + failed fetch + no cached value:
+ *   `{ source: "default", fetchedAt: <now> }` — the 2% fallback is used. This
+ *   is the case downstream reports MUST flag, because Sharpe / alpha computed
+ *   against a 2% floor that was never observed in market data is a fiction.
+ *
+ * DE-029: closes the silent-failure loop where a first-fetch network failure
+ * propagated `DEFAULT_RISK_FREE_RATE` indistinguishable from a live
+ * observation.
+ *
+ * @returns The annualized risk-free rate plus its provenance.
+ */
+export declare function getRiskFreeRateWithProvenance(): Promise<RiskFreeRateResult>;
+/**
+ * Returns the current annualized risk-free rate (decimal, e.g. 0.0452 for
+ * 4.52%), fetching from the US Treasury Fiscal Data API and caching for 24h.
+ *
+ * Behavior:
+ * - If a fresh cached value exists (<24h old), returns it without a network
+ *   round-trip.
+ * - If the cache is stale or empty, fetches the latest 13-week T-Bill rate,
+ *   updates the cache, and returns it.
+ * - If the fetch fails, returns the last-known-good cached value (even if
+ *   expired) or {@link DEFAULT_RISK_FREE_RATE} as a last resort, logging a
+ *   warning in both cases.
+ * - Concurrent calls during a cold cache are deduplicated so only one network
+ *   request is in flight at a time.
+ *
+ * For provenance-aware callers (performance reports, audit logging) prefer
+ * {@link getRiskFreeRateWithProvenance}, which returns both the rate AND
+ * whether it came from a live fetch, the cache, or the fallback default.
+ *
+ * @returns Annualized risk-free rate as a decimal.
+ */
+export declare function getRiskFreeRate(): Promise<number>;
+/**
+ * Synchronous accessor that returns the most recent cached risk-free rate
+ * without performing I/O. If the cache is stale, a background refresh is
+ * kicked off (fire-and-forget) so the next synchronous call sees a fresh
+ * value. Intended for hot paths (e.g., Sharpe/alpha calculation inside tight
+ * loops) where the existing function signature cannot be made async.
+ *
+ * Callers that can tolerate an async boundary should prefer
+ * {@link getRiskFreeRate}.
+ *
+ * @returns The cached annualized risk-free rate as a decimal, or
+ *          {@link DEFAULT_RISK_FREE_RATE} if no value has been cached yet.
+ */
+export declare function getCachedRiskFreeRateSync(): number;
+/**
+ * Provenance-aware sibling of {@link getCachedRiskFreeRateSync}. Returns the
+ * cached rate plus a flag indicating whether a real value has been cached
+ * (`"cached"`) or whether the caller is being given the {@link DEFAULT_RISK_FREE_RATE}
+ * fallback (`"default"`).
+ *
+ * Use this in synchronous hot paths that nonetheless need to flag computations
+ * made against the fallback (e.g., real-time alpha streaming where async
+ * round-trips are not viable but downstream reports must still distinguish
+ * live from fictional rates).
+ *
+ * As with the original sync accessor, a stale cache triggers a fire-and-forget
+ * background refresh so the next synchronous call sees fresh data; the call
+ * itself remains synchronous and returns the last-known-good value.
+ *
+ * DE-029: closes the silent-failure loop where the synchronous fallback was
+ * indistinguishable from a real cache hit.
+ *
+ * @returns A {@link RiskFreeRateResult} carrying the rate and its provenance.
+ */
+export declare function getCachedRiskFreeRateSyncWithProvenance(): RiskFreeRateResult;
+//# sourceMappingURL=risk-free-rate.d.ts.map

package/dist/types/risk-free-rate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-free-rate.d.ts","sourceRoot":"","sources":["../../src/risk-free-rate.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;;;OAIG;IACH,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAsB,CAAC;AA6CzD;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAOlD;AA8CD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,kBAAkB,CAAC,CA2DjF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAGvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uCAAuC,IAAI,kBAAkB,CAyB5E"}