square.rb 44.1.0.20250924 → 45.0.1.20260122

data/lib/square/gift_cards/client.rb

@@ -3,7 +3,9 @@
 module Square
   module GiftCards
     class Client
-      # @return [Square::GiftCards::Client]
+      # @param client [Square::Internal::Http::RawClient]
+      #
+      # @return [void]
       def initialize(client:)
         @client = client
       end
@@ -11,183 +13,275 @@ module Square
       # Lists all gift cards. You can specify optional filters to retrieve
       # a subset of the gift cards. Results are sorted by `created_at` in ascending order.
       #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String, nil] :type
+      # @option params [String, nil] :state
+      # @option params [Integer, nil] :limit
+      # @option params [String, nil] :cursor
+      # @option params [String, nil] :customer_id
+      #
       # @return [Square::Types::ListGiftCardsResponse]
       def list(request_options: {}, **params)
-        _query_param_names = [
-          %w[type state limit cursor customer_id],
-          %i[type state limit cursor customer_id]
-        ].flatten
-        _query = params.slice(*_query_param_names)
-        params.except(*_query_param_names)
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[type state limit cursor customer_id]
+        query_params = {}
+        query_params["type"] = params[:type] if params.key?(:type)
+        query_params["state"] = params[:state] if params.key?(:state)
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["cursor"] = params[:cursor] if params.key?(:cursor)
+        query_params["customer_id"] = params[:customer_id] if params.key?(:customer_id)
+        params.except(*query_param_names)
 
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
-          method: "GET",
-          path: "v2/gift-cards",
-          query: _query
-        )
-        begin
-          _response = @client.send(_request)
-        rescue Net::HTTPRequestTimeout
-          raise Square::Errors::TimeoutError
-        end
-        code = _response.code.to_i
-        if code.between?(200, 299)
-          Square::Types::ListGiftCardsResponse.load(_response.body)
-        else
-          error_class = Square::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(_response.body, code: code)
+        Square::Internal::CursorItemIterator.new(
+          cursor_field: :cursor,
+          item_field: :gift_cards,
+          initial_cursor: query_params[:cursor]
+        ) do |next_cursor|
+          query_params[:cursor] = next_cursor
+          request = Square::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "GET",
+            path: "v2/gift-cards",
+            query: query_params,
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise Square::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            Square::Types::ListGiftCardsResponse.load(response.body)
+          else
+            error_class = Square::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
         end
       end
 
       # Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card
       # has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call
       # [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) and create an `ACTIVATE`
-      # activity with the initial balance. Alternatively, you can use [RefundPayment](api-endpoint:Refunds-RefundPayment)
+      # activity with the initial balance. Alternatively, you can use
+      # [RefundPayment](api-endpoint:Refunds-RefundPayment)
       # to refund a payment to the new gift card.
       #
+      # @param request_options [Hash]
+      # @param params [Square::GiftCards::Types::CreateGiftCardRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
       # @return [Square::Types::CreateGiftCardResponse]
       def create(request_options: {}, **params)
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
           method: "POST",
           path: "v2/gift-cards",
-          body: params
+          body: Square::GiftCards::Types::CreateGiftCardRequest.new(params).to_h,
+          request_options: request_options
         )
         begin
-          _response = @client.send(_request)
+          response = @client.send(request)
         rescue Net::HTTPRequestTimeout
           raise Square::Errors::TimeoutError
         end
-        code = _response.code.to_i
+        code = response.code.to_i
         if code.between?(200, 299)
-          Square::Types::CreateGiftCardResponse.load(_response.body)
+          Square::Types::CreateGiftCardResponse.load(response.body)
         else
           error_class = Square::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(_response.body, code: code)
+          raise error_class.new(response.body, code: code)
         end
       end
 
       # Retrieves a gift card using the gift card account number (GAN).
       #
+      # @param request_options [Hash]
+      # @param params [Square::GiftCards::Types::GetGiftCardFromGanRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
       # @return [Square::Types::GetGiftCardFromGanResponse]
       def get_from_gan(request_options: {}, **params)
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
           method: "POST",
           path: "v2/gift-cards/from-gan",
-          body: params
+          body: Square::GiftCards::Types::GetGiftCardFromGanRequest.new(params).to_h,
+          request_options: request_options
         )
         begin
-          _response = @client.send(_request)
+          response = @client.send(request)
         rescue Net::HTTPRequestTimeout
           raise Square::Errors::TimeoutError
         end
-        code = _response.code.to_i
+        code = response.code.to_i
         if code.between?(200, 299)
