lipwa 0.1.2 → 0.1.4

data/lib/lipwa/logging.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Lipwa
+  module Logging
+    REDACTED = "[REDACTED]"
+
+    # Produces sanitized copies of nested payloads without mutating caller data.
+    module Redactor
+      SECRET_NAMES = "authorization|signature|cookie|api[_-]?key|access[_-]?token|" \
+                     "refresh[_-]?token|token|consumer[_-]?key|client[_-]?id|" \
+                     "secret|password|passkey|" \
+                     "security[_-]?credential|private[_-]?key|admin[_-]?key|invoice[_-]?key|encryption[_-]?key"
+      SENSITIVE_KEY = /(?:#{SECRET_NAMES})/i
+      STRING_PATTERNS = [
+        /((?:authorization|proxy-authorization|signature)\s*:\s*)[^\r\n,]+/i,
+        /((?:^|[?&])(?:#{SECRET_NAMES})=)[^&#\s]+/i,
+        /(["']?(?:#{SECRET_NAMES})["']?\s*[:=]\s*["'])[^"']*(["'])/i
+      ].freeze
+
+      module_function
+
+      def call(value, key: nil) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+        return REDACTED if sensitive_key?(key)
+
+        case value
+        when Hash
+          value.each_with_object({}) do |(child_key, child_value), copy|
+            copy[child_key] = call(child_value, key: child_key)
+          end
+        when Array then value.map { |item| call(item) }
+        when String then redact_string(value)
+        when Exception then { class: value.class.name, message: redact_string(value.message) }
+        else value
+        end
+      end
+
+      def sensitive_key?(key) = key&.to_s&.match?(SENSITIVE_KEY)
+
+      def redact_string(value)
+        STRING_PATTERNS.reduce(value.dup) do |redacted, pattern|
+          redacted.gsub(pattern) { "#{Regexp.last_match(1)}#{REDACTED}#{Regexp.last_match(2)}" }
+        end
+      end
+    end
+
+    # Faraday middleware that emits one structured, sanitized event per call.
+    class Middleware < Faraday::Middleware
+      def initialize(app, logger)
+        super(app)
+        @logger = logger
+      end
+
+      def call(env)
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @app.call(env).on_complete { |completed| log(completed, started_at) }
+      rescue StandardError => e
+        log(env, started_at, error: e)
+        raise
+      end
+
+      private
+
+      def log(env, started_at, error: nil) # rubocop:disable Metrics/AbcSize
+        event = {
+          event: "lipwa.http", method: env.method&.to_s&.upcase,
+          url: sanitized_url(env.url), status: env.status,
+          duration_ms: elapsed_ms(started_at),
+          request: { headers: Redactor.call(env.request_headers.to_h), body: redact_body(env.request_body) },
+          response: { headers: Redactor.call(env.response_headers.to_h), body: redact_body(env.response_body) }
+        }
+        event[:error] = Redactor.call(error) if error
+        @logger.public_send(error || env.status.to_i >= 400 ? :error : :info, event)
+      end
+
+      def sanitized_url(url)
+        return unless url
+
+        copy = url.dup
+        copy.user = REDACTED if copy.user
+        copy.password = REDACTED if copy.password
+        copy.query = Redactor.redact_string(copy.query) if copy.query
+        copy.to_s
+      end
+
+      def redact_body(body)
+        parsed = body.is_a?(String) ? JSON.parse(body) : body
+        Redactor.call(parsed)
+      rescue JSON::ParserError
+        Redactor.call(body)
+      end
+
+      def elapsed_ms(started_at)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(1)
+      end
+    end
+  end
+end

data/lib/lipwa/money.rb

@@ -4,10 +4,10 @@ require "dry/struct"
 require_relative "types"
 
 module Lipwa
-  # Immutable representation of an amount in minor currency units.
-  # KES has no subunit in practice, but we keep minor units as the
-  # storage form so other currencies fit the same shape later.
+  # Immutable, decimal representation of an amount in one currency.
   class Money < Dry::Struct
+    include Comparable
+
     attribute :amount, Types::Amount
     attribute :currency, Types::Currency.default("KES")
 
@@ -21,16 +21,45 @@ module Lipwa
       self.class.new(amount: amount - other.amount, currency: currency)
     end
 
+    def *(other)
+      self.class.new(amount: amount * decimal_scalar(other), currency: currency)
+    end
+
+    def /(other)
+      divisor = decimal_scalar(other)
+      raise ZeroDivisionError, "divided by 0" if divisor.zero?
+
+      self.class.new(amount: amount / divisor, currency: currency)
+    end
+
+    def <=>(other)
+      return nil unless other.is_a?(self.class)
+
+      assert_same_currency!(other)
+      amount <=> other.amount
+    end
+
+    def zero?
+      amount.zero?
+    end
+
     def to_s
-      "#{amount} #{currency}"
+      "#{amount.to_s("F")} #{currency}"
     end
 
     private
 
     def assert_same_currency!(other)
+      raise TypeError, "expected #{self.class}, got #{other.class}" unless other.is_a?(self.class)
       return if currency == other.currency
 
       raise ArgumentError, "currency mismatch: #{currency} vs #{other.currency}"
     end
+
+    def decimal_scalar(value)
+      Types::Coercible::Decimal[value]
+    rescue Dry::Types::CoercionError, Dry::Types::ConstraintError
+      raise TypeError, "expected a numeric scalar, got #{value.inspect}"
+    end
   end
 end

data/lib/lipwa/types.rb

@@ -7,9 +7,9 @@ module Lipwa
   module Types
     include Dry.Types()
 
-    # Amounts are always integers in minor currency units (e.g. cents,
-    # or whole KES since M-Pesa has no subunit) to avoid float math.
-    Amount = Types::Strict::Integer.constrained(gteq: 0)
+    # BigDecimal-backed amounts avoid binary floating-point errors while
+    # accepting the numeric and string inputs commonly received from APIs.
+    Amount = Types::Coercible::Decimal.constrained(gteq: 0)
 
     Currency = Types::Strict::String.constrained(format: /\A[A-Z]{3}\z/)
 

data/lib/lipwa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lipwa
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end

data/lib/lipwa/webhooks/coop_bank.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../webhook"
+
+module Lipwa
+  module Webhooks
+    # Normalizes Co-op Bank transaction callbacks into WebhookEvent.
+    module CoopBank
+      module_function
+
+      def call(body:, headers: {}) # rubocop:disable Lint/UnusedMethodArgument
+        payload = body.is_a?(String) ? JSON.parse(body) : body
+        code = payload["MessageCode"]
+
+        Lipwa::WebhookEvent.new(
+          provider: :coop_bank,
+          event_type: :transaction_status,
+          success: code.to_s == "0",
+          provider_reference: payload["MessageReference"]&.to_s,
+          message: payload["MessageDescription"]&.to_s,
+          raw: payload
+        )
+      end
+    end
+  end
+end
+
+Lipwa::Webhook.register(:coop_bank, Lipwa::Webhooks::CoopBank)

data/lib/lipwa/webhooks/jenga.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require_relative "../webhook"
+
+module Lipwa
+  module Webhooks
+    # Parses Jenga HQ receive-payment Instant Payment Notifications (IPNs).
+    module Jenga
+      module_function
+
+      # rubocop:disable Metrics/MethodLength
+      def call(body:, headers: {})
+        payload = parse(body)
+        transaction = payload.fetch("transaction", {})
+        authorization = header(headers, "Authorization")
+
+        Lipwa::WebhookEvent.new(
+          provider: :jenga,
+          event_type: :receive_payment,
+          success: transaction["status"].to_s.casecmp?("SUCCESS"),
+          provider_reference: transaction["reference"],
+          message: transaction["remarks"],
+          raw: payload,
+          verifier: lambda do |raw:, username:, password:, **|
+            verify_signature(raw: raw, authorization: authorization, username: username, password: password)
+          end
+        )
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def parse(body)
+        body.is_a?(String) ? JSON.parse(body) : body
+      end
+
+      def verify_signature(raw:, authorization:, username:, password:) # rubocop:disable Lint/UnusedMethodArgument
+        return false unless authorization.is_a?(String) && username.is_a?(String) && password.is_a?(String)
+        return false if username.strip.empty? || password.strip.empty?
+
+        expected = "Basic #{Base64.strict_encode64("#{username}:#{password}")}"
+        return false unless authorization.bytesize == expected.bytesize
+
+        OpenSSL.fixed_length_secure_compare(authorization, expected)
+      end
+
+      def header(headers, name)
+        pair = headers.find { |key, _| key.to_s.casecmp?(name) }
+        pair&.last
+      end
+    end
+  end
+end
+
+Lipwa::Webhook.register(:jenga, Lipwa::Webhooks::Jenga)

data/lib/lipwa/webhooks/lnbits.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "openssl"
+require_relative "../webhook"
+
+module Lipwa
+  module Webhooks
+    # Parses LNbits invoice-payment callbacks. LNbits does not sign webhook
+    # bodies by default; the verifier compares a per-invoice token supplied in
+    # the webhook URL instead. Treat the callback only as a notification and
+    # independently confirm payment with #check_invoice before crediting it.
+    module Lnbits
+      module_function
+
+      def call(body:, headers: {}) # rubocop:disable Lint/UnusedMethodArgument
+        payload = parse(body)
+
+        Lipwa::WebhookEvent.new(
+          provider: :lnbits,
+          event_type: :payment,
+          success: !payload.key?("paid") || payload["paid"] == true,
+          provider_reference: payload.fetch("payment_hash"),
+          message: payload["memo"],
+          raw: payload,
+          verifier: method(:verify_signature)
+        )
+      end
+
+      def parse(body)
+        body.is_a?(String) ? JSON.parse(body) : body
+      end
+
+      # This verifies knowledge of a shared URL token, not authenticity of the
+      # body. The ** passthrough preserves the API for a future HMAC mode.
+      def verify_signature(raw: nil, expected_token: nil, provided_token: nil, **) # rubocop:disable Lint/UnusedMethodArgument
+        return false unless expected_token.is_a?(String) && provided_token.is_a?(String)
+        return false if expected_token.strip.empty?
+        return false unless expected_token.bytesize == provided_token.bytesize
+
+        OpenSSL.fixed_length_secure_compare(expected_token, provided_token)
+      end
+    end
+  end
+end
+
+Lipwa::Webhook.register(:lnbits, Lipwa::Webhooks::Lnbits)

data/lib/lipwa.rb

@@ -2,6 +2,7 @@
 
 require_relative "lipwa/version"
 require_relative "lipwa/errors"
+require_relative "lipwa/logging"
 require_relative "lipwa/types"
 require_relative "lipwa/money"
 require_relative "lipwa/response"
@@ -11,8 +12,12 @@ require_relative "lipwa/configuration"
 require_relative "lipwa/capability"
 require_relative "lipwa/gateway"
 require_relative "lipwa/gateways"
+require_relative "lipwa/context"
 require_relative "lipwa/webhook"
 require_relative "lipwa/webhooks/mpesa"
+require_relative "lipwa/webhooks/jenga"
+require_relative "lipwa/webhooks/coop_bank"
+require_relative "lipwa/webhooks/lnbits"
 require_relative "lipwa/contracts/c2b_register_urls_contract"
 require_relative "lipwa/contracts/c2b_simulate_contract"
 require_relative "lipwa/capabilities/c2b"
@@ -22,10 +27,34 @@ require_relative "lipwa/contracts/disbursement_contract"
 require_relative "lipwa/capabilities/disbursement"
 require_relative "lipwa/contracts/status_query_contract"
 require_relative "lipwa/capabilities/status_query"
+require_relative "lipwa/contracts/lightning_invoice_contract"
+require_relative "lipwa/contracts/lightning_invoice_check_contract"
+require_relative "lipwa/contracts/lightning_payment_contract"
+require_relative "lipwa/contracts/lightning_payment_check_contract"
+require_relative "lipwa/capabilities/lightning_invoice"
+require_relative "lipwa/capabilities/lightning_payment"
+require_relative "lipwa/gateways/lnbits"
+require_relative "lipwa/contracts/bank_transfer_contract"
+require_relative "lipwa/capabilities/bank_transfer"
+require_relative "lipwa/contracts/card_payment_contract"
+require_relative "lipwa/contracts/card_transaction_contract"
+require_relative "lipwa/capabilities/purchase"
+require_relative "lipwa/capabilities/authorize"
+require_relative "lipwa/capabilities/capture"
+require_relative "lipwa/capabilities/void"
 require_relative "lipwa/gateways/mpesa"
+require_relative "lipwa/gateways/coop_bank"
 
+require_relative "lipwa/gateways/jenga"
+require_relative "lipwa/gateways/pesapal"
+require_relative "lipwa/gateways/flutterwave"
+require_relative "lipwa/gateways/paystack"
 # Unified payment gateway abstraction for African payment providers.
 module Lipwa
+  def self.context(&block)
+    Context.new(&block)
+  end
+
   def self.gateway(name)
     Gateways[name]
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lipwa
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Paul Oguda
@@ -147,42 +147,70 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/lipwa.rb
 - lib/lipwa/auth_strategies.rb
+- lib/lipwa/auth_strategies/api_key.rb
 - lib/lipwa/auth_strategies/base.rb
 - lib/lipwa/auth_strategies/bearer_token.rb
+- lib/lipwa/auth_strategies/jenga.rb
 - lib/lipwa/auth_strategies/none.rb
+- lib/lipwa/capabilities/authorize.rb
+- lib/lipwa/capabilities/bank_transfer.rb
 - lib/lipwa/capabilities/c2b.rb
+- lib/lipwa/capabilities/capture.rb
 - lib/lipwa/capabilities/disbursement.rb
+- lib/lipwa/capabilities/lightning_invoice.rb
+- lib/lipwa/capabilities/lightning_payment.rb
+- lib/lipwa/capabilities/purchase.rb
 - lib/lipwa/capabilities/refund.rb
 - lib/lipwa/capabilities/status_query.rb
 - lib/lipwa/capabilities/stk_push.rb
+- lib/lipwa/capabilities/void.rb
 - lib/lipwa/capability.rb
 - lib/lipwa/configuration.rb
+- lib/lipwa/configuration_snapshot.rb
+- lib/lipwa/context.rb
+- lib/lipwa/contracts/bank_transfer_contract.rb
 - lib/lipwa/contracts/c2b_register_urls_contract.rb
 - lib/lipwa/contracts/c2b_simulate_contract.rb
+- lib/lipwa/contracts/card_payment_contract.rb
+- lib/lipwa/contracts/card_transaction_contract.rb
 - lib/lipwa/contracts/disbursement_contract.rb
+- lib/lipwa/contracts/lightning_invoice_check_contract.rb
+- lib/lipwa/contracts/lightning_invoice_contract.rb
+- lib/lipwa/contracts/lightning_payment_check_contract.rb
+- lib/lipwa/contracts/lightning_payment_contract.rb
 - lib/lipwa/contracts/refund_contract.rb
 - lib/lipwa/contracts/status_query_contract.rb
 - lib/lipwa/contracts/stk_push_contract.rb
 - lib/lipwa/errors.rb
 - lib/lipwa/gateway.rb
 - lib/lipwa/gateways.rb
+- lib/lipwa/gateways/coop_bank.rb
+- lib/lipwa/gateways/coop_bank/auth.rb
+- lib/lipwa/gateways/flutterwave.rb
+- lib/lipwa/gateways/jenga.rb
+- lib/lipwa/gateways/jenga/auth.rb
+- lib/lipwa/gateways/lnbits.rb
 - lib/lipwa/gateways/mpesa.rb
 - lib/lipwa/gateways/mpesa/auth.rb
 - lib/lipwa/gateways/mpesa/security_credential.rb
+- lib/lipwa/gateways/paystack.rb
+- lib/lipwa/gateways/pesapal.rb
+- lib/lipwa/gateways/pesapal/auth.rb
 - lib/lipwa/http_adapter.rb
+- lib/lipwa/logging.rb
 - lib/lipwa/money.rb
 - lib/lipwa/response.rb
 - lib/lipwa/types.rb
 - lib/lipwa/version.rb
 - lib/lipwa/webhook.rb
+- lib/lipwa/webhooks/coop_bank.rb
+- lib/lipwa/webhooks/jenga.rb
+- lib/lipwa/webhooks/lnbits.rb
 - lib/lipwa/webhooks/mpesa.rb
-- sig/lipwa.rbs
 homepage: https://github.com/kamalogudah/lipwa
 licenses:
 - MIT

data/CODE_OF_CONDUCT.md

@@ -1,10 +0,0 @@
-# Code of Conduct
-
-"lipwa" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
-
-* Participants will be tolerant of opposing views.
-* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
-* When interpreting the words and actions of others, participants should always assume good intentions.
-* Behaviour which can be reasonably considered harassment will not be tolerated.
-
-If you have any concerns about behaviour within this project, please contact us at ["mcpaul2058@gmail.com"](mailto:"mcpaul2058@gmail.com").

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "minitest/test_task"
-
-Minitest::TestTask.create
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[test rubocop]

data/sig/lipwa.rbs

@@ -1,4 +0,0 @@
-module Lipwa
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end