abacatepay-ruby 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8249cc166bb8f5534c7299d4da8aac7c08193e8a33df8e7a7618737adb44a08c
-  data.tar.gz: f939f4979946f82d9e5a189d634ca4a7c99aa11e555646aec213b2f34dd4b817
+  metadata.gz: 604226a94737477c55324bf08cb81736cce65fdf482453bd2667572c8986b010
+  data.tar.gz: 4e292b8d7db21a444cc4348bd59bc2cf396849ff8d99db4d4463ab1b651962fe
 SHA512:
-  metadata.gz: 4a14de54241b2901c7873becb95bab7bcceee8e7208b60b02114138eba6c72b1b6c16d5167c9f26f1b96fa9343bbe40097153f8b801b927b5c5dff02b3c0585c
-  data.tar.gz: e70fc7b7efea2223fbe1093f6f792e394f697da22fe92f01c738bec6a016df8116d09c5d4eec56accd4dbd5cd63a4628a8b6bb721742b76695f1436edc1139e7
+  metadata.gz: 55eeee33fcf8a4b509c849f85d90ccb3f0fb4a2b4aad040325da4a6ed19bf2b60394190ce848ff0b03fa98ec56b0bddccf2fae677c19b1db1dfc7c744819286a
+  data.tar.gz: e8258c5ba01696d7d76fb85b4314a047052b04f13e0a90c4a826fe83f14ce967ea817cb445d3158a61be27a6ec4af99da9fc0c4dd477449c1bf1b60412f7f612

data/.rubocop.yml

@@ -122,4 +122,15 @@ RSpec/SpecFilePathFormat:
 RSpec/DescribeClass:
   Exclude:
     - "spec/clients/request_contract_spec.rb"
+    - "spec/clients/pagination_spec.rb"
+    - "spec/clients/resilience_spec.rb"
+    - "spec/clients/logging_spec.rb"
+    - "spec/clients/boleto_spec.rb"
     - "spec/packaging_spec.rb"
+
+# `has_more?` mirrors the API's own `hasMore` field and matches the convention
+# other payment SDKs use for cursor pagination. `more?` would read as a
+# different question.
+Naming/PredicatePrefix:
+  AllowedMethods:
+    - has_more?

data/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-08-05
+
+### Added
+
+- **BOLETO support.** The method was rejected outright by the `Billings::Methods`
+  enum even though it is a first-class payment method in the v2 API. Adds the
+  enum value, the boleto-only `due_date`/`interest`/`fine` fields on checkouts,
+  and a `method:` argument on `TransparentClient#create` (which previously
+  hard-coded PIX). Boleto responses now expose `bar_code`, `url`, `br_code`,
+  `br_code_base64` and `expires_at`.
+- **Cursor pagination.** List endpoints cap at 100 items and report `hasMore`
+  plus a cursor; the SDK discarded that metadata, making record 101
+  unreachable. `list` now returns an `AbacatePay::Collection` — Enumerable and
+  Array-compatible, so existing code is unaffected — carrying `has_more?` and
+  `next_cursor`. `each_page` and `auto_paging_each` walk every page.
+- **Retries with exponential backoff and jitter** on 429 and 5xx, configurable
+  via `config.max_retries` (default 2). Only idempotent methods are retried;
+  POST never is, because repeating `checkouts/create` after a timeout could
+  charge a customer twice and the API exposes no idempotency key.
+- **Optional request logging** via `config.logger`, with the bearer token
+  redacted and bodies never logged.
+- `SubscriptionClient#change_plan` and `#record_usage` — the last two of the 45
+  documented v2 endpoints. All 45 are now covered.
+- `subscription.payment_failed` and `subscription.trial_started` webhook event
+  types. `payment_failed` is the dunning signal.
+- Checkout fields the v2 API accepts but the SDK never sent: `max_installments`
+  (nested under `card`), `up_sell_product_id` and `custom_metadata`.
+- A `User-Agent` identifying the SDK and Ruby version.
+
+### Fixed
+
+- `Webhooks.parse` aside, malformed API responses raised `JSON::ParserError`
+  and a missing `data` field raised `KeyError`; both are now `ApiError`.
+
+### Changed
+
+- `BillingClient`'s deprecation warning now states that its `/billings/*`
+  endpoints do not exist on either API version, so every call fails. It will be
+  removed in 2.0.0.
+
+### Corrected
+
+- The 1.0.0 notes stated that the v1 API "has been retired and answers Not found
+  for every path". That is wrong: v1 is still served, under a different dialect
+  — singular paths (`/v1/billing/`, `/v1/customer/`) and different resource
+  names (`pixQrCode`). The original diagnosis tested v2-shaped paths against
+  `/v1`. The fix itself stands: this SDK only ever spoke v2's dialect, so 10 of
+  the 12 paths it calls do not exist on v1 and routing there produced 404s.
+
 ## [1.0.0] - 2026-08-05
 
 First stable release. The public surface is now covered by CI on four Ruby
@@ -121,5 +170,6 @@ versions and will not change without a major bump.
 
 - Initial release
 
