eodhd 0.19.5

data/lib/Eodhd/Fundamentals.rb

@@ -0,0 +1,92 @@
+# Eodhd/Fundamentals.rb
+# Eodhd::Fundamentals
+
+require_relative './Fundamentals/AnalystRatings'
+require_relative './Fundamentals/Earnings'
+require_relative './Fundamentals/ESGScores'
+require_relative './Fundamentals/Financials'
+require_relative './Fundamentals/General'
+require_relative './Fundamentals/Highlights'
+require_relative './Fundamentals/Holders'
+require_relative './Fundamentals/InsiderTransaction'
+require_relative './Fundamentals/OutstandingShares'
+require_relative './Fundamentals/SharesStats'
+require_relative './Fundamentals/SplitsDividends'
+require_relative './Fundamentals/Technicals'
+require_relative './Fundamentals/Valuation'
+
+class Eodhd
+  class Fundamentals
+    class << self
+      def all(client: nil, api_token: nil, exchange_code:, symbol:, filter: nil)
+        load(client: client, api_token: api_token, exchange_code: exchange_code, symbol: symbol, filter: filter)
+      end
+
+      private
+
+      def load(client: nil, api_token: nil, exchange_code:, symbol:, filter:)
+        client ||= Client.new(api_token: api_token)
+        response = client.fundamentals(exchange_code: exchange_code, symbol: symbol, filter: filter)
+        self.new(
+          exchange_code: exchange_code,
+          symbol: symbol,
+          general: response['General'],
+          highlights: response['Highlights'],
+          valuation: response['Valuation'],
+          shares_stats: response['SharesStats'],
+          technicals: response['Technicals'],
+          splits_dividends: response['SplitsDividends'],
+          analyst_ratings: response['AnalystRatings'],
+          holders: response['Holders'],
+          insider_transactions: response['InsiderTransactions'],
+          esg_scores: response['ESGScores'],
+          outstanding_shares: response['outstandingShares'],
+          earnings: response['Earnings'],
+          financials: response['Financials']
+        )
+      end
+    end # class << self
+
+    attr_reader\
+      :exchange_code,
+      :symbol,
+      :general,
+      :highlights,
+      :valuation,
+      :shares_stats,
+      :technicals,
+      :splits_dividends,
+      :analyst_ratings,
+      :holders,
+      :insider_transactions,
+      :esg_scores,
+      :outstanding_shares,
+      :earnings,
+      :financials
+
+    private
+
+    def initialize(exchange_code:, symbol:, general:, highlights:, valuation:, shares_stats:, technicals:, splits_dividends:, analyst_ratings:, holders:, insider_transactions:, esg_scores:, outstanding_shares:, earnings:, financials:)
+      @exchange_code = exchange_code
+      @symbol = symbol
+      @general = General.new(general) if general
+      @highlights = Highlights.new(highlights) if highlights
+      @valuation = Valuation.new(valuation) if valuation
+      @shares_stats = SharesStats.new(shares_stats) if shares_stats
+      @technicals = Technicals.new(technicals) if technicals
+      @splits_dividends = SplitsDividends.new(splits_dividends) if splits_dividends
+      @analyst_ratings = AnalystRatings.new(analyst_ratings) if analyst_ratings
+      @holders = Holders.new(holders) if holders
+      @insider_transactions = wrap_insider_transactions(insider_transactions)
+      @esg_scores = ESGScores.new(esg_scores) if esg_scores
+      @outstanding_shares = OutstandingShares.new(outstanding_shares) if outstanding_shares
+      @earnings = Earnings.new(earnings) if earnings
+      @financials = Financials.new(financials) if financials
+    end
+
+    def wrap_insider_transactions(entries)
+      return [] unless entries
+      entries.values.map{|entry| InsiderTransaction.new(entry)}.sort_by(&:date)
+    end
+  end
+end

data/lib/Eodhd/Intraday.rb

