synapse_pay_rest 0.0.15 → 2.0.0

data/lib/synapse_pay_rest/api/users.rb

@@ -3,62 +3,123 @@ require 'base64'
 require 'open-uri'
 
 module SynapsePayRest
-  # should maybe create User class
+  # Wrapper class for /users endpoints
   class Users
-    # Should refactor this to HTTPClient
+    # Valid optional args for #get
+    # @todo Should refactor this to HTTPClient
     VALID_QUERY_PARAMS = [:query, :page, :per_page].freeze
 
+    # @!attribute [rw] client
+    #   @return [SynapsePayRest::HTTPClient]
     attr_accessor :client
 
+    # @param [SynapsePayRest::HTTPClient]
     def initialize(client)
       @client = client
     end
 
-    # refactor to automate oauth
-    def refresh(payload: raise("payload is required"))
-      path = "/oauth/#{@client.user_id}"
-      response = @client.post(path, payload)
-      client.update_headers(oauth_key: response['oauth_key']) if response['oauth_key']
-      response
-    end
-
+    # Sends a GET request to /users endpoint and returns the response. Queries a
+    # specific user_id if user_id supplied, else queries all users. 
+    # 
+    # @param user_id [String,void] id of the user
+    # @param query [String] (optional) response will be filtered to 
+    #   users with matching name/email
+    # @param page [String,Integer] (optional) response will default to 1
+    # @param per_page [String,Integer] (optional) response will default to 20
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    # 
+    # @todo Probably should use CGI or RestClient's param builder instead of
+    # rolling our own, probably error-prone and untested version
+    # https://github.com/rest-client/rest-client#usage-raw-url
     def get(user_id: nil, **options)
       path = create_user_path(user_id: user_id)
 
-      # factor single user and all users into separate methods
       if user_id
         response = client.get(path)
         client.update_headers(user_id: response['_id']) if response['_id']
         return response
       end
 
-      # Should factor this out into HTTPClient and separate args for paginate/search(name/email)/per_page
       params = VALID_QUERY_PARAMS.map do |p|
         options[p] ? "#{p}=#{options[p]}" : nil
       end.compact
 
-      # Probably should use CGI or RestClient's param builder instead of
-      # rolling our own, probably error-prone and untested version
-      # https://github.com/rest-client/rest-client#usage-raw-url
       path += '?' + params.join('&') if params.any?
       client.get(path)
     end
 
-    def update(payload: raise("payload is required"))
-      path = create_user_path(user_id: client.user_id)
-      response = client.patch(path, payload)
+    # Sends a POST request to /users endpoint to create a new user, and returns
+    # the response.
+    # 
+    # @param payload [Hash]
+    # @see https://docs.synapsepay.com/docs/create-a-user payload structure
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    def create(payload:)
+      path = create_user_path
+      response = client.post(path, payload)
       client.update_headers(user_id: response['_id']) if response['_id']
       response
     end
 
-    def create(payload: raise("payload is required"))
-      path = create_user_path
-      response = client.post(path, payload)
-      client.update_headers(user_id: response['_id']) if response['_id']
+    # Sends a POST request to /oauth/:user_id endpoint to obtain a new oauth key
+    # and update the client's headers, and returns the response
+    # 
+    # @param payload [Hash]
+    # @see https://docs.synapsepay.com/docs/get-oauth_key-refresh-token payload structure
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    def refresh(payload:)
+      path = "/oauth/#{@client.user_id}"
+      response = @client.post(path, payload)
+      client.update_headers(oauth_key: response['oauth_key']) if response['oauth_key']
       response
     end
 
-    def encode_attachment(file_path: raise("file_path is required"), file_type: nil)
+    # Sends a PATCH request to /users endpoint, updating the current user,
+    # which can also include adding/updating user CIP documents, and returns the response.
+    # 
+    # @param payload [Hash]
+    # @see https://docs.synapsepay.com/docs/update-user payload structure for
+    #   updating user
+    # @see https://docs.synapsepay.com/docs/adding-documents payload structure
+    #   for adding documents to user
+    # @see https://docs.synapsepay.com/docs/updating-existing-document payload
+    #   structure for updating user's existing documents
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    def update(payload:)
+      path = create_user_path(user_id: client.user_id)
+      response = client.patch(path, payload)
+      client.update_headers(user_id: response['_id']) if response['_id']
+      response
+    end
+    # Alias for #update (legacy name)
+    alias_method :answer_kba, :update
+    # Alias for #update (legacy name)
+    alias_method :add_doc, :update
+
+    # Converts a file to base64 for use in payloads for adding physical documents.
+    # 
+    # @param file_path [String]
+    # @param file_type [String,void] (optional) MIME type of file (will attempt
+    #   to autodetect if nil)
+    # 
+    # @return [String] base64 encoded file
+    def encode_attachment(file_path:, file_type: nil)
       # try to find file_type
       if file_type.nil?
         content_types = MIME::Types.type_for(file_path)