-          Square::Types::GetGiftCardFromGanResponse.load(_response.body)
+          Square::Types::GetGiftCardFromGanResponse.load(response.body)
         else
           error_class = Square::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(_response.body, code: code)
+          raise error_class.new(response.body, code: code)
         end
       end
 
       # Retrieves a gift card using a secure payment token that represents the gift card.
       #
+      # @param request_options [Hash]
+      # @param params [Square::GiftCards::Types::GetGiftCardFromNonceRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
       # @return [Square::Types::GetGiftCardFromNonceResponse]
       def get_from_nonce(request_options: {}, **params)
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
           method: "POST",
           path: "v2/gift-cards/from-nonce",
-          body: params
+          body: Square::GiftCards::Types::GetGiftCardFromNonceRequest.new(params).to_h,
+          request_options: request_options
         )
         begin
-          _response = @client.send(_request)
+          response = @client.send(request)
         rescue Net::HTTPRequestTimeout
           raise Square::Errors::TimeoutError
         end
-        code = _response.code.to_i
+        code = response.code.to_i
         if code.between?(200, 299)
-          Square::Types::GetGiftCardFromNonceResponse.load(_response.body)
+          Square::Types::GetGiftCardFromNonceResponse.load(response.body)
         else
           error_class = Square::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(_response.body, code: code)
+          raise error_class.new(response.body, code: code)
         end
       end
 
       # Links a customer to a gift card, which is also referred to as adding a card on file.
       #
+      # @param request_options [Hash]
+      # @param params [Square::GiftCards::Types::LinkCustomerToGiftCardRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :gift_card_id
+      #
       # @return [Square::Types::LinkCustomerToGiftCardResponse]
       def link_customer(request_options: {}, **params)
-        _path_param_names = ["gift_card_id"]
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request_data = Square::GiftCards::Types::LinkCustomerToGiftCardRequest.new(params).to_h
+        non_body_param_names = ["gift_card_id"]
+        body = request_data.except(*non_body_param_names)
 
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
           method: "POST",
           path: "v2/gift-cards/#{params[:gift_card_id]}/link-customer",
-          body: params.except(*_path_param_names)
+          body: body,
+          request_options: request_options
         )
         begin
-          _response = @client.send(_request)
+          response = @client.send(request)
         rescue Net::HTTPRequestTimeout
           raise Square::Errors::TimeoutError
         end
-        code = _response.code.to_i
+        code = response.code.to_i
         if code.between?(200, 299)
-          Square::Types::LinkCustomerToGiftCardResponse.load(_response.body)
+          Square::Types::LinkCustomerToGiftCardResponse.load(response.body)
         else
           error_class = Square::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(_response.body, code: code)
+          raise error_class.new(response.body, code: code)
         end
       end
 
       # Unlinks a customer from a gift card, which is also referred to as removing a card on file.
       #
+      # @param request_options [Hash]
+      # @param params [Square::GiftCards::Types::UnlinkCustomerFromGiftCardRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :gift_card_id
+      #
       # @return [Square::Types::UnlinkCustomerFromGiftCardResponse]
       def unlink_customer(request_options: {}, **params)
-        _path_param_names = ["gift_card_id"]
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request_data = Square::GiftCards::Types::UnlinkCustomerFromGiftCardRequest.new(params).to_h
+        non_body_param_names = ["gift_card_id"]
+        body = request_data.except(*non_body_param_names)
 
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
           method: "POST",
           path: "v2/gift-cards/#{params[:gift_card_id]}/unlink-customer",
-          body: params.except(*_path_param_names)
+          body: body,
+          request_options: request_options
         )
         begin
-          _response = @client.send(_request)
+          response = @client.send(request)
         rescue Net::HTTPRequestTimeout
           raise Square::Errors::TimeoutError
         end
-        code = _response.code.to_i
+        code = response.code.to_i
         if code.between?(200, 299)
-          Square::Types::UnlinkCustomerFromGiftCardResponse.load(_response.body)
+          Square::Types::UnlinkCustomerFromGiftCardResponse.load(response.body)
         else
           error_class = Square::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(_response.body, code: code)
+          raise error_class.new(response.body, code: code)
         end
       end
 
       # Retrieves a gift card using the gift card ID.
       #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      #
       # @return [Square::Types::GetGiftCardResponse]
       def get(request_options: {}, **params)
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
           method: "GET",
-          path: "v2/gift-cards/#{params[:id]}"
+          path: "v2/gift-cards/#{params[:id]}",
+          request_options: request_options
         )
         begin
