fin-ratios 0.7.3 → 1.0.2

package/dist/index.js

@@ -117,10 +117,10 @@ gordonGrowthModel.formula = "D1 / (r - g)";
 gordonGrowthModel.description = "DDM for stable dividend-paying stocks. Only valid when r > g.";
 function reverseDcf(input) {
   const target = input.marketCap + (input.netDebt ?? 0);
-  const computeEV = (g5) => {
+  const computeEV = (g7) => {
     const result = dcf2Stage({
       baseFcf: input.baseFcf,
-      growthRate: g5,
+      growthRate: g7,
       years: input.years,
       terminalGrowthRate: input.terminalGrowthRate,
       wacc: input.wacc
@@ -450,8 +450,8 @@ function annualizeReturn(returnValue, periodsPerYear) {
 }
 function stdDev(values, ddof = 1) {
   if (values.length < 2) return null;
-  const mean5 = values.reduce((a, b) => a + b, 0) / values.length;
-  const variance = values.reduce((sum, v) => sum + Math.pow(v - mean5, 2), 0) / (values.length - ddof);
+  const mean7 = values.reduce((a, b) => a + b, 0) / values.length;
+  const variance = values.reduce((sum, v) => sum + Math.pow(v - mean7, 2), 0) / (values.length - ddof);
   return Math.sqrt(variance);
 }
 function mean(values) {
@@ -1945,8 +1945,8 @@ function fairValueRange(options) {
     if (fy && fy > 0) estimates[`FCF Yield (${(targetYield * 100).toFixed(0)}%)`] = fy;
   }
   if (eps && bvps) {
-    const g5 = grahamValue(eps, bvps);
-    if (g5 && g5 > 0) estimates["Graham Number"] = g5;
+    const g7 = grahamValue(eps, bvps);
+    if (g7 && g7 > 0) estimates["Graham Number"] = g7;
   }
   if (ebitda && ebitda > 0 && shares && shares > 0) {
     const v = evEbitdaValue(ebitda, totalDebt, cash, shares, evEbitdaMultiple);
@@ -2057,6 +2057,550 @@ function portfolioQuality(holdings, options = {}) {
   };
 }
 
-export { affo, altmanZScore, annualizeReturn, arrPerFte, assetTurnover, beneishMScore, beta, burnMultiple, bvpsGrowth, cacPaybackPeriod, cacheStats, cached, cagr, calmarRatio, capRate, capexToDepreciation, capexToRevenue, capitalAllocationScore, capitalTurnover, cashConversionCycle, cashRatio, cashReturnOnAssets, cet1Ratio, clearCache, combinedRatio, computeAll, conditionalVaR, currentRatio, customerAcquisitionCost, customerLifetimeValue, dcf2Stage, debtServiceCoverageRatio, debtToAssets, debtToCapital, debtToEquity, defensiveIntervalRatio, dio, dividendGrowthRate, downsideCaptureRatio, dpo, dso, duPont3, earningsPowerValue, earningsQualityScore, ebitdaCoverageRatio, ebitdaGrowth, ebitdaMargin, efficiencyRatio, enterpriseValue, epsGrowth, equityMultiplier, evEbit, evEbitda, evFcf, evInvestedCapital, evRevenue, expenseRatio, fairValueRange, fcfConversion, fcfGrowth, fcfMargin, fcfYield, ffo, fixedAssetTurnover, fixedChargeCoverageRatio, forwardPe, freeCashFlow, gordonGrowthModel, grahamIntrinsicValue, grahamNumber, grossMargin, grossRevenueRetention, historicalVaR, informationRatio, interestCoverageRatio, invalidate as invalidateCache, inventoryTurnover, investedCapital, jensensAlpha, leveredFcf, loanToDepositRatio, lossRatio, ltvCacRatio, magicFormula, magicNumber, maxDrawdown, maximumDrawdown, mean, moatScore, montierCScore, netDebtToEbitda, netDebtToEquity, netInterestMargin, netOperatingIncome, netProfitMargin, netRevenueRetention, nopat, nopatMargin, nplRatio, occupancyRate, ocfToSales, ohlsonOScore, omegaRatio, operatingCashFlowRatio, operatingLeverage, operatingMargin, ownerEarnings, pAffo, pFcf, pFfo, parametricVaR, payablesTurnover, pb, pe, peg, percentile, piotroskiFScore, portfolioQuality, premiumsToSurplus, pricesToReturns, profitPerEmployee, provisionCoverageRatio, ps, qualityScore, quickRatio, receivablesTurnover, revenueCAGR, revenueGrowth, revenuePerEmployee, reverseDcf, roa, roce, roe, roic, rote, ruleOf40, saasQuickRatio, safeDivide, scenarioDcf, setCache, sharpeRatio, sortinoRatio, stdDev, tangibleBookValuePerShare, tier1CapitalRatio, tobinsQ, trackingError, treynorRatio, ulcerIndex, underwritingProfitMargin, unleveredFcf, upsideCaptureRatio, workingCapitalTurnover };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+// src/utils/valuation-score.ts
+function _clamp(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function _lerp(x, x0, x1, y0, y1) {
+  if (x1 === x0) return y0;
+  const t = (x - x0) / (x1 - x0);
+  return y0 + _clamp(t, 0, 1) * (y1 - y0);
+}
+function scoreEarningsYield(params, rf) {
+  let ey = null;
+  if (params.earningsYieldPct !== void 0) {
+    ey = params.earningsYieldPct / 100;
+  } else if (params.peRatio !== void 0 && params.peRatio > 0) {
+    ey = 1 / params.peRatio;
+  }
+  if (ey === null) {
+    return [0.5, ["Earnings yield: no P/E or earnings yield data (neutral score)"]];
+  }
+  const excess = ey - rf;
+  const score = _lerp(excess, -0.04, 0.04, 0, 1);
+  const label = excess >= 0.02 ? "attractive" : excess >= 0 ? "slight premium" : "below risk-free";
+  return [score, [
+    `Earnings yield: ${(ey * 100).toFixed(2)}%  vs  risk-free ${(rf * 100).toFixed(2)}%  (spread ${excess >= 0 ? "+" : ""}${(excess * 100).toFixed(2)}%)`,
+    `Earnings yield spread: ${label}`
+  ]];
+}
+function scoreFcfYield(params) {
+  let fy = null;
+  if (params.fcfYieldPct !== void 0) {
+    fy = params.fcfYieldPct / 100;
+  } else if (params.pFcf !== void 0 && params.pFcf > 0) {
+    fy = 1 / params.pFcf;
+  }
+  if (fy === null) {
+    return [0.5, ["FCF yield: no P/FCF or FCF yield data (neutral score)"]];
+  }
+  let score;
+  if (fy < 0.02) {
+    score = _lerp(fy, -0.02, 0.02, 0, 0.3);
+  } else if (fy < 0.05) {
+    score = _lerp(fy, 0.02, 0.05, 0.3, 0.7);
+  } else {
+    score = _lerp(fy, 0.05, 0.08, 0.7, 1);
+  }
+  const label = fy >= 0.06 ? "excellent" : fy >= 0.04 ? "good" : fy >= 0.02 ? "modest" : "thin";
+  return [score, [
+    `FCF yield: ${(fy * 100).toFixed(2)}%  (${label})`
+  ]];
+}
+function scoreEvEbitda(params) {
+  if (params.evEbitda === void 0) {
+    return [0.5, ["EV/EBITDA: not provided (neutral score)"]];
+  }
+  const ev = params.evEbitda;
+  if (ev <= 0) {
+    return [0.2, ["EV/EBITDA: negative or zero (uninvestable or distressed)"]];
+  }
+  let score;
+  if (ev < 12) {
+    score = _lerp(ev, 5, 12, 1, 0.6);
+  } else if (ev < 20) {
+    score = _lerp(ev, 12, 20, 0.6, 0.2);
+  } else {
+    score = _lerp(ev, 20, 30, 0.2, 0.05);
+  }
+  const label = ev < 10 ? "deep value" : ev < 14 ? "reasonable" : ev < 20 ? "full valued" : "expensive";
+  return [score, [
+    `EV/EBITDA: ${ev.toFixed(1)}\xD7  (${label})`
+  ]];
+}
+function scorePbRatio(params) {
+  if (params.pbRatio === void 0) {
+    return [0.5, ["P/B ratio: not provided (neutral score)"]];
+  }
+  const pb2 = params.pbRatio;
+  if (pb2 <= 0) {
+    return [0.15, ["P/B ratio: negative book value \u2014 balance sheet impaired"]];
+  }
+  let score;
+  if (pb2 < 2) {
+    score = _lerp(pb2, 0.5, 2, 1, 0.65);
+  } else if (pb2 < 4) {
+    score = _lerp(pb2, 2, 4, 0.65, 0.3);
+  } else {
+    score = _lerp(pb2, 4, 8, 0.3, 0.05);
+  }
+  const label = pb2 < 1.5 ? "near book value" : pb2 < 3 ? "moderate premium" : pb2 < 5 ? "high premium" : "very high premium";
+  return [score, [
+    `P/B ratio: ${pb2.toFixed(2)}\xD7  (${label})`
+  ]];
+}
+function scoreDcfUpside(params) {
+  if (params.dcfUpsidePct === void 0) {
+    return [0.5, ["DCF upside: not provided (neutral score)"]];
+  }
+  const u = params.dcfUpsidePct / 100;
+  let score;
+  if (u < 0) {
+    score = _lerp(u, -0.5, 0, 0, 0.3);
+  } else if (u < 0.3) {
+    score = _lerp(u, 0, 0.3, 0.3, 0.75);
+  } else {
+    score = _lerp(u, 0.3, 0.6, 0.75, 1);
+  }
+  const label = u >= 0.3 ? "significant margin of safety" : u >= 0.1 ? "modest upside" : u >= 0 ? "fairly valued" : "trading above intrinsic value";
+  return [score, [
+    `DCF upside: ${(u * 100).toFixed(1)}%  (${label})`
+  ]];
+}
+function valuationAttractivenessScore(params) {
+  const rf = params.riskFreeRate ?? 0.045;
+  const [eyScore, eyEv] = scoreEarningsYield(params, rf);
+  const [fyScore, fyEv] = scoreFcfYield(params);
+  const [evScore, evEv] = scoreEvEbitda(params);
+  const [pbScore, pbEv] = scorePbRatio(params);
+  const [dcfScore, dcfEv] = scoreDcfUpside(params);
+  const raw = 0.25 * eyScore + 0.25 * fyScore + 0.2 * evScore + 0.15 * pbScore + 0.15 * dcfScore;
+  const score = Math.round(_clamp(raw, 0, 1) * 100);
+  const rating = score >= 65 ? "attractive" : score >= 40 ? "fair" : score >= 20 ? "expensive" : "overvalued";
+  const desc = {
+    attractive: "Multiple signals indicate price is below intrinsic value \u2014 margin of safety present",
+    fair: "Price appears broadly in line with fundamental value",
+    expensive: "Price embeds optimistic assumptions \u2014 limited margin of safety",
+    overvalued: "Price materially exceeds indicated intrinsic value across multiple metrics"
+  };
+  return {
+    score,
+    rating,
+    components: {
+      earningsYield: Math.round(eyScore * 1e4) / 1e4,
+      fcfYield: Math.round(fyScore * 1e4) / 1e4,
+      evEbitda: Math.round(evScore * 1e4) / 1e4,
+      pbRatio: Math.round(pbScore * 1e4) / 1e4,
+      dcfUpside: Math.round(dcfScore * 1e4) / 1e4
+    },
+    riskFreeRate: rf,
+    evidence: [...eyEv, ...fyEv, ...evEv, ...pbEv, ...dcfEv],
+    interpretation: `Score ${score}/100: ${desc[rating]}`
+  };
+}
+
+// src/utils/management-score.ts
+function mean5(xs) {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+function std4(xs) {
+  if (xs.length < 2) return 0;
+  const m = mean5(xs);
+  return Math.sqrt(xs.reduce((a, x) => a + (x - m) ** 2, 0) / (xs.length - 1));
+}
+function cv4(xs) {
+  const m = mean5(xs);
+  return Math.abs(m) > 1e-9 ? std4(xs) / Math.abs(m) : 1;
+}
+function olsSlope4(ys) {
+  const n = ys.length;
+  if (n < 2) return 0;
+  const xm = (n - 1) / 2;
+  const ym = mean5(ys);
+  const ssXX = Array.from({ length: n }, (_, i) => (i - xm) ** 2).reduce((a, b) => a + b, 0);
+  const ssXY = Array.from({ length: n }, (_, i) => (i - xm) * ((ys[i] ?? 0) - ym)).reduce((a, b) => a + b, 0);
+  return ssXX ? ssXY / ssXX : 0;
+}
+function clamp3(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function lerp(x, x0, x1, y0, y1) {
+  if (x1 === x0) return y0;
+  return y0 + clamp3((x - x0) / (x1 - x0), 0, 1) * (y1 - y0);
+}
+function g5(d, k) {
+  const v = d[k];
+  return typeof v === "number" && isFinite(v) ? v : 0;
+}
+function yearRoic3(d) {
+  const ebit = g5(d, "ebit");
+  const ic = g5(d, "totalEquity") + g5(d, "totalDebt") - g5(d, "cash");
+  if (ic <= 0) return null;
+  const ebt = g5(d, "ebt") || ebit - g5(d, "interestExpense");
+  const tax = g5(d, "incomeTaxExpense");
+  const taxRate = ebt > 0 && tax > 0 ? clamp3(tax / ebt, 0, 0.5) : 0.21;
+  return ebit * (1 - taxRate) / ic;
+}
+function estimateHurdleRate(series, provided) {
+  if (provided !== void 0) return provided;
+  const d = series[series.length - 1];
+  const equity = g5(d, "totalEquity");
+  const debt = g5(d, "totalDebt");
+  const cash = g5(d, "cash");
+  const totalCap = equity + debt - cash;
+  if (totalCap <= 0) return 0.1;
+  const costEquity = 0.045 + 0.055;
+  const interest = g5(d, "interestExpense");
+  let costDebt = 0.04;
+  if (debt > 0 && interest > 0) {
+    const preTax = clamp3(interest / debt, 0.02, 0.15);
+    const ebt = g5(d, "ebt") || g5(d, "ebit") - interest;
+    const tax = g5(d, "incomeTaxExpense");
+    const taxRate = ebt > 0 && tax > 0 ? clamp3(tax / ebt, 0, 0.4) : 0.21;
+    costDebt = preTax * (1 - taxRate);
+  }
+  const wE = clamp3(equity / totalCap, 0, 1);
+  return clamp3(wE * costEquity + (1 - wE) * costDebt, 0.06, 0.2);
+}
+function scoreRoicExcellence(series, hurdle) {
+  const roicVals = series.map(yearRoic3).filter((r) => r !== null);
+  if (!roicVals.length) return [0.35, ["ROIC excellence: insufficient data (neutral score)"]];
+  const meanRoic = mean5(roicVals);
+  const slope = olsSlope4(roicVals);
+  const consistency = clamp3(1 - cv4(roicVals) * 0.5, 0, 1);
+  const level = lerp(meanRoic, 0.05, 0.3, 0, 1);
+  const trendAdj = slope > 0.01 ? 0.08 : slope < -0.01 ? -0.08 : 0;
+  const score = clamp3(0.55 * level + 0.35 * consistency + trendAdj, 0, 1);
+  const aboveHurdle = roicVals.filter((r) => r > hurdle).length;
+  const dir = slope > 0.01 ? "improving" : slope < -0.01 ? "declining" : "stable";
+  return [score, [
+    `ROIC excellence: mean ${(meanRoic * 100).toFixed(1)}%  (hurdle ${(hurdle * 100).toFixed(1)}%,  ${aboveHurdle}/${roicVals.length} years above)`,
+    `ROIC trend: ${dir}  (OLS ${(slope * 100).toFixed(2)}%/yr)`
+  ]];
+}
+function scoreMarginStability(series) {
+  const margins = series.filter((d) => g5(d, "revenue") > 0 && g5(d, "ebit") !== 0).map((d) => g5(d, "ebit") / g5(d, "revenue"));
+  if (margins.length < 2) return [0.4, ["Margin stability: insufficient revenue/EBIT data (neutral score)"]];
+  const meanMargin = mean5(margins);
+  const slope = olsSlope4(margins);
+  const consistency = clamp3(1 - cv4(margins) * 1, 0, 1);
+  const level = lerp(meanMargin, 0, 0.3, 0, 1);
+  const trendAdj = slope > 5e-3 ? 0.08 : slope < -5e-3 ? -0.08 : 0;
+  const score = clamp3(0.5 * level + 0.4 * consistency + trendAdj, 0, 1);
+  const dir = slope > 5e-3 ? "expanding" : slope < -5e-3 ? "contracting" : "stable";
+  const quality = meanMargin >= 0.2 ? "high" : meanMargin >= 0.1 ? "moderate" : "thin";
+  return [score, [
+    `Operating margin: mean ${(meanMargin * 100).toFixed(1)}%  (${quality} quality,  CV ${cv4(margins).toFixed(3)})`,
+    `Margin trend: ${dir}  (OLS ${(slope * 100).toFixed(3)}%/yr)`
+  ]];
+}
+function scoreShareholderOrientation(series) {
+  const shares = series.map((d) => g5(d, "sharesOutstanding")).filter((s) => s > 0);
+  if (shares.length < 2) return [0.5, ["Shareholder orientation: share count data unavailable (neutral score)"]];
+  const meanShares = mean5(shares);
+  const slope = olsSlope4(shares);
+  const slopePct = meanShares > 0 ? slope / meanShares : 0;
+  const score = clamp3(0.5 - slopePct * 5, 0, 1);
+  const pctChange = (shares[shares.length - 1] - shares[0]) / shares[0];
+  const dir = slopePct < -0.01 ? "declining (buybacks)" : slopePct > 0.01 ? "growing (dilution)" : "roughly flat";
+  return [score, [
+    `Share count: ${dir}  (${pctChange >= 0 ? "+" : ""}${(pctChange * 100).toFixed(1)}% over period)`,
+    slopePct < -5e-3 ? "Management is reducing share count \u2014 shareholder friendly" : slopePct > 0.02 ? "Material share dilution detected \u2014 value transfer risk" : "Share count broadly stable"
+  ]];
+}
+function scoreRevenueExecution(series) {
+  const growthRates = [];
+  for (let i = 1; i < series.length; i++) {
+    const prevRev = g5(series[i - 1], "revenue");
+    const currRev = g5(series[i], "revenue");
+    if (prevRev > 0) growthRates.push((currRev - prevRev) / prevRev);
+  }
+  if (!growthRates.length) return [0.4, ["Revenue execution: insufficient revenue data (neutral score)"]];
+  const meanGrowth = mean5(growthRates);
+  const level = lerp(meanGrowth, -0.05, 0.2, 0, 1);
+  const consistency = clamp3(1 - cv4(growthRates) * 0.4, 0, 1);
+  const score = clamp3(0.65 * level + 0.35 * consistency, 0, 1);
+  const posYears = growthRates.filter((r) => r > 0).length;
+  const quality = meanGrowth >= 0.1 ? "strong" : meanGrowth >= 0.04 ? "adequate" : meanGrowth >= 0 ? "sluggish" : "declining";
+  return [score, [
+    `Revenue growth: mean ${(meanGrowth * 100).toFixed(1)}%/yr  (${quality},  ${posYears}/${growthRates.length} years positive)`
+  ]];
+}
+function managementQualityScoreFromSeries(annualData, hurdleRate) {
+  if (annualData.length < 3) {
+    throw new Error("managementQualityScoreFromSeries requires at least 3 years of data.");
+  }
+  const hurdle = estimateHurdleRate(annualData, hurdleRate);
+  const [roicScore, roicEv] = scoreRoicExcellence(annualData, hurdle);
+  const [marginScore, marginEv] = scoreMarginStability(annualData);
+  const [soScore, soEv] = scoreShareholderOrientation(annualData);
+  const [revScore, revEv] = scoreRevenueExecution(annualData);
+  const raw = 0.35 * roicScore + 0.25 * marginScore + 0.25 * soScore + 0.15 * revScore;
+  const score = Math.round(clamp3(raw, 0, 1) * 100);
+  const rating = score >= 75 ? "excellent" : score >= 50 ? "good" : score >= 25 ? "fair" : "poor";
+  const desc = {
+    excellent: "Management consistently earns high ROIC, protects margins, and treats shareholders well",
+    good: "Solid operational track record with most quality signals positive",
+    fair: "Mixed signals \u2014 some areas of strength but meaningful shortfalls elsewhere",
+    poor: "Weak returns, margin deterioration, or material shareholder dilution detected"
+  };
+  return {
+    score,
+    rating,
+    components: {
+      roicExcellence: Math.round(roicScore * 1e4) / 1e4,
+      marginStability: Math.round(marginScore * 1e4) / 1e4,
+      shareholderOrientation: Math.round(soScore * 1e4) / 1e4,
+      revenueExecution: Math.round(revScore * 1e4) / 1e4
+    },
+    hurdleRateUsed: hurdle,
+    yearsAnalyzed: annualData.length,
+    evidence: [...roicEv, ...marginEv, ...soEv, ...revEv],
+    interpretation: `Score ${score}/100: ${desc[rating]}`
+  };
+}
+
+// src/utils/dividend-score.ts
+function mean6(xs) {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+function clamp4(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function g6(d, k) {
+  const v = d[k];
+  return typeof v === "number" && isFinite(v) ? v : 0;
+}
+function isDividendPayer(series) {
+  return series.some((d) => {
+    const div = d.dividendsPaid;
+    return typeof div === "number" && isFinite(div) && div > 0;
+  });
+}
+function scoreFcfPayout(series) {
+  const ratios = [];
+  for (const d of series) {
+    const div = g6(d, "dividendsPaid");
+    if (div <= 0) continue;
+    const cfo = g6(d, "operatingCashFlow");
+    const capex = g6(d, "capex");
+    const fcf = cfo - capex;
+    if (fcf !== 0) ratios.push(div / fcf);
+  }
+  if (!ratios.length) return [0.5, ["FCF payout ratio: no dividend/FCF overlap (neutral score)"]];
+  const avg = mean6(ratios);
+  let score;
+  if (avg < 0.4) score = 1;
+  else if (avg < 0.6) score = 0.75;
+  else if (avg < 0.8) score = 0.45;
+  else if (avg <= 1) score = 0.15;
+  else score = 0;
+  const quality = avg < 0.4 ? "very well covered" : avg < 0.6 ? "adequately covered" : avg < 0.8 ? "tight" : avg <= 1 ? "stressed" : "uncovered by FCF";
+  return [score, [
+    `FCF payout ratio: mean ${(avg * 100).toFixed(0)}%  (${quality})`
+  ]];
+}
+function scoreEarningsPayout(series) {
+  const ratios = [];
+  for (const d of series) {
+    const div = g6(d, "dividendsPaid");
+    const ni = g6(d, "netIncome");
+    if (div > 0 && ni > 0) ratios.push(div / ni);
+  }
+  if (!ratios.length) return [0.5, ["Earnings payout ratio: no dividend/earnings overlap (neutral score)"]];
+  const avg = mean6(ratios);
+  let score;
+  if (avg < 0.35) score = 1;
+  else if (avg < 0.55) score = 0.75;
+  else if (avg < 0.75) score = 0.45;
+  else if (avg <= 1) score = 0.2;
+  else score = 0;
+  const quality = avg < 0.35 ? "conservative" : avg < 0.55 ? "moderate" : avg < 0.75 ? "elevated" : avg <= 1 ? "high" : "exceeds earnings";
+  return [score, [
+    `Earnings payout ratio: mean ${(avg * 100).toFixed(0)}%  (${quality})`
+  ]];
+}
+function scoreBalanceSheet(series) {
+  const d = series[series.length - 1];
+  const totalDebt = g6(d, "totalDebt");
+  const cash = g6(d, "cash");
+  const netDebt = totalDebt - cash;
+  const ebit = g6(d, "ebit");
+  const dep = g6(d, "depreciation");
+  const ebitda = ebit + dep;
+  if (ebitda <= 0) {
+    return [0.3, ["Balance sheet strength: EBITDA unavailable or negative (below-neutral score)"]];
+  }
+  const ratio = netDebt / ebitda;
+  let score;
+  if (ratio < 0) score = 1;
+  else if (ratio < 1) score = 0.85;
+  else if (ratio < 2) score = 0.65;
+  else if (ratio < 3) score = 0.4;
+  else if (ratio < 4) score = 0.2;
+  else score = 0.05;
+  const quality = ratio < 0 ? "net cash position" : ratio < 1 ? "very low leverage" : ratio < 2 ? "modest leverage" : ratio < 3 ? "moderate leverage" : ratio < 4 ? "elevated leverage" : "highly levered";
+  return [score, [
+    `Net debt / EBITDA: ${ratio.toFixed(2)}\xD7  (${quality})`
+  ]];
+}
+function scoreDividendGrowthTrack(series) {
+  const divs = series.map((d) => g6(d, "dividendsPaid")).filter((d) => d > 0);
+  if (divs.length < 2) {
+    return [0.15, ["Dividend growth track: insufficient history (below-neutral score)"]];
+  }
+  let consecutive = 0;
+  for (let i = 1; i < divs.length; i++) {
+    if ((divs[i] ?? 0) >= (divs[i - 1] ?? 0)) {
+      consecutive++;
+    } else {
+      consecutive = 0;
+    }
+  }
+  let score;
+  if (consecutive >= 10) score = 1;
+  else if (consecutive >= 7) score = 0.75;
+  else if (consecutive >= 4) score = 0.55;
+  else if (consecutive >= 2) score = 0.35;
+  else score = 0.15;
+  const label = consecutive >= 10 ? "dividend aristocrat-level streak" : consecutive >= 7 ? "strong track record" : consecutive >= 4 ? "solid track record" : consecutive >= 2 ? "limited track record" : "recent cut or minimal history";
+  return [score, [
+    `Dividend growth track: ${consecutive} consecutive non-declining year(s)  (${label})`
+  ]];
+}
+function dividendSafetyScoreFromSeries(annualData) {
+  const payer = isDividendPayer(annualData);
+  if (!payer) {
+    return {
+      score: 50,
+      rating: "non-payer",
+      isDividendPayer: false,
+      yearsAnalyzed: annualData.length,
+      components: {
+        fcfPayoutRatio: 0.5,
+        earningsPayoutRatio: 0.5,
+        balanceSheetStrength: 0.5,
+        dividendGrowthTrack: 0.5
+      },
+      evidence: ["No dividends detected across the provided data series"],
+      interpretation: "Score 50/100: Company does not pay a dividend \u2014 score is not meaningful"
+    };
+  }
+  const [fcfScore, fcfEv] = scoreFcfPayout(annualData);
+  const [epScore, epEv] = scoreEarningsPayout(annualData);
+  const [bsScore, bsEv] = scoreBalanceSheet(annualData);
+  const [dgtScore, dgtEv] = scoreDividendGrowthTrack(annualData);
+  const raw = 0.35 * fcfScore + 0.25 * epScore + 0.25 * bsScore + 0.15 * dgtScore;
+  const score = Math.round(clamp4(raw, 0, 1) * 100);
+  const rating = score >= 70 ? "safe" : score >= 45 ? "adequate" : score >= 20 ? "risky" : "danger";
+  const desc = {
+    safe: "Dividend well-covered by cash flows with a strong balance sheet",
+    adequate: "Dividend appears sustainable but headroom is limited in some areas",
+    risky: "Coverage is strained \u2014 dividend could be at risk in a downturn",
+    danger: "Dividend likely unsustainable; cut probability is high"
+  };
+  return {
+    score,
+    rating,
+    components: {
+      fcfPayoutRatio: Math.round(fcfScore * 1e4) / 1e4,
+      earningsPayoutRatio: Math.round(epScore * 1e4) / 1e4,
+      balanceSheetStrength: Math.round(bsScore * 1e4) / 1e4,
+      dividendGrowthTrack: Math.round(dgtScore * 1e4) / 1e4
+    },
+    isDividendPayer: true,
+    yearsAnalyzed: annualData.length,
+    evidence: [...fcfEv, ...epEv, ...bsEv, ...dgtEv],
+    interpretation: `Score ${score}/100: ${desc[rating]}`
+  };
+}
+
+// src/utils/investment-score.ts
+function clamp5(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function gradeFromScore(score) {
+  if (score >= 90) return "A+";
+  if (score >= 80) return "A";
+  if (score >= 70) return "B+";
+  if (score >= 60) return "B";
+  if (score >= 45) return "C";
+  if (score >= 25) return "D";
+  return "F";
+}
+function convictionFromScore(score) {
+  if (score >= 80) return "strongBuy";
+  if (score >= 65) return "buy";
+  if (score >= 45) return "hold";
+  if (score >= 30) return "sell";
+  return "strongSell";
+}
+function computeWeightedScore(inputs) {
+  const hasValuation = inputs.valuationScore !== void 0;
+  if (hasValuation) {
+    return 0.25 * inputs.moatScore + 0.2 * inputs.capitalAllocationScore + 0.2 * inputs.earningsQualityScore + 0.15 * inputs.managementScore + 0.2 * inputs.valuationScore;
+  }
+  return 0.3125 * inputs.moatScore + 0.25 * inputs.capitalAllocationScore + 0.25 * inputs.earningsQualityScore + 0.1875 * inputs.managementScore;
+}
+function investmentScoreFromScores(inputs) {
+  const rawScore = computeWeightedScore(inputs);
+  const score = Math.round(clamp5(rawScore, 0, 100));
+  const grade = gradeFromScore(score);
+  const conviction = convictionFromScore(score);
+  const hasVal = inputs.valuationScore !== void 0;
+  const evidence = [
+    `Economic Moat:         ${inputs.moatScore}/100  (weight ${hasVal ? "25" : "31"}%)`,
+    `Capital Allocation:    ${inputs.capitalAllocationScore}/100  (weight ${hasVal ? "20" : "25"}%)`,
+    `Earnings Quality:      ${inputs.earningsQualityScore}/100  (weight ${hasVal ? "20" : "25"}%)`,
+    `Management Quality:    ${inputs.managementScore}/100  (weight ${hasVal ? "15" : "19"}%)`
+  ];
+  if (hasVal) {
+    evidence.push(`Valuation:             ${inputs.valuationScore}/100  (weight 20%)`);
+  } else {
+    evidence.push("Valuation:             not provided (weight redistributed)");
+  }
+  const convictionLabel = {
+    strongBuy: "Strong Buy \u2014 exceptional quality at an attractive price",
+    buy: "Buy \u2014 above-average quality with reasonable valuation",
+    hold: "Hold \u2014 average quality or price adequately reflects value",
+    sell: "Sell \u2014 below-average quality or price significantly exceeds value",
+    strongSell: "Strong Sell \u2014 poor quality and/or materially overpriced"
+  };
+  return {
+    score,
+    grade,
+    conviction,
+    components: {
+      moat: inputs.moatScore,
+      capitalAllocation: inputs.capitalAllocationScore,
+      earningsQuality: inputs.earningsQualityScore,
+      management: inputs.managementScore,
+      valuation: inputs.valuationScore ?? null
+    },
+    evidence,
+    interpretation: `Grade ${grade}  |  Score ${score}/100  |  ${convictionLabel[conviction]}`
+  };
+}
+function investmentScoreFromSeries(annualData, valuationParams, wacc) {
+  if (annualData.length < 3) {
+    throw new Error("investmentScoreFromSeries requires at least 3 years of data.");
+  }
+  const waccOpt = wacc !== void 0 ? { wacc } : {};
+  const moatResult = moatScore(annualData, waccOpt);
+  const caResult = capitalAllocationScore(annualData, waccOpt);
+  const eqResult = earningsQualityScore(annualData);
+  const mgmtResult = managementQualityScoreFromSeries(annualData, wacc);
+  const inputs = {
+    moatScore: moatResult.score,
+    capitalAllocationScore: caResult.score,
+    earningsQualityScore: eqResult.score,
+    managementScore: mgmtResult.score
+  };
+  if (valuationParams !== void 0) {
+    const valResult = valuationAttractivenessScore(valuationParams);
+    inputs.valuationScore = valResult.score;
+  }
+  return investmentScoreFromScores(inputs);
+}
+
+export { affo, altmanZScore, annualizeReturn, arrPerFte, assetTurnover, beneishMScore, beta, burnMultiple, bvpsGrowth, cacPaybackPeriod, cacheStats, cached, cagr, calmarRatio, capRate, capexToDepreciation, capexToRevenue, capitalAllocationScore, capitalTurnover, cashConversionCycle, cashRatio, cashReturnOnAssets, cet1Ratio, clearCache, combinedRatio, computeAll, conditionalVaR, currentRatio, customerAcquisitionCost, customerLifetimeValue, dcf2Stage, debtServiceCoverageRatio, debtToAssets, debtToCapital, debtToEquity, defensiveIntervalRatio, dio, dividendGrowthRate, dividendSafetyScoreFromSeries, downsideCaptureRatio, dpo, dso, duPont3, earningsPowerValue, earningsQualityScore, ebitdaCoverageRatio, ebitdaGrowth, ebitdaMargin, efficiencyRatio, enterpriseValue, epsGrowth, equityMultiplier, evEbit, evEbitda, evFcf, evInvestedCapital, evRevenue, expenseRatio, fairValueRange, fcfConversion, fcfGrowth, fcfMargin, fcfYield, ffo, fixedAssetTurnover, fixedChargeCoverageRatio, forwardPe, freeCashFlow, gordonGrowthModel, grahamIntrinsicValue, grahamNumber, grossMargin, grossRevenueRetention, historicalVaR, informationRatio, interestCoverageRatio, invalidate as invalidateCache, inventoryTurnover, investedCapital, investmentScoreFromScores, investmentScoreFromSeries, jensensAlpha, leveredFcf, loanToDepositRatio, lossRatio, ltvCacRatio, magicFormula, magicNumber, managementQualityScoreFromSeries, maxDrawdown, maximumDrawdown, mean, moatScore, montierCScore, netDebtToEbitda, netDebtToEquity, netInterestMargin, netOperatingIncome, netProfitMargin, netRevenueRetention, nopat, nopatMargin, nplRatio, occupancyRate, ocfToSales, ohlsonOScore, omegaRatio, operatingCashFlowRatio, operatingLeverage, operatingMargin, ownerEarnings, pAffo, pFcf, pFfo, parametricVaR, payablesTurnover, pb, pe, peg, percentile, piotroskiFScore, portfolioQuality, premiumsToSurplus, pricesToReturns, profitPerEmployee, provisionCoverageRatio, ps, qualityScore, quickRatio, receivablesTurnover, revenueCAGR, revenueGrowth, revenuePerEmployee, reverseDcf, roa, roce, roe, roic, rote, ruleOf40, saasQuickRatio, safeDivide, scenarioDcf, setCache, sharpeRatio, sortinoRatio, stdDev, tangibleBookValuePerShare, tier1CapitalRatio, tobinsQ, trackingError, treynorRatio, ulcerIndex, underwritingProfitMargin, unleveredFcf, upsideCaptureRatio, valuationAttractivenessScore, workingCapitalTurnover };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fin-ratios",
-  "version": "0.7.3",
-  "description": "The most comprehensive financial ratios library. 136+ ratios across valuation, profitability, risk, composite scores, SaaS metrics, and more. Includes batch compute, scenario DCF, caching, React hooks, and MCP server for AI agents.",
+  "version": "1.0.2",
+  "description": "The most comprehensive financial ratios library. 136+ ratios · 10 institutional-grade scoring models · TypeScript + Python · Valuation, Management, Dividend Safety, Investment Scores · FastAPI, MCP server, React hooks, EDGAR fetcher, Pandas/Polars · Zero runtime core dependencies.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -32,6 +32,11 @@
       "import": "./dist/fetchers/alphavantage/index.js",
       "require": "./dist/fetchers/alphavantage/index.cjs"
     },
+    "./fetchers/polygon": {
+      "types": "./dist/fetchers/polygon/index.d.ts",
+      "import": "./dist/fetchers/polygon/index.js",
+      "require": "./dist/fetchers/polygon/index.cjs"
+    },
     "./hooks": {
       "types": "./dist/hooks/index.d.ts",
       "import": "./dist/hooks/index.js",
@@ -57,6 +62,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "prepack": "cp ../README.md . && cp ../LICENSE .",
+    "postpack": "rm -f README.md LICENSE",
     "prepublishOnly": "npm run build && npm run typecheck"
   },
   "keywords": [
@@ -80,7 +87,8 @@
     "url": "https://github.com/piyushgupta344"
   },
   "license": "MIT",
-  "homepage": "https://github.com/piyushgupta344/fin-ratios#readme",
+  "sideEffects": false,
+  "homepage": "https://piyushgupta344.github.io/fin-ratios/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/piyushgupta344/fin-ratios.git"

package/dist/fetchers/alphavantage/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../src/fetchers/alphavantage/index.ts"],"names":[],"mappings":";;;AAcA,IAAM,IAAA,GAAO,mCAAA;AAmBb,eAAsB,iBAAA,CACpB,QACA,OAAA,EACmC;AACnC,EAAA,MAAM,EAAE,MAAA,EAAQ,OAAA,GAAU,CAAA,EAAG,SAAA,GAAY,OAAM,GAAI,OAAA;AAEnD,EAAA,MAAM,IAAA,GAAO,YAAY,kBAAA,GAAqB,eAAA;AAE9C,EAAA,MAAM,CAAC,SAAS,OAAA,EAAS,MAAA,EAAQ,SAAS,CAAA,GAAI,MAAM,QAAQ,GAAA,CAAI;AAAA,IAC9D,IAAA,CAAK,EAAE,QAAA,EAAU,kBAAA,EAAoB,QAAQ,MAAA,EAAQ,MAAA,EAAQ,QAAQ,CAAA;AAAA,IACrE,IAAA,CAAK,EAAE,QAAA,EAAU,eAAA,EAAoB,QAAQ,MAAA,EAAQ,MAAA,EAAQ,QAAQ,CAAA;AAAA,IACrE,IAAA,CAAK,EAAE,QAAA,EAAU,WAAA,EAAoB,QAAQ,MAAA,EAAQ,MAAA,EAAQ,QAAQ,CAAA;AAAA,IACrE,IAAA,CAAK,EAAE,QAAA,EAAU,cAAA,EAAoB,QAAQ,MAAA,EAAQ,MAAA,EAAQ,QAAQ;AAAA,GACtE,CAAA;AAED,EAAA,MAAM,UAAA,GAAA,CAAqB,QAAQ,IAAI,CAAA,IAAK,EAAC,EAAG,KAAA,CAAM,GAAG,OAAO,CAAA;AAChE,EAAA,MAAM,UAAA,GAAA,CAAqB,QAAQ,IAAI,CAAA,IAAK,EAAC,EAAG,KAAA,CAAM,GAAG,OAAO,CAAA;AAChE,EAAA,MAAM,SAAA,GAAA,CAAqB,OAAO,IAAI,CAAA,IAAM,EAAC,EAAG,KAAA,CAAM,GAAG,OAAO,CAAA;AAChE,EAAA,MAAM,KAAA,GAAQ,SAAA,CAAU,cAAc,CAAA,IAAK,EAAC;AAE5C,EAAA,MAAM,KAAA,GAAQ,EAAA,CAAG,KAAA,CAAM,WAAW,CAAC,CAAA;AACnC,EAAA,MAAM,UAAoC,EAAC;AAE3C,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,UAAA,CAAW,QAAQ,CAAA,EAAA,EAAK;AAC1C,IAAA,MAAM,GAAA,GAAM,UAAA,CAAW,CAAC,CAAA,IAAK,EAAC;AAC9B,IAAA,MAAM,GAAA,GAAM,UAAA,CAAW,CAAC,CAAA,IAAK,EAAC;AAC9B,IAAA,MAAM,EAAA,GAAM,SAAA,CAAU,CAAC,CAAA,IAAM,EAAC;AAE9B,IAAA,OAAA,CAAQ,IAAA,CAAK;AAAA,MACX,MAAA,EAAQ,IAAI,gBAAA,IAAoB,EAAA;AAAA,MAChC,MAAA,EAAQ;AAAA,QACN,OAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,YAAY,CAAA;AAAA,QAC/C,WAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,WAAW,CAAA;AAAA,QAC9C,IAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,aAAa,CAAA;AAAA,QAChD,IAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,IAAI,CAAA;AAAA,QACvC,MAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,MAAM,CAAA;AAAA,QACzC,SAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,SAAS,CAAA;AAAA,QAC5C,iBAA4B,IAAA,CAAK,GAAA,CAAI,EAAA,CAAG,GAAA,CAAI,eAAe,CAAC,CAAA;AAAA,QAC5D,gBAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,gBAAgB,CAAA;AAAA,QACnD,GAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,eAAe,CAAA;AAAA,QAClD,2BAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,2BAA2B,CAAA;AAAA,QAC9D,iBAAA,EAA4B,EAAA,CAAG,GAAA,CAAI,4BAA4B,CAAA;AAAA,QAC/D,GAAA,EAA4B;AAAA,OAC9B;AAAA,MACA,OAAA,EAAS;AAAA,QACP,WAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,WAAW,CAAA;AAAA,QACtC,aAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,kBAAkB,CAAA;AAAA,QAC7C,IAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,qCAAqC,CAAA;AAAA,QAChE,kBAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,qBAAqB,CAAA;AAAA,QAChD,SAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,SAAS,CAAA;AAAA,QACpC,MAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,yBAAyB,CAAA;AAAA,QACpD,QAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,QAAQ,CAAA;AAAA,QACnC,gBAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,gBAAgB,CAAA;AAAA,QAC3C,gBAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,gBAAgB,CAAA;AAAA,QAC3C,kBAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,uBAAuB,CAAA;AAAA,QAClD,eAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,sBAAsB,CAAA;AAAA,QACjD,YAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,sBAAsB,CAAA;AAAA,QACjD,SAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,sBAAsB,CAAA;AAAA,QACjD,WAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,sBAAsB,CAAA;AAAA,QACjD,iBAAA,EAAoB,EAAA,CAAG,GAAA,CAAI,4BAA4B;AAAA,OACzD;AAAA,MACA,QAAA,EAAU;AAAA,QACR,iBAAA,EAAmB,EAAA,CAAG,EAAA,CAAG,iBAAiB,CAAA;AAAA,QAC1C,OAAmB,IAAA,CAAK,GAAA,CAAI,EAAA,CAAG,EAAA,CAAG,mBAAmB,CAAC,CAAA;AAAA,QACtD,iBAAA,EAAmB,EAAA,CAAG,EAAA,CAAG,sBAAsB,CAAA;AAAA,QAC/C,iBAAA,EAAmB,EAAA,CAAG,EAAA,CAAG,qBAAqB,CAAA;AAAA,QAC9C,aAAA,EAAmB,EAAA,CAAG,EAAA,CAAG,cAAc;AAAA,OACzC;AAAA,MACA,UAAA,EAAY;AAAA,QACV,KAAA;AAAA,QACA,SAAA,EAAmB,CAAA;AAAA;AAAA,QACnB,iBAAA,EAAmB,EAAA,CAAG,GAAA,CAAI,4BAA4B,CAAA;AAAA,QACtD;AAAA;AACF,KACD,CAAA;AAAA,EACH;AAEA,EAAA,OAAO,OAAA;AACT;AAEA,eAAe,KAAK,MAAA,EAAkD;AACpE,EAAA,MAAM,KAAA,GAAQ,IAAI,eAAA,CAAgB,MAAM,CAAA;AACxC,EAAA,MAAM,OAAO,MAAM,KAAA,CAAM,GAAG,IAAI,CAAA,CAAA,EAAI,KAAK,CAAA,CAAE,CAAA;AAC3C,EAAA,IAAI,CAAC,KAAK,EAAA,EAAI,MAAM,IAAI,KAAA,CAAM,CAAA,8BAAA,EAAiC,IAAA,CAAK,MAAM,CAAA,CAAE,CAAA;AAC5E,EAAA,OAAO,KAAK,IAAA,EAAK;AACnB;AAEA,SAAS,GAAG,CAAA,EAAoB;AAC9B,EAAA,IAAI,KAAK,IAAA,IAAQ,CAAA,KAAM,MAAA,IAAU,CAAA,KAAM,KAAK,OAAO,CAAA;AACnD,EAAA,MAAM,CAAA,GAAI,OAAO,CAAC,CAAA;AAClB,EAAA,OAAO,KAAA,CAAM,CAAC,CAAA,GAAI,CAAA,GAAI,CAAA;AACxB","file":"index.cjs","sourcesContent":["/**\n * Alpha Vantage fetcher for fin-ratios (TypeScript).\n *\n * Free tier: 25 requests/day. Premium: higher limits.\n * Get a free API key at https://www.alphavantage.co/support/#api-key\n *\n * @example\n * import { fetchAlphaVantage } from 'fin-ratios/fetchers/alphavantage'\n * const data = await fetchAlphaVantage('IBM', { apiKey: 'your_key' })\n * console.log(data.income.revenue)\n */\n\nimport type { IncomeStatement, BalanceSheet, CashFlowStatement, MarketData } from '../../types/index.js'\n\nconst BASE = 'https://www.alphavantage.co/query'\n\nexport interface AlphaVantageOptions {\n  apiKey: string\n  periods?: number\n  quarterly?: boolean\n}\n\nexport interface AlphaVantagePeriodData {\n  period: string\n  income: IncomeStatement\n  balance: BalanceSheet\n  cashFlow: CashFlowStatement\n  marketData: MarketData\n}\n\n/**\n * Fetch financial statements from Alpha Vantage for a given ticker.\n */\nexport async function fetchAlphaVantage(\n  ticker: string,\n  options: AlphaVantageOptions\n): Promise<AlphaVantagePeriodData[]> {\n  const { apiKey, periods = 4, quarterly = false } = options\n\n  const freq = quarterly ? 'quarterlyReports' : 'annualReports'\n\n  const [incData, balData, cfData, quoteData] = await Promise.all([\n    _get({ function: 'INCOME_STATEMENT', symbol: ticker, apikey: apiKey }),\n    _get({ function: 'BALANCE_SHEET',    symbol: ticker, apikey: apiKey }),\n    _get({ function: 'CASH_FLOW',        symbol: ticker, apikey: apiKey }),\n    _get({ function: 'GLOBAL_QUOTE',     symbol: ticker, apikey: apiKey }),\n  ]) as any[]\n\n  const incReports: any[] = (incData[freq] ?? []).slice(0, periods)\n  const balReports: any[] = (balData[freq] ?? []).slice(0, periods)\n  const cfReports:  any[] = (cfData[freq]  ?? []).slice(0, periods)\n  const quote = quoteData['Global Quote'] ?? {}\n\n  const price = _n(quote['05. price'])\n  const results: AlphaVantagePeriodData[] = []\n\n  for (let i = 0; i < incReports.length; i++) {\n    const inc = incReports[i] ?? {}\n    const bal = balReports[i] ?? {}\n    const cf  = cfReports[i]  ?? {}\n\n    results.push({\n      period: inc.fiscalDateEnding ?? '',\n      income: {\n        revenue:                    _n(inc.totalRevenue),\n        grossProfit:                _n(inc.grossProfit),\n        cogs:                       _n(inc.costOfRevenue),\n        ebit:                       _n(inc.ebit),\n        ebitda:                     _n(inc.ebitda),\n        netIncome:                  _n(inc.netIncome),\n        interestExpense:            Math.abs(_n(inc.interestExpense)),\n        incomeTaxExpense:           _n(inc.incomeTaxExpense),\n        ebt:                        _n(inc.incomeBeforeTax),\n        depreciationAndAmortization:_n(inc.depreciationAndAmortization),\n        sharesOutstanding:          _n(inc.commonStockSharesOutstanding),\n        eps:                        0,\n      },\n      balance: {\n        totalAssets:        _n(bal.totalAssets),\n        currentAssets:      _n(bal.totalCurrentAssets),\n        cash:               _n(bal.cashAndCashEquivalentsAtCarryingValue),\n        accountsReceivable: _n(bal.currentNetReceivables),\n        inventory:          _n(bal.inventory),\n        netPPE:             _n(bal.propertyPlantEquipmentNet),\n        goodwill:           _n(bal.goodwill),\n        retainedEarnings:   _n(bal.retainedEarnings),\n        totalLiabilities:   _n(bal.totalLiabilities),\n        currentLiabilities: _n(bal.totalCurrentLiabilities),\n        accountsPayable:    _n(bal.currentAccountsPayable),\n        longTermDebt:       _n(bal.longTermDebtNoncurrent),\n        totalDebt:          _n(bal.shortLongTermDebtTotal),\n        totalEquity:        _n(bal.totalShareholderEquity),\n        sharesOutstanding:  _n(bal.commonStockSharesOutstanding),\n      },\n      cashFlow: {\n        operatingCashFlow: _n(cf.operatingCashflow),\n        capex:             Math.abs(_n(cf.capitalExpenditures)),\n        investingCashFlow: _n(cf.cashflowFromInvestment),\n        financingCashFlow: _n(cf.cashflowFromFinancing),\n        dividendsPaid:     _n(cf.dividendPayout),\n      },\n      marketData: {\n        price,\n        marketCap:         0, // not returned by Alpha Vantage income statement endpoints\n        sharesOutstanding: _n(inc.commonStockSharesOutstanding),\n        ticker,\n      },\n    })\n  }\n\n  return results\n}\n\nasync function _get(params: Record<string, string>): Promise<unknown> {\n  const query = new URLSearchParams(params)\n  const resp = await fetch(`${BASE}?${query}`)\n  if (!resp.ok) throw new Error(`Alpha Vantage request failed: ${resp.status}`)\n  return resp.json()\n}\n\nfunction _n(v: unknown): number {\n  if (v == null || v === 'None' || v === '-') return 0\n  const n = Number(v)\n  return isNaN(n) ? 0 : n\n}\n"]}