+[1.1.0]: https://github.com/AbacatePay/abacatepay-ruby-sdk/releases/tag/v1.1.0
 [1.0.0]: https://github.com/AbacatePay/abacatepay-ruby-sdk/releases/tag/v1.0.0
 [0.1.0]: https://github.com/AbacatePay/abacatepay-ruby-sdk/releases/tag/v0.1.0

data/README.md

@@ -42,8 +42,10 @@ gem 'abacatepay-ruby'
 
 ```ruby
 AbacatePay.configure do |config|
-  config.api_token = ENV['ABACATEPAY_TOKEN']
-  config.timeout = 30 # opcional, em segundos
+  config.api_token  = ENV['ABACATEPAY_TOKEN']
+  config.timeout    = 30      # opcional, segundos (default 30)
+  config.max_retries = 2      # opcional, retry em 429/5xx (default 2, 0 desliga)
+  config.logger     = Rails.logger # opcional, token é redigido
 end
 ```
 
@@ -101,9 +103,26 @@ AbacatePay.checkouts.list(status: 'PAID', email: 'user@example.com')
 
 <div align="center">
 
+Listas retornam no máximo 100 itens. O resultado é uma `Collection` — funciona como Array, e ainda carrega o cursor:
+
+</div>
+
+```ruby
+page = AbacatePay.customers.list
+page.first.id     # funciona como Array
+page.has_more?    # => true
+page.next_cursor  # => "cust_abc123"
+
+# Para percorrer tudo sem lidar com cursor:
+AbacatePay.customers.auto_paging_each { |customer| puts customer.id }
+AbacatePay.customers.each_page { |page| puts page.size }
+```
+
+<div align="center">
+
 ## Versionamento
 
-O SDK fala **exclusivamente a v2** — `https://api.abacatepay.com/v2`. A v1 foi desligada pela AbacatePay e responde `{"error":"Not found"}` em toda rota, então não há o que negociar.
+O SDK fala **exclusivamente a v2** — `https://api.abacatepay.com/v2`. A v1 ainda existe para integrações legadas, mas usa outro dialeto (caminhos no singular como `/v1/billing/`, `/v1/customer/`) que este SDK nunca implementou. Se você precisa da v1, chame a API diretamente.
 
 O ambiente (dev mode x produção) é definido **pela chave de API**, não por configuração: chaves de Dev mode geram transações simuladas. Por isso `config.environment` não faz nada — ela continua aceita para não quebrar initializers existentes, mas emite aviso de depreciação.
 
@@ -214,7 +233,7 @@ Todos os recursos são acessíveis pela fachada `AbacatePay.<recurso>`.
 | `products` | `list` `get` `create` `delete` |
 | `coupons` | `list` `get` `create` `delete` `toggle` |
 | `checkouts` | `list` `get` `create` `refund` |
-| `subscriptions` | `list` `create` `cancel` |
+| `subscriptions` | `list` `create` `cancel` `change_plan` `record_usage` |
 | `transparents` | `list` `create` `check` `simulate_payment` `refund` |
 | `pix` | `list` `get` `send_pix` |
 | `payouts` | `list` `get` `create` |
