market-feed 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,507 @@
+/**
+ * Minimal interface that any cache backend must implement.
+ * Implement this interface to plug in Redis, Upstash, filesystem, etc.
+ *
+ * @example
+ * ```ts
+ * import type { CacheDriver } from 'market-feed';
+ * import { createClient } from 'redis';
+ *
+ * const redis = createClient();
+ * const driver: CacheDriver = {
+ *   async get(key) { const v = await redis.get(key); return v ? JSON.parse(v) : undefined; },
+ *   async set(key, value, ttl) { await redis.set(key, JSON.stringify(value), { EX: ttl }); },
+ *   async delete(key) { await redis.del(key); },
+ *   async clear() { await redis.flushDb(); },
+ * };
+ * ```
+ */
+interface CacheDriver {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+interface CacheConfig {
+    /** Default TTL in seconds for cached responses. Defaults to 60. */
+    ttl?: number;
+    /** Maximum number of entries in the memory cache. Defaults to 500. */
+    maxSize?: number;
+    /**
+     * Custom cache driver. When provided, `maxSize` is ignored
+     * (the driver manages its own eviction).
+     */
+    driver?: CacheDriver;
+    /**
+     * Per-method TTL overrides (in seconds).
+     * Keys are method names: "quote", "historical", "company", "news", "search", "marketStatus".
+     */
+    ttlOverrides?: Partial<Record<CacheMethod, number>>;
+}
+type CacheMethod = "quote" | "historical" | "company" | "news" | "search" | "marketStatus";
+
+interface CompanyProfile {
+    symbol: string;
+    name: string;
+    description?: string;
+    sector?: string;
+    industry?: string;
+    /** ISO 3166-1 alpha-2 country code, e.g. "US" */
+    country?: string;
+    employees?: number;
+    website?: string;
+    ceo?: string;
+    /** Market cap in USD */
+    marketCap?: number;
+    /** Price-to-earnings ratio */
+    peRatio?: number;
+    /** Forward PE ratio */
+    forwardPE?: number;
+    /** Price-to-book ratio */
+    priceToBook?: number;
+    /** Annual dividend yield as a decimal, e.g. 0.015 = 1.5% */
+    dividendYield?: number;
+    /** Beta (5Y monthly) */
+    beta?: number;
+    /** Exchange identifier */
+    exchange?: string;
+    /** Currency */
+    currency?: string;
+    /** IPO date */
+    ipoDate?: Date;
+    provider: string;
+    raw?: unknown;
+}
+interface CompanyOptions {
+    raw?: boolean;
+}
+
+type HistoricalInterval = "1m" | "2m" | "5m" | "15m" | "30m" | "60m" | "90m" | "1h" | "1d" | "5d" | "1wk" | "1mo" | "3mo";
+interface HistoricalOptions {
+    /**
+     * Start date — ISO 8601 string ("2024-01-01") or a Date object.
+     * Defaults to 1 year ago.
+     */
+    period1?: string | Date;
+    /**
+     * End date — ISO 8601 string or a Date object.
+     * Defaults to today.
+     */
+    period2?: string | Date;
+    /** Bar interval. Defaults to "1d". */
+    interval?: HistoricalInterval;
+    /** Include the raw provider response on each bar */
+    raw?: boolean;
+}
+interface HistoricalBar {
+    date: Date;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    /** Adjusted close price (splits + dividends). May be absent for intraday. */
+    adjClose?: number;
+    volume: number;
+    raw?: unknown;
+}
+
+type TradingSession = "pre" | "regular" | "post" | "closed";
+interface MarketStatus {
+    /** Whether the primary session is currently open */
+    isOpen: boolean;
+    /** Current trading session type */
+    session: TradingSession;
+    /** Next session open time */
+    nextOpen?: Date;
+    /** Current (or next) session close time */
+    nextClose?: Date;
+    /** Market/exchange identifier, e.g. "US", "LSE" */
+    market?: string;
+    /** Timezone of the exchange, e.g. "America/New_York" */
+    timezone?: string;
+    provider: string;
+    raw?: unknown;
+}
+interface MarketStatusOptions {
+    raw?: boolean;
+}
+
+interface NewsItem {
+    /** Provider-specific unique ID */
+    id: string;
+    title: string;
+    summary?: string;
+    url: string;
+    /** Publisher / source name */
+    source: string;
+    publishedAt: Date;
+    /** Ticker symbols mentioned in this article */
+    symbols: string[];
+    /** Thumbnail image URL */
+    thumbnail?: string;
+    provider: string;
+    raw?: unknown;
+}
+interface NewsOptions {
+    /** Maximum number of articles to return. Defaults to 10. */
+    limit?: number;
+    raw?: boolean;
+}
+
+interface Quote {
+    /** Ticker symbol, e.g. "AAPL" */
+    symbol: string;
+    /** Full company or asset name */
+    name: string;
+    /** Current or last-traded price */
+    price: number;
+    /** Absolute change from previous close */
+    change: number;
+    /** Percentage change from previous close */
+    changePercent: number;
+    /** Opening price for current/last session */
+    open: number;
+    /** Intraday high */
+    high: number;
+    /** Intraday low */
+    low: number;
+    /** Closing price of last completed session */
+    close: number;
+    /** Previous session close */
+    previousClose: number;
+    /** Volume traded in current/last session */
+    volume: number;
+    /** Average volume (30-day) */
+    avgVolume?: number;
+    /** Market capitalisation in quote currency */
+    marketCap?: number;
+    /** 52-week high */
+    fiftyTwoWeekHigh?: number;
+    /** 52-week low */
+    fiftyTwoWeekLow?: number;
+    /** Currency the price is quoted in, e.g. "USD" */
+    currency: string;
+    /** Exchange identifier, e.g. "NASDAQ" */
+    exchange: string;
+    /** Timestamp of the quote data */
+    timestamp: Date;
+    /** Which provider delivered this data */
+    provider: string;
+    /** Raw provider response — available when `raw: true` is passed to the client */
+    raw?: unknown;
+}
+interface QuoteOptions {
+    /** Include the raw provider response on each Quote object */
+    raw?: boolean;
+}
+
+type AssetType = "stock" | "etf" | "crypto" | "forex" | "index" | "mutual-fund" | "future" | "unknown";
+interface SearchResult {
+    symbol: string;
+    name: string;
+    type: AssetType;
+    exchange?: string;
+    currency?: string;
+    /** ISIN when available */
+    isin?: string;
+    provider: string;
+    raw?: unknown;
+}
+interface SearchOptions {
+    /** Maximum number of results to return. Defaults to 10. */
+    limit?: number;
+    raw?: boolean;
+}
+
+/**
+ * The contract every provider adapter must satisfy.
+ *
+ * Methods marked optional (`?`) are not supported by all free-tier APIs.
+ * The MarketFeed client only calls them when the active provider declares them.
+ */
+interface MarketProvider {
+    /** Human-readable provider name, e.g. "yahoo" */
+    readonly name: string;
+    /**
+     * Fetch real-time (or latest delayed) quotes for one or more symbols.
+     * Always returns an array — callers slice as needed.
+     */
+    quote(symbols: string[], options?: QuoteOptions): Promise<Quote[]>;
+    /**
+     * Fetch OHLCV bars for a single symbol over a date range.
+     */
+    historical(symbol: string, options?: HistoricalOptions): Promise<HistoricalBar[]>;
+    /**
+     * Search for tickers matching a query string.
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Fetch company/asset profile. Optional — not all providers support this.
+     */
+    company?(symbol: string, options?: CompanyOptions): Promise<CompanyProfile>;
+    /**
+     * Fetch recent news for a symbol. Optional.
+     */
+    news?(symbol: string, options?: NewsOptions): Promise<NewsItem[]>;
+    /**
+     * Return current market status for a given market identifier (e.g. "US").
+     * Optional.
+     */
+    marketStatus?(market?: string, options?: MarketStatusOptions): Promise<MarketStatus>;
+}
+
+interface MarketFeedOptions {
+    /**
+     * Ordered list of provider adapters.
+     * When `fallback: true`, each is tried in order until one succeeds.
+     * Defaults to `[new YahooProvider()]`.
+     */
+    providers?: MarketProvider[];
+    /**
+     * Cache configuration. Pass `false` to disable caching entirely.
+     * Defaults to an in-memory LRU cache with 60s TTL.
+     */
+    cache?: CacheConfig | false;
+    /**
+     * When `true`, automatically tries the next provider if the current one fails.
+     * Defaults to `true`.
+     */
+    fallback?: boolean;
+}
+/**
+ * The unified MarketFeed client.
+ *
+ * Wraps one or more provider adapters under a single consistent API.
+ * Handles caching, fallback, and error aggregation transparently.
+ *
+ * @example
+ * ```ts
+ * import { MarketFeed } from 'market-feed';
+ *
+ * const feed = new MarketFeed();
+ * const quote = await feed.quote('AAPL');
+ * console.log(quote.price); // 189.84
+ * ```
+ */
+declare class MarketFeed {
+    private readonly providers;
+    private readonly cache;
+    private readonly fallback;
+    private readonly ttls;
+    constructor(options?: MarketFeedOptions);
+    /** Fetch a quote for a single symbol. */
+    quote(symbol: string, options?: QuoteOptions): Promise<Quote>;
+    /** Fetch quotes for multiple symbols in parallel. */
+    quote(symbols: string[], options?: QuoteOptions): Promise<Quote[]>;
+    historical(symbol: string, options?: HistoricalOptions): Promise<HistoricalBar[]>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    company(symbol: string, options?: CompanyOptions): Promise<CompanyProfile>;
+    news(symbol: string, options?: NewsOptions): Promise<NewsItem[]>;
+    marketStatus(market?: string, options?: MarketStatusOptions): Promise<MarketStatus>;
+    /** Invalidate all cached entries. */
+    clearCache(): Promise<void>;
+    /** Invalidate a specific cache key (exact match). */
+    invalidate(key: string): Promise<void>;
+    private withFallback;
+    private getCache;
+    private setCache;
+}
+
+interface YahooProviderOptions {
+    /** Request timeout in milliseconds. Defaults to 10 000. */
+    timeoutMs?: number;
+    /** Retry attempts on transient failures. Defaults to 2. */
+    retries?: number;
+}
+/**
+ * Yahoo Finance provider — no API key required.
+ *
+ * Uses the unofficial Yahoo Finance v8 chart API, which is free and publicly
+ * accessible but not officially supported. Use respectfully.
+ */
+declare class YahooProvider implements MarketProvider {
+    readonly name = "yahoo";
+    private readonly http1;
+    private readonly http2;
+    constructor(options?: YahooProviderOptions);
+    quote(symbols: string[], options?: QuoteOptions): Promise<Quote[]>;
+    private fetchSingleQuote;
+    historical(symbol: string, options?: HistoricalOptions): Promise<HistoricalBar[]>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    company(symbol: string, options?: CompanyOptions): Promise<CompanyProfile>;
+}
+
+/**
+ * Token-bucket rate limiter.
+ *
+ * Tokens refill at `refillRate` tokens per second up to `capacity`.
+ * Call `consume()` before each API request; it throws `RateLimitError`
+ * if the bucket is empty.
+ */
+declare class RateLimiter {
+    private readonly providerName;
+    private readonly capacity;
+    private readonly refillRate;
+    private tokens;
+    private lastRefill;
+    /**
+     * @param providerName  Used in error messages
+     * @param capacity      Maximum tokens in the bucket (= burst limit)
+     * @param refillRate    Tokens added per second
+     */
+    constructor(providerName: string, capacity: number, refillRate: number);
+    /**
+     * Attempt to consume `count` tokens.
+     * Throws `RateLimitError` if insufficient tokens are available.
+     */
+    consume(count?: number): void;
+    /**
+     * Returns true if at least `count` tokens are available without consuming them.
+     */
+    canConsume(count?: number): boolean;
+    /** Milliseconds until the bucket has at least `count` tokens. 0 if already available. */
+    waitTimeMs(count?: number): number;
+    private refill;
+}
+
+interface AlphaVantageProviderOptions {
+    apiKey: string;
+    /** Request timeout in milliseconds. Defaults to 10 000. */
+    timeoutMs?: number;
+    /** Retry attempts on transient failures. Defaults to 2. */
+    retries?: number;
+    /**
+     * Override the rate limiter.
+     * Free tier: 5 calls/minute, 25 calls/day.
+     * Premium tier: higher — set refillRate accordingly.
+     */
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Alpha Vantage provider.
+ *
+ * Free tier: 25 API calls/day, 5 calls/minute.
+ * The rate limiter is enforced client-side to avoid burning your daily quota.
+ */
+declare class AlphaVantageProvider implements MarketProvider {
+    readonly name = "alpha-vantage";
+    private readonly http;
+    private readonly apiKey;
+    private readonly limiter;
+    constructor(options: AlphaVantageProviderOptions);
+    quote(symbols: string[], options?: QuoteOptions): Promise<Quote[]>;
+    private fetchSingleQuote;
+    historical(symbol: string, options?: HistoricalOptions): Promise<HistoricalBar[]>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    company(symbol: string, options?: CompanyOptions): Promise<CompanyProfile>;
+    private checkRateLimit;
+}
+
+interface PolygonProviderOptions {
+    apiKey: string;
+    /** Request timeout in milliseconds. Defaults to 10 000. */
+    timeoutMs?: number;
+    /** Retry attempts on transient failures. Defaults to 2. */
+    retries?: number;
+    /**
+     * Override the rate limiter.
+     * Free tier: 5 calls/minute. Unlimited for paid plans.
+     */
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Polygon.io provider.
+ *
+ * Free tier provides 15-minute delayed data with 5 API calls per minute.
+ * Paid plans unlock real-time data and higher rate limits.
+ */
+declare class PolygonProvider implements MarketProvider {
+    private readonly options;
+    readonly name = "polygon";
+    private readonly http;
+    private readonly limiter;
+    constructor(options: PolygonProviderOptions);
+    quote(symbols: string[], options?: QuoteOptions): Promise<Quote[]>;
+    historical(symbol: string, options?: HistoricalOptions): Promise<HistoricalBar[]>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    company(symbol: string, options?: CompanyOptions): Promise<CompanyProfile>;
+    news(symbol: string, options?: NewsOptions): Promise<NewsItem[]>;
+    private assertSuccess;
+}
+
+/**
+ * A simple LRU (Least-Recently-Used) in-memory cache with TTL support.
+ * No dependencies — uses a Map for O(1) access and insertion-order eviction.
+ */
+declare class MemoryCacheDriver implements CacheDriver {
+    private readonly store;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /** Current number of cached entries (including potentially expired ones). */
+    get size(): number;
+}
+
+/**
+ * Base error class for all market-feed errors.
+ * Includes the provider name so callers can identify the source.
+ */
+declare class MarketFeedError extends Error {
+    readonly provider: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, provider: string, cause?: unknown | undefined);
+}
+/**
+ * Thrown when an upstream provider returns an HTTP error or unexpected payload.
+ */
+declare class ProviderError extends MarketFeedError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, provider: string, statusCode?: number | undefined, cause?: unknown);
+}
+/**
+ * Thrown when a provider's rate limit is reached.
+ * Contains the earliest time the caller may retry.
+ */
+declare class RateLimitError extends MarketFeedError {
+    readonly retryAfter?: Date | undefined;
+    constructor(provider: string, retryAfter?: Date | undefined);
+}
+/**
+ * Thrown when all configured providers have failed for a given operation.
+ */
+declare class AllProvidersFailedError extends Error {
+    readonly errors: MarketFeedError[];
+    constructor(errors: MarketFeedError[], operation: string);
+}
+/**
+ * Thrown when a required feature is not supported by the active provider.
+ */
+declare class UnsupportedOperationError extends MarketFeedError {
+    constructor(provider: string, operation: string);
+}
+
+/**
+ * Normalise a ticker symbol for use with a specific provider.
+ *
+ * Different providers use slightly different conventions:
+ *  - Yahoo Finance:   "BRK-B", "BTC-USD"
+ *  - Alpha Vantage:  "BRKB",  "BTCUSD" (no separator for crypto pairs)
+ *  - Polygon.io:     "BRK/B", "X:BTCUSD"
+ */
+/** Strip exchange suffixes like ".NASDAQ" or ".NYSE" */
+declare function stripExchange(symbol: string): string;
+/** Upper-case and trim a symbol */
+declare function normalise(symbol: string): string;
+/** Convert "BTC/USD" or "BTCUSD" → "BTC-USD" (Yahoo style) */
+declare function toYahooSymbol(symbol: string): string;
+/** Convert "BTC-USD" → "BTCUSD" (Alpha Vantage style for some endpoints) */
+declare function toAlphaVantageSymbol(symbol: string): string;
+/** Convert "BTC-USD" → "X:BTCUSD" for Polygon crypto, else leave as-is */
+declare function toPolygonSymbol(symbol: string): string;
+/** Deduplicate and normalise an array of symbols */
+declare function dedupeSymbols(symbols: string[]): string[];
+
+export { AllProvidersFailedError, AlphaVantageProvider, type AlphaVantageProviderOptions, type AssetType, type CacheConfig, type CacheDriver, type CacheMethod, type CompanyOptions, type CompanyProfile, type HistoricalBar, type HistoricalInterval, type HistoricalOptions, MarketFeed, MarketFeedError, type MarketFeedOptions, type MarketProvider, type MarketStatus, type MarketStatusOptions, MemoryCacheDriver, type NewsItem, type NewsOptions, PolygonProvider, type PolygonProviderOptions, ProviderError, type Quote, type QuoteOptions, RateLimitError, RateLimiter, type SearchOptions, type SearchResult, type TradingSession, UnsupportedOperationError, YahooProvider, type YahooProviderOptions, dedupeSymbols, normalise, stripExchange, toAlphaVantageSymbol, toPolygonSymbol, toYahooSymbol };