lipwa 0.1.2 → 0.1.4

data/lib/lipwa/auth_strategies/jenga.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require_relative "base"
+
+module Lipwa
+  module AuthStrategies
+    # Adds Jenga HQ's OAuth2 bearer token and RSA-SHA256 request signature.
+    #
+    # Jenga defines a different signature formula for each endpoint. The
+    # signature_payload callable receives the Faraday::Env for the outgoing
+    # request and must return the exact concatenated String required by that
+    # endpoint (without separators). It is evaluated for every request.
+    class Jenga < Base
+      def initialize(token_provider:, private_key:, signature_payload:)
+        super()
+        validate_callable!(token_provider, :token_provider)
+        validate_callable!(signature_payload, :signature_payload)
+
+        @token_provider = token_provider
+        @private_key = parse_private_key(private_key)
+        @signature_payload = signature_payload
+      end
+
+      def initialize_copy(source)
+        super
+        @token_provider = @token_provider.dup
+      end
+
+      def apply(env)
+        payload = @signature_payload.call(env)
+        raise ArgumentError, "signature_payload must return a String" unless payload.is_a?(String)
+
+        signature = @private_key.sign(OpenSSL::Digest.new("SHA256"), payload)
+        env.request_headers["Authorization"] = "Bearer #{@token_provider.call}"
+        env.request_headers["Signature"] = Base64.strict_encode64(signature)
+      end
+
+      private
+
+      def validate_callable!(value, name)
+        raise ArgumentError, "#{name} must respond to #call" unless value.respond_to?(:call)
+      end
+
+      def parse_private_key(private_key)
+        key = private_key.is_a?(OpenSSL::PKey::RSA) ? private_key : OpenSSL::PKey::RSA.new(private_key)
+        raise ArgumentError, "private_key must contain an RSA private key" unless key.private?
+
+        key
+      rescue OpenSSL::PKey::PKeyError, TypeError
+        raise ArgumentError, "private_key must be an RSA private key or PEM encoded RSA private key"
+      end
+    end
+
+    JengaHQ = Jenga
+  end
+end

data/lib/lipwa/auth_strategies.rb

@@ -3,3 +3,5 @@
 require_relative "auth_strategies/base"
 require_relative "auth_strategies/none"
 require_relative "auth_strategies/bearer_token"
+require_relative "auth_strategies/api_key"
+require_relative "auth_strategies/jenga"

data/lib/lipwa/capabilities/authorize.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/card_payment_contract"
+
+module Lipwa
+  module Capabilities
+    # Creates a provider authorization flow without exposing card data.
+    module Authorize
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :authorize
+
+      CONTRACT = Lipwa::Contracts::CardPaymentContract.new
+
+      def authorize(**params)
+        idempotency_key = params.delete(:idempotency_key)
+        validation = CONTRACT.call(params)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_authorize(validation.to_h, idempotency_key)
+      end
+    end
+  end
+end

