forest_admin_datasource_mambu_payments 1.33.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75e0d0f5bf5d786f1b1b546d6f9b6c2f1ba9a84ea34af18c886c3dff870bb2bb
+  data.tar.gz: a20371a99995fbca040eab5fe38eef71867bb5b093bdbaad20e2d542ff735cf7
+SHA512:
+  metadata.gz: d23380a9dc6ce5487ec104f2f2ca57b1c65c9239ce16ebf2c8845c290134904d363d318868de4252be95b82934b7ad601df5b71efce60cfb8290f0312f1760d6
+  data.tar.gz: 7fc354ae457585278d86cf4d1244a8c22028df25fa9928a512bfd9aa6f385c4cae289395f27643329c37c23ec2b36481fb3099e24a222981fa7a0f5b84ee59f7

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/forest_admin_datasource_mambu_payments.gemspec

@@ -0,0 +1,37 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+
+require_relative 'lib/forest_admin_datasource_mambu_payments/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'forest_admin_datasource_mambu_payments'
+  spec.version     = ForestAdminDatasourceMambuPayments::VERSION
+  spec.authors     = ['Forest Admin']
+  spec.email       = ['contact@forestadmin.com']
+  spec.homepage    = 'https://www.forestadmin.com'
+  spec.summary     = 'Mambu Payments (Numeral) datasource for Forest Admin Ruby agent.'
+  spec.description = 'Surface Mambu Payments connected accounts, payment orders, ' \
+                     'transactions and balances as Forest Admin collections.'
+  spec.license     = 'GPL-3.0'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/ForestAdmin/agent-ruby'
+  spec.metadata['changelog_uri']   = 'https://github.com/ForestAdmin/agent-ruby/blob/main/CHANGELOG.md'
+  spec.metadata['rubygems_mfa_required'] = 'false'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 6.1'
+  spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'faraday-retry', '~> 2.0'
+  spec.add_dependency 'zeitwerk', '~> 2.3'
+end

data/lib/forest_admin_datasource_mambu_payments/client/reads.rb

@@ -0,0 +1,66 @@
+module ForestAdminDatasourceMambuPayments
+  class Client
+    module Reads
+      def list_connected_accounts(**params)  = list_resource('connected_accounts', params)
+      def find_connected_account(id)         = get_resource('connected_accounts', id)
+
+      def list_payment_orders(**params)  = list_resource('payment_orders', params)
+      def find_payment_order(id)         = get_resource('payment_orders', id)
+
+      def list_transactions(**params)  = list_resource('transactions', params)
+      def find_transaction(id)         = get_resource('transactions', id)
+
+      def list_balances(**params)  = list_resource('balances', params)
+      def find_balance(id)         = get_resource('balances', id)
+
+      def list_account_holders(**params)  = list_resource('account_holders', params)
+      def find_account_holder(id)         = get_resource('account_holders', id)
+
+      def list_external_accounts(**params)  = list_resource('external_accounts', params)
+      def find_external_account(id)         = get_resource('external_accounts', id)
+
+      def list_internal_accounts(**params)  = list_resource('internal_accounts', params)
+      def find_internal_account(id)         = get_resource('internal_accounts', id)
+
+      def list_incoming_payments(**params)  = list_resource('incoming_payments', params)
+      def find_incoming_payment(id)         = get_resource('incoming_payments', id)
+
+      def list_direct_debit_mandates(**params)  = list_resource('direct_debit_mandates', params)
+      def find_direct_debit_mandate(id)         = get_resource('direct_debit_mandates', id)
+
+      def list_expected_payments(**params)  = list_resource('expected_payments', params)
+      def find_expected_payment(id)         = get_resource('expected_payments', id)
+
+      def list_events(**params)  = list_resource('events', params)
+      def find_event(id)         = get_resource('events', id)
+
+      def list_files(**params)  = list_resource('files', params)
+      def find_file(id)         = get_resource('files', id)
+
+      def list_returns(**params)  = list_resource('returns', params)
+      def find_return(id)         = get_resource('returns', id)
+
+      # Claims are arrived-from-the-network resources (created via the sandbox
+      # simulator or by the counterparty bank). No POST/PATCH/DELETE here:
+      # accept/reject are lifecycle actions and would belong in a plugin.
+      def list_claims(**params)  = list_resource('claims', params)
+      def find_claim(id)         = get_resource('claims', id)
+
+      def list_reconciliations(**params)  = list_resource('reconciliations', params)
+      def find_reconciliation(id)         = get_resource('reconciliations', id)
+
+      # Payment captures are emitted by PSPs (or registered manually via API
+      # to reconcile reporting files). create/update/cancel exist on the
+      # Numeral API but are lifecycle operations deferred to a future plugin.
+      def list_payment_captures(**params)  = list_resource('payment_captures', params)
+      def find_payment_capture(id)         = get_resource('payment_captures', id)
+
+      # Payee verification requests are emitted by Numeral when an outgoing
+      # verification is sent (via the TriggerPayeeVerification plugin) or
+      # when an incoming verification arrives from the network. send /
+      # simulate are exposed as smart actions, not collection writes.
+      def list_payee_verification_requests(**params)  = list_resource('payee_verification_requests', params)
+      def find_payee_verification_request(id)         = get_resource('payee_verification_requests', id)
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/client/writes.rb

