market-data-analyzer 2.0.0

package/src/utils/api.ts

@@ -0,0 +1,262 @@
+/**
+ * API helpers for Yahoo Finance and CoinGecko free endpoints.
+ *
+ * Yahoo Finance: Uses the v8 finance quote/chart endpoints (publicly accessible).
+ * CoinGecko: Uses the free /api/v3 endpoints (no API key needed, rate-limited).
+ */
+
+import { priceCache } from "./cache.js";
+import type {
+  YahooQuote,
+  YahooChartPoint,
+  CoinGeckoMarketData,
+  CoinGeckoGlobalData,
+} from "../types.js";
+
+// ---------------------------------------------------------------------------
+// User-Agent to avoid blocks
+// ---------------------------------------------------------------------------
+
+const UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+
+async function fetchJSON<T>(url: string): Promise<T> {
+  const res = await fetch(url, {
+    headers: {
+      "User-Agent": UA,
+      Accept: "application/json",
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} from ${url}: ${res.statusText}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+// ---------------------------------------------------------------------------
+// Yahoo Finance helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a quote for one or more symbols via Yahoo Finance v6 quote endpoint.
+ */
+export async function yahooQuote(symbols: string[]): Promise<YahooQuote[]> {
+  const cacheKey = `yq:${symbols.sort().join(",")}`;
+  const cached = priceCache.get<YahooQuote[]>(cacheKey);
+  if (cached) return cached;
+
+  const joined = symbols.join(",");
+  const url = `https://query1.finance.yahoo.com/v6/finance/quote?symbols=${encodeURIComponent(joined)}`;
+
+  try {
+    const data = await fetchJSON<any>(url);
+    const quotes: YahooQuote[] =
+      data?.finance?.result?.[0]?.quotes ??
+      data?.quoteResponse?.result ??
+      [];
+    priceCache.set(cacheKey, quotes);
+    return quotes;
+  } catch {
+    // Fallback: try v7 endpoint
+    const url7 = `https://query1.finance.yahoo.com/v7/finance/quote?symbols=${encodeURIComponent(joined)}`;
+    try {
+      const data = await fetchJSON<any>(url7);
+      const quotes: YahooQuote[] = data?.quoteResponse?.result ?? [];
+      priceCache.set(cacheKey, quotes);
+      return quotes;
+    } catch {
+      // Final fallback: try v8 quote summary for single symbols
+      if (symbols.length === 1) {
+        return [await yahooQuoteSummary(symbols[0])];
+      }
+      throw new Error(`Failed to fetch Yahoo Finance quotes for: ${joined}`);
+    }
+  }
+}
+
+/**
+ * Fallback: v10 quoteSummary for a single symbol.
+ */
+async function yahooQuoteSummary(symbol: string): Promise<YahooQuote> {
+  const url = `https://query1.finance.yahoo.com/v10/finance/quoteSummary/${encodeURIComponent(symbol)}?modules=price,summaryDetail,defaultKeyStatistics`;
+  const data = await fetchJSON<any>(url);
+  const result = data?.quoteSummary?.result?.[0];
+  const price = result?.price ?? {};
+  const summary = result?.summaryDetail ?? {};
+
+  return {
+    symbol: price.symbol ?? symbol,
+    shortName: price.shortName,
+    longName: price.longName,
+    regularMarketPrice: price.regularMarketPrice?.raw,
+    regularMarketChange: price.regularMarketChange?.raw,
+    regularMarketChangePercent: price.regularMarketChangePercent?.raw
+      ? price.regularMarketChangePercent.raw * 100
+      : undefined,
+    regularMarketVolume: price.regularMarketVolume?.raw,
+    regularMarketDayHigh: price.regularMarketDayHigh?.raw,
+    regularMarketDayLow: price.regularMarketDayLow?.raw,
+    regularMarketOpen: price.regularMarketOpen?.raw,
+    regularMarketPreviousClose: price.regularMarketPreviousClose?.raw,
+    fiftyTwoWeekHigh: summary.fiftyTwoWeekHigh?.raw,
+    fiftyTwoWeekLow: summary.fiftyTwoWeekLow?.raw,
+    fiftyDayAverage: summary.fiftyDayAverage?.raw,
+    twoHundredDayAverage: summary.twoHundredDayAverage?.raw,
+    marketCap: price.marketCap?.raw,
+    trailingPE: summary.trailingPE?.raw,
+    forwardPE: summary.forwardPE?.raw,
+    trailingAnnualDividendYield: summary.trailingAnnualDividendYield?.raw,
+  };
+}
+
+/**
+ * Fetch historical chart data from Yahoo Finance.
+ * @param symbol  Ticker symbol
+ * @param range   "1mo", "3mo", "6mo", "1y", "5y"
+ * @param interval "1d", "1wk", "1mo"
+ */
+export async function yahooChart(
+  symbol: string,
+  range: string = "6mo",
+  interval: string = "1d",
+): Promise<YahooChartPoint[]> {
+  const cacheKey = `yc:${symbol}:${range}:${interval}`;
+  const cached = priceCache.get<YahooChartPoint[]>(cacheKey);
+  if (cached) return cached;
+
+  const url = `https://query1.finance.yahoo.com/v8/finance/chart/${encodeURIComponent(symbol)}?range=${range}&interval=${interval}&includePrePost=false`;
+  const data = await fetchJSON<any>(url);
+  const result = data?.chart?.result?.[0];
+  if (!result) {
+    throw new Error(`No chart data returned for ${symbol}`);
+  }
+
+  const timestamps: number[] = result.timestamp ?? [];
+  const ohlcv = result.indicators?.quote?.[0] ?? {};
+  const adjClose = result.indicators?.adjclose?.[0]?.adjclose;
+
+  const points: YahooChartPoint[] = [];
+  for (let i = 0; i < timestamps.length; i++) {
+    const close = adjClose?.[i] ?? ohlcv.close?.[i];
+    if (close == null || ohlcv.open?.[i] == null) continue;
+    points.push({
+      date: timestamps[i],
+      open: ohlcv.open[i],
+      high: ohlcv.high?.[i] ?? ohlcv.open[i],
+      low: ohlcv.low?.[i] ?? ohlcv.open[i],
+      close,
+      volume: ohlcv.volume?.[i] ?? 0,
+    });
+  }
+
+  priceCache.set(cacheKey, points);
+  return points;
+}
+
+/**
+ * Screen stocks using Yahoo Finance's screener or quote list.
+ * Fetches quotes for a predefined set of popular tickers and filters them.
+ */
+export async function yahooScreener(
+  symbols: string[],
+): Promise<YahooQuote[]> {
+  // Batch into groups of 20 to stay within URL limits
+  const results: YahooQuote[] = [];
+  for (let i = 0; i < symbols.length; i += 20) {
+    const batch = symbols.slice(i, i + 20);
+    const quotes = await yahooQuote(batch);
+    results.push(...quotes);
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// CoinGecko helpers
+// ---------------------------------------------------------------------------
+
+const CG_BASE = "https://api.coingecko.com/api/v3";
+
+/**
+ * Fetch market data for one or more coins by ID.
+ */
+export async function coingeckoMarkets(
+  ids: string[],
+  vsCurrency: string = "usd",
+): Promise<CoinGeckoMarketData[]> {
+  const cacheKey = `cg:${ids.sort().join(",")}:${vsCurrency}`;
+  const cached = priceCache.get<CoinGeckoMarketData[]>(cacheKey);
+  if (cached) return cached;
+
+  const url = `${CG_BASE}/coins/markets?vs_currency=${vsCurrency}&ids=${ids.join(",")}&order=market_cap_desc&per_page=100&page=1&sparkline=false&price_change_percentage=7d,30d`;
+  const data = await fetchJSON<CoinGeckoMarketData[]>(url);
+  priceCache.set(cacheKey, data);
+  return data;
+}
+
+/**
+ * Fetch global crypto market data.
+ */
+export async function coingeckoGlobal(): Promise<CoinGeckoGlobalData> {
+  const cacheKey = "cg:global";
+  const cached = priceCache.get<CoinGeckoGlobalData>(cacheKey);
+  if (cached) return cached;
+
+  const data = await fetchJSON<{ data: CoinGeckoGlobalData }>(`${CG_BASE}/global`);
+  priceCache.set(cacheKey, data.data);
+  return data.data;
+}
+
+/**
+ * Map common symbols to CoinGecko IDs.
+ */
+export function symbolToCoinGeckoId(symbol: string): string {
+  const map: Record<string, string> = {
+    BTC: "bitcoin",
+    ETH: "ethereum",
+    SOL: "solana",
+    BNB: "binancecoin",
+    XRP: "ripple",
+    ADA: "cardano",
+    DOGE: "dogecoin",
+    DOT: "polkadot",
+    AVAX: "avalanche-2",
+    MATIC: "matic-network",
+    LINK: "chainlink",
+    UNI: "uniswap",
+    ATOM: "cosmos",
+    LTC: "litecoin",
+    NEAR: "near",
+    APT: "aptos",
+    ARB: "arbitrum",
+    OP: "optimism",
+    SUI: "sui",
+    TRX: "tron",
+    SHIB: "shiba-inu",
+    PEPE: "pepe",
+  };
+  const upper = symbol.toUpperCase().replace("-USD", "").replace("USD", "");
+  return map[upper] ?? symbol.toLowerCase();
+}
+
+// ---------------------------------------------------------------------------
+// Popular stock symbols for screening
+// ---------------------------------------------------------------------------
+
+export const POPULAR_SYMBOLS = [
+  // Mega-cap tech
+  "AAPL", "MSFT", "NVDA", "GOOGL", "AMZN", "META", "TSLA", "AVGO", "TSM", "ORCL",
+  // More tech
+  "CRM", "AMD", "INTC", "ADBE", "NFLX", "CSCO", "QCOM", "TXN", "AMAT", "NOW",
+  // Financials
+  "JPM", "V", "MA", "BAC", "GS", "MS", "BRK-B", "AXP", "BLK", "SCHW",
+  // Healthcare
+  "UNH", "JNJ", "LLY", "PFE", "ABBV", "MRK", "TMO", "ABT", "DHR", "BMY",
+  // Consumer
+  "WMT", "PG", "KO", "PEP", "COST", "MCD", "NKE", "HD", "LOW", "SBUX",
+  // Energy
+  "XOM", "CVX", "COP", "SLB", "EOG",
+  // Industrials
+  "CAT", "GE", "UNP", "HON", "BA", "RTX", "DE", "LMT",
+  // Other
+  "DIS", "NEE", "AMT", "PLD", "LIN", "SPGI",
+];

package/src/utils/cache.ts

@@ -0,0 +1,65 @@
+/**
+ * In-memory cache with configurable TTL.
+ * Default TTL is 5 minutes (300_000 ms) for price data.
+ */
+
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+}
+
+export class MemoryCache {
+  private store = new Map<string, CacheEntry<unknown>>();
+  private defaultTTL: number;
+
+  constructor(defaultTTLMs: number = 300_000) {
+    this.defaultTTL = defaultTTLMs;
+  }
+
+  get<T>(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value as T;
+  }
+
+  set<T>(key: string, value: T, ttlMs?: number): void {
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + (ttlMs ?? this.defaultTTL),
+    });
+  }
+
+  has(key: string): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  delete(key: string): void {
+    this.store.delete(key);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  /** Remove all expired entries. */
+  prune(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  get size(): number {
+    this.prune();
+    return this.store.size;
+  }
+}
+
+/** Shared price cache instance -- 5 minute TTL */
+export const priceCache = new MemoryCache(300_000);

package/src/utils/math.ts

@@ -0,0 +1,332 @@
+/**
+ * Financial math utilities -- technical indicators, risk metrics, etc.
+ * Pure functions with no external dependencies.
+ */
+
+// ---------------------------------------------------------------------------
+// Basic statistics
+// ---------------------------------------------------------------------------
+
+export function mean(values: number[]): number {
+  if (values.length === 0) return 0;
+  return values.reduce((s, v) => s + v, 0) / values.length;
+}
+
+export function stdDev(values: number[]): number {
+  if (values.length < 2) return 0;
+  const m = mean(values);
+  const variance = values.reduce((s, v) => s + (v - m) ** 2, 0) / values.length;
+  return Math.sqrt(variance);
+}
+
+export function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = (p / 100) * (sorted.length - 1);
+  const lower = Math.floor(idx);
+  const upper = Math.ceil(idx);
+  if (lower === upper) return sorted[lower];
+  const frac = idx - lower;
+  return sorted[lower] * (1 - frac) + sorted[upper] * frac;
+}
+
+export function pricesToReturns(prices: number[]): number[] {
+  const returns: number[] = [];
+  for (let i = 1; i < prices.length; i++) {
+    if (prices[i - 1] !== 0) {
+      returns.push((prices[i] - prices[i - 1]) / prices[i - 1]);
+    }
+  }
+  return returns;
+}
+
+export function correlation(a: number[], b: number[]): number {
+  const n = Math.min(a.length, b.length);
+  if (n < 2) return 0;
+  const ma = mean(a.slice(0, n));
+  const mb = mean(b.slice(0, n));
+  let sumAB = 0, sumA2 = 0, sumB2 = 0;
+  for (let i = 0; i < n; i++) {
+    const da = a[i] - ma;
+    const db = b[i] - mb;
+    sumAB += da * db;
+    sumA2 += da * da;
+    sumB2 += db * db;
+  }
+  const denom = Math.sqrt(sumA2 * sumB2);
+  return denom > 0 ? sumAB / denom : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Moving averages
+// ---------------------------------------------------------------------------
+
+export function sma(values: number[], period: number): (number | null)[] {
+  const result: (number | null)[] = [];
+  for (let i = 0; i < values.length; i++) {
+    if (i < period - 1) {
+      result.push(null);
+    } else {
+      let sum = 0;
+      for (let j = i - period + 1; j <= i; j++) sum += values[j];
+      result.push(sum / period);
+    }
+  }
+  return result;
+}
+
+export function ema(values: number[], period: number): (number | null)[] {
+  const result: (number | null)[] = [];
+  const multiplier = 2 / (period + 1);
+  let prev: number | null = null;
+
+  for (let i = 0; i < values.length; i++) {
+    if (i < period - 1) {
+      result.push(null);
+    } else if (prev === null) {
+      let sum = 0;
+      for (let j = i - period + 1; j <= i; j++) sum += values[j];
+      prev = sum / period;
+      result.push(prev);
+    } else {
+      prev = (values[i] - prev) * multiplier + prev;
+      result.push(prev);
+    }
+  }
+  return result;
+}
+
+/** Get the latest non-null value from an indicator series. */
+export function lastValue(series: (number | null)[]): number | null {
+  for (let i = series.length - 1; i >= 0; i--) {
+    if (series[i] !== null) return series[i];
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// RSI (Relative Strength Index)
+// ---------------------------------------------------------------------------
+
+export function rsi(closes: number[], period: number = 14): (number | null)[] {
+  if (closes.length < period + 1) return closes.map(() => null);
+
+  const result: (number | null)[] = [null];
+  const gains: number[] = [];
+  const losses: number[] = [];
+
+  for (let i = 1; i < closes.length; i++) {
+    const change = closes[i] - closes[i - 1];
+    gains.push(change > 0 ? change : 0);
+    losses.push(change < 0 ? -change : 0);
+  }
+
+  let avgGain = 0;
+  let avgLoss = 0;
+
+  // Initial averages
+  for (let i = 0; i < period; i++) {
+    avgGain += gains[i];
+    avgLoss += losses[i];
+  }
+  avgGain /= period;
+  avgLoss /= period;
+
+  for (let i = 0; i < gains.length; i++) {
+    if (i < period - 1) {
+      result.push(null);
+    } else if (i === period - 1) {
+      if (avgLoss === 0) {
+        result.push(100);
+      } else {
+        result.push(100 - 100 / (1 + avgGain / avgLoss));
+      }
+    } else {
+      // Wilder smoothing
+      avgGain = (avgGain * (period - 1) + gains[i]) / period;
+      avgLoss = (avgLoss * (period - 1) + losses[i]) / period;
+      if (avgLoss === 0) {
+        result.push(100);
+      } else {
+        result.push(100 - 100 / (1 + avgGain / avgLoss));
+      }
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// MACD
+// ---------------------------------------------------------------------------
+
+export interface MACDResult {
+  line: (number | null)[];
+  signal: (number | null)[];
+  histogram: (number | null)[];
+}
+
+export function macd(
+  closes: number[],
+  fastPeriod = 12,
+  slowPeriod = 26,
+  signalPeriod = 9,
+): MACDResult {
+  const fastEma = ema(closes, fastPeriod);
+  const slowEma = ema(closes, slowPeriod);
+
+  const macdLine: (number | null)[] = [];
+  for (let i = 0; i < closes.length; i++) {
+    if (fastEma[i] !== null && slowEma[i] !== null) {
+      macdLine.push(fastEma[i]! - slowEma[i]!);
+    } else {
+      macdLine.push(null);
+    }
+  }
+
+  // Signal line = EMA of MACD line
+  const nonNull: number[] = [];
+  const nonNullIdx: number[] = [];
+  for (let i = 0; i < macdLine.length; i++) {
+    if (macdLine[i] !== null) {
+      nonNull.push(macdLine[i]!);
+      nonNullIdx.push(i);
+    }
+  }
+
+  const sigEma = ema(nonNull, signalPeriod);
+  const signalLine: (number | null)[] = new Array(closes.length).fill(null);
+  for (let i = 0; i < nonNullIdx.length; i++) {
+    signalLine[nonNullIdx[i]] = sigEma[i];
+  }
+
+  const histogram: (number | null)[] = [];
+  for (let i = 0; i < closes.length; i++) {
+    if (macdLine[i] !== null && signalLine[i] !== null) {
+      histogram.push(macdLine[i]! - signalLine[i]!);
+    } else {
+      histogram.push(null);
+    }
+  }
+
+  return { line: macdLine, signal: signalLine, histogram };
+}
+
+// ---------------------------------------------------------------------------
+// Support / Resistance (pivot-based)
+// ---------------------------------------------------------------------------
+
+export function findSupportResistance(
+  highs: number[],
+  lows: number[],
+  closes: number[],
+  lookback: number = 20,
+): { support: number[]; resistance: number[] } {
+  const support: number[] = [];
+  const resistance: number[] = [];
+
+  if (closes.length < lookback) {
+    return { support: [], resistance: [] };
+  }
+
+  const currentPrice = closes[closes.length - 1];
+
+  // Find local minima (support) and maxima (resistance)
+  const windowSize = Math.max(5, Math.floor(lookback / 4));
+  for (let i = windowSize; i < closes.length - windowSize; i++) {
+    let isLocalMin = true;
+    let isLocalMax = true;
+
+    for (let j = i - windowSize; j <= i + windowSize; j++) {
+      if (j === i) continue;
+      if (lows[j] < lows[i]) isLocalMin = false;
+      if (highs[j] > highs[i]) isLocalMax = false;
+    }
+
+    if (isLocalMin && lows[i] < currentPrice) {
+      support.push(Math.round(lows[i] * 100) / 100);
+    }
+    if (isLocalMax && highs[i] > currentPrice) {
+      resistance.push(Math.round(highs[i] * 100) / 100);
+    }
+  }
+
+  // Deduplicate: merge levels within 1% of each other
+  const dedup = (levels: number[]): number[] => {
+    if (levels.length === 0) return [];
+    levels.sort((a, b) => a - b);
+    const merged: number[] = [levels[0]];
+    for (let i = 1; i < levels.length; i++) {
+      const last = merged[merged.length - 1];
+      if (Math.abs(levels[i] - last) / last < 0.01) {
+        merged[merged.length - 1] = (last + levels[i]) / 2;
+      } else {
+        merged.push(levels[i]);
+      }
+    }
+    return merged;
+  };
+
+  // Return closest 3 levels each
+  const dedupedSupport = dedup(support).sort((a, b) => b - a).slice(0, 3);
+  const dedupedResistance = dedup(resistance).sort((a, b) => a - b).slice(0, 3);
+
+  return { support: dedupedSupport, resistance: dedupedResistance };
+}
+
+// ---------------------------------------------------------------------------
+// Max drawdown
+// ---------------------------------------------------------------------------
+
+export function maxDrawdown(prices: number[]): number {
+  if (prices.length < 2) return 0;
+  let peak = prices[0];
+  let worst = 0;
+  for (const p of prices) {
+    if (p > peak) peak = p;
+    const dd = (peak - p) / peak;
+    if (dd > worst) worst = dd;
+  }
+  return worst;
+}
+
+// ---------------------------------------------------------------------------
+// Sharpe ratio approximation
+// ---------------------------------------------------------------------------
+
+const TRADING_DAYS = 252;
+const DEFAULT_RISK_FREE_RATE = 0.045; // ~4.5% annualized
+
+export function sharpeRatio(
+  returns: number[],
+  riskFreeRate: number = DEFAULT_RISK_FREE_RATE,
+): number {
+  if (returns.length < 2) return 0;
+  const dailyRfr = riskFreeRate / TRADING_DAYS;
+  const avgReturn = mean(returns);
+  const vol = stdDev(returns);
+  if (vol === 0) return 0;
+  return ((avgReturn - dailyRfr) / vol) * Math.sqrt(TRADING_DAYS);
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+export function formatCurrency(n: number): string {
+  if (Math.abs(n) >= 1e12) return `$${(n / 1e12).toFixed(2)}T`;
+  if (Math.abs(n) >= 1e9) return `$${(n / 1e9).toFixed(2)}B`;
+  if (Math.abs(n) >= 1e6) return `$${(n / 1e6).toFixed(2)}M`;
+  return `$${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+export function formatVolume(n: number): string {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return n.toString();
+}
+
+export function formatPct(n: number, decimals: number = 2): string {
+  const sign = n >= 0 ? "+" : "";
+  return `${sign}${(n * 100).toFixed(decimals)}%`;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}