iex-ruby-client 1.2.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71bec851d78d50e5e8625f18e94212bd3d5825a1bf90a3809258e6ef88dcae34
-  data.tar.gz: b3f668404aada9eb2bcfa7f56767ce51083222c9f40a2fa95f15d005be9ee7ed
+  metadata.gz: ab2cf9c9b5a300629e51b810e4f556ba5d3113a226faa0b2a9293be2939cdb24
+  data.tar.gz: cbab6366388a36eddac8a9e55c4eb4e9e5254cd883f0fe135bdb63d7e359f137
 SHA512:
-  metadata.gz: bf29091889a722d957ea6abceb5dc60d761fde868abc4212829c48723fc668870dbad46a75815823224bf324bd466fc917669792b320c85b0a907979b37008cc
-  data.tar.gz: 1222b56a8c47e79cd36b92b124128fa0162f8acbd9aa466f212cd0bc3bbe94036c2cc0c79243e348cf3b65ebb527ba47d46b91850dc8059cd081cab247568971
+  metadata.gz: 3a08d8c90fdc3a1ac756321711a76d2b65f01d8c5935b160125fcb41751452da65588d5b29ab1f3f000026171c61ceafdb9ce270af62c342c701512e83a706e0
+  data.tar.gz: b6cbac7f892c7e1ce514cb5906180d60d73b66b5a80edb777eb7ac754fad309b9ce8745b08e8ce1c5f4cc27c109f84b558025f70bc53b754c1ef2e0ac4ccd3e4

data/.env.sample

@@ -0,0 +1,2 @@
+IEX_API_PUBLISHABLE_TOKEN=test-iex-api-publishable-token
+IEX_API_SECRET_TOKEN=test-iex-api-secret-token

data/.gitignore

@@ -4,3 +4,4 @@ Gemfile.lock
 .DS_Store
 .bundle
 .idea
+.irbrc

data/.rubocop_todo.yml

@@ -11,11 +11,3 @@
 Style/AsciiComments:
   Exclude:
     - 'lib/iex/resources/quote.rb'
