fin-ratios 0.7.3 → 1.0.0

package/dist/fetchers/polygon/index.cjs

@@ -0,0 +1,176 @@
+'use strict';
+
+// src/fetchers/polygon/index.ts
+var POLYGON_BASE = "https://api.polygon.io/vX/reference/financials";
+var _moduleKey;
+function setPolygonApiKey(key) {
+  _moduleKey = key;
+}
+async function fetchPolygon(ticker, options = {}) {
+  const { numYears = 5, timeframe = "annual" } = options;
+  const apiKey = options.apiKey ?? _moduleKey ?? (typeof process !== "undefined" ? process.env["POLYGON_API_KEY"] : void 0);
+  if (!apiKey) {
+    throw new Error(
+      "Polygon.io API key is required. Provide it via options.apiKey, setPolygonApiKey(), or the POLYGON_API_KEY environment variable."
+    );
+  }
+  const startDate = _startDate(Math.max(numYears, 2));
+  const params = new URLSearchParams({
+    ticker: ticker.toUpperCase(),
+    timeframe,
+    limit: String(Math.min(numYears, 100)),
+    sort: "period_of_report_date",
+    order: "asc",
+    "filing_date.gte": startDate,
+    apiKey
+  });
+  const url = `${POLYGON_BASE}?${params.toString()}`;
+  let payload;
+  try {
+    const resp = await fetch(url);
+    if (resp.status === 401) {
+      throw new Error(
+        "Polygon API returned 401 Unauthorized \u2014 check your API key."
+      );
+    }
+    if (resp.status === 429) {
+      throw new Error(
+        "Polygon API rate limit exceeded (free tier: 5 req/min). Wait a moment and retry."
+      );
+    }
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(
+        `Polygon API request failed for ${ticker}: HTTP ${resp.status} \u2014 ${body.slice(0, 200)}`
+      );
+    }
+    payload = await resp.json();
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("Polygon API")) throw err;
+    throw new Error(
+      `Polygon API request failed for ${ticker}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const results = payload.results ?? [];
+  return results.map((item) => _mapRecord(item));
+}
+function _mapRecord(item) {
+  const inc = item.financials?.income_statement ?? {};
+  const bal = item.financials?.balance_sheet ?? {};
+  const cf = item.financials?.cash_flow_statement ?? {};
+  const revenue = _v(inc, "revenues", "net_revenues", "total_revenues");
+  const grossProfit = _v(inc, "gross_profit");
+  const ebit = _v(
+    inc,
+    "operating_income",
+    "income_loss_from_continuing_operations_before_tax"
+  );
+  const netIncome = _v(inc, "net_income_loss", "net_income_loss_attributable_to_parent");
+  const taxExpense = _v(inc, "income_tax_expense_benefit");
+  const interestExp = Math.abs(_v(inc, "interest_expense_operating", "interest_expense"));
+  const ebtDirect = _v(
+    inc,
+    "income_loss_from_continuing_operations_before_tax",
+    "income_before_income_taxes"
+  );
+  const ebt = ebtDirect !== 0 ? ebtDirect : netIncome + taxExpense;
+  const totalAssets = _v(bal, "assets");
+  const currentAssets = _v(bal, "current_assets");
+  const cash = _v(
+    bal,
+    "cash_and_cash_equivalents_including_short_term_investments",
+    "cash_and_cash_equivalents",
+    "cash"
+  );
+  const currentLiab = _v(bal, "current_liabilities");
+  const totalEquity = _v(
+    bal,
+    "equity",
+    "stockholders_equity",
+    "equity_attributable_to_parent"
+  );
+  const longTermDebt = _v(bal, "long_term_debt");
+  const ar = _v(
+    bal,
+    "accounts_receivable",
+    "accounts_receivable_net_current",
+    "trade_and_other_receivables_current"
+  );
+  const ocf = _v(
+    cf,
+    "net_cash_flow_from_operating_activities",
+    "net_cash_provided_by_used_in_operating_activities"
+  );
+  const investingCf = _v(
+    cf,
+    "net_cash_flow_from_investing_activities",
+    "net_cash_provided_by_used_in_investing_activities"
+  );
+  const capexDirect = _v(
+    cf,
+    "payments_to_acquire_property_plant_and_equipment",
+    "capital_expenditures"
+  );
+  const capex = capexDirect !== 0 ? Math.abs(capexDirect) : Math.abs(investingCf);
+  const dividendsPaid = Math.abs(
+    _v(cf, "payments_of_dividends", "payments_of_dividends_common_stock", "dividends_paid")
+  );
+  let depreciation = _v(
+    inc,
+    "depreciation_and_amortization",
+    "depreciation_depletion_and_amortization"
+  );
+  if (depreciation === 0) {
+    depreciation = _v(
+      cf,
+      "depreciation_depletion_and_amortization",
+      "depreciation_and_amortization"
+    );
+  }
+  const sharesBS = _v(bal, "common_stock_shares_outstanding");
+  const sharesInc = _v(inc, "basic_average_shares", "diluted_average_shares");
+  const sharesOutstanding = sharesBS !== 0 ? sharesBS : sharesInc !== 0 ? sharesInc : void 0;
+  const year = String(item.fiscal_year ?? item.period_of_report_date?.slice(0, 4) ?? "");
+  return {
+    year,
+    revenue,
+    grossProfit,
+    ebit,
+    netIncome,
+    totalAssets,
+    totalEquity,
+    totalDebt: longTermDebt,
+    cash,
+    capex,
+    depreciation,
+    operatingCashFlow: ocf,
+    incomeTaxExpense: taxExpense,
+    ebt,
+    interestExpense: interestExp,
+    currentAssets,
+    currentLiabilities: currentLiab,
+    accountsReceivable: ar,
+    dividendsPaid,
+    ...sharesOutstanding !== void 0 ? { sharesOutstanding } : {}
+  };
+}
+function _v(section, ...keys) {
+  for (const k of keys) {
+    const node = section[k];
+    if (node && node.value != null) {
+      const n = Number(node.value);
+      if (!isNaN(n)) return n;
+    }
+  }
+  return 0;
+}
+function _startDate(years) {
+  const d = /* @__PURE__ */ new Date();
+  d.setFullYear(d.getFullYear() - years);
+  return d.toISOString().slice(0, 10);
+}
+
+exports.fetchPolygon = fetchPolygon;
+exports.setPolygonApiKey = setPolygonApiKey;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/fetchers/polygon/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Polygon.io fetcher for fin-ratios (TypeScript).\n *\n * Fetches fundamental financial data from the Polygon.io REST API.\n * API key required — get one at https://polygon.io.\n * US companies only.  Free tier: 5 req/min, ~2 years of history.\n *\n * @example\n * import { fetchPolygon, setPolygonApiKey } from 'fin-ratios/fetchers/polygon'\n * setPolygonApiKey('your-api-key')\n * const data = await fetchPolygon('AAPL', { numYears: 5 })\n * // data is oldest-first and compatible with all scoring utilities\n */\n\nconst POLYGON_BASE = 'https://api.polygon.io/vX/reference/financials'\n\n// ── Module-level key storage ───────────────────────────────────────────────────\n\nlet _moduleKey: string | undefined\n\n/**\n * Store a Polygon.io API key module-wide.\n * Subsequent calls to {@link fetchPolygon} will use this key unless overridden\n * via the {@link PolygonOptions.apiKey} option.\n */\nexport function setPolygonApiKey(key: string): void {\n  _moduleKey = key\n}\n\n// ── Types ──────────────────────────────────────────────────────────────────────\n\nexport interface PolygonOptions {\n  /** Number of annual periods to retrieve (default: 5). */\n  numYears?: number\n  /**\n   * Polygon.io API key.  Falls back to the module-level key set via\n   * {@link setPolygonApiKey} and then to the `POLYGON_API_KEY` environment\n   * variable (Node.js only).\n   */\n  apiKey?: string\n  /** ``'annual'`` (default) or ``'quarterly'``. */\n  timeframe?: 'annual' | 'quarterly'\n}\n\n/**\n * Normalised annual financial record returned by {@link fetchPolygon}.\n * Field names are compatible with the `EdgarAnnualRecord` type used by the\n * EDGAR fetcher, so the data can be passed directly to all scoring utilities:\n * `moatScore`, `capitalAllocationScore`, `earningsQualityScore`,\n * `qualityScore`, `investmentScore`, etc.\n */\nexport interface PolygonAnnualRecord {\n  /** Four-digit fiscal year string, e.g. ``'2023'``. */\n  year: string\n  revenue: number\n  grossProfit: number\n  /** Operating income (EBIT). */\n  ebit: number\n  netIncome: number\n  totalAssets: number\n  totalEquity: number\n  /** Long-term debt (used as total debt proxy). */\n  totalDebt: number\n  cash: number\n  /** Capital expenditures (absolute value). */\n  capex: number\n  depreciation: number\n  operatingCashFlow: number\n  incomeTaxExpense: number\n  ebt: number\n  interestExpense: number\n  currentAssets: number\n  currentLiabilities: number\n  accountsReceivable: number\n  /** Dividends paid (absolute value).  Zero for non-payers. */\n  dividendsPaid?: number\n  /** Shares outstanding (or weighted-average basic shares). */\n  sharesOutstanding?: number\n}\n\n// ── Internal Polygon response types ───────────────────────────────────────────\n\ninterface _PolygonValue {\n  value?: number | null\n  unit?: string\n  label?: string\n}\n\ninterface _PolygonFinancials {\n  income_statement?: Record<string, _PolygonValue>\n  balance_sheet?: Record<string, _PolygonValue>\n  cash_flow_statement?: Record<string, _PolygonValue>\n}\n\ninterface _PolygonResult {\n  fiscal_year?: string | number\n  period_of_report_date?: string\n  financials?: _PolygonFinancials\n}\n\ninterface _PolygonResponse {\n  results?: _PolygonResult[]\n  status?: string\n  request_id?: string\n  next_url?: string\n}\n\n// ── Public API ─────────────────────────────────────────────────────────────────\n\n/**\n * Fetch annual financial data from Polygon.io.\n *\n * @param ticker - Stock ticker symbol (e.g. ``'AAPL'``).\n * @param options - Options including API key, number of years, and timeframe.\n * @returns Oldest-first list of annual records compatible with all scoring\n *   utilities (moatScore, capitalAllocationScore, qualityScore, etc.).\n *\n * @throws {Error} If no API key is available.\n * @throws {Error} If the Polygon.io API request fails.\n *\n * @example\n * import { fetchPolygon } from 'fin-ratios/fetchers/polygon'\n * const data = await fetchPolygon('AAPL', { numYears: 5, apiKey: 'your-key' })\n */\nexport async function fetchPolygon(\n  ticker: string,\n  options: PolygonOptions = {}\n): Promise<PolygonAnnualRecord[]> {\n  const { numYears = 5, timeframe = 'annual' } = options\n\n  // Resolve API key: option > module-level > env var\n  const apiKey =\n    options.apiKey ??\n    _moduleKey ??\n    (typeof process !== 'undefined' ? process.env['POLYGON_API_KEY'] : undefined)\n\n  if (!apiKey) {\n    throw new Error(\n      'Polygon.io API key is required. Provide it via options.apiKey, ' +\n        'setPolygonApiKey(), or the POLYGON_API_KEY environment variable.'\n    )\n  }\n\n  // Build start date: go back numYears years from today\n  const startDate = _startDate(Math.max(numYears, 2))\n\n  const params = new URLSearchParams({\n    ticker:                  ticker.toUpperCase(),\n    timeframe,\n    limit:                   String(Math.min(numYears, 100)),\n    sort:                    'period_of_report_date',\n    order:                   'asc',\n    'filing_date.gte':       startDate,\n    apiKey,\n  })\n\n  const url = `${POLYGON_BASE}?${params.toString()}`\n\n  let payload: _PolygonResponse\n  try {\n    const resp = await fetch(url)\n    if (resp.status === 401) {\n      throw new Error(\n        'Polygon API returned 401 Unauthorized — check your API key.'\n      )\n    }\n    if (resp.status === 429) {\n      throw new Error(\n        'Polygon API rate limit exceeded (free tier: 5 req/min). ' +\n          'Wait a moment and retry.'\n      )\n    }\n    if (!resp.ok) {\n      const body = await resp.text().catch(() => '')\n      throw new Error(\n        `Polygon API request failed for ${ticker}: HTTP ${resp.status} — ${body.slice(0, 200)}`\n      )\n    }\n    payload = (await resp.json()) as _PolygonResponse\n  } catch (err) {\n    // Re-throw errors we constructed above; wrap unexpected fetch failures\n    if (err instanceof Error && err.message.startsWith('Polygon API')) throw err\n    throw new Error(\n      `Polygon API request failed for ${ticker}: ${err instanceof Error ? err.message : String(err)}`\n    )\n  }\n\n  const results = payload.results ?? []\n  return results.map(item => _mapRecord(item))\n}\n\n// ── Mapping helpers ────────────────────────────────────────────────────────────\n\nfunction _mapRecord(item: _PolygonResult): PolygonAnnualRecord {\n  const inc = item.financials?.income_statement    ?? {}\n  const bal = item.financials?.balance_sheet       ?? {}\n  const cf  = item.financials?.cash_flow_statement ?? {}\n\n  const revenue      = _v(inc, 'revenues', 'net_revenues', 'total_revenues')\n  const grossProfit  = _v(inc, 'gross_profit')\n  const ebit         = _v(inc, 'operating_income',\n                           'income_loss_from_continuing_operations_before_tax')\n  const netIncome    = _v(inc, 'net_income_loss', 'net_income_loss_attributable_to_parent')\n  const taxExpense   = _v(inc, 'income_tax_expense_benefit')\n  const interestExp  = Math.abs(_v(inc, 'interest_expense_operating', 'interest_expense'))\n\n  // EBT: prefer direct field, fall back to net income + taxes\n  const ebtDirect    = _v(inc, 'income_loss_from_continuing_operations_before_tax',\n                           'income_before_income_taxes')\n  const ebt          = ebtDirect !== 0 ? ebtDirect : netIncome + taxExpense\n\n  const totalAssets  = _v(bal, 'assets')\n  const currentAssets = _v(bal, 'current_assets')\n  const cash         = _v(bal,\n                          'cash_and_cash_equivalents_including_short_term_investments',\n                          'cash_and_cash_equivalents', 'cash')\n  const currentLiab  = _v(bal, 'current_liabilities')\n  const totalEquity  = _v(bal, 'equity', 'stockholders_equity',\n                           'equity_attributable_to_parent')\n  const longTermDebt = _v(bal, 'long_term_debt')\n  const ar           = _v(bal, 'accounts_receivable',\n                           'accounts_receivable_net_current',\n                           'trade_and_other_receivables_current')\n\n  const ocf          = _v(cf, 'net_cash_flow_from_operating_activities',\n                           'net_cash_provided_by_used_in_operating_activities')\n  const investingCf  = _v(cf, 'net_cash_flow_from_investing_activities',\n                           'net_cash_provided_by_used_in_investing_activities')\n  const capexDirect  = _v(cf,\n                           'payments_to_acquire_property_plant_and_equipment',\n                           'capital_expenditures')\n  const capex        = capexDirect !== 0 ? Math.abs(capexDirect) : Math.abs(investingCf)\n\n  const dividendsPaid = Math.abs(\n    _v(cf, 'payments_of_dividends', 'payments_of_dividends_common_stock', 'dividends_paid')\n  )\n\n  let depreciation = _v(inc, 'depreciation_and_amortization',\n                         'depreciation_depletion_and_amortization')\n  if (depreciation === 0) {\n    depreciation = _v(cf, 'depreciation_depletion_and_amortization',\n                      'depreciation_and_amortization')\n  }\n\n  // Shares: prefer balance-sheet figure; fall back to income-statement weighted avg\n  const sharesBS    = _v(bal, 'common_stock_shares_outstanding')\n  const sharesInc   = _v(inc, 'basic_average_shares', 'diluted_average_shares')\n  const sharesOutstanding = sharesBS !== 0 ? sharesBS : sharesInc !== 0 ? sharesInc : undefined\n\n  const year = String(item.fiscal_year ?? item.period_of_report_date?.slice(0, 4) ?? '')\n\n  return {\n    year,\n    revenue,\n    grossProfit,\n    ebit,\n    netIncome,\n    totalAssets,\n    totalEquity,\n    totalDebt:          longTermDebt,\n    cash,\n    capex,\n    depreciation,\n    operatingCashFlow:  ocf,\n    incomeTaxExpense:   taxExpense,\n    ebt,\n    interestExpense:    interestExp,\n    currentAssets,\n    currentLiabilities: currentLiab,\n    accountsReceivable: ar,\n    dividendsPaid:      dividendsPaid,\n    ...(sharesOutstanding !== undefined ? { sharesOutstanding } : {}),\n  }\n}\n\n/** Extract the first non-zero numeric value from a Polygon section by key priority. */\nfunction _v(\n  section: Record<string, _PolygonValue>,\n  ...keys: string[]\n): number {\n  for (const k of keys) {\n    const node = section[k]\n    if (node && node.value != null) {\n      const n = Number(node.value)\n      if (!isNaN(n)) return n\n    }\n  }\n  return 0\n}\n\n/** Return an ISO date string N years ago from today. */\nfunction _startDate(years: number): string {\n  const d = new Date()\n  d.setFullYear(d.getFullYear() - years)\n  return d.toISOString().slice(0, 10)\n}\n"]}

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

@@ -0,0 +1,84 @@
+/**
+ * Polygon.io fetcher for fin-ratios (TypeScript).
+ *
+ * Fetches fundamental financial data from the Polygon.io REST API.
+ * API key required — get one at https://polygon.io.
+ * US companies only.  Free tier: 5 req/min, ~2 years of history.
+ *
+ * @example
+ * import { fetchPolygon, setPolygonApiKey } from 'fin-ratios/fetchers/polygon'
+ * setPolygonApiKey('your-api-key')
+ * const data = await fetchPolygon('AAPL', { numYears: 5 })
+ * // data is oldest-first and compatible with all scoring utilities
+ */
+/**
+ * Store a Polygon.io API key module-wide.
+ * Subsequent calls to {@link fetchPolygon} will use this key unless overridden
+ * via the {@link PolygonOptions.apiKey} option.
+ */
+declare function setPolygonApiKey(key: string): void;
+interface PolygonOptions {
+    /** Number of annual periods to retrieve (default: 5). */
+    numYears?: number;
+    /**
+     * Polygon.io API key.  Falls back to the module-level key set via
+     * {@link setPolygonApiKey} and then to the `POLYGON_API_KEY` environment
+     * variable (Node.js only).
+     */
+    apiKey?: string;
+    /** ``'annual'`` (default) or ``'quarterly'``. */
+    timeframe?: 'annual' | 'quarterly';
+}
+/**
+ * Normalised annual financial record returned by {@link fetchPolygon}.
+ * Field names are compatible with the `EdgarAnnualRecord` type used by the
+ * EDGAR fetcher, so the data can be passed directly to all scoring utilities:
+ * `moatScore`, `capitalAllocationScore`, `earningsQualityScore`,
+ * `qualityScore`, `investmentScore`, etc.
+ */
+interface PolygonAnnualRecord {
+    /** Four-digit fiscal year string, e.g. ``'2023'``. */
+    year: string;
+    revenue: number;
+    grossProfit: number;
+    /** Operating income (EBIT). */
+    ebit: number;
+    netIncome: number;
+    totalAssets: number;
+    totalEquity: number;
+    /** Long-term debt (used as total debt proxy). */
+    totalDebt: number;
+    cash: number;
+    /** Capital expenditures (absolute value). */
+    capex: number;
+    depreciation: number;
+    operatingCashFlow: number;
+    incomeTaxExpense: number;
+    ebt: number;
+    interestExpense: number;
+    currentAssets: number;
+    currentLiabilities: number;
+    accountsReceivable: number;
+    /** Dividends paid (absolute value).  Zero for non-payers. */
+    dividendsPaid?: number;
+    /** Shares outstanding (or weighted-average basic shares). */
+    sharesOutstanding?: number;
+}
+/**
+ * Fetch annual financial data from Polygon.io.
+ *
+ * @param ticker - Stock ticker symbol (e.g. ``'AAPL'``).
+ * @param options - Options including API key, number of years, and timeframe.
+ * @returns Oldest-first list of annual records compatible with all scoring
+ *   utilities (moatScore, capitalAllocationScore, qualityScore, etc.).
+ *
+ * @throws {Error} If no API key is available.
+ * @throws {Error} If the Polygon.io API request fails.
+ *
+ * @example
+ * import { fetchPolygon } from 'fin-ratios/fetchers/polygon'
+ * const data = await fetchPolygon('AAPL', { numYears: 5, apiKey: 'your-key' })
+ */
+declare function fetchPolygon(ticker: string, options?: PolygonOptions): Promise<PolygonAnnualRecord[]>;
+
+export { type PolygonAnnualRecord, type PolygonOptions, fetchPolygon, setPolygonApiKey };

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

@@ -0,0 +1,84 @@
+/**
+ * Polygon.io fetcher for fin-ratios (TypeScript).
+ *
+ * Fetches fundamental financial data from the Polygon.io REST API.
+ * API key required — get one at https://polygon.io.
+ * US companies only.  Free tier: 5 req/min, ~2 years of history.
+ *
+ * @example
+ * import { fetchPolygon, setPolygonApiKey } from 'fin-ratios/fetchers/polygon'
+ * setPolygonApiKey('your-api-key')
+ * const data = await fetchPolygon('AAPL', { numYears: 5 })
+ * // data is oldest-first and compatible with all scoring utilities
+ */
+/**
+ * Store a Polygon.io API key module-wide.
+ * Subsequent calls to {@link fetchPolygon} will use this key unless overridden
+ * via the {@link PolygonOptions.apiKey} option.
+ */
+declare function setPolygonApiKey(key: string): void;
+interface PolygonOptions {
+    /** Number of annual periods to retrieve (default: 5). */
+    numYears?: number;
+    /**
+     * Polygon.io API key.  Falls back to the module-level key set via
+     * {@link setPolygonApiKey} and then to the `POLYGON_API_KEY` environment
+     * variable (Node.js only).
+     */
+    apiKey?: string;
+    /** ``'annual'`` (default) or ``'quarterly'``. */
+    timeframe?: 'annual' | 'quarterly';
+}
+/**
+ * Normalised annual financial record returned by {@link fetchPolygon}.
+ * Field names are compatible with the `EdgarAnnualRecord` type used by the
+ * EDGAR fetcher, so the data can be passed directly to all scoring utilities:
+ * `moatScore`, `capitalAllocationScore`, `earningsQualityScore`,
+ * `qualityScore`, `investmentScore`, etc.
+ */
+interface PolygonAnnualRecord {
+    /** Four-digit fiscal year string, e.g. ``'2023'``. */
+    year: string;
+    revenue: number;
+    grossProfit: number;
+    /** Operating income (EBIT). */
+    ebit: number;
+    netIncome: number;
+    totalAssets: number;
+    totalEquity: number;
+    /** Long-term debt (used as total debt proxy). */
+    totalDebt: number;
+    cash: number;
+    /** Capital expenditures (absolute value). */
+    capex: number;
+    depreciation: number;
+    operatingCashFlow: number;
+    incomeTaxExpense: number;
+    ebt: number;
+    interestExpense: number;
+    currentAssets: number;
+    currentLiabilities: number;
+    accountsReceivable: number;
+    /** Dividends paid (absolute value).  Zero for non-payers. */
+    dividendsPaid?: number;
+    /** Shares outstanding (or weighted-average basic shares). */
+    sharesOutstanding?: number;
+}
+/**
+ * Fetch annual financial data from Polygon.io.
+ *
+ * @param ticker - Stock ticker symbol (e.g. ``'AAPL'``).
+ * @param options - Options including API key, number of years, and timeframe.
+ * @returns Oldest-first list of annual records compatible with all scoring
+ *   utilities (moatScore, capitalAllocationScore, qualityScore, etc.).
+ *
+ * @throws {Error} If no API key is available.
+ * @throws {Error} If the Polygon.io API request fails.
+ *
+ * @example
+ * import { fetchPolygon } from 'fin-ratios/fetchers/polygon'
+ * const data = await fetchPolygon('AAPL', { numYears: 5, apiKey: 'your-key' })
+ */
+declare function fetchPolygon(ticker: string, options?: PolygonOptions): Promise<PolygonAnnualRecord[]>;
+
+export { type PolygonAnnualRecord, type PolygonOptions, fetchPolygon, setPolygonApiKey };

package/dist/fetchers/polygon/index.js

@@ -0,0 +1,173 @@
+// src/fetchers/polygon/index.ts
+var POLYGON_BASE = "https://api.polygon.io/vX/reference/financials";
+var _moduleKey;
+function setPolygonApiKey(key) {
+  _moduleKey = key;
+}
+async function fetchPolygon(ticker, options = {}) {
+  const { numYears = 5, timeframe = "annual" } = options;
+  const apiKey = options.apiKey ?? _moduleKey ?? (typeof process !== "undefined" ? process.env["POLYGON_API_KEY"] : void 0);
+  if (!apiKey) {
+    throw new Error(
+      "Polygon.io API key is required. Provide it via options.apiKey, setPolygonApiKey(), or the POLYGON_API_KEY environment variable."
+    );
+  }
+  const startDate = _startDate(Math.max(numYears, 2));
+  const params = new URLSearchParams({
+    ticker: ticker.toUpperCase(),
+    timeframe,
+    limit: String(Math.min(numYears, 100)),
+    sort: "period_of_report_date",
+    order: "asc",
+    "filing_date.gte": startDate,
+    apiKey
+  });
+  const url = `${POLYGON_BASE}?${params.toString()}`;
+  let payload;
+  try {
+    const resp = await fetch(url);
+    if (resp.status === 401) {
+      throw new Error(
+        "Polygon API returned 401 Unauthorized \u2014 check your API key."
+      );
+    }
+    if (resp.status === 429) {
+      throw new Error(
+        "Polygon API rate limit exceeded (free tier: 5 req/min). Wait a moment and retry."
+      );
+    }
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(
+        `Polygon API request failed for ${ticker}: HTTP ${resp.status} \u2014 ${body.slice(0, 200)}`
+      );
+    }
+    payload = await resp.json();
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("Polygon API")) throw err;
+    throw new Error(
+      `Polygon API request failed for ${ticker}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const results = payload.results ?? [];
+  return results.map((item) => _mapRecord(item));
+}
+function _mapRecord(item) {
+  const inc = item.financials?.income_statement ?? {};
+  const bal = item.financials?.balance_sheet ?? {};
+  const cf = item.financials?.cash_flow_statement ?? {};
+  const revenue = _v(inc, "revenues", "net_revenues", "total_revenues");
+  const grossProfit = _v(inc, "gross_profit");
+  const ebit = _v(
+    inc,
+    "operating_income",
+    "income_loss_from_continuing_operations_before_tax"
+  );
+  const netIncome = _v(inc, "net_income_loss", "net_income_loss_attributable_to_parent");
+  const taxExpense = _v(inc, "income_tax_expense_benefit");
+  const interestExp = Math.abs(_v(inc, "interest_expense_operating", "interest_expense"));
+  const ebtDirect = _v(
+    inc,
+    "income_loss_from_continuing_operations_before_tax",
+    "income_before_income_taxes"
+  );
+  const ebt = ebtDirect !== 0 ? ebtDirect : netIncome + taxExpense;
+  const totalAssets = _v(bal, "assets");
+  const currentAssets = _v(bal, "current_assets");
+  const cash = _v(
+    bal,
+    "cash_and_cash_equivalents_including_short_term_investments",
+    "cash_and_cash_equivalents",
+    "cash"
+  );
+  const currentLiab = _v(bal, "current_liabilities");
+  const totalEquity = _v(
+    bal,
+    "equity",
+    "stockholders_equity",
+    "equity_attributable_to_parent"
+  );
+  const longTermDebt = _v(bal, "long_term_debt");
+  const ar = _v(
+    bal,
+    "accounts_receivable",
+    "accounts_receivable_net_current",
+    "trade_and_other_receivables_current"
+  );
+  const ocf = _v(
+    cf,
+    "net_cash_flow_from_operating_activities",
+    "net_cash_provided_by_used_in_operating_activities"
+  );
+  const investingCf = _v(
+    cf,
+    "net_cash_flow_from_investing_activities",
+    "net_cash_provided_by_used_in_investing_activities"
+  );
+  const capexDirect = _v(
+    cf,
+    "payments_to_acquire_property_plant_and_equipment",
+    "capital_expenditures"
+  );
+  const capex = capexDirect !== 0 ? Math.abs(capexDirect) : Math.abs(investingCf);
+  const dividendsPaid = Math.abs(
+    _v(cf, "payments_of_dividends", "payments_of_dividends_common_stock", "dividends_paid")
+  );
+  let depreciation = _v(
+    inc,
+    "depreciation_and_amortization",
+    "depreciation_depletion_and_amortization"
+  );
+  if (depreciation === 0) {
+    depreciation = _v(
+      cf,
+      "depreciation_depletion_and_amortization",
+      "depreciation_and_amortization"
+    );
+  }
+  const sharesBS = _v(bal, "common_stock_shares_outstanding");
+  const sharesInc = _v(inc, "basic_average_shares", "diluted_average_shares");
+  const sharesOutstanding = sharesBS !== 0 ? sharesBS : sharesInc !== 0 ? sharesInc : void 0;
+  const year = String(item.fiscal_year ?? item.period_of_report_date?.slice(0, 4) ?? "");
+  return {
+    year,
+    revenue,
+    grossProfit,
+    ebit,
+    netIncome,
+    totalAssets,
+    totalEquity,
+    totalDebt: longTermDebt,
+    cash,
+    capex,
+    depreciation,
+    operatingCashFlow: ocf,
+    incomeTaxExpense: taxExpense,
+    ebt,
+    interestExpense: interestExp,
+    currentAssets,
+    currentLiabilities: currentLiab,
+    accountsReceivable: ar,
+    dividendsPaid,
+    ...sharesOutstanding !== void 0 ? { sharesOutstanding } : {}
+  };
+}
+function _v(section, ...keys) {
+  for (const k of keys) {
+    const node = section[k];
+    if (node && node.value != null) {
+      const n = Number(node.value);
+      if (!isNaN(n)) return n;
+    }
+  }
+  return 0;
+}
+function _startDate(years) {
+  const d = /* @__PURE__ */ new Date();
+  d.setFullYear(d.getFullYear() - years);
+  return d.toISOString().slice(0, 10);
+}
+
+export { fetchPolygon, setPolygonApiKey };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/fetchers/polygon/index.ts"],"names":[],"mappings":";AAcA,IAAM,YAAA,GAAe,gDAAA;AAIrB,IAAI,UAAA;AAOG,SAAS,iBAAiB,GAAA,EAAmB;AAClD,EAAA,UAAA,GAAa,GAAA;AACf;AAiGA,eAAsB,YAAA,CACpB,MAAA,EACA,OAAA,GAA0B,EAAC,EACK;AAChC,EAAA,MAAM,EAAE,QAAA,GAAW,CAAA,EAAG,SAAA,GAAY,UAAS,GAAI,OAAA;AAG/C,EAAA,MAAM,MAAA,GACJ,OAAA,CAAQ,MAAA,IACR,UAAA,KACC,OAAO,YAAY,WAAA,GAAc,OAAA,CAAQ,GAAA,CAAI,iBAAiB,CAAA,GAAI,MAAA,CAAA;AAErE,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAEF;AAAA,EACF;AAGA,EAAA,MAAM,YAAY,UAAA,CAAW,IAAA,CAAK,GAAA,CAAI,QAAA,EAAU,CAAC,CAAC,CAAA;AAElD,EAAA,MAAM,MAAA,GAAS,IAAI,eAAA,CAAgB;AAAA,IACjC,MAAA,EAAyB,OAAO,WAAA,EAAY;AAAA,IAC5C,SAAA;AAAA,IACA,OAAyB,MAAA,CAAO,IAAA,CAAK,GAAA,CAAI,QAAA,EAAU,GAAG,CAAC,CAAA;AAAA,IACvD,IAAA,EAAyB,uBAAA;AAAA,IACzB,KAAA,EAAyB,KAAA;AAAA,IACzB,iBAAA,EAAyB,SAAA;AAAA,IACzB;AAAA,GACD,CAAA;AAED,EAAA,MAAM,MAAM,CAAA,EAAG,YAAY,CAAA,CAAA,EAAI,MAAA,CAAO,UAAU,CAAA,CAAA;AAEhD,EAAA,IAAI,OAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAM,IAAA,GAAO,MAAM,KAAA,CAAM,GAAG,CAAA;AAC5B,IAAA,IAAI,IAAA,CAAK,WAAW,GAAA,EAAK;AACvB,MAAA,MAAM,IAAI,KAAA;AAAA,QACR;AAAA,OACF;AAAA,IACF;AACA,IAAA,IAAI,IAAA,CAAK,WAAW,GAAA,EAAK;AACvB,MAAA,MAAM,IAAI,KAAA;AAAA,QACR;AAAA,OAEF;AAAA,IACF;AACA,IAAA,IAAI,CAAC,KAAK,EAAA,EAAI;AACZ,MAAA,MAAM,OAAO,MAAM,IAAA,CAAK,MAAK,CAAE,KAAA,CAAM,MAAM,EAAE,CAAA;AAC7C,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,+BAAA,EAAkC,MAAM,CAAA,OAAA,EAAU,IAAA,CAAK,MAAM,WAAM,IAAA,CAAK,KAAA,CAAM,CAAA,EAAG,GAAG,CAAC,CAAA;AAAA,OACvF;AAAA,IACF;AACA,IAAA,OAAA,GAAW,MAAM,KAAK,IAAA,EAAK;AAAA,EAC7B,SAAS,GAAA,EAAK;AAEZ,IAAA,IAAI,eAAe,KAAA,IAAS,GAAA,CAAI,QAAQ,UAAA,CAAW,aAAa,GAAG,MAAM,GAAA;AACzE,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,+BAAA,EAAkC,MAAM,CAAA,EAAA,EAAK,GAAA,YAAe,QAAQ,GAAA,CAAI,OAAA,GAAU,MAAA,CAAO,GAAG,CAAC,CAAA;AAAA,KAC/F;AAAA,EACF;AAEA,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,OAAA,IAAW,EAAC;AACpC,EAAA,OAAO,OAAA,CAAQ,GAAA,CAAI,CAAA,IAAA,KAAQ,UAAA,CAAW,IAAI,CAAC,CAAA;AAC7C;AAIA,SAAS,WAAW,IAAA,EAA2C;AAC7D,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,UAAA,EAAY,gBAAA,IAAuB,EAAC;AACrD,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,UAAA,EAAY,aAAA,IAAuB,EAAC;AACrD,EAAA,MAAM,EAAA,GAAM,IAAA,CAAK,UAAA,EAAY,mBAAA,IAAuB,EAAC;AAErD,EAAA,MAAM,OAAA,GAAe,EAAA,CAAG,GAAA,EAAK,UAAA,EAAY,gBAAgB,gBAAgB,CAAA;AACzE,EAAA,MAAM,WAAA,GAAe,EAAA,CAAG,GAAA,EAAK,cAAc,CAAA;AAC3C,EAAA,MAAM,IAAA,GAAe,EAAA;AAAA,IAAG,GAAA;AAAA,IAAK,kBAAA;AAAA,IACJ;AAAA,GAAmD;AAC5E,EAAA,MAAM,SAAA,GAAe,EAAA,CAAG,GAAA,EAAK,iBAAA,EAAmB,wCAAwC,CAAA;AACxF,EAAA,MAAM,UAAA,GAAe,EAAA,CAAG,GAAA,EAAK,4BAA4B,CAAA;AACzD,EAAA,MAAM,cAAe,IAAA,CAAK,GAAA,CAAI,GAAG,GAAA,EAAK,4BAAA,EAA8B,kBAAkB,CAAC,CAAA;AAGvF,EAAA,MAAM,SAAA,GAAe,EAAA;AAAA,IAAG,GAAA;AAAA,IAAK,mDAAA;AAAA,IACJ;AAAA,GAA4B;AACrD,EAAA,MAAM,GAAA,GAAe,SAAA,KAAc,CAAA,GAAI,SAAA,GAAY,SAAA,GAAY,UAAA;AAE/D,EAAA,MAAM,WAAA,GAAe,EAAA,CAAG,GAAA,EAAK,QAAQ,CAAA;AACrC,EAAA,MAAM,aAAA,GAAgB,EAAA,CAAG,GAAA,EAAK,gBAAgB,CAAA;AAC9C,EAAA,MAAM,IAAA,GAAe,EAAA;AAAA,IAAG,GAAA;AAAA,IACA,4DAAA;AAAA,IACA,2BAAA;AAAA,IAA6B;AAAA,GAAM;AAC3D,EAAA,MAAM,WAAA,GAAe,EAAA,CAAG,GAAA,EAAK,qBAAqB,CAAA;AAClD,EAAA,MAAM,WAAA,GAAe,EAAA;AAAA,IAAG,GAAA;AAAA,IAAK,QAAA;AAAA,IAAU,qBAAA;AAAA,IACd;AAAA,GAA+B;AACxD,EAAA,MAAM,YAAA,GAAe,EAAA,CAAG,GAAA,EAAK,gBAAgB,CAAA;AAC7C,EAAA,MAAM,EAAA,GAAe,EAAA;AAAA,IAAG,GAAA;AAAA,IAAK,qBAAA;AAAA,IACJ,iCAAA;AAAA,IACA;AAAA,GAAqC;AAE9D,EAAA,MAAM,GAAA,GAAe,EAAA;AAAA,IAAG,EAAA;AAAA,IAAI,yCAAA;AAAA,IACH;AAAA,GAAmD;AAC5E,EAAA,MAAM,WAAA,GAAe,EAAA;AAAA,IAAG,EAAA;AAAA,IAAI,yCAAA;AAAA,IACH;AAAA,GAAmD;AAC5E,EAAA,MAAM,WAAA,GAAe,EAAA;AAAA,IAAG,EAAA;AAAA,IACC,kDAAA;AAAA,IACA;AAAA,GAAsB;AAC/C,EAAA,MAAM,KAAA,GAAe,gBAAgB,CAAA,GAAI,IAAA,CAAK,IAAI,WAAW,CAAA,GAAI,IAAA,CAAK,GAAA,CAAI,WAAW,CAAA;AAErF,EAAA,MAAM,gBAAgB,IAAA,CAAK,GAAA;AAAA,IACzB,EAAA,CAAG,EAAA,EAAI,uBAAA,EAAyB,oCAAA,EAAsC,gBAAgB;AAAA,GACxF;AAEA,EAAA,IAAI,YAAA,GAAe,EAAA;AAAA,IAAG,GAAA;AAAA,IAAK,+BAAA;AAAA,IACJ;AAAA,GAAyC;AAChE,EAAA,IAAI,iBAAiB,CAAA,EAAG;AACtB,IAAA,YAAA,GAAe,EAAA;AAAA,MAAG,EAAA;AAAA,MAAI,yCAAA;AAAA,MACJ;AAAA,KAA+B;AAAA,EACnD;AAGA,EAAA,MAAM,QAAA,GAAc,EAAA,CAAG,GAAA,EAAK,iCAAiC,CAAA;AAC7D,EAAA,MAAM,SAAA,GAAc,EAAA,CAAG,GAAA,EAAK,sBAAA,EAAwB,wBAAwB,CAAA;AAC5E,EAAA,MAAM,oBAAoB,QAAA,KAAa,CAAA,GAAI,QAAA,GAAW,SAAA,KAAc,IAAI,SAAA,GAAY,MAAA;AAEpF,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,IAAA,CAAK,WAAA,IAAe,IAAA,CAAK,uBAAuB,KAAA,CAAM,CAAA,EAAG,CAAC,CAAA,IAAK,EAAE,CAAA;AAErF,EAAA,OAAO;AAAA,IACL,IAAA;AAAA,IACA,OAAA;AAAA,IACA,WAAA;AAAA,IACA,IAAA;AAAA,IACA,SAAA;AAAA,IACA,WAAA;AAAA,IACA,WAAA;AAAA,IACA,SAAA,EAAoB,YAAA;AAAA,IACpB,IAAA;AAAA,IACA,KAAA;AAAA,IACA,YAAA;AAAA,IACA,iBAAA,EAAoB,GAAA;AAAA,IACpB,gBAAA,EAAoB,UAAA;AAAA,IACpB,GAAA;AAAA,IACA,eAAA,EAAoB,WAAA;AAAA,IACpB,aAAA;AAAA,IACA,kBAAA,EAAoB,WAAA;AAAA,IACpB,kBAAA,EAAoB,EAAA;AAAA,IACpB,aAAA;AAAA,IACA,GAAI,iBAAA,KAAsB,MAAA,GAAY,EAAE,iBAAA,KAAsB;AAAC,GACjE;AACF;AAGA,SAAS,EAAA,CACP,YACG,IAAA,EACK;AACR,EAAA,KAAA,MAAW,KAAK,IAAA,EAAM;AACpB,IAAA,MAAM,IAAA,GAAO,QAAQ,CAAC,CAAA;AACtB,IAAA,IAAI,IAAA,IAAQ,IAAA,CAAK,KAAA,IAAS,IAAA,EAAM;AAC9B,MAAA,MAAM,CAAA,GAAI,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA;AAC3B,MAAA,IAAI,CAAC,KAAA,CAAM,CAAC,CAAA,EAAG,OAAO,CAAA;AAAA,IACxB;AAAA,EACF;AACA,EAAA,OAAO,CAAA;AACT;AAGA,SAAS,WAAW,KAAA,EAAuB;AACzC,EAAA,MAAM,CAAA,uBAAQ,IAAA,EAAK;AACnB,EAAA,CAAA,CAAE,WAAA,CAAY,CAAA,CAAE,WAAA,EAAY,GAAI,KAAK,CAAA;AACrC,EAAA,OAAO,CAAA,CAAE,WAAA,EAAY,CAAE,KAAA,CAAM,GAAG,EAAE,CAAA;AACpC","file":"index.js","sourcesContent":["/**\n * Polygon.io fetcher for fin-ratios (TypeScript).\n *\n * Fetches fundamental financial data from the Polygon.io REST API.\n * API key required — get one at https://polygon.io.\n * US companies only.  Free tier: 5 req/min, ~2 years of history.\n *\n * @example\n * import { fetchPolygon, setPolygonApiKey } from 'fin-ratios/fetchers/polygon'\n * setPolygonApiKey('your-api-key')\n * const data = await fetchPolygon('AAPL', { numYears: 5 })\n * // data is oldest-first and compatible with all scoring utilities\n */\n\nconst POLYGON_BASE = 'https://api.polygon.io/vX/reference/financials'\n\n// ── Module-level key storage ───────────────────────────────────────────────────\n\nlet _moduleKey: string | undefined\n\n/**\n * Store a Polygon.io API key module-wide.\n * Subsequent calls to {@link fetchPolygon} will use this key unless overridden\n * via the {@link PolygonOptions.apiKey} option.\n */\nexport function setPolygonApiKey(key: string): void {\n  _moduleKey = key\n}\n\n// ── Types ──────────────────────────────────────────────────────────────────────\n\nexport interface PolygonOptions {\n  /** Number of annual periods to retrieve (default: 5). */\n  numYears?: number\n  /**\n   * Polygon.io API key.  Falls back to the module-level key set via\n   * {@link setPolygonApiKey} and then to the `POLYGON_API_KEY` environment\n   * variable (Node.js only).\n   */\n  apiKey?: string\n  /** ``'annual'`` (default) or ``'quarterly'``. */\n  timeframe?: 'annual' | 'quarterly'\n}\n\n/**\n * Normalised annual financial record returned by {@link fetchPolygon}.\n * Field names are compatible with the `EdgarAnnualRecord` type used by the\n * EDGAR fetcher, so the data can be passed directly to all scoring utilities:\n * `moatScore`, `capitalAllocationScore`, `earningsQualityScore`,\n * `qualityScore`, `investmentScore`, etc.\n */\nexport interface PolygonAnnualRecord {\n  /** Four-digit fiscal year string, e.g. ``'2023'``. */\n  year: string\n  revenue: number\n  grossProfit: number\n  /** Operating income (EBIT). */\n  ebit: number\n  netIncome: number\n  totalAssets: number\n  totalEquity: number\n  /** Long-term debt (used as total debt proxy). */\n  totalDebt: number\n  cash: number\n  /** Capital expenditures (absolute value). */\n  capex: number\n  depreciation: number\n  operatingCashFlow: number\n  incomeTaxExpense: number\n  ebt: number\n  interestExpense: number\n  currentAssets: number\n  currentLiabilities: number\n  accountsReceivable: number\n  /** Dividends paid (absolute value).  Zero for non-payers. */\n  dividendsPaid?: number\n  /** Shares outstanding (or weighted-average basic shares). */\n  sharesOutstanding?: number\n}\n\n// ── Internal Polygon response types ───────────────────────────────────────────\n\ninterface _PolygonValue {\n  value?: number | null\n  unit?: string\n  label?: string\n}\n\ninterface _PolygonFinancials {\n  income_statement?: Record<string, _PolygonValue>\n  balance_sheet?: Record<string, _PolygonValue>\n  cash_flow_statement?: Record<string, _PolygonValue>\n}\n\ninterface _PolygonResult {\n  fiscal_year?: string | number\n  period_of_report_date?: string\n  financials?: _PolygonFinancials\n}\n\ninterface _PolygonResponse {\n  results?: _PolygonResult[]\n  status?: string\n  request_id?: string\n  next_url?: string\n}\n\n// ── Public API ─────────────────────────────────────────────────────────────────\n\n/**\n * Fetch annual financial data from Polygon.io.\n *\n * @param ticker - Stock ticker symbol (e.g. ``'AAPL'``).\n * @param options - Options including API key, number of years, and timeframe.\n * @returns Oldest-first list of annual records compatible with all scoring\n *   utilities (moatScore, capitalAllocationScore, qualityScore, etc.).\n *\n * @throws {Error} If no API key is available.\n * @throws {Error} If the Polygon.io API request fails.\n *\n * @example\n * import { fetchPolygon } from 'fin-ratios/fetchers/polygon'\n * const data = await fetchPolygon('AAPL', { numYears: 5, apiKey: 'your-key' })\n */\nexport async function fetchPolygon(\n  ticker: string,\n  options: PolygonOptions = {}\n): Promise<PolygonAnnualRecord[]> {\n  const { numYears = 5, timeframe = 'annual' } = options\n\n  // Resolve API key: option > module-level > env var\n  const apiKey =\n    options.apiKey ??\n    _moduleKey ??\n    (typeof process !== 'undefined' ? process.env['POLYGON_API_KEY'] : undefined)\n\n  if (!apiKey) {\n    throw new Error(\n      'Polygon.io API key is required. Provide it via options.apiKey, ' +\n        'setPolygonApiKey(), or the POLYGON_API_KEY environment variable.'\n    )\n  }\n\n  // Build start date: go back numYears years from today\n  const startDate = _startDate(Math.max(numYears, 2))\n\n  const params = new URLSearchParams({\n    ticker:                  ticker.toUpperCase(),\n    timeframe,\n    limit:                   String(Math.min(numYears, 100)),\n    sort:                    'period_of_report_date',\n    order:                   'asc',\n    'filing_date.gte':       startDate,\n    apiKey,\n  })\n\n  const url = `${POLYGON_BASE}?${params.toString()}`\n\n  let payload: _PolygonResponse\n  try {\n    const resp = await fetch(url)\n    if (resp.status === 401) {\n      throw new Error(\n        'Polygon API returned 401 Unauthorized — check your API key.'\n      )\n    }\n    if (resp.status === 429) {\n      throw new Error(\n        'Polygon API rate limit exceeded (free tier: 5 req/min). ' +\n          'Wait a moment and retry.'\n      )\n    }\n    if (!resp.ok) {\n      const body = await resp.text().catch(() => '')\n      throw new Error(\n        `Polygon API request failed for ${ticker}: HTTP ${resp.status} — ${body.slice(0, 200)}`\n      )\n    }\n    payload = (await resp.json()) as _PolygonResponse\n  } catch (err) {\n    // Re-throw errors we constructed above; wrap unexpected fetch failures\n    if (err instanceof Error && err.message.startsWith('Polygon API')) throw err\n    throw new Error(\n      `Polygon API request failed for ${ticker}: ${err instanceof Error ? err.message : String(err)}`\n    )\n  }\n\n  const results = payload.results ?? []\n  return results.map(item => _mapRecord(item))\n}\n\n// ── Mapping helpers ────────────────────────────────────────────────────────────\n\nfunction _mapRecord(item: _PolygonResult): PolygonAnnualRecord {\n  const inc = item.financials?.income_statement    ?? {}\n  const bal = item.financials?.balance_sheet       ?? {}\n  const cf  = item.financials?.cash_flow_statement ?? {}\n\n  const revenue      = _v(inc, 'revenues', 'net_revenues', 'total_revenues')\n  const grossProfit  = _v(inc, 'gross_profit')\n  const ebit         = _v(inc, 'operating_income',\n                           'income_loss_from_continuing_operations_before_tax')\n  const netIncome    = _v(inc, 'net_income_loss', 'net_income_loss_attributable_to_parent')\n  const taxExpense   = _v(inc, 'income_tax_expense_benefit')\n  const interestExp  = Math.abs(_v(inc, 'interest_expense_operating', 'interest_expense'))\n\n  // EBT: prefer direct field, fall back to net income + taxes\n  const ebtDirect    = _v(inc, 'income_loss_from_continuing_operations_before_tax',\n                           'income_before_income_taxes')\n  const ebt          = ebtDirect !== 0 ? ebtDirect : netIncome + taxExpense\n\n  const totalAssets  = _v(bal, 'assets')\n  const currentAssets = _v(bal, 'current_assets')\n  const cash         = _v(bal,\n                          'cash_and_cash_equivalents_including_short_term_investments',\n                          'cash_and_cash_equivalents', 'cash')\n  const currentLiab  = _v(bal, 'current_liabilities')\n  const totalEquity  = _v(bal, 'equity', 'stockholders_equity',\n                           'equity_attributable_to_parent')\n  const longTermDebt = _v(bal, 'long_term_debt')\n  const ar           = _v(bal, 'accounts_receivable',\n                           'accounts_receivable_net_current',\n                           'trade_and_other_receivables_current')\n\n  const ocf          = _v(cf, 'net_cash_flow_from_operating_activities',\n                           'net_cash_provided_by_used_in_operating_activities')\n  const investingCf  = _v(cf, 'net_cash_flow_from_investing_activities',\n                           'net_cash_provided_by_used_in_investing_activities')\n  const capexDirect  = _v(cf,\n                           'payments_to_acquire_property_plant_and_equipment',\n                           'capital_expenditures')\n  const capex        = capexDirect !== 0 ? Math.abs(capexDirect) : Math.abs(investingCf)\n\n  const dividendsPaid = Math.abs(\n    _v(cf, 'payments_of_dividends', 'payments_of_dividends_common_stock', 'dividends_paid')\n  )\n\n  let depreciation = _v(inc, 'depreciation_and_amortization',\n                         'depreciation_depletion_and_amortization')\n  if (depreciation === 0) {\n    depreciation = _v(cf, 'depreciation_depletion_and_amortization',\n                      'depreciation_and_amortization')\n  }\n\n  // Shares: prefer balance-sheet figure; fall back to income-statement weighted avg\n  const sharesBS    = _v(bal, 'common_stock_shares_outstanding')\n  const sharesInc   = _v(inc, 'basic_average_shares', 'diluted_average_shares')\n  const sharesOutstanding = sharesBS !== 0 ? sharesBS : sharesInc !== 0 ? sharesInc : undefined\n\n  const year = String(item.fiscal_year ?? item.period_of_report_date?.slice(0, 4) ?? '')\n\n  return {\n    year,\n    revenue,\n    grossProfit,\n    ebit,\n    netIncome,\n    totalAssets,\n    totalEquity,\n    totalDebt:          longTermDebt,\n    cash,\n    capex,\n    depreciation,\n    operatingCashFlow:  ocf,\n    incomeTaxExpense:   taxExpense,\n    ebt,\n    interestExpense:    interestExp,\n    currentAssets,\n    currentLiabilities: currentLiab,\n    accountsReceivable: ar,\n    dividendsPaid:      dividendsPaid,\n    ...(sharesOutstanding !== undefined ? { sharesOutstanding } : {}),\n  }\n}\n\n/** Extract the first non-zero numeric value from a Polygon section by key priority. */\nfunction _v(\n  section: Record<string, _PolygonValue>,\n  ...keys: string[]\n): number {\n  for (const k of keys) {\n    const node = section[k]\n    if (node && node.value != null) {\n      const n = Number(node.value)\n      if (!isNaN(n)) return n\n    }\n  }\n  return 0\n}\n\n/** Return an ISO date string N years ago from today. */\nfunction _startDate(years: number): string {\n  const d = new Date()\n  d.setFullYear(d.getFullYear() - years)\n  return d.toISOString().slice(0, 10)\n}\n"]}