apilayer 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2c90421964d0e4f1e87b8dd237cc9fd9829828d4
-  data.tar.gz: 0d134f0f06cfa93e4c1aeb7bab7cebf2b48f4d4c
+  metadata.gz: 741fe800b4155a1935d910a84c38bcae92be05cf
+  data.tar.gz: 6eb86705872f060ee900f3aeb286f92c5abf5e2c
 SHA512:
-  metadata.gz: cc9197e568e72415aca957bff9eebcdcac94be67a5e17c5b6d78822808c4828675eadbf1efb1726693fd309d1cbce578cc43746ef5905fce46924a90681cbdc3
-  data.tar.gz: 5559cc9b38fbdf4f34b92727b58c3d03f6b3222b5ade671a25708596e2f573a1a938c45786af2f77fc3a9871bfb1260a33f7f8bd62bd64b5204b51545fb122d0
+  metadata.gz: bca4854b31225c90b787f3d63bed8134a0bc13ab4ef262f4b99ad76f5a898208e91b9439c01329c1b5e06f2b4b2bf264d20a98b880c8240f9acf5b8f704414b0
+  data.tar.gz: a37bfb3f5e8923a56ce13cbd99e3c005fe3cc34c38b7b6fdd73c649f6e3575549e062afd6cad651f299ab57648ef63e2e7bf72f681af50b12d5743933bb2e58c

data/README.rdoc

