market_data 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b63212c9e8ada21f198021bc3537392d9a6a34933682ebe789923883c2f38131
-  data.tar.gz: 9afa24ef746a81f115628f65aff4bccfdbfbf3086887444d62409545be76b7fb
+  metadata.gz: c83d3644178f120e069d283ebfc132d543ac8dbe2aca9734388d2cd56274bf7c
+  data.tar.gz: eeef52d93f45e64b4869749bd787b0af576924a0b617e8897c4eada6dcf813b2
 SHA512:
-  metadata.gz: e21e172593fcee9340de7ca5ac37373db2d07479e2c912c01d7bf05399e012edcf405caf12c2cbf3ad0545b4ae8a166d6c98f40f67367e60040f818356866666
-  data.tar.gz: a3fcd6d6368c073621e9f400be5412b82e88ada5cce2b00a26b4e6697b97b6beb568564f64032c6c8eb777db93fe7afa3f324c616465e2913b838fd02ffa3eed
+  metadata.gz: b01a71a756244d6461e19cad34abb3b25df2705b43e03e47a936a66a471879f8ae0038e49ab01f062ec0db4c046e40e2d80d3162a5c065f535ffa7877efed548
+  data.tar.gz: fe1a289aa65eb0e6a0682b9e263a232f0eb2b913a808b9c6ac5271e46b52123a4c805a586bc5b2a1b9aeda92c17fb640815e6230907a9dcf6a0c5379bcd34b59

data/CHANGELOG.md

@@ -24,4 +24,9 @@
 ## [0.2.1] - 2024-10-09
 
 - Fix broken tests
-- Add support for new optional parameters for `quotes` and `bulk_quotes` endpoint
+- Add support for new optional parameters for `quotes` and `bulk_quotes` endpoint
+
+## [0.3.0] - 2024-10-09
+
+- Add support for Earnings endpoint under the `earnings` method
+- Introduced `Validations` module for parameter validation logic

data/README.md