@@ -0,0 +1,76 @@
+# Eodhd/Intraday.rb
+# Eodhd::Intraday
+
+class Eodhd
+  class Intraday
+    class << self
+      def all(client: nil, api_token: nil, exchange_code: 'US', symbol:, interval:, from: nil, to: nil)
+        load(
+          client: client,
+          api_token: api_token,
+          exchange_code: exchange_code,
+          symbol: symbol,
+          interval: interval,
+          from: from,
+          to: to
+        )
+      end
+
+      private
+
+      def load(client: nil, api_token: nil, exchange_code: 'US', symbol:, interval:, from:, to:)
+        client ||= Client.new(api_token: api_token)
+        client.intraday(
+          exchange_code: exchange_code,
+          symbol: symbol,
+          interval: interval,
+          from: from,
+          to: to
+        ).collect do |intraday_data|
+          self.new(
+            exchange_code: exchange_code,
+            symbol: symbol,
+            interval: interval,
+            timestamp: intraday_data['timestamp'],
+            gmtoffset: intraday_data['gmtoffset'],
+            datetime: intraday_data['datetime'],
+            open: intraday_data['open'],
+            high: intraday_data['high'],
+            low: intraday_data['low'],
+            close: intraday_data['close'],
+            volume: intraday_data['volume']
+          )
+        end
+      end
+    end # class << self
+
+    attr_reader\
+      :exchange_code,
+      :symbol,
+      :interval,
+      :timestamp,
+      :gmtoffset,
+      :datetime,
+      :open,
+      :high,
+      :low,
+      :close,
+      :volume
+
+    private
+
+    def initialize(exchange_code:, symbol:, interval:, timestamp:, gmtoffset:, datetime:, open:, high:, low:, close:, volume:)
+      @exchange_code = exchange_code
+      @symbol = symbol
+      @interval = interval
+      @timestamp = timestamp
+      @gmtoffset = gmtoffset
+      @datetime = datetime
+      @open = open
+      @high = high
+      @low = low
+      @close = close
+      @volume = volume
+    end
+  end
+end

data/lib/Eodhd/VERSION.rb

@@ -0,0 +1,3 @@
+class Eodhd
+  VERSION = '0.19.5'
+end

data/lib/Eodhd/Validations.rb

@@ -0,0 +1,78 @@
+# Eodhd/Validations.rb
+# Eodhd::Validations
+
+class Eodhd
+  module Validations
+    def validate_arguments(exchange_code: nil, exchange_id: nil, symbol: nil, period: nil, interval: nil, from: nil, to: nil, date: nil)
+      exchange_code ||= exchange_id
+      validate_exchange_code(exchange_code)
+      validate_symbol(symbol)
+      validate_period(period)
+      validate_interval(interval)
+      validate_date(from, 'from')
+      validate_date(to, 'to')
+      validate_date_range(from, to)
+    end
+
+    def validate_exchange_code(exchange_code)
+      return unless exchange_code
+      unless exchange_code.match?(/\A[A-Z]{2,6}\z/)
+        raise ArgumentError, "Invalid exchange_code '#{exchange_code}'. Must be 2-6 uppercase letters"
+      end
+    end
+
+    def validate_symbol(symbol)
+      return unless symbol
+      if symbol.strip.empty?
+        raise ArgumentError, "Symbol cannot be empty"
+      end
+      unless symbol.match?(/\A[A-Za-z0-9.-]{1,12}\z/)
+        raise ArgumentError, "Invalid symbol '#{symbol}'. Must be 1-12 characters, letters/numbers/dots/hyphens only"
+      end
+    end
+
+    def validate_period(period)
+      return unless period
+      valid_periods = %w[d w m]
+      unless valid_periods.include?(period)
+        raise ArgumentError, "Invalid period '#{period}'. Must be one of: #{valid_periods.join(', ')}"
+      end
+    end
+
+    def validate_interval(interval)
+      return unless interval
+      valid_intervals = %w[1m 5m 15m 30m 1h 4h 1d 1w 1mo]
+      unless valid_intervals.include?(interval)
+        raise ArgumentError, "Invalid interval: #{interval}. Must be one of: #{valid_intervals.join(', ')}"
+      end
+    end
+
+    def validate_date(date, param_name = 'date')
+      return unless date
+      case date
+      when Date
+        return
+      when String
+        unless date.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          raise ArgumentError, "Invalid #{param_name} '#{date}'. Must be in format 'yyyy-mm-dd'"
+        end
+        begin
+          Date.parse(date)
+        rescue Date::Error
+          raise ArgumentError, "Invalid #{param_name} '#{date}'. Not a valid date"
+        end
+      else
+        raise ArgumentError, "Invalid #{param_name}. Must be String in 'yyyy-mm-dd' format or Date object"
+      end
+    end
+
+    def validate_date_range(from, to)
+      return unless from && to
+      from_date = from.is_a?(Date) ? from : Date.parse(from.to_s)
+      to_date = to.is_a?(Date) ? to : Date.parse(to.to_s)
+      if from_date > to_date
+        raise ArgumentError, "from date (#{from}) cannot be after to date (#{to})"
+      end
+    end
+  end
+end

