fundamentalista 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eeff95349adcf9312850781f5792f603793c0a104cd49a370d7895eddb9bf334
-  data.tar.gz: 1268d8bd7117f7a874de9d8fd65b51f13d70d2b5b1aae5b106e0426b20b1f852
+  metadata.gz: 157c2e2b5398a2feb0e9c1d80b76b8273909a6d0e7fbd038929d647bb3b3d5e2
+  data.tar.gz: e4a34806e3588dcc4afdb41bf287523fc75500e1d74c13fb4aed7c477690bf6e
 SHA512:
-  metadata.gz: db32e147665acf8f33c7a0d8afe0df06377bd4273b70a33064f077919bf8a7684e06885a17c25b54921578dcf8e66863b921cb481c947e987b2e4181edfa2f2f
-  data.tar.gz: aa1d5c94637e79a7f215b3bf7d0532ca1f6636a8ca5df2c233621b3237af58ac39fcf0664600d5baf5634a6c191378f79a9cf5a87434b3bddfb30e05155a529e
+  metadata.gz: c9087d1aa92bd0d94baba9181ec26a8d598f5161af28aaa8e587cc2f8a5d7ca474ac056386c062a1aeac9eb9fb33fee27b81f4b8444886180a608b0b6fd4b677
+  data.tar.gz: e2e157259a7ce3a6768751599749dfc668b1be23445d9b1a453f459e5c70e01babcf06d87089f66d581572a987e5733103f7981070bb19c7af156f59308f7374

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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`.

data/README.md

@@ -52,8 +52,11 @@ 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
@@ -73,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.
@@ -212,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.
@@ -325,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, `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 own statements. 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
 

data/lib/fundamentalista/company.rb

@@ -13,6 +13,9 @@ 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
@@ -35,11 +38,13 @@ module Fundamentalista
     end
 
     # Returns the Financials, newest first. +period+ is +:annual+ or
-    # +:quarterly+ and +limit+ the number of periods. Raises
-    # NoFinancialsError when the provider has none, as with a fresh listing.
-    def financials(period: :annual, limit: 5)
-      @financials[[period, limit]] ||= provider.financials(self, period: period, limit: limit).tap do |financials|
-        raise NoFinancialsError, "#{provider.class.slug} has no #{period} statements for #{ticker}" if financials.none?
+    # +: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
 
@@ -77,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)

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/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/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/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/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: {})

data/lib/fundamentalista/providers/chain.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  module Providers
+    # Several providers tried in order: a company is resolved by the first
+    # one that lists it, and every question goes to the first one with an
+    # answer. Reading EDGAR for what it files and FMP for the rest, or for
+    # the quarters of a 20-F filer, is one list away.
+    #
+    #   Fundamentalista.company("YPF", provider: [:edgar, :fmp]).financials(period: :quarterly)
+    #
+    class Chain < Provider
+      attr_reader :providers
+
+      def initialize(config, providers)
+        super(config)
+        @providers = providers
+      end
+
+      def company(ticker)
+        found = attempt(:company, ticker)
+        Company.new(**found.to_h.except(:provider), provider: self)
+      end
+
+      %i[financials quote estimates prices segments rates filings earnings].each do |question|
+        define_method(question) { |*args, **options| attempt(question, *args, **options) }
+      end
+
+      private
+
+      def attempt(question, *args, **options)
+        outcome = nil
+        providers.each do |provider|
+          outcome = provider.public_send(question, *args, **options)
+          return outcome unless empty?(outcome)
+        rescue Error, NotImplementedError => e
+          config.logger.debug("#{provider.class.slug} could not answer #{question}: #{e.message}")
+          outcome = e
+        end
+        outcome.is_a?(Exception) ? raise(outcome) : outcome
+      end
+
+      def empty?(outcome)
+        outcome.nil? || (outcome.respond_to?(:none?) && outcome.none?)
+      end
+    end
+  end
+end

data/lib/fundamentalista/providers/edgar/facts.rb

@@ -18,6 +18,9 @@ module Fundamentalista
       # Weighted average share counts do not subtract, so the year to date
       # average stands in for the quarter, and per share earnings are left
       # for the statement to compute from it.
+      #
+      # Given +as_of+, only values filed by that date count, so the
+      # statements read as they stood then.
       class Facts # :nodoc:
         ANNUAL = (350..380)
         QUARTER = (80..100)
@@ -27,19 +30,20 @@ module Fundamentalista
         TAXONOMIES = %w[us-gaap ifrs-full dei].freeze
         CURRENCY = /\A[A-Z]{3}\b/
 