@@ -2,12 +2,11 @@
 
 A Ruby wrapper for the [MarketData API](https://www.marketdata.app/docs/api).
 
-![coverage](https://img.shields.io/badge/coverage%3A-84.71%25-yellow.svg)
+![coverage](https://img.shields.io/badge/coverage%3A-87.77%25-yellow.svg)
 
 ## Installation
 
     $ gem install market_data
-    $ bundle install
 
 ## Usage
 
@@ -93,7 +92,7 @@ For the `bulk_candles` method you pass a array of ticker symbols. Resolution is
 
 It returns a hashmap with the ticker symbol as a key.
 
-        $ candles = cl.bulk_candles(["AAPL", "AMD", "NOTAQUOTE"])
+        $ candles = client.bulk_candles(["AAPL", "AMD", "NOTAQUOTE"])
 
         $ candles["AMD"]
         $ => #<struct MarketData::Models::Candle symbol="AMD", open=174.05, high=174.05, low=169.55, close=171.02, volume=33391035, time=1728446400>
@@ -103,6 +102,30 @@ It returns a hashmap with the ticker symbol as a key.
 
 If a quote is not found, the hashmap will return a nil value for that ticker's key.
 
+### Earnings
+
+See the API [docs](https://www.marketdata.app/docs/api/stocks/earnings) for parameter specification.
+
+        $ client.earnings("AAPL", from: (Time.now - MarketData::Constants::YEAR).iso8601, to: Time.now.iso8601, countback: nil, report: nil, date: nil)
+        $ => [#<struct MarketData::Models::Earning
+            symbol="AAPL",
+            fiscal_year=2023,
+            fiscal_quarter=4,
+            date=1696046400,
+            report_date=1698897600,
+            report_time="after close",
+            currency="USD",
+            reported_eps=1.46,
+            estimated_eps=1.39,
+            surprise_eps=0.07,
+            surprise_eps_pct=0.0504,
+            updated=1728273600>,
+            #<struct MarketData::Models::Earning
+            symbol="AAPL",
+            fiscal_year=2024,
+            fiscal_quarter=1,
+            ...
+
 ## ROADMAP
 
 The following is an ordered list of next expected developments, based on the endpoints present in the [docs](https://www.marketdata.app/docs/api)
@@ -113,7 +136,7 @@ From Stocks endpoints:
 - [X] Candles
 - [X] Bulk Candles
 - [X] Support for new optional parameters for Quotes and Bulk Quotes
-- [ ] Earnings
+- [X] Earnings
 
 From Markets endpoints:
 - [ ] Status

data/lib/market_data/constants.rb

@@ -5,9 +5,47 @@ module MarketData
     HOUR = MINUTE * 60
     DAY = HOUR * 24
     WEEK = DAY * 7
+    MONTH_30 = DAY * 30
+    MONTH_31 = DAY * 31
     YEAR = DAY * 365
 
-    QUOTE_FIELDS = [:symbol, :ask, :askSize, :bid, :bidSize, :mid, :last, :change, :changepct, :volume, :updated, :high52, :low52]
-    CANDLE_FIELDS = [:symbol, :open, :high, :low, :close, :volume, :time]
+    EARNING_FIELD_MAPPING = {
+      symbol: "symbol",
+      fiscal_year: "fiscalYear",
+      fiscal_quarter: "fiscalQuarter",
+      date: "date",
+      report_date: "reportDate",
+      report_time: "reportTime",
+      currency: "currency",
+      reported_eps: "reportedEPS",
+      estimated_eps: "estimatedEPS",
+      surprise_eps: "surpriseEPS",
+      surprise_eps_pct: "surpriseEPSpct",
+      updated: "updated"
+    }
+    CANDLE_FIELD_MAPPING = {
+      symbol: "symbol",
+      open: "o",
+      close: "c",
+      low: "l",
+      high: "h",
+      volume: "v",
+      time: "t",
+    }
+    QUOTE_FIELD_MAPPING = {
+      symbol: "symbol",
+      ask: "ask",
+      ask_size: "askSize",
+      bid: "bid",
+      bid_size: "bidSize",
+      mid: "mid",
+      last: "last",
+      change: "change",
+      change_pct: "changepct",
+      volume: "volume",
+      updated: "updated",
+      high52: "high52",
+      low52: "low52",
+    }
   end
 end

data/lib/market_data/mappers.rb

@@ -3,32 +3,16 @@ require 'market_data/models'
 module MarketData
   module Mappers
     include MarketData::Models
-
     SYMBOL_RESPONSE_KEY = "symbol"
     STATUS_RESPONSE_KEY = "s"
 
     def map_quote response, i=0
-      Quote.new(
-        symbol: response["symbol"][i],
-        ask: response["ask"][i],
-        askSize: response["askSize"][i],
-        bid: response["bid"][i],
-        bidSize: response["bidSize"][i],
-        mid: response["mid"][i],
-        last: response["last"][i],
-        change: response["change"][i],
-        changepct: response["changepct"][i],
-        volume: response["volume"][i],
-        updated: response["updated"][i],
-        high52: response.fetch("high52", nil),
-        low52: response.fetch("low52", nil),
-      )
+      Quote.new(**map_fields_for(response, :quote, i))
     end
 
     def map_bulk_quotes response
       h = Hash.new
-      size = response[SYMBOL_RESPONSE_KEY].size
-      for i in 0..(size - 1) do
+      (0..(response[SYMBOL_RESPONSE_KEY].size - 1)).each do |i|
         qquote = map_quote(response, i)
         h[response[SYMBOL_RESPONSE_KEY][i]] = !qquote.blank? ? qquote : nil
       end
@@ -37,31 +21,50 @@ module MarketData
 
     def map_candles response, symbol
       ar = []
-      size = response["o"].size
-    
-      for i in 0..(size - 1) do
-        ar << Candle.new(
-          open: response["o"][i],
-          high: response["h"][i],
-          low: response["l"][i],
-          close: response["c"][i],
-          volume: response["v"][i],
-          time: response["t"][i],
-          symbol: symbol
-        )
+      (0..(response["o"].size - 1)).each do |i|
+        args = map_fields_for(response, :candle, i)
+        args[:symbol] = symbol
+        ar << Candle.new(**args)
       end
+    
       ar
     end
 
     def map_bulk_candles response
       h = Hash.new
-      size = response[SYMBOL_RESPONSE_KEY].size
-    
-      for i in 0..(size - 1) do
-        candle = Candle.new(symbol: response["symbol"][i], open: response["o"][i], high: response["h"][i], low: response["l"][i], close: response["c"][i], volume: response["v"][i], time: response["t"][i])
+      (0..(response[SYMBOL_RESPONSE_KEY].size - 1)).each do |i|
+        candle = Candle.new(**map_fields_for(response, :candle, i))
         h[response[SYMBOL_RESPONSE_KEY][i]] = !candle.blank? ? candle : nil
       end
       h
     end
+
+    def map_earning response
+      ar = []
+      (0..(response[SYMBOL_RESPONSE_KEY].size - 1)).each do |i|
+        ar << Earning.new(**map_fields_for(response, :earning, i))
+      end
+      ar
+    end
+
+    def map_fields_for(response, kind, i=0)
+      mapping = {}
+      case kind
+      when :candle
+        mapping = Constants::CANDLE_FIELD_MAPPING
+      when :earning
+        mapping = Constants::EARNING_FIELD_MAPPING
+      when :quote
+        mapping = Constants::QUOTE_FIELD_MAPPING
+      else
+        raise BadParameterError.new("unrecognized model for mapping: #{kind}")
+      end
+      
+      r = {}
+      mapping.each do |field, mapped|
+        r.store(field, response.fetch(mapped, nil).nil? ? nil : response.fetch(mapped)[i])
+      end
+      r
+    end
   end
 end

data/lib/market_data/models.rb

@@ -2,18 +2,18 @@ require 'market_data/constants'
 
 module MarketData
   module Models
-    include MarketData::Constants
-
-    Quote = Struct.new(*Constants::QUOTE_FIELDS) do
+    Quote = Struct.new(*Constants::QUOTE_FIELD_MAPPING.keys) do
       def blank?
-        (QUOTE_FIELDS - [:symbol]).all? { |mmethod| self[mmethod].nil?}
+        (Constants::QUOTE_FIELD_MAPPING.keys - [:symbol]).all? { |mmethod| self[mmethod].nil?}
       end
     end
 
-    Candle = Struct.new(*Constants::CANDLE_FIELDS) do
+    Candle = Struct.new(*Constants::CANDLE_FIELD_MAPPING.keys) do
       def blank?
-        (CANDLE_FIELDS - [:symbol]).all? { |mmethod| self[mmethod].nil?}
+        (Constants::CANDLE_FIELD_MAPPING.keys - [:symbol]).all? { |mmethod| self[mmethod].nil?}
       end
     end
+
+    Earning = Struct.new(*Constants::EARNING_FIELD_MAPPING.keys)
   end
 end

data/lib/market_data/quotes.rb

@@ -1,53 +1,38 @@
 require 'market_data/conn'
 require 'market_data/errors'
 require 'market_data/mappers'
+require 'market_data/validations'
 
 module MarketData
   module Quotes
     include MarketData::Mappers
     include MarketData::Errors
     include MarketData::Conn
+    include MarketData::Validations
 
     @@single = "/v1/stocks/quotes/"
     @@bulk = "/v1/stocks/bulkquotes/"
     @@candles = "/v1/stocks/candles/"
     @@bulk_candles = "/v1/stocks/bulkcandles/"
+    @@earnings = "/v1/stocks/earnings/"
 
     def quote(symbol, w52 = false, extended = false)
+      query = validate_quotes_input!(symbol: symbol, w52: w52, extended: extended)
+      
       path_hash = { host: MarketData.base_host, path: @@single + symbol }
-      query_hash = {}
-      if w52
-        query_hash["52week"] = true
-      end
-      # MarketData API considers extended as true by default
-      if !extended
-        query_hash[:extended] = false
-      end
-      if !query_hash.empty?
-        path_hash[:query] = URI.encode_www_form(query_hash)
+      if !query.empty?
+        path_hash[:query] = URI.encode_www_form(query)
       end
+      
       res = do_connect(get_uri path_hash)
       map_quote(res)
     end
 
     def bulk_quotes(symbols, snapshot = false, extended = false)
-      path_hash = { host: MarketData.base_host, path: @@bulk  }
-      query_hash = {}
+      query = validate_bulk_quotes_input!(symbols: symbols, snapshot: snapshot, extended: extended)
       
-      # MarketData API considers extended as true by default
-      if !extended
-        query_hash[:extended] = false
-      end
-
-      if snapshot
-        query_hash[:snapshot] = true
-      else
-        if !symbols.is_a?(Array) || symbols.size < 1
-          raise BadParameterError.new("symbols must be a non-empty list")
-        end
-        query_hash[:symbols] = symbols.join(",")
-      end
-      path_hash[:query] = URI.encode_www_form(query_hash)
+      path_hash = { host: MarketData.base_host, path: @@bulk  }
+      path_hash[:query] = URI.encode_www_form(query)
 
       res = do_connect(get_uri path_hash)
       map_bulk_quotes res
@@ -56,43 +41,33 @@ module MarketData
     def candles(symbol, opts = {})
       defaults = {resolution: "D", from: nil, to: Time.now.utc.to_i, countback: nil}
       opts = defaults.merge(opts)
-      
-      query_hash = {to: opts[:to]}
-    
-      # TODO Move method validations into own class
-      # TODO check to is either iso8601 or unix
-      if opts[:from].nil? && opts[:countback].nil?
-        raise BadParameterError.new("either :from or :countback must be supplied")
-      end
-
-      if opts[:from].nil?
-        query_hash[:countback] = opts[:countback]
-      else
-        query_hash[:from] = opts[:from]
-      end
+      query =  validate_candles_input!(**opts)
       
       path_hash = { host: MarketData.base_host, path: @@candles + opts[:resolution] + "/" + symbol }
-      path_hash[:query] = URI.encode_www_form(query_hash)
+      path_hash[:query] = URI.encode_www_form(query)
       
       res = do_connect(get_uri path_hash)
       map_candles res, symbol
     end
 
     def bulk_candles(symbols, resolution = "D")
-      unless resolution == "daily" || resolution == "1D" || resolution == "D"
-        raise BadParameterError.new("only daily resolution is allowed for this endpoint")
-      end
+      query = validate_bulk_candles_input!(symbols: symbols, resolution: resolution)
+      query = query.except(:resolution)
+      
       path_hash = { host: MarketData.base_host, path: @@bulk_candles + resolution + "/" }
+      path_hash[:query] = URI.encode_www_form(query)
       
-      if !symbols.is_a?(Array) || symbols.size < 1
-        raise BadParameterError.new("symbols must be a non-empty list")
-      end
-      query_hash = { symbols: symbols.join(",") }
+      res = do_connect(get_uri path_hash)
+      map_bulk_candles res
+    end
 
-      path_hash[:query] = URI.encode_www_form(query_hash)
+    def earnings(symbol, opts = {from: nil, to: nil, countback: nil, date: nil, report: nil})
+      path_hash = { host: MarketData.base_host(), path: @@earnings + symbol}
+      query = validate_earnings_input!(**opts)
+      path_hash[:query] = URI.encode_www_form(query)
 
       res = do_connect(get_uri path_hash)
-      map_bulk_candles res
+      map_earning res
     end
   end
 end

data/lib/market_data/validations.rb

@@ -0,0 +1,128 @@
+require 'date'
+
+module MarketData
+  module Validations
+    include MarketData::Errors
+    
+    VALID_DAILY_RESOLUTION = ['daily', 'D', '1D', '2D', '3D', '4D', '5D']
+    VALID_RESOLUTIONS = [
+      *VALID_DAILY_RESOLUTION,
+      'weekly', 'W', '1W', '2W', '3W', '4W', '5W',
+      'monthly', 'M', '1M', '2M', '3M', '4M', '5M',
+      'yearly', 'Y', '1Y', '2Y', '3Y', '4Y', '5Y',
+    ]
+
+    def validate_quotes_input!(symbol: nil, w52: nil, extended: nil)
+      result = {}
+    
+      if w52
+        result.merge!({"52week" => true})
+      end
+      # MarketData API considers extended as true by default. Should be included
+      # in the query when false
+      if !extended
+        result.merge!({extended: false})
+      end
+      
+      result
+    end
+    
+    def validate_bulk_quotes_input!(symbols: nil, snapshot: nil, extended: nil)
+      result = {extended: false}
+      if snapshot
+        result.merge!({snapshot: true})
+      else
+        if !symbols.kind_of?(Array) || symbols.size < 2
+          raise BadParameterError.new("symbols must be list with at least 2 symbols")
+        end
+        result.merge!({symbols: symbols.join(",")})
+      end
+      if extended
+        result.merge!({extended: true})
+      end
+      
+      result
+    end
+
+    def validate_bulk_candles_input!(resolution: nil, symbols: nil)
+      s, r = validate_resolution(resolution, VALID_DAILY_RESOLUTION)
+      if s == :invalid
+        raise BadParameterError.new(r)
+      end
+      if !symbols.kind_of?(Array) || symbols.size < 2
+        raise BadParameterError.new("symbols must be list with at least 2 symbols")
+      end
+
+      r.merge({symbols: symbols.join(",")})
+    end
+
+    def validate_candles_input!(
+      resolution: nil, from: nil, to: nil, countback: nil
+    )
+
+      state, response = validate_from_to_countback_strategy(from: from, to: to, countback: countback)
+      if state == :invalid
+        raise BadParameterError.new(response)
+      end
+
+      state, res = validate_resolution(resolution)
+      if state == :invalid
+        raise BadParameterError.new(res)
+      end
+
+      response.merge(res)
+    end
+    
+    def validate_earnings_input!(
+      from: nil, to: nil, countback: nil, date: nil, report: nil
+    )
+      if !date.nil?
+        return {date: date}
+      end
+      if !report.nil?
+        return {report: report}
+      end
+      
+      state, response = validate_from_to_countback_strategy(from: from, to: to, countback: countback)
+      if state == :invalid
+        raise BadParameterError.new(response)
+      end
+
+      return response
+    end
+
+    def validate_from_to_countback_strategy(
+      from: nil, to: nil, countback: nil
+    )
+      if !from.nil? && !to.nil?
+        return :valid, {from: from, to: to}
+      end
+      if !to.nil? && !countback.nil? && from.nil?
+        return :valid, {to: to, countback: countback}
+      end
+      
+      return :invalid, "supply either :from and :to, or :to and :countback"
+    end
+
+    def validate_resolution resolution, allowed_values = VALID_RESOLUTIONS
+      if VALID_RESOLUTIONS.include? resolution
+        return :valid, {resolution: resolution}
+      end
+      return :invalid, "invalid resolution: #{resolution}"
+    end
+    
+    def time_valid?(t)
+      if t.kind_of?(String)
+        begin
+          DateTime.iso8601(t)
+          return true
+        rescue
+          return false
+        end
+      end
+      if t.kind_of?(Integer)
+        return t > 0
+      end
+    end
+  end
+end

data/lib/market_data/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MarketData
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: market_data
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Sebastián González
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-09 00:00:00.000000000 Z
+date: 2024-10-11 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby client for the MarketData API.
 email:
@@ -31,6 +31,7 @@ files:
 - lib/market_data/mappers.rb
 - lib/market_data/models.rb
 - lib/market_data/quotes.rb
+- lib/market_data/validations.rb
 - lib/market_data/version.rb
 - market_data.gemspec
 - sig/market_data.rbs