square.rb 44.1.0.20250924 → 45.0.1.20260122

data/lib/square/internal/iterators/item_iterator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Square
+  module Internal
+    class ItemIterator
+      include Enumerable
+
+      # Iterates over each item returned by the API.
+      #
+      # @param block [Proc] The block which each retrieved item is yielded to.
+      # @return [NilClass]
+      def each(&block)
+        while (item = next_element)
+          block.call(item)
+        end
+      end
+
+      # Whether another item will be available from the API.
+      #
+      # @return [Boolean]
+      def next?
+        load_next_page if @page.nil?
+        return false if @page.nil?
+
+        return true if any_items_in_cached_page?
+
+        load_next_page
+        any_items_in_cached_page?
+      end
+
+      # Retrieves the next item from the API.
+      def next_element
+        item = next_item_from_cached_page
+        return item if item
+
+        load_next_page
+        next_item_from_cached_page
+      end
+
+      private
+
+      def next_item_from_cached_page
+        return unless @page
+
+        items = @page.send(@item_field)
+        return nil if items.nil?
+
+        items.shift
+      end
+
+      def any_items_in_cached_page?
+        return false unless @page
+
+        items = @page.send(@item_field)
+        return false if items.nil?
+
+        !items.empty?
+      end
+
+      def load_next_page
+        @page = @page_iterator.next_page
+      end
+    end
+  end
+end

data/lib/square/internal/iterators/offset_item_iterator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Square
+  module Internal
+    class OffsetItemIterator < ItemIterator
+      # Instantiates an OffsetItemIterator, an Enumerable class which wraps calls to an offset-based paginated API and yields the individual items from it.
+      #
+      # @param initial_page [Integer] The initial page or offset to start from when iterating.
+      # @param item_field [Symbol] The name of the field in API responses to extract the items to iterate over.
+      # @param has_next_field [Symbol] The name of the field in API responses containing a boolean of whether another page exists.
+      # @param step [Boolean] If true, treats the page number as a true offset (i.e. increments the page number by the number of items returned from each call rather than just 1)
+      # @param block [Proc] A block which is responsible for receiving a page number to use and returning the given page from the API.
+      #
+      # @return [Square::Internal::OffsetItemIterator]
+      def initialize(initial_page:, item_field:, has_next_field:, step:, &)
+        super()
+        @item_field = item_field
+        @page_iterator = OffsetPageIterator.new(initial_page:, item_field:, has_next_field:, step:, &)
+        @page = nil
+      end
+
+      # Returns the OffsetPageIterator that is mediating access to the underlying API.
+      #
+      # @return [Square::Internal::OffsetPageIterator]
+      def pages
+        @page_iterator
+      end
+    end
+  end
+end

