abacatepay-ruby 1.1.0 → 1.2.2

data/lib/abacate_pay/clients/payout_client.rb

@@ -32,7 +32,13 @@ module AbacatePay
         response = request("POST", "create", json: {
                              amount: data.amount,
                              externalId: data.external_id,
-                             description: data.description
+                             description: data.description,
+                             # The API nests the destination under `pix`, with
+                             # `key` and `type`. Sending pixKey/pixKeyType at the
+                             # top level fails with "Property 'pix' is missing";
+                             # nesting the wrong names fails with
+                             # "Property 'pix.type' is missing".
+                             pix: { key: data.pix_key, type: data.pix_key_type }
                            })
         Resources::Payouts.new(response)
       end

data/lib/abacate_pay/clients/pix_client.rb

@@ -13,7 +13,11 @@ module AbacatePay
         super(URI, client)
       end
 
-      # @param params [Hash] Optional pagination params (after, before, limit)
+      # The API requires an `id` on this endpoint: a bare call fails with
+      # "Expected property 'id' to be string but found: undefined". Despite the
+      # name it filters rather than lists.
+      #
+      # @param params [Hash] Params forwarded to the API; `id` is required
       # @return [Array<Resources::PixTransfers>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
@@ -37,8 +41,12 @@ module AbacatePay
                              amount: data.amount,
                              externalId: data.external_id,
                              description: data.description,
-                             key: data.key,
-                             keyType: data.key_type
+                             # The API nests the destination under `pix`, with
+                             # `key` and `type`. Sending pixKey/pixKeyType at the
+                             # top level fails with "Property 'pix' is missing";
+                             # nesting the wrong names fails with
+                             # "Property 'pix.type' is missing".
+                             pix: { key: data.key, type: data.key_type }
                            })
         Resources::PixTransfers.new(response)
       end

data/lib/abacate_pay/clients/product_client.rb

@@ -46,7 +46,10 @@ module AbacatePay
       # @param id [String] Product ID
       # @return [Resources::Products]
       def delete(id)
-        response = request("POST", "delete", json: { id: id })
+        # The API reads the id from the query string on delete endpoints.
+        # Sending it only in the body fails with
+        # "Expected property 'id' to be string but found: undefined".
+        response = request("POST", "delete", params: { id: id }, json: {})
         Resources::Products.new(response)
       end
     end

data/lib/abacate_pay/clients/store_client.rb

@@ -12,7 +12,9 @@ module AbacatePay
 
       # @return [Resources::Store]
       def get
-        response = request("GET", "store/get")
+        # The API serves this as `stores/get`, plural, even though the reference
+        # documents `store/get`. The singular path answers HTTP 400.
+        response = request("GET", "stores/get")
         Resources::Store.new(response)
       end
 

data/lib/abacate_pay/clients/subscription_client.rb

@@ -26,15 +26,10 @@ module AbacatePay
           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
+          # The API expects the product id here, the same shape checkouts use.
+          # Sending externalId fails with
+          # "Expected property 'items.0.id' to be string".
+          items: data.products&.map { |product| { id: product.external_id, quantity: product.quantity } }
         }
 
         response = request("POST", "create", json: request_data)
@@ -52,7 +47,7 @@ module AbacatePay
       end
 
       # Changes the main product of an active subscription. The new price takes
-      # effect on the next billing cycle — the current cycle is untouched.
+      # 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

data/lib/abacate_pay/clients/transparent_client.rb

@@ -45,12 +45,14 @@ module AbacatePay
       # @param id [String] QR code ID (dev mode only)
       # @return [Resources::Transparents]
       def simulate_payment(id)
-        response = request("POST", "simulate-payment", json: { id: id })
+        # The API reads the id from the query string here, like #check. Sending
+        # it only in the body fails with "Expected property 'id'".
+        response = request("POST", "simulate-payment", params: { id: id }, json: {})
         Resources::Transparents.new(response)
       end
 
       # Refunds a transparent payment in full. AbacatePay does not support
-      # partial refunds — the original amount is always returned.
+      # partial refunds, the original amount is always returned.
       #
       # @param id [String] Public charge ID (`pix_char_...`, `card_...`, `char_...`)
       # @return [Resources::Transparents] The refunded charge

data/lib/abacate_pay/clients/webhook_client.rb

