abacatepay-ruby 0.1.0 → 1.1.0

data/lib/abacate_pay/clients/pix_client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for outbound PIX transfers in the AbacatePay API.
+    #
+    # Transfers are sent to a PIX key; see Enums::Pix::KeyTypes for the
+    # accepted key formats.
+    class PixClient < Client
+      URI = "pix"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::PixTransfers>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::PixTransfers)
+      end
+
+      # @param id [String] PIX transfer ID
+      # @return [Resources::PixTransfers]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::PixTransfers.new(response)
+      end
+
+      # Sends a PIX transfer to an external key.
+      # Named send_pix to avoid conflict with Ruby's Object#send.
+      #
+      # @param data [Resources::PixTransfers]
+      # @return [Resources::PixTransfers]
+      def send_pix(data)
+        response = request("POST", "send", json: {
+                             amount: data.amount,
+                             externalId: data.external_id,
+                             description: data.description,
+                             key: data.key,
+                             keyType: data.key_type
+                           })
+        Resources::PixTransfers.new(response)
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/product_client.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for the product catalogue in the AbacatePay API.
+    #
+    # Products are the line items referenced by billings and checkouts.
+    class ProductClient < Client
+      URI = "products"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Products>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::Products)
+      end
+
+      # @param id [String] Product ID or externalId
+      # @return [Resources::Products]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::Products.new(response)
+      end
+
+      # @param data [Resources::Products]
+      # @return [Resources::Products]
+      def create(data)
+        request_data = {
+          externalId: data.external_id,
+          name: data.name,
+          price: data.price,
+          currency: data.currency || "BRL",
+          description: data.description
+        }
+        request_data[:imageUrl] = data.image_url if data.image_url && !data.image_url.to_s.empty?
+        request_data[:cycle] = data.cycle if data.cycle && !data.cycle.to_s.empty?
+
+        response = request("POST", "create", json: request_data)
+        Resources::Products.new(response)
+      end
+
+      # @param id [String] Product ID
+      # @return [Resources::Products]
+      def delete(id)
+        response = request("POST", "delete", json: { id: id })
+        Resources::Products.new(response)
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/store_client.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for store-level data in the AbacatePay API.
+    #
+    # Exposes the account balance and revenue reporting for a date range.
+    class StoreClient < Client
+      def initialize(client = nil)
+        super("", client)
+      end
+
+      # @return [Resources::Store]
+      def get
+        response = request("GET", "store/get")
+        Resources::Store.new(response)
+      end
+
+      # @return [Hash] Merchant info
+      def merchant_info
+        request("GET", "public-mrr/merchant-info")
+      end
+
+      # @return [Hash] MRR metrics
+      def mrr
+        request("GET", "public-mrr/mrr")
+      end
+
+      # @param start_date [String] Start date (YYYY-MM-DD)
+      # @param end_date [String] End date (YYYY-MM-DD)
+      # @return [Hash] Revenue data
+      def revenue(start_date:, end_date:)
+        request("GET", "public-mrr/revenue", params: {
+                  startDate: start_date,
+                  endDate: end_date
+                })
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients/subscription_client.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for recurring subscriptions in the AbacatePay API.
+    #
+    # See Enums::Products::Cycles for the supported billing cycles.
+    class SubscriptionClient < Client
+      URI = "subscriptions"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Subscriptions>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::Subscriptions)
+      end
+
+      # @param data [Resources::Subscriptions]
+      # @return [Resources::Subscriptions]
+      def create(data)
+        request_data = {
+          methods: data.methods,
+          externalId: data.external_id,
+          customerId: data.customer&.id,
+          items: data.products&.map do |product|
+            {
+              externalId: product.external_id,
+              name: product.name,
+              description: product.description,
+              quantity: product.quantity,
+              price: product.price
+            }
+          end
+        }
+
+        response = request("POST", "create", json: request_data)
+        Resources::Subscriptions.new(response)
+      end
+
+      # Cancels an active subscription immediately. Pending future instalments
+      # are cancelled along with it.
+      #
+      # @param id [String] The subscription ID (`subs_...`)
+      # @return [Resources::Subscriptions] The cancelled subscription
+      def cancel(id)
+        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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Clients
+    # Client for transparent PIX checkout in the AbacatePay API.
+    #
+    # Transparent checkout returns the QR code and copy-and-paste
+    # payload directly, so the payment stays inside your own UI.
+    class TransparentClient < Client
+      URI = "transparents"
+
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional pagination params (after, before, limit)
+      # @return [Array<Resources::Transparents>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::Transparents)
+      end
+
+      # Creates a transparent charge.
+      #
+      # @param data [Resources::Transparents] The charge to create
+      # @param method [String] "PIX" or "BOLETO"
+      # @return [Resources::Transparents]
+      # @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
+
+      # @param id [String] QR code ID
+      # @return [Resources::Transparents]
+      def check(id)
+        response = request("GET", "check", params: { id: id })
+        Resources::Transparents.new(response)
+      end
+
+      # @param id [String] QR code ID (dev mode only)
+      # @return [Resources::Transparents]
+      def simulate_payment(id)
+        response = request("POST", "simulate-payment", json: { id: id })
+        Resources::Transparents.new(response)
+      end
+
+      # Refunds a transparent payment in full. AbacatePay does not support
+      # partial refunds — the original amount is always returned.
+      #
+      # @param id [String] Public charge ID (`pix_char_...`, `card_...`, `char_...`)
+      # @return [Resources::Transparents] The refunded charge
+      def refund(id)
+        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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module AbacatePay
+  module Clients
+    # Client for managing webhook endpoint registrations in the AbacatePay API.
+    #
+    # This manages *where* AbacatePay delivers events. To verify and parse an
+    # inbound delivery, use {AbacatePay::Webhooks.construct_event}.
+    class WebhookClient < Client
+      URI = "webhooks"
+
+      # @param client [Faraday::Connection, nil] Optional Faraday client
+      def initialize(client = nil)
+        super(URI, client)
+      end
+
+      # @param params [Hash] Optional params (limit, after, before, startDate, endDate)
+      # @return [Array<Resources::WebhookEndpoints>]
+      def list(**params)
+        response = request("GET", "list", params: params.empty? ? nil : params)
+        build_list(response, Resources::WebhookEndpoints)
+      end
+
+      # @param id [String] The webhook ID
+      # @return [Resources::WebhookEndpoints]
+      def get(id)
+        response = request("GET", "get", params: { id: id })
+        Resources::WebhookEndpoints.new(response)
+      end
+
+      # Registers a new webhook endpoint.
+      #
+      # 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
+      # @param endpoint [String] HTTPS URL that will receive the events
+      # @param secret [String] Signing secret
+      # @param events [Array<String>] Event types to subscribe to
+      # @return [Resources::WebhookEndpoints] The created webhook
+      # @raise [ArgumentError] if the endpoint is not an HTTPS URL
+      def create(name:, endpoint:, secret:, events:)
+        raise ArgumentError, "endpoint must be an HTTPS URL, got #{endpoint.inspect}" unless https_url?(endpoint)
+        raise ArgumentError, "events must not be empty" if Array(events).empty?
+
+        response = request("POST", "create", json: {
+                             name: name,
+                             endpoint: endpoint,
+                             secret: secret,
+                             events: Array(events)
+                           })
+        Resources::WebhookEndpoints.new(response)
+      end
+
+      # @param id [String] The webhook ID
+      # @return [Resources::WebhookEndpoints] The deleted webhook
+      def delete(id)
+        response = request("POST", "delete", json: { id: id })
+        Resources::WebhookEndpoints.new(response)
+      end
+
+      private
+
+      # AbacatePay only delivers to HTTPS endpoints; failing here beats a
+      # confusing rejection after the round trip.
+      #
+      # The class-level URI constant shadows Ruby's URI module inside this
+      # class, so the global scope operator is required.
+      #
+      # @param value [String] The candidate URL
+      # @return [Boolean]
+      def https_url?(value)
+        uri = ::URI::DEFAULT_PARSER.parse(value.to_s)
+        uri.is_a?(::URI::HTTPS) && !uri.host.nil?
+      rescue ::URI::InvalidURIError
+        false
+      end
+    end
+  end
+end

