NAME
At - The AT Protocol for Social Networking
SYNOPSIS
use At;
my $at = At->new( host => 'https://fun.example' );
$at->server_createSession( 'sanko', '1111-aaaa-zzzz-0000' );
$at->repo_createRecord(
$at->did,
'app.bsky.feed.post',
{ '$type' => 'app.bsky.feed.post', text => 'Hello world! I posted this via the API.', createdAt => time }
);
DESCRIPTION
The AT Protocol is a "social networking technology created to power the next generation of social applications."
At.pm uses perl's new class system which requires perl 5.38.x or better and, like the protocol itself, is still under development.
At::Bluesky
At::Bluesky is a subclass with the host set to https://bluesky.social
and all the lexicon related to the social networking site included.
App Passwords
Taken from the AT Protocol's official documentation:
For the security of your account, when using any third-party clients, please generate an app password at Settings > Advanced > App passwords.
App passwords have most of the same abilities as the user's account password, but they're restricted from destructive actions such as account deletion or account migration. They are also restricted from creating additional app passwords.
Read their disclaimer here: https://atproto.com/community/projects#disclaimer.
Methods
The API attempts to follow the layout of the underlying protocol so changes to this module might be beyond my control.
new( ... )
Creates an AT client and initiates an authentication session.
my $self = At->new( host => 'https://bsky.social' );
Expected parameters include:
host
- required-
Host for the account. If you're using the 'official' Bluesky, this would be 'https://bsky.social' but you'll probably want
At::Bluesky->new(...)
because that client comes with all the bits that aren't part of the core protocol.
admin_disableAccountInvites( ... )
Disable an account from receiving new invite codes, but does not invalidate existing codes.
Expected parameters include:
admin_disableInviteCodes( )
Disable some set of codes and/or all codes associated with a set of users.
Expected parameters include:
codes
-
List of codes.
accounts
-
List of account DIDs.
admin_deleteAccount( ... )
$at->admin_deleteAccount( 'did://...' );
Delete a user account as an administrator.
Expected parameters include:
Returns a true value on success.
admin_disableAccountInvites( ..., [...] )
$at->admin_disableAccountInvites( 'did://...' );
Disable an account from receiving new invite codes, but does not invalidate existing codes.
Expected parameters include:
Returns a true value on success.
admin_emitModerationEvent( ..., [...] )
$at->admin_emitModerationEvent( ... );
Take a moderation action on an actor.
Expected parameters include:
Returns a new At::Lexicon::com::atproto::admin::modEventView
object on success.
admin_enableAccountInvites( ..., [...] )
$at->admin_enableAccountInvites( 'did://...' );
Re-enable an account's ability to receive invite codes.
Expected parameters include:
Returns a true value on success.
admin_getAccountInfo( ..., [...] )
$at->admin_getAccountInfo( 'did://...' );
Get details about an account.
Expected parameters include:
Returns a new At::Lexicon::com::atproto::admin::accountView
object on success.
admin_getInviteCodes( [...] )
$at->admin_getInviteCodes( );
Get an admin view of invite codes.
Expected parameters include:
sort
-
Order to sort the codes: 'recent' or 'usage' with 'recent' being the default.
limit
-
How many codes to return. Minimum of 1, maximum of 500, default of 100.
cursor
Returns a new At::Lexicon::com::atproto::server::inviteCode
object on success.
admin_getModerationEvent( ... )
$at->admin_getModerationEvent( 77736393829 );
Get details about a moderation event.
Expected parameters include:
Returns a new At::Lexicon::com::atproto::admin::modEventViewDetail
object on success.
admin_getRecord( ..., [...] )
$at->admin_getRecord( 'at://...' );
Get details about a record.
Expected parameters include:
Returns a new At::Lexicon::com::atproto::admin::recordViewDetail
object on success.
admin_getRepo( ... )
$at->admin_getRepo( 'did:...' );
Get details about a repository.
Expected parameters include:
Returns a new At::Lexicon::com::atproto::admin::repoViewDetail
object on success.
admin_getSubjectStatus( [...] )
$at->admin_getSubjectStatus( 'did:...' );
Get details about a repository.
Expected parameters include:
did
uri
blob
Returns a subject and, optionally, the takedown reason as a new At::Lexicon::com::atproto::admin::statusAttr
object on success.
admin_queryModerationEvents( [...] )
$at->admin_queryModerationEvents( 'did:...' );
List moderation events related to a subject.
Expected parameters include:
types
-
The types of events (fully qualified string in the format of
com.atproto.admin#modEvent...
) to filter by. If not specified, all events are returned. createdBy
sortDirection
-
Sort direction for the events.
asc
ordesc
. Defaults to descending order of created at timestamp. subject
includeAllUserRecords
-
If true, events on all record types (posts, lists, profile etc.) owned by the did are returned.
limit
-
Minimum is 1, maximum is 100, 50 is the default.
cursor
Returns a list of events as new At::Lexicon::com::atproto::admin::modEventView
objects on success.
admin_queryModerationStatuses( [...] )
$at->admin_queryModerationStatuses( 'did:...' );
List moderation events related to a subject.
Expected parameters include:
subject
comment
-
Search subjects by keyword from comments.
reportedAfter
-
Search subjects reported after a given timestamp.
reportedBefore
-
Search subjects reported before a given timestamp.
reviewedAfter
-
Search subjects reviewed after a given timestamp.
reviewedBefore
-
Search subjects reviewed before a given timestamp.
includeMuted
-
By default, we don't include muted subjects in the results. Set this to true to include them.
reviewState
-
Specify when fetching subjects in a certain state.
ignoreSubjects
lastReviewedBy
-
Get all subject statuses that were reviewed by a specific moderator.
sortField
-
lastReviewedAt
orlastReportedAt
, which is the default. sortDirection
-
asc
ordesc
, which is the default. takendown
-
Get subjects that were taken down.
limit
-
Minimum of 1, maximum is 100, the default is 50.
cursor
Returns a list of subject statuses as new At::Lexicon::com::atproto::admin::subjectStatusView
objects on success.
admin_searchRepos( [...] )
$at->admin_searchRepos( 'hydra' );
Find repositories based on a search term.
Expected parameters include:
query
limit
-
Minimum of 1, maximum is 100, the default is 50.
cursor
Returns a list of repos as new At::Lexicon::com::atproto::admin::repoView
objects on success.
admin_sendEmail( ..., [...] )
$at->admin_sendEmail( 'did:...', 'Hi!', 'did:...' );
Send email to a user's account email address.
Expected parameters include:
recipientDid
- requiredsenderDid
- requiredcontent
- requiredsubject
comment
-
Additional comment by the sender that won't be used in the email itself but helpful to provide more context for moderators/reviewers.
Returns a sent status boolean.
admin_updateAccountEmail( ... )
$at->admin_updateAccountEmail( 'atproto2.bsky.social', 'contact@example.com' );
Administrative action to update an account's email.
Expected parameters include:
Returns a true value on success.
admin_updateAccountHandle( ... )
$at->admin_updateAccountHandle( 'did:...', 'atproto2.bsky.social' );
Administrative action to update an account's handle.
Expected parameters include:
Returns a true value on success.
admin_updateSubjectStatus( ..., [...] )
$at->admin_updateSubjectStatus( ... );
Update the service-specific admin status of a subject (account, record, or blob).
Expected parameters include:
Returns the subject and takedown objects on success.
identity_resolveHandle( ... )
$at->identity_resolveHandle( 'atproto.bsky.social' );
Provides the DID of a repo.
Expected parameters include:
Returns the DID on success.
identity_updateHandle( ... )
$at->identity_updateHandle( 'atproto.bsky.social' );
Updates the handle of the account.
Expected parameters include:
Returns a true value on success.
label_queryLabels( ... )
$at->label_queryLabels( '' );
Find labels relevant to the provided URI patterns.
Expected parameters include:
uriPatterns
- required-
List of AT URI patterns to match (boolean 'OR'). Each may be a prefix (ending with '*'; will match inclusive of the string leading to '*'), or a full URI.
sources
-
Optional list of label sources (DIDs) to filter on.
limit
-
Number of results to return. 250 max. Default is 50.
cursor
On success, labels are returned as a list of new At::Lexicon::com::atproto::label
objects.
label_subscribeLabels( ..., [...] )
$at->label_subscribeLabels( sub { ... } );
Subscribe to label updates.
Expected parameters include:
callback
- required-
Code reference triggered with every event.
cursor
-
The last known event to backfill from.
On success, a websocket is initiated. Events we receive include At::Lexicon::com::atproto::label::subscribeLables::labels
and At::Lexicon::com::atproto::label::subscribeLables::info
objects.
label_subscribeLabels_p( ..., [...] )
$at->label_subscribeLabels_p( sub { ... } );
Subscribe to label updates.
Expected parameters include:
callback
- required-
Code reference triggered with every event.
cursor
-
The last known event to backfill from.
On success, a websocket is initiated and a promise is returned. Events we receive include At::Lexicon::com::atproto::label::subscribeLables::labels
and At::Lexicon::com::atproto::label::subscribeLables::info
objects.
moderation_createReport( ..., [...] )
$at->moderation_createReport( { '$type' => 'com.atproto.moderation.defs#reasonSpam' }, { '$type' => 'com.atproto.repo.strongRef', uri => ..., cid => ... } );
Report a repo or a record.
Expected parameters include:
reasonType
- required-
An
At::Lexicon::com::atproto::moderation::reasonType
object. subject
- required-
An
At::Lexicon::com::atproto::admin::repoRef
orAt::Lexicon::com::atproto::repo::strongRef
object. reason
On success, an id, the original reason type, subject, and reason, are returned as well as the DID of the user making the report and a timestamp.
repo_applyWrites( ..., [...] )
$at->repo_applyWrites( $at->did, [ ... ] );
Apply a batch transaction of creates, updates, and deletes.
Expected parameters include:
repo
- required-
The handle or DID of the repo.
writes
-
Array of At::Lexicon::com::atproto::repo::applyWrites::create, At::Lexicon::com::atproto::repo::applyWrites::update, or At::Lexicon::com::atproto::repo::applyWrites::delete objects.
validate
- required-
Flag for validating the records.
swapCommit
Returns a true value on success.
repo_createRecord( ..., [...] )
Create a new record.
$at->repo_createRecord(
$at->did,
'app.bsky.feed.post',
{ '$type' => 'app.bsky.feed.post', text => "Hello world! I posted this via the API.", createdAt => gmtime->datetime . 'Z' }
);
Expected parameters include:
repo
- required-
The handle or DID of the repo.
collection
- required-
The NSID of the record collection.
record
- required-
The record to create.
validate
-
Flag for validating the record.
swapCommit
-
Compare and swap with the previous commit by CID.
rkey
-
The key of the record.
Returns the uri and cid of the newly created record on success.
repo_deleteRecord( ..., [...] )
Create a new record.
$at->repo_deleteRecord( $at->did, 'app.bsky.feed.post', '3kiburrigys27' );
Expected parameters include:
repo
- required-
The handle or DID of the repo.
collection
- required-
The NSID of the record collection.
rkey
-
The key of the record.
swapRecord
-
Compare and swap with the previous record by CID.
swapCommit
-
Compare and swap with the previous commit by CID.
Returns a true value on success.
repo_describeRepo( ... )
$at->repo_describeRepo( $at->did );
Get information about the repo, including the list of collections.
Expected parameters include:
On success, returns the repo's handle, did, a didDoc, a list of supported collections, a flag indicating whether or not the handle is correct.
repo_getRecord( ..., [...] )
$at->repo_getRecord( $at->did, 'app.bsky.feed.post', '3kiburrigys27' );
Get a record.
Expected parameters include:
repo
- required-
The handle or DID of the repo.
collection
- required-
The NSID of the record collection.
rkey
- required-
The key of the record.
cid
-
The CID of the version of the record. If not specified, then return the most recent version.
Returns the uri, value, and, optionally, cid of the requested record on success.
repo_listRecords( ..., [...] )
$at->repo_listRecords( $at->did, 'app.bsky.feed.post' );
List a range of records in a collection.
Expected parameters include:
repo
- required-
The handle or DID of the repo.
collection
- required-
The NSID of the record type.
limit
-
The number of records to return.
Maximum is 100, minimum is 1, default is 50.
reverse
-
Flag to reverse the order of the returned records.
cursor
repo_putRecord( ..., [...] )
$at->repo_putRecord( $at->did, 'app.bsky.feed.post', 'aaaaaaaaaaaaaaa', {...} );
Write a record, creating or updating it as needed.
Expected parameters include:
repo
- required-
The handle or DID of the repo.
collection
- required-
The NSID of the record collection.
rkey
- required-
The key of the record.
record
- required-
The record to write.
validate
-
Flag for validating the record.
swapRecord
-
Compare and swap with the previous record by CID.
swapCommit
-
Compare and swap with the previous commit by CID.
Returns the record's uri and cid on success.
repo_uploadBlob( ... )
Upload a new blob to be added to repo in a later request.
Expected parameters include:
Returns the blob on success.
server_createSession( ... )
$at->server_createSession( 'sanko', '1111-2222-3333-4444' );
Create an authentication session.
Expected parameters include:
identifier
- required-
Handle or other identifier supported by the server for the authenticating user.
password
- required
On success, the access and refresh JSON web tokens, the account's handle, DID and (optionally) other data is returned.
server_describeServer( )
Get a document describing the service's accounts configuration.
$at->server_describeServer( );
This method does not require an authenticated session.
Returns a boolean value indicating whether an invite code is required, a list of available user domains, and links to the TOS and privacy policy.
server_listAppPasswords( )
$at->server_listAppPasswords( );
List all App Passwords.
Returns a list of passwords as new At::Lexicon::com::atproto::server::listAppPasswords::appPassword
objects.
server_getSession( )
$at->server_getSession( );
Get information about the current session.
Returns the handle, DID, and (optionally) other data.
server_getAccountInviteCodes( )
$at->server_getAccountInviteCodes( );
Get all invite codes for a given account.
Returns codes as a list of new At::Lexicon::com::atproto::server::inviteCode
objects.
server_getAccountInviteCodes( [...] )
$at->server_getAccountInviteCodes( );
Get all invite codes for a given account.
Expected parameters include:
includeUsed
-
Optional boolean flag.
createAvailable
-
Optional boolean flag.
Returns a list of At::Lexicon::com::atproto::server::inviteCode
objects on success. Note that this method returns an error if the session was authorized with an app password.
server_updateEmail( ..., [...] )
$at->server_updateEmail( 'smith...@gmail.com' );
Update an account's email.
Expected parameters include:
email
- requiredtoken
-
This method requires a token from
requestEmailUpdate( ... )
if the account's email has been confirmed.
server_requestEmailUpdate( ... )
$at->server_requestEmailUpdate( 1 );
Request a token in order to update email.
Expected parameters include:
server_revokeAppPassword( ... )
$at->server_revokeAppPassword( 'Demo App [beta]' );
Revoke an App Password by name.
Expected parameters include:
server_resetPassword( ... )
$at->server_resetPassword( 'fdsjlkJIofdsaf89w3jqirfu2q8docwe', '****************' );
Reset a user account password using a token.
Expected parameters include:
server_resetPassword( ... )
$at->server_resetPassword( 'fdsjlkJIofdsaf89w3jqirfu2q8docwe', '****************' );
Reset a user account password using a token.
Expected parameters include:
server_reserveSigningKey( [...] )
$at->server_reserveSigningKey( 'did:...' );
Reserve a repo signing key for account creation.
Expected parameters include:
did
-
The did to reserve a new did:key for.
On success, a public signing key in the form of a did:key is returned.
server_requestPasswordReset( [...] )
$at->server_requestPasswordReset( 'smith...@gmail.com' );
Initiate a user account password reset via email.
Expected parameters include:
server_requestEmailConfirmation( )
$at->server_requestEmailConfirmation( );
Request an email with a code to confirm ownership of email.
server_requestAccountDelete( )
$at->server_requestAccountDelete( );
Initiate a user account deletion via email.
server_deleteSession( )
$at->server_deleteSession( );
Initiate a user account deletion via email.
server_deleteAccount( )
$at->server_deleteAccount( );
Delete an actor's account with a token and password.
Expected parameters include:
server_createInviteCodes( ..., [...] )
$at->server_createInviteCodes( 1, 1 );
Create invite codes.
Expected parameters include:
codeCount
- required-
The number of codes to create. Default value is 1.
useCount
- required-
Int.
forAccounts
-
List of DIDs.
On success, returns a list of new At::Lexicon::com::atproto::server::createInviteCodes::accountCodes
objects.
server_createInviteCode( ..., [...] )
$at->server_createInviteCode( 1 );
Create an invite code.
Expected parameters include:
On success, a new invite code is returned.
server_createAppPassword( ..., [...] )
$at->server_createAppPassword( 'AT Client [release]' );
Create an App Password.
Expected parameters include:
On success, a new At::Lexicon::com::atproto::server::createAppPassword::appPassword
object.
server_createAccount( ..., [...] )
$at->server_createAccount( 'jsmith....', '*********' );
Create an account.
Expected parameters include:
On success, JSON web access and refresh tokens, the handle, did, and (optionally) a server defined didDoc are returned.
server_confirmEmail( ... )
$at->server_confirmEmail( 'jsmith...@gmail.com', 'idkidkidkidkdifkasjkdfsaojfd' );
Confirm an email using a token from requestEmailConfirmation( )
,
Expected parameters include:
sync_getBlocks( ... )
$at->sync_getBlocks( 'did...' );
Get blocks from a given repo.
Expected parameters include
sync_getLatestCommit( ... )
$at->sync_getLatestCommit( 'did...' );
Get the current commit CID & revision of the repo.
Expected parameters include:
Returns the revision and cid on success.
sync_getRecord( ..., [...] )
$at->sync_getRecord( 'did...', ... );
Get blocks needed for existence or non-existence of record.
Expected parameters include:
did
- required-
The DID of the repo.
collection
- required-
NSID.
rkey
- requiredcommit
-
An optional past commit CID.
sync_getRepo( ... )
$at->sync_getRepo( 'did...', ... );
Gets the DID's repo, optionally catching up from a specific revision.
Expected parameters include:
sync_listBlobs( ..., [...] )
$at->sync_listBlobs( 'did...' );
List blob CIDs since some revision.
Expected parameters include:
did
- required-
The DID of the repo.
since
-
on of the repo to list blobs since.
limit
-
Minimum is 1, maximum is 1000, default is 500.
cursor
On success, a list of cids is returned and, optionally, a cursor.
sync_listRepos( [...] )
$at->sync_listRepos( );
List DIDs and root CIDs of hosted repos.
Expected parameters include:
limit
-
Maximum is 1000, minimum is 1, default is 500.
cursor
On success, a list of At::Lexicon::com::atproto::sync::repo
objects is returned and, optionally, a cursor.
sync_notifyOfUpdate( ... )
$at->sync_notifyOfUpdate( 'example.com' );
Notify a crawling service of a recent update; often when a long break between updates causes the connection with the crawling service to break.
Expected parameters include:
Returns a true value on success.
sync_requestCrawl( ... )
$at->sync_requestCrawl( 'example.com' );
Request a service to persistently crawl hosted repos.
Expected parameters include:
Returns a true value on success.
sync_getBlob( ... )
$at->sync_getBlob( 'did...', ... );
Get a blob associated with a given repo.
Expected parameters include:
sync_subscribeRepos( ... )
$at->sync_subscribeRepos( sub {...} );
Subscribe to repo updates.
Expected parameters include:
sync_subscribeRepos_p( ... )
TODO
temp_fetchLabels( [...] )
$at->temp_fetchLabels;
Fetch all labels from a labeler created after a certain date.
Expected parameters include:
since
limit
-
Default is 50, minimum is 1, maximum is 250.
Returns a list of labels as new At::Lexicon::com::atproto::label
objects on success.
temp_pushBlob( ... )
$at->temp_pushBlob( 'did:...' );
Gets the did's repo, optionally catching up from a specific revision.
Expected parameters include:
temp_transferAccount( ... )
$at->temp_transferAccount( ... );
Transfer an account.
Expected parameters include:
temp_importRepo( ... )
$at->temp_importRepo( 'did...' );
Gets the did's repo, optionally catching up from a specific revision.
Expected parameters include:
See Also
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>