data/lib/Eodhd/WebSocketClient.rb

@@ -0,0 +1,130 @@
+# Eodhd/WebSocketClient.rb
+# Eodhd::WebSocketClient
+
+# Notes:
+# 1. All 4 of 4 WebSocket endpoints which Eodhd provides (See https://eodhd.com/financial-apis/new-real-time-data-api-websockets.) are as folllows...
+#   i.   US market trade data: wss://ws.eodhistoricaldata.com/ws/us?api_token=XXX
+#   ii.  US market quote data: wss://ws.eodhistoricaldata.com/ws/us-quote?api_token=XXX
+#   iii. Forex: wss://ws.eodhistoricaldata.com/ws/forex?api_token=XXX
+#   iv.  Crypto: wss://ws.eodhistoricaldata.com/ws/crypto?api_token=XXX
+
+require 'iodine'
+require 'json'
+
+require_relative './DefaultLogger'
+require_relative './Error'
+
+class Eodhd
+  class WebSocketClient
+    API_HOST = 'ws.eodhistoricaldata.com'
+
+    class Handler
+      def on_open(connection)
+        connection.write({action: 'subscribe', symbols: @symbols}.to_json)
+      end
+
+      def on_message(connection, message)
+        dataframe = handle_response(message)
+        @consumer.call(dataframe) if @consumer
+      end
+
+      def on_close(connection)
+        Iodine.stop
+      end
+
+      private
+
+      def initialize(symbols:, consumer:, logger: nil)
+        @symbols = symbols
+        @consumer = consumer
+        @logger = logger
+      end
+
+      def log_error(code:, message:, body:)
+        log_string = "WebSocketError #{code}\n#{message}\n#{body}"
+        @logger.error(log_string) if use_logging?
+      end
+
+      def handle_response(message)
+        JSON.parse(message)
+      rescue StandardError => e
+        log_error(code: 'ws_parse_error', message: e.message, body: message)
+        raise Eodhd::Error.new(code: 'ws_parse_error', message: e.message, body: message)
+      end
+
+      def use_logging?
+        !@logger.nil?
+      end
+    end
+
+    class << self
+      def path_prefix
+        '/ws'
+      end
+
+      def us_trade(api_token:, symbols:, consumer:)
+        self.class.new(api_token: api_token, asset_class: 'us', symbols: symbols, consumer: consumer)
+      end
+      alias_method :us, :us_trade
+
+      def us_quote(api_token:, symbols:, consumer:)
+        self.class.new(api_token: api_token, asset_class: 'us-quote', symbols: symbols, consumer: consumer)
+      end
+
+      def forex(api_token:, symbols:, consumer:)
+        self.class.new(api_token: api_token, asset_class: 'forex', symbols: symbols, consumer: consumer)
+      end
+
+      def crypto(api_token:, symbols:, consumer:)
+        self.class.new(api_token: api_token, asset_class: 'crypto', symbols: symbols, consumer: consumer)
+      end
+    end # class << self
+
+    attr_accessor\
+      :api_token,
+      :asset_class,
+      :consumer,
+      :logger
+
+    attr_reader\
+      :symbols
+
+    def symbols=(symbols)
+      @symbols = format_symbols(symbols)
+    end
+
+    def run
+      Iodine.threads = 1
+      Iodine.connect(url: url, handler: Handler.new(symbols: @symbols, consumer: @consumer, logger: @logger))
+      Iodine.start
+    rescue SystemExit, Interrupt
+      return
+    end
+
+    private
+
+    def initialize(api_token:, asset_class:, symbols:, consumer:, logger: nil, use_default_logger: false)
+      @api_token = api_token
+      @asset_class = asset_class # crypto, forex, us-quote, us
+      @symbols = format_symbols(symbols)
+      @consumer = consumer
+      @logger = use_default_logger ? DefaultLogger.logger : logger
+    end
+
+    def use_logging?
+      !@logger.nil?
+    end
+
+    def format_symbols(symbols)
+      if symbols.is_a?(Array)
+        symbols.join(',')
+      elsif symbols.is_a?(String)
+        symbols
+      end
+    end
+
+    def url
+      "wss://#{API_HOST}#{self.class.path_prefix}/#{@asset_class}?api_token=#{@api_token}"
+    end
+  end
+end