-
-# Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, Autocorrect.
-# SupportedStyles: module_function, extend_self
-Style/ModuleFunction:
-  Exclude:
-    - 'lib/iex/api/config.rb'

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+### 1.5.0 (2021/08/15)
+* [#105](https://github.com/dblock/iex-ruby-client/pull/105): Added support for fetching latest foreign exchange rates - [@mathu97](https://github.com/mathu97).
+* [#106](https://github.com/dblock/iex-ruby-client/pull/106): Added support for fetching a single key stat with `key_stat(symbol, stat)` endpoint - [@agrberg](https://github.com/agrberg).
+* [#107](https://github.com/dblock/iex-ruby-client/pull/107): Added `./script/console` for ease of local development - [@agrberg](https://github.com/agrberg).
+
+### 1.4.1 (2021/05/15)
+* [#103](https://github.com/dblock/iex-ruby-client/pull/103): Added support for fetching symbols for an exchange - [@mathu97](https://github.com/mathu97).
+* [#99](https://github.com/dblock/iex-ruby-client/pull/99): Added `image` and `paywalled` to news - [@reddavis](https://github.com/reddavis).
+* [#100](https://github.com/dblock/iex-ruby-client/pull/100): Added `language` to news - [@reddavis](https://github.com/reddavis).
+
+### 1.4.0 (2020/11/19)
+* [#90](https://github.com/dblock/iex-ruby-client/pull/90): Added documentation for advanced stats and removed `avg_30_Volume` from advanced stats since it is found in key stats - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#91](https://github.com/dblock/iex-ruby-client/pull/91): Added support for Balance Sheet API endpoint - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#92](https://github.com/dblock/iex-ruby-client/pull/92): Added support for Cash Flow Statements API endpoint - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#93](https://github.com/dblock/iex-ruby-client/pull/93): Added `fiscal_date` and `currency` to income statements - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#94](https://github.com/dblock/iex-ruby-client/pull/94): Added `historical_prices` API endpoint - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#95](https://github.com/dblock/iex-ruby-client/pull/95): Added all KeyStat properties to AdvancedStats since they are already returned in the API call - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+
+### 1.3.0 (2020/10/31)
+
+* [#82](https://github.com/dblock/iex-ruby-client/pull/82): Added `config.referer` to set HTTP `Referer` header. This enables IEX's "Manage domains" domain locking for tokens - [@agrberg](https://github.com/agrberg).
+* [#70](https://github.com/dblock/iex-ruby-client/pull/70): Added support for `ref_data_isin` taking a single `String` parameter - [@rodolfobandeira](https://github.com/rodolfobandeira).
+* [#84](https://github.com/dblock/iex-ruby-client/pull/84): Added support for Advanced Stats API - [@FanaHOVA](https://github.com/fanahova).
+* [#86](https://github.com/dblock/iex-ruby-client/issues/86): Added advanced logger configuration to `config.logger`. Now a hash with keys `:instance, :options, and :proc` can be passed and used directly with Faraday - [@agrberg](https://github.com/agrberg).
+* [#88](https://github.com/dblock/iex-ruby-client/pull/88): Updated logger configuration to work like `Config` class and allow attribute and block based configuration - [@agrberg](https://github.com/agrberg).
+* [#89](https://github.com/dblock/iex-ruby-client/pull/89): Backfill breaking `Config#logger` setting change from [#88](https://github.com/dblock/iex-ruby-client/pull/88) - [@agrberg](https://github.com/agrberg).
+
 ### 1.2.0 (2020/09/01)
 
 * [#78](https://github.com/dblock/iex-ruby-client/pull/78): Added `Quote#extended_change_percent` and `Quote#extended_change_percent_s` properties to Quote - [@reddavis](https://github.com/reddavis).

data/Gemfile

@@ -5,5 +5,6 @@ gemspec
 group :test do
   gem 'danger-changelog', '~> 0.6.0'
   gem 'danger-toc', '~> 0.2.0'
+  gem 'dotenv'
   gem 'pry'
 end

data/README.md

@@ -15,22 +15,29 @@ A Ruby client for the [The IEX Cloud API](https://iexcloud.io/docs/api/).
   - [Get a Quote](#get-a-quote)
   - [Get a OHLC (Open, High, Low, Close) price](#get-a-ohlc-open-high-low-close-price)
   - [Get a Market OHLC (Open, High, Low, Close) prices](#get-a-market-ohlc-open-high-low-close-prices)
+  - [Get Historical Prices](#get-historical-prices)
   - [Get Company Information](#get-company-information)
   - [Get a Company Logo](#get-a-company-logo)
   - [Get Recent News](#get-recent-news)
   - [Get Chart](#get-chart)
   - [Get Key Stats](#get-key-stats)
+  - [Get Advanced Stats](#get-advanced-stats)
   - [Get Dividends](#get-dividends)
   - [Get Earnings](#get-earnings)
   - [Get Income Statement](#get-income-statement)
+  - [Get Balance Sheet](#get-balance-sheet)
+  - [Get Cash Flow Statement](#get-cash-flow-statement)
   - [Get Sector Performance](#get-sector-performance)
   - [Get Largest Trades](#get-largest-trades)
   - [Get a Quote for Crypto Currencies](#get-a-quote-for-crypto-currencies)
   - [ISIN Mapping](#isin-mapping)
   - [Get Symbols](#get-symbols)
+  - [Get Symbols for an Exchange](#get-symbols-for-an-exchange)
+  - [Get Latest Foreign Exchange Rates](#get-latest-foreign-exchange-rates)
   - [Get List](#get-list)
   - [Other Requests](#other-requests)
 - [Configuration](#configuration)
+  - [Logging](#logging)
 - [Sandbox Environment](#sandbox-environment)
 - [Errors](#errors)
   - [SymbolNotFound](#symbolnotfound)
@@ -129,6 +136,60 @@ market['SPY'].high #
 market['SPY'].low #
 ```
 
+### Get Historical Prices
+
+Fetches a list of historical prices.
+
+There are currently a few limitations of this endpoint compared to the official IEX one.
+
+Options for `range` include:
+`max, ytd, 5y, 2y, 1y, 6m, 3m, 1m, 5d, date`
+
+NOTE: If you use the `date` value for the `range` parameter:
+
+- The options _must_ include a date entry, `{date: ...}`
+- The date value _must_ be either a Date object, or a string formatted as `YYYYMMDD`. Anything else will result in an `IEX::Errors::ClientError`.
+- The options _must_ include `chartByDay: 'true'` or an `ArgumentError` will be raised.
+- See below for examples.
+
+`Query params` supported include:
+`chartByDay`
+
+This is a complicated endpoint as there is a lot of granularity over the time period of data returned. See below for a variety of ways to request data, NOTE: this is _NOT_ as exhaustive list.
+
+```ruby
+historical_prices = client.historical_prices('MSFT') # One month of data
+historical_prices = client.historical_prices('MSFT', {range: 'max'}) # All data up to 15 years
+historical_prices = client.historical_prices('MSFT', {range: 'ytd'}) # Year to date data
+historical_prices = client.historical_prices('MSFT', {range: '5y'}) # 5 years of data
+historical_prices = client.historical_prices('MSFT', {range: '6m'}) # 6 months of data
+historical_prices = client.historical_prices('MSFT', {range: '5d'}) # 5 days of data
+historical_prices = client.historical_prices('MSFT', {range: 'date', date: '20200930', chartByDay: 'true'}) # One day of data
+historical_prices = client.historical_prices('MSFT', {range: 'date', date: Date.parse('2020-09-30'), chartByDay: 'true'}) # One day of data
+...
+```
+
+Once you have the data over the preferred time period, you can access the following fields
+
+```ruby
+historical_prices = client.historical_prices('MSFT') # One month of data
+
+historical_price = historical_prices.first
+historical_price.date # 2020-10-07
+historical_price.open #207.06
+historical_price.open_dollar # '$207.06'
+historical_price.close # 209.83
+historical_price.close_dollar # '$209.83'
+historical_price.high # 210.11
+historical_price.high_dollar # '$210.11'
+historical_price.low # 206.72
+historical_price.low_dollar # '$206.72'
+historical_price.volume # 25681054
+...
+```
+
+There are a lot of options here so I would recommend viewing the official IEX documentation [#historical-prices](https://iexcloud.io/docs/api/#historical-prices) or [historical_prices.rb](lib/iex/resources/historical_prices.rb) for returned fields.
+
 ### Get Company Information
 
 Fetches company information for a symbol.
@@ -262,8 +323,58 @@ key_stats.pe_ratio # 29.47
 key_stats.beta # 1.4135449089973444
 ```
 
+You can also fetch a single stat for a symbol. **Note** that IEX uses `lowerCamelCase` for the names of the stats.
+
+```ruby
+client.key_stat('VTI', 'dividendYield') # 0.01271760965303361
+```
+
 See [#key-stats](https://iexcloud.io/docs/api/#key-stats) for detailed documentation or [key_stats.rb](lib/iex/resources/key_stats.rb) for returned fields.
 
+### Get Advanced Stats
+
+Fetches company's advanced stats for a symbol, this will include all key stats as well.
+
+```ruby
+advanced_stats = client.advanced_stats('MSFT')
+
+advanced_stats.total_cash # 66301000000
+advanced_stats.total_cash_dollars # "$66,301,000,000"
+advanced_stats.current_debt # 20748000000
+advanced_stats.current_debt_dollars # "$2,074,8000,000"
+advanced_stats.revenue # 265809000000
+advanced_stats.revenue_dollars # "$265,809,000,000"
+advanced_stats.gross_profit # 101983000000
+advanced_stats.gross_profit_dollar # "$101,983,000,000"
+advanced_stats.total_revenue # 265809000000
+advanced_stats.total_revenue_dollar # "$265,809,000,000"
+advanced_stats.ebitda # 80342000000
+advanced_stats.ebitda_dollar # "$80,342,000,000"
+advanced_stats.revenue_per_share # 0.02
+advanced_stats.revenue_per_share_dollar # "$0.02"
+advanced_stats.revenue_per_employee # 2013704.55
+advanced_stats.revenue_per_employee_dollar # "$2,013,704.55"
+advanced_stats.debt_to_equity # 1.07
+advanced_stats.profit_margin # 22.396157
+advanced_stats.enterprise_value # 1022460690000
+advanced_stats.enterprise_value_dollar # "$1,022,460,690,000"
+advanced_stats.enterprise_value_to_revenue # 3.85
+advanced_stats.price_to_sales # 3.49
+advanced_stats.price_to_sales_dollar # "$3.49"
+advanced_stats.price_to_book # 8.805916432564608
+advanced_stats.forward_pe_ratio # 18.14
+advanced_stats.pe_high # 22.61
+advanced_stats.pe_low # 11.98
+advanced_stats.peg_ratio # 2.19
+advanced_stats.week_52_high_date # "2019-11-19"
+advanced_stats.week_52_low_date # "2019-01-03
+advanced_stats.beta # 1.4661365583766115
+advanced_stats.put_call_ratio # 0.6780362005229779
+...
+```
+
+See [#advanced-stats](https://iexcloud.io/docs/api/#advanced-stats) for detailed documentation or [advanced_stats.rb](lib/iex/resources/advanced_stats.rb) for returned fields.
+
 ### Get Dividends
 
 Fetches dividends for a symbol.
@@ -303,12 +414,16 @@ See [#earnings](https://iexcloud.io/docs/api/#earnings) for detailed documentati
 
 ### Get Income Statement
 
-Fetches income statement for a symbol.
+Fetches income statements for a symbol.
 
 ```ruby
-income = client.income('MSFT')
+income_statements = client.income('MSFT')
 
+# Multiple income statements are returned with 1 API call.
+income = income_statements.first
 income.report_date # '2019-03-31'
+income.fiscal_date # '2019-03-31'
+income.currency # 'USD'
 income.total_revenue # 30_505_000_000
 income.total_revenue_dollar # '$30,505,000,000'
 income.cost_of_revenue # 10_170_000_000
@@ -320,6 +435,48 @@ income.gross_profit_dollar # '$20,335,000,000'
 
 See [#income-statement](https://iexcloud.io/docs/api/#income-statement) for detailed documentation or [income.rb](lib/iex/resources/income.rb) for returned fields.
 
+### Get Balance Sheet
+
+Fetches balance sheets for a symbol.
+
+```ruby
+balance_sheets = client.balance_sheet('MSFT')
+
+# Multiple balance sheets are returned with 1 API call.
+balance_sheet = balance_sheets.first
+balance_sheet.report_date # '2017-03-31'
+balance_sheet.fiscal_date # '2017-03-31'
+balance_sheet.currency # 'USD'
+balance_sheet.current_cash # 25_913_000_000
+balance_sheet.current_cash_dollar # '$25,913,000,000'
+balance_sheet.short_term_investments # 40_388_000_000
+balance_sheet.short_term_investments_dollar # '$40,388,000,000'
+...
+```
+
+See [#balance-sheet](https://iexcloud.io/docs/api/#balance-sheet) for detailed documentation or [balance_sheet.rb](lib/iex/resources/balance_sheet.rb) for returned fields.
+
+### Get Cash Flow Statement
+
+Fetches cash flow statements for a symbol.
+
+```ruby
+cash_flow_statements = client.cash_flow('MSFT')
+
+# Multiple cash flow statements are returned with 1 API call.
+cash_flow = cash_flow_statements.first
+cash_flow.report_date # '2018-09-30'
+cash_flow.fiscal_date # '2018-09-30'
+cash_flow.currency # 'USD'
+cash_flow.net_income # 14_125_000_000
+cash_flow.net_income_dollar # '$14,125,000,000'
+cash_flow.depreciation # 2_754_000_000
+cash_flow.depreciation_dollar # '$2,754,000,000'
+...
+```
+
+See [#cash-flow](https://iexcloud.io/docs/api/#cash-flow) for detailed documentation or [cash_flow.rb](lib/iex/resources/cash_flow.rb) for returned fields.
+
 ### Get Sector Performance
 
 Fetches latest sector's performance.
@@ -378,10 +535,10 @@ See [#crypto](https://iexcloud.io/docs/api/#crypto) for detailed documentation o
 
 ### ISIN Mapping
 
-Converts ISIN to IEX Cloud symbols.
+Convert ISIN to IEX Cloud symbols.
 
 ```ruby
-symbols = client.ref_data_isin(['US0378331005'])
+symbols = client.ref_data_isin('US0378331005')
 
 symbols.first.exchange # NAS
 symbols.first.iex_id # IEX_4D48333344362D52
@@ -389,6 +546,12 @@ symbols.first.region # US
 symbols.first.symbol # AAPL
 ```
 
+The API also lets you convert multiple ISINs to IEX Cloud symbols.
+
+```ruby
+symbols = client.ref_data_isin(['US0378331005', 'US0378331006'])
+```
+
 You can use `mapped: true` option to receive symbols grouped by their ISINs.
 
 ```ruby
@@ -399,7 +562,7 @@ See [#ISIN Mapping](https://iexcloud.io/docs/api/#isin-mapping) for detailed doc
 
 ### Get Symbols
 
-Returns an array of symbols
+Returns an array of symbols.
 
 ```ruby
 symbols = client.ref_data_symbols()
@@ -413,6 +576,37 @@ symbol.symbol # A
 
 See [#symbols](https://iexcloud.io/docs/api/#symbols) for detailed documentation or [symbols.rb](lib/iex/resources/symbols.rb) for returned fields.
 
+### Get Symbols for an Exchange
+
+Returns an array of symbols for a given exchange.
+
+```ruby
+symbols = client.ref_data_symbols_for_exchange('TSX')
+
+symbol = symbols.first
+symbol.exchange # TSX
+symbol.iex_id # IEX_4656374258322D52
+symbol.region # CA
+symbol.symbol # A-CV
+```
+
+See [#international-symbols](https://iexcloud.io/docs/api/#international-symbols) for returned fields.
+
+### Get Latest Foreign Exchange Rates
+
+Returns an array of foreign exchange rates for a given list of symbols.
+
+```ruby
+rates = client.fx_latest(['USDCAD', 'USDGBP', 'USDJPY'])
+
+rate = rates.first
+rate.symbol # USDCAD
+rate.rate # 1.25674
+rate.timestamp # <Date: 2021-07-23 ((2459419j,0s,0n),+0s,2299161j)>
+```
+
+See [#latest-currency-rates](https://iexcloud.io/docs/api/#latest-currency-rates) for returned fields.
+
 ### Get List
 
 Returns an array of quotes for the top 10 symbols in a specified list.
@@ -437,7 +631,7 @@ client.post('ref-data/isin', isin: ['US0378331005'], token: 'secret_token') # [{
 You can configure client options globally or directly with a `IEX::Api::Client` instance.
 
 ```ruby
-IEX::Api::Client.configure do |config|
+IEX::Api.configure do |config|
   config.publishable_token = ENV['IEX_API_PUBLISHABLE_TOKEN']
   config.endpoint = 'https://sandbox.iexapis.com/v1' # use sandbox environment
 end
@@ -452,23 +646,48 @@ client = IEX::Api::Client.new(
 
 The following settings are supported.
 
-setting             | description
---------------------|------------
-user_agent          | User-agent, defaults to _IEX Ruby Client/version_.
-proxy               | Optional HTTP proxy.
-ca_path             | Optional SSL certificates path.
-ca_file             | Optional SSL certificates file.
-logger              | Optional `Logger` instance that logs HTTP requests.
-timeout             | Optional open/read timeout in seconds.
-open_timeout        | Optional connection open timeout in seconds.
-publishable_token   | IEX Cloud API publishable token.
-endpoint            | Defaults to `https://cloud.iexapis.com/v1`.
+| setting           | description                                                                 |
+| ----------------- | --------------------------------------------------------------------------- |
+| user_agent        | User-agent, defaults to _IEX Ruby Client/version_.                          |
+| proxy             | Optional HTTP proxy.                                                        |
+| ca_path           | Optional SSL certificates path.                                             |
+| ca_file           | Optional SSL certificates file.                                             |
+| logger            | Optional `Logger` instance or logger configuration to log HTTP requests.    |
+| timeout           | Optional open/read timeout in seconds.                                      |
+| open_timeout      | Optional connection open timeout in seconds.                                |
+| publishable_token | IEX Cloud API publishable token.                                            |
+| endpoint          | Defaults to `https://cloud.iexapis.com/v1`.                                 |
+| referer           | Optional string for HTTP `Referer` header, enables token domain management. |
+
+### Logging
+
+Faraday will not log HTTP requests by default. In order to do this you can either provide a `logger` instance or configuration attributes to `IEX::Api::Client`. Configuration allows you to supply the `instance`, `options`, and `proc` to [Faraday](https://lostisland.github.io/faraday/middleware/logger#include-and-exclude-headersbodies).
+
+```ruby
+logger_instance = Logger.new(STDOUT)
+
+IEX::Api.configure do |config|
+  config.logger.instance = logger_instance
+  config.logger.options = { bodies: true }
+  config.logger.proc = proc { |logger| logger.filter(/T?[sp]k_\w+/i, '[REMOVED]') }
+end
+# or
+IEX::Api.logger do |logger|
+  logger.instance = logger_instance
+  logger.options = …
+  logger.proc = …
+end
+# or
+IEX::Api.logger = logger_instance
+# or
+IEX::Api::Client.new(logger: logger_instance)
+```
 
 ## Sandbox Environment
 
 IEX recommends you use a sandbox token and endpoint for testing.
 
-However, please note that data in the IEX sandbox environment is scrambled. Therefore elements such as company and people names, descriptions, tags, and website URLs don't render any coherent data.
+However, please note that data in the IEX sandbox environment is scrambled. Therefore elements such as company and people names, descriptions, tags, and website URLs don't render any coherent data. In addition, results, such as closing market prices and dividend yield, are not accurate and vary on every call.
 
 See [IEX sandbox environment](https://intercom.help/iexcloud/en/articles/2915433-testing-with-the-iex-cloud-sandbox) for more information.
 

data/RELEASING.md

@@ -11,15 +11,15 @@ bundle install
 rake
 ```
 
-Check that the last build succeeded in [Travis CI](https://travis-ci.org/dblock/iex-ruby-client) for all supported platforms.
+Check that the last build succeeded in [Travis CI](https://travis-ci.com/github/dblock/iex-ruby-client) for all supported platforms.
 
 Change "Next" in [CHANGELOG.md](CHANGELOG.md) to the current date.
 
 ```
-### 0.2.2 (7/10/2015)
+### 0.2.2 (2015/10/07)
 ```
 
-Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+Remove the line with "* Your contribution here.", since there will be no more contributions to this release.
 
 Commit your changes.