lipwa 0.1.2 → 0.1.4

data/lib/lipwa/gateways/lnbits.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../gateway"
+require_relative "../gateways"
+require_relative "../capabilities/lightning_invoice"
+require_relative "../capabilities/lightning_payment"
+
+module Lipwa
+  module Gateways
+    # LNbits gateway. Each wallet supplies an instance URL and a scoped
+    # invoice/read key capable of creating and checking invoices.
+    class Lnbits < Lipwa::Gateway
+      include Lipwa::Capabilities::LightningInvoice
+      include Lipwa::Capabilities::LightningPayment
+
+      setting :invoice_key
+      setting :admin_key
+
+      private
+
+      def lightning_payment_http
+        @lightning_payment_http ||= build_admin_http_adapter
+      end
+
+      def build_admin_http_adapter
+        config = self.config
+        ensure_lnbits_admin_config_present!(config)
+
+        HttpAdapter.new(**http_adapter_options(config, config.admin_key))
+      end
+
+      def build_http_adapter
+        config = self.config
+        ensure_lnbits_config_present!(config)
+
+        HttpAdapter.new(**http_adapter_options(config, config.invoice_key))
+      end
+
+      def http_adapter_options(config, api_key)
+        {
+          base_url: config.base_url,
+          auth_strategy: AuthStrategies::ApiKey.new(api_key),
+          timeout: config.timeout || global_config.default_timeout,
+          open_timeout: config.open_timeout,
+          logger: config.logger || global_config.logger,
+          adapter: global_config.adapter
+        }
+      end
+
+      def ensure_lnbits_config_present!(config)
+        return if config.base_url && config.invoice_key
+
+        raise Lipwa::ConfigurationError,
+              "#{self.class} is missing base_url/invoice_key — set them via .configure"
+      end
+
+      def ensure_lnbits_admin_config_present!(config)
+        return if config.base_url && config.admin_key
+
+        raise Lipwa::ConfigurationError,
+              "#{self.class} is missing base_url/admin_key — set them via .configure"
+      end
+    end
+  end
+end
+
+Lipwa::Gateways.register(:lnbits, Lipwa::Gateways::Lnbits)

data/lib/lipwa/gateways/mpesa/auth.rb

@@ -31,22 +31,38 @@ module Lipwa
         # token that goes stale mid-flight.
         EXPIRY_BUFFER = 60
 
-        def initialize(consumer_key:, consumer_secret:, env: :sandbox, http: nil, clock: -> { Time.now })
+        # rubocop:disable Metrics/ParameterLists
+        def initialize(consumer_key:, consumer_secret:, env: :sandbox, base_url: nil, http: nil, clock: -> { Time.now })
           ensure_credentials_present!(consumer_key, consumer_secret)
 
           @consumer_key = consumer_key
           @consumer_secret = consumer_secret
           @clock = clock
-          @http = http || Lipwa::HttpAdapter.new(base_url: base_url_for(env))
+          @http = http || Lipwa::HttpAdapter.new(base_url: base_url || base_url_for(env))
           @mutex = Mutex.new
           @token = nil
           @expires_at = nil
         end
+        # rubocop:enable Metrics/ParameterLists
 
         # Returns a cached access token, or fetches (and caches) a new
         # one if there's none yet or the cached one is about to expire.
         # Safe to call concurrently: only one refresh happens in flight,
         # other callers block on it and reuse its result.
+        def initialize_copy(source)
+          super
+          @token = nil
+          @expires_at = nil
+          @mutex = Mutex.new
+          @http = Lipwa::HttpAdapter.new(base_url: @http.base_url, timeout: @http.timeout,
+                                         open_timeout: @http.open_timeout, logger: @http.logger,
+                                         adapter: @http.adapter)
+        end
+
+        def inspect
+          "#<#{self.class}:0x#{object_id.to_s(16)}>"
+        end
+
         def call
           return @token if fresh?
 

data/lib/lipwa/gateways/mpesa.rb

@@ -11,8 +11,8 @@ require_relative "../capabilities/refund"
 module Lipwa
   module Gateways
     # Safaricom Daraja gateway. base_url and auth_strategy are derived
-    # automatically from env/consumer_key/consumer_secret rather than set
-    # directly, since Daraja's OAuth + sandbox/production hosts are fixed
+    # automatically from env/consumer_key/consumer_secret unless explicitly
+    # overridden, since Daraja's OAuth + sandbox/production hosts are fixed
     # per environment.
     class Mpesa < Lipwa::Gateway
       include Lipwa::Capabilities::C2B