@@ -0,0 +1,42 @@
+module ForestAdminDatasourceMambuPayments
+  class Client
+    module Writes
+      def create_payment_order(attrs)     = post_resource('payment_orders', attrs)
+      def update_payment_order(id, attrs) = patch_resource('payment_orders', id, attrs)
+      def delete_payment_order(id)        = delete_resource('payment_orders', id)
+      def approve_payment_order(id, attrs = {}) = post_action_resource('payment_orders', id, 'approve', attrs)
+      def cancel_payment_order(id, attrs = {})  = post_action_resource('payment_orders', id, 'cancel', attrs)
+
+      def create_account_holder(attrs)     = post_resource('account_holders', attrs)
+      def update_account_holder(id, attrs) = patch_resource('account_holders', id, attrs)
+      def delete_account_holder(id)        = delete_resource('account_holders', id)
+
+      def create_external_account(attrs)     = post_resource('external_accounts', attrs)
+      def update_external_account(id, attrs) = patch_resource('external_accounts', id, attrs)
+      def delete_external_account(id)        = delete_resource('external_accounts', id)
+      def verify_external_account(id, attrs = {}) = post_action_resource('external_accounts', id, 'verify', attrs)
+
+      def create_internal_account(attrs)     = post_resource('internal_accounts', attrs)
+      def update_internal_account(id, attrs) = patch_resource('internal_accounts', id, attrs)
+      def delete_internal_account(id)        = delete_resource('internal_accounts', id)
+
+      def create_direct_debit_mandate(attrs)     = post_resource('direct_debit_mandates', attrs)
+      def update_direct_debit_mandate(id, attrs) = patch_resource('direct_debit_mandates', id, attrs)
+      def delete_direct_debit_mandate(id)        = delete_resource('direct_debit_mandates', id)
+
+      def create_expected_payment(attrs)     = post_resource('expected_payments', attrs)
+      def update_expected_payment(id, attrs) = patch_resource('expected_payments', id, attrs)
+      def delete_expected_payment(id)        = delete_resource('expected_payments', id)
+
+      # Numeral has no DELETE on /returns; the lifecycle "cancel"/"approve" are
+      # exposed as side-effect actions and would belong in a plugin, not here.
+      def create_return(attrs)     = post_resource('returns', attrs)
+      def update_return(id, attrs) = patch_resource('returns', id, attrs)
+
+      # Numeral has no DELETE on /reconciliations either; cancel is a lifecycle
+      # action and is deferred to a future plugin.
+      def create_reconciliation(attrs)     = post_resource('reconciliations', attrs)
+      def update_reconciliation(id, attrs) = patch_resource('reconciliations', id, attrs)
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/client.rb

