fundamentalista 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60ef7c2913952daa4c9a4bcf633813d421326b9cc9ccc55755731ef536c51785
-  data.tar.gz: 712549d9e3a33d73e2ce21ca19c5780267cdb64a02261b546dff0e62ac05c3e2
+  metadata.gz: 157c2e2b5398a2feb0e9c1d80b76b8273909a6d0e7fbd038929d647bb3b3d5e2
+  data.tar.gz: e4a34806e3588dcc4afdb41bf287523fc75500e1d74c13fb4aed7c477690bf6e
 SHA512:
-  metadata.gz: a5d017ed989ad8ba888720041675e15bd683fdf391dcfb9dbdf5d14918f9acc88581854eeef5ed4995f69b3ad25074f5e60f1df63e420e03481ed387b342a302
-  data.tar.gz: f839a5b66257300a5b139fac8d303b031ebfd282878b16bdaa6a79dd643d59a905b89499d1ab93195f623190b74d5c66cd5cf4fe36792ceddde8c4c4e0af364b
+  metadata.gz: c9087d1aa92bd0d94baba9181ec26a8d598f5161af28aaa8e587cc2f8a5d7ca474ac056386c062a1aeac9eb9fb33fee27b81f4b8444886180a608b0b6fd4b677
+  data.tar.gz: e2e157259a7ce3a6768751599749dfc668b1be23445d9b1a453f459e5c70e01babcf06d87089f66d581572a987e5733103f7981070bb19c7af156f59308f7374

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.7.0
+
+- Statements as they stood on a date with `financials(as_of:)`, before later filings and restatements, from EDGAR.
+- `Company#filings` from EDGAR's submissions index, as `Filing` objects with the period reported, the document URL and the lag between the two.
+- Earnings releases from FMP as `EarningsRelease`, with `Company#next_earnings` and the EPS surprise.
+- A `Providers::Chain` behind a list of providers, so `provider: [:edgar, :fmp]` reads EDGAR for what it files and FMP for the rest, such as the quarters of a 20-F filer.
+- `Fundamentalista.metrics`, a catalogue of every line item a period resolves, with statement, unit, derivation and whether it is a balance or a flow.
+- The reporting currency comes from the latest filing, so a company that changed currencies is read in the new one.
+
+## 0.6.0
+
+- Derived fourth quarters keep the annual weighted average shares and compute diluted EPS instead of subtracting year to date values; the `:year_to_date` derivation says so on the `Source`.
+- Fourth quarters an older 10-K labels `Q4`, revenue read from the concept the latest filing uses, currency from the statements rather than USD by default, and one currency per company when a filer tags several.
+- Concepts for IFRS depreciation, borrowings, sales of goods, CECL credit provisions, insurance reserves summed from claims and future policy benefits, premiums receivable and reinsurance recoverables.
+- Expenses and outflows as magnitudes whichever sign the filer gave them; `bank?` requires positive net interest income.
+- Dividends per share on the cash flow statement, read from the filing before it is derived.
+- NOPAT on the income statement, ROIC and Greenblatt's return on capital built on it, net working capital without inventory, and a floor on negative working capital.
+- `DCF` rejects missing inputs and earnings power value is `nil` at a zero discount rate; the residual income model grows earnings before charging for the book.
+- `Company#financials` raises `NoFinancialsError` when a filer has no statements, and every error inherits `Fundamentalista::Error`.
+- `Company` and `Source` serialize, `Period#to_h` carries its sources, `Valuation#to_h` carries the price, and `as_json` returns string keys.
+- Companies looked up by CIK, comparisons over trailing twelve months with `period: :ttm`, and one company facts document per company per provider.
+
 ## 0.5.0
 
 - Exchange `Rates` from FMP or your own, and comparisons in one currency that convert amounts and leave ratios alone.

data/README.md

@@ -51,8 +51,12 @@ apple = Fundamentalista.company("AAPL")
 apple = Fundamentalista.company("AAPL", provider: :fmp)
 apple.name   # => "Apple Inc."
 apple.cik    # => 320193
