view release on metacpan or  search on metacpan

lib/At.pm  view on Meta::CPAN

official AT Protocol repository and saves it to your user cache.

=back

This system ensures that the library can support new or updated features without requiring a new release of the Perl
module.

=head1 METHODS

=head2 C<new( [ host => ..., share => ... ] )>

Constructor.

Expected parameters include:

=over

=item C<host>

Host for the service. Defaults to C<bsky.social>.

=item C<share>

Location of lexicons. Defaults to the C<share> directory under the distribution.

=item C<lexicon_paths>

An optional path string or arrayref of paths to search for Lexicons before checking the default cache locations. Useful
for local development with a checkout of the C<atproto> repository.

=item C<http>

A pre-instantiated L<At::UserAgent> object. By default, this is auto-detected by checking for L<Mojo::UserAgent>,
falling back to L<HTTP::Tiny>.

=back

=head2 C<oauth_start( $handle, $client_id, $redirect_uri, [ $scope ] )>

Initiates the OAuth 2.0 Authorization Code flow. Returns the authorization URL.

=head2 C<oauth_callback( $code, $state )>

Exchanges the authorization code for tokens and completes the OAuth flow.

=head2 C<oauth_refresh()>

Uses the session's refresh token to obtain a new set of access and refresh tokens. Automatically handles DPoP nonces
and spec-compliant proof generation (omitting C<ath> during refresh).

=head2 C<login( $handle, $app_password )>

Performs legacy password-based authentication. B<Deprecated: Use OAuth instead.>

=head2 C<resume( $access_jwt, $refresh_jwt, [ $token_type, $dpop_key_jwk, $client_id, $handle, $pds ] )>

Resumes a previous session using stored tokens and metadata.

=head2 C<get( $method, [ \%params ] )>

Calls an XRPC query (GET). Returns the decoded JSON response.

=head2 C<post( $method, [ \%data ] )>

Calls an XRPC procedure (POST). Returns the decoded JSON response.

=head2 C<subscribe( $method, $callback )>

Connects to a WebSocket stream (Firehose).

=head2 C<firehose( $callback, [ $url ] )>

Returns a new L<At::Protocol::Firehose> client. C<$url> defaults to the Bluesky relay firehose.

=head2 C<resolve_handle( $handle )>

Resolves a handle to a DID.

=head2 C<resolve_did_to_handle( $did )>

Reverse resolution: resolves a DID to its primary handle.

=head2 C<atproto_proxy( [ $service_did ] )>

Gets or sets the C<atproto-proxy> header value on the underlying user agent. When set, requests will be sent to the
primary C<host> but include this header, signaling the PDS to proxy the request to the specified service.

Example for Bluesky Chat:

    $at->http->at_protocol_proxy("did:web:api.bsky.chat#bsky_chat");

=head2 C<upload_blob( $data, $mime_type )>

Uploads a raw binary blob to the PDS. Returns the blob's metadata (CID, etc).

=head2 C<create_record( $collection, $record, [ $rkey ] )>

Helper to create a new record in a specific collection. Automatically uses the authenticated user's DID.

=head2 C<delete_record( $collection, $rkey )>

Helper to delete a record from a specific collection.

=head2 C<put_record( $collection, $rkey, $record, [ $swapRecord ] )>

Helper to write a record (creating or updating it) at a specific rkey.

=head2 C<apply_writes( $writes, [ $swapCommit ] )>

Atomic multi-record update. C<$writes> should be an arrayref of create/update/delete operations.

=head2 C<collection_scope( $collection, [ $action ] )>

Helper to generate granular OAuth scopes (e.g., C<repo:app.bsky.feed.post?action=create>).

=head2 C<session()>

Returns the current L<At::Protocol::Session> object.

=head2 C<did()>

Returns the DID of the authenticated user.

=head2 C<peer_id_for_did( $did )>