data/lib/lipwa/capabilities/bank_transfer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/bank_transfer_contract"
+module Lipwa
+  module Capabilities
+    module BankTransfer
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :bank_transfer
+      TRANSFER_CONTRACT = Lipwa::Contracts::BankTransferContract.new
+      ACCOUNT_CONTRACT = Lipwa::Contracts::BankAccountContract.new
+      STATEMENT_CONTRACT = Lipwa::Contracts::BankStatementContract.new
+
+      def transfer(rail:, amount:, source_account:, destination_account:, reference:, narration: nil,
+                   callback_url: nil, destination_bank_code: nil, destination_name: nil, biller_code: nil,
+                   idempotency_key: nil)
+        args = { rail: rail, amount: amount, source_account: source_account,
+                 destination_account: destination_account, reference: reference, narration: narration,
+                 callback_url: callback_url, destination_bank_code: destination_bank_code,
+                 destination_name: destination_name, biller_code: biller_code }
+        invoke_bank_operation(TRANSFER_CONTRACT, args, idempotency_key) do |params, key|
+          bank_transfer_request(params, key)
+        end
+      end
+
+      def balance(account_number:, message_reference: nil, idempotency_key: nil)
+        invoke_bank_operation(ACCOUNT_CONTRACT,
+                              { account_number: account_number, message_reference: message_reference },
+                              idempotency_key) do |params, key|
+          bank_balance_request(params, key)
+        end
+      end
+
+      def statement(account_number:, from_date: nil, to_date: nil, message_reference: nil,
+                    idempotency_key: nil)
+        args = { account_number: account_number, from_date: from_date, to_date: to_date,
+                 message_reference: message_reference }
+        invoke_bank_operation(STATEMENT_CONTRACT, args, idempotency_key) do |params, key|
+          bank_statement_request(params, key)
+        end
+      end
+
+      private
+
+      def invoke_bank_operation(contract, args, idempotency_key)
+        validation = contract.call(args)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        build_bank_response(yield(validation.to_h, idempotency_key).body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def build_bank_response(body)
+        code = body["ResponseCode"] || body["responseCode"] || body["Code"] || body["code"]
+        reference = body["MessageReference"] || body["messageReference"] || body["TransactionReference"] || body["transactionReference"]
+        message = body["ResponseMessage"] || body["responseMessage"] || body["Message"] || body["message"]
+        success = code.nil? || %w[0 00 000 200 Success SUCCESS].include?(code.to_s)
+        Success(Lipwa::Response.new(success: success, provider_reference: reference&.to_s,
+                                    message: message&.to_s, code: code&.to_s, raw: body))
+      end
+    end
+  end
+end

data/lib/lipwa/capabilities/c2b.rb

@@ -24,7 +24,7 @@ module Lipwa
       REGISTER_URLS_CONTRACT = Lipwa::Contracts::C2bRegisterUrlsContract.new
       SIMULATE_CONTRACT = Lipwa::Contracts::C2bSimulateContract.new
 
-      def register_urls(validation_url:, confirmation_url:, response_type: "Completed")
+      def register_urls(validation_url:, confirmation_url:, response_type: "Completed", idempotency_key: nil)
         validation = REGISTER_URLS_CONTRACT.call(
           validation_url: validation_url,
           confirmation_url: confirmation_url,
@@ -32,13 +32,14 @@ module Lipwa
         )
         return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
 
-        perform_register_urls(validation.to_h)
+        perform_register_urls(validation.to_h, idempotency_key)
       end
 
       # Sandbox-only: triggers a simulated C2B payment so the
       # registered validation/confirmation URLs can be exercised
       # without a real customer transaction.
-      def simulate(amount:, phone_number:, bill_ref_number:, command_id: "CustomerPayBillOnline")
+      def simulate(amount:, phone_number:, bill_ref_number:, command_id: "CustomerPayBillOnline",
+                   idempotency_key: nil)
         validation = SIMULATE_CONTRACT.call(
           amount: amount,
           phone_number: phone_number,
@@ -47,13 +48,13 @@ module Lipwa
         )
         return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
 
-        perform_simulate(validation.to_h)
+        perform_simulate(validation.to_h, idempotency_key)
       end
 
       private
 
-      def perform_register_urls(params)
-        response = http.post(REGISTER_URLS_PATH, body: register_urls_body(params))
+      def perform_register_urls(params, idempotency_key)
+        response = http.post(REGISTER_URLS_PATH, body: register_urls_body(params), idempotency_key: idempotency_key)
 
         build_c2b_response(response.body)
       rescue Lipwa::GatewayError => e
@@ -62,15 +63,15 @@ module Lipwa
 
       def register_urls_body(params)
         {
-          ShortCode: self.class.config.shortcode,
+          ShortCode: config.shortcode,
           ResponseType: params[:response_type],
           ConfirmationURL: params[:confirmation_url],
           ValidationURL: params[:validation_url]
         }
       end
 
-      def perform_simulate(params)
-        response = http.post(SIMULATE_PATH, body: simulate_body(params))
+      def perform_simulate(params, idempotency_key)
+        response = http.post(SIMULATE_PATH, body: simulate_body(params), idempotency_key: idempotency_key)
 
         build_c2b_response(response.body)
       rescue Lipwa::GatewayError => e
@@ -79,7 +80,7 @@ module Lipwa
 
       def simulate_body(params)
         {
-          ShortCode: self.class.config.shortcode,
+          ShortCode: config.shortcode,
           CommandID: params[:command_id],
           Amount: params[:amount].amount,
           Msisdn: params[:phone_number],

data/lib/lipwa/capabilities/capture.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
+    # Confirms a provider authorization has completed successfully.
+    module Capture
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :capture
+
+      CONTRACT = Lipwa::Contracts::CardTransactionContract.new
+
+      def capture(authorization:, amount: nil, idempotency_key: nil)
+        validation = CONTRACT.call({ authorization: authorization, amount: amount }.compact)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_capture(validation.to_h, idempotency_key)
+      end
+    end
+  end
+end

data/lib/lipwa/capabilities/disbursement.rb

@@ -28,29 +28,28 @@ module Lipwa
 
       # rubocop:disable Metrics/ParameterLists
       def disburse(command_id:, amount:, party_b:, remarks:, result_url:, queue_timeout_url:, occasion: nil,
-                   account_reference: nil)
-        validate_and_disburse(
-          command_id: command_id, amount: amount, party_b: party_b, remarks: remarks,
-          result_url: result_url, queue_timeout_url: queue_timeout_url,
-          occasion: occasion, account_reference: account_reference
-        )
+                   account_reference: nil, idempotency_key: nil)
+        args = { command_id: command_id, amount: amount, party_b: party_b, remarks: remarks,
+                 result_url: result_url, queue_timeout_url: queue_timeout_url,
+                 occasion: occasion, account_reference: account_reference }
+        validate_and_disburse(args, idempotency_key)
       end
       # rubocop:enable Metrics/ParameterLists
 
       private
 
-      def validate_and_disburse(args)
+      def validate_and_disburse(args, idempotency_key)
         validation = CONTRACT.call(args)
         return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
 
-        perform_disburse(validation.to_h)
+        perform_disburse(validation.to_h, idempotency_key)
       end
 
-      def perform_disburse(params)
+      def perform_disburse(params, idempotency_key)
         ensure_disbursement_config_present!
         path = B2C_COMMAND_IDS.include?(params[:command_id]) ? B2C_PATH : B2B_PATH
 
-        response = http.post(path, body: disbursement_body(params))
+        response = http.post(path, body: disbursement_body(params), idempotency_key: idempotency_key)
 
         build_disbursement_response(response.body)
       rescue Lipwa::GatewayError => e
@@ -67,10 +66,10 @@ module Lipwa
 
       def b2c_body(params)
         {
-          InitiatorName: self.class.config.initiator_name,
+          InitiatorName: config.initiator_name,
           SecurityCredential: security_credential,
           CommandID: params[:command_id],
-          PartyA: self.class.config.shortcode,
+          PartyA: config.shortcode,
           PartyB: params[:party_b],
           Occasion: params[:occasion]
         }.merge(shared_disbursement_fields(params))
@@ -78,12 +77,12 @@ module Lipwa
 
       def b2b_body(params)
         {
-          Initiator: self.class.config.initiator_name,
+          Initiator: config.initiator_name,
           SecurityCredential: security_credential,
           CommandID: params[:command_id],
           SenderIdentifierType: "4",
           RecieverIdentifierType: "4",
-          PartyA: self.class.config.shortcode,
+          PartyA: config.shortcode,
           PartyB: params[:party_b],
           AccountReference: params[:account_reference]
         }.merge(shared_disbursement_fields(params))
@@ -100,8 +99,8 @@ module Lipwa
 
       def security_credential
         Lipwa::Gateways::Mpesa::SecurityCredential.encrypt(
-          self.class.config.initiator_password,
-          cert: self.class.config.security_credential_cert
+          config.initiator_password,
+          cert: config.security_credential_cert
         )
       end
 
@@ -117,7 +116,7 @@ module Lipwa
       end
 
       def ensure_disbursement_config_present!
-        config = self.class.config
+        config = self.config
         return if config.initiator_name && config.initiator_password && config.security_credential_cert
 
         raise Lipwa::ConfigurationError,

data/lib/lipwa/capabilities/lightning_invoice.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/lightning_invoice_contract"
+require_relative "../contracts/lightning_invoice_check_contract"
+
+module Lipwa
+  module Capabilities
+    # Creates and checks LNbits Lightning invoices. Amounts passed to
+    # #create_invoice are integer satoshis; they intentionally do not use
+    # Lipwa::Money because BTC/sats are outside the ISO-4217 money model.
+    module LightningInvoice
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :lightning_invoice
+
+      PATH = "/api/v1/payments"
+      CREATE_CONTRACT = Lipwa::Contracts::LightningInvoiceContract.new
+      CHECK_CONTRACT = Lipwa::Contracts::LightningInvoiceCheckContract.new
+
+      def create_invoice(amount_sats:, memo: nil, expiry: nil, webhook_url: nil)
+        validation = CREATE_CONTRACT.call(
+          amount_sats: amount_sats, memo: memo, expiry: expiry, webhook_url: webhook_url
+        )
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_create_invoice(validation.to_h)
+      end
+
+      def check_invoice(payment_hash:)
+        validation = CHECK_CONTRACT.call(payment_hash: payment_hash)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_check_invoice(validation.to_h)
+      end
+
+      private
+
+      def perform_create_invoice(params)
+        response = http.post(PATH, body: lightning_invoice_body(params))
+
+        Success(Lipwa::Response.new(
+                  success: true,
+                  provider_reference: response.body["payment_hash"],
+                  raw: response.body
+                ))
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def perform_check_invoice(params)
+        response = http.get("#{PATH}/#{params[:payment_hash]}")
+
+        Success(Lipwa::Response.new(
+                  success: response.body["paid"] == true,
+                  provider_reference: params[:payment_hash],
+                  raw: response.body
+                ))
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def lightning_invoice_body(params)
+        {
+          out: false,
+          amount: params[:amount_sats],
+          memo: params[:memo],
+          expiry: params[:expiry],
+          webhook: params[:webhook_url]
+        }.compact
+      end
+    end
+  end
+end

data/lib/lipwa/capabilities/lightning_payment.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/lightning_payment_contract"
+require_relative "../contracts/lightning_payment_check_contract"
+
+module Lipwa
+  module Capabilities
+    # Sends and reconciles outbound Lightning payments. This capability is
+    # deliberately separate from LightningInvoice because spending requires a
+    # materially more privileged credential than receiving.
+    module LightningPayment
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :lightning_payment
+
+      PATH = "/api/v1/payments"
+      PAY_CONTRACT = Lipwa::Contracts::LightningPaymentContract.new
+      CHECK_CONTRACT = Lipwa::Contracts::LightningPaymentCheckContract.new
+
+      def pay_invoice(bolt11:)
+        validation = PAY_CONTRACT.call(bolt11: bolt11)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_pay_invoice(validation.to_h)
+      end
+
+      def check_payment(payment_hash:)
+        validation = CHECK_CONTRACT.call(payment_hash: payment_hash)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_check_payment(validation.to_h)
+      end
+
+      private
+
+      def perform_pay_invoice(params)
+        response = lightning_payment_http.post(PATH, body: { out: true, bolt11: params[:bolt11] })
+        Success(payment_response(response.body))
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def perform_check_payment(params)
+        response = lightning_payment_http.get("#{PATH}/#{params[:payment_hash]}")
+        Success(payment_response(response.body, payment_hash: params[:payment_hash]))
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def payment_response(payload, payment_hash: nil)
+        Lipwa::Response.new(
+          success: payment_successful?(payload),
+          provider_reference: payment_hash || payload["payment_hash"],
+          message: payload["detail"] || payload["message"],
+          raw: payload
+        )
+      end
+
+      def payment_successful?(payload)
+        payload["paid"] == true || payload["status"].to_s.casecmp?("success")
+      end
+
+      # Gateways with distinct spending credentials override this method.
+      def lightning_payment_http
+        http
+      end
+    end
+  end
+end

data/lib/lipwa/capabilities/purchase.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/card_payment_contract"
+
+module Lipwa
+  module Capabilities
+    # Creates a payment which is collected in the provider checkout flow.
+    module Purchase
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :purchase
+
+      CONTRACT = Lipwa::Contracts::CardPaymentContract.new
+
+      def purchase(**params)
+        idempotency_key = params.delete(:idempotency_key)
+        validation = CONTRACT.call(params)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_purchase(validation.to_h, idempotency_key)
+      end
+    end
+  end
+end

data/lib/lipwa/capabilities/refund.rb

@@ -24,27 +24,27 @@ module Lipwa
       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
-        )
+      def refund(transaction_id:, amount:, remarks:, result_url:, queue_timeout_url:, occasion: nil,
+                 idempotency_key: nil)
+        args = { transaction_id: transaction_id, amount: amount, remarks: remarks,
+                 result_url: result_url, queue_timeout_url: queue_timeout_url, occasion: occasion }
+        validate_and_refund(args, idempotency_key)
       end
       # rubocop:enable Metrics/ParameterLists
 
       private
 
