forest_admin_datasource_mambu_payments 1.33.1

data/lib/forest_admin_datasource_mambu_payments/collections/return.rb

@@ -0,0 +1,132 @@
+# rubocop:disable Metrics/ClassLength, Metrics/MethodLength
+module ForestAdminDatasourceMambuPayments
+  module Collections
+    class Return < BaseCollection
+      ManyToOneSchema = ForestAdminDatasourceToolkit::Schema::Relations::ManyToOneSchema
+
+      ENUM_DIRECTION       = %w[credit debit].freeze
+      ENUM_TYPE            = %w[sepa sepa_instant].freeze
+      ENUM_RETURN_TYPE     = %w[return refund reversal].freeze
+      ENUM_STATUS          = %w[pending sent processing executed received rejected].freeze
+      ENUM_RELATED_PAYMENT = %w[payment_order incoming_payment].freeze
+
+      client_resource :return
+
+      def initialize(datasource)
+        super(datasource, 'MambuReturn')
+        define_schema
+        define_relations
+        reconcile_filter_operators!
+      end
+
+      def create(_caller, data)
+        serialize(datasource.client.create_return(build_payload(data)))
+      end
+
+      def update(caller, filter, patch)
+        payload = build_payload(patch)
+        ids_for(caller, filter).each { |id| datasource.client.update_return(id, payload) }
+      end
+
+      def serialize(record)
+        a = attrs_of(record)
+        {
+          'id' => a['id'],
+          'object' => a['object'],
+          'connected_account_id' => a['connected_account_id'],
+          'related_payment_id' => a['related_payment_id'],
+          'related_payment_type' => a['related_payment_type'],
+          'related_payment_suspended' => a['related_payment_suspended'],
+          'return_type' => a['return_type'],
+          'type' => a['type'],
+          'direction' => a['direction'],
+          'status' => a['status'],
+          'status_details' => a['status_details'],
+          'return_reason' => a['return_reason'],
+          'amount' => a['amount'],
+          'currency' => a['currency'],
+          'reconciliation_status' => a['reconciliation_status'],
+          'reconciled_amount' => a['reconciled_amount'],
+          'value_date' => a['value_date'],
+          'booking_date' => a['booking_date'],
+          'originating_account' => a['originating_account'],
+          'receiving_account' => a['receiving_account'],
+          'aggregation_reference' => a['aggregation_reference'],
+          'file_id' => a['file_id'],
+          'metadata' => a['metadata'],
+          'created_at' => a['created_at']
+        }
+      end
+
+      protected
+
+      def collection_filters
+        {
+          'connected_account_id' => { ops: [Operators::EQUAL, Operators::IN] },
+          'related_payment_id' => { ops: [Operators::EQUAL, Operators::IN] },
+          'status' => { ops: [Operators::EQUAL, Operators::IN] },
+          'type' => { 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))
+        # related_payment_id can target a payment_order OR an incoming_payment
+        # depending on related_payment_type — we expose it as a plain string
+        # rather than a typed relation (Forest can't model the polymorphism).
+        add_field('related_payment_id', ColumnSchema.new(column_type: 'String',
+                                                         is_read_only: false, is_sortable: false))
+        add_field('related_payment_type', ColumnSchema.new(column_type: 'Enum', enum_values: ENUM_RELATED_PAYMENT,
+                                                           is_read_only: true, is_sortable: false))
+        add_field('related_payment_suspended', ColumnSchema.new(column_type: 'Boolean',
+                                                                is_read_only: false, is_sortable: false))
+        add_field('return_type', ColumnSchema.new(column_type: 'Enum', enum_values: ENUM_RETURN_TYPE,
+                                                  is_read_only: true, is_sortable: true))
+        add_field('type', ColumnSchema.new(column_type: 'Enum', enum_values: ENUM_TYPE,
+                                           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('status', ColumnSchema.new(column_type: 'Enum', enum_values: ENUM_STATUS,
+                                             is_read_only: false, is_sortable: true))
+        add_field('status_details', ColumnSchema.new(column_type: 'String', is_read_only: false, is_sortable: false))
+        add_field('return_reason', ColumnSchema.new(column_type: 'String', is_read_only: false, 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('reconciliation_status', ColumnSchema.new(column_type: 'String', is_read_only: true,
+                                                            is_sortable: false))
+        add_field('reconciled_amount', ColumnSchema.new(column_type: 'Number', is_read_only: true, is_sortable: false))
+        add_field('value_date', ColumnSchema.new(column_type: 'Date', is_read_only: true, is_sortable: true))
+        add_field('booking_date', ColumnSchema.new(column_type: 'Date', is_read_only: true, is_sortable: true))
+        add_field('originating_account', ColumnSchema.new(column_type: 'Json', is_read_only: true, is_sortable: false))
+        add_field('receiving_account', ColumnSchema.new(column_type: 'Json', is_read_only: true, is_sortable: false))
+        add_field('aggregation_reference', ColumnSchema.new(column_type: 'String', is_read_only: true,
+                                                            is_sortable: false))
+        add_field('file_id', ColumnSchema.new(column_type: 'String', is_read_only: true, is_sortable: false))
+        add_field('metadata', ColumnSchema.new(column_type: 'Json', is_read_only: false, 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
+# rubocop:enable Metrics/ClassLength, Metrics/MethodLength

data/lib/forest_admin_datasource_mambu_payments/collections/transaction.rb

@@ -0,0 +1,113 @@
+module ForestAdminDatasourceMambuPayments
+  module Collections
+    class Transaction < BaseCollection
+      ManyToOneSchema = ForestAdminDatasourceToolkit::Schema::Relations::ManyToOneSchema
+
+      ENUM_DIRECTION = %w[debit credit].freeze
+
+      client_resource :transaction
+
+      def initialize(datasource)
+        super(datasource, 'MambuTransaction')
+        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'],
+          'category' => a['category'],
+          'direction' => a['direction'],
+          'amount' => a['amount'],
+          'currency' => a['currency'],
+          'description' => a['description'],
+          'structured_reference' => a['structured_reference'],
+          'value_date' => a['value_date'],
+          'booking_date' => a['booking_date'],
+          'internal_account_id' => a['internal_account_id'],
+          'external_account_id' => a['external_account_id'],
+          'uetr' => a['uetr'],
+          'bank_data' => a['bank_data'],
+          'reconciliation_status' => a['reconciliation_status'],
+          'reconciled_amount' => a['reconciled_amount'],
+          'custom_fields' => a['custom_fields'],
+          'created_at' => a['created_at']
+        }
+      end
+
+      protected
+
+      def collection_filters
+        {
+          'connected_account_id' => { ops: [Operators::EQUAL, Operators::IN] },
+          'internal_account_id' => { ops: [Operators::EQUAL, Operators::IN] },
+          'external_account_id' => { ops: [Operators::EQUAL, Operators::IN] }
+        }
+      end
+
+      def many_to_one_embeds
+        [
+          { foreign_key: 'connected_account_id', relation_name: 'connected_account',
+            collection: 'MambuConnectedAccount' },
+          { foreign_key: 'internal_account_id', relation_name: 'internal_account',
+            collection: 'MambuInternalAccount' },
+          { foreign_key: 'external_account_id', relation_name: 'external_account',
+            collection: 'MambuExternalAccount' }
+        ]
+      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('category', 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('description', ColumnSchema.new(column_type: 'String', is_read_only: true, is_sortable: false))
+        add_field('structured_reference', ColumnSchema.new(column_type: 'String', is_read_only: true,
+                                                           is_sortable: false))
+        add_field('value_date', ColumnSchema.new(column_type: 'Date', is_read_only: true, is_sortable: true))
+        add_field('booking_date', ColumnSchema.new(column_type: 'Date', is_read_only: true, is_sortable: true))
+        add_field('internal_account_id', ColumnSchema.new(column_type: 'String',
+                                                          is_read_only: true, is_sortable: false))
+        add_field('external_account_id', ColumnSchema.new(column_type: 'String',
+                                                          is_read_only: true, is_sortable: false))
+        add_field('uetr', ColumnSchema.new(column_type: 'String', is_read_only: true, is_sortable: false))
+        add_field('bank_data', ColumnSchema.new(column_type: 'Json', is_read_only: true, is_sortable: false))
+        add_field('reconciliation_status', ColumnSchema.new(column_type: 'String', is_read_only: true,
+                                                            is_sortable: true))
+        add_field('reconciled_amount', ColumnSchema.new(column_type: 'Number', is_read_only: true, is_sortable: false))
+        add_field('custom_fields', 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'
+                                       ))
+        add_field('internal_account', ManyToOneSchema.new(
+                                        foreign_collection: 'MambuInternalAccount',
+                                        foreign_key: 'internal_account_id',
+                                        foreign_key_target: 'id'
+                                      ))
+        add_field('external_account', ManyToOneSchema.new(
+                                        foreign_collection: 'MambuExternalAccount',
+                                        foreign_key: 'external_account_id',
+                                        foreign_key_target: 'id'
+                                      ))
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/configuration.rb

@@ -0,0 +1,36 @@
+module ForestAdminDatasourceMambuPayments
+  class Configuration
+    DEFAULT_BASE_URL = 'https://api.numeral.io'.freeze
+    SANDBOX_BASE_URL = 'https://api.sandbox.numeral.io'.freeze
+    API_VERSION      = 'v1'.freeze
+
+    attr_reader :api_key, :base_url, :open_timeout, :timeout
+
+    def initialize(api_key:, base_url: nil, sandbox: false, open_timeout: 5, timeout: 30)
+      @api_key      = api_key
+      @base_url     = base_url || (sandbox ? SANDBOX_BASE_URL : DEFAULT_BASE_URL)
+      @open_timeout = open_timeout
+      @timeout      = timeout
+      validate!
+    end
+
+    def url
+      "#{@base_url.chomp("/")}/#{API_VERSION}"
+    end
+
+    private
+
+    def validate!
+      missing = []
+      missing << 'api_key' if blank?(@api_key)
+      return if missing.empty?
+
+      raise ConfigurationError,
+            "ForestAdminDatasourceMambuPayments missing required config: #{missing.join(", ")}"
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/datasource.rb

@@ -0,0 +1,35 @@
+module ForestAdminDatasourceMambuPayments
+  class Datasource < ForestAdminDatasourceToolkit::Datasource
+    attr_reader :client, :configuration
+
+    def initialize(api_key:, base_url: nil, sandbox: false)
+      super()
+      @configuration = Configuration.new(api_key: api_key, base_url: base_url, sandbox: sandbox)
+      @client = Client.new(@configuration)
+
+      register_collections
+    end
+
+    private
+
+    def register_collections
+      add_collection(Collections::ConnectedAccount.new(self))
+      add_collection(Collections::PaymentOrder.new(self))
+      add_collection(Collections::Transaction.new(self))
+      add_collection(Collections::Balance.new(self))
+      add_collection(Collections::AccountHolder.new(self))
+      add_collection(Collections::ExternalAccount.new(self))
+      add_collection(Collections::InternalAccount.new(self))
+      add_collection(Collections::IncomingPayment.new(self))
+      add_collection(Collections::DirectDebitMandate.new(self))
+      add_collection(Collections::ExpectedPayment.new(self))
+      add_collection(Collections::Event.new(self))
+      add_collection(Collections::File.new(self))
+      add_collection(Collections::Return.new(self))
+      add_collection(Collections::Claim.new(self))
+      add_collection(Collections::Reconciliation.new(self))
+      add_collection(Collections::PaymentCapture.new(self))
+      add_collection(Collections::PayeeVerificationRequest.new(self))
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/disable_search.rb

@@ -0,0 +1,31 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    # Numeral's list endpoints have no free-text search. Forest emulates search
+    # by OR-ing a condition over every searchable column, which the
+    # ConditionTreeTranslator deliberately rejects (it cannot push an OR to
+    # Numeral) — so an operator typing in the search bar would get an error.
+    #
+    # This plugin turns the search bar off on every Mambu collection, which is
+    # the honest behaviour: the API can filter (per `api_filters`) but not
+    # search. Install it once at the datasource level:
+    #
+    #   @agent.use(ForestAdminDatasourceMambuPayments::Plugins::DisableSearch, {})
+    class DisableSearch < ForestAdminDatasourceCustomizer::Plugins::Plugin
+      COLLECTIONS = %w[
+        MambuConnectedAccount MambuPaymentOrder MambuTransaction MambuBalance
+        MambuAccountHolder MambuExternalAccount MambuInternalAccount
+        MambuIncomingPayment MambuDirectDebitMandate MambuExpectedPayment
+        MambuEvent MambuFile MambuReturn MambuClaim MambuReconciliation
+        MambuPaymentCapture MambuPayeeVerificationRequest
+      ].freeze
+
+      def run(datasource_customizer, _collection_customizer = nil, _options = {})
+        Helpers.require_datasource!(datasource_customizer, self.class)
+
+        COLLECTIONS.each do |name|
+          datasource_customizer.customize_collection(name, &:disable_search)
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/helpers.rb

@@ -0,0 +1,94 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    # Shared helpers for Mambu Payments plugins: input normalization, host
+    # record id resolution, and per-id rescue logic for bulk transitions.
+    module Helpers
+      ActionScope = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+
+      SCOPE_KEYS = %i[single bulk].freeze
+      SCOPES = { single: ActionScope::SINGLE, bulk: ActionScope::BULK }.freeze
+
+      module_function
+
+      # Relation plugins must be installed at the datasource level
+      # (`@agent.use(plugin, {})`) so they can customize several collections at
+      # once. Raises a clear error when a caller installs one on a single
+      # collection instead.
+      def require_datasource!(datasource_customizer, plugin_class)
+        return if datasource_customizer
+
+        name = plugin_class.is_a?(Class) ? plugin_class.name.split('::').last : plugin_class
+        raise ArgumentError,
+              "#{name} must be installed at the datasource level via @agent.use(plugin, {})"
+      end
+
+      def normalize_scopes(value)
+        list = Array(value).map(&:to_sym).uniq
+        list = SCOPE_KEYS if list.empty?
+        unknown = list - SCOPE_KEYS
+        return list if unknown.empty?
+
+        raise ForestAdminDatasourceToolkit::Exceptions::ForestException,
+              "Unknown scopes: #{unknown.join(", ")}. Allowed: #{SCOPE_KEYS.join(", ")}."
+      end
+
+      def resolve_ids(context, field)
+        records = context.get_records([field])
+        records = [records].compact unless records.is_a?(Array)
+        records.filter_map { |r| r[field] || r[field.to_sym] }
+      rescue StandardError => e
+        ForestAdminDatasourceMambuPayments.logger.warn(
+          "[forest_admin_datasource_mambu_payments] failed to resolve ids from '#{field}': " \
+          "#{e.class}: #{e.message}"
+        )
+        []
+      end
+
+      # Per-id rescue so a single API failure doesn't abort the remaining ids.
+      def each_with_rescue(ids, label)
+        succeeded = []
+        failed = []
+        ids.each do |id|
+          yield id
+          succeeded << id
+        rescue StandardError => e
+          ForestAdminDatasourceMambuPayments.logger.warn(
+            "[forest_admin_datasource_mambu_payments] #{label} failed for ##{id}: #{e.class}: #{e.message}"
+          )
+          failed << [id, "#{e.class}: #{e.message}"]
+        end
+        [succeeded, failed]
+      end
+
+      def present?(value)
+        !value.nil? && value.to_s != ''
+      end
+
+      def to_int(value)
+        return nil unless present?(value)
+
+        Integer(value.to_s)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def write_back(context, field, value)
+        return :skipped if field.nil? || value.nil?
+
+        context.collection.update(context.filter, { field => value })
+        :ok
+      rescue StandardError => e
+        ForestAdminDatasourceMambuPayments.logger.warn(
+          "[forest_admin_datasource_mambu_payments] write-back to '#{field}' failed: #{e.class}: #{e.message}"
+        )
+        [:failed, "#{e.class}: #{e.message}"]
+      end
+
+      def write_back_warning(writeback)
+        return nil unless writeback.is_a?(Array) && writeback.first == :failed
+
+        " (warning: could not write the id back to the host record: #{writeback.last})"
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/messages.rb

@@ -0,0 +1,30 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Messages
+      module_function
+
+      def success(succeeded, failed, noun:, verb_past:)
+        [succeeded_phrase(succeeded, noun, verb_past), failed_phrase(failed, noun)].compact.join(' ')
+      end
+
+      def all_failed(failed, noun:, verb:)
+        return "Failed to #{verb} #{noun} ##{failed.first.first}: #{failed.first.last}" if failed.size == 1
+
+        "Failed to #{verb} all #{failed.size} #{noun}s. First error: #{failed.first.last}"
+      end
+
+      def succeeded_phrase(succeeded, noun, verb_past)
+        return nil if succeeded.empty?
+        return "#{noun.capitalize} ##{succeeded.first} #{verb_past}." if succeeded.size == 1
+
+        "#{succeeded.size} #{noun}s #{verb_past}."
+      end
+
+      def failed_phrase(failed, _noun)
+        return nil if failed.empty?
+
+        "#{failed.size} failed: #{failed.map(&:first).join(", ")}."
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/relations/holder_link_plugin.rb

@@ -0,0 +1,56 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Relations
+      # Base for AccountHolder links reached transitively through an account
+      # relation. The `host` imports `account_holder_id` from a related account,
+      # exposes a ManyToOne to AccountHolder, and gets a TwoStepHolderFilter
+      # (which rewrites holder filters onto `local_fk`); AccountHolder gets the
+      # reciprocal OneToMany. Subclasses configure it declaratively:
+      #
+      #   class LinkAccountHolderToIncomingPayments < HolderLinkPlugin
+      #     link host: 'MambuIncomingPayment', name: 'incoming_payments',
+      #          local_fk: 'internal_account_id', intermediate: 'MambuInternalAccount',
+      #          import_path: 'internal_account:account_holder_id'
+      #   end
+      #
+      # Install at the datasource level: @agent.use(plugin, {}).
+      class HolderLinkPlugin < ForestAdminDatasourceCustomizer::Plugins::Plugin
+        ACCOUNT_HOLDER = 'MambuAccountHolder'.freeze
+        FK_NAME = 'account_holder_id'.freeze
+
+        class << self
+          attr_reader :config
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def self.link(host:, name:, local_fk:, intermediate:, import_path:, many_to_one_name: 'account_holder')
+          @config = {
+            host: host, name: name, local_fk: local_fk, intermediate: intermediate,
+            import_path: import_path, many_to_one_name: many_to_one_name
+          }
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def run(datasource_customizer, _collection_customizer = nil, _options = {})
+          Plugins::Helpers.require_datasource!(datasource_customizer, self.class)
+
+          cfg = self.class.config
+          datasource_customizer.customize_collection(cfg[:host]) do |c|
+            c.import_field(FK_NAME, path: cfg[:import_path], readonly: true)
+            c.add_many_to_one_relation(cfg[:many_to_one_name], ACCOUNT_HOLDER,
+                                       foreign_key: FK_NAME, foreign_key_target: 'id')
+            TwoStepHolderFilter.install(c,
+                                        fk_name: FK_NAME,
+                                        local_fk: cfg[:local_fk],
+                                        intermediate_collection: cfg[:intermediate])
+          end
+
+          datasource_customizer.customize_collection(ACCOUNT_HOLDER) do |c|
+            c.add_one_to_many_relation(cfg[:name], cfg[:host],
+                                       origin_key: FK_NAME, origin_key_target: 'id')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/relations/link_account_holder_to_direct_debit_mandates.rb

@@ -0,0 +1,14 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Relations
+      # AccountHolder <-> DirectDebitMandate, transitive via the external account
+      # (DirectDebitMandate.external_account.account_holder_id).
+      # Install at the datasource level: @agent.use(plugin, {}).
+      class LinkAccountHolderToDirectDebitMandates < HolderLinkPlugin
+        link host: 'MambuDirectDebitMandate', name: 'direct_debit_mandates',
+             local_fk: 'external_account_id', intermediate: 'MambuExternalAccount',
+             import_path: 'external_account:account_holder_id'
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/relations/link_account_holder_to_incoming_payments.rb

@@ -0,0 +1,14 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Relations
+      # AccountHolder <-> IncomingPayment, transitive via the internal account
+      # (IncomingPayment.internal_account.account_holder_id).
+      # Install at the datasource level: @agent.use(plugin, {}).
+      class LinkAccountHolderToIncomingPayments < HolderLinkPlugin
+        link host: 'MambuIncomingPayment', name: 'incoming_payments',
+             local_fk: 'internal_account_id', intermediate: 'MambuInternalAccount',
+             import_path: 'internal_account:account_holder_id'
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/relations/link_external_account_to_direct_debit_mandates.rb

@@ -0,0 +1,13 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Relations
+      # Reciprocal OneToMany on MambuExternalAccount for the native
+      # DirectDebitMandate.external_account ManyToOne.
+      # Install at the datasource level: @agent.use(plugin, {}).
+      class LinkExternalAccountToDirectDebitMandates < OneToManyLinkPlugin
+        link host: 'MambuExternalAccount', to: 'MambuDirectDebitMandate',
+             name: 'direct_debit_mandates', origin_key: 'external_account_id'
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/relations/link_external_account_to_incoming_payments.rb

@@ -0,0 +1,13 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Relations
+      # Reciprocal OneToMany on MambuExternalAccount for the native
+      # IncomingPayment.external_account ManyToOne.
+      # Install at the datasource level: @agent.use(plugin, {}).
+      class LinkExternalAccountToIncomingPayments < OneToManyLinkPlugin
+        link host: 'MambuExternalAccount', to: 'MambuIncomingPayment',
+             name: 'incoming_payments', origin_key: 'external_account_id'
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/relations/link_external_account_to_payment_orders.rb

@@ -0,0 +1,13 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Relations
+      # Reciprocal OneToMany on MambuExternalAccount for the native
+      # PaymentOrder.external_account ManyToOne (receiving account).
+      # Install at the datasource level: @agent.use(plugin, {}).
+      class LinkExternalAccountToPaymentOrders < OneToManyLinkPlugin
+        link host: 'MambuExternalAccount', to: 'MambuPaymentOrder',
+             name: 'payment_orders', origin_key: 'receiving_account_id'
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/relations/link_incoming_payment_to_events.rb

@@ -0,0 +1,13 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Relations
+      # OneToMany on MambuIncomingPayment over Event.related_object_id
+      # (events emitted for this incoming payment).
+      # Install at the datasource level: @agent.use(plugin, {}).
+      class LinkIncomingPaymentToEvents < OneToManyLinkPlugin
+        link host: 'MambuIncomingPayment', to: 'MambuEvent',
+             name: 'events', origin_key: 'related_object_id'
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/relations/link_incoming_payment_to_expected_payments.rb

@@ -0,0 +1,21 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Relations
+      # IncomingPayment <-> ExpectedPayment matched through two reconciliations
+      # sharing a transaction (cross-pivot resolution).
+      # Install at the datasource level: @agent.use(plugin, {}).
+      class LinkIncomingPaymentToExpectedPayments < TwoStepLinkPlugin
+        link owner: 'MambuIncomingPayment', filtered: 'MambuExpectedPayment',
+             name: 'matched_expected_payments', foreign_key: 'incoming_payment_id'
+
+        def install_source_filter(collection)
+          TwoStepCrossReconciliationFilter.install(collection,
+                                                   fk_name: 'incoming_payment_id',
+                                                   src_payment_type: 'incoming_payment',
+                                                   dst_payment_type: 'expected_payment',
+                                                   target_field: 'id')
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/relations/link_incoming_payment_to_returns.rb

@@ -0,0 +1,12 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module Relations
+      # OneToMany on MambuIncomingPayment over Return.related_payment_id.
+      # Install at the datasource level: @agent.use(plugin, {}).
+      class LinkIncomingPaymentToReturns < OneToManyLinkPlugin
+        link host: 'MambuIncomingPayment', to: 'MambuReturn',
+             name: 'returns', origin_key: 'related_payment_id'
+      end
+    end
+  end
+end