lipwa 0.1.2 → 0.1.4

data/lib/lipwa/capabilities/stk_push.rb

@@ -21,7 +21,9 @@ module Lipwa
 
       CONTRACT = Lipwa::Contracts::StkPushContract.new
 
-      def stk_push(amount:, phone_number:, account_reference:, callback_url:, transaction_desc: nil)
+      # rubocop:disable Metrics/ParameterLists
+      def stk_push(amount:, phone_number:, account_reference:, callback_url:, transaction_desc: nil,
+                   idempotency_key: nil)
         validation = CONTRACT.call(
           amount: amount,
           phone_number: phone_number,
@@ -31,13 +33,14 @@ module Lipwa
         )
         return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
 
-        perform_stk_push(validation.to_h)
+        perform_stk_push(validation.to_h, idempotency_key)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       private
 
-      def perform_stk_push(params)
-        response = http.post(PATH, body: stk_push_body(params))
+      def perform_stk_push(params, idempotency_key)
+        response = http.post(PATH, body: stk_push_body(params), idempotency_key: idempotency_key)
 
         build_stk_push_response(response.body)
       rescue Lipwa::GatewayError => e
@@ -45,7 +48,7 @@ module Lipwa
       end
 
       def stk_push_body(params)
-        config = self.class.config
+        config = self.config
         timestamp = Time.now.strftime("%Y%m%d%H%M%S")
 
         {

data/lib/lipwa/capabilities/void.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/card_transaction_contract"
+
+module Lipwa
+  module Capabilities
+    # Cancels an authorization which has not completed.
+    module Void
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :void
+
+      CONTRACT = Lipwa::Contracts::CardTransactionContract.new
+
+      def void(authorization:, idempotency_key: nil)
+        validation = CONTRACT.call(authorization: authorization)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_void(validation.to_h, idempotency_key)
+      end
+    end
+  end
+end

data/lib/lipwa/configuration_snapshot.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "logging"
+
+module Lipwa
+  # Copies setting data while preserving service objects such as loggers.
+  module ConfigurationSnapshot
+    module_function
+
+    def finalize(config)
+      config.values.transform_values! { |value| freeze_value(copy_value(value)) }
+      config.define_singleton_method(:inspect) do
+        values = Lipwa::Logging::Redactor.call(to_h)
+        "#<#{self.class} values=#{values.inspect}>"
+      end
+      config.finalize!
+      config.values.freeze
+      config
+    end
+
+    def freeze_value(value)
+      case value
+      when Dry::Configurable::Config then finalize(value)
+      when Array then value.each { |item| freeze_value(item) }.freeze
+      when Hash then value.each_value { |item| freeze_value(item) }.freeze
+      when String then value.freeze
+      end
+      value
+    end
+
+    def snapshot(source)
+      source.dup.tap do |copy|
+        copy.values.transform_values! { |value| copy_value(value) }
+      end
+    end
+
+    # Copy configuration data without duplicating services such as loggers or
+    # callable clocks, and without running setting constructors a second time.
+    def copy_value(value)
+      case value
+      when Dry::Configurable::Config then snapshot(value)
+      when String then value.dup
+      when Array then value.map { |item| copy_value(item) }
+      when Hash then value.transform_values { |item| copy_value(item) }
+      else value
+      end
+    end
+  end
+end

data/lib/lipwa/context.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "delegate"
+require_relative "gateways"
+require_relative "configuration_snapshot"
+
+module Lipwa
+  # An explicit, immutable configuration scope with its own gateway instances.
+  class Context
+    # Delegates settings to Dry::Configurable so constructors and errors survive.
+    class Builder < SimpleDelegator
+      def initialize(config, gateway_configs)
+        super(config)
+        @gateway_configs = gateway_configs
+      end
+
+      def gateway(name)
+        config = @gateway_configs[name]
+        yield config if block_given?
+        config
+      end
+    end
+    private_constant :Builder
+
+    attr_reader :config
+
+    def initialize
+      @config = snapshot(Lipwa.config)
+      classes = Gateways.gateway_classes
+      gateway_configs = snapshot_gateways(classes)
+      yield Builder.new(config, gateway_configs) if block_given?
+      finalize(config)
+      @gateways = build_gateways(classes, gateway_configs)
+      freeze
+    end
+
+    def gateway(name)
+      @gateways[name]
+    end
+
+    private
+
+    include ConfigurationSnapshot
+
+    def snapshot_gateways(classes)
+      Dry::Container.new.tap do |configs|
+        classes.each { |name, klass| configs.register(name, snapshot(klass.config)) }
+      end
+    end
+
+    def build_gateways(classes, gateway_configs)
+      Dry::Container.new.tap do |gateways|
+        classes.each do |name, klass|
+          provider_config = finalize(gateway_configs[name])
+          gateways.register(name, memoize: true) { klass.new(config: provider_config, global_config: config) }
+        end
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/bank_transfer_contract.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+require_relative "../money"
+module Lipwa
+  module Contracts
+    class BankTransferContract < Dry::Validation::Contract
+      RAILS = %i[internal rtgs pesalink swift bill_payment].freeze
+      schema do
+        required(:rail).filled(:symbol)
+        required(:amount).filled
+        required(:source_account).filled(:string)
+        required(:destination_account).filled(:string)
+        required(:reference).filled(:string)
+        optional(:narration).maybe(:string)
+        optional(:callback_url).maybe(:string)
+        optional(:destination_bank_code).maybe(:string)
+        optional(:destination_name).maybe(:string)
+        optional(:biller_code).maybe(:string)
+      end
+      rule(:rail) { key.failure("must be one of #{RAILS.join(", ")}") unless RAILS.include?(value) }
+      rule(:amount) do
+        next key.failure("must be a Lipwa::Money") unless value.is_a?(Lipwa::Money)
+
+        key.failure("must be greater than zero") unless value.amount.positive?
+      end
+      rule(:destination_bank_code, :rail) do
+        if %i[rtgs swift].include?(values[:rail]) && values[:destination_bank_code].to_s.empty?
+          key(:destination_bank_code).failure("is required for RTGS transfers")
+        end
+      end
+      rule(:biller_code, :rail) do
+        if values[:rail] == :bill_payment && values[:biller_code].to_s.empty?
+          key(:biller_code).failure("is required for bill payments")
+        end
+      end
+      rule(:callback_url) { key.failure("must be an https:// URL") if value && !value.start_with?("https://") }
+    end
+
+    class BankAccountContract < Dry::Validation::Contract
+      schema do
+        required(:account_number).filled(:string)
+        optional(:message_reference).maybe(:string)
+      end
+    end
+
+    class BankStatementContract < Dry::Validation::Contract
+      schema do
+        required(:account_number).filled(:string)
+        optional(:from_date).maybe(:date)
+        optional(:to_date).maybe(:date)
+        optional(:message_reference).maybe(:string)
+      end
+      rule(:from_date, :to_date) do
+        if values[:from_date] && values[:to_date] && values[:to_date] < values[:from_date]
+          key(:to_date).failure("must be on or after from_date")
+        end
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/card_payment_contract.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+require_relative "../money"
+
+module Lipwa
+  module Contracts
+    # Validates the shared hosted-checkout request shape.
+    class CardPaymentContract < Dry::Validation::Contract
+      schema do
+        required(:amount).filled
+        required(:reference).filled(:string)
+        required(:description).filled(:string)
+        required(:callback_url).filled(:string)
+        required(:notification_id).filled(:string)
+        required(:billing_address).hash
+        optional(:cancellation_url).maybe(:string)
+        optional(:redirect_mode).maybe(:string)
+        optional(:branch).maybe(:string)
+        optional(:card_number).maybe(:string)
+        optional(:cvv).maybe(:string)
+        optional(:expiry_month).maybe(:string)
+        optional(:expiry_year).maybe(:string)
+        optional(:fullname).maybe(:string)
+        optional(:phone_number).maybe(:string)
+        optional(:usesecureauth).maybe(:bool)
+      end
+
+      rule(:amount) do
+        next key.failure("must be a Lipwa::Money") unless value.is_a?(Lipwa::Money)
+
+        key.failure("must be greater than zero") unless value.amount.positive?
+      end
+
+      rule(:reference) do
+        key.failure("must be 50 characters or fewer") if value.length > 50
+        key.failure("contains unsupported characters") unless value.match?(/\A[A-Za-z0-9_.:-]+\z/)
+      end
+
+      rule(:description) { key.failure("must be 100 characters or fewer") if value.length > 100 }
+
+      rule(:callback_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+
+      rule(:cancellation_url) do
+        key.failure("must be an https:// URL") if value && !value.start_with?("https://")
+      end
+
+      rule(:billing_address) do
+        address = value
+        unless address[:email_address] || address["email_address"] ||
+               address[:phone_number] || address["phone_number"]
+          key.failure("must contain an email_address or phone_number")
+        end
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/card_transaction_contract.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module Lipwa
+  module Contracts
+    # Validates operations addressing an existing provider authorization.
+    class CardTransactionContract < Dry::Validation::Contract
+      schema do
+        required(:authorization).filled(:string)
+        optional(:amount).filled
+      end
+
+      rule(:authorization) do
+        unless value.match?(/\A[A-Za-z0-9_.:-]+\z/) && !%w[. ..].include?(value)
+          key.failure("contains unsupported characters")
+        end
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/lightning_invoice_check_contract.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module Lipwa
+  module Contracts
+    # Validates the LNbits payment hash used to look up an invoice.
+    class LightningInvoiceCheckContract < Dry::Validation::Contract
+      schema do
+        required(:payment_hash).filled(:string)
+      end
+
+      rule(:payment_hash) do
+        key.failure("contains unsupported characters") unless value.match?(/\A[A-Za-z0-9_-]+\z/)
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/lightning_invoice_contract.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module Lipwa
+  module Contracts
+    # Validates invoice creation parameters before any network call is
+    # made. Amounts are integer satoshis, not Lipwa::Money: Bitcoin is
+    # not an ISO-4217 currency and this capability does no currency math.
+    class LightningInvoiceContract < Dry::Validation::Contract
+      schema do
+        required(:amount_sats).filled(:integer)
+        optional(:memo).maybe(:string)
+        optional(:expiry).maybe(:integer)
+        optional(:webhook_url).maybe(:string)
+      end
+
+      rule(:amount_sats) do
+        key.failure("must be greater than zero") unless value.positive?
+      end
+
+      rule(:webhook_url) do
+        key.failure("must be an https:// URL") if value && !value.start_with?("https://")
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/lightning_payment_check_contract.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module Lipwa
+  module Contracts
+    # Validates the payment hash used to reconcile an outbound payment.
+    class LightningPaymentCheckContract < Dry::Validation::Contract
+      schema do
+        required(:payment_hash).filled(:string)
+      end
+
+      rule(:payment_hash) do
+        key.failure("contains unsupported characters") unless value.match?(/\A[A-Za-z0-9_-]+\z/)
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/lightning_payment_contract.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module Lipwa
+  module Contracts
+    # Validates an outbound BOLT11 invoice before wallet funds can be spent.
+    class LightningPaymentContract < Dry::Validation::Contract
+      schema do
+        required(:bolt11).filled(:string)
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/status_query_contract.rb

@@ -11,19 +11,42 @@ module Lipwa
     # per-call param.
     class StatusQueryContract < Dry::Validation::Contract
       schema do
-        required(:transaction_id).filled(:string)
-        required(:remarks).filled(:string)
-        required(:result_url).filled(:string)
-        required(:queue_timeout_url).filled(:string)
+        optional(:transaction_id).maybe(:string)
+        optional(:message_reference).maybe(:string)
+        optional(:remarks).maybe(:string)
+        optional(:result_url).maybe(:string)
+        optional(:queue_timeout_url).maybe(:string)
         optional(:occasion).maybe(:string)
       end
 
+      rule(:transaction_id, :message_reference) do
+        if values[:transaction_id].to_s.empty? && values[:message_reference].to_s.empty?
+          key(:transaction_id).failure("or message_reference must be filled")
+        elsif values[:transaction_id] && values[:message_reference]
+          key(:message_reference).failure("cannot be used with transaction_id")
+        end
+      end
+
+      rule(:remarks, :transaction_id) do
+        key(:remarks).failure("must be filled") if values[:transaction_id] && values[:remarks].to_s.empty?
+      end
+
+      rule(:result_url, :transaction_id) do
+        key(:result_url).failure("must be filled") if values[:transaction_id] && values[:result_url].to_s.empty?
+      end
+
+      rule(:queue_timeout_url, :transaction_id) do
+        if values[:transaction_id] && values[:queue_timeout_url].to_s.empty?
+          key(:queue_timeout_url).failure("must be filled")
+        end
+      end
+
       rule(:result_url) do
-        key.failure("must be an https:// URL") unless value.start_with?("https://")
+        key.failure("must be an https:// URL") if value && !value.start_with?("https://")
       end
 
       rule(:queue_timeout_url) do
-        key.failure("must be an https:// URL") unless value.start_with?("https://")
+        key.failure("must be an https:// URL") if value && !value.start_with?("https://")
       end
     end
   end

data/lib/lipwa/errors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "logging"
+
 module Lipwa
   # Base class for everything the gem raises or wraps in a Failure.
   class Error < StandardError; end
@@ -41,8 +43,8 @@ module Lipwa
 
     def initialize(message, code: nil, raw: nil)
       @code = code
-      @raw = raw
-      super(message)
+      @raw = Logging::Redactor.call(raw)
+      super(Logging::Redactor.redact_string(message.to_s))
     end
   end
 end

data/lib/lipwa/gateway.rb

@@ -6,7 +6,7 @@ require_relative "types"
 require_relative "capability"
 require_relative "auth_strategies"
 require_relative "http_adapter"
-require_relative "configuration"
+require_relative "configuration_snapshot"
 
 module Lipwa
   # Abstract base every provider gateway (Mpesa, CoopBank, Jenga, ...)
@@ -41,6 +41,19 @@ module Lipwa
       end
     end
 
+    attr_reader :config, :global_config
+
+    # Explicit snapshots win over defaults captured at construction time.
+    def initialize(config: nil, global_config: nil)
+      @config = ConfigurationSnapshot.snapshot(config || self.class.config)
+      strategy = @config.auth_strategy
+      @config.auth_strategy = strategy.respond_to?(:apply) ? strategy.dup : strategy&.call
+      ConfigurationSnapshot.finalize(@config)
+      @global_config = ConfigurationSnapshot.finalize(
+        ConfigurationSnapshot.snapshot(global_config || Lipwa.config)
+      )
+    end
+
     def capability?(name)
       self.class.capabilities.include?(name.to_sym)
     end
@@ -49,19 +62,25 @@ module Lipwa
       @http ||= build_http_adapter
     end
 
+    # Configuration contains credentials, so the default object inspection is
+    # deliberately replaced with a diagnostic that cannot serialize them.
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)}>"
+    end
+
     private
 
     def build_http_adapter
