@adaptic/utils 0.0.99

package/dist/types/polygon.d.ts

@@ -0,0 +1,126 @@
+/**********************************************************************************
+ * Polygon.io calls
+ **********************************************************************************/
+import { PolygonQuote, PolygonPriceData, PolygonGroupedDailyResponse, PolygonTickerInfo, PolygonDailyOpenClose, PolygonTradesResponse } 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<PolygonTickerInfo | null>} The ticker information or null if not found.
+ */
+export declare const fetchTickerInfo: (symbol: string, options?: {
+    apiKey?: string;
+}) => Promise<PolygonTickerInfo | 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<PolygonQuote>} The last trade information.
+ */
+export declare const fetchLastTrade: (symbol: string, options?: {
+    apiKey?: string;
+}) => Promise<PolygonQuote>;
+/**
+ * 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<PolygonPriceData[]>} The fetched price data.
+ */
+export declare const fetchPrices: (params: {
+    ticker: string;
+    start: number;
+    end?: number;
+    multiplier: number;
+    timespan: string;
+    limit?: number;
+}, options?: {
+    apiKey?: string;
+}) => Promise<PolygonPriceData[]>;
+/**
+ * Analyzes the price data for a given stock.
+ * @param {PolygonPriceData[]} priceData - The price data to analyze.
+ * @returns {string} The analysis report.
+ */
+export declare function analysePolygonPriceData(priceData: PolygonPriceData[]): 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<PolygonGroupedDailyResponse>} The grouped daily response.
+ */
+export declare const fetchGroupedDaily: (date: string, options?: {
+    apiKey?: string;
+    adjusted?: boolean;
+    includeOTC?: boolean;
+}) => Promise<PolygonGroupedDailyResponse>;
+/**
+ * Formats the price data into a readable string.
+ * @param {PolygonPriceData[]} priceData - The price data to format.
+ * @returns {string} The formatted price data.
+ */
+export declare function formatPriceData(priceData: PolygonPriceData[]): 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<PolygonDailyOpenClose>} The daily open and close data.
+ */
+symbol: string, date?: Date, options?: {
+    apiKey?: string;
+    adjusted?: boolean;
+}) => Promise<PolygonDailyOpenClose>;
+/**
+ * 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<PolygonTradesResponse>} 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<PolygonTradesResponse>;
+//# sourceMappingURL=polygon.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"polygon.d.ts","sourceRoot":"","sources":["../../src/polygon.ts"],"names":[],"mappings":"AAAA;;oFAEoF;AAIpF,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,2BAA2B,EAE3B,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EAEtB,MAAM,SAAS,CAAC;AAajB;;;;;;GAMG;AAEH,eAAO,MAAM,eAAe,GAC1B,QAAQ,MAAM,EACd,UAAU;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,KAC5B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAiGlC,CAAC;AAGF;;;;;;GAMG;AAEH,eAAO,MAAM,cAAc,GACzB,QAAQ,MAAM,EACd,UAAU;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,KAC5B,OAAO,CAAC,YAAY,CAmEtB,CAAC;AAGF;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,WAAW,GACtB,QAAQ;IACN,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,EACD,UAAU;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,KAC5B,OAAO,CAAC,gBAAgB,EAAE,CAgG5B,CAAC;AAEF;;;;GAIG;AAEH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,MAAM,CA8C7E;AAID;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,UAAU;IACR,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,KACA,OAAO,CAAC,2BAA2B,CAoErC,CAAC;AAEF;;;;GAIG;AAEH,wBAAgB,eAAe,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAoBrE;AAED,eAAO,MAAM,mBAAmB;AAC9B;;;;;;;;GAQG;AAEH,QAAQ,MAAM,EACd,OAAM,IAAiB,EACvB,UAAU;IACR,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,KACA,OAAO,CAAC,qBAAqB,CA6B/B,CAAC;AAIF;;;;;GAKG;AAEH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,IAAI,EACpB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAcxC;AAED;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,WAAW,GACtB,QAAQ,MAAM,EACd,UAAU;IACR,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,KACA,OAAO,CAAC,qBAAqB,CAgE/B,CAAC"}

package/dist/types/price-utils.d.ts

@@ -0,0 +1,26 @@
+import { types } from "@adaptic/backend-legacy";
+import { EquityPoint, AlpacaPortfolioHistory } from "./types/index";
+import { MarketTimeUtil } from "./market-time";
+export declare const computeTotalFees: (trade: types.Trade) => Promise<number>;
+/**
+ * Rounds price based on value:
+ * - For prices >= $1, rounds to nearest $0.01
+ * - For prices < $1, rounds to nearest $0.0001
+ */
+export declare function roundStockPrice(price: number): number;
+export declare function getEquityValues(equityData: EquityPoint[], portfolioHistory?: AlpacaPortfolioHistory, marketTimeUtil?: MarketTimeUtil, period?: string): {
+    latestEquity: number;
+    initialEquity: number;
+    latestTimestamp?: undefined;
+    initialTimestamp?: undefined;
+    baseValueAsOf?: undefined;
+    baseValue?: undefined;
+} | {
+    latestEquity: number;
+    initialEquity: number;
+    latestTimestamp: import("lightweight-charts").Time;
+    initialTimestamp: import("lightweight-charts").Time;
+    baseValueAsOf: string | undefined;
+    baseValue: number | undefined;
+};
+//# sourceMappingURL=price-utils.d.ts.map

package/dist/types/price-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"price-utils.d.ts","sourceRoot":"","sources":["../../src/price-utils.ts"],"names":[],"mappings":"AAEA,OAAgB,EAAS,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAe,cAAc,EAAE,MAAM,eAAe,CAAC;AAyE5D,eAAO,MAAM,gBAAgB,GAAU,OAAO,KAAK,CAAC,KAAK,KAAG,OAAO,CAAC,MAAM,CAiBzE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,WAAW,EAAE,EACzB,gBAAgB,CAAC,EAAE,sBAAsB,EACzC,cAAc,CAAC,EAAE,cAAc,EAC/B,MAAM,CAAC,EAAE,MAAM;;;;;;;;;;;;;;EAsHhB"}

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

@@ -0,0 +1,171 @@
+/**
+ * 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, Polygon, 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.polygon.acquire();
+ * await rateLimiters.alphaVantage.acquire();
+ * ```
+ */
+export declare const rateLimiters: {
+    /**
+     * Alpaca API rate limiter
+     *
+     * Configured for 200 requests per minute.
+     * See: https://alpaca.markets/docs/api-references/trading-api/#rate-limit
+     */
+    alpaca: TokenBucketRateLimiter;
+    /**
+     * Polygon.io API rate limiter
+     *
+     * Configured for 5 requests per second (basic plan).
+     * Adjust if you have a different subscription tier.
+     * See: https://polygon.io/pricing
+     */
+    polygon: 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;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,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;;;;;OAKG;;IAQH;;;;;;OAMG;;IAQH;;;;;;;;;;;;;;;;;OAiBG;;CAOJ,CAAC"}