data/lib/Hash/x_www_form_urlencode.rb

@@ -0,0 +1,7 @@
+# Hash/x_www_form_urlencode.rb
+# Hash#x_www_form_urlencode
+
+# 20241009
+# 0.1.0
+
+require 'Thoran/Hash/XWwwFormUrlencode/x_www_form_urlencode'

data/lib/Thoran/Hash/XWwwFormUrlencode/x_www_form_urlencode.rb

@@ -0,0 +1,27 @@
+# Thoran/Hash/XWwwFormUrlencode/x_www_form_urlencode.rb
+# Thoran::Hash::XWwwFormUrlencode#x_www_form_urlencode
+
+# 20260713
+# 0.3.0
+
+# Changes since 0.2:
+# -/0: (The class name and the snake case name really are consistent now.)
+# 1. /XWwwFormUrlEncode/XWwwFormUrlencode/
+# 2. /url_encode/urlencode/
+
+require 'Thoran/String/Urlencode/urlencode'
+
+module Thoran
+  module Hash
+    module XWwwFormUrlencode
+
+      def x_www_form_urlencode(joiner = '&')
+        inject([]){|a,e| a << "#{e.first.to_s.urlencode}=#{e.last.to_s.urlencode}" unless e.last.nil?; a}.join(joiner)
+      end
+      alias_method :x_www_form_url_encode, :x_www_form_urlencode
+
+    end
+  end
+end
+
+Hash.send(:include, Thoran::Hash::XWwwFormUrlencode)

data/lib/Thoran/String/Urlencode/urlencode.rb

@@ -0,0 +1,29 @@
+# Thoran/String/Urlencode/urlencode.rb
+# Thoran::String::Urlencode#urlencode
+
+# 20260713
+# 0.4.0
+
+# Acknowledgements: I've simply ripped off and refashioned the code from the CGI module!...
+
+# Changes since 0.3:
+# -/0: More consistent naming.
+# 1. /UrlEncode/Urlencode/
+# 2. /url_encode/urlencode/
+
+module Thoran
+  module String
+    module Urlencode
+
+      def urlencode
+        self.gsub(/([^ a-zA-Z0-9_.-]+)/n) do
+          '%' + $1.unpack('H2' * $1.size).join('%').upcase
+        end.tr(' ', '+')
+      end
+      alias_method :url_encode, :urlencode
+
+    end
+  end
+end
+
+String.send(:include, Thoran::String::Urlencode)

