@adaptic/utils 0.0.382 → 0.1.0

package/dist/types/alpaca/market-data/news.d.ts

@@ -0,0 +1,87 @@
+/**
+ * News Module
+ * Market news and analysis using Alpaca SDK
+ */
+import { AlpacaClient } from '../client';
+import { SimpleNews } from '../../types/alpaca-types';
+/**
+ * Error thrown when news operations fail
+ */
+export declare class NewsError extends Error {
+    code: string;
+    symbol?: string | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, symbol?: string | undefined, details?: unknown | undefined);
+}
+/**
+ * Parameters for fetching news
+ */
+export interface GetNewsParams {
+    /** Symbols to filter news by */
+    symbols?: string[];
+    /** Start date/time for the news range */
+    start?: Date;
+    /** End date/time for the news range */
+    end?: Date;
+    /** Maximum number of articles to return (default 10, max 50) */
+    limit?: number;
+    /** Sort order: 'asc' for oldest first, 'desc' for newest first (default) */
+    sort?: 'asc' | 'desc';
+    /** Include full article content (default false) */
+    includeContent?: boolean;
+}
+/**
+ * Get news articles with optional filtering
+ * @param client - AlpacaClient instance
+ * @param params - Parameters for fetching news
+ * @returns Array of simplified news articles
+ * @throws NewsError if the request fails
+ */
+export declare function getNews(client: AlpacaClient, params?: GetNewsParams): Promise<SimpleNews[]>;
+/**
+ * Get latest news for a specific symbol
+ * @param client - AlpacaClient instance
+ * @param symbol - Stock symbol to get news for
+ * @param limit - Maximum number of articles (default 10)
+ * @returns Array of simplified news articles
+ * @throws NewsError if the request fails
+ */
+export declare function getLatestNews(client: AlpacaClient, symbol: string, limit?: number): Promise<SimpleNews[]>;
+/**
+ * Search news by keyword in headlines and summaries
+ * Note: This performs client-side filtering since Alpaca API doesn't support keyword search
+ * @param client - AlpacaClient instance
+ * @param query - Search query (case-insensitive)
+ * @param limit - Maximum number of articles (default 10)
+ * @returns Array of simplified news articles matching the query
+ * @throws NewsError if the request fails
+ */
+export declare function searchNews(client: AlpacaClient, query: string, limit?: number): Promise<SimpleNews[]>;
+/**
+ * Get news for multiple symbols
+ * @param client - AlpacaClient instance
+ * @param symbols - Array of stock symbols
+ * @param limit - Maximum number of articles per symbol (default 5)
+ * @returns Map of symbol to news articles
+ */
+export declare function getNewsForSymbols(client: AlpacaClient, symbols: string[], limit?: number): Promise<Map<string, SimpleNews[]>>;
+/**
+ * Get average sentiment for a symbol based on recent news
+ * @param client - AlpacaClient instance
+ * @param symbol - Stock symbol
+ * @param limit - Number of articles to analyze (default 10)
+ * @returns Average sentiment score between -1 and 1
+ */
+export declare function getSymbolSentiment(client: AlpacaClient, symbol: string, limit?: number): Promise<{
+    sentiment: number;
+    articleCount: number;
+}>;
+declare const _default: {
+    getNews: typeof getNews;
+    getLatestNews: typeof getLatestNews;
+    searchNews: typeof searchNews;
+    getNewsForSymbols: typeof getNewsForSymbols;
+    getSymbolSentiment: typeof getSymbolSentiment;
+};
+export default _default;
+//# sourceMappingURL=news.d.ts.map

package/dist/types/alpaca/market-data/news.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"news.d.ts","sourceRoot":"","sources":["../../../../src/alpaca/market-data/news.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAqB,UAAU,EAAgB,MAAM,0BAA0B,CAAC;AAQvF;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAGzB,IAAI,EAAE,MAAM;IACZ,MAAM,CAAC,EAAE,MAAM;IACf,OAAO,CAAC,EAAE,OAAO;gBAHxB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,OAAO,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yCAAyC;IACzC,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,uCAAuC;IACvC,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACtB,mDAAmD;IACnD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAgJD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,YAAY,EACpB,MAAM,GAAE,aAAkB,GACzB,OAAO,CAAC,UAAU,EAAE,CAAC,CA8GvB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,UAAU,EAAE,CAAC,CAcvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,UAAU,EAAE,CAAC,CAoDvB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,GAAE,MAAU,GAChB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CA2CpC;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAmBtD;;;;;;;;AAED,wBAME"}

