volabit 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3a051bef9491dd7c9dd9e355908101508ecee078
-  data.tar.gz: 4fe851e275af21008e9366687ed9ae2e4d5dfc76
+  metadata.gz: eee00815e91c6b9ef5675445fbec8583f0933994
+  data.tar.gz: b29d96bb6053d3afd0767cb0161d26dbb827f69a
 SHA512:
-  metadata.gz: b54d6f318b4bc0bb1988c8cf8042e2e94443734564dfe587fc65837a1c79a4211ed1b796bd8d53c8940cc55499efc9ff7aed915e08297822820d75ee442ac9e4
-  data.tar.gz: 09a5e247a2ac8ca02790d418a769376492d00124a519d8eed2cfb47d8e3e8cb10d4e7e1852e022776a41572af19814ff7e1bd33a035d9512b478e57f9ceeb413
+  metadata.gz: 8474154744464f82bd1d6c05608e6c7f2b812dc9235bc7be2284d639c3395d089040d19a96319f7b541fa4e390547126341693927c6918ed4868447b04cf5439
+  data.tar.gz: e004c534fbf1b59ab8f0db75acd69ca030e144a31ab1cd0aa427d1c6c02c5e373465671b7553e7a1b11de6fd062325b26fc0ab7e4b116254a644acea79017b9a

data/CHANGELOG.md

@@ -1,23 +1,35 @@
 
 # Change Log
+You can see the supported releases on the [project GitHub repository](http://https://github.com/coincovemx/ruby-api-client/releases).
 
 ## To Do
 - Add specs.
 - Add proper docs.
 - Automatics test suite run. (Codeship)
-- Check methods that require special permissions and bitcoin/pesos funds.
 
-## [Unreleased](unreleased)
+## Unreleased
 ### Added
 - No recent changes.
 
-## [v0.0.1](v0.0.1)
+## v1.1.0
+### Added
+- Better token handling with `tokens`, `request_tokens`, `ùse_tokens` and `refresh_tokens` available from the client public methods.
+- Aliases for the methods with name changes.
+- `send_money` (`send_funds`) method replaces the `send` method to avoid the clash with the `Òbject#send` method.
+- ArgumentError exceptions for params on methods that use them to build the resource URL.
+
+###Fixed
+- Refreshing the tokens now correctly sets the newly obtained tokens.
+- `Client#new_payment` docs tell that the method is available to all the users.
+
+### Removed
+- `send` method. Use `send_money` method from now on.
+
+## v1.0.0
+### Added
 - OAuth2 integration.
 - Exchange rates wrappers.
 - Users wrappers.
 - Transactions wrappers.
 - Slips wrappers.
 - Merchants wrappers.
-
-[v0.0.1]: https://github.com/coincovemx/api-client/tree/v0.0.1
-[unreleased]: http://https://github.com/coincovemx/api-client/tree/development

data/LICENSE.txt

@@ -1,4 +1,3 @@
-Copyright (c) 2015 David O' Rojo
 
 MIT License
 

data/README.md

@@ -1,8 +1,9 @@
+
 [![Gem Version](https://badge.fury.io/rb/volabit.svg)](http://badge.fury.io/rb/volabit)
 
 # Volabit
 
-Volabit's API Ruby library. Integrate the Volabit services in your apps with ease.
+Volabit's API library for Ruby. Integrate the Volabit services in your apps with ease.
 
 You can see the available methods on the [project wiki][wiki]. Details of the API use can be found on the [official page][api-docs].
 
@@ -20,8 +21,8 @@ And then execute:
 
 Or install it yourself as:
 
-    $ git clone https://github.com/coincovemx/api-client.git
-    $ cd api-client
+    $ git clone https://github.com/coincovemx/ruby-api-client.git
+    $ cd ruby-api-client
     $ bundle
     $ gem build volabit.gemspec
     $ gem install volabit-[version].gem
@@ -31,9 +32,9 @@ Or install it yourself as:
 1) Instance a new Volabit client object.
 
 ```ruby
-app_id      = 'The registered API for your APP.'
-secret      = 'The registered secret for your APP.'
-callback    = 'The registered callback URL for your APP'
+app_id   = 'The registered API for your APP.'
+secret   = 'The registered secret for your APP.'
+callback = 'The registered callback URL for your APP'
 
 volabit_client = Volabit::Client.new(app_id, secret, callback)
 ```
@@ -44,6 +45,13 @@ Note that by default the Volabit client uses the **production** environment. If
 volabit_client.sandbox true
 ```
 
+You can also provide this parameter upon client instantiation.
+
+```ruby
+environment    = 'sandbox'
+volabit_client = Volabit::Client.new(app_id, secret, callback, environment)
+```
+
 2) Get the URL that will allow the user to authorize your app to use his/her account. (It should be opened in a browser.)
 
 ```ruby
@@ -53,16 +61,16 @@ auth_url = volabit_client.authorize
 3) After you get the authorization code (sent at the callback URL that you provided), you'll use it to get the refresh and access tokens. This code can be used only once, so be sure to store the token object for later use or your app will have to be reauthorized.
 
 ```ruby
-volabit_client.get_token 'The given authorization code.'
+volabit_client.request_tokens 'The given authorization code.'
 ```
 
-4) If you already have a `token` and a `refresh_token` you can use:
+Or, if you already have a `token` and a `refresh_token` you can use:
 
 ```ruby
-volabit_client.use_token 'token', 'refresh_token'
+volabit_client.use_tokens 'token', 'refresh_token'
 ```
 