-      config = self.class.config
+      config = self.config
       ensure_base_url_configured!(config)
 
       HttpAdapter.new(
         base_url: config.base_url,
         auth_strategy: config.auth_strategy || AuthStrategies::None.new,
-        timeout: config.timeout || Lipwa.config.default_timeout,
+        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
 

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "base64"
+require "faraday"
+require "json"
+require_relative "../../errors"
+module Lipwa
+  module Gateways
+    class CoopBank
+      class Auth
+        EXPIRY_BUFFER = 60
+        def initialize(client_id:, client_secret:, token_url:, clock: -> { Time.now })
+          unless client_id && client_secret
+            raise Lipwa::ConfigurationError,
+                  "CoopBank::Auth requires client_id and client_secret"
+          end
+
+          @client_id = client_id
+          @client_secret = client_secret
+          @token_url = token_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 fresh?
+
+          @mutex.synchronize { refresh! unless fresh? }
+          @token
+        end
+
+        private
+
+        def fresh? = @token && @expires_at && @clock.call < @expires_at
+
+        def refresh!
+          response = Faraday.post(@token_url) do |request|
+            request.headers["Authorization"] = "Basic #{Base64.strict_encode64("#{@client_id}:#{@client_secret}")}"
+            request.headers["Content-Type"] = "application/x-www-form-urlencoded"
+            request.body = "grant_type=client_credentials"
+          end
+          body = JSON.parse(response.body)
+          unless response.success?
+            raise Lipwa::GatewayError.new("Co-op OAuth failed", code: response.status.to_s,
+                                                                raw: body)
+          end
+
+          @token = body.fetch("access_token")
+          @expires_at = @clock.call + body.fetch("expires_in", 3600).to_i - EXPIRY_BUFFER
+        rescue Faraday::Error, JSON::ParserError, KeyError => e
+          raise Lipwa::GatewayError.new("unexpected Co-op OAuth response: #{e.message}",
+                                        raw: defined?(body) ? body : nil)
+        end
+      end
+    end
+  end
+end