payment_kit 1.0.0

data/lib/payment_kit/webhook.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module PaymentKit
+  # Webhook signature verification and event construction (Rails-free PORO).
+  #
+  # PaymentKit delivers +X-Webhook-Signature: sha256=<hex>+ over the raw body.
+  # Multiple signing secrets are tried in order, which is what the +roll-secret+
+  # grace period requires: during rotation both the old and new secret are live.
+  module Webhook
+    module_function
+
+    # Verifies +payload+ against +signature+ using one or more secrets and returns
+    # the parsed JSON event as a Hash.
+    #
+    # +payload+::   raw request body String, never a re-serialised version
+    # +signature+:: +X-Webhook-Signature+ header value
+    # +secrets+::   one signing secret String, or an Array of them
+    #
+    # Raises AuthenticationError when no signing secret is configured,
+    # SignatureVerificationError when the signature is missing or does not
+    # verify, and InvalidRequestError when the verified payload is not JSON.
+    def construct_event(payload, signature, secrets)
+      secret_list = Array(secrets).flatten.compact.reject { |value| blank?(value) }
+      raise AuthenticationError, "PaymentKit signing_secret is not configured" if secret_list.empty?
+
+      raise SignatureVerificationError, "PaymentKit webhook signature is missing" if blank?(signature)
+
+      verified = secret_list.any? { |secret| signature_valid?(payload, signature, secret) }
+      raise SignatureVerificationError, "PaymentKit webhook signature verification failed" unless verified
+
+      parse_payload(payload)
+    end
+
+    def signature_valid?(payload, signature, secret) # :nodoc:
+      received = signature.to_s.sub(/\Asha256=/, "")
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, payload.to_s)
+      secure_compare(expected, received)
+    end
+
+    # Parsing happens only after a secret verified the payload, so a malformed
+    # body is reported as a bad request rather than a signature failure.
+    def parse_payload(payload)
+      JSON.parse(payload.to_s)
+    rescue JSON::ParserError => e
+      raise InvalidRequestError, "PaymentKit webhook payload is not valid JSON: #{e.message}"
+    end
+
+    def blank?(value) # :nodoc:
+      value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+        (value.is_a?(String) && value.strip.empty?)
+    end
+
+    def secure_compare(left, right) # :nodoc:
+      return false unless left.bytesize == right.bytesize
+
+      OpenSSL.fixed_length_secure_compare(left, right)
+    end
+
+    private_class_method :signature_valid?, :parse_payload, :blank?, :secure_compare
+  end
+end