@@ -0,0 +1,166 @@
+module ForestAdminDatasourceMambuPayments
+  # rubocop:disable Metrics/ClassLength
+  class Client
+    include Reads
+    include Writes
+
+    MAX_PER_PAGE = 100
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    private
+
+    def list_resource(path, params = {})
+      must_succeed("list(#{path})") do
+        body = connection.get(path, normalize_params(params)).body
+        extract_records(body, path)
+      end
+    end
+
+    def get_resource(path, id)
+      extract_record(connection.get("#{path}/#{id}").body)
+    rescue Faraday::ResourceNotFound
+      nil
+    rescue Faraday::Error => e
+      raise api_error("get(#{path}/#{id})", e)
+    rescue StandardError => e
+      raise APIError, "Mambu Payments API call failed: get(#{path}/#{id}): #{e.class}: #{e.message}"
+    end
+
+    def post_resource(path, attributes)
+      must_succeed("create(#{path})") do
+        extract_record(connection.post(path, attributes).body)
+      end
+    end
+
+    def patch_resource(path, id, attributes)
+      must_succeed("update(#{path}/#{id})") do
+        extract_record(connection.patch("#{path}/#{id}", attributes).body)
+      end
+    end
+
+    # POST .../:id/:action — Numeral exposes side-effect endpoints (approve,
+    # cancel, verify) as sub-paths returning the updated resource.
+    def post_action_resource(path, id, action, attributes = {})
+      must_succeed("#{action}(#{path}/#{id})") do
+        extract_record(connection.post("#{path}/#{id}/#{action}", attributes).body)
+      end
+    end
+
+    # Numeral list responses are typically wrapped (e.g. { "data": [...] } or
+    # { "connected_accounts": [...] }) but we accept a raw array too. Falls back
+    # to the first array-valued field so we don't silently coerce a wrapper hash
+    # into an array of [key, value] pairs.
+    def extract_records(body, path)
+      return body if body.is_a?(Array)
+      return [] unless body.is_a?(Hash)
+
+      wrapped = body['data'] || body[path] || body['records'] || body['items']
+      wrapped.is_a?(Array) ? wrapped : fallback_records(body, path)
+    end
+
+    # Last resort when the wrapper key is unknown: return the first array-valued
+    # field, logging that we guessed so an unexpected envelope is visible.
+    def fallback_records(body, path)
+      fallback = body.values.find { |v| v.is_a?(Array) }
+      return [] unless fallback
+
+      ForestAdminDatasourceMambuPayments.logger.warn(
+        "[forest_admin_datasource_mambu_payments] list(#{path}) used wrapper-key fallback; " \
+        "body keys=#{body.keys.inspect}"
+      )
+      fallback
+    end
+
+    def extract_record(body)
+      return nil if body.nil?
+      return body['data'] if body.is_a?(Hash) && body['data'].is_a?(Hash)
+
+      body
+    end
+
+    def delete_resource(path, id)
+      must_succeed("delete(#{path}/#{id})") do
+        connection.delete("#{path}/#{id}")
+        true
+      end
+    end
+
+    def normalize_params(params)
+      params.compact.transform_values { |v| v.is_a?(Array) ? v.join(',') : v }
+    end
+
+    def must_succeed(operation)
+      yield
+    rescue Faraday::Error => e
+      raise api_error(operation, e)
+    rescue StandardError => e
+      raise APIError, "Mambu Payments API call failed: #{operation}: #{e.class}: #{e.message}"
+    end
+
+    # Builds an APIError that preserves the HTTP status and the API's own error
+    # body. Numeral returns structured validation errors (e.g. on a 422), which
+    # smart actions surface to the operator instead of a generic failure string.
+    def api_error(operation, error)
+      response = error.respond_to?(:response) ? error.response : nil
+      status = response.is_a?(Hash) ? response[:status] : nil
+      body   = response.is_a?(Hash) ? response[:body] : nil
+      detail = error_detail(status, body) || "#{error.class}: #{error.message}"
+      APIError.new("Mambu Payments API call failed: #{operation}: #{detail}", status: status, body: parse_body(body))
+    end
+
+    def error_detail(status, body)
+      return nil unless status
+
+      ["HTTP #{status}", error_message(parse_body(body))].compact.join(' ').strip
+    end
+
+    # Pulls the human-readable message out of the common Numeral error shapes
+    # ({ "error": { "message": ... } }, { "errors": [...] }, { "message": ... }).
+    def error_message(parsed)
+      return parsed.to_s[0, 500] unless parsed.is_a?(Hash)
+
+      message = parsed.dig('error', 'message') || parsed['message'] || parsed['detail'] || join_errors(parsed['errors'])
+      (message.to_s.empty? ? parsed.to_json : message)[0, 500]
+    end
+
+    def join_errors(errors)
+      Array(errors).filter_map { |e| e.is_a?(Hash) ? (e['message'] || e['detail']) : e }.join('; ')
+    end
+
+    def parse_body(body)
+      return body unless body.is_a?(String) && !body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def best_effort(operation, default:)
+      yield
+    rescue StandardError => e
+      ForestAdminDatasourceMambuPayments.logger.warn(
+        "[forest_admin_datasource_mambu_payments] #{operation} failed; degrading: #{e.class}: #{e.message}"
+      )
+      default
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: @configuration.url) do |f|
+        f.request :json
+        f.request :retry, max: 3, interval: 0.2, backoff_factor: 2,
+                          retry_statuses: [429, 502, 503, 504]
+        f.response :json
+        f.response :raise_error
+        f.headers['x-api-key']  = @configuration.api_key
+        f.headers['Accept']     = 'application/json'
+        f.headers['User-Agent'] = "forest_admin_datasource_mambu_payments/#{VERSION}"
+        f.options.open_timeout = @configuration.open_timeout
+        f.options.timeout      = @configuration.timeout
+      end
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/forest_admin_datasource_mambu_payments/collections/account_holder.rb