-5) You're ready to use our API. Just call any method listed [here][wiki].
+4) You're ready to use our API. Just call any method listed [here][wiki].
 
 ```ruby
 tickers = volabit_client.tickers
@@ -76,15 +84,16 @@ tickers = volabit_client.tickers
 #    }
 ```
 
+**Note**: You can obtain the current tokens used by the client with the method `Client#tokens`. Be sure to keep them **safe** withing your application for later use.
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/volabit/fork )
+1. Fork it ( https://github.com/[my-github-username]/ruby-api-client/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
 
 
-[wiki]: https://github.com/coincovemx/api-client/wiki
+[wiki]: https://github.com/coincovemx/ruby-api-client/wiki
 [api-docs]: https://coincovemx.github.io/

data/lib/volabit.rb

@@ -4,6 +4,8 @@ require_relative 'volabit/api'
 require_relative 'volabit/version'
 
 module Volabit
+
+  # Class that handles authorizations and API calls.
   class Client
     include Auth
     include API

data/lib/volabit/api.rb

@@ -8,30 +8,19 @@ module Volabit
   module API
     private
 
-    # Request a resource using the GET method.
-    def get_resource(resource, params = nil)
-      raise no_token_error unless @token
-      @token.refresh if @token.expired?
-      response = @token.get(resource, params: params)
-      JSON.parse response.body, :symbolize_names => true
-    end
-
-    def post_to_resource(resource, params)
-      raise no_token_error unless @token
-      @token.refresh if @token.expired?
-      response = @token.post(resource, params: params)
-      JSON.parse response.body, :symbolize_names => true
-    end
+    # Request given resource using the provided method and params.
+    def resource(verb, resource, params = nil)
+      no_token_error unless @token
+      refresh_tokens if @token.expired?
 
-    def delete_resource(resource)
-      raise no_token_error unless @token
-      @token.refresh if @token.expired?
-      response = @token.delete(resource)
+      response = @token.send(verb, resource, params: params)
       JSON.parse response.body, :symbolize_names => true
     end
 
+    # Raises an exception intended when there is no OAuth2::AccessToken
+    # available.
     def no_token_error
-      'Error: you have to run get_token or set_token before use this method.'
+      raise StandardError, 'Call get_tokens or use_tokens before this method.'
     end
   end
 end

data/lib/volabit/api/rates.rb

@@ -4,16 +4,25 @@ module Rates
   # Gets the exchange price from certain currency amount to other currency.
   # @note BTC units are expected in satoshis. Other currencies units are
   #       expected in cents.
-  def spot_prices(amount:, from: 'BTC', to: 'MXN')
-    raise ArgumentError, 'Currencies must be different.' if from.eql? to
-    get_resource 'api/v1/spot-prices', {
-      currency_from: from, currency_to: to, amount: amount
+  def spot_prices(amount, from: 'BTC', to: 'MXN')
+    same_currencies_error if from.eql? to
+
+    resource :get, 'api/v1/spot-prices', {
+      currency_from: from,
+      currency_to: to,
+      amount: amount
     }
   end
 
   # Gets the exchange price list for the supported currencies.
   def tickers
-    get_resource 'api/v1/tickers'
+    resource :get, 'api/v1/tickers'
+  end
+
+  private
+
+  def same_currencies_error
+    raise ArgumentError, 'Currencies must be different.'
   end
 end
 

data/lib/volabit/api/slips.rb

@@ -1,28 +1,35 @@
 
 # Methods to manage slips in the user wallet.
 module Slips
-  # Creates a slip you can use to load your wallet.
+  # Creates a slip that can be used to load the user wallet.
   def new_slip(currency:, amount:, type:)
-    post_to_resource 'api/v1/users/me/slips', {
+    resource :post, 'api/v1/users/me/slips', {
       currency: currency,
       amount: amount,
       type: type
     }
   end
 
+  alias_method :create_slip, :new_slip
+
   # Gets the information of a specific slip.
   def get_slip_data(id:)
-    get_resource "api/v1/users/me/slips/#{id}"
+    empty_param_error('id') if id.to_s.eql? ''
+    resource :get, "api/v1/users/me/slips/#{id}"
   end
 
+  alias_method :slip_data, :get_slip_data
+
   # Deletes a specific slip.
   def delete_slip(id:)
-    delete_resource "api/v1/users/me/slips/#{id}"
+    empty_param_error('id') if id.to_s.eql? ''
+    resource :delete, "api/v1/users/me/slips/#{id}"
   end
 
   # Informs of a receipt used to load a wallet's slip.
   def report_receipt(id:, amount:, affiliation:, authorization:)
-    post_to_resource "api/v1/users/me/slips/#{id}/report", {
+    empty_param_error('id') if id.to_s.eql? ''
+    resource :post, "api/v1/users/me/slips/#{id}/report", {
       amount: amount,
       affiliation_number: affiliation,
       authorization_number: authorization
@@ -31,7 +38,14 @@ module Slips
 
   # Lists the available options to load a slip.
   def get_load_methods
-    get_resource 'api/v1/users/me/slips/methods'
+    resource :get, 'api/v1/users/me/slips/methods'
+  end
+
+  alias_method :load_methods, :get_load_methods
+
+  private
+  def empty_param_error(param)
+    raise ArgumentError, ":#{param} must not be nil or empty."
   end
 end
 

data/lib/volabit/api/transactions.rb

@@ -4,7 +4,7 @@ module Transactions
   # Instantly buy bitcoins using fiat balance.
   # @note The amount is expected in satoshis.
   def buy_bitcoins(amount:)
-    post_to_resource 'api/v1/users/me/buys', {
+    resource :post, 'api/v1/users/me/buys', {
       amount: amount
     }
   end
@@ -12,27 +12,28 @@ module Transactions
   # Instantly sell bitcoins to get fiat balance.
   # @note The amount is expected in satoshis.
   def sell_bitcoins(amount:)
-    post_to_resource 'api/v1/users/me/sells', {
+    resource :post, 'api/v1/users/me/sells', {
       amount: amount
     }
   end
 
   # Instantly send fiat or bitcoins to an address.
-  # @note The amount is expected in satoshis for bitcoins and cents for fiat
+  # @note The amount is expected in satoshis for bitcoins and cents for
   #       fiat currencies.
-  def send(currency:, amount:, address:)
-    post_to_resource 'api/v1/users/me/send', {
+  def send_money(currency:, amount:, address:)
+    resource :post, 'api/v1/users/me/send', {
       amount: amount,
       address: address,
       currency: currency
     }
   end
 
+  alias_method :send_funds, :send_money
+
   # Requests a special address to receive a bitcoin payment that will be
-  # instantly converted to the designated currency.
-  # @note This action requires special merchant permissions to be performed.
+  # converted to the designated currency.
   def new_payment(currency:, amount:)
-    post_to_resource 'api/v1/users/me/green-addresses', {
+    resource :post, 'api/v1/users/me/green-addresses', {
       currency: currency,
       amount: amount
     }

data/lib/volabit/api/users.rb

@@ -1,10 +1,10 @@
 
 # API endpoints for user account management.
 module Users
-  # Creates a new user account.
-  # @note Special partner permissions are required to perform this action.
+  # Request the creation of a new user with the given params.
+  # @note This action requires partner privileges.
   def create_user(acceptance:, email:, pass: '')
-    post_to_resource 'api/v1/users', {
+    resource :post, 'api/v1/users', {
       accepts_terms_of_service: acceptance,
       user: {
         email: email, password: pass
@@ -14,9 +14,9 @@ module Users
 
   alias_method :new_user, :create_user
 
-  # Get the account information from the user that authorized the app.
+  # Gets the information details of the app user.
   def me
-    get_resource 'api/v1/users/me'
+    resource :get, 'api/v1/users/me'
   end
 
   alias_method :user_data, :me

data/lib/volabit/auth.rb

@@ -5,7 +5,7 @@ require_relative 'common'
 
 module Volabit
   include Common::Constants
-  extend  Common::Helpers
+  extend Common::Helpers
 
   # Methods to manage the OAuth2 authentication process.
   module Auth
@@ -19,53 +19,82 @@ module Volabit
       @oauth_client.auth_code.authorize_url redirect_uri: @url
     end
 
+    # Gets the information of the tokens currently set on the client.
+    #
+    # @return [Hash] including the access and refresh tokens and the
+    #         expiration POSIX time, or an error message it one occurs
+    #         while requesting the tokens.
+    def tokens
+      (@token.kind_of? OAuth2::AccessToken) ? @token.to_hash : @token
+    end
+
     # Requests and sets the access and refresh tokens to use the Volabit API
     # resources.
     #
     # @param  auth_token [String]
-    # @return [OAuth2::AccessToken] object that includes the credentials to
-    #         access the API and the methods to renew itself.
-    def get_token(auth_code)
+    # @return [Hash] with the tokens information. (See #tokens).
+    def request_tokens(auth_code)
       @token = @oauth_client.auth_code.get_token auth_code, redirect_uri: @url
-      {
-        :token          => @token.token,
-        :refresh_token  => @token.refresh_token,
-        :expires_in     => @token.expires_in,
-        :expires_at     => @token.expires_at,
-        :options        => @token.options
-      }
+      tokens
     end
 
-    def use_token(token, refresh_token)
-      token = OAuth2::AccessToken.new @oauth_client, token, { :refresh_token  => refresh_token }
-      token_info = JSON.parse token.get('/oauth/token/info').body
-      expires_in = token_info['expires_in_seconds']
-      @token = OAuth2::AccessToken.new @oauth_client, token, {
-        :refresh_token  => refresh_token,
-        :expires_in     => expires_in,
-        :mode           => :header,
-        :header_format  => 'Bearer %s',
-        :param_name     => 'access_token'
-      }
+    alias_method :get_token, :request_tokens
+
+    # Loads the client with the provided token information.
+    #
+    # @param  tokens_hash [Hash] that must contain at least the access and
+    #         refresh tokens.
+    # @return [Hash] with the tokens information. (See #tokens).
+    def use_tokens(tokens_hash)
+      @token = OAuth2::AccessToken.from_hash @oauth_client, tokens_hash
+      retrieve_missing_token_info if @token.expires_at.nil?
+      tokens
+    end
+
+    alias_method :use_token, :use_tokens
+
+    # Triggers a refresh of the current tokens.
+    #
+    # @return [Hash] with the tokens information. (See #tokens).
+    # @note   This method is provided as convenience, as the client checks the
+    #         expiration of the tokens before each call to the API.
+    def refresh_tokens
+      @token = @token.refresh!
+      tokens
     end
 
     # Toggles the test environment with a boolean value.
     # @note Set it before requiring the user authorization or your app will need
-    # to be reauthorized.)
+    #       to be reauthorized.
     def sandbox(flag)
-      @oauth_client.site = case flag
-      when true  then Volabit.site_for 'sandbox'
-      when false then Volabit.site_for 'production'
-      else
-        @oauth_client.site
+      case flag
+      when true  then @oauth_client.site = Volabit.site_for 'sandbox'
+      when false then @oauth_client.site = Volabit.site_for 'production'
       end
     end
 
     private
 
+    # Gets and sets information about the expiration time for provided
+    # tokens without it.
+    def retrieve_missing_token_info
+      response = JSON.parse @token.get('/oauth/token/info').body
+
+      if response['error']
+        response['hint'] = 'Reauthorization may be required.'
+        @token = response
+      else
+        time_left = response['expires_in_seconds']
+        @token.instance_variable_set '@expires_at', (Time.now.to_i + time_left)
+      end
+    end
+
     # Instances a new OAuth client to manage authorizations.
     def set_oauth_client(id, secret, env)
-      @oauth_client = OAuth2::Client.new(id, secret, site: Volabit.site_for(env))
+      @oauth_client = OAuth2::Client.new(id, secret, {
+        site: Volabit.site_for(env),
+        raise_errors: false
+      })
     end
   end
 end

data/lib/volabit/common.rb

@@ -3,7 +3,8 @@ require_relative 'common/constants'
 require_relative 'common/helpers'
 
 module Volabit
-  # Values and methods used by the library.
+  # Common values and methods used by the library.
   module Common
+    # See files under /lib/volabit/common/
   end
 end

data/lib/volabit/version.rb

@@ -1,3 +1,3 @@
 module Volabit
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: volabit
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - The Volabit Team & Contributors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-11 00:00:00.000000000 Z
+date: 2015-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth2
@@ -159,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: Library for the Volabit API.