abacatepay-ruby 0.1.0 → 1.1.0

data/lib/abacate_pay/resources/pix_transfers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Resources
+    # Represents an outbound PIX transfer in the AbacatePay system.
+    class PixTransfers < Resource
+      ENUM_PROPERTIES = {
+        status: "AbacatePay::Enums::Transfers::Statuses",
+        key_type: "AbacatePay::Enums::Pix::KeyTypes"
+      }.freeze
+
+      DATETIME_PROPERTIES = %w[created_at updated_at].freeze
+
+      attr_reader :id, :amount, :external_id, :description,
+                  :key, :key_type, :status, :created_at, :updated_at
+
+      def initialize(data)
+        fill(data)
+      end
+
+      private
+
+      def process_value(property, value)
+        return nil if value.nil?
+
+        if DATETIME_PROPERTIES.include?(property)
+          initialize_date_time(value)
+        elsif ENUM_PROPERTIES.key?(property.to_sym)
+          initialize_enum(Object.const_get(ENUM_PROPERTIES[property.to_sym]), value)
+        else
+          value
+        end
+      end
+
+      protected
+
+      attr_writer :id, :amount, :external_id, :description,
+                  :key, :key_type, :status, :created_at, :updated_at
+    end
+  end
+end

data/lib/abacate_pay/resources/products.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Resources
+    # Represents a catalogue product in the AbacatePay system.
+    class Products < Resource
+      ENUM_PROPERTIES = {
+        cycle: "AbacatePay::Enums::Products::Cycles"
+      }.freeze
+
+      DATETIME_PROPERTIES = %w[created_at updated_at].freeze
+
+      attr_reader :id, :external_id, :name, :price, :currency,
+                  :description, :image_url, :cycle, :created_at, :updated_at
+
+      def initialize(data)
+        fill(data)
+      end
+
+      private
+
+      def process_value(property, value)
+        return nil if value.nil?
+
+        if DATETIME_PROPERTIES.include?(property)
+          initialize_date_time(value)
+        elsif ENUM_PROPERTIES.key?(property.to_sym)
+          initialize_enum(Object.const_get(ENUM_PROPERTIES[property.to_sym]), value)
+        else
+          value
+        end
+      end
+
+      protected
+
+      attr_writer :id, :external_id, :name, :price, :currency,
+                  :description, :image_url, :cycle, :created_at, :updated_at
+    end
+  end
+end

data/lib/{abacatepay → abacate_pay}/resources/resource.rb

@@ -12,8 +12,9 @@ module AbacatePay
       # @return [DateTime, nil] The initialized DateTime object or nil
       # @raise [ArgumentError] If the value is invalid
       def initialize_date_time(value)
-        return nil if value.nil? || value.empty?
+        return nil if value.nil?
         return value.clone if value.is_a?(DateTime)
+        return nil if value.empty?
 
         DateTime.parse(value)
       rescue Date::Error
@@ -28,7 +29,7 @@ module AbacatePay
       # @raise [ArgumentError] If the value is invalid
       def initialize_enum(enum_class, value)
         return nil if value.nil? || value.empty?
-        
+
         enum_class.validate!(value)
       end
 
@@ -39,8 +40,9 @@ module AbacatePay
       # @return [Object, nil] The initialized resource or nil
       # @raise [ArgumentError] If the value is invalid
       def initialize_resource(resource_class, value)
-        return nil if value.nil? || value.empty?
+        return nil if value.nil?
         return value.clone if value.is_a?(resource_class)
+        return nil if value.respond_to?(:empty?) && value.empty?
 
         unless value.is_a?(Hash)
           raise ArgumentError, "Invalid resource value. Expected Hash or #{resource_class}, got #{value.class}"
@@ -49,6 +51,16 @@ module AbacatePay
         resource_class.new(value)
       end
 
+      # Default value processor — returns the value as-is.
+      # Subclasses override this to handle enums, datetimes, and nested resources.
+      #
+      # @param _property [String] The property name
+      # @param value [Object] The raw value
+      # @return [Object] The processed value
+      def process_value(_property, value)
+        value
+      end
+
       # Fill the object with data
       #
       # @param data [Hash] The data to fill with
@@ -57,7 +69,7 @@ module AbacatePay
         data.each do |key, value|
           property = camel_to_snake(key)
           next unless respond_to?("#{property}=", true)
-          
+
           send("#{property}=", process_value(property, value))
         end
       end
@@ -78,7 +90,7 @@ module AbacatePay
       # @param str [String] The string to convert
       # @return [String] The converted string
       def snake_to_camel(str)
-        str.split('_')
+        str.split("_")
            .map.with_index { |word, i| i.zero? ? word : word.capitalize }
            .join
       end
@@ -90,25 +102,25 @@ module AbacatePay
       # @return [Hash] The hash representation
       def to_hash
         instance_variables.each_with_object({}) do |var, hash|
-          next if var.to_s.start_with?('@__')
-          
+          next if var.to_s.start_with?("@__")
+
           value = instance_variable_get(var)
