documentation

3 files changed, 264 insertions, 0 deletions

diff --git a/bin/pocket b/bin/pocket
index a73633c..b335ae1 100644
--- a/bin/pocket
+++ b/bin/pocket
@@ -1,6 +1,101 @@
 #!/usr/bin/env perl
 use strict;
 use warnings;
+# PODNAME: pocket
+# ABSTRACT: interact with the Pocket API from the command line
+
+=head1 SYNOPSIS
+
+  $ pocket list
+  Enter your consumer key: ...
+  Visit https://getpocket.com/auth/authorize?request_token=...&redirect_uri=https://getpocket.com/ and log in. When you're done, press enter to continue.
+
+  http://the-toast.net/2015/04/27/looking-back-fragments-from-womens-shelters-1981-1996/view-all/
+  https://modelviewculture.com/pieces/dreaming-holding-onto-the-hope-of-justice-in-technology-and-america
+  [...]
+  $ pocket words --archive
+  2233913
+
+=head1 DESCRIPTION
+
+This program provides several subcommands to allow you to interact with your
+Pocket list from the command line. It will automatically authenticate as
+needed, prompting you for your consumer key, and will store the returned
+credentials in C<~/.pocket>.
+
+=head1 COMMANDS
+
+=head2 authenticate
+
+Authenticates you with the Pocket API and does nothing else. Not usually
+necessary, since all of the following commands will automatically authenticate
+as necessary.
+
+=head2 list
+
+Prints the URLs in your list. By default, prints unread URLs, but also takes options to adjust the list that is returned:
+
+=over 4
+
+=item --unread
+
+Return only unread links. This is the default, but can be provided for
+explicitness.
+
+=item --archive
+
+Return only archived links.
+
+=item --all
+
+Return both unread and archived links.
+
+=item --tag=<tag>
+
+Return links with the given tag. This option can be passed multiple times, and
+may be combined with the above options.
+
+=back
+
+=head2 words
+
+Takes the same options as C<list>, but instead of printing the URLs of the
+articles, prints the number of words in all of those articles combined.
+
+=head2 search <string>
+
+Returns a list of URLs whose title or URL contains C<string>. Takes the same
+options as C<list> to limit the search.
+
+=head2 favorites
+
+Returns a list of favorited URLs. Takes the same options as C<list>.
+
+=head2 add <url> [title]
+
+Adds C<url> to your list, optionally with the given C<title>.
+
+=head2 archive <url>
+
+Moves C<url> from your list to your archive.
+
+=head2 readd <url>
+
+Moves C<url> from your archive to your list.
+
+=head2 favorite <url>
+
+Marks C<url> as a favorite.
+
+=head2 unfavorite <url>
+
+Unmarks C<url> as a favorite.
+
+=head2 delete <url>
+
+Deletes C<url> from your list and/or archive entirely.
+
+=cut
 
 use WWW::Pocket::Script;
 WWW::Pocket::Script->new->run(@ARGV);
diff --git a/dist.ini b/dist.ini
index ae31fcf..7d3c026 100644
--- a/dist.ini
+++ b/dist.ini
@@ -8,4 +8,7 @@ copyright_holder = Jesse Luehrs
 dist = WWW-Pocket
 repository = github
 
+[MetaNoIndex]
+package = WWW::Pocket::Script
+
 [AutoPrereqs]
diff --git a/lib/WWW/Pocket.pm b/lib/WWW/Pocket.pm
index 2b032f0..645f30c 100644
--- a/lib/WWW/Pocket.pm
+++ b/lib/WWW/Pocket.pm
@@ -1,15 +1,63 @@
 package WWW::Pocket;
 use Moose;
+# ABSTRACT: Wrapper for the Pocket v3 API
 
 use HTTP::Tiny;
 use JSON::PP;
 
+=head1 SYNOPSIS
+
+  use WWW::Pocket;
+
+  my $pocket = WWW::Pocket->new(
+      # get a consumer key at https://getpocket.com/developer/
+      consumer_key => '...',
+  );
+
+  my ($url, $code) = $pocket->start_authentication('https://example.com/');
+  # visit $url, log in
+  $pocket->finish_authentication($code);
+
+  say for map { $_->{resolved_url} } values %{ $pocket->retrieve->{list} };
+
+=head1 DESCRIPTION
+
+This module wraps the L<Pocket|https://getpocket.com/> v3 API. To use, you
+must first authenticate via OAuth by providing a valid consumer key, and then
+visiting the OAuth endpoint (handled by the C<start_authentication> and
+C<finish_authentication> methods). Once logged in, you can interact with the
+API via the C<add>, C<modify>, and C<retrieve> methods, which correspond to
+the endpoints documented at L<https://getpocket.com/developer/docs/overview>.
+
+This module also ships with a command line scripts called C<pocket>, for
+interacting with the API from the command line. See the documentation for that
+script for more details.
+
+=cut
+
+=attr consumer_key
+
+The consumer key for your application. You can generate a consumer key at
+L<https://getpocket.com/developer/apps/>. Required.
+
+=cut
+
 has consumer_key => (
     is       => 'ro',
     isa      => 'Str',
     required => 1,
 );
 
