payment_kit 1.0.0

data/Rakefile

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+# RDoc stopped being a default gem in Ruby 4, so it is not guaranteed to be
+# present. Guard the require: a bundle without it should still run spec and
+# rubocop rather than failing to load the Rakefile at all.
+begin
+  require "rdoc/task"
+  require_relative "lib/payment_kit/version"
+
+  # rake rdoc → doc/, rake rerdoc → rebuild from scratch, rake clobber_rdoc → remove.
+  RDoc::Task.new do |rdoc|
+    rdoc.rdoc_dir = "doc"
+    rdoc.title = "PaymentKit #{PaymentKit::VERSION}"
+    rdoc.main = "README.md"
+
+    # app/ carries the optional Rails webhook controller; the architecture reviews
+    # at the repo root are research notes about other libraries, not API docs.
+    rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt",
+                            "lib/**/*.rb", "app/**/*.rb")
+
+    rdoc.options << "--line-numbers"
+    rdoc.options << "--hyperlink-all"
+    rdoc.options << "--charset=UTF-8"
+  end
+rescue LoadError
+  desc "Generate the API reference (requires the rdoc gem)"
+  task :rdoc do
+    abort 'RDoc is not available. Add `gem "rdoc"` to your Gemfile, then run bundle install.'
+  end
+end
+
+task default: %i[spec rubocop]

data/app/controllers/payment_kit/webhook_controller.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PaymentKit
+  # HTTP entrypoint: verify signature(s) → dedupe → instrument → 200 OK.
+  #
+  # PaymentKit treats 4xx as a permanent failure (no retry) and retries 5xx or
+  # timeouts five times over roughly 27 hours, so failure mapping matters:
+  #
+  # * bad/missing signature      → 401, never retried
+  # * verified but unparseable   → 400, never retried
+  # * subscriber raised          → 500 by default (retried), or 200 when
+  #                                +PaymentKit.error_handler+ is configured
+  #
+  # Endpoints must answer within 30 seconds, so subscribers should enqueue work
+  # rather than perform it inline.
+  class WebhookController < ActionController::Base
+    if respond_to?(:skip_forgery_protection)
+      skip_forgery_protection
+    elsif respond_to?(:protect_from_forgery)
+      skip_before_action :verify_authenticity_token, raise: false
+    end
+
+    # Handles one webhook delivery: verify, deduplicate, dispatch, answer.
+    def event
+      # raw_post (not body.read) so verification still sees the exact bytes
+      # after middleware or param parsing has consumed the request stream.
+      PaymentKit.process_webhook(
+        request.raw_post,
+        request.headers["X-Webhook-Signature"]
+      )
+      head :ok
+    rescue AuthenticationError => e
+      logger&.error("[PaymentKit::WebhookController] #{e.message}")
+      head :unauthorized
+    rescue InvalidRequestError => e
+      logger&.error("[PaymentKit::WebhookController] #{e.message}")
+      head :bad_request
+    rescue StandardError => e
+      raise if PaymentKit.error_handler.nil?
+
+      PaymentKit.error_handler.call(e, request)
+      head :ok
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+PaymentKit::Engine.routes.draw do
+  root to: "webhook#event", via: :post
+end

data/lib/payment_kit/client.rb

