view release on metacpan or  search on metacpan

lib/AnyEvent/Twitter.pm  view on Meta::CPAN

    my %query;
    for my $pair (split /&/, $body) {
        my ($key, $value) = split /=/, $pair;
        $query{$key} = URI::Escape::uri_unescape($value);
    }

    return %query;
}

sub parse_timestamp { # Twitter uses weird created_at format: "Thu Mar 01 17:38:56 +0000 2012"
    my ($class, $created_at) = @_;
    localtime( Time::Piece->strptime($created_at, '%a %b %d %H:%M:%S %z %Y' )->epoch )
}

1;
__END__

=encoding utf-8

=head1 NAME

AnyEvent::Twitter - A thin wrapper for Twitter API using OAuth

=head1 SYNOPSIS

    use utf8;
    use Data::Dumper;
    use AnyEvent;
    use AnyEvent::Twitter;

    my $ua = AnyEvent::Twitter->new(
        consumer_key    => 'consumer_key',
        consumer_secret => 'consumer_secret',
        token           => 'access_token',
        token_secret    => 'access_token_secret',
    );

    # or

    my $ua = AnyEvent::Twitter->new(
        consumer_key        => 'consumer_key',
        consumer_secret     => 'consumer_secret',
        access_token        => 'access_token',
        access_token_secret => 'access_token_secret',
    );

    # or, if you use eg/gen_token.pl, you can write simply as:

    my $json_text = slurp 'config.json';
    my $config    = JSON::decode_json($json_text);
    my $ua = AnyEvent::Twitter->new(%$config);

    my $cv = AE::cv;

    # GET request
    $cv->begin;
    $ua->get('account/verify_credentials', sub {
        my ($header, $response, $reason) = @_;

        say $response->{screen_name};
        $cv->end;
    });

    # GET request with parameters
    $cv->begin;
    $ua->get('account/verify_credentials', {
        include_entities => 1
    }, sub {
        my ($header, $response, $reason) = @_;

        say $response->{screen_name};
        $cv->end;
    });

    # POST request with parameters
    $cv->begin;
    $ua->post('statuses/update', {
        status => 'いろはにほへと ちりぬるを'
    }, sub {
        my ($header, $response, $reason) = @_;

        say $response->{user}{screen_name};
        $cv->end;
    });

    # verbose and old style
    $cv->begin;
    $ua->request(
        method => 'GET',
        api    => 'account/verify_credentials',
        sub {
            my ($hdr, $res, $reason) = @_;

            if ($res) {
                print "ratelimit-remaining : ", $hdr->{'x-ratelimit-remaining'}, "\n",
                      "x-ratelimit-reset   : ", $hdr->{'x-ratelimit-reset'}, "\n",
                      "screen_name         : ", $res->{screen_name}, "\n";
            } else {
                say $reason;
            }
            $cv->end;
        }
    );

    $cv->begin;
    $ua->request(
        method => 'POST',
        api    => 'statuses/update',
        params => { status => 'hello world!' },
        sub {
            print Dumper \@_;
            $cv->end;
        }
    );

    $cv->begin;
    $ua->request(
        method => 'POST',
        url    => 'http://api.twitter.com/1/statuses/update.json',
        params => { status => 'いろはにほへと ちりぬるを' },
        sub {
            print Dumper \@_;
            $cv->end;
        }
    );

    $cv->recv;

=head1 DESCRIPTION

AnyEvent::Twitter is a very thin wrapper for Twitter API using OAuth.

=head1 API VERSION

As of version 0.63, L<AnyEvent::Twitter> supports Twitter REST API v1.1.

NOTE: API version 1.0 is already deprecated.

=head1 METHODS

=head2 new

All arguments are required except C<api_version>.
If you don't know how to obtain these parameters, take a look at eg/gen_token.pl and run it.

=over 4

=item C<consumer_key>

=item C<consumer_secret>

=item C<access_token> (or C<token>)

=item C<access_token_secret> (or C<token_secret>)

=item C<api_version> (optional; default: 1.1)

If you have a problem with API changes, specify C<api_version> parameter.
Possible values are: C<1.1> or C<1.0>

