exchangeratesapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef9e9997eae5b2ccf694e05a3366d5962d2193705eaf56ae332794bf05b79920
+  data.tar.gz: c2a7b9ecb02a80da408c7f20689b4725330477a59db832a769599993c97f6cbf
+SHA512:
+  metadata.gz: cebb2c92e30e7d28688a29c7d476cf69ad1c0e1fe29fce9460618c7eb8485abf8b2609bef3ae6d0f62ea3b56708fd1c4eef95c34b6bf6cbef7345b3ce18f3166
+  data.tar.gz: fd8a9be97cb2533a8fa6b08d943a7b8412330b1e468285d56d6b825eac715e4c98a5ae0853a2deaf4ed58faad10dea8cc347634e442e96166caeac7ee96c91b3

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+- Initial release of the Exchange Rates API client gem
+- Support for latest exchange rates
+- Support for historical exchange rates
+- Support for currency conversion
+- Support for getting supported currencies
+- Support for time series data (paid plan)
+- Support for fluctuation data (paid plan)
+- Comprehensive error handling with custom error classes
+- PayloadWrapper for easy response handling
+- Full test coverage with RSpec
+- VCR integration for API testing 

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mehul Jain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,214 @@
+# Exchange Rates API Client
+
+A simple and efficient Ruby client for the [Exchange Rates API](https://exchangeratesapi.io/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'exchangeratesapi'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install exchangeratesapi
+```
+
+## Usage
+
+### Basic Setup
+
+```ruby
+require 'exchangeratesapi'
+
+# Initialize with API key
+client = ExchangeRatesAPI.new('your_api_key_here')
+
+# Or use environment variable
+ENV['EXCHANGE_RATE_API_KEY'] = 'your_api_key_here'
+client = ExchangeRatesAPI.new
+```
+
+### Get Latest Exchange Rates
+
+```ruby
+# Get latest rates with USD as base currency
+response = client.latest(from_currency: 'USD', to_currency: 'EUR,GBP')
+
+puts response.success?        # => true
+puts response.base           # => "USD"
+puts response.date           # => "2024-01-15"
+puts response.rates['EUR']   # => 0.85
+puts response.rates['GBP']   # => 0.73
+
+# Get all available rates (no to_currency specified)
+response = client.latest(from_currency: 'USD')
+```
+
+### Get Historical Exchange Rates
+
+```ruby
+# Get rates for a specific date
+response = client.historical('2024-01-01', from_currency: 'USD', to_currency: 'EUR')
+
+puts response.historical?    # => true
+puts response.date          # => "2024-01-01"
+puts response.rates['EUR']  # => 0.84
+```
+
+### Currency Conversion
+
+```ruby
+# Convert 100 USD to EUR
+result = client.convert(amount: 100, from_currency: 'USD', to_currency: 'EUR')
+
+puts result[:amount]           # => 100
+puts result[:from_currency]    # => "USD"
+puts result[:to_currency]      # => "EUR"
+puts result[:rate]             # => 0.85
+puts result[:converted_amount] # => 85.0
+puts result[:date]             # => "2024-01-15"
+
+# Convert with historical rates
+result = client.convert(
+  amount: 100,
+  from_currency: 'USD',
+  to_currency: 'EUR',
+  date: '2024-01-01'
+)
+```
+
+### Get Supported Currencies
+
+```ruby
+response = client.currencies
+
+response.symbols.each do |code, info|
+  puts "#{code}: #{info['description']}"
+end
+# => USD: United States Dollar
+# => EUR: Euro
+# => GBP: British Pound Sterling
+# ...
+```
+
+### Get Exchange Rate for Specific Currencies
+
+```ruby
+# Get current rate
+response = client.exchange_rate(from_currency: 'USD', to_currency: 'EUR')
+
+# Get historical rate
+response = client.exchange_rate(
+  from_currency: 'USD',
+  to_currency: 'EUR',
+  date: '2024-01-01'
+)
+```
+
+### Advanced Features (Paid Plans)
+
+#### Time Series Data
+
+```ruby
+response = client.time_series(
+  start_date: '2024-01-01',
+  end_date: '2024-01-31',
+  from_currency: 'USD',
+  to_currency: 'EUR'
+)
+```
+
+#### Fluctuation Data
+
+```ruby
+response = client.fluctuation(
+  start_date: '2024-01-01',
+  end_date: '2024-01-31',
+  from_currency: 'USD',
+  to_currency: 'EUR'
+)
+```
+
+## Error Handling
+
+The gem provides specific error classes for different types of errors:
+
+```ruby
+begin
+  response = client.latest
+rescue ExchangeRatesAPI::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue ExchangeRatesAPI::RateLimitError => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue ExchangeRatesAPI::ServerError => e
+  puts "Server error: #{e.message}"
+rescue ExchangeRatesAPI::RequestError => e
+  puts "Request error: #{e.message}"
+end
+```
+
+## Response Wrapper
+
+All API responses are wrapped in a `PayloadWrapper` object that provides convenient access to response data:
+
+```ruby
+response = client.latest(from_currency: 'USD', to_currency: 'EUR')
+
+# Direct access to response data
+response.success?     # => true/false
+response.base        # => base currency
+response.date        # => date of rates
+response.rates       # => hash of rates
+response.timestamp   # => Unix timestamp
+response.historical? # => true for historical data
+
+# Check for errors
+if response.error?
+  error_info = response.error_info
+  puts "Error: #{error_info['message']} (Code: #{error_info['code']})"
+end
+
+# Convert to hash or JSON
+response.to_h        # => original response hash
+response.to_json     # => JSON string
+```
+
+## Configuration
+
+### Environment Variables
+
+- `EXCHANGE_RATE_API_KEY`: Your API key from exchangeratesapi.io
+- `EXCHANGE_RATE_API_BASE`: Custom base URL (optional, defaults to https://api.exchangeratesapi.io/v1)
+
+### Custom Base URL
+
+```ruby
+client = ExchangeRatesAPI.new('your_api_key', 'https://custom.api.com/v1')
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mehul/exchangeratesapi. 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/mehul/exchangeratesapi/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ExchangeRatesAPI project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mehul/exchangeratesapi/blob/main/CODE_OF_CONDUCT.md).