data/lib/abacate_pay/clients.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Client must load first — every other client inherits from it.
+require "abacate_pay/clients/client"
+
+require "abacate_pay/clients/billing_client"
+require "abacate_pay/clients/checkout_client"
+require "abacate_pay/clients/coupon_client"
+require "abacate_pay/clients/customer_client"
+require "abacate_pay/clients/payment_link_client"
+require "abacate_pay/clients/payout_client"
+require "abacate_pay/clients/pix_client"
+require "abacate_pay/clients/product_client"
+require "abacate_pay/clients/store_client"
+require "abacate_pay/clients/subscription_client"
+require "abacate_pay/clients/transparent_client"
+require "abacate_pay/clients/webhook_client"
+
+module AbacatePay
+  # The Clients module contains all API client implementations
+  # for interacting with the AbacatePay API endpoints.
+  module Clients
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  # Configuration class for the AbacatePay SDK
+  #
+  # This class handles all configuration options for the SDK, including
+  # API credentials and request behaviour.
+  #
+  # @api public
+  class Configuration
+    # 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
+    attr_accessor :api_token
+
+    # @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
+    #   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.
+    # @return [nil]
+    attr_reader :environment
+
+    # @deprecated See {#environment}.
+    # @param value [Symbol] Ignored
+    # @return [void]
+    def environment=(value)
+      @environment = value
+      warn "[DEPRECATION] AbacatePay config.environment has no effect and will be removed. " \
+           "The environment is determined by the API key: Dev mode keys simulate transactions, " \
+           "production keys do not."
+    end
+
+    # Validates the configuration
+    #
+    # @raise [ConfigurationError] if any required settings are missing or invalid
+    # @return [void]
+    #
+    # @api public
+    def validate!
+      raise ConfigurationError, "API token is required" if api_token.nil?
+      raise ConfigurationError, "API token must not be empty" if api_token.to_s.strip.empty?
+    end
+
+    # Gets the base API URL
+    #
+    # @return [String] The base API URL
+    #
+    # @api public
+    def api_url
+      API_BASE_URL
+    end
+  end
+end

