abacatepay-ruby 0.1.0 → 1.1.0

data/abacatepay-ruby.gemspec

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "lib/abacatepay/version"
+require_relative "lib/abacate_pay/version"
 
 Gem::Specification.new do |spec|
   spec.name = "abacatepay-ruby"
@@ -8,17 +8,21 @@ Gem::Specification.new do |spec|
   spec.authors = ["Matheus Cardoso"]
   spec.email = ["mathuscardoso@gmail.com"]
 
-  spec.summary = "AbacatePay Ruby on Rails SDK for you to start receiving payments in seconds"
-  spec.description = "The easiest way to integrate your Ruby on Rails SDK base code to AbacatePay Gateway with support to coroutines."
+  spec.summary = "AbacatePay Ruby SDK for you to start receiving payments in seconds"
+  spec.description = "The easiest way to integrate your Ruby application with AbacatePay Gateway " \
+                     "for payments, subscriptions, PIX transfers, and more."
   spec.homepage = "https://www.abacatepay.com/"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.6.0"
+  # faraday 2.x requires Ruby >= 3.0 and the pinned Bundler requires >= 3.2.
+  # 3.2 is the oldest version exercised by CI; 2.6 was never actually installable.
+  spec.required_ruby_version = ">= 3.2.0"
 
-  # spec.metadata["allowed_push_host"] = "https://github.com/AbacatePay/abacatepay-ruby-sdk"
+  # spec.metadata["allowed_push_host"] = "https://rubygems.pkg.github.com/AbacatePay"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/AbacatePay/abacatepay-ruby-sdk"
   spec.metadata["changelog_uri"] = "https://github.com/AbacatePay/abacatepay-ruby-sdk/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -33,14 +37,17 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Runtime dependencies
-  spec.add_dependency "rails", "~> 7.0", ">= 7.0.0"
-  spec.add_dependency "faraday", "~> 2.9"
+  # >= 2.14.3 excludes CVE-2026-54297 (stack-exhaustion DoS in
+  # 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 "rspec-rails", "~> 6.0"
+  spec.add_development_dependency "bundler-audit", "~> 0.9"
+  spec.add_development_dependency "rspec", "~> 3.12"
   spec.add_development_dependency "rubocop", "~> 1.57"
-  spec.add_development_dependency "rubocop-rails", "~> 2.22"
-  spec.add_development_dependency "rubocop-rspec", "~> 2.25"
+  spec.add_development_dependency "rubocop-rspec", "~> 3.0"
   spec.add_development_dependency "simplecov", "~> 0.22"
 
   # For more information and examples about making a new gem, check out our