data/lib/exchangeratesapi/client.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module ExchangeRatesAPI
+  class Client
+    include HTTParty
+    base_uri "https://api.exchangeratesapi.io/v1"
+
+    attr_reader :api_key, :base_url
+
+    def initialize(api_key = nil, base_url = nil)
+      @api_key = api_key || ENV.fetch("EXCHANGE_RATE_API_KEY", nil)
+      @base_url = base_url || ENV.fetch("EXCHANGE_RATE_API_BASE", "https://api.exchangeratesapi.io/v1")
+      
+      # Set the base URI for HTTParty
+      self.class.base_uri @base_url
+    end
+
+    # Get latest exchange rates
+    # @param from_currency [String] Base currency (e.g., "USD")
+    # @param to_currency [String] Target currency (e.g., "EUR") or comma-separated list
+    # @return [PayloadWrapper] Response wrapped in PayloadWrapper
+    def latest(from_currency: "EUR", to_currency: nil)
+      params = { base: from_currency }
+      params[:symbols] = to_currency if to_currency
+      
+      response = execute_request("get", "/latest", params)
+      parse_and_raise_error(response) unless success_response?(response)
+      PayloadWrapper.new(response.parsed_response)
+    end
+
+    # Get historical exchange rates
+    # @param date [String] Date in YYYY-MM-DD format
+    # @param from_currency [String] Base currency (e.g., "USD")
+    # @param to_currency [String] Target currency (e.g., "EUR") or comma-separated list
+    # @return [PayloadWrapper] Response wrapped in PayloadWrapper
+    def historical(date, from_currency: "EUR", to_currency: nil)
+      params = { base: from_currency }
+      params[:symbols] = to_currency if to_currency
+      
+      response = execute_request("get", "/#{date}", params)
+      parse_and_raise_error(response) unless success_response?(response)
+      PayloadWrapper.new(response.parsed_response)
+    end
+
+    # Get exchange rate for specific currencies
+    # @param from_currency [String] Base currency (e.g., "USD")
+    # @param to_currency [String] Target currency (e.g., "EUR")
+    # @param date [String, nil] Optional date in YYYY-MM-DD format for historical rates
+    # @return [PayloadWrapper] Response wrapped in PayloadWrapper
+    def exchange_rate(from_currency:, to_currency:, date: nil)
+      if date
+        historical(date, from_currency: from_currency, to_currency: to_currency)
+      else
+        latest(from_currency: from_currency, to_currency: to_currency)
+      end
+    end
+
+    # Get supported currencies
+    # @return [PayloadWrapper] Response wrapped in PayloadWrapper
+    def currencies
+      response = execute_request("get", "/symbols")
+      parse_and_raise_error(response) unless success_response?(response)
+      PayloadWrapper.new(response.parsed_response)
+    end
+
+    # Convert amount between currencies
+    # @param amount [Numeric] Amount to convert
+    # @param from_currency [String] Source currency (e.g., "USD")
+    # @param to_currency [String] Target currency (e.g., "EUR")
+    # @param date [String, nil] Optional date in YYYY-MM-DD format for historical rates
+    # @return [Hash] Conversion result with amount and rate
+    def convert(amount:, from_currency:, to_currency:, date: nil)
+      response = exchange_rate(
+        from_currency: from_currency,
+        to_currency: to_currency,
+        date: date
+      )
+      
+      rate = response.rates[to_currency]
+      raise ExchangeRatesAPI::Error.new("Rate not found for #{to_currency}") if rate.nil?
+      converted_amount = amount * rate
+      
+      {
+        amount: amount,
+        from_currency: from_currency,
+        to_currency: to_currency,
+        rate: rate,
+        converted_amount: converted_amount,
+        date: response.date
+      }
+    end
+
+    # Get time series data (requires paid plan)
+    # @param start_date [String] Start date in YYYY-MM-DD format
+    # @param end_date [String] End date in YYYY-MM-DD format
+    # @param from_currency [String] Base currency (e.g., "USD")
+    # @param to_currency [String] Target currency (e.g., "EUR")
+    # @return [PayloadWrapper] Response wrapped in PayloadWrapper
+    def time_series(start_date:, end_date:, from_currency: "EUR", to_currency:)
+      params = {
+        base: from_currency,
+        symbols: to_currency,
+        start_date: start_date,
+        end_date: end_date
+      }
+      
+      response = execute_request("get", "/timeseries", params)
+      parse_and_raise_error(response) unless success_response?(response)
+      PayloadWrapper.new(response.parsed_response)
+    end
+
+    # Get fluctuation data (requires paid plan)
+    # @param start_date [String] Start date in YYYY-MM-DD format
+    # @param end_date [String] End date in YYYY-MM-DD format
+    # @param from_currency [String] Base currency (e.g., "USD")
+    # @param to_currency [String] Target currency (e.g., "EUR")
+    # @return [PayloadWrapper] Response wrapped in PayloadWrapper
+    def fluctuation(start_date:, end_date:, from_currency: "EUR", to_currency:)
+      params = {
+        base: from_currency,
+        symbols: to_currency,
+        start_date: start_date,
+        end_date: end_date
+      }
+      
+      response = execute_request("get", "/fluctuation", params)
+      parse_and_raise_error(response) unless success_response?(response)
+      PayloadWrapper.new(response.parsed_response)
+    end
+
+    private
+
+    def execute_request(method, endpoint, params = {})
+      # Add API key to params if available
+      params[:access_key] = api_key if api_key
+      
+      # Build URL with query parameters
+      uri = URI("#{base_url}#{endpoint}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      
+      self.class.send(method, uri.to_s, headers: default_headers)
+    end
+
+    def default_headers
+      { "Content-Type" => "application/json" }
+    end
+
+    def parse_and_raise_error(response)
+      if response.code.to_s.start_with?("5")
+        raise_error(ServerError, response)
+      elsif response.code == 401
+        raise_error(AuthenticationError, response)
+      elsif response.code == 429
+        raise_error(RateLimitError, response)
+      else
+        raise_error(RequestError, response)
+      end
+    end
+
+    def raise_error(error_class, response)
+      error_message = "Error processing request: #{response.code}"
+      
+      if response.parsed_response && response.parsed_response["error"]
+        error_info = response.parsed_response["error"]
+        error_message = "#{error_message} - #{error_info['info']} (Code: #{error_info['code']})"
+      end
+      
+      raise error_class.new(error_message, error_response: response)
+    end
+
+    def success_response?(response)
+      response.code == 200
+    end
+  end
+end 

data/lib/exchangeratesapi/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ExchangeRatesAPI
+  class Error < StandardError
+    attr_reader :error_response
+
+    def initialize(message = nil, error_response: nil)
+      @error_response = error_response
+      super(message || "Exchange Rates API error")
+    end
+  end
+
+  class RequestError < Error
+    def initialize(message = nil, error_response: nil)
+      super(message, error_response: error_response)
+    end
+  end
+
+  class ServerError < Error
+    def initialize(message = nil, error_response: nil)
+      super(message, error_response: error_response)
+    end
+  end
+
+  class AuthenticationError < Error
+    def initialize(message = nil, error_response: nil)
+      super(message || "Authentication failed", error_response: error_response)
+    end
+  end
+
+  class RateLimitError < Error
+    def initialize(message = nil, error_response: nil)
+      super(message || "Rate limit exceeded", error_response: error_response)
+    end
+  end
+end 

data/lib/exchangeratesapi/payload_wrapper.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ExchangeRatesAPI
+  class PayloadWrapper
+    attr_reader :data
+
+    def initialize(data)
+      @data = data
+    end
+
+    def success?
+      data["success"] == true
+    end
+
+    def base
+      data["base"]
+    end
+
+    def date
+      data["date"]
+    end
+
+    def rates
+      data["rates"] || {}
+    end
+
+    def timestamp
+      data["timestamp"]
+    end
+
+    def historical?
+      data["historical"] == true
+    end
+
+    def error?
+      !data["error"].nil?
+    end
+
+    def error_info
+      return nil unless error?
+      {
+        "code" => data["error"]["code"],
+        "message" => data["error"]["info"]
+      }
+    end
+
+    def to_h
+      data
+    end
+
+    def to_json
+      data.to_json
+    end
+
+    def method_missing(method_name, *args, &block)
+      if data.respond_to?(method_name)
+        data.send(method_name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      data.respond_to?(method_name) || super
+    end
+  end
+end 

data/lib/exchangeratesapi/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ExchangeRatesAPI
+  VERSION = "0.1.0"
+end 

data/lib/exchangeratesapi.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+
+require_relative "exchangeratesapi/version"
+require_relative "exchangeratesapi/client"
+require_relative "exchangeratesapi/errors"
+require_relative "exchangeratesapi/payload_wrapper"
+
+module ExchangeRatesAPI
+  class << self
+    def new(api_key = nil, base_url = nil)
+      Client.new(api_key, base_url)
+    end
+  end
+end 

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: exchangeratesapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mehul Jain
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-07-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A simple and efficient Ruby client for the Exchange Rates API (exchangeratesapi.io)
+email:
+- mehul@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/exchangeratesapi.rb
+- lib/exchangeratesapi/client.rb
+- lib/exchangeratesapi/errors.rb
+- lib/exchangeratesapi/payload_wrapper.rb
+- lib/exchangeratesapi/version.rb
+homepage: https://github.com/mehul/exchangeratesapi
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mehul/exchangeratesapi
+  source_code_uri: https://github.com/mehul/exchangeratesapi
+  changelog_uri: https://github.com/mehul/exchangeratesapi/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: Ruby client for the Exchange Rates API
+test_files: []