+exxon = Fundamentalista.company(34088)   # a CIK, for registrants the ticker list no longer carries
+ypf = Fundamentalista.company("YPF", provider: [:edgar, :fmp])   # EDGAR first, FMP for what it lacks
 ```
 
+A list of providers is a chain: the company comes from the first one that lists it, and every question goes to the first one with an answer, so a 20-F filer gets its annual statements with provenance from EDGAR and its quarters from FMP. `config.default_provider` takes a list too.
+
 `financials` returns the reporting history as `Financials`, an `Enumerable` of `Period`s ordered newest first. Each `Period` carries its `income`, `balance` and `cash_flow` statements and knows the period before it, which is what average balances, growth and the Piotroski score are built on.
 
 ```ruby
@@ -72,6 +76,8 @@ financials.series(:dividends_paid_per_share)         # any of them per share
 financials.growth(:free_cash_flow_per_share, years: 5)
 ```
 
+`Fundamentalista.metrics` catalogues every line item `metric` resolves, as `Metric` objects with the statement, the unit (`:currency`, `:shares`, `:per_share` or `:rate`), whether the item is reported or derived, and whether it is a balance at a date or a flow over the period, so an application can offer only what the gem can fill in.
+
 ### Quarters and the trailing twelve months
 
 Annual figures go stale for up to a year, so most analysis runs on the trailing twelve months. `financials(period: :quarterly)` returns quarters with their `quarter` number, and `ttm` adds the last four into one `Period` of type `:ttm`: flows summed, the diluted share count averaged, the latest balance sheet kept, and the four quarters before as its `prior`, so ratios on average balances, growth and the Piotroski score all work on it.
@@ -84,7 +90,7 @@ ttm.growth(:revenue)                # against the previous twelve months
 apple.valuation(price: 320, period: ttm).pe
 ```
 
-EDGAR reports quarterly cash flows only year to date, and the fourth quarter only as the annual figure. Fundamentalista reads a quarter directly when the filing has a three month value and derives it otherwise as the difference between two year to date values that share a fiscal year start.
+EDGAR reports quarterly cash flows only year to date, and the fourth quarter only as the annual figure. Fundamentalista reads a quarter directly when the filing has a three month value and derives it otherwise as the difference between two year to date values that share a fiscal year start. Weighted average shares are not additive, so a derived fourth quarter keeps the annual average, and diluted EPS is computed from net income and shares rather than derived.
 
 ### Statements
 
@@ -94,9 +100,9 @@ EDGAR reports quarterly cash flows only year to date, and the fourth quarter onl
 | `BalanceSheet` | cash, short term investments, receivables, inventory, current assets, PP&E, total assets, payables, current liabilities, total liabilities, short and long term debt, total debt, equity, minority interest, retained earnings, shares outstanding | total liabilities, total debt, liquid assets, net debt, working capital, net working capital |
 
 EBIT is operating income when the company reports one, and income before tax plus interest expense otherwise, which is what pharmaceutical and oil companies leave you; interest coverage, EV/EBIT, Greenblatt's yield and return on capital and the Altman Z-score all use it. Figures follow the line as reported: receivables are trade receivables, PP&E excludes lease right-of-use assets, cost of revenue is the company's own line.
-| `CashFlowStatement` | operating cash flow, capital expenditure, free cash flow, dividends paid, share repurchases | free cash flow, shareholder returns |
+| `CashFlowStatement` | operating cash flow, capital expenditure, free cash flow, dividends paid, dividends per share, share repurchases | free cash flow, shareholder returns |
 
-Outflows are positive amounts: `capital_expenditure` is what was spent.
+Outflows are positive amounts whichever sign the filer gave them: `capital_expenditure` is what was spent.
 
 ## Banks
 