data/lib/eodhd.rb

@@ -0,0 +1,78 @@
+# Eodhd.rb
+# Eodhd
+
+require_relative './Eodhd/Client'
+require_relative './Eodhd/EodBulkLastDay'
+require_relative './Eodhd/EodData'
+require_relative './Eodhd/Exchange'
+require_relative './Eodhd/ExchangeSymbol'
+require_relative './Eodhd/Intraday'
+require_relative './Eodhd/Fundamentals'
+require_relative './Eodhd/WebSocketClient'
+require_relative './Eodhd/VERSION'
+
+class Eodhd
+  def exchanges
+    Eodhd::Exchange.all(api_token: @api_token)
+  end
+
+  def exchange_symbols(exchange: nil, exchange_code: nil)
+    exchange_code ||= exchange&.code
+    Eodhd::ExchangeSymbol.all(api_token: @api_token, exchange_code: exchange_code)
+  end
+
+  def eod_data(exchange: nil, exchange_code: nil, exchange_symbol: nil, symbol: nil, period: nil, from: nil, to: nil)
+    exchange_code ||= exchange&.code
+    symbol ||= exchange_symbol&.code
+    Eodhd::EodData.all(api_token: @api_token, exchange_code: exchange_code, symbol: symbol, period: period, from: from, to: to)
+  end
+
+  def eod_bulk_last_day(exchange: nil, exchange_code: nil, date:)
+    exchange_code ||= exchange&.code
+    Eodhd::EodBulkLastDay.all(api_token: @api_token, exchange_code: exchange_code, date: date)
+  end
+
+  def intraday(exchange: nil, exchange_code: nil, exchange_symbol: nil, symbol: nil, interval:, from: nil, to: nil)
+    exchange_code ||= exchange&.code
+    symbol ||= exchange_symbol&.code
+    Eodhd::Intraday.all(api_token: @api_token, exchange_code: exchange_code, symbol: symbol, interval: interval, from: from, to: to)
+  end
+
+  def fundamentals(exchange: nil, exchange_code: nil, exchange_symbol: nil, symbol: nil, filter: nil)
+    exchange_code ||= exchange&.code
+    symbol ||= exchange_symbol&.code
+    Eodhd::Fundamentals.all(api_token: @api_token, exchange_code: exchange_code, symbol: symbol, filter: filter)
+  end
+
+  def us_trade_stream(symbols)
+    stream(asset_class: 'us', symbols: symbols)
+  end
+  alias_method :us_stream, :us_trade_stream
+
+  def us_quote_stream(symbols)
+    stream(asset_class: 'us-quote', symbols: symbols)
+  end
+
+  def forex_stream(symbols)
+    stream(asset_class: 'forex', symbols: symbols)
+  end
+
+  def crypto_stream(symbols)
+    stream(asset_class: 'crypto', symbols: symbols)
+  end
+
+  private
+
+  def initialize(api_token:, consumer: nil)
+    @api_token = api_token
+    @consumer = consumer
+  end
+
+  def web_socket(asset_class:, symbols:)
+    Eodhd::WebSocketClient.new(api_token: @api_token, asset_class: asset_class, symbols: symbols, consumer: @consumer)
+  end
+
+  def stream(asset_class:, symbols:)
+    web_socket(asset_class: asset_class, symbols: symbols).run
+  end
+end

data/test/Eodhd/Client_test.rb

