twelvedata_ruby 0.2.2 → 0.4.0

data/README.md

@@ -1,9 +1,18 @@
 # TwelvedataRuby
 
-[![Gem Version](https://badge.fury.io/rb/twelvedata_ruby.svg)](https://badge.fury.io/rb/twelvedata_ruby)
+[![Gem Version](https://badge.fury.io/rb/ruby.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/ruby)
 
-TwelvedataRuby is a Ruby library that exposes some convenient ways to access Twelve Data API to get information on stock, forex, crypto, and other financial market data. In order to do so, a free API key is required which can be easily requested [here](https://twelvedata.com/pricing). Visit their [API's full documentation](https://twelvedata.com/docs)
+A Ruby client library for accessing [Twelve Data's](https://twelvedata.com) comprehensive financial API. Get real-time and historical data for stocks, forex, cryptocurrencies, ETFs, indices, and more.
 
+## Features
+
+- 🚀 **Modern Ruby** - Requires Ruby 3.4.0+, follows modern Ruby practices
+- 📈 **Comprehensive API Coverage** - All Twelve Data endpoints supported
+- 🔒 **Type Safety** - Strong parameter validation and error handling
+- 📊 **Multiple Formats** - JSON and CSV response formats
+- 🧪 **Well Tested** - 100% test coverage
+- 🔧 **Developer Friendly** - Excellent error messages and debugging support
+- ⚡ **High Performance** - Built on HTTPX for concurrent requests
 
 ## Installation
 
@@ -15,142 +24,437 @@ gem 'twelvedata_ruby'
 
 And then execute:
 
-    $ bundle install
+```bash
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install twelvedata_ruby
+```bash
+gem install twelvedata_ruby
+```
 
-## Usage
+## Quick Start
 
-The preferred way to include the Twelve Data API key in the request payload is to assign it to an ENVIRONMENT variable which your Ruby application can fetch if none was explicitly assigned. The default ENVIRONMENTt variable name is `TWELVEDATA_API_KEY` but you can configure this to any other value  using the `#apikey_env_var_name=` setter method.
+### 1. Get Your API Key
 
-To get hold of the singleton `TwelvedataRuby::Client.instance`, you can directly used that inherited instance method from the mixed in `Singleton` module or thru the gem's module helper class method:
+Sign up for a free API key at [Twelve Data](https://twelvedata.com/pricing).
+
+### 2. Basic Usage
 
 ```ruby
-require "twelvedata_ruby"
+require 'twelvedata_ruby'
+
+# Option 1: Configure with API key directly
+client = TwelvedataRuby.client(apikey: "your-api-key-here")
+
+# Option 2: Use environment variable (recommended)
+ENV['TWELVEDATA_API_KEY'] = 'your-api-key-here'
 client = TwelvedataRuby.client
+
+# Get a stock quote
+response = client.quote(symbol: "AAPL")
+puts response.parsed_body
+# => {
+#   symbol: "AAPL",
+#   name: "Apple Inc",
+#   exchange: "NASDAQ",
+#   currency: "USD",
+#   datetime: "2024-01-15",
+#   open: "185.00",
+#   high: "187.50",
+#   low: "184.20",
+#   close: "186.75",
+#   volume: "45678900",
+#   ...
+# }
 ```
 
-By not passing anything to the options method parameters, the `client` instance attributes will have default values. Though you can still set different values to the attributes through their helper setter methods:
+## API Reference
+
+### Stock Market Data
 
 ```ruby
-client.apikey = "twelvedata-apikey"
-client.apikey_env_var_name = "the_environment_variable_name" # the helper getter method will upcase the value
-client.connect_timeout = 300 # can also accept "300"
+# Real-time quote
+client.quote(symbol: "AAPL")
+client.quote(symbol: "GOOGL", exchange: "NASDAQ")
+
+# Current price only
+client.price(symbol: "TSLA")
+
+# Historical time series data
+client.time_series(
+  symbol: "AAPL",
+  interval: "1day",
+  start_date: "2024-01-01",
+  end_date: "2024-01-31"
+)
+
+# End of day prices
+client.eod(symbol: "MSFT")
+
+# Search for symbols
+client.symbol_search(symbol: "Apple")
 ```
 
-or simply set them all at once:
+### Forex & Currency
 
 ```ruby
-require "twelvedata_ruby"
-client = TwelvedataRuby.client(apikey: "twelvedata-apikey", connect_timeout: 300)
-# or client = TwelvedataRuby.client(apikey_env_var_name: "the_environment_variable_name", connect_timeout: 300)
+# Exchange rates
+client.exchange_rate(symbol: "USD/EUR")
+
+# Currency conversion
+client.currency_conversion(symbol: "USD/EUR", amount: 100)
+
+# Available forex pairs
+client.forex_pairs
 ```
 
-The default values though are sufficient already.
+### Cryptocurrency
 
-Getting any type of financial data then from the API, simply invoke any valid endpoint name to the client instance. For example, to fetch some data for `GOOG` stock symbol using quote, timeseries, price, and etd API endpoints:
+```ruby
+# Crypto quotes
+client.quote(symbol: "BTC/USD")
+
+# Available cryptocurrencies
+client.cryptocurrencies
+
+# Crypto exchanges
+client.cryptocurrency_exchanges
+```
+
+### Market Reference Data
 
 ```ruby
-# 1. response content-type will be :csv
-client.quote(symbol: "GOOG", format: :csv)
-# 2. assigns custom attachment name
-client.timeseries(symbol: "GOOG", interval: "1hour", format: :csv, filename: "google_timeseries_1hour.csv")
-# 3. the content-type format will be :json
-client.price(symbol: "GOOG")
-# 4. the passed apikey is the used in the request payload
-client.etd(symbol: "GOOG", apikey: "overrides-whatever-is-the-current-apikey")
-# 5. an example of invocation which the API will respond with 401 error code
-client.etd(symbol: "GOOG", apikey: "invalid-api-key")
-# 6. still exactly the same object with client
-TwelvedataRuby.client.api_usage
-# 7. an invalid request wherein the required query parameter :interval is missing
-TwelvedataRuby.client.timeseries(symbol: "GOOG")
-# 8. an invalid request because it contains an invalid parameter
-client.price(symbol: "GOOG", invalid_parameter: "value")
-# 9. invoking a non-existing API endpoint will cause a NoMethodError exception
-client.price(symbol: "GOOG", invalid_parameter: "value")
-```
-
-All of the invocations possible return instance value is one of the following:
-- `TwelvedataRuby::Response` instance object which `#error` instance getter method can return a nil or kind of `TwelvedataRuby::ResponseError` instance if the API, or the API web server responded with some errors. #5 is an example which the API response will have status error with 401 code. `TwelvedataRuby::Response` resolves this into `TwelvedataRuby::UnauthorizedResponseError` instance.
-- `TwelvedataRuby::ResponseError` instance object itself when some error occurred that's not coming from the API
-- a Hash instance which has an `:errors` key that contains instances of kind `TwelvedataRuby::EndpointError`. This is an invalid request scenario which the #7, #8, and #9 examples. No actual API request was sent in this scenario.
-
-On first invocation of a valid endpoint name, a `TwelvedataRuby::Client` instance method of the same name is dynamically defined. So in effect, ideally, there can be a one-to-one mapping of all the API endpoints with their respective parameters constraints. Please visit their excellent API documentation to know more of the endpoint details here https://twelvedata.com/doc. Or if you're in a hurry, you can list the endpoints definitions:
+# Available stocks
+client.stocks(exchange: "NASDAQ")
+
+# ETF information
+client.etf
+
+# Market indices
+client.indices
+
+# Stock exchanges
+client.exchanges
+
+# Technical indicators
+client.technical_indicators
+```
+
+### Account & Usage
 
 ```ruby
-TwelvedataRuby::Endpoint.definitions
+# Check API usage
+usage = client.api_usage
+puts "Current usage: #{usage.parsed_body[:current_usage]}/#{usage.parsed_body[:plan_limit]}"
 ```
 
-Another way of fetching data from API endpoints is by building a valid `TwelvedataRuby::Request` instance, then invoke `#fetch` on this instance. The possible return values are the same with the above examples.
+## Advanced Usage
+
+### Response Formats
 
 ```ruby
-quote_req = TwelvedataRuby::Request.new(:quote, symbol: "IBM")
-quote_resp = quote_req.fetch
-timeseries_req = TwelvedataRuby::Request.new(:quote, symbol: "IBM", interval: "1hour", format: :csv)
-timeseries_resp = timeseries_req.fetch
-etd_req = TwelvedataRuby::Request.new(:etd, symbol: "GOOG")
-etd_resp = etd_req.fetch
-# or just simply chain
-price_resp = TwelvedataRuby::Request.new(:price, symbol: "GOOG").fetch
+# JSON response (default)
+response = client.quote(symbol: "AAPL", format: :json)
+data = response.parsed_body # Hash
+
+# CSV response
+response = client.quote(symbol: "AAPL", format: :csv)
+table = response.parsed_body # CSV::Table
+
+# Save CSV to file
+response = client.time_series(
+  symbol: "AAPL",
+  interval: "1day",
+  format: :csv,
+  filename: "apple_daily.csv"
+)
+response.save_to_file("./data/apple_data.csv")
 ```
 
-An advantage of building a valid request instance first then invoke the `#fetch` on it is you actually have an option to not send the request one by one BUT rather send them to the API server all at once simultaneously (might be in parallel). Like so taking the above examples' request instance objects, send them all simultaneously
+### Error Handling
 
 ```ruby
-# returns a 3 element array of Response objects
-resp_objects_array = TwelvedataRuby::Client.request(quote_req, timeseries_req, etd_req)
+response = client.quote(symbol: "INVALID")
+
+if response.error
+  case response.error
+  when TwelvedataRuby::UnauthorizedResponseError
+    puts "Invalid API key"
+  when TwelvedataRuby::NotFoundResponseError
+    puts "Symbol not found"
+  when TwelvedataRuby::TooManyRequestsResponseError
+    puts "Rate limit exceeded"
+  else
+    puts "Error: #{response.error.message}"
+  end
+else
+  puts response.parsed_body
+end
 ```
 
-Be caution that the above example, depending on the number request objects sent and how large the responses, hitting the daily limit is likely possible. But then again if you have several api keys you might be able to supply each request object with its own apikey. :)
+### Configuration Options
 
+```ruby
+client = TwelvedataRuby.client(
+  apikey: "your-api-key",
+  connect_timeout: 5000,  # milliseconds
+  apikey_env_var_name: "CUSTOM_API_KEY_VAR"
+)
+
+# Update configuration later
+client.configure(connect_timeout: 10000)
+
+# Or set individual options
+client.apikey = "new-api-key"
+client.connect_timeout = 3000
+```
 
-The data from a successful API request can be access from `Response#parsed_body`. If request format is `:json` then it will be a `Hash` instance
+### Concurrent Requests
 
 ```ruby
-TwelvedataRuby.client.quote(symbol: "GOOG").parsed_body
-=>
-{:symbol=>"GOOG",
- :name=>"Alphabet Inc",
- :exchange=>"NASDAQ",
- :currency=>"USD",
- :datetime=>"2021-07-15",
- :open=>"2650.00000",
- :high=>"2651.89990",
- :low=>"2611.95996",
- :close=>"2625.33008",
- :volume=>"828300",
- :previous_close=>"2641.64990",
- :change=>"-16.31982",
- :percent_change=>"-0.61779",
- :average_volume=>"850344",
- :fifty_two_week=>{:low=>"1406.55005", :high=>"2659.91992", :low_change=>"1218.78003", :high_change=>"-34.58984", :low_change_percent=>"86.65031", :high_change_percent=>"-1.30041", :range=>"1406.550049 - 2659.919922"}}
-```
-
-Likewise, if the API request format is `:csv` then `Response#parsed_body` will be `CSV#Table` instance
+# Create multiple requests
+requests = [
+  TwelvedataRuby::Request.new(:quote, symbol: "AAPL"),
+  TwelvedataRuby::Request.new(:quote, symbol: "GOOGL"),
+  TwelvedataRuby::Request.new(:quote, symbol: "MSFT")
+]
+
+# Send them concurrently
+responses = TwelvedataRuby::Client.request(requests)
+responses.each_with_index do |http_response, index|
+  response = TwelvedataRuby::Response.resolve(http_response, requests[index])
+  puts "#{requests[index].query_params[:symbol]}: #{response.parsed_body[:close]}"
+end
+```
+
+### Complex Data Queries
 
 ```ruby
-TwelvedataRuby.client.quote(symbol: "GOOG", format: :csv).parsed_body
-=> #<CSV::Table mode:col_or_row row_count:2>
+# POST request for complex data
+response = client.complex_data(
+  symbols: "AAPL,GOOGL,MSFT",
+  intervals: "1day,1week",
+  start_date: "2024-01-01",
+  end_date: "2024-01-31",
+  methods: "time_series"
+)
+```
+
+## Response Objects
+
+### Response Methods
+
+```ruby
+response = client.quote(symbol: "AAPL")
+
+# Response status
+response.success?           # => true/false
+response.http_status_code   # => 200
+response.status_code        # => API status code
+
+# Content information
+response.content_type       # => :json, :csv, :plain
+response.body_bytesize      # => response size in bytes
+
+# Parsed data
+response.parsed_body        # => Hash, CSV::Table, or String
+response.body              # => alias for parsed_body
+
+# Error information
+response.error             # => nil or ResponseError instance
+
+# File operations
+response.attachment_filename  # => "filename.csv" if present
+response.save_to_file("path/to/file.csv")
+response.dump_parsed_body     # => serialized content
+
+# Debugging
+response.to_s              # => human-readable summary
+response.inspect           # => detailed inspection
+```
+
+### Error Types
+
+```ruby
+# Base error types
+TwelvedataRuby::Error                    # Base error class
+TwelvedataRuby::ConfigurationError       # Configuration issues
+TwelvedataRuby::NetworkError            # Network connectivity issues
+
+# API endpoint errors
+TwelvedataRuby::EndpointError           # Invalid endpoint usage
+TwelvedataRuby::EndpointNameError       # Invalid endpoint name
+TwelvedataRuby::EndpointParametersKeysError     # Invalid parameters
+TwelvedataRuby::EndpointRequiredParametersError # Missing required parameters
+
+# API response errors
+TwelvedataRuby::ResponseError           # Base response error
+TwelvedataRuby::BadRequestResponseError         # 400 errors
+TwelvedataRuby::UnauthorizedResponseError       # 401 errors
+TwelvedataRuby::ForbiddenResponseError          # 403 errors
+TwelvedataRuby::NotFoundResponseError           # 404 errors
+TwelvedataRuby::TooManyRequestsResponseError    # 429 errors
+TwelvedataRuby::InternalServerResponseError     # 500 errors
+```
+
+## Available Endpoints
+
+| Endpoint                   | Method | Required Parameters                              | Description                |
+| -------------------------- | ------ | ------------------------------------------------ | -------------------------- |
+| `quote`                    | GET    | `symbol`                                         | Real-time stock quote      |
+| `price`                    | GET    | `symbol`                                         | Current stock price        |
+| `time_series`              | GET    | `symbol`, `interval`                             | Historical price data      |
+| `eod`                      | GET    | `symbol`                                         | End of day price           |
+| `exchange_rate`            | GET    | `symbol`                                         | Forex exchange rate        |
+| `currency_conversion`      | GET    | `symbol`, `amount`                               | Currency conversion        |
+| `symbol_search`            | GET    | `symbol`                                         | Search for symbols         |
+| `earliest_timestamp`       | GET    | `symbol`, `interval`                             | Earliest available data    |
+| `api_usage`                | GET    | -                                                | API usage statistics       |
+| `stocks`                   | GET    | -                                                | Available stocks           |
+| `forex_pairs`              | GET    | -                                                | Available forex pairs      |
+| `cryptocurrencies`         | GET    | -                                                | Available cryptocurrencies |
+| `etf`                      | GET    | -                                                | Available ETFs             |
+| `indices`                  | GET    | -                                                | Available indices          |
+| `exchanges`                | GET    | -                                                | Available exchanges        |
+| `cryptocurrency_exchanges` | GET    | -                                                | Available crypto exchanges |
+| `technical_indicators`     | GET    | -                                                | Available indicators       |
+| `earnings`                 | GET    | `symbol`                                         | Earnings data              |
+| `earnings_calendar`        | GET    | -                                                | Earnings calendar          |
+| `complex_data`             | POST   | `symbols`, `intervals`, `start_date`, `end_date` | Complex data queries       |
+
+For complete parameter documentation, visit [Twelve Data's API documentation](https://twelvedata.com/docs).
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with coverage
+COVERAGE=true bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/lib/twelvedata_ruby/client_spec.rb
+
+# Run with profile information
+PROFILE=true bundle exec rspec
+```
+
+### Code Quality
+
+```bash
+# Run RuboCop
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -A
+
+# Generate documentation
+bundle exec yard doc
+```
+
+### Debugging
+
+```ruby
+# Enable debugging output
+require 'pry'
+
+client = TwelvedataRuby.client(apikey: "your-key")
+response = client.quote(symbol: "AAPL")
+
+# Debug response
+binding.pry
+
+# Inspect request details
+puts response.request.to_h
+puts response.request.full_url
+puts response.request.query_params
 ```
 
-## Documentation
-You can browse the source code [documentation](https://kanroyalhigh.github.io/twelvedata_ruby/doc/)
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/twelvedata_ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/twelvedata_ruby/blob/master/CODE_OF_CONDUCT.md).
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes with tests
+4. Run the test suite (`bundle exec rspec`)
+5. Run RuboCop (`bundle exec rubocop`)
+6. Commit your changes (`git commit -am 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+## Release Process
+
+#### Quick Release Guide
+
+```bash
+# 1. Prepare release
+bin/release prepare --version 0.4.1
+
+# 2. Push changes
+git push origin main
+
+# 3. Create GitHub release with tag v0.4.1
+# → Automatic publication to RubyGems.org via GitHub Actions
+```
+
+#### Release Helper Commands
+
+```bash
+# Check if ready for release
+bin/release check
+
+# Auto-bump version
+bin/release bump --type patch    # 0.4.0 → 0.4.1
+bin/release bump --type minor    # 0.4.0 → 0.5.0
+bin/release bump --type major    # 0.4.0 → 1.0.0
+
+# Dry run (test without changes)
+bin/release prepare --version 0.4.1 --dry-run
+```
+
+#### GitHub Workflows
+
+- **CI**: Runs tests, linting, and security scans on every push/PR
+- **Release**: Automatically publishes to RubyGems.org when GitHub release is created
+- **Documentation**: Updates GitHub Pages with latest API docs
+
+#### Manual Release (Advanced)
+
+```bash
+# Trigger release workflow manually
+gh workflow run release.yml \
+  --field version=0.4.1 \
+  --field dry_run=false
+```
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This gem is available as open source under the terms of the [MIT License](LICENSE).
 
 ## Code of Conduct
 
-Everyone interacting in the TwelvedataRuby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/twelvedata_ruby/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the TwelvedataRuby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Support
+
+- 📖 [API Documentation](https://kanutocd.github.io/twelvedata_ruby/doc/)
+- 🐛 [Issue Tracker](https://github.com/kanutocd/twelvedata_ruby/issues)
+- 📧 Email: kenneth.c.demanawa@gmail.com
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
+
+## Notice
 
+This is not an official Twelve Data Ruby library. The author of this gem is not affiliated with Twelve Data in any way, shape or form. Twelve Data APIs and data are Copyright © 2024 Twelve Data Pte. Ltd.
 
-# Notice
+---
 
-This is not an offical Twelve Data ruby library and the author of this gem is not affiliated with Twelve Data in any way, shape or form. Twelve Data APIs and data are Copyright © 2020 Twelve Data Pte. Ltd
+**Made with ❤️ by the Ruby community**

data/Rakefile

@@ -2,11 +2,117 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "rubocop/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+# RSpec tasks
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = [
+    "--format", "progress",
+    "--color",
+    "--require", "spec_helper"
+  ]
+end
 
-require "rubocop/rake_task"
+# RuboCop tasks
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.options = ["--display-cop-names"]
+end
+
+RuboCop::RakeTask.new("rubocop:auto_correct") do |task|
+  task.options = ["--auto-correct"]
+end
+
+# Quality assurance task
+desc "Run all quality checks"
+task :qa do
+  puts "🔍 Running RuboCop..."
+  Rake::Task["rubocop"].invoke
+
+  puts "\n🧪 Running tests..."
+  Rake::Task["spec"].invoke
+
+  puts "\n✅ All quality checks passed!"
+rescue SystemExit => e
+  puts "\n❌ Quality checks failed!"
+  exit e.status
+end
+
+# Documentation tasks
+begin
+  require "yard"
+
+  YARD::Rake::YardocTask.new(:doc) do |task|
+    task.files = ["lib/**/*.rb"]
+    task.options = [
+      "--markup", "markdown",
+      "--markup-provider", "kramdown",
+      "--main", "README.md",
+      "--output-dir", "doc"
+    ]
+  end
+
+  desc "Generate and open documentation"
+  task docs: :doc do
+    system("open doc/index.html") if RUBY_PLATFORM.include?("darwin")
+  end
+rescue LoadError
+  puts "YARD not available. Install it with: gem install yard"
+end
+
+# Coverage task
+desc "Run tests with coverage report"
+task :coverage do
+  ENV["COVERAGE"] = "true"
+  Rake::Task["spec"].invoke
+end
+
+# Development setup task
+desc "Set up development environment"
+task :setup do
+  puts "📦 Installing dependencies..."
+  system("bundle install")
+
+  puts "🔧 Setting up git hooks..."
+  setup_git_hooks
+
+  puts "✅ Development environment ready!"
+end
+
+# Release preparation task
+desc "Prepare for release"
+task :release_prep do
+  puts "🔍 Running quality checks..."
+  Rake::Task["qa"].invoke
+
+  puts "📚 Generating documentation..."
+  Rake::Task["doc"].invoke if defined?(YARD)
+
+  puts "✅ Ready for release!"
+end
+
+# Console task for development
+desc "Start interactive console with gem loaded"
+task :console do
+  require "irb"
+  require "twelvedata_ruby"
+  ARGV.clear
+  IRB.start
+end
+
+# Default task
+task default: :qa
+
+# Helper methods
+def setup_git_hooks
+  hooks_dir = File.join(__dir__, ".git", "hooks")
+  return unless Dir.exist?(hooks_dir)
 
-RuboCop::RakeTask.new
+  pre_commit_hook = File.join(hooks_dir, "pre-commit")
+  File.write(pre_commit_hook, <<~HOOK)
+    #!/bin/sh
+    echo "Running pre-commit checks..."
+    bundle exec rubocop --format simple
+  HOOK
 
-task default: %i[spec rubocop]
+  File.chmod(0o755, pre_commit_hook) if File.exist?(pre_commit_hook)
+end