abacatepay-ruby 1.0.0 → 1.2.1

data/lib/abacate_pay/enums/billings/methods.rb

@@ -10,12 +10,19 @@ module AbacatePay
         # PIX payment method.
         # @return [String] Represents the PIX payment method, a popular instant payment system in Brazil
         PIX = "PIX"
+
+        # @return [String] Credit card payment
         CARD = "CARD"
 
+        # Boleto bancário. Supports a due date and late-payment interest/fine -
+        # see Resources::Checkouts#due_date, #interest and #fine.
+        # @return [String] Boleto payment method
+        BOLETO = "BOLETO"
+
         # Gets all valid method values
         # @return [Array<String>] List of all valid payment methods
         def self.values
-          [PIX, CARD]
+          [PIX, CARD, BOLETO]
         end
 
         # Validates if a given value is a valid method

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

@@ -13,6 +13,12 @@ module AbacatePay
         SUBSCRIPTION_COMPLETED = "subscription.completed"
         SUBSCRIPTION_RENEWED = "subscription.renewed"
         SUBSCRIPTION_CANCELLED = "subscription.cancelled"
+
+        # Recurring charge failed, the dunning signal. Without handling this,
+        # a failing subscription looks identical to a healthy one.
+        SUBSCRIPTION_PAYMENT_FAILED = "subscription.payment_failed"
+
+        SUBSCRIPTION_TRIAL_STARTED = "subscription.trial_started"
         TRANSFER_COMPLETED = "transfer.completed"
         TRANSFER_FAILED = "transfer.failed"
         PAYOUT_COMPLETED = "payout.completed"
@@ -23,6 +29,7 @@ module AbacatePay
             CHECKOUT_COMPLETED, CHECKOUT_REFUNDED, CHECKOUT_DISPUTED,
             TRANSPARENT_COMPLETED, TRANSPARENT_REFUNDED, TRANSPARENT_DISPUTED,
             SUBSCRIPTION_COMPLETED, SUBSCRIPTION_RENEWED, SUBSCRIPTION_CANCELLED,
+            SUBSCRIPTION_PAYMENT_FAILED, SUBSCRIPTION_TRIAL_STARTED,
             TRANSFER_COMPLETED, TRANSFER_FAILED,
             PAYOUT_COMPLETED, PAYOUT_FAILED
           ]

data/lib/abacate_pay/resources/checkouts.rb

@@ -20,7 +20,13 @@ module AbacatePay
 
       attr_reader :id, :url, :amount, :status, :dev_mode, :methods,
                   :products, :metadata, :customer, :coupons, :external_id,
-                  :frequency, :created_at, :updated_at
+                  :frequency, :created_at, :updated_at,
+                  # BOLETO-only: due date (YYYY-MM-DD) plus late-payment charges.
+                  :due_date, :interest, :fine,
+                  # CARD-only: maximum number of instalments offered.
+                  :max_installments,
+                  # Order bump shown at checkout, and free-form merchant data.
+                  :up_sell_product_id, :custom_metadata
 
       def initialize(data)
         fill(data)
@@ -70,7 +76,9 @@ module AbacatePay
 
       attr_writer :id, :url, :amount, :status, :dev_mode, :methods,
                   :products, :metadata, :customer, :coupons, :external_id,
-                  :frequency, :created_at, :updated_at
+                  :frequency, :created_at, :updated_at,
+                  :due_date, :interest, :fine, :max_installments,
+                  :up_sell_product_id, :custom_metadata
     end
   end
 end

data/lib/abacate_pay/resources/customers.rb

@@ -2,45 +2,86 @@
 
 module AbacatePay
   module Resources
-    # Represents a customer resource in the AbacatePay payment system.
+    # Represents a customer in the AbacatePay system.
     #
-    # This class handles customer data including identification and metadata,
-    # providing a structured way to manage customer information within the system.
+    # The API returns the customer fields at the top level of the object:
+    #
+    #   { "id": "cust_...", "name": "Ana", "email": "ana@example.com",
+    #     "cellphone": "...", "taxId": "...", "metadata": {} }
+    #
+    # Earlier versions of this class only mapped `id` and a nested `metadata`,
+    # so every other field was silently dropped and `customer.metadata.name`
+    # came back nil for real API data.
+    #
+    # Both shapes work now: the fields are exposed directly, and `metadata`
+    # keeps answering for code written against the previous interface.
     class Customers < Resource
