view release on metacpan or  search on metacpan

lib/At.pm  view on Meta::CPAN

    my $res = $at->post( 'com.atproto.server.createAccount' => {
        handle      => 'newuser.bsky.social',
        email       => 'user@example.com',
        password    => 'secure-password',
        inviteCode  => 'bsky-social-abcde'
    });

=head1 Working With Data: Records and Repositories

Data in the AT Protocol is stored in 'repositories' as 'records'. Each record belongs to a 'collection' (defined by a
Lexicon).

=head2 Creating a Post

Posts are records in, for example, the C<app.bsky.feed.post> collection.

    $at->post( 'com.atproto.repo.createRecord' => {
        repo       => $at->did,
        collection => 'app.bsky.feed.post',
        record     => {
            '$type'   => 'app.bsky.feed.post',
            text      => 'Content of the post',
            createdAt => At::_now->to_string,
        }
    });

=head2 Listing Records

To see what's in a collection:

    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};
    }

=head1 Drinking from the Firehose: Real-time Streaming

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

=head2 Subscribing to the Firehose

    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();

B<Note:> The Firehose requires L<Codec::CBOR> and an async event loop to keep the connection alive. Currently, At.pm
supports L<Mojo::UserAgent> so you should usually use L<Mojo::IOLoop>:

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

=head1 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.

=head2 How it works

When you call a method like C<app.bsky.actor.getProfile>, the library:

=over

=item 1. B<Checks user-provided paths:> It looks in any directories passed to C<lexicon_paths>.

=item 2. B<Checks local storage:> It looks for the schema in the distribution's C<share> directory.

=item 3. B<Checks user cache:> It looks in C<~/.cache/atproto/lexicons/>.

=item 4. B<Downloads if missing:> If not found, it automatically downloads the schema from the
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