-      def validate_and_refund(args)
+      def validate_and_refund(args, idempotency_key)
         validation = CONTRACT.call(args)
         return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
 
-        perform_refund(validation.to_h)
+        perform_refund(validation.to_h, idempotency_key)
       end
 
-      def perform_refund(params)
+      def perform_refund(params, idempotency_key)
         ensure_refund_config_present!
 
-        response = http.post(PATH, body: refund_body(params))
+        response = http.post(PATH, body: refund_body(params), idempotency_key: idempotency_key)
 
         build_refund_response(response.body)
       rescue Lipwa::GatewayError => e
@@ -53,12 +53,12 @@ module Lipwa
 
       def refund_body(params)
         {
-          Initiator: self.class.config.initiator_name,
+          Initiator: config.initiator_name,
           SecurityCredential: security_credential,
           CommandID: "TransactionReversal",
           TransactionID: params[:transaction_id],
           Amount: params[:amount].amount,
-          ReceiverParty: self.class.config.shortcode,
+          ReceiverParty: config.shortcode,
           RecieverIdentifierType: RECEIVER_IDENTIFIER_TYPE
         }.merge(shared_refund_fields(params))
       end
@@ -74,8 +74,8 @@ module Lipwa
 
       def security_credential
         Lipwa::Gateways::Mpesa::SecurityCredential.encrypt(
-          self.class.config.initiator_password,
-          cert: self.class.config.security_credential_cert
+          config.initiator_password,
+          cert: config.security_credential_cert
         )
       end
 