@@ -0,0 +1,449 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "securerandom"
+require "uri"
+
+require_relative "resources/customers"
+require_relative "resources/subscriptions"
+require_relative "resources/invoices"
+require_relative "resources/payments"
+require_relative "resources/catalog"
+
+module PaymentKit
+  # HTTP client for the PaymentKit API.
+  #
+  # Authenticates with a Bearer secret key, scopes requests to an account base URL,
+  # encodes JSON bodies, auto-paginates list endpoints, maps RFC 7807 errors, and
+  # retries transient failures with exponential backoff.
+  #
+  # Endpoint methods live in the +PaymentKit::Resources::*+ modules.
+  class Client
+    # Backwards-compatible aliases: applications written against a nested error
+    # namespace (+PaymentKit::Client::AuthenticationError+) keep working.
+    Error = PaymentKit::Error
+    AuthenticationError = PaymentKit::AuthenticationError
+    PermissionError = PaymentKit::PermissionError
+    SignatureVerificationError = PaymentKit::SignatureVerificationError
+    InvalidRequestError = PaymentKit::InvalidRequestError
+    ConflictError = PaymentKit::ConflictError
+    CardError = PaymentKit::CardError
+    RateLimitError = PaymentKit::RateLimitError
+    APIError = PaymentKit::APIError
+    ApiError = PaymentKit::APIError
+    APIConnectionError = PaymentKit::APIConnectionError
+    ConnectionError = PaymentKit::APIConnectionError
+
+    # Redirects followed before giving up.
+    MAX_REDIRECTS = 3
+    # Statuses that are always safe to replay. 409 is deliberately excluded:
+    # PaymentKit marks only *some* conflicts retryable via +error_code+.
+    RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+    # 409 +error_code+ values documented as retry-safe with no side effects.
+    RETRYABLE_ERROR_CODES = %w[invoice_locked].freeze
+    # Redirects PaymentKit uses for path canonicalization; both preserve the verb.
+    REDIRECT_STATUSES = [307, 308].freeze
+    # Methods that receive an auto-generated Idempotency-Key when the caller
+    # does not supply one, so internal retries cannot double-charge.
+    IDEMPOTENT_METHODS = %i[post put patch].freeze
+    # Ceiling for a server-supplied Retry-After, so a hostile or mistaken header
+    # cannot park a request for hours.
+    MAX_RETRY_DELAY = 32
+    # Characters of raw response body appended to a 4xx message for context.
+    RAW_BODY_LIMIT = 800
+
+    include Resources::Customers
+    include Resources::Subscriptions
+    include Resources::Invoices
+    include Resources::Payments
+    include Resources::Catalog
+
+    # Builds a client. Every keyword falls back to PaymentKit.configuration (or
+    # to +configuration:+ when given), so a bare <tt>Client.new</tt> uses the
+    # global settings.
+    #
+    # Raises AuthenticationError when +secret_key+ is missing or contains
+    # whitespace, and InvalidRequestError when neither +base_url+ nor
+    # +account_id+ is configured.
+    def initialize(secret_key: nil, account_id: nil, base_url: nil, api_host: nil,
+                   open_timeout: nil, read_timeout: nil, max_retries: nil,
+                   signing_secret: nil, configuration: nil)
+      base = configuration || PaymentKit.configuration
+      @config = base.merge(
+        secret_key: secret_key,
+        account_id: account_id,
+        base_url: base_url,
+        api_host: api_host,
+        open_timeout: open_timeout,
+        read_timeout: read_timeout,
+        max_retries: max_retries,
+        signing_secret: signing_secret
+      )
+
+      raise AuthenticationError, "PaymentKit secret_key is not configured" if blank?(@config.secret_key)
+      if @config.secret_key.to_s.match?(/\s/)
+        raise AuthenticationError, "PaymentKit secret_key cannot contain whitespace"
+      end
+
+      @base_url = @config.resolved_base_url
+    end
+
+    # Resolved base URL every account-scoped request is sent to.
+    attr_reader :base_url
+
+    # --- Webhooks -----------------------------------------------------------
+    # Verifies HMAC-SHA256 over the raw payload (`X-Webhook-Signature: sha256=<hex>`).
+    # Delegates to +PaymentKit::Webhook.construct_event+ (supports one or many secrets).
+    def verify_webhook(payload, signature, secret: nil)
+      secrets = secret.nil? ? @config.signing_secrets : secret
+      Webhook.construct_event(payload, signature, secrets)
+    end
+
+    # --- Escape hatch -------------------------------------------------------
+    # Calls any PaymentKit endpoint, including ones this SDK does not wrap yet
+    # (payment links, refunds, webhook endpoint management, …). Goes through the
+    # same auth, retry, idempotency and error mapping as the typed methods.
+    #
+    #   client.raw_request(:get, "/payment-links", params: { limit: 10 })
+    #   client.raw_request(:post, "/webhook-endpoints/we_1/roll-secret",
+    #                      params: { ttl_seconds: 3600 })
+    #
+    # Endpoints that are not account-scoped (for example the customer portal
+    # surface at +/billing-portal/token/...+) opt out of the account prefix:
+    #
+    #   client.raw_request(:get, "/billing-portal/token/#{token}/payment-methods",
+    #                      account_scoped: false)
+    def raw_request(method, path, params: nil, idempotency_key: nil, account_scoped: true)
+      query = method == :get ? params : nil
+      body = method == :get ? nil : params
+      request(
+        method, path,
+        query: query, body: body,
+        idempotency_key: idempotency_key, account_scoped: account_scoped
+      )
+    end
+
+    private
+
+    def get(path, params = {}) = request(:get, path, query: params)
+
+    # Write helpers accept the body either positionally (+post(path, {a: 1})+) or
+    # as loose keywords (+post(path, nil, a: 1)+), so resource methods keep their
+    # original brace-less call style while also taking +idempotency_key:+.
+    def post(path, params = nil, idempotency_key: nil, **rest)
+      request(:post, path, body: params || rest, idempotency_key: idempotency_key)
+    end
+
+    def put(path, params = nil, idempotency_key: nil, **rest)
+      request(:put, path, body: params || rest, idempotency_key: idempotency_key)
+    end
+
+    def patch(path, params = nil, idempotency_key: nil, **rest)
+      request(:patch, path, body: params || rest, idempotency_key: idempotency_key)
+    end
+
+    def delete(path, idempotency_key: nil)
+      request(:delete, path, idempotency_key: idempotency_key)
+    end
+
+    def list(path, params)
+      params = stringify_keys(params || {})
+      results = []
+      offset = 0
+      limit = params["limit"] || 100
+
+      loop do
+        query = params.merge("limit" => limit, "offset" => offset)
+        page = request(:get, path, query: query)
+        data = Array(page["items"])
+        results.concat(data)
+        break unless page["has_more"] && !data.empty?
+
+        offset += data.size
+      end
+
+      results
+    end
+
+    # Wraps the request/retry loop with instrumentation. +request_end+ fires on
+    # both the success and failure paths, once per logical call.
+    def request(method, path, query: nil, body: nil, idempotency_key: nil, account_scoped: true)
+      stats = { status: nil, retries: 0, request_id: nil }
+      started = monotonic_time
+      notify_request_begin(method, path)
+
+      perform(
+        method, path,
+        query: query, body: body, idempotency_key: idempotency_key,
+        account_scoped: account_scoped, stats: stats
+      )
+    ensure
+      notify_request_end(method, path, stats, monotonic_time - started)
+    end
+
+    def perform(method, path, query:, body:, idempotency_key:, account_scoped:, stats:, attempt: 0)
+      uri = build_uri(path, query, account_scoped)
+      idempotency_key ||= SecureRandom.uuid if idempotent_write?(method, body)
+      response = send_with_redirects(method, uri, body, idempotency_key)
+      status = response.code.to_i
+      stats[:status] = status
+      stats[:request_id] = header_request_id(response)
+      return parse_body(response.body) if status.between?(200, 299)
+
+      if retryable_response?(status, response.body) && attempt < @config.max_retries
+        stats[:retries] = attempt + 1
+        sleep(retry_delay(attempt, response))
+        return perform(
+          method, path,
+          query: query, body: body, idempotency_key: idempotency_key,
+          account_scoped: account_scoped, stats: stats, attempt: attempt + 1
+        )
+      end
+
+      raise error_for(status, response.body, response)
+    rescue Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError, IOError => e
+      raise APIConnectionError, "PaymentKit connection error: #{e.message}"
+    end
+
+    def build_uri(path, query, account_scoped)
+      base = account_scoped ? @base_url : @config.unscoped_base_url
+      uri = URI("#{base}#{path}")
+      return uri if blank?(query)
+
+      flat = flatten_params(stringify_keys(query))
+      uri.query = URI.encode_www_form(flat) unless flat.empty?
+      uri
+    end
+
+    def monotonic_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def notify_request_begin(method, path)
+      return unless Instrumentation.subscribers?(:request_begin)
+
+      Instrumentation.notify(
+        :request_begin,
+        Instrumentation::RequestBeginEvent.new(method: method, path: path)
+      )
+    end
+
+    def notify_request_end(method, path, stats, duration)
+      return unless Instrumentation.subscribers?(:request_end)
+
+      Instrumentation.notify(
+        :request_end,
+        Instrumentation::RequestEvent.new(
+          method: method, path: path, status: stats[:status], duration: duration,
+          num_retries: stats[:retries], request_id: stats[:request_id]
+        )
+      )
+    end
+
+    # A 409 is only replayed when PaymentKit flags it as retryable (or reports a
+    # known side-effect-free +error_code+); other conflicts are terminal.
+    def retryable_response?(status, raw)
+      return true if RETRYABLE_STATUSES.include?(status)
+      return false unless status == 409
+
+      problem = parse_error_json(raw)
+      problem["retryable"] == true || RETRYABLE_ERROR_CODES.include?(problem["error_code"].to_s)
+    end
+
+    def send_with_redirects(method, uri, body, idempotency_key, redirects = 0)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.read_timeout
+
+      req = build_request(method, uri, body, idempotency_key)
+      response = transport(http, req)
+
+      if REDIRECT_STATUSES.include?(response.code.to_i) &&
+         present?(response["location"]) &&
+         redirects < MAX_REDIRECTS
+        target = URI.join(uri, response["location"])
+        target.query = uri.query if target.query.nil?
+        return send_with_redirects(method, target, body, idempotency_key, redirects + 1)
+      end
+
+      response
+    end
+
+    # Seam for specs: stub this instead of making live HTTP calls.
+    def transport(http, request)
+      http.request(request)
+    end
+
+    def build_request(method, uri, body, idempotency_key)
+      klass = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        patch: Net::HTTP::Patch,
+        delete: Net::HTTP::Delete
+      }.fetch(method)
+
+      req = klass.new(uri.request_uri)
+      req["Authorization"] = "Bearer #{@config.secret_key}"
+      req["Accept"] = "application/json"
+      req["Idempotency-Key"] = idempotency_key if idempotency_key
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(stringify_keys(body))
+      end
+      req
+    end
+
+    def idempotent_write?(method, body)
+      IDEMPOTENT_METHODS.include?(method) && !body.nil?
+    end
+
+    # Honours a numeric +Retry-After+ when the API sends one (typically on 429),
+    # otherwise falls back to exponential backoff.
+    def retry_delay(attempt, response = nil)
+      after = retry_after_seconds(response)
+      return [after, MAX_RETRY_DELAY].min if after
+
+      0.5 * (2**attempt)
+    end
+
+    def retry_after_seconds(response)
+      raw = response && response["retry-after"]
+      return if blank?(raw)
+
+      seconds = Float(raw.to_s, exception: false)
+      seconds if seconds&.positive?
+    end
+
+    def header_request_id(response)
+      response["request-id"] || response["x-request-id"]
+    end
+
+    def parse_body(raw)
+      return {} if blank?(raw)
+
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise APIError.new(
+        "PaymentKit returned a success status with an unparseable body: #{e.message}",
+        body: raw
+      )
+    end
+
+    def error_for(status, raw, response = nil)
+      parsed = parse_error_json(raw)
+      message = error_message(parsed, status, raw)
+      attrs = {
+        status: status,
+        body: raw,
+        request_id: parsed["request_id"] || (response && header_request_id(response)),
+        error_code: parsed["error_code"],
+        retryable: parsed["retryable"]
+      }
+
+      case status
+      when 401 then AuthenticationError.new(message, **attrs)
+      when 403 then PermissionError.new(message, **attrs)
+      when 400, 404, 422 then InvalidRequestError.new(with_raw_body(message, raw), **attrs)
+      when 402 then CardError.new(message, **attrs)
+      when 409 then ConflictError.new(message, **attrs)
+      when 429 then RateLimitError.new(message, **attrs)
+      else APIError.new(message, **attrs)
+      end
+    end
+
+    def error_message(parsed, status, raw)
+      detail = parsed["detail"]
+      detail = format_validation_detail(detail) if detail.is_a?(Array)
+      message = detail
+      message = parsed["title"] if blank?(message)
+      message = dig_error_message(parsed) if blank?(message)
+      message = parsed["message"] if blank?(message)
+      message = raw if blank?(message)
+      message = "PaymentKit API error (HTTP #{status})" if blank?(message)
+      message
+    end
+
+    def parse_error_json(raw)
+      parsed = JSON.parse(raw.to_s)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def dig_error_message(parsed)
+      error = parsed["error"]
+      return unless error.is_a?(Hash)
+
+      error["message"]
+    end
+
+    def with_raw_body(message, raw)
+      body = raw.to_s.strip
+      return message if body.empty? || message.to_s.include?(body)
+
+      "#{message} — #{truncate(body, RAW_BODY_LIMIT)}"
+    end
+
+    def format_validation_detail(detail)
+      Array(detail).filter_map do |entry|
+        next entry unless entry.is_a?(Hash)
+
+        location = Array(entry["loc"]).join(".")
+        parts = [location.empty? ? nil : location, entry["msg"]].compact
+        text = parts.join(": ")
+        text.empty? ? nil : text
+      end.join("; ")
+    end
+
+    def flatten_params(params, prefix = nil)
+      return [] if blank?(params)
+
+      params.flat_map do |key, value|
+        composed = prefix ? "#{prefix}[#{key}]" : key.to_s
+        case value
+        when Hash
+          flatten_params(stringify_keys(value), composed)
+        when Array
+          value.flat_map do |item|
+            if item.is_a?(Hash) || item.is_a?(Array)
+              flatten_params(item.is_a?(Hash) ? stringify_keys(item) : item, "#{composed}[]")
+            else
+              [["#{composed}[]", item]]
+            end
+          end
+        else
+          [[composed, value]]
+        end
+      end
+    end
+
+    def stringify_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested), memo|
+          memo[key.to_s] = stringify_keys(nested)
+        end
+      when Array
+        value.map { |item| stringify_keys(item) }
+      else
+        value
+      end
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+        (value.is_a?(String) && value.strip.empty?)
+    end
+
+    def present?(value)
+      !blank?(value)
+    end
+
+    def truncate(string, limit)
+      return string if string.length <= limit
+
+      "#{string[0, limit]}..."
+    end
+  end
+end

