abacatepay-ruby 0.1.0 → 1.0.0

data/lib/abacate_pay/resources/webhook_endpoints.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Resources
+    # Represents a registered webhook endpoint in the AbacatePay system.
+    #
+    # This is the endpoint *registration* — the URL AbacatePay delivers events
+    # to. For verifying and parsing an inbound delivery, see {AbacatePay::Webhooks}.
+    class WebhookEndpoints < Resource
+      # @return [String, nil] Webhook ID
+      attr_accessor :id
+
+      # @return [String, nil] Identifying name
+      attr_accessor :name
+
+      # @return [String, nil] HTTPS URL that receives the events
+      attr_accessor :endpoint
+
+      # @return [Array<String>, nil] Event types this endpoint subscribes to
+      attr_accessor :events
+
+      # @return [Boolean, nil] Whether the endpoint is active
+      attr_accessor :active
+
+      # @return [DateTime, nil] Creation timestamp
+      attr_accessor :created_at
+
+      # @return [DateTime, nil] Last update timestamp
+      attr_accessor :updated_at
+
+      # @param data [Hash] The webhook properties
+      def initialize(data)
+        fill(data)
+      end
+
+      private
+
+      # @param property [String] The property name
+      # @param value [Object] The raw value
+      # @return [Object] The processed value
+      def process_value(property, value)
+        case property
+        when "created_at", "updated_at" then initialize_date_time(value)
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/abacate_pay/resources.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Resource must load first — every other resource inherits from it.
+require "abacate_pay/resources/resource"
+
+require "abacate_pay/resources/billings"
+require "abacate_pay/resources/billings/metadata"
+require "abacate_pay/resources/billings/product"
+require "abacate_pay/resources/checkouts"
+require "abacate_pay/resources/coupons"
+require "abacate_pay/resources/customers"
+require "abacate_pay/resources/customers/metadata"
+require "abacate_pay/resources/payouts"
+require "abacate_pay/resources/pix_transfers"
+require "abacate_pay/resources/products"
+require "abacate_pay/resources/store"
+require "abacate_pay/resources/store/balance"
+require "abacate_pay/resources/subscriptions"
+require "abacate_pay/resources/transparents"
+require "abacate_pay/resources/webhook_endpoints"
+
+module AbacatePay
+  # The Resources module contains all resource classes that
+  # represent the various entities in the AbacatePay system.
+  module Resources
+  end
+end

data/lib/{abacatepay → abacate_pay}/version.rb

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

data/lib/abacate_pay/webhooks/event.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Webhooks
+    # A parsed webhook event.
+    #
+    # Accepts both the camelCase and snake_case spellings AbacatePay has used
+    # for the envelope fields, so older and newer webhook versions both parse.
+    class Event
+      attr_reader :type, :data, :created_at
+
+      # @param data [Hash] Parsed webhook payload
+      def initialize(data)
+        @type = data["event"] || data["type"]
+        @data = data["data"]
+        @created_at = data["createdAt"] || data["created_at"]
+      end
+    end
+  end
+end