@@ -363,6 +382,64 @@ AbacatePay.payouts.create(
 
 <div align="center">
 
+### Boleto
+
+Boleto tem vencimento, juros e multa próprios. Todos os valores em centavos.
+
+</div>
+
+```ruby
+AbacatePay.checkouts.create(
+  AbacatePay::Resources::Checkouts.new(
+    methods: ['BOLETO'],
+    due_date: '2026-08-15',              # opcional; default 3 dias úteis
+    interest: { value: 100 },            # juros ao mês
+    fine: { value: 200, type: 'PERCENTAGE' }, # ou type: 'FIXED'
+    products: [
+      AbacatePay::Resources::Billings::Product.new(external_id: 'prod_123', quantity: 1)
+    ]
+  )
+)
+```
+
+<div align="center">
+
+No checkout transparente, o boleto exige nome e CPF/CNPJ do pagador — o SDK valida antes de chamar a API:
+
+</div>
+
+```ruby
+charge = AbacatePay::Resources::Transparents.new(amount: 25_000, due_date: '2026-08-15')
+# charge.customer precisa ter metadata.name e metadata.tax_id
+
+boleto = AbacatePay.transparents.create(charge, method: 'BOLETO')
+boleto.bar_code        # linha digitável
+boleto.url             # PDF para impressão
+boleto.br_code         # PIX alternativo da mesma cobrança
+```
+
+<div align="center">
+
+### Parcelamento e order bump
+
+</div>
+
+```ruby
+AbacatePay.checkouts.create(
+  AbacatePay::Resources::Checkouts.new(
+    methods: ['CARD'],
+    max_installments: 12,
+    up_sell_product_id: 'prod_bump',
+    custom_metadata: { origem: 'app-mobile' },
+    products: [
+      AbacatePay::Resources::Billings::Product.new(external_id: 'prod_123', quantity: 1)
+    ]
+  )
+)
+```
+
+<div align="center">
+
 ### Links de pagamento
 
 Um link reutilizável, pago por vários clientes de forma independente — vendas em massa, rifas, formulários de inscrição. Para uma cobrança por cliente, use `checkouts`.
@@ -407,6 +484,12 @@ Cancela imediatamente; parcelas futuras pendentes são canceladas junto.
 
 ```ruby
 AbacatePay.subscriptions.cancel('subs_abc123xyz')
+
+# Upgrade/downgrade — vale a partir do próximo ciclo
+AbacatePay.subscriptions.change_plan('subs_abc123xyz', product_id: 'prod_pro', quantity: 1)
+
+# Cobrança por uso — produto sem ciclo
+AbacatePay.subscriptions.record_usage('subs_abc123xyz', product_id: 'prod_api', units: 50)
 ```
 
 <div align="center">

data/abacatepay-ruby.gemspec

@@ -41,6 +41,7 @@ Gem::Specification.new do |spec|
   # NestedParamsEncoder). The lockfile only protects this repo — consumers are
   # protected by the constraint here.
   spec.add_dependency "faraday", "~> 2.14", ">= 2.14.3"
+  spec.add_dependency "faraday-retry", "~> 2.3"
 
   # Development dependencies
   spec.add_development_dependency "bundler-audit", "~> 0.9"

data/lib/abacate_pay/clients/billing_client.rb

@@ -2,7 +2,15 @@
 
 module AbacatePay
   module Clients
-    # Client class for managing billing-related operations in the AbacatePay API.
+    # Deprecated client for the v1 billing endpoints.
+    #
+    # The endpoints this class calls (`/billings/create`, `/billings/list`) do
+    # not exist on either API version — v2 replaced them with `/checkouts/*`,
+    # and v1 uses the singular `/billing/*`. Every call raises ApiError.
+    #
+    # Kept only so existing code keeps loading; it will be removed in 2.0.0.
+    #
+    # @deprecated Use {CheckoutClient} instead.
     class BillingClient < Client
       # API endpoint for billing-related operations
       URI = "billings"
@@ -10,7 +18,9 @@ module AbacatePay
       # @param client [Faraday::Connection, nil] Optional Faraday client for custom configurations
       # @deprecated Use {CheckoutClient} instead
       def initialize(client = nil)
-        warn "[DEPRECATION] BillingClient is deprecated. Use CheckoutClient instead."
+        warn "[DEPRECATION] BillingClient calls /billings/* endpoints that do not exist on the " \
+             "AbacatePay API — every request will fail. Use AbacatePay.checkouts instead. " \
+             "This class will be removed in 2.0.0."
         super(URI, client)
       end
 
@@ -19,7 +29,7 @@ module AbacatePay
       # @return [Array<Resources::Billing>] Array of Billing objects
       def list
         response = request("GET", "list")
-        Array(response).map { |data| Resources::Billings.new(data) }
+        build_list(response, Resources::Billings)
       end
 
       # Creates a new billing

data/lib/abacate_pay/clients/checkout_client.rb

@@ -17,7 +17,7 @@ module AbacatePay
       # @return [Array<Resources::Checkouts>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::Checkouts.new(data) }
+        build_list(response, Resources::Checkouts)
       end
 
       # @param id [String] Checkout ID
@@ -62,8 +62,29 @@ module AbacatePay
           items: data.products&.map { |product| { id: product.external_id, quantity: product.quantity } },
           externalId: data.external_id,
           coupons: data.coupons,
-          customerId: customer_id.to_s.empty? ? nil : customer_id
-        }.compact
+          customerId: customer_id.to_s.empty? ? nil : customer_id,
+          upSellProductId: data.up_sell_product_id,
+          metadata: data.custom_metadata
+        }.merge(boleto_options(data)).merge(card_options(data)).compact
+      end
+
+      # BOLETO-only fields. The API rejects them for other methods, so they are
+      # only sent when the caller actually set them.
+      #
+      # @param data [Resources::Checkouts] The checkout to serialize
+      # @return [Hash] The boleto payload fragment
+      def boleto_options(data)
+        { dueDate: data.due_date, interest: data.interest, fine: data.fine }
+      end
+
+      # CARD-only instalment cap, which the API nests under `card`.
+      #
+      # @param data [Resources::Checkouts] The checkout to serialize
+      # @return [Hash] The card payload fragment
+      def card_options(data)
+        return {} unless data.max_installments
+
+        { card: { maxInstallments: data.max_installments } }
       end
     end
   end

data/lib/abacate_pay/clients/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/retry"
 
 module AbacatePay
   module Clients
@@ -9,12 +10,64 @@ module AbacatePay
     # This class handles API requests using Faraday and provides a way to manage
     # authentication and communication with the AbacatePay service.
     class Client