package/dist/types/alpaca/market-data/quotes.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Quotes Module
+ * Real-time and snapshot quote data using Alpaca SDK
+ */
+import { AlpacaClient } from '../client';
+import { AlpacaQuote, LatestQuotesResponse, DataFeed } from '../../types/alpaca-types';
+/**
+ * Error thrown when quote operations fail
+ */
+export declare class QuoteError extends Error {
+    code: string;
+    symbol?: string | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, symbol?: string | undefined, details?: unknown | undefined);
+}
+/**
+ * Spread information for a symbol
+ */
+export interface SpreadInfo {
+    /** Bid price */
+    bid: number;
+    /** Ask price */
+    ask: number;
+    /** Absolute spread (ask - bid) */
+    spread: number;
+    /** Spread as percentage of mid price */
+    spreadPercent: number;
+    /** Mid price ((bid + ask) / 2) */
+    midPrice: number;
+    /** Bid size */
+    bidSize: number;
+    /** Ask size */
+    askSize: number;
+}
+/**
+ * Get latest quote for a single symbol
+ * @param client - AlpacaClient instance
+ * @param symbol - Stock symbol to get quote for
+ * @param feed - Optional data feed (sip, iex, delayed_sip)
+ * @returns Latest quote for the symbol
+ * @throws QuoteError if the request fails
+ */
+export declare function getLatestQuote(client: AlpacaClient, symbol: string, feed?: DataFeed): Promise<AlpacaQuote>;
+/**
+ * Get latest quotes for multiple symbols
+ * @param client - AlpacaClient instance
+ * @param symbols - Array of stock symbols
+ * @param feed - Optional data feed (sip, iex, delayed_sip)
+ * @returns Object containing quotes for all requested symbols
+ * @throws QuoteError if the request fails
+ */
+export declare function getLatestQuotes(client: AlpacaClient, symbols: string[], feed?: DataFeed): Promise<LatestQuotesResponse>;
+/**
+ * Get bid/ask spread for a symbol
+ * Useful for evaluating liquidity and trading costs
+ * @param client - AlpacaClient instance
+ * @param symbol - Stock symbol
+ * @returns Spread information including bid, ask, spread, and percentage
+ * @throws QuoteError if the request fails or if prices are invalid
+ */
+export declare function getSpread(client: AlpacaClient, symbol: string): Promise<SpreadInfo>;
+/**
+ * Get multiple spreads for an array of symbols
+ * @param client - AlpacaClient instance
+ * @param symbols - Array of stock symbols
+ * @returns Map of symbol to spread information
+ */
+export declare function getSpreads(client: AlpacaClient, symbols: string[]): Promise<Map<string, SpreadInfo>>;
+/**
+ * Check if a symbol has good liquidity based on spread
+ * @param client - AlpacaClient instance
+ * @param symbol - Stock symbol
+ * @param maxSpreadPercent - Maximum acceptable spread percentage (default 1%)
+ * @returns true if spread is within acceptable range
+ */
+export declare function hasGoodLiquidity(client: AlpacaClient, symbol: string, maxSpreadPercent?: number): Promise<boolean>;
+declare const _default: {
+    getLatestQuote: typeof getLatestQuote;
+    getLatestQuotes: typeof getLatestQuotes;
+    getSpread: typeof getSpread;
+    getSpreads: typeof getSpreads;
+    hasGoodLiquidity: typeof hasGoodLiquidity;
+};
+export default _default;
+//# sourceMappingURL=quotes.d.ts.map

