lipwa 0.1.1

data/lib/lipwa/capabilities/refund.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/refund_contract"
+
+module Lipwa
+  module Capabilities
+    # Reverses a completed M-Pesa transaction (Daraja's Transaction
+    # Reversal API) by its TransactionID. Like Disbursement and
+    # StatusQuery, Daraja requires a SecurityCredential, and the reversal
+    # call itself only acknowledges receipt; the actual outcome arrives
+    # later at result_url as a third callback envelope
+    # (`{"Result" => {...}}`), parsed generically by
+    # Lipwa::Webhooks::Mpesa alongside StatusQuery/Disbursement results.
+    module Refund
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :refund
+
+      PATH = "/mpesa/reversal/v1/request"
+      RECEIVER_IDENTIFIER_TYPE = "11" # organization shortcode, per Daraja's Reversal API spec
+
+      CONTRACT = Lipwa::Contracts::RefundContract.new
+
+      # rubocop:disable Metrics/ParameterLists
+      def refund(transaction_id:, amount:, remarks:, result_url:, queue_timeout_url:, occasion: nil)
+        validate_and_refund(
+          transaction_id: transaction_id, amount: amount, remarks: remarks,
+          result_url: result_url, queue_timeout_url: queue_timeout_url, occasion: occasion
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      private
+
+      def validate_and_refund(args)
+        validation = CONTRACT.call(args)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_refund(validation.to_h)
+      end
+
+      def perform_refund(params)
+        ensure_refund_config_present!
+
+        response = http.post(PATH, body: refund_body(params))
+
+        build_refund_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def refund_body(params)
+        {
+          Initiator: self.class.config.initiator_name,
+          SecurityCredential: security_credential,
+          CommandID: "TransactionReversal",
+          TransactionID: params[:transaction_id],
+          Amount: params[:amount].amount,
+          ReceiverParty: self.class.config.shortcode,
+          RecieverIdentifierType: RECEIVER_IDENTIFIER_TYPE
+        }.merge(shared_refund_fields(params))
+      end
+
+      def shared_refund_fields(params)
+        {
+          ResultURL: params[:result_url],
+          QueueTimeOutURL: params[:queue_timeout_url],
+          Remarks: params[:remarks],
+          Occasion: params[:occasion]
+        }
+      end
+
+      def security_credential
+        Lipwa::Gateways::Mpesa::SecurityCredential.encrypt(
+          self.class.config.initiator_password,
+          cert: self.class.config.security_credential_cert
+        )
+      end
+
+      def build_refund_response(body)
+        Success(Lipwa::Response.new(
+                  success: body["ResponseCode"] == "0",
+                  provider_reference: body["ConversationID"] || body["OriginatorConversationID"],
+                  message: body["ResponseDescription"] || body["errorMessage"],
+                  code: (body["ResponseCode"] || body["errorCode"])&.to_s,
+                  raw: body
+                ))
+      end
+
+      def ensure_refund_config_present!
+        config = self.class.config
+        return if config.initiator_name && config.initiator_password && config.security_credential_cert
+
+        raise Lipwa::ConfigurationError,
+              "#{self.class} is missing initiator_name/initiator_password/security_credential_cert " \
+              "— set them via .configure to use #refund"
+      end
+    end
+  end
+end

data/lib/lipwa/capabilities/status_query.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/status_query_contract"
+
+module Lipwa
+  module Capabilities
+    # Actively queries Daraja for the outcome of a prior transaction
+    # (STK Push, C2B, B2C/B2B) by its TransactionID, for the "all async
+    # flows" case described in plan.md — a complement to, not a
+    # replacement for, the passive webhook/result-callback path. Like
+    # Disbursement, Daraja requires a SecurityCredential, and the query
+    # call itself only acknowledges receipt; the actual status arrives
+    # later at result_url as a third callback envelope
+    # (`{"Result" => {...}}`), parsed by Lipwa::Webhooks::Mpesa as a
+    # :transaction_status event.
+    module StatusQuery
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :status_query
+
+      PATH = "/mpesa/transactionstatus/v1/query"
+      IDENTIFIER_TYPE = "4" # shortcode
+
+      CONTRACT = Lipwa::Contracts::StatusQueryContract.new
+
+      def status(transaction_id:, remarks:, result_url:, queue_timeout_url:, occasion: nil)
+        validate_and_query(
+          transaction_id: transaction_id, remarks: remarks, result_url: result_url,
+          queue_timeout_url: queue_timeout_url, occasion: occasion
+        )
+      end
+
+      private
+
+      def validate_and_query(args)
+        validation = CONTRACT.call(args)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_status_query(validation.to_h)
+      end
+
+      def perform_status_query(params)
+        ensure_status_query_config_present!
+
+        response = http.post(PATH, body: status_query_body(params))
+
+        build_status_query_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def status_query_body(params)
+        {
+          Initiator: self.class.config.initiator_name,
+          SecurityCredential: security_credential,
+          CommandID: "TransactionStatusQuery",
+          TransactionID: params[:transaction_id],
+          PartyA: self.class.config.shortcode,
+          IdentifierType: IDENTIFIER_TYPE
+        }.merge(shared_status_query_fields(params))
+      end
+
+      def shared_status_query_fields(params)
+        {
+          ResultURL: params[:result_url],
+          QueueTimeOutURL: params[:queue_timeout_url],
+          Remarks: params[:remarks],
+          Occasion: params[:occasion]
+        }
+      end
+
+      def security_credential
+        Lipwa::Gateways::Mpesa::SecurityCredential.encrypt(
+          self.class.config.initiator_password,
+          cert: self.class.config.security_credential_cert
+        )
+      end
+
+      def build_status_query_response(body)
+        Success(Lipwa::Response.new(
+                  success: body["ResponseCode"] == "0",
+                  provider_reference: body["ConversationID"] || body["OriginatorConversationID"],
+                  message: body["ResponseDescription"] || body["errorMessage"],
+                  code: (body["ResponseCode"] || body["errorCode"])&.to_s,
+                  raw: body
+                ))
+      end
+
+      def ensure_status_query_config_present!
+        config = self.class.config
+        return if config.initiator_name && config.initiator_password && config.security_credential_cert
+
+        raise Lipwa::ConfigurationError,
+              "#{self.class} is missing initiator_name/initiator_password/security_credential_cert " \
+              "— set them via .configure to use #status"
+      end
+    end
+  end
+end

data/lib/lipwa/capabilities/stk_push.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "base64"
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/stk_push_contract"
+
+module Lipwa
+  module Capabilities
+    # Lipa Na M-Pesa Online (STK Push): pushes a payment prompt to the
+    # payer's phone. The actual result arrives later via the merchant's
+    # callback URL — this call only confirms Daraja accepted the request
+    # (CheckoutRequestID), it is not itself the payment result.
+    module StkPush
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :stk_push
+
+      PATH = "/mpesa/stkpush/v1/processrequest"
+      TRANSACTION_TYPE = "CustomerPayBillOnline"
+
+      CONTRACT = Lipwa::Contracts::StkPushContract.new
+
+      def stk_push(amount:, phone_number:, account_reference:, callback_url:, transaction_desc: nil)
+        validation = CONTRACT.call(
+          amount: amount,
+          phone_number: phone_number,
+          account_reference: account_reference,
+          callback_url: callback_url,
+          transaction_desc: transaction_desc || account_reference
+        )
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_stk_push(validation.to_h)
+      end
+
+      private
+
+      def perform_stk_push(params)
+        response = http.post(PATH, body: stk_push_body(params))
+
+        build_stk_push_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def stk_push_body(params)
+        config = self.class.config
+        timestamp = Time.now.strftime("%Y%m%d%H%M%S")
+
+        {
+          BusinessShortCode: config.shortcode,
+          Password: stk_push_password(config, timestamp),
+          Timestamp: timestamp,
+          TransactionType: TRANSACTION_TYPE,
+          PartyA: params[:phone_number],
+          PartyB: config.shortcode
+        }.merge(stk_push_transaction_fields(params))
+      end
+
+      def stk_push_transaction_fields(params)
+        {
+          Amount: params[:amount].amount,
+          PhoneNumber: params[:phone_number],
+          CallBackURL: params[:callback_url],
+          AccountReference: params[:account_reference],
+          TransactionDesc: params[:transaction_desc]
+        }
+      end
+
+      def stk_push_password(config, timestamp)
+        Base64.strict_encode64("#{config.shortcode}#{config.passkey}#{timestamp}")
+      end
+
+      def build_stk_push_response(body)
+        Success(Lipwa::Response.new(
+                  success: body["ResponseCode"] == "0",
+                  provider_reference: body["CheckoutRequestID"],
+                  message: body["ResponseDescription"] || body["errorMessage"],
+                  code: (body["ResponseCode"] || body["errorCode"])&.to_s,
+                  raw: body
+                ))
+      end
+    end
+  end
+end

data/lib/lipwa/capability.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Lipwa
+  # Mixin for capability modules (Lipwa::Capabilities::StkPush,
+  # Lipwa::Capabilities::Disbursement, ...). A capability module extends
+  # this and declares its `capability_name`; when the module is included
+  # into a Gateway subclass, that name is auto-registered so
+  # `gateway.capability?(:stk_push)` reflects reality — the method
+  # existing — instead of a hand-maintained list that can drift.
+  #
+  #   module Lipwa
+  #     module Capabilities
+  #       module StkPush
+  #         extend Lipwa::Capability
+  #         self.capability_name = :stk_push
+  #
+  #         def stk_push(...); end
+  #       end
+  #     end
+  #   end
+  module Capability
+    def self.extended(capability_module)
+      capability_module.singleton_class.attr_accessor :capability_name
+    end
+
+    def included(base)
+      super
+      unless capability_name
+        raise Lipwa::ConfigurationError, "#{self} must set `self.capability_name` before being included"
+      end
+
+      base.register_capability(capability_name)
+    end
+  end
+end

data/lib/lipwa/configuration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "dry/configurable"
+
+# Unified payment gateway abstraction for African payment providers.
+module Lipwa
+  extend Dry::Configurable
+
+  setting :logger
+  setting :default_timeout, default: 10
+  setting :adapter, default: Faraday.default_adapter
+end

data/lib/lipwa/contracts/c2b_register_urls_contract.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module Lipwa
+  module Contracts
+    # Validates the kwargs Lipwa::Capabilities::C2B#register_urls is
+    # called with, before any network call is made. Validates the
+    # capability's own params, not the raw Daraja wire payload.
+    class C2bRegisterUrlsContract < Dry::Validation::Contract
+      RESPONSE_TYPES = %w[Completed Cancelled].freeze
+
+      schema do
+        required(:validation_url).filled(:string)
+        required(:confirmation_url).filled(:string)
+        required(:response_type).filled(:string)
+      end
+
+      rule(:validation_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+
+      rule(:confirmation_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+
+      rule(:response_type) do
+        key.failure("must be one of #{RESPONSE_TYPES.join(", ")}") unless RESPONSE_TYPES.include?(value)
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/c2b_simulate_contract.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+require_relative "../money"
+
+module Lipwa
+  module Contracts
+    # Validates the kwargs Lipwa::Capabilities::C2B#simulate is called
+    # with, before any network call is made. Validates the capability's
+    # own params, not the raw Daraja wire payload.
+    class C2bSimulateContract < Dry::Validation::Contract
+      COMMAND_IDS = %w[CustomerPayBillOnline CustomerBuyGoodsOnline].freeze
+
+      schema do
+        required(:amount).filled
+        required(:phone_number).filled(:string)
+        required(:bill_ref_number).filled(:string)
+        required(:command_id).filled(:string)
+      end
+
+      rule(:amount) do
+        next key.failure("must be a Lipwa::Money") unless value.is_a?(Lipwa::Money)
+
+        key.failure("must be KES") if value.currency != "KES"
+        key.failure("must be greater than zero") if value.amount <= 0
+      end
+
+      rule(:phone_number) do
+        key.failure("must be a Safaricom MSISDN, e.g. 254712345678") unless value.match?(/\A254[17]\d{8}\z/)
+      end
+
+      rule(:bill_ref_number) do
+        key.failure("must be 20 characters or fewer") if value.length > 20
+      end
+
+      rule(:command_id) do
+        key.failure("must be one of #{COMMAND_IDS.join(", ")}") unless COMMAND_IDS.include?(value)
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/disbursement_contract.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+require_relative "../money"
+
+module Lipwa
+  module Contracts
+    # Validates the kwargs Lipwa::Capabilities::Disbursement#disburse is
+    # called with, before any network call is made. Covers both B2C
+    # (PartyB is a phone number) and B2B (PartyB is a business shortcode,
+    # AccountReference required) shapes under one contract, mirroring how
+    # #disburse itself dispatches on command_id rather than exposing two
+    # methods.
+    class DisbursementContract < Dry::Validation::Contract
+      B2C_COMMAND_IDS = %w[SalaryPayment BusinessPayment PromotionPayment].freeze
+      B2B_COMMAND_IDS = %w[BusinessPayBill BusinessBuyGoods MerchantToMerchantTransfer].freeze
+      COMMAND_IDS = (B2C_COMMAND_IDS + B2B_COMMAND_IDS).freeze
+
+      schema do
+        required(:command_id).filled(:string)
+        required(:amount).filled
+        required(:party_b).filled(:string)
+        required(:remarks).filled(:string)
+        required(:result_url).filled(:string)
+        required(:queue_timeout_url).filled(:string)
+        optional(:occasion).maybe(:string)
+        optional(:account_reference).maybe(:string)
+      end
+
+      rule(:amount) do
+        next key.failure("must be a Lipwa::Money") unless value.is_a?(Lipwa::Money)
+
+        key.failure("must be KES") if value.currency != "KES"
+        key.failure("must be greater than zero") if value.amount <= 0
+      end
+
+      rule(:command_id) do
+        key.failure("must be one of #{COMMAND_IDS.join(", ")}") unless COMMAND_IDS.include?(value)
+      end
+
+      rule(:party_b, :command_id) do
+        next unless B2C_COMMAND_IDS.include?(values[:command_id])
+
+        unless values[:party_b].match?(/\A254[17]\d{8}\z/)
+          key(:party_b).failure("must be a Safaricom MSISDN, e.g. 254712345678")
+        end
+      end
+
+      rule(:account_reference, :command_id) do
+        next unless B2B_COMMAND_IDS.include?(values[:command_id])
+
+        if values[:account_reference].nil? || values[:account_reference].empty?
+          key(:account_reference).failure("is required for B2B command IDs")
+        end
+      end
+
+      rule(:result_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+
+      rule(:queue_timeout_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/refund_contract.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+require_relative "../money"
+
+module Lipwa
+  module Contracts
+    # Validates the kwargs Lipwa::Capabilities::Refund#refund is called
+    # with, before any network call is made. ReceiverParty and
+    # RecieverIdentifierType aren't part of the schema — like
+    # StatusQuery's PartyA, they're always the gateway's own shortcode,
+    # not a per-call param.
+    class RefundContract < Dry::Validation::Contract
+      schema do
+        required(:transaction_id).filled(:string)
+        required(:amount).filled
+        required(:remarks).filled(:string)
+        required(:result_url).filled(:string)
+        required(:queue_timeout_url).filled(:string)
+        optional(:occasion).maybe(:string)
+      end
+
+      rule(:amount) do
+        next key.failure("must be a Lipwa::Money") unless value.is_a?(Lipwa::Money)
+
+        key.failure("must be KES") if value.currency != "KES"
+        key.failure("must be greater than zero") if value.amount <= 0
+      end
+
+      rule(:result_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+
+      rule(:queue_timeout_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/status_query_contract.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module Lipwa
+  module Contracts
+    # Validates the kwargs Lipwa::Capabilities::StatusQuery#status is
+    # called with, before any network call is made. PartyA and
+    # IdentifierType aren't part of the schema — like Disbursement's
+    # PartyA, they're always the gateway's own shortcode, not a
+    # 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(:occasion).maybe(:string)
+      end
+
+      rule(:result_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+
+      rule(:queue_timeout_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+    end
+  end
+end

data/lib/lipwa/contracts/stk_push_contract.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+require_relative "../money"
+
+module Lipwa
+  module Contracts
+    # Validates the kwargs Lipwa::Capabilities::StkPush#stk_push is
+    # called with, before any network call is made. Validates the
+    # capability's own params, not the raw Daraja wire payload.
+    class StkPushContract < Dry::Validation::Contract
+      schema do
+        required(:amount).filled
+        required(:phone_number).filled(:string)
+        required(:account_reference).filled(:string)
+        required(:callback_url).filled(:string)
+        optional(:transaction_desc).maybe(:string)
+      end
+
+      rule(:amount) do
+        next key.failure("must be a Lipwa::Money") unless value.is_a?(Lipwa::Money)
+
+        key.failure("must be KES") if value.currency != "KES"
+        key.failure("must be greater than zero") if value.amount <= 0
+      end
+
+      rule(:phone_number) do
+        key.failure("must be a Safaricom MSISDN, e.g. 254712345678") unless value.match?(/\A254[17]\d{8}\z/)
+      end
+
+      rule(:account_reference) do
+        key.failure("must be 12 characters or fewer") if value.length > 12
+      end
+
+      rule(:callback_url) do
+        key.failure("must be an https:// URL") unless value.start_with?("https://")
+      end
+    end
+  end
+end

data/lib/lipwa/errors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Lipwa
+  # Base class for everything the gem raises or wraps in a Failure.
+  class Error < StandardError; end
+
+  # Raised (not wrapped) when a gateway is misconfigured — missing
+  # credentials, invalid environment, etc. A programmer/ops mistake,
+  # not something callers should route through Result handling.
+  class ConfigurationError < Error; end
+
+  # Raised (not wrapped) when calling a capability method a gateway
+  # doesn't include. A programmer mistake caught at call time.
+  class UnsupportedCapabilityError < Error; end
+
+  # Raised (not wrapped) when Lipwa::Webhook.parse_webhook is called for
+  # a provider with no registered parser. A programmer/config mistake,
+  # not something callers should route through Result handling.
+  class UnsupportedProviderError < Error; end
+
+  # Wrapped in Failure(...). The inbound webhook body could not be
+  # parsed (e.g. invalid JSON) — a runtime condition on untrusted
+  # network input, not a programmer mistake.
+  class WebhookParseError < Error; end
+
+  # Wrapped in Failure(...). Request params failed contract validation
+  # before any network call was made.
+  class ValidationError < Error
+    attr_reader :validation_result
+
+    def initialize(validation_result)
+      @validation_result = validation_result
+      super(validation_result.errors.to_h.to_s)
+    end
+  end
+
+  # Wrapped in Failure(...). The provider's API returned an error, or
+  # the HTTP call itself failed (timeout, connection error, etc).
+  class GatewayError < Error
+    attr_reader :code, :raw
+
+    def initialize(message, code: nil, raw: nil)
+      @code = code
+      @raw = raw
+      super(message)
+    end
+  end
+end