square.rb 44.2.0.20251016 → 45.0.1.20260122

data/lib/square/customers/client.rb

@@ -3,7 +3,9 @@
 module Square
   module Customers
     class Client
-      # @return [Square::Customers::Client]
+      # @param client [Square::Internal::Http::RawClient]
+      #
+      # @return [void]
       def initialize(client:)
         @client = client
       end
@@ -14,32 +16,56 @@ module Square
       # for the listing operation in well under 30 seconds. Occasionally, propagation of the new or updated
       # profiles can take closer to one minute or longer, especially during network incidents and outages.
       #
+      # @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] :cursor
+      # @option params [Integer, nil] :limit
+      # @option params [Square::Types::CustomerSortField, nil] :sort_field
+      # @option params [Square::Types::SortOrder, nil] :sort_order
+      # @option params [Boolean, nil] :count
+      #
       # @return [Square::Types::ListCustomersResponse]
       def list(request_options: {}, **params)
-        _query_param_names = [
-          %w[cursor limit sort_field sort_order count],
-          %i[cursor limit sort_field sort_order count]
-        ].flatten
-        _query = params.slice(*_query_param_names)
-        params.except(*_query_param_names)
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[cursor limit sort_field sort_order count]
+        query_params = {}
+        query_params["cursor"] = params[:cursor] if params.key?(:cursor)
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["sort_field"] = params[:sort_field] if params.key?(:sort_field)
+        query_params["sort_order"] = params[:sort_order] if params.key?(:sort_order)
+        query_params["count"] = params[:count] if params.key?(:count)
+        params.except(*query_param_names)
 
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
-          method: "GET",
-          path: "v2/customers",
-          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::ListCustomersResponse.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: :customers,
+          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/customers",
+            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::ListCustomersResponse.load(response.body)
+          else
+            error_class = Square::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
         end
       end
 
@@ -54,25 +80,35 @@ module Square
       # - `email_address`
       # - `phone_number`
       #
+      # @param request_options [Hash]
+      # @param params [Square::Customers::Types::CreateCustomerRequest]
+      # @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::CreateCustomerResponse]
       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/customers",
-          body: params
+          body: Square::Customers::Types::CreateCustomerRequest.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::CreateCustomerResponse.load(_response.body)
+          Square::Types::CreateCustomerResponse.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
 
@@ -88,25 +124,35 @@ module Square
       # - `email_address`
       # - `phone_number`
       #
+      # @param request_options [Hash]
+      # @param params [Square::Customers::Types::BulkCreateCustomersRequest]
+      # @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::BulkCreateCustomersResponse]
       def batch_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/customers/bulk-create",
-          body: params
+          body: Square::Customers::Types::BulkCreateCustomersRequest.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::BulkCreateCustomersResponse.load(_response.body)
+          Square::Types::BulkCreateCustomersResponse.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
 
@@ -114,25 +160,35 @@ module Square
       #
       # The endpoint takes a list of customer IDs and returns a map of responses.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Customers::Types::BulkDeleteCustomersRequest]
+      # @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::BulkDeleteCustomersResponse]
       def bulk_delete_customers(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/customers/bulk-delete",
-          body: params
+          body: Square::Customers::Types::BulkDeleteCustomersRequest.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::BulkDeleteCustomersResponse.load(_response.body)
+          Square::Types::BulkDeleteCustomersResponse.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
 
@@ -140,25 +196,35 @@ module Square
       #
       # This endpoint takes a list of customer IDs and returns a map of responses.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Customers::Types::BulkRetrieveCustomersRequest]
+      # @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::BulkRetrieveCustomersResponse]
       def bulk_retrieve_customers(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/customers/bulk-retrieve",
-          body: params
+          body: Square::Customers::Types::BulkRetrieveCustomersRequest.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::BulkRetrieveCustomersResponse.load(_response.body)
+          Square::Types::BulkRetrieveCustomersResponse.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
 
@@ -166,25 +232,35 @@ module Square
       #
       # This endpoint takes a map of individual update requests and returns a map of responses.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Customers::Types::BulkUpdateCustomersRequest]
+      # @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::BulkUpdateCustomersResponse]
       def bulk_update_customers(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/customers/bulk-update",
-          body: params
+          body: Square::Customers::Types::BulkUpdateCustomersRequest.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::BulkUpdateCustomersResponse.load(_response.body)
+          Square::Types::BulkUpdateCustomersResponse.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
 
@@ -198,110 +274,157 @@ module Square
       # for the search operation in well under 30 seconds. Occasionally, propagation of the new or updated
       # profiles can take closer to one minute or longer, especially during network incidents and outages.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Customers::Types::SearchCustomersRequest]
+      # @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::SearchCustomersResponse]
       def search(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/customers/search",
-          body: params
+          body: Square::Customers::Types::SearchCustomersRequest.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::SearchCustomersResponse.load(_response.body)
+          Square::Types::SearchCustomersResponse.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
 
       # Returns details for a single customer.
       #
+      # @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] :customer_id
+      #
       # @return [Square::Types::GetCustomerResponse]
       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/customers/#{params[:customer_id]}"
+          path: "v2/customers/#{params[:customer_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::GetCustomerResponse.load(_response.body)
+          Square::Types::GetCustomerResponse.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 customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request.
+      # Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in
+      # the request.
       # To add or update a field, specify the new value. To remove a field, specify `null`.
       #
-      # To update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.
+      # To update a customer profile that was created by merging existing profiles, you must use the ID of the newly
+      # created profile.
+      #
+      # @param request_options [Hash]
+      # @param params [Square::Customers::Types::UpdateCustomerRequest]
+      # @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] :customer_id
       #
       # @return [Square::Types::UpdateCustomerResponse]
       def update(request_options: {}, **params)
-        _path_param_names = ["customer_id"]
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request_data = Square::Customers::Types::UpdateCustomerRequest.new(params).to_h
+        non_body_param_names = ["customer_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/customers/#{params[:customer_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::UpdateCustomerResponse.load(_response.body)
+          Square::Types::UpdateCustomerResponse.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
 
       # Deletes a customer profile from a business.
       #
-      # To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.
+      # To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly
+      # created profile.
+      #
+      # @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] :customer_id
+      # @option params [Integer, nil] :version
       #
       # @return [Square::Types::DeleteCustomerResponse]
       def delete(request_options: {}, **params)
-        _query_param_names = [
-          ["version"],
-          %i[version]
-        ].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[version]
+        query_params = {}
+        query_params["version"] = params[:version] if params.key?(:version)
+        params = params.except(*query_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: "DELETE",
           path: "v2/customers/#{params[:customer_id]}",
-          query: _query
+          query: query_params,
+          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::DeleteCustomerResponse.load(_response.body)
+          Square::Types::DeleteCustomerResponse.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