Merge pull request #53 from juni-b-queer/39-move-reusable-handlers-docs

#39 - Move reusable handlers docs
juni-b-queer · May 17, 2024 · ac2763a · ac2763a
2 parents 2f0336e + a317154
commit ac2763a
Show file tree

Hide file tree

Showing 3 changed files with 118 additions and 123 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,5 @@
 # bsky-event-handlers
 
-
 An easy package to use for making bluesky bots with validators and handler actions
 
 [![GitHub Actions Test Status](https://img.shields.io/github/actions/workflow/status/juni-b-queer/bsky-event-handlers/testandlint.yml?logo=github&label=Tests)](https://github.com/juni-b-queer/bsky-event-handlers/actions/workflows/testandlint.yml?query=branch%3Amain)
@@ -14,23 +13,24 @@ An easy package to use for making bluesky bots with validators and handler actio
 
 Scaffold a new project with this package using: \
 [![create-bsky-bot](https://img.shields.io/badge/create--bsky--bot-white.svg?logo=npm&color=blue)](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)
+-   [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)
 
@@ -61,9 +61,9 @@ Create your bsky agent and prepare your jetstreamSubscription variable
 
 ```typescript
 const testAgent = new HandlerAgent(
-  'test-bot',
-  <string>Bun.env.TEST_BSKY_HANDLE,
-  <string>Bun.env.TEST_BSKY_PASSWORD
+    'test-bot',
+    <string>Bun.env.TEST_BSKY_HANDLE,
+    <string>Bun.env.TEST_BSKY_PASSWORD
 );
 
 let jetstreamSubscription: JetstreamSubscription;
@@ -73,28 +73,28 @@ 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: [],
-  },
+    post: {
+        c: [
+            new CreateSkeetHandler(
+                [new InputEqualsValidator('Hello')],
+                [new ReplyToSkeetAction('World!')],
+                testAgent
+            ),
+        ],
+        d: [],
+    },
+    like: {
+        c: [],
+        d: [],
+    },
+    follow: {
+        c: [],
+        d: [],
+    },
+    repost: {
+        c: [],
+        d: [],
+    },
 };
 ```
 
@@ -104,15 +104,15 @@ for our example, we'll only be acting upon post creations, so our handlers will
 
 ```typescript
 const handlers: JetstreamSubscriptionHandlers = {
-  post: {
-    c: [
-      new CreateSkeetHandler(
-        [new InputEqualsValidator('Hello')],
-        [new ReplyToSkeetAction('World!')],
-        testAgent
-      ),
-    ],
-  },
+    post: {
+        c: [
+            new CreateSkeetHandler(
+                [new InputEqualsValidator('Hello')],
+                [new ReplyToSkeetAction('World!')],
+                testAgent
+            ),
+        ],
+    },
 };
 ```
 
@@ -123,69 +123,69 @@ Then in out `initialize` function, we authenticate the agent, and create the Jet
 
 ```typescript
 async function initialize() {
-  await testAgent.authenticate();
-  DebugLog.info('INIT', 'Initialized!');
+    await testAgent.authenticate();
+    DebugLog.info('INIT', 'Initialized!');
 
-  jetstreamSubscription = new JetstreamSubscription(
-    handlers,
-    <string>Bun.env.JETSTREAM_URL
-  );
+    jetstreamSubscription = new JetstreamSubscription(
+        handlers,
+        <string>Bun.env.JETSTREAM_URL
+    );
 }
 ```
 
 Then finally, we call initialize, then start the subscription to listen for events
 
 ```typescript
 initialize().then(() => {
-  jetstreamSubscription.createSubscription();
+    jetstreamSubscription.createSubscription();
 });
 ```
 
 All together, a simple bot index.ts would look like
 
 ```typescript
 import {
-  HandlerAgent,
-  JetstreamSubscriptionHandlers,
-  JetstreamSubscription,
-  CreateSkeetHandler,
-  InputEqualsValidator,
-  ReplyToSkeetAction,
-  DebugLog,
+    HandlerAgent,
+    JetstreamSubscriptionHandlers,
+    JetstreamSubscription,
+    CreateSkeetHandler,
+    InputEqualsValidator,
+    ReplyToSkeetAction,
+    DebugLog,
 } from 'bsky-event-handlers';
 
 const testAgent = new HandlerAgent(
-  'test-bot',
-  <string>Bun.env.TEST_BSKY_HANDLE,
-  <string>Bun.env.TEST_BSKY_PASSWORD
+    'test-bot',
+    <string>Bun.env.TEST_BSKY_HANDLE,
+    <string>Bun.env.TEST_BSKY_PASSWORD
 );
 
 let jetstreamSubscription: JetstreamSubscription;
 
 const handlers: JetstreamSubscriptionHandlers = {
-  post: {
-    c: [
-      new CreateSkeetHandler(
-        [new InputEqualsValidator('Hello')],
-        [new ReplyToSkeetAction('World!')],
-        testAgent
-      ),
-    ],
-  },
+    post: {
+        c: [
+            new CreateSkeetHandler(
+                [new InputEqualsValidator('Hello')],
+                [new ReplyToSkeetAction('World!')],
+                testAgent
+            ),
+        ],
+    },
 };
 
 async function initialize() {
-  await testAgent.authenticate();
-  DebugLog.info('INIT', 'Initialized!');
+    await testAgent.authenticate();
+    DebugLog.info('INIT', 'Initialized!');
 
-  jetstreamSubscription = new JetstreamSubscription(
-    handlers,
-    <string>Bun.env.JETSTREAM_URL
-  );
+    jetstreamSubscription = new JetstreamSubscription(
+        handlers,
+        <string>Bun.env.JETSTREAM_URL
+    );
 }
 
 initialize().then(() => {
-  jetstreamSubscription.createSubscription();
+    jetstreamSubscription.createSubscription();
 });
 ```
 
@@ -224,13 +224,12 @@ your bot in response to defined triggers, enhancing your bot's interactivity, fl
 
 ## 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)
-
+-   [@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
 
 [![discord](https://img.shields.io/badge/junib33-7289da.svg?logo=discord)](#contact-me)
-[![bsky](https://img.shields.io/badge/Juni!_on_Bluesky-5BCEFA.svg?logo=bluesky)](https://bsky.app/profile/did:plc:wpp4lklhvmopw6zcy6qb42ru)
+[![bsky](https://img.shields.io/badge/Juni!_on_Bluesky-5BCEFA.svg?logo=bluesky)](https://bsky.app/profile/did:plc:wpp4lklhvmopw6zcy6qb42ru)
diff --git a/src/handlers/README.md b/src/handlers/README.md
@@ -57,37 +57,3 @@ CreateSkeetHandler.make(
     handlerAgent
 );
 ```
-
-## Creating a reusable handler
-
-A handler needs validators, actions, and an agent. Creating your own handler makes it easier to reuse them. The Good/Bad bot handlers are premade and ready to use.
-
-Your handler must extend AbstractMessageHandler or for handlers to only handle CreateSkeetMessages, extend CreateSkeetHandler.
-
-The below example simply takes in the handlerAgent, but has the validators and actions set automatically in the constructor
-
-```typescript
-export class ExampleHandler extends CreateSkeetHandler {
-    constructor(public handlerAgent: HandlerAgent) {
-        super(
-            [InputEqualsValidator.make('Hello')],
-            [ReplyToSkeetAction.make('World!')],
-            handlerAgent
-        );
-    }
-
-    async handle(message: CreateSkeetMessage): Promise<void> {
-        return super.handle(message);
-    }
-}
-```
-
-To use this handler, you'll just use `ExampleHandler.make(handlerAgent)` in your handlers object
-
-```typescript
-let handlers = {
-    post: {
-        c: [ExampleHandler.make(handlerAgent)],
-    },
-};
-```
diff --git a/src/handlers/premade-handlers/README.md b/src/handlers/premade-handlers/README.md
@@ -26,6 +26,36 @@ And the third is what the response will be if someone uses the command
 
 `OfflineHandler.make(handlerAgent, "command", "response")`
 
-# Creating premade handlers
-
-See the Creating a reusable handler section in the [Handlers README](../README.md#creating-a-reusable-handler)
+## Creating a reusable handler
+
+A handler needs validators, actions, and an agent. Creating your own handler makes it easier to reuse them. The Good/Bad bot handlers are premade and ready to use.
+
+Your handler must extend AbstractMessageHandler or for handlers to only handle CreateSkeetMessages, extend CreateSkeetHandler.
+
+The below example simply takes in the handlerAgent, but has the validators and actions set automatically in the constructor
+
+```typescript
+export class ExampleHandler extends CreateSkeetHandler {
+    constructor(public handlerAgent: HandlerAgent) {
+        super(
+            [InputEqualsValidator.make('Hello')],
+            [ReplyToSkeetAction.make('World!')],
+            handlerAgent
+        );
+    }
+
+    async handle(message: CreateSkeetMessage): Promise<void> {
+        return super.handle(message);
+    }
+}
+```
+
+To use this handler, you'll just use `ExampleHandler.make(handlerAgent)` in your handlers object
+
+```typescript
+let handlers = {
+    post: {
+        c: [ExampleHandler.make(handlerAgent)],
+    },
+};
+```