######################################################################
   OAuth::Cmdline 0.04
######################################################################

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

SYNOPSIS
         # Use a site-specific class instead of the parent class, see
         # description below for generic cases

       my $oauth = OAuth::Cmdline::GoogleDrive->new( );
       $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 the Google
   Drive API and Spotify. But stay tuned, I'll refactor the site-specific
   parts of the code soon, so that it'll work with Evernote, Tumblr and
   others as well. Hey, or send me a pull request if you want to beat me to
   it! :) So far the following subclasses are available:

       OAuth::Cmdline::GoogleDrive
       OAuth::Cmdline::Spotify

   If you want to use this module for a different service, go ahead and try
   it, it might just as well work. In this case, specify the "site"
   parameter, which determines the name of the cache file with the access
   token and other settings in your home directory:

         # Will use standard OAuth techniques and save your
         # tokens in ~/.some-other.site.yml
       my $oauth = OAuth::Cmdline->new( site => "some-other-site" );

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::GoogleDrive->new(
           client_id     => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
           client_secret => "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
           login_uri     => "https://accounts.spotify.com/authorize",
           token_uri     => "https://accounts.spotify.com/api/token",
           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.

 Public Methods
   "new()"
       Instantiate a new OAuth::Cmdline::XXX object. XXX stands for the
       specific site's implementation, and can be "GoogleDrive" or
       "Spotify" or similar.

   "authorization_headers()"
       Returns the HTTP header name and value the specific site requires
       for authentication. For example, in GoogleDrive's case, the values
       are:

           AuthorizationBearer xxxxx.yyy

       The method is used to pass the authentication header key and value
       to an otherwise unauthenticated web request, like

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

   "token_expired()"
       (Internal) Check if the access token is expired and will be
       refreshed on the next call of "authorization_headers()".

   "token_expire()"
       Force the expiration of the access token, so that the next request
       obtains a new one.

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]>