package/dist/types/alpaca/market-data/quotes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quotes.d.ts","sourceRoot":"","sources":["../../../../src/alpaca/market-data/quotes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAQvF;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IAG1B,IAAI,EAAE,MAAM;IACZ,MAAM,CAAC,EAAE,MAAM;IACf,OAAO,CAAC,EAAE,OAAO;gBAHxB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,OAAO,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gBAAgB;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,QAAQ,GACd,OAAO,CAAC,WAAW,CAAC,CAuDtB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,CAAC,EAAE,QAAQ,GACd,OAAO,CAAC,oBAAoB,CAAC,CA+E/B;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,CAAC,CAiCrB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CA0BlC;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,gBAAgB,GAAE,MAAY,GAC7B,OAAO,CAAC,OAAO,CAAC,CAQlB;;;;;;;;AAED,wBAME"}

package/dist/types/alpaca/market-data/trades.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Trades Module
+ * Real-time and historical trade data using Alpaca SDK
+ */
+import { AlpacaClient } from '../client';
+import { AlpacaTrade, LatestTradesResponse, DataFeed } from '../../types/alpaca-types';
+/**
+ * Error thrown when trade operations fail
+ */
+export declare class TradeError extends Error {
+    code: string;
+    symbol?: string | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, symbol?: string | undefined, details?: unknown | undefined);
+}
+/**
+ * Parameters for fetching historical trades
+ */
+export interface GetHistoricalTradesParams {
+    /** Stock symbol */
+    symbol: string;
+    /** Start date/time for the data range */
+    start: Date;
+    /** End date/time for the data range (defaults to now) */
+    end?: Date;
+    /** Maximum number of trades to return */
+    limit?: number;
+    /** Data feed (sip for premium, iex for free tier) */
+    feed?: DataFeed;
+}
+/**
+ * Get latest trade for a single symbol
+ * @param client - AlpacaClient instance
+ * @param symbol - Stock symbol to get trade for
+ * @param feed - Optional data feed (sip, iex, delayed_sip)
+ * @returns Latest trade for the symbol
+ * @throws TradeError if the request fails
+ */
+export declare function getLatestTrade(client: AlpacaClient, symbol: string, feed?: DataFeed): Promise<AlpacaTrade>;
+/**
+ * Get latest trades for multiple symbols
+ * @param client - AlpacaClient instance
+ * @param symbols - Array of stock symbols
+ * @param feed - Optional data feed (sip, iex, delayed_sip)
+ * @returns Object containing trades for all requested symbols
+ * @throws TradeError if the request fails
+ */
+export declare function getLatestTrades(client: AlpacaClient, symbols: string[], feed?: DataFeed): Promise<LatestTradesResponse>;
+/**
+ * Get historical trades with automatic pagination
+ * @param client - AlpacaClient instance
+ * @param params - Parameters for fetching historical trades
+ * @returns Array of trades for the symbol
+ * @throws TradeError if the request fails
+ */
+export declare function getHistoricalTrades(client: AlpacaClient, params: GetHistoricalTradesParams): Promise<AlpacaTrade[]>;
+/**
+ * Get current price for a symbol
+ * Uses mid-point of latest quote if available, otherwise falls back to last trade price
+ * @param client - AlpacaClient instance
+ * @param symbol - Stock symbol
+ * @param feed - Optional data feed (sip, iex, delayed_sip)
+ * @returns Current price for the symbol
+ * @throws TradeError if unable to get price
+ */
+export declare function getCurrentPrice(client: AlpacaClient, symbol: string, feed?: DataFeed): Promise<number>;
+/**
+ * Get current prices for multiple symbols
+ * Uses mid-point of latest quote if available, otherwise falls back to last trade price
+ * @param client - AlpacaClient instance
+ * @param symbols - Array of stock symbols
+ * @param feed - Optional data feed (sip, iex, delayed_sip)
+ * @returns Map of symbol to current price
+ */
+export declare function getCurrentPrices(client: AlpacaClient, symbols: string[], feed?: DataFeed): Promise<Map<string, number>>;
+/**
+ * Get trade volume summary for a symbol over a time period
+ * @param client - AlpacaClient instance
+ * @param symbol - Stock symbol
+ * @param start - Start date/time
+ * @param end - End date/time (defaults to now)
+ * @returns Total volume and trade count for the period
+ */
+export declare function getTradeVolume(client: AlpacaClient, symbol: string, start: Date, end?: Date): Promise<{
+    totalVolume: number;
+    tradeCount: number;
+    avgTradeSize: number;
+}>;
+declare const _default: {
+    getLatestTrade: typeof getLatestTrade;
+    getLatestTrades: typeof getLatestTrades;
+    getHistoricalTrades: typeof getHistoricalTrades;
+    getCurrentPrice: typeof getCurrentPrice;
+    getCurrentPrices: typeof getCurrentPrices;
+    getTradeVolume: typeof getTradeVolume;
+};
+export default _default;
+//# sourceMappingURL=trades.d.ts.map