data/lib/{abacatepay/enums/billing → abacate_pay/enums/billings}/frequencies.rb

@@ -2,7 +2,7 @@
 
 module AbacatePay
   module Enums
-    module Billing
+    module Billings
       # Enumeration defining billing frequencies.
       #
       # This enumeration is used to categorize different payment or billing frequencies.
@@ -10,11 +10,16 @@ module AbacatePay
         # One-time billing.
         # @return [String] Represents a billing that occurs only once
         ONE_TIME = "ONE_TIME"
+        WEEKLY = "WEEKLY"
+        MONTHLY = "MONTHLY"
+        SEMIANNUALLY = "SEMIANNUALLY"
+        ANNUALLY = "ANNUALLY"
+        MULTIPLE_PAYMENTS = "MULTIPLE_PAYMENTS"
 
         # Gets all valid frequency values
         # @return [Array<String>] List of all valid frequencies
         def self.values
-          [ONE_TIME]
+          [ONE_TIME, WEEKLY, MONTHLY, SEMIANNUALLY, ANNUALLY, MULTIPLE_PAYMENTS]
         end
 
         # Validates if a given value is a valid frequency
@@ -30,9 +35,10 @@ module AbacatePay
         # @raise [ArgumentError] if value is invalid
         def self.validate!(value)
           raise ArgumentError, "Invalid frequency: #{value}" unless valid?(value)
+
           value
         end
       end
     end
   end
-end
+end