@@ -11,6 +11,9 @@ module AbacatePay
     class WebhookClient < Client
       URI = "webhooks"
 
+      # Shortest signing secret the API accepts.
+      MINIMUM_SECRET_LENGTH = 32
+
       # @param client [Faraday::Connection, nil] Optional Faraday client
       def initialize(client = nil)
         super(URI, client)
@@ -32,7 +35,7 @@ module AbacatePay
 
       # Registers a new webhook endpoint.
       #
-      # The secret is what AbacatePay signs deliveries with — pass the same
+      # 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
@@ -40,11 +43,19 @@ module AbacatePay
       # @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
+      # @raise [ArgumentError] if the endpoint is not HTTPS, the event list is
+      #   empty, or the secret is shorter than the API accepts
       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?
 
+        # The API rejects anything shorter with
+        # "Expected string length greater or equal to 32".
+        if secret.to_s.length < MINIMUM_SECRET_LENGTH
+          raise ArgumentError,
+                "secret must be at least #{MINIMUM_SECRET_LENGTH} characters, got #{secret.to_s.length}"
+        end
+
         response = request("POST", "create", json: {
                              name: name,
                              endpoint: endpoint,
@@ -55,9 +66,15 @@ module AbacatePay
       end
 
       # @param id [String] The webhook ID
-      # @return [Resources::WebhookEndpoints] The deleted webhook
+      # @return [Resources::WebhookEndpoints, nil] The deleted webhook, or nil
+      #   when the API confirms the deletion without echoing the object
       def delete(id)
-        response = request("POST", "delete", json: { id: id })
+        # The API reads the id from the query string here, like
+        # transparents/simulate-payment. Sending it in the body fails with
+        # "Expected property 'id' to be string but found: undefined".
+        response = request("POST", "delete", params: { id: id }, json: {})
+        return nil if response.nil?
+
         Resources::WebhookEndpoints.new(response)
       end
 

data/lib/abacate_pay/clients.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Client must load first — every other client inherits from it.
+# Client must load first: every other client inherits from it.
 require "abacate_pay/clients/client"
 
 require "abacate_pay/clients/billing_client"

data/lib/abacate_pay/configuration.rb

@@ -9,8 +9,8 @@ module AbacatePay
   # @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
+    # 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"
@@ -43,7 +43,7 @@ module AbacatePay
       @api_token = nil
     end
 
-    # @deprecated The environment is determined by the API key itself — keys
+    # @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.

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

@@ -14,7 +14,7 @@ module AbacatePay
         # @return [String] Credit card payment
         CARD = "CARD"
 
-        # Boleto bancário. Supports a due date and late-payment interest/fine —
+        # 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"

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

@@ -10,8 +10,11 @@ module AbacatePay
         PAID = "PAID"
         REFUNDED = "REFUNDED"
 
+        # Reusable payment links are created ACTIVE rather than PENDING.
+        ACTIVE = "ACTIVE"
+
         def self.values
-          [PENDING, EXPIRED, CANCELLED, PAID, REFUNDED]
+          [PENDING, EXPIRED, CANCELLED, PAID, REFUNDED, ACTIVE]
         end
 
         def self.valid?(value)

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

@@ -8,8 +8,11 @@ module AbacatePay
         INACTIVE = "INACTIVE"
         EXPIRED = "EXPIRED"
 
+        # What the API returns for a coupon turned off through `toggle`.
+        DISABLED = "DISABLED"
+
         def self.values
-          [ACTIVE, INACTIVE, EXPIRED]
+          [ACTIVE, INACTIVE, EXPIRED, DISABLED]
         end
 
         def self.valid?(value)

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

@@ -14,7 +14,7 @@ module AbacatePay
         SUBSCRIPTION_RENEWED = "subscription.renewed"
         SUBSCRIPTION_CANCELLED = "subscription.cancelled"
 
-        # Recurring charge failed — the dunning signal. Without handling this,
+        # Recurring charge failed, the dunning signal. Without handling this,
         # a failing subscription looks identical to a healthy one.
         SUBSCRIPTION_PAYMENT_FAILED = "subscription.payment_failed"
 

data/lib/abacate_pay/resources/coupons.rb

@@ -11,13 +11,38 @@ module AbacatePay
 
       DATETIME_PROPERTIES = %w[created_at updated_at].freeze
 
-      attr_reader :id, :code, :discount, :discount_kind, :max_redeems,
-                  :current_redeems, :status, :created_at, :updated_at
+      attr_reader :id, :discount, :discount_kind, :max_redeems,
+                  :status, :notes, :dev_mode, :created_at, :updated_at
+
+      # @return [Integer, nil] Times the coupon has been redeemed
+      attr_reader :redeems_count
 
       def initialize(data)
         fill(data)
       end
 
+      # The coupon code.
+      #
+      # The API uses the code as the object's `id` and sends no separate
+      # `code` field, so this reader was always nil for API data.
+      #
+      # @return [String, nil]
+      def code
+        @code || @id
+      end
+
+      # @return [Integer, nil] Times the coupon has been redeemed
+      #
+      # @deprecated The API calls this `redeemsCount`; use {#redeems_count}.
+      def current_redeems
+        @current_redeems || @redeems_count
+      end
+
+      # @return [Boolean, nil] Whether the coupon belongs to Dev mode
+      def dev_mode?
+        @dev_mode
+      end
+
       private
 
       def process_value(property, value)
@@ -35,7 +60,8 @@ module AbacatePay
       protected
 
       attr_writer :id, :code, :discount, :discount_kind, :max_redeems,
-                  :current_redeems, :status, :created_at, :updated_at
+                  :current_redeems, :redeems_count, :status, :notes,
+                  :dev_mode, :created_at, :updated_at
     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/payouts.rb

@@ -10,6 +10,12 @@ module AbacatePay
 
       DATETIME_PROPERTIES = %w[created_at updated_at].freeze
 
+      # @return [String, nil] Destination PIX key
+      attr_accessor :pix_key
+
+      # @return [String, nil] Destination PIX key type
+      attr_accessor :pix_key_type
+
       attr_reader :id, :amount, :external_id, :description,
                   :status, :created_at, :updated_at
 

data/lib/abacate_pay/resources/resource.rb

@@ -21,16 +21,28 @@ module AbacatePay
         raise ArgumentError, "Invalid datetime value: #{value}"
       end
 
-      # Initialize an enum from a string or enum object
+      # Initialize an enum from a string or enum object.
+      #
+      # Unknown values pass through with a warning rather than raising. This
+      # method runs while parsing API responses, and AbacatePay adds statuses
+      # over time: rejecting an unrecognised one would turn every new value
+      # into a crash inside `list` and `get` for every integration at once.
+      # That happened with the coupon status `DISABLED` and the payment-link
+      # status `ACTIVE`, neither of which the SDK knew about.
+      #
+      # Use {AbacatePay::Enums} `validate!` directly when you want a hard
+      # failure on a value you are about to send.
       #
       # @param enum_class [Class] The enum class to initialize
       # @param value [String, Object] The value to initialize
-      # @return [Object, nil] The initialized enum or nil
-      # @raise [ArgumentError] If the value is invalid
+      # @return [Object, nil] The value, validated when known
       def initialize_enum(enum_class, value)
         return nil if value.nil? || value.empty?
+        return value if enum_class.valid?(value)
 
-        enum_class.validate!(value)
+        warn "[AbacatePay] unknown #{enum_class.name.split("::").last} value #{value.inspect}. " \
+             "Passing it through; upgrade the gem if this is a new API value."
+        value
       end
 
       # Initialize a resource from a hash or resource object
@@ -51,7 +63,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
@@ -66,6 +78,10 @@ module AbacatePay
       # @param data [Hash] The data to fill with
       # @return [void]
       def fill(data)
+        # Some endpoints answer a successful call with no payload, so the
+        # resource is built from nil. An empty object beats a NoMethodError.
+        return if data.nil?
+
         data.each do |key, value|
           property = camel_to_snake(key)
           next unless respond_to?("#{property}=", true)

data/lib/abacate_pay/resources/transparents.rb

@@ -10,19 +10,36 @@ module AbacatePay
 
       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,
+                  :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
+                  # 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
+                  :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
@@ -47,7 +64,7 @@ module AbacatePay
                   :expires_in, :qr_code, :qr_code_image, :customer,
                   :metadata, :dev_mode, :created_at, :updated_at,
                   :due_date, :bar_code, :url, :br_code, :br_code_base64,
-                  :expires_at
+                  :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.1.0"
+  VERSION = "1.2.2"
 end