innocenzi/bluesky-notification-channel

Bluesky notification channel for the Laravel framework

v0.2.2 2024-12-05 14:10 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^11.0
• spatie/laravel-package-tools: ^1.16.5

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.64
• guzzlehttp/guzzle: ^7.9.2
• nunomaduro/collision: ^8.5
• orchestra/testbench: ^9.5.2
• pestphp/pest: ^3.5
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• spatie/laravel-ray: ^1.37.1

MIT

• Enzo Innocenzi

• laravel
• notification-channel
• bluesky
• Enzo Innocenzi

README

 

Notification channel implementation to create Bluesky posts using Laravel.

composer require innocenzi/bluesky-notification-channel

 

Configuring credentials

To interact with its API, Bluesky recommends creating an application-specific password instead of using your account's main password. You may generate one in your account settings. Once created, fill your .env accordingly:

BLUESKY_USERNAME=your-handle
BLUESKY_PASSWORD=your-app-password

Add these values to config/services.php:

return [
    // ...
    'bluesky' => [
      'username' => env('BLUESKY_USERNAME'),
      'password' => env('BLUESKY_PASSWORD'),
    ]
];

 

Publishing posts

To create a post, you will need to instruct the notification of your choice to use the BlueskyChannel channel and to implement the corresponding toBluesky method.

This method may return a BlueskyPost instance or a simple string.

final class CreateBlueskyPost extends Notification
{
    public function via(object $notifiable): array
    {
        return [
            BlueskyChannel::class
        ];
    }

    public function toBluesky(object $notifiable): BlueskyPost
    {
        return BlueskyPost::make()
            ->text('Test from Laravel');
    }
}

You may then dispatch the notification:

// Without a notifiable
(new AnonymousNotifiable())->notify(new CreateBlueskyPost);

// With a notifiable
$post->notify(new CreateBlueskyPost);

 

Sessions

Bluesky doesn't provide a way to authenticate requests using classic API tokens. Instead, they only offer a JWT-based authentication system, including an access and a refresh token.

Since these tokens expire, they cannot be stored in the environment. They are generated dynamically by creating and refreshing sessions and they need to be kept for as long as possible.

This notification channel implementation uses a session manager and an identity repository based on Laravel's cache. This may be overriden by swapping NotificationChannels\Bluesky\IdentityRepository\IdentityRepository in the container.

Additionnally, the key used by the cache-based identity repository may be configured by setting the services.bluesky.identity_cache_key option.

 

Embeds

For Bluesky, embeds are a client-side responsibility, which means we have to generate website embeds ourselves.

This notification channel implementation uses Bluesky's own private API, cardyb.bsky.app, to fetch a website's metadata, including an URL to its thumbnail. However, that thumbnail stills has to be uploaded to Bluesky as a blob, so a reference to that blob can be added to the post's embed.

You may disable automatic embed generation by calling withoutAutomaticEmbeds on a BlueskyPost instance, or replace the implementation altogether by swapping NotificationChannels\Bluesky\Embeds\EmbedResolver in the container.