data/lib/abacate_pay/clients/billing_client.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # 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"
+
+      # @param client [Faraday::Connection, nil] Optional Faraday client for custom configurations
+      # @deprecated Use {CheckoutClient} instead
+      def initialize(client = nil)
+        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
+
+      # Retrieves a list of billings
+      #
+      # @return [Array<Resources::Billing>] Array of Billing objects
+      def list
+        response = request("GET", "list")
+        build_list(response, Resources::Billings)
+      end
+
+      # Creates a new billing
+      #
+      # @param data [Resources::Billing] The billing data to be sent for creation
+      # @return [Resources::Billing] The created Billing object
+      def create(data)
+        response = request("POST", "create", json: build_create_payload(data))
+        Resources::Billings.new(response)
+      end
+
+      private
+
+      # Builds the create-billing request payload
+      #
+      # @param data [Resources::Billings] The billing to serialize
+      # @return [Hash] The request payload
+      def build_create_payload(data)
+        {
+          frequency: data.frequency,
+          methods: data.methods,
+          returnUrl: data.metadata&.return_url,
+          completionUrl: data.metadata&.completion_url,
+          items: data.products&.map { |product| serialize_product(product) }
+        }.merge(serialize_customer(data.customer))
+      end
+
+      # @param product [Resources::Billings::Product] The product to serialize
+      # @return [Hash] The product payload
+      def serialize_product(product)
+        {
+          externalId: product.external_id,
+          name: product.name,
+          description: product.description,
+          quantity: product.quantity,
+          price: product.price
+        }
+      end
+
+      # An existing customer is referenced by id; a new one is sent inline.
+      #
+      # @param customer [Resources::Customers, nil] The customer to serialize
+      # @return [Hash] The customer payload fragment
+      def serialize_customer(customer)
+        return { customerId: customer.id } if customer&.id
+
+        {
+          customer: {
+            name: customer&.metadata&.name,
+            email: customer&.metadata&.email,
+            cellphone: customer&.metadata&.cellphone,
+            taxId: customer&.metadata&.tax_id
+          }
+        }
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/checkout_client.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for one-off checkout sessions in the AbacatePay API.
+    #
+    # Checkouts are single-payment links; use SubscriptionClient for
+    # recurring charges.
+    class CheckoutClient < Client
+      URI = "checkouts"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional filtering params (id, externalId, status, email, taxId, after, before, limit)
+      # @return [Array<Resources::Checkouts>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::Checkouts)
+      end
+
+      # @param id [String] Checkout ID
+      # @return [Resources::Checkouts]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Checkouts.new(response)
+      end
+
+      # @param data [Resources::Checkouts]
+      # @return [Resources::Checkouts]
+      def create(data)
+        response = request("POST", "create", json: build_create_payload(data))
+        Resources::Checkouts.new(response)
+      end
+
+      # Refunds a paid checkout in full. AbacatePay does not support partial
+      # refunds — the original amount is always returned.
+      #
+      # @param id [String] Public checkout ID (`bill_...`) or charge ID
+      #   (`char_...`, `pix_char_...`, `card_...`)
+      # @return [Resources::Checkouts] The refunded checkout
+      def refund(id)
+        response = request("POST", "refund", json: { id: id })
+        Resources::Checkouts.new(response)
+      end
+
+      private
+
+      # Builds the create-checkout request payload
+      #
+      # @param data [Resources::Checkouts] The checkout to serialize
+      # @return [Hash] The request payload, with nil entries removed
+      def build_create_payload(data)
+        customer_id = data.customer&.id
+
+        {
+          frequency: data.frequency,
+          methods: data.methods,
+          returnUrl: data.metadata&.return_url,
+          completionUrl: data.metadata&.completion_url,
+          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,
+          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
+end

data/lib/abacate_pay/clients/client.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+
+module AbacatePay
+  module Clients
+    # Client class for interacting with the AbacatePay API.
+    #
+    # 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
+      #
+      # @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, 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
+
+        parsed = JSON.parse(response.body)
+        raise ApiError, "API error: #{parsed["error"]}" if parsed["error"]
+
+        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 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
+      #
+      # @param uri [String] The endpoint URI
+      # @return [Faraday::Connection] Configured Faraday client
+      def build_client(uri)
+        configuration = AbacatePay.configuration!
+        base_url = uri.empty? ? "#{configuration.api_url}/" : "#{configuration.api_url}/#{uri}/"
+
+        Faraday.new(
+          url: base_url,
+          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
+      #
+      # @param error [Faraday::Error] The error to handle
+      # @raise [ApiError] With appropriate error message
+      def handle_request_error(error)
+        error_message = if error.response&.body
+                          response_body = JSON.parse(error.response.body)
+                          response_body["message"] || response_body["error"]
+                        end
+
+        raise ApiError, "Request error: #{error_message || error.message}"
+      rescue JSON::ParserError
+        raise ApiError, "Request error: #{error.message}"
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/coupon_client.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for discount coupons in the AbacatePay API.
+    #
+    # Supports creating, listing, deleting and toggling coupons
+    # between active and inactive.
+    class CouponClient < Client
+      URI = "coupons"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Coupons>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::Coupons)
+      end
+
+      # @param id [String] Coupon ID
+      # @return [Resources::Coupons]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Coupons.new(response)
+      end
+
+      # @param data [Resources::Coupons]
+      # @return [Resources::Coupons]
+      def create(data)
+        response = request("POST", "create", json: {
+                             code: data.code,
+                             discount: data.discount,
+                             discountKind: data.discount_kind,
+                             maxRedeems: data.max_redeems
+                           })
+        Resources::Coupons.new(response)
+      end
+
+      # @param id [String] Coupon ID
+      # @return [Resources::Coupons]
+      def delete(id)
+        response = request("POST", "delete", json: { id: id })
+        Resources::Coupons.new(response)
+      end
+
+      # @param id [String] Coupon ID
+      # @return [Resources::Coupons]
+      def toggle(id)
+        response = request("POST", "toggle", json: { id: id })
+        Resources::Coupons.new(response)
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/customer_client.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client class for managing customer-related operations in the AbacatePay API.
+    class CustomerClient < Client
+      # API endpoint for customer-related operations
+      URI = "customers"
+
+      # @param client [Faraday::Connection, nil] Optional Faraday client for custom configurations
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # Retrieves a list of customers
+      #
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Customers>] Array of Customer objects
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::Customers)
+      end
+
+      # Retrieves a customer by ID
+      #
+      # @param id [String] The customer ID
+      # @return [Resources::Customers] The Customer object
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Customers.new(response)
+      end
+
+      # Creates a new customer
+      #
+      # @param data [Resources::Customers] The customer data to be sent for creation
+      # @return [Resources::Customers] The created Customer object
+      def create(data)
+        response = request("POST", "create", json: {
+                             name: data.metadata&.name,
+                             email: data.metadata&.email,
+                             cellphone: data.metadata&.cellphone,
+                             taxId: data.metadata&.tax_id
+                           })
+
+        Resources::Customers.new(response)
+      end
+
+      # Deletes a customer
+      #
+      # @param id [String] The customer ID
+      # @return [Resources::Customers] The deleted Customer object
+      def delete(id)
+        response = request("POST", "delete", json: { id: id })
+        Resources::Customers.new(response)
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/payment_link_client.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+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.
+    # Use CheckoutClient when each customer needs their own charge.
+    class PaymentLinkClient < Client
+      URI = "payment-links"
+
+      # Payment links are always multi-payment by definition; the API rejects
+      # any other frequency on this endpoint.
+      FREQUENCY = "MULTIPLE_PAYMENTS"
+
+      # @param client [Faraday::Connection, nil] Optional Faraday client
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Checkouts>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::Checkouts)
+      end
+
+      # @param id [String] The payment link ID
+      # @return [Resources::Checkouts]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Checkouts.new(response)
+      end
+
+      # Creates a reusable payment link.
+      #
+      # @param data [Resources::Checkouts] The link definition
+      # @return [Resources::Checkouts] The created link, with `url` populated
+      def create(data)
+        response = request("POST", "create", json: build_create_payload(data))
+        Resources::Checkouts.new(response)
+      end
+
+      # Refunds a payment made through the link.
+      #
+      # @param id [String] Public charge ID
+      # @return [Resources::Checkouts] The refunded charge
+      def refund(id)
+        response = request("POST", "refund", json: { id: id })
+        Resources::Checkouts.new(response)
+      end
+
+      private
+
+      # @param data [Resources::Checkouts] The link to serialize
+      # @return [Hash] The request payload, with nil entries removed
+      def build_create_payload(data)
+        {
+          frequency: FREQUENCY,
+          methods: data.methods,
+          items: data.products&.map { |product| { id: product.external_id, quantity: product.quantity } },
+          externalId: data.external_id,
+          returnUrl: data.metadata&.return_url,
+          completionUrl: data.metadata&.completion_url,
+          coupons: data.coupons
+        }.compact
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/payout_client.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for payouts (withdrawals) in the AbacatePay API.
+    #
+    # Payouts move settled balance out of the store account.
+    class PayoutClient < Client
+      URI = "payouts"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Payouts>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::Payouts)
+      end
+
+      # @param id [String] Payout ID
+      # @return [Resources::Payouts]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Payouts.new(response)
+      end
+
+      # @param data [Resources::Payouts]
+      # @return [Resources::Payouts]
+      def create(data)
+        response = request("POST", "create", json: {
+                             amount: data.amount,
+                             externalId: data.external_id,
+                             description: data.description
+                           })
+        Resources::Payouts.new(response)
+      end
+    end
+  end
+end