lavenda-pay-ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 574e87e7c3cdf2f4a985cc4269a4691d929153f6e515e304411595b061e94a7a
+  data.tar.gz: 4cd0279828335208b8a5582c144d9ceb88c5b67ca05f32f66dc842e86d8a1f07
+SHA512:
+  metadata.gz: 23c4df6684ff61b6462c940da2a61c4dbb265ea44bceffa5d7d86e29d4d0b3a4e4689f73b0a22f6496ad7fb072e005285cab609546342e85926329c7551a1cc8
+  data.tar.gz: a266e6e3e0e4b556af750e0650c954a97496c3bf656c42ebf6062f86e7d6a690ef40b929f45a21f0fbef41fca13b41033a896cf65d6d74581762982d730d411f

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: customers, orders and webhook handling extracted from the
+  Catavento and Lavenda Store adapters.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 La Venda Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# Lavenda Pay Ruby
+
+Ruby client for the [Lavenda Pay](https://github.com/LaVendaSoftware/pay-ruby) payments API.
+Framework-agnostic (no Rails/ActiveSupport dependency): create customers and orders, and verify/parse webhooks.
+
+## Installation
+
+```ruby
+gem "lavenda-pay-ruby", github: "LaVendaSoftware/pay-ruby"
+```
+
+## Configuration
+
+```ruby
+# config/initializers/lavenda_pay.rb
+LavendaPay.configure do |config|
+  config.base_url = ENV.fetch("LAVENDA_PAY_BASE_URL", Rails.application.credentials.dig(:lavenda_pay, :base_url))
+  config.api_token = ENV.fetch("LAVENDA_PAY_API_TOKEN", Rails.application.credentials.dig(:lavenda_pay, :api_token))
+  config.webhook_secret = ENV.fetch("LAVENDA_PAY_WEBHOOK_SECRET", Rails.application.credentials.dig(:lavenda_pay, :webhook_secret))
+end
+```
+
+`base_url` is the root of the Lavenda Pay installation, without the `/api` suffix.
+
+Outside Rails, set the values directly. Anything left unset falls back to the `LAVENDA_PAY_BASE_URL`,
+`LAVENDA_PAY_API_TOKEN` and `LAVENDA_PAY_WEBHOOK_SECRET` environment variables.
+
+Every operation is a class with `.call` that uses this global configuration. For several accounts, build a client and
+pass it to the operation:
+
+```ruby
+client = LavendaPay::Client.new(base_url: "...", api_token: "...")
+LavendaPay::Orders::Find.new(client:).call("order_...")
+```
+
+## Customers
+
+```ruby
+customer = LavendaPay::Customers::Create.call(
+  full_name: "Pedro Henrique", user_email: "pedro@example.com",
+  document_type: "cpf", document_number: "71415355436",
+  dial_code: "55", phone_number: "(49) 98726-1668", eid: "TUTOR-1"
+)
+customer.pid # => "cus_..."
+
+# Only `user_email` and `document_number` are supported filters (the API ignores
+# anything else and would return every customer); returns nil when none match.
+LavendaPay::Customers::FindBy.call(document_number: "71415355436") ||
+  LavendaPay::Customers::FindBy.call(user_email: "pedro@example.com")
+
+LavendaPay::Customers::Find.call("cus_...")
+LavendaPay::Customers::List.call(user_email: "pedro@example.com", page: 1)
+```
+
+## Orders
+
+```ruby
+order = LavendaPay::Orders::Create.call(
+  customer_pid: customer.pid,
+  payment_method_kinds: ["pix", "credit_card"],
+  description: "Material didático",
+  eid: "ORD-0123",
+  frequency: "once",
+  currency: "brl",
+  items_attributes: [{product_title: "Material didático", quantity: 1, unit_price: 450.0}]
+)
+order.pid    # => "order_..."
+order.status # => "draft"
+
+LavendaPay::Orders::Find.call(order.pid)
+```
+
+## Errors
+
+Non-2xx responses raise a `LavendaPay::ApiError` subclass exposing `status`, `body` and `errors`:
+`BadRequestError` (400), `AuthenticationError` (401/403), `NotFoundError` (404), `UnprocessableError` (422),
+`ServerError` (5xx). Network failures raise `ConnectionError`; missing config raises `ConfigurationError`.
+
+```ruby
+begin
+  LavendaPay::Customers::Create.call(params)
+rescue LavendaPay::UnprocessableError => error
+  error.errors # => {"user_email" => ["is invalid"]}
+end
+```
+
+## Webhooks
+
+Lavenda Pay POSTs JSON to your endpoint with the shared secret in the header exposed as
+`LavendaPay::Webhooks::Signature::HEADER`.
+
+### Rails engine (recommended)
+
+Mount the engine and give it a handler. It verifies the secret, parses the payload and calls your handler with a
+`LavendaPay::Webhooks::Event` for every supported event.
+
+```ruby
+# config/routes.rb
+mount LavendaPay::Engine => "/webhooks/lavenda_pay"
+
+# config/initializers/lavenda_pay.rb
+LavendaPay.configure do |config|
+  # ...base_url, api_token, webhook_secret
+  config.on_event = ->(event) { MyApp::Webhooks::Process.call(event:) } # any callable
+end
+```
+
+Responses: `200` for handled and unsupported events, `401` for a wrong or missing secret, `422` for an invalid payload.
+Exceptions raised by the handler are not rescued, so the request fails with `500` and the sender retries; make the
+handler idempotent (see `event.idempotency_key`). Without `on_event` configured the endpoint raises a
+`ConfigurationError`.
+
+### Your own controller
+
+```ruby
+class Webhooks::LavendaPayController < ActionController::API
+  def create
+    event = LavendaPay::Webhooks::ConstructEvent.call(
+      request.raw_post, request.headers[LavendaPay::Webhooks::Signature::HEADER]
+    )
+
+    return head :ok unless event.supported?
+
+    if event.order?
+      order = Order.find_by!(gateway_order_pid: event.pid)
+      order.update!(status: event.data["status"], paid: event.name == "order_paid")
+    end
+
+    head :ok
+  rescue LavendaPay::InvalidWebhookSignatureError
+    head :unauthorized
+  rescue LavendaPay::InvalidWebhookPayloadError
+    head :unprocessable_entity
+  end
+end
+```
+
+`LavendaPay::Webhooks::VerifySignature.call(secret)` and `LavendaPay::Webhooks::ParseEvent.call(raw_body)` are
+available separately. `event.idempotency_key` (`"order_paid:Order:order_123"`) is stable across redeliveries; use it to de-duplicate.
+Supported events: `order_created`, `order_pending`, `order_partially_paid`, `order_paid`, `order_refund_requested`,
+`order_refunded`, `order_cancelled`, `payment_created`, `payment_processing`, `payment_pending`, `payment_paid`,
+`payment_refused`, `payment_refund_requested`, `payment_refunded`, `payment_partially_refunded`, `payment_canceled`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```

data/app/controllers/lavenda_pay/webhooks_controller.rb

@@ -0,0 +1,29 @@
+module LavendaPay
+  class WebhooksController < ActionController::API
+    def create
+      event = Webhooks::ConstructEvent.call(
+        request.raw_post,
+        request.headers[Webhooks::Signature::HEADER]
+      )
+
+      handle(event) if event.supported?
+
+      head :ok
+    rescue InvalidWebhookSignatureError
+      head :unauthorized
+    rescue InvalidWebhookPayloadError
+      head :unprocessable_entity
+    end
+
+    private
+
+    # Errors raised by the handler are not rescued on purpose: the request
+    # fails with 500 so the sender retries the delivery.
+    def handle(event)
+      handler = LavendaPay.configuration.on_event
+      raise ConfigurationError, "LavendaPay on_event handler is not configured" if handler.nil?
+
+      handler.call(event)
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,3 @@
+LavendaPay::Engine.routes.draw do
+  post "/", to: "webhooks#create"
+end

data/lib/lavenda-pay-ruby.rb

@@ -0,0 +1,2 @@
+# Bundler requires a gem by its name; the code lives under `lavenda_pay`.
+require "lavenda_pay"

data/lib/lavenda_pay/client.rb

@@ -0,0 +1,32 @@
+module LavendaPay
+  # Holds a configuration and the HTTP transport. Pass it to an operation to
+  # talk to a different account than the global one:
+  #
+  #   client = LavendaPay::Client.new(base_url: "...", api_token: "...")
+  #   LavendaPay::Orders::Find.new(client: client).call("order_...")
+  class Client
+    attr_reader :configuration
+
+    # Uses the global configuration unless options override it.
+    def initialize(**options)
+      @configuration = build_configuration(options)
+    end
+
+    def http = @http ||= HTTP.new(configuration)
+
+    private
+
+    def build_configuration(options)
+      return LavendaPay.configuration if options.empty?
+
+      base = LavendaPay.configuration
+      Configuration.new.tap do |config|
+        config.base_url = options.fetch(:base_url, base.base_url)
+        config.api_token = options.fetch(:api_token, base.api_token)
+        config.webhook_secret = options.fetch(:webhook_secret, base.webhook_secret)
+        config.open_timeout = options.fetch(:open_timeout, base.open_timeout)
+        config.read_timeout = options.fetch(:read_timeout, base.read_timeout)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/configuration.rb

@@ -0,0 +1,34 @@
+module LavendaPay
+  class Configuration
+    DEFAULT_TIMEOUT = 30
+
+    attr_writer :base_url, :api_token, :webhook_secret
+    attr_accessor :open_timeout, :read_timeout, :logger
+
+    # Callable receiving a LavendaPay::Webhooks::Event; used by the mounted engine.
+    attr_accessor :on_event
+
+    def initialize
+      @open_timeout = DEFAULT_TIMEOUT
+      @read_timeout = DEFAULT_TIMEOUT
+    end
+
+    # Root URL of the Lavenda Pay installation, without the `/api` suffix.
+    def base_url = @base_url || ENV["LAVENDA_PAY_BASE_URL"]
+
+    def api_token = @api_token || ENV["LAVENDA_PAY_API_TOKEN"]
+
+    def webhook_secret = @webhook_secret || ENV["LAVENDA_PAY_WEBHOOK_SECRET"]
+
+    def validate!
+      raise ConfigurationError, "LavendaPay base_url is not configured (LAVENDA_PAY_BASE_URL)" if blank?(base_url)
+      raise ConfigurationError, "LavendaPay api_token is not configured (LAVENDA_PAY_API_TOKEN)" if blank?(api_token)
+
+      self
+    end
+
+    private
+
+    def blank?(value) = value.nil? || value.to_s.strip.empty?
+  end
+end

data/lib/lavenda_pay/customers/create.rb

@@ -0,0 +1,14 @@
+module LavendaPay
+  module Customers
+    # LavendaPay::Customers::Create.call(
+    #   full_name: "...", user_email: "...", document_type: "cpf",
+    #   document_number: "...", dial_code: "55", phone_number: "...", eid: "..."
+    # ) # => LavendaPay::Customer
+    class Create < Operation
+      def call(params)
+        body = http.post("/v1/customers", body: {customer: params})
+        Customer.new(body["customer"] || body)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/customers/find.rb

@@ -0,0 +1,11 @@
+module LavendaPay
+  module Customers
+    # LavendaPay::Customers::Find.call("cus_...") # => LavendaPay::Customer
+    class Find < Operation
+      def call(pid)
+        body = http.get("/v1/customers/#{escape(pid)}")
+        Customer.new(body["customer"] || body)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/customers/find_by.rb

@@ -0,0 +1,16 @@
+module LavendaPay
+  module Customers
+    # First customer matching the filters, or nil. Returns nil (without hitting
+    # the API) when no supported filter is given.
+    #
+    # LavendaPay::Customers::FindBy.call(document_number: "...")
+    class FindBy < Operation
+      def call(**filters)
+        filters = filters.slice(*FILTER_KEYS).reject { |_, value| value.nil? || value.to_s.strip.empty? }
+        return if filters.empty?
+
+        List.new(client: client).call(**filters).first
+      end
+    end
+  end
+end

data/lib/lavenda_pay/customers/list.rb

@@ -0,0 +1,16 @@
+module LavendaPay
+  module Customers
+    # Query keys the API filters on. Any other key is ignored server-side and
+    # the API would return *every* customer, so we never send them.
+    FILTER_KEYS = %i[user_email document_number].freeze
+
+    # LavendaPay::Customers::List.call(user_email: "...", page: 1)
+    # # => [LavendaPay::Customer, ...]
+    class List < Operation
+      def call(page: nil, **filters)
+        body = http.get("/v1/customers", params: {page:}.merge(filters.slice(*FILTER_KEYS)))
+        Array(body["customers"]).map { |attributes| Customer.new(attributes) }
+      end
+    end
+  end
+end

data/lib/lavenda_pay/engine.rb

@@ -0,0 +1,10 @@
+require "rails/engine"
+
+module LavendaPay
+  # Mount it to get a webhook endpoint without writing a controller:
+  #
+  #   mount LavendaPay::Engine => "/webhooks/lavenda_pay"
+  class Engine < ::Rails::Engine
+    isolate_namespace LavendaPay
+  end
+end

data/lib/lavenda_pay/errors.rb

@@ -0,0 +1,37 @@
+module LavendaPay
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class ConnectionError < Error; end
+
+  # Raised when the API answers with a non-2xx status.
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body.is_a?(Hash) ? body : {}
+      super(message || "Lavenda Pay API responded with #{status}")
+    end
+
+    # Errors as returned by the API (`{"errors" => ...}` or `{"error" => ...}`).
+    def errors
+      [body["errors"], body["error"]].find { |value| value && !value.empty? } || []
+    end
+  end
+
+  class BadRequestError < ApiError; end
+
+  class AuthenticationError < ApiError; end
+
+  class NotFoundError < ApiError; end
+
+  class UnprocessableError < ApiError; end
+
+  class ServerError < ApiError; end
+
+  class InvalidWebhookSignatureError < Error; end
+
+  class InvalidWebhookPayloadError < Error; end
+end

data/lib/lavenda_pay/http.rb

@@ -0,0 +1,95 @@
+require "json"
+require "net/http"
+require "uri"
+
+module LavendaPay
+  # Minimal JSON-over-HTTP transport built on net/http.
+  class HTTP
+    ERROR_CLASSES = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => AuthenticationError,
+      404 => NotFoundError,
+      422 => UnprocessableError
+    }.freeze
+
+    NETWORK_ERRORS = [
+      SocketError, Timeout::Error, EOFError, IOError,
+      Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, OpenSSL::SSL::SSLError
+    ].freeze
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def get(path, params: {})
+      request(Net::HTTP::Get, path, params:)
+    end
+
+    def post(path, body: nil)
+      request(Net::HTTP::Post, path, body:)
+    end
+
+    private
+
+    attr_reader :configuration
+
+    def request(verb_class, path, params: {}, body: nil)
+      configuration.validate!
+
+      uri = build_uri(path, params)
+      req = verb_class.new(uri, headers)
+      req.body = JSON.generate(body) unless body.nil?
+
+      response = perform(uri, req)
+      handle(response)
+    end
+
+    def perform(uri, req)
+      Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: configuration.open_timeout,
+        read_timeout: configuration.read_timeout
+      ) { |http| http.request(req) }
+    rescue *NETWORK_ERRORS => error
+      raise ConnectionError, "#{error.class}: #{error.message}"
+    end
+
+    def handle(response)
+      status = response.code.to_i
+      parsed = parse(response.body)
+
+      return parsed if (200..299).cover?(status)
+
+      raise error_class(status).new(nil, status:, body: parsed)
+    end
+
+    def error_class(status)
+      ERROR_CLASSES.fetch(status) { (500..599).cover?(status) ? ServerError : ApiError }
+    end
+
+    def parse(raw)
+      return {} if raw.nil? || raw.strip.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def build_uri(path, params)
+      uri = URI.parse("#{configuration.base_url.to_s.chomp("/")}/api#{path}")
+      compact = params.reject { |_, value| value.nil? || value.to_s.empty? }
+      uri.query = URI.encode_www_form(compact) unless compact.empty?
+      uri
+    end
+
+    def headers
+      {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "Authorization" => "Bearer #{configuration.api_token}"
+      }
+    end
+  end
+end

data/lib/lavenda_pay/operation.rb

@@ -0,0 +1,22 @@
+module LavendaPay
+  # Base class for every API operation. Each one is invoked as
+  # `LavendaPay::Customers::Create.call(params)` using the global
+  # configuration, or on an explicit client:
+  #
+  #   LavendaPay::Customers::Create.new(client: client).call(params)
+  class Operation
+    def self.call(*args, **kwargs) = new.call(*args, **kwargs)
+
+    def initialize(client: LavendaPay.client)
+      @client = client
+    end
+
+    private
+
+    attr_reader :client
+
+    def http = client.http
+
+    def escape(value) = URI.encode_www_form_component(value.to_s)
+  end
+end

data/lib/lavenda_pay/orders/create.rb

@@ -0,0 +1,15 @@
+module LavendaPay
+  module Orders
+    # LavendaPay::Orders::Create.call(
+    #   customer_pid: "...", payment_method_kinds: ["pix", "credit_card"],
+    #   description: "...", eid: "ORD-1", frequency: "once", currency: "brl",
+    #   items_attributes: [{product_title: "...", quantity: 1, unit_price: 450.0}]
+    # ) # => LavendaPay::Order
+    class Create < Operation
+      def call(params)
+        body = http.post("/v1/orders", body: {order: params})
+        Order.new(body["order"] || body)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/orders/find.rb

@@ -0,0 +1,11 @@
+module LavendaPay
+  module Orders
+    # LavendaPay::Orders::Find.call("order_...") # => LavendaPay::Order
+    class Find < Operation
+      def call(pid)
+        body = http.get("/v1/orders/#{escape(pid)}")
+        Order.new(body["order"] || body)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/resource.rb

@@ -0,0 +1,30 @@
+module LavendaPay
+  # Thin read-only wrapper over an API payload. Keys are exposed as methods
+  # (`customer.pid`) and via `#[]`; the raw payload stays available as `#to_h`.
+  class Resource
+    attr_reader :attributes
+    alias_method :to_h, :attributes
+
+    def initialize(attributes)
+      @attributes = (attributes || {}).transform_keys(&:to_s).freeze
+    end
+
+    def [](key) = attributes[key.to_s]
+
+    def pid = attributes["pid"]
+
+    def respond_to_missing?(name, include_private = false)
+      attributes.key?(name.to_s) || super
+    end
+
+    def method_missing(name, *args)
+      return attributes[name.to_s] if args.empty? && attributes.key?(name.to_s)
+
+      super
+    end
+
+    def ==(other) = other.is_a?(self.class) && other.attributes == attributes
+
+    def inspect = "#<#{self.class.name} #{attributes.inspect}>"
+  end
+end

data/lib/lavenda_pay/resources/customer.rb

@@ -0,0 +1,6 @@
+module LavendaPay
+  class Customer < Resource
+    # Attributes: pid, full_name, user_email, document_type, document_number,
+    # dial_code, phone_number.
+  end
+end

data/lib/lavenda_pay/resources/order.rb

@@ -0,0 +1,9 @@
+module LavendaPay
+  class Order < Resource
+    # Attributes: pid, status, expires_at, requires_billing_address, customer.
+    def customer
+      value = self["customer"]
+      value.is_a?(Hash) ? Customer.new(value) : value
+    end
+  end
+end

data/lib/lavenda_pay/version.rb

@@ -0,0 +1,3 @@
+module LavendaPay
+  VERSION = "0.0.1"
+end

data/lib/lavenda_pay/webhooks/construct_event.rb

@@ -0,0 +1,15 @@
+module LavendaPay
+  module Webhooks
+    # Checks the secret header, then parses the raw body. For controllers:
+    #
+    #   event = LavendaPay::Webhooks::ConstructEvent.call(
+    #     request.raw_post, request.headers[LavendaPay::Webhooks::Signature::HEADER]
+    #   )
+    class ConstructEvent
+      def self.call(raw_body, received_secret, secret: LavendaPay.configuration.webhook_secret)
+        VerifySignature.call(received_secret, secret:)
+        ParseEvent.call(raw_body)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/webhooks/event.rb

@@ -0,0 +1,69 @@
+module LavendaPay
+  module Webhooks
+    # A parsed webhook delivery from Lavenda Pay:
+    #   {"event" => "order_paid", "resource_type" => "Order",
+    #    "resource_pid" => "order_123", "data" => {...}}
+    class Event
+      ORDER_EVENTS = %w[
+        order_created order_pending order_partially_paid order_paid
+        order_refund_requested order_refunded order_cancelled
+      ].freeze
+
+      PAYMENT_EVENTS = %w[
+        payment_created payment_processing payment_pending payment_paid
+        payment_refused payment_refund_requested payment_refunded
+        payment_partially_refunded payment_canceled
+      ].freeze
+
+      SUPPORTED_EVENTS = (ORDER_EVENTS + PAYMENT_EVENTS).freeze
+
+      REQUIRED_KEYS = %w[event resource_type data].freeze
+
+      attr_reader :payload
+
+      # Raises InvalidWebhookPayloadError when required keys are missing.
+      def self.parse(payload)
+        payload = JSON.parse(payload) if payload.is_a?(String)
+        raise InvalidWebhookPayloadError, "payload must be a JSON object" unless payload.is_a?(Hash)
+
+        payload = payload.transform_keys(&:to_s)
+        missing = REQUIRED_KEYS.reject { |key| present?(payload[key]) }
+        missing << "resource_pid" unless present?(payload["resource_pid"]) || present?(payload["resource_id"])
+        raise InvalidWebhookPayloadError, "missing keys: #{missing.join(", ")}" unless missing.empty?
+
+        new(payload)
+      rescue JSON::ParserError => error
+        raise InvalidWebhookPayloadError, "invalid JSON: #{error.message}"
+      end
+
+      def self.present?(value) = !(value.nil? || (value.respond_to?(:empty?) && value.empty?))
+
+      def initialize(payload)
+        @payload = payload
+      end
+
+      def name = payload["event"]
+
+      def resource_type = payload["resource_type"]
+
+      # Lavenda Pay sends `resource_pid`; older consumers used `resource_id`.
+      def resource_id = (payload["resource_pid"] || payload["resource_id"]).to_s
+
+      def data = payload["data"]
+
+      # pid of the order/payment the event is about.
+      def pid = data.is_a?(Hash) ? data["pid"] : nil
+
+      def supported? = SUPPORTED_EVENTS.include?(name)
+
+      def order? = name.to_s.start_with?("order_")
+
+      def payment? = name.to_s.start_with?("payment_")
+
+      def order = order? && data.is_a?(Hash) ? Order.new(data) : nil
+
+      # Stable key for de-duplicating deliveries.
+      def idempotency_key = [name, resource_type, resource_id].join(":")
+    end
+  end
+end

data/lib/lavenda_pay/webhooks/parse_event.rb

@@ -0,0 +1,9 @@
+module LavendaPay
+  module Webhooks
+    # LavendaPay::Webhooks::ParseEvent.call(request.raw_post) # => Event
+    # Raises InvalidWebhookPayloadError for bad JSON or missing keys.
+    class ParseEvent
+      def self.call(payload) = Event.parse(payload)
+    end
+  end
+end

data/lib/lavenda_pay/webhooks/signature.rb

@@ -0,0 +1,22 @@
+require "openssl"
+
+module LavendaPay
+  module Webhooks
+    # Lavenda Pay authenticates deliveries with a shared secret sent in the
+    # webhook secret header (see HEADER).
+    module Signature
+      HEADER = "X-Lavenda-Pay-Webhook-Secret".freeze
+
+      module_function
+
+      def valid?(received, secret: LavendaPay.configuration.webhook_secret)
+        return false if received.nil? || received.empty? || secret.nil? || secret.empty?
+
+        # Hash both sides so the comparison is constant-time regardless of length.
+        OpenSSL.fixed_length_secure_compare(digest(received), digest(secret))
+      end
+
+      def digest(value) = OpenSSL::Digest::SHA256.digest(value.to_s)
+    end
+  end
+end

data/lib/lavenda_pay/webhooks/verify_signature.rb

@@ -0,0 +1,13 @@
+module LavendaPay
+  module Webhooks
+    # LavendaPay::Webhooks::VerifySignature.call(request.headers[Signature::HEADER])
+    # # => true, or raises InvalidWebhookSignatureError
+    class VerifySignature
+      def self.call(received, secret: LavendaPay.configuration.webhook_secret)
+        return true if Signature.valid?(received, secret:)
+
+        raise InvalidWebhookSignatureError, "invalid webhook secret"
+      end
+    end
+  end
+end

data/lib/lavenda_pay/webhooks.rb

@@ -0,0 +1,5 @@
+require_relative "webhooks/event"
+require_relative "webhooks/signature"
+require_relative "webhooks/verify_signature"
+require_relative "webhooks/parse_event"
+require_relative "webhooks/construct_event"

data/lib/lavenda_pay.rb

@@ -0,0 +1,33 @@
+require_relative "lavenda_pay/version"
+require_relative "lavenda_pay/errors"
+require_relative "lavenda_pay/configuration"
+require_relative "lavenda_pay/http"
+require_relative "lavenda_pay/resource"
+require_relative "lavenda_pay/resources/customer"
+require_relative "lavenda_pay/resources/order"
+require_relative "lavenda_pay/client"
+require_relative "lavenda_pay/operation"
+require_relative "lavenda_pay/customers/create"
+require_relative "lavenda_pay/customers/find"
+require_relative "lavenda_pay/customers/list"
+require_relative "lavenda_pay/customers/find_by"
+require_relative "lavenda_pay/orders/create"
+require_relative "lavenda_pay/orders/find"
+require_relative "lavenda_pay/webhooks"
+require_relative "lavenda_pay/engine" if defined?(Rails::Engine)
+
+module LavendaPay
+  class << self
+    def configuration = @configuration ||= Configuration.new
+
+    def configure
+      yield configuration
+      configuration
+    end
+
+    def reset_configuration! = @configuration = nil
+
+    # Client bound to the global configuration.
+    def client = Client.new
+  end
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: lavenda-pay-ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- La Venda Software
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: Create customers and orders on Lavenda Pay and verify/parse its webhooks,
+  without depending on Rails.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/controllers/lavenda_pay/webhooks_controller.rb
+- config/routes.rb
+- lib/lavenda-pay-ruby.rb
+- lib/lavenda_pay.rb
+- lib/lavenda_pay/client.rb
+- lib/lavenda_pay/configuration.rb
+- lib/lavenda_pay/customers/create.rb
+- lib/lavenda_pay/customers/find.rb
+- lib/lavenda_pay/customers/find_by.rb
+- lib/lavenda_pay/customers/list.rb
+- lib/lavenda_pay/engine.rb
+- lib/lavenda_pay/errors.rb
+- lib/lavenda_pay/http.rb
+- lib/lavenda_pay/operation.rb
+- lib/lavenda_pay/orders/create.rb
+- lib/lavenda_pay/orders/find.rb
+- lib/lavenda_pay/resource.rb
+- lib/lavenda_pay/resources/customer.rb
+- lib/lavenda_pay/resources/order.rb
+- lib/lavenda_pay/version.rb
+- lib/lavenda_pay/webhooks.rb
+- lib/lavenda_pay/webhooks/construct_event.rb
+- lib/lavenda_pay/webhooks/event.rb
+- lib/lavenda_pay/webhooks/parse_event.rb
+- lib/lavenda_pay/webhooks/signature.rb
+- lib/lavenda_pay/webhooks/verify_signature.rb
+homepage: https://github.com/LaVendaSoftware/pay-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LaVendaSoftware/pay-ruby
+  source_code_uri: https://github.com/LaVendaSoftware/pay-ruby
+  changelog_uri: https://github.com/LaVendaSoftware/pay-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.13
+specification_version: 4
+summary: Ruby client for the Lavenda Pay payments API.
+test_files: []