view release on metacpan or  search on metacpan

lib/At.pm  view on Meta::CPAN

=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 )>

Resolves an AT Protocol DID to a libp2p PeerID. This is used to discover the user's data on the P2P network.

=head2 C<get_repo_head( $did )>

Retrieves the current MST (Merkle Search Tree) root CID for a user's repository via the C<com.atproto.sync.getHead>
endpoint.

=head2 C<get_block( $cid_str, [ $target_peer_id ] )>

Retrieves a raw block by its CID. If an C<ipfs_node> was provided to the constructor, this method will:

=over

=item Check the local blockstore.

=item Attempt to fetch the block via Bitswap from the provided C<$target_peer_id>.

=item Fall back to the centralized PDS via HTTP if the block is not found in the P2P network.

=back

Returns a L<Future> that resolves to the block data.

=head1 Decentralized Data Synchronization

When an C<ipfs_node> is provided to the L<At> constructor, the library enables peer-to-peer data synchronization
compliant with the AT Protocol Sync specification (L<https://atproto.com/specs/sync>).

=head2 Peer-to-Peer Repository Mirroring

By combining C<peer_id_for_did> and C<get_block>, this library can mirror entire user repositories without relying on a
centralized Relay or PDS. The process involves:

=over

=item Identity bridging: Converting the user's DID to a libp2p PeerID.

=item Root resolution: Getting the latest MST root CID.

=item MST traversal: Recursively walking the Merkle Search Tree.

=item Block exchange: Using Bitswap to fetch missing blocks from peers.

=back

This decentralized approach significantly reduces the load on centralized infrastructure and enables data availability
even during outages of primary service providers.

=head1 ERROR HANDLING

Exception handling is carried out by returning L<At::Error> objects which have untrue boolean values.

=head1 See Also

L<Bluesky> - Bluesky client library

L<App::bsky> - Bluesky client on the command line

L<https://docs.bsky.app/docs/api/>

=head1 LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License
2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=begin stopwords

atproto Bluesky auth authed login

=end stopwords

=cut