@@ -190,7 +196,7 @@ peers.rank(:pe, ascending: true)
 peers.magic_formula
 ```
 
-Tickers the provider cannot resolve are logged and left out, so one bad symbol does not spoil a screen.
+Tickers the provider cannot resolve are logged and left out, so one bad symbol does not spoil a screen. Comparisons read the latest fiscal year; pass `period: :ttm` to compare trailing twelve months instead.
 
 Ratios and multiples compare across currencies as they are; amounts do not. Pass `currency:` and the amounts, revenue, market cap, book value per share and the rest, are converted through exchange `Rates`, fetched from FMP or given by you on EDGAR, while everything that is a rate or a multiple stays untouched.
 
@@ -202,7 +208,7 @@ Fundamentalista.compare("AAPL", "NVO", currency: "USD", provider: :fmp).table(:r
 
 ## Provenance
 
-Every EDGAR line item remembers where it came from. `period.source(:revenue)` returns the XBRL concept, the form and filing date it was read from, and whether the figure was reported as is, summed from split concepts, or derived from year to date values.
+Every EDGAR line item remembers where it came from. `period.source(:revenue)` returns the XBRL concept, the form and filing date it was read from, and whether the figure was reported as is, summed from split concepts, derived from year to date values, or, for a weighted average, carried from the year to date figure.
 
 ```ruby
 year.source(:revenue)
@@ -211,6 +217,19 @@ year.source(:short_term_debt).derivation   # => :summed
 year.sources                                # every item
 ```
 
+EDGAR keeps every value ever filed, so a period can also be read as it stood on a date, before later filings and restatements: `apple.financials(as_of: Date.new(2024, 6, 30))` returns the fiscal years filed by then, with the figures of that time. FMP has no history of its own statements and raises `UnsupportedPeriodError` there.
+
+### Filings and earnings dates
+
+`company.filings` lists the company's SEC filings from the submissions index, newest first, each with its form, filing date, the last day of the period it reports, the accession number and the URL of its primary document. `lag` is the days between the period's end and the filing, which is the company's reporting rhythm: Apple files 34 days after every quarter. `company.earnings` lists earnings releases from FMP, reported and scheduled, with the actual and estimated EPS and revenue, and `next_earnings` is the next one on the calendar.
+
+```ruby
+apple.filings(form: "10-Q").first        # => #<Fundamentalista::Filing form: "10-Q", filed_on: 2026-07-31, period_ended_on: 2026-06-27>
+apple.filings(form: "10-K").map(&:lag)   # => [34, 34, 34, ...]
+apple.next_earnings                      # => #<Fundamentalista::EarningsRelease date: 2026-10-29, eps_estimate: 2.05>  (FMP)
+apple.earnings.last.surprise             # EPS over the estimate, as a rate
+```
+
 ## Valuation
 
 `company.valuation` pairs the latest annual period with a market snapshot: the provider's quote, or a price you pass. EDGAR has no market data, so pass a price there.
@@ -324,11 +343,14 @@ valuation.residual_income_value(cost_of_equity: 0.09, growth: 0.04, years: 10)
 | Prices and beta | No, bring a PriceHistory and a beta | Yes |
 | Revenue segments | No | Yes |
 | Exchange rates | No, bring Rates | Yes |
+| Statements as of a past date | Yes | No |
+| Filings | Yes | No |
+| Earnings dates | No | Yes |
 | Coverage | Companies filing with the SEC, US GAAP and IFRS, in their reporting currency | Global |
 
 EDGAR publishes every value a company ever tagged, restatements included. Fundamentalista reads each line item for the period it describes and keeps the most recently filed value, while the fiscal year label comes from the original filing. Companies tag the same idea under different XBRL concepts, so each line item has an ordered list of concepts in `Providers::Edgar::Tags`, and the first one reported wins. Debt excludes lease obligations, which FMP's `totalDebt` includes.
 
-Foreign filers report under IFRS in 20-F and 40-F filings with their own taxonomy; the same line items map to it, and `Period#currency` says what the figures are in. Quarterly data is a 10-Q affair, so IFRS filers get annual periods.
+Foreign filers report under IFRS in 20-F and 40-F filings with their own taxonomy; the same line items map to it, and `Period#currency` says what the figures are in, `nil` when the filing reports revenue and assets in no currency at all. Filers that tag several currencies, such as a Chinese company reporting in CNY with USD convenience figures, are read in the currency of their latest statements; a company that changed its reporting currency keeps the years in the new one. Quarterly data is a 10-Q affair, so IFRS filers get annual periods.
 
 ### Coverage
 
@@ -341,9 +363,13 @@ The concept map is measured, not guessed. `script/coverage` reads the latest ann
 | diluted EPS, income before tax, interest expense, depreciation and amortization, diluted shares | 5% to 7% |
 | shares outstanding, PP&E, capital expenditure | 11% to 14% |
 