@@ -28,33 +28,38 @@ module Lipwa
       setting :initiator_name
       setting :initiator_password
       setting :security_credential_cert
+      setting :clock
 
       private
 
       def build_http_adapter
-        config = self.class.config
+        config = self.config
         ensure_mpesa_config_present!(config)
 
         HttpAdapter.new(**http_adapter_options(config))
       end
 
       def http_adapter_options(config)
+        base_url = config.base_url || Auth::BASE_URLS.fetch(config.env)
         {
-          base_url: Auth::BASE_URLS.fetch(config.env),
-          auth_strategy: AuthStrategies::BearerToken.new(build_auth(config)),
-          timeout: config.timeout || Lipwa.config.default_timeout,
+          base_url: base_url,
+          auth_strategy: config.auth_strategy || AuthStrategies::BearerToken.new(build_auth(config, base_url)),
+          timeout: config.timeout || global_config.default_timeout,
           open_timeout: config.open_timeout,
-          logger: config.logger || Lipwa.config.logger,
-          adapter: Lipwa.config.adapter
+          logger: config.logger || global_config.logger,
+          adapter: global_config.adapter
         }
       end
 
-      def build_auth(config)
-        Auth.new(consumer_key: config.consumer_key, consumer_secret: config.consumer_secret, env: config.env)
+      def build_auth(config, base_url)
+        Auth.new(consumer_key: config.consumer_key, consumer_secret: config.consumer_secret,
+                 env: config.env, base_url: base_url,
+                 clock: config.clock || -> { Time.now })
       end
 
       def ensure_mpesa_config_present!(config)
-        return if config.consumer_key && config.consumer_secret && config.shortcode && config.passkey
+        return if config.shortcode && config.passkey &&
+                  (config.auth_strategy || (config.consumer_key && config.consumer_secret))
 
         raise Lipwa::ConfigurationError,
               "#{self.class} is missing consumer_key/consumer_secret/shortcode/passkey — set them via .configure"

data/lib/lipwa/gateways/paystack.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "../gateway"
+require_relative "../gateways"
+require_relative "../capabilities/purchase"
+require_relative "../capabilities/authorize"
+require_relative "../capabilities/capture"
+require_relative "../capabilities/void"
+
+module Lipwa
+  module Gateways
+    # Paystack hosted card payments. Paystack captures card payments in its
+    # checkout flow, so capture verifies the transaction and void refunds it.
+    class Paystack < Lipwa::Gateway
+      include Lipwa::Capabilities::Purchase
+      include Lipwa::Capabilities::Authorize
+      include Lipwa::Capabilities::Capture
+      include Lipwa::Capabilities::Void
+
+      BASE_URL = "https://api.paystack.co"
+      INITIALIZE_PATH = "/transaction/initialize"
+      VERIFY_PATH = "/transaction/verify"
+      REFUND_PATH = "/refund"
+      SUBUNIT_FACTOR = 100
+
+      setting :secret_key
+
+      private
+
+      def perform_purchase(params, idempotency_key) = initialize_transaction(params, idempotency_key)
+      def perform_authorize(params, idempotency_key) = initialize_transaction(params, idempotency_key)
+
+      def perform_capture(params, idempotency_key)
+        response = http.get("#{VERIFY_PATH}/#{params[:authorization]}", idempotency_key: idempotency_key)
+        build_response(response.body, fallback_reference: params[:authorization], require_completed: true)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def perform_void(params, idempotency_key)
+        response = http.post(REFUND_PATH, body: { transaction: params[:authorization] },
+                                          idempotency_key: idempotency_key)
+        build_response(response.body, fallback_reference: params[:authorization])
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def initialize_transaction(params, idempotency_key)
+        email = address_value(params[:billing_address], :email_address)
+        return Failure(Lipwa::GatewayError.new("billing_address email_address is required by Paystack")) unless email
+
+        response = http.post(INITIALIZE_PATH, body: initialize_body(params, email),
+                                              idempotency_key: idempotency_key)
+        build_response(response.body, fallback_reference: params[:reference])
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def initialize_body(params, email)
+        {
+          email: email,
+          amount: paystack_amount(params[:amount]),
+          currency: params[:amount].currency,
+          reference: params[:reference],
+          callback_url: params[:callback_url],
+          channels: ["card"],
+          metadata: { description: params[:description], notification_id: params[:notification_id] }
+        }
+      end
+
+      def paystack_amount(money)
+        subunits = money.amount * SUBUNIT_FACTOR
+        raise Lipwa::GatewayError, "amount must resolve to a whole Paystack subunit" unless subunits.frac.zero?
+
+        subunits.to_i
+      end
+
+      def address_value(address, key) = address[key] || address[key.to_s]
+
+      def build_response(body, fallback_reference:, require_completed: false)
+        data = body["data"].is_a?(Hash) ? body["data"] : {}
+        Success(Lipwa::Response.new(
+                  success: response_successful?(body, data, require_completed),
+                  provider_reference: (data["reference"] || fallback_reference)&.to_s,
+                  message: body["message"] || data["status"],
+                  code: (data["status"] || body["status"])&.to_s,
+                  raw: body
+                ))
+      end
+
+      def response_successful?(body, data, require_completed)
+        return false unless body["status"] == true
+        return true unless require_completed
+
+        data["status"].to_s.casecmp?("success")
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def build_http_adapter
+        config = self.config
+        ensure_paystack_config_present!(config)
+        auth = config.auth_strategy || AuthStrategies::BearerToken.new(-> { config.secret_key })
+        HttpAdapter.new(base_url: config.base_url || BASE_URL, auth_strategy: auth,
+                        timeout: config.timeout || global_config.default_timeout,
+                        open_timeout: config.open_timeout, logger: config.logger || global_config.logger,
+                        adapter: global_config.adapter)
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def ensure_paystack_config_present!(config)
+        return if config.auth_strategy || config.secret_key
+
+        raise Lipwa::ConfigurationError, "#{self.class} is missing secret_key — set it via .configure"
+      end
+    end
+  end
+end
+
+Lipwa::Gateways.register(:paystack, Lipwa::Gateways::Paystack)

