fin-ratios 0.7.1 → 1.0.0

package/dist/fetchers/edgar/index.cjs

@@ -4,63 +4,75 @@
 var COMPANY_TICKERS_URL = "https://data.sec.gov/files/company_tickers.json";
 var EDGAR_BASE = "https://data.sec.gov/api/xbrl/companyfacts";
 var HEADERS = {
-  "User-Agent": "fin-ratios/0.1.0 contact@fin-ratios.dev",
+  "User-Agent": "fin-ratios/1.0 contact@fin-ratios.dev",
   "Accept-Encoding": "gzip, deflate"
 };
 async function fetchEdgar(ticker, options = {}) {
-  const { numYears = 3 } = options;
+  const { numYears = 5 } = options;
   const tickerMap = await _get(COMPANY_TICKERS_URL);
-  const entry = Object.values(tickerMap).find((v) => v.ticker.toUpperCase() === ticker.toUpperCase());
+  const entry = Object.values(tickerMap).find(
+    (v) => v.ticker.toUpperCase() === ticker.toUpperCase()
+  );
   if (!entry) throw new Error(`EDGAR: ticker ${ticker} not found`);
   const cik = String(entry.cik_str).padStart(10, "0");
   const facts = await _get(`${EDGAR_BASE}/CIK${cik}.json`);
   const gaap = facts.facts["us-gaap"] ?? {};
   function _annual(concept) {
-    const entries = gaap[concept]?.units?.USD ?? [];
-    return entries.filter((e) => e.form === "10-K").sort((a, b) => b.end.localeCompare(a.end));
+    return (gaap[concept]?.units?.USD ?? []).filter((e) => e.form === "10-K").sort((a, b) => b.end.localeCompare(a.end));
   }
-  function _latestForYear(concept, year) {
-    const annual = _annual(concept);
-    const match = annual.find((e) => e.end.startsWith(year));
-    return match?.val ?? 0;
+  function _annualShares(concept) {
+    return (gaap[concept]?.units?.shares ?? []).filter((e) => e.form === "10-K").sort((a, b) => b.end.localeCompare(a.end));
   }
-  const revenueEntries = _annual("Revenues").concat(_annual("RevenueFromContractWithCustomerExcludingAssessedTax"));
-  const years = [...new Set(revenueEntries.map((e) => e.end.slice(0, 4)))].slice(0, numYears);
-  const results = [];
-  for (const year of years) {
-    const rev = _latestForYear("Revenues", year) || _latestForYear("RevenueFromContractWithCustomerExcludingAssessedTax", year);
-    const ni = _latestForYear("NetIncomeLoss", year);
-    const ebit = _latestForYear("OperatingIncomeLoss", year);
-    const ta = _latestForYear("Assets", year);
-    const ca = _latestForYear("AssetsCurrent", year);
-    const cash = _latestForYear("CashAndCashEquivalentsAtCarryingValue", year);
-    const ar = _latestForYear("AccountsReceivableNetCurrent", year);
-    const inv = _latestForYear("InventoryNet", year);
-    const cl = _latestForYear("LiabilitiesCurrent", year);
-    const tl = _latestForYear("Liabilities", year);
-    const ltd = _latestForYear("LongTermDebt", year);
-    const re = _latestForYear("RetainedEarningsAccumulatedDeficit", year);
-    const te = _latestForYear("StockholdersEquity", year);
-    const ocf = _latestForYear("NetCashProvidedByUsedInOperatingActivities", year);
-    const capex = _latestForYear("PaymentsToAcquirePropertyPlantAndEquipment", year);
-    const gp = _latestForYear("GrossProfit", year);
-    const int = _latestForYear("InterestExpense", year);
-    const tax = _latestForYear("IncomeTaxExpense", year) || _latestForYear("IncomeTaxesPaidNet", year);
-    results.push({
+  function _pick(concept, year) {
+    return _annual(concept).find((e) => e.end.startsWith(year))?.val ?? 0;
+  }
+  function _pickShares(concept, year) {
+    return _annualShares(concept).find((e) => e.end.startsWith(year))?.val ?? 0;
+  }
+  const revEntries = _annual("Revenues").concat(
+    _annual("RevenueFromContractWithCustomerExcludingAssessedTax")
+  );
+  const years = [...new Set(revEntries.map((e) => e.end.slice(0, 4)))].slice(0, numYears);
+  return years.map((year) => {
+    const rev = _pick("Revenues", year) || _pick("RevenueFromContractWithCustomerExcludingAssessedTax", year);
+    const gp = _pick("GrossProfit", year);
+    const ebit = _pick("OperatingIncomeLoss", year);
+    const ni = _pick("NetIncomeLoss", year);
+    const tax = _pick("IncomeTaxExpenseBenefit", year) || _pick("IncomeTaxesPaidNet", year);
+    const int_ = _pick("InterestExpense", year) || _pick("InterestAndDebtExpense", year);
+    const depr = _pick("DepreciationDepletionAndAmortization", year) || _pick("DepreciationAndAmortization", year);
+    const ta = _pick("Assets", year);
+    const ca = _pick("AssetsCurrent", year);
+    const cash = _pick("CashAndCashEquivalentsAtCarryingValue", year) || _pick("CashCashEquivalentsAndShortTermInvestments", year);
+    const ar = _pick("AccountsReceivableNetCurrent", year);
+    const inv = _pick("InventoryNet", year);
+    const cl = _pick("LiabilitiesCurrent", year);
+    const tl = _pick("Liabilities", year);
+    const ltd = _pick("LongTermDebt", year) || _pick("LongTermDebtNoncurrent", year);
+    const std = _pick("ShortTermBorrowings", year) || _pick("DebtCurrent", year);
+    const re = _pick("RetainedEarningsAccumulatedDeficit", year);
+    const te = _pick("StockholdersEquity", year) || _pick("StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest", year);
+    const ocf = _pick("NetCashProvidedByUsedInOperatingActivities", year);
+    const capex = _pick("PaymentsToAcquirePropertyPlantAndEquipment", year);
+    const divs = _pick("PaymentsOfDividends", year) || _pick("PaymentsOfDividendsCommonStock", year);
+    const shs = _pickShares("CommonStockSharesOutstanding", year) || _pickShares("CommonStockSharesIssued", year);
+    const totalDebt = ltd + std;
+    const ebt = ni + tax;
+    return {
       fiscalYear: year,
       income: {
         revenue: rev,
         grossProfit: gp,
         cogs: rev - gp,
         ebit,
-        ebitda: 0,
+        ebitda: ebit + depr,
         netIncome: ni,
-        interestExpense: Math.abs(int),
+        interestExpense: Math.abs(int_),
         incomeTaxExpense: tax,
-        ebt: ni + tax,
-        depreciationAndAmortization: 0,
-        sharesOutstanding: 0,
-        eps: 0
+        ebt,
+        depreciationAndAmortization: depr,
+        sharesOutstanding: shs,
+        eps: shs > 0 ? ni / shs : 0
       },
       balance: {
         totalAssets: ta,
@@ -73,56 +85,68 @@ async function fetchEdgar(ticker, options = {}) {
         retainedEarnings: re,
         totalLiabilities: tl,
         currentLiabilities: cl,
-        accountsPayable: 0,
+        accountsPayable: _pick("AccountsPayableCurrent", year),
         longTermDebt: ltd,
-        totalDebt: ltd,
+        totalDebt,
         totalEquity: te,
-        sharesOutstanding: 0
+        sharesOutstanding: shs
       },
       cashFlow: {
         operatingCashFlow: ocf,
         capex: Math.abs(capex),
         investingCashFlow: 0,
-        financingCashFlow: 0
+        financingCashFlow: 0,
+        dividendsPaid: Math.abs(divs)
       }
-    });
-  }
-  return results;
+    };
+  });
+}
+function normalizeForScoring(filings) {
+  return [...filings].reverse().map((f) => {
+    const rec = {
+      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,
+      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
+    };
+    rec.dividendsPaid = f.cashFlow.dividendsPaid;
+    if (f.balance.sharesOutstanding) rec.sharesOutstanding = f.balance.sharesOutstanding;
+    return rec;
+  });
 }
 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
-  }));
+  return normalizeForScoring(filings);
+}
+async function fetchEdgarNormalized(ticker, options = {}) {
+  return normalizeForScoring(await fetchEdgar(ticker, options));
 }
 async function fetchEdgarFlat(ticker, options = {}) {
-  const filings = await fetchEdgar(ticker, options);
-  return flattenEdgarData(filings);
+  return fetchEdgarNormalized(ticker, options);
 }
 async function _get(url) {
   const resp = await fetch(url, { headers: HEADERS });
-  if (!resp.ok) throw new Error(`EDGAR request failed: ${resp.status} ${url}`);
+  if (!resp.ok) throw new Error(`EDGAR fetch failed: ${resp.status} ${url}`);
   return resp.json();
 }
 
 exports.fetchEdgar = fetchEdgar;
 exports.fetchEdgarFlat = fetchEdgarFlat;
