fin-ratios 0.7.3 → 1.0.2

package/dist/fetchers/alphavantage/index.cjs

@@ -85,5 +85,3 @@ function _n(v) {
 }
 
 exports.fetchAlphaVantage = fetchAlphaVantage;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map

package/dist/fetchers/alphavantage/index.js

@@ -83,5 +83,3 @@ function _n(v) {
 }
 
 export { fetchAlphaVantage };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/fetchers/edgar/index.cjs

@@ -148,5 +148,3 @@ 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.js

@@ -142,5 +142,3 @@ async function _get(url) {
 }
 
 export { fetchEdgar, fetchEdgarFlat, fetchEdgarNormalized, flattenEdgarData, normalizeForScoring };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/fetchers/fmp/index.cjs

@@ -106,5 +106,3 @@ function _n(v) {
 
 exports.fetchFmp = fetchFmp;
 exports.fetchFmpSp500 = fetchFmpSp500;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map

package/dist/fetchers/fmp/index.js

@@ -103,5 +103,3 @@ function _n(v) {
 }
 
 export { fetchFmp, fetchFmpSp500 };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/fetchers/polygon/index.cjs

@@ -0,0 +1,174 @@
+'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;

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,171 @@
+// 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 };

package/dist/fetchers/yahoo/index.cjs

@@ -130,5 +130,3 @@ function _n(v) {
 
 exports.fetchPriceHistory = fetchPriceHistory;
 exports.fetchYahoo = fetchYahoo;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map

package/dist/fetchers/yahoo/index.js

@@ -127,5 +127,3 @@ function _n(v) {
 }
 
 export { fetchPriceHistory, fetchYahoo };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/hooks/index.cjs

@@ -610,5 +610,3 @@ exports.useHealthScore = useHealthScore;
 exports.useRatio = useRatio;
 exports.useRatios = useRatios;
 exports.useScenarioDcf = useScenarioDcf;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map

package/dist/hooks/index.js

@@ -604,5 +604,3 @@ function useCompareRatios(tickers, fetcher) {
 }
 
 export { useCompareRatios, useHealthScore, useRatio, useRatios, useScenarioDcf };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map