The Easiest and Powerful Dart/Flutter Library for Bluesky Social 🎯

1. Guide 🌎

1. Guide 🌎 #

This library provides the easiest way to use Bluesky Social in Dart and Flutter apps.

Show some ❤️ and star the repo to support the project.

bluesky is developed on the basis of the atproto package. However, the atproto package is highly integrated into this package, so you do not need to be aware of atproto when you use bluesky.

If you want to use atproto-only features, please check atproto.

1.1. Features 💎 #

✅ The wrapper library for Bluesky Social.
✅ Easily integrates with the Dart & Flutter apps.
✅ Provides response objects with a guaranteed safe types.
✅ Well documented and well tested.
✅ Supports the powerful automatic retry.

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 #

import 'package:bluesky/bluesky.dart' as bsky;

Future<void> main() async {
  try {
    final bluesky = bsky.Bluesky.fromSession(
      //! First you need to establish session with ATP server.
      await _session,

      //! The default is `bsky.social`
      service: 'SERVICE_NAME',

      //! Automatic retry is available when server error or network error occurs
      //! when communicating with the API.
      retryConfig: bsky.RetryConfig(
        maxAttempts: 5,
        jitter: bsky.Jitter(
          minInSeconds: 2,
          maxInSeconds: 5,
        ),
        onExecute: (event) => print(
          'Retry after ${event.intervalInSeconds} seconds...'
          '[${event.retryCount} times]',
        ),
      ),

      //! The default timeout is 10 seconds.
      timeout: Duration(seconds: 20),
    );

    //! Let's get home timeline!
    final feeds = await bluesky.feeds.findTimeline(
      limit: 10,
    );

    print(feeds);

    //! Let's post cool stuff!
    final createdRecord = await bluesky.feeds.createPost(
      text: 'Hello, Bluesky!',
    );

    print(createdRecord);

    //! And delete it.
    await bluesky.repositories.deleteRecord(
      uri: createdRecord.data.uri,
    );
  } on bsky.UnauthorizedException catch (e) {
    print(e);
  } on bsky.XRPCException catch (e) {
    print(e);
  }
}

Future<bsky.Session> get _session async {
  final session = await bsky.createSession(
    service: 'SERVICE_NAME', //! The default is `bsky.social`
    identifier: 'YOUR_HANDLE_OR_EMAIL', //! Like `shinyakato.bsky.social`
    password: 'YOUR_PASSWORD',
  );

  return session.data;
}

1.3. Supported Lexicons 👀 #

1.3.1. Actors #

Lexicon	Method Name
GET app.bsky.actor.searchActors	searchActors
GET app.bsky.actor.getProfile	findProfile
GET app.bsky.actor.getProfiles	findProfiles
GET app.bsky.actor.getSuggestions	findSuggestions
GET app.bsky.actor.searchActorsTypeahead	searchTypeahead

1.3.2. Feeds #

Lexicon	Method Name
POST app.bsky.feed.post	createPost
GET app.bsky.feed.getTimeline	findTimeline
POST app.bsky.feed.repost	createRepost
POST app.bsky.feed.like	createLike
GET app.bsky.feed.getAuthorFeed	findFeed
GET app.bsky.feed.getLikes	findLikes
GET app.bsky.feed.getRepostedBy	findRepostedBy
GET app.bsky.feed.getPostThread	findPosThread

1.3.3. Notifications #

Lexicon	Method Name
GET app.bsky.notification.listNotifications	findNotifications
GET app.bsky.notification.getUnreadCount	findUnreadCount
POST app.bsky.notification.updateSeen	updateNotificationsAdRead

1.3.4. Graphs #

Lexicon	Method Name
POST app.bsky.graph.follow	createFollow
GET app.bsky.graph.getFollows	findFollows
GET app.bsky.graph.getFollowers	findFollowers
POST app.bsky.graph.muteActor	createMute
POST app.bsky.graph.unmuteActor	deleteMute
GET app.bsky.graph.getMutes	findMutes

1.3.5. Unspecced #

Lexicon	Method Name
GET app.bsky.unspecced.getPopular	findPopularFeed

1.4. Tips 🏄 #

1.4.1. Method Names #

bluesky uses the following standard prefixes depending on endpoint characteristics. So it's very easy to find the method corresponding to the endpoint you want to use!

Prefix	Description
find	This prefix is attached to endpoints that reference accounts, etc.
search	This prefix is attached to endpoints that perform extensive searches.
create	This prefix is attached to the endpoint performing the create state.
delete	This prefix is attached to the endpoint performing the delete state.
update	This prefix is attached to the endpoint performing the update state.

1.4.2. Create Session #

First, in order for us to enjoy using this library programmatically in Bluesky, we need to send a request to the ATP server and establish a session.

Once this session is established, you will have an access token to use Bluesky's API.

You can easily establish a session with the following process. Prepare the name of the service you wish to establish a session with and your credentials.

import 'package:bluesky/bluesky.dart' as bsky;

