NAME
At::Bluesky - Bluesky Extentions to the Core AT Protocol
SYNOPSIS
use At::Bluesky;
my $bsky = At::Bluesky->new( identifier => 'sanko', password => '1111-2222-3333-4444');
$bsky->actor_getProfiles( 'xkcd.com', 'marthawells.bsky.social' );
DESCRIPTION
The AT Protocol is a "social networking technology created to power the next generation of social applications." The Bluesky lexicons are official extensions to the core spec.
Methods
As a subclass of At.pm, see that module for inherited methods.
new( ... )
At::Bluesky->new( identifier => 'sanko', password => '1111-2222-3333-4444' );
Expected parameters include:
identifier
- required-
Handle or other identifier supported by the server for the authenticating user.
password
- required-
This is the app password not the account's password. App passwords are generated at https://bsky.app/settings/app-passwords.
actor_getPreferences( )
$bsky->actor_getPreferences;
Get private preferences attached to the current account. Expected use is synchronization between multiple devices, and import/export during account migration. Requires auth.
On success, returns a new At::Lexicon::app::bsky::actor::preferences
object.
actor_getProfile( ... )
$bsky->actor_getProfile( 'sankor.bsky.social' );
Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth.
Expected parameters include:
On success, returns a new At::Lexicon::app::bsky::actor::profileViewDetailed
object.
actor_getProfiles( ... )
$bsky->actor_getProfiles( 'xkcd.com', 'marthawells.bsky.social' );
Get detailed profile views of multiple actors.
On success, returns a list of up to 25 new At::Lexicon::app::bsky::actor::profileViewDetailed
objects.
actor_getSuggestions( [...] )
$bsky->actor_getSuggestions( ); # grab 50 results
my $res = $bsky->actor_getSuggestions( limit => 75 ); # limit number of results to 75
$bsky->actor_getSuggestions( limit => 75, cursor => $res->{cursor} ); # look for the next group of 75 results
Get a list of suggested actors. Expected use is discovery of accounts to follow during new account onboarding.
Expected parameters include:
limit
-
Maximum of 100, minimum of 1, and 50 is the default.
cursor
On success, returns a list of actors as new At::Lexicon::app::bsky::actor::profileView
objects and (optionally) a cursor.
actor_searchActorsTypeahead( ..., [...] )
$bsky->actor_searchActorsTypeahead( query => 'joh' ); # grab 10 results
$bsky->actor_searchActorsTypeahead( query => 'joh', limit => 30 ); # limit number of results to 30
Find actor suggestions for a prefix search term. Expected use is for auto-completion during text field entry. Does not require auth.
Expected parameters include:
query
- required-
Search query prefix; not a full query string.
limit
-
Maximum of 100, minimum of 1, and 10 is the default.
On success, returns a list of actors as new At::Lexicon::app::bsky::actor::profileViewBasic
objects.
actor_searchActors( ..., [...] )
$bsky->actor_searchActors( query => 'john' ); # grab 25 results
my $res = $bsky->actor_searchActors( query => 'john', limit => 30 ); # limit number of results to 30
$bsky->actor_searchActors( query => 'john', limit => 30, cursor => $res->{cursor} ); # next 30 results
Find actors (profiles) matching search criteria. Does not require auth.
Expected parameters include:
query
- required-
Search query string. Syntax, phrase, boolean, and faceting is unspecified, but Lucene query syntax is recommended.
limit
-
Maximum of 100, minimum of 1, and 25 is the default.
cursor
On success, returns a list of actors as new At::Lexicon::app::bsky::actor::profileViewBasic
objects and (optionally) a cursor.
actor_putPreferences( ... )
$bsky->actor_putPreferences( { '$type' => 'app.bsky.actor#adultContentPref', enabled => false } ); # pass along a coerced adultContentPref object
Set the private preferences attached to the account. This may be an At::Lexicon::app::bsky::actor::adultContentPref
, At::Lexicon::app::bsky::actor::contentLabelPref
, At::Lexicon::app::bsky::actor::savedFeedsPref
, At::Lexicon::app::bsky::actor::personalDetailsPref
, At::Lexicon::app::bsky::actor::feedViewPref
, or At::Lexicon::app::bsky::actor::threadViewPref
. They're coerced if not already objects.
On success, returns a true value.
feed_getSuggestedFeeds( [...] )
$bsky->feed_getSuggestedFeeds( limit => 10 );
Get a list of suggested feeds (feed generators) for the requesting account.
Expected parameters include:
limit
-
The number of feeds to return. Min. is 1, max is 100, 50 is the default.
cursor
On success, returns a list of feeds as new At::Lexicon::app::bsky::feed::generatorView
objects and (optionally) a cursor.
feed_getTimeline( [...] )
$bsky->feed_getTimeline( );
$bsky->feed_getTimeline( algorithm => 'reverse-chronological', limit => 30 );
Get a view of the requesting account's home timeline. This is expected to be some form of reverse-chronological feed.
Expected parameters include:
algorithm
-
"Variant 'algorithm' for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism.
Potential values include:
reverse-chronological
limit
-
The number of posts to return. Min. is 1, max is 100, 50 is the default.
cursor
On success, returns the feed containing a list of new At::Lexicon::app::bsky::feed::feedViewPost
objects and (optionally) a cursor.
feed_searchPosts( ..., [...] )
$bsky->feed_searchPosts( query => "perl", limit => 10 );
Find posts matching search criteria, returning views of those posts.
Expected parameters include:
query
- required-
Search query string; syntax, phrase, boolean, and faceting is unspecified, but Lucene query syntax is recommended.
limit
-
The number of posts to return. Min. is 1, max is 100, 25 is the default.
cursor
-
Optional pagination mechanism; may not necessarily allow scrolling through entire result set.
On success, returns a list of posts containing new At::Lexicon::app::bsky::feed::postView
objects and (optionally) a cursor. The total number of hits might also be returned. If so, the value may be rounded/truncated, and it may not be possible to paginate through all hits
feed_getAuthorFeed( ..., [...] )
$bsky->feed_getAuthorFeed( actor => "bsky.app" );
Get a view of an actor's 'author feed' (post and reposts by the author). Does not require auth.
Expected parameters include:
actor
- requiredlimit
-
The number of posts to return. Min. is 1, max is 100, 50 is the default.
filter
-
Combinations of post/repost types to include in response.
Options include:
cursor
-
Optional pagination mechanism; may not necessarily allow scrolling through entire result set.
On success, returns a feed of posts containing new At::Lexicon::app::bsky::feed::feedViewPost
objects and (optionally) a cursor.
feed_getRepostedBy( ..., [...] )
$bsky->feed_getRepostedBy( uri => 'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3kghpdkfnsk2i' );
Get a list of reposts for a given post.
Expected parameters include:
uri
- required-
Reference (AT-URI) of post record.
cid
-
If supplied, filters to reposts of specific version (by CID) of the post record.
limit
-
The number of authors to return. Min. is 1, max is 100, 50 is the default.
cursor
On success, returns the original uri, a list of reposters as At::Lexicon::app::bsky::actor::profileView
objects and (optionally) a cursor and the original cid.
feed_getActorFeeds( ..., [...] )
$bsky->feed_getActorFeeds( actor => 'bsky.app' );
Get a list of feeds (feed generator records) created by the actor (in the actor's repo).
Expected parameters include:
actor
- requiredlimit
-
The number of feeds to return. Min. is 1, max is 100, 50 is the default.
cursor
On success, returns a list of feeds as At::Lexicon::app::bsky::feed::generatorView
objects and (optionally) a cursor.
feed_getActorLikes( ..., [...] )
$bsky->feed_getActorLikes( actor => 'bsky.app' );
Get a list of posts liked by an actor. Does not require auth.
Expected parameters include:
actor
- requiredlimit
-
The number of posts to return. Min. is 1, max is 100, 50 is the default.
cursor
On success, returns a list of posts as At::Lexicon::app::bsky::feed::feedViewPost
objects and (optionally) a cursor.
feed_getPosts( ... )
$bsky->feed_getPosts( 'at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3kftlbujmfk24' );
Gets post views for a specified list of posts (by AT-URI). This is sometimes referred to as 'hydrating' a 'feed skeleton'.
Expected parameters include:
On success, returns a list of posts as At::Lexicon::app::bsky::feed::postView
objects.
feed_getPostThread( ..., [...] )
$bsky->feed_getPostThread( uri => 'at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3kftlbujmfk24' );
Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.
Expected parameters include:
uri
- required-
Reference (AT-URI) to post record.
depth
-
How many levels of reply depth should be included in response.
Maximum value: 1000, Minimum value: 0, Default: 6.
parentHeight
-
How many levels of parent (and grandparent, etc) post to include.
Maximum value: 1000, Minimum value: 0, Default: 80.
On success, returns the thread containing replies as a new At::Lexicon::app::bsky::feed::threadViewPost
object.
feed_getLikes( ..., [...] )
$bsky->feed_getLikes( 'at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3kftlbujmfk24' );
Get like records which reference a subject (by AT-URI and CID).
Expected parameters include:
uri
- required-
AT-URI of the subject (eg, a post record).
cid
-
CID of the subject record (aka, specific version of record), to filter likes.
limit
-
The number of likes to return. Min. is 1, max is 100, 50 is the default.
cursor
On success, returns the original URI, a list of likes as At::Lexicon::app::bsky::feed::getLikes::like
objects and (optionally) a cursor, and the original cid.
feed_getListFeed( ..., [...] )
$bsky->feed_getListFeed( list => 'at://did:plc:kyttpb6um57f4c2wep25lqhq/app.bsky.graph.list/3k4diugcw3k2p' );
Get a feed of recent posts from a list (posts and reposts from any actors on the list). Does not require auth.
Expected parameters include:
list
- required-
Reference (AT-URI) to the list record.
limit
-
The number of results to return. Min. is 1, max is 100, 50 is the default.
cursor
On success, returns feed containing a list of At::Lexicon::app::bsky::feed::feedViewPost
objects and (optionally) a cursor.
feed_getFeedSkeleton( ..., [...] )
$bsky->feed_getFeedSkeleton( feed => 'at://did:plc:kyttpb6um57f4c2wep25lqhq/app.bsky.graph.list/3k4diugcw3k2p' );
Get a skeleton of a feed provided by a feed generator. Auth is optional, depending on provider requirements, and provides the DID of the requester. Implemented by Feed Generator Service.
Expected parameters include:
feed
- required-
Reference to feed generator record describing the specific feed being requested.
limit
-
The number of results to return. Min. is 1, max is 100, 50 is the default.
cursor
On success, returns a feed containing a list of At::Lexicon::app::bsky::feed::skeletonFeedPost
objects and (optionally) a cursor.
feed_getFeedGenerator( ... )
$bsky->feed_getFeedGenerator( feed => 'at://did:plc:kyttpb6um57f4c2wep25lqhq/app.bsky.feed.generator/aaalfodybabzy' );
Get information about a feed generator. Implemented by AppView.
Expected parameters include:
On success, returns a At::Lexicon::app::bsky::feed::generatorView
object and booleans indicating whether the feed generator service has been online recently, or else seems to be inactive, and whether the feed generator service is compatible with the record declaration.
feed_getFeedGenerators( ... )
$bsky->feed_getFeedGenerators( 'at://did:plc:kyttpb6um57f4c2wep25lqhq/app.bsky.feed.generator/aaalfodybabzy', 'at://did:plc:eaf...' );
Get information about a list of feed generators.
Expected parameters include:
On success, returns a list of feeds as new At::Lexicon::app::bsky::feed::generatorView
objects.
feed_getFeed( ..., [...] )
$bsky->feed_getFeed( 'at://did:plc:kyttpb6um57f4c2wep25lqhq/app.bsky.graph.list/3k4diugcw3k2p' );
Get a hydrated feed from an actor's selected feed generator. Implemented by App View.
Expected parameters include:
On success, returns feed containing a list of At::Lexicon::app::bsky::feed::feedViewPost
objects and (optionally) a cursor.
feed_describeFeedGenerator( )
$bsky->feed_describeFeedGenerator( );
Get information about a feed generator, including policies and offered feed URIs. Does not require auth; implemented by Feed Generator services (not App View).
On success, returns feeds containing a list of At::Lexicon::app::bsky::feed::describeFeedGenerator
objects, the DID, and (optionally) links as an At::Lexicon::app::bsky::feed::describeFeedGenerator::links
object.
graph_getBlocks( [ ... ] )
$bsky->graph_getBlocks( limit => 20 );
Enumerates which accounts the requesting account is currently blocking. Requires auth.
Expected parameters include:
limit
-
Maximum of 100, minimum of 1, and 50 is the default.
cursor
On success, returns a list of At::Lexicon::app::bsky::actor::profileView
objects.
graph_getFollowers( ..., [ ... ] )
$bsky->graph_getFollowers( actor => 'sankor.bsky.social' );
Enumerates accounts which follow a specified account (actor).
Expected parameters include:
On success, returns a list of followers as At::Lexicon::app::bsky::actor::profileView
objects and the original actor as the subject, and, potentially, a cursor.
graph_getFollows( ..., [ ... ] )
$bsky->graph_getFollows( actor => 'sankor.bsky.social' );
Enumerates accounts which a specified account (actor) follows.
Expected parameters include:
On success, returns a list of follows as At::Lexicon::app::bsky::actor::profileView
objects and the original actor as the subject, and, potentially, a cursor.
graph_getList( ..., [ ... ] )
$bsky->graph_getList( list => 'at://did:plc:.../app.bsky.graph.list/...' );
Gets a 'view' (with additional context) of a specified list.
Expected parameters include:
list
- required-
Reference (AT-URI) of the list record to hydrate.
limit
-
Maximum of 100, minimum of 1, and 50 is the default.
cursor
On success, returns a list of At::Lexicon::app::bsky::graph::listItemView
objects, the original list as a At::Lexicon::app::bsky::graph::listView
object and, potentially, a cursor.
graph_getListBlocks( [ ... ] )
$bsky->graph_getListBlocks( limit => 10 );
Get mod lists that the requesting account (actor) is blocking. Requires auth.
Expected parameters include:
limit
-
Maximum of 100, minimum of 1, and 50 is the default.
cursor
On success, returns a list of At::Lexicon::app::bsky::graph::listView
objects and, potentially, a cursor.
graph_getListMutes( [ ... ] )
$bsky->graph_getListMutes( cursor => ... );
Enumerates mod lists that the requesting account (actor) currently has muted. Requires auth.
Expected parameters include:
limit
-
Maximum of 100, minimum of 1, and 50 is the default.
cursor
On success, returns a list of At::Lexicon::app::bsky::graph::listView
objects and, potentially, a cursor.
graph_getLists( ..., [ ... ] )
$bsky->graph_getLists( actor => 'sankor.bsky.social' );
Enumerates the lists created by a specified account (actor).
Expected parameters include:
actor
- required-
The account (actor) to enumerate lists from.
limit
-
Maximum of 100, minimum of 1, and 50 is the default.
cursor
On success, returns a list of At::Lexicon::app::bsky::graph::listView
objects and, potentially, a cursor.
graph_getMutes( [ ... ] )
$bsky->graph_getMutes( );
Enumerates accounts that the requesting account (actor) currently has muted. Requires auth.
Expected parameters include:
limit
-
Maximum of 100, minimum of 1, and 50 is the default.
cursor
On success, returns a list of At::Lexicon::app::bsky::actor::profileView
objects.
graph_getRelationships( ... )
$bsky->graph_getRelationships('sankor.bsky.social');
Enumerates public relationships between one account, and a list of other accounts. Does not require auth.
Expected parameters include:
actor
-
Primary account requesting relationships for.
others
-
List of 'other' accounts to be related back to the primary.
On success, returns a list of At::Lexicon::app::bsky::graph::relationship
objects and, optionally, the primary actor.
graph_getSuggestedFollowsByActor( ... )
$bsky->graph_getSuggestedFollowsByActor('sankor.bsky.social');
Enumerates follows similar to a given account (actor). Expected use is to recommend additional accounts immediately after following one account.
Expected parameters include:
actor
On success, returns a list of At::Lexicon::app::bsky::actor::profileViewDetailed
objects.
graph_muteActor( ... )
$bsky->graph_muteActor( 'at://...' );
Creates a mute relationship for the specified account. Mutes are private in Bluesky. Requires auth.
Expected parameters include:
actor
-
Person to mute.
graph_muteActorList( ... )
$bsky->graph_muteActorList( 'at://...' );
Creates a mute relationship for the specified list of accounts. Mutes are private in Bluesky. Requires auth.
Expected parameters include:
list
-
List of people to mute.
graph_unmuteActor( ... )
$bsky->graph_unmuteActor( 'at://...' );
Unmutes the specified account. Requires auth.
Expected parameters include:
actor
-
Person to mute.
graph_unmuteActorList( ... )
$bsky->graph_unmuteActorList( 'at://...' );
Unmutes the specified list of accounts. Requires auth.
Expected parameters include:
list
notification_listNotifications( [...] )
$bsky->notification_listNotifications( cursor => ... );
Enumerate notifications for the requesting account. Requires auth.
Expected parameters include:
limit
seenAt
-
A timestamp.
cursor
On success, returns a list of notifications as At::Lexicon::app::bsky::notification
objects and, optionally, a cursor.
notification_getUnreadCount( [...] )
$bsky->notification_getUnreadCount( );
Count the number of unread notifications for the requesting account. Requires auth.
Expected parameters include:
seenAt
-
A timestamp.
On success, returns a count of unread notifications.
notification_updateSeen( ... )
$bsky->notification_updateSeen( time );
Notify server that the requesting account has seen notifications. Requires auth.
Expected parameters include:
notification_registerPush( [...] )
$bsky->notification_registerPush(
...
);
Register to receive push notifications, via a specified service, for the requesting account. Requires auth.
Expected parameters include:
appId
- requiredplatform
- required-
Known values include 'ios', 'android', and 'web'.
serviceDid
- requiredtoken
- required
See https://github.com/bluesky-social/atproto/discussions/1914.
unspecced_getPopularFeedGenerators( [...] )
$bsky->unspecced_getPopularFeedGenerators( query => 'time' );
An unspecced view of globally popular feed generators.
Expected parameters include:
query
limit
-
Maximum of 100, minimum of 1, and 50 is the default.
cursor
On success, returns a list of feeds as At::Lexicon::app::bsky::feed::generatorView
objects and, optionally, a cursor.
unspecced_getTaggedSuggestions( )
$bsky->unspecced_getTaggedSuggestions( );
Get a list of suggestions (feeds and users) tagged with categories.
On success, returns a list of suggestions as At::Lexicon::app::bsky::unspecced::suggestion
objects.
unspecced_searchActorsSkeleton( ..., [...] )
$bsky->unspecced_searchActorsSkeleton( query => 'jake' );
Backend Actors (profile) search, returns only skeleton.
Expected parameters include:
query
- required-
Search query string; syntax, phrase, boolean, and faceting is unspecified, but Lucene query syntax is recommended. For typeahead search, only simple term match is supported, not full syntax.
typeahead
-
If true, acts as fast/simple 'typeahead' query.
limit
-
Maximum of 100, minimum of 1, and 25 is the default.
cursor
-
Optional pagination mechanism; may not necessarily allow scrolling through entire result set.
On success, returns a list of actors as At::Lexicon::app::bsky::unspecced::skeletonSearchActor
objects and, optionally, an approximate count of all search hits and a cursor.
unspecced_searchPostsSkeleton( ..., [...] )
$bsky->unspecced_searchPostsSkeleton( query => 'for sure' );
Backend Posts search, returns only skeleton.
Expected parameters include:
query
- required-
Search query string; syntax, phrase, boolean, and faceting is unspecified, but Lucene query syntax is recommended. For typeahead search, only simple term match is supported, not full syntax.
limit
-
Maximum of 100, minimum of 1, and 25 is the default.
cursor
-
Optional pagination mechanism; may not necessarily allow scrolling through entire result set.
On success, returns a list of posts as At::Lexicon::app::bsky::unspecced::skeletonSearchPost
objects and, optionally, an approximate count of all search hits and a cursor.
See Also
App::bsky - Bluesky client on the command line
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>