@@ -67,7 +128,7 @@ module SynapsePayRest
 
       # if file_type not found in previous step
       if file_type.nil?
-        raise("File type not found. Specify a file_type argument.")
+        raise('File type not found. Specify a file_type argument.')
       end
 
       file_contents = open(file_path) { |f| f.read }
@@ -76,33 +137,32 @@ module SynapsePayRest
       mime_padding + encoded
     end
 
-    # this is just an alias for update. leaving here for legacy users.
-    def answer_kba(payload: raise("payload is required"))
-      update(payload: payload)
-    end
-
-    # this is just an alias for update. leaving here for legacy users.
-    def add_doc(payload: raise("payload is required"))
-      update(payload: payload)
-    end
-
-    # deprecated
-    def attach_file(file_path: raise("file_path is required"))
-      warn caller.first + " DEPRECATION WARNING: the method #{self.class}##{__method__} is deprecated. Use SynapsePayRest::Users::update with encode_attachment instead."
+    # Detects the file type of the file and calls #attach_file_with_file_type
+    # on it.
+    # 
+    # @param file_path [String]
+    # @deprecated Use #update with KYC 2.0 payload instead.
+    def attach_file(file_path:)
+      warn caller.first + " DEPRECATION WARNING: #{self.class}##{__method__} is deprecated. Use #update with encode_attachment instead."
 
       file_contents = open(file_path) { |f| f.read }
       content_types = MIME::Types.type_for(file_path)
       file_type = content_types.first.content_type if content_types.any?
       if file_type.nil?
-        raise("File type not found. Use attach_file_with_file_type(file_path: <file_path>, file_type: <file_type>)")
+        raise('File type not found. Use attach_file_with_file_type(file_path: <file_path>, file_type: <file_type>)')
       else
         attach_file_with_file_type(file_path: file_path, file_type: file_type)
       end
     end
 
-    # deprecated
-    def attach_file_with_file_type(file_path: raise("file_path is required"), file_type: raise("file_type is required"))
-      warn caller.first + " DEPRECATION WARNING: the method #{self.class}##{__method__} is deprecated. Use SynapsePayRest::Users::update with encode_attachment instead."
+    # Converts a file to base64 and sends it to the API using deprecated KYC 1.0 
+    # call.
+    # 
+    # @param file_path [String]
+    # @param file_type [String] MIME type
+    # @deprecated Use #update with KYC 2.0 payload instead.
+    def attach_file_with_file_type(file_path:, file_type:)
+      warn caller.first + " DEPRECATION WARNING: #{self.class}##{__method__} is deprecated. Use #update with encode_attachment instead."
 
       path = create_user_path(user_id: @client.user_id)
       file_contents = open(file_path) { |f| f.read }

data/lib/synapse_pay_rest/client.rb