+exports.fetchEdgarNormalized = fetchEdgarNormalized;
 exports.flattenEdgarData = flattenEdgarData;
+exports.normalizeForScoring = normalizeForScoring;
 //# 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":"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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"]}
+{"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, fetchEdgarNormalized } from 'fin-ratios/fetchers/edgar'\n *\n * // Structured filings (newest-first)\n * const filings = await fetchEdgar('AAPL', { numYears: 5 })\n *\n * // Flat records ready for scoring utilities (oldest-first)\n * const annualData = await fetchEdgarNormalized('AAPL', { numYears: 10 })\n * const quality = qualityScore(annualData)\n */\n\nimport type { IncomeStatement, BalanceSheet, CashFlowStatement } from '../../types/index.js'\nimport type { AnnualQualityData } from '../../utils/quality-score.js'\nimport type { AnnualCapitalData } from '../../utils/capital-allocation.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/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 & { dividendsPaid: number }\n}\n\n/**\n * Normalised annual record that satisfies all scoring utility input types:\n * moatScore, capitalAllocationScore, earningsQualityScore, qualityScore.\n */\nexport type EdgarAnnualRecord = AnnualQualityData &\n  AnnualCapitalData & {\n    year: string\n    sharesOutstanding?: number\n    currentAssets?: number\n    currentLiabilities?: number\n  }\n\n/**\n * Fetch multi-year annual filings from SEC EDGAR for a US stock ticker.\n * Returns newest-first.\n */\nexport async function fetchEdgar(\n  ticker: string,\n  options: EdgarOptions = {}\n): Promise<EdgarFilingData[]> {\n  const { numYears = 5 } = options\n\n  // Resolve ticker → CIK\n  const tickerMap = (await _get(COMPANY_TICKERS_URL)) as Record<\n    string,\n    { cik_str: number; ticker: string; title: string }\n  >\n  const entry = Object.values(tickerMap).find(\n    v => v.ticker.toUpperCase() === ticker.toUpperCase()\n  )\n  if (!entry) throw new Error(`EDGAR: ticker ${ticker} not found`)\n\n  const cik = String(entry.cik_str).padStart(10, '0')\n  const facts = (await _get(`${EDGAR_BASE}/CIK${cik}.json`)) as {\n    facts: {\n      'us-gaap'?: Record<\n        string,\n        {\n          units: {\n            USD?: { val: number; end: string; form: string; fp: string }[]\n            shares?: { val: number; end: string; form: string; fp: string }[]\n          }\n        }\n      >\n    }\n  }\n\n  const gaap = facts.facts['us-gaap'] ?? {}\n\n  function _annual(concept: string): { end: string; val: number }[] {\n    return (gaap[concept]?.units?.USD ?? [])\n      .filter(e => e.form === '10-K')\n      .sort((a, b) => b.end.localeCompare(a.end))\n  }\n\n  function _annualShares(concept: string): { end: string; val: number }[] {\n    return (gaap[concept]?.units?.shares ?? [])\n      .filter(e => e.form === '10-K')\n      .sort((a, b) => b.end.localeCompare(a.end))\n  }\n\n  function _pick(concept: string, year: string): number {\n    return _annual(concept).find(e => e.end.startsWith(year))?.val ?? 0\n  }\n\n  function _pickShares(concept: string, year: string): number {\n    return _annualShares(concept).find(e => e.end.startsWith(year))?.val ?? 0\n  }\n\n  // Determine available fiscal years from revenue\n  const revEntries = _annual('Revenues').concat(\n    _annual('RevenueFromContractWithCustomerExcludingAssessedTax')\n  )\n  const years = [...new Set(revEntries.map(e => e.end.slice(0, 4)))].slice(0, numYears)\n\n  return years.map(year => {\n    const rev   = _pick('Revenues', year) || _pick('RevenueFromContractWithCustomerExcludingAssessedTax', year)\n    const gp    = _pick('GrossProfit', year)\n    const ebit  = _pick('OperatingIncomeLoss', year)\n    const ni    = _pick('NetIncomeLoss', year)\n    const tax   = _pick('IncomeTaxExpenseBenefit', year) || _pick('IncomeTaxesPaidNet', year)\n    const int_  = _pick('InterestExpense', year) || _pick('InterestAndDebtExpense', year)\n    const depr  = _pick('DepreciationDepletionAndAmortization', year) || _pick('DepreciationAndAmortization', year)\n    const ta    = _pick('Assets', year)\n    const ca    = _pick('AssetsCurrent', year)\n    const cash  = _pick('CashAndCashEquivalentsAtCarryingValue', year) || _pick('CashCashEquivalentsAndShortTermInvestments', year)\n    const ar    = _pick('AccountsReceivableNetCurrent', year)\n    const inv   = _pick('InventoryNet', year)\n    const cl    = _pick('LiabilitiesCurrent', year)\n    const tl    = _pick('Liabilities', year)\n    const ltd   = _pick('LongTermDebt', year) || _pick('LongTermDebtNoncurrent', year)\n    const std   = _pick('ShortTermBorrowings', year) || _pick('DebtCurrent', year)\n    const re    = _pick('RetainedEarningsAccumulatedDeficit', year)\n    const te    = _pick('StockholdersEquity', year) || _pick('StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest', year)\n    const ocf   = _pick('NetCashProvidedByUsedInOperatingActivities', year)\n    const capex = _pick('PaymentsToAcquirePropertyPlantAndEquipment', year)\n    const divs  = _pick('PaymentsOfDividends', year) || _pick('PaymentsOfDividendsCommonStock', year)\n    const shs   = _pickShares('CommonStockSharesOutstanding', year) || _pickShares('CommonStockSharesIssued', year)\n\n    const totalDebt = ltd + std\n    const ebt = ni + tax\n\n    return {\n      fiscalYear: year,\n      income: {\n        revenue: rev, grossProfit: gp, cogs: rev - gp,\n        ebit, ebitda: ebit + depr, netIncome: ni,\n        interestExpense: Math.abs(int_), incomeTaxExpense: tax, ebt,\n        depreciationAndAmortization: depr,\n        sharesOutstanding: shs, eps: shs > 0 ? ni / shs : 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: _pick('AccountsPayableCurrent', year),\n        longTermDebt: ltd, totalDebt,\n        totalEquity: te, sharesOutstanding: shs,\n      },\n      cashFlow: {\n        operatingCashFlow: ocf, capex: Math.abs(capex),\n        investingCashFlow: 0, financingCashFlow: 0,\n        dividendsPaid: Math.abs(divs),\n      },\n    }\n  })\n}\n\n/**\n * Flatten EDGAR filings into a list of normalised annual records, oldest-first.\n * The returned type satisfies all scoring utility inputs:\n * moatScore, capitalAllocationScore, earningsQualityScore, qualityScore.\n */\nexport function normalizeForScoring(filings: EdgarFilingData[]): EdgarAnnualRecord[] {\n  return [...filings].reverse().map(f => {\n    const rec: EdgarAnnualRecord = {\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,\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    rec.dividendsPaid = f.cashFlow.dividendsPaid\n    if (f.balance.sharesOutstanding)  rec.sharesOutstanding = f.balance.sharesOutstanding\n    return rec\n  })\n}\n\n/**\n * @deprecated Use `normalizeForScoring` instead.\n * Kept for backwards compatibility.\n */\nexport function flattenEdgarData(filings: EdgarFilingData[]): EdgarAnnualRecord[] {\n  return normalizeForScoring(filings)\n}\n\n/**\n * Fetch EDGAR data and return normalised annual records (oldest-first),\n * ready to pass directly to qualityScore(), moatScore(), etc.\n *\n * @example\n * const annualData = await fetchEdgarNormalized('AAPL', { numYears: 10 })\n * const qs = qualityScore(annualData)\n */\nexport async function fetchEdgarNormalized(\n  ticker: string,\n  options: EdgarOptions = {},\n): Promise<EdgarAnnualRecord[]> {\n  return normalizeForScoring(await fetchEdgar(ticker, options))\n}\n\n/**\n * @deprecated Use `fetchEdgarNormalized` instead.\n */\nexport async function fetchEdgarFlat(\n  ticker: string,\n  options: EdgarOptions = {},\n): Promise<EdgarAnnualRecord[]> {\n  return fetchEdgarNormalized(ticker, options)\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 fetch failed: ${resp.status} ${url}`)\n  return resp.json()\n}\n"]}

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

