######################################################################
   OAuth::Cmdline 0.01
######################################################################

NAME
   OAuth::Cmdline - OAuth2 for command line applications using web services

SYNOPSIS
       my $oauth = OAuth::Cmdline->new( site => "spotify" );
       $oauth->access_token();

DESCRIPTION
   OAuth::Cmdline helps standalone command line scripts to deal with web
   services requiring OAuth access tokens.

WARNING: LIMITED ALPHA RELEASE
   While "OAuth::Cmdline" has been envisioned to work with various
   OAuth-controlled web services, it currently only works with Spotify. But
   stay tuned, I'll refactor the site-specific parts of the code soon, so
   that it'll work with Google Drive, Evernote and others as well. Hey, or
   send me a pull request if you want to beat me to it! :)

GETTING STARTED
   To obtain the initial set of access and refresh tokens from the
   OAuth-controlled site, you need to register your command line app with
   the site and you'll get a "Client ID" and a "Client Secret" in return.
   Also, the site's SDK will point out the "Login URI" and the "Token URI"
   to be used with the particular service. Then, run the following script
   (the example uses the Spotify web service)

       use OAuth::Cmdline;
       use OAuth::Cmdline::Mojo;

       my $oauth = OAuth::Cmdline->new(
           client_id     => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
           client_secret => "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
           login_uri     => "https://accounts.spotify.com/authorize",
           token_uri     => "https://accounts.spotify.com/api/token",
           site          => "spotify",
           scope         => "user-read-private",
       );

       my $app = OAuth::Cmdline::Mojo->new(
           oauth => $oauth,
       );

       $app->start( 'daemon', '-l', $oauth->local_uri );

   and point a browser to the URL displayed at startup. Clicking on the
   link displayed will take you to the OAuth-controlled site, where you
   need to log in and allow the app access to the user data, following the
   flow provided on the site. The site will then redirect to the web server
   started by the script, which will receive an initial access token with
   an expiration date and a refresh token from the site, and store it
   locally in the cache file in your home directory (~/.sitename.yml).

ACCESS TOKEN ACCESS
   Once the cache file has been initialized, the application can use the
   "access_token()" method in order to get a valid access token. If
   "OAuth::Cmdline" finds out that the cached access token is expired,
   it'll automatically refresh it for you behind the scenes.

   "OAuth::Cmdline" also offers a convenience function for providing a hash
   with authorization headers for use with LWP::UserAgent:

       my $resp = $ua->get( $url, $oauth->authorization_headers );

   This will create an "Authorization" header based on the access token and
   include it in the request to the web service.

LEGALESE
   Copyright 2014 by Mike Schilli, all rights reserved. This program is
   free software, you can redistribute it and/or modify it under the same
   terms as Perl itself.

AUTHOR
   2014, Mike Schilli <[email protected]>