@@ -0,0 +1,49 @@
+module SynapsePayRest
+  # Initializes various wrapper settings such as development mode and request
+  # header values. Also stores and initializes endpoint class instances 
+  # (Users, Nodes, Transactions) for making API calls.
+  class Client
+    # @!attribute [rw] http_client
+    #   @return [SynapsePayRest::HTTPClient]
+    # @!attribute [rw] users
+    #   @return [SynapsePayRest::Users]
+    # @!attribute [rw] nodes
+    #   @return [SynapsePayRest::Nodes]
+    # @!attribute [rw] transactions
+    #   @return [SynapsePayRest::Transactions]
+    attr_accessor :http_client, :users, :nodes, :transactions
+
+    # Alias for #transactions (legacy name)
+    alias_method :trans, :transactions
+    # Alias for #http_client (legacy name)
+    alias_method :client, :http_client
+
+    # @param client_id [String] should be stored in environment variable
+    # @param client_secret [String] should be stored in environment variable
+    # @param ip_address [String] user's IP address
+    # @param fingerprint [String] a hashed value, either unique to user or static
+    # @param user_id [String] (optional)
+    # @param development_mode [String] default true
+    # @param logging [Boolean] (optional) logs to stdout when true
+    # @param log_to [String] (optional) file path to log to file (logging must be true)
+    def initialize(client_id:, client_secret:, ip_address:, fingerprint: nil,
+                   user_id: nil, development_mode: true, **options)
+      base_url = if development_mode
+                   'https://sandbox.synapsepay.com/api/3'
+                 else
+                   'https://synapsepay.com/api/3'
+                 end
+
+      @http_client  = HTTPClient.new(base_url: base_url,
+                                     client_id: client_id,
+                                     client_secret: client_secret,
+                                     user_id: user_id,
+                                     fingerprint: fingerprint,
+                                     ip_address: ip_address,
+                                     **options)
+      @users        = Users.new @http_client
+      @nodes        = Nodes.new @http_client
+      @transactions = Transactions.new @http_client
+    end
+  end
+end

data/lib/synapse_pay_rest/error.rb

@@ -1,4 +1,5 @@
 module SynapsePayRest
+  # Custom class for handling HTTP and API errors.
   class Error < StandardError
     # Raised on a 4xx HTTP status code
     ClientError = Class.new(self)
@@ -48,6 +49,10 @@ module SynapsePayRest
     # Raised on the HTTP status code 504
     GatewayTimeout = Class.new(ServerError)
 
+    # HTTP status code to Error subclass mapping
+    #
+    # @todo need to add an error message for various 202 cases (fingerprint, mfa, etc)
+    # @todo doesn't do well when there's an html response from nginx for bad gateway/timeout
     ERRORS = {
       400 => SynapsePayRest::Error::BadRequest,
       401 => SynapsePayRest::Error::Unauthorized,
@@ -62,8 +67,8 @@ module SynapsePayRest
       500 => SynapsePayRest::Error::InternalServerError,
       502 => SynapsePayRest::Error::BadGateway,
       503 => SynapsePayRest::Error::ServiceUnavailable,
-      504 => SynapsePayRest::Error::GatewayTimeout,
-    }
+      504 => SynapsePayRest::Error::GatewayTimeout
+    }.freeze
 
     # The SynapsePay API Error Code
     #
@@ -82,6 +87,7 @@ module SynapsePayRest
       # @param code [Integer]
       # @return [SynapsePayRest::Error]
       def error_from_response(body, code)
+        code = code.to_i
         klass = ERRORS[code] || SynapsePayRest::Error
         message, error_code = parse_error(body)
         klass.new(message: message, code: error_code, response: body)

data/lib/synapse_pay_rest/http_client.rb

@@ -2,57 +2,124 @@ require 'rest-client'
 require 'json'
 
 module SynapsePayRest
+  # Wrapper for HTTP requests using RestClient.
   class HTTPClient
-    attr_accessor :base_url, :config, :headers, :user_id
+    # @!attribute [rw] base_url
+    #   @return [String] the base url of the API (production or sandbox)
+    # @!attribute [rw] config
+    #   @return [Hash] various settings related to request headers
+    # @!attribute [rw] user_id
+    #   @return [String] the user_id which is stored upon a call to Users#get or Users#create
+    attr_accessor :base_url, :config, :user_id
 
-    def initialize(config, base_url, user_id: nil)
-      @config = config
+    # @param base_url [String] the base url of the API (production or sandbox)
+    # @param client_id [String]
+    # @param client_secret [String]
+    # @param fingerprint [String]
+    # @param ip_address [String]
+    # @param user_id [String] (optional) automatically stored on call to Users#get or Users#create
+    # @param logging [Boolean] (optional) logs to stdout when true
+    # @param log_to [String] (optional) file path to log to file (logging must be true)
+    def initialize(base_url:, client_id:, fingerprint:, ip_address:, client_secret:,
+                   user_id: nil, **options)
+
+      log_to         = options[:log_to] || 'stdout'
+      RestClient.log = log_to if options[:logging]
+
+      @config = {
+        fingerprint:   fingerprint,
+        client_id:     client_id,
+        client_secret: client_secret
+      }
       @base_url = base_url
-      # RestClient.log = 'stdout'
-      @user_id = user_id
+      @user_id  = user_id
     end
 