@@ -1,4 +1,5 @@
 import { I as IncomeStatement, B as BalanceSheet, C as CashFlowStatement } from '../../financials-DUHxWDPS.cjs';
+import { A as AnnualQualityData, a as AnnualCapitalData } from '../../quality-score-DC4evvdz.cjs';
 
 /**
  * SEC EDGAR fetcher for fin-ratios (TypeScript).
@@ -9,11 +10,14 @@ import { I as IncomeStatement, B as BalanceSheet, C as CashFlowStatement } from
  * Rate limit: ~10 requests/second (SEC guidelines). Add delays for bulk use.
  *
  * @example
- * import { fetchEdgar } from 'fin-ratios/fetchers/edgar'
- * const filings = await fetchEdgar('AAPL', { numYears: 3 })
- * for (const f of filings) {
- *   console.log(`${f.fiscalYear}: Revenue $${(f.income.revenue/1e9).toFixed(1)}B`)
- * }
+ * import { fetchEdgar, fetchEdgarNormalized } from 'fin-ratios/fetchers/edgar'
+ *
+ * // Structured filings (newest-first)
+ * const filings = await fetchEdgar('AAPL', { numYears: 5 })
+ *
+ * // Flat records ready for scoring utilities (oldest-first)
+ * const annualData = await fetchEdgarNormalized('AAPL', { numYears: 10 })
+ * const quality = qualityScore(annualData)
  */
 
 interface EdgarOptions {
@@ -23,41 +27,48 @@ interface EdgarFilingData {
     fiscalYear: string;
     income: IncomeStatement;
     balance: BalanceSheet;
-    cashFlow: CashFlowStatement;
+    cashFlow: CashFlowStatement & {
+        dividendsPaid: number;
+    };
 }
+/**
+ * Normalised annual record that satisfies all scoring utility input types:
+ * moatScore, capitalAllocationScore, earningsQualityScore, qualityScore.
+ */
+type EdgarAnnualRecord = AnnualQualityData & AnnualCapitalData & {
+    year: string;
+    sharesOutstanding?: number;
+    currentAssets?: number;
+    currentLiabilities?: number;
+};
 /**
  * Fetch multi-year annual filings from SEC EDGAR for a US stock ticker.
+ * Returns newest-first.
  */
 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).
