paytree 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03f7bf934f81e5f84019e8e2a20026e49db6f363433e7c00ce5b6d6ddbf6d177
-  data.tar.gz: 6698c7711565529fcd2397120d40fad539e2df905832549f06a8b565f0576a85
+  metadata.gz: 00f6d817e282de2ec9b8b94a6ff632ddb957b2c52f67cefe89a7afbf7dd6aee9
+  data.tar.gz: 9815218a37b228ee2e5b75e85bf3a7d0378b47907436df845a9163f6ee303de1
 SHA512:
-  metadata.gz: 3c50a67fe8d0d6b65a6e7268c010097a8c191b991c6bcc5f20ad13cbd227c0621e2fe658d1aec1cb646d1c1e6a95439165b618bf56ed8f6811f37cdfb56c0f5f
-  data.tar.gz: b4379981cb0ba478550d60de21a74948ca5b7d7ae5d22210cd1cecf6a349a9bfa3bef32fa574d43483bb9bb1b770e432a621315522ac0eb798ef280fe88c9712
+  metadata.gz: db7d90e5c0564309bb45394c66738f5e932172012c4f054417a2f7c357a08d5a7eb6dd2ce1b5bda6f8d32d80c044bc91dee633c14bab92475a2427466ed8d8b3
+  data.tar.gz: a9d0a1b6a51500501d8737edee17d7d56f10d21eab22135bd7a37a93fb49efe954f352106e0093937436daa0b8e6458499b2a635270bc1c90b88612b9510ec31

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    paytree (0.2.0)
-      faraday (~> 2.0)
+    paytree (0.4.0)
+      httpx (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.2)
+    activesupport (8.0.3)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -25,23 +25,20 @@ GEM
     ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.4.1)
-    bigdecimal (3.2.2)
+    bigdecimal (3.3.1)
     concurrent-ruby (1.3.5)
-    connection_pool (2.5.3)
+    connection_pool (2.5.4)
     crack (1.0.0)
       bigdecimal
       rexml
     date (3.4.1)
     diff-lcs (1.6.2)
     drb (2.2.3)
-    erb (5.0.2)
-    faraday (2.13.2)
-      faraday-net_http (>= 2.0, < 3.5)
-      json
-      logger
-    faraday-net_http (3.4.1)
-      net-http (>= 0.5.0)
-    hashdiff (1.2.0)
+    erb (5.1.1)
+    hashdiff (1.2.1)
+    http-2 (1.1.1)
+    httpx (1.6.2)
+      http-2 (>= 1.0.0)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     io-console (0.8.1)
@@ -49,36 +46,35 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.12.2)
+    json (2.15.1)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (5.25.5)
-    net-http (0.6.0)
-      uri
+    minitest (5.26.0)
     parallel (1.27.0)
-    parser (3.3.8.0)
+    parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
-    pp (0.6.2)
+    pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.4.0)
+    prism (1.6.0)
     psych (5.2.6)
       date
       stringio
     public_suffix (6.0.2)
     racc (1.8.1)
-    rack (3.1.16)
+    rack (3.2.3)
     rainbow (3.1.1)
     rake (13.3.0)
-    rdoc (6.14.2)
+    rdoc (6.15.0)
       erb
       psych (>= 4.0.0)
-    regexp_parser (2.10.0)
-    reline (0.6.1)
+      tsort
+    regexp_parser (2.11.3)
+    reline (0.6.2)
       io-console (~> 0.5)
-    rexml (3.4.1)
+    rexml (3.4.4)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -88,11 +84,11 @@ GEM
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.6)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
-    rubocop (1.75.8)
+    rspec-support (3.13.6)
+    rubocop (1.80.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -100,17 +96,17 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.46.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.45.1)
+    rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.25.0)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
-    rubocop-rails (2.32.0)
+    rubocop-rails (2.33.4)
       activesupport (>= 4.2.0)
       lint_roller (~> 1.1)
       rack (>= 1.1)
