opencandle 0.5.0 → 0.6.0

package/src/providers/yahoo-finance.ts

@@ -1,14 +1,23 @@
-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, OptionsMarketSession, OptionsQuoteStatus } from "../types/options.js";
-import type { FundHoldings } from "../types/portfolio.js";
+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 { computeGreeks } from "../tools/options/greeks.js";
+import type { OHLCV, StockQuote } from "../types/market.js";
+import type {
+  OptionContract,
+  OptionsChain,
+  OptionsMarketSession,
+  OptionsQuoteStatus,
+} from "../types/options.js";
+import type { FundHoldings } from "../types/portfolio.js";
+import { InvalidSymbolError } from "./errors.js";
 
 const BASE_URL = "https://query1.finance.yahoo.com/v8/finance/chart";
 const QUOTE_SUMMARY_URL = "https://query1.finance.yahoo.com/v10/finance/quoteSummary";
+const STALE_QUOTE_MAX_RETRY_AFTER_MS = 1_000;
+
+type YahooNumber = number | { raw?: number; fmt?: string };
 
 interface YahooChartResponse {
   chart: {
@@ -42,10 +51,10 @@ interface YahooQuoteSummaryResponse {
         holdings?: Array<{
           symbol?: string;
           holdingName?: string;
-          holdingPercent?: number;
+          holdingPercent?: YahooNumber;
         }>;
         equityHoldings?: {
-          sectorWeightings?: Array<Record<string, number>>;
+          sectorWeightings?: Array<Record<string, YahooNumber>>;
         };
       };
     }>;
@@ -64,6 +73,7 @@ export async function getQuote(symbol: string): Promise<StockQuote> {
     const url = `${BASE_URL}/${encodeURIComponent(symbol)}?interval=1d&range=1d`;
     const data = await httpGet<YahooChartResponse>(url, {
       headers: { "User-Agent": "OpenCandle/1.0" },
+      maxRetryAfterMs: STALE_QUOTE_MAX_RETRY_AFTER_MS,
     });
 
     if (data.chart.error) {
@@ -97,8 +107,16 @@ export async function getQuote(symbol: string): Promise<StockQuote> {
       week52High: meta.fiftyTwoWeekHigh ?? 0,
       week52Low: meta.fiftyTwoWeekLow ?? 0,
       timestamp: Date.now(),
+      currency:
+        typeof meta.currency === "string" && meta.currency.trim() !== ""
+          ? meta.currency.trim().toUpperCase()
+          : null,
     };
 
+    if (isZeroResultQuote(quote)) {
+      throw new InvalidSymbolError(symbol.toUpperCase(), "yahoo");
+    }
+
     cache.set(cacheKey, quote, TTL.QUOTE);
     return quote;
   } catch (error) {
@@ -108,6 +126,16 @@ export async function getQuote(symbol: string): Promise<StockQuote> {
   }
 }
 
+function isZeroResultQuote(quote: StockQuote): boolean {
+  return (
+    quote.price === 0 &&
+    quote.volume === 0 &&
+    quote.week52High === 0 &&
+    quote.week52Low === 0 &&
+    quote.marketCap === 0
+  );
+}
+
 export async function getHistory(
   symbol: string,
   range: string = "6mo",
@@ -162,14 +190,12 @@ export async function getFundHoldings(symbol: string): Promise<FundHoldings> {
   try {
     await rateLimiter.acquire("yahoo");
 
-    const modules = encodeURIComponent("price,topHoldings");
-    const url = `${QUOTE_SUMMARY_URL}/${encodeURIComponent(normalizedSymbol)}?modules=${modules}`;
-    const data = await httpGet<YahooQuoteSummaryResponse>(url, {
-      headers: { "User-Agent": "OpenCandle/1.0" },
-    });
+    const data = await getFundHoldingsSummary(normalizedSymbol);
     const result = data.quoteSummary.result?.[0];
     if (data.quoteSummary.error) {
-      throw new Error(`Yahoo Finance: ${data.quoteSummary.error.description ?? data.quoteSummary.error.code ?? "quoteSummary error"}`);
+      throw new Error(
+        `Yahoo Finance: ${data.quoteSummary.error.description ?? data.quoteSummary.error.code ?? "quoteSummary error"}`,
+      );
     }
     if (!result?.topHoldings?.holdings?.length) {
       throw new Error(`Yahoo Finance: no fund holdings returned for ${normalizedSymbol}`);
@@ -183,11 +209,13 @@ export async function getFundHoldings(symbol: string): Promise<FundHoldings> {
         const holdingSymbol = holding.symbol?.trim().toUpperCase();
         const weight = normalizeHoldingWeight(holding.holdingPercent);
         if (!holdingSymbol || weight === undefined) return [];
-        return [{
-          symbol: holdingSymbol,
-          name: holding.holdingName?.trim() || holdingSymbol,
-          weight,
-        }];
+        return [
+          {
+            symbol: holdingSymbol,
+            name: holding.holdingName?.trim() || holdingSymbol,
+            weight,
+          },
+        ];
       }),
       sectorWeights: normalizeSectorWeights(result.topHoldings.equityHoldings?.sectorWeightings),
     };
@@ -204,13 +232,56 @@ export async function getFundHoldings(symbol: string): Promise<FundHoldings> {
   }
 }
 
-function normalizeHoldingWeight(value: number | undefined): number | undefined {
-  if (value === undefined || !Number.isFinite(value) || value <= 0) return undefined;
-  return value > 1 ? roundWeight(value / 100) : roundWeight(value);
+async function getFundHoldingsSummary(symbol: string): Promise<YahooQuoteSummaryResponse> {
+  try {
+    return await fetchFundHoldingsSummary(symbol);
+  } catch (error) {
+    if (!isYahooAuthError(error)) throw error;
+    return fetchFundHoldingsSummaryWithCrumb(symbol);
+  }
+}
+
+async function fetchFundHoldingsSummary(symbol: string): Promise<YahooQuoteSummaryResponse> {
+  const modules = encodeURIComponent("price,topHoldings");
+  const url = `${QUOTE_SUMMARY_URL}/${encodeURIComponent(symbol)}?modules=${modules}`;
+  return httpGet<YahooQuoteSummaryResponse>(url, {
+    headers: { "User-Agent": "OpenCandle/1.0" },
+  });
+}
+
+async function fetchFundHoldingsSummaryWithCrumb(
+  symbol: string,
+): Promise<YahooQuoteSummaryResponse> {
+  const modules = encodeURIComponent("price,topHoldings");
+  const { crumb, cookie } = await getYahooCrumb();
+  const url = `${QUOTE_SUMMARY_URL}/${encodeURIComponent(symbol)}?modules=${modules}&crumb=${encodeURIComponent(crumb)}`;
+  try {
+    return await httpGet<YahooQuoteSummaryResponse>(url, {
+      headers: { "User-Agent": BROWSER_UA, Cookie: cookie },
+    });
+  } catch (error) {
+    if (!isYahooAuthError(error)) throw error;
+    clearCrumbCache();
+    const fresh = await getYahooCrumb();
+    const retryUrl = `${QUOTE_SUMMARY_URL}/${encodeURIComponent(symbol)}?modules=${modules}&crumb=${encodeURIComponent(fresh.crumb)}`;
+    return httpGet<YahooQuoteSummaryResponse>(retryUrl, {
+      headers: { "User-Agent": BROWSER_UA, Cookie: fresh.cookie },
+    });
+  }
+}
+
+function isYahooAuthError(error: unknown): boolean {
+  return error instanceof HttpError && (error.status === 401 || error.status === 429);
+}
+
+function normalizeHoldingWeight(value: YahooNumber | undefined): number | undefined {
+  const numeric = typeof value === "number" ? value : value?.raw;
+  if (numeric === undefined || !Number.isFinite(numeric) || numeric <= 0) return undefined;
+  return numeric > 1 ? roundWeight(numeric / 100) : roundWeight(numeric);
 }
 
 function normalizeSectorWeights(
-  sectors: Array<Record<string, number>> | undefined,
+  sectors: Array<Record<string, YahooNumber>> | undefined,
 ): Record<string, number> | undefined {
   if (!sectors?.length) return undefined;
   const weights: Record<string, number> = {};
@@ -231,6 +302,7 @@ function roundWeight(value: number): number {
 
 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";
+const YAHOO_RAW_FETCH_TIMEOUT_MS = 10_000;
 
 let cachedCrumb: { crumb: string; cookie: string; expiresAt: number } | null = null;
 
@@ -246,15 +318,30 @@ export async function getYahooCrumb(): Promise<{ crumb: string; cookie: string }
   // 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 },
+    signal: yahooRawFetchSignal(),
   });
   const setCookie = cookieRes.headers.get("set-cookie") ?? "";
   const cookie = setCookie.split(";")[0]; // Extract just the cookie value
+  if (!cookie) {
+    if (!cookieRes.ok) {
+      throw new Error(
+        `Yahoo crumb cookie request failed: HTTP ${cookieRes.status} ${cookieRes.statusText}`.trim(),
+      );
+    }
+    throw new Error("Yahoo crumb cookie request did not return a session cookie");
+  }
 
   // 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 },
+    signal: yahooRawFetchSignal(),
   });
-  const crumb = await crumbRes.text();
+  if (!crumbRes.ok) {
+    throw new Error(
+      `Yahoo crumb request failed: HTTP ${crumbRes.status} ${crumbRes.statusText}`.trim(),
+    );
+  }
+  const crumb = (await crumbRes.text()).trim();
 
   if (!crumb || crumb.includes("Unauthorized")) {
     throw new Error("Failed to acquire Yahoo Finance crumb");
@@ -281,25 +368,23 @@ interface YahooOptionsResponse {
   };
 }
 
-export async function getOptionsChain(
-  symbol: string,
-  expiration?: number,
-): Promise<OptionsChain> {
+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 {
+    const { crumb, cookie } = await getYahooCrumb();
+    const url = `https://query1.finance.yahoo.com/v7/finance/options/${encodeURIComponent(symbol)}?crumb=${encodeURIComponent(crumb)}${dateParam}`;
     res = await fetch(url, {
       headers: { "User-Agent": BROWSER_UA, Cookie: cookie },
+      signal: yahooRawFetchSignal(),
     });
   } catch (error) {
     fetchError = error;
@@ -313,6 +398,7 @@ export async function getOptionsChain(
       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 },
+        signal: yahooRawFetchSignal(),
       });
     } catch (error) {
       fetchError = error;
@@ -344,10 +430,13 @@ export async function getOptionsChain(
       throw new Error(message);
     }
     if (browserError instanceof Error) {
-      const message = fetchError instanceof Error ? fetchError.message : "Yahoo Finance options: fetch failed";
+      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");
+    throw fetchError instanceof Error
+      ? fetchError
+      : new Error("Yahoo Finance options: fetch failed");
   }
 
   const data: YahooOptionsResponse = await res.json();
@@ -356,6 +445,10 @@ export async function getOptionsChain(
   return chain;
 }
 
+function yahooRawFetchSignal(): AbortSignal {
+  return AbortSignal.timeout(YAHOO_RAW_FETCH_TIMEOUT_MS);
+}
+
 /**
  * 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.
@@ -364,7 +457,7 @@ export async function getOptionsChain(
  */
 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 MIN_TIME_YEARS = 1 / (365 * 24); // ~1 hour floor
   const SECONDS_PER_YEAR = 365 * 24 * 3600;
 
   const expiryCloseTs = expirationTs + MARKET_CLOSE_OFFSET_S;
@@ -449,6 +542,9 @@ function parseOptionsResponse(data: YahooOptionsResponse): OptionsChain {
   const quote = result.quote;
   const underlyingPrice = quote.regularMarketPrice ?? 0;
   const opts = result.options[0];
+  if (!opts && underlyingPrice === 0) {
+    throw new InvalidSymbolError(result.underlyingSymbol, "yahoo");
+  }
   const riskFreeRate = 0.05;
 
   const expirationTs = opts.expirationDate;
@@ -458,7 +554,14 @@ function parseOptionsResponse(data: YahooOptionsResponse): OptionsChain {
   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 });
+    const greeks = computeGreeks({
+      type,
+      spot: underlyingPrice,
+      strike,
+      timeYears,
+      iv,
+      riskFreeRate,
+    });
     return {
       contractSymbol: c.contractSymbol ?? "",
       type,
@@ -485,7 +588,9 @@ function parseOptionsResponse(data: YahooOptionsResponse): OptionsChain {
     symbol: result.underlyingSymbol,
     underlyingPrice,
     expirationDate,
-    expirationDates: result.expirationDates.map((ts) => new Date(ts * 1000).toISOString().split("T")[0]),
+    expirationDates: result.expirationDates.map(
+      (ts) => new Date(ts * 1000).toISOString().split("T")[0],
+    ),
     calls,
     puts,
     totalCallVolume,

package/src/routing/classify-intent.ts

@@ -1,5 +1,5 @@
-import type { ClassificationResult, WorkflowType, ExtractedEntities } from "./types.js";
 import { extractEntities } from "./entity-extractor.js";
+import type { ClassificationResult, ExtractedEntities, WorkflowType } from "./types.js";
 
 interface Rule {
   workflow: WorkflowType;
@@ -43,7 +43,9 @@ const RULES: Rule[] = [
       return (
         entities.symbols.length >= 1 &&
         (/\bi\s+own\b/.test(lower) || /\bmy\s+holdings\b/.test(lower)) &&
-        (/\bportfolio\s+risk\b/.test(lower) || /\bbiggest\s+risk\b/.test(lower) || /\bconcentration\b/.test(lower))
+        (/\bportfolio\s+risk\b/.test(lower) ||
+          /\bbiggest\s+risk\b/.test(lower) ||
+          /\bconcentration\b/.test(lower))
       );
     },
   },
@@ -91,9 +93,7 @@ const RULES: Rule[] = [
       if (hasCompareKeywords && entities.symbols.length >= 2) return false;
 
       return (
-        /\bbacktest\b/.test(lower) ||
-        /\bsentiment\b/.test(lower) ||
-        /\brate\s+cuts?\b/.test(lower)
+        /\bbacktest\b/.test(lower) || /\bsentiment\b/.test(lower) || /\brate\s+cuts?\b/.test(lower)
       );
     },
   },
@@ -145,6 +145,14 @@ const RULES: Rule[] = [
       return hasOptionKeywords && entities.symbols.length >= 1;
     },
   },
+  // Stateful portfolio/watchlist/alert/prediction mutations must not be
+  // mistaken for compare or portfolio-construction workflows just because a
+  // cost basis, target, or currency token is present.
+  {
+    workflow: "watchlist_or_tracking",
+    confidence: 0.95,
+    test: (input) => isStatefulTrackingRequest(input),
+  },
   // Compare: keyword + 2+ symbols (uppercase)
   {
     workflow: "compare_assets",
@@ -165,8 +173,10 @@ const RULES: Rule[] = [
     confidence: 0.85,
     test: (input, entities) => {
       const lower = input.toLowerCase();
-      return entities.symbols.length >= 2 &&
-        /\bcompare\s+[a-z]{1,5}\b(?:\s*,?\s*(?:and\s+)?[a-z]{1,5}\b)+/.test(lower);
+      return (
+        entities.symbols.length >= 2 &&
+        /\bcompare\s+[a-z]{1,5}\b(?:\s*,?\s*(?:and\s+)?[a-z]{1,5}\b)+/.test(lower)
+      );
     },
   },
   // Compare: 2+ uppercase symbols without explicit keyword
@@ -275,11 +285,92 @@ export function classifyIntent(input: string): ClassificationResult {
 function isPortfolioEvaluationRequest(input: string): boolean {
   const lower = input.toLowerCase();
   const hasEvaluationIntent =
-    /\b(?:evaluat(?:e|ion)|review|assess|analy[sz]e|prospects?|risks?|opportunities?|mitigat(?:e|ion)|adjustment)\b/.test(lower);
+    /\b(?:evaluat(?:e|ion)|review|assess|analy[sz]e|prospects?|risks?|opportunities?|mitigat(?:e|ion)|adjustment)\b/.test(
+      lower,
+    );
   const hasPortfolioObject =
-    /\b(?:portfolio|allocation|asset\s+allocation|60\/40|equity|fixed\s+income|bonds?)\b/.test(lower);
+    /\b(?:portfolio|allocation|asset\s+allocation|60\/40|equity|fixed\s+income|bonds?)\b/.test(
+      lower,
+    );
   const hasConstructionIntent =
     /\b(?:build|create|construct|put\s+together|invest|allocate)\b/.test(lower) &&
-    (/\$\s*\d|\b\d+(?:\.\d+)?\s*k\b|\bbudget\b|\bcapital\b/.test(lower));
+    /\$\s*\d|\b\d+(?:\.\d+)?\s*k\b|\bbudget\b|\bcapital\b/.test(lower);
   return hasEvaluationIntent && hasPortfolioObject && !hasConstructionIntent;
 }
+
+function isStatefulTrackingRequest(input: string): boolean {
+  const lower = input.toLowerCase();
+  const hasPortfolioConstructionIntent =
+    /\b(?:build|create|construct|put\s+together)\b/.test(lower) &&
+    /\bportfolio\b/.test(lower) &&
+    /\$\s*\d|\b\d+(?:\.\d+)?\s*k\b|\bbudget\b|\bcapital\b/.test(lower);
+  const hasStateVerb =
+    /\b(?:add|remove|update|record|track|create|configure|check|show|list|view|cancel)\b/.test(
+      lower,
+    );
+  const hasStateObject =
+    /\b(?:watchlist|portfolio|holding|holdings|position|positions|prediction|predictions|alert|alerts|daily\s+report|watchlist\s+report|report\s+history)\b/.test(
+      lower,
+    );
+  const hasPortfolioLotShape =
+    /\b(?:add|record|track)\b/.test(lower) &&
+    /\b\d+(?:\.\d+)?\s+shares?\b/.test(lower) &&
+    /\b(?:portfolio|holding|holdings|position|positions)\b/.test(lower);
+  if (hasPortfolioConstructionIntent) return false;
+  return (hasStateVerb && hasStateObject) || hasPortfolioLotShape;
+}
+
+const FINANCE_SIGNAL_TERMS = [
+  "stock",
+  "stocks",
+  "shares",
+  "ticker",
+  "tickers",
+  "etf",
+  "etfs",
+  "ipo",
+  "earnings",
+  "dividend",
+  "dividends",
+  "valuation",
+  "stock market",
+  "invest",
+  "investing",
+  "investment",
+  "portfolio",
+  "watchlist",
+  "bond",
+  "bonds",
+  "bond yield",
+  "treasury",
+  "the fed",
+  "inflation",
+  "interest rates",
+  "crypto",
+  "bitcoin",
+  "ethereum",
+  "options chain",
+  "covered call",
+  "puts",
+  "bullish",
+  "bearish",
+  "hedge",
+  "price target",
+  "cost basis",
+  "nasdaq",
+  "s&p",
+];
+
+const FINANCE_SIGNAL_PATTERN = new RegExp(
+  `\\b(?:${FINANCE_SIGNAL_TERMS.map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`,
+  "i",
+);
+
+/**
+ * Deterministic finance-vocabulary check for rules-mode fallback turns whose
+ * intent did not match a workflow and whose entities carry no symbols (for
+ * example theme prompts about private companies or sectors).
+ */
+export function hasFinanceSignals(input: string): boolean {
+  return FINANCE_SIGNAL_PATTERN.test(input);
+}

package/src/routing/defaults.ts

@@ -1,4 +1,4 @@
-import type { PortfolioSlots, OptionsScreenerSlots } from "./types.js";
+import type { OptionsScreenerSlots, PortfolioSlots } from "./types.js";
 
 export const PORTFOLIO_DEFAULTS: Omit<PortfolioSlots, "budget"> = {
   riskProfile: "balanced",