Provided by: libnet-twitter-perl_4.01002-1_all bug

NAME

       Net::Twitter::Role::OAuth - Net::Twitter role that provides OAuth instead of Basic
       Authentication

VERSION

       version 4.01002

SYNOPSIS

         use Net::Twitter;

         my $nt = Net::Twitter->new(
             traits          => ['API::RESTv1_1', 'OAuth'],
             consumer_key    => "YOUR-CONSUMER-KEY",
             consumer_secret => "YOUR-CONSUMER-SECRET",
         );

         # Do some Authentication work. See EXAMPLES

         my $tweets = $nt->friends_timeline;
         my $res    = $nt->update({ status => "I CAN HAZ OAUTH!" });

DESCRIPTION

       Net::Twitter::Role::OAuth is a Net::Twitter role that provides OAuth authentication
       instead of the default Basic Authentication.

       Note that this client only works with APIs that are compatible to OAuth authentication.

IMPORTANT

       Beginning with version 3.02, it is necessary for web applications to pass the "callback"
       parameter to "get_authorization_url".  In the absence of a callback parameter, when the
       user authorizes the application a PIN number is displayed rather than redirecting the user
       back to your site.

EXAMPLES

       See the "examples" directory in this distribution for working examples of both desktop and
       web applications.

       Here's how to authorize users as a desktop app mode:

         use Net::Twitter;

         my $nt = Net::Twitter->new(
             traits          => ['API::RESTv1_1', 'OAuth'],
             consumer_key    => "YOUR-CONSUMER-KEY",
             consumer_secret => "YOUR-CONSUMER-SECRET",
         );

         # You'll save the token and secret in cookie, config file or session database
         my($access_token, $access_token_secret) = restore_tokens();
         if ($access_token && $access_token_secret) {
             $nt->access_token($access_token);
             $nt->access_token_secret($access_token_secret);
         }

         unless ( $nt->authorized ) {
             # The client is not yet authorized: Do it now
             print "Authorize this app at ", $nt->get_authorization_url, " and enter the PIN#\n";

             my $pin = <STDIN>; # wait for input
             chomp $pin;

             my($access_token, $access_token_secret, $user_id, $screen_name) = $nt->request_access_token(verifier => $pin);
             save_tokens($access_token, $access_token_secret); # if necessary
         }

         # Everything's ready

       In a web application mode, you need to save the oauth_token and oauth_token_secret
       somewhere when you redirect the user to the OAuth authorization URL.

         sub twitter_authorize : Local {
             my($self, $c) = @_;

             my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
             my $url = $nt->get_authorization_url(callback => $callbackurl);

             $c->response->cookies->{oauth} = {
                 value => {
                     token => $nt->request_token,
                     token_secret => $nt->request_token_secret,
                 },
             };

             $c->response->redirect($url);
         }

       And when the user returns back, you'll reset those request token and secret to upgrade the
       request token to access token.

         sub twitter_auth_callback : Local {
             my($self, $c) = @_;

             my %cookie = $c->request->cookies->{oauth}->value;
             my $verifier = $c->req->params->{oauth_verifier};

             my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
             $nt->request_token($cookie{token});
             $nt->request_token_secret($cookie{token_secret});

             my($access_token, $access_token_secret, $user_id, $screen_name)
                 = $nt->request_access_token(verifier => $verifier);

             # Save $access_token and $access_token_secret in the database associated with $c->user
         }

       Later on, you can retrieve and reset those access token and secret before calling any
       Twitter API methods.

         sub make_tweet : Local {
             my($self, $c) = @_;

             my($access_token, $access_token_secret) = ...;

             my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
             $nt->access_token($access_token);
             $nt->access_token_secret($access_token_secret);

             # Now you can call any Net::Twitter API methods on $nt
             my $status = $c->req->param('status');
             my $res = $nt->update({ status => $status });
         }

METHODS

       authorized
           Whether the client has the necessary credentials to be authorized.

           Note that the credentials may be wrong and so the request may fail.

       request_access_token(verifier => $verifier)
           Request the access token, access token secret, user id and screen name for this user.
           You must pass the PIN# (for desktop applications) or the "oauth_verifier" value,
           provided as a parameter to the oauth callback (for web applications) as $verifier.

           The user must have authorized this app at the url given by "get_authorization_url"
           first.

           Returns the access_token, access_token_secret, user_id, and screen_name in a list.
           Also sets them internally so that after calling this method, you can immediately call
           API methods requiring authentication.

       xauth($username, $password)
           Exchanges the $username and $password for access tokens.  This method has the same
           return value as "request_access_token": access_token, access_token_secret, user_id,
           and screen_name in a list. Also, like "request_access_token", it sets the access_token
           and access_secret, internally, so you can immediately call API methods requiring
           authentication.

       get_authorization_url(callback => $callback_url)
           Get the URL used to authorize the user.  Returns a "URI" object.  For web
           applications, pass your applications callback URL as the "callback" parameter.  No
           arguments are required for desktop applications ("callback" defaults to "oob", out-of-
           band).

       get_authentication_url(callback => $callback_url)
           Get the URL used to authenticate the user with "Sign in with Twitter" authentication
           flow.  Returns a "URI" object.  For web applications, pass your applications callback
           URL as the "callback" parameter.  No arguments are required for desktop applications
           ("callback" defaults to "oob", out-of-band).

       access_token
           Get or set the access token.

       access_token_secret
           Get or set the access token secret.

       request_token
           Get or set the request token.

       request_token_secret
           Get or set the request token secret.

DEPRECATED METHODS

       oauth
           Prior versions used Net::OAuth::Simple.  This method provided access to the contained
           Net::OAuth::Simple object. Beginning with Net::Twitter 3.00, the OAuth methods were
           delegated to Net::OAuth::Simple.  They have since made first class methods.
           Net::Simple::OAuth is no longer used.  A warning will be displayed when accessing
           OAuth methods via the <oauth> method.  The "oauth" method will be removed in a future
           release.

       is_authorized
           Use "authorized" instead.

       oauth_authorization_url
           Use "get_authorization_url" instead.

       oauth_token
              $nt->oauth_token($access_token, $access_token_secret);

           Use "access_token" and "access_token_seccret" instead:

              $nt->access_token($access_token);
              $nt->access_token_secret($access_token_secret);

ACKNOWLEDGEMENTS

       This module was originally authored by Tatsuhiko Miyagawa as "Net::Twitter::OAuth", a
       subclass of the "Net::Twitter" 2.x. It was refactored into a Moose Role for use in
       "Net::Twitter" 3.0 and above by Marc Mims.  Many thanks to Tatsuhiko for the original work
       on both code and documentation.

AUTHORS

       Marc Mims <marc@questright.com>

       Tatsuhiko Miyagawa <miyagawa@bulknews.net>

LICENSE

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

       Net::Twitter, Net::Twitter::OAuth::Simple, Net::OAuth::Simple