-          _response = @client.send(_request)
+          response = @client.send(request)
         rescue Net::HTTPRequestTimeout
           raise Square::Errors::TimeoutError
         end
-        code = _response.code.to_i
+        code = response.code.to_i
         if code.between?(200, 299)
-          Square::Types::GetGiftCardResponse.load(_response.body)
+          Square::Types::GetGiftCardResponse.load(response.body)
         else
           error_class = Square::Errors::ResponseError.subclass_for_code(code)
-          raise error_class.new(_response.body, code: code)
+          raise error_class.new(response.body, code: code)
         end
       end
 

data/lib/square/internal/http/base_request.rb

@@ -22,6 +22,12 @@ module Square
           @request_options = request_options
         end
 
+        # @return [Hash] The query parameters merged with additional query parameters from request options.
+        def encode_query
+          additional_query = @request_options&.dig(:additional_query_parameters) || @request_options&.dig("additional_query_parameters") || {}
+          @query.merge(additional_query)
+        end
+
         # Child classes should implement:
         # - encode_headers: Returns the encoded HTTP request headers.
         # - encode_body: Returns the encoded HTTP request body.

data/lib/square/internal/http/raw_client.rb

@@ -5,6 +5,18 @@ module Square
     module Http
       # @api private
       class RawClient
+        # Default HTTP status codes that trigger a retry
+        RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504, 521, 522, 524].freeze
+        # Initial delay between retries in seconds
+        INITIAL_RETRY_DELAY = 0.5
+        # Maximum delay between retries in seconds
+        MAX_RETRY_DELAY = 60.0
+        # Jitter factor for randomizing retry delays (20%)
+        JITTER_FACTOR = 0.2
+
+        # @return [String] The base URL for requests
+        attr_reader :base_url
+
         # @param base_url [String] The base url for the request.
         # @param max_retries [Integer] The number of times to retry a failed request, defaults to 2.
         # @param timeout [Float] The timeout for the request, defaults to 60.0 seconds.
@@ -24,34 +36,106 @@ module Square
         # @return [HTTP::Response] The HTTP response.
         def send(request)
           url = build_url(request)
+          attempt = 0
+          response = nil
 
-          http_request = build_http_request(
-            url:,
-            method: request.method,
-            headers: request.encode_headers,
-            body: request.encode_body
-          )
+          loop do
+            http_request = build_http_request(
+              url:,
+              method: request.method,
+              headers: request.encode_headers,
+              body: request.encode_body
+            )
+
+            conn = connect(url)
+            conn.open_timeout = @timeout
+            conn.read_timeout = @timeout
+            conn.write_timeout = @timeout
+            conn.continue_timeout = @timeout
+
+            response = conn.request(http_request)
+
+            break unless should_retry?(response, attempt)
+
+            delay = retry_delay(response, attempt)
+            sleep(delay)
+            attempt += 1
+          end
+
+          response
+        end
+
+        # Determines if a request should be retried based on the response status code.
+        # @param response [Net::HTTPResponse] The HTTP response.
+        # @param attempt [Integer] The current retry attempt (0-indexed).
+        # @return [Boolean] Whether the request should be retried.
+        def should_retry?(response, attempt)
+          return false if attempt >= @max_retries
+
+          status = response.code.to_i
+          RETRYABLE_STATUSES.include?(status)
+        end
+
+        # Calculates the delay before the next retry attempt using exponential backoff with jitter.
+        # Respects Retry-After header if present.
+        # @param response [Net::HTTPResponse] The HTTP response.
+        # @param attempt [Integer] The current retry attempt (0-indexed).
+        # @return [Float] The delay in seconds before the next retry.
+        def retry_delay(response, attempt)
+          # Check for Retry-After header (can be seconds or HTTP date)
+          retry_after = response["Retry-After"]
+          if retry_after
+            delay = parse_retry_after(retry_after)
+            return [delay, MAX_RETRY_DELAY].min if delay&.positive?
+          end
+
+          # Exponential backoff with jitter: base_delay * 2^attempt
+          base_delay = INITIAL_RETRY_DELAY * (2**attempt)
+          add_jitter([base_delay, MAX_RETRY_DELAY].min)
+        end
+
+        # Parses the Retry-After header value.
+        # @param value [String] The Retry-After header value (seconds or HTTP date).
+        # @return [Float, nil] The delay in seconds, or nil if parsing fails.
+        def parse_retry_after(value)
+          # Try parsing as integer (seconds)
+          seconds = Integer(value, exception: false)
+          return seconds.to_f if seconds
 