-    def get_headers
-      # refactor to use symbols
-      user    = "#{config['oauth_key']}|#{config['fingerprint']}"
-      gateway = "#{config['client_id']}|#{config['client_secret']}"
+    # Returns headers for HTTP requests.
+    # 
+    # @return [Hash]
+    def headers
+      user    = "#{config[:oauth_key]}|#{config[:fingerprint]}"
+      gateway = "#{config[:client_id]}|#{config[:client_secret]}"
       headers = {
-        :content_type => :json,
-        :accept => :json,
+        :content_type  => :json,
+        :accept        => :json,
         'X-SP-GATEWAY' => gateway,
-        'X-SP-USER' => user,
-        'X-SP-USER-IP' => config['ip_address'] 
+        'X-SP-USER'    => user,
+        'X-SP-USER-IP' => config[:ip_address]
       }
     end
+    # Alias for #headers (legacy name)
+    alias_method :get_headers, :headers
 
-    def update_headers(user_id: nil, oauth_key: nil, fingerprint: nil, client_id: nil, client_secret: nil, ip_address: nil)
-      # this doesn't really belongs in headers
-      self.user_id = user_id if user_id
-
-      config['fingerprint']   = fingerprint if fingerprint
-      config['oauth_key']     = oauth_key if oauth_key
-      config['client_id']     = client_id if client_id
-      config['client_secret'] = client_secret if client_secret
-      config['ip_address']    = ip_address if ip_address
+    # Updates headers and/or user_id.
+    # 
+    # @param user_id [String,void]
+    # @param oauth_key [String,void]
+    # @param fingerprint [String,void]
+    # @param client_id [String,void]
+    # @param client_secret [String,void]
+    # @param ip_address [String,void]
+    # 
+    # @return [void]
+    def update_headers(user_id: nil, oauth_key: nil, fingerprint: nil,
+                       client_id: nil, client_secret: nil, ip_address: nil)
+      self.user_id           = user_id if user_id
+      config[:fingerprint]   = fingerprint if fingerprint
+      config[:oauth_key]     = oauth_key if oauth_key
+      config[:client_id]     = client_id if client_id
+      config[:client_secret] = client_secret if client_secret
+      config[:ip_address]    = ip_address if ip_address
+      nil
     end
 
+    # Sends a POST request to the given path with the given payload.
+    # 
+    # @param path [String]
+    # @param payload [Hash]
+    # 
+    # @raise [SynapsePayRest::Error] subclass depends on HTTP response
+    # 
+    # @return [Hash] API response
     def post(path, payload)
-      response = with_error_handling { RestClient.post(full_url(path), payload.to_json, get_headers) }
+      response = with_error_handling { RestClient.post(full_url(path), payload.to_json, headers) }
       JSON.parse(response)
     end
 
+    # Sends a PATCH request to the given path with the given payload.
+    # 
+    # @param path [String]
+    # @param payload [Hash]
+    # 
+    # @raise [SynapsePayRest::Error] subclass depends on HTTP response
+    # 
+    # @return [Hash] API response
     def patch(path, payload)
-      response = with_error_handling { RestClient.patch(full_url(path), payload.to_json, get_headers) }
+      response = with_error_handling { RestClient.patch(full_url(path), payload.to_json, headers) }
       JSON.parse(response)
     end
 
+    # Sends a GET request to the given path with the given payload.
+    # 
+    # @param path [String]
+    # 
+    # @raise [SynapsePayRest::Error] subclass depends on HTTP response
+    # 
+    # @return [Hash] API response
     def get(path)
-      response = with_error_handling { RestClient.get(full_url(path), get_headers) }
+      response = with_error_handling { RestClient.get(full_url(path), headers) }
       JSON.parse(response)
     end
 
+    # Sends a DELETE request to the given path with the given payload.
+    # 
+    # @param path [String]
+    # 
+    # @raise [SynapsePayRest::Error] subclass depends on HTTP response
+    # 
+    # @return [Hash] API response
     def delete(path)
-      response = with_error_handling { RestClient.delete(full_url(path), get_headers) }
+      response = with_error_handling { RestClient.delete(full_url(path), headers) }
       JSON.parse(response)
     end
 
@@ -66,7 +133,7 @@ module SynapsePayRest
       yield
     rescue RestClient::Exception => e
       body = JSON.parse(e.response.body)