+      # Statuses worth retrying. 429 is rate limiting and 5xx are transient —
+      # AbacatePay's own reference tells integrators to back off on both.
+      RETRIABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+
+      # Only methods that are safe to repeat. POST is excluded: retrying
+      # `checkouts/create` after a timeout could charge a customer twice, and
+      # the API exposes no idempotency key to make that safe.
+      RETRIABLE_METHODS = %i[get head options].freeze
+
+      # Passing `exceptions` replaces faraday-retry's defaults rather than
+      # adding to them, and Faraday::RetriableResponse is what the middleware
+      # raises internally for a retriable status. Omitting it silently disables
+      # status-code retries altogether.
+      RETRIABLE_EXCEPTIONS = [
+        Faraday::RetriableResponse,
+        Faraday::TimeoutError,
+        Faraday::ConnectionFailed,
+        Errno::ETIMEDOUT
+      ].freeze
+
       # @param uri [String] The specific API endpoint to interact with
       # @param client [Faraday::Connection, nil] Optional Faraday client for custom configurations
       def initialize(uri, client = nil)
         @client = client || build_client(uri)
       end
 
+      # Yields every page of a list endpoint, following the cursor.
+      #
+      # @param params [Hash] Params forwarded to each `list` call
+      # @yield [AbacatePay::Collection] Each page in order
+      # @return [void]
+      def each_page(**params)
+        return to_enum(:each_page, **params) unless block_given?
+
+        cursor = params.delete(:after)
+        loop do
+          page = list(**params, **(cursor ? { after: cursor } : {}))
+          yield page
+          break unless page.respond_to?(:has_more?) && page.has_more? && page.next_cursor
+
+          cursor = page.next_cursor
+        end
+      end
+
+      # Yields every record across every page.
+      #
+      # Prefer this over `list` when the result set can exceed the 100-item
+      # page limit.
+      #
+      # @param params [Hash] Params forwarded to each `list` call
+      # @yield [Object] Each resource
+      # @return [void]
+      def auto_paging_each(**params, &)
+        return to_enum(:auto_paging_each, **params) unless block_given?
+
+        each_page(**params) { |page| page.each(&) }
+      end
+
       private
 
       # Sends an HTTP request to the API
@@ -22,7 +75,8 @@ module AbacatePay
       # @param method [String] The HTTP method (e.g., GET, POST)
       # @param uri [String] The endpoint URI relative to the base URI
       # @param options [Hash] Optional settings and parameters for the request
-      # @return [Hash] The response data
+      # @return [Hash, AbacatePay::Collection] The response data — a Collection
+      #   when the API reports pagination, the raw data otherwise
       # @raise [ApiError] If an error occurs during the request
       def request(method, uri, options = {})
         response = @client.public_send(method.downcase) do |req|
@@ -34,11 +88,27 @@ module AbacatePay
         parsed = JSON.parse(response.body)
         raise ApiError, "API error: #{parsed["error"]}" if parsed["error"]
 
-        parsed.fetch("data")
+        data = parsed.fetch("data")
+        # Preserve the cursor when the API sends one; dropping it made paging
+        # past the first 100 records impossible.
+        parsed["pagination"] ? Collection.new(data, parsed["pagination"]) : data
       rescue Faraday::Error => e
         handle_request_error(e)
-      rescue StandardError => e
-        raise ApiError, "Unexpected error: #{e.message}"
+      rescue JSON::ParserError => e
+        raise ApiError, "Malformed API response: #{e.message}"
+      rescue KeyError
+        raise ApiError, "API response is missing the 'data' field"
+      end
+
+      # Maps a list response into resources without losing the page cursor.
+      #
+      # @param response [Array, AbacatePay::Collection] The raw list response
+      # @param resource_class [Class] The resource to instantiate per item
+      # @return [Array, AbacatePay::Collection] Mapped items, still paginated
+      #   when the API reported pagination
+      def build_list(response, resource_class)
+        items = Array(response).map { |data| resource_class.new(data) }
+        response.is_a?(Collection) ? response.with_items(items) : items
       end
 
       # Builds a new Faraday client with default configuration
