fin-ratios 0.4.0 → 0.7.0

package/dist/fetchers/edgar/index.cjs

@@ -89,6 +89,32 @@ async function fetchEdgar(ticker, options = {}) {
   }
   return results;
 }
+function flattenEdgarData(filings) {
+  return [...filings].reverse().map((f) => ({
+    year: f.fiscalYear,
+    revenue: f.income.revenue,
+    grossProfit: f.income.grossProfit,
+    ebit: f.income.ebit,
+    ebt: f.income.ebt,
+    netIncome: f.income.netIncome,
+    incomeTaxExpense: f.income.incomeTaxExpense,
+    interestExpense: f.income.interestExpense,
+    totalAssets: f.balance.totalAssets,
+    totalEquity: f.balance.totalEquity,
+    totalDebt: f.balance.totalDebt || f.balance.longTermDebt,
+    cash: f.balance.cash,
+    currentAssets: f.balance.currentAssets,
+    currentLiabilities: f.balance.currentLiabilities,
+    capex: f.cashFlow.capex,
+    depreciation: f.income.depreciationAndAmortization,
+    operatingCashFlow: f.cashFlow.operatingCashFlow,
+    accountsReceivable: f.balance.accountsReceivable
+  }));
+}
+async function fetchEdgarFlat(ticker, options = {}) {
+  const filings = await fetchEdgar(ticker, options);
+  return flattenEdgarData(filings);
+}
 async function _get(url) {
   const resp = await fetch(url, { headers: HEADERS });
   if (!resp.ok) throw new Error(`EDGAR request failed: ${resp.status} ${url}`);
@@ -96,5 +122,7 @@ async function _get(url) {
 }
 
 exports.fetchEdgar = fetchEdgar;
+exports.fetchEdgarFlat = fetchEdgarFlat;
+exports.flattenEdgarData = flattenEdgarData;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/fetchers/edgar/index.ts"],"names":[],"mappings":";;;AAkBA,IAAM,mBAAA,GAAsB,iDAAA;AAC5B,IAAM,UAAA,GAAa,4CAAA;AAEnB,IAAM,OAAA,GAAU;AAAA,EACd,YAAA,EAAc,yCAAA;AAAA,EACd,iBAAA,EAAmB;AACrB,CAAA;AAgBA,eAAsB,UAAA,CACpB,MAAA,EACA,OAAA,GAAwB,EAAC,EACG;AAC5B,EAAA,MAAM,EAAE,QAAA,GAAW,CAAA,EAAE,GAAI,OAAA;AAGzB,EAAA,MAAM,SAAA,GAAa,MAAM,IAAA,CAAK,mBAAmB,CAAA;AACjD,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,MAAA,CAAO,SAAS,CAAA,CAAE,IAAA,CAAK,CAAA,CAAA,KAAK,CAAA,CAAE,MAAA,CAAO,WAAA,EAAY,KAAM,MAAA,CAAO,aAAa,CAAA;AAChG,EAAA,IAAI,CAAC,KAAA,EAAO,MAAM,IAAI,KAAA,CAAM,CAAA,cAAA,EAAiB,MAAM,CAAA,UAAA,CAAY,CAAA;AAE/D,EAAA,MAAM,MAAM,MAAA,CAAO,KAAA,CAAM,OAAO,CAAA,CAAE,QAAA,CAAS,IAAI,GAAG,CAAA;AAGlD,EAAA,MAAM,QAAS,MAAM,IAAA,CAAK,GAAG,UAAU,CAAA,IAAA,EAAO,GAAG,CAAA,KAAA,CAAO,CAAA;AAMxD,EAAA,MAAM,IAAA,GAAO,KAAA,CAAM,KAAA,CAAM,SAAS,KAAK,EAAC;AAExC,EAAA,SAAS,QAAQ,OAAA,EAAiD;AAChE,IAAA,MAAM,UAAU,IAAA,CAAK,OAAO,CAAA,EAAG,KAAA,EAAO,OAAO,EAAC;AAC9C,IAAA,OAAO,QACJ,MAAA,CAAO,CAAA,CAAA,KAAK,CAAA,CAAE,IAAA,KAAS,MAAM,CAAA,CAC7B,IAAA,CAAK,CAAC,CAAA,EAAG,MAAM,CAAA,CAAE,GAAA,CAAI,aAAA,CAAc,CAAA,CAAE,GAAG,CAAC,CAAA;AAAA,EAC9C;AAEA,EAAA,SAAS,cAAA,CAAe,SAAiB,IAAA,EAAsB;AAC7D,IAAA,MAAM,MAAA,GAAS,QAAQ,OAAO,CAAA;AAC9B,IAAA,MAAM,KAAA,GAAQ,OAAO,IAAA,CAAK,CAAA,CAAA,KAAK,EAAE,GAAA,CAAI,UAAA,CAAW,IAAI,CAAC,CAAA;AACrD,IAAA,OAAO,OAAO,GAAA,IAAO,CAAA;AAAA,EACvB;AAGA,EAAA,MAAM,iBAAiB,OAAA,CAAQ,UAAU,EAAE,MAAA,CAAO,OAAA,CAAQ,qDAAqD,CAAC,CAAA;AAChH,EAAA,MAAM,QAAQ,CAAC,GAAG,IAAI,GAAA,CAAI,cAAA,CAAe,IAAI,CAAA,CAAA,KAAK,CAAA,CAAE,IAAI,KAAA,CAAM,CAAA,EAAG,CAAC,CAAC,CAAC,CAAC,CAAA,CAAE,KAAA,CAAM,GAAG,QAAQ,CAAA;AAExF,EAAA,MAAM,UAA6B,EAAC;AAEpC,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,MAAM,MAAQ,cAAA,CAAe,UAAA,EAAY,IAAI,CAAA,IAAK,cAAA,CAAe,uDAAuD,IAAI,CAAA;AAC5H,IAAA,MAAM,EAAA,GAAQ,cAAA,CAAe,eAAA,EAAiB,IAAI,CAAA;AAClD,IAAA,MAAM,IAAA,GAAQ,cAAA,CAAe,qBAAA,EAAuB,IAAI,CAAA;AACxD,IAAA,MAAM,EAAA,GAAQ,cAAA,CAAe,QAAA,EAAU,IAAI,CAAA;AAC3C,IAAA,MAAM,EAAA,GAAQ,cAAA,CAAe,eAAA,EAAiB,IAAI,CAAA;AAClD,IAAA,MAAM,IAAA,GAAQ,cAAA,CAAe,uCAAA,EAAyC,IAAI,CAAA;AAC1E,IAAA,MAAM,EAAA,GAAQ,cAAA,CAAe,8BAAA,EAAgC,IAAI,CAAA;AACjE,IAAA,MAAM,GAAA,GAAQ,cAAA,CAAe,cAAA,EAAgB,IAAI,CAAA;AACjD,IAAA,MAAM,EAAA,GAAQ,cAAA,CAAe,oBAAA,EAAsB,IAAI,CAAA;AACvD,IAAA,MAAM,EAAA,GAAQ,cAAA,CAAe,aAAA,EAAe,IAAI,CAAA;AAChD,IAAA,MAAM,GAAA,GAAQ,cAAA,CAAe,cAAA,EAAgB,IAAI,CAAA;AACjD,IAAA,MAAM,EAAA,GAAQ,cAAA,CAAe,oCAAA,EAAsC,IAAI,CAAA;AACvE,IAAA,MAAM,EAAA,GAAQ,cAAA,CAAe,oBAAA,EAAsB,IAAI,CAAA;AACvD,IAAA,MAAM,GAAA,GAAQ,cAAA,CAAe,4CAAA,EAA8C,IAAI,CAAA;AAC/E,IAAA,MAAM,KAAA,GAAQ,cAAA,CAAe,4CAAA,EAA8C,IAAI,CAAA;AAC/E,IAAA,MAAM,EAAA,GAAQ,cAAA,CAAe,aAAA,EAAe,IAAI,CAAA;AAChD,IAAA,MAAM,GAAA,GAAQ,cAAA,CAAe,iBAAA,EAAmB,IAAI,CAAA;AACpD,IAAA,MAAM,MAAQ,cAAA,CAAe,kBAAA,EAAoB,IAAI,CAAA,IAAK,cAAA,CAAe,sBAAsB,IAAI,CAAA;AAEnG,IAAA,OAAA,CAAQ,IAAA,CAAK;AAAA,MACX,UAAA,EAAY,IAAA;AAAA,MACZ,MAAA,EAAQ;AAAA,QACN,OAAA,EAAS,GAAA;AAAA,QAAK,WAAA,EAAa,EAAA;AAAA,QAAI,MAAM,GAAA,GAAM,EAAA;AAAA,QAC3C,IAAA;AAAA,QAAM,MAAA,EAAQ,CAAA;AAAA,QAAG,SAAA,EAAW,EAAA;AAAA,QAC5B,eAAA,EAAiB,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA;AAAA,QAAG,gBAAA,EAAkB,GAAA;AAAA,QAAK,KAAK,EAAA,GAAK,GAAA;AAAA,QACjE,2BAAA,EAA6B,CAAA;AAAA,QAAG,iBAAA,EAAmB,CAAA;AAAA,QAAG,GAAA,EAAK;AAAA,OAC7D;AAAA,MACA,OAAA,EAAS;AAAA,QACP,WAAA,EAAa,EAAA;AAAA,QAAI,aAAA,EAAe,EAAA;AAAA,QAAI,IAAA;AAAA,QAAM,kBAAA,EAAoB,EAAA;AAAA,QAC9D,SAAA,EAAW,GAAA;AAAA,QAAK,MAAA,EAAQ,CAAA;AAAA,QAAG,QAAA,EAAU,CAAA;AAAA,QACrC,gBAAA,EAAkB,EAAA;AAAA,QAAI,gBAAA,EAAkB,EAAA;AAAA,QAAI,kBAAA,EAAoB,EAAA;AAAA,QAChE,eAAA,EAAiB,CAAA;AAAA,QAAG,YAAA,EAAc,GAAA;AAAA,QAAK,SAAA,EAAW,GAAA;AAAA,QAClD,WAAA,EAAa,EAAA;AAAA,QAAI,iBAAA,EAAmB;AAAA,OACtC;AAAA,MACA,QAAA,EAAU;AAAA,QACR,iBAAA,EAAmB,GAAA;AAAA,QAAK,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAK,CAAA;AAAA,QAC7C,iBAAA,EAAmB,CAAA;AAAA,QAAG,iBAAA,EAAmB;AAAA;AAC3C,KACD,CAAA;AAAA,EACH;AAEA,EAAA,OAAO,OAAA;AACT;AAEA,eAAe,KAAK,GAAA,EAA+B;AACjD,EAAA,MAAM,OAAO,MAAM,KAAA,CAAM,KAAK,EAAE,OAAA,EAAS,SAAS,CAAA;AAClD,EAAA,IAAI,CAAC,IAAA,CAAK,EAAA,EAAI,MAAM,IAAI,KAAA,CAAM,CAAA,sBAAA,EAAyB,IAAA,CAAK,MAAM,CAAA,CAAA,EAAI,GAAG,CAAA,CAAE,CAAA;AAC3E,EAAA,OAAO,KAAK,IAAA,EAAK;AACnB","file":"index.cjs","sourcesContent":["/**\n * SEC EDGAR fetcher for fin-ratios (TypeScript).\n *\n * Fetches financial data from the free SEC EDGAR XBRL API.\n * No API key required. US companies only.\n *\n * Rate limit: ~10 requests/second (SEC guidelines). Add delays for bulk use.\n *\n * @example\n * import { fetchEdgar } from 'fin-ratios/fetchers/edgar'\n * const filings = await fetchEdgar('AAPL', { numYears: 3 })\n * for (const f of filings) {\n *   console.log(`${f.fiscalYear}: Revenue $${(f.income.revenue/1e9).toFixed(1)}B`)\n * }\n */\n\nimport type { IncomeStatement, BalanceSheet, CashFlowStatement } from '../../types/index.js'\n\nconst COMPANY_TICKERS_URL = 'https://data.sec.gov/files/company_tickers.json'\nconst EDGAR_BASE = 'https://data.sec.gov/api/xbrl/companyfacts'\n\nconst HEADERS = {\n  'User-Agent': 'fin-ratios/0.1.0 contact@fin-ratios.dev',\n  'Accept-Encoding': 'gzip, deflate',\n}\n\nexport interface EdgarOptions {\n  numYears?: number\n}\n\nexport interface EdgarFilingData {\n  fiscalYear: string\n  income: IncomeStatement\n  balance: BalanceSheet\n  cashFlow: CashFlowStatement\n}\n\n/**\n * Fetch multi-year annual filings from SEC EDGAR for a US stock ticker.\n */\nexport async function fetchEdgar(\n  ticker: string,\n  options: EdgarOptions = {}\n): Promise<EdgarFilingData[]> {\n  const { numYears = 3 } = options\n\n  // Step 1: Resolve ticker → CIK\n  const tickerMap = (await _get(COMPANY_TICKERS_URL)) as Record<string, { cik_str: number; ticker: string; title: string }>\n  const entry = Object.values(tickerMap).find(v => v.ticker.toUpperCase() === ticker.toUpperCase())\n  if (!entry) throw new Error(`EDGAR: ticker ${ticker} not found`)\n\n  const cik = String(entry.cik_str).padStart(10, '0')\n\n  // Step 2: Fetch company facts (XBRL)\n  const facts = (await _get(`${EDGAR_BASE}/CIK${cik}.json`)) as {\n    facts: {\n      'us-gaap'?: Record<string, { units: { USD?: { val: number; end: string; form: string; fp: string }[] } }>\n    }\n  }\n\n  const gaap = facts.facts['us-gaap'] ?? {}\n\n  function _annual(concept: string): { end: string; val: number }[] {\n    const entries = gaap[concept]?.units?.USD ?? []\n    return entries\n      .filter(e => e.form === '10-K')\n      .sort((a, b) => b.end.localeCompare(a.end))\n  }\n\n  function _latestForYear(concept: string, year: string): number {\n    const annual = _annual(concept)\n    const match = annual.find(e => e.end.startsWith(year))\n    return match?.val ?? 0\n  }\n\n  // Collect available fiscal years from revenue\n  const revenueEntries = _annual('Revenues').concat(_annual('RevenueFromContractWithCustomerExcludingAssessedTax'))\n  const years = [...new Set(revenueEntries.map(e => e.end.slice(0, 4)))].slice(0, numYears)\n\n  const results: EdgarFilingData[] = []\n\n  for (const year of years) {\n    const rev   = _latestForYear('Revenues', year) || _latestForYear('RevenueFromContractWithCustomerExcludingAssessedTax', year)\n    const ni    = _latestForYear('NetIncomeLoss', year)\n    const ebit  = _latestForYear('OperatingIncomeLoss', year)\n    const ta    = _latestForYear('Assets', year)\n    const ca    = _latestForYear('AssetsCurrent', year)\n    const cash  = _latestForYear('CashAndCashEquivalentsAtCarryingValue', year)\n    const ar    = _latestForYear('AccountsReceivableNetCurrent', year)\n    const inv   = _latestForYear('InventoryNet', year)\n    const cl    = _latestForYear('LiabilitiesCurrent', year)\n    const tl    = _latestForYear('Liabilities', year)\n    const ltd   = _latestForYear('LongTermDebt', year)\n    const re    = _latestForYear('RetainedEarningsAccumulatedDeficit', year)\n    const te    = _latestForYear('StockholdersEquity', year)\n    const ocf   = _latestForYear('NetCashProvidedByUsedInOperatingActivities', year)\n    const capex = _latestForYear('PaymentsToAcquirePropertyPlantAndEquipment', year)\n    const gp    = _latestForYear('GrossProfit', year)\n    const int   = _latestForYear('InterestExpense', year)\n    const tax   = _latestForYear('IncomeTaxExpense', year) || _latestForYear('IncomeTaxesPaidNet', year)\n\n    results.push({\n      fiscalYear: year,\n      income: {\n        revenue: rev, grossProfit: gp, cogs: rev - gp,\n        ebit, ebitda: 0, netIncome: ni,\n        interestExpense: Math.abs(int), incomeTaxExpense: tax, ebt: ni + tax,\n        depreciationAndAmortization: 0, sharesOutstanding: 0, eps: 0,\n      },\n      balance: {\n        totalAssets: ta, currentAssets: ca, cash, accountsReceivable: ar,\n        inventory: inv, netPPE: 0, goodwill: 0,\n        retainedEarnings: re, totalLiabilities: tl, currentLiabilities: cl,\n        accountsPayable: 0, longTermDebt: ltd, totalDebt: ltd,\n        totalEquity: te, sharesOutstanding: 0,\n      },\n      cashFlow: {\n        operatingCashFlow: ocf, capex: Math.abs(capex),\n        investingCashFlow: 0, financingCashFlow: 0,\n      },\n    })\n  }\n\n  return results\n}\n\nasync function _get(url: string): Promise<unknown> {\n  const resp = await fetch(url, { headers: HEADERS })\n  if (!resp.ok) throw new Error(`EDGAR request failed: ${resp.status} ${url}`)\n  return resp.json()\n}\n"]}
+{"version":3,"sources":["../../../src/fetchers/edgar/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * SEC EDGAR fetcher for fin-ratios (TypeScript).\n *\n * Fetches financial data from the free SEC EDGAR XBRL API.\n * No API key required. US companies only.\n *\n * Rate limit: ~10 requests/second (SEC guidelines). Add delays for bulk use.\n *\n * @example\n * import { fetchEdgar } from 'fin-ratios/fetchers/edgar'\n * const filings = await fetchEdgar('AAPL', { numYears: 3 })\n * for (const f of filings) {\n *   console.log(`${f.fiscalYear}: Revenue $${(f.income.revenue/1e9).toFixed(1)}B`)\n * }\n */\n\nimport type { IncomeStatement, BalanceSheet, CashFlowStatement } from '../../types/index.js'\n\nconst COMPANY_TICKERS_URL = 'https://data.sec.gov/files/company_tickers.json'\nconst EDGAR_BASE = 'https://data.sec.gov/api/xbrl/companyfacts'\n\nconst HEADERS = {\n  'User-Agent': 'fin-ratios/0.1.0 contact@fin-ratios.dev',\n  'Accept-Encoding': 'gzip, deflate',\n}\n\nexport interface EdgarOptions {\n  numYears?: number\n}\n\nexport interface EdgarFilingData {\n  fiscalYear: string\n  income: IncomeStatement\n  balance: BalanceSheet\n  cashFlow: CashFlowStatement\n}\n\n/**\n * Fetch multi-year annual filings from SEC EDGAR for a US stock ticker.\n */\nexport async function fetchEdgar(\n  ticker: string,\n  options: EdgarOptions = {}\n): Promise<EdgarFilingData[]> {\n  const { numYears = 3 } = options\n\n  // Step 1: Resolve ticker → CIK\n  const tickerMap = (await _get(COMPANY_TICKERS_URL)) as Record<string, { cik_str: number; ticker: string; title: string }>\n  const entry = Object.values(tickerMap).find(v => v.ticker.toUpperCase() === ticker.toUpperCase())\n  if (!entry) throw new Error(`EDGAR: ticker ${ticker} not found`)\n\n  const cik = String(entry.cik_str).padStart(10, '0')\n\n  // Step 2: Fetch company facts (XBRL)\n  const facts = (await _get(`${EDGAR_BASE}/CIK${cik}.json`)) as {\n    facts: {\n      'us-gaap'?: Record<string, { units: { USD?: { val: number; end: string; form: string; fp: string }[] } }>\n    }\n  }\n\n  const gaap = facts.facts['us-gaap'] ?? {}\n\n  function _annual(concept: string): { end: string; val: number }[] {\n    const entries = gaap[concept]?.units?.USD ?? []\n    return entries\n      .filter(e => e.form === '10-K')\n      .sort((a, b) => b.end.localeCompare(a.end))\n  }\n\n  function _latestForYear(concept: string, year: string): number {\n    const annual = _annual(concept)\n    const match = annual.find(e => e.end.startsWith(year))\n    return match?.val ?? 0\n  }\n\n  // Collect available fiscal years from revenue\n  const revenueEntries = _annual('Revenues').concat(_annual('RevenueFromContractWithCustomerExcludingAssessedTax'))\n  const years = [...new Set(revenueEntries.map(e => e.end.slice(0, 4)))].slice(0, numYears)\n\n  const results: EdgarFilingData[] = []\n\n  for (const year of years) {\n    const rev   = _latestForYear('Revenues', year) || _latestForYear('RevenueFromContractWithCustomerExcludingAssessedTax', year)\n    const ni    = _latestForYear('NetIncomeLoss', year)\n    const ebit  = _latestForYear('OperatingIncomeLoss', year)\n    const ta    = _latestForYear('Assets', year)\n    const ca    = _latestForYear('AssetsCurrent', year)\n    const cash  = _latestForYear('CashAndCashEquivalentsAtCarryingValue', year)\n    const ar    = _latestForYear('AccountsReceivableNetCurrent', year)\n    const inv   = _latestForYear('InventoryNet', year)\n    const cl    = _latestForYear('LiabilitiesCurrent', year)\n    const tl    = _latestForYear('Liabilities', year)\n    const ltd   = _latestForYear('LongTermDebt', year)\n    const re    = _latestForYear('RetainedEarningsAccumulatedDeficit', year)\n    const te    = _latestForYear('StockholdersEquity', year)\n    const ocf   = _latestForYear('NetCashProvidedByUsedInOperatingActivities', year)\n    const capex = _latestForYear('PaymentsToAcquirePropertyPlantAndEquipment', year)\n    const gp    = _latestForYear('GrossProfit', year)\n    const int   = _latestForYear('InterestExpense', year)\n    const tax   = _latestForYear('IncomeTaxExpense', year) || _latestForYear('IncomeTaxesPaidNet', year)\n\n    results.push({\n      fiscalYear: year,\n      income: {\n        revenue: rev, grossProfit: gp, cogs: rev - gp,\n        ebit, ebitda: 0, netIncome: ni,\n        interestExpense: Math.abs(int), incomeTaxExpense: tax, ebt: ni + tax,\n        depreciationAndAmortization: 0, sharesOutstanding: 0, eps: 0,\n      },\n      balance: {\n        totalAssets: ta, currentAssets: ca, cash, accountsReceivable: ar,\n        inventory: inv, netPPE: 0, goodwill: 0,\n        retainedEarnings: re, totalLiabilities: tl, currentLiabilities: cl,\n        accountsPayable: 0, longTermDebt: ltd, totalDebt: ltd,\n        totalEquity: te, sharesOutstanding: 0,\n      },\n      cashFlow: {\n        operatingCashFlow: ocf, capex: Math.abs(capex),\n        investingCashFlow: 0, financingCashFlow: 0,\n      },\n    })\n  }\n\n  return results\n}\n\n/**\n * Flatten EDGAR filing data into the format expected by scoring utilities\n * (moatScore, capitalAllocationScore, earningsQualityScore, qualityScore).\n * Returns records in chronological order (oldest first).\n */\nexport function flattenEdgarData(filings: EdgarFilingData[]): Array<{\n  year: string\n  revenue: number\n  grossProfit: number\n  ebit: number\n  ebt: number\n  netIncome: number\n  incomeTaxExpense: number\n  interestExpense: number\n  totalAssets: number\n  totalEquity: number\n  totalDebt: number\n  cash: number\n  currentAssets: number\n  currentLiabilities: number\n  capex: number\n  depreciation: number\n  operatingCashFlow: number\n  accountsReceivable: number\n}> {\n  return [...filings]\n    .reverse() // EDGAR returns newest-first; we want oldest-first\n    .map(f => ({\n      year:               f.fiscalYear,\n      revenue:            f.income.revenue,\n      grossProfit:        f.income.grossProfit,\n      ebit:               f.income.ebit,\n      ebt:                f.income.ebt,\n      netIncome:          f.income.netIncome,\n      incomeTaxExpense:   f.income.incomeTaxExpense,\n      interestExpense:    f.income.interestExpense,\n      totalAssets:        f.balance.totalAssets,\n      totalEquity:        f.balance.totalEquity,\n      totalDebt:          f.balance.totalDebt || f.balance.longTermDebt,\n      cash:               f.balance.cash,\n      currentAssets:      f.balance.currentAssets,\n      currentLiabilities: f.balance.currentLiabilities,\n      capex:              f.cashFlow.capex,\n      depreciation:       f.income.depreciationAndAmortization,\n      operatingCashFlow:  f.cashFlow.operatingCashFlow,\n      accountsReceivable: f.balance.accountsReceivable,\n    }))\n}\n\n/**\n * Fetch EDGAR data for a ticker and return flat records ready for scoring utilities.\n * Records are returned oldest-first.\n */\nexport async function fetchEdgarFlat(\n  ticker: string,\n  options: EdgarOptions = {},\n): Promise<ReturnType<typeof flattenEdgarData>> {\n  const filings = await fetchEdgar(ticker, options)\n  return flattenEdgarData(filings)\n}\n\nasync function _get(url: string): Promise<unknown> {\n  const resp = await fetch(url, { headers: HEADERS })\n  if (!resp.ok) throw new Error(`EDGAR request failed: ${resp.status} ${url}`)\n  return resp.json()\n}\n"]}

package/dist/fetchers/edgar/index.d.cts

@@ -29,5 +29,35 @@ interface EdgarFilingData {
  * Fetch multi-year annual filings from SEC EDGAR for a US stock ticker.
  */
 declare function fetchEdgar(ticker: string, options?: EdgarOptions): Promise<EdgarFilingData[]>;
+/**
+ * Flatten EDGAR filing data into the format expected by scoring utilities
+ * (moatScore, capitalAllocationScore, earningsQualityScore, qualityScore).
+ * Returns records in chronological order (oldest first).
+ */
+declare function flattenEdgarData(filings: EdgarFilingData[]): Array<{
+    year: string;
+    revenue: number;
+    grossProfit: number;
+    ebit: number;
+    ebt: number;
+    netIncome: number;
+    incomeTaxExpense: number;
+    interestExpense: number;
+    totalAssets: number;
+    totalEquity: number;
+    totalDebt: number;
+    cash: number;
+    currentAssets: number;
+    currentLiabilities: number;
+    capex: number;
+    depreciation: number;
+    operatingCashFlow: number;
+    accountsReceivable: number;
+}>;
+/**
+ * Fetch EDGAR data for a ticker and return flat records ready for scoring utilities.
+ * Records are returned oldest-first.
+ */
+declare function fetchEdgarFlat(ticker: string, options?: EdgarOptions): Promise<ReturnType<typeof flattenEdgarData>>;
 
-export { type EdgarFilingData, type EdgarOptions, fetchEdgar };
+export { type EdgarFilingData, type EdgarOptions, fetchEdgar, fetchEdgarFlat, flattenEdgarData };

package/dist/fetchers/edgar/index.d.ts

@@ -29,5 +29,35 @@ interface EdgarFilingData {
  * Fetch multi-year annual filings from SEC EDGAR for a US stock ticker.
  */
 declare function fetchEdgar(ticker: string, options?: EdgarOptions): Promise<EdgarFilingData[]>;
+/**
+ * Flatten EDGAR filing data into the format expected by scoring utilities
+ * (moatScore, capitalAllocationScore, earningsQualityScore, qualityScore).
+ * Returns records in chronological order (oldest first).
+ */
+declare function flattenEdgarData(filings: EdgarFilingData[]): Array<{
+    year: string;
+    revenue: number;
+    grossProfit: number;
+    ebit: number;
+    ebt: number;
+    netIncome: number;
+    incomeTaxExpense: number;
+    interestExpense: number;
+    totalAssets: number;
+    totalEquity: number;
+    totalDebt: number;
+    cash: number;
+    currentAssets: number;
+    currentLiabilities: number;
+    capex: number;
+    depreciation: number;
+    operatingCashFlow: number;
+    accountsReceivable: number;
+}>;
+/**
+ * Fetch EDGAR data for a ticker and return flat records ready for scoring utilities.
+ * Records are returned oldest-first.
+ */
+declare function fetchEdgarFlat(ticker: string, options?: EdgarOptions): Promise<ReturnType<typeof flattenEdgarData>>;
 
-export { type EdgarFilingData, type EdgarOptions, fetchEdgar };
+export { type EdgarFilingData, type EdgarOptions, fetchEdgar, fetchEdgarFlat, flattenEdgarData };

package/dist/fetchers/edgar/index.js

@@ -87,12 +87,38 @@ async function fetchEdgar(ticker, options = {}) {
   }
   return results;
 }
+function flattenEdgarData(filings) {
+  return [...filings].reverse().map((f) => ({
+    year: f.fiscalYear,
+    revenue: f.income.revenue,
+    grossProfit: f.income.grossProfit,
+    ebit: f.income.ebit,
+    ebt: f.income.ebt,
+    netIncome: f.income.netIncome,
+    incomeTaxExpense: f.income.incomeTaxExpense,
+    interestExpense: f.income.interestExpense,
+    totalAssets: f.balance.totalAssets,
+    totalEquity: f.balance.totalEquity,
+    totalDebt: f.balance.totalDebt || f.balance.longTermDebt,
+    cash: f.balance.cash,
+    currentAssets: f.balance.currentAssets,
+    currentLiabilities: f.balance.currentLiabilities,
+    capex: f.cashFlow.capex,
+    depreciation: f.income.depreciationAndAmortization,
+    operatingCashFlow: f.cashFlow.operatingCashFlow,
+    accountsReceivable: f.balance.accountsReceivable
+  }));
+}
+async function fetchEdgarFlat(ticker, options = {}) {
+  const filings = await fetchEdgar(ticker, options);
+  return flattenEdgarData(filings);
+}
 async function _get(url) {
   const resp = await fetch(url, { headers: HEADERS });
   if (!resp.ok) throw new Error(`EDGAR request failed: ${resp.status} ${url}`);
   return resp.json();
 }
 
-export { fetchEdgar };
+export { fetchEdgar, fetchEdgarFlat, flattenEdgarData };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/fetchers/edgar/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/fetchers/edgar/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * SEC EDGAR fetcher for fin-ratios (TypeScript).\n *\n * Fetches financial data from the free SEC EDGAR XBRL API.\n * No API key required. US companies only.\n *\n * Rate limit: ~10 requests/second (SEC guidelines). Add delays for bulk use.\n *\n * @example\n * import { fetchEdgar } from 'fin-ratios/fetchers/edgar'\n * const filings = await fetchEdgar('AAPL', { numYears: 3 })\n * for (const f of filings) {\n *   console.log(`${f.fiscalYear}: Revenue $${(f.income.revenue/1e9).toFixed(1)}B`)\n * }\n */\n\nimport type { IncomeStatement, BalanceSheet, CashFlowStatement } from '../../types/index.js'\n\nconst COMPANY_TICKERS_URL = 'https://data.sec.gov/files/company_tickers.json'\nconst EDGAR_BASE = 'https://data.sec.gov/api/xbrl/companyfacts'\n\nconst HEADERS = {\n  'User-Agent': 'fin-ratios/0.1.0 contact@fin-ratios.dev',\n  'Accept-Encoding': 'gzip, deflate',\n}\n\nexport interface EdgarOptions {\n  numYears?: number\n}\n\nexport interface EdgarFilingData {\n  fiscalYear: string\n  income: IncomeStatement\n  balance: BalanceSheet\n  cashFlow: CashFlowStatement\n}\n\n/**\n * Fetch multi-year annual filings from SEC EDGAR for a US stock ticker.\n */\nexport async function fetchEdgar(\n  ticker: string,\n  options: EdgarOptions = {}\n): Promise<EdgarFilingData[]> {\n  const { numYears = 3 } = options\n\n  // Step 1: Resolve ticker → CIK\n  const tickerMap = (await _get(COMPANY_TICKERS_URL)) as Record<string, { cik_str: number; ticker: string; title: string }>\n  const entry = Object.values(tickerMap).find(v => v.ticker.toUpperCase() === ticker.toUpperCase())\n  if (!entry) throw new Error(`EDGAR: ticker ${ticker} not found`)\n\n  const cik = String(entry.cik_str).padStart(10, '0')\n\n  // Step 2: Fetch company facts (XBRL)\n  const facts = (await _get(`${EDGAR_BASE}/CIK${cik}.json`)) as {\n    facts: {\n      'us-gaap'?: Record<string, { units: { USD?: { val: number; end: string; form: string; fp: string }[] } }>\n    }\n  }\n\n  const gaap = facts.facts['us-gaap'] ?? {}\n\n  function _annual(concept: string): { end: string; val: number }[] {\n    const entries = gaap[concept]?.units?.USD ?? []\n    return entries\n      .filter(e => e.form === '10-K')\n      .sort((a, b) => b.end.localeCompare(a.end))\n  }\n\n  function _latestForYear(concept: string, year: string): number {\n    const annual = _annual(concept)\n    const match = annual.find(e => e.end.startsWith(year))\n    return match?.val ?? 0\n  }\n\n  // Collect available fiscal years from revenue\n  const revenueEntries = _annual('Revenues').concat(_annual('RevenueFromContractWithCustomerExcludingAssessedTax'))\n  const years = [...new Set(revenueEntries.map(e => e.end.slice(0, 4)))].slice(0, numYears)\n\n  const results: EdgarFilingData[] = []\n\n  for (const year of years) {\n    const rev   = _latestForYear('Revenues', year) || _latestForYear('RevenueFromContractWithCustomerExcludingAssessedTax', year)\n    const ni    = _latestForYear('NetIncomeLoss', year)\n    const ebit  = _latestForYear('OperatingIncomeLoss', year)\n    const ta    = _latestForYear('Assets', year)\n    const ca    = _latestForYear('AssetsCurrent', year)\n    const cash  = _latestForYear('CashAndCashEquivalentsAtCarryingValue', year)\n    const ar    = _latestForYear('AccountsReceivableNetCurrent', year)\n    const inv   = _latestForYear('InventoryNet', year)\n    const cl    = _latestForYear('LiabilitiesCurrent', year)\n    const tl    = _latestForYear('Liabilities', year)\n    const ltd   = _latestForYear('LongTermDebt', year)\n    const re    = _latestForYear('RetainedEarningsAccumulatedDeficit', year)\n    const te    = _latestForYear('StockholdersEquity', year)\n    const ocf   = _latestForYear('NetCashProvidedByUsedInOperatingActivities', year)\n    const capex = _latestForYear('PaymentsToAcquirePropertyPlantAndEquipment', year)\n    const gp    = _latestForYear('GrossProfit', year)\n    const int   = _latestForYear('InterestExpense', year)\n    const tax   = _latestForYear('IncomeTaxExpense', year) || _latestForYear('IncomeTaxesPaidNet', year)\n\n    results.push({\n      fiscalYear: year,\n      income: {\n        revenue: rev, grossProfit: gp, cogs: rev - gp,\n        ebit, ebitda: 0, netIncome: ni,\n        interestExpense: Math.abs(int), incomeTaxExpense: tax, ebt: ni + tax,\n        depreciationAndAmortization: 0, sharesOutstanding: 0, eps: 0,\n      },\n      balance: {\n        totalAssets: ta, currentAssets: ca, cash, accountsReceivable: ar,\n        inventory: inv, netPPE: 0, goodwill: 0,\n        retainedEarnings: re, totalLiabilities: tl, currentLiabilities: cl,\n        accountsPayable: 0, longTermDebt: ltd, totalDebt: ltd,\n        totalEquity: te, sharesOutstanding: 0,\n      },\n      cashFlow: {\n        operatingCashFlow: ocf, capex: Math.abs(capex),\n        investingCashFlow: 0, financingCashFlow: 0,\n      },\n    })\n  }\n\n  return results\n}\n\nasync function _get(url: string): Promise<unknown> {\n  const resp = await fetch(url, { headers: HEADERS })\n  if (!resp.ok) throw new Error(`EDGAR request failed: ${resp.status} ${url}`)\n  return resp.json()\n}\n"]}
+{"version":3,"sources":["../../../src/fetchers/edgar/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * SEC EDGAR fetcher for fin-ratios (TypeScript).\n *\n * Fetches financial data from the free SEC EDGAR XBRL API.\n * No API key required. US companies only.\n *\n * Rate limit: ~10 requests/second (SEC guidelines). Add delays for bulk use.\n *\n * @example\n * import { fetchEdgar } from 'fin-ratios/fetchers/edgar'\n * const filings = await fetchEdgar('AAPL', { numYears: 3 })\n * for (const f of filings) {\n *   console.log(`${f.fiscalYear}: Revenue $${(f.income.revenue/1e9).toFixed(1)}B`)\n * }\n */\n\nimport type { IncomeStatement, BalanceSheet, CashFlowStatement } from '../../types/index.js'\n\nconst COMPANY_TICKERS_URL = 'https://data.sec.gov/files/company_tickers.json'\nconst EDGAR_BASE = 'https://data.sec.gov/api/xbrl/companyfacts'\n\nconst HEADERS = {\n  'User-Agent': 'fin-ratios/0.1.0 contact@fin-ratios.dev',\n  'Accept-Encoding': 'gzip, deflate',\n}\n\nexport interface EdgarOptions {\n  numYears?: number\n}\n\nexport interface EdgarFilingData {\n  fiscalYear: string\n  income: IncomeStatement\n  balance: BalanceSheet\n  cashFlow: CashFlowStatement\n}\n\n/**\n * Fetch multi-year annual filings from SEC EDGAR for a US stock ticker.\n */\nexport async function fetchEdgar(\n  ticker: string,\n  options: EdgarOptions = {}\n): Promise<EdgarFilingData[]> {\n  const { numYears = 3 } = options\n\n  // Step 1: Resolve ticker → CIK\n  const tickerMap = (await _get(COMPANY_TICKERS_URL)) as Record<string, { cik_str: number; ticker: string; title: string }>\n  const entry = Object.values(tickerMap).find(v => v.ticker.toUpperCase() === ticker.toUpperCase())\n  if (!entry) throw new Error(`EDGAR: ticker ${ticker} not found`)\n\n  const cik = String(entry.cik_str).padStart(10, '0')\n\n  // Step 2: Fetch company facts (XBRL)\n  const facts = (await _get(`${EDGAR_BASE}/CIK${cik}.json`)) as {\n    facts: {\n      'us-gaap'?: Record<string, { units: { USD?: { val: number; end: string; form: string; fp: string }[] } }>\n    }\n  }\n\n  const gaap = facts.facts['us-gaap'] ?? {}\n\n  function _annual(concept: string): { end: string; val: number }[] {\n    const entries = gaap[concept]?.units?.USD ?? []\n    return entries\n      .filter(e => e.form === '10-K')\n      .sort((a, b) => b.end.localeCompare(a.end))\n  }\n\n  function _latestForYear(concept: string, year: string): number {\n    const annual = _annual(concept)\n    const match = annual.find(e => e.end.startsWith(year))\n    return match?.val ?? 0\n  }\n\n  // Collect available fiscal years from revenue\n  const revenueEntries = _annual('Revenues').concat(_annual('RevenueFromContractWithCustomerExcludingAssessedTax'))\n  const years = [...new Set(revenueEntries.map(e => e.end.slice(0, 4)))].slice(0, numYears)\n\n  const results: EdgarFilingData[] = []\n\n  for (const year of years) {\n    const rev   = _latestForYear('Revenues', year) || _latestForYear('RevenueFromContractWithCustomerExcludingAssessedTax', year)\n    const ni    = _latestForYear('NetIncomeLoss', year)\n    const ebit  = _latestForYear('OperatingIncomeLoss', year)\n    const ta    = _latestForYear('Assets', year)\n    const ca    = _latestForYear('AssetsCurrent', year)\n    const cash  = _latestForYear('CashAndCashEquivalentsAtCarryingValue', year)\n    const ar    = _latestForYear('AccountsReceivableNetCurrent', year)\n    const inv   = _latestForYear('InventoryNet', year)\n    const cl    = _latestForYear('LiabilitiesCurrent', year)\n    const tl    = _latestForYear('Liabilities', year)\n    const ltd   = _latestForYear('LongTermDebt', year)\n    const re    = _latestForYear('RetainedEarningsAccumulatedDeficit', year)\n    const te    = _latestForYear('StockholdersEquity', year)\n    const ocf   = _latestForYear('NetCashProvidedByUsedInOperatingActivities', year)\n    const capex = _latestForYear('PaymentsToAcquirePropertyPlantAndEquipment', year)\n    const gp    = _latestForYear('GrossProfit', year)\n    const int   = _latestForYear('InterestExpense', year)\n    const tax   = _latestForYear('IncomeTaxExpense', year) || _latestForYear('IncomeTaxesPaidNet', year)\n\n    results.push({\n      fiscalYear: year,\n      income: {\n        revenue: rev, grossProfit: gp, cogs: rev - gp,\n        ebit, ebitda: 0, netIncome: ni,\n        interestExpense: Math.abs(int), incomeTaxExpense: tax, ebt: ni + tax,\n        depreciationAndAmortization: 0, sharesOutstanding: 0, eps: 0,\n      },\n      balance: {\n        totalAssets: ta, currentAssets: ca, cash, accountsReceivable: ar,\n        inventory: inv, netPPE: 0, goodwill: 0,\n        retainedEarnings: re, totalLiabilities: tl, currentLiabilities: cl,\n        accountsPayable: 0, longTermDebt: ltd, totalDebt: ltd,\n        totalEquity: te, sharesOutstanding: 0,\n      },\n      cashFlow: {\n        operatingCashFlow: ocf, capex: Math.abs(capex),\n        investingCashFlow: 0, financingCashFlow: 0,\n      },\n    })\n  }\n\n  return results\n}\n\n/**\n * Flatten EDGAR filing data into the format expected by scoring utilities\n * (moatScore, capitalAllocationScore, earningsQualityScore, qualityScore).\n * Returns records in chronological order (oldest first).\n */\nexport function flattenEdgarData(filings: EdgarFilingData[]): Array<{\n  year: string\n  revenue: number\n  grossProfit: number\n  ebit: number\n  ebt: number\n  netIncome: number\n  incomeTaxExpense: number\n  interestExpense: number\n  totalAssets: number\n  totalEquity: number\n  totalDebt: number\n  cash: number\n  currentAssets: number\n  currentLiabilities: number\n  capex: number\n  depreciation: number\n  operatingCashFlow: number\n  accountsReceivable: number\n}> {\n  return [...filings]\n    .reverse() // EDGAR returns newest-first; we want oldest-first\n    .map(f => ({\n      year:               f.fiscalYear,\n      revenue:            f.income.revenue,\n      grossProfit:        f.income.grossProfit,\n      ebit:               f.income.ebit,\n      ebt:                f.income.ebt,\n      netIncome:          f.income.netIncome,\n      incomeTaxExpense:   f.income.incomeTaxExpense,\n      interestExpense:    f.income.interestExpense,\n      totalAssets:        f.balance.totalAssets,\n      totalEquity:        f.balance.totalEquity,\n      totalDebt:          f.balance.totalDebt || f.balance.longTermDebt,\n      cash:               f.balance.cash,\n      currentAssets:      f.balance.currentAssets,\n      currentLiabilities: f.balance.currentLiabilities,\n      capex:              f.cashFlow.capex,\n      depreciation:       f.income.depreciationAndAmortization,\n      operatingCashFlow:  f.cashFlow.operatingCashFlow,\n      accountsReceivable: f.balance.accountsReceivable,\n    }))\n}\n\n/**\n * Fetch EDGAR data for a ticker and return flat records ready for scoring utilities.\n * Records are returned oldest-first.\n */\nexport async function fetchEdgarFlat(\n  ticker: string,\n  options: EdgarOptions = {},\n): Promise<ReturnType<typeof flattenEdgarData>> {\n  const filings = await fetchEdgar(ticker, options)\n  return flattenEdgarData(filings)\n}\n\nasync function _get(url: string): Promise<unknown> {\n  const resp = await fetch(url, { headers: HEADERS })\n  if (!resp.ok) throw new Error(`EDGAR request failed: ${resp.status} ${url}`)\n  return resp.json()\n}\n"]}

package/dist/index.cjs

@@ -119,10 +119,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 = (g4) => {
+  const computeEV = (g5) => {
     const result = dcf2Stage({
       baseFcf: input.baseFcf,
-      growthRate: g4,
+      growthRate: g5,
       years: input.years,
       terminalGrowthRate: input.terminalGrowthRate,
       wacc: input.wacc
@@ -452,8 +452,8 @@ function annualizeReturn(returnValue, periodsPerYear) {
 }
 function stdDev(values, ddof = 1) {
   if (values.length < 2) return null;
-  const mean4 = values.reduce((a, b) => a + b, 0) / values.length;
-  const variance = values.reduce((sum, v) => sum + Math.pow(v - mean4, 2), 0) / (values.length - ddof);
+  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);
   return Math.sqrt(variance);
 }
 function mean(values) {
@@ -1725,6 +1725,340 @@ function capitalAllocationScore(annualData, options = {}) {
   };
 }
 
+// src/utils/earnings-quality.ts
+function mean4(xs) {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+function std3(xs) {
+  if (xs.length < 2) return 0;
+  const m = mean4(xs);
+  return Math.sqrt(xs.reduce((a, x) => a + (x - m) ** 2, 0) / (xs.length - 1));
+}
+function cv3(xs) {
+  const m = mean4(xs);
+  return Math.abs(m) > 1e-9 ? std3(xs) / Math.abs(m) : 1;
+}
+function olsSlope3(ys) {
+  const n = ys.length;
+  if (n < 2) return 0;
+  const xm = (n - 1) / 2;
+  const ym = mean4(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 clamp2(x, lo, hi) {
+  return Math.max(lo, Math.min(hi, x));
+}
+function g4(d, k) {
+  const v = d[k];
+  return typeof v === "number" && isFinite(v) ? v : 0;
+}
+function scoreAccruals(series) {
+  const ratios = [];
+  for (let i = 0; i < series.length; i++) {
+    const d = series[i];
+    const ni = g4(d, "netIncome");
+    const cfo = g4(d, "operatingCashFlow");
+    if (ni === 0 && cfo === 0) continue;
+    const prevAssets = i > 0 ? g4(series[i - 1], "totalAssets") : g4(d, "totalAssets");
+    const avgAssets = (g4(d, "totalAssets") + prevAssets) / 2;
+    if (avgAssets <= 0) continue;
+    ratios.push((ni - cfo) / avgAssets);
+  }
+  if (!ratios.length) return [0.4, ["Accruals ratio: operating cash flow not available (neutral score)"]];
+  const ma = mean4(ratios);
+  const level = clamp2(1 - (ma + 0.05) / 0.15, 0, 1);
+  const stability = Math.max(0, 1 - cv3(ratios));
+  const score = clamp2(0.7 * level + 0.3 * stability, 0, 1);
+  const quality = ma < 0 ? "cash-backed" : ma < 0.05 ? "modest accruals" : "high accruals";
+  return [score, [
+    `Accruals ratio: mean ${(ma * 100).toFixed(1)}% of assets  (${quality})`,
+    ma < 0.02 ? "Earnings predominantly backed by cash flows" : "Elevated accruals \u2014 verify cash conversion"
+  ]];
+}
+function scoreCashEarnings(series) {
+  const ratios = [];
+  for (const d of series) {
+    const ni = g4(d, "netIncome");
+    const cfo = g4(d, "operatingCashFlow");
+    if (ni > 0) ratios.push(cfo / ni);
+  }
+  if (!ratios.length) return [0.4, ["Cash earnings quality: insufficient CFO/NI data (neutral score)"]];
+  const mr = mean4(ratios);
+  const level = clamp2((mr - 0.5) / 1, 0, 1);
+  const stability = Math.max(0, 1 - cv3(ratios) * 0.8);
+  const score = clamp2(0.65 * level + 0.35 * stability, 0, 1);
+  const above = ratios.filter((r) => r >= 1).length;
+  const quality = mr >= 1.2 ? "excellent" : mr >= 0.9 ? "good" : "weak";
+  return [score, [
+    `CFO/NI conversion: mean ${mr.toFixed(2)}\xD7  (${above}/${ratios.length} years \u2265 1.0)`,
+    `Cash earnings quality: ${quality}`
+  ]];
+}
+function scoreRevenueRecognition(series) {
+  const spreads = [];
+  for (let i = 1; i < series.length; i++) {
+    const prev = series[i - 1];
+    const curr = series[i];
+    if (g4(prev, "revenue") <= 0) continue;
+    const revGrowth = (g4(curr, "revenue") - g4(prev, "revenue")) / g4(prev, "revenue");
+    const arPrev = g4(prev, "accountsReceivable");
+    const arCurr = g4(curr, "accountsReceivable");
+    if (arPrev > 0 && arCurr > 0) {
+      spreads.push(revGrowth - (arCurr - arPrev) / arPrev);
+    }
+  }
+  if (!spreads.length) return [0.45, ["Revenue recognition: accounts receivable data unavailable (neutral score)"]];
+  const ms = mean4(spreads);
+  const level = clamp2((ms + 0.15) / 0.25, 0, 1);
+  const consistency = Math.max(0, 1 - cv3(spreads) * 0.5);
+  const score = clamp2(0.65 * level + 0.35 * consistency, 0, 1);
+  const quality = ms > 0.05 ? "conservative" : ms > -0.05 ? "neutral" : "aggressive";
+  const pos = spreads.filter((s) => s >= 0).length;
+  return [score, [
+    `Revenue recognition: revenue-AR spread ${(ms * 100).toFixed(1)}%/yr  (${quality})`,
+    `Revenue outpaced receivables in ${pos}/${spreads.length} periods`
+  ]];
+}
+function scoreGrossMarginStability(series) {
+  const gms = series.filter((d) => g4(d, "revenue") > 0 && g4(d, "grossProfit") > 0).map((d) => g4(d, "grossProfit") / g4(d, "revenue"));
+  if (gms.length < 2) return [0.45, ["Gross margin stability: insufficient data (neutral score)"]];
+  const mgm = mean4(gms);
+  const cvGm = cv3(gms);
+  const slope = olsSlope3(gms);
+  const stability = clamp2(1 - cvGm * 3, 0, 1);
+  const trendAdj = slope > 5e-3 ? 0.08 : slope < -5e-3 ? -0.08 : 0;
+  const score = clamp2(stability + trendAdj, 0, 1);
+  const trend = slope > 5e-3 ? "improving" : slope < -5e-3 ? "eroding" : "stable";
+  const quality = cvGm < 0.05 ? "high" : cvGm < 0.15 ? "moderate" : "low";
+  return [score, [
+    `Gross margin: mean ${(mgm * 100).toFixed(1)}%  stability ${quality} (CV ${cvGm.toFixed(3)})`,
+    `Gross margin trend: ${trend}`
+  ]];
+}
+function scoreAssetEfficiency(series) {
+  const tos = series.filter((d) => g4(d, "totalAssets") > 0 && g4(d, "revenue") > 0).map((d) => g4(d, "revenue") / g4(d, "totalAssets"));
+  if (tos.length < 2) return [0.45, ["Asset efficiency: insufficient data (neutral score)"]];
+  const slope = olsSlope3(tos);
+  const mto = mean4(tos);
+  const trendScore = clamp2(0.5 + slope * 5, 0, 1);
+  const level = clamp2((mto - 0.2) / 1.5, 0, 1);
+  const score = clamp2(0.5 * trendScore + 0.5 * level, 0, 1);
+  const dir = slope > 0.02 ? "improving" : slope < -0.02 ? "declining" : "stable";
+  return [score, [`Asset turnover: mean ${mto.toFixed(2)}\xD7  trend ${dir}  (slope ${slope.toFixed(3)}/yr)`]];
+}
+function earningsQualityScore(annualData, _options = {}) {
+  if (annualData.length < 2) {
+    throw new Error("earningsQualityScore requires at least 2 years of data.");
+  }
+  const [accScore, accEv] = scoreAccruals(annualData);
+  const [cfeScore, cfeEv] = scoreCashEarnings(annualData);
+  const [revScore, revEv] = scoreRevenueRecognition(annualData);
+  const [gmsScore, gmsEv] = scoreGrossMarginStability(annualData);
+  const [effScore, effEv] = scoreAssetEfficiency(annualData);
+  const raw = 0.3 * accScore + 0.25 * cfeScore + 0.2 * revScore + 0.15 * gmsScore + 0.1 * effScore;
+  const score = Math.round(clamp2(raw, 0, 1) * 100);
+  const rating = score >= 75 ? "high" : score >= 50 ? "medium" : score >= 25 ? "low" : "poor";
+  return {
+    score,
+    rating,
+    components: {
+      accrualsRatio: Math.round(accScore * 1e4) / 1e4,
+      cashEarnings: Math.round(cfeScore * 1e4) / 1e4,
+      revenueRecognition: Math.round(revScore * 1e4) / 1e4,
+      grossMarginStability: Math.round(gmsScore * 1e4) / 1e4,
+      assetEfficiency: Math.round(effScore * 1e4) / 1e4
+    },
+    yearsAnalyzed: annualData.length,
+    evidence: [...accEv, ...cfeEv, ...revEv, ...gmsEv, ...effEv]
+  };
+}
+
+// src/utils/fair-value.ts
+function percentile2(xs, p) {
+  if (!xs.length) return 0;
+  const sorted = [...xs].sort((a, b) => a - b);
+  const idx = p / 100 * (sorted.length - 1);
+  const lo = Math.floor(idx);
+  const hi = Math.min(lo + 1, sorted.length - 1);
+  return (sorted[lo] ?? 0) + ((sorted[hi] ?? 0) - (sorted[lo] ?? 0)) * (idx - lo);
+}
+function trimmedMean(xs) {
+  if (xs.length <= 3) return xs.reduce((a, b) => a + b, 0) / xs.length;
+  const sorted = [...xs].sort((a, b) => a - b).slice(1, -1);
+  return sorted.reduce((a, b) => a + b, 0) / sorted.length;
+}
+function round2(x) {
+  return Math.round(x * 100) / 100;
+}
+function dcfValue(fcf, growthRate, terminalGrowth, wacc, shares, years) {
+  if (wacc <= terminalGrowth || fcf <= 0 || shares <= 0) return null;
+  let pv = 0;
+  let cf = fcf;
+  for (let i = 1; i <= years; i++) {
+    cf *= 1 + growthRate;
+    pv += cf / (1 + wacc) ** i;
+  }
+  const terminal = cf * (1 + terminalGrowth) / (wacc - terminalGrowth);
+  pv += terminal / (1 + wacc) ** years;
+  return pv / shares;
+}
+function grahamValue(eps, bvps) {
+  return eps > 0 && bvps > 0 ? Math.sqrt(22.5 * eps * bvps) : null;
+}
+function fcfYieldValue(fcf, shares, targetYield) {
+  return fcf > 0 && shares > 0 && targetYield > 0 ? fcf / targetYield / shares : null;
+}
+function evEbitdaValue(ebitda, totalDebt, cash, shares, multiple) {
+  if (ebitda <= 0 || shares <= 0) return null;
+  const equityValue = ebitda * multiple - totalDebt + cash;
+  return equityValue > 0 ? equityValue / shares : null;
+}
+function epvValue(ebit, taxRate, wacc, shares, cash, totalDebt) {
+  if (ebit <= 0 || wacc <= 0 || shares <= 0) return null;
+  const equityValue = ebit * (1 - taxRate) / wacc + cash - totalDebt;
+  return equityValue > 0 ? equityValue / shares : null;
+}
+function fairValueRange(options) {
+  const {
+    fcf,
+    shares,
+    growthRate = 0.08,
+    terminalGrowth = 0.03,
+    wacc = 0.09,
+    dcfYears = 10,
+    eps,
+    bvps,
+    targetYield = 0.04,
+    ebitda,
+    totalDebt = 0,
+    cash = 0,
+    evEbitdaMultiple = 12,
+    ebit,
+    taxRate = 0.21,
+    currentPrice
+  } = options;
+  const estimates = {};
+  if (fcf && fcf > 0 && shares && shares > 0) {
+    const v = dcfValue(fcf, growthRate, terminalGrowth, wacc, shares, dcfYears);
+    if (v && v > 0) estimates["DCF (2-stage)"] = v;
+    const fy = fcfYieldValue(fcf, shares, targetYield);
+    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;
+  }
+  if (ebitda && ebitda > 0 && shares && shares > 0) {
+    const v = evEbitdaValue(ebitda, totalDebt, cash, shares, evEbitdaMultiple);
+    if (v && v > 0) estimates[`EV/EBITDA (${evEbitdaMultiple.toFixed(0)}\xD7)`] = v;
+  }
+  if (ebit && ebit > 0 && shares && shares > 0) {
+    const v = epvValue(ebit, taxRate, wacc, shares, cash, totalDebt);
+    if (v && v > 0) estimates["Earnings Power Value"] = v;
+  }
+  if (!Object.keys(estimates).length) {
+    throw new Error(
+      "No valuation methods could be computed. Provide at least one of: (fcf + shares), (eps + bvps), (ebitda + shares), (ebit + shares)."
+    );
+  }
+  const vals = Object.values(estimates);
+  const baseValue = round2(trimmedMean(vals));
+  const bearValue = round2(percentile2(vals, 25));
+  const bullValue = round2(percentile2(vals, 75));
+  const result = {
+    estimates: Object.fromEntries(Object.entries(estimates).map(([k, v]) => [k, round2(v)])),
+    baseValue,
+    bearValue,
+    bullValue,
+    methodsUsed: vals.length
+  };
+  if (currentPrice !== void 0 && currentPrice > 0) {
+    result.currentPrice = currentPrice;
+    result.upsidePct = Math.round((baseValue / currentPrice - 1) * 1e3) / 10;
+    result.marginOfSafety = Math.round((bearValue / currentPrice - 1) * 1e3) / 10;
+  }
+  return result;
+}
+
+// src/utils/quality-score.ts
+function qualityScore(annualData, options = {}) {
+  if (annualData.length < 2) {
+    throw new Error("qualityScore requires at least 2 years of data.");
+  }
+  const eq = earningsQualityScore(annualData);
+  const ms = moatScore(annualData, options);
+  const ca = capitalAllocationScore(annualData, options);
+  const eqNorm = eq.score / 100;
+  const msNorm = ms.score / 100;
+  const caNorm = ca.score / 100;
+  const raw = 0.35 * eqNorm + 0.35 * msNorm + 0.3 * caNorm;
+  const score = Math.round(raw * 100);
+  const grade = score >= 80 ? "exceptional" : score >= 60 ? "strong" : score >= 40 ? "moderate" : score >= 20 ? "weak" : "poor";
+  return {
+    score,
+    grade,
+    components: {
+      earningsQuality: Math.round(eqNorm * 1e4) / 1e4,
+      moat: Math.round(msNorm * 1e4) / 1e4,
+      capitalAllocation: Math.round(caNorm * 1e4) / 1e4
+    },
+    subScores: { earningsQuality: eq, moat: ms, capitalAllocation: ca },
+    yearsAnalyzed: annualData.length,
+    evidence: [
+      `Earnings Quality:   ${eq.score}/100 [${eq.rating.toUpperCase()}]`,
+      `Economic Moat:      ${ms.score}/100 [${ms.width.toUpperCase()}]`,
+      `Capital Allocation: ${ca.score}/100 [${ca.rating.toUpperCase()}]`
+    ]
+  };
+}
+
+// src/utils/portfolio.ts
+function portfolioQuality(holdings, options = {}) {
+  if (!holdings.length) throw new Error("holdings must be a non-empty array.");
+  const totalWeight = holdings.reduce((s, h) => s + h.weight, 0);
+  if (totalWeight <= 0) throw new Error("Sum of holding weights must be positive.");
+  const results = holdings.map((h) => {
+    const normWeight = h.weight / totalWeight;
+    try {
+      const q = qualityScore(h.annualData, options);
+      return { ticker: h.ticker, weight: normWeight, quality: q };
+    } catch (err) {
+      return {
+        ticker: h.ticker,
+        weight: normWeight,
+        quality: null,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  });
+  const successful = results.filter(
+    (r) => r.quality !== null
+  );
+  if (!successful.length) {
+    throw new Error("All holdings failed to compute. Check data and minimum year requirements.");
+  }
+  const effWeight = successful.reduce((s, h) => s + h.weight, 0);
+  const renorm = effWeight > 0 ? 1 / effWeight : 1;
+  const wavg = (fn) => Math.round(successful.reduce((s, h) => s + h.weight * fn(h.quality) * renorm, 0) * 10) / 10;
+  const wq = wavg((q) => q.score);
+  const wm = wavg((q) => q.subScores.moat.score);
+  const weq = wavg((q) => q.subScores.earningsQuality.score);
+  const wca = wavg((q) => q.subScores.capitalAllocation.score);
+  const grade = wq >= 80 ? "exceptional" : wq >= 60 ? "strong" : wq >= 40 ? "moderate" : wq >= 20 ? "weak" : "poor";
+  return {
+    holdings: results,
+    weightedQualityScore: wq,
+    weightedMoatScore: wm,
+    weightedEarningsQuality: weq,
+    weightedCapitalAllocation: wca,
+    effectiveWeight: Math.round(effWeight * 1e4) / 1e4,
+    grade,
+    errors: results.filter((r) => r.error).map((r) => `${r.ticker}: ${r.error}`)
+  };
+}
+
 exports.affo = affo;
 exports.altmanZScore = altmanZScore;
 exports.annualizeReturn = annualizeReturn;
@@ -1768,6 +2102,7 @@ exports.dpo = dpo;
 exports.dso = dso;
 exports.duPont3 = duPont3;
 exports.earningsPowerValue = earningsPowerValue;
+exports.earningsQualityScore = earningsQualityScore;
 exports.ebitdaCoverageRatio = ebitdaCoverageRatio;
 exports.ebitdaGrowth = ebitdaGrowth;
 exports.ebitdaMargin = ebitdaMargin;
@@ -1781,6 +2116,7 @@ exports.evFcf = evFcf;
 exports.evInvestedCapital = evInvestedCapital;
 exports.evRevenue = evRevenue;
 exports.expenseRatio = expenseRatio;
+exports.fairValueRange = fairValueRange;
 exports.fcfConversion = fcfConversion;
 exports.fcfGrowth = fcfGrowth;
 exports.fcfMargin = fcfMargin;
@@ -1840,11 +2176,13 @@ exports.pe = pe;
 exports.peg = peg;
 exports.percentile = percentile;
 exports.piotroskiFScore = piotroskiFScore;
+exports.portfolioQuality = portfolioQuality;
 exports.premiumsToSurplus = premiumsToSurplus;
 exports.pricesToReturns = pricesToReturns;
 exports.profitPerEmployee = profitPerEmployee;
 exports.provisionCoverageRatio = provisionCoverageRatio;
 exports.ps = ps;
+exports.qualityScore = qualityScore;
 exports.quickRatio = quickRatio;
 exports.receivablesTurnover = receivablesTurnover;
 exports.revenueCAGR = revenueCAGR;