mangopay 3.0.1 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 67c10c6356d088795e976707bb179e568a7f5368
-  data.tar.gz: dcd3cd6d68b8012d37752e00d6f6edf15b1b8223
+  metadata.gz: fae2d9875515d0ac49e200836b8741894d6009eb
+  data.tar.gz: 754c2abd123306ef475b1fa0ef89f37725e8b0ad
 SHA512:
-  metadata.gz: 841c0922c44245dfe8505dc25756fb3f82621b2823e4993a0ccd3c19248972068102508491ef391c19b6918de7b504746de71d0d61998635552d854628e4aa8c
-  data.tar.gz: 4497c0d2305ac47148712956bcf071f56b69ce2c73e2ca287296c42404cf020967372130b4b92e9ae13d4d82b05663e5c06da50f595e01c43333374b1dae2815
+  metadata.gz: f3c10e1d1fc80d4650a48662204b90c3d83d7af10c3be4fa4be9bb88caf9e0062e0622956488b15ad72d38ed55d8942af55187ba8b41de8cc249d65cab2eec43
+  data.tar.gz: 0c15e721136d89ed3ac62152c24673e6d7b74e1cf6219ef8c40b73196ec44fef34c0b20be043c8dbec47eebc5e5aecddd95f4f022c4a2e2a99a3ed58e6b53ec3

data/.gitignore

@@ -8,9 +8,9 @@ lib/bundler/man
 pkg
 rdoc
 spec/reports