-        def initialize(document)
+        def initialize(document, as_of: nil)
           facts = document.fetch('facts', {})
           @facts = TAXONOMIES.map { |taxonomy| facts.fetch(taxonomy, {}) }
+          @as_of = as_of&.iso8601
         end
 
         # The ISO code of the currency revenue, or failing that the balance
-        # sheet, is reported in; +nil+ when the document says nothing.
+        # sheet, was last reported in, so a company that changed its
+        # reporting currency is read in the new one; +nil+ when the
+        # document says nothing.
         def currency
           return @currency if defined?(@currency)
 
-          @currency = (Tags::INCOME[:revenue] + ['Assets']).lazy.filter_map do |concept|
-            units(concept).keys.find { |unit| unit.match?(/\A[A-Z]{3}\z/) }
-          end.first
+          @currency = (Tags::INCOME[:revenue] + ['Assets']).lazy.filter_map { |concept| latest_currency(concept) }.first
         end
 
         # The fiscal years on file, newest first, as [year, ended_on] pairs.
@@ -176,8 +180,19 @@ module Fundamentalista
           (Date.parse(entry['end']) - Date.parse(entry['start'])).to_i
         end
 
+        def latest_currency(concept)
+          units(concept).filter_map do |unit, entries|
+            last = filed(entries).max_by { |entry| entry['filed'] }
+            [unit, last['filed']] if last && unit.match?(/\A[A-Z]{3}\z/)
+          end.max_by(&:last)&.first
+        end
+
         def entries(concept)
-          units(concept).select { |unit, _| !unit.match?(CURRENCY) || unit.start_with?(currency.to_s) }.values.flatten
+          filed(units(concept).select { |unit, _| !unit.match?(CURRENCY) || unit.start_with?(currency.to_s) }.values.flatten)
+        end
+
+        def filed(entries)
+          entries.select { |entry| @as_of.nil? || entry['filed'] <= @as_of }
         end
 
         def units(concept)

data/lib/fundamentalista/providers/edgar.rb

@@ -8,12 +8,15 @@ module Fundamentalista
     # filings and quarterly ones from 10-Q filings, with fourth quarters
     # derived from the annual figures; foreign filers reporting under IFRS
     # in 20-F and 40-F filings get their annual periods in their own
-    # currency. It has no market data, so quotes come from the price you
-    # pass to Company#valuation. Requests are spaced to respect the SEC's
-    # rate limit, see Configuration#edgar_requests_per_second.
+    # currency, and any period can be read as it stood on a date. It has
+    # no market data, so quotes come from the price you pass to
+    # Company#valuation. Requests are spaced to respect the SEC's rate
+    # limit, see Configuration#edgar_requests_per_second.
     class Edgar < Provider
       TICKERS_URL = 'https://www.sec.gov/files/company_tickers.json'
       FACTS_URL = 'https://data.sec.gov/api/xbrl/companyfacts/CIK%010d.json'
+      SUBMISSIONS_URL = 'https://data.sec.gov/submissions/CIK%010d.json'
+      DOCUMENT_URL = 'https://www.sec.gov/Archives/edgar/data/%d/%s/%s'
 
       # Resolves a ticker, or a CIK given as digits for registrants the
       # ticker list no longer carries, such as the predecessor of a company
@@ -26,8 +29,8 @@ module Fundamentalista
         Company.new(ticker: entry['ticker'], name: entry['title'], cik: entry['cik_str'], provider: self)
       end
 
-      def financials(company, period: :annual, limit: 5)
-        facts = Facts.new(company_facts(company))
+      def financials(company, period: :annual, limit: 5, as_of: nil)
+        facts = Facts.new(company_facts(company), as_of: as_of)
         @currency = facts.currency
         periods = case period
                   when :annual then facts.fiscal_years.first(limit).map { |year, ended_on| annual_period(facts, year, ended_on) }
@@ -45,6 +48,23 @@ module Fundamentalista
         []
       end
 
+      def earnings(_company)
+        []
+      end
+
+      # The filings in the submissions index, newest first: the last
+      # thousand, which reach back a decade or more of 10-K and 10-Q.
+      def filings(company)
+        recent = get(format(SUBMISSIONS_URL, company.cik), headers: headers).dig('filings', 'recent')
+        recent['form'].each_index.map do |index|
+          accession = recent['accessionNumber'][index]
+          reported = recent['reportDate'][index]
+          Filing.new(form: recent['form'][index], filed_on: Date.parse(recent['filingDate'][index]),
+                     period_ended_on: reported.to_s.empty? ? nil : Date.parse(reported), accession: accession,
+                     url: format(DOCUMENT_URL, company.cik, accession.delete('-'), recent['primaryDocument'][index]))
+        end
+      end
+
       def prices(company, **)
         raise QuoteUnavailableError, "EDGAR has no prices for #{company.ticker}; pass a PriceHistory"
       end

