view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

Example for Bluesky Chat:

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

## `upload_blob( $data, $mime_type )`

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

## `create_record( $collection, $record, [ $rkey ] )`

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

## `delete_record( $collection, $rkey )`

Helper to delete a record from a specific collection.

## `put_record( $collection, $rkey, $record, [ $swapRecord ] )`

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

## `apply_writes( $writes, [ $swapCommit ] )`

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

## `collection_scope( $collection, [ $action ] )`

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

## `session()`

Returns the current [At::Protocol::Session](https://metacpan.org/pod/At%3A%3AProtocol%3A%3ASession) object.

## `did()`

Returns the DID of the authenticated user.

## `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.

## `get_repo_head( $did )`

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

## `get_block( $cid_str, [ $target_peer_id ] )`

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

- Check the local blockstore.
- Attempt to fetch the block via Bitswap from the provided `$target_peer_id`.
- Fall back to the centralized PDS via HTTP if the block is not found in the P2P network.

Returns a [Future](https://metacpan.org/pod/Future) that resolves to the block data.

# Decentralized Data Synchronization

When an `ipfs_node` is provided to the [At](https://metacpan.org/pod/At) constructor, the library enables peer-to-peer data synchronization
compliant with the AT Protocol Sync specification ([https://atproto.com/specs/sync](https://atproto.com/specs/sync)).

## Peer-to-Peer Repository Mirroring

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

- Identity bridging: Converting the user's DID to a libp2p PeerID.
- Root resolution: Getting the latest MST root CID.
- MST traversal: Recursively walking the Merkle Search Tree.
- Block exchange: Using Bitswap to fetch missing blocks from peers.

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

# ERROR HANDLING

Exception handling is carried out by returning [At::Error](https://metacpan.org/pod/At%3A%3AError) objects which have untrue boolean values.

# See Also

[Bluesky](https://metacpan.org/pod/Bluesky) - Bluesky client library

[App::bsky](https://metacpan.org/pod/App%3A%3Absky) - Bluesky client on the command line

[https://docs.bsky.app/docs/api/](https://docs.bsky.app/docs/api/)

# 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.

# AUTHOR

Sanko Robinson <sanko@cpan.org>