Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/juni-b-queer/bsky-event-handlers
Typescript based framework for building Bluesky bots. Designed to be easily extendable, this bot framework can be used to make almost any bot you could want.
https://github.com/juni-b-queer/bsky-event-handlers
Last synced: about 1 month ago
JSON representation
Typescript based framework for building Bluesky bots. Designed to be easily extendable, this bot framework can be used to make almost any bot you could want.
- Host: GitHub
- URL: https://github.com/juni-b-queer/bsky-event-handlers
- Owner: juni-b-queer
- Created: 2023-12-22T16:49:52.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-18T18:33:40.000Z (2 months ago)
- Last Synced: 2024-10-20T08:14:01.308Z (2 months ago)
- Language: TypeScript
- Size: 1.17 MB
- Stars: 20
- Watchers: 1
- Forks: 0
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-bluesky - bsky-event-handlers - A simple and extendable Typescript framework and package for creating Bluesky bots that consume the firehose stream, without having to touch any firehose code. (Other tools)
README
# bsky-event-handlers
An easy package to use for making bluesky bots with validators and handler actions
[](https://github.com/juni-b-queer/bsky-event-handlers/actions/workflows/testandlint.yml?query=branch%3Amain)
[](https://github.com/juni-b-queer/bsky-event-handlers/actions/workflows/semanticversionpublish.yml?query=branch%3Amain)
[](https://app.codecov.io/gh/juni-b-queer/bsky-event-handlers)
[](https://www.npmjs.com/package/bsky-event-handlers)
[](https://github.com/juni-b-queer/bsky-event-handlers/releases/latest)
[](https://github.com/juni-b-queer/bsky-event-handlers/releases)
[](https://github.com/juni-b-queer/bsky-event-handlers)
Scaffold a new project with this package using: \
[](https://www.npmjs.com/package/create-bsky-bot)
# Table of contents
**There is a lot of work left to be done for likes, reskeets, and follows, but is mostly complete for handling new
skeets**
- [Quickstart](#quickstart)
- [Overview](#overview)
- [Agent](./src/agent/README.md)
- [Validators](./src/validations/README.md)
- [Actions](./src/actions/README.md)
- [Handlers](./src/handlers/README.md)
- [Record Handlers](./src/handlers/README.md)
- [Pre-made Handlers](./src/handlers/premade-handlers/README.md)
- [Jetsteam Firehose Subscription](./src/firehose/README.md)
- [Utility Functions](./src/utils/README.md)
- [Jetstream Types](./src/types/README.md)
- [Credits](#credits)
[npm Package](https://www.npmjs.com/package/bsky-event-handlers)
# Quickstart
## Scaffold project with [create-bsky-bot](https://github.com/juni-b-queer/create-bsky-bot)
Run `bunx create-bsky-bot {name}` to scaffold the project with jetstream and docker files all ready for you
Enter the new directory
Copy the .env.example into a new .env and fill in the handle and password
Start building!
To run it, run `make up`. This will build your bot into a container and run it, along with a jetstream container.
## Getting it running on your own
This guide is assuming you're using BunJS
Install the package
`bun install --save bsky-event-handlers`
Then, in your `index.ts` you'll need a few things
Create your bsky agent and prepare your jetstreamSubscription variable
```typescript
const testAgent = new HandlerAgent(
'test-bot',
Bun.env.TEST_BSKY_HANDLE,
Bun.env.TEST_BSKY_PASSWORD
);
let jetstreamSubscription: JetstreamSubscription;
```
Initialize your handlers
```typescript
const handlers: JetstreamSubscriptionHandlers = {
post: {
c: [
new CreateSkeetHandler(
[new InputEqualsValidator('Hello')],
[new ReplyToSkeetAction('World!')],
testAgent
),
],
d: [],
},
like: {
c: [],
d: [],
},
follow: {
c: [],
d: [],
},
repost: {
c: [],
d: [],
},
};
```
If you're not acting on the creation/deletion of either of the four options, you can exclude them from this object
for our example, we'll only be acting upon post creations, so our handlers will look like
```typescript
const handlers: JetstreamSubscriptionHandlers = {
post: {
c: [
new CreateSkeetHandler(
[new InputEqualsValidator('Hello')],
[new ReplyToSkeetAction('World!')],
testAgent
),
],
},
};
```
By excluding the others, the Jetstream subscription will automatically update it's subscription url to query for only
post events.
Then in out `initialize` function, we authenticate the agent, and create the JetstreamSubscription object
```typescript
async function initialize() {
await testAgent.authenticate();
DebugLog.info('INIT', 'Initialized!');
jetstreamSubscription = new JetstreamSubscription(
handlers,
Bun.env.JETSTREAM_URL
);
}
```
Then finally, we call initialize, then start the subscription to listen for events
```typescript
initialize().then(() => {
jetstreamSubscription.createSubscription();
});
```
All together, a simple bot index.ts would look like
```typescript
import {
HandlerAgent,
JetstreamSubscriptionHandlers,
JetstreamSubscription,
CreateSkeetHandler,
InputEqualsValidator,
ReplyToSkeetAction,
DebugLog,
} from 'bsky-event-handlers';
const testAgent = new HandlerAgent(
'test-bot',
Bun.env.TEST_BSKY_HANDLE,
Bun.env.TEST_BSKY_PASSWORD
);
let jetstreamSubscription: JetstreamSubscription;
const handlers: JetstreamSubscriptionHandlers = {
post: {
c: [
new CreateSkeetHandler(
[new InputEqualsValidator('Hello')],
[new ReplyToSkeetAction('World!')],
testAgent
),
],
},
};
async function initialize() {
await testAgent.authenticate();
DebugLog.info('INIT', 'Initialized!');
jetstreamSubscription = new JetstreamSubscription(
handlers,
Bun.env.JETSTREAM_URL
);
}
initialize().then(() => {
jetstreamSubscription.createSubscription();
});
```
A simple hello world bot is only 44 lines of code, and that's including the import!
For full example code with Jetstream setup and docker usage, see
my [Test firehose bot](https://github.com/juni-b-queer/test-firehose-bot)
### Env requirements
Your .env should look something like this
```.env
TEST_BSKY_HANDLE=handle.bsky.social
TEST_BSKY_PASSWORD=app-pass-word
DEBUG_LOG_ACTIVE=true #This will enable DebugLog
DEBUG_LOG_LEVEL=info # This sets the minimum log level that will be output
JETSTREAM_URL='ws://localhost:6008/subscribe'
```
# Overview
I wrote this package because I wanted a simple and quick way to get firehose bluesky bots up and running.
Bluesky Event Handlers is a powerful, adaptable package developed for creating bots within the Bluesky ecosystem. The
package offers a wide array of inbuilt validators and action handlers to facilitate the creation of event-driven bot
actions- all of which contribute to smoother, faster, and more efficient bot development.
The package internally uses the Bluesky Agent to interact with the Bluesky network. The flexibility provided by the
AbstractValidator and AbstractMessageAction base classes, paves the way for easy extension and creation of custom
validators and actions to suit your specific requirements.
By leveraging the combination of Validators and Actions, you can create a unique sequence of automatic responses for
your bot in response to defined triggers, enhancing your bot's interactivity, flexibility and efficiency.
# Credits
## Packages/dependencies used
- [@atproto/api](https://www.npmjs.com/package/@atproto/api)
- [Jetstream](https://github.com/ericvolp12/jetstream) (Though I use
a [forked version](https://github.com/juni-b-queer/jetstream) to include the CID and build/publish the docker
container)
## Contact me
[](#contact-me)
[](https://bsky.app/profile/did:plc:wpp4lklhvmopw6zcy6qb42ru)