mangopay-v4 4.0.0

data/lib/mangopay/api/service/wallets.rb

@@ -0,0 +1,99 @@
+require_relative '../uri_provider'
+require_relative '../../model/request/filter_request'
+
+module MangoApi
+
+  # Provides API method delegates concerning the +Wallet+ entity.
+  module Wallets
+    class << self
+      include UriProvider
+
+      # Creates a new wallet entity.
+      #
+      # +Wallet+ properties:
+      # * Required
+      #   * owners
+      #   * description
+      #   * currency
+      # * Optional
+      #   * tag
+      #
+      # @param +wallet+ [Wallet] model object of wallet to be created
+      # @param +id_key+ [String] idempotency key for future response replication
+      # @return [Wallet] the newly-created Wallet entity object
+      def create(wallet, id_key = nil)
+        uri = provide_uri(:create_wallet)
+        response = HttpClient.post(uri, wallet, id_key)
+        parse response
+      end
+
+      # Updates the wallet entity identifiable by
+      # the provided wallet object's ID.
+      #
+      # +Wallet+ optional properties:
+      # * tag
+      # * description
+      #
+      # @param +wallet+ [Wallet] wallet object with corresponding ID
+      # and updated data
+      # @return [Wallet] updated wallet entity
+      def update(wallet)
+        uri = provide_uri(:update_wallet, wallet)
+        response = HttpClient.put(uri, wallet)
+        parse response
+      end
+
+      # Retrieves a wallet entity.
+      #
+      # @param +id+ [String] ID of the wallet to be retrieved
+      # @return [Wallet] the requested entity
+      def get(id)
+        uri = provide_uri(:get_wallet, id)
+        response = HttpClient.get(uri)
+        parse response
+      end
+
+      # Retrieves pages of wallet entities belonging to a certain user entity.
+      # Allows configuration of paging and sorting parameters by
+      # yielding a filtering object to a provided block. When no filters
+      # are specified, will retrieve the first page of 10 newest results.
+      #
+      # Allowed +FilterRequest+ params:
+      # * page
+      # * per_page
+      # * sort_field and sort_direction
+      #
+      # @param +id+ [String] ID of the user whose wallets to retrieve
+      # @return [Array] the requested entities
+      def of_user(id)
+        uri = provide_uri(:get_users_wallets, id)
+        filter_request = nil
+        yield filter_request = FilterRequest.new if block_given?
+        results = HttpClient.get(uri, filter_request)
+        parse_results results
+      end
+
+      private
+
+      # Parses an array of JSON-originating hashes into the corresponding
+      # Wallet entity objects.
+      #
+      # @param +results+ [Array] JSON-originating data hashes
+      # @return [Array] parsed Wallet entity objects
+      def parse_results(results)
+        results.collect do |entity|
+          parse entity
+        end
+      end
+
+      # Parses a JSON-originating hash into the corresponding
+      # Wallet entity object.
+      #
+      # @param +response+ [Hash] JSON-originating data hash
+      # @return [Wallet] corresponding Wallet entity object
+      def parse(response)
+        MangoModel::Wallet.new.dejsonify response
+      end
+    end
+  end
+end

data/lib/mangopay/api/uri_provider.rb

@@ -0,0 +1,35 @@
+require_relative 'api_methods'
+
+module MangoApi
+
+  # Provides full contextual URL details for API calls.
+  module UriProvider
+
+    # Returns the URI for a given API endpoint. Calls `eval` on the
+    # declared API method string if the URL contains parameter placeholders,
+    # replacing them with data as passed into the method with the two
+    # 'param' params.
+    #
+    # @param [Symbol] +api_method_symbol+ API endpoint symbol key,
+    # as specified in ApiMethods
+    # @param [Object] +_param1+ First entity containing data necessary
+    # for parsing the URL (i.e. resource ID)
+    # @param [Object] +_param2+ Second entity containing necessary parsing data
+    #
+    # @return [URI] URI for the API endpoint specified by Symbol
+    def provide_uri(api_method_symbol,
+                    _param1 = nil,
+                    _param2 = nil)
+      _, unparsed = ApiMethods[api_method_symbol]
+      raise("No method declared for key :#{api_method_symbol}") unless unparsed
+      parsed_path = unparsed.include?('%') ? eval(unparsed) : unparsed
+      config = MangoPay.configuration
+      full_url = [config.root_url,
+                  config.api_version,
+                  config.client_id,
+                  parsed_path]
+                 .join('/')
+      URI(full_url)
+    end
+  end
+end

