abacatepay-ruby 0.1.0 → 1.0.0

data/lib/abacate_pay/clients/transparent_client.rb

@@ -0,0 +1,73 @@
+# 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)
+        Array(response).map { |data| Resources::Transparents.new(data) }
+      end
+
+      # @param data [Resources::Transparents]
+      # @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)
+        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
+    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)
+        Array(response).map { |data| Resources::WebhookEndpoints.new(data) }
+      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/configuration.rb

@@ -0,0 +1,67 @@
+# 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 AbacatePay serves. The v1 prefix was retired and now
+    # answers `{"error":"Not found"}` for every path, so there is nothing to
+    # negotiate between.
+    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
+
+    # Initialize a new configuration with default values
+    #
+    # @api public
+    def initialize
+      @timeout = 30
+      @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

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

@@ -2,7 +2,7 @@
 
 module AbacatePay
   module Enums
-    module Billing
+    module Billings
       # Enumeration defining billing methods.
       #
       # This enumeration is used to represent different payment methods available for billing.
@@ -10,11 +10,12 @@ module AbacatePay
         # PIX payment method.
         # @return [String] Represents the PIX payment method, a popular instant payment system in Brazil
         PIX = "PIX"
+        CARD = "CARD"
 
         # Gets all valid method values
         # @return [Array<String>] List of all valid payment methods
         def self.values
-          [PIX]
+          [PIX, CARD]
         end
 
         # Validates if a given value is a valid method
@@ -30,9 +31,10 @@ module AbacatePay
         # @raise [ArgumentError] if value is invalid
         def self.validate!(value)
           raise ArgumentError, "Invalid payment method: #{value}" unless valid?(value)
+
           value
         end
       end
     end
   end
-end
+end

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

@@ -2,7 +2,7 @@
 
 module AbacatePay
   module Enums
-    module Billing
+    module Billings
       # Enumeration defining billing statuses.
       #
       # This enumeration is used to represent the various statuses that a billing process can have.
@@ -46,9 +46,10 @@ module AbacatePay
         # @raise [ArgumentError] if value is invalid
         def self.validate!(value)
           raise ArgumentError, "Invalid status: #{value}" unless valid?(value)
+
           value
         end
       end
     end
   end
-end
+end