@@ -51,17 +121,66 @@ module AbacatePay
 
         Faraday.new(
           url: base_url,
-          headers: {
-            "Content-Type" => "application/json",
-            "Authorization" => "Bearer #{configuration.api_token}"
-          },
+          headers: build_headers(configuration),
           # Without an explicit timeout a hung gateway blocks the caller's
           # thread indefinitely — inside a Rails request, that is an outage.
           request: {
             timeout: configuration.timeout,
             open_timeout: configuration.timeout
           }
-        )
+        ) do |builder|
+          configure_retries(builder, configuration)
+          configure_logging(builder, configuration)
+          builder.adapter Faraday.default_adapter
+        end
+      end
+
+      # @param configuration [AbacatePay::Configuration] The active configuration
+      # @return [Hash] Request headers
+      def build_headers(configuration)
+        {
+          "Content-Type" => "application/json",
+          "Authorization" => "Bearer #{configuration.api_token}",
+          "User-Agent" => "abacatepay-ruby/#{AbacatePay::VERSION} ruby/#{RUBY_VERSION}"
+        }
+      end
+
+      # @param builder [Faraday::Connection] The connection being built
+      # @param configuration [AbacatePay::Configuration] The active configuration
+      # @return [void]
+      def configure_retries(builder, configuration)
+        return if configuration.max_retries.to_i <= 0
+
+        # `retry_if` is deliberately left at its default (never retry outside
+        # `methods`). Overriding it would re-enable retries for POST, which is
+        # exactly what must not happen for charge creation.
+        builder.request :retry,
+                        max: configuration.max_retries,
+                        interval: 0.5,
+                        backoff_factor: 2,
+                        max_interval: 8,
+                        # Jitter: without it, every client that hit the same
+                        # rate limit retries in lockstep and hits it again.
+                        interval_randomness: 0.5,
+                        retry_statuses: RETRIABLE_STATUSES,
+                        methods: RETRIABLE_METHODS,
+                        exceptions: RETRIABLE_EXCEPTIONS
+      end
+
+      # @param builder [Faraday::Connection] The connection being built
+      # @param configuration [AbacatePay::Configuration] The active configuration
+      # @return [void]
+      def configure_logging(builder, configuration)
+        return unless configuration.logger
+
+        builder.response :logger, configuration.logger, headers: true, bodies: false do |logger|
+          # Faraday renders header values inspected, so the token appears as
+          #   Authorization: "Bearer abc_live_..."
+          # Both spellings are filtered so a change in that formatting cannot
+          # silently start leaking the credential.
+          logger.filter(/(Authorization:\s*")Bearer\s+[^"]*(")/i, '\1Bearer [REDACTED]\2')
+          logger.filter(/(Authorization:\s*)Bearer\s+\S+/i, '\1Bearer [REDACTED]')
+        end
       end
 
       # Handles API request errors
@@ -75,6 +194,8 @@ module AbacatePay
                         end
 
         raise ApiError, "Request error: #{error_message || error.message}"
+      rescue JSON::ParserError
+        raise ApiError, "Request error: #{error.message}"
       end
     end
   end

data/lib/abacate_pay/clients/coupon_client.rb

@@ -17,7 +17,7 @@ module AbacatePay
       # @return [Array<Resources::Coupons>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::Coupons.new(data) }
+        build_list(response, Resources::Coupons)
       end
 
       # @param id [String] Coupon ID

data/lib/abacate_pay/clients/customer_client.rb

@@ -18,7 +18,7 @@ module AbacatePay
       # @return [Array<Resources::Customers>] Array of Customer objects
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::Customers.new(data) }
+        build_list(response, Resources::Customers)
       end
 
       # Retrieves a customer by ID

data/lib/abacate_pay/clients/payment_link_client.rb

@@ -23,7 +23,7 @@ module AbacatePay
       # @return [Array<Resources::Checkouts>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::Checkouts.new(data) }
+        build_list(response, Resources::Checkouts)
       end
 
       # @param id [String] The payment link ID

data/lib/abacate_pay/clients/payout_client.rb

@@ -16,7 +16,7 @@ module AbacatePay
       # @return [Array<Resources::Payouts>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::Payouts.new(data) }
+        build_list(response, Resources::Payouts)
       end
 
       # @param id [String] Payout ID

data/lib/abacate_pay/clients/pix_client.rb

@@ -17,7 +17,7 @@ module AbacatePay
       # @return [Array<Resources::PixTransfers>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::PixTransfers.new(data) }
+        build_list(response, Resources::PixTransfers)
       end
 
       # @param id [String] PIX transfer ID

data/lib/abacate_pay/clients/product_client.rb

@@ -16,7 +16,7 @@ module AbacatePay
       # @return [Array<Resources::Products>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::Products.new(data) }
+        build_list(response, Resources::Products)
       end
 
       # @param id [String] Product ID or externalId

data/lib/abacate_pay/clients/subscription_client.rb

@@ -16,7 +16,7 @@ module AbacatePay
       # @return [Array<Resources::Subscriptions>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::Subscriptions.new(data) }
+        build_list(response, Resources::Subscriptions)
       end
 
       # @param data [Resources::Subscriptions]
@@ -50,6 +50,41 @@ module AbacatePay
         response = request("POST", "cancel", json: { id: id })
         Resources::Subscriptions.new(response)
       end
+
+      # Changes the main product of an active subscription. The new price takes
+      # effect on the next billing cycle — the current cycle is untouched.
+      #
+      # @param id [String] The subscription ID (`subs_...`)
+      # @param product_id [String] The new product ID (`prod_...`), which must have a cycle
+      # @param quantity [Integer] Quantity of the product, minimum 1
+      # @return [Hash] The pending update object (`status: "PENDING"`)
+      # @raise [ArgumentError] if quantity is below 1
+      def change_plan(id, product_id:, quantity: 1)
+        raise ArgumentError, "quantity must be at least 1, got #{quantity.inspect}" if quantity.to_i < 1
+
+        request("POST", "change-plan", json: { id: id, productId: product_id, quantity: quantity.to_i })
+      end
+
+      # Records usage of a pay-as-you-go product on an active subscription. The
+      # amount is added to the next pending instalment of the cycle.
+      #
+      # @param id [String] The subscription ID (`subs_...`)
+      # @param product_id [String] The usage product ID (`prod_...`), which must NOT have a cycle
+      # @param units [Integer] Number of units, minimum 1
+      # @param action [String] "add" to add units, "subtract" to reverse units
+      #   already recorded in the same cycle
+      # @return [Hash] The recorded usage
+      # @raise [ArgumentError] if units is below 1 or action is not add/subtract
+      def record_usage(id, product_id:, units:, action: "add")
+        raise ArgumentError, "units must be at least 1, got #{units.inspect}" if units.to_i < 1
+
+        unless %w[add subtract].include?(action.to_s)
+          raise ArgumentError, "action must be \"add\" or \"subtract\", got #{action.inspect}"
+        end
+
+        request("POST", "record-usage",
+                json: { id: id, productId: product_id, units: units.to_i, action: action.to_s })
+      end
     end
   end
 end

data/lib/abacate_pay/clients/transparent_client.rb

@@ -17,31 +17,21 @@ module AbacatePay
       # @return [Array<Resources::Transparents>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::Transparents.new(data) }
+        build_list(response, Resources::Transparents)
       end
 
-      # @param data [Resources::Transparents]
+      # Creates a transparent charge.
+      #
+      # @param data [Resources::Transparents] The charge to create
+      # @param method [String] "PIX" or "BOLETO"
       # @return [Resources::Transparents]
-      def create(data)
-        request_data = {
-          method: "PIX",
-          data: {
-            amount: data.amount
-          },
-          expiresIn: data.expires_in,
-          description: data.description
-        }
-
-        if data.customer
-          request_data[:customer] = {
-            name: data.customer.metadata&.name,
-            email: data.customer.metadata&.email,
-            cellphone: data.customer.metadata&.cellphone,
-            taxId: data.customer.metadata&.tax_id
-          }
-        end
-
-        response = request("POST", "create", json: request_data)
+      # @raise [ArgumentError] if the method is not supported, or if a BOLETO
+      #   charge is missing the payer name/taxId the API requires
+      def create(data, method: Enums::Billings::Methods::PIX)
+        validate_transparent_method!(method)
+        validate_boleto_payer!(data) if method == Enums::Billings::Methods::BOLETO
+
+        response = request("POST", "create", json: build_create_payload(data, method))
         Resources::Transparents.new(response)
       end
 
@@ -68,6 +58,68 @@ module AbacatePay
         response = request("POST", "refund", json: { id: id })
         Resources::Transparents.new(response)
       end
+
+      private
+
+      # Only PIX and BOLETO are transparent-checkout methods; CARD goes through
+      # the hosted checkout.
+      #
+      # @param method [String] The requested method
+      # @return [void]
+      def validate_transparent_method!(method)
+        supported = [Enums::Billings::Methods::PIX, Enums::Billings::Methods::BOLETO]
+        return if supported.include?(method)
+
+        raise ArgumentError, "Transparent checkout supports #{supported.join(" and ")}, got #{method.inspect}"
+      end
+
+      # The API requires the payer's name and taxId for boleto. Failing here
+      # names the missing field instead of returning a generic 422.
+      #
+      # @param data [Resources::Transparents] The charge to validate
+      # @return [void]
+      def validate_boleto_payer!(data)
+        metadata = data.customer&.metadata
+        missing = []
+        missing << "customer.metadata.name" if metadata&.name.to_s.strip.empty?
+        missing << "customer.metadata.tax_id" if metadata&.tax_id.to_s.strip.empty?
+        return if missing.empty?
+
+        raise ArgumentError, "BOLETO requires #{missing.join(" and ")}"
+      end
+
+      # @param data [Resources::Transparents] The charge to serialize
+      # @param method [String] "PIX" or "BOLETO"
+      # @return [Hash] The request payload
+      def build_create_payload(data, method)
+        payload = {
+          method: method,
+          data: {
+            amount: data.amount,
+            dueDate: data.due_date
+          }.compact,
+          expiresIn: data.expires_in,
+          description: data.description
+        }.compact
+
+        customer = serialize_customer(data.customer)
+        payload[:data][:customer] = customer if customer
+
+        payload
+      end
+
+      # @param customer [Resources::Customers, nil] The payer
+      # @return [Hash, nil] The customer payload, or nil when absent
+      def serialize_customer(customer)
+        return nil unless customer
+
+        {
+          name: customer.metadata&.name,
+          email: customer.metadata&.email,
+          cellphone: customer.metadata&.cellphone,
+          taxId: customer.metadata&.tax_id
+        }.compact
+      end
     end
   end
 end

data/lib/abacate_pay/clients/webhook_client.rb

@@ -20,7 +20,7 @@ module AbacatePay
       # @return [Array<Resources::WebhookEndpoints>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::WebhookEndpoints.new(data) }
+        build_list(response, Resources::WebhookEndpoints)
       end
 
       # @param id [String] The webhook ID

data/lib/abacate_pay/collection.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  # A page of results plus the cursor needed to fetch the next one.
+  #
+  # List endpoints return at most 100 items and report whether more exist. The
+  # SDK used to return a bare Array and drop that metadata, which made it
+  # impossible to page past the first 100 records.
+  #
+  # Behaves like an Array everywhere an Array was returned before, so existing
+  # code keeps working:
+  #
+  #   customers = AbacatePay.customers.list
+  #   customers.each { |c| puts c.id }   # Enumerable
+  #   customers.size                     # items on this page
+  #   customers.has_more?                # is there another page?
+  #
+  # To walk every page without handling cursors:
+  #
+  #   AbacatePay.customers.each_page { |page| page.each { |c| puts c.id } }
+  #   AbacatePay.customers.auto_paging_each { |customer| puts customer.id }
+  class Collection
+    include Enumerable
+
+    # @return [Array] The items on this page
+    attr_reader :items
+
+    # @return [String, nil] Cursor for the next page, passed back as `after`
+    attr_reader :next_cursor
+
+    # @return [String, nil] Cursor for the previous page, passed back as `before`
+    attr_reader :before_cursor
+
+    # @param items [Array] The items on this page
+    # @param pagination [Hash, nil] The raw `pagination` object from the API
+    def initialize(items, pagination = nil)
+      @items = Array(items)
+      pagination = {} unless pagination.is_a?(Hash)
+      @has_more = pagination["hasMore"] || false
+      @next_cursor = pagination["next"]
+      @before_cursor = pagination["before"]
+    end
+
+    # @yield [Object] Each item on this page
+    # @return [Enumerator, self]
+    def each(&)
+      return to_enum(:each) unless block_given?
+
+      items.each(&)
+      self
+    end
+
+    # Whether the API reported further pages after this one.
+    #
+    # @return [Boolean]
+    def has_more?
+      @has_more
+    end
+
+    # @return [Integer] Number of items on this page
+    def size
+      items.size
+    end
+    alias length size
+    alias count size
+
+    # @return [Boolean]
+    def empty?
+      items.empty?
+    end
+
+    # @param index [Integer, Range] Index into this page
+    # @return [Object, Array, nil]
+    def [](index)
+      items[index]
+    end
+
+    # @return [Array] A plain Array copy of this page
+    def to_a
+      items.dup
+    end
+    alias to_ary to_a
+
+    # Returns a new Collection with different items and the same cursor.
+    # Used to turn raw hashes into resources without losing pagination.
+    #
+    # @param new_items [Array] The mapped items
+    # @return [Collection]
+    def with_items(new_items)
+      self.class.new(new_items, "hasMore" => has_more?, "next" => next_cursor, "before" => before_cursor)
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} size=#{size} has_more=#{has_more?} next=#{next_cursor.inspect}>"
+    end
+  end
+end

