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:

actor - required

Handle or DID of account to fetch profile of.

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 - required

limit

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:

posts_with_replies - default

posts_no_replies

posts_with_media

posts_and_author_threads

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 - required

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 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 - required

limit

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:

uris - required

List of post AT-URIs to return hydrated views for.

No more than 25 at a time.

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:

feed - required

AT-URI of the feed generator record.

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:

feeds - required

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:

feed - required

cursor

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:

actor - required

limit

Maximum of 100, minimum of 1, and 50 is the default.

cursor

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:

actor - required

limit

Maximum of 100, minimum of 1, and 50 is the default.

cursor

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:

seenAt - required

A timestamp.

notification_registerPush( [...] )

    $bsky->notification_registerPush(
        ...
    );

Register to receive push notifications, via a specified service, for the requesting account. Requires auth.

Expected parameters include:

appId - required

platform - required

Known values include 'ios', 'android', and 'web'.

serviceDid - required

token - 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>

cpanm At

perl -MCPAN -e shell
install At