forest_admin_datasource_mambu_payments 1.33.1

data/lib/forest_admin_datasource_mambu_payments/plugins/smart_actions/create_account_holder.rb

@@ -0,0 +1,44 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module SmartActions
+      class CreateAccountHolder < ForestAdminDatasourceCustomizer::Plugins::Plugin
+        BaseAction  = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+        ActionScope = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+        FieldType   = ForestAdminDatasourceCustomizer::Decorators::Action::Types::FieldType
+
+        NAME = 'Create Mambu account holder'.freeze
+
+        def run(_datasource_customizer, collection_customizer = nil, options = {})
+          datasource = options[:datasource]
+          raise ArgumentError, 'CreateAccountHolder plugin requires :datasource' unless datasource
+          raise ArgumentError, 'CreateAccountHolder plugin requires a collection' unless collection_customizer
+
+          collection_customizer.add_action(options[:action_name] || NAME, build_action(datasource, options))
+        end
+
+        private
+
+        def build_action(datasource, opts)
+          BaseAction.new(scope: ActionScope::SINGLE, form: form, &executor(datasource, opts))
+        end
+
+        def form
+          [{ type: FieldType::STRING, label: 'Name', is_required: true,
+             description: 'Display name of the account holder.' }]
+        end
+
+        def executor(datasource, opts)
+          lambda do |context, result_builder|
+            values = context.form_values
+            payload = { 'name' => values['Name'] }
+            holder = datasource.client.create_account_holder(payload)
+            id = holder.is_a?(Hash) ? holder['id'] : nil
+            writeback = Helpers.write_back(context, opts[:result_field], id)
+            message = id ? "Account holder ##{id} created." : 'Account holder created.'
+            result_builder.success(message: "#{message}#{Helpers.write_back_warning(writeback)}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/smart_actions/create_external_account.rb

@@ -0,0 +1,54 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module SmartActions
+      class CreateExternalAccount < ForestAdminDatasourceCustomizer::Plugins::Plugin
+        BaseAction  = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+        ActionScope = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+        FieldType   = ForestAdminDatasourceCustomizer::Decorators::Action::Types::FieldType
+
+        NAME = 'Create Mambu external account'.freeze
+
+        def run(_datasource_customizer, collection_customizer = nil, options = {})
+          datasource = options[:datasource]
+          raise ArgumentError, 'CreateExternalAccount plugin requires :datasource' unless datasource
+          raise ArgumentError, 'CreateExternalAccount plugin requires a collection' unless collection_customizer
+
+          collection_customizer.add_action(options[:action_name] || NAME, build_action(datasource, options))
+        end
+
+        private
+
+        def build_action(datasource, opts)
+          BaseAction.new(scope: ActionScope::SINGLE, form: form, &executor(datasource, opts))
+        end
+
+        def form
+          [
+            { type: FieldType::STRING, label: 'Holder name', is_required: true,
+              description: 'Name of the legal entity or individual holding the account.' },
+            { type: FieldType::STRING, label: 'Account number', is_required: true,
+              description: 'IBAN, UK account number, or local format.' },
+            { type: FieldType::STRING, label: 'Bank code', is_required: true,
+              description: 'BIC, UK sort code, US routing number, or local equivalent.' }
+          ]
+        end
+
+        def executor(datasource, opts)
+          lambda do |context, result_builder|
+            values = context.form_values
+            payload = {
+              'holder_name' => values['Holder name'],
+              'account_number' => values['Account number'],
+              'bank_code' => values['Bank code']
+            }
+            account = datasource.client.create_external_account(payload)
+            id = account.is_a?(Hash) ? account['id'] : nil
+            writeback = Helpers.write_back(context, opts[:result_field], id)
+            message = id ? "External account ##{id} created." : 'External account created.'
+            result_builder.success(message: "#{message}#{Helpers.write_back_warning(writeback)}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/smart_actions/create_internal_account.rb

@@ -0,0 +1,58 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module SmartActions
+      class CreateInternalAccount < ForestAdminDatasourceCustomizer::Plugins::Plugin
+        BaseAction  = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+        ActionScope = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+        FieldType   = ForestAdminDatasourceCustomizer::Decorators::Action::Types::FieldType
+
+        NAME = 'Create Mambu internal account'.freeze
+        TYPES = %w[own virtual].freeze
+
+        def run(_datasource_customizer, collection_customizer = nil, options = {})
+          datasource = options[:datasource]
+          raise ArgumentError, 'CreateInternalAccount plugin requires :datasource' unless datasource
+          raise ArgumentError, 'CreateInternalAccount plugin requires a collection' unless collection_customizer
+
+          collection_customizer.add_action(options[:action_name] || NAME, build_action(datasource, options))
+        end
+
+        private
+
+        def build_action(datasource, opts)
+          BaseAction.new(scope: ActionScope::SINGLE, form: form, &executor(datasource, opts))
+        end
+
+        def form
+          [
+            { type: FieldType::ENUM, label: 'Type', is_required: true, enum_values: TYPES,
+              description: 'own (real bank account) or virtual (sub-account).' },
+            { type: FieldType::STRING, label: 'Name', is_required: true,
+              description: 'Display name (max 100 characters).' },
+            { type: FieldType::STRING, label: 'Holder name', is_required: true,
+              description: 'Account holder name (max 100 characters).' },
+            { type: FieldType::STRING, label: 'Account number', is_required: true,
+              description: 'IBAN or local account number (own); up to 35 alnum chars (virtual).' }
+          ]
+        end
+
+        def executor(datasource, opts)
+          lambda do |context, result_builder|
+            values = context.form_values
+            payload = {
+              'type' => values['Type'],
+              'name' => values['Name'],
+              'holder_name' => values['Holder name'],
+              'account_number' => values['Account number']
+            }
+            account = datasource.client.create_internal_account(payload)
+            id = account.is_a?(Hash) ? account['id'] : nil
+            writeback = Helpers.write_back(context, opts[:result_field], id)
+            message = id ? "Internal account ##{id} created." : 'Internal account created.'
+            result_builder.success(message: "#{message}#{Helpers.write_back_warning(writeback)}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/smart_actions/create_payment_order.rb

@@ -0,0 +1,66 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module SmartActions
+      class CreatePaymentOrder < ForestAdminDatasourceCustomizer::Plugins::Plugin
+        BaseAction  = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+        ActionScope = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+        FieldType   = ForestAdminDatasourceCustomizer::Decorators::Action::Types::FieldType
+
+        NAME = 'Create Mambu payment order'.freeze
+        DIRECTIONS = %w[credit debit].freeze
+
+        def run(_datasource_customizer, collection_customizer = nil, options = {})
+          datasource = options[:datasource]
+          raise ArgumentError, 'CreatePaymentOrder plugin requires :datasource' unless datasource
+          raise ArgumentError, 'CreatePaymentOrder plugin requires a collection' unless collection_customizer
+
+          collection_customizer.add_action(options[:action_name] || NAME, build_action(datasource, options))
+        end
+
+        private
+
+        def build_action(datasource, opts)
+          BaseAction.new(scope: ActionScope::SINGLE, form: form, &executor(datasource, opts))
+        end
+
+        def form
+          [
+            { type: FieldType::STRING, label: 'Type', is_required: true,
+              description: 'Payment type (e.g. sepa_credit_transfer, swift). See Numeral docs for the full list.' },
+            { type: FieldType::ENUM, label: 'Direction', is_required: true, enum_values: DIRECTIONS },
+            { type: FieldType::NUMBER, label: 'Amount', is_required: true,
+              description: "Amount in the currency's smallest unit (e.g. cents for EUR)." },
+            { type: FieldType::STRING, label: 'Currency', is_required: true,
+              description: 'ISO 4217 code (e.g. EUR, USD).' },
+            { type: FieldType::STRING, label: 'Reference', is_required: true,
+              description: 'Reference shown on the account statements (max 140 characters).' },
+            { type: FieldType::STRING, label: 'Connected account id', is_required: true,
+              description: 'UUID of the connected account that triggers the payment.' }
+          ]
+        end
+
+        def executor(datasource, opts)
+          lambda do |context, result_builder|
+            values = context.form_values
+            amount = Helpers.to_int(values['Amount'])
+            next result_builder.error(message: 'Amount must be an integer (smallest currency unit).') unless amount
+
+            payload = {
+              'type' => values['Type'],
+              'direction' => values['Direction'],
+              'amount' => amount,
+              'currency' => values['Currency'],
+              'reference' => values['Reference'],
+              'connected_account_id' => values['Connected account id']
+            }
+            order = datasource.client.create_payment_order(payload)
+            id = order.is_a?(Hash) ? order['id'] : nil
+            writeback = Helpers.write_back(context, opts[:result_field], id)
+            message = id ? "Payment order ##{id} created." : 'Payment order created.'
+            result_builder.success(message: "#{message}#{Helpers.write_back_warning(writeback)}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/smart_actions/trigger_payee_verification.rb

@@ -0,0 +1,58 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module SmartActions
+      # Triggers Numeral's asynchronous external-account verification (a.k.a.
+      # Verification of Payee / VOP). The API returns immediately with status
+      # `pending_verification`; the actual result lands ~30s later via webhook.
+      class TriggerPayeeVerification < ForestAdminDatasourceCustomizer::Plugins::Plugin
+        BaseAction  = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+        ActionScope = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+
+        NAMES = { single: 'Trigger payee verification',
+                  bulk: 'Trigger payee verification on selected accounts' }.freeze
+
+        def run(_datasource_customizer, collection_customizer = nil, options = {})
+          datasource = options[:datasource]
+          record_id_field = options[:record_id_field]
+          raise ArgumentError, 'TriggerPayeeVerification plugin requires :datasource' unless datasource
+          raise ArgumentError, 'TriggerPayeeVerification plugin requires :record_id_field' unless record_id_field
+          raise ArgumentError, 'TriggerPayeeVerification plugin requires a collection' unless collection_customizer
+
+          Helpers.normalize_scopes(options[:scopes]).each do |scope_key|
+            collection_customizer.add_action(NAMES[scope_key], build_action(datasource, scope_key, record_id_field))
+          end
+        end
+
+        private
+
+        def build_action(datasource, scope_key, record_id_field)
+          BaseAction.new(scope: Helpers::SCOPES[scope_key], &executor(datasource, record_id_field))
+        end
+
+        def executor(datasource, record_id_field)
+          lambda do |context, result_builder|
+            ids = Helpers.resolve_ids(context, record_id_field)
+            if ids.empty?
+              next result_builder.error(message: "No Mambu external account id found in '#{record_id_field}'.")
+            end
+
+            succeeded, failed = Helpers.each_with_rescue(ids, 'verify_external_account') do |id|
+              datasource.client.verify_external_account(id)
+            end
+            finalize(result_builder, succeeded, failed)
+          end
+        end
+
+        def finalize(result_builder, succeeded, failed)
+          if succeeded.empty?
+            return result_builder.error(message: Messages.all_failed(failed, noun: 'external account',
+                                                                             verb: 'verify'))
+          end
+
+          result_builder.success(message: Messages.success(succeeded, failed, noun: 'external account',
+                                                                              verb_past: 'now pending verification'))
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/smart_actions/update_account_holder.rb

@@ -0,0 +1,67 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module SmartActions
+      class UpdateAccountHolder < ForestAdminDatasourceCustomizer::Plugins::Plugin
+        BaseAction  = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+        ActionScope = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+        FieldType   = ForestAdminDatasourceCustomizer::Decorators::Action::Types::FieldType
+
+        NAME = 'Update Mambu account holder'.freeze
+
+        def run(_datasource_customizer, collection_customizer = nil, options = {})
+          datasource = options[:datasource]
+          record_id_field = options[:record_id_field]
+          raise ArgumentError, 'UpdateAccountHolder plugin requires :datasource' unless datasource
+          raise ArgumentError, 'UpdateAccountHolder plugin requires :record_id_field' unless record_id_field
+          raise ArgumentError, 'UpdateAccountHolder plugin requires a collection' unless collection_customizer
+
+          collection_customizer.add_action(options[:action_name] || NAME, build_action(datasource, options))
+        end
+
+        private
+
+        def build_action(datasource, opts)
+          BaseAction.new(scope: ActionScope::SINGLE, form: form, &executor(datasource, opts))
+        end
+
+        def form
+          [{ type: FieldType::STRING, label: 'Name',
+             description: 'New display name (leave empty to keep the current value).' }]
+        end
+
+        def executor(datasource, opts)
+          lambda do |context, result_builder|
+            ids = Helpers.resolve_ids(context, opts[:record_id_field])
+            if ids.empty?
+              next result_builder.error(message: "No Mambu account holder id found in '#{opts[:record_id_field]}'.")
+            end
+
+            payload = build_payload(context.form_values)
+            next result_builder.error(message: 'Nothing to update: fill at least one field.') if payload.empty?
+
+            succeeded, failed = Helpers.each_with_rescue(ids, 'update_account_holder') do |id|
+              datasource.client.update_account_holder(id, payload)
+            end
+            finalize(result_builder, succeeded, failed)
+          end
+        end
+
+        def build_payload(values)
+          payload = {}
+          payload['name'] = values['Name'] if Helpers.present?(values['Name'])
+          payload
+        end
+
+        def finalize(result_builder, succeeded, failed)
+          if succeeded.empty?
+            return result_builder.error(message: Messages.all_failed(failed, noun: 'account holder',
+                                                                             verb: 'update'))
+          end
+
+          result_builder.success(message: Messages.success(succeeded, failed, noun: 'account holder',
+                                                                              verb_past: 'updated'))
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/smart_actions/update_external_account.rb

@@ -0,0 +1,75 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module SmartActions
+      class UpdateExternalAccount < ForestAdminDatasourceCustomizer::Plugins::Plugin
+        BaseAction  = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+        ActionScope = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+        FieldType   = ForestAdminDatasourceCustomizer::Decorators::Action::Types::FieldType
+
+        NAME = 'Update Mambu external account'.freeze
+
+        def run(_datasource_customizer, collection_customizer = nil, options = {})
+          datasource = options[:datasource]
+          record_id_field = options[:record_id_field]
+          raise ArgumentError, 'UpdateExternalAccount plugin requires :datasource' unless datasource
+          raise ArgumentError, 'UpdateExternalAccount plugin requires :record_id_field' unless record_id_field
+          raise ArgumentError, 'UpdateExternalAccount plugin requires a collection' unless collection_customizer
+
+          collection_customizer.add_action(options[:action_name] || NAME, build_action(datasource, options))
+        end
+
+        private
+
+        def build_action(datasource, opts)
+          BaseAction.new(scope: ActionScope::SINGLE, form: form, &executor(datasource, opts))
+        end
+
+        def form
+          [
+            { type: FieldType::STRING, label: 'Holder name',
+              description: 'Leave empty to keep the current value.' },
+            { type: FieldType::STRING, label: 'Account number',
+              description: 'Leave empty to keep the current value.' },
+            { type: FieldType::STRING, label: 'Bank code',
+              description: 'Leave empty to keep the current value.' }
+          ]
+        end
+
+        def executor(datasource, opts)
+          lambda do |context, result_builder|
+            ids = Helpers.resolve_ids(context, opts[:record_id_field])
+            if ids.empty?
+              next result_builder.error(message: "No Mambu external account id found in '#{opts[:record_id_field]}'.")
+            end
+
+            payload = build_payload(context.form_values)
+            next result_builder.error(message: 'Nothing to update: fill at least one field.') if payload.empty?
+
+            succeeded, failed = Helpers.each_with_rescue(ids, 'update_external_account') do |id|
+              datasource.client.update_external_account(id, payload)
+            end
+            finalize(result_builder, succeeded, failed)
+          end
+        end
+
+        def build_payload(values)
+          payload = {}
+          payload['holder_name']    = values['Holder name']    if Helpers.present?(values['Holder name'])
+          payload['account_number'] = values['Account number'] if Helpers.present?(values['Account number'])
+          payload['bank_code']      = values['Bank code']      if Helpers.present?(values['Bank code'])
+          payload
+        end
+
+        def finalize(result_builder, succeeded, failed)
+          if succeeded.empty?
+            return result_builder.error(message: Messages.all_failed(failed, noun: 'external account',
+                                                                             verb: 'update'))
+          end
+
+          result_builder.success(message: Messages.success(succeeded, failed, noun: 'external account',
+                                                                              verb_past: 'updated'))
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/plugins/smart_actions/update_internal_account.rb

@@ -0,0 +1,75 @@
+module ForestAdminDatasourceMambuPayments
+  module Plugins
+    module SmartActions
+      class UpdateInternalAccount < ForestAdminDatasourceCustomizer::Plugins::Plugin
+        BaseAction  = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+        ActionScope = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+        FieldType   = ForestAdminDatasourceCustomizer::Decorators::Action::Types::FieldType
+
+        NAME = 'Update Mambu internal account'.freeze
+
+        def run(_datasource_customizer, collection_customizer = nil, options = {})
+          datasource = options[:datasource]
+          record_id_field = options[:record_id_field]
+          raise ArgumentError, 'UpdateInternalAccount plugin requires :datasource' unless datasource
+          raise ArgumentError, 'UpdateInternalAccount plugin requires :record_id_field' unless record_id_field
+          raise ArgumentError, 'UpdateInternalAccount plugin requires a collection' unless collection_customizer
+
+          collection_customizer.add_action(options[:action_name] || NAME, build_action(datasource, options))
+        end
+
+        private
+
+        def build_action(datasource, opts)
+          BaseAction.new(scope: ActionScope::SINGLE, form: form, &executor(datasource, opts))
+        end
+
+        def form
+          [
+            { type: FieldType::STRING, label: 'Name',
+              description: 'Leave empty to keep the current value.' },
+            { type: FieldType::STRING, label: 'Holder name',
+              description: 'Leave empty to keep the current value.' },
+            { type: FieldType::STRING, label: 'Account number',
+              description: 'Leave empty to keep the current value.' }
+          ]
+        end
+
+        def executor(datasource, opts)
+          lambda do |context, result_builder|
+            ids = Helpers.resolve_ids(context, opts[:record_id_field])
+            if ids.empty?
+              next result_builder.error(message: "No Mambu internal account id found in '#{opts[:record_id_field]}'.")
+            end
+
+            payload = build_payload(context.form_values)
+            next result_builder.error(message: 'Nothing to update: fill at least one field.') if payload.empty?
+
+            succeeded, failed = Helpers.each_with_rescue(ids, 'update_internal_account') do |id|
+              datasource.client.update_internal_account(id, payload)
+            end
+            finalize(result_builder, succeeded, failed)
+          end
+        end
+
+        def build_payload(values)
+          payload = {}
+          payload['name']           = values['Name']           if Helpers.present?(values['Name'])
+          payload['holder_name']    = values['Holder name']    if Helpers.present?(values['Holder name'])
+          payload['account_number'] = values['Account number'] if Helpers.present?(values['Account number'])
+          payload
+        end
+
+        def finalize(result_builder, succeeded, failed)
+          if succeeded.empty?
+            return result_builder.error(message: Messages.all_failed(failed, noun: 'internal account',
+                                                                             verb: 'update'))
+          end
+
+          result_builder.success(message: Messages.success(succeeded, failed, noun: 'internal account',
+                                                                              verb_past: 'updated'))
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/query/condition_tree_translator.rb

@@ -0,0 +1,115 @@
+module ForestAdminDatasourceMambuPayments
+  module Query
+    # Translates a Forest condition tree into a hash of Numeral query params.
+    #
+    # The previous version of `fetch_records` short-circuited on `id` and
+    # otherwise sent an unfiltered list — silently producing wrong counts and
+    # missing rows whenever the UI applied a non-id predicate. This translator
+    # raises `UnsupportedOperatorError` for anything it cannot map, so the
+    # failure mode is "loud error" rather than "wrong data".
+    #
+    # Each collection declares its server-filterable fields via `api_filters`:
+    #
+    #   { 'connected_account_id' => { ops: [EQUAL, IN], param: 'connected_account_id' } }
+    #
+    # `param` defaults to the field name. EQUAL emits a scalar value, IN emits
+    # an Array (the client joins arrays with commas — see `Client#normalize_params`).
+    # Top-level OR aggregation is rejected: Numeral list endpoints have no
+    # general OR support, so silently translating "A or B" to "A and B" would
+    # be wrong in both directions.
+    class ConditionTreeTranslator
+      Operators = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Operators
+      Branch    = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeBranch
+      Leaf      = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeLeaf
+
+      def self.call(condition_tree, api_filters: {})
+        return {} if condition_tree.nil?
+
+        new(api_filters).translate(condition_tree)
+      end
+
+      def initialize(api_filters)
+        @api_filters = api_filters || {}
+      end
+
+      def translate(node)
+        case node
+        when Branch then translate_branch(node)
+        when Leaf   then translate_leaf(node)
+        else
+          raise UnsupportedOperatorError, "Unknown condition node: #{node.class}"
+        end
+      end
+
+      private
+
+      def translate_branch(branch)
+        unless branch.aggregator.to_s.casecmp('and').zero?
+          raise UnsupportedOperatorError,
+                "Mambu Payments list endpoints do not support OR aggregation (got #{branch.aggregator.inspect}). " \
+                'Split the request into separate filters.'
+        end
+
+        branch.conditions.each_with_object({}) do |condition, acc|
+          translate(condition).each do |key, value|
+            if acc.key?(key)
+              raise UnsupportedOperatorError,
+                    "Conflicting predicates on '#{key}': cannot pass the same query param twice."
+            end
+
+            acc[key] = value
+          end
+        end
+      end
+
+      def translate_leaf(leaf)
+        spec = @api_filters[leaf.field]
+        unless spec
+          raise UnsupportedOperatorError,
+                "Mambu Payments datasource does not yet translate filters on '#{leaf.field}'. " \
+                'Add it to the collection\'s `api_filters` after verifying the Numeral docs.'
+        end
+
+        param = (spec[:param] || leaf.field).to_s
+        ops   = Array(spec[:ops])
+        unless ops.include?(leaf.operator)
+          raise UnsupportedOperatorError,
+                "Operator '#{leaf.operator}' is not supported on field '#{leaf.field}'. " \
+                "Supported: #{ops.join(", ")}."
+        end
+
+        translate_value(param, leaf.operator, leaf.value)
+      end
+
+      def translate_value(param, operator, value)
+        case operator
+        when Operators::EQUAL
+          raise_nil_value(param) if value.nil?
+          { param => value }
+        when Operators::IN
+          values = Array(value).reject { |v| v.nil? || v.to_s.empty? }
+          raise_empty_in(param) if values.empty?
+          { param => values }
+        else
+          raise UnsupportedOperatorError,
+                "Operator '#{operator}' is declared in api_filters but has no translation rule."
+        end
+      end
+
+      # `field=` with a nil value would semantically degrade to "filter present" on
+      # most REST APIs — silently the wrong query. Use PRESENT / BLANK instead
+      # (once those operators are wired up here).
+      def raise_nil_value(param)
+        raise UnsupportedOperatorError,
+              "Filter value on '#{param}' is nil; the PRESENT / BLANK operators are not yet supported."
+      end
+
+      # An empty `IN []` would translate to no params, silently turning
+      # "match nothing" into "match everything". Raise instead.
+      def raise_empty_in(param)
+        raise UnsupportedOperatorError,
+              "IN on '#{param}' was given an empty array; pass at least one value."
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_mambu_payments/version.rb

@@ -0,0 +1,3 @@
+module ForestAdminDatasourceMambuPayments
+  VERSION = "1.33.1"
+end

data/lib/forest_admin_datasource_mambu_payments.rb

@@ -0,0 +1,44 @@
+require_relative 'forest_admin_datasource_mambu_payments/version'
+require 'logger'
+require 'zeitwerk'
+require 'faraday'
+require 'faraday/retry'
+require 'forest_admin_datasource_toolkit'
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module ForestAdminDatasourceMambuPayments
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class UnsupportedOperatorError < Error; end
+
+  # Raised when a Numeral API call fails. Carries the HTTP status and the
+  # (parsed) response body so callers — smart actions in particular — can
+  # surface the API's own validation message instead of a generic string.
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  class << self
+    attr_writer :logger
+
+    def logger
+      @logger ||= default_logger
+    end
+
+    private
+
+    def default_logger
+      return Rails.logger if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Logger.new($stderr).tap { |l| l.progname = 'forest_admin_datasource_mambu_payments' }
+    end
+  end
+end