data/lib/abacate_pay/webhooks.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module AbacatePay
+  # Verification and parsing of inbound AbacatePay webhooks.
+  #
+  # Webhook bodies are the least trusted input an integration handles: they
+  # arrive unauthenticated on a public endpoint. Every entry point here treats
+  # missing, malformed, and hostile input as an expected case and surfaces it
+  # as a typed SDK error, never as a raw parser or NoMethodError.
+  module Webhooks
+    # Raised when a webhook signature is missing, malformed, or does not match.
+    class SignatureError < AbacatePay::Error; end
+
+    # Raised when a webhook body is not a JSON object the SDK can interpret.
+    class PayloadError < AbacatePay::Error; end
+
+    # Verifies a webhook signature using HMAC-SHA256.
+    #
+    # @param payload [String] The raw request body
+    # @param signature [String] The X-Webhook-Signature header value
+    # @param secret [String] Your webhook secret/public key
+    # @return [true] if signature is valid
+    # @raise [SignatureError] if the signature is missing or invalid
+    def self.verify!(payload:, signature:, secret:)
+      raise SignatureError, "Missing webhook signature" if signature.nil? || signature.to_s.empty?
+      raise SignatureError, "Missing webhook secret" if secret.nil? || secret.to_s.empty?
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, payload.to_s)
+      raise SignatureError, "Invalid webhook signature" unless secure_compare(expected, signature.to_s)
+
+      true
+    end
+
+    # Checks if a webhook signature is valid.
+    #
+    # Never raises for untrusted input — a missing header, an empty secret, or a
+    # forged signature all return false.
+    #
+    # @param payload [String] The raw request body
+    # @param signature [String] The X-Webhook-Signature header value
+    # @param secret [String] Your webhook secret/public key
+    # @return [Boolean]
+    def self.valid?(payload:, signature:, secret:)
+      verify!(payload: payload, signature: signature, secret: secret)
+      true
+    rescue SignatureError
+      false
+    end
+
+    # Parses a webhook payload into an Event object.
+    #
+    # Prefer {construct_event}, which refuses to parse a body it has not
+    # authenticated first.
+    #
+    # @param payload [String] The raw JSON request body
+    # @return [Event] The parsed event
+    # @raise [PayloadError] if the body is not a JSON object
+    def self.parse(payload)
+      data = JSON.parse(payload.to_s)
+      raise PayloadError, "Expected a JSON object, got #{data.class}" unless data.is_a?(Hash)
+
+      Event.new(data)
+    rescue JSON::ParserError => e
+      raise PayloadError, "Malformed webhook payload: #{e.message}"
+    end
+
+    # Verifies a webhook signature and parses the body in one step.
+    #
+    # This is the only entry point that cannot be used to act on an
+    # unauthenticated payload, and is what integrations should call.
+    #
+    # @param payload [String] The raw request body
+    # @param signature [String] The X-Webhook-Signature header value
+    # @param secret [String] Your webhook secret/public key
+    # @return [Event] The verified, parsed event
+    # @raise [SignatureError] if the signature is missing or invalid
+    # @raise [PayloadError] if the body is not a JSON object
+    def self.construct_event(payload:, signature:, secret:)
+      verify!(payload: payload, signature: signature, secret: secret)
+      parse(payload)
+    end
+
+    # Constant-time comparison to prevent timing attacks.
+    #
+    # @param expected [String] The signature computed from the payload
+    # @param actual [String] The signature supplied by the caller
+    # @return [Boolean]
+    def self.secure_compare(expected, actual)
+      return false unless expected.bytesize == actual.bytesize
+
+      OpenSSL.fixed_length_secure_compare(expected, actual)
+    end
+    private_class_method :secure_compare
+  end
+end
+
+require "abacate_pay/webhooks/event"

data/lib/abacate_pay.rb

@@ -10,12 +10,26 @@ module AbacatePay
   class ApiError < Error; end
 
   class << self
-    # Gets or sets the global configuration
-    attr_accessor :configuration
+    # @return [Configuration, nil] The global configuration
+    attr_reader :configuration
+
+    # Replacing the configuration invalidates every memoized client, so a
+    # client built against the previous credentials can never outlive them.
+    #
+    # @param value [Configuration, nil] The new configuration
+    # @return [void]
+    def configuration=(value)
+      @configuration = value
+      reset_clients!
+    end
   end
 
   # Configures the SDK
   #
+  # Memoized clients are discarded so a token changed at runtime takes effect
+  # immediately. Without this, a client built before the change keeps sending
+  # the old bearer token.
+  #
   # @example
   #   AbacatePay.configure do |config|
   #     config.api_token = "your-token-here"
@@ -28,6 +42,7 @@ module AbacatePay
     self.configuration ||= Configuration.new
     yield(configuration)
     configuration.validate!
+    reset_clients!
   end
 
   # Resets the configuration to defaults
@@ -35,8 +50,100 @@ module AbacatePay
   # @return [void]
   def self.reset!
     self.configuration = Configuration.new