-          conn = connect(url)
-          conn.open_timeout = @timeout
-          conn.read_timeout = @timeout
-          conn.write_timeout = @timeout
-          conn.continue_timeout = @timeout
-
-          conn.request(http_request)
-          # begin
-          #   conn.request(http_request)
-          # rescue StandardError => e
-          #   raise HttpError, "HTTP request failed: #{e.message}"
-          # end
+          # Try parsing as HTTP date
+          begin
+            retry_time = Time.httpdate(value)
+            delay = retry_time - Time.now
+            delay.positive? ? delay : nil
+          rescue ArgumentError
+            nil
+          end
+        end
+
+        # Adds random jitter to a delay value.
+        # @param delay [Float] The base delay in seconds.
+        # @return [Float] The delay with jitter applied.
+        def add_jitter(delay)
+          jitter = delay * JITTER_FACTOR * (rand - 0.5) * 2
+          [delay + jitter, 0].max
         end
 
         # @param request [Square::Internal::Http::BaseRequest] The HTTP request.
         # @return [URI::Generic] The URL.
         def build_url(request)
+          encoded_query = request.encode_query
+
+          # If the path is already an absolute URL, use it directly
+          if request.path.start_with?("http://", "https://")
+            url = request.path
+            url = "#{url}?#{encode_query(encoded_query)}" if encoded_query&.any?
+            return URI.parse(url)
+          end
+
           path = request.path.start_with?("/") ? request.path[1..] : request.path
-          url = "#{@base_url.chomp("/")}/#{path}"
-          url = "#{url}?#{encode_query(request.query)}" if request.query&.any?
+          base = request.base_url || @base_url
+          url = "#{base.chomp("/")}/#{path}"
+          url = "#{url}?#{encode_query(encoded_query)}" if encoded_query&.any?
           URI.parse(url)
         end
 
@@ -96,9 +180,16 @@ module Square
 
           http = Net::HTTP.new(url.host, port)
           http.use_ssl = is_https
+          # NOTE: We handle retries at the application level with HTTP status code awareness,
+          # so we set max_retries to 0 to disable Net::HTTP's built-in network-level retries.
           http.max_retries = 0
           http
         end
+
+        # @return [String]
+        def inspect
+          "#<#{self.class.name}:0x#{object_id.to_s(16)} @base_url=#{@base_url.inspect}>"
+        end
       end
     end
   end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Square
+  module Internal
+    class CursorItemIterator < ItemIterator
+      # Instantiates a CursorItemIterator, an Enumerable class which wraps calls to a cursor-based paginated API and yields individual items from it.
+      #
+      # @param initial_cursor [String] The initial cursor to use when iterating, if any.
+      # @param cursor_field [Symbol] The field in API responses to extract the next cursor from.
+      # @param item_field [Symbol] The field in API responses to extract the items to iterate over.
+      # @param block [Proc] A block which is responsible for receiving a cursor to use and returning the given page from the API.
+      # @return [Square::Internal::CursorItemIterator]
+      def initialize(initial_cursor:, cursor_field:, item_field:, &)
+        super()
+        @item_field = item_field
+        @page_iterator = CursorPageIterator.new(initial_cursor:, cursor_field:, &)
+        @page = nil
+      end
+
+      # Returns the CursorPageIterator mediating access to the underlying API.
+      #
+      # @return [Square::Internal::CursorPageIterator]
+      def pages
+        @page_iterator
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Square
+  module Internal
+    class CursorPageIterator
+      include Enumerable
+
+      # Instantiates a CursorPageIterator, an Enumerable class which wraps calls to a cursor-based paginated API and yields pages of items.
+      #
+      # @param initial_cursor [String] The initial cursor to use when iterating, if any.
+      # @param cursor_field [Symbol] The name of the field in API responses to extract the next cursor from.
+      # @param block [Proc] A block which is responsible for receiving a cursor to use and returning the given page from the API.
+      # @return [Square::Internal::CursorPageIterator]
+      def initialize(initial_cursor:, cursor_field:, &block)
+        @need_initial_load = initial_cursor.nil?
+        @cursor = initial_cursor
+        @cursor_field = cursor_field
+        @get_next_page = block
+      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?
+        @need_initial_load || !@cursor.nil?
+      end
+
+      # Retrieves the next page from the API.
+      #
+      # @return [Boolean]
+      def next_page
+        return if !@need_initial_load && @cursor.nil?
+
+        @need_initial_load = false
+        fetched_page = @get_next_page.call(@cursor)
+        @cursor = fetched_page.send(@cursor_field)
+        fetched_page
+      end
+    end
+  end
+end