square.rb 44.1.0.20250924 → 45.0.1.20260122

data/lib/square/payments/client.rb

@@ -3,7 +3,9 @@
 module Square
   module Payments
     class Client
-      # @return [Square::Payments::Client]
+      # @param client [Square::Internal::Http::RawClient]
+      #
+      # @return [void]
       def initialize(client:)
         @client = client
       end
@@ -15,34 +17,76 @@ module Square
       #
       # The maximum results per page is 100.
       #
+      # @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] :begin_time
+      # @option params [String, nil] :end_time
+      # @option params [String, nil] :sort_order
+      # @option params [String, nil] :cursor
+      # @option params [String, nil] :location_id
+      # @option params [Integer, nil] :total
+      # @option params [String, nil] :last_4
+      # @option params [String, nil] :card_brand
+      # @option params [Integer, nil] :limit
+      # @option params [Boolean, nil] :is_offline_payment
+      # @option params [String, nil] :offline_begin_time
+      # @option params [String, nil] :offline_end_time
+      # @option params [String, nil] :updated_at_begin_time
+      # @option params [String, nil] :updated_at_end_time
+      # @option params [Square::Types::ListPaymentsRequestSortField, nil] :sort_field
+      #
       # @return [Square::Types::ListPaymentsResponse]
       def list(request_options: {}, **params)
-        _query_param_names = [
-          %w[begin_time end_time sort_order cursor location_id total last_4 card_brand limit
-             is_offline_payment offline_begin_time offline_end_time updated_at_begin_time updated_at_end_time sort_field],
-          %i[begin_time end_time sort_order cursor location_id total last_4 card_brand limit is_offline_payment
-             offline_begin_time offline_end_time updated_at_begin_time updated_at_end_time sort_field]
-        ].flatten
-        _query = params.slice(*_query_param_names)
-        params.except(*_query_param_names)
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[begin_time end_time sort_order cursor location_id total last_4 card_brand limit is_offline_payment offline_begin_time offline_end_time updated_at_begin_time updated_at_end_time sort_field]
+        query_params = {}
+        query_params["begin_time"] = params[:begin_time] if params.key?(:begin_time)
+        query_params["end_time"] = params[:end_time] if params.key?(:end_time)
+        query_params["sort_order"] = params[:sort_order] if params.key?(:sort_order)
+        query_params["cursor"] = params[:cursor] if params.key?(:cursor)
+        query_params["location_id"] = params[:location_id] if params.key?(:location_id)
+        query_params["total"] = params[:total] if params.key?(:total)
+        query_params["last_4"] = params[:last_4] if params.key?(:last_4)
+        query_params["card_brand"] = params[:card_brand] if params.key?(:card_brand)
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["is_offline_payment"] = params[:is_offline_payment] if params.key?(:is_offline_payment)
+        query_params["offline_begin_time"] = params[:offline_begin_time] if params.key?(:offline_begin_time)
+        query_params["offline_end_time"] = params[:offline_end_time] if params.key?(:offline_end_time)
+        query_params["updated_at_begin_time"] = params[:updated_at_begin_time] if params.key?(:updated_at_begin_time)
+        query_params["updated_at_end_time"] = params[:updated_at_end_time] if params.key?(:updated_at_end_time)
+        query_params["sort_field"] = params[:sort_field] if params.key?(:sort_field)
+        params.except(*query_param_names)
 
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
-          method: "GET",
-          path: "v2/payments",
-          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::ListPaymentsResponse.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: :payments,
+          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/payments",
+            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::ListPaymentsResponse.load(response.body)
+          else
+            error_class = Square::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
         end
       end
 
@@ -55,25 +99,35 @@ module Square
       # The endpoint creates a
       # `Payment` object and returns it in the response.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Payments::Types::CreatePaymentRequest]
+      # @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::CreatePaymentResponse]
       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/payments",
-          body: params
+          body: Square::Payments::Types::CreatePaymentRequest.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::CreatePaymentResponse.load(_response.body)
+          Square::Types::CreatePaymentResponse.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
 
@@ -89,99 +143,144 @@ module Square
       # Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint
       # returns successfully.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Payments::Types::CancelPaymentByIdempotencyKeyRequest]