-      # Maps property names to their corresponding resource classes
       RESOURCE_PROPERTIES = {
         metadata: "AbacatePay::Resources::Customers::Metadata"
       }.freeze
 
-      # @return [String, nil] The unique identifier for the customer
-      attr_reader :id
+      # Fields the API sends inside the customer object.
+      IDENTITY_FIELDS = %i[name email cellphone tax_id].freeze
 
-      # @return [Metadata, nil] Additional customer information
-      attr_reader :metadata
+      attr_reader :id, :country, :zip_code, :dev_mode
 
-      # Creates a new Customer instance
-      #
-      # @param data [Hash] The raw customer data
-      # @raise [ArgumentError] If the data is invalid
+      # @return [String, nil] Customer's name
+      attr_reader :name
+
+      # @return [String, nil] Customer's email address
+      attr_reader :email
+
+      # @return [String, nil] Customer's cellphone number
+      attr_reader :cellphone
+
+      # @return [String, nil] Customer's tax identification number
+      attr_reader :tax_id
+
+      # @param data [Hash] The customer properties
       def initialize(data)
         fill(data)
       end
 
-      private
+      # @return [Boolean, nil] Whether this customer belongs to Dev mode
+      def dev_mode?
+        @dev_mode
+      end
 
-      # Process a value based on its property
+      # The identity fields, wrapped.
       #
+      # Kept because `customer.metadata.name` is what the README documented and
+      # what existing integrations call. When the API sends the fields at the
+      # top level, this builds the wrapper from them rather than returning the
+      # empty object the API puts in `metadata`.
+      #
+      # @return [Customers::Metadata, nil]
+      def metadata
+        return @metadata if metadata_populated?(@metadata)
+
+        identity = IDENTITY_FIELDS.to_h { |field| [field, public_send(field)] }.compact
+        return @metadata if identity.empty?
+
+        Customers::Metadata.new(identity)
+      end
+
+      private
+
+      # @param metadata [Customers::Metadata, nil]
+      # @return [Boolean] Whether the API actually filled the nested object
+      def metadata_populated?(metadata)
+        return false if metadata.nil?
+
+        IDENTITY_FIELDS.any? { |field| metadata.public_send(field) }
+      end
+
       # @param property [String] The property name
-      # @param value [Object] The value to process
+      # @param value [Object] The raw value
       # @return [Object] The processed value
       def process_value(property, value)
         return nil if value.nil?
 
         if RESOURCE_PROPERTIES.key?(property.to_sym)
-          initialize_resource(
-            Object.const_get(RESOURCE_PROPERTIES[property.to_sym]),
-            value
-          )
+          initialize_resource(Object.const_get(RESOURCE_PROPERTIES[property.to_sym]), value)
         else
           value
         end
@@ -48,8 +89,8 @@ module AbacatePay
 
       protected
 
-      # @!visibility private
-      attr_writer :id, :metadata
+      attr_writer :id, :metadata, :name, :email, :cellphone, :tax_id,
+                  :country, :zip_code, :dev_mode
     end
   end
 end

data/lib/abacate_pay/resources/resource.rb

@@ -51,7 +51,7 @@ module AbacatePay
         resource_class.new(value)
       end
 
-      # Default value processor — returns the value as-is.
+      # Default value processor, returns the value as-is.
       # Subclasses override this to handle enums, datetimes, and nested resources.
       #
       # @param _property [String] The property name

data/lib/abacate_pay/resources/transparents.rb

@@ -2,22 +2,44 @@
 
 module AbacatePay
   module Resources
-    # Represents a transparent PIX checkout in the AbacatePay system.
+    # Represents a transparent checkout (PIX or boleto) in the AbacatePay system.
     class Transparents < Resource
       RESOURCE_PROPERTIES = {
         customer: "AbacatePay::Resources::Customers"
       }.freeze
 
-      DATETIME_PROPERTIES = %w[created_at updated_at].freeze
+      DATETIME_PROPERTIES = %w[created_at updated_at expires_at].freeze
 
+      # qr_code and qr_code_image are defined below rather than generated here:
+      # they fall back to the br_code fields the API actually sends.
       attr_reader :id, :amount, :status, :method, :description,