data/lib/payment_kit.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/notifications"
+
+require_relative "payment_kit/version"
+require_relative "payment_kit/errors"
+require_relative "payment_kit/configuration"
+require_relative "payment_kit/instrumentation"
+require_relative "payment_kit/namespace"
+require_relative "payment_kit/notification_adapter"
+require_relative "payment_kit/webhook"
+require_relative "payment_kit/client"
+
+# Ruby HTTP client and webhook event bus for the PaymentKit REST API.
+#
+# HTTP API access goes through +PaymentKit::Client+. Inbound webhooks are
+# verified and then fanned out via +ActiveSupport::Notifications+
+# (+subscribe+ / +instrument+ / +all+).
+module PaymentKit
+  class << self
+    # Wraps each subscriber so it receives a single event argument.
+    # Defaults to NotificationAdapter.
+    attr_accessor :adapter
+
+    # Pub/sub backend. Defaults to +ActiveSupport::Notifications+; any object
+    # answering +instrument(name, payload)+ and +subscribe(pattern, callable)+ works.
+    attr_accessor :backend
+
+    # Namespace prefixing instrumented event names. Defaults to
+    # <tt>Namespace.new("payment_kit.")</tt>.
+    attr_accessor :namespace
+
+    # Callable run before dispatch. Return the event to continue, +nil+ to drop it.
+    attr_accessor :event_filter
+
+    # Callable run after verification, before dispatch — the deduplication hook.
+    # Return the event to continue, +nil+ to drop a redelivery.
+    attr_accessor :event_retriever
+
+    # Callable <tt>(exception, request)</tt> used by WebhookController to report a
+    # failed delivery and answer +200+ instead of +500+.
+    attr_accessor :error_handler
+
+    # Callable <tt>(exception, event)</tt> that isolates a failing subscriber, so
+    # one raising handler does not fail the whole delivery.
+    attr_accessor :subscriber_error_handler
+
+    # Global configuration object, created on first use.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Two forms, chosen by block arity:
+    #
+    #   PaymentKit.configure { |config| config.secret_key = "st_..." }  # settings
+    #   PaymentKit.configure { subscribe("invoice.paid") { |e| ... } }  # subscriber DSL
+    #
+    # The arity-0 form runs against the module itself, so subscriptions can be
+    # registered without repeating the +PaymentKit.+ receiver.
+    def configure(&block)
+      raise ArgumentError, "PaymentKit.configure requires a block" if block.nil?
+
+      block.arity.zero? ? instance_eval(&block) : yield(configuration)
+      configuration
+    end
+
+    # Restores configuration and the event-bus hooks to their defaults.
+    # Intended for test suites.
+    def reset_configuration!
+      @configuration = Configuration.new
+      self.event_filter = DEFAULT_EVENT_FILTER
+      self.event_retriever = DEFAULT_EVENT_RETRIEVER
+      self.error_handler = nil
+      self.subscriber_error_handler = nil
+      configuration
+    end
+
+    # --- Signing secrets ----------------------------------------------------
+
+    # First configured signing secret.
+    def signing_secret
+      configuration.signing_secret
+    end
+
+    # Assigns a single signing secret, replacing any already configured.
+    def signing_secret=(value)
+      configuration.signing_secret = value
+    end
+
+    # All configured signing secrets, as an Array. During a +roll-secret+ grace
+    # period both the old and new secret are live and are tried in order.
+    def signing_secrets
+      Array(configuration.signing_secrets).compact
+    end
+
+    # Assigns the full list of signing secrets.
+    def signing_secrets=(value)
+      configuration.signing_secrets = value.nil? ? nil : Array(value)
+    end
+
+    # --- Pub/Sub ------------------------------------------------------------
+
+    # Subscribe to an event type or type prefix (e.g. +"invoice.paid"+, +"invoice."+).
+    def subscribe(name, callable = nil, &block)
+      handler = callable || block
+      raise ArgumentError, "subscriber callable or block required" if handler.nil?
+
+      backend.subscribe(namespace.to_regexp(name), adapter.call(isolate(handler)))
+    end
+
+    # Subscribe to every namespaced PaymentKit event.
+    def all(callable = nil, &)
+      subscribe(nil, callable, &)
+    end
+
+    # Run +event_filter+, then notify subscribers under +payment_kit.<type>+.
+    # Returns the (possibly filtered) event, or +nil+ when the filter drops it.
+    def instrument(event)
+      filtered = event_filter.call(event)
+      return if filtered.nil?
+
+      type = event_type(filtered)
+      raise InvalidRequestError, "PaymentKit event is missing a type" if type.empty?
+
+      backend.instrument(namespace.call(type), filtered)
+      filtered
+    end
+
+    # Verify webhook signature(s), run the retriever, instrument the event.
+    #
+    # Returns the dispatched event, or +nil+ when +event_retriever+ dropped it
+    # (for example a duplicate delivery).
+    def process_webhook(payload, signature, secrets: nil)
+      event = Webhook.construct_event(payload, signature, secrets || signing_secrets)
+      event = event_retriever.call(event)
+      return if event.nil?
+
+      instrument(event)
+      event
+    end
+
+    # Whether any subscriber is currently listening for +name+.
+    def listening?(name)
+      notifier = backend.notifier
+      return false unless notifier.respond_to?(:listening?)
+
+      notifier.listening?(namespace.call(name))
+    end
+
+    private
+
+    # Opt-in per-subscriber failure isolation.
+    #
+    # ActiveSupport runs the remaining subscribers even when one raises, but it
+    # then re-raises (or aggregates into +InstrumentationSubscriberError+), so the
+    # webhook request fails and PaymentKit redelivers the whole event — re-running
+    # the subscribers that already succeeded. Setting a +subscriber_error_handler+
+    # reports the failure instead and lets the delivery be acknowledged.
+    #
+    # Read at dispatch time, so it can be configured after subscribing.
+    def isolate(handler)
+      lambda do |event|
+        handler.call(event)
+      rescue StandardError => e
+        raise if subscriber_error_handler.nil?
+
+        subscriber_error_handler.call(e, event)
+      end
+    end
+
+    def event_type(event)
+      if event.respond_to?(:type) && !event.is_a?(Hash)
+        event.type
+      elsif event.is_a?(Hash)
+        event["type"] || event[:type]
+      end.to_s
+    end
+  end
+
+  # Identity filter: dispatches every event. Replace via +event_filter=+.
+  DEFAULT_EVENT_FILTER = ->(event) { event }
+
+  # Runs after signature verification and before dispatch. Return the event to
+  # continue, or +nil+ to drop it. PaymentKit redelivers on retry, so hosts
+  # should deduplicate here on the event id — the same value PaymentKit sends in
+  # the +X-Webhook-Event-Id+ header:
+  #
+  #   PaymentKit.event_retriever = lambda do |event|
+  #     key = "payment_kit:webhook:#{event["id"]}"
+  #     Sidekiq.redis { |r| r.set(key, "1", nx: true, ex: 3 * 24 * 60 * 60) } ? event : nil
+  #   end
+  DEFAULT_EVENT_RETRIEVER = ->(event) { event }
+
+  self.adapter = NotificationAdapter
+  self.backend = ActiveSupport::Notifications
+  self.namespace = Namespace.new("payment_kit.")
+  self.event_filter = DEFAULT_EVENT_FILTER
+  self.event_retriever = DEFAULT_EVENT_RETRIEVER
+  self.error_handler = nil
+  self.subscriber_error_handler = nil
+end
+
+require_relative "payment_kit/engine" if defined?(Rails::Engine)

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: payment_kit
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Muhammad Asim
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: PaymentKit is a Ruby SDK for authenticating to and calling the PaymentKit
+  API.
+email:
+- mughalma096@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/payment_kit/webhook_controller.rb
+- config/routes.rb
+- lib/payment_kit.rb
+- lib/payment_kit/client.rb
+- lib/payment_kit/configuration.rb
+- lib/payment_kit/engine.rb
+- lib/payment_kit/errors.rb
+- lib/payment_kit/instrumentation.rb
+- lib/payment_kit/namespace.rb
+- lib/payment_kit/notification_adapter.rb
+- lib/payment_kit/resources/catalog.rb
+- lib/payment_kit/resources/customers.rb
+- lib/payment_kit/resources/invoices.rb
+- lib/payment_kit/resources/payments.rb
+- lib/payment_kit/resources/subscriptions.rb
+- lib/payment_kit/version.rb
+- lib/payment_kit/webhook.rb
+homepage: https://docs.paymentkit.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://docs.paymentkit.com
+  source_code_uri: https://github.com/mughalma096/payment_kit
+  changelog_uri: https://github.com/mughalma096/payment_kit/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options:
+- "--main"
+- README.md
+- "--title"
+- PaymentKit 1.0.0
+- "--line-numbers"
+- "--hyperlink-all"
+- "--charset=UTF-8"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.17
+specification_version: 4
+summary: Ruby HTTP client for the PaymentKit REST API.
+test_files: []