paytree 0.2.0

data/lib/paytree/mpesa/adapters/daraja/c2b.rb

@@ -0,0 +1,47 @@
+require "paytree/mpesa/adapters/daraja/base"
+
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        class C2B < Base
+          REGISTER_ENDPOINT = "/mpesa/c2b/v1/registerurl"
+          SIMULATE_ENDPOINT = "/mpesa/c2b/v1/simulate"
+
+          class << self
+            def register_urls(short_code:, confirmation_url:, validation_url:)
+              with_error_handling(context: :c2b_register) do
+                validate_for(:c2b_register, short_code:, confirmation_url:, validation_url:)
+
+                payload = {
+                  ShortCode: short_code,
+                  ResponseType: "Completed",
+                  ConfirmationURL: confirmation_url,
+                  ValidationURL: validation_url
+                }
+
+                post_to_mpesa(:c2b_register, REGISTER_ENDPOINT, payload)
+              end
+            end
+
+            def simulate(phone_number:, amount:, reference:)
+              with_error_handling(context: :c2b_simulate) do
+                validate_for(:c2b_simulate, phone_number:, amount:, reference:)
+
+                payload = {
+                  ShortCode: config.shortcode,
+                  CommandID: "CustomerPayBillOnline",
+                  Amount: amount,
+                  Msisdn: phone_number,
+                  BillRefNumber: reference
+                }
+
+                post_to_mpesa(:c2b_simulate, SIMULATE_ENDPOINT, payload)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paytree/mpesa/adapters/daraja/response_helpers.rb