-                  :expires_in, :qr_code, :qr_code_image, :customer,
-                  :metadata, :dev_mode, :created_at, :updated_at
+                  :expires_in, :customer,
+                  :metadata, :dev_mode, :created_at, :updated_at,
+                  # Boleto: due date sent on create, plus the payment slip the
+                  # API returns: digitable line, viewing URL, and the PIX
+                  # fallback issued for the same charge.
+                  :due_date, :bar_code, :url, :br_code, :br_code_base64,
+                  :expires_at, :platform_fee, :receipt_url
 
       def initialize(data)
         fill(data)
       end
 
+      # The API returns the copy-and-paste payload as `brCode` and the image as
+      # `brCodeBase64`. Older documentation used `qrCode`/`qrCodeImage`, so both
+      # spellings are accepted: the reader prefers the `qr*` value when the API
+      # sends one and falls back to `br*`.
+      #
+      # @return [String, nil] PIX copy-and-paste payload
+      def qr_code
+        @qr_code || br_code
+      end
+
+      # @return [String, nil] PIX QR code image as a data URI
+      def qr_code_image
+        @qr_code_image || br_code_base64
+      end
+
       def dev_mode?
         @dev_mode
       end
@@ -40,7 +62,9 @@ module AbacatePay
 
       attr_writer :id, :amount, :status, :method, :description,
                   :expires_in, :qr_code, :qr_code_image, :customer,
-                  :metadata, :dev_mode, :created_at, :updated_at
+                  :metadata, :dev_mode, :created_at, :updated_at,
+                  :due_date, :bar_code, :url, :br_code, :br_code_base64,
+                  :expires_at, :platform_fee, :receipt_url
     end
   end
 end

data/lib/abacate_pay/resources/webhook_endpoints.rb

@@ -4,7 +4,7 @@ module AbacatePay
   module Resources
     # Represents a registered webhook endpoint in the AbacatePay system.
     #
-    # This is the endpoint *registration* — the URL AbacatePay delivers events
+    # 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

data/lib/abacate_pay/resources.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Resource must load first — every other resource inherits from it.
+# Resource must load first: every other resource inherits from it.
 require "abacate_pay/resources/resource"
 
 require "abacate_pay/resources/billings"

data/lib/abacate_pay/version.rb

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

data/lib/abacate_pay/webhooks.rb

@@ -17,33 +17,65 @@ module AbacatePay
     # 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.
+    # AbacatePay signs every delivery with this fixed key, published at
+    # https://docs.abacatepay.com/pages/webhooks/security and hard-coded in the
+    # Node, Python and Go samples there.
+    #
+    # It is public and global, so it proves only that the body was not altered
+    # in transit, it does NOT prove the request came from AbacatePay, since
+    # anyone can compute a valid signature with it. Origin is authenticated by
+    # the `webhookSecret` query parameter; see {verify_secret!}. Use both.
+    PUBLIC_KEY = "t9dXRhHHo3yDEj5pVDYz0frf7q6bMKyMRmxxCPIPp3RCplBfXRxqlC6ZpiWmOqj4L63qEaeUOtrCI8P0VMU" \
+                 "go6iIga2ri9ogaHFs0WIIywSMg0q7RmBfybe1E5XJcfC4IW3alNqym0tXoAKkzvfEjZxV6bE0oG2zJrNNYmU" \
+                 "CKZyV0KZ3JS8Votf9EAWWYdiDkMkpbMdPggfh1EqHlVkMiTady6jOR3hyzGEHrIz2Ret0xHKMbiqkr9HS1Jh" \
+                 "NHDX9"
+
+    # Verifies the `X-Webhook-Signature` header: HMAC-SHA256 over the raw body,
+    # base64-encoded.
     #
     # @param payload [String] The raw request body
     # @param signature [String] The X-Webhook-Signature header value
-    # @param secret [String] Your webhook secret/public key
+    # @param secret [String] HMAC key. Defaults to {PUBLIC_KEY}, which is what
+    #   AbacatePay signs with.
     # @return [true] if signature is valid
     # @raise [SignatureError] if the signature is missing or invalid
-    def self.verify!(payload:, signature:, secret:)
+    def self.verify!(payload:, signature:, secret: PUBLIC_KEY)
       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)