-      raise Error.error_from_response(body, e.response.code)
+      raise Error.error_from_response(body, body['error_code'])
     end
   end
 end

data/lib/synapse_pay_rest/models/node/ach_us_node.rb

@@ -0,0 +1,111 @@
+module SynapsePayRest
+  # Represents a US bank account for processing ACH payments. Can be added by
+  # account/routing number or via bank login for selected banks (recommended).
+  # 
+  # @see https://docs.synapsepay.com/docs/node-resources nodes documentation
+  # @see https://synapsepay.com/api/v3/institutions/show valid banks for login
+  class AchUsNode < BaseNode
+    class << self
+      # Creates an ACH-US node via bank login, belonging to user supplied.
+      # 
+      # @param user [SynapsePayRest::User] the user to whom the node belongs 
+      # @param bank_name [String] 
+      # @see https://synapsepay.com/api/v3/institutions/show valid bank_name options
+      # @param username [String] user's bank login username
+      # @param password [String] user's bank login password
+      # 
+      # @raise [SynapsePayRest::Error]
+      # 
+      # @return [Array<SynapsePayRest::AchUsNode>] may contain multiple nodes (checking and/or savings)s
+      def create_via_bank_login(user:, bank_name:, username:, password:)
+        raise ArgumentError, 'user must be a User object' unless user.is_a?(User)
+        raise ArgumentError, 'bank_name must be a String' unless bank_name.is_a?(String)
+        raise ArgumentError, 'username must be a String' unless username.is_a?(String)
+        raise ArgumentError, 'password must be a String' unless password.is_a?(String)
+
+        payload = payload_for_create_via_bank_login(bank_name: bank_name, username: username, password: password)
+        user.authenticate
+        response = user.client.nodes.add(payload: payload)
+        # MFA questions
+        if response['mfa']
+          create_unverified_node(user, response)
+        else
+          create_multiple_from_response(user, response['nodes'])
+        end
+      end
+
+      private
+
+      # Converts args into payload for request JSON.
+      def payload_for_create(nickname:, account_number:, routing_number:, 
+        account_type:, account_class:, **options)
+        payload = {
+          'type' => 'ACH-US',
+          'info' => {
+            'nickname'    => nickname,
+            'account_num' => account_number,
+            'routing_num' => routing_number,
+            'type'        => account_type,
+            'class'       => account_class
+          }
+        }
+        # optional payload fields
+        extra = {}
+        extra['supp_id']            = options[:supp_id] if options[:supp_id]
+        extra['gateway_restricted'] = options[:gateway_restricted] if options[:gateway_restricted]
+        payload['extra'] = extra if extra.any?
+
+        payload
+      end
+
+      def payload_for_create_via_bank_login(bank_name:, username:, password:)
+        {
+          'type' => 'ACH-US',
+          'info' => {
+            'bank_id'   => username,
+            'bank_pw'   => password,
+            'bank_name' => bank_name
+          }
+        }
+      end
+      
+      # Creates a SynapsePayRest::UnverifiedNode when bank responds with MFA
+      # questions.
+      def create_unverified_node(user, response)
+        UnverifiedNode.new(
+          user:             user,
+          mfa_access_token: response['mfa']['access_token'],
+          mfa_message:      response['mfa']['message'],
+          mfa_verified:     false
+        )
+      end
+    end
+
+    # Verifies the microdeposit amounts sent to the user's account to verify
+    # a node added by account and routing number. Node will be locked if max
+    # tries exceeded.
+    # 
+    # @param amount1 [Float]
+    # @param amount2 [Float]
+    # 
+    # @raise [SynapsePayRest::Error] if wrong guess or HTTP error
+    # 
+    # @return [SynapsePayRest::AchUsNode]
+    def verify_microdeposits(amount1:, amount2:)
+      [amount1, amount2].each do |arg|
+        raise ArgumentError, "#{arg} must be float" unless arg.is_a?(Float)
+      end
+
+      payload = verify_microdeposits_payload(amount1: amount1, amount2: amount2)
+      response = user.client.nodes.patch(node_id: id, payload: payload)
+      self.class.create_from_response(user, response)
+    end
+
+    private
+
+    # Converts the data to hash format for request JSON.
+    def verify_microdeposits_payload(amount1:, amount2:)
+      {'micro' => [amount1, amount2]}
+    end
+  end
+end