-What is missing beyond that is mostly absent from the filing itself: inventory and cost of revenue at service and financial companies, buybacks and dividends at companies that do none, a classified balance sheet at banks and insurers. Companies with no annual filing yet, such as a fresh listing, raise `NoFinancialsError`.
+What is missing beyond that is mostly absent from the filing itself: inventory and cost of revenue at service and financial companies, buybacks and dividends at companies that do none, a classified balance sheet at banks and insurers. Companies with no annual filing yet, such as a fresh listing, raise `NoFinancialsError` from `financials`.
+
+Every error inherits `Fundamentalista::Error`. Provider errors are typed: `CompanyNotFoundError`, `UnauthorizedError`, `RateLimitError`, `ServerError`, each carrying the HTTP `response`. Transient failures are retried, and EDGAR requests are spaced to the SEC's rate limit.
+
+### Limitations
 
-Provider errors are typed: `CompanyNotFoundError`, `UnauthorizedError`, `RateLimitError`, `ServerError`, each carrying the HTTP `response`. Transient failures are retried, and EDGAR requests are spaced to the SEC's rate limit.
+The figures are as filed. A stock split is restated only in filings made after it, so per share history before the split is in pre-split shares. Companies with several share classes tag the totals per class, so `diluted_shares` and `shares_outstanding` can be missing for them. A company in its first year of filing may label two quarters the same way, and one of them is dropped. Expenses a filer negates, such as a released credit provision, keep their sign.
 
 ### Caching
 

data/lib/fundamentalista/balance_sheet.rb

@@ -40,8 +40,9 @@ module Fundamentalista
 
     # Working capital net of cash and debt: receivables plus inventory minus
     # payables, the operating capital Greenblatt's return on capital uses.
+    # A company with no inventory line has none.
     def net_working_capital
-      Decimal.subtract(Decimal.sum(receivables, inventory), payables)
+      Decimal.subtract(Decimal.sum(receivables, inventory || BigDecimal('0')), payables)
     end
   end
 end

data/lib/fundamentalista/banking.rb

@@ -19,9 +19,11 @@ module Fundamentalista
       new(**summed.to_h, **balances)
     end
 
-    # Whether the company reports net interest income, the mark of a bank.
+    # Whether the company earns net interest income, the mark of a bank;
+    # an insurer or industrial tagging its net interest expense there is
+    # not one.
     def bank?
-      !net_interest_income.nil? && !net_interest_income.zero?
+      !net_interest_income.nil? && net_interest_income.positive?
     end
 
     # Net interest income plus noninterest income, a bank's revenue.

data/lib/fundamentalista/cash_flow_statement.rb

@@ -2,9 +2,11 @@
 
 module Fundamentalista
   # One period of the cash flow statement. Outflows are positive amounts:
-  # +capital_expenditure+ is what was spent, +dividends_paid+ what was paid.
+  # +capital_expenditure+ is what was spent, +dividends_paid+ what was paid,
+  # and +dividends_per_share+ what was declared on each share.
   class CashFlowStatement < Statement
-    field :operating_cash_flow, :capital_expenditure, :free_cash_flow, :dividends_paid, :share_repurchases
+    field :operating_cash_flow, :capital_expenditure, :free_cash_flow, :dividends_paid, :dividends_per_share,
+          :share_repurchases
 
     # Free cash flow, derived from operating cash flow and capital
     # expenditure when not reported.

data/lib/fundamentalista/company.rb

@@ -13,9 +13,13 @@ module Fundamentalista
   #   company.estimate.eps                   # FMP only
   #   company.valuation_history(:pe)         # {2025 => {price:, pe:}, ...}
   #   company.segments(by: :geography).share # FMP only
+  #   company.financials(as_of: Date.new(2024, 6, 30))   # as they stood then, EDGAR only
+  #   company.filings(form: "10-Q").first.filed_on       # EDGAR only
+  #   company.next_earnings.date                         # FMP only
   #
   class Company
     include Inspectable
+    include Serializable
 
     attr_reader :ticker, :name, :cik, :currency, :provider
 