data/lib/fundamentalista/providers/fmp.rb

@@ -4,8 +4,8 @@ module Fundamentalista
   module Providers
     # Financial Modeling Prep. Needs Configuration#fmp_api_key. Serves
     # annual and quarterly periods, company profiles with beta, live
-    # quotes, analyst estimates, daily prices, revenue segments and
-    # exchange rates.
+    # quotes, analyst estimates, earnings releases, daily prices, revenue
+    # segments and exchange rates.
     class FMP < Provider
       BASE_URL = 'https://financialmodelingprep.com/stable/'
 
@@ -17,7 +17,9 @@ module Fundamentalista
                     currency: profile['currency'], beta: profile['beta'], provider: self)
       end
 
-      def financials(company, period: :annual, limit: 5)
+      def financials(company, period: :annual, limit: 5, as_of: nil)
+        raise UnsupportedPeriodError, 'FMP serves statements as they stand today; as_of: needs EDGAR' if as_of
+
         params = { symbol: company.ticker, period: period == :quarterly ? 'quarter' : 'annual', limit: limit }
         statements = %w[income-statement balance-sheet-statement cash-flow-statement].map do |endpoint|
           by_date(fetch(endpoint, params))
@@ -64,6 +66,14 @@ module Fundamentalista
         end
       end
 
+      # The last dozen earnings releases, scheduled ones included.
+      def earnings(company)
+        fetch('earnings', symbol: company.ticker, limit: 12).map do |row|
+          EarningsRelease.new(date: Date.parse(row['date']), eps: row['epsActual'], eps_estimate: row['epsEstimated'],
+                              revenue: row['revenueActual'], revenue_estimate: row['revenueEstimated'])
+        end
+      end
+
       private
 
       def build_period(date, income, balance, cash_flow)

data/lib/fundamentalista/version.rb

@@ -2,5 +2,5 @@
 
 module Fundamentalista
   # The version of the fundamentalista gem, as a string.
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

data/lib/fundamentalista.rb

@@ -29,8 +29,9 @@ loader.setup
 #
 module Fundamentalista
   class << self
-    # Returns the Company behind +ticker+, resolved through +provider+
-    # (+:edgar+ or +:fmp+, defaulting to the configured provider).
+    # Returns the Company behind +ticker+, resolved through +provider+:
+    # +:edgar+, +:fmp+, or a list of them tried in order, defaulting to
+    # the configured provider.
     def company(ticker, provider: config.default_provider)
       provider(provider).company(ticker)
     end
@@ -51,14 +52,27 @@ module Fundamentalista
       Comparison.new(companies, prices: prices, period: period, currency: currency, rates: rates)
     end
 
-    # Returns an instance of the provider registered under +slug+.
+    # Returns an instance of the provider registered under +slug+, or a
+    # Providers::Chain of them when given a list.
     def provider(slug)
+      return Providers::Chain.new(config, slug.map { |each| provider(each) }) if slug.is_a?(Array)
+
       klass = providers.fetch(slug.to_sym) do
         raise ConfigurationError, "Unknown provider #{slug.inspect}. Known providers: #{providers.keys.join(', ')}"
       end
       klass.new(config)
     end
 
+    # Every line item a Period resolves, as Metric objects.
+    def metrics
+      Metric.all
+    end
+
+    # The Metric called +name+.
+    def metric(name)
+      Metric.find(name)
+    end
+
     # The registered providers, keyed by slug.
     def providers
       @providers ||= { edgar: Providers::Edgar, fmp: Providers::FMP }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fundamentalista
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Bruno Costanzo
@@ -87,15 +87,19 @@ files:
 - lib/fundamentalista/configuration.rb
 - lib/fundamentalista/dcf.rb
 - lib/fundamentalista/decimal.rb
+- lib/fundamentalista/earnings_release.rb
 - lib/fundamentalista/error.rb
 - lib/fundamentalista/estimate.rb
+- lib/fundamentalista/filing.rb
 - lib/fundamentalista/financials.rb
 - lib/fundamentalista/income_statement.rb
 - lib/fundamentalista/inspectable.rb
 - lib/fundamentalista/insurance.rb
+- lib/fundamentalista/metric.rb
 - lib/fundamentalista/period.rb
 - lib/fundamentalista/price_history.rb
 - lib/fundamentalista/provider.rb
+- lib/fundamentalista/providers/chain.rb
 - lib/fundamentalista/providers/edgar.rb
 - lib/fundamentalista/providers/edgar/facts.rb
 - lib/fundamentalista/providers/edgar/tags.rb