data/lib/abacate_pay/configuration.rb

@@ -8,9 +8,11 @@ module AbacatePay
   #
   # @api public
   class Configuration
-    # The only base URL AbacatePay serves. The v1 prefix was retired and now
-    # answers `{"error":"Not found"}` for every path, so there is nothing to
-    # negotiate between.
+    # The only base URL this SDK speaks. v1 still exists, but under a
+    # different dialect — singular paths (`/v1/billing/`, `/v1/customer/`) and
+    # different resource names (`pixQrCode`) — which this SDK has never
+    # implemented. Deriving a base URL from the token prefix only produced 404s
+    # against v1 while sending v2-shaped paths.
     API_BASE_URL = "https://api.abacatepay.com/v2"
 
     # @return [String] API token for authentication
@@ -19,11 +21,25 @@ module AbacatePay
     # @return [Integer] Request timeout in seconds
     attr_accessor :timeout
 
+    # Retries apply to idempotent requests only (GET/HEAD/OPTIONS) on 429 and
+    # 5xx, with exponential backoff and jitter. Set to 0 to disable.
+    #
+    # @return [Integer] Maximum retry attempts
+    attr_accessor :max_retries
+
+    # Optional logger. Request and response headers are logged with the bearer
+    # token redacted; bodies are never logged, since they carry customer PII.
+    #
+    # @return [Logger, nil]
+    attr_accessor :logger
+
     # Initialize a new configuration with default values
     #
     # @api public
     def initialize
       @timeout = 30