@@ -34,9 +38,14 @@ module Fundamentalista
     end
 
     # Returns the Financials, newest first. +period+ is +:annual+ or
-    # +:quarterly+ and +limit+ the number of periods.
-    def financials(period: :annual, limit: 5)
-      @financials[[period, limit]] ||= provider.financials(self, period: period, limit: limit)
+    # +:quarterly+ and +limit+ the number of periods. Given +as_of+, the
+    # statements read as they stood on that date, before later filings and
+    # restatements, which EDGAR alone can do. Raises NoFinancialsError
+    # when the provider has none, as with a fresh listing.
+    def financials(period: :annual, limit: 5, as_of: nil)
+      @financials[[period, limit, as_of]] ||= provider.financials(self, period: period, limit: limit, as_of: as_of).tap do |found|
+        raise NoFinancialsError, "#{provider.class.slug} has no #{period} statements for #{ticker}" if found.none?
+      end
     end
 
     # Returns the PriceHistory between +from+ and +to+. Raises
@@ -73,6 +82,25 @@ module Fundamentalista
       @segments[by] ||= provider.segments(self, by: by)
     end
 
+    # Returns the company's Filings with the SEC, newest first, or those
+    # of one +form+ such as "10-Q". EDGAR only.
+    def filings(form: nil)
+      @filings ||= provider.filings(self)
+      form ? @filings.select { |filing| filing.form == form } : @filings
+    end
+
+    # Returns the EarningsReleases the provider knows, reported and
+    # scheduled, oldest first. Empty for EDGAR.
+    def earnings
+      @earnings ||= provider.earnings(self).sort_by(&:date)
+    end
+
+    # Returns the next EarningsRelease on or after +after+, today by
+    # default, or +nil+.
+    def next_earnings(after: Date.today)
+      earnings.find { |release| release.date >= after }
+    end
+
     # Returns the trailing twelve months as a Period, built from the last
     # +quarters+ quarterly periods; eight give it a prior period too.
     def ttm(quarters: 8)
@@ -100,7 +128,8 @@ module Fundamentalista
     # Returns the Valuation of the latest annual period at +price+, or at
     # the provider's quote when no price is given, with the next fiscal
     # year's Estimate when the provider has one.
-    def valuation(price: nil, period: latest_period)
+    def valuation(price: nil, period: nil)
+      period ||= latest_period
       Valuation.new(period, price ? Quote.new(price: price) : quote, estimate: estimate(after: period.ended_on))
     end
 
@@ -109,14 +138,17 @@ module Fundamentalista
       latest_period.ratios
     end
 
-    # The latest annual Period. Raises NoFinancialsError when the provider
-    # has no annual statements for the company, as with a fresh listing.
+    # The latest annual Period.
     def latest_period
-      financials.latest || raise(NoFinancialsError, "#{provider.class.slug} has no annual statements for #{ticker}")
+      financials.latest
+    end
+
+    def to_h
+      { ticker: ticker, name: name, cik: cik, currency: currency, beta: beta, provider: provider.class.slug }
     end
 
     def inspect_attributes # :nodoc:
-      { ticker: ticker, name: name, cik: cik, provider: provider.class.slug }
+      to_h.slice(:ticker, :name, :cik, :provider)
     end
   end
 end

data/lib/fundamentalista/comparison.rb

@@ -3,14 +3,16 @@
 module Fundamentalista
   # Several companies side by side: any ratio, valuation figure, score or
   # line item as a table, rankings on any of them, and Greenblatt's magic
-  # formula ranking. With a +currency+, amounts such as revenue or market
-  # cap are converted into it through Rates, while ratios and multiples
-  # stay as they are.
+  # formula ranking, on the latest fiscal year or, with +period: :ttm+, on
+  # the trailing twelve months. With a +currency+, amounts such as revenue
+  # or market cap are converted into it through Rates, while ratios and
+  # multiples stay as they are.
   #
   #   peers = Fundamentalista.compare("AAPL", "MSFT", prices: { "AAPL" => 320, "MSFT" => 500 })
   #   peers.table(:roe, :pe, :piotroski)   # => {"AAPL" => {roe: ..., pe: ..., piotroski: 8}, ...}
   #   peers.rank(:pe, ascending: true)     # => ["MSFT", "AAPL"]
   #   peers.magic_formula                  # => ["AAPL", "MSFT"]