@@ -122,10 +118,10 @@ GEM
       rubocop-rails (>= 2.30)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    standard (1.50.0)
+    standard (1.51.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.5)
+      rubocop (~> 1.80.2)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
@@ -135,19 +131,22 @@ GEM
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.25.0)
     stringio (3.1.7)
+    tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
-    uri (1.0.3)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.0.4)
     webmock (3.25.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
+  arm64-darwin-25
   x86_64-darwin-24
+  x86_64-darwin-25
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -18,6 +18,8 @@ Currently supports Kenya's M-Pesa via the Daraja API with plans for additional p
 - **Convention over Configuration**: One clear setup pattern, opinionated defaults
 - **Safe Defaults**: Sandbox mode, proper timeouts, comprehensive error handling
 - **Batteries Included**: STK Push, B2C, B2B, C2B operations out of the box
+- **API Versioning**: Support for both Daraja API v1 and v3 with backward compatibility
+- **Enhanced Reliability**: Automatic token retry with exponential backoff
 - **Security First**: Credential management, no hardcoded secrets
 
 ## Quick Start
@@ -89,12 +91,59 @@ Paytree.configure_mpesa(
 #   shortcode: "YOUR_PRODUCTION_SHORTCODE",
 #   passkey: Rails.application.credentials.mpesa[:passkey],
 #   sandbox: false,
-#   retryable_errors: ["429.001.01", "500.001.02", "503.001.01"]  # Optional: errors to retry
+#   api_version: "v1",                                            # Optional: "v1" (default) or "v3"
+#   retryable_errors: ["429.001.01", "500.001.02", "503.001.01"] # Optional: errors to retry
 # )
 ```
 
 ---
 
+## API Version Support
+
+Paytree supports both M-Pesa Daraja API v1 and v3 endpoints. The API version can be configured globally or via environment variables.
+
+### Configuration Options
+
+```ruby
+# Use v1 API (default - backward compatible)
+Paytree.configure_mpesa(
+  key: "YOUR_KEY",
+  secret: "YOUR_SECRET",
+  api_version: "v1"  # Default
+)
+
+# Use v3 API (latest features)
+Paytree.configure_mpesa(
+  key: "YOUR_KEY",
+  secret: "YOUR_SECRET",
+  api_version: "v3"
+)
+
+# Or via environment variable
+ENV['MPESA_API_VERSION'] = 'v3'
+Paytree.configure_mpesa(
+  key: "YOUR_KEY",
+  secret: "YOUR_SECRET"
+  # api_version automatically picked up from ENV
+)
+```
+
+### Differences Between v1 and v3
+
+| Feature | v1 | v3 |
+|---------|----|----|
+| **Endpoints** | `/mpesa/b2c/v1/paymentrequest` | `/mpesa/b2c/v3/paymentrequest` |
+| **OriginatorConversationID** | Not required | Auto-generated UUID |
+| **Reliability** | Standard | Enhanced with better tracking |
+
+
+**Backward Compatibility:**
+- Existing code continues to work unchanged (defaults to v1)
+- No breaking changes when upgrading Paytree versions
+- Can switch between v1/v3 by changing configuration only
+
+---
+
 ## Usage Examples
 
 ### STK Push (Customer Payment)
@@ -168,7 +217,7 @@ end
 
 Send funds directly to a customer’s M-Pesa wallet via the B2C API.
 
-### Example
+### Basic Example
 ```ruby
 response = Paytree::Mpesa::B2C.call(
   phone_number: "254712345678",
@@ -186,6 +235,43 @@ else
 end
 ```
 
+### v3 API Features
+
+When using `api_version: "v3"`, B2C calls automatically include an `OriginatorConversationID` for enhanced tracking:
+
+```ruby
+# Configure for v3 API
+Paytree.configure_mpesa(
+  key: "YOUR_KEY",
+  secret: "YOUR_SECRET",
+  api_version: "v3"
+)
+
+# Same call, but now uses v3 endpoint with auto-generated OriginatorConversationID
+response = Paytree::Mpesa::B2C.call(
+  phone_number: "254712345678",
+  amount: 100
+)
+
+# v3 response includes additional tracking data
+if response.success?
+  puts "Conversation ID: #{response.data["ConversationID"]}"
+  puts "Originator ID: #{response.data["OriginatorConversationID"]}" # Auto-generated UUID
+end
+```
+
+### Custom OriginatorConversationID (v3 only)
+
+You can provide your own tracking ID for v3 API calls:
+
+```ruby
+response = Paytree::Mpesa::B2C.call(
+  phone_number: "254712345678",
+  amount: 100,
+  originator_conversation_id: "CUSTOM-TRACK-#{Time.now.to_i}"
+)
+```
+
 ---
 
 ## C2B (Customer to Business)
@@ -321,6 +407,9 @@ Paytree allows you to configure which error codes should be considered retryable
 - `"429.001.01"` - Rate limit exceeded
 - `"500.001.02"` - Temporary server error
 - `"503.001.01"` - Service temporarily unavailable
+- `"timeout.connection"` - Network connection timeout (Net::OpenTimeout)
+- `"timeout.read"` - Network read timeout (Net::ReadTimeout)
+- `"timeout.request"` - HTTP request timeout (HTTPX::TimeoutError)
 
 Configure retryable errors during setup:
 
@@ -328,7 +417,14 @@ Configure retryable errors during setup:
 Paytree.configure_mpesa(
   key: "YOUR_KEY",
   secret: "YOUR_SECRET",
-  retryable_errors: ["429.001.01", "500.001.02", "503.001.01"]
+  retryable_errors: [
+    "429.001.01",         # Rate limit
+    "500.001.02",         # Server error  
+    "503.001.01",         # Service unavailable
+    "timeout.connection", # Connection timeout
+    "timeout.read",       # Read timeout
+    "timeout.request"     # Request timeout
+  ]
 )
 ```
 

data/lib/paytree/configs/mpesa.rb

@@ -3,16 +3,17 @@ require "logger"
 module Paytree
   module Configs
     class Mpesa
+      attr_writer :logger
       attr_accessor :key, :secret, :shortcode, :passkey, :adapter,
         :initiator_name, :initiator_password, :sandbox,
-        :extras, :timeout, :retryable_errors
+        :extras, :timeout, :retryable_errors, :api_version
 
       def initialize
         @extras = {}
         @logger = nil
-        @mutex = Mutex.new
         @timeout = 30      # Default 30 second timeout
         @retryable_errors = []  # Default empty array
+        @api_version = "v1"     # Default to v1 for backward compatibility
       end
 
       def base_url
@@ -20,15 +21,7 @@ module Paytree
       end
 
       def logger
-        @mutex.synchronize do
-          @logger ||= Logger.new($stdout)
-        end
-      end
-
-      def logger=(new_logger)
-        @mutex.synchronize do
-          @logger = new_logger
-        end
+        @logger ||= Logger.new($stdout)
       end
     end
   end

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

@@ -5,7 +5,9 @@ module Paytree
     module Adapters
       module Daraja
         class B2B < Base
-          ENDPOINT = "/mpesa/b2b/v1/paymentrequest"
+          def self.endpoint
+            "/mpesa/b2b/#{config.api_version}/paymentrequest"
+          end
 
           class << self
             def call(short_code:, receiver_shortcode:, amount:, account_reference:, **opts)
@@ -28,7 +30,7 @@ module Paytree
                   ResultURL: config.extras[:result_url]
                 }.compact
 
-                post_to_mpesa(:b2b, ENDPOINT, payload)
+                post_to_mpesa(:b2b, endpoint, payload)
               end
             end
           end

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

@@ -5,7 +5,9 @@ module Paytree
     module Adapters
       module Daraja
         class B2C < Base
-          ENDPOINT = "/mpesa/b2c/v1/paymentrequest"
+          def self.endpoint
+            "/mpesa/b2c/#{config.api_version}/paymentrequest"
+          end
 
           class << self
             def call(phone_number:, amount:, **opts)
@@ -23,9 +25,14 @@ module Paytree
                   CommandID: opts[:command_id] || "BusinessPayment",
                   Remarks: opts[:remarks] || "OK",
                   Occasion: opts[:occasion] || "Payment"
-                }.compact
+                }
+
+                # Add OriginatorConversationID for v3
+                if config.api_version == "v3"
+                  payload[:OriginatorConversationID] = opts[:originator_conversation_id] || generate_conversation_id
+                end
 
