NAME
    Net::Disqus - Disqus.com API access

VERSION
    version 1.19

SYNOPSIS
        use Net::Disqus;
        my $disqus = Net::Disqus->new(
            api_secret  => 'your_api_secret',
            %options,
            );

        my $reactions = $disqus->reactions->list(...);

OBJECT METHODS
  new(%options)
    Creates a new Net::Disqus object. Arguments that can be passed to the
    constructor:

        api_secret      (REQUIRED)  Your Disqus API secret
        secure          (optional)  When set, will use HTTPS instead of HTTP
        ua_args         (optional)  Arguments to pass to the user agent (See L<Net::Disqus::UserAgent>)
        pass_api_errors (optional)  If set, API errors are passed back as result so you can inspect it,
                                    otherwise an exception is thrown if an API error occurs.

  rate_limit
    Returns the rate limit you have on the Disqus API.

  rate_limit_remaining
    Returns the number of requests you have remaining out of your rate
    limit.

  rate_limit_reset
    Returns an epoch time when your rate limit will be reset.

  rate_limit_resets_in
    Returns the number of seconds until your rate limit will be reset.

  rate_limit_wait
    Returns the number of seconds you have to wait after the last performed
    request to exactly use up your rate limit before it's reset. Will return
    undef if the rate limit values aren't set, or for some reason you happen
    to hit it right when your limit resets. WARNING: Do not use
    sleep($disqus->rate_limit_wait), the net effect of sleep(undef) is that
    your application will sleep forever.

        An example:

            while(1) {
                my $reactions = $disqus->reactions->list(forum => 'mysite');
                my $wait = $diqus->rate_limit_wait;
                ...
                sleep($wait || 60); 
            }

  fetch(url, %args)
    Returns the result from an API call. Pass the following arguments:

        url     (REQUIRED)  The url to call on the Disqus API
        %args   (optional)  Arguments to pass to the API

    This method will use the interfaces.json file to check whether the
    endpoint you requested is valid and whether you have passed all required
    arguments. An exception is thrown for invalid endpoints or missing
    required arguments.

CALLING API METHODS
    You can call API methods either by their full URL:

        $disqus->fetch('/reactions/list', forum => 'foo')

    Or you can get the same result like this:

        $disqus->reactions->list(forum => 'foo');

    Use whatever you're more comfortable with.

    For a list of API methods and their arguments, please see
    <http://disqus.com/api/docs/>.

    All API calls will return a hash reference containing at the very least
    a 'code' and a 'response' key. Use the API documentation or API console
    to find out what exactly is returned.

EXCEPTION HANDLING
    When errors occur, and the 'pass_api_errors' option is not set,
    Net::Disqus will die and throw a Net::Disqus::Exception object. The
    object contains two properties, 'code' and 'text. Use the below table to
    find out what the problem was:

        Code    Text
        -------------------------------------------------------------------------------
        0       Success
        1       Endpoint not valid
        2       Missing or invalid argument
        3       Endpoint resource not valid
        4       You must provide an authenticated user for this method
        5       Invalid API key
        6       Invalid API version
        7       You cannot access this resource using %(request_method)s
        8       A requested object was not found
        9       You cannot access this resource using your %(access_type)s API key
        10      This operation is not supported
        11      Your API key is not valid on this domain
        12      This application does not have enough privileges to access this resource
        13      You have exceeded the rate limit for this resource
        14      You have exceeded the rate limit for your account
        15      There was internal server error while processing your request
        16      Your request timed out
        17      The authenticated user does not have access to this feature
        500*    No such API endpoint
        500*    <variable>

    The above list was taken from <http://disqus.com/api/docs/errors/>. The
    HTTP status codes are not returned in the exception object. Exception
    code '500' is Net::Disqus' own, and will either contain the 'No such API
    endpoint' message if you are trying to access an endpoint not defined,
    or whatever error LWP::UserAgent encountered.

    If you have set the 'pass_api_errors' option, the JSON error object will
    be returned to your application, so you will have to check the code
    yourself according to the above table.

EXCEPTION HANDLING EXAMPLES
    An example using Try::Tiny:

        my $nd = Net::Disqus->new(api_secret => 'reallyinvalid');
        my $res;

        try {
            $res = $nd->reactions->list(forum => 'foo');
        } catch {
            # $_ contains the Net::Disqus::Exception object
            #
            # $_->code should contain '5' and $_->text should contain 'Invalid API Key'
        };

    Another example:

        my $nd = Net::Disqus->new(api_secret => 'myrealapikeygoeshere');
        my $res;

        try {
            $res = $nd->fetch('/this/isnt/good');
        } catch {
            # $_ contains the Net::Disqus::Exception object
            #
            # $_->code should contain '500' and $_->text should contain 'No such API endpoint'
        };

    And an example where we want to do this ourselves:

        my $nd = Net::Disqus->new(api_secret => 'reallyinvalid', pass_api_errors => 1);
        my $res;

        try {
            $res = $nd->reactions->list(forum => 'foo');
        } catch {
            # this will not result in an error unless there was no connection possible
        };
        # and now
        # $res->{code} == 5;
        # $res->{response} eq 'Invalid API Key';

AUTHOR
    Ben van Staveren, "<madcat at cpan.org>"

BUGS AND/OR CONTRIBUTING
    Please report any bugs or feature requests through the web interface at
    <https://github.com/benvanstaveren/net-disqus/issues>. If you want to
    contribute code or patches, feel free to fork the Git repository located
    at <https://github.com/benvanstaveren/net-disqus> and make pull requests
    for any patches you have.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc Net::Disqus

    You can also look for information at:

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/Net-Disqus>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/Net-Disqus>

    *   Search CPAN

        <http://search.cpan.org/dist/Net-Disqus/>

ACKNOWLEDGEMENTS
    Parts of the code based on Disqus' official Python lib.

LICENSE AND COPYRIGHT
    Copyright 2011 Ben van Staveren.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.