+spec/tmp/*.tmp
 test/tmp
 test/version_tmp
-tmp
 tags
 
 # YARD artifacts

data/README.md

@@ -1,37 +1,66 @@
 # MangoPay2 Ruby SDK
 
 The gem for interacting with the version 2 of the MangoPay API.
-See the [API documentation]() for more details on the API.
+See the [API documentation](http://docs.mangopay.com/api-references/)
+for more details on the API.
 
 Tested on the following versions of Ruby: 1.9.2, 1.9.3, 2.0.0
 
-## Code Status
-[![Build Status]()]()
-[![Code Climate]()]()
-[![Dependency Status]()]()
-
 ## NEWS
 
-### Version 3.0.0
+### Version 3.*
 ** BREAKING CHANGES **
-This version of the gem is targeting the MangoPay API Version 2.
+This version (3.*) of the gem is targeting the MangoPay API Version 2.
 It has a brand new structure to make the api calls easier to use
+and is not backward compatible with 2.* series.
 
 ## Usage
 
 ### Install
-* Install the gem by either running ```gem install mangopay``` or by adding it to your Gemfile ```gem 'mangopay'```
+* Install the gem by either running ```gem install mangopay```
+or by adding it to your Gemfile ```gem 'mangopay'```
+
+* The Rails users will be happy to know that there is a new generator script
+that will help you configure your access to the MangoPay API version 2.
+Simply run ``rails generate mangopay:install CLIENT_ID CLIENT_NAME CLIENT_EMAIL``
+where CLIENT_ID is the id you will use to connect to the api
+and CLIENT_NAME is a full name that will be use to identify all communications
+between you and the MangoPay Team.
 
-* The Rails users will be happy to know that there is a new generator script that will help you configure your access to the MangoPay API version 2.
-Simply run ``rails generate mangopay:install CLIENT_ID CLIENT_NAME`` where CLIENT_ID is the id you will use to connect to the api and CLIENT_NAME is a full name that will be use to identify all communications between you and the MangoPay Team.
+* Otherwise, call ```MangoPay.configure``` in your script as shown in the snippet below.
 
 ### Examples
 
+```ruby
+require 'mangopay'
+
+# configuration (not required if Rails generator fired as above)
+MangoPay.configure do |c|
+  c.preproduction = true
+  c.client_id = 'YOUR_CLIENT_ID'
+  c.client_passphrase = 'YOUR_CLIENT_PASSWORD'
+end
+
+# get some user by id
+john = MangoPay::User.fetch(john_id) # => {FirstName"=>"John", "LastName"=>"Doe", ...}
+
+# update some of his data
+MangoPay::NaturalUser.update(john_id, {'LastName' => 'CHANGED'}) # => {FirstName"=>"John", "LastName"=>"CHANGED", ...}
+
+# get all users (with pagination)
+pagination = {'page' => 1, 'per_page' => 8} # get 1st page, 8 items per page
+users = MangoPay::User.fetch(pagination) # => [{...}, ...]: list of 8 users data hashes
+pagination # => {"page"=>1, "per_page"=>8, "total_pages"=>748, "total_items"=>5978}
+
+# get John's bank accounts
+accounts = MangoPay::BankAccount.fetch(john_id) # => [{...}, ...]: list of accounts data hashes (10 per page by default)
+```
 
 ### Tests
 Make sure that you have run: ```bundle install```
 Then you just have to run rspec ```rspec``` to run all the test suite.
-Feel free to report any test failure by creating an issue on the [Gem's Github](https://github.com/MangoPay/mangopay2-ruby-sdk/issues)
+Feel free to report any test failure by creating an issue
+on the [Gem's Github](https://github.com/MangoPay/mangopay2-ruby-sdk/issues)
 
 ## Contributing
 
@@ -61,7 +90,7 @@ Syntax:
 * a = b and not a=b.
 * Follow the conventions you see used in the source already.
 
-A contribution can also be as simple as a +1 on issues tickets to show us what you would like to see in this gem.
+A contribution can also be as simple as a +1 on issues tickets to show us
+what you would like to see in this gem.
 
 That's it for now. Good Hacking...
->>>>>>> dev

data/lib/mangopay.rb

@@ -2,13 +2,13 @@ require 'net/http'
 require 'cgi/util'
 require 'multi_json'
 
-# Version
+# helpers
 require 'mangopay/version'
-
-# JSON
 require 'mangopay/json'
+require 'mangopay/errors'
+require 'mangopay/authorization_token'
 
-# Resources
+# resources
 require 'mangopay/http_calls'
 require 'mangopay/resource'
 require 'mangopay/client'
@@ -24,13 +24,12 @@ require 'mangopay/bank_account'
 require 'mangopay/card_registration'
 require 'mangopay/card'
 
-# Errors
-require 'mangopay/errors'
-
 module MangoPay
 
   class Configuration
-    attr_accessor :root_url, :client_id, :client_passphrase, :preproduction
+    attr_accessor :preproduction, :root_url,
+      :client_id, :client_passphrase,
+      :temp_dir
 
     def preproduction
       @preproduction || false
@@ -54,17 +53,46 @@ module MangoPay
     URI(configuration.root_url + url)
   end
 
-  def self.request(method, url, params={}, headers={})
+  #
+  # - +method+: HTTP method; lowercase symbol, e.g. :get, :post etc.
+  # - +url+: the part after Configuration#root_url
+  # - +params+: hash; entity data for creation, update etc.; will dump it by JSON and assign to Net::HTTPRequest#body
+  # - +filters+: hash; pagination params etc.; will encode it by URI and assign to URI#query
+  # - +headers+: hash; request_headers by default
+  # - +before_request_proc+: optional proc; will call it passing the Net::HTTPRequest instance just before Net::HTTPRequest#request
+  #
+  # Raises MangoPay::ResponseError if response code != 200.
+  #
+  def self.request(method, url, params={}, filters={}, headers = request_headers, before_request_proc = nil)
     uri = api_uri(url)
+    uri.query = URI.encode_www_form(filters) unless filters.empty?
 
     res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
-      request = Net::HTTP::const_get(method.capitalize).new(uri.request_uri, request_headers)
-      request.body = MangoPay::JSON.dump(params)
-      http.request request
+      req = Net::HTTP::const_get(method.capitalize).new(uri.request_uri, headers)
+      req.body = MangoPay::JSON.dump(params)
+      before_request_proc.call(req) if before_request_proc
+      http.request req
     end
-    MangoPay::JSON.load(res.body)
+
+    # decode json data
+    begin
+      data = MangoPay::JSON.load(res.body)
+    rescue MultiJson::LoadError
+      data = {}
+    end
+
+    raise MangoPay::ResponseError.new(uri, res.code, data) unless res.is_a? Net::HTTPOK
+
+    # copy pagination info if any
+    ['x-number-of-pages', 'x-number-of-items'].each { |k|
+      filters[k.gsub('x-number-of-', 'total_')] = res[k].to_i if res[k]
+    }
+
+    data
   end
 
+  private
+
   def self.user_agent
     @uname ||= get_uname
 
@@ -83,30 +111,11 @@ module MangoPay
     'uname lookup failed'
   end
 
-  def self.get_oauth_token
-    if @auth_timestamp.nil? || @auth_timestamp <= Time.now || @auth_token.nil?
-      uri = api_uri('/api/oauth/token')
-      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
-        req = Net::HTTP::Post.new(uri.request_uri)
-        req.basic_auth configuration.client_id, configuration.client_passphrase
-        req.body = 'grant_type=client_credentials'
-        http.request req
-      end
-      @auth_token = MangoPay::JSON.load(res.body)
-      @auth_timestamp = Time.now + @auth_token['expires_in'].to_i
-    end
-    @auth_token
-  end
-
-  def self.oauth_token
-    oauth = get_oauth_token
-    "#{oauth['token_type']} #{oauth['access_token']}"
-  end
-
   def self.request_headers
+    auth_token = MangoPay::AuthorizationToken::Manager.get_token
     headers = {
       'user_agent' => "MangoPay V1 RubyBindings/#{MangoPay::VERSION}",
-      'Authorization' => oauth_token,
+      'Authorization' => "#{auth_token['token_type']} #{auth_token['access_token']}",
       'Content-Type' => 'application/json'
     }
     begin

data/lib/mangopay/authorization_token.rb

@@ -0,0 +1,76 @@
+module MangoPay
+  module AuthorizationToken
+
+    class Manager
+
+      class << self
+        def storage
+          @@storage ||= StaticStorage.new
+        end
+        def storage= (storage)
+          @@storage = storage
+        end
+      end
+
+      def self.get_token
+        token = storage.get
+        if token.nil? || token['timestamp'].nil? || token['timestamp'] <= Time.now
+          token = MangoPay.request(:post, '/api/oauth/token', {}, {}, {}, Proc.new do |req|
+            cfg = MangoPay.configuration
+            req.basic_auth cfg.client_id, cfg.client_passphrase
+            req.body = 'grant_type=client_credentials'
+          end)
+          token['timestamp'] = Time.now + token['expires_in'].to_i
+          storage.store token
+        end
+        token
+      end
+    end
+
+    class StaticStorage
+      def get
+        @@token ||= nil
+      end
+      def store(token)
+        @@token = token
+      end
+    end
+
+    class FileStorage
+      require 'yaml'
+      @temp_dir
+
+      def initialize(temp_dir = nil)
+        @temp_dir = temp_dir || MangoPay.configuration.temp_dir
+        if !@temp_dir
+          raise "Path to temporary folder is not defined"
+        end
+      end
+
+      def get
+        begin
+          f = File.open(file_path, File::RDONLY)
+          f.flock(File::LOCK_SH)
+          txt = f.read
+          f.close
+          YAML.load(txt) || nil
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+
+      def store(token)
+        File.open(file_path, File::RDWR|File::CREAT, 0644) do |f|
+          f.flock(File::LOCK_EX)
+          f.truncate(0)
+          f.rewind
+          f.puts(YAML.dump(token))
+        end
+      end
+
+      def file_path
+        File.join(@temp_dir, "MangoPay.AuthorizationToken.FileStore.tmp")
+      end
+    end
+  end
+end

data/lib/mangopay/bank_account.rb

@@ -3,18 +3,25 @@ module MangoPay
     include MangoPay::HTTPCalls::Create
     include MangoPay::HTTPCalls::Fetch
 
-    def self.fetch(*ids)
-      url = ids.length == 1 ? url(ids[0]) : url(ids[0], ids[1])
-      MangoPay.request(:get, url)
+    # Fetches:
+    # - list of bank accounts belonging to the given +user_id+
+    # - or single bank account belonging to the given +user_id+ with the given +bank_account_id+.
+    # 
+    # In case of list query, optional +filters+ is a hash accepting pagination params
+    # (+page+, +per_page+; see MangoPay::HTTPCalls::Fetch::ClassMethods#fetch)
+    #
+    def self.fetch(user_id, bank_account_id_or_filters={})
+      bank_account_id, filters = MangoPay::HTTPCalls::Fetch.parse_id_or_filters(bank_account_id_or_filters)
+      MangoPay.request(:get, url(user_id, bank_account_id), {}, filters)
     end
 
     private
 
-    def self.url(*id)
-      if id.length == 1
-        "/v2/#{MangoPay.configuration.client_id}/users/#{CGI.escape(id[0])}/bankaccounts"
+    def self.url(user_id, bank_account_id = nil)
+      if bank_account_id
+        "/v2/#{MangoPay.configuration.client_id}/users/#{CGI.escape(user_id.to_s)}/bankaccounts/#{CGI.escape(bank_account_id.to_s)}"
       else
-        "/v2/#{MangoPay.configuration.client_id}/users/#{CGI.escape(id[0])}/bankaccounts/#{CGI.escape(id[1])}"
+        "/v2/#{MangoPay.configuration.client_id}/users/#{CGI.escape(user_id.to_s)}/bankaccounts"
       end
     end
   end

data/lib/mangopay/client.rb

@@ -1,17 +1,11 @@
-module MangoPay
-  class Client < Resource
-
-    def self.create(params)
-      uri = URI(MangoPay.configuration.root_url + '/api/clients/')
-      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
-        request = Net::HTTP::Post.new(uri.request_uri, {
-          'user_agent' => "MangoPay V1 RubyBindings/#{MangoPay::VERSION}",
-          'Content-Type' => 'application/json'
-        })
-        request.body = MangoPay::JSON.dump(params)
-        http.request request
-      end
-      MangoPay::JSON.load(res.body)
-    end
-  end
-end
+module MangoPay
+  class Client < Resource
+
+    def self.create(params)
+      MangoPay.request(:post, '/api/clients/', params, {}, {
+        'user_agent' => "MangoPay V1 RubyBindings/#{MangoPay::VERSION}",
+        'Content-Type' => 'application/json'
+      })
+    end
+  end
+end

data/lib/mangopay/errors.rb

@@ -1,4 +1,24 @@
 module MangoPay
- class Errors
- end
+
+  # Generic error superclass for MangoPay specific errors.
+  # Currently never instantiated directly.
+  # Currently only single subclass used.
+  class Error < StandardError
+  end
+
+  # Thrown from any MangoPay API call whenever
+  # it returns response with HTTP code != 200.
+  class ResponseError < Error
+
+    attr_reader :request_url, :code, :details
+
+    def initialize(request_url, code, details)
+      @request_url, @code, @details = request_url, code, details
+      super(message) if message
+    end
+
+    def message; @details['Message']; end
+    def type;    @details['Type']; end
+    def errors;  @details['errors']; end
+  end
 end

data/lib/mangopay/http_calls.rb

@@ -28,14 +28,36 @@ module MangoPay
 
     module Fetch
       module ClassMethods
-        def fetch(id = nil, filters = {})
-          response = MangoPay.request(:get, url(id), filters)
+
+        # - Fetching single entity by +id+:
+        # 
+        #   MangoPay::User.fetch("user-id") # => {"FirstName"=>"Mango", "LastName"=>"Pay", ...}
+        # 
+        # - Fetching multiple entities with _optional_ +filters+ hash,
+        #   including _pagination_ params
+        #   (+page+, +per_page+; see http://docs.mangopay.com/api-references/pagination/):
+        #   
+        #   MangoPay::User.fetch() # => [{...}, ...]: list of user data hashes (10 per page by default)
+        #   MangoPay::User.fetch({'page' => 2, 'per_page' => 3}) # => list of 3 hashes from 2nd page
+        # 
+        # - For paginated queries the +filters+ param will be supplemented by +total_pages+ and +total_items+ info:
+        #   
+        #   MangoPay::User.fetch(filter = {'page' => 2, 'per_page' => 3})
+        #   filter # => {"page"=>2, "per_page"=>3, "total_pages"=>1969, "total_items"=>5905}
+        #
+        def fetch(id_or_filters = nil)
+          id, filters = MangoPay::HTTPCalls::Fetch.parse_id_or_filters(id_or_filters)
+          response = MangoPay.request(:get, url(id), {}, filters)
         end
       end
 
       def self.included(base)
         base.extend(ClassMethods)
       end
+
+      def self.parse_id_or_filters(id_or_filters = nil)
+        id_or_filters.is_a?(Hash) ? [nil, id_or_filters] : [id_or_filters, {}]
+      end
     end
 
     module Refund

data/lib/mangopay/legal_user.rb

@@ -5,7 +5,7 @@ module MangoPay
 
     def self.url(id = nil)
       if id
-        "/v2/#{MangoPay.configuration.client_id}/users/legal/#{CGI.escape(id)}"
+        "/v2/#{MangoPay.configuration.client_id}/users/legal/#{CGI.escape(id.to_s)}"
       else
         "/v2/#{MangoPay.configuration.client_id}/users/legal"
       end