opencandle 0.2.0 → 0.4.0

package/src/providers/yahoo-finance.ts

@@ -0,0 +1,367 @@
+import { httpGet } from "../infra/http-client.js";
+import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
+import { rateLimiter } from "../infra/rate-limiter.js";
+import { StealthBrowser } from "../infra/browser.js";
+import type { StockQuote, OHLCV } from "../types/market.js";
+import type { OptionsChain, OptionContract } from "../types/options.js";
+import { computeGreeks } from "../tools/options/greeks.js";
+
+const BASE_URL = "https://query1.finance.yahoo.com/v8/finance/chart";
+
+interface YahooChartResponse {
+  chart: {
+    result: Array<{
+      meta: Record<string, any>;
+      timestamp: number[];
+      indicators: {
+        quote: Array<{
+          open: number[];
+          high: number[];
+          low: number[];
+          close: number[];
+          volume: number[];
+        }>;
+        adjclose?: Array<{ adjclose: number[] }>;
+      };
+    }>;
+    error?: { code: string; description: string };
+  };
+}
+
+export async function getQuote(symbol: string): Promise<StockQuote> {
+  const cacheKey = `yahoo:quote:${symbol}`;
+  const cached = cache.get<StockQuote>(cacheKey);
+  if (cached) return cached;
+
+  try {
+    await rateLimiter.acquire("yahoo");
+
+    const url = `${BASE_URL}/${encodeURIComponent(symbol)}?interval=1d&range=1d`;
+    const data = await httpGet<YahooChartResponse>(url, {
+      headers: { "User-Agent": "OpenCandle/1.0" },
+    });
+
+    if (data.chart.error) {
+      throw new Error(`Yahoo Finance: ${data.chart.error.description}`);
+    }
+
+    const result = data.chart.result[0];
+    const meta = result.meta;
+    const indicators = result.indicators.quote[0];
+
+    const price = meta.regularMarketPrice ?? 0;
+    const prevClose = meta.chartPreviousClose ?? meta.previousClose ?? price;
+    const change = price - prevClose;
+    const changePercent = prevClose !== 0 ? (change / prevClose) * 100 : 0;
+
+    // Open price: try meta first, fall back to indicators
+    const open = meta.regularMarketOpen ?? indicators?.open?.[0] ?? price;
+
+    const quote: StockQuote = {
+      symbol: meta.symbol,
+      price,
+      change,
+      changePercent,
+      open,
+      high: meta.regularMarketDayHigh ?? indicators?.high?.[0] ?? price,
+      low: meta.regularMarketDayLow ?? indicators?.low?.[0] ?? price,
+      previousClose: prevClose,
+      volume: meta.regularMarketVolume ?? 0,
+      marketCap: meta.marketCap ?? 0,
+      pe: null, // Not in chart endpoint
+      week52High: meta.fiftyTwoWeekHigh ?? 0,
+      week52Low: meta.fiftyTwoWeekLow ?? 0,
+      timestamp: Date.now(),
+    };
+
+    cache.set(cacheKey, quote, TTL.QUOTE);
+    return quote;
+  } catch (error) {
+    const stale = cache.getStale<StockQuote>(cacheKey, STALE_LIMIT.QUOTE);
+    if (stale) return stale.value;
+    throw error;
+  }
+}
+
+export async function getHistory(
+  symbol: string,
+  range: string = "6mo",
+  interval: string = "1d",
+): Promise<OHLCV[]> {
+  const cacheKey = `yahoo:history:${symbol}:${range}:${interval}`;
+  const cached = cache.get<OHLCV[]>(cacheKey);
+  if (cached) return cached;
+
+  try {
+    await rateLimiter.acquire("yahoo");
+
+    const url = `${BASE_URL}/${encodeURIComponent(symbol)}?interval=${interval}&range=${range}`;
+    const data = await httpGet<YahooChartResponse>(url, {
+      headers: { "User-Agent": "OpenCandle/1.0" },
+    });
+
+    if (data.chart.error) {
+      throw new Error(`Yahoo Finance: ${data.chart.error.description}`);
+    }
+
+    const result = data.chart.result[0];
+    const timestamps = result.timestamp;
+    const quotes = result.indicators.quote[0];
+
+    const ohlcv: OHLCV[] = timestamps
+      .map((ts, i) => ({
+        date: new Date(ts * 1000).toISOString().split("T")[0],
+        open: quotes.open[i],
+        high: quotes.high[i],
+        low: quotes.low[i],
+        close: quotes.close[i],
+        volume: quotes.volume[i],
+      }))
+      .filter((bar) => bar.open != null && bar.close != null);
+
+    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;
+  }
+}
+
+// --- Options Chain (v7 API with crumb+cookie auth) ---
+
+const BROWSER_UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+
+let cachedCrumb: { crumb: string; cookie: string; expiresAt: number } | null = null;
+
+export function clearCrumbCache(): void {
+  cachedCrumb = null;
+}
+
+export async function getYahooCrumb(): Promise<{ crumb: string; cookie: string }> {
+  if (cachedCrumb && Date.now() < cachedCrumb.expiresAt) {
+    return { crumb: cachedCrumb.crumb, cookie: cachedCrumb.cookie };
+  }
+
+  // Step 1: Hit fc.yahoo.com to get a session cookie
+  const cookieRes = await fetch("https://fc.yahoo.com/t", {
+    headers: { "User-Agent": BROWSER_UA },
+  });
+  const setCookie = cookieRes.headers.get("set-cookie") ?? "";
+  const cookie = setCookie.split(";")[0]; // Extract just the cookie value
+
+  // Step 2: Use the cookie to get a crumb
+  const crumbRes = await fetch("https://query2.finance.yahoo.com/v1/test/getcrumb", {
+    headers: { "User-Agent": BROWSER_UA, Cookie: cookie },
+  });
+  const crumb = await crumbRes.text();
+
+  if (!crumb || crumb.includes("Unauthorized")) {
+    throw new Error("Failed to acquire Yahoo Finance crumb");
+  }
+
+  cachedCrumb = { crumb, cookie, expiresAt: Date.now() + TTL.CRUMB };
+  return { crumb, cookie };
+}
+
+interface YahooOptionsResponse {
+  optionChain: {
+    result: Array<{
+      underlyingSymbol: string;
+      expirationDates: number[];
+      strikes: number[];
+      quote: Record<string, any>;
+      options: Array<{
+        expirationDate: number;
+        calls: any[];
+        puts: any[];
+      }>;
+    }>;
+    error?: any;
+  };
+}
+
+export async function getOptionsChain(
+  symbol: string,
+  expiration?: number,
+): Promise<OptionsChain> {
+  const cacheKey = `yahoo:options:${symbol}:${expiration ?? "nearest"}`;
+  const cached = cache.get<OptionsChain>(cacheKey);
+  if (cached) return cached;
+
+  await rateLimiter.acquire("yahoo");
+
+  const { crumb, cookie } = await getYahooCrumb();
+  const dateParam = expiration ? `&date=${expiration}` : "";
+  const url = `https://query1.finance.yahoo.com/v7/finance/options/${encodeURIComponent(symbol)}?crumb=${encodeURIComponent(crumb)}${dateParam}`;
+
+  let res: Response | null = null;
+  let fetchError: unknown;
+  try {
+    res = await fetch(url, {
+      headers: { "User-Agent": BROWSER_UA, Cookie: cookie },
+    });
+  } catch (error) {
+    fetchError = error;
+  }
+
+  // On 401 or 429, refresh crumb and retry once
+  if (res?.status === 401 || res?.status === 429) {
+    try {
+      clearCrumbCache();
+      const fresh = await getYahooCrumb();
+      const retryUrl = `https://query1.finance.yahoo.com/v7/finance/options/${encodeURIComponent(symbol)}?crumb=${encodeURIComponent(fresh.crumb)}${dateParam}`;
+      res = await fetch(retryUrl, {
+        headers: { "User-Agent": BROWSER_UA, Cookie: fresh.cookie },
+      });
+    } catch (error) {
+      fetchError = error;
+      res = null;
+    }
+  }
+
+  // If still failing, fall back to stealth browser (bypasses TLS fingerprinting)
+  if (!res?.ok) {
+    let browserError: unknown;
+    try {
+      const browserData = await fetchOptionsViaBrowser(symbol, expiration);
+      if (browserData) {
+        const chain = parseOptionsResponse(symbol, browserData);
+        cache.set(cacheKey, chain, TTL.OPTIONS_CHAIN);
+        return chain;
+      }
+    } catch (error) {
+      browserError = error;
+    }
+    // All fetches failed — try stale cache before giving up
+    const stale = cache.getStale<OptionsChain>(cacheKey, STALE_LIMIT.OPTIONS_CHAIN);
+    if (stale) return stale.value;
+    if (res) {
+      const message = `Yahoo Finance options: HTTP ${res.status}`;
+      if (browserError instanceof Error) {
+        throw new Error(`${message}; browser fallback failed: ${browserError.message}`);
+      }
+      throw new Error(message);
+    }
+    if (browserError instanceof Error) {
+      const message = fetchError instanceof Error ? fetchError.message : "Yahoo Finance options: fetch failed";
+      throw new Error(`${message}; browser fallback failed: ${browserError.message}`);
+    }
+    throw fetchError instanceof Error ? fetchError : new Error("Yahoo Finance options: fetch failed");
+  }
+
+  const data: YahooOptionsResponse = await res.json();
+  const chain = parseOptionsResponse(symbol, data);
+  cache.set(cacheKey, chain, TTL.OPTIONS_CHAIN);
+  return chain;
+}
+
+/**
+ * Compute time to expiry in years from a Yahoo expiration timestamp (midnight UTC).
+ * US equity options expire at 4:00 PM ET. During EDT that is 20:00 UTC.
+ * We use 21:00 UTC (4 PM EST / 5 PM EDT) as a conservative close offset
+ * and apply a floor of ~1 hour to prevent numerical instability near expiry.
+ */
+export function computeTimeToExpiry(expirationTs: number, nowMs: number = Date.now()): number {
+  const MARKET_CLOSE_OFFSET_S = 21 * 3600; // 21:00 UTC ≈ 4 PM ET
+  const MIN_TIME_YEARS = 1 / (365 * 24);   // ~1 hour floor
+  const SECONDS_PER_YEAR = 365 * 24 * 3600;
+
+  const expiryCloseTs = expirationTs + MARKET_CLOSE_OFFSET_S;
+  const remainingS = expiryCloseTs - nowMs / 1000;
+
+  if (remainingS <= 0) return 0;
+  return Math.max(MIN_TIME_YEARS, remainingS / SECONDS_PER_YEAR);
+}
+
+function parseOptionsResponse(symbol: string, data: YahooOptionsResponse): OptionsChain {
+  if (data.optionChain.error) {
+    throw new Error(`Yahoo Finance options: ${JSON.stringify(data.optionChain.error)}`);
+  }
+
+  const result = data.optionChain.result[0];
+  const quote = result.quote;
+  const underlyingPrice = quote.regularMarketPrice ?? 0;
+  const opts = result.options[0];
+  const riskFreeRate = 0.05;
+
+  const expirationTs = opts.expirationDate;
+  const expirationDate = new Date(expirationTs * 1000).toISOString().split("T")[0];
+  const timeYears = computeTimeToExpiry(expirationTs);
+
+  const mapContract = (c: any, type: "call" | "put"): OptionContract => {
+    const strike = c.strike ?? c.strike?.raw ?? 0;
+    const iv = c.impliedVolatility ?? c.impliedVolatility?.raw ?? 0;
+    const greeks = computeGreeks({ type, spot: underlyingPrice, strike, timeYears, iv, riskFreeRate });
+    return {
+      contractSymbol: c.contractSymbol ?? "",
+      type,
+      strike,
+      expiration: expirationDate,
+      bid: c.bid ?? c.bid?.raw ?? 0,
+      ask: c.ask ?? c.ask?.raw ?? 0,
+      lastPrice: c.lastPrice ?? c.lastPrice?.raw ?? 0,
+      volume: c.volume ?? c.volume?.raw ?? 0,
+      openInterest: c.openInterest ?? c.openInterest?.raw ?? 0,
+      impliedVolatility: iv,
+      inTheMoney: c.inTheMoney ?? false,
+      greeks,
+    };
+  };
+
+  const calls = (opts.calls ?? []).map((c: any) => mapContract(c, "call"));
+  const puts = (opts.puts ?? []).map((c: any) => mapContract(c, "put"));
+  const totalCallVolume = calls.reduce((s, c) => s + c.volume, 0);
+  const totalPutVolume = puts.reduce((s, c) => s + c.volume, 0);
+
+  return {
+    symbol: result.underlyingSymbol,
+    underlyingPrice,
+    expirationDate,
+    expirationDates: result.expirationDates.map((ts) => new Date(ts * 1000).toISOString().split("T")[0]),
+    calls,
+    puts,
+    totalCallVolume,
+    totalPutVolume,
+    putCallRatio: totalCallVolume > 0 ? totalPutVolume / totalCallVolume : 0,
+    fetchedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Fallback: fetch options data via Camoufox stealth browser.
+ * Bypasses Yahoo's TLS fingerprinting and rate limiting.
+ */
+async function fetchOptionsViaBrowser(
+  symbol: string,
+  expiration?: number,
+): Promise<YahooOptionsResponse | null> {
+  try {
+    // Avoid loading the script-heavy Yahoo Finance homepage: Playwright 1.60
+    // can crash on some pageerror payloads emitted by finance.yahoo.com.
+    // Navigating directly to Yahoo's JSON endpoints still uses the browser's
+    // cookies/TLS fingerprint without requiring cross-origin fetch from page JS.
+    const dateParam = expiration ? `&date=${expiration}` : "";
+    return await StealthBrowser.run(async (page) => {
+      await page.goto("https://query2.finance.yahoo.com/v1/test/getcrumb", {
+        waitUntil: "domcontentloaded",
+        timeout: 15000,
+      });
+      const crumb = (await page.locator("body").innerText()).trim();
+      if (!crumb) return null;
+
+      const url = `https://query1.finance.yahoo.com/v7/finance/options/${encodeURIComponent(symbol)}?crumb=${encodeURIComponent(crumb)}${dateParam}`;
+      const response = await page.goto(url, {
+        waitUntil: "domcontentloaded",
+        timeout: 15000,
+      });
+      if (!response?.ok()) return null;
+
+      const text = (await page.locator("body").innerText()).trim();
+      return JSON.parse(text) as YahooOptionsResponse;
+    });
+  } catch (error) {
+    throw error instanceof Error ? error : new Error(String(error));
+  }
+}

package/src/routing/classify-intent.ts

@@ -0,0 +1,194 @@
+import type { ClassificationResult, WorkflowType, ExtractedEntities } from "./types.js";
+import { extractEntities } from "./entity-extractor.js";
+
+interface Rule {
+  workflow: WorkflowType;
+  test: (input: string, entities: ExtractedEntities) => boolean;
+  confidence: number;
+}
+
+const ANALYSIS_PATTERNS = [
+  /^\s*analyze\s+\$?([A-Za-z]{1,5})\s*$/i,
+  /^\s*full\s+analysis\s+(?:of\s+)?\$?([A-Za-z]{1,5})\s*$/i,
+  /^\s*deep\s+dive\s+(?:on\s+)?\$?([A-Za-z]{1,5})\s*$/i,
+];
+
+const RULES: Rule[] = [
+  // Exact-match analysis patterns (highest priority)
+  {
+    workflow: "single_asset_analysis",
+    confidence: 1.0,
+    test: (input) => ANALYSIS_PATTERNS.some((p) => p.test(input)),
+  },
+  {
+    workflow: "single_asset_analysis",
+    confidence: 0.85,
+    test: (input, entities) => {
+      const lower = input.toLowerCase();
+      return (
+        entities.symbols.length === 1 &&
+        (/\bis\s+\S+\s+(?:attractive|undervalued|overvalued|cheap|expensive)/i.test(lower) ||
+          /\bshould\s+i\s+buy\s+\$?[a-z]{1,5}\b/i.test(lower) ||
+          /\bwhat\s+do\s+you\s+think\s+(?:of|about)\s+\$?[a-z]{1,5}\b/i.test(lower))
+      );
+    },
+  },
+  // News / event queries — symbol or topic + news keywords
+  // Must come before compare_assets to prevent "NVDA and AI chip exports" from
+  // matching as a 2-symbol comparison.
+  {
+    workflow: "general_finance_qa",
+    confidence: 0.9,
+    test: (input) => {
+      const lower = input.toLowerCase();
+      const hasNewsKeyword =
+        /\bnews\b/.test(lower) ||
+        /\blatest\b/.test(lower) ||
+        /\brecent\b/.test(lower) ||
+        /\bhappening\b/.test(lower) ||
+        /\bannouncement/.test(lower) ||
+        /\binvestigation\b/.test(lower) ||
+        /\bregulat/.test(lower) ||
+        /\blawsuit\b/.test(lower) ||
+        /\btariff/.test(lower) ||
+        /\bexport/.test(lower) ||
+        /\bupdate\b/.test(lower);
+      return hasNewsKeyword;
+    },
+  },
+  // Options: symbol + option keyword
+  {
+    workflow: "options_screener",
+    confidence: 0.95,
+    test: (input, entities) => {
+      const lower = input.toLowerCase();
+      const hasOptionKeywords =
+        /\bcalls?\b/.test(lower) ||
+        /\bputs?\b/.test(lower) ||
+        /\boption(?:s)?\s*chain\b/.test(lower) ||
+        /\boptions?\b/.test(lower);
+      return hasOptionKeywords && entities.symbols.length >= 1;
+    },
+  },
+  // Compare: keyword + 2+ symbols (uppercase)
+  {
+    workflow: "compare_assets",
+    confidence: 0.95,
+    test: (input, entities) => {
+      const lower = input.toLowerCase();
+      const hasCompareKeywords =
+        /\bcompare\b/.test(lower) ||
+        /\bvs\.?\b/.test(lower) ||
+        /\bversus\b/.test(lower) ||
+        /\bwhich\s+is\s+better\b/.test(lower);
+      return hasCompareKeywords && entities.symbols.length >= 2;
+    },
+  },
+  // Compare: keyword + lowercase tickers ("Compare aapl and msft")
+  {
+    workflow: "compare_assets",
+    confidence: 0.85,
+    test: (input) => {
+      const lower = input.toLowerCase();
+      return /\bcompare\s+[a-z]{1,5}(?:\s*,?\s*(?:and\s+)?[a-z]{1,5})+/.test(lower);
+    },
+  },
+  // Compare: 2+ uppercase symbols without explicit keyword
+  {
+    workflow: "compare_assets",
+    confidence: 0.8,
+    test: (_input, entities) => entities.symbols.length >= 2,
+  },
+  // Watchlist/tracking: must come before portfolio_builder to catch "show my portfolio"
+  {
+    workflow: "watchlist_or_tracking",
+    confidence: 0.95,
+    test: (input) => {
+      const lower = input.toLowerCase();
+      return (
+        /\bwatchlist\b/.test(lower) ||
+        /\bprediction/i.test(lower) ||
+        /\bshow\s+my\s+portfolio\b/.test(lower) ||
+        /\bmy\s+portfolio\b/.test(lower) ||
+        /\btrack\b/.test(lower)
+      );
+    },
+  },
+  // Portfolio: budget + invest keyword
+  {
+    workflow: "portfolio_builder",
+    confidence: 0.9,
+    test: (input, entities) => {
+      const lower = input.toLowerCase();
+      return (
+        entities.budget !== undefined &&
+        (/\binvest\b/.test(lower) ||
+          /\bportfolio\b/.test(lower) ||
+          /\ballocat/i.test(lower) ||
+          /\bposition/i.test(lower) ||
+          /\bbuy\b/.test(lower))
+      );
+    },
+  },
+  // Portfolio: keyword-only (no budget required)
+  {
+    workflow: "portfolio_builder",
+    confidence: 0.8,
+    test: (input) => {
+      const lower = input.toLowerCase();
+      return (
+        /\bportfolio\b/.test(lower) ||
+        /\bwhat\s+should\s+i\s+(?:invest|buy)\b/.test(lower) ||
+        /\bbuild\s+(?:me\s+)?a?\s*(?:diversified\s+)?.*portfolio\b/.test(lower) ||
+        (/\binvest\s+in\b/.test(lower) && /\bwhat\b/.test(lower))
+      );
+    },
+  },
+  // General finance Q&A
+  {
+    workflow: "general_finance_qa",
+    confidence: 0.85,
+    test: (input) => {
+      const lower = input.toLowerCase();
+      return (
+        /^what\s+(?:is|are|does|do)\b/.test(lower) ||
+        /^how\s+(?:does|do|is|are)\b/.test(lower) ||
+        /^explain\b/.test(lower) ||
+        /^define\b/.test(lower) ||
+        /\bwhat\s+does\s+\S+\s+mean\b/.test(lower)
+      );
+    },
+  },
+];
+
+export function classifyIntent(input: string): ClassificationResult {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return {
+      workflow: "unclassified",
+      confidence: 0,
+      tier: "rule",
+      entities: { symbols: [] },
+    };
+  }
+
+  const entities = extractEntities(trimmed);
+
+  for (const rule of RULES) {
+    if (rule.test(trimmed, entities)) {
+      return {
+        workflow: rule.workflow,
+        confidence: rule.confidence,
+        tier: "rule",
+        entities,
+      };
+    }
+  }
+
+  return {
+    workflow: "unclassified",
+    confidence: 0,
+    tier: "rule",
+    entities,
+  };
+}

package/src/routing/defaults.ts

@@ -0,0 +1,29 @@
+import type { PortfolioSlots, OptionsScreenerSlots } from "./types.js";
+
+export const PORTFOLIO_DEFAULTS: Omit<PortfolioSlots, "budget"> = {
+  riskProfile: "balanced",
+  timeHorizon: "1y_plus",
+  assetScope: "mixed_etf_and_large_cap_equities",
+  positionCount: 4,
+  maxSinglePositionPct: 35,
+};
+
+export const OPTIONS_SCREENER_DEFAULTS: Omit<OptionsScreenerSlots, "symbol" | "direction"> = {
+  dteTarget: "25_to_45_days",
+  objective: "balanced_leverage_and_probability",
+  moneynessPreference: "atm_to_slightly_otm",
+  liquidityMinimum: "high_open_interest_and_tight_spread",
+};
+
+export function parseDteTarget(dteTarget: string): { minDays: number; maxDays: number } | null {
+  const rangeMatch = dteTarget.match(/^(\d+)_to_(\d+)_days$/);
+  if (rangeMatch) {
+    return { minDays: parseInt(rangeMatch[1], 10), maxDays: parseInt(rangeMatch[2], 10) };
+  }
+  const plusMatch = dteTarget.match(/^(\d+)_plus_days$/);
+  if (plusMatch) {
+    const min = parseInt(plusMatch[1], 10);
+    return { minDays: min, maxDays: Math.max(min, 1095) };
+  }
+  return null;
+}