Future<void> main() async {
  final session = await bsky.createSession(
    service: 'SERVICE_NAME', //! The default is `bsky.social`
    identifier: 'YOUR_HANDLE_OR_EMAIL', //! Like `shinyakato.bsky.social`
    password: 'YOUR_PASSWORD',
  );

  print(session);
}

Once you have established a session, you can now create an instance of the Bluesky object. You can easily create an instance of a Bluesky object from a previously established Session object.

import 'package:bluesky/bluesky.dart' as bsky;

Future<void> main() async {
  final session = await bsky.createSession(
    service: 'SERVICE_NAME', //! The default is `bsky.social`
    identifier: 'YOUR_HANDLE_OR_EMAIL', //! Like `shinyakato.bsky.social`
    password: 'YOUR_PASSWORD',
  );

  final bluesky = bsky.Bluesky.fromSession(
    session.data,
  );
}

Or, you can do as follows:

import 'package:bluesky/bluesky.dart' as bsky;

Future<void> main() async {
  final session = await bsky.createSession(
    service: 'SERVICE_NAME', //! The default is `bsky.social`
    identifier: 'YOUR_HANDLE_OR_EMAIL', //! Like `shinyakato.bsky.social`
    password: 'YOUR_PASSWORD',
  );

  final bluesky = bsky.Bluesky(
    did: session.data.did,
    accessJwt: session.data.accessJwt,
  );
}

1.4.3. Null Parameter at Request #

In this library, parameters that are not required at request time, i.e., optional parameters, are defined as nullable. However, developers do not need to be aware of the null parameter when sending requests when using this library.

It means the parameters specified with a null value are safely removed and ignored before the request is sent.

For example, arguments specified with null are ignored in the following request.

import 'package:bluesky/bluesky.dart' as bsky;

Future<void> main() async {
  final bluesky = bsky.Bluesky.fromSession(await _session);
  //! Let's get home timeline!
  final feeds = await bluesky.feeds.getHomeTimeline(
    algorithm: null,
    limit: null,
  );

  print(feeds);
}

Future<bsky.Session> get _session async {
  final session = await bsky.createSession(
    identifier: 'YOUR_HANDLE_OR_EMAIL',
    password: 'YOUR_PASSWORD',
  );

  return session.data;
}

1.4.4. Change the Timeout Duration #

The library specifies a default timeout of 10 seconds for all API communications.

However, there may be times when you wish to specify an arbitrary timeout duration. If there is such a demand, an arbitrary timeout duration can be specified as follows.

import 'package:bluesky/bluesky.dart' as bsky;

Future<void> main() async {
  final bluesky = bsky.Bluesky(
    did: 'YOUR_DID',
    accessJwt: 'YOUR_TOKEN',

    //! The default timeout is 10 seconds.
    timeout: Duration(seconds: 20),
  );
}

1.4.5. Automatic Retry #

Due to the nature of this library's communication with external systems, timeouts may occur due to inevitable communication failures or temporary crashes of the server to which requests are sent.

When such timeouts occur, an effective countermeasure in many cases is to send the request again after a certain interval. And bluesky provides an automatic retry feature as a solution to this problem.

Also, errors subject to retry are as follows.

When the status code of the response returned from ATP server is 500 or 503.
When the network is temporarily lost and a SocketException is thrown.
When communication times out temporarily and a TimeoutException is thrown

1.4.5.1. Exponential Backoff and Jitter

Although the algorithm introduced earlier that exponentially increases the retry interval is already powerful, some may believe that it is not yet sufficient to distribute the sensation of retries. It's more distributed than equally spaced retries, but retries still occur at static intervals.

This problem can be solved by adding a random number called Jitter, and this method is called the Exponential Backoff and Jitter algorithm. By adding a random number to the exponentially increasing retry interval, the retry interval can be distributed more flexibly.

Similar to the previous example, bluesky can be implemented as follows.

import 'package:bluesky/bluesky.dart' as bsky;

Future<void> main() async {
  final bluesky = bsky.Bluesky(
    did: 'YOUR_DID',
    accessJwt: 'YOUR_TOKEN',

    //! Add these lines.
    retryConfig: bsky.RetryConfig(
      maxAttempts: 3,
    ),
  );
}

In the above implementation, the interval increases exponentially for each retry count with jitter. It can be expressed by next formula.

(2 ^ retryCount) + jitter(Random Number between 0 ~ 3)

1.4.5.2. Do Something on Retry

It would be useful to output logging on retries and a popup notifying the user that a retry has been executed. So bluesky provides callbacks that can perform arbitrary processing when retries are executed.

It can be implemented as follows.

import 'package:bluesky/bluesky.dart' as bsky;

Future<void> main() async {
  final bluesky = bsky.Bluesky(
    did: 'YOUR_DID',
    accessJwt: 'YOUR_TOKEN',

    retryConfig: bsky.RetryConfig(
      maxAttempts: 3,

      //! Add this line.
      onExecute: (event) => print('Retrying... ${event.retryCount} times.'),
    ),
  );
}

The RetryEvent passed to the callback contains information on retries.

1.4.6. Thrown Exceptions #

bluesky provides a convenient exception object for easy handling of exceptional responses and errors returned from AT Protocol.