+  #   Fundamentalista.compare("AAPL", "MSFT", period: :ttm).values(:roe)
   #   Fundamentalista.compare("AAPL", "NVO", currency: "USD").values(:revenue)
   #
   class Comparison
@@ -23,13 +25,18 @@ module Fundamentalista
 
     attr_reader :companies
 
+    # +:annual+ for the latest fiscal year, +:ttm+ for the trailing twelve
+    # months.
+    attr_reader :period
+
     # The currency amounts are converted into, or +nil+ to leave each
     # company in its own.
     attr_reader :currency
 
-    def initialize(companies, prices: {}, currency: nil, rates: nil)
+    def initialize(companies, prices: {}, period: :annual, currency: nil, rates: nil)
       @companies = companies.to_h { |company| [company.ticker, company] }
       @prices = prices.transform_keys(&:to_s)
+      @period = period
       @currency = currency
       @rates = rates
     end
@@ -83,7 +90,7 @@ module Fundamentalista
     private
 
     def metric(company, name)
-      period = company.latest_period
+      period = period_of(company)
       valuation = valuation_of(company, period)
       return period.ratios.public_send(name) if Ratios::ALL.include?(name)
       if Valuation::ALL.include?(name)
@@ -94,6 +101,10 @@ module Fundamentalista
       converted(period.metric(name), period, amount: !name.end_with?('shares_outstanding', 'diluted_shares'))
     end
 
+    def period_of(company)
+      period == :ttm ? company.ttm : company.latest_period
+    end
+
     def converted(value, period, amount:)
       return value if value.nil? || !amount || currency.nil? || period.currency == currency
 

data/lib/fundamentalista/configuration.rb

@@ -36,7 +36,8 @@ module Fundamentalista
     # The Financial Modeling Prep API key.
     option :fmp_api_key
 
-    # The provider Fundamentalista.company uses when none is given.
+    # The provider Fundamentalista.company uses when none is given: a
+    # slug, or a list of slugs tried in order.
     option :default_provider, :edgar
 
     # Seconds to wait for a provider response.

data/lib/fundamentalista/dcf.rb

@@ -24,7 +24,9 @@ module Fundamentalista
       @terminal_growth = Decimal.wrap(terminal_growth)
       @years = years
       @fade = fade
+      raise ArgumentError, 'cash_flow, growth and discount_rate are required' if [@cash_flow, @growth, @discount_rate].any?(nil)
       raise ArgumentError, 'discount_rate must exceed terminal_growth' if @discount_rate <= @terminal_growth
+      raise ArgumentError, 'years must be at least 1' if years < 1
     end
 
     # Whether growth fades towards the terminal rate over the projection.

data/lib/fundamentalista/earnings_release.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # One earnings release, past or scheduled: its date, the diluted EPS
+  # and revenue reported, and what analysts expected. A scheduled release
+  # has estimates and no actuals yet.
+  class EarningsRelease
+    include Inspectable
+    include Serializable
+
+    attr_reader :date, :eps, :eps_estimate, :revenue, :revenue_estimate
+
+    def initialize(date:, eps: nil, eps_estimate: nil, revenue: nil, revenue_estimate: nil)
+      @date = date
+      @eps = Decimal.wrap(eps)
+      @eps_estimate = Decimal.wrap(eps_estimate)
+      @revenue = Decimal.wrap(revenue)
+      @revenue_estimate = Decimal.wrap(revenue_estimate)
+    end
+
+    # Whether the results are out.
+    def reported?
+      !eps.nil?
+    end
+
+    # The EPS surprise as a rate over the estimate, or +nil+ before the
+    # release or without an estimate.
+    def surprise
+      eps && eps_estimate && Decimal.ratio(eps - eps_estimate, eps_estimate.abs)
+    end
+
+    def to_h
+      { date: date, eps: eps, eps_estimate: eps_estimate, revenue: revenue, revenue_estimate: revenue_estimate }
+    end
+
+    def inspect_attributes # :nodoc:
+      { date: date, eps: eps, eps_estimate: eps_estimate }
+    end
+  end
+end