-                post_to_mpesa(:b2c, ENDPOINT, payload)
+                post_to_mpesa(:b2c, endpoint, payload.compact)
               end
             end
           end

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

@@ -1,5 +1,9 @@
 require "base64"
+require "securerandom"
 require_relative "response_helpers"
+require_relative "http_client_factory"
+require_relative "validator"
+require_relative "token_manager"
 require_relative "../../../utils/error_handling"
 
 module Paytree
@@ -10,36 +14,32 @@ module Paytree
           class << self
             include Paytree::Utils::ErrorHandling
             include Paytree::Mpesa::Adapters::Daraja::ResponseHelpers
+            include Paytree::Mpesa::Adapters::Daraja::HttpClientFactory
+            include Paytree::Mpesa::Adapters::Daraja::Validator
+            include Paytree::Mpesa::Adapters::Daraja::TokenManager
 
             def config = Paytree[:mpesa]
 
-            def connection
-              @connection ||= Faraday.new(url: config.base_url) do |conn|
-                conn.options.timeout = config.timeout
-                conn.options.open_timeout = config.timeout / 2
+            # Thread-safe HTTP client for regular API calls
+            def http_client
+              thread_safe_client(:@http_client)
+            end
 
-                conn.request :json
-                conn.response :json, content_type: "application/json"
-              end
+            # Thread-safe HTTP client with retry logic for token fetching
+            # Retries on: timeouts, connection errors, and 5xx server errors
+            def token_http_client
+              thread_safe_client(:@token_http_client, plugins: [:retries], **retry_options)
             end
 
             def post_to_mpesa(operation, endpoint, payload)