=back

=head2 get

=over 4

=item C<< $ua->get($api, sub {}) >>

=item C<< $ua->get($api, \%params, sub {}) >>

=item C<< $ua->get($url, sub {}) >>

=item C<< $ua->get($url, \%params, sub {}) >>

=back

=head2 post

=over 4

=item C<< $ua->post($api, \%params, sub {}) >>

=item C<< $ua->post($url, \%params, sub {}) >>

=item C<< $ua->post($api, \@params, sub {}) >>

=item C<< $ua->post($url, \@params, sub {}) >>

=back

=head3 UPLOADING MEDIA FILE

You can use C<statuses/update_with_media> API to upload photos by specifying parameters as arrayref like below example.

Uploading photos will be tranferred with Content-Type C<multipart/form-data> (not C<application/x-www-form-urlencoded>)

    use utf8;
    $ua->post(
        'statuses/update_with_media',
        [
            status    => '桜',
            'media[]' => [ undef, $filename, Content => $loaded_image_binary ],
        ],
        sub {
            my ($hdr, $res, $reason) = @_;
            say $res->{user}{screen_name};
        }
    );


=head2 request

These parameters are required.

=over 4

=item C<api> or C<url>

The C<api> parameter is a shortcut option.

If you want to specify the API C<url>, the C<url> parameter is good for you. The format should be 'json'.

The C<api> parameter will be internally processed as:

    sprintf 'https://api.twitter.com/1.1/%s.json', $api; # version 1.1
    sprintf 'http://api.twitter.com/1/%s.json',    $api; # version 1.0

You can find available C<api>s at L<API Documentation|https://dev.twitter.com/docs/api>

=item C<method> and C<params>

Investigate the HTTP method and required parameters of Twitter API that you want to use.
Then specify it. GET and POST methods are allowed. You can omit C<params> if Twitter API doesn't require it.

=item callback

This module is L<AnyEvent::HTTP> style, so you have to pass the callback (coderef).

Passed callback will be called with C<$header>, C<$response>, C<$reason> and C<$error_response>.
If something is wrong with the response from Twitter API, C<$response> will be C<undef>.
On non-2xx HTTP status code, you can get the decoded response via C<$error_response>.
So you can check the value like below.

    my $callback = sub {
        my ($header, $response, $reason, $error_response) = @_;

        if ($response) {
            say $response->{screen_name};
        } else {
            say $reason;
            for my $error (@{$error_response->{errors}}) {
                say "$error->{code}: $error->{message}";
            }
        }
    };

=back

=head2 parse_timestamp

C<parse_timestamp> parses C<created_at> timestamp like "Thu Mar 01 17:38:56 +0000 2012".
It returns L<Time::Piece> object. Its timezone is localtime.

=over 4

=item C<< AnyEvent::Twitter->parse_timestamp($created_at) >>

=back

=head1 TESTS

Most of all tests are written as author tests since this module depends on remote API server.
So if you want read code that works well, take a look at C<xt/> directory.

=head1 EXPERIMENTAL METHODS

Methods listed below are experimental feature. So interfaces or returned values may vary in the future.

=head2 C<< AnyEvent::Twitter->get_request_token >>

    AnyEvent::Twitter->get_request_token(
        consumer_key    => $consumer_key,
        consumer_secret => $consumer_secret,
        callback_url    => 'http://example.com/callback',
        # auth => 'authenticate',
        cb => sub {
            my ($location, $response, $body, $header) = @_;
            # $location is the endpoint where users are asked the permission
            # $response is a hashref of parsed body
            # $body is raw response itself
            # $header is response headers
        },
    );

=head2 C<< AnyEvent::Twitter->get_access_token >>

    AnyEvent::Twitter->get_access_token(
        consumer_key       => $consumer_key,
        consumer_secret    => $consumer_secret,
        oauth_token        => $oauth_token,
        oauth_token_secret => $oauth_token_secret,
        oauth_verifier     => $oauth_verifier,
        cb => sub {
            my ($token, $body, $header) = @_;
            # $token is the parsed body
            # $body is raw response
            # $header is response headers
        },
    );

=head1 CONTRIBUTORS