data/lib/square/internal/iterators/offset_page_iterator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Square
+  module Internal
+    class OffsetPageIterator
+      include Enumerable
+
+      # Instantiates an OffsetPageIterator, an Enumerable class which wraps calls to an offset-based paginated API and yields pages of items from it.
+      #
+      # @param initial_page [Integer] The initial page to use when iterating, if any.
+      # @param item_field [Symbol] The field to pull the list of items to iterate over.
+      # @param has_next_field [Symbol] The field to pull the boolean of whether a next page exists from, if any.
+      # @param step [Boolean] If true, treats the page number as a true offset (i.e. increments the page number by the number of items returned from each call rather than just 1)
+      # @param block [Proc] A block which is responsible for receiving a page number to use and returning the given page from the API.
+      # @return [Square::Internal::OffsetPageIterator]
+      def initialize(initial_page:, item_field:, has_next_field:, step:, &block)
+        @page_number = initial_page || (step ? 0 : 1)
+        @item_field = item_field
+        @has_next_field = has_next_field
+        @step = step
+        @get_next_page = block
+
+        # A cache of whether the API has another page, if it gives us that information...
+        @next_page = nil
+        # ...or the actual next page, preloaded, if it doesn't.
+        @has_next_page = nil
+      end
+
+      # Iterates over each page returned by the API.
+      #
+      # @param block [Proc] The block which each retrieved page is yielded to.
+      # @return [NilClass]
+      def each(&block)
+        while (page = next_page)
+          block.call(page)
+        end
+      end
+
+      # Whether another page will be available from the API.
+      #
+      # @return [Boolean]
+      def next?
+        return @has_next_page unless @has_next_page.nil?
+        return true if @next_page
+
+        fetched_page = @get_next_page.call(@page_number)
+        fetched_page_items = fetched_page&.send(@item_field)
+        if fetched_page_items.nil? || fetched_page_items.empty?
+          @has_next_page = false
+        else
+          @next_page = fetched_page
+          true
+        end
+      end
+
+      # Returns the next page from the API.
+      def next_page
+        return nil if @page_number.nil?
+
+        if @next_page
+          this_page = @next_page
+          @next_page = nil
+        else
+          this_page = @get_next_page.call(@page_number)
+        end
+
+        @has_next_page = this_page&.send(@has_next_field) if @has_next_field
+
+        items = this_page.send(@item_field)
+        if items.nil? || items.empty?
+          @page_number = nil
+          return nil
+        elsif @step
+          @page_number += items.length
+        else
+          @page_number += 1
+        end
+
+        this_page
+      end
+    end
+  end
+end

data/lib/square/internal/json/request.rb

@@ -22,10 +22,11 @@ module Square
 
         # @return [Hash] The encoded HTTP request headers.
         def encode_headers
+          additional_headers = @request_options&.dig(:additional_headers) || @request_options&.dig("additional_headers") || {}
           {
             "Content-Type" => "application/json",
             "Accept" => "application/json"
-          }.merge(@headers)
+          }.merge(@headers).merge(additional_headers)
         end
 
         # @return [String, nil] The encoded HTTP request body.

data/lib/square/internal/multipart/multipart_request.rb

@@ -22,9 +22,10 @@ module Square
 
         # @return [Hash] The encoded HTTP request headers.
         def encode_headers
+          additional_headers = @request_options&.dig(:additional_headers) || @request_options&.dig("additional_headers") || {}
           {
             "Content-Type" => @body.content_type
-          }.merge(@headers)
+          }.merge(@headers).merge(additional_headers)
         end
 
         # @return [String, nil] The encoded HTTP request body.

data/lib/square/internal/types/enum.rb

@@ -39,6 +39,14 @@ module Square
           value
         end
 
+        # Parse JSON string and coerce to the enum value
+        #
+        # @param str [String] JSON string to parse
+        # @return [String] The enum value
+        def load(str)
+          coerce(::JSON.parse(str))
+        end
+
         def inspect
           "#{name}[#{values.join(", ")}]"
         end

data/lib/square/internal/types/model/field.rb

@@ -6,6 +6,11 @@ module Square
       class Model
         # Definition of a field on a model
         class Field
+          SENSITIVE_FIELD_NAMES = %i[
+            password secret token api_key apikey access_token refresh_token
+            client_secret client_id credential bearer authorization
+          ].freeze
+
           attr_reader :name, :type, :optional, :nullable, :api_name, :value, :default
 
           def initialize(name:, type:, optional: false, nullable: false, api_name: nil, value: nil, default: nil)
@@ -13,7 +18,7 @@ module Square
             @type = type
             @optional = optional
             @nullable = nullable
-            @api_name = (api_name || name).to_sym
+            @api_name = api_name || name.to_s
             @value = value
             @default = default
           end
@@ -21,6 +26,11 @@ module Square
           def literal?
             !value.nil?
           end
+
+          def sensitive?
+            SENSITIVE_FIELD_NAMES.include?(@name) ||
+              SENSITIVE_FIELD_NAMES.any? { |sensitive| @name.to_s.include?(sensitive.to_s) }
+          end
         end
       end
     end

data/lib/square/internal/types/model.rb