data/lib/abacate_pay/enums/checkouts/statuses.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Enums
+    module Checkouts
+      class Statuses
+        PENDING = "PENDING"
+        EXPIRED = "EXPIRED"
+        CANCELLED = "CANCELLED"
+        PAID = "PAID"
+        REFUNDED = "REFUNDED"
+
+        def self.values
+          [PENDING, EXPIRED, CANCELLED, PAID, REFUNDED]
+        end
+
+        def self.valid?(value)
+          values.include?(value)
+        end
+
+        def self.validate!(value)
+          raise ArgumentError, "Invalid checkout status: #{value}" unless valid?(value)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/abacate_pay/enums/coupons/discount_kinds.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Enums
+    module Coupons
+      class DiscountKinds
+        PERCENTAGE = "PERCENTAGE"
+        FIXED = "FIXED"
+
+        def self.values
+          [PERCENTAGE, FIXED]
+        end
+
+        def self.valid?(value)
+          values.include?(value)
+        end
+
+        def self.validate!(value)
+          raise ArgumentError, "Invalid discount kind: #{value}" unless valid?(value)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/abacate_pay/enums/coupons/statuses.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Enums
+    module Coupons
+      class Statuses
+        ACTIVE = "ACTIVE"
+        INACTIVE = "INACTIVE"
+        EXPIRED = "EXPIRED"
+
+        def self.values
+          [ACTIVE, INACTIVE, EXPIRED]
+        end
+
+        def self.valid?(value)
+          values.include?(value)
+        end
+
+        def self.validate!(value)
+          raise ArgumentError, "Invalid coupon status: #{value}" unless valid?(value)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/abacate_pay/enums/payouts/statuses.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Enums
+    module Payouts
+      class Statuses
+        PENDING = "PENDING"
+        COMPLETE = "COMPLETE"
+        CANCELLED = "CANCELLED"
+        EXPIRED = "EXPIRED"
+        REFUNDED = "REFUNDED"
+
+        def self.values
+          [PENDING, COMPLETE, CANCELLED, EXPIRED, REFUNDED]
+        end
+
+        def self.valid?(value)
+          values.include?(value)
+        end
+
+        def self.validate!(value)
+          raise ArgumentError, "Invalid payout status: #{value}" unless valid?(value)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/abacate_pay/enums/pix/key_types.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Enums
+    module Pix
+      class KeyTypes
+        CPF = "CPF"
+        CNPJ = "CNPJ"
+        PHONE = "PHONE"
+        EMAIL = "EMAIL"
+        RANDOM = "RANDOM"
+        BR_CODE = "BR_CODE"
+
+        def self.values
+          [CPF, CNPJ, PHONE, EMAIL, RANDOM, BR_CODE]
+        end
+
+        def self.valid?(value)
+          values.include?(value)
+        end
+
+        def self.validate!(value)
+          raise ArgumentError, "Invalid PIX key type: #{value}" unless valid?(value)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/abacate_pay/enums/products/cycles.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Enums
+    module Products
+      class Cycles
+        WEEKLY = "WEEKLY"
+        MONTHLY = "MONTHLY"
+        SEMIANNUALLY = "SEMIANNUALLY"
+        ANNUALLY = "ANNUALLY"
+
+        def self.values
+          [WEEKLY, MONTHLY, SEMIANNUALLY, ANNUALLY]
+        end
+
+        def self.valid?(value)
+          values.include?(value)
+        end
+
+        def self.validate!(value)
+          raise ArgumentError, "Invalid product cycle: #{value}" unless valid?(value)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/abacate_pay/enums/transfers/statuses.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Enums
+    module Transfers
+      class Statuses
+        PENDING = "PENDING"
+        COMPLETE = "COMPLETE"
+        CANCELLED = "CANCELLED"
+        EXPIRED = "EXPIRED"
+        REFUNDED = "REFUNDED"
+        FAILED = "FAILED"
+
+        def self.values
+          [PENDING, COMPLETE, CANCELLED, EXPIRED, REFUNDED, FAILED]
+        end
+
+        def self.valid?(value)
+          values.include?(value)
+        end
+
+        def self.validate!(value)
+          raise ArgumentError, "Invalid transfer status: #{value}" unless valid?(value)
+
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Enums
+    module Webhooks
+      class EventTypes
+        CHECKOUT_COMPLETED = "checkout.completed"
+        CHECKOUT_REFUNDED = "checkout.refunded"
+        CHECKOUT_DISPUTED = "checkout.disputed"
+        TRANSPARENT_COMPLETED = "transparent.completed"
+        TRANSPARENT_REFUNDED = "transparent.refunded"
+        TRANSPARENT_DISPUTED = "transparent.disputed"
+        SUBSCRIPTION_COMPLETED = "subscription.completed"
+        SUBSCRIPTION_RENEWED = "subscription.renewed"
+        SUBSCRIPTION_CANCELLED = "subscription.cancelled"
+        TRANSFER_COMPLETED = "transfer.completed"
+        TRANSFER_FAILED = "transfer.failed"
+        PAYOUT_COMPLETED = "payout.completed"
+        PAYOUT_FAILED = "payout.failed"
+
+        def self.values
+          [
+            CHECKOUT_COMPLETED, CHECKOUT_REFUNDED, CHECKOUT_DISPUTED,
+            TRANSPARENT_COMPLETED, TRANSPARENT_REFUNDED, TRANSPARENT_DISPUTED,
+            SUBSCRIPTION_COMPLETED, SUBSCRIPTION_RENEWED, SUBSCRIPTION_CANCELLED,
+            TRANSFER_COMPLETED, TRANSFER_FAILED,
+            PAYOUT_COMPLETED, PAYOUT_FAILED
+          ]
+        end
+
+        def self.valid?(value)
+          values.include?(value)
+        end
+
+        def self.validate!(value)
+          raise ArgumentError, "Invalid webhook event type: #{value}" unless valid?(value)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/abacate_pay/enums.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "abacate_pay/enums/billings/frequencies"
+require "abacate_pay/enums/billings/methods"
+require "abacate_pay/enums/billings/statuses"
+require "abacate_pay/enums/checkouts/statuses"
+require "abacate_pay/enums/coupons/discount_kinds"
+require "abacate_pay/enums/coupons/statuses"
+require "abacate_pay/enums/payouts/statuses"
+require "abacate_pay/enums/pix/key_types"
+require "abacate_pay/enums/products/cycles"
+require "abacate_pay/enums/transfers/statuses"
+require "abacate_pay/enums/webhooks/event_types"
+
+module AbacatePay
+  # The Enums module contains all enumeration classes used
+  # throughout the AbacatePay SDK.
+  module Enums
+  end
+end

data/lib/{abacatepay/resources/billing → abacate_pay/resources/billings}/metadata.rb

@@ -2,7 +2,7 @@
 
 module AbacatePay
   module Resources
-    module Billing
+    class Billings
       # Represents metadata for a billing resource in the AbacatePay system.
       #
       # This class contains additional information related to a billing resource,
@@ -23,13 +23,7 @@ module AbacatePay
         def initialize(data)
           fill(data)
         end
-
-        protected
-
-        def to_hash
-          super
-        end
       end
     end
   end
-end
+end

data/lib/{abacatepay/resources/billing → abacate_pay/resources/billings}/product.rb

@@ -2,7 +2,7 @@
 
 module AbacatePay
   module Resources
-    module Billing
+    class Billings
       # Represents a product in a billing resource in the AbacatePay system.
       #
       # This class contains information about a product, such as its identifier,
@@ -32,13 +32,7 @@ module AbacatePay
         def initialize(data)
           fill(data)
         end
-
-        protected
-
-        def to_hash
-          super
-        end
       end
     end
   end
-end
+end