bluesky

Complete Bluesky Social client library for Dart and Flutter

1. Guide 🌎

The bluesky package provides a comprehensive client library specifically designed for Bluesky Social, built on top of the AT Protocol. It combines full AT Protocol functionality with Bluesky-specific features, offering the most complete solution for building Bluesky applications.

This package extends the atproto package with Bluesky-specific services including social feeds, notifications, user profiles, and chat functionality. It provides high-level abstractions for common Bluesky operations while maintaining access to all underlying AT Protocol features.

Use this package when building applications specifically for Bluesky Social. For general AT Protocol development or other AT Protocol services, consider using the atproto package directly. The bluesky package includes everything from atproto plus Bluesky-specific enhancements.

1.1. Features ⭐

  • Complete Bluesky API Coverage - Full support for app.bsky.* and chat.bsky.* endpoints
  • Social Feed Management - Timeline, posts, likes, reposts, and feed algorithms
  • User Profiles & Social Graph - Profile management, follows, blocks, and mutes
  • Real-time Notifications - Push notifications and notification management
  • Chat & Messaging - Direct messages and conversation management
  • Content Moderation - Advanced moderation tools and content filtering
  • Media Support - Image, video, and blob upload with processing
  • Built-in AT Protocol - Includes all atproto package functionality
  • Advanced Authentication - Session management and OAuth DPoP support
  • Cross-platform Ready - Works with Dart, Flutter, and server applications

1.2. Getting Started 💪

1.2.1. Install Library

With Dart:

dart pub add bluesky

Or With Flutter:

flutter pub add bluesky

1.2.2. Import

import 'package:bluesky/bluesky.dart';

1.2.3. Implementation

Basic Authentication and Setup

import 'package:bluesky/atproto.dart';
import 'package:bluesky/bluesky.dart';
import 'package:bluesky/core.dart';

Future<void> main(List<String> args) async {
  // Create a session with your Bluesky credentials
  final session = await createSession(
    service: 'bsky.social',
    identifier: 'your.handle.bsky.social',
    password: 'your-app-password',
  );

  // Initialize the Bluesky client
  final bsky = Bluesky.fromSession(
    session.data,
    retryConfig: RetryConfig(
      maxAttempts: 3,
      jitter: Jitter(minInSeconds: 1, maxInSeconds: 3),
    ),
  );
}

Social Feed Operations

import 'dart:io';

import 'package:bluesky/app_bsky_embed_images.dart';
import 'package:bluesky/app_bsky_feed_post.dart';
import 'package:bluesky/atproto.dart';
import 'package:bluesky/bluesky.dart';
import 'package:bluesky/com_atproto_repo_strongref.dart';

Future<void> main(List<String> args) async {
  // Create a session with your Bluesky credentials
  final session = await createSession(
    service: 'bsky.social',
    identifier: 'your.handle.bsky.social',
    password: 'your-app-password',
  );

  // Initialize the Bluesky client
  final bsky = Bluesky.fromSession(session.data);

  // Get your home timeline
  final timeline = await bsky.feed.getTimeline(limit: 50);

  // Create a post
  await bsky.feed.post.create(text: 'Hello Bluesky!');

  // Create a post with media
  final image = File('./cool_path.jpg').readAsBytesSync();
  final imageBlob = await bsky.atproto.repo.uploadBlob(bytes: image);

  final post = await bsky.feed.post.create(
    text: 'Check out this image!',
    embed: UFeedPostEmbed.embedImages(
      data: EmbedImages(
        images: [EmbedImagesImage(image: imageBlob.data.blob, alt: 'My image')],
      ),
    ),
  );

  // Like a post
  await bsky.feed.like.create(
    subject: RepoStrongRef(uri: post.data.uri, cid: post.data.cid),
  );
}

User Profiles and Social Graph

import 'package:bluesky/app_bsky_actor_defs.dart';
import 'package:bluesky/atproto.dart';
import 'package:bluesky/bluesky.dart';

Future<void> main(List<String> args) async {
  // Create a session with your Bluesky credentials
  final session = await createSession(
    service: 'bsky.social',
    identifier: 'your.handle.bsky.social',
    password: 'your-app-password',
  );

  // Initialize the Bluesky client
  final bsky = Bluesky.fromSession(session.data);

  // Get user profile
  final profile = await bsky.actor.getProfile(actor: 'user.bsky.social');

  // Follow a user
  await bsky.graph.follow.create(subject: 'did:plc:example123');

  // Get followers
  final followers = await bsky.graph.getFollowers(
    actor: 'user.bsky.social',
    limit: 100,
  );

  // Update your profile
  await bsky.actor.putPreferences(
    preferences: [
      UPreferences.adultContentPref(data: AdultContentPref(enabled: false)),
    ],
  );
}