@@ -112,7 +112,7 @@ module Square
             end
           end
 
-          def coerce(value, strict: (respond_to?(:strict?) ? strict? : false))
+          def coerce(value, strict: (respond_to?(:strict?) ? strict? : false)) # rubocop:disable Lint/UnusedMethodArgument
             return value if value.is_a?(self)
 
             return value unless value.is_a?(::Hash)
@@ -141,7 +141,7 @@ module Square
           values = Utils.symbolize_keys(values.dup)
 
           self.class.fields.each do |field_name, field|
-            value = values.delete(field.api_name)
+            value = values.delete(field.api_name.to_sym) || values.delete(field.api_name) || values.delete(field_name)
 
             field_value = value || (if field.literal?
                                       field.value
@@ -161,7 +161,7 @@ module Square
         end
 
         def to_h
-          self.class.fields.merge(self.class.extra_fields).each_with_object({}) do |(name, field), acc|
+          result = self.class.fields.merge(self.class.extra_fields).each_with_object({}) do |(name, field), acc|
             # If there is a value present in the data, use that value
             # If there is a `nil` value present in the data, and it is optional but NOT nullable, exclude key altogether
             # If there is a `nil` value present in the data, and it is optional and nullable, use the nil value
@@ -178,6 +178,14 @@ module Square
 
             acc[field.api_name] = value
           end
+
+          # Inject union discriminant if this instance was coerced from a discriminated union
+          # and the discriminant key is not already present in the result
+          discriminant_key = instance_variable_get(:@_fern_union_discriminant_key)
+          discriminant_value = instance_variable_get(:@_fern_union_discriminant_value)
+          result[discriminant_key] = discriminant_value if discriminant_key && discriminant_value && !result.key?(discriminant_key)
+
+          result
         end
 
         def ==(other)
@@ -187,7 +195,9 @@ module Square
         # @return [String]
         def inspect
           attrs = @data.map do |name, value|
-            "#{name}=#{value.inspect}"
+            field = self.class.fields[name] || self.class.extra_fields[name]
+            display_value = field&.sensitive? ? "[REDACTED]" : value.inspect
+            "#{name}=#{display_value}"
           end
 
           "#<#{self.class.name}:0x#{object_id&.to_s(16)} #{attrs.join(" ")}>"

data/lib/square/internal/types/union.rb

@@ -38,23 +38,84 @@ module Square
           !@discriminant.nil?
         end
 
+        # Check if value matches a type, handling type wrapper instances
+        # (Internal::Types::Hash and Internal::Types::Array instances)
+        #
+        # @param value [Object]
+        # @param member_type [Object]
+        # @return [Boolean]
+        private def type_matches?(value, member_type)
+          case member_type
+          when Square::Internal::Types::Hash
+            value.is_a?(::Hash)
+          when Square::Internal::Types::Array
+            value.is_a?(::Array)
+          when Class, Module
+            value.is_a?(member_type)
+          else
+            false
+          end
+        end
+
         # Resolves the type of a value to be one of the members
         #
         # @param value [Object]
         # @return [Class]
         private def resolve_member(value)
           if discriminated? && value.is_a?(::Hash)
-            disciminant_value = value.fetch(@discriminant, nil)
+            # Try both symbol and string keys for the discriminant
+            discriminant_value = value.fetch(@discriminant, nil) || value.fetch(@discriminant.to_s, nil)
 
-            return if disciminant_value.nil?
+            return if discriminant_value.nil?
 
-            members.to_h[disciminant_value]&.call
+            # Convert to string for consistent comparison
+            discriminant_str = discriminant_value.to_s
+
+            # First try exact match
+            members_hash = members.to_h
+            result = members_hash[discriminant_str]&.call
+            return result if result
+
+            # Try case-insensitive match as fallback
+            discriminant_lower = discriminant_str.downcase
+            matching_keys = members_hash.keys.select { |k| k.to_s.downcase == discriminant_lower }
+
+            # Only use case-insensitive match if exactly one key matches (avoid ambiguity)
+            return members_hash[matching_keys.first]&.call if matching_keys.length == 1
+
+            nil
           else
-            members.find do |_key, mem|
+            # First try exact type matching
+            result = members.find do |_key, mem|
               member_type = Utils.unwrap_type(mem)
-
-              value.is_a?(member_type)
+              type_matches?(value, member_type)
             end&.last&.call
+
+            return result if result
+
+            # For Hash values, try to coerce into Model member types
+            if value.is_a?(::Hash)
+              members.find do |_key, mem|
+                member_type = Utils.unwrap_type(mem)
+                # Check if member_type is a Model class
+                next unless member_type.is_a?(Class) && member_type <= Model
+
+                # Try to coerce the hash into this model type with strict mode
+                begin
+                  candidate = Utils.coerce(member_type, value, strict: true)
+
+                  # Validate that all required (non-optional) fields are present
+                  # This ensures undiscriminated unions properly distinguish between member types
+                  member_type.fields.each do |field_name, field|
+                    raise Errors::TypeError, "Required field `#{field_name}` missing for union member #{member_type.name}" if candidate.instance_variable_get(:@data)[field_name].nil? && !field.optional
+                  end
+
+                  true
+                rescue Errors::TypeError
+                  false
+                end
+              end&.last&.call
+            end
           end
         end
 
@@ -72,7 +133,27 @@ module Square
             raise Errors::TypeError, "could not resolve to member of union #{self}"
           end
 
-          Utils.coerce(type, value, strict: strict)
+          coerced = Utils.coerce(type, value, strict: strict)
+
+          # For discriminated unions, store the discriminant info on the coerced instance
+          # so it can be injected back during serialization (to_h)
+          if discriminated? && value.is_a?(::Hash) && coerced.is_a?(Model)
+            discriminant_value = value.fetch(@discriminant, nil) || value.fetch(@discriminant.to_s, nil)
+            if discriminant_value
+              coerced.instance_variable_set(:@_fern_union_discriminant_key, @discriminant.to_s)
+              coerced.instance_variable_set(:@_fern_union_discriminant_value, discriminant_value)
+            end
+          end
+
+          coerced
+        end
+
+        # Parse JSON string and coerce to the correct union member type
+        #
+        # @param str [String] JSON string to parse
+        # @return [Object] Coerced value matching a union member
+        def load(str)
+          coerce(::JSON.parse(str, symbolize_names: true))
         end
       end
     end

data/lib/square/internal/types/utils.rb

@@ -26,7 +26,7 @@ module Square
           type.is_a?(Proc) ? type.call : type
         end
 
-        def self.coerce(target, value, strict: false) # rubocop:disable Metrics/CyclomaticComplexity
+        def self.coerce(target, value, strict: false)
           type = unwrap_type(target)
 
           case type
@@ -75,9 +75,10 @@ module Square
             end
           in Module
             case type
-            in ->(t) { t.singleton_class.included_modules.include?(Enum) }
-              return type.coerce(value, strict: strict)
-            in ->(t) { t.singleton_class.included_modules.include?(Union) }
+            in ->(t) {
+                 t.singleton_class.include?(Enum) ||
+                   t.singleton_class.include?(Union)
+               }
               return type.coerce(value, strict: strict)
             else
               value
@@ -94,6 +95,21 @@ module Square
         def self.symbolize_keys(hash)
           hash.transform_keys(&:to_sym)
         end
+
+        # Converts camelCase keys to snake_case symbols
+        # This allows SDK methods to accept both snake_case and camelCase keys
+        # e.g., { refundMethod: ... } becomes { refund_method: ... }
+        #
+        # @param hash [Hash]
+        # @return [Hash]
+        def self.normalize_keys(hash)
+          hash.transform_keys do |key|
+            key_str = key.to_s
+            # Convert camelCase to snake_case
+            snake_case = key_str.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+            snake_case.to_sym
+          end
+        end
       end
     end
   end