data/lib/lipwa/gateways/pesapal/auth.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "../../errors"
+
+module Lipwa
+  module Gateways
+    class Pesapal
+      # Fetches and briefly caches Pesapal API bearer tokens.
+      class Auth
+        TOKEN_PATH = "/api/Auth/RequestToken"
+
+        def initialize(consumer_key:, consumer_secret:, base_url:, clock: -> { Time.now })
+          @consumer_key = consumer_key
+          @consumer_secret = consumer_secret
+          @base_url = base_url
+          @clock = clock
+          @mutex = Mutex.new
+        end
+
+        def initialize_copy(source)
+          super
+          @token = nil
+          @expires_at = nil
+          @mutex = Mutex.new
+        end
+
+        def inspect
+          "#<#{self.class}:0x#{object_id.to_s(16)}>"
+        end
+
+        def call
+          return @token if @token && @expires_at && @clock.call < @expires_at
+
+          @mutex.synchronize do
+            fetch_token unless @token && @expires_at && @clock.call < @expires_at
+          end
+
+          @token
+        end
+
+        private
+
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def fetch_token
+          response = Faraday.post("#{@base_url}#{TOKEN_PATH}") do |request|
+            request.headers["Accept"] = "application/json"
+            request.headers["Content-Type"] = "application/json"
+            request.body = JSON.generate(consumer_key: @consumer_key, consumer_secret: @consumer_secret)
+          end
+          body = JSON.parse(response.body)
+          token = body["token"]
+          raise_auth_error(response, body) unless response.success? && token
+
+          @token = token
+          @expires_at = @clock.call + 270
+          @token
+        rescue Faraday::Error, JSON::ParserError => e
+          raise Lipwa::GatewayError.new("Pesapal authentication failed: #{e.message}", raw: e)
+        end
+
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+        def raise_auth_error(response, body)
+          error = body["error"].is_a?(Hash) ? body["error"] : {}
+          message = error["message"] || body["message"] || "Pesapal authentication failed"
+          raise Lipwa::GatewayError.new(message, code: (error["code"] || response.status).to_s, raw: body)
+        end
+      end
+    end
+  end
+end