Chat and Messaging

import 'package:bluesky/atproto.dart';
import 'package:bluesky/bluesky_chat.dart';
import 'package:bluesky/chat_bsky_convo_defs.dart';

Future<void> main(List<String> args) async {
  // Create a session with your Bluesky credentials
  final session = await createSession(
    service: 'bsky.social',
    identifier: 'your.handle.bsky.social',
    password: 'your-app-password',
  );

  // Initialize chat client
  final chat = BlueskyChat.fromSession(session.data);

  // List conversations
  final conversations = await chat.convo.listConvos();

  // Send a message
  await chat.convo.sendMessage(
    convoId: 'conversation-id',
    message: MessageInput(text: 'Hello there!'),
  );
}

1.3. Supported Endpoints 👀

The bluesky package provides comprehensive coverage of both AT Protocol and Bluesky-specific services:

Bluesky Social Services (app.bsky.*)

Actor Service (app.bsky.actor.*)

  • Profile Management - Get and update user profiles, preferences, and settings
  • Search - Search for users and actors across the network

Feed Service (app.bsky.feed.*)

  • Timeline Operations - Home timeline, author feeds, and custom algorithms
  • Post Management - Create, delete, and interact with posts
  • Social Interactions - Likes, reposts, and post threading
  • Feed Generators - Custom feed algorithms and discovery

Graph Service (app.bsky.graph.*)

  • Social Connections - Follow, unfollow, block, and mute operations
  • Relationship Queries - Get followers, following, and relationship status
  • List Management - Create and manage user lists

Notification Service (app.bsky.notification.*)

  • Notification Management - List, mark read, and manage notifications
  • Push Notifications - Register and manage push notification preferences

Video Service (app.bsky.video.*)

  • Video Upload - Upload and process video content
  • Video Management - Manage video assets and metadata

Labeler Service (app.bsky.labeler.*)

  • Content Labeling - Apply and manage content labels
  • Moderation Integration - Work with moderation services

Chat Services (chat.bsky.*)

Conversation Service (chat.bsky.convo.*)

  • Message Management - Send, receive, and manage messages
  • Conversation Operations - Create, list, and manage conversations
  • Chat Moderation - Report and moderate chat content

AT Protocol Services (Inherited from atproto)

All AT Protocol services from the atproto package are included:

  • Server Service - Session and account management
  • Identity Service - Handle and DID operations
  • Repository Service - Record and data management
  • Sync Service - Real-time data synchronization
  • Moderation Service - Content reporting and moderation
  • Label Service - Content labeling and metadata

Complete API Reference

1.4. More Tips 🏄

Libraries

