view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

To see what's in a collection:

```perl
my $res = $at->get( 'com.atproto.repo.listRecords' => {
    repo       => $at->did,
    collection => 'app.bsky.feed.post',
    limit      => 10
});

for my $record (@{$res->{records}}) {
    say $record->{value}{text};
}
```

# Drinking from the Firehose: Real-time Streaming

The Firehose is a real-time stream of **all** events happening on the network (or a specific PDS). This includes new
posts, likes, handle changes, deletions, and more.

## Subscribing to the Firehose

```perl
my $fh = $at->firehose(sub ( $header, $body, $err ) {
    if ($err) {
        warn "Firehose error: $err";
        return;
    }

    if ($header->{t} eq '#commit') {
        say 'New commit in repo: ' . $body->{repo};
    }
});

$fh->start();
```

**Note:** The Firehose requires [Codec::CBOR](https://metacpan.org/pod/Codec%3A%3ACBOR) and an async event loop to keep the connection alive. Currently, At.pm
supports [Mojo::UserAgent](https://metacpan.org/pod/Mojo%3A%3AUserAgent) so you should usually use [Mojo::IOLoop](https://metacpan.org/pod/Mojo%3A%3AIOLoop):

```perl
use Mojo::IOLoop;
# ... setup firehose ...
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
```

# Lexicon Caching

The AT Protocol defines its API endpoints using "Lexicons" (JSON schemas). This library uses these schemas to
automatically coerce API responses into Perl objects.

## How it works

When you call a method like `app.bsky.actor.getProfile`, the library:

- 1. **Checks user-provided paths:** It looks in any directories passed to `lexicon_paths`.
- 2. **Checks local storage:** It looks for the schema in the distribution's `share` directory.
- 3. **Checks user cache:** It looks in `~/.cache/atproto/lexicons/`.
- 4. **Downloads if missing:** If not found, it automatically downloads the schema from the
official AT Protocol repository and saves it to your user cache.

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

# METHODS

## `new( [ host =` ..., share => ... \] )>

Constructor.

Expected parameters include:

- `host`

    Host for the service. Defaults to `bsky.social`.

- `share`

    Location of lexicons. Defaults to the `share` directory under the distribution.

- `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 `atproto` repository.

- `http`

    A pre-instantiated [At::UserAgent](https://metacpan.org/pod/At%3A%3AUserAgent) object. By default, this is auto-detected by checking for [Mojo::UserAgent](https://metacpan.org/pod/Mojo%3A%3AUserAgent),
    falling back to [HTTP::Tiny](https://metacpan.org/pod/HTTP%3A%3ATiny).

## `oauth_start( $handle, $client_id, $redirect_uri, [ $scope ] )`

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

## `oauth_callback( $code, $state )`

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

## `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 `ath` during refresh).

## `login( $handle, $app_password )`

Performs legacy password-based authentication. **Deprecated: Use OAuth instead.**

## `resume( $access_jwt, $refresh_jwt, [ $token_type, $dpop_key_jwk, $client_id, $handle, $pds ] )`

Resumes a previous session using stored tokens and metadata.

## `get( $method, [ \%params ] )`

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

## `post( $method, [ \%data ] )`

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

## `subscribe( $method, $callback )`

Connects to a WebSocket stream (Firehose).