spotify-api-sdk 1.0.0

data/lib/spotify_web_api/controllers/player_controller.rb

@@ -0,0 +1,509 @@
+# spotify_web_api
+#
+# This file was automatically generated by APIMATIC v2.0
+# ( https://apimatic.io ).
+
+module SpotifyWebApi
+  # PlayerController
+  class PlayerController < BaseController
+    # Get information about the user’s current playback state, including track
+    # or episode, progress, and active device.
+    # @param [String] market Optional parameter: Example:
+    # @param [String] additional_types Optional parameter: Example:
+    # @return [CurrentlyPlayingContextObject] response from the API call
+    def get_information_about_the_users_current_playback(market: nil,
+                                                         additional_types: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/me/player',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(market, key: 'market'))
+                   .query_param(new_parameter(additional_types, key: 'additional_types'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(CurrentlyPlayingContextObject.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Transfer playback to a new device and optionally begin playback. This API
+    # only works for users who have Spotify Premium. The order of execution is
+    # not guaranteed when you use this API with other Player API endpoints.
+    # @param [MePlayerRequest] body Optional parameter: Example:
+    # @return [void] response from the API call
+    def transfer_a_users_playback(body: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::PUT,
+                                     '/me/player',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Get information about a user’s available Spotify Connect devices. Some
+    # device models are not supported and will not be listed in the API
+    # response.
+    # @return [ManyDevices] response from the API call
+    def get_a_users_available_devices
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/me/player/devices',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(ManyDevices.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Get the object currently being played on the user's Spotify account.
+    # @param [String] market Optional parameter: Example:
+    # @param [String] additional_types Optional parameter: Example:
+    # @return [CurrentlyPlayingObject] response from the API call
+    def get_the_users_currently_playing_track(market: nil,
+                                              additional_types: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/me/player/currently-playing',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(market, key: 'market'))
+                   .query_param(new_parameter(additional_types, key: 'additional_types'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(CurrentlyPlayingObject.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Start a new context or resume current playback on the user's active
+    # device. This API only works for users who have Spotify Premium. The order
+    # of execution is not guaranteed when you use this API with other Player API
+    # endpoints.
+    # @param [String] device_id Optional parameter: Example:
+    # @param [MePlayerPlayRequest] body Optional parameter: Example:
+    # @return [void] response from the API call
+    def start_a_users_playback(device_id: nil,
+                               body: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::PUT,
+                                     '/me/player/play',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .query_param(new_parameter(device_id, key: 'device_id'))
+                   .body_param(new_parameter(body))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Pause playback on the user's account. This API only works for users who
+    # have Spotify Premium. The order of execution is not guaranteed when you
+    # use this API with other Player API endpoints.
+    # @param [String] device_id Optional parameter: Example:
+    # @return [void] response from the API call
+    def pause_a_users_playback(device_id: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::PUT,
+                                     '/me/player/pause',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(device_id, key: 'device_id'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Skips to next track in the user’s queue. This API only works for users who
+    # have Spotify Premium. The order of execution is not guaranteed when you
+    # use this API with other Player API endpoints.
+    # @param [String] device_id Optional parameter: Example:
+    # @return [void] response from the API call
+    def skip_users_playback_to_next_track(device_id: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/me/player/next',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(device_id, key: 'device_id'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Skips to previous track in the user’s queue. This API only works for users
+    # who have Spotify Premium. The order of execution is not guaranteed when
+    # you use this API with other Player API endpoints.
+    # @param [String] device_id Optional parameter: Example:
+    # @return [void] response from the API call
+    def skip_users_playback_to_previous_track(device_id: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/me/player/previous',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(device_id, key: 'device_id'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Seeks to the given position in the user’s currently playing track. This
+    # API only works for users who have Spotify Premium. The order of execution
+    # is not guaranteed when you use this API with other Player API endpoints.
+    # @param [Integer] position_ms Required parameter: Example:
+    # @param [String] device_id Optional parameter: Example:
+    # @return [void] response from the API call
+    def seek_to_position_in_currently_playing_track(position_ms,
+                                                    device_id: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::PUT,
+                                     '/me/player/seek',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(position_ms, key: 'position_ms'))
+                   .query_param(new_parameter(device_id, key: 'device_id'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Set the repeat mode for the user's playback. This API only works for users
+    # who have Spotify Premium. The order of execution is not guaranteed when
+    # you use this API with other Player API endpoints.
+    # @param [String] state Required parameter: Example:
+    # @param [String] device_id Optional parameter: Example:
+    # @return [void] response from the API call
+    def set_repeat_mode_on_users_playback(state,
+                                          device_id: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::PUT,
+                                     '/me/player/repeat',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(state, key: 'state'))
+                   .query_param(new_parameter(device_id, key: 'device_id'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Set the volume for the user’s current playback device. This API only works
+    # for users who have Spotify Premium. The order of execution is not
+    # guaranteed when you use this API with other Player API endpoints.
+    # @param [Integer] volume_percent Required parameter: Example:
+    # @param [String] device_id Optional parameter: Example:
+    # @return [void] response from the API call
+    def set_volume_for_users_playback(volume_percent,
+                                      device_id: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::PUT,
+                                     '/me/player/volume',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(volume_percent, key: 'volume_percent'))
+                   .query_param(new_parameter(device_id, key: 'device_id'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Toggle shuffle on or off for user’s playback. This API only works for
+    # users who have Spotify Premium. The order of execution is not guaranteed
+    # when you use this API with other Player API endpoints.
+    # @param [TrueClass | FalseClass] state Required parameter: Example:
+    # @param [String] device_id Optional parameter: Example:
+    # @return [void] response from the API call
+    def toggle_shuffle_for_users_playback(state,
+                                          device_id: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::PUT,
+                                     '/me/player/shuffle',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(state, key: 'state'))
+                   .query_param(new_parameter(device_id, key: 'device_id'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Get tracks from the current user's recently played tracks.
+    # _**Note**: Currently doesn't support podcast episodes._
+    # @param [Integer] limit Optional parameter: Example:20
+    # @param [Integer] after Optional parameter: Example:
+    # @param [Integer] before Optional parameter: Example:
+    # @return [CursorPagingPlayHistoryObject] response from the API call
+    def get_recently_played(limit: 20,
+                            after: nil,
+                            before: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/me/player/recently-played',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(limit, key: 'limit'))
+                   .query_param(new_parameter(after, key: 'after'))
+                   .query_param(new_parameter(before, key: 'before'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(CursorPagingPlayHistoryObject.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Get the list of objects that make up the user's queue.
+    # @return [QueueObject] response from the API call
+    def get_queue
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/me/player/queue',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(QueueObject.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+
+    # Add an item to the end of the user's current playback queue. This API only
+    # works for users who have Spotify Premium. The order of execution is not
+    # guaranteed when you use this API with other Player API endpoints.
+    # @param [String] uri Required parameter: Example:
+    # @param [String] device_id Optional parameter: Example:
+    # @return [void] response from the API call
+    def add_to_queue(uri,
+                     device_id: nil)
+      new_api_call_builder
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/me/player/queue',
+                                     Server::DEFAULT)
+                   .query_param(new_parameter(uri, key: 'uri'))
+                   .query_param(new_parameter(device_id, key: 'device_id'))
+                   .auth(Single.new('oauth_2_0')))
+        .response(new_response_handler
+                    .is_response_void(true)
+                    .is_api_response(true)
+                    .local_error('401',
+                                 "Bad or expired token. This can happen if the user revoked a'\
+                                  ' token or\nthe access token has expired. You should'\
+                                  ' re-authenticate the user.\n",
+                                 UnauthorizedException)
+                    .local_error('403',
+                                 "Bad OAuth request (wrong consumer key, bad nonce, expired'\
+                                  '\ntimestamp...). Unfortunately, re-authenticating the user'\
+                                  ' won't help here.\n",
+                                 ForbiddenException)
+                    .local_error('429',
+                                 "The app has exceeded its rate limits.\n",
+                                 TooManyRequestsException))
+        .execute
+    end
+  end
+end