+      expected = base64_hmac(secret.to_s, payload.to_s)
       raise SignatureError, "Invalid webhook signature" unless secure_compare(expected, signature.to_s)
 
       true
     end
 
+    # Verifies the `webhookSecret` query parameter, which is what actually
+    # authenticates the request as coming from AbacatePay.
+    #
+    # The HMAC signature alone cannot do this: it is computed with a public key.
+    #
+    # @param received [String] The `webhookSecret` query parameter as received
+    # @param expected [String] The secret you configured on the webhook
+    # @return [true] if they match
+    # @raise [SignatureError] if either is missing or they differ
+    def self.verify_secret!(received:, expected:)
+      raise SignatureError, "Missing webhook secret parameter" if received.nil? || received.to_s.empty?
+      raise SignatureError, "Missing expected webhook secret" if expected.nil? || expected.to_s.empty?
+      raise SignatureError, "Invalid webhook secret" unless secure_compare(expected.to_s, received.to_s)
+
+      true
+    end
+
     # Checks if a webhook signature is valid.
     #
-    # Never raises for untrusted input — a missing header, an empty secret, or a
+    # 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:)
+    def self.valid?(payload:, signature:, secret: PUBLIC_KEY)
       verify!(payload: payload, signature: signature, secret: secret)
       true
     rescue SignatureError
@@ -78,11 +110,25 @@ module AbacatePay
     # @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:)
+    def self.construct_event(payload:, signature:, secret: PUBLIC_KEY)
       verify!(payload: payload, signature: signature, secret: secret)
       parse(payload)
     end
 
+    # Base64-encoded HMAC-SHA256, matching what AbacatePay sends.
+    #
+    # Uses Array#pack rather than the base64 gem: base64 stopped being a default
+    # gem in Ruby 3.4, and requiring it would add a runtime dependency for one
+    # call.
+    #
+    # @param secret [String] The HMAC key
+    # @param payload [String] The raw body
+    # @return [String] The base64 signature
+    def self.base64_hmac(secret, payload)
+      [OpenSSL::HMAC.digest("SHA256", secret, payload)].pack("m0")
+    end
+    private_class_method :base64_hmac
+
     # Constant-time comparison to prevent timing attacks.
     #
     # @param expected [String] The signature computed from the payload

data/lib/abacate_pay.rb

@@ -2,6 +2,7 @@
 
 require "abacate_pay/version"
 require "abacate_pay/configuration"
+require "abacate_pay/collection"
 
 # Main module for AbacatePay SDK integration
 module AbacatePay

data/lib/abacatepay-ruby.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name.
+#
+# Bundler requires a gem by its own name, so `gem "abacatepay-ruby"` in a
+# Gemfile makes Rails call `require "abacatepay-ruby"` (and then
+# `require "abacatepay/ruby"`). Neither matched `lib/abacate_pay.rb`, so the SDK
+# silently failed to load and the first call raised
+# `undefined method 'configure' for module AbacatePay` — the module existed with
+# only VERSION in it, defined as a side effect of the gemspec.
+#
+# This file makes the default `gem "abacatepay-ruby"` work without a `require:`
+# option. `require "abacate_pay"` keeps working for anyone already using it.
+require_relative "abacate_pay"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: abacatepay-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Matheus Cardoso
@@ -29,6 +29,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.14.3
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -91,14 +105,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
 description: The easiest way to integrate your Ruby application with AbacatePay Gateway
   for payments, subscriptions, PIX transfers, and more.
 email:
@@ -130,6 +144,7 @@ files:
 - lib/abacate_pay/clients/subscription_client.rb
 - lib/abacate_pay/clients/transparent_client.rb
 - lib/abacate_pay/clients/webhook_client.rb
+- lib/abacate_pay/collection.rb
 - lib/abacate_pay/configuration.rb
 - lib/abacate_pay/enums.rb
 - lib/abacate_pay/enums/billings/frequencies.rb
@@ -163,6 +178,7 @@ files:
 - lib/abacate_pay/version.rb
 - lib/abacate_pay/webhooks.rb
 - lib/abacate_pay/webhooks/event.rb
+- lib/abacatepay-ruby.rb
 homepage: https://www.abacatepay.com/
 licenses:
 - MIT