@@ -0,0 +1,37 @@
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        module ResponseHelpers
+          def build_response(response, operation)
+            parsed = response.body
+
+            Paytree::Response.new(
+              provider: :mpesa,
+              operation:,
+              status: response.success? ? :success : :error,
+              message: response_message(parsed),
+              code: response_code(parsed),
+              data: parsed,
+              raw_response: response
+            )
+          end
+
+          private
+
+          def response_message(parsed)
+            parsed["ResponseDescription"] ||
+              parsed["ResultDesc"] ||
+              parsed["errorMessage"]
+          end
+
+          def response_code(parsed)
+            parsed["ResponseCode"] ||
+              parsed["ResultCode"] ||
+              parsed["errorCode"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paytree/mpesa/adapters/daraja/stk_push.rb

@@ -0,0 +1,40 @@
+require "paytree/mpesa/adapters/daraja/base"
+
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        class StkPush < Base
+          ENDPOINT = "/mpesa/stkpush/v1/processrequest"
+
+          class << self
+            def call(phone_number:, amount:, reference:)
+              with_error_handling(context: :stk_push) do
+                validate_for(:stk_push, phone_number:, amount:, reference:)
+
+                timestamp = Time.now.strftime("%Y%m%d%H%M%S")
+                password = Base64.strict_encode64("#{config.shortcode}#{config.passkey}#{timestamp}")
+
+                payload = {
+                  BusinessShortCode: config.shortcode,
+                  Password: password,
+                  Timestamp: timestamp,
+                  TransactionType: "CustomerPayBillOnline",
+                  Amount: amount,
+                  PartyA: phone_number,
+                  PartyB: config.shortcode,
+                  PhoneNumber: phone_number,
+                  CallBackURL: config.extras[:callback_url],
+                  AccountReference: reference,
+                  TransactionDesc: reference
+                }
+
+                post_to_mpesa(:stk_push, ENDPOINT, payload)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paytree/mpesa/adapters/daraja/stk_query.rb

@@ -0,0 +1,33 @@
+require "paytree/mpesa/adapters/daraja/base"
+
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        class StkQuery < Base
+          ENDPOINT = "/mpesa/stkpushquery/v1/query"
+
+          class << self
+            def call(checkout_request_id:)
+              with_error_handling(context: :stk_query) do
+                config = self.config
+
+                timestamp = Time.now.strftime("%Y%m%d%H%M%S")
+                password = Base64.strict_encode64("#{config.shortcode}#{config.passkey}#{timestamp}")
+
+                payload = {
+                  BusinessShortCode: config.shortcode,
+                  Password: password,
+                  Timestamp: timestamp,
+                  CheckoutRequestID: checkout_request_id
+                }
+
+                post_to_mpesa(:stk_query, ENDPOINT, payload)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paytree/mpesa/adapters/daraja.rb

@@ -0,0 +1,17 @@
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        extend Paytree::FeatureSet
+
+        supports :stk_push, :stk_query, :b2c, :c2b, :b2b
+
+        autoload :StkPush, "paytree/mpesa/adapters/daraja/stk_push"
+        autoload :StkQuery, "paytree/mpesa/adapters/daraja/stk_query"
+        autoload :B2C, "paytree/mpesa/adapters/daraja/b2c"
+        autoload :C2B, "paytree/mpesa/adapters/daraja/c2b"
+        autoload :B2B, "paytree/mpesa/adapters/daraja/b2b"
+      end
+    end
+  end
+end

data/lib/paytree/mpesa/adapters.rb

@@ -0,0 +1,7 @@
+module Paytree
+  module Mpesa
+    module Adapters
+      autoload :Daraja, "paytree/mpesa/adapters/daraja"
+    end
+  end
+end

data/lib/paytree/mpesa/b2b.rb

@@ -0,0 +1,15 @@
+module Paytree
+  module Mpesa
+    class B2B
+      def self.call(**args)
+        adapter = Paytree::Mpesa.config.adapter
+
+        unless adapter.respond_to?(:supports?) && adapter.supports?(:b2b)
+          raise NotImplementedError, "B2B not supported by #{adapter}"
+        end
+
+        adapter::B2B.call(**args)
+      end
+    end
+  end
+end

data/lib/paytree/mpesa/b2c.rb

@@ -0,0 +1,15 @@
+module Paytree
+  module Mpesa
+    class B2C
+      def self.call(**args)
+        adapter = Paytree::Mpesa.config.adapter
+
+        unless adapter.respond_to?(:supports?) && adapter.supports?(:b2c)
+          raise NotImplementedError, "B2C not supported by #{adapter}"
+        end
+
+        adapter::B2C.call(**args)
+      end
+    end
+  end
+end

data/lib/paytree/mpesa/c2b.rb

@@ -0,0 +1,19 @@
+module Paytree
+  module Mpesa
+    class C2B
+      def self.register_urls(**args)
+        adapter = Paytree::Mpesa.config.adapter
+        raise NotImplementedError unless adapter.supports?(:c2b)
+
+        adapter::C2B.register_urls(**args)
+      end
+
+      def self.simulate(**args)
+        adapter = Paytree::Mpesa.config.adapter
+        raise NotImplementedError unless adapter.supports?(:c2b)
+
+        adapter::C2B.simulate(**args)
+      end
+    end
+  end
+end

data/lib/paytree/mpesa/stk_push.rb

@@ -0,0 +1,15 @@
+module Paytree
+  module Mpesa
+    class StkPush
+      def self.call(**args)
+        adapter = Paytree::Mpesa.config.adapter || Adapters::Daraja
+
+        unless adapter.respond_to?(:supports?) && adapter.supports?(:stk_push)
+          raise NotImplementedError, "STK Push not supported by #{adapter}"
+        end
+
+        adapter::StkPush.call(**args)
+      end
+    end
+  end
+end

data/lib/paytree/mpesa/stk_query.rb

@@ -0,0 +1,15 @@
+module Paytree
+  module Mpesa
+    class StkQuery
+      def self.call(**args)
+        adapter = Paytree::Mpesa.config.adapter
+
+        unless adapter.respond_to?(:supports?) && adapter.supports?(:stk_query)
+          raise NotImplementedError, "STK Query not supported by #{adapter}"
+        end
+
+        adapter::StkQuery.call(**args)
+      end
+    end
+  end
+end

data/lib/paytree/mpesa.rb

@@ -0,0 +1,9 @@
+module Paytree
+  module Mpesa
+    autoload :Adapters, "paytree/mpesa/adapters"
+
+    def self.config
+      Paytree[:mpesa]
+    end
+  end
+end

data/lib/paytree/response.rb

@@ -0,0 +1,44 @@
+module Paytree
+  class Response
+    attr_reader :provider, :operation, :status, :message, :code, :data, :raw_response
+
+    def initialize(provider:, operation:, status:, message:, code:, data:, raw_response:)
+      @provider = provider
+      @operation = operation
+      @status = status
+      @message = message
+      @code = code
+      @data = data
+      @raw_response = raw_response
+    end
+
+    def success?
+      status == :success
+    end
+
+    def error?
+      status == :error
+    end
+
+    def retryable?
+      return false unless error?
+      return false unless code
+
+      config = Paytree[provider]
+      return false unless config&.respond_to?(:retryable_errors)
+
+      config.retryable_errors.include?(code)
+    end
+
+    def to_h
+      {
+        provider:,
+        operation:,
+        status:,
+        message:,
+        code:,
+        data:
+      }
+    end
+  end
+end

data/lib/paytree/utils/error_handling.rb

@@ -0,0 +1,115 @@
+module Paytree
+  module Utils
+    module ErrorHandling
+      def with_error_handling(context: nil)
+        yield
+      rescue Paytree::Errors::ValidationError,
+        Paytree::Errors::Base => e
+        emit_error(e, context)
+        raise
+      rescue Faraday::TimeoutError => e
+        handle_faraday_error(
+          e,
+          context,
+          error_class: Paytree::Errors::MpesaResponseError,
+          error_type: "Timeout"
+        )
+      rescue Faraday::ParsingError, JSON::ParserError => e
+        handle_faraday_error(
+          e,
+          context,
+          error_class: Paytree::Errors::MpesaMalformedResponse,
+          error_type: "Malformed response"
+        )
+      rescue Faraday::ClientError => e
+        handle_faraday_error(
+          e,
+          context,
+          error_class: Paytree::Errors::MpesaClientError,
+          error_type: "Client error",
+          extract_info: true
+        )
+      rescue Faraday::ServerError => e
+        handle_faraday_error(
+          e,
+          context,
+          error_class: Paytree::Errors::MpesaServerError,
+          error_type: "Server error",
+          extract_info: true
+        )
+      rescue => e
+        wrap_and_raise(
+          Paytree::Errors::Base,
+          "Unexpected error in #{context}: #{e.message}",
+          e, context
+        )
+      end
+
+      private
+
+      def handle_faraday_error(error, context, error_class:, error_type:, extract_info: false)
+        if extract_info
+          info = parse_faraday_error(error)
+          message = info[:message] || error.message
+          code = info[:code]
+        else
+          message = error.message
+          code = nil
+        end
+
+        wrap_and_raise(
+          error_class, "#{error_type} in #{context}: #{message}", error, context, code
+        )
+      end
+
+      def wrap_and_raise(klass, message, original, context, code = nil)
+        error = klass.new(message)
+        error.define_singleton_method(:code) { code } if code
+        emit_error(error, context)
+
+        raise error
+      end
+
+      def emit_error(error, context, **metadata)
+        config = get_config_for_context(context)
+        logger = config.respond_to?(:logger) ? config.logger : Logger.new($stdout)
+
+        logger.error format_error_message(error, context)
+      end
+
+      def get_config_for_context(context)
+        provider = extract_provider_from_context(context) || :mpesa
+        Paytree[provider]
+      end
+
+      def extract_provider_from_context(context)
+        return :mpesa if context.to_s.downcase.include?("mpesa")
+        # Can be extended to support other providers based on context
+        nil
+      end
+
+      def parse_faraday_error(faraday_error)
+        body = faraday_error.response&.dig(:body)
+        return {} unless body.is_a?(Hash)
+
+        {
+          message: body["errorMessage"] ||
+            body["ResponseDescription"] ||
+            body["ResultDesc"],
+          code: body["errorCode"] ||
+            body["ResponseCode"] ||
+            body["ResultCode"]
+        }
+      rescue NoMethodError, KeyError, TypeError
+        {}
+      end
+
+      def format_error_message(error, context)
+        provider = extract_provider_from_context(context) || :mpesa
+        code = (error.respond_to?(:code) && error.code) ? " (code: #{error.code})" : ""
+
+        "[#{provider.to_s.upcase}/#{context}] #{error.class}: #{error.message}#{code}"
+      end
+    end
+  end
+end

data/lib/paytree/version.rb

@@ -0,0 +1,3 @@
+module Paytree
+  VERSION = "0.2.0"
+end

data/lib/paytree.rb

@@ -0,0 +1,82 @@
+require "json"
+require "faraday"
+
+Dir[File.join(__dir__, "paytree/**/*.rb")].sort.each { |file| require file }
+
+module Paytree
+  class << self
+    def registry
+      @registry ||= ConfigurationRegistry.new
+    end
+
+    def configure(provider, config_class = nil)
+      raise ArgumentError, "Missing block" unless block_given?
+      raise ArgumentError, "Missing config_class" unless config_class
+
+      registry.configure(provider, config_class) { |hash| yield hash }
+    end
+
+    def configure_mpesa(**options)
+      config = Configs::Mpesa.new
+
+      # Auto-load from environment variables if not provided
+      options = auto_load_env_vars.merge(options)
+
+      # Set configuration values
+      options.each do |key, value|
+        if config.respond_to?("#{key}=")
+          config.send("#{key}=", value)
+        elsif key == :extras
+          config.extras.merge!(value)
+        end
+      end
+
+      # Set smart defaults
+      config.sandbox = true if config.sandbox.nil?
+
+      registry.store_config(:mpesa, config)
+    end
+
+    def [](provider)
+      registry[provider]
+    end
+
+    private
+
+    def auto_load_env_vars
+      env_mapping = {
+        key: "MPESA_CONSUMER_KEY",
+        secret: "MPESA_CONSUMER_SECRET",
+        shortcode: "MPESA_SHORTCODE",
+        passkey: "MPESA_PASSKEY",
+        initiator_name: "MPESA_INITIATOR_NAME",
+        initiator_password: "MPESA_INITIATOR_PASSWORD",
+        sandbox: "MPESA_SANDBOX"
+      }
+
+      config = {}
+      env_mapping.each do |config_key, env_var|
+        value = ENV[env_var]
+        next unless value
+
+        # Convert sandbox to boolean
+        if config_key == :sandbox
+          value = %w[true 1 yes].include?(value.downcase)
+        end
+
+        config[config_key] = value
+      end
+
+      # Load extras from environment
+      extras = {}
+      %w[callback_url result_url timeout_url].each do |extra|
+        env_var = "MPESA_#{extra.upcase}"
+        extras[extra.to_sym] = ENV[env_var] if ENV[env_var]
+      end
+
+      config[:extras] = extras unless extras.empty?
+
+      config
+    end
+  end
+end

data/paytree.gemspec

@@ -0,0 +1,40 @@
+require_relative "lib/paytree/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "paytree"
+  spec.version = Paytree::VERSION
+  spec.authors = ["Charles Chuck"]
+  spec.email = ["chalcchuck@gmail.com"]
+
+  spec.summary = "Rails-optional payments abstraction for M-Pesa (Daraja) and more."
+  spec.description = "Clean, adapter-based Ruby DSL for mobile money integrations like M-Pesa via Daraja, with future provider support (Tingg, Airtel, Cellulant)."
+  spec.homepage = "https://github.com/mundanecodes/paytree"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/mundanecodes/paytree"
+  spec.metadata["changelog_uri"] = "https://github.com/mundanecodes/paytree/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://github.com/mundanecodes/paytree/blob/main/README.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/mundanecodes/paytree/issues"
+  spec.metadata["wiki_uri"] = "https://github.com/mundanecodes/paytree/wiki"
+  spec.metadata["mailing_list_uri"] = "https://github.com/mundanecodes/paytree/discussions"
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features|bin|exe)/}) || f.include?(".git")
+    end
+  end
+
+  spec.require_paths = ["lib"]
+
+  # Runtime deps
+  spec.add_dependency "faraday", "~> 2.0"
+
+  # Dev/test deps
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "webmock", "~> 3.18"
+  spec.add_development_dependency "standard"
+  spec.add_development_dependency "rubocop-rails-omakase"
+end

data/sig/paytree.rbs

@@ -0,0 +1,4 @@
+module Payments
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end