@@ -90,7 +90,7 @@ module Lipwa
       end
 
       def ensure_refund_config_present!
-        config = self.class.config
+        config = self.config
         return if config.initiator_name && config.initiator_password && config.security_credential_cert
 
         raise Lipwa::ConfigurationError,

data/lib/lipwa/capabilities/status_query.rb

@@ -25,39 +25,48 @@ module Lipwa
 
       CONTRACT = Lipwa::Contracts::StatusQueryContract.new
 
-      def status(transaction_id:, remarks:, result_url:, queue_timeout_url:, occasion: nil)
+      def status(transaction_id: nil, message_reference: nil, remarks: nil, result_url: nil, # rubocop:disable Metrics/ParameterLists
+                 queue_timeout_url: nil, occasion: nil, idempotency_key: nil)
         validate_and_query(
-          transaction_id: transaction_id, remarks: remarks, result_url: result_url,
-          queue_timeout_url: queue_timeout_url, occasion: occasion
+          {
+            transaction_id: transaction_id, message_reference: message_reference,
+            remarks: remarks, result_url: result_url,
+            queue_timeout_url: queue_timeout_url, occasion: occasion
+          },
+          idempotency_key
         )
       end
 
       private
 
-      def validate_and_query(args)
+      def validate_and_query(args, idempotency_key)
         validation = CONTRACT.call(args)
         return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
 
