pago-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e1d8d540d5ad5f23bf997c722a53baaac2fe9f157ea8f5700b8553ce9a12b854
+  data.tar.gz: 58912be52a4a7efb47c1431732aaa497b71b9faf4e50cbea47a66d6313988744
+SHA512:
+  metadata.gz: e681002b41f4b3457ff8c23a2a9833d307f41c17dfcdce5e574a229ccaa440825e7b7f2b8270498129e9130bc54f9e82e92c63a47627f153fab2e10f4cce2989
+  data.tar.gz: 19074f7bf295a69e73cbf2bae4fe57a6088cbf3869300a4d2724ff146633fbb0409c6dc3a5008ae50a396c93d1138a216dfde305504b135e78afd8b146f1f593

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Pago
+
+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,131 @@
+# Pago Ruby SDK
+
+Ruby client for the [Pago](https://pago.sh) API, generated from its OpenAPI
+specification. Requires Ruby 3.1 or newer and has **no runtime dependencies** —
+only `net/http`, `json` and `openssl` from the standard library.
+
+```ruby
+gem "pago-sdk"
+```
+
+## Usage
+
+```ruby
+require "pago"
+
+client = Pago::Client.new(access_token: ENV.fetch("PAGO_ACCESS_TOKEN"))
+```
+
+`Pago::Client` always tracks the latest API version (2026-04).
+Pin a version explicitly to opt out of that:
+
+```ruby
+client = Pago::V2026_04::Client.new(access_token: token)
+```
+
+The base URL defaults to `https://api.pago.sh` and reads `PAGO_BASE_URL` when
+set; the sandbox lives at `Pago::BaseClient::SANDBOX_BASE_URL`.
+
+## Models
+
+Models are immutable value objects built with keyword arguments. Required
+properties are required keyword arguments; everything else defaults to unset.
+
+```ruby
+order = Pago::Models::Order.from_json(payload)
+order.id
+order.to_json_hash          # Hash ready for JSON.generate
+order.to_json               # String
+```
+
+Only the attributes you actually set are serialized, so a partial update never
+sends `null` for the fields it does not touch. Properties this SDK release does
+not know about survive a `from_json` / `to_json` round trip untouched.
+
+## Pagination
+
+Every paginated operation gets an `_each` companion returning a
+`Pago::Paginator`, a plain `Enumerable` over the items that fetches pages on
+demand:
+
+```ruby
+client.products.list_each(organization_id: id).each { |product| puts product.name }
+client.products.list_each(organization_id: id).first(50)
+client.products.list_each(organization_id: id) { |product| puts product.name }
+client.products.list_each(organization_id: id).pages.count   # page objects
+```
+
+## Errors
+
+Every declared error response has its own class, inheriting from the generic
+error matching its status code:
+
+```ruby
+begin
+  client.products.get(product_id)
+rescue Pago::Errors::ResourceNotFound => e
+  e.status_code   # 404
+  e.data          # deserialized error payload
+rescue Pago::NotFoundError
+  # any 404 of the API
+rescue Pago::APIError => e
+  # anything the API rejected
+rescue Pago::NetworkError
+  # the request never reached the API
+end
+```
+
+## Webhooks
+
+Signature verification follows the [Standard Webhooks](https://www.standardwebhooks.com)
+specification, and the payload comes back as the model matching its event type:
+
+```ruby
+event = Pago::Webhooks.validate_event(
+  body: request.body.read,
+  headers: request.headers,
+  secret: ENV.fetch("PAGO_WEBHOOK_SECRET")
+)
+
+case event
+when Pago::Models::WebhookOrderPaidPayload then fulfill(event.data)
+end
+```
+
+The secret is the one shown when the endpoint is created — the `whsec_` prefix
+followed by the base64 encoded signing key. Pass it verbatim: the SDK strips the
+prefix and base64 decodes the rest to obtain the HMAC key, exactly like every
+other Standard Webhooks implementation.
+
+It raises `Pago::WebhookVerificationError` on a bad signature or a timestamp
+outside the five minute window, `Pago::WebhookSecretError` (a subclass of it)
+when the secret is not in `whsec_<base64>` form, and
+`Pago::WebhookUnknownTypeError` for an event type this SDK release does not know.
+
+## Custom HTTP adapter
+
+The client talks to any object answering `call(Pago::HTTP::Request)` and
+returning a `Pago::HTTP::Response` — useful for instrumentation, retries or
+tests:
+
+```ruby
+class LoggingAdapter
+  def initialize(inner) = @inner = inner
+
+  def call(request)
+    warn "#{request.http_method} #{request.url}"
+    @inner.call(request)
+  end
+end
+
+Pago::Client.new(access_token: token, adapter: LoggingAdapter.new(Pago::HTTP::NetHTTPAdapter.new))
+```
+
+## Types
+
+The gem ships [RBS](https://github.com/ruby/rbs) signatures under `sig/`, and
+every public method carries YARD documentation.
+
+## License
+
+MIT

data/lib/pago/base_client.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Pago
+  # Shared behaviour of every generated, version specific client.
+  class BaseClient
+    DEFAULT_BASE_URL = "https://api.pago.sh"
+    SANDBOX_BASE_URL = "https://sandbox-api.pago.sh"
+    API_VERSION = nil
+
+    # @return [String] the base URL every request is sent to.
+    attr_reader :base_url
+    # @return [#call] the injected HTTP adapter.
+    attr_reader :adapter
+
+    # @param access_token [String, nil] bearer token; defaults to `PAGO_ACCESS_TOKEN`.
+    # @param base_url [String, nil] defaults to `PAGO_BASE_URL`, then to the production URL.
+    # @param adapter [#call, nil] anything answering `call(Pago::HTTP::Request)`.
+    # @param headers [Hash] extra headers sent with every request.
+    def initialize(access_token: nil, base_url: nil, adapter: nil, headers: {})
+      @access_token = access_token || ENV.fetch("PAGO_ACCESS_TOKEN", nil)
+      @base_url = (base_url || ENV.fetch("PAGO_BASE_URL", DEFAULT_BASE_URL)).sub(%r{/+\z}, "")
+      @adapter = adapter || HTTP::NetHTTPAdapter.new
+      @extra_headers = headers
+    end
+
+    # @return [String, nil] the API version this client speaks.
+    def api_version = self.class.const_get(:API_VERSION)
+
+    # Perform an HTTP request and decode its response.
+    #
+    # @param http_method [String]
+    # @param path [String] path template, `{name}` placeholders included.
+    # @param path_params [Hash{String => Object}]
+    # @param query [Hash{String => Object}]
+    # @param body [Object, nil] serialized as JSON when present.
+    # @param response_type [Symbol] `:json`, `:text` or `:none`.
+    # @param errors [Hash{Integer => Class}] status code to generated error class.
+    # @raise [Pago::APIError] when the API answers with a non 2xx status.
+    # @return [Object, String, nil]
+    def request(http_method:, path:, path_params: {}, query: {}, body: nil,
+                response_type: :json, errors: {})
+      response = @adapter.call(
+        HTTP::Request.new(
+          http_method: http_method,
+          url: build_url(path, path_params, query),
+          headers: build_headers(body),
+          body: body.nil? ? nil : JSON.generate(Serde.dump(body))
+        )
+      )
+      handle(response, response_type: response_type, errors: errors)
+    end
+
+    private
+
+    def build_url(path, path_params, query)
+      url = "#{@base_url}#{Serde.path(path, path_params || {})}"
+      pairs = Serde.query(query || {})
+      return url if pairs.empty?
+
+      "#{url}?#{URI.encode_www_form(pairs)}"
+    end
+
+    def build_headers(body)
+      headers = {
+        "Accept" => "application/json",
+        "User-Agent" => "pago-sdk-ruby/#{Pago::VERSION}"
+      }
+      headers["Authorization"] = "Bearer #{@access_token}" if @access_token
+      headers["Pago-Version"] = api_version if api_version
+      headers["Content-Type"] = "application/json" unless body.nil?
+      headers.merge(@extra_headers)
+    end
+
+    def handle(response, response_type:, errors:)
+      raise build_error(response, errors) unless response.success?
+
+      case response_type
+      when :json then parse_json(response.body)
+      when :text then response.body
+      end
+    end
+
+    def parse_json(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise SerializationError, "Failed to parse Pago API response: #{e.message}"
+    end
+
+    def build_error(response, errors)
+      status = response.status
+      body = begin
+        parse_json(response.body)
+      rescue SerializationError
+        response.body
+      end
+
+      error_class = errors[status]
+      return error_class.from_response(status_code: status, body: body, response: response) if error_class
+
+      message = "Pago API returned an error: #{status} - #{response.body}"
+      if status == 429
+        RateLimitError.new(message, status_code: status, body: body, response: response,
+                                    retry_after: retry_after(response))
+      else
+        Pago.error_class_for(status).new(message, status_code: status, body: body, response: response)
+      end
+    end
+
+    def retry_after(response)
+      value = (response.headers || {}).find { |name, _| name.to_s.downcase == "retry-after" }&.last
+      value&.to_i
+    end
+  end
+end

data/lib/pago/errors.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Pago
+  # Base class of every error raised by this SDK.
+  class Error < StandardError; end
+
+  # Raised when the request never produced an HTTP response.
+  class NetworkError < Error; end
+
+  # Raised when the connection or the read timed out.
+  class TimeoutError < NetworkError; end
+
+  # Raised when a response body could not be decoded.
+  class SerializationError < Error; end
+
+  # Raised when the API answered with a non 2xx status code.
+  class APIError < Error
+    # @return [Integer] the HTTP status code of the response.
+    attr_reader :status_code
+    # @return [Object, nil] the deserialized error payload, when the endpoint declares one.
+    attr_reader :data
+    # @return [Object, nil] the raw parsed body of the response.
+    attr_reader :body
+    # @return [Pago::HTTP::Response, nil] the raw HTTP response.
+    attr_reader :response
+
+    def initialize(message = nil, status_code: nil, data: nil, body: nil, response: nil)
+      @status_code = status_code
+      @data = data
+      @body = body
+      @response = response
+      super(message || "Pago API returned an error: #{status_code}")
+    end
+  end
+
+  # Raised for 4xx responses.
+  class ClientError < APIError; end
+
+  class BadRequestError < ClientError; end
+  class AuthenticationError < ClientError; end
+  class PaymentRequiredError < ClientError; end
+  class PermissionDeniedError < ClientError; end
+  class NotFoundError < ClientError; end
+  class ConflictError < ClientError; end
+  class GoneError < ClientError; end
+  class PreconditionFailedError < ClientError; end
+  class UnprocessableEntityError < ClientError; end
+
+  # Raised for 429 responses.
+  class RateLimitError < ClientError
+    # @return [Integer, nil] the value of the Retry-After header, in seconds.
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **options)
+      @retry_after = retry_after
+      super(message, **options)
+    end
+  end
+
+  # Raised for 5xx responses.
+  class ServerError < APIError; end
+
+  STATUS_ERROR_CLASSES = {
+    400 => BadRequestError,
+    401 => AuthenticationError,
+    402 => PaymentRequiredError,
+    403 => PermissionDeniedError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    410 => GoneError,
+    412 => PreconditionFailedError,
+    422 => UnprocessableEntityError,
+    429 => RateLimitError
+  }.freeze
+
+  # @param status_code [Integer]
+  # @return [Class] the generic error class matching an HTTP status code.
+  def self.error_class_for(status_code)
+    return ServerError if status_code >= 500
+
+    STATUS_ERROR_CLASSES.fetch(status_code, ClientError)
+  end
+end

data/lib/pago/http.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Pago
+  # Transport layer.
+  #
+  # The client only ever calls `adapter.call(request)`, so any object honouring
+  # that contract can replace {NetHTTPAdapter} — a Faraday wrapper, a test
+  # double, an instrumented adapter.
+  module HTTP
+    # @!attribute http_method
+    #   @return [String] the HTTP verb, uppercased.
+    Request = Struct.new(:http_method, :url, :headers, :body, keyword_init: true)
+
+    Response = Struct.new(:status, :headers, :body, keyword_init: true) do
+      def success? = status >= 200 && status < 300
+    end
+
+    NET_HTTP_CLASSES = {
+      "GET" => Net::HTTP::Get,
+      "POST" => Net::HTTP::Post,
+      "PUT" => Net::HTTP::Put,
+      "PATCH" => Net::HTTP::Patch,
+      "DELETE" => Net::HTTP::Delete,
+      "HEAD" => Net::HTTP::Head,
+      "OPTIONS" => Net::HTTP::Options,
+      "TRACE" => Net::HTTP::Trace
+    }.freeze
+
+    # The default adapter, backed by the `net/http` standard library.
+    class NetHTTPAdapter
+      def initialize(open_timeout: 10, read_timeout: 60)
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+      end
+
+      # @param request [Pago::HTTP::Request]
+      # @return [Pago::HTTP::Response]
+      def call(request)
+        uri = URI.parse(request.url)
+        net_request = build_request(uri, request)
+        response = start(uri) { |http| http.request(net_request) }
+        Response.new(
+          status: response.code.to_i,
+          headers: response.each_header.to_h,
+          body: response.body || ""
+        )
+      rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error => e
+        raise ::Pago::TimeoutError, "Pago API request timed out: #{e.message}"
+      rescue SocketError, SystemCallError, OpenSSL::SSL::SSLError, IOError, EOFError => e
+        raise ::Pago::NetworkError, "Pago API network error: #{e.message}"
+      end
+
+      private
+
+      def build_request(uri, request)
+        verb = request.http_method.to_s.upcase
+        klass = NET_HTTP_CLASSES.fetch(verb) do
+          raise ::Pago::Error, "Unsupported HTTP method: #{verb}"
+        end
+        net_request = klass.new(uri.request_uri)
+        (request.headers || {}).each { |name, value| net_request[name] = value }
+        net_request.body = request.body unless request.body.nil?
+        net_request
+      end
+
+      def start(uri, &block)
+        Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: @open_timeout,
+          read_timeout: @read_timeout,
+          &block
+        )
+      end
+    end
+  end
+end

data/lib/pago/model.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Pago
+  # Base class of every generated model.
+  #
+  # Models are immutable value objects. `from_json` rebuilds one from a parsed
+  # JSON object and keeps the raw payload around, so unknown properties added by
+  # a newer API version survive a `from_json` / `to_json` round trip.
+  class Model
+    JSON_KEYS = {}.freeze
+    REQUIRED_KEYS = [].freeze
+
+    class << self
+      # @return [Hash{Symbol => String}] attribute name to JSON property name.
+      def json_keys = const_get(:JSON_KEYS)
+
+      # @return [Array<String>] the JSON properties the schema declares required.
+      def required_json_keys = const_get(:REQUIRED_KEYS)
+
+      # @param data [Hash, String, nil]
+      # @return [Pago::Model, nil]
+      def from_json(data)
+        data = ::JSON.parse(data) if data.is_a?(String)
+        data = ::Pago::Serde.object(data)
+        return nil if data.nil?
+
+        wrap_raw(new, data)
+      end
+
+      def wrap_raw(instance, data)
+        instance.instance_variable_set(:@__raw, data)
+        instance
+      end
+      private :wrap_raw
+    end
+
+    def initialize
+      @__present = {}
+      @__raw = nil
+    end
+
+    # @return [Boolean] whether an attribute was explicitly set.
+    def field_set?(name) = @__present.key?(name.to_sym)
+
+    # @return [Hash] the JSON representation of this model.
+    def to_json_hash
+      result = @__raw ? @__raw.dup : {}
+      self.class.json_keys.each do |name, key|
+        next unless @__present.key?(name)
+
+        result[key] = ::Pago::Serde.dump(instance_variable_get(:"@#{name}"))
+      end
+      result
+    end
+    alias to_h to_json_hash
+
+    def to_json(*args) = to_json_hash.to_json(*args)
+
+    def [](key) = to_json_hash[key.to_s]
+
+    def ==(other) = other.instance_of?(self.class) && other.to_json_hash == to_json_hash
+    alias eql? ==
+
+    def hash = [self.class, to_json_hash].hash
+
+    def inspect
+      attributes = self.class.json_keys.keys.filter_map do |name|
+        next unless @__present.key?(name)
+
+        "#{name}=#{instance_variable_get(:"@#{name}").inspect}"
+      end
+      "#<#{self.class.name}#{attributes.empty? ? "" : " #{attributes.join(", ")}"}>"
+    end
+
+    private
+
+    def assign(name, value)
+      if ::Pago::UNSET.equal?(value)
+        instance_variable_set(:"@#{name}", nil)
+      else
+        @__present[name] = true
+        instance_variable_set(:"@#{name}", value)
+      end
+    end
+  end
+end

data/lib/pago/paginator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Pago
+  # Lazily walks every page of a paginated endpoint.
+  #
+  # It is a plain `Enumerable` over the *items*, so the whole standard library
+  # applies: `each`, `map`, `select`, `first(20)`, `lazy`, `each_slice`… Pages
+  # are fetched on demand, one request at a time, and `#pages` exposes the raw
+  # page objects when the pagination metadata itself is needed.
+  #
+  # @example
+  #   client.products.list_each(organization_id: id).first(50)
+  class Paginator
+    include Enumerable
+
+    # @yieldparam page [Integer] the 1-based page number to fetch.
+    # @yieldreturn [Object] the deserialized page, answering `items` and `pagination`.
+    def initialize(&fetch_page)
+      raise ArgumentError, "Pago::Paginator requires a block" unless block_given?
+
+      @fetch_page = fetch_page
+    end
+
+    # @yieldparam item [Object] every item of every page.
+    # @return [Enumerator] when no block is given.
+    def each
+      return to_enum(:each) unless block_given?
+
+      pages.each do |page|
+        items = page.respond_to?(:items) ? page.items : nil
+        break if items.nil?
+
+        items.each { |item| yield(item) }
+      end
+      self
+    end
+
+    # @return [Enumerator] the successive page objects, metadata included.
+    def pages
+      return to_enum(:pages) unless block_given?
+
+      number = 1
+      loop do
+        page = @fetch_page.call(number)
+        break if page.nil?
+
+        yield(page)
+        max_page = max_page_of(page)
+        break if max_page.nil? || number >= max_page
+
+        number += 1
+      end
+      self
+    end
+
+    private
+
+    def max_page_of(page)
+      return nil unless page.respond_to?(:pagination)
+
+      pagination = page.pagination
+      return nil unless pagination.respond_to?(:max_page)
+
+      pagination.max_page
+    end
+  end
+end