+      @max_retries = 2
+      @logger = nil
       @api_token = nil
     end
 

data/lib/abacate_pay/enums/billings/methods.rb

@@ -10,12 +10,19 @@ module AbacatePay
         # PIX payment method.
         # @return [String] Represents the PIX payment method, a popular instant payment system in Brazil
         PIX = "PIX"
+
+        # @return [String] Credit card payment
         CARD = "CARD"
 
+        # Boleto bancário. Supports a due date and late-payment interest/fine —
+        # see Resources::Checkouts#due_date, #interest and #fine.
+        # @return [String] Boleto payment method
+        BOLETO = "BOLETO"
+
         # Gets all valid method values
         # @return [Array<String>] List of all valid payment methods
         def self.values
-          [PIX, CARD]
+          [PIX, CARD, BOLETO]
         end
 
         # Validates if a given value is a valid method

data/lib/abacate_pay/enums/webhooks/event_types.rb

@@ -13,6 +13,12 @@ module AbacatePay
         SUBSCRIPTION_COMPLETED = "subscription.completed"
         SUBSCRIPTION_RENEWED = "subscription.renewed"
         SUBSCRIPTION_CANCELLED = "subscription.cancelled"
+
+        # Recurring charge failed — the dunning signal. Without handling this,
+        # a failing subscription looks identical to a healthy one.
+        SUBSCRIPTION_PAYMENT_FAILED = "subscription.payment_failed"
+
+        SUBSCRIPTION_TRIAL_STARTED = "subscription.trial_started"
         TRANSFER_COMPLETED = "transfer.completed"
         TRANSFER_FAILED = "transfer.failed"
         PAYOUT_COMPLETED = "payout.completed"