@@ -0,0 +1,64 @@
+== apilayer {<img src="https://secure.travis-ci.org/actfong/apilayer.png"/>}[http://travis-ci.org/actfong/apilayer] {<img src="https://codeclimate.com/github/actfong/apilayer.png"/>}[https://codeclimate.com/github/actfong/apilayer] {<img src="https://badge.fury.io/rb/apilayer.svg" alt="Gem Version" />}[https://badge.fury.io/rb/apilayer] 
+
+Ruby wrapper for various services of apilayer.
+See http://apilayer.com for more details.
+
+=== Version 1.0
+For this version, only the API-features that are available to the free accounts are supported. See the documentation of http://currencylayer.com and http://vatlayer.com for more details.
+
+=== Installation
+
+==== Using Bundler
+
+Add apilayer in your <tt>Gemfile</tt>:
+
+  gem "apilayer"
+
+Run the following in your console:
+
+  $ bundle install
+  
+=== Usage
+
+==== Set up Apilayer
+Once you sign up for a service of *apilayer*, you will receive an access_key. Please pay attention that different services of apilayer (such as *vatlayer* and *currencylayer*) have different access keys.
+
+Then you can use your access_key(s) to configure your Apilayer module like this:
+
+  Apilayer.configure do |configs|
+    configs.vat_key = "my_vatlayer_access_key_123"
+    configs.currency_key = "my_currencylayer_access_key_123"
+  end
+
+Please note that you don't need to assign keys for both services. You only need to assign the key for the service you have signed up for.
+
+Once that is done, you are ready to go
+
+==== currencylayer
+After setting the access_key for *currencylayer*, you can use Apilayer::Currency to call *currencylayer*'s API
+  Apilayer::Currency.live
+  Apilayer::Currency.live("EUR", "GBP", "CHF")
+  
+  Apilayer::Currency.historical("2016-01-01")
+  Apilayer::Currency.historical("2016-01-01", "EUR", "GBP", "CHF")
+
+==== vatlayer
+
+After setting the access_key for *vatlayer*, you can use Apilayer::Vat to call *vatlayer*'s API
+
+  Apilayer::Vat.validate("LU26375245")
+  Apilayer::Vat.rate(:country_code, "NL")
+  Apilayer::Vat.rate(:ip_address, "176.249.153.36")
+  Apilayer::Vat.rate_list
+  Apilayer::Vat.price(100, :country, "NL")
+  Apilayer::Vat.price(100, :ip_address, "176.249.153.36")
+  
+==== Re-Configure Apilayer's access_keys
+If you happened to have forgotten to provide an access_key or entered an incorrect one, you can re-configure your Apilayer module by:
+
+  # Example: reconfigure access_key for vatlayer
+  Apilayer::Vatlayer.reset_connection
+  Apilayer.configure do |configs|
+    configs.vat_key = "my_valid_key_123"
+  end
+  

data/lib/apilayer/connection_helper.rb

@@ -1,15 +1,29 @@
 module Apilayer
   module ConnectionHelper
 
+    ##
+    # Creates a connection for the extended module to an apilayer-service, such as currencylayer and vatlayer.
+    # Uses access_key(s) configured with Apilayer module.
+    def connection
+      @connection ||= ::Faraday.new(:url => 'http://apilayer.net',
+        :params => {"access_key" => Apilayer.configs[self.const_get(:APILAYER_CONFIG_KEY)]})
+    end
+
+    ##
+    # Resets the connection for the extended module. Used when the user needs to re-enter his/her access_key(s)
     def reset_connection
       @connection = nil
     end
 
+    ##
+    # Makes a get-request to apilayer's service and parses the JSON response into a Hash
     def get_and_parse(url, params={})
       resp = get_request(url, params)
       parse_response(resp)
     end
 
+    ##
+    # Makes a get-request to apilayer's service
     def get_request(url, params={})
       # calls connection method on the extended module
       connection.get do |req|
@@ -20,6 +34,9 @@ module Apilayer
       end
     end
 
+    ##
+    # Parses the JSON response from apilayer into a Hash
+    # When errors are returned by apilayer, the 'info' and 'code' from its error will be used to raise an Apilayer::Error
     def parse_response(resp)
       body = JSON.parse(resp.body)
       # According to documentation, currencylayer has a "success" field 

data/lib/apilayer/currency.rb

@@ -1,14 +1,23 @@
+##
+# Ruby wrapper for currencylayer. See https://currencylayer.com/documentation for more info
 module Apilayer
   module Currency
     extend ConnectionHelper
 
-    CURRENCYLAYER_KEY_MISSING_MSG = "Please configure access_key for currency_layer first!"
+    ##
+    # Determines which access_key in Apilayer.configs to use 
+    # in order to to make a connection to currencylayer
+    APILAYER_CONFIG_KEY = :currency_key
 
-    def self.connection
-      @connection ||= ::Faraday.new(:url => 'http://apilayer.net', 
-                                    :params => {"access_key" => Apilayer.configs[:currency_key]})
-    end
+    ### API methods
+    #
 
+    ##
+    # Api-Method: Calls the /live endpoint to get real-time exchange rates.
+    # When no currency-codes are specified, it will return all exchange rates for your source-currency.
+    # Example:
+    #   Apilayer::Currency.live
+    #   Apilayer::Currency.live("EUR", "GBP", "CHF")
     def self.live(*currencies)
       if currencies.any?
         currencies_str = join_by_commas(currencies)
@@ -19,19 +28,20 @@ module Apilayer
       end
     end
 
+    ##
+    # Api-Method: Calls the /historical endpoint to get exchange rates for a specific date.
+    # When no currency-codes are specified, it will return all exchange rates for your source-currency.
+    # Example:
+    #   Apilayer::Currency.historical("2016-01-01")
+    #   Apilayer::Currency.historical("2016-01-01", "EUR", "GBP", "CHF")
     def self.historical(date, *currencies)      
       params = {:date => date}
       params.merge!(:currencies => join_by_commas(currencies)) if currencies.any?
       get_and_parse("historical", params)
     end
 
-=begin
-    def self.convert(from, to, amount, date=nil)
-      params = {:from => from, :to => to, :amount => amount}
-      params.merge!(:date => date) if date
-      get_and_parse("convert", params)
-    end
-=end
+    ##
+    # Joins currencies in an array as a comma-separated-string
     def self.join_by_commas(currencies)
       currencies.map(&:strip).join(",")
     end

data/lib/apilayer/error.rb

@@ -1,3 +1,5 @@
+##
+# Error-class for errors that are returned by apilayer's services
 module Apilayer
   class Error < StandardError
     attr_reader :code

data/lib/apilayer/vat.rb

@@ -1,36 +1,63 @@
+##
+# Ruby wrapper for vatlayer. See https://vatlayer.com/documentation for more info
 module Apilayer
   module Vat
     extend ConnectionHelper
 
     COUNTRY_CRITERIA_MISSING_MSG = "You must provide either :country_code or :ip_address"
-    VATLAYER_KEY_MISSING_MSG = "Please configure access_key for vat_layer first!"
 
-    def self.connection
-      @connection ||= ::Faraday.new(:url => 'http://apilayer.net',
-                                    :params => {"access_key" => Apilayer.configs[:vat_key]})
-    end
+    ##
+    # Determines which access_key in Apilayer.configs to use 
+    # in order to make a connection to vatlayer
+    APILAYER_CONFIG_KEY = :vat_key
 
+    ##
+    # Validates whether a supported criteria has been provided to .rate and .price
     def self.validate_country_criteria(criteria)
       unless [:country_code, :ip_address].include? criteria
         raise Apilayer::Error.new COUNTRY_CRITERIA_MISSING_MSG
       end
     end
 
+    ### API methods
+    #
+
+    ##
+    # Api-Method: Calls the /validate endpoint to validate a given VAT-number.
+    # Example:
+    #   Apilayer::Vat.validate("LU26375245")
     def self.validate(vat_number)
       params = {:vat_number => vat_number}
       get_and_parse("validate", params)
     end
 
+    ##
+    # Api-Method: Calls the /rate endpoint to get the VAT-rate of a given country, 
+    # based on country-code or ip-address.
+    # Example:
+    #   Apilayer::Vat.rate(:country_code, "NL")
+    #   Apilayer::Vat.rate(:ip_address, "176.249.153.36")
     def self.rate(criteria, value)
       validate_country_criteria(criteria)
       params = {criteria.to_sym => value}
       get_and_parse("rate", params)
     end
 
+    ##
+    # Api-Method: Calls the /rate_list endpoint to get the standard and reduced VAT-rates
+    # for all EU countries.
+    # Example:
+    #   Apilayer::Vat.rate_list
     def self.rate_list
       get_and_parse("rate_list")
     end
 
+    ##
+    # Api-Method: Calls the /price endpoint to get price including and excluding VAT 
+    # for a given price and country. It also returns the VAT rate for that country
+    # Example:
+    #   Apilayer::Vat.price(100, :country, "NL")
+    #   Apilayer::Vat.price(100, :ip_address, "176.249.153.36")
     def self.price(price, criteria, value)
       validate_country_criteria(criteria)
       params = {:amount => price, criteria.to_sym => value}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apilayer
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Alex Fong
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-10 00:00:00.000000000 Z
+date: 2016-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -50,6 +50,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.1
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -110,6 +130,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.11.0
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -190,6 +230,6 @@ rubyforge_project:
 rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
-summary: Ruby wrapper for various services of apilayer. See https://apilayer.com/
-  for more details.
+summary: Ruby wrapper for currencylayer and vatlayer from apilayer.com. For more info,
+  see http://apilayer.com
 test_files: []