-              build_response(
-                connection.post(endpoint, payload.to_json, headers),
-                operation
-              )
+              response = http_client.post(endpoint, json: payload, headers:)
+              build_response(response, operation)
             end
 
             def headers
               {"Authorization" => "Bearer #{token}", "Content-Type" => "application/json"}
             end
 
-            def token
-              return @token if token_valid?
-
-              fetch_token
-            end
-
             def encrypt_credential(config)
               cert_path = config.extras[:cert_path]
               unless cert_path && File.exist?(cert_path)
@@ -55,76 +55,8 @@ module Paytree
                 "Failed to encrypt password with certificate #{cert_path}: #{e.message}"
             end
 
-            # ------------------------------------------------------------------
-            # Validation rules
-            # ------------------------------------------------------------------
-            VALIDATIONS = {
-              c2b_register: {required: %i[short_code confirmation_url validation_url]},
-              c2b_simulate: {required: %i[phone_number amount reference]},
-              stk_push: {required: %i[phone_number amount reference]},
-              b2c: {required: %i[phone_number amount], config: %i[result_url]},
-              b2b: {
-                required: %i[short_code receiver_shortcode account_reference amount],
-                config: %i[result_url timeout_url],
-                command_id: %w[BusinessPayBill BusinessBuyGoods]
-              }
-            }.freeze
-
-            def validate_for(operation, params = {})
-              rules = VALIDATIONS[operation] ||
-                raise(Paytree::Errors::UnsupportedOperation, "Unknown operation: #{operation}")
-
-              Array(rules[:required]).each { |field| validate_field(field, params[field]) }
-
-              Array(rules[:config]).each do |key|
-                unless config.extras[key]
-                  raise Paytree::Errors::ConfigurationError, "Missing `#{key}` in Mpesa extras config"
-                end
-              end
-
-              if (allowed = rules[:command_id]) && !allowed.include?(params[:command_id])
-                raise Paytree::Errors::ValidationError,
-                  "command_id must be one of: #{allowed.join(", ")}"
-              end
-            end
-
-            def validate_field(field, value)
-              case field
-              when :amount
-                unless value.is_a?(Numeric) && value >= 1
-                  raise Paytree::Errors::ValidationError,
-                    "amount must be a positive number"
-                end
-              when :phone_number
-                phone_regex = /^254\d{9}$/
-                unless value.to_s.match?(phone_regex)
-                  raise Paytree::Errors::ValidationError,
-                    "phone_number must be a valid Kenyan format (254XXXXXXXXX)"
-                end
-              else
-                raise Paytree::Errors::ValidationError, "#{field} cannot be blank" if value.to_s.strip.empty?
-              end
-            end
-
-            private
-
-            def fetch_token
-              cred = Base64.strict_encode64("#{config.key}:#{config.secret}")
-
-              response = connection.get("/oauth/v1/generate", grant_type: "client_credentials") do |r|
-                r.headers["Authorization"] = "Basic #{cred}"
-              end
-
-              data = response.body
-              @token = data["access_token"]
-              @token_expiry = Time.now + data["expires_in"].to_i
-              @token
-            rescue Faraday::Error => e
-              raise Paytree::Errors::MpesaTokenError, "Unable to fetch token: #{e.message}"
-            end
-
-            def token_valid?
-              @token && @token_expiry && Time.now < @token_expiry
+            def generate_conversation_id
+              SecureRandom.uuid
             end
           end
         end

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