-        perform_status_query(validation.to_h)
+        perform_status_query(validation.to_h, idempotency_key)
       end
 
-      def perform_status_query(params)
+      def perform_status_query(params, idempotency_key)
         ensure_status_query_config_present!
 
-        response = http.post(PATH, body: status_query_body(params))
+        response = status_query_request(params, idempotency_key)
 
         build_status_query_response(response.body)
       rescue Lipwa::GatewayError => e
         Failure(e)
       end
 
+      def status_query_request(params, idempotency_key)
+        http.post(PATH, body: status_query_body(params), idempotency_key: idempotency_key)
+      end
+
       def status_query_body(params)
         {
-          Initiator: self.class.config.initiator_name,
+          Initiator: config.initiator_name,
           SecurityCredential: security_credential,
           CommandID: "TransactionStatusQuery",
           TransactionID: params[:transaction_id],
-          PartyA: self.class.config.shortcode,
+          PartyA: config.shortcode,
           IdentifierType: IDENTIFIER_TYPE
         }.merge(shared_status_query_fields(params))
       end
@@ -73,8 +82,8 @@ module Lipwa
 
       def security_credential
         Lipwa::Gateways::Mpesa::SecurityCredential.encrypt(
-          self.class.config.initiator_password,
-          cert: self.class.config.security_credential_cert
+          config.initiator_password,
+          cert: config.security_credential_cert
         )
       end
 
@@ -89,7 +98,7 @@ module Lipwa
       end
 
       def ensure_status_query_config_present!
-        config = self.class.config
+        config = self.config
         return if config.initiator_name && config.initiator_password && config.security_credential_cert
 
         raise Lipwa::ConfigurationError,