data/lib/mangopay/common/json_tag_converter.rb

@@ -0,0 +1,68 @@
+module MangoPay
+
+  # Converts field names between Ruby and API formats.
+  module JsonTagConverter
+    class << self
+
+      # Converts a snake_case-named field name to
+      # its API UpperCamelCase counterpart.
+      def to_json_tag(field)
+        field.split('_').collect do |word|
+          apply_capitalization word
+        end.join
+      end
+
+      # Applies necessary capitalization to a word
+      # in order to match API conventions.
+      def apply_capitalization(word)
+        word.sub!('kyc', 'KYC')
+        word.sub!('url', 'URL')
+        word.sub!('iban', 'IBAN')
+        word.sub!('bic', 'BIC')
+        word.sub!('aba', 'ABA')
+        word.sub!('ubo', 'UBO')
+        word[0] = word[0].upcase
+        word
+      end
+
+      # Converts an API-returned UpperCamelCase-named JSON tag
+      # to its Ruby-standard snake_case counterpart.
+      def from_json_tag(tag)
+        tag = tag.sub('UBO', 'Ubo')
+        parts = tag.split(/(?=[A-Z])/)
+        parts = compress_upcase_strings(parts)
+        field = ''
+        parts.each.with_index do |part, index|
+          decapitalize part
+          field << '_' if !field.empty? && (part.length > 1\
+          || (part == 'e' && parts[index + 1] == 'Money'))
+          field << part
+        end
+        field
+      end
+
+      # Takes an array of strings and sticks together those
+      # which are single uppercase letters in order to form
+      # the actual words they compose.
+      def compress_upcase_strings(strings)
+        result = []
+        current = ''
+        strings.each do |string|
+          if string.length > 1
+            result << current unless current.empty?
+            current = ''
+            result << string
+            next
+          end
+          current << (current.empty? ? string : string.downcase)
+        end
+        current.empty? ? result : result << current
+      end
+
+      def decapitalize(word)
+        word[0] = word[0].downcase
+        word
+      end
+    end
+  end
+end

data/lib/mangopay/common/jsonifier.rb