+ * Flatten EDGAR filings into a list of normalised annual records, oldest-first.
+ * The returned type satisfies all scoring utility inputs:
+ * moatScore, capitalAllocationScore, earningsQualityScore, qualityScore.
  */
-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;
-}>;
+declare function normalizeForScoring(filings: EdgarFilingData[]): EdgarAnnualRecord[];
+/**
+ * @deprecated Use `normalizeForScoring` instead.
+ * Kept for backwards compatibility.
+ */
+declare function flattenEdgarData(filings: EdgarFilingData[]): EdgarAnnualRecord[];
+/**
+ * Fetch EDGAR data and return normalised annual records (oldest-first),
+ * ready to pass directly to qualityScore(), moatScore(), etc.
+ *
+ * @example
+ * const annualData = await fetchEdgarNormalized('AAPL', { numYears: 10 })
+ * const qs = qualityScore(annualData)
+ */
+declare function fetchEdgarNormalized(ticker: string, options?: EdgarOptions): Promise<EdgarAnnualRecord[]>;
 /**
- * Fetch EDGAR data for a ticker and return flat records ready for scoring utilities.
- * Records are returned oldest-first.
+ * @deprecated Use `fetchEdgarNormalized` instead.
  */
-declare function fetchEdgarFlat(ticker: string, options?: EdgarOptions): Promise<ReturnType<typeof flattenEdgarData>>;
+declare function fetchEdgarFlat(ticker: string, options?: EdgarOptions): Promise<EdgarAnnualRecord[]>;
 