package/dist/types/alpaca/market-data/trades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trades.d.ts","sourceRoot":"","sources":["../../../../src/alpaca/market-data/trades.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAQvF;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IAG1B,IAAI,EAAE,MAAM;IACZ,MAAM,CAAC,EAAE,MAAM;IACf,OAAO,CAAC,EAAE,OAAO;gBAHxB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,OAAO,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,KAAK,EAAE,IAAI,CAAC;IACZ,yDAAyD;IACzD,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAYD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,QAAQ,GACd,OAAO,CAAC,WAAW,CAAC,CAqDtB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,CAAC,EAAE,QAAQ,GACd,OAAO,CAAC,oBAAoB,CAAC,CA2E/B;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,WAAW,EAAE,CAAC,CAwExB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,QAAQ,GACd,OAAO,CAAC,MAAM,CAAC,CAwDjB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,CAAC,EAAE,QAAQ,GACd,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAgF9B;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,IAAI,EACX,GAAG,CAAC,EAAE,IAAI,GACT,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CA0B5E;;;;;;;;;AAED,wBAOE"}

package/dist/types/alpaca/options/contracts.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Options Contracts Module
+ * Query and analyze option contracts
+ */
+import { AlpacaClient } from '../client';
+import { OptionContract, OptionType, GetOptionContractsParams } from '../../types/alpaca-types';
+/**
+ * Parameters for getting option chain
+ */
+export interface GetOptionChainParams {
+    /** Filter by expiration date (YYYY-MM-DD format) */
+    expirationDate?: string;
+    /** Filter by strike price range */
+    strikePrice?: {
+        min?: number;
+        max?: number;
+    };
+    /** Filter by option type (call or put) */
+    type?: OptionType;
+}
+/**
+ * ATM options result containing both call and put
+ */
+export interface ATMOptionsResult {
+    /** ATM call option if found */
+    call: OptionContract | null;
+    /** ATM put option if found */
+    put: OptionContract | null;
+    /** The strike price used for ATM determination */
+    strikePrice: number;
+    /** Current underlying price used for determination */
+    underlyingPrice: number;
+}
+/**
+ * Options chain grouped by expiration and strike
+ */
+export interface GroupedOptionChain {
+    /** The underlying symbol */
+    underlying: string;
+    /** Chain grouped by expiration date */
+    byExpiration: {
+        [expirationDate: string]: {
+            /** Calls at each strike */
+            calls: {
+                [strike: string]: OptionContract;
+            };
+            /** Puts at each strike */
+            puts: {
+                [strike: string]: OptionContract;
+            };
+        };
+    };
+    /** All available expiration dates */
+    expirations: string[];
+    /** All available strike prices */
+    strikes: number[];
+}
+/**
+ * Get option contracts for an underlying symbol with filters
+ *
+ * @param client - The AlpacaClient instance
+ * @param params - Query parameters for filtering contracts
+ * @returns Array of option contracts matching the criteria
+ * @throws Error if API request fails
+ *
+ * @example
+ * // Get all AAPL option contracts
+ * const contracts = await getOptionContracts(client, {
+ *   underlying_symbols: ['AAPL'],
+ * });
+ *
+ * @example
+ * // Get AAPL calls expiring in the next 30 days
+ * const today = new Date();
+ * const thirtyDaysOut = new Date(today.getTime() + 30 * 24 * 60 * 60 * 1000);
+ * const contracts = await getOptionContracts(client, {
+ *   underlying_symbols: ['AAPL'],
+ *   type: 'call',
+ *   expiration_date_gte: today.toISOString().split('T')[0],
+ *   expiration_date_lte: thirtyDaysOut.toISOString().split('T')[0],
+ * });
+ */
+export declare function getOptionContracts(client: AlpacaClient, params: GetOptionContractsParams): Promise<OptionContract[]>;
+/**
+ * Get a specific option contract by symbol or ID
+ *
+ * @param client - The AlpacaClient instance
+ * @param symbolOrId - Option contract symbol (e.g., AAPL230120C00150000) or contract ID
+ * @returns The option contract details
+ * @throws Error if contract not found or API request fails
+ *
+ * @example
+ * // Get contract by OCC symbol
+ * const contract = await getOptionContract(client, 'AAPL230120C00150000');
+ *
+ * @example
+ * // Get contract by ID
+ * const contract = await getOptionContract(client, 'contract-uuid-here');
+ */
+export declare function getOptionContract(client: AlpacaClient, symbolOrId: string): Promise<OptionContract>;
+/**
+ * Get option chain for a symbol with optional filters
+ *
+ * @param client - The AlpacaClient instance
+ * @param underlying - The underlying symbol (e.g., 'AAPL')
+ * @param params - Optional filter parameters
+ * @returns Array of option contracts in the chain
+ *
+ * @example
+ * // Get full option chain for AAPL
+ * const chain = await getOptionChain(client, 'AAPL');
+ *
+ * @example
+ * // Get AAPL puts at specific strike range
+ * const chain = await getOptionChain(client, 'AAPL', {
+ *   type: 'put',
+ *   strikePrice: { min: 140, max: 160 },
+ * });
+ */
+export declare function getOptionChain(client: AlpacaClient, underlying: string, params?: GetOptionChainParams): Promise<OptionContract[]>;
+/**
+ * Get available expiration dates for an underlying symbol
+ *
+ * @param client - The AlpacaClient instance
+ * @param underlying - The underlying symbol (e.g., 'AAPL')
+ * @returns Sorted array of expiration dates (YYYY-MM-DD format)
+ *
+ * @example
+ * const expirations = await getExpirationDates(client, 'AAPL');
+ * console.log(`Next expiration: ${expirations[0]}`);
+ */
+export declare function getExpirationDates(client: AlpacaClient, underlying: string): Promise<string[]>;
+/**
+ * Get available strike prices for an underlying at a specific expiration
+ *
+ * @param client - The AlpacaClient instance
+ * @param underlying - The underlying symbol
+ * @param expirationDate - The expiration date (YYYY-MM-DD format)
+ * @returns Sorted array of available strike prices
+ *
+ * @example
+ * const strikes = await getStrikePrices(client, 'AAPL', '2024-01-19');
+ */
+export declare function getStrikePrices(client: AlpacaClient, underlying: string, expirationDate: string): Promise<number[]>;
+/**
+ * Find ATM (at-the-money) options for an underlying
+ * Returns both call and put options at the strike price closest to current price
+ *
+ * @param client - The AlpacaClient instance
+ * @param underlying - The underlying symbol
+ * @param expirationDate - The expiration date (YYYY-MM-DD format)
+ * @param currentPrice - Current price of the underlying (required to determine ATM)
+ * @param type - Optional filter to return only call or put
+ * @returns ATM options result with call and/or put contracts
+ *
+ * @example
+ * // Get both ATM call and put
+ * const atm = await findATMOptions(client, 'AAPL', '2024-01-19', 175.50);
+ * console.log(`ATM Call: ${atm.call?.symbol}`);
+ * console.log(`ATM Put: ${atm.put?.symbol}`);
+ *
+ * @example
+ * // Get only ATM call
+ * const atm = await findATMOptions(client, 'AAPL', '2024-01-19', 175.50, 'call');
+ */
+export declare function findATMOptions(client: AlpacaClient, underlying: string, expirationDate: string, currentPrice: number, type?: OptionType): Promise<ATMOptionsResult>;
+/**
+ * Get grouped option chain organized by expiration and strike
+ *
+ * @param client - The AlpacaClient instance
+ * @param underlying - The underlying symbol
+ * @param expirationDates - Optional array of expiration dates to include
+ * @returns Grouped option chain structure
+ *
+ * @example
+ * const chain = await getGroupedOptionChain(client, 'AAPL');
+ * // Access calls at specific expiration and strike
+ * const call = chain.byExpiration['2024-01-19'].calls['175'];
+ */
+export declare function getGroupedOptionChain(client: AlpacaClient, underlying: string, expirationDates?: string[]): Promise<GroupedOptionChain>;
+/**
+ * Find options contracts within a delta range (approximated by strike distance from current price)
+ *
+ * @param client - The AlpacaClient instance
+ * @param underlying - The underlying symbol
+ * @param expirationDate - The expiration date
+ * @param currentPrice - Current price of the underlying
+ * @param targetDeltaPercent - Target delta as percentage of current price (e.g., 5 for 5%)
+ * @param type - Option type (call or put)
+ * @returns Array of contracts within the delta range
+ *
+ * @example
+ * // Find calls approximately 5% OTM
+ * const otmCalls = await findOptionsByDelta(client, 'AAPL', '2024-01-19', 175, 5, 'call');
+ */
+export declare function findOptionsByDelta(client: AlpacaClient, underlying: string, expirationDate: string, currentPrice: number, targetDeltaPercent: number, type: OptionType): Promise<OptionContract[]>;
+/**
+ * Find the nearest expiration date to a target number of days out
+ *
+ * @param client - The AlpacaClient instance
+ * @param underlying - The underlying symbol
+ * @param targetDays - Target number of days to expiration
+ * @returns The nearest available expiration date
+ *
+ * @example
+ * // Find expiration closest to 30 days out
+ * const expiration = await findNearestExpiration(client, 'AAPL', 30);
+ */
+export declare function findNearestExpiration(client: AlpacaClient, underlying: string, targetDays: number): Promise<string>;
+/**
+ * Parse OCC option symbol to extract components
+ *
+ * @param occSymbol - OCC option symbol (e.g., AAPL230120C00150000)
+ * @returns Parsed symbol components
+ *
+ * @example
+ * const parsed = parseOCCSymbol('AAPL230120C00150000');
+ * // Returns: { underlying: 'AAPL', expiration: '2023-01-20', type: 'call', strike: 150 }
+ */
+export declare function parseOCCSymbol(occSymbol: string): {
+    underlying: string;
+    expiration: string;
+    type: OptionType;
+    strike: number;
+} | null;
+/**
+ * Build OCC option symbol from components
+ *
+ * @param underlying - The underlying symbol
+ * @param expiration - Expiration date (YYYY-MM-DD format)
+ * @param type - Option type (call or put)
+ * @param strike - Strike price
+ * @returns OCC-formatted option symbol
+ *
+ * @example
+ * const symbol = buildOCCSymbol('AAPL', '2023-01-20', 'call', 150);
+ * // Returns: 'AAPL230120C00150000'
+ */
+export declare function buildOCCSymbol(underlying: string, expiration: string, type: OptionType, strike: number): string;
+/**
+ * Check if an option contract is tradable
+ *
+ * @param contract - The option contract to check
+ * @returns True if the contract is active and tradable
+ */
+export declare function isContractTradable(contract: OptionContract): boolean;
+/**
+ * Calculate days to expiration for a contract
+ *
+ * @param contract - The option contract
+ * @returns Number of calendar days until expiration
+ */
+export declare function getDaysToExpiration(contract: OptionContract): number;
+/**
+ * Check if a contract is expiring within N days
+ *
+ * @param contract - The option contract
+ * @param days - Number of days threshold
+ * @returns True if contract expires within the specified days
+ */
+export declare function isExpiringWithin(contract: OptionContract, days: number): boolean;
+declare const _default: {
+    getOptionContracts: typeof getOptionContracts;
+    getOptionContract: typeof getOptionContract;
+    getOptionChain: typeof getOptionChain;
+    getExpirationDates: typeof getExpirationDates;
+    getStrikePrices: typeof getStrikePrices;
+    findATMOptions: typeof findATMOptions;
+    getGroupedOptionChain: typeof getGroupedOptionChain;
+    findOptionsByDelta: typeof findOptionsByDelta;
+    findNearestExpiration: typeof findNearestExpiration;
+    parseOCCSymbol: typeof parseOCCSymbol;
+    buildOCCSymbol: typeof buildOCCSymbol;
+    isContractTradable: typeof isContractTradable;
+    getDaysToExpiration: typeof getDaysToExpiration;
+    isExpiringWithin: typeof isExpiringWithin;
+};
+export default _default;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/types/alpaca/options/contracts.d.ts.map

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