@@ -0,0 +1,62 @@
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        module HttpClientFactory
+          private
+
+          # Creates a thread-safe memoized HTTP client
+          # @param ivar_name [Symbol] Instance variable name (e.g., :@http_client)
+          # @param plugins [Array<Symbol>] HTTPX plugins to load (e.g., [:retries])
+          # @param options [Hash] Additional HTTPX options
+          # @return [HTTPX::Session] Configured HTTP client
+          def thread_safe_client(ivar_name, plugins: [], **options)
+            cached = instance_variable_get(ivar_name)
+            return cached if cached
+
+            mutex_name = :"#{ivar_name}_mutex"
+            mutex = instance_variable_get(mutex_name) || instance_variable_set(mutex_name, Mutex.new)
+
+            mutex.synchronize do
+              cached = instance_variable_get(ivar_name)
+              return cached if cached
+
+              client = plugins.reduce(HTTPX) { |c, plugin| c.plugin(plugin) }
+
+              instance_variable_set(
+                ivar_name,
+                client.with(base_http_options.merge(options))
+              )
+            end
+          end
+
+          def base_http_options
+            {
+              origin: config.base_url,
+              timeout: {
+                connect_timeout: config.timeout / 2,
+                operation_timeout: config.timeout
+              },
+              ssl: {
+                verify_mode: OpenSSL::SSL::VERIFY_NONE
+              }
+            }
+          end
+
+          def retry_options
+            {
+              max_retries: 3,
+              retry_change_requests: true,
+              retry_on: ->(response) {
+                # Retry on network errors (timeouts, connection failures)
+                return true if response.is_a?(HTTPX::ErrorResponse)
+                # Retry on 5xx server errors
+                [500, 502, 503, 504].include?(response.status)
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,12 +4,18 @@ module Paytree
       module Daraja
         module ResponseHelpers
           def build_response(response, operation)
-            parsed = response.body
+            # Handle ErrorResponse from HTTPX
+            if response.is_a?(HTTPX::ErrorResponse)
+              raise response.error if response.error
+              raise HTTPX::Error, "Request failed"
+            end
+
+            parsed = response.json
 
             Paytree::Response.new(
               provider: :mpesa,
               operation:,
-              status: response.success? ? :success : :error,
+              status: successful_response?(response) ? :success : :error,
               message: response_message(parsed),
               code: response_code(parsed),
               data: parsed,
@@ -19,6 +25,10 @@ module Paytree
 
           private
 
+          def successful_response?(response)
+            response.status >= 200 && response.status < 300
+          end
+
           def response_message(parsed)
             parsed["ResponseDescription"] ||
               parsed["ResultDesc"] ||

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

@@ -0,0 +1,74 @@
+require "base64"
+
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        # Thread-safe token management for M-Pesa Daraja API
+        # Handles OAuth token fetching, caching, and expiry validation
+        module TokenManager
+          # Returns a valid access token, fetching a new one if needed
+          # @return [String] Valid access token
+          def token
+            return @token if token_valid?
+
+            @token_mutex ||= Mutex.new
+            @token_mutex.synchronize do
+              return @token if token_valid?
+
+              fetch_token
+            end
+          end
+
+          private
+
+          # Fetches a new OAuth token from M-Pesa API
+          # Automatically retries on network errors and 5xx responses
+          # @return [String] Access token
+          # @raise [Paytree::Errors::MpesaTokenError] if token fetch fails
+          def fetch_token
+            credentials = encode_credentials
+
+            response = token_http_client.get(
+              "/oauth/v1/generate",
+              params: {grant_type: "client_credentials"},
+              headers: {"Authorization" => "Basic #{credentials}"}
+            )
+
+            validate_token_response(response)
+            parse_and_cache_token(response)
+          rescue HTTPX::Error => e
+            raise Paytree::Errors::MpesaTokenError, "Unable to fetch token: #{e.message}"
+          end
+
+          def encode_credentials
+            Base64.strict_encode64("#{config.key}:#{config.secret}")
+          end
+
+          def validate_token_response(response)
+            if response.is_a?(HTTPX::ErrorResponse) || response.error
+              error_msg = response.error ? response.error.message : "Request failed"
+              raise Paytree::Errors::MpesaTokenError, "Unable to fetch token: #{error_msg}"
+            end
+
+            unless response.status == 200
+              raise Paytree::Errors::MpesaTokenError,
+                "Token request failed with status #{response.status}"
+            end
+          end
+
+          def parse_and_cache_token(response)
+            response_data = response.json
+            @token = response_data["access_token"]
+            @token_expiry = Time.now + response_data["expires_in"].to_i
+            @token
+          end
+
+          def token_valid?
+            @token && @token_expiry && Time.now < @token_expiry
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        # Validation module for M-Pesa API operations
+        # Validates required fields, config values, and operation-specific parameters
+        module Validator
+          VALIDATIONS = {
+            c2b_register: {required: %i[short_code confirmation_url validation_url]},
+            c2b_simulate: {required: %i[phone_number amount reference]},
+            stk_push: {required: %i[phone_number amount reference]},
+            b2c: {required: %i[phone_number amount], config: %i[result_url]},
+            b2b: {
+              required: %i[short_code receiver_shortcode account_reference amount],
+              config: %i[result_url timeout_url],
+              command_id: %w[BusinessPayBill BusinessBuyGoods]
+            }
+          }.freeze
+
+          # Validates parameters for a given operation
+          # @param operation [Symbol] The operation to validate for (e.g., :stk_push, :b2c)
+          # @param params [Hash] Parameters to validate
+          # @raise [Paytree::Errors::UnsupportedOperation] if operation is unknown
+          # @raise [Paytree::Errors::ValidationError] if validation fails
+          # @raise [Paytree::Errors::ConfigurationError] if required config is missing
+          def validate_for(operation, params = {})
+            rules = VALIDATIONS[operation] ||
+              raise(Paytree::Errors::UnsupportedOperation, "Unknown operation: #{operation}")
+
+            # Validate required fields
+            Array(rules[:required]).each { |field| validate_field(field, params[field]) }
+
+            # Validate required config values
+            Array(rules[:config]).each do |key|
+              unless config.extras[key]
+                raise Paytree::Errors::ConfigurationError, "Missing `#{key}` in Mpesa extras config"
+              end
+            end
+
+            # Validate command_id if specified
+            if (allowed = rules[:command_id]) && !allowed.include?(params[:command_id])
+              raise Paytree::Errors::ValidationError,
+                "command_id must be one of: #{allowed.join(", ")}"
+            end
+          end
+
+          # Validates a single field based on its type
+          # @param field [Symbol] Field name
+          # @param value [Object] Field value to validate
+          # @raise [Paytree::Errors::ValidationError] if validation fails
+          def validate_field(field, value)
+            case field
+            when :amount then validate_amount(value)
+            when :phone_number then validate_phone_number(value)
+            else
+              validate_presence(field, value)
+            end
+          end
+
+          private
+
+          # Validates amount is a positive number
+          def validate_amount(value)
+            unless value.is_a?(Numeric) && value >= 1
+              raise Paytree::Errors::ValidationError,
+                "amount must be a positive number"
+            end
+          end
+
+          # Validates phone number is in valid Kenyan format (254XXXXXXXXX)
+          def validate_phone_number(value)
+            phone_regex = /^254\d{9}$/
+            unless value.to_s.match?(phone_regex)
+              raise Paytree::Errors::ValidationError,
+                "phone_number must be a valid Kenyan format (254XXXXXXXXX)"
+            end
+          end
+
+          # Validates field is not blank
+          def validate_presence(field, value)
+            if value.to_s.strip.empty?
+              raise Paytree::Errors::ValidationError, "#{field} cannot be blank"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paytree/utils/error_handling.rb

@@ -7,35 +7,61 @@ module Paytree
         Paytree::Errors::Base => e
         emit_error(e, context)
         raise
-      rescue Faraday::TimeoutError => e
-        handle_faraday_error(
+      rescue HTTPX::TimeoutError => e
+        handle_http_error(
           e,
           context,
           error_class: Paytree::Errors::MpesaResponseError,
-          error_type: "Timeout"
+          error_type: "Timeout",
+          code: "timeout.request"
         )
-      rescue Faraday::ParsingError, JSON::ParserError => e
-        handle_faraday_error(
+      rescue Net::OpenTimeout => e
+        handle_http_error(
           e,
           context,
-          error_class: Paytree::Errors::MpesaMalformedResponse,
-          error_type: "Malformed response"
+          error_class: Paytree::Errors::MpesaResponseError,
+          error_type: "Timeout",
+          code: "timeout.connection"
+        )
+      rescue Net::ReadTimeout => e
+        handle_http_error(
+          e,
+          context,
+          error_class: Paytree::Errors::MpesaResponseError,
+          error_type: "Timeout",
+          code: "timeout.read"
         )
-      rescue Faraday::ClientError => e
-        handle_faraday_error(
+      rescue JSON::ParserError => e
+        handle_http_error(
           e,
           context,
-          error_class: Paytree::Errors::MpesaClientError,
-          error_type: "Client error",
-          extract_info: true
+          error_class: Paytree::Errors::MpesaMalformedResponse,
+          error_type: "Malformed response"
         )
-      rescue Faraday::ServerError => e
-        handle_faraday_error(
+      rescue HTTPX::HTTPError => e
+        if e.response.status >= 500
+          handle_http_error(
+            e,
+            context,
+            error_class: Paytree::Errors::MpesaServerError,
+            error_type: "Server error",
+            extract_info: true
+          )
+        else
+          handle_http_error(
+            e,
+            context,
+            error_class: Paytree::Errors::MpesaClientError,
+            error_type: "Client error",
+            extract_info: true
+          )
+        end
+      rescue HTTPX::Error => e
+        handle_http_error(
           e,
           context,
-          error_class: Paytree::Errors::MpesaServerError,
-          error_type: "Server error",
-          extract_info: true
+          error_class: Paytree::Errors::MpesaResponseError,
+          error_type: "HTTP error"
         )
       rescue => e
         wrap_and_raise(
@@ -47,14 +73,13 @@ module Paytree
 
       private
 
-      def handle_faraday_error(error, context, error_class:, error_type:, extract_info: false)
+      def handle_http_error(error, context, error_class:, error_type:, extract_info: false, code: nil)
         if extract_info
-          info = parse_faraday_error(error)
+          info = parse_http_error(error)
           message = info[:message] || error.message
-          code = info[:code]
+          code ||= info[:code]
         else
           message = error.message
-          code = nil
         end
 
         wrap_and_raise(
@@ -88,8 +113,14 @@ module Paytree
         nil
       end
 
-      def parse_faraday_error(faraday_error)
-        body = faraday_error.response&.dig(:body)
+      def parse_http_error(http_error)
+        return {} unless http_error.respond_to?(:response)
+
+        body = begin
+          http_error.response.json
+        rescue
+          http_error.response.body.to_s
+        end
         return {} unless body.is_a?(Hash)
 
         {

data/lib/paytree/version.rb

@@ -1,3 +1,3 @@
 module Paytree
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
 end

data/lib/paytree.rb

@@ -1,5 +1,5 @@
 require "json"
-require "faraday"
+require "httpx"
 
 Dir[File.join(__dir__, "paytree/**/*.rb")].sort.each { |file| require file }
 
@@ -51,7 +51,8 @@ module Paytree
         passkey: "MPESA_PASSKEY",
         initiator_name: "MPESA_INITIATOR_NAME",
         initiator_password: "MPESA_INITIATOR_PASSWORD",
-        sandbox: "MPESA_SANDBOX"
+        sandbox: "MPESA_SANDBOX",
+        api_version: "MPESA_API_VERSION"
       }
 
       config = {}

data/paytree.gemspec

@@ -27,14 +27,14 @@ Gem::Specification.new do |spec|
 
   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")
+      f.match(%r{^(test|spec|features|bin|exe)/}) || f.include?(".git") || f.end_with?(".gem")
     end
   end
 
   spec.require_paths = ["lib"]
 
   # Runtime deps
-  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "httpx", "~> 1.0"
 
   # Dev/test deps
   spec.add_development_dependency "rspec", "~> 3.12"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paytree
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Charles Chuck
@@ -10,19 +10,19 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: faraday
+  name: httpx
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -112,9 +112,12 @@ files:
 - lib/paytree/mpesa/adapters/daraja/b2c.rb
 - lib/paytree/mpesa/adapters/daraja/base.rb
 - lib/paytree/mpesa/adapters/daraja/c2b.rb
+- lib/paytree/mpesa/adapters/daraja/http_client_factory.rb
 - lib/paytree/mpesa/adapters/daraja/response_helpers.rb
 - lib/paytree/mpesa/adapters/daraja/stk_push.rb
 - lib/paytree/mpesa/adapters/daraja/stk_query.rb
+- lib/paytree/mpesa/adapters/daraja/token_manager.rb
+- lib/paytree/mpesa/adapters/daraja/validator.rb
 - lib/paytree/mpesa/b2b.rb
 - lib/paytree/mpesa/b2c.rb
 - lib/paytree/mpesa/c2b.rb
@@ -123,7 +126,6 @@ files:
 - lib/paytree/response.rb
 - lib/paytree/utils/error_handling.rb
 - lib/paytree/version.rb
-- paytree-0.2.0.gem
 - paytree.gemspec
 - sig/paytree.rbs
 homepage: https://github.com/mundanecodes/paytree