-export { type EdgarFilingData, type EdgarOptions, fetchEdgar, fetchEdgarFlat, flattenEdgarData };
+export { type EdgarAnnualRecord, type EdgarFilingData, type EdgarOptions, fetchEdgar, fetchEdgarFlat, fetchEdgarNormalized, flattenEdgarData, normalizeForScoring };

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

@@ -1,4 +1,5 @@
 import { I as IncomeStatement, B as BalanceSheet, C as CashFlowStatement } from '../../financials-DUHxWDPS.js';
+import { A as AnnualQualityData, a as AnnualCapitalData } from '../../quality-score-DC4evvdz.js';
 
 /**
  * SEC EDGAR fetcher for fin-ratios (TypeScript).
@@ -9,11 +10,14 @@ import { I as IncomeStatement, B as BalanceSheet, C as CashFlowStatement } from
  * Rate limit: ~10 requests/second (SEC guidelines). Add delays for bulk use.
  *
  * @example
- * import { fetchEdgar } from 'fin-ratios/fetchers/edgar'
- * const filings = await fetchEdgar('AAPL', { numYears: 3 })
- * for (const f of filings) {
- *   console.log(`${f.fiscalYear}: Revenue $${(f.income.revenue/1e9).toFixed(1)}B`)
- * }
+ * import { fetchEdgar, fetchEdgarNormalized } from 'fin-ratios/fetchers/edgar'
+ *
+ * // Structured filings (newest-first)
+ * const filings = await fetchEdgar('AAPL', { numYears: 5 })
+ *
+ * // Flat records ready for scoring utilities (oldest-first)
+ * const annualData = await fetchEdgarNormalized('AAPL', { numYears: 10 })
+ * const quality = qualityScore(annualData)
  */
 
 interface EdgarOptions {
@@ -23,41 +27,48 @@ interface EdgarFilingData {
     fiscalYear: string;
     income: IncomeStatement;
     balance: BalanceSheet;
-    cashFlow: CashFlowStatement;
+    cashFlow: CashFlowStatement & {
+        dividendsPaid: number;
+    };
 }
+/**
+ * Normalised annual record that satisfies all scoring utility input types:
+ * moatScore, capitalAllocationScore, earningsQualityScore, qualityScore.
+ */
+type EdgarAnnualRecord = AnnualQualityData & AnnualCapitalData & {
+    year: string;
+    sharesOutstanding?: number;
+    currentAssets?: number;
+    currentLiabilities?: number;
+};
 /**
  * Fetch multi-year annual filings from SEC EDGAR for a US stock ticker.
+ * Returns newest-first.
  */
 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).