Exception	Description
XRPCException	Parent class for all the following Exceptions.
UnauthorizedException	Thrown when authentication fails with the specified access token.
RateLimitExceededException	Thrown when the rate limit is reached.
InvalidRequestException	Thrown when request parameters are invalid.
InternalServerErrorException	Thrown when a failure occurs on the ATP server.

Also, all of the above exceptions thrown from the bluesky process extend XRPCException. This means that you can take all exceptions as XRPCException or handle them as certain exception types, depending on the situation.

However note that, if you receive an individual type exception, be sure to define the process so that the individual exception type is cached before XRPCException. Otherwise, certain type exceptions will also be caught as XRPCException.

Therefore, if you need to catch a specific type of exception in addition to XRPCException, be sure to catch XRPCException in the bottom catch clause as in the following example.

import 'package:bluesky/bluesky.dart' as bsky;

Future<void> main() async {
  final bluesky = bsky.Bluesky(
    did: 'YOUR_DID',
    accessJwt: 'YOUR_TOKEN',
  );

  try {
    final response = await bluesky.feeds.getHomeTimeline();

    print(response);
  } on bsky.UnauthorizedException catch (e) {
    print(e);
  } on bsky.XRPCException catch (e) {
    print(e);
  }
}

1.5. Contribution 🏆 #

If you would like to contribute to bluesky, please create an issue or create a Pull Request.

There are many ways to contribute to the OSS. For example, the following subjects can be considered:

There are request parameters or response fields that are not implemented.
Documentation is outdated or incomplete.
Have a better way or idea to achieve the functionality.
etc...

You can see more details from resources below:

Or you can create a discussion if you like.

Feel free to join this development, diverse opinions make software better!

1.6. Support ❤️ #

The simplest way to show us your support is by giving the project a star at GitHub and Pub.dev.

You can also support this project by becoming a sponsor on GitHub:

You can also show on your repository that your app is made with bluesky by using one of the following badges:

[![Powered by bluesky](https://img.shields.io/badge/Powered%20by-bluesky-00acee.svg)](https://github.com/myConsciousness/atproto.dart)
[![Powered by bluesky](https://img.shields.io/badge/Powered%20by-bluesky-00acee.svg?style=flat-square)](https://github.com/myConsciousness/atproto.dart)
[![Powered by bluesky](https://img.shields.io/badge/Powered%20by-bluesky-00acee.svg?style=for-the-badge)](https://github.com/myConsciousness/atproto.dart)

1.7. License 🔑 #

All resources of bluesky is provided under the BSD-3 license.

Copyright 2023 Shinya Kato. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided the conditions.

Note
License notices in the source are strictly validated based on .github/header-checker-lint.yml. Please check header-checker-lint.yml for the permitted standards.

1.8. More Information 🧐 #

bluesky was designed and implemented by Shinya Kato (@myConsciousness).

bluesky 0.3.7
bluesky: ^0.3.7 copied to clipboard

Metadata

1. Guide 🌎 #

1.1. Features 💎 #

1.2. Getting Started ⚡ #

1.2.1. Install Library #

1.2.2. Import #

1.2.3. Implementation #

1.3. Supported Lexicons 👀 #

1.3.1. Actors #

1.3.2. Feeds #

1.3.3. Notifications #

1.3.4. Graphs #

1.3.5. Unspecced #

1.4. Tips 🏄 #

1.4.1. Method Names #

1.4.2. Create Session #

1.4.3. Null Parameter at Request #

1.4.4. Change the Timeout Duration #

1.4.5. Automatic Retry #

1.4.5.1. Exponential Backoff and Jitter

1.4.5.2. Do Something on Retry

1.4.6. Thrown Exceptions #

1.5. Contribution 🏆 #

1.6. Support ❤️ #

1.7. License 🔑 #

1.8. More Information 🧐 #

← Metadata

Publisher

Metadata

Funding

License

Dependencies

More

bluesky 0.3.7 bluesky: ^0.3.7 copied to clipboard

Metadata

1. Guide 🌎 #

1.1. Features 💎 #

1.2. Getting Started ⚡ #

1.2.1. Install Library #

1.2.2. Import #

1.2.3. Implementation #

1.3. Supported Lexicons 👀 #

1.3.1. Actors #

1.3.2. Feeds #

1.3.3. Notifications #

1.3.4. Graphs #

1.3.5. Unspecced #

1.4. Tips 🏄 #

1.4.1. Method Names #

1.4.2. Create Session #

1.4.3. Null Parameter at Request #

1.4.4. Change the Timeout Duration #

1.4.5. Automatic Retry #

1.4.5.1. Exponential Backoff and Jitter

1.4.5.2. Do Something on Retry

1.4.6. Thrown Exceptions #

1.5. Contribution 🏆 #

1.6. Support ❤️ #

1.7. License 🔑 #

1.8. More Information 🧐 #

← Metadata

Publisher

Metadata

Funding

License

Dependencies

More

bluesky 0.3.7
bluesky: ^0.3.7 copied to clipboard