data/lib/lipwa/gateways/pesapal.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "../gateway"
+require_relative "../gateways"
+require_relative "../capabilities/purchase"
+require_relative "../capabilities/authorize"
+require_relative "../capabilities/capture"
+require_relative "../capabilities/void"
+
+module Lipwa
+  module Gateways
+    # Pesapal API 3.0 hosted-checkout gateway.
+    class Pesapal < Lipwa::Gateway
+      include Lipwa::Capabilities::Purchase
+      include Lipwa::Capabilities::Authorize
+      include Lipwa::Capabilities::Capture
+      include Lipwa::Capabilities::Void
+
+      BASE_URLS = {
+        sandbox: "https://cybqa.pesapal.com/pesapalv3",
+        production: "https://pay.pesapal.com/v3"
+      }.freeze
+      SUBMIT_ORDER_PATH = "/api/Transactions/SubmitOrderRequest"
+      STATUS_PATH = "/api/Transactions/GetTransactionStatus"
+      CANCEL_PATH = "/api/Transactions/CancelOrder"
+
+      setting :consumer_key
+      setting :consumer_secret
+      setting :clock
+
+      private
+
+      def perform_purchase(params, idempotency_key) = submit_order(params, idempotency_key)
+      def perform_authorize(params, idempotency_key) = submit_order(params, idempotency_key)
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def perform_capture(params, idempotency_key)
+        response = http.get(STATUS_PATH, params: { orderTrackingId: params[:authorization] },
+                                         idempotency_key: idempotency_key)
+        body = response.body
+        completed = body["payment_status_description"].to_s.casecmp?("COMPLETED") ||
+                    body["status_code"].to_i == 1
+        Success(Lipwa::Response.new(
+                  success: completed,
+                  provider_reference: body["confirmation_code"] || params[:authorization],
+                  message: body["payment_status_description"] || pesapal_message(body),
+                  code: (body["status_code"] || body["status"])&.to_s,
+                  raw: body
+                ))
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+      def perform_void(params, idempotency_key)
+        response = http.post(CANCEL_PATH, body: { order_tracking_id: params[:authorization] },
+                                          idempotency_key: idempotency_key)
+        build_response(response.body, fallback_reference: params[:authorization])
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def submit_order(params, idempotency_key)
+        response = http.post(SUBMIT_ORDER_PATH, body: order_body(params), idempotency_key: idempotency_key)
+        build_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def order_body(params)
+        {
+          id: params[:reference], currency: params[:amount].currency, amount: params[:amount].amount,
+          description: params[:description], callback_url: params[:callback_url],
+          notification_id: params[:notification_id], billing_address: params[:billing_address],
+          cancellation_url: params[:cancellation_url], redirect_mode: params[:redirect_mode],
+          branch: params[:branch]
+        }.compact
+      end
+
+      def build_response(body, fallback_reference: nil)
+        status = body["status"].to_s
+        error = pesapal_error(body)
+        Success(Lipwa::Response.new(
+                  success: error.empty? && status.start_with?("2"),
+                  provider_reference: body["order_tracking_id"] || fallback_reference,
+                  message: body["message"] || error["message"],
+                  code: status.empty? ? error["code"]&.to_s : status,
+                  raw: body
+                ))
+      end
+
+      def pesapal_error(body) = body["error"].is_a?(Hash) ? body["error"] : {}
+      def pesapal_message(body) = pesapal_error(body)["message"]
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def build_http_adapter
+        config = self.config
+        ensure_pesapal_config_present!(config)
+        base_url = config.base_url || BASE_URLS.fetch(config.env)
+        auth = config.auth_strategy || AuthStrategies::BearerToken.new(
+          Auth.new(consumer_key: config.consumer_key, consumer_secret: config.consumer_secret,
+                   base_url: base_url, clock: config.clock || -> { Time.now })
+        )
+        HttpAdapter.new(base_url: base_url, auth_strategy: auth,
+                        timeout: config.timeout || global_config.default_timeout,
+                        open_timeout: config.open_timeout, logger: config.logger || global_config.logger,
+                        adapter: global_config.adapter)
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+      def ensure_pesapal_config_present!(config)
+        return if config.auth_strategy || (config.consumer_key && config.consumer_secret)
+
+        raise Lipwa::ConfigurationError,
+              "#{self.class} is missing consumer_key/consumer_secret — set them via .configure"
+      end
+    end
+  end
+end
+
+require_relative "pesapal/auth"
+
+Lipwa::Gateways.register(:pesapal, Lipwa::Gateways::Pesapal)

data/lib/lipwa/gateways.rb

@@ -18,7 +18,13 @@ module Lipwa
           raise Lipwa::ConfigurationError, "#{gateway_class} must be a subclass of Lipwa::Gateway"
         end
 
-        super(key.to_sym, memoize: true) { gateway_class.new }
+        super(key.to_sym, memoize: true) { gateway_class.new }.tap do
+          (@gateway_classes ||= {})[key.to_s] = gateway_class
+        end
+      end
+
+      def gateway_classes
+        (@gateway_classes || {}).dup
       end
     end
   end

data/lib/lipwa/http_adapter.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require "bigdecimal"
 require "faraday"
 require "faraday/retry"
+require "json"
 require_relative "errors"
 require_relative "auth_strategies"
+require_relative "logging"
 
 module Lipwa
   # Thin wrapper around Faraday shared by every gateway's HTTP calls:
@@ -12,17 +15,28 @@ module Lipwa
   # bearer tokens (M-Pesa, Co-op) and request-signing (Jenga) plug into
   # the same request path without HttpAdapter knowing which is which.
   class HttpAdapter