+    reset_clients!
+  end
+
+  # Returns the configuration, refusing to proceed if the SDK was never set up.
+  #
+  # Forgetting to call {configure} is the most common first-run mistake; without
+  # this the failure surfaces as `NoMethodError: undefined method 'api_url' for
+  # nil` from deep inside the client.
+  #
+  # @return [Configuration] The active configuration
+  # @raise [ConfigurationError] if {configure} has not been called
+  def self.configuration!
+    configuration || raise(
+      ConfigurationError,
+      "AbacatePay is not configured. Call AbacatePay.configure { |c| c.api_token = ENV['ABACATEPAY_API_KEY'] } first."
+    )
+  end
+
+  # Discards every memoized client so the next call rebuilds from current config
+  #
+  # @return [void]
+  def self.reset_clients!
+    @clients = {}
+  end
+
+  # @return [Hash{Symbol => Clients::Client}] Memoized clients, keyed by name
+  def self.clients
+    @clients ||= {}
+  end
+  private_class_method :clients
+
+  # @return [Clients::CustomerClient] Customer API client
+  def self.customers
+    clients[:customers] ||= Clients::CustomerClient.new
+  end
+
+  # @return [Clients::ProductClient] Product API client
+  def self.products
+    clients[:products] ||= Clients::ProductClient.new
+  end
+
+  # @return [Clients::CouponClient] Coupon API client
+  def self.coupons
+    clients[:coupons] ||= Clients::CouponClient.new
+  end
+
+  # @return [Clients::CheckoutClient] Checkout API client
+  def self.checkouts
+    clients[:checkouts] ||= Clients::CheckoutClient.new
+  end
+
+  # @return [Clients::SubscriptionClient] Subscription API client
+  def self.subscriptions
+    clients[:subscriptions] ||= Clients::SubscriptionClient.new
+  end
+
+  # @return [Clients::TransparentClient] PIX Transparent API client
+  def self.transparents
+    clients[:transparents] ||= Clients::TransparentClient.new
+  end
+
+  # @return [Clients::PixClient] PIX Transfer API client
+  def self.pix
+    clients[:pix] ||= Clients::PixClient.new
+  end
+
+  # @return [Clients::PayoutClient] Payout API client
+  def self.payouts
+    clients[:payouts] ||= Clients::PayoutClient.new
+  end
+
+  # @return [Clients::StoreClient] Store API client
+  def self.store
+    clients[:store] ||= Clients::StoreClient.new
+  end
+
+  # @return [Clients::PaymentLinkClient] Reusable payment link API client
+  def self.payment_links
+    clients[:payment_links] ||= Clients::PaymentLinkClient.new
+  end
+
+  # Webhook *endpoint registration*. To verify an inbound delivery, use
+  # {AbacatePay::Webhooks.construct_event}.
+  #
+  # @return [Clients::WebhookClient] Webhook management API client
+  def self.webhook_endpoints
+    clients[:webhook_endpoints] ||= Clients::WebhookClient.new
   end
 end
 
-# Autoload all components
-Dir[File.join(__dir__, "abacate_pay", "**", "*.rb")].sort.each { |file| require file }
+# Components are required explicitly, in dependency order. A glob would load
+# clients/billing_client.rb before clients/client.rb and blow up on the
+# superclass, and it silently swallows files that were never wired up.
+require "abacate_pay/enums"
+require "abacate_pay/resources"
+require "abacate_pay/clients"
+require "abacate_pay/webhooks"

metadata

@@ -1,63 +1,62 @@
 --- !ruby/object:Gem::Specification
 name: abacatepay-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Matheus Cardoso
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-13 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2.14'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 2.14.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2.14'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 2.14.3
 - !ruby/object:Gem::Dependency
-  name: faraday
+  name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.9'
-  type: :runtime
+        version: '0.9'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.9'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '3.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '3.12'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -72,34 +71,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.57'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.22'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.22'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.25'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.25'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -114,8 +99,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.22'
-description: The easiest way to integrate your Ruby on Rails SDK base code to AbacatePay
-  Gateway with support to coroutines.
+description: The easiest way to integrate your Ruby application with AbacatePay Gateway
+  for payments, subscriptions, PIX transfers, and more.
 email:
 - mathuscardoso@gmail.com
 executables: []
@@ -131,24 +116,53 @@ files:
 - Rakefile
 - abacatepay-ruby.gemspec
 - lib/abacate_pay.rb
