abacatepay-ruby 1.0.0 → 1.2.1

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,23 +75,74 @@ 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|
-          req.url uri
-          req.params = options[:params] if options[:params]
-          req.body = options[:json].to_json if options[:json]
-        end
-
+        response = send_request(method, uri, options)
         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
+
+      # Issues the HTTP call.
+      #
+      # @param method [String] The HTTP method
+      # @param uri [String] The endpoint URI relative to the base URI
+      # @param options [Hash] Params and JSON body
+      # @return [Faraday::Response]
+      def send_request(method, uri, options)
+        @client.public_send(method.downcase) do |req|
+          req.url uri
+          req.params = options[:params] if options[:params]
+          req.body = compact_payload(options[:json]).to_json if options[:json]
+        end
+      end
+
+      # Removes nil values from an outgoing payload, at every depth.
+      #
+      # The API rejects explicit nulls: `{"cellphone": null}` comes back as
+      # HTTP 400 "Expected property 'cellphone' to be string but found: null",
+      # and payload builders naturally produce them for optional fields the
+      # caller left unset. Doing this at the boundary means no endpoint, present
+      # or future, can forget it.
+      #
+      # @param payload [Object] The payload about to be serialised
+      # @return [Object] The payload without nil entries
+      def compact_payload(payload)
+        case payload
+        when Hash
+          payload.each_with_object({}) do |(key, value), result|
+            next if value.nil?
+
+            result[key] = compact_payload(value)
+          end
+        when Array
+          payload.compact.map { |item| compact_payload(item) }
+        else
+          payload
+        end
+      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 +155,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.
+          # 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 +228,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

@@ -4,8 +4,8 @@ module AbacatePay
   module Clients
     # Client for reusable payment links in the AbacatePay API.
     #
-    # A payment link can be paid by many customers independently — mass sales,
-    # raffles, sign-up forms — without creating one checkout per customer.
+    # A payment link can be paid by many customers independently, mass sales,
+    # raffles, sign-up forms, without creating one checkout per customer.
     # Use CheckoutClient when each customer needs their own charge.
     class PaymentLinkClient < Client
       URI = "payment-links"
@@ -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/store_client.rb

@@ -12,7 +12,9 @@ module AbacatePay
 
       # @return [Resources::Store]
       def get
-        response = request("GET", "store/get")
+        # The API serves this as `stores/get`, plural, even though the reference
+        # documents `store/get`. The singular path answers HTTP 400.
+        response = request("GET", "stores/get")
         Resources::Store.new(response)
       end
 

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
 
@@ -55,12 +45,14 @@ module AbacatePay
       # @param id [String] QR code ID (dev mode only)
       # @return [Resources::Transparents]
       def simulate_payment(id)
-        response = request("POST", "simulate-payment", json: { id: id })
+        # The API reads the id from the query string here, like #check. Sending
+        # it only in the body fails with "Expected property 'id'".
+        response = request("POST", "simulate-payment", params: { id: id }, json: {})
         Resources::Transparents.new(response)
       end
 
       # Refunds a transparent payment in full. AbacatePay does not support
-      # partial refunds — the original amount is always returned.
+      # partial refunds, the original amount is always returned.
       #
       # @param id [String] Public charge ID (`pix_char_...`, `card_...`, `char_...`)
       # @return [Resources::Transparents] The refunded charge
@@ -68,6 +60,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
@@ -32,7 +32,7 @@ module AbacatePay
 
       # Registers a new webhook endpoint.
       #
-      # The secret is what AbacatePay signs deliveries with — pass the same
+      # The secret is what AbacatePay signs deliveries with, pass the same
       # value to {AbacatePay::Webhooks.construct_event} when handling them.
       #
       # @param name [String] Identifying name

data/lib/abacate_pay/clients.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Client must load first — every other client inherits from it.
+# Client must load first: every other client inherits from it.
 require "abacate_pay/clients/client"
 
 require "abacate_pay/clients/billing_client"

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,15 +21,29 @@ 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
 
-    # @deprecated The environment is determined by the API key itself — keys
+    # @deprecated The environment is determined by the API key itself, keys
     #   created in Dev mode produce simulated transactions, production keys
     #   produce real ones. This setting has never had any effect and is kept
     #   only so existing initializers keep loading.