+=attr access_token
+
+The token returned when you successfully authenticate. This can be used to
+reauthenticate with the server without having to log in every time. It is set
+automatically by C<finish_authentication>, but can also be provided directly
+to avoid having to reauthenticate. It is required to be set before any API
+methods are called.
+
+=cut
+
 has access_token => (
     is        => 'ro',
     isa       => 'Str',
@@ -19,6 +67,14 @@ has access_token => (
     writer    => '_set_access_token',
 );
 
+=attr username
+
+The username that you have authenticated as. It is set automatically by
+C<finish_authentication>, and can also be provided directly. It is
+informational only.
+
+=cut
+
 has username => (
     is        => 'ro',
     isa       => 'Str',
@@ -26,12 +82,25 @@ has username => (
     writer    => '_set_username',
 );
 
+=attr base_uri
+
+The base URI for the Pocket service. Defaults to C<https://getpocket.com/>.
+
+=cut
+
 has base_uri => (
     is      => 'ro',
     isa     => 'Str',
     default => 'https://getpocket.com/',
 );
 
+=attr api_base_uri
+
+The base URI for the API endpoints. Defaults to appending C</v3/> to the
+C<base_uri>.
+
+=cut
+
 has api_base_uri => (
     is      => 'ro',
     isa     => 'Str',
@@ -43,6 +112,13 @@ has api_base_uri => (
     },
 );
 
+=attr auth_base_uri
+
+The base URI for the authentication endpoints. Defaults to appending C</auth/>
+to the C<base_uri>.
+
+=cut
+
 has auth_base_uri => (
     is      => 'ro',
     isa     => 'Str',
@@ -54,6 +130,12 @@ has auth_base_uri => (
     },
 );
 
+=attr ua
+
+The L<HTTP::Tiny> instance used to access the api.
+
+=cut
+
 has ua => (
     is      => 'ro',
     isa     => 'HTTP::Tiny',
@@ -61,6 +143,17 @@ has ua => (
     default => sub { HTTP::Tiny->new },
 );
 
+=method start_authentication($redirect_uri)
+
+Call this method to begin the authentication process. You must provide the
+C<$redirect_uri>, which is where the user will be redirected to after
+authenticating. This method returns a URL and an authentication code. The user
+must visit the URL to log into Pocket and approve the application, and then
+you should call C<finish_authentication> with the authentication code after
+that is done.
+
+=cut
+
 sub start_authentication {
     my $self = shift;
     my ($redirect_uri) = @_;
@@ -80,6 +173,16 @@ sub start_authentication {
     );
 }
 
+=method finish_authentication($code)
+
+Finishes the authentication process. Call this method with the code returned
+by C<start_authentication> after the user has visited the URL which was also
+returned by C<start_authentication>. Once this method returns, the
+C<access_key> and C<username> attributes will be set, and other API methods
+can be successfully called.
+
+=cut
+
 sub finish_authentication {
     my $self = shift;
     my ($code) = @_;
@@ -98,18 +201,40 @@ sub finish_authentication {
     return;
 }
 
+=method add(%params)
+
+Wraps the L<add|https://getpocket.com/developer/docs/v3/add> endpoint.
+C<%params> can include any parameters documented in the API documentation.
+
+=cut
+
 sub add {
     my $self = shift;
     my (%params) = @_;
     return $self->_endpoint_request('add', \%params);
 }
 
+=method modify
+
+Wraps the L<modify|https://getpocket.com/developer/docs/v3/modify> endpoint.
+C<%params> can include any parameters documented in the API documentation.
+
+=cut
+
 sub modify {
     my $self = shift;
     my (%params) = @_;
     return $self->_endpoint_request('send', \%params);
 }
 
+=method retrieve
+
+Wraps the L<retrieve|https://getpocket.com/developer/docs/v3/retrieve>
+endpoint. C<%params> can include any parameters documented in the API
+documentation.
+
+=cut
+
 sub retrieve {
     my $self = shift;
     my (%params) = @_;
@@ -147,4 +272,45 @@ sub _request {
 __PACKAGE__->meta->make_immutable;
 no Moose;
 
+=head1 BUGS
+
+No known bugs.
+
+Please report any bugs to GitHub Issues at
+L<https://github.com/doy/www-pocket/issues>.
+
+=head1 SEE ALSO
+
+L<Webservice::Pocket> for the v2 API
+
+=head1 SUPPORT
+
+You can find this documentation for this module with the perldoc command.
+
+    perldoc WWW::Pocket
+
+You can also look for information at:
+
+=over 4
+
+=item * MetaCPAN
+
+L<https://metacpan.org/release/WWW-Pocket>
+
+=item * Github
+
+L<https://github.com/doy/www-pocket>
+
+=item * RT: CPAN's request tracker
+
+L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Pocket>
+
+=item * CPAN Ratings
+
+L<http://cpanratings.perl.org/d/WWW-Pocket>
+
+=back
+
+=cut
+
 1;