@@ -0,0 +1,111 @@
+# Eodhd/Client_test.rb
+
+require_relative '../helper'
+
+describe Eodhd::Client do
+  let(:api_token){ENV.fetch('EODHD_API_TOKEN', '<API_TOKEN>')}
+  let(:client){Eodhd::Client.new(api_token: api_token)}
+
+  describe "#exchanges_list" do
+    it "returns parsed JSON array" do
+      VCR.use_cassette("client_exchanges_list") do
+        result = client.exchanges_list
+        _(result).must_be_kind_of(Array)
+        _(result.first["Code"]).wont_be_nil
+      end
+    end
+
+    it "raises Eodhd::Error on failure" do
+      VCR.use_cassette("client_exchanges_list_401_error") do
+        _{client.exchanges_list}.must_raise(Eodhd::Error)
+      end
+    end
+  end
+
+  describe "#exchange_symbol_list" do
+    it "returns parsed JSON array" do
+      VCR.use_cassette("client_exchange_symbol_list") do
+        result = client.exchange_symbol_list(exchange_code: 'AU')
+        _(result).must_be_kind_of(Array)
+        _(result.first['Code']).wont_be_nil
+      end
+    end
+
+    it "raises Eodhd::Error on failure" do
+      VCR.use_cassette("client_exchange_symbol_list_401_error") do
+        _{client.exchange_symbol_list(exchange_code: 'AU')}.must_raise(Eodhd::Error)
+      end
+    end
+  end
+
+  describe "#eod_data" do
+    it "returns parsed JSON array" do
+      VCR.use_cassette('client_eod_data') do
+        result = client.eod_data(exchange_id: 'AU', symbol: 'BHP', period: 'd')
+        _(result).must_be_kind_of(Array)
+        _(result.first.keys).must_equal(%w{date open high low close adjusted_close volume})
+      end
+    end
+
+    it "raises Eodhd::Error on failure" do
+      VCR.use_cassette('client_eod_data_401_error') do
+        _{client.eod_data(exchange_id: 'AU', symbol: 'BHP', period: 'd')}.must_raise(Eodhd::Error)
+      end
+    end
+  end
+
+  describe "#eod_bulk_last_day" do
+    it "returns parsed JSON array" do
+      VCR.use_cassette("client_eod_bulk_last_day") do
+        result = client.eod_bulk_last_day(exchange_id: 'AU', date: "2024-09-30")
+        _(result).must_be_kind_of(Array)
+        _(result.first.keys).must_equal(%w{code exchange_short_name date open high low close adjusted_close volume})
+      end
+    end
+
+    it "raises Eodhd::Error on failure" do
+      VCR.use_cassette('client_eod_bulk_last_day_401_error') do
+        _{client.eod_bulk_last_day(exchange_id: 'AU', date: "2024-09-30")}.must_raise(Eodhd::Error)
+      end
+    end
+  end
+
+  describe "#intraday" do
+    it "returns parsed JSON array" do
+      VCR.use_cassette('client_intraday') do
+        result = client.intraday(exchange_code: 'US', symbol: 'AAPL', interval: '5m')
+        _(result).must_be_kind_of(Array)
+        _(result.first.keys).must_equal(%w{timestamp gmtoffset datetime open high low close volume})
+      end
+    end
+
+    it "raises Eodhd::Error on failure" do
+      VCR.use_cassette('client_intraday_401_error') do
+        _{client.intraday(exchange_code: 'US', symbol: 'AAPL', interval: '5m')}.must_raise(Eodhd::Error)
+      end
+    end
+  end
+
+  describe "#fundamentals" do
+    it "returns parsed JSON hash" do
+      VCR.use_cassette('client_fundamentals') do
+        result = client.fundamentals(exchange_code: 'US', symbol: 'AAPL')
+        _(result).must_be_kind_of(Hash)
+        _(result['General']).wont_be_nil
+      end
+    end
+
+    it "supports filter parameter" do
+      VCR.use_cassette('client_fundamentals_filtered') do
+        result = client.fundamentals(exchange_code: 'US', symbol: 'AAPL', filter: 'General')
+        _(result).must_be_kind_of(Hash)
+      end
+    end
+
+    it "raises Eodhd::Error on failure" do
+      VCR.use_cassette('client_fundamentals_401_error') do
+        _{client.fundamentals(exchange_code: 'US', symbol: 'AAPL')}.must_raise(Eodhd::Error)
+      end
+    end
+  end
+end