data/lib/fundamentalista/error.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Fundamentalista
-  # Base class for errors raised while talking to a data provider. Carries
-  # the HTTP response when there is one.
+  # Base class of every error the gem raises, so one rescue catches them
+  # all. Errors raised while talking to a data provider carry the HTTP
+  # response when there is one.
   class Error < StandardError
     attr_reader :response
 
@@ -12,12 +13,12 @@ module Fundamentalista
     end
   end
 
-  class ConfigurationError < StandardError; end
+  class ConfigurationError < Error; end
   class CompanyNotFoundError < Error; end
   class UnauthorizedError < Error; end
   class RateLimitError < Error; end
   class ServerError < Error; end
-  class UnsupportedPeriodError < StandardError; end
-  class NoFinancialsError < StandardError; end
-  class QuoteUnavailableError < StandardError; end
+  class UnsupportedPeriodError < Error; end
+  class NoFinancialsError < Error; end
+  class QuoteUnavailableError < Error; end
 end

data/lib/fundamentalista/filing.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # One filing with the SEC: its form, the day it was filed, the last day
+  # of the period it reports, its accession number and the URL of its
+  # primary document. The lag between a period's end and its filing is
+  # what a company's reporting rhythm looks like.
+  class Filing
+    include Inspectable
+    include Serializable
+
+    attr_reader :form, :filed_on, :period_ended_on, :accession, :url
+
+    def initialize(form:, filed_on:, accession:, url:, period_ended_on: nil)
+      @form = form
+      @filed_on = filed_on
+      @period_ended_on = period_ended_on
+      @accession = accession
+      @url = url
+    end
+
+    # The days between the end of the period reported and the filing, or
+    # +nil+ for filings that report no period.
+    def lag
+      period_ended_on && (filed_on - period_ended_on).to_i
+    end
+
+    def to_h
+      { form: form, filed_on: filed_on, period_ended_on: period_ended_on, accession: accession, url: url }
+    end
+
+    def inspect_attributes # :nodoc:
+      to_h.slice(:form, :filed_on, :period_ended_on)
+    end
+  end
+end

data/lib/fundamentalista/income_statement.rb

@@ -43,5 +43,13 @@ module Fundamentalista
     def tax_rate
       Decimal.ratio(income_tax, income_before_tax)
     end
+
+    # Net operating profit after tax: EBIT taxed at the effective rate,
+    # held between 0 and 100% so a tax benefit or a loss year does not
+    # inflate it.
+    def nopat
+      rate = tax_rate
+      ebit && rate && (ebit * (1 - rate.clamp(0, 1)))
+    end
   end
 end

data/lib/fundamentalista/metric.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # One line item Period#metric resolves: its name, the statement it lives
+  # on, whether it is reported or derived, its unit, and whether it is a
+  # balance at a date or a flow over a period. The catalogue lets an
+  # application offer only what the gem can fill in.
+  #
+  #   Fundamentalista.metrics.map(&:name)        # => [:revenue, :cost_of_revenue, ...]
+  #   Fundamentalista.metric(:net_debt).instant? # => true
+  #
+  class Metric
+    include Inspectable
+    include Serializable
+
+    STATEMENTS = { income: IncomeStatement, balance: BalanceSheet, cash_flow: CashFlowStatement,
+                   banking: Banking, insurance: Insurance }.freeze
+    INSTANTS = (Banking::INSTANT + Insurance::INSTANT).freeze
+    private_constant :STATEMENTS, :INSTANTS
+
+    class << self
+      # Every metric, reported ones first within each statement.
+      def all
+        @all ||= STATEMENTS.flat_map { |statement, klass| of(statement, klass) }
+                           .push(new(name: :owner_earnings, statement: :period, derived: true))
+                           .uniq(&:name)
+      end
+
+      # The metric called +name+. Raises ArgumentError for a name no
+      # statement reports.
+      def find(name)
+        all.find { |metric| metric.name == name.to_sym } || raise(ArgumentError, "Unknown metric #{name.inspect}")
+      end
+
+      private
+
+      def of(statement, klass)
+        derived = klass.public_instance_methods(false).reject { |method| method.end_with?('?') } - klass.fields
+        klass.fields.map { |name| new(name: name, statement: statement) } +
+          derived.map { |name| new(name: name, statement: statement, derived: true) }
+      end
+    end
+
+    attr_reader :name, :statement
+
+    def initialize(name:, statement:, derived: false)
+      @name = name
+      @statement = statement
+      @derived = derived
+    end
+
+    # Whether the item is computed from others rather than reported.
+    def derived?
+      @derived
+    end
+
+    # +:currency+ for amounts, +:shares+ for share counts, +:per_share+ or
+    # +:rate+.
+    def unit
+      case name
+      when /per_share|\Aeps_/ then :per_share
+      when /shares/ then :shares
+      when /_rate\z|_ratio\z/ then :rate
+      else :currency
+      end
+    end
+
+    # Whether the item is a balance at the period's end rather than a
+    # flow over the period.
+    def instant?
+      statement == :balance || INSTANTS.include?(name)
+    end
+
+    def to_h
+      { name: name, statement: statement, unit: unit, derived: derived?, instant: instant? }
+    end
+
+    alias inspect_attributes to_h
+  end
+end