@@ -0,0 +1,249 @@
+require 'json'
+require_relative 'read_only_fields'
+require_relative '../common/json_tag_converter'
+require_relative 'log_provider'
+require_relative '../model/model'
+require_relative '../model/entity/account/bank_account'
+
+module MangoPay
+
+  # To be included in order to apply JSON de/serialization methods
+  module Jsonifier
+    # require here to satisfy circular dependency
+    require_relative '../model/entity/card_registration'
+    require_relative '../model/entity/pre_authorization'
+    require_relative '../model/entity/account/iban_bank_account'
+    require_relative '../model/entity/account/us_bank_account'
+    require_relative '../model/entity/account/ca_bank_account'
+    require_relative '../model/entity/account/gb_bank_account'
+    require_relative '../model/entity/account/other_bank_account'
+    require_relative '../model/entity/mandate'
+    require_relative '../model/entity/kyc_document'
+    require_relative '../model/entity/pay_out'
+    require_relative '../model/entity/ubo_declaration'
+    require_relative '../model/entity/hook'
+    require_relative '../model/entity/dispute'
+    require_relative '../model/entity/dispute_document'
+    require_relative '../model/entity/report'
+    require_relative '../model/declared_ubo'
+    LOG = LogProvider.provide(self)
+
+    # Serializes an object to a JSON string.
+    # Read-only fields will be removed
+    #
+    # @return [String] JSON string of non-read-only fields and values
+    def jsonify!
+      json = hashed_variables.to_json
+      # hash.to_json() sometimes adds
+      # unnecessary backslashes and double quotes
+      json.delete!('\\')
+      json.gsub!(/"{/, '{')
+      json.gsub!(/}"/, '}')
+      LOG.debug 'JSONIFIED {}', inspect
+      LOG.debug 'INTO {}', json
+      json
+    end
+
+    # De-serializes an object from a JSON-originating hash.
+    #
+    # @param +hash+ [Hash] hash converted from an API-returned JSON string
+    # @return [Object] corresponding object (typed)
+    def dejsonify(hash)
+      hash.each do |tag, value|
+        field = JsonTagConverter.from_json_tag tag
+        field_value = nil
+        if field == 'type'
+          if is_a? MangoModel::BankAccount
+            field_value = MangoModel::AccountType.value_of value
+          elsif is_a? MangoModel::KycDocument
+            field_value = MangoModel::KycDocumentType.value_of value
+          elsif is_a? MangoModel::DisputeDocument
+            field_value = MangoModel::DisputeDocumentType.value_of value
+          end
+        end
+        if field == 'status'
+          if is_a? MangoModel::CardRegistration
+            field_value = MangoModel::CardStatus.value_of value
+          elsif is_a? MangoModel::PreAuthorization
+            field_value = MangoModel::PreAuthorizationStatus.value_of value
+          elsif is_a?(MangoModel::KycDocument) || is_a?(MangoModel::DisputeDocument)
+            field_value = MangoModel::DocumentStatus.value_of value
+          elsif is_a? MangoModel::UboDeclaration
+            field_value = MangoModel::UboDeclarationStatus.value_of value
+          elsif is_a? MangoModel::DeclaredUbo
+            field_value = MangoModel::DeclaredUboStatus.value_of value
+          elsif is_a? MangoModel::Hook
+            field_value = MangoModel::HookStatus.value_of value
+          elsif is_a? MangoModel::Dispute
+            field_value = MangoModel::DisputeStatus.value_of value
+          elsif is_a? MangoModel::Report
+            field_value = MangoModel::ReportStatus.value_of value
+          end
+        end
+        if is_a? MangoModel::Mandate
+          if field == 'culture'
+            field_value = MangoModel::MandateCultureCode.value_of value
+          elsif field == 'status'
+            field_value = MangoModel::MandateStatus.value_of value
+          elsif field == 'execution_type'
+            field_value = MangoModel::MandateExecutionType.value_of value
+          end
+        end
+        if field == 'execution_type' && is_a?(MangoModel::PreAuthorization)
+          field_value = MangoModel::PreAuthorizationExecutionType.value_of value
+        end
+        if field == 'payment_type' && is_a?(MangoModel::PayOut)
+          field_value = MangoModel::PayOutPaymentType.value_of value
+        end
+        if field == 'refused_reason_type'
+          if is_a? MangoModel::DeclaredUbo
+            field_value = MangoModel::DeclaredUboRefusedReasonType.value_of value
+          elsif is_a? MangoModel::DisputeDocument
+            field_value = MangoModel::DisputeDocRefusedReasonType.value_of value
+          end
+        end
+        if field == 'validity' && is_a?(MangoModel::Hook)
+          field_value = MangoModel::HookValidity.value_of value
+        end
+        if field == 'date' && is_a?(MangoModel::Event)
+          field_value = value
+        end
+        if field == 'declared_ubos' && is_a?(MangoModel::UboDeclaration)
+          field_value = []
+          value.each do |declared_ubo|
+            field_value << MangoModel::DeclaredUbo.new.dejsonify(declared_ubo)
+          end
+        end
+        if field == 'bank_account' && is_a?(MangoModel::BankWireDirectPayIn)
+          field_value = case value['Type']
+                        when MangoModel::AccountType::IBAN.to_s
+                          MangoModel::IbanBankAccount.new.dejsonify value
+                        when MangoModel::AccountType::US.to_s
+                          MangoModel::UsBankAccount.new.dejsonify value
+                        when MangoModel::AccountType::CA.to_s
+                          MangoModel::CaBankAccount.new.dejsonify value
+                        when MangoModel::AccountType::GB.to_s
+                          MangoModel::GbBankAccount.new.dejsonify value
+                        when MangoModel::AccountType::OTHER.to_s
+                          MangoModel::OtherBankAccount.new.dejsonify value
+                        else
+                          raise 'Unrecognized bank account type: ' + value['Type']
+                        end
+        end
+        unless field_value
+          field_value = case field
+                        when *MangoModel.fields_of_type(MangoModel::Address)
+                          MangoModel::Address.new.dejsonify value
+                        when *MangoModel.fields_of_type(MangoModel::Money)
+                          MangoModel::Money.new.dejsonify value
+                        when *MangoModel.fields_of_type(MangoModel::RefundReason)
+                          MangoModel::RefundReason.new.dejsonify value
+                        when *MangoModel.fields_of_type(MangoModel::DisputeReason)
+                          MangoModel::DisputeReason.new.dejsonify value
+                        when *MangoModel.fields_of_type(MangoModel::PersonType)
+                          MangoModel::PersonType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::KycLevel)
+                          MangoModel::KycLevel.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::LegalPersonType)
+                          MangoModel::LegalPersonType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::CountryIso)
+                          MangoModel::CountryIso.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::DepositType)
+                          MangoModel::DepositType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::CurrencyIso)
+                          MangoModel::CurrencyIso.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::FundsType)
+                          MangoModel::FundsType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::PlatformType)
+                          MangoModel::PlatformType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::TransactionType)
+                          MangoModel::TransactionType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::TransactionNature)
+                          MangoModel::TransactionNature.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::TransactionStatus)
+                          MangoModel::TransactionStatus.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::PayInPaymentType)
+                          MangoModel::PayInPaymentType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::PayInExecutionType)
+                          MangoModel::PayInExecutionType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::CardType)
+                          MangoModel::CardType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::SecureMode)
+                          MangoModel::SecureMode.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::CultureCode)
+                          MangoModel::CultureCode.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::CardValidity)
+                          MangoModel::CardValidity.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::PaymentStatus)
+                          MangoModel::PaymentStatus.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::DirectDebitType)
+                          MangoModel::DirectDebitType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::MandateScheme)
+                          MangoModel::MandateScheme.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::MandateType)
+                          MangoModel::MandateType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::KycDocRefusedReasonType)
+                          MangoModel::KycDocRefusedReasonType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::NaturalUserCapacity)
+                          MangoModel::NaturalUserCapacity.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::EventType)
+                          MangoModel::EventType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::RefundReasonType)
+                          MangoModel::RefundReasonType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::DisputeType)
+                          MangoModel::DisputeType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::DisputeReasonType)
+                          MangoModel::DisputeReasonType.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::DisputeStatus)
+                          MangoModel::DisputeStatus.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::DownloadFormat)
+                          MangoModel::DownloadFormat.value_of value
+                        when *MangoModel.fields_of_type(MangoModel::ReportType)
+                          MangoModel::ReportType.value_of value
+                        when *MangoModel.fields_of_type(DateTime)
+                          DateTime.parse value
+                        else
+                          value
+                        end
+        end
+        instance_variable_set "@#{field}", field_value
+      end
+      LOG.debug 'DE-JSONIFIED {}', hash
+      LOG.debug 'INTO {}', inspect
+      self
+    end
+
+    private
+
+    # Prepares a hash mapping API-standard
+    # instance variable names to their JSON values.
+    # Removes any of the fields which are considered
+    # read-only by the API
+    def hashed_variables
+      hash = {}
+      instance_variables.each do |var|
+        key = JsonTagConverter.to_json_tag var.to_s[1..-1]
+        value = json_value_for var
+        hash[key] = value
+      end
+      ReadOnlyFields.remove_from! hash
+      hash
+    end
+
+    # Converts the value in a specified instance variable
+    # to its JSON representation.
+    def json_value_for(var_name)
+      var_value = instance_variable_get var_name
+      begin
+        if var_value.singleton_class.included_modules.include? Jsonifier
+          var_value.jsonify!
+        else
+          var_value
+        end
+      rescue TypeError
+        # raised by .singleton_class() when called on primitives
+        var_value
+      end
+    end
+  end
+end