square.rb 44.2.0.20251016 → 45.0.1.20260122

data/lib/square/bookings/client.rb

@@ -3,7 +3,9 @@
 module Square
   module Bookings
     class Client
-      # @return [Square::Bookings::Client]
+      # @param client [Square::Internal::Http::RawClient]
+      #
+      # @return [void]
       def initialize(client:)
         @client = client
       end
@@ -11,34 +13,63 @@ module Square
       # Retrieve a collection of bookings.
       #
       # To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.
-      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
+      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_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 [Integer, nil] :limit
+      # @option params [String, nil] :cursor
+      # @option params [String, nil] :customer_id
+      # @option params [String, nil] :team_member_id
+      # @option params [String, nil] :location_id
+      # @option params [String, nil] :start_at_min
+      # @option params [String, nil] :start_at_max
       #
       # @return [Square::Types::ListBookingsResponse]
       def list(request_options: {}, **params)
-        _query_param_names = [
-          %w[limit cursor customer_id team_member_id location_id start_at_min start_at_max],
-          %i[limit cursor customer_id team_member_id location_id start_at_min start_at_max]
-        ].flatten
-        _query = params.slice(*_query_param_names)
-        params.except(*_query_param_names)
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[limit cursor customer_id team_member_id location_id start_at_min start_at_max]
+        query_params = {}
+        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)
+        query_params["team_member_id"] = params[:team_member_id] if params.key?(:team_member_id)
+        query_params["location_id"] = params[:location_id] if params.key?(:location_id)
+        query_params["start_at_min"] = params[:start_at_min] if params.key?(:start_at_min)
+        query_params["start_at_max"] = params[:start_at_max] if params.key?(:start_at_max)
+        params.except(*query_param_names)
 
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
-          method: "GET",
-          path: "v2/bookings",
-          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::ListBookingsResponse.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: :bookings,
+          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/bookings",
+            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::ListBookingsResponse.load(response.body)
+          else
+            error_class = Square::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
         end
       end
 
@@ -52,244 +83,351 @@ module Square
       # - `Booking.AppointmentSegment.service_variation_version`
       #
       # To call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.
-      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.
+      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for
+      # the OAuth scope.
       #
-      # For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*
+      # For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to
+      # *Appointments Plus*
       # or *Appointments Premium*.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Bookings::Types::CreateBookingRequest]
+      # @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::CreateBookingResponse]
       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/bookings",
-          body: params
+          body: Square::Bookings::Types::CreateBookingRequest.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::CreateBookingResponse.load(_response.body)
+          Square::Types::CreateBookingResponse.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
 
       # Searches for availabilities for booking.
       #
       # To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.
-      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
+      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the
+      # OAuth scope.
+      #
+      # @param request_options [Hash]
+      # @param params [Square::Bookings::Types::SearchAvailabilityRequest]
+      # @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::SearchAvailabilityResponse]
       def search_availability(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/bookings/availability/search",
-          body: params
+          body: Square::Bookings::Types::SearchAvailabilityRequest.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::SearchAvailabilityResponse.load(_response.body)
+          Square::Types::SearchAvailabilityResponse.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
 
       # Bulk-Retrieves a list of bookings by booking IDs.
       #
       # To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.
-      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
+      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the
+      # OAuth scope.
+      #
+      # @param request_options [Hash]
+      # @param params [Square::Bookings::Types::BulkRetrieveBookingsRequest]
+      # @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::BulkRetrieveBookingsResponse]
       def bulk_retrieve_bookings(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/bookings/bulk-retrieve",
-          body: params
+          body: Square::Bookings::Types::BulkRetrieveBookingsRequest.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::BulkRetrieveBookingsResponse.load(_response.body)
+          Square::Types::BulkRetrieveBookingsResponse.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 seller's booking 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
+      #
       # @return [Square::Types::GetBusinessBookingProfileResponse]
-      def get_business_profile(request_options: {}, **_params)
-        _request = Square::Internal::JSON::Request.new(
-          base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
+      def get_business_profile(request_options: {}, **params)
+        Square::Internal::Types::Utils.normalize_keys(params)
+        request = Square::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
           method: "GET",
-          path: "v2/bookings/business-booking-profile"
+          path: "v2/bookings/business-booking-profile",
+          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::GetBusinessBookingProfileResponse.load(_response.body)
+          Square::Types::GetBusinessBookingProfileResponse.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 seller's location booking 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] :location_id
+      #
       # @return [Square::Types::RetrieveLocationBookingProfileResponse]
       def retrieve_location_booking_profile(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/bookings/location-booking-profiles/#{params[:location_id]}"
+          path: "v2/bookings/location-booking-profiles/#{params[:location_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::RetrieveLocationBookingProfileResponse.load(_response.body)
+          Square::Types::RetrieveLocationBookingProfileResponse.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 one or more team members' booking profiles.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Bookings::Types::BulkRetrieveTeamMemberBookingProfilesRequest]
+      # @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::BulkRetrieveTeamMemberBookingProfilesResponse]
       def bulk_retrieve_team_member_booking_profiles(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/bookings/team-member-booking-profiles/bulk-retrieve",
-          body: params
+          body: Square::Bookings::Types::BulkRetrieveTeamMemberBookingProfilesRequest.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::BulkRetrieveTeamMemberBookingProfilesResponse.load(_response.body)
+          Square::Types::BulkRetrieveTeamMemberBookingProfilesResponse.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 booking.
       #
       # To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.
-      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
+      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_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] :booking_id
       #
       # @return [Square::Types::GetBookingResponse]
       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/bookings/#{params[:booking_id]}"
+          path: "v2/bookings/#{params[:booking_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::GetBookingResponse.load(_response.body)
+          Square::Types::GetBookingResponse.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 booking.
       #
       # To call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.
-      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.
+      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for
+      # the OAuth scope.
       #
-      # For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*
+      # For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to
+      # *Appointments Plus*
       # or *Appointments Premium*.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Bookings::Types::UpdateBookingRequest]
+      # @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] :booking_id
+      #
       # @return [Square::Types::UpdateBookingResponse]
       def update(request_options: {}, **params)
-        _path_param_names = ["booking_id"]
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request_data = Square::Bookings::Types::UpdateBookingRequest.new(params).to_h
+        non_body_param_names = ["booking_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/bookings/#{params[:booking_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::UpdateBookingResponse.load(_response.body)
+          Square::Types::UpdateBookingResponse.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 an existing booking.
       #
       # To call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.
-      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.
+      # To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for
+      # the OAuth scope.
       #
-      # For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*
+      # For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to
+      # *Appointments Plus*
       # or *Appointments Premium*.
       #
+      # @param request_options [Hash]
+      # @param params [Square::Bookings::Types::CancelBookingRequest]
+      # @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] :booking_id
+      #
       # @return [Square::Types::CancelBookingResponse]
       def cancel(request_options: {}, **params)
-        _path_param_names = ["booking_id"]
+        params = Square::Internal::Types::Utils.normalize_keys(params)
+        request_data = Square::Bookings::Types::CancelBookingRequest.new(params).to_h
+        non_body_param_names = ["booking_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/bookings/#{params[:booking_id]}/cancel",
-          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::CancelBookingResponse.load(_response.body)
+          Square::Types::CancelBookingResponse.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