@@ -0,0 +1,64 @@
+module ForestAdminDatasourceMambuPayments
+  module Collections
+    class AccountHolder < BaseCollection
+      OneToManySchema = ForestAdminDatasourceToolkit::Schema::Relations::OneToManySchema
+
+      client_resource :account_holder
+
+      def initialize(datasource)
+        super(datasource, 'MambuAccountHolder')
+        define_schema
+        define_relations
+        reconcile_filter_operators!
+      end
+
+      def create(_caller, data)
+        serialize(datasource.client.create_account_holder(build_payload(data)))
+      end
+
+      def update(caller, filter, patch)
+        payload = build_payload(patch)
+        ids_for(caller, filter).each { |id| datasource.client.update_account_holder(id, payload) }
+      end
+
+      def delete(caller, filter)
+        ids_for(caller, filter).each { |id| datasource.client.delete_account_holder(id) }
+      end
+
+      def serialize(record)
+        a = attrs_of(record)
+        {
+          'id' => a['id'],
+          'object' => a['object'],
+          'name' => a['name'],
+          'metadata' => a['metadata'],
+          'disabled_at' => a['disabled_at'],
+          'created_at' => a['created_at']
+        }
+      end
+
+      private
+
+      def define_schema
+        add_field('id', ColumnSchema.new(column_type: 'String', is_primary_key: true,
+                                         is_read_only: true, is_sortable: true))
+        add_field('object', ColumnSchema.new(column_type: 'String', is_read_only: true, is_sortable: false))
+        add_field('name', ColumnSchema.new(column_type: 'String', is_read_only: false, is_sortable: true))
+        add_field('metadata', ColumnSchema.new(column_type: 'Json', is_read_only: false, is_sortable: false))
+        add_field('disabled_at', ColumnSchema.new(column_type: 'Date', is_read_only: true, is_sortable: true))
+        add_field('created_at', ColumnSchema.new(column_type: 'Date', is_read_only: true, is_sortable: true))
+      end
+
+      def define_relations
+        add_field('external_accounts', OneToManySchema.new(
+                                         foreign_collection: 'MambuExternalAccount',
+                                         origin_key: 'account_holder_id', origin_key_target: 'id'
+                                       ))
+        add_field('internal_accounts', OneToManySchema.new(
+                                         foreign_collection: 'MambuInternalAccount',
+                                         origin_key: 'account_holder_id', origin_key_target: 'id'
+                                       ))
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/collections/balance.rb

@@ -0,0 +1,75 @@
+module ForestAdminDatasourceMambuPayments
+  module Collections
+    class Balance < BaseCollection
+      ManyToOneSchema = ForestAdminDatasourceToolkit::Schema::Relations::ManyToOneSchema
+
+      ENUM_DIRECTION = %w[debit credit].freeze
+
+      client_resource :balance
+
+      def initialize(datasource)
+        super(datasource, 'MambuBalance')
+        define_schema
+        define_relations
+        reconcile_filter_operators!
+      end
+
+      def serialize(record)
+        a = attrs_of(record)
+        {
+          'id' => a['id'],
+          'object' => a['object'],
+          'connected_account_id' => a['connected_account_id'],
+          'type' => a['type'],
+          'direction' => a['direction'],
+          'amount' => a['amount'],
+          'currency' => a['currency'],
+          'date' => a['date'],
+          'bank_data' => a['bank_data'],
+          'created_at' => a['created_at']
+        }
+      end
+
+      protected
+
+      def collection_filters
+        {
+          'connected_account_id' => { ops: [Operators::EQUAL, Operators::IN] }
+        }
+      end
+
+      def many_to_one_embeds
+        [
+          { foreign_key: 'connected_account_id', relation_name: 'connected_account',
+            collection: 'MambuConnectedAccount' }
+        ]
+      end
+
+      private
+
+      def define_schema
+        add_field('id', ColumnSchema.new(column_type: 'String', is_primary_key: true,
+                                         is_read_only: true, is_sortable: true))
+        add_field('object', ColumnSchema.new(column_type: 'String', is_read_only: true, is_sortable: false))
+        add_field('connected_account_id', ColumnSchema.new(column_type: 'String',
+                                                           is_read_only: true, is_sortable: true))
+        add_field('type', ColumnSchema.new(column_type: 'String', is_read_only: true, is_sortable: true))
+        add_field('direction', ColumnSchema.new(column_type: 'Enum', enum_values: ENUM_DIRECTION,
+                                                is_read_only: true, is_sortable: false))
+        add_field('amount', ColumnSchema.new(column_type: 'Number', is_read_only: true, is_sortable: false))
+        add_field('currency', ColumnSchema.new(column_type: 'String', is_read_only: true, is_sortable: false))
+        add_field('date', ColumnSchema.new(column_type: 'Date', is_read_only: true, is_sortable: true))
+        add_field('bank_data', ColumnSchema.new(column_type: 'Json', is_read_only: true, is_sortable: false))
+        add_field('created_at', ColumnSchema.new(column_type: 'Date', is_read_only: true, is_sortable: true))
+      end
+
+      def define_relations
+        add_field('connected_account', ManyToOneSchema.new(
+                                         foreign_collection: 'MambuConnectedAccount',
+                                         foreign_key: 'connected_account_id',
+                                         foreign_key_target: 'id'
+                                       ))
+      end
+    end
+  end
+end