-- lib/abacatepay/clients.rb
-- lib/abacatepay/clients/billing_client.rb
-- lib/abacatepay/clients/client.rb
-- lib/abacatepay/clients/customer_client.rb
-- lib/abacatepay/configuration.rb
-- lib/abacatepay/enums.rb
-- lib/abacatepay/enums/billing/frequencies.rb
-- lib/abacatepay/enums/billing/methods.rb
-- lib/abacatepay/enums/billing/statuses.rb
-- lib/abacatepay/resources.rb
-- lib/abacatepay/resources/billing.rb
-- lib/abacatepay/resources/billing/metadata.rb
-- lib/abacatepay/resources/billing/product.rb
-- lib/abacatepay/resources/customer.rb
-- lib/abacatepay/resources/customer/metadata.rb
-- lib/abacatepay/resources/resource.rb
-- lib/abacatepay/version.rb
-- sig/abacatepay/rails.rbs
+- lib/abacate_pay/clients.rb
+- lib/abacate_pay/clients/billing_client.rb
+- lib/abacate_pay/clients/checkout_client.rb
+- lib/abacate_pay/clients/client.rb
+- lib/abacate_pay/clients/coupon_client.rb
+- lib/abacate_pay/clients/customer_client.rb
+- lib/abacate_pay/clients/payment_link_client.rb
+- lib/abacate_pay/clients/payout_client.rb
+- lib/abacate_pay/clients/pix_client.rb
+- lib/abacate_pay/clients/product_client.rb
+- lib/abacate_pay/clients/store_client.rb
+- lib/abacate_pay/clients/subscription_client.rb
+- lib/abacate_pay/clients/transparent_client.rb
+- lib/abacate_pay/clients/webhook_client.rb
+- lib/abacate_pay/configuration.rb
+- lib/abacate_pay/enums.rb
+- lib/abacate_pay/enums/billings/frequencies.rb
+- lib/abacate_pay/enums/billings/methods.rb
+- lib/abacate_pay/enums/billings/statuses.rb
+- lib/abacate_pay/enums/checkouts/statuses.rb
+- lib/abacate_pay/enums/coupons/discount_kinds.rb
+- lib/abacate_pay/enums/coupons/statuses.rb
+- lib/abacate_pay/enums/payouts/statuses.rb
+- lib/abacate_pay/enums/pix/key_types.rb
+- lib/abacate_pay/enums/products/cycles.rb
+- lib/abacate_pay/enums/transfers/statuses.rb
+- lib/abacate_pay/enums/webhooks/event_types.rb
+- lib/abacate_pay/resources.rb
+- lib/abacate_pay/resources/billings.rb
+- lib/abacate_pay/resources/billings/metadata.rb
+- lib/abacate_pay/resources/billings/product.rb
+- lib/abacate_pay/resources/checkouts.rb
+- lib/abacate_pay/resources/coupons.rb
+- lib/abacate_pay/resources/customers.rb
+- lib/abacate_pay/resources/customers/metadata.rb
+- lib/abacate_pay/resources/payouts.rb
+- lib/abacate_pay/resources/pix_transfers.rb
+- lib/abacate_pay/resources/products.rb
+- lib/abacate_pay/resources/resource.rb
+- lib/abacate_pay/resources/store.rb
+- lib/abacate_pay/resources/store/balance.rb
+- lib/abacate_pay/resources/subscriptions.rb
+- lib/abacate_pay/resources/transparents.rb
+- lib/abacate_pay/resources/webhook_endpoints.rb
+- lib/abacate_pay/version.rb
+- lib/abacate_pay/webhooks.rb
+- lib/abacate_pay/webhooks/event.rb
 homepage: https://www.abacatepay.com/
 licenses:
 - MIT
@@ -156,7 +170,7 @@ metadata:
   homepage_uri: https://www.abacatepay.com/
   source_code_uri: https://github.com/AbacatePay/abacatepay-ruby-sdk
   changelog_uri: https://github.com/AbacatePay/abacatepay-ruby-sdk/blob/main/CHANGELOG.md
-post_install_message:
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -164,15 +178,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: AbacatePay Ruby on Rails SDK for you to start receiving payments in seconds
+summary: AbacatePay Ruby SDK for you to start receiving payments in seconds
 test_files: []

data/lib/abacatepay/clients/billing_client.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-module AbacatePay
-  module Clients
-    # Client class for managing billing-related operations in the AbacatePay API.
-    class BillingClient < Client
-      # API endpoint for billing-related operations
-      URI = "billing"
-
-      # @param client [Faraday::Connection, nil] Optional Faraday client for custom configurations
-      def initialize(client = nil)
-        super(URI, client)
-      end
-
-      # Retrieves a list of billings
-      #
-      # @return [Array<Resources::Billing>] Array of Billing objects
-      def list
-        response = request("GET", "list")
-        response.map { |data| Resources::Billing.new(data) }
-      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)
-        request_data = {
-          frequency: data.frequency,
-          methods: data.methods,
-          returnUrl: data.metadata&.return_url,
-          completionUrl: data.metadata&.completion_url,
-          products: data.products&.map { |product|
-            {
-              externalId: product.external_id,
-              name: product.name,
-              description: product.description,
-              quantity: product.quantity,
-              price: product.price
-            }
-          }
-        }
-
-        if data.customer&.id
-          request_data[:customerId] = data.customer.id
-        else
-          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::Billing.new(response)
-      end
-    end
-  end
-end

data/lib/abacatepay/clients/customer_client.rb

@@ -1,39 +0,0 @@
-# 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 = "customer"
-
-      # @param client [Faraday::Connection, nil] Optional Faraday client for custom configurations
-      def initialize(client = nil)
-        super(URI, client)
-      end
-
-      # Retrieves a list of customers
-      #
-      # @return [Array<Resources::Customer>] Array of Customer objects
-      def list
-        response = request("GET", "list")
-        response.map { |data| Resources::Customer.new(data) }
-      end
-
-      # Creates a new customer
-      #
-      # @param data [Resources::Customer] The customer data to be sent for creation
-      # @return [Resources::Customer] 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::Customer.new(response)
-      end
-    end
-  end
-end

data/lib/abacatepay/clients.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "abacate_pay/clients/client"
-require "abacate_pay/clients/billing_client"
-require "abacate_pay/clients/customer_client"
-
-module AbacatePay
-  # The Clients module contains all API client implementations
-  # for interacting with the AbacatePay API endpoints.
-  module Clients
-  end
-end