data/lib/fundamentalista/period.rb

@@ -96,11 +96,11 @@ module Fundamentalista
       earlier && Decimal.cagr(earlier.metric(metric), self.metric(metric), 1)
     end
 
-    # Returns the period and its statements as a Hash.
+    # Returns the period, its statements and its sources as a Hash.
     def to_h
       { fiscal_year: fiscal_year, quarter: quarter, type: type, ended_on: ended_on, currency: currency,
         income: income.to_h, balance: balance.to_h, cash_flow: cash_flow.to_h, banking: banking.to_h,
-        insurance: insurance.to_h }
+        insurance: insurance.to_h, sources: sources.transform_values(&:to_h) }
     end
 
     # The days the period spans, for turning turnover into days.
@@ -137,19 +137,20 @@ module Fundamentalista
     # Returns the line item +name+ from whichever statement reports it, or
     # +nil+. Derived items such as +free_cash_flow+ count, so does
     # +owner_earnings+, and any of them followed by +_per_share+ is divided
-    # by the shares outstanding.
+    # by the shares outstanding, unless a statement reports it per share
+    # already, as with +dividends_per_share+.
     #
     #   period.metric(:revenue)                    # => 0.416161e12
     #   period.metric(:free_cash_flow_per_share)   # => 0.66854e1
     #
     def metric(name)
       return owner_earnings if name == :owner_earnings
-      return per_share(name.to_s.delete_suffix('_per_share').to_sym) if name.end_with?('_per_share')
 
       statement = [income, balance, cash_flow, banking, insurance].find { |candidate| candidate.respond_to?(name) }
-      raise ArgumentError, "Unknown metric #{name.inspect}" unless statement
+      return statement.public_send(name) if statement
+      return per_share(name.to_s.delete_suffix('_per_share').to_sym) if name.end_with?('_per_share')
 
-      statement.public_send(name)
+      raise ArgumentError, "Unknown metric #{name.inspect}"
     end
 
     # Returns +name+ divided by the shares outstanding at the end of the

data/lib/fundamentalista/provider.rb

@@ -3,8 +3,9 @@
 module Fundamentalista
   # The contract every data source implements: resolve a Company, return
   # its Financials, a Quote or +nil+, the analyst Estimates it has, its
-  # PriceHistory and its revenue Segments, and exchange Rates. Subclasses
-  # get an HTTP client with retries and error mapping.
+  # PriceHistory, its revenue Segments, its Filings and EarningsReleases,
+  # and exchange Rates. Subclasses get an HTTP client with retries and
+  # error mapping.
   class Provider
     class << self
       # The symbol the provider is registered under.
@@ -23,7 +24,7 @@ module Fundamentalista
       raise NotImplementedError
     end
 
-    def financials(company, period:, limit:)
+    def financials(company, period:, limit:, as_of: nil)
       raise NotImplementedError
     end
 
@@ -47,6 +48,14 @@ module Fundamentalista
       raise NotImplementedError
     end
 
+    def filings(company)
+      raise NotImplementedError
+    end
+
+    def earnings(company)
+      raise NotImplementedError
+    end
+
     private
 
     def get(url, params = {}, headers: {})