opencandle 0.11.1 → 0.12.0

package/src/providers/alpha-vantage.ts

@@ -1,340 +0,0 @@
-import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
-import { HttpError, httpGet } from "../infra/http-client.js";
-import { rateLimiter } from "../infra/rate-limiter.js";
-import type { CompanyOverview, EarningsData, FinancialStatement } from "../types/fundamentals.js";
-import type { OHLCV, StockQuote } from "../types/market.js";
-import { ProviderCredentialError } from "./provider-credential-error.js";
-
-const BASE_URL = "https://www.alphavantage.co/query";
-const MISSING_OVERVIEW_TTL = 15 * 60_000;
-
-/**
- * Detects authentication failures in HTTP errors and re-throws them as a
- * typed `ProviderCredentialError` so the tool layer can convert them into
- * a `[OPENCANDLE_CREDENTIAL_REQUIRED ...]` tagged content block.
- *
- * Call from every catch block in this module BEFORE any stale-cache fallback
- * so that a real 401/403 does not silently get masked by cached data.
- */
-function throwIfAuthError(error: unknown): void {
-  if (error instanceof HttpError && (error.status === 401 || error.status === 403)) {
-    throw new ProviderCredentialError("alpha_vantage", "stale", error.status);
-  }
-}
-
-function buildUrl(fn: string, params: Record<string, string>, apiKey: string): string {
-  const qs = new URLSearchParams({ function: fn, ...params, apikey: apiKey });
-  return `${BASE_URL}?${qs}`;
-}
-
-function throwIfApiMessage(data: unknown): void {
-  if (!data || typeof data !== "object") return;
-
-  const payload = data as Record<string, unknown>;
-  const message = payload.Note ?? payload.Information ?? payload["Error Message"];
-  if (typeof message !== "string" || message.length === 0) return;
-
-  const normalized = message.toLowerCase();
-  if (normalized.includes("api call frequency") || normalized.includes("rate limit")) {
-    throw new Error(`Alpha Vantage rate limited: ${message}`);
-  }
-  if (normalized.includes("invalid api")) {
-    throw new ProviderCredentialError("alpha_vantage", "stale");
-  }
-  throw new Error(`Alpha Vantage error: ${message}`);
-}
-
-export async function getOverview(symbol: string, apiKey: string): Promise<CompanyOverview> {
-  const cacheKey = `av:overview:${symbol}`;
-  const missingCacheKey = `${cacheKey}:missing`;
-  const cached = cache.get<CompanyOverview>(cacheKey);
-  if (cached) return cached;
-  if (cache.get<string>(missingCacheKey)) {
-    throw new Error(`Alpha Vantage: No data found for ${symbol}`);
-  }
-
-  try {
-    await rateLimiter.acquire("alphavantage");
-
-    const url = buildUrl("OVERVIEW", { symbol }, apiKey);
-    const data = await httpGet<Record<string, string>>(url);
-    throwIfApiMessage(data);
-
-    if (!data.Symbol) {
-      cache.set(missingCacheKey, "missing", MISSING_OVERVIEW_TTL);
-      throw new Error(`Alpha Vantage: No data found for ${symbol}`);
-    }
-
-    const result: CompanyOverview = {
-      symbol: data.Symbol,
-      name: data.Name,
-      description: data.Description,
-      exchange: data.Exchange,
-      sector: data.Sector,
-      industry: data.Industry,
-      marketCap: parseNum(data.MarketCapitalization),
-      pe: parseNullableNum(data.PERatio),
-      forwardPe: parseNullableNum(data.ForwardPE),
-      eps: parseNullableNum(data.EPS),
-      dividendYield: parseNullableNum(data.DividendYield),
-      beta: parseNullableNum(data.Beta),
-      week52High: parseNum(data["52WeekHigh"]),
-      week52Low: parseNum(data["52WeekLow"]),
-      avgVolume: 0, // Alpha Vantage OVERVIEW does not expose average volume
-      profitMargin: parseNullableNum(data.ProfitMargin),
-      revenueGrowth: parseNullableNum(data.QuarterlyRevenueGrowthYOY),
-    };
-
-    cache.set(cacheKey, result, TTL.FUNDAMENTALS);
-    return result;
-  } catch (error) {
-    throwIfAuthError(error);
-    const stale = cache.getStale<CompanyOverview>(cacheKey, STALE_LIMIT.FUNDAMENTALS);
-    if (stale) return stale.value;
-    throw error;
-  }
-}
-
-export async function getEarnings(symbol: string, apiKey: string): Promise<EarningsData> {
-  const cacheKey = `av:earnings:${symbol}`;
-  const cached = cache.get<EarningsData>(cacheKey);
-  if (cached) return cached;
-
-  try {
-    await rateLimiter.acquire("alphavantage");
-
-    const url = buildUrl("EARNINGS", { symbol }, apiKey);
-    const data = await httpGet<{ quarterlyEarnings: any[] }>(url);
-    throwIfApiMessage(data);
-
-    const quarterly = (data.quarterlyEarnings ?? []).slice(0, 8).map((e: any) => ({
-      date: e.fiscalDateEnding,
-      reportedEPS: parseFloat(e.reportedEPS) || 0,
-      estimatedEPS: parseFloat(e.estimatedEPS) || 0,
-      surprise: parseFloat(e.surprise) || 0,
-      surprisePercent: parseFloat(e.surprisePercentage) || 0,
-    }));
-
-    const result: EarningsData = { symbol, quarterly };
-    cache.set(cacheKey, result, TTL.FUNDAMENTALS);
-    return result;
-  } catch (error) {
-    throwIfAuthError(error);
-    const stale = cache.getStale<EarningsData>(cacheKey, STALE_LIMIT.FUNDAMENTALS);
-    if (stale) return stale.value;
-    throw error;
-  }
-}
-
-export async function getFinancials(symbol: string, apiKey: string): Promise<FinancialStatement[]> {
-  const cacheKey = `av:financials:${symbol}`;
-  const cached = cache.get<FinancialStatement[]>(cacheKey);
-  if (cached) return cached;
-
-  try {
-    // Fetch sequentially to respect Alpha Vantage rate limits (5 req/min free tier)
-    const incomeData = await fetchStatement<{ annualReports: any[] }>(
-      "INCOME_STATEMENT",
-      symbol,
-      apiKey,
-    );
-    const balanceData = await fetchStatement<{ annualReports: any[] }>(
-      "BALANCE_SHEET",
-      symbol,
-      apiKey,
-    );
-    const cashFlowData = await fetchStatement<{ annualReports: any[] }>(
-      "CASH_FLOW",
-      symbol,
-      apiKey,
-    );
-
-    const incomeReports = incomeData.annualReports ?? [];
-    const balanceReports = balanceData.annualReports ?? [];
-    const cashFlowReports = cashFlowData.annualReports ?? [];
-
-    // Index balance sheet and cash flow by fiscal date for merging
-    const balanceByDate = new Map(balanceReports.map((r: any) => [r.fiscalDateEnding, r]));
-    const cashFlowByDate = new Map(cashFlowReports.map((r: any) => [r.fiscalDateEnding, r]));
-
-    const statements = incomeReports.slice(0, 4).map((r: any) => {
-      const balance = balanceByDate.get(r.fiscalDateEnding) ?? {};
-      const cf = cashFlowByDate.get(r.fiscalDateEnding) ?? {};
-      const opCashFlow = parseNum(cf.operatingCashflow);
-      const capex = parseNum(cf.capitalExpenditures);
-
-      const totalDebt = parseNum(balance.shortLongTermDebtTotal);
-      const cash = parseNum(balance.cashAndCashEquivalentsAtCarryingValue);
-
-      return {
-        fiscalDate: r.fiscalDateEnding,
-        revenue: parseNum(r.totalRevenue),
-        grossProfit: parseNum(r.grossProfit),
-        operatingIncome: parseNum(r.operatingIncome),
-        netIncome: parseNum(r.netIncome),
-        eps: parseFloat(r.reportedEPS) || 0,
-        totalAssets: parseNum(balance.totalAssets),
-        totalLiabilities: parseNum(balance.totalLiabilities),
-        totalEquity: parseNum(balance.totalShareholderEquity),
-        operatingCashFlow: opCashFlow,
-        freeCashFlow: opCashFlow - capex,
-        totalDebt: totalDebt || undefined,
-        cashAndEquivalents: cash || undefined,
-      };
-    });
-
-    cache.set(cacheKey, statements, TTL.FUNDAMENTALS);
-    return statements;
-  } catch (error) {
-    throwIfAuthError(error);
-    const stale = cache.getStale<FinancialStatement[]>(cacheKey, STALE_LIMIT.FUNDAMENTALS);
-    if (stale) return stale.value;
-    throw error;
-  }
-}
-
-async function fetchStatement<T>(fn: string, symbol: string, apiKey: string): Promise<T> {
-  await rateLimiter.acquire("alphavantage");
-  const url = buildUrl(fn, { symbol }, apiKey);
-  const data = await httpGet<T>(url);
-  throwIfApiMessage(data);
-  return data;
-}
-
-export async function getGlobalQuote(symbol: string, apiKey: string): Promise<StockQuote> {
-  const cacheKey = `av:globalquote:${symbol}`;
-  const cached = cache.get<StockQuote>(cacheKey);
-  if (cached) return cached;
-
-  try {
-    await rateLimiter.acquire("alphavantage");
-
-    const url = buildUrl("GLOBAL_QUOTE", { symbol }, apiKey);
-    const data = await httpGet<{ "Global Quote": Record<string, string> }>(url);
-    throwIfApiMessage(data);
-    const gq = data["Global Quote"];
-
-    if (!gq || !gq["05. price"]) {
-      throw new Error(`Alpha Vantage: No quote data for ${symbol}`);
-    }
-
-    const price = parseFloat(gq["05. price"]) || 0;
-    const result: StockQuote = {
-      symbol: gq["01. symbol"] ?? symbol,
-      price,
-      change: parseFloat(gq["09. change"]) || 0,
-      changePercent: parseFloat(gq["10. change percent"]?.replace("%", "")) || 0,
-      open: parseFloat(gq["02. open"]) || 0,
-      high: parseFloat(gq["03. high"]) || 0,
-      low: parseFloat(gq["04. low"]) || 0,
-      previousClose: parseFloat(gq["08. previous close"]) || 0,
-      volume: parseInt(gq["06. volume"], 10) || 0,
-      marketCap: 0, // Not available from GLOBAL_QUOTE
-      pe: null, // Not available from GLOBAL_QUOTE
-      week52High: 0, // Not available from GLOBAL_QUOTE
-      week52Low: 0, // Not available from GLOBAL_QUOTE
-      timestamp: Date.now(),
-      asOf: dateOnlyValue(gq["07. latest trading day"]),
-    };
-
-    cache.set(cacheKey, result, TTL.QUOTE);
-    return result;
-  } catch (error) {
-    throwIfAuthError(error);
-    const stale = cache.getStale<StockQuote>(cacheKey, STALE_LIMIT.QUOTE);
-    if (stale) return stale.value;
-    throw error;
-  }
-}
-
-function dateOnlyValue(value: string | undefined): string | undefined {
-  if (!value || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return undefined;
-  return value;
-}
-
-export async function getDailyHistory(
-  symbol: string,
-  apiKey: string,
-  range: string = "6mo",
-): Promise<OHLCV[]> {
-  const cacheKey = `av:daily:${symbol}:${range}`;
-  const cached = cache.get<OHLCV[]>(cacheKey);
-  if (cached) return cached;
-
-  try {
-    await rateLimiter.acquire("alphavantage");
-
-    // compact = last 100 data points, full = full 20+ year history
-    const daysNeeded = rangeToDays(range);
-    const outputsize = daysNeeded > 100 ? "full" : "compact";
-    const url = buildUrl("TIME_SERIES_DAILY", { symbol, outputsize }, apiKey);
-    const data = await httpGet<{ "Time Series (Daily)": Record<string, Record<string, string>> }>(
-      url,
-    );
-    throwIfApiMessage(data);
-
-    const timeSeries = data["Time Series (Daily)"];
-    if (!timeSeries) {
-      throw new Error(`Alpha Vantage: No daily history for ${symbol}`);
-    }
-
-    const sorted = Object.entries(timeSeries)
-      .map(([date, bar]) => ({
-        date,
-        open: parseFloat(bar["1. open"]) || 0,
-        high: parseFloat(bar["2. high"]) || 0,
-        low: parseFloat(bar["3. low"]) || 0,
-        close: parseFloat(bar["4. close"]) || 0,
-        volume: parseInt(bar["5. volume"], 10) || 0,
-      }))
-      .sort((a, b) => a.date.localeCompare(b.date));
-
-    // Count-based slicing for ytd is only an estimate (ignores holidays and
-    // the starting weekday) and can leak prior-year bars; filter by date.
-    const ohlcv: OHLCV[] =
-      range === "ytd"
-        ? sorted.filter((bar) => bar.date >= `${new Date().getFullYear()}-01-01`)
-        : sorted.slice(-daysNeeded);
-
-    cache.set(cacheKey, ohlcv, TTL.HISTORY);
-    return ohlcv;
-  } catch (error) {
-    throwIfAuthError(error);
-    const stale = cache.getStale<OHLCV[]>(cacheKey, STALE_LIMIT.HISTORY);
-    if (stale) return stale.value;
-    throw error;
-  }
-}
-
-function rangeToDays(range: string): number {
-  const map: Record<string, number> = {
-    "1d": 1,
-    "5d": 5,
-    "1mo": 22,
-    "3mo": 66,
-    "6mo": 130,
-    "1y": 252,
-    "2y": 504,
-    "5y": 1260,
-    "10y": 2520,
-    max: 5000,
-  };
-  if (range === "ytd") return tradingDaysSinceStartOfYear();
-  return map[range] ?? 130;
-}
-
-function tradingDaysSinceStartOfYear(date = new Date()): number {
-  const start = new Date(date.getFullYear(), 0, 1);
-  const calendarDays = Math.max(1, Math.ceil((date.getTime() - start.getTime()) / 86_400_000) + 1);
-  return Math.max(1, Math.ceil((calendarDays / 7) * 5));
-}
-
-function parseNum(s: string | undefined): number {
-  return parseFloat(s ?? "0") || 0;
-}
-
-function parseNullableNum(s: string | undefined): number | null {
-  if (!s || s === "None" || s === "-") return null;
-  const n = parseFloat(s);
-  return isNaN(n) ? null : n;
-}

package/src/providers/coingecko.ts

@@ -1,95 +0,0 @@
-import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
-import { httpGet } from "../infra/http-client.js";
-import { rateLimiter } from "../infra/rate-limiter.js";
-import type { CryptoPrice, OHLCV } from "../types/market.js";
-
-const BASE_URL = "https://api.coingecko.com/api/v3";
-
-interface CoinGeckoDetailResponse {
-  id: string;
-  symbol: string;
-  name: string;
-  market_data: {
-    current_price: { usd: number };
-    price_change_24h: number;
-    price_change_percentage_24h: number;
-    market_cap: { usd: number };
-    total_volume: { usd: number };
-    high_24h: { usd: number };
-    low_24h: { usd: number };
-    ath: { usd: number };
-    ath_date: { usd: string };
-    last_updated?: string;
-    circulating_supply: number;
-    total_supply: number | null;
-  };
-}
-
-export async function getCryptoPrice(id: string): Promise<CryptoPrice> {
-  const cacheKey = `coingecko:price:${id}`;
-  const cached = cache.get<CryptoPrice>(cacheKey);
-  if (cached) return cached;
-
-  try {
-    await rateLimiter.acquire("coingecko");
-
-    const url = `${BASE_URL}/coins/${encodeURIComponent(id)}?localization=false&tickers=false&community_data=false&developer_data=false`;
-    const data = await httpGet<CoinGeckoDetailResponse>(url);
-
-    const md = data.market_data;
-    const result: CryptoPrice = {
-      id: data.id,
-      symbol: data.symbol,
-      name: data.name,
-      price: md.current_price.usd,
-      change24h: md.price_change_24h,
-      changePercent24h: md.price_change_percentage_24h,
-      marketCap: md.market_cap.usd,
-      volume24h: md.total_volume.usd,
-      high24h: md.high_24h.usd,
-      low24h: md.low_24h.usd,
-      ath: md.ath.usd,
-      athDate: md.ath_date.usd,
-      circulatingSupply: md.circulating_supply,
-      totalSupply: md.total_supply,
-      timestamp: Date.now(),
-      asOf: md.last_updated,
-    };
-
-    cache.set(cacheKey, result, TTL.QUOTE);
-    return result;
-  } catch (error) {
-    const stale = cache.getStale<CryptoPrice>(cacheKey, STALE_LIMIT.QUOTE);
-    if (stale) return stale.value;
-    throw error;
-  }
-}
-
-export async function getCryptoHistory(id: string, days: number = 180): Promise<OHLCV[]> {
-  const cacheKey = `coingecko:history:${id}:${days}`;
-  const cached = cache.get<OHLCV[]>(cacheKey);
-  if (cached) return cached;
-
-  try {
-    await rateLimiter.acquire("coingecko");
-
-    const url = `${BASE_URL}/coins/${encodeURIComponent(id)}/ohlc?vs_currency=usd&days=${days}`;
-    const data = await httpGet<number[][]>(url);
-
-    const ohlcv: OHLCV[] = data.map(([ts, open, high, low, close]) => ({
-      date: new Date(ts).toISOString().split("T")[0],
-      open,
-      high,
-      low,
-      close,
-      volume: 0, // OHLC endpoint doesn't include volume
-    }));
-
-    cache.set(cacheKey, ohlcv, TTL.HISTORY);
-    return ohlcv;
-  } catch (error) {
-    const stale = cache.getStale<OHLCV[]>(cacheKey, STALE_LIMIT.HISTORY);
-    if (stale) return stale.value;
-    throw error;
-  }
-}

package/src/providers/errors.ts

@@ -1,9 +0,0 @@
-export class InvalidSymbolError extends Error {
-  constructor(
-    public readonly symbol: string,
-    public readonly provider: string,
-  ) {
-    super(`Invalid symbol ${symbol} for ${provider}`);
-    this.name = "InvalidSymbolError";
-  }
-}