app_bsky_actor_defs
app_bsky_actor_getpreferences
app_bsky_actor_getprofile
app_bsky_actor_getprofiles
app_bsky_actor_getsuggestions
app_bsky_actor_profile
app_bsky_actor_putpreferences
app_bsky_actor_searchactors
app_bsky_actor_searchactorstypeahead
app_bsky_actor_status
app_bsky_bookmark_createbookmark
app_bsky_bookmark_defs
app_bsky_bookmark_deletebookmark
app_bsky_bookmark_getbookmarks
app_bsky_embed_defs
app_bsky_embed_external
app_bsky_embed_images
app_bsky_embed_record
app_bsky_embed_recordwithmedia
app_bsky_embed_video
app_bsky_feed_defs
app_bsky_feed_describefeedgenerator
app_bsky_feed_generator
app_bsky_feed_getactorfeeds
app_bsky_feed_getactorlikes
app_bsky_feed_getauthorfeed
app_bsky_feed_getfeed
app_bsky_feed_getfeedgenerator
app_bsky_feed_getfeedgenerators
app_bsky_feed_getfeedskeleton
app_bsky_feed_getlikes
app_bsky_feed_getlistfeed
app_bsky_feed_getposts
app_bsky_feed_getpostthread
app_bsky_feed_getquotes
app_bsky_feed_getrepostedby
app_bsky_feed_getsuggestedfeeds
app_bsky_feed_gettimeline
app_bsky_feed_like
app_bsky_feed_post
app_bsky_feed_postgate
app_bsky_feed_repost
app_bsky_feed_searchposts
app_bsky_feed_sendinteractions
app_bsky_feed_threadgate
app_bsky_graph_block
app_bsky_graph_defs
app_bsky_graph_follow
app_bsky_graph_getactorstarterpacks
app_bsky_graph_getblocks
app_bsky_graph_getfollowers
app_bsky_graph_getfollows
app_bsky_graph_getknownfollowers
app_bsky_graph_getlist
app_bsky_graph_getlistblocks
app_bsky_graph_getlistmutes
app_bsky_graph_getlists
app_bsky_graph_getlistswithmembership
app_bsky_graph_getmutes
app_bsky_graph_getrelationships
app_bsky_graph_getstarterpack
app_bsky_graph_getstarterpacks
app_bsky_graph_getstarterpackswithmembership
app_bsky_graph_getsuggestedfollowsbyactor
app_bsky_graph_list
app_bsky_graph_listblock
app_bsky_graph_listitem
app_bsky_graph_muteactor
app_bsky_graph_muteactorlist
app_bsky_graph_mutethread
app_bsky_graph_searchstarterpacks
app_bsky_graph_starterpack
app_bsky_graph_unmuteactor
app_bsky_graph_unmuteactorlist
app_bsky_graph_unmutethread
app_bsky_graph_verification
app_bsky_labeler_defs
app_bsky_labeler_getservices
app_bsky_labeler_service
app_bsky_notification_declaration
app_bsky_notification_defs
app_bsky_notification_getpreferences
app_bsky_notification_getunreadcount
app_bsky_notification_listactivitysubscriptions
app_bsky_notification_listnotifications
app_bsky_notification_putactivitysubscription
app_bsky_notification_putpreferences
app_bsky_notification_putpreferencesv2
app_bsky_notification_registerpush
app_bsky_notification_unregisterpush
app_bsky_notification_updateseen
app_bsky_richtext_facet
app_bsky_services
app_bsky_unspecced_defs
app_bsky_unspecced_getconfig
app_bsky_unspecced_getpopularfeedgenerators
app_bsky_unspecced_getpostthreadotherv2
app_bsky_unspecced_getpostthreadv2
app_bsky_unspecced_getsuggestedfeeds
app_bsky_unspecced_getsuggestedfeedsskeleton
app_bsky_unspecced_getsuggestedstarterpacks
app_bsky_unspecced_getsuggestedstarterpacksskeleton
app_bsky_unspecced_getsuggestedusers
app_bsky_unspecced_getsuggestedusersskeleton
app_bsky_unspecced_getsuggestionsskeleton
app_bsky_unspecced_gettaggedsuggestions
app_bsky_unspecced_gettrendingtopics
app_bsky_unspecced_gettrends
app_bsky_unspecced_gettrendsskeleton
app_bsky_unspecced_initageassurance
app_bsky_unspecced_searchactorsskeleton
app_bsky_unspecced_searchpostsskeleton
app_bsky_unspecced_searchstarterpacksskeleton
app_bsky_video_defs
app_bsky_video_getjobstatus
app_bsky_video_getuploadlimits
app_bsky_video_uploadvideo
atproto
atproto_oauth
bluesky
bluesky_chat
cardyb
chat_bsky_actor_declaration
chat_bsky_actor_defs
chat_bsky_convo_acceptconvo
chat_bsky_convo_addreaction
chat_bsky_convo_defs
chat_bsky_convo_deletemessageforself
chat_bsky_convo_getconvo
chat_bsky_convo_getconvoavailability
chat_bsky_convo_getconvoformembers
chat_bsky_convo_getlog
chat_bsky_convo_getmessages
chat_bsky_convo_leaveconvo
chat_bsky_convo_listconvos
chat_bsky_convo_muteconvo
chat_bsky_convo_removereaction
chat_bsky_convo_sendmessage
chat_bsky_convo_sendmessagebatch
chat_bsky_convo_unmuteconvo
chat_bsky_convo_updateallread
chat_bsky_convo_updateread
chat_bsky_moderation_getactormetadata
chat_bsky_moderation_getmessagecontext
chat_bsky_moderation_updateactoraccess
chat_bsky_services
com_atproto_admin_defs
com_atproto_admin_deleteaccount
com_atproto_admin_disableaccountinvites
com_atproto_admin_disableinvitecodes
com_atproto_admin_enableaccountinvites
com_atproto_admin_getaccountinfo
com_atproto_admin_getaccountinfos
com_atproto_admin_getinvitecodes
com_atproto_admin_getsubjectstatus
com_atproto_admin_searchaccounts
com_atproto_admin_sendemail
com_atproto_admin_updateaccountemail
com_atproto_admin_updateaccounthandle
com_atproto_admin_updateaccountpassword
com_atproto_admin_updateaccountsigningkey
com_atproto_admin_updatesubjectstatus
com_atproto_identity_defs
com_atproto_identity_getrecommendeddidcredentials
com_atproto_identity_refreshidentity
com_atproto_identity_resolvedid
com_atproto_identity_resolvehandle
com_atproto_identity_resolveidentity
com_atproto_identity_signplcoperation
com_atproto_identity_submitplcoperation
com_atproto_identity_updatehandle
com_atproto_label_defs
com_atproto_label_querylabels
com_atproto_label_subscribelabels
com_atproto_lexicon_schema
com_atproto_moderation_createreport
com_atproto_moderation_defs
com_atproto_repo_applywrites
com_atproto_repo_createrecord
com_atproto_repo_defs
com_atproto_repo_deleterecord
com_atproto_repo_describerepo
com_atproto_repo_getrecord
com_atproto_repo_listmissingblobs
com_atproto_repo_listrecords
com_atproto_repo_putrecord
com_atproto_repo_strongref
com_atproto_repo_uploadblob
com_atproto_server_checkaccountstatus
com_atproto_server_confirmemail
com_atproto_server_createaccount
com_atproto_server_createapppassword
com_atproto_server_createinvitecode
com_atproto_server_createinvitecodes
com_atproto_server_createsession
com_atproto_server_deactivateaccount
com_atproto_server_defs
com_atproto_server_deleteaccount
com_atproto_server_describeserver
com_atproto_server_getaccountinvitecodes
com_atproto_server_getserviceauth
com_atproto_server_getsession
com_atproto_server_listapppasswords
com_atproto_server_refreshsession
com_atproto_server_requestemailupdate
com_atproto_server_requestpasswordreset
com_atproto_server_reservesigningkey
com_atproto_server_resetpassword
com_atproto_server_revokeapppassword
com_atproto_server_updateemail
com_atproto_services
com_atproto_sync_defs
com_atproto_sync_getblob
com_atproto_sync_getblocks
com_atproto_sync_getcheckout
com_atproto_sync_gethead
com_atproto_sync_gethoststatus
com_atproto_sync_getlatestcommit
com_atproto_sync_getrecord
com_atproto_sync_getrepo
com_atproto_sync_getrepostatus
com_atproto_sync_listblobs
com_atproto_sync_listhosts
com_atproto_sync_listrepos
com_atproto_sync_listreposbycollection
com_atproto_sync_notifyofupdate
com_atproto_sync_requestcrawl
com_atproto_sync_subscriberepos
com_atproto_temp_addreservedhandle
com_atproto_temp_checkhandleavailability
com_atproto_temp_checksignupqueue
com_atproto_temp_fetchlabels
com_atproto_temp_requestphoneverification
com_atproto_temp_revokeaccountcredentials
core
firehose
ids
lex_namespaces
moderation
tools_ozone_communication_createtemplate
tools_ozone_communication_defs
tools_ozone_communication_deletetemplate
tools_ozone_communication_listtemplates
tools_ozone_communication_updatetemplate
tools_ozone_hosting_getaccounthistory
tools_ozone_moderation_defs
tools_ozone_moderation_emitevent
tools_ozone_moderation_getaccounttimeline
tools_ozone_moderation_getevent
tools_ozone_moderation_getrecord
tools_ozone_moderation_getrecords
tools_ozone_moderation_getrepo
tools_ozone_moderation_getreporterstats
tools_ozone_moderation_getrepos
tools_ozone_moderation_getsubjects
tools_ozone_moderation_queryevents
tools_ozone_moderation_querystatuses
tools_ozone_moderation_searchrepos
tools_ozone_report_defs
tools_ozone_server_getconfig
tools_ozone_services
tools_ozone_set_addvalues
tools_ozone_set_defs
tools_ozone_set_deleteset
tools_ozone_set_deletevalues
tools_ozone_set_getvalues
tools_ozone_set_querysets
tools_ozone_setting_defs
tools_ozone_setting_listoptions
tools_ozone_setting_removeoptions
tools_ozone_setting_upsertoption
tools_ozone_signature_defs
tools_ozone_signature_findcorrelation
tools_ozone_signature_findrelatedaccounts
tools_ozone_signature_searchaccounts
tools_ozone_team_addmember
tools_ozone_team_defs
tools_ozone_team_deletemember
tools_ozone_team_listmembers
tools_ozone_team_updatemember
tools_ozone_verification_defs
tools_ozone_verification_grantverifications
tools_ozone_verification_listverifications
tools_ozone_verification_revokeverifications