NAME C - Interaction with spotify.com API SYNOPSIS use IO::Async::Loop; use Future::AsyncAwait; use Net::Async::Spotify; my $loop = IO::Async::Loop->new; my $spotify = Net::Async::Spotify->new( client_id => '5fe01282e44241328a84e7c5cc169165', client_secret => '6f12e202e44241328a84e7c5dd169125', ); $loop->add($spotify); # Generate the needed Authorize hash. # Requesting permission for all available scopes, and without prompting user if already approved. my %authorize = $spotify->authorize(scope => ['scopes'], show_dialog => 'false'); my $auth_uri = $authorize{uri}; my $auth_state = $authorize{state}; # Obtain Authorization code from callback request. my $auth_code = '...'; # from `code` path parameter. # Get the needed Access Token await $spotify->obtain_token( code => $auth_code, auto_refresh => 1, ); # You can now request any API call await $spotify->api->player->start_a_users_playback(); # Token will be auto refreshed before it's expiry. $loop->run; DESCRIPTION Net::Async::Spotify Provides an interface for interacting with "Spotify API" It does so while being an IO::Async::Notifier instance, with a Net::Async::HTTP child to reach Spotify API, running on an IO::Async::Loop. Where all listed Spotify API calls and their response objects are auto-generated and defined here from documentation page. For easier maintainability. CONSTRUCTOR new $spotify = Net::Async::Spotify->new( %args ) Constructs a new Net::Async::Spotify Object, in which is actually an IO::Async::Notifier instance. Takes a number of named arguments at construction time, which can be grouped like so: App Params More details about them can be found in "Spotify App Settings page" client_id => STRING Spotify App Client ID. "client_id" client_secret => STRING Spotify App Client Secret. "client_secret" redirect_uri => STRING Spotify App callback URI. "redirect_uri" base_uri => STRING Spotify base_uri default is set to https://accounts.spotify.com/. "base_uri" Token Params Used for "token". It's parameter can be passed here too, however not needed as they can be obtained. When not passed then they should be obtained by calling "obtain_token" access_token => STRING Spotify User's "Access Token" refresh_token => STRING Spotify User's "Refresh Token" token_type => STRING Spotify "Access Token type" API param used for "API". It is used to create only selected Spotify APIs instead of all. When not passed it will load all available "Spotify APIs" apis => ArrayRef a List of limited APIs to be loaded. Passed to Net::Async::Spotify::API when being created. METHODS token Net::Async::Spotify::Token Object, holding Spotify Token information. API Returns an instance of Net::Async::Spotify::API which includes all needed Spotify API Classes as methods. To be used to access and call any loaded Spotify API $spotify->api->->player->transfer_a_users_playback( device_ids => '...', play => 'true' )->get; Note that the response from any API call, belongs to Net::Async::Spotify::Object group class. For both, API calls and their response objects are being collected and auto generated from "Spotify doc page" , check . authorize Returns an URI object with it being the needed Spotify Authorization request along with the needed parameters set. also return random hexadecimal number as the state attached to this request. Pretty much the things needed for "Spotify Obtaining Authorization" Accepts limited named parameters client_id Spotify ClientID, set to class "client_id" if not passed. response_type set as code for default. Since Authorization Code Flow is used. redirect_uri URI string that will be used as Authorization callback URL. Set to main app "redirect_url" if not peresnt. state Used as linking mechanism between this generated Authorize Request, and the incoming callback code response. will be set to a random hexadecimal number. For more info see "Cross-Site Request Forgery" Optional and defaulted to a random 8 digit hexadecimal string, using Math::Random::Secure::irand scope Sets permissions to be requested. Accepts array of scopes or scopes categories. e.g. scope => [app_remote_control', 'user-follow-read', 'spotify_connect'] for more info "Spotify Scopes" , also Net::Async::Spotify::Scope. show_dialog optional param can be passed set to either true|false Whether or not to force the user to approve the app again if they've already done so. false (default) from Spotify API itself. $spotify->authorize( scope => [ 'user-read-playback-state', 'user-read-currently-playing', 'playlists', ], ); Returns a Hash containing uri as the Authorization URL needed, and state as the value that is used in it "state" obtain_token Method used to obtain access and refresh token from passed Authorization code. https://developer.spotify.com/documentation/general/guides/authorization-guide/ especifically Step 2 & 4 in Authorization Code Flow. Support for other methods can be easily added, however not needed at the moment. Accepts limited parameters, and based on them will decide whether to get new token from Authorization code or from a previously obtained refresh token. Note that it does not check for "state" value as this step should be handled by caller. code representing Spotify Authorization Code, if passed, grant_type parameter will be set to authorization_code. and the request will be for a new Spotify Token pair. redirect_uri optional, must be matching the one used to obtain code. Only used when "code" parameter is present auto_refresh if set it will start IO::Async::Timer::Periodic in order to refresh access token before it expires. Accessed from "Token Timer" http Accessor to underlying Net::Async::HTTP object, which is used to perform requests. token_timer An instance of IO::Async::Timer::Periodic which is set to be called before 46 seconds of curret Token expiry time Can be started by "auto_refresh" option client_id Accessor for Spotify App Client ID client_secret Accessor for Spotify App Client Secret redirect_uri Accessor for Spotify App defined redirect URL base_uri Accessor for Spotify Base URI spotify-cli.pl Located at bin/spotify-cli.pl, This will be installed with the package, where it gives us a CLI for Spotify API. Have some predefined commands, while it supports all API calls. Can run in various modes, one of them being interactive. Currently it is just a simple CLI tool with minimal functionality. Serves as implementation example for this library. # For full information spotify-cli.pl -h Independent CLI library will be implemented using Tickit crawl-api-doc.pl Located at scripts/spotify-cli.pl, this script is mainly used for ease of implementation and maintability. It will parse "Spotify API Documentation page" and utilizes a Template in order to create corresponding Classes for every Spotify API type and call, along with Responce Objects. these 4 templates are what currently availabe and can be extended: SpotifyAPI_main_pm.tt2 Located at scripts/SpotifyAPI_main_pm.tt2 | Template for all Net::Async::Spotify::API::* Main base class for custom functionality. One time generation. SpotifyAPI_pm.tt2 Located at scripts/SpotifyAPI_pm.tt2 | Template for all Net::Async::Spotify::API::Generated::* Class for all available Spotify API calls defined as methods. Updated on Spotify API new releases. SpotifyObj_main_pm.tt2 Located at scripts/SpotifyObj_main_pm.tt2 | Template for all Main base class for custom functionality. One time generation. SpotifyObj_pm.tt2 Located at scripts/SpotifyObj_pm.tt2 | Template for all Class for all available Spotify Response Objects, where fields are set to be methods. Updated on Spotify API new releases. It accepts a couple of options to determines what you want to do. # To generate all of the above. perl scripts/crawl-api-doc.pl -e -o -i # Can be also used to explore API, combined with jq perl scripts/crawl-api-doc.pl -j | jq . # For more details and optionns perl scripts/crawl-api-doc.pl -h Note that when Spotify releases changes on their API, all what it takes to update this package is: - Spotify to update their documentation page. - run this script and release changes.