view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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

## `firehose( $callback, [ $url ] )`

Returns a new [At::Protocol::Firehose](https://metacpan.org/pod/At%3A%3AProtocol%3A%3AFirehose) client. `$url` defaults to the Bluesky relay firehose.

## `resolve_handle( $handle )`

Resolves a handle to a DID.

## `resolve_did_to_handle( $did )`

Reverse resolution: resolves a DID to its primary handle.

## `atproto_proxy( [ $service_did ] )`

Gets or sets the `atproto-proxy` header value on the underlying user agent. When set, requests will be sent to the
primary `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");
```

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