@@ -23,6 +29,7 @@ module AbacatePay
             CHECKOUT_COMPLETED, CHECKOUT_REFUNDED, CHECKOUT_DISPUTED,
             TRANSPARENT_COMPLETED, TRANSPARENT_REFUNDED, TRANSPARENT_DISPUTED,
             SUBSCRIPTION_COMPLETED, SUBSCRIPTION_RENEWED, SUBSCRIPTION_CANCELLED,
+            SUBSCRIPTION_PAYMENT_FAILED, SUBSCRIPTION_TRIAL_STARTED,
             TRANSFER_COMPLETED, TRANSFER_FAILED,
             PAYOUT_COMPLETED, PAYOUT_FAILED
           ]

data/lib/abacate_pay/resources/checkouts.rb

@@ -20,7 +20,13 @@ module AbacatePay
 
       attr_reader :id, :url, :amount, :status, :dev_mode, :methods,
                   :products, :metadata, :customer, :coupons, :external_id,
-                  :frequency, :created_at, :updated_at
+                  :frequency, :created_at, :updated_at,
+                  # BOLETO-only: due date (YYYY-MM-DD) plus late-payment charges.
+                  :due_date, :interest, :fine,
+                  # CARD-only: maximum number of instalments offered.
+                  :max_installments,
+                  # Order bump shown at checkout, and free-form merchant data.
+                  :up_sell_product_id, :custom_metadata
 
       def initialize(data)
         fill(data)
@@ -70,7 +76,9 @@ module AbacatePay
 
       attr_writer :id, :url, :amount, :status, :dev_mode, :methods,
                   :products, :metadata, :customer, :coupons, :external_id,
-                  :frequency, :created_at, :updated_at
+                  :frequency, :created_at, :updated_at,
+                  :due_date, :interest, :fine, :max_installments,
+                  :up_sell_product_id, :custom_metadata
     end
   end
 end

data/lib/abacate_pay/resources/transparents.rb

@@ -2,17 +2,22 @@
 
 module AbacatePay
   module Resources
-    # Represents a transparent PIX checkout in the AbacatePay system.
+    # Represents a transparent checkout (PIX or boleto) in the AbacatePay system.
     class Transparents < Resource
       RESOURCE_PROPERTIES = {
         customer: "AbacatePay::Resources::Customers"
       }.freeze
 
-      DATETIME_PROPERTIES = %w[created_at updated_at].freeze
+      DATETIME_PROPERTIES = %w[created_at updated_at expires_at].freeze
 
       attr_reader :id, :amount, :status, :method, :description,
                   :expires_in, :qr_code, :qr_code_image, :customer,
-                  :metadata, :dev_mode, :created_at, :updated_at
+                  :metadata, :dev_mode, :created_at, :updated_at,
+                  # Boleto: due date sent on create, plus the payment slip the
+                  # API returns — digitable line, viewing URL, and the PIX
+                  # fallback issued for the same charge.
+                  :due_date, :bar_code, :url, :br_code, :br_code_base64,
+                  :expires_at
 
       def initialize(data)
         fill(data)
@@ -40,7 +45,9 @@ module AbacatePay
 
       attr_writer :id, :amount, :status, :method, :description,
                   :expires_in, :qr_code, :qr_code_image, :customer,
-                  :metadata, :dev_mode, :created_at, :updated_at
+                  :metadata, :dev_mode, :created_at, :updated_at,
+                  :due_date, :bar_code, :url, :br_code, :br_code_base64,
+                  :expires_at
     end
   end
 end

data/lib/abacate_pay/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AbacatePay
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/abacate_pay.rb

@@ -2,6 +2,7 @@
 
 require "abacate_pay/version"
 require "abacate_pay/configuration"
+require "abacate_pay/collection"
 
 # Main module for AbacatePay SDK integration
 module AbacatePay

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: abacatepay-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Matheus Cardoso
@@ -29,6 +29,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.14.3
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -130,6 +144,7 @@ files:
 - lib/abacate_pay/clients/subscription_client.rb
 - lib/abacate_pay/clients/transparent_client.rb
 - lib/abacate_pay/clients/webhook_client.rb
+- lib/abacate_pay/collection.rb
 - lib/abacate_pay/configuration.rb
 - lib/abacate_pay/enums.rb
 - lib/abacate_pay/enums/billings/frequencies.rb