+      # @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::CancelPaymentByIdempotencyKeyResponse]
       def cancel_by_idempotency_key(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/payments/cancel",
-          body: params
+          body: Square::Payments::Types::CancelPaymentByIdempotencyKeyRequest.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::CancelPaymentByIdempotencyKeyResponse.load(_response.body)
+          Square::Types::CancelPaymentByIdempotencyKeyResponse.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 details for a specific payment.
       #
+      # @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] :payment_id
+      #
       # @return [Square::Types::GetPaymentResponse]
       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/payments/#{params[:payment_id]}"
+          path: "v2/payments/#{params[:payment_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::GetPaymentResponse.load(_response.body)
+          Square::Types::GetPaymentResponse.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
 
       # Updates a payment with the APPROVED status.
       # You can update the `amount_money` and `tip_money` using this endpoint.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Payments::Types::UpdatePaymentRequest]
+      # @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] :payment_id
+      #
       # @return [Square::Types::UpdatePaymentResponse]
       def update(request_options: {}, **params)
-        _path_param_names = ["payment_id"]
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request_data = Square::Payments::Types::UpdatePaymentRequest.new(params).to_h
+        non_body_param_names = ["payment_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: "PUT",
           path: "v2/payments/#{params[:payment_id]}",
-          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::UpdatePaymentResponse.load(_response.body)
+          Square::Types::UpdatePaymentResponse.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
 
       # Cancels (voids) a payment. You can use this endpoint to cancel a payment with
       # the APPROVED `status`.
       #
+      # @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] :payment_id
+      #
       # @return [Square::Types::CancelPaymentResponse]
       def cancel(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/payments/#{params[:payment_id]}/cancel"
+          path: "v2/payments/#{params[:payment_id]}/cancel",
+          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::CancelPaymentResponse.load(_response.body)
+          Square::Types::CancelPaymentResponse.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
 
@@ -190,27 +289,40 @@ module Square
       #
       # You can use this endpoint to complete a payment with the APPROVED `status`.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Payments::Types::CompletePaymentRequest]
+      # @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] :payment_id
+      #
       # @return [Square::Types::CompletePaymentResponse]
       def complete(request_options: {}, **params)
-        _path_param_names = ["payment_id"]
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request_data = Square::Payments::Types::CompletePaymentRequest.new(params).to_h
+        non_body_param_names = ["payment_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/payments/#{params[:payment_id]}/complete",
-          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::CompletePaymentResponse.load(_response.body)
+          Square::Types::CompletePaymentResponse.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
     end

data/lib/square/payouts/client.rb

@@ -3,7 +3,9 @@
 module Square
   module Payouts
     class Client
-      # @return [Square::Payouts::Client]
+      # @param client [Square::Internal::Http::RawClient]
+      #
+      # @return [void]
       def initialize(client:)
         @client = client
       end
@@ -12,88 +14,148 @@ module Square
       # You can filter payouts by location ID, status, time range, and order them in ascending or descending order.
       # To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.
       #
+      # @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] :location_id
+      # @option params [Square::Types::PayoutStatus, nil] :status
+      # @option params [String, nil] :begin_time
+      # @option params [String, nil] :end_time
+      # @option params [Square::Types::SortOrder, nil] :sort_order
+      # @option params [String, nil] :cursor
+      # @option params [Integer, nil] :limit
+      #
       # @return [Square::Types::ListPayoutsResponse]
       def list(request_options: {}, **params)
-        _query_param_names = [
-          %w[location_id status begin_time end_time sort_order cursor limit],
-          %i[location_id status begin_time end_time sort_order cursor limit]
-        ].flatten
-        _query = params.slice(*_query_param_names)
-        params.except(*_query_param_names)
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[location_id status begin_time end_time sort_order cursor limit]
+        query_params = {}
+        query_params["location_id"] = params[:location_id] if params.key?(:location_id)
+        query_params["status"] = params[:status] if params.key?(:status)
+        query_params["begin_time"] = params[:begin_time] if params.key?(:begin_time)
+        query_params["end_time"] = params[:end_time] if params.key?(:end_time)
+        query_params["sort_order"] = params[:sort_order] if params.key?(:sort_order)
+        query_params["cursor"] = params[:cursor] if params.key?(:cursor)
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        params.except(*query_param_names)
 
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
-          method: "GET",
-          path: "v2/payouts",
-          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::ListPayoutsResponse.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: :payouts,
+          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/payouts",
+            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::ListPayoutsResponse.load(response.body)
+          else
+            error_class = Square::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
         end
       end
 
       # Retrieves details of a specific payout identified by a payout ID.
       # To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.
       #
+      # @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] :payout_id
+      #
       # @return [Square::Types::GetPayoutResponse]
       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/payouts/#{params[:payout_id]}"
+          path: "v2/payouts/#{params[:payout_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::GetPayoutResponse.load(_response.body)
+          Square::Types::GetPayoutResponse.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 list of all payout entries for a specific payout.
       # To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.
       #
+      # @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] :payout_id
+      # @option params [Square::Types::SortOrder, nil] :sort_order
+      # @option params [String, nil] :cursor
+      # @option params [Integer, nil] :limit
+      #
       # @return [Square::Types::ListPayoutEntriesResponse]
       def list_entries(request_options: {}, **params)
-        _query_param_names = [
-          %w[sort_order cursor limit],
-          %i[sort_order cursor limit]
-        ].flatten
-        _query = params.slice(*_query_param_names)
-        params = params.except(*_query_param_names)
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[sort_order cursor limit]
+        query_params = {}
+        query_params["sort_order"] = params[:sort_order] if params.key?(:sort_order)
+        query_params["cursor"] = params[:cursor] if params.key?(:cursor)
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        params = params.except(*query_param_names)
 
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
-          method: "GET",
-          path: "v2/payouts/#{params[:payout_id]}/payout-entries",
-          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::ListPayoutEntriesResponse.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: :payout_entries,
+          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/payouts/#{params[:payout_id]}/payout-entries",
+            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::ListPayoutEntriesResponse.load(response.body)
+          else
+            error_class = Square::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
         end
       end
     end