-          key = snake_to_camel(var.to_s.delete('@'))
-          
+          key = snake_to_camel(var.to_s.delete("@"))
+
           hash[key] = case value
-                     when DateTime
-                       value.iso8601
-                     when Resource
-                       value.to_hash
-                     when Module
-                       value.respond_to?(:value) ? value.value : value
-                     when Array
-                       value.map { |v| v.respond_to?(:to_hash) ? v.to_hash : v }
-                     else
-                       value
-                     end
+                      when DateTime
+                        value.iso8601
+                      when Resource
+                        value.to_hash
+                      when Module
+                        value.respond_to?(:value) ? value.value : value
+                      when Array
+                        value.map { |v| v.respond_to?(:to_hash) ? v.to_hash : v }
+                      else
+                        value
+                      end
         end.compact
       end
     end
   end
-end
+end

data/lib/abacate_pay/resources/store/balance.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Resources
+    class Store < Resource
+      # Represents the available balance of a store.
+      class Balance < Resource
+        attr_reader :available, :pending, :blocked
+
+        def initialize(data)
+          fill(data)
+        end
+
+        protected
+
+        attr_writer :available, :pending, :blocked
+      end
+    end
+  end
+end

data/lib/abacate_pay/resources/store.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Resources
+    # Represents store-level account data in the AbacatePay system.
+    class Store < Resource
+      RESOURCE_PROPERTIES = {
+        balance: "AbacatePay::Resources::Store::Balance"
+      }.freeze
+
+      attr_reader :id, :name, :balance
+
+      def initialize(data)
+        fill(data)
+      end
+
+      private
+
+      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)
+        else
+          value
+        end
+      end
+
+      protected
+
+      attr_writer :id, :name, :balance
+    end
+  end
+end
+
+require "abacate_pay/resources/store/balance"

data/lib/abacate_pay/resources/subscriptions.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Resources
+    # Represents a recurring subscription in the AbacatePay system.
+    class Subscriptions < Resource
+      RESOURCE_PROPERTIES = {
+        customer: "AbacatePay::Resources::Customers",
+        products: "AbacatePay::Resources::Billings::Product"
+      }.freeze
+
+      ENUM_PROPERTIES = {
+        status: "AbacatePay::Enums::Checkouts::Statuses",
+        methods: "AbacatePay::Enums::Billings::Methods"
+      }.freeze
+
+      DATETIME_PROPERTIES = %w[created_at updated_at].freeze
+
+      attr_reader :id, :url, :customer, :products, :methods, :status,
+                  :external_id, :metadata, :dev_mode, :created_at, :updated_at
+
+      def initialize(data)
+        fill(data)
+      end
+
+      def dev_mode?
+        @dev_mode
+      end
+
+      private
+
+      def process_value(property, value)
+        return nil if value.nil?
+
+        if DATETIME_PROPERTIES.include?(property)
+          initialize_date_time(value)
+        elsif ENUM_PROPERTIES.key?(property.to_sym)
+          process_enum_value(property, value)
+        elsif RESOURCE_PROPERTIES.key?(property.to_sym)
+          process_resource_value(property, value)
+        else
+          value
+        end
+      end
+
+      def process_enum_value(property, value)
+        enum_class = Object.const_get(ENUM_PROPERTIES[property.to_sym])
+
+        if value.is_a?(Array)
+          value.map { |item| initialize_enum(enum_class, item) }
+        else
+          initialize_enum(enum_class, value)
+        end
+      end
+
+      def process_resource_value(property, value)
+        resource_class = Object.const_get(RESOURCE_PROPERTIES[property.to_sym])
+
+        if property.to_s == "products" && value.is_a?(Array)
+          value.map { |item| initialize_resource(resource_class, item) }
+        else
+          initialize_resource(resource_class, value)
+        end
+      end
+
+      protected
+
+      attr_writer :id, :url, :customer, :products, :methods, :status,
+                  :external_id, :metadata, :dev_mode, :created_at, :updated_at
+    end
+  end
+end

data/lib/abacate_pay/resources/transparents.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module AbacatePay
+  module Resources
+    # 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 expires_at].freeze
+
+      attr_reader :id, :amount, :status, :method, :description,
+                  :expires_in, :qr_code, :qr_code_image, :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
+
+      def initialize(data)
+        fill(data)
+      end
+
+      def dev_mode?
+        @dev_mode
+      end
+
+      private
+
+      def process_value(property, value)
+        return nil if value.nil?
+
+        if DATETIME_PROPERTIES.include?(property)
+          initialize_date_time(value)
+        elsif RESOURCE_PROPERTIES.key?(property.to_sym)
+          initialize_resource(Object.const_get(RESOURCE_PROPERTIES[property.to_sym]), value)
+        else
+          value
+        end
+      end
+
+      protected
+
+      attr_writer :id, :amount, :status, :method, :description,
+                  :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
+    end
+  end
+end

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.1.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"