data/lib/payment_kit/configuration.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module PaymentKit
+  # Settings shared between global configuration and per-client overrides.
+  class Configuration
+    # API host root, without the account segment.
+    DEFAULT_API_HOST = "https://app.paymentkit.com/api"
+    # TCP connect timeout, in seconds.
+    DEFAULT_OPEN_TIMEOUT = 10
+    # Response read timeout, in seconds.
+    DEFAULT_READ_TIMEOUT = 30
+    # Attempts made after a transient failure before giving up.
+    DEFAULT_MAX_RETRIES = 2
+
+    # Server secret token (+st_prod_...+). Never expose this in a browser.
+    attr_accessor :secret_key
+
+    # Account external id (+acc_prod_...+), used as the API path prefix.
+    attr_accessor :account_id
+
+    # API host root; defaults to DEFAULT_API_HOST.
+    attr_accessor :api_host
+
+    # Full base URL override. When set, +account_id+ is not appended.
+    attr_accessor :base_url
+
+    # TCP connect timeout, in seconds.
+    attr_accessor :open_timeout
+
+    # Response read timeout, in seconds.
+    attr_accessor :read_timeout
+
+    # Attempts made after a transient failure before giving up.
+    attr_accessor :max_retries
+
+    # Webhook signing secrets (+whsec_...+), tried in order during rotation.
+    attr_accessor :signing_secrets
+
+    # Builds a configuration with the DEFAULT_* values and no credentials.
+    def initialize
+      @api_host = DEFAULT_API_HOST
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @read_timeout = DEFAULT_READ_TIMEOUT
+      @max_retries = DEFAULT_MAX_RETRIES
+      @signing_secrets = nil
+    end
+
+    def initialize_copy(other) # :nodoc:
+      super
+      @secret_key = other.secret_key
+      @account_id = other.account_id
+      @api_host = other.api_host
+      @base_url = other.base_url
+      @open_timeout = other.open_timeout
+      @read_timeout = other.read_timeout
+      @max_retries = other.max_retries
+      @signing_secrets = other.signing_secrets&.dup
+    end
+
+    # Singular accessor for the first signing secret.
+    def signing_secret
+      Array(signing_secrets).compact.first
+    end
+
+    # Assigns a single signing secret, replacing any already configured.
+    def signing_secret=(value)
+      @signing_secrets = value.nil? ? nil : Array(value)
+    end
+
+    # Merge keyword overrides into a duplicate configuration.
+    def merge(**overrides)
+      dup.tap do |config|
+        overrides.each do |key, value|
+          next if value.nil?
+
+          writer = "#{key}="
+          raise ArgumentError, "Unknown configuration option: #{key}" unless config.respond_to?(writer)
+
+          config.public_send(writer, value)
+        end
+      end
+    end
+
+    # Base URL every account-scoped request is sent to: an explicit +base_url+
+    # when set, otherwise <tt>{api_host}/{account_id}</tt>.
+    #
+    # Raises InvalidRequestError when neither is configured.
+    def resolved_base_url
+      return base_url.to_s.chomp("/") if present?(base_url)
+
+      host = (api_host || DEFAULT_API_HOST).to_s.chomp("/")
+      raise InvalidRequestError, "PaymentKit account_id is not configured" if blank?(account_id)
+
+      "#{host}/#{account_id}"
+    end
+
+    # Base for endpoints that are not account-scoped (e.g. the customer portal
+    # surface). An explicit +base_url+ wins, since the account segment cannot be
+    # reliably stripped back off it.
+    def unscoped_base_url
+      return base_url.to_s.chomp("/") if present?(base_url)
+
+      (api_host || DEFAULT_API_HOST).to_s.chomp("/")
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+        (value.is_a?(String) && value.strip.empty?)
+    end
+
+    def present?(value)
+      !blank?(value)
+    end
+  end
+end

data/lib/payment_kit/engine.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module PaymentKit
+  # Isolated Rails Engine that exposes POST / for webhook delivery.
+  #
+  # Loaded only when Rails is present (soft coupling).
+  class Engine < ::Rails::Engine
+    isolate_namespace PaymentKit
+  end
+end