+    IDEMPOTENCY_HEADER = "Idempotency-Key"
+    RETRYABLE_METHODS = %i[get head options].freeze
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+    RETRYABLE_EXCEPTIONS = Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS.freeze
+    RETRY_IF_IDEMPOTENT = lambda do |env, _exception|
+      value = env.request_headers[IDEMPOTENCY_HEADER]
+      !value.nil? && !value.empty?
+    end
+
     DEFAULT_RETRY_OPTIONS = {
       max: 2,
       interval: 0.5,
       interval_randomness: 0.5,
       backoff_factor: 2,
-      retry_statuses: [429, 500, 502, 503, 504],
-      methods: %i[get post put patch delete],
-      exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS
+      max_interval: 5,
+      retry_statuses: RETRYABLE_STATUSES,
+      methods: RETRYABLE_METHODS,
+      exceptions: RETRYABLE_EXCEPTIONS,
+      retry_if: RETRY_IF_IDEMPOTENT
     }.freeze
 
-    attr_reader :base_url, :auth_strategy, :timeout, :open_timeout, :logger, :adapter
+    attr_reader :base_url, :auth_strategy, :timeout, :open_timeout, :logger, :adapter, :retry_options
 
     # rubocop:disable Metrics/ParameterLists
     def initialize(base_url:, auth_strategy: AuthStrategies::None.new, timeout: 10,
@@ -33,22 +47,28 @@ module Lipwa
       @timeout = timeout
       @open_timeout = open_timeout
       @logger = logger
-      @retry_options = DEFAULT_RETRY_OPTIONS.merge(retry_options)
+      @retry_options = DEFAULT_RETRY_OPTIONS.merge(retry_options).freeze
       @stubs = stubs
       @adapter = adapter
     end
     # rubocop:enable Metrics/ParameterLists
 
-    def get(path, params: {}, headers: {})
-      request(:get, path, params: params, headers: headers)
+    def get(path, params: {}, headers: {}, idempotency_key: nil)
+      request(:get, path, params: params, headers: idempotency_headers(headers, idempotency_key))
+    end
+
+    def post(path, body: nil, params: {}, headers: {}, idempotency_key: nil)
+      request(:post, path, body: body, params: params, headers: idempotency_headers(headers, idempotency_key))
     end
 
-    def post(path, body: nil, params: {}, headers: {})
-      request(:post, path, body: body, params: params, headers: headers)
+    def put(path, body: nil, params: {}, headers: {}, idempotency_key: nil)
+      request(:put, path, body: body, params: params, headers: idempotency_headers(headers, idempotency_key))
     end
 
-    def put(path, body: nil, params: {}, headers: {})
-      request(:put, path, body: body, params: params, headers: headers)
+    # Auth strategies may own API keys or OAuth clients. Avoid recursively
+    # exposing them through the adapter's default instance-variable dump.
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)}>"
     end
 
     private
@@ -65,7 +85,28 @@ module Lipwa
       req.url(path)
       req.params.update(params) if params && !params.empty?
       req.headers.update(headers)
-      req.body = body if body
+      req.body = json_safe_decimals(body) if body
+    end
+
+    def idempotency_headers(headers, idempotency_key)
+      return headers unless idempotency_key
+
+      headers.merge(IDEMPOTENCY_HEADER => idempotency_key)
+    end
+
+    # JSON otherwise encodes BigDecimal as a quoted scientific-notation string.
+    # A fragment preserves the exact base-10 value as a JSON number.
+    def json_safe_decimals(value)
+      case value
+      when BigDecimal
+        JSON::Fragment.new(value.to_s("F"))
+      when Hash
+        value.transform_values { |item| json_safe_decimals(item) }
+      when Array
+        value.map { |item| json_safe_decimals(item) }
+      else
+        value
+      end
     end
 
     def connection
@@ -77,17 +118,15 @@ module Lipwa
     end
 
     def configure_middleware(conn)
-      conn.request :retry, @retry_options
+      conn.request :retry, retry_options
       conn.request :json
       conn.response :json, content_type: /\bjson$/
-      configure_logger(conn) if logger
       conn.use AuthMiddleware, auth_strategy
+      configure_logger(conn) if logger
     end
 
     def configure_logger(conn)
-      conn.response :logger, logger, headers: true, bodies: true do |l|
-        l.filter(/(Authorization: )(.+)/, '\1[REDACTED]')
-      end
+      conn.use Logging::Middleware, logger
     end
 
     def configure_timeouts(conn)