view release on metacpan or  search on metacpan

lib/Net/Async/WebSearch/Provider/Reddit/OAuth.pm  view on Meta::CPAN

=head2 complete_authorization(%args)

Exchanges an authorization code for an access/refresh token pair. Required:
C<http> (a L<Net::Async::HTTP> — typically C<< $ws->http >>), C<code> (the
value from the redirect), and C<redirect_uri> (must match the one used in
L</authorize_url>). Returns a Future of the access token; also populates
C<< $self->access_token >>, C<< $self->refresh_token >>, and
C<< $self->token_expires_at >>, and fires C<on_token_refresh> if set.

=head2 token_state

Snapshots the currently-held auth state as a hashref:

  { access_token, refresh_token, token_expires_at }

Feed this hash back to a future C<new()> call (or drop its keys in as
C<access_token => ..., refresh_token => ..., token_expires_at => ...>) to
continue the same authenticated session. Intended for host-app session
persistence — this library does not persist anything on its own.

=head2 search

Same contract as the parent provider — plus a transparent token fetch/refresh
round-trip before the first search (and again when the cached token is about
to expire). For C<authorization_code> grants without a seeded refresh_token,
the caller must drive L</authorize_url> / L</complete_authorization> first;
otherwise the first search will fail.

=head1 SETUP

Reddit apps are created at L<https://www.reddit.com/prefs/apps>. The flow:

=over 4

=item 1.

Log in to Reddit with the account that should own the app. For app-only /
installed grants this can be any account; for C<grant_type=password> it must
be the account whose credentials you're going to use.

=item 2.

Scroll to the bottom of L<https://www.reddit.com/prefs/apps> and click
B<"create app"> (or B<"create another app">).

=item 3.

Pick the app type:

=over 4

=item * B<script> — when you plan to use C<grant_type=password> or the default
C<client_credentials>. This is the right choice for personal/CLI tools and
backend services where I<you> own the account. Gets the "full" rate limit.

=item * B<web app> — for server-side web apps using the authorization-code
flow (not covered by this provider; use it only with C<client_credentials>
here).

=item * B<installed app> — for mobile/desktop clients without a server-held
secret. Use with C<grant_type=installed> and supply a per-device C<device_id>.

=back

=item 4.

Fill in C<name>, C<description>, and C<about url> (anything reasonable).
For C<redirect uri> use C<http://localhost:8000> (not used by this provider
but the form demands a value).

=item 5.

Submit. Reddit shows you two strings:

=over 4

=item * The C<client_id>: the short string shown right under the app name
(looks like C<AbCdEfGhIjKlMn>).

=item * The C<secret>: next to the label "secret". Copy it now — it won't be
shown again in full.

=back

For B<installed> apps there is no secret — pass C<client_secret =E<gt> ''>.

=item 6.

B<Choose a real User-Agent.> Reddit's API wiki explicitly asks for the form
C<< <platform>:<app-id>:<version> (by /u/<your-reddit-name>) >>, e.g.
C<my-search-bot/1.0 by /u/myaccount>. Generic UAs (Python-requests, curl,
LWP::UserAgent) get throttled into oblivion. Pass it via C<user_agent =E<gt> ...>
on C<new>.

=item 7.

B<Respect the rate limits.> Authenticated OAuth clients get ~100 QPM
(queries per minute) per OAuth-ID. Script apps pin to the account,
app-only / installed pin to the client_id.

=back

After setup, the provider handles the token dance for you: it POSTs to
C<https://www.reddit.com/api/v1/access_token>, caches the bearer token
until C<token_margin> seconds before expiry, and attaches it to every
search request against C<https://oauth.reddit.com>.

=head1 SEE ALSO

L<Net::Async::WebSearch::Provider::Reddit>,
L<https://www.reddit.com/prefs/apps>,
L<https://github.com/reddit-archive/reddit/wiki/OAuth2>,
L<https://support.reddithelp.com/hc/en-us/articles/16160319875092-Reddit-Data-API-Wiki>

=head1 SUPPORT

=head2 Issues

Please report bugs and feature requests on GitHub at
L<https://github.com/Getty/p5-net-async-websearch/issues>.