+ * Flatten EDGAR filings into a list of normalised annual records, oldest-first.
+ * The returned type satisfies all scoring utility inputs:
+ * moatScore, capitalAllocationScore, earningsQualityScore, qualityScore.
  */
-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;
-}>;
+declare function normalizeForScoring(filings: EdgarFilingData[]): EdgarAnnualRecord[];
+/**
+ * @deprecated Use `normalizeForScoring` instead.
+ * Kept for backwards compatibility.
+ */
+declare function flattenEdgarData(filings: EdgarFilingData[]): EdgarAnnualRecord[];
+/**
+ * Fetch EDGAR data and return normalised annual records (oldest-first),
+ * ready to pass directly to qualityScore(), moatScore(), etc.
+ *
+ * @example
+ * const annualData = await fetchEdgarNormalized('AAPL', { numYears: 10 })
+ * const qs = qualityScore(annualData)
+ */
+declare function fetchEdgarNormalized(ticker: string, options?: EdgarOptions): Promise<EdgarAnnualRecord[]>;
 /**
- * Fetch EDGAR data for a ticker and return flat records ready for scoring utilities.
- * Records are returned oldest-first.
+ * @deprecated Use `fetchEdgarNormalized` instead.
  */
-declare function fetchEdgarFlat(ticker: string, options?: EdgarOptions): Promise<ReturnType<typeof flattenEdgarData>>;
+declare function fetchEdgarFlat(ticker: string, options?: EdgarOptions): Promise<EdgarAnnualRecord[]>;
 
-export { type EdgarFilingData, type EdgarOptions, fetchEdgar, fetchEdgarFlat, flattenEdgarData };
+export { type EdgarAnnualRecord, type EdgarFilingData, type EdgarOptions, fetchEdgar, fetchEdgarFlat, fetchEdgarNormalized, flattenEdgarData, normalizeForScoring };