}
160 |
161 |
162 | );
163 | };
164 |
165 | const app = new Hono();
166 |
167 | app.get("/", (c) => {
168 | return c.html();
169 | });
170 |
171 | app.post("/otp", async (c) => {
172 | const form = await c.req.formData();
173 | const handle = form.get("handle")?.toString();
174 | if (handle == null) return c.notFound();
175 | const emojis = generateRandomEmojis();
176 | const session = bot.getSession(c.req.url);
177 | const recipient = await session.context.lookupObject(handle);
178 | if (!isActor(recipient)) return c.notFound();
179 | const message = await session.publish(
180 | text`${recipient} Please choose the only emojis you see in the web page to authenticate:`,
181 | {
182 | visibility: "direct",
183 | class: Question,
184 | poll: {
185 | multiple: true,
186 | options: EMOJI_CODES,
187 | endTime: Temporal.Now.instant().add({ minutes: 15 }),
188 | },
189 | },
190 | );
191 | await kv.set(["emojis", message.id.href], emojis, {
192 | expireIn: 15 * 60 * 1000, // 15 minutes
193 | });
194 | await kv.set(["recipients", message.id.href], recipient.id?.href, {
195 | expireIn: 15 * 60 * 1000, // 15 minutes
196 | });
197 | return c.html(
198 | ,
199 | );
200 | });
201 |
202 | app.post("/authenticate", async (c) => {
203 | const form = await c.req.formData();
204 | const messageId = form.get("messageId")?.toString();
205 | if (messageId == null) return c.notFound();
206 | const key = await kv.get(["emojis", messageId]);
207 | if (key?.value == null) return c.notFound();
208 | const emojis = new Set(key.value);
209 | const answer = new Set();
210 | for await (const entry of kv.list({ prefix: ["votes", messageId] })) {
211 | if (entry.key.length < 3 || typeof entry.key[2] !== "string") continue;
212 | answer.add(entry.key[2]);
213 | }
214 | const authenticated = answer.size === emojis.size &&
215 | answer.difference(emojis).size === 0;
216 | return c.html();
217 | });
218 |
219 | export default {
220 | async fetch(request: Request): Promise {
221 | request = await getXForwardedRequest(request);
222 | const url = new URL(request.url);
223 | if (
224 | url.pathname.startsWith("/.well-known/") ||
225 | url.pathname.startsWith("/ap/")
226 | ) {
227 | return await bot.fetch(request);
228 | }
229 | return await app.fetch(request);
230 | },
231 | };
232 |
--------------------------------------------------------------------------------
/docs/.vitepress/config.mts:
--------------------------------------------------------------------------------
1 | import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
2 | import deflist from "markdown-it-deflist";
3 | import footnote from "markdown-it-footnote";
4 | import { jsrRef } from "markdown-it-jsr-ref";
5 | import process from "node:process";
6 | import { ModuleKind, ModuleResolutionKind } from "typescript";
7 | import { defineConfig } from "vitepress";
8 | import {
9 | groupIconMdPlugin,
10 | groupIconVitePlugin,
11 | } from "vitepress-plugin-group-icons";
12 | import llmstxt from "vitepress-plugin-llms";
13 |
14 | const jsrRefPlugin = await jsrRef({
15 | package: "@fedify/botkit",
16 | version: "unstable",
17 | cachePath: ".jsr-cache.json",
18 | });
19 |
20 | let plausibleScript: [string, Record][] = [];
21 | if (process.env.PLAUSIBLE_DOMAIN) {
22 | plausibleScript = [
23 | [
24 | "script",
25 | {
26 | defer: "defer",
27 | "data-domain": process.env.PLAUSIBLE_DOMAIN,
28 | src: "https://plausible.io/js/plausible.js",
29 | },
30 | ],
31 | ];
32 | }
33 |
34 | const concepts = {
35 | text: "Concepts",
36 | items: [
37 | { text: "Bot", link: "/concepts/bot.md" },
38 | { text: "Session", link: "/concepts/session.md" },
39 | { text: "Events", link: "/concepts/events.md" },
40 | { text: "Message", link: "/concepts/message.md" },
41 | { text: "Text", link: "/concepts/text.md" },
42 | { text: "Repository", link: "/concepts/repository.md" },
43 | ],
44 | };
45 |
46 | const deploy = {
47 | text: "Deploy",
48 | items: [
49 | { text: "Store and message queue", link: "/deploy/store-mq.md" },
50 | { text: "Deno Deploy", link: "/deploy/deno-deploy.md" },
51 | { text: "Docker", link: "/deploy/docker.md" },
52 | { text: "Self-hosting", link: "/deploy/self-hosting.md" },
53 | ],
54 | };
55 |
56 | const references = {
57 | text: "References",
58 | items: [
59 | { text: "@fedify/botkit", link: "https://jsr.io/@fedify/botkit/doc" },
60 | {
61 | text: "@fedify/botkit-sqlite",
62 | link: "https://jsr.io/@fedify/botkit-sqlite/doc",
63 | },
64 | ],
65 | };
66 |
67 | // https://vitepress.dev/reference/site-config
68 | export default defineConfig({
69 | title: "BotKit by Fedify",
70 | description: "A framework for creating your ActivityPub bots",
71 | themeConfig: {
72 | // https://vitepress.dev/reference/default-theme-config
73 | logo: "/logo.svg",
74 | nav: [
75 | { text: "Home", link: "/" },
76 | { text: "About", link: "/intro.md" },
77 | { text: "Start", link: "/start.md" },
78 | concepts,
79 | deploy,
80 | references,
81 | { text: "Recipes", link: "/recipes.md" },
82 | { text: "Examples", link: "/examples.md" },
83 | ],
84 |
85 | sidebar: [
86 | { text: "What is BotKit?", link: "/intro.md" },
87 | { text: "Getting started", link: "/start.md" },
88 | concepts,
89 | deploy,
90 | references,
91 | { text: "Recipes", link: "/recipes.md" },
92 | { text: "Examples", link: "/examples.md" },
93 | { text: "Changelog", link: "/changelog.md" },
94 | ],
95 |
96 | socialLinks: [
97 | {
98 | icon: "jsr",
99 | link: "https://jsr.io/@fedify/botkit",
100 | ariaLabel: "JSR",
101 | },
102 | {
103 | icon: "npm",
104 | link: "https://www.npmjs.com/package/@fedify/botkit",
105 | ariaLabel: "npm",
106 | },
107 | {
108 | icon: "discord",
109 | link: "https://discord.gg/bhtwpzURwd",
110 | ariaLabel: "Discord",
111 | },
112 | {
113 | icon: {
114 | svg:
115 | '',
116 | },
117 | link: "https://hollo.social/@botkit",
118 | ariaLabel: "Hollo (ActivityPub)",
119 | },
120 | { icon: "github", link: "https://github.com/fedify-dev/botkit" },
121 | ],
122 |
123 | search: {
124 | provider: "local",
125 | },
126 |
127 | outline: "deep",
128 | },
129 |
130 | head: [
131 | [
132 | "link",
133 | {
134 | rel: "icon",
135 | type: "image/png",
136 | sizes: "192x192",
137 | href: "/favicon-192x192.png",
138 | },
139 | ],
140 | [
141 | "link",
142 | {
143 | rel: "icon",
144 | type: "image/png",
145 | sizes: "32x32",
146 | href: "/favicon-32x32.png",
147 | },
148 | ],
149 | [
150 | "meta",
151 | {
152 | property: "og:image",
153 | content:
154 | "https://repository-images.githubusercontent.com/913141583/852a1091-14d5-46a0-b3bf-8d2f45ef6e7f",
155 | },
156 | ],
157 | [
158 | "meta",
159 | {
160 | name: "fediverse:creator",
161 | content: "@botkit@hollo.social",
162 | },
163 | ],
164 | ...plausibleScript,
165 | ],
166 |
167 | cleanUrls: true,
168 | ignoreDeadLinks: true,
169 |
170 | markdown: {
171 | languages: ["js", "jsx", "ts", "tsx", "typescript", "bash", "sh", "shell", "json", "text", "html"],
172 | codeTransformers: [
173 | transformerTwoslash({
174 | twoslashOptions: {
175 | compilerOptions: {
176 | lib: ["dom", "dom.iterable", "esnext"],
177 | types: ["dom", "dom.iterable", "esnext", "@types/deno", "node"],
178 | moduleResolution: ModuleResolutionKind.Bundler,
179 | module: ModuleKind.ESNext,
180 | },
181 | },
182 | }),
183 | ],
184 | config(md) {
185 | md.use(deflist);
186 | md.use(footnote);
187 | md.use(groupIconMdPlugin);
188 | md.use(jsrRefPlugin);
189 | },
190 | },
191 |
192 | sitemap: {
193 | hostname: process.env.SITEMAP_HOSTNAME,
194 | },
195 |
196 | vite: {
197 | plugins: [
198 | groupIconVitePlugin(),
199 | llmstxt({
200 | ignoreFiles: [
201 | "changelog.md",
202 | ],
203 | }),
204 | ],
205 | },
206 |
207 | transformHead(context) {
208 | return [
209 | [
210 | "meta",
211 | { property: "og:title", content: context.title },
212 | ],
213 | [
214 | "meta",
215 | { property: "og:description", content: context.description },
216 | ],
217 | ];
218 | },
219 | });
220 |
221 | // cSpell: ignore deflist
222 |
--------------------------------------------------------------------------------
/docs/recipes.md:
--------------------------------------------------------------------------------
1 | ---
2 | description: >-
3 | The recipes section contains a list of recipes that demonstrate how to
4 | implement common tasks with BotKit.
5 | ---
6 |
7 | Recipes
8 | =======
9 |
10 | The recipes section contains a list of recipes that demonstrate how to implement
11 | common tasks with BotKit.
12 |
13 |
14 | Sending a direct message
15 | ------------------------
16 |
17 | It is very simple to send a direct message to a user: set
18 | the [`visibility`](./concepts/message.md#visibility) option to `"direct"`
19 | when calling the [`Session.publish()`](./concepts/message.md#publishing-a-message)
20 | method:
21 |
22 | ~~~~ typescript twoslash
23 | import { type Bot, text } from "@fedify/botkit";
24 | const bot = {} as unknown as Bot;
25 | // ---cut-before---
26 | bot.onMention = async (session, message) => {
27 | await session.publish(
28 | text`Hi, ${message.actor}!`,
29 | { visibility: "direct" },
30 | );
31 | };
32 | ~~~~
33 |
34 | > [!CAUTION]
35 | > You need to mention at least one actor in the message to send a direct
36 | > message. Otherwise, the message won't be read by anyone.
37 |
38 |
39 | Following back
40 | --------------
41 |
42 | To let your bot follow back all of its followers, you can use
43 | the [`onFollow`](./concepts/events.md#follow) event with
44 | the [`Session.follow()`](./concepts//session.md#following-an-actor) method
45 | together:
46 |
47 | ~~~~ typescript twoslash
48 | import type { Bot } from "@fedify/botkit";
49 | const bot = {} as unknown as Bot;
50 | // ---cut-before---
51 | bot.onFollow = async (session, followRequest) => {
52 | await followRequest.accept();
53 | await session.follow(followRequest.follower);
54 | };
55 | ~~~~
56 |
57 | > [!NOTE]
58 | > It is not guaranteed that the follow request will be accepted.
59 | > The actor may reject your bot's follow request.
60 |
61 |
62 | Automatically deleting old messages
63 | -----------------------------------
64 |
65 | To automatically delete old messages after a certain period, you can use
66 | [`Session.getOutbox()`](./concepts/message.md#getting-published-messages) method,
67 | [`AuthorizedMessage.delete()`](./concepts/message.md#deleting-a-message) method,
68 | and the [`setInterval()`] function together. The following example shows how to
69 | delete all messages older than a week:
70 |
71 | ~~~~ typescript twoslash
72 | import type { Bot, Session } from "@fedify/botkit";
73 | import { Temporal } from "@js-temporal/polyfill";
74 | const bot = {} as unknown as Bot;
75 | // ---cut-before---
76 | async function deleteOldPosts(session: Session): Promise {
77 | const now = Temporal.Now.instant();
78 | const oneWeekAgo = now.subtract({ hours: 7 * 24 });
79 | const oldPosts = session.getOutbox({ until: oneWeekAgo });
80 | for await (const post of oldPosts) {
81 | await post.delete();
82 | }
83 | }
84 |
85 | setInterval(
86 | deleteOldPosts,
87 | 1000 * 60 * 60,
88 | bot.getSession("https://yourdomain")
89 | );
90 | ~~~~
91 |
92 | [`setInterval()`]: https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval
93 |
94 |
95 | Scheduled messages
96 | ------------------
97 |
98 | You can use the [`setInterval()`] function to send messages at regular
99 | intervals:
100 |
101 | ~~~~ typescript twoslash
102 | import { type Bot, text } from "@fedify/botkit";
103 | const bot = {} as unknown as Bot;
104 | // ---cut-before---
105 | setInterval(async () => {
106 | const session = bot.getSession("https://yourdomain");
107 | await session.publish(text`Hello, world!`);
108 | }, 1000 * 60 * 60);
109 | ~~~~
110 |
111 | Or if you use Deno, you can use non-standard APIs like [`Deno.cron()`] to send
112 | messages at specific times:
113 |
114 | ~~~~ typescript twoslash
115 | import { type Bot, text } from "@fedify/botkit";
116 | const bot = {} as unknown as Bot;
117 | // ---cut-before---
118 | Deno.cron("scheduled messages", "0 0 12 * * *", async () => {
119 | const session = bot.getSession("https://yourdomain");
120 | await session.publish(text`Hello, world!`);
121 | });
122 | ~~~~
123 |
124 | [`Deno.cron()`]: https://docs.deno.com/api/deno/~/Deno.cron
125 |
126 |
127 | Automatically liking mentions
128 | -----------------------------
129 |
130 | It is simple to automatically like mentions of your bot. You can use the
131 | [`onMention`](./concepts/events.md#mention) event handler and
132 | the [`Message.like()`](./concepts/message.md#liking-a-message) method together:
133 |
134 | ~~~~ typescript twoslash
135 | import type { Bot } from "@fedify/botkit";
136 | const bot = {} as unknown as Bot;
137 | // ---cut-before---
138 | bot.onMention = async (session, message) => {
139 | await message.like();
140 | };
141 | ~~~~
142 |
143 |
144 | Automatically replying to mentions
145 | ----------------------------------
146 |
147 | It is simple to automatically reply to mentions of your bot. You can use the
148 | [`onMention`](./concepts/events.md#mention) event handler and
149 | the [`Message.reply()`](./concepts/message.md#replying-to-a-message) method
150 | together:
151 |
152 | ~~~~ typescript twoslash
153 | import { type Bot, text } from "@fedify/botkit";
154 | const bot = {} as unknown as Bot;
155 | // ---cut-before---
156 | bot.onMention = async (session, message) => {
157 | await message.reply(text`You mentioned me, ${message.actor}!`);
158 | };
159 | ~~~~
160 |
161 |
162 | Thread creation
163 | ---------------
164 |
165 | Although BotKit has no limitation on characters in a message, sometimes you may
166 | want to create a thread for storytelling or to make audience engagement easier.
167 | You can use the [`Message.reply()`](./concepts/message.md#replying-to-a-message)
168 | method to your own messages too:
169 |
170 | ~~~~ typescript twoslash
171 | import type { AuthorizedMessage, Bot, Note, Session, Text } from "@fedify/botkit";
172 | import { text } from "@fedify/botkit";
173 | const bot = {} as unknown as Bot;
174 | // ---cut-before---
175 | async function *createThread(
176 | session: Session,
177 | messages: Text<"block", TContextData>[]
178 | ): AsyncIterable> {
179 | let parent = await session.publish(messages[0]);
180 | yield parent;
181 | for (let i = 1; i < messages.length; i++) {
182 | parent = await parent.reply(messages[i]);
183 | yield parent;
184 | }
185 | }
186 |
187 | const messages = [
188 | text`Once upon a time, there was a bot named BotKit.`,
189 | text`BotKit was created by a developer who wanted to make a bot.`,
190 | text`The developer used BotKit to create a bot that could do anything.`,
191 | text`The bot was so powerful that it could even create other bots.`,
192 | text`And so, BotKit lived happily ever after.`,
193 | ];
194 | const session = bot.getSession("https://yourdomain", undefined);
195 | for await (const message of createThread(session, messages)) {
196 | console.debug(`Created message ${message.id}`);
197 | }
198 | ~~~~
199 |
200 |
201 | Thread traversal
202 | ----------------
203 |
204 | Suppose your bot is an LLM-based chatbot and you want to give your LLM model
205 | the previous messages in a thread as context. You can achieve this by
206 | recursively traversing
207 | the [`Message.replyTarget`](./concepts/message.md#traversing-the-conversation)
208 | property:
209 |
210 | ~~~~ typescript twoslash
211 | import type { Message, MessageClass, Session } from "@fedify/botkit";
212 | // ---cut-before---
213 | async function traverseThread(
214 | session: Session,
215 | message: Message
216 | ): Promise[]> {
217 | const thread: Message[] = [];
218 | let m: Message | undefined = message;
219 | while (m != null) {
220 | thread.push(m);
221 | m = m.replyTarget;
222 | }
223 | thread.reverse();
224 | return thread;
225 | }
226 | ~~~~
227 |
--------------------------------------------------------------------------------
/CHANGES.md:
--------------------------------------------------------------------------------
1 | BotKit changelog
2 | ================
3 |
4 | Version 0.4.0
5 | -------------
6 |
7 | To be released.
8 |
9 | ### @fedify/botkit
10 |
11 | - Added a remote follow button to the web interface.
12 | [[#10], [#14] by Hyeonseo Kim]
13 |
14 | - Added a Follow button on the bot's profile page that allows users to
15 | follow the bot from their own fediverse instance without manual
16 | searching.
17 | - When clicked, the button opens a modal dialog where users can enter
18 | their fediverse handle (e.g., `@username@instance.com`).
19 | - The feature uses WebFinger to discover the user's instance and
20 | automatically redirects to the appropriate follow page using the OStatus
21 | subscribe protocol.
22 |
23 | [#10]: https://github.com/fedify-dev/botkit/issues/10
24 | [#14]: https://github.com/fedify-dev/botkit/pull/14
25 |
26 |
27 | Version 0.3.0
28 | -------------
29 |
30 | Released on August 28, 2025.
31 |
32 | - BotKit now supports Node.js alongside of Deno. The minimum required
33 | version of Node.js is 22.0.0.
34 |
35 | ### @fedify/botkit
36 |
37 | - BotKit now supports publishing polls. [[#7], [#8]]
38 |
39 | - Added `Poll` interface.
40 | - Added `Vote` interface.
41 | - Added an overload of the `Session.publish()` method that accepts
42 | `SessionPublishOptionsWithQuestion` as the second argument.
43 | - Added `SessionPublishOptionsWithQuestion` interface.
44 | - Added `Bot.onVote` event.
45 | - Added `VoteEventHandler` type.
46 | - Added `KvStoreRepositoryPrefixes.polls` option.
47 |
48 | - Added `@fedify/botkit/repository` module that provides repository
49 | implementations for BotKit.
50 |
51 | - Added `RepositoryGetMessagesOptions` interface.
52 | - Added `RepositoryGetFollowersOptions` interface.
53 | - Added `Uuid` type.
54 | - Added `KvKey` type.
55 | - Added `KvStore` type.
56 | - Added `KvStoreRepositoryPrefixes` interface.
57 | - Added `Announce` class.
58 | - Added `Create` class.
59 | - Added `MemoryCachedRepository` class.
60 |
61 | - Added web frontend followers page. [[#2], [#13] by Hyeonseo Kim]
62 |
63 | - Added `/followers` route that displays a list of bot followers.
64 | - Made follower count on the main page clickable, linking to `/followers`.
65 |
66 | - Upgraded Fedify to 1.8.8.
67 |
68 | [#2]: https://github.com/fedify-dev/botkit/issues/2
69 | [#7]: https://github.com/fedify-dev/botkit/issues/7
70 | [#8]: https://github.com/fedify-dev/botkit/pull/8
71 | [#13]: https://github.com/fedify-dev/botkit/pull/13
72 |
73 | ### @fedify/botkit-sqlite
74 |
75 | - Added `SqliteRepository` class that implements a SQLite-based repository
76 | for BotKit.
77 | - Added `SqliteRepositoryOptions` interface.
78 |
79 |
80 | Version 0.2.4
81 | -------------
82 |
83 | Released on August 26, 2025.
84 |
85 | - Upgraded Fedifyh to 1.5.7 which fixes a bug where HTTP Signature
86 | verification failed for requests having `created` or `expires` fields
87 | in their `Signature` header, causing `500 Internal Server Error` responses
88 | in inbox handlers.
89 |
90 |
91 | Version 0.2.3
92 | -------------
93 |
94 | Released on August 25, 2025.
95 |
96 | - Upgraded Fedify to 1.5.6, which fixes a bug where ActivityPub Discovery
97 | failed to recognize XHTML self-closing `` tags. The HTML/XHTML parser
98 | now correctly handles whitespace before the self-closing slash (`/>`),
99 | improving compatibility with XHTML documents that follow the self-closing
100 | tag format.
101 |
102 |
103 | Version 0.2.2
104 | -------------
105 |
106 | Released on August 8, 2025.
107 |
108 | - Upgrade Fedify to 1.5.5, which includes a critical security
109 | fix [CVE-2025-54888] that addresses an authentication bypass
110 | vulnerability allowing actor impersonation. [[CVE-2025-54888]]
111 |
112 |
113 | Version 0.2.1
114 | -------------
115 |
116 | Released on July 8, 2025.
117 |
118 | - Fixed a bug where messages from `Session.getOutbox()` didn't have `update()`
119 | and `delete()` methods. [[#9]]
120 |
121 | [#9]: https://github.com/fedify-dev/botkit/issues/9
122 |
123 |
124 | Version 0.2.0
125 | -------------
126 |
127 | Released on April 21, 2025.
128 |
129 | - Image attachments in posts became shown in the web interface.
130 |
131 | - Added custom emoji support.
132 |
133 | - The return type of `Text.getTags()` method became
134 | `AsyncIterable` (was `AsyncIterable`).
135 | - Added `Bot.addCustomEmojis()` method.
136 | - Added `CustomEmojiText` class.
137 | - Added `customEmoji()` function.
138 | - Added `CustomEmojiBase` interface.
139 | - Added `CustomEmojiFromUrl` interface.
140 | - Added `CustomEmojiFromFile` interface.
141 | - Added `CustomEmoji` type.
142 | - Added `DeferredCustomEmoji` type.
143 | - The `text` tagged template literal function now accepts `Emoji` objects
144 | (provided by Fedify).
145 |
146 | - Added emoji reaction support.
147 |
148 | - Added `Emoji` type.
149 | - Added `isEmoji()` predicate function.
150 | - Added `emoji()` tagged template literal function.
151 | - Added `Message.react()` method.
152 | - Added `Reaction` interface.
153 | - Added `AuthorizedReaction` interface.
154 | - Added `Bot.onReact` event.
155 | - Added `Bot.onUnreact` event.
156 | - Added `ReactionEventHandler` type.
157 | - Added `UndoneReactionEventHandler` type.
158 |
159 | - Added quote support.
160 |
161 | - Added `SessionPublishOptions.quoteTarget` option.
162 | - Added `Message.quoteTarget` property.
163 | - Added `Bot.onQuote` event.
164 | - Added `QuoteEventHandler` type.
165 |
166 | - Added `SessionGetOutboxOptions` interface.
167 |
168 | - Activities are more precisely propagated.
169 |
170 | - The `Message.reply()` method now sends the `Create` activity to
171 | the author of the original message as well.
172 | - The `Message.share()` method now sends the `Announce` activity to
173 | the author of the original message as well.
174 | - The `AuthorizedSharedMessage.unshare()` method now sends the `Undo`
175 | activity to the author of the original message as well.
176 | - The `AuthorizedMessage.update()` method now sends the `Update` activity
177 | to the author of the original message as well if it is a reply.
178 | - The `AuthorizedMessage.delete()` method now sends the `Delete` activity
179 | to the author of the original message as well if it is a reply.
180 |
181 |
182 | Version 0.1.4
183 | -------------
184 |
185 | Released on August 26, 2025.
186 |
187 | - Upgraded Fedifyh to 1.4.15 which fixes a bug where HTTP Signature
188 | verification failed for requests having `created` or `expires` fields
189 | in their `Signature` header, causing `500 Internal Server Error` responses
190 | in inbox handlers.
191 |
192 |
193 | Version 0.1.3
194 | -------------
195 |
196 | Released on August 25, 2025.
197 |
198 | - Upgraded Fedify to 1.4.14, which fixes a bug where ActivityPub Discovery
199 | failed to recognize XHTML self-closing `` tags. The HTML/XHTML parser
200 | now correctly handles whitespace before the self-closing slash (`/>`),
201 | improving compatibility with XHTML documents that follow the self-closing
202 | tag format.
203 |
204 |
205 | Version 0.1.2
206 | -------------
207 |
208 | Released on August 8, 2025.
209 |
210 | - Upgraded Fedify to 1.4.13, which includes a critical security
211 | fix [CVE-2025-54888] that addresses an authentication bypass
212 | vulnerability allowing actor impersonation. [[CVE-2025-54888]]
213 |
214 | [CVE-2025-54888]: https://github.com/fedify-dev/fedify/security/advisories/GHSA-6jcc-xgcr-q3h4
215 |
216 |
217 | Version 0.1.1
218 | -------------
219 |
220 | Released on February 10, 2025.
221 |
222 | - Fixed a bug where direct and followers-only messages that reply to a bot
223 | had been forwarded to the bot's followers.
224 |
225 |
226 | Version 0.1.0
227 | -------------
228 |
229 | Initial release. Released on February 7, 2025.
230 |
--------------------------------------------------------------------------------
/docs/concepts/session.md:
--------------------------------------------------------------------------------
1 | ---
2 | description: >-
3 | The Session object is a short-lived object that actively communicates with
4 | the fediverse. Learn how to create a session and publish messages to the
5 | fediverse.
6 | ---
7 |
8 | Session
9 | =======
10 |
11 | The `Session` object is a short-lived object that actively communicates with
12 | the fediverse. It can be [created by yourself](#creating-a-session),
13 | or you can get it when an event handler is called.
14 |
15 |
16 | Creating a session
17 | ------------------
18 |
19 | You can create a session by calling the `Bot.getSession()` method:
20 |
21 | ~~~~ typescript twoslash
22 | import type { Bot } from "@fedify/botkit";
23 | const bot = {} as unknown as Bot;
24 | // ---cut-before---
25 | const session = bot.getSession("https://mydomain");
26 | ~~~~
27 |
28 | It takes a single argument, the origin of the server to which your bot belongs.
29 | In practice, you would have an environment variable that contains the hostname
30 | of your server, and you would pass it to the `~Bot.getSession()` method:
31 |
32 | ::: code-group
33 |
34 | ~~~~ typescript [Deno] twoslash
35 | import type { Bot } from "@fedify/botkit";
36 | const bot = {} as unknown as Bot;
37 | // ---cut-before---
38 | const SERVER_NAME = Deno.env.get("SERVER_NAME");
39 | if (SERVER_NAME == null) {
40 | console.error("The SERVER_NAME environment variable is not set.");
41 | Deno.exit(1);
42 | }
43 |
44 | const session = bot.getSession(`https://${SERVER_NAME}`); // [!code highlight]
45 | ~~~~
46 |
47 | ~~~~ typescript [Node.js] twoslash
48 | import type { Bot } from "@fedify/botkit";
49 | const bot = {} as unknown as Bot;
50 | // ---cut-before---
51 | const SERVER_NAME = process.env.SERVER_NAME;
52 | if (SERVER_NAME == null) {
53 | console.error("The SERVER_NAME environment variable is not set.");
54 | Deno.exit(1);
55 | }
56 |
57 | const session = bot.getSession(`https://${SERVER_NAME}`); // [!code highlight]
58 | ~~~~
59 |
60 | :::
61 |
62 |
63 | Getting a session from an event handler
64 | ---------------------------------------
65 |
66 | When an event handler is called, you can get a session from the `Session`
67 | object that is passed as the first argument:
68 |
69 | ~~~~ typescript twoslash
70 | import type { Bot } from "@fedify/botkit";
71 | const bot = {} as unknown as Bot;
72 | // ---cut-before---
73 | bot.onMention = async (session, message) => {
74 | // `session` is a `Session` object
75 | };
76 | ~~~~
77 |
78 | To learn more about event handlers, see the [*Events* section](./events.md).
79 |
80 |
81 | Determining the actor URI of the bot
82 | ------------------------------------
83 |
84 | The `Session` object has an `actorId` property that contains the URI of the bot
85 | actor. You can use this URI to refer to the bot in messages:
86 |
87 | ~~~~ typescript twoslash
88 | import { type Bot, text } from "@fedify/botkit";
89 | const bot = {} as unknown as Bot;
90 | // ---cut-before---
91 | bot.onFollow = async (session, actor) => {
92 | await session.publish(
93 | text`Hi, ${actor}! I'm ${session.actorId}. Thanks for following me!`
94 | );
95 | };
96 | ~~~~
97 |
98 |
99 | Determining the fediverse handle of the bot
100 | -------------------------------------------
101 |
102 | The `Session` object has an `actorHandle` property that contains the fediverse
103 | handle of the bot. It looks like an email address except that it starts with
104 | an `@` symbol: `@myBot@myDomain`. You can use this handle to refer to the bot
105 | in messages:
106 |
107 | ~~~~ typescript twoslash
108 | import type { Bot } from "@fedify/botkit";
109 | import { markdown } from "@fedify/botkit/text";
110 | const bot = {} as unknown as Bot;
111 | // ---cut-before---
112 | bot.onFollow = async (session, actor) => {
113 | await session.publish(
114 | markdown(`I'm ${session.actorHandle}. Thanks for following me!`)
115 | );
116 | };
117 | ~~~~
118 |
119 |
120 | Getting the bot's `Actor` object
121 | --------------------------------
122 |
123 | The `Session` object has a `~Session.getActor()` method that returns the `Actor`
124 | object of the bot:
125 |
126 | ~~~~ typescript twoslash
127 | import type { Actor, Session } from "@fedify/botkit";
128 | const session = {} as unknown as Session;
129 | // ---cut-before---
130 | const actor: Actor = await session.getActor();
131 | ~~~~
132 |
133 |
134 | Publishing a message
135 | --------------------
136 |
137 | See the [*Publishing a message* section](./message.md#publishing-a-message)
138 | in the *Message* concept document.
139 |
140 |
141 | Getting published messages
142 | ----------------------
143 |
144 | See the [*Getting published messages*
145 | section](./message.md#getting-published-messages) in the *Message* concept
146 | document.
147 |
148 |
149 | Following an actor
150 | ------------------
151 |
152 | Your bot can follow an actor by calling the `Session.follow()` method.
153 | The following example shows how to get the `bot` follow back all of its
154 | followers:
155 |
156 | ~~~~ typescript twoslash
157 | import type { Bot } from "@fedify/botkit";
158 | const bot = {} as unknown as Bot;
159 | // ---cut-before---
160 | bot.onFollow = async (session, followRequest) => {
161 | await followRequest.accept();
162 | await session.follow(followRequest.follower);
163 | };
164 | ~~~~
165 |
166 | > [!CAUTION]
167 | > The `~Session.follow()` method just sends a follow request to the actor,
168 | > but it does not guarantee that the actor will accept the follow request.
169 | > The actor may reject the follow request, and your bot will not be able to
170 | > follow the actor.
171 | >
172 | > If you want to know whether the actor has accepted or rejected the follow
173 | > request, you need to register
174 | > the [`Bot.onAcceptFollow`](./events.md#accept-follow) and
175 | > [`Bot.onRejectFollow`](./events.md#reject-follow) event handlers.
176 |
177 | > [!TIP]
178 | > It takes several kinds of objects as an argument, such as `Actor`, `string`,
179 | > and `URL`:
180 | >
181 | > `Actor`
182 | > : The actor to follow.
183 | >
184 | > `URL`
185 | > : The URI of the actor to follow.
186 | > E.g., `new URL("https://example.com/users/alice")`.
187 | >
188 | > `string`
189 | > : The URI or the fediverse handle of the actor to follow.
190 | > E.g., `"https://example.com/users/alice"` or `"@alice@example.com"`.
191 |
192 | > [!NOTE]
193 | > If you try to follow an actor that is already followed, the method will just
194 | > do nothing.
195 |
196 |
197 | Unfollowing an actor
198 | --------------------
199 |
200 | Likewise, your bot can unfollow an actor by calling the `Session.unfollow()`
201 | method. The following example shows how to make the `bot` unfollow if any of
202 | its followers unfollow it:
203 |
204 | ~~~~ typescript twoslash
205 | import type { Bot } from "@fedify/botkit";
206 | const bot = {} as unknown as Bot;
207 | // ---cut-before---
208 | bot.onUnfollow = async (session, actor) => {
209 | await session.unfollow(actor);
210 | };
211 | ~~~~
212 |
213 | > [!TIP]
214 | > Like the `~Session.follow()` method, the `~Session.unfollow()` method takes
215 | > several kinds of objects as an argument, such as `Actor`, `string`, and `URL`.
216 |
217 | > [!NOTE]
218 | > If you try to unfollow an actor that is not followed, the method will just
219 | > do nothing.
220 |
221 |
222 | Checking if the bot follows an actor
223 | ------------------------------------
224 |
225 | The `Session` object has a `~Session.follows()` method that returns a boolean
226 | value indicating whether your bot follows a given actor. The following example
227 | shows how to check if your bot follows an actor and respond accordingly:
228 |
229 | ~~~~ typescript twoslash
230 | import { type Bot, text } from "@fedify/botkit";
231 | const bot = {} as unknown as Bot;
232 | // ---cut-before---
233 | bot.onMention = async (session, message) => {
234 | const follows = await session.follows(message.actor);
235 | await session.publish(
236 | follows
237 | ? text`Hi ${message.actor}, I'm already following you!`
238 | : text`Hi ${message.actor}, I don't follow you yet.`
239 | );
240 | };
241 | ~~~~
242 |
243 | > [!TIP]
244 | > Like other methods, `~Session.follows()` accepts several types of arguments
245 | > such as `Actor`, `string`, and `URL`.
246 |
247 | > [!NOTE]
248 | > This method returns `false` if the given actor doesn't exist or is
249 | > inaccessible.
250 |
--------------------------------------------------------------------------------
/packages/botkit/src/session.ts:
--------------------------------------------------------------------------------
1 | // BotKit by Fedify: A framework for creating ActivityPub bots
2 | // Copyright (C) 2025 Hong Minhee
3 | //
4 | // This program is free software: you can redistribute it and/or modify
5 | // it under the terms of the GNU Affero General Public License as
6 | // published by the Free Software Foundation, either version 3 of the
7 | // License, or (at your option) any later version.
8 | //
9 | // This program is distributed in the hope that it will be useful,
10 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | // GNU Affero General Public License for more details.
13 | //
14 | // You should have received a copy of the GNU Affero General Public License
15 | // along with this program. If not, see .
16 | import type {
17 | Actor,
18 | Article,
19 | ChatMessage,
20 | Context,
21 | Document,
22 | Note,
23 | Question,
24 | } from "@fedify/fedify";
25 | import type { LanguageTag } from "@phensley/language-tag";
26 | import type { Bot } from "./bot.ts";
27 | import type {
28 | AuthorizedMessage,
29 | Message,
30 | MessageClass,
31 | MessageVisibility,
32 | } from "./message.ts";
33 | import type { Poll } from "./poll.ts";
34 | import type { Text } from "./text.ts";
35 |
36 | /**
37 | * A session to control the bot.
38 | */
39 | export interface Session {
40 | /**
41 | * The bot to which the session belongs.
42 | */
43 | readonly bot: Bot;
44 |
45 | /**
46 | * The Fedify context of the session.
47 | */
48 | readonly context: Context;
49 |
50 | /**
51 | * The URI of the bot actor.
52 | */
53 | readonly actorId: URL;
54 |
55 | /**
56 | * The fediverse handle of the bot actor. It starts with `@`.
57 | */
58 | readonly actorHandle: `@${string}@${string}`;
59 |
60 | /**
61 | * Gets the `Actor` object of the bot.
62 | * @returns The `Actor` object of the bot.
63 | */
64 | getActor(): Promise;
65 |
66 | /**
67 | * Send a follow request to the specified actor.
68 | *
69 | * Note that it does not guarantee that the follow request will be accepted.
70 | * You might need to handle {@link Bot.onAcceptFollow} and
71 | * {@link Bot.onRejectFollow} events to know the result.
72 | *
73 | * If the bot is already following the actor, it does nothing.
74 | * @param actor The actor to follow. It can be an `Actor` object, or a `URL`
75 | * of the actor, or a URI string or a fediverse handle of the
76 | * actor.
77 | * @throws {TypeError} If the actor URL is invalid or the resolved object
78 | * is not an `Actor` or the actor is the bot itself.
79 | */
80 | follow(actor: Actor | URL | string): Promise;
81 |
82 | /**
83 | * Unfollow the specified actor.
84 | *
85 | * Unlike {@link Session.follow}, it immediately unfollows the actor without
86 | * any confirmation.
87 | *
88 | * If the bot is not following the actor, it does nothing.
89 | * @param actor The actor to unfollow. It can be an `Actor` object,
90 | * or a `URL` of the actor, or a URI string or a fediverse handle
91 | * of the actor.
92 | * @throws {TypeError} If the actor URL is invalid or the resolved object
93 | * is not an `Actor` or the actor is the bot itself.
94 | */
95 | unfollow(actor: Actor | URL | string): Promise;
96 |
97 | /**
98 | * Checks whether the bot is following the specified actor.
99 | * @param actor The actor to check whether the bot is following. It can be
100 | * an `Actor` object, or a `URL` of the actor, or a URI string
101 | * or a fediverse handle of the actor.
102 | * @returns `true` if the bot is following the actor, otherwise `false`.
103 | * @throws {TypeError} If the actor URL is invalid or the resolved object
104 | * is not an `Actor`.
105 | */
106 | follows(actor: Actor | URL | string): Promise;
107 |
108 | /**
109 | * Publishes a message attributed to the bot.
110 | * @param text The content of the note.
111 | * @param options The options for publishing the message.
112 | * @returns The published message.
113 | */
114 | publish(
115 | content: Text<"block", TContextData>,
116 | options?: SessionPublishOptions,
117 | ): Promise>;
118 |
119 | /**
120 | * Publishes a message attributed to the bot.
121 | * @typeParam T The class of the published message.
122 | * @param text The content of the note.
123 | * @param options The options for publishing the message.
124 | * @returns The published message.
125 | */
126 | publish(
127 | content: Text<"block", TContextData>,
128 | options: SessionPublishOptionsWithClass,
129 | ): Promise>;
130 |
131 | /**
132 | * Publishes a question attributed to the bot with a poll.
133 | * @param content The content of the question.
134 | * @param options The options for publishing the question.
135 | * @returns The published question.
136 | * @since 0.3.0
137 | */
138 | publish(
139 | content: Text<"block", TContextData>,
140 | options: SessionPublishOptionsWithQuestion,
141 | ): Promise>;
142 |
143 | /**
144 | * Gets messages from the bot's outbox.
145 | * @param options The options for getting messages.
146 | * @returns An async iterable of messages.
147 | */
148 | getOutbox(
149 | options?: SessionGetOutboxOptions,
150 | ): AsyncIterable>;
151 | }
152 |
153 | /**
154 | * Options for publishing a message.
155 | * @typeParam TContextData The type of the context data.
156 | */
157 | export interface SessionPublishOptions {
158 | /**
159 | * The language of the published message.
160 | */
161 | readonly language?: string | LanguageTag;
162 |
163 | /**
164 | * The visibility of the published message. If omitted, `"public"` will be
165 | * used.
166 | */
167 | readonly visibility?: Exclude;
168 |
169 | /**
170 | * The media attachments of the published message.
171 | */
172 | readonly attachments?: Document[];
173 |
174 | /**
175 | * The message to quote in the published message.
176 | * @since 0.2.0
177 | */
178 | readonly quoteTarget?: Message;
179 | }
180 |
181 | /**
182 | * Options for publishing a message with a specific class.
183 | * @typeParam T The class of the published message.
184 | * @typeParam TContextData The type of the context data.
185 | */
186 | export interface SessionPublishOptionsWithClass<
187 | T extends MessageClass,
188 | TContextData,
189 | > extends SessionPublishOptions {
190 | /**
191 | * The class of the published message. If omitted, `Note` will be used.
192 | */
193 | readonly class: T extends Article ? typeof Article
194 | : T extends ChatMessage ? typeof ChatMessage
195 | : T extends Note ? typeof Note
196 | : T extends Question ? typeof Question
197 | : never;
198 | }
199 |
200 | /**
201 | * Options for publishing a question with a poll.
202 | * @typeParam TContextData The type of the context data.
203 | * @since 0.3.0
204 | */
205 | export interface SessionPublishOptionsWithQuestion
206 | extends SessionPublishOptionsWithClass {
207 | /**
208 | * The poll to attach to the question.
209 | * @since 0.3.0
210 | */
211 | readonly poll: Poll;
212 | }
213 |
214 | /**
215 | * Options for getting messages from the bot's outbox.
216 | */
217 | export interface SessionGetOutboxOptions {
218 | /**
219 | * The order of the messages. If omitted, `"newest"` will be used.
220 | * @default `"newest"`
221 | */
222 | readonly order?: "oldest" | "newest";
223 |
224 | /**
225 | * The timestamp to get messages created at or before this time.
226 | * If omitted, no limit will be applied.
227 | */
228 | readonly until?: Temporal.Instant;
229 |
230 | /**
231 | * The timestamp to get messages created at or after this time.
232 | * If omitted, no limit will be applied.
233 | */
234 | readonly since?: Temporal.Instant;
235 |
236 | /**
237 | * The maximum number of messages to get. If omitted, no limit will be
238 | * applied.
239 | */
240 | readonly limit?: number;
241 | }
242 |
--------------------------------------------------------------------------------
/packages/botkit/src/message.ts:
--------------------------------------------------------------------------------
1 | // BotKit by Fedify: A framework for creating ActivityPub bots
2 | // Copyright (C) 2025 Hong Minhee
3 | //
4 | // This program is free software: you can redistribute it and/or modify
5 | // it under the terms of the GNU Affero General Public License as
6 | // published by the Free Software Foundation, either version 3 of the
7 | // License, or (at your option) any later version.
8 | //
9 | // This program is distributed in the hope that it will be useful,
10 | // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 | // GNU Affero General Public License for more details.
13 | //
14 | // You should have received a copy of the GNU Affero General Public License
15 | // along with this program. If not, see .
16 | import type {
17 | Actor,
18 | Announce,
19 | Article,
20 | ChatMessage,
21 | Document,
22 | Emoji as CustomEmoji,
23 | Hashtag,
24 | Note,
25 | Question,
26 | } from "@fedify/fedify/vocab";
27 | import type { LanguageTag } from "@phensley/language-tag";
28 | import type { DeferredCustomEmoji, Emoji } from "./emoji.ts";
29 | import type { AuthorizedLike, AuthorizedReaction } from "./reaction.ts";
30 | import type {
31 | SessionPublishOptions,
32 | SessionPublishOptionsWithClass,
33 | } from "./session.ts";
34 | import type { Text } from "./text.ts";
35 | export {
36 | Article,
37 | Audio,
38 | ChatMessage,
39 | Document,
40 | Hashtag,
41 | Image,
42 | isActor,
43 | Note,
44 | Question,
45 | Video,
46 | } from "@fedify/fedify/vocab";
47 | export type { Actor } from "@fedify/fedify/vocab";
48 | export { LanguageTag, parseLanguageTag } from "@phensley/language-tag";
49 |
50 | /**
51 | * A possible message class.
52 | */
53 | export type MessageClass = Article | ChatMessage | Note | Question;
54 |
55 | /**
56 | * The visibility of a message.
57 | */
58 | export type MessageVisibility =
59 | /**
60 | * Signifies that the message is public; it can be seen and discovered by
61 | * anyone.
62 | */
63 | | "public"
64 | /**
65 | * Signifies that the message is quietly public; it can be seen by anyone,
66 | * but it will not appear in public timelines or search results.
67 | */
68 | | "unlisted"
69 | /**
70 | * Signifies that the message is only visible to followers of the account.
71 | * It will not appear in public timelines or search results.
72 | */
73 | | "followers"
74 | /**
75 | * Signifies that the message is private; it can only be seen by mentioned
76 | * accounts.
77 | */
78 | | "direct"
79 | /**
80 | * Signifies that the message is unknown; it is not clear who can see it.
81 | * It is usually the case when the message is published by a minor fediverse
82 | * server that is incompatible with Mastodon-style visibility.
83 | */
84 | | "unknown";
85 |
86 | /**
87 | * A message in the ActivityPub network. It is a thin wrapper around
88 | * a Fedify object: an `Article`, a `ChatMessage`, a `Note`, or a `Question`.
89 | * @typeParam T The class of the message. One of `Article`, `ChatMessage`,
90 | * `Note`, or `Question`.
91 | * @typeParam TContextData The type of the context data.
92 | */
93 | export interface Message {
94 | /**
95 | * The underlying raw message object.
96 | */
97 | readonly raw: T;
98 |
99 | /**
100 | * The URI of the message.
101 | */
102 | readonly id: URL;
103 |
104 | /**
105 | * The actor who published the message.
106 | */
107 | readonly actor: Actor;
108 |
109 | /**
110 | * The visibility of the message.
111 | */
112 | readonly visibility: MessageVisibility;
113 |
114 | /**
115 | * The language of the message if the content is tagged with a language.
116 | */
117 | readonly language?: LanguageTag;
118 |
119 | /**
120 | * The plain text content of the message.
121 | */
122 | readonly text: string;
123 |
124 | /**
125 | * The HTML content of the message.
126 | */
127 | readonly html: string;
128 |
129 | /**
130 | * The original message in reply to, if the message is a reply.
131 | */
132 | readonly replyTarget?: Message;
133 |
134 | /**
135 | * The actors mentioned in the message.
136 | */
137 | readonly mentions: readonly Actor[];
138 |
139 | /**
140 | * The hashtags used in the message.
141 | */
142 | readonly hashtags: readonly Hashtag[];
143 |
144 | /**
145 | * The media attachments of the message.
146 | */
147 | readonly attachments: readonly Document[];
148 |
149 | /**
150 | * The message quoted by this message, if any.
151 | * @since 0.2.0
152 | */
153 | readonly quoteTarget?: Message;
154 |
155 | /**
156 | * The published time of the message.
157 | */
158 | readonly published?: Temporal.Instant;
159 |
160 | /**
161 | * The updated time of the message, if it is updated.
162 | */
163 | readonly updated?: Temporal.Instant;
164 |
165 | /**
166 | * Publishes a reply to the message.
167 | * @param text The content of the message.
168 | * @param options The options for publishing the message.
169 | * @returns The published message.
170 | */
171 | reply(
172 | text: Text<"block", TContextData>,
173 | options?: SessionPublishOptions,
174 | ): Promise>;
175 |
176 | /**
177 | * Publishes a reply to the message.
178 | * @typeParam T The class of the published message.
179 | * @param text The content of the message.
180 | * @param options The options for publishing the message.
181 | * @returns The published message.
182 | */
183 | reply(
184 | text: Text<"block", TContextData>,
185 | options?: SessionPublishOptionsWithClass,
186 | ): Promise>;
187 |
188 | /**
189 | * Shares the message.
190 | *
191 | * It throws an error if the visibility of the message is neither `"public"`
192 | * nor `"unlisted"`.
193 | * @param options The options for sharing the message.
194 | * @returns The shared message.
195 | * @throws {TypeError} If the visibility of the message is not `"public"` or
196 | * `"unlisted"`.
197 | */
198 | share(
199 | options?: MessageShareOptions,
200 | ): Promise>;
201 |
202 | /**
203 | * Likes the message.
204 | * @returns The like object.
205 | */
206 | like(): Promise>;
207 |
208 | /**
209 | * Reacts to the message with a Unicode emoji or a custom emoji.
210 | * @param emoji The emoji to react with. It can be either a Unicode emoji or
211 | * a custom emoji.
212 | * @returns The reaction object.
213 | * @since 0.2.0
214 | */
215 | react(
216 | emoji: Emoji | CustomEmoji | DeferredCustomEmoji,
217 | ): Promise>;
218 | }
219 |
220 | /**
221 | * An authorized message in the ActivityPub network. Usually it is a message
222 | * published by the bot itself.
223 | * @typeParam T The class of the message. One of `Article`, `ChatMessage`,
224 | * `Note`, or `Question`.
225 | * @typeParam TContextData The type of the context data.
226 | */
227 | export interface AuthorizedMessage
228 | extends Message {
229 | /**
230 | * Updates the message with new content.
231 | * @param text The new content of the message.
232 | */
233 | update(text: Text<"block", TContextData>): Promise;
234 |
235 | /**
236 | * Deletes the message, if possible.
237 | *
238 | * If the message is already deleted, it will be a no-op.
239 | */
240 | delete(): Promise;
241 | }
242 |
243 | /**
244 | * Options for sharing a message.
245 | */
246 | export interface MessageShareOptions {
247 | /**
248 | * The visibility of the shared message. If omitted, the visibility of the
249 | * original message will be used.
250 | */
251 | readonly visibility?: Exclude;
252 | }
253 |
254 | /**
255 | * A shared message in the ActivityPub network. It is a thin wrapper around
256 | * an `Announce`, which is a Fedify object.
257 | * @typeParam T The class of the message. One of `Article`, `ChatMessage`,
258 | * `Note`, or `Question`.
259 | * @typeParam TContextData The type of the context data.
260 | */
261 | export interface SharedMessage {
262 | /**
263 | * The underlying raw shared message object.
264 | */
265 | readonly raw: Announce;
266 |
267 | /**
268 | * The URI of the shared message.
269 | */
270 | readonly id: URL;
271 |
272 | /**
273 | * The actor who shared the message.
274 | */
275 | readonly actor: Actor;
276 |
277 | /**
278 | * The visibility of the shared message.
279 | */
280 | readonly visibility: MessageVisibility;
281 |
282 | /**
283 | * The original message.
284 | */
285 | readonly original: Message;
286 | }
287 |
288 | /**
289 | * An authorized shared message in the ActivityPub network. Usually it is a
290 | * message shared by the bot itself.
291 | * @typeParam T The class of the message. One of `Article`, `ChatMessage`,
292 | * `Note`, or `Question`.
293 | * @typeParam TContextData The type of the context data.
294 | */
295 | export interface AuthorizedSharedMessage
296 | extends SharedMessage {
297 | /**
298 | * Undoes the shared message.
299 | *
300 | * If the shared message is already undone, it silently fails.
301 | */
302 | unshare(): Promise;
303 | }
304 |
--------------------------------------------------------------------------------
/docs/start.md:
--------------------------------------------------------------------------------
1 | ---
2 | description: >-
3 | Learn how to install BotKit and create an ActivityPub bot with it.
4 | ---
5 |
6 | Getting started
7 | ===============
8 |
9 |
10 | Installing BotKit
11 | -----------------
12 |
13 | BotKit is available for both Node.js and Deno. You can install BotKit
14 | depending on your environment.
15 |
16 | ### Deno
17 |
18 | You need to create a new project for your bot and install BotKit as
19 | a dependency:
20 |
21 | ~~~~ bash
22 | deno add jsr:@fedify/botkit
23 | ~~~~
24 |
25 | Since BotKit uses the [Temporal] API which is still unstable in Deno, you need
26 | to turn it on in your *deno.json* settings:
27 |
28 | ~~~~ json [deno.json] {5}
29 | {
30 | "imports": {
31 | "@fedify/botkit": "jsr:@fedify/botkit@0.3.0"
32 | },
33 | "unstable": ["temporal"]
34 | }
35 | ~~~~
36 |
37 | [Temporal]: https://tc39.es/proposal-temporal/docs/
38 |
39 | ### Node.js
40 |
41 | You can install BotKit from npm:
42 |
43 | ::: code-group
44 |
45 | ~~~~ bash [npm]
46 | npm add @fedify/botkit
47 | ~~~~
48 |
49 | ~~~~ bash [pnpm]
50 | pnpm add @fedify/botkit
51 | ~~~~
52 |
53 | ~~~~ bash [Yarn]
54 | yarn add @fedify/botkit
55 | ~~~~
56 |
57 | :::
58 |
59 |
60 | Creating a bot
61 | --------------
62 |
63 | To create a bot, you need to create a new TypeScript file and define your
64 | [`Bot`](./concepts/bot.md) instance using
65 | the [`createBot()`](./concepts/bot.md#instantiation) function:
66 |
67 | ~~~~ typescript [bot.ts] {8-14} twoslash
68 | import {
69 | createBot,
70 | InProcessMessageQueue,
71 | MemoryKvStore,
72 | text,
73 | } from "@fedify/botkit";
74 |
75 | const bot = createBot({
76 | username: "mybot",
77 | name: "My Bot",
78 | summary: text`A bot powered by BotKit.`,
79 | kv: new MemoryKvStore(),
80 | queue: new InProcessMessageQueue(),
81 | });
82 | ~~~~
83 |
84 | In the above code snippet, we created a new bot instance named `bot` with
85 | the [`username`](./concepts/bot.md#createbotoptions-username) `mybot`—the first
86 | part of the fediverse handle. The bot will be addressed as `@mybot@your-domain`
87 | in the fediverse.
88 |
89 | The [`name`](./concepts/bot.md#createbotoptions-name) and
90 | [`summary`](./concepts/bot.md#createbotoptions-summary) are the display name and
91 | the bio of the bot, respectively. Note that the `summary` is not a string, but
92 | a `Text` object that can be used to format rich text. For more information on
93 | `Text`, see the [*Text* chapter](./concepts/text.md).
94 |
95 | The [`kv`](./concepts/bot.md#createbotoptions-kv) is the underlying key–value
96 | store that BotKit uses to store data. In the above code snippet, we used the
97 | [`MemoryKvStore`] class, which stores data in memory for development purposes.
98 |
99 | The [`queue`](./concepts/bot.md#createbotoptions-queue) is the message queue
100 | that BotKit uses to deal with background tasks. In the above code snippet,
101 | we used the [`InProcessMessageQueue`] class, which processes messages in the
102 | same process for development purposes.
103 |
104 | > [!CAUTION]
105 | > Although [`MemoryKvStore`] and [`InProcessMessageQueue`] are useful for
106 | > development, they must not be used in production. You should use a persistent
107 | > key–value store and a message queue service in production. For more drivers
108 | > available, see the Fedify's related docs:
109 | >
110 | > - [*Key–value store*]
111 | > - [*Message queue*]
112 |
113 | [`MemoryKvStore`]: https://fedify.dev/manual/kv#memorykvstore
114 | [`InProcessMessageQueue`]: https://fedify.dev/manual/mq#inprocessmessagequeue
115 | [*Key–value store*]: https://fedify.dev/manual/kv
116 | [*Message queue*]: https://fedify.dev/manual/mq
117 |
118 |
119 | Handling events
120 | ---------------
121 |
122 | BotKit supports various [events](./concepts/events.md) such as
123 | [`onFollow`](./concepts/events.md#follow) and
124 | [`onMention`](./concepts/events.md#mention). You can handle these events by
125 | setting the corresponding event handlers on the `Bot` instance.
126 |
127 | Here, we will let the bot [publish](./concepts/message.md#publishing-a-message)
128 | a direct message when someone [follows](./concepts/events.md#follow) the bot:
129 |
130 | ~~~~ typescript [bot.ts] twoslash
131 | import type { Bot, Session } from "@fedify/botkit";
132 | import { text } from "@fedify/botkit";
133 | const bot = {} as unknown as Bot;
134 | const session = {} as unknown as Session;
135 | // ---cut-before---
136 | bot.onFollow = async (session, follower) => {
137 | await session.publish(text`Thanks for following me, ${follower}!`, {
138 | visibility: "direct",
139 | });
140 | };
141 | ~~~~
142 |
143 |
144 | Running the bot
145 | ---------------
146 |
147 | To run the bot, you need to first connect the bot to the HTTP server. There
148 | are different ways to run the bot depending on the environment you are
149 | using. Here, we will show you how to run the bot in Deno and Node.js.
150 |
151 | ### Deno
152 |
153 | We will utilize [`deno serve`] command. In order to connect the bot to Deno's
154 | HTTP server, you need to `export` the `bot` instance as a default export in
155 | the *bot.ts* file:
156 |
157 | ~~~~ typescript [bot.ts] twoslash
158 | import type { Bot } from "@fedify/botkit";
159 | const bot = {} as unknown as Bot;
160 | // ---cut-before---
161 | export default bot;
162 | ~~~~
163 |
164 | Then, you can run the bot using the following command:
165 |
166 | ~~~~ bash
167 | deno serve -A ./bot.ts
168 | ~~~~
169 |
170 | Then, it will show the following message:
171 |
172 | ~~~~
173 | deno serve: Listening on http://0.0.0.0:8000/
174 | ~~~~
175 |
176 | And your bot will be available at .
177 |
178 | [`deno serve`]: https://docs.deno.com/runtime/reference/cli/serve/
179 |
180 | ### Node.js
181 |
182 | In Node.js, we will use the [srvx] package to run the bot. First, you need to
183 | install the *srvx* package:
184 |
185 | ::: code-group
186 |
187 | ~~~~ bash [npm]
188 | npm add srvx
189 | ~~~~
190 |
191 | ~~~~ bash [pnpm]
192 | pnpm add srvx
193 | ~~~~
194 |
195 | ~~~~ bash [Yarn]
196 | yarn add srvx
197 | ~~~~
198 |
199 | :::
200 |
201 | Then, import [`serve()`] function from `srvx` module:
202 |
203 | ~~~~ typescript [bot.ts] twoslash
204 | import { serve } from "srvx";
205 | ~~~~
206 |
207 | Finally, you can run the bot using the [`serve()`] function at the end of
208 | the *bot.ts* file:
209 |
210 | ~~~~ typescript [bot.ts] twoslash
211 | import type { Bot } from "@fedify/botkit";
212 | import { serve } from "srvx";
213 | const bot = {} as unknown as Bot;
214 | // ---cut-before---
215 | const server = serve({
216 | ...bot,
217 | port: 8000,
218 | });
219 | await server.ready();
220 | console.log(`Bot is running at ${server.url}`);
221 | ~~~~
222 |
223 | Then, you can run the bot using the following command:
224 |
225 | ~~~~ bash
226 | node --experimental-transform-types ./bot.ts
227 | ~~~~
228 |
229 | The above command will start the bot and it will be available at
230 | :
231 |
232 | ~~~~
233 | Bot is running at http://localhost:8000/
234 | ~~~~
235 |
236 | [srvx]: https://srvx.h3.dev/
237 | [`serve()`]: https://srvx.h3.dev/guide/server
238 |
239 |
240 | Exposing the bot to the public internet
241 | ---------------------------------------
242 |
243 | However, other fediverse servers cannot interact with your bot if it is only
244 | available on your local machine. To expose your bot to the public internet,
245 | you can use a tunneling service like [`fedify tunnel`], [ngrok], [Tailscale
246 | Funnel], etc.
247 |
248 | Since those tunneling services practically act as an L7 reverse proxy,
249 | you need to turn on
250 | the [`behindProxy`](./concepts/bot.md#createbotoptions-behindproxy) option:
251 |
252 | ~~~~ typescript [bot.ts] twoslash
253 | import {
254 | createBot,
255 | InProcessMessageQueue,
256 | MemoryKvStore,
257 | text,
258 | } from "@fedify/botkit";
259 | // ---cut-before---
260 | const bot = createBot({
261 | username: "mybot",
262 | name: "My Bot",
263 | summary: text`A bot powered by BotKit.`,
264 | kv: new MemoryKvStore(),
265 | queue: new InProcessMessageQueue(),
266 | behindProxy: true, // [!code highlight]
267 | });
268 | ~~~~
269 |
270 | Here, we will use [`fedify tunnel`] to expose the bot to the public internet.
271 | [Install the `fedify` command first][2], and then run the following command:
272 |
273 | ~~~~ bash
274 | fedify tunnel 8000
275 | ~~~~
276 |
277 | The above command will expose your bot to the public internet, and you will get
278 | a temporary public hostname that your bot can be accessed from the
279 | fediverse:[^1]
280 |
281 | ~~~~
282 | ✔ Your local server at 8000 is now publicly accessible:
283 |
284 | https://c4d3933be87bc2.lhr.life/
285 |
286 | Press ^C to close the tunnel.
287 | ~~~~
288 |
289 | [^1]: The hostname will be different in your case.
290 |
291 | [`fedify tunnel`]: https://fedify.dev/cli#fedify-tunnel-exposing-a-local-http-server-to-the-public-internet
292 | [ngrok]: https://ngrok.com/
293 | [Tailscale Funnel]: https://tailscale.com/kb/1223/funnel
294 | [2]: https://fedify.dev/cli#installation
295 |
296 |
297 | Testing the bot
298 | ---------------
299 |
300 | To test the bot, you can use [ActivityPub.Academy], a development-purpose
301 | Mastodon instance. ActivityPub.Academy allows you to immediately create
302 | an ephemeral fediverse account and provides several tools to debug your
303 | ActivityPub application such as *Activity Log*.
304 |
305 | Okay, let's create a new account on ActivityPub.Academy and follow your bot
306 | account: `@mybot@c4d3933be87bc2.lhr.life`—replace `c4d3933be87bc2.lhr.life`
307 | with the domain name assigned by the [`fedify tunnel`] command.
308 |
309 | Here's how you can follow your bot account—in ActivityPub.Academy's search bar,
310 | type `@mybot@c4d3933be87bc2.lhr.life` and click the account:
311 |
312 | 
314 |
315 | Then, click the *Follow* button:
316 |
317 | 
319 |
320 | Few seconds later, you will receive a direct message from your bot:
321 |
322 | 
324 |
325 |
326 | [ActivityPub.Academy]: https://activitypub.academy/
327 |
328 |
329 |
--------------------------------------------------------------------------------
/docs/concepts/repository.md:
--------------------------------------------------------------------------------
1 | ---
2 | description: >-
3 | A repository is a data access object that provides an abstraction over the
4 | underlying data source. This document provides an overview of repositories
5 | and how they are used in the framework.
6 | ---
7 |
8 | Repository
9 | ==========
10 |
11 | A repository is a data access object that provides an abstraction over the
12 | underlying data source. BotKit provides a few built-in repositories that
13 | can be used to interact with the database, but you can also create your own
14 | repositories to interact with other data sources.
15 |
16 |
17 | `KvRepository`
18 | --------------
19 |
20 | It is the default repository provided by BotKit. If you omit the
21 | [`repository`](./bot.md#createbotoptions-repository) option of
22 | the [`createBot()`](./bot.md#instantiation) function, BotKit will use
23 | the `KvRepository` by default.
24 |
25 | The `KvRepository` is a repository that stores data in a key–value store
26 | through the [`KvStore`] interface, which is provided by the Fedify.
27 | Since the [`KvStore`] interface itself also abstracts over the underlying
28 | data source, you can easily switch between different key–value stores
29 | without changing the repository implementation.
30 |
31 | There are several [`KvStore`] implementations available in the Fedify:
32 |
33 | [`RedisKvStore`]
34 | : [`RedisKvStore`] is a key–value store implementation that uses Redis as
35 | the backend storage. It provides scalability and high performance, making
36 | it suitable for production use in distributed systems. It requires
37 | a Redis server setup and maintenance.
38 |
39 | > [!NOTE]
40 | > The [`RedisKvStore`] class is available in the [@fedify/redis] package.
41 |
42 | [`PostgresKvStore`]
43 | : [`PostgresKvStore`] is a key–value store implementation that uses
44 | PostgreSQL as the backend storage. It provides scalability and high
45 | performance, making it suitable for production use in distributed systems.
46 | It requires a PostgreSQL server setup and maintenance.
47 |
48 | > [!NOTE]
49 | > The [`PostgresKvStore`] class is available in the [@fedify/postgres]
50 | > package.
51 |
52 | [`DenoKvStore`] (Deno only)
53 | : [`DenoKvStore`] is a key–value store implementation for [Deno] runtime
54 | that uses Deno's built-in [`Deno.openKv()`] API. It provides persistent
55 | storage and good performance for Deno environments. It's suitable for
56 | production use in Deno applications.
57 |
58 | > [!NOTE]
59 | > The [`DenoKvStore`] class is available in *x/deno* module of
60 | > the [@fedify/fedify] package.
61 |
62 | [`MemoryKvStore`]
63 | : A simple in-memory key–value store that doesn't persist data. It's
64 | best suited for development and testing environments where data don't
65 | have to be shared across multiple nodes. No setup is required, making
66 | it easy to get started.
67 |
68 | > [!TIP]
69 | > Although [`MemoryKvStore`] is provided by Fedify, BotKit also re-exports
70 | > it for convenience.
71 |
72 | [`KvStore`]: https://fedify.dev/manual/kv
73 | [`RedisKvStore`]: https://fedify.dev/manual/kv#rediskvstore
74 | [@fedify/redis]: https://github.com/fedify-dev/redis
75 | [`PostgresKvStore`]: https://fedify.dev/manual/kv#postgreskvstore
76 | [@fedify/postgres]: https://github.com/fedify-dev/postgres
77 | [`DenoKvStore`]: https://fedify.dev/manual/kv#denokvstore-deno-only
78 | [Deno]: https://deno.com/
79 | [`Deno.openKv()`]: https://docs.deno.com/api/deno/~/Deno.openKv
80 | [@fedify/fedify]: https://fedify.dev/
81 | [`MemoryKvStore`]: https://fedify.dev/manual/kv#memorykvstore
82 |
83 |
84 | `SqliteRepository`
85 | ------------------
86 |
87 | *This API is available since BotKit 0.3.0.*
88 |
89 | The `SqliteRepository` is a repository that stores data in a SQLite database
90 | using the [`node:sqlite`] module. It provides a production-ready storage
91 | solution with excellent performance and reliability, while maintaining
92 | compatibility with both Deno and Node.js environments.
93 |
94 | Unlike [`KvRepository`](#kvrepository) which requires a separate key–value store
95 | setup, `SqliteRepository` can operate with either an in-memory database for
96 | development/testing or a file-based database for production use. It offers ACID
97 | compliance through transactions, write-ahead logging (WAL) mode for optimal
98 | performance, and proper indexing for efficient data retrieval.
99 |
100 | In order to use `SqliteRepository`, you need to install the
101 | *@fedify/botkit-sqlite* package:
102 |
103 | ::: code-group
104 |
105 | ~~~~ sh [Deno]
106 | deno add jsr:@fedify/botkit-sqlite
107 | ~~~~
108 |
109 | ~~~~ sh [npm]
110 | npm add @fedify/botkit-sqlite
111 | ~~~~
112 |
113 | ~~~~ sh [pnpm]
114 | pnpm add @fedify/botkit-sqlite
115 | ~~~~
116 |
117 | ~~~~ sh [Yarn]
118 | yarn add @fedify/botkit-sqlite
119 | ~~~~
120 |
121 | :::
122 |
123 | The `SqliteRepository` constructor accepts an options object with the following
124 | properties:
125 |
126 | `path` (optional)
127 | : Path to the SQLite database file. Defaults to `":memory:"` for an
128 | in-memory database. Use a file path for persistent storage.
129 |
130 | `wal` (optional)
131 | : Whether to enable write-ahead logging (WAL) mode for better performance.
132 | Defaults to `true` for file-based databases. WAL mode is not applicable
133 | for in-memory databases.
134 |
135 | [`node:sqlite`]: https://nodejs.org/api/sqlite.html
136 |
137 |
138 | `MemoryRepository`
139 | ------------------
140 |
141 | The `MemoryRepository` is a repository that stores data in memory, which means
142 | that data is not persisted across restarts. It's best suited for development
143 | and testing environments where data don't have to be shared across multiple
144 | nodes. No setup is required, making it easy to get started.
145 |
146 | > [!TIP]
147 | > How does it differ from using [`KvRepository`](#kvrepository) with
148 | > [`MemoryKvStore`]?—In practice, there's no difference between using
149 | > `MemoryRepository` and [`KvRepository`](#kvrepository) with
150 | > [`MemoryKvStore`]. The only differences are that `MemoryRepository` is
151 | > a more convenient way to use `MemoryKvStore` and that it's slightly more
152 | > efficient because it doesn't have to go through the [`KvStore`] interface.
153 |
154 |
155 | `MemoryCachedRepository`
156 | ------------------------
157 |
158 | *This API is available since BotKit 0.3.0.*
159 |
160 | The `MemoryCachedRepository` is a repository decorator that adds an in-memory
161 | cache layer on top of another repository. This is useful for improving
162 | performance by reducing the number of accesses to the underlying persistent
163 | storage, but it increases memory usage. The cache is not persistent and will
164 | be lost when the process exits.
165 |
166 | It takes an existing `Repository` instance (like `KvRepository` or even
167 | another `MemoryCachedRepository`) and wraps it. Write operations are performed
168 | on both the underlying repository and the cache. Read operations first check
169 | the cache; if the data is found, it's returned directly. Otherwise, the data
170 | is fetched from the underlying repository, stored in the cache, and then
171 | returned.
172 |
173 | > [!NOTE]
174 | > List operations like `getMessages` and `getFollowers`, and count operations
175 | > like `countMessages` and `countFollowers` are not cached due to the
176 | > complexity of handling various filtering and pagination options. These
177 | > operations always delegate directly to the underlying repository.
178 |
179 |
180 | Implementing a custom repository
181 | --------------------------------
182 |
183 | You can create your own repository by implementing the `Repository` interface.
184 | The `Repository` interface is a generic interface that defines the basic
185 | CRUD (create, read, update, delete) operations for data access.
186 |
187 | The `Repository` interface consists of the following five domains of operations
188 | in general:
189 |
190 | Key pairs
191 | : Key pairs are the singleton data that are used for the bot actor.
192 | At the surface level, the key pairs are represented as [`CryptoKeyPair`]
193 | objects, but you would typically store them as [JWK].
194 |
195 | > [!TIP]
196 | > Fedify provides `exportJwk()` and `importJwk()` functions to convert
197 | > a [`CryptoKey`] object to a JWK object and vice versa.
198 |
199 | Messages
200 | : Messages are the data of the messages that are published by the bot.
201 | Remote messages received from the remote server are not included in this
202 | domain. Each message has its own UUID and represented by either
203 | a `Create` object or an `Announce` object (which both are provided by
204 | Fedify).
205 |
206 | You probably want to serialize the messages into JSON before
207 | storing them, so you can use [`toJsonLd()`] method that belong to
208 | the `Create` and `Announce` objects, and use [`fromJsonLd()`] method
209 | to deserialize them.
210 |
211 | Followers
212 | : Followers are the data of the actors that follow the bot. Each follower
213 | is represented by `Actor` object (provided by Fedify) and is associated
214 | with a follow ID, a URI of the `Follow` activity.
215 |
216 | Similar to messages, you can serialize the `Actor` object into JSON
217 | using the [`toJsonLd()`] method, and deserialize it using the
218 | [`fromJsonLd()`] method.
219 |
220 | > [!CAUTION]
221 | > The `Repository.hasFollower()` method takes the URI of an `Actor`, not
222 | > the follow ID.
223 |
224 | Sent follows
225 | : Sent follows are the data of the follow requests that the bot has sent.
226 | Each sent follow is represented by a `Follow` object (provided by Fedify)
227 | and is associated with its own UUID.
228 |
229 | Similar to messages and followers, you can serialize the `Follow` object
230 | into JSON using the [`toJsonLd()`] method, and deserialize it using the
231 | [`fromJsonLd()`] method.
232 |
233 | Followees
234 | : Followees are the data of the actors that the bot follows. Each followee
235 | is represented by a `Follow` object (provided by Fedify) instead of `Actor`,
236 | and associated with an actor ID (not a follow ID).
237 |
238 | Similar to messages, followers, and sent follows, you can serialize
239 | the `Follow` object into JSON using the [`toJsonLd()`] method, and
240 | deserialize it using the [`fromJsonLd()`] method.
241 |
242 | [`CryptoKeyPair`]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair
243 | [JWK]: https://datatracker.ietf.org/doc/html/rfc7517
244 | [`CryptoKey`]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey
245 | [`toJsonLd()`]: https://fedify.dev/manual/vocab#json-ld
246 | [`fromJsonLd()`]: https://fedify.dev/manual/vocab#json-ld
247 |
--------------------------------------------------------------------------------
/docs/deploy/store-mq.md:
--------------------------------------------------------------------------------
1 | ---
2 | description: >-
3 | Learn how to configure and manage key–value stores and message queues for your
4 | BotKit bot across different deployment environments.
5 | ---
6 |
7 | Key–value store and message queue
8 | =================================
9 |
10 | BotKit requires two main backend services for operation:
11 |
12 | 1. A key–value store for persistent data storage
13 | 2. A message queue for handling background tasks
14 |
15 | This guide covers configuration options for different deployment environments
16 | and provides recommendations for production use.
17 |
18 |
19 | Key–value stores
20 | ----------------
21 |
22 | Key–value stores are used to store persistent data for your bot, such as
23 | messages, followers, and followees. Usually you would want to pair a key–value
24 | store with the main database for your application.
25 |
26 | BotKit supports the following key–value store implementations:
27 |
28 | ### [Deno KV] (Deno Deploy)
29 |
30 | [Deno KV] is the simplest option when running on [Deno Deploy]. It's built into
31 | the Deno runtime with no additional infrastructure needed, provides automatic
32 | replication on Deno Deploy, and supports ACID transactions. However, it's only
33 | available in Deno environments, has limited querying capabilities, and size
34 | limits per value (64KB on Deno Deploy).
35 |
36 | ~~~~ typescript
37 | import { DenoKvStore } from "@fedify/fedify/x/deno";
38 |
39 | const kv = await Deno.openKv();
40 |
41 | const bot = createBot({
42 | username: "mybot",
43 | kv: new DenoKvStore(kv),
44 | // ... other configuration
45 | });
46 | ~~~~
47 |
48 | Since [`DenoKvStore`] is provided by [Fedify], you need to install the
49 | *@fedify/fedify* package to use it:
50 |
51 | ~~~~ sh [Deno]
52 | deno add jsr:@fedify/fedify
53 | ~~~~
54 |
55 | [Deno KV]: https://deno.land/manual/runtime/kv
56 | [Deno Deploy]: https://deno.com/deploy
57 | [`DenoKvStore`]: https://fedify.dev/manual/kv#denokvstore-deno-only
58 | [Fedify]: https://fedify.dev/
59 |
60 | ### [SQLite]
61 |
62 | [SQLite] is a good choice for local development and testing, as well as for
63 | small-scale production deployments. It's lightweight and easy to set up,
64 | provides ACID compliance and transaction support, making it excellent for
65 | development and testing environments. However, it's not suitable for
66 | high-concurrency production use and has limited scalability.
67 |
68 | ~~~~ typescript twoslash
69 | import { createBot } from "@fedify/botkit";
70 | import { SqliteKvStore } from "@fedify/sqlite";
71 | import { DatabaseSync } from "node:sqlite";
72 |
73 | const sqlite = new DatabaseSync("bot-data.db");
74 | const bot = createBot({
75 | username: "mybot",
76 | kv: new SqliteKvStore(sqlite),
77 | });
78 | ~~~~
79 |
80 | You need to install the *@fedify/sqlite* package to use the [`SqliteKvStore`]:
81 |
82 | ::: code-group
83 |
84 | ~~~~ sh [Deno]
85 | deno add jsr:@fedify/sqlite
86 | ~~~~
87 |
88 | ~~~~ sh [npm]
89 | npm add @fedify/sqlite
90 | ~~~~
91 |
92 | ~~~~ sh [pnpm]
93 | pnpm add @fedify/sqlite
94 | ~~~~
95 |
96 | ~~~~ sh [Yarn]
97 | yarn add @fedify/sqlite
98 | ~~~~
99 |
100 | :::
101 |
102 | [SQLite]: https://www.sqlite.org/
103 | [`SqliteKvStore`]: https://fedify.dev/manual/kv#sqlitekvstore
104 |
105 | ### [Redis] or [Valkey]
106 |
107 | [Redis] (or its open source fork [Valkey]) is recommended for production
108 | deployments needing high performance. It offers excellent performance,
109 | clustering support, and wide hosting options, making it ideal for scalable
110 | production environments.
111 |
112 | ::: code-group
113 |
114 | ~~~~ typescript [Deno] twoslash
115 | import { createBot } from "@fedify/botkit";
116 | import { RedisKvStore } from "@fedify/redis";
117 | import { Redis } from "ioredis";
118 |
119 | const redis = new Redis({
120 | host: Deno.env.get("REDIS_HOST"),
121 | port: parseInt(Deno.env.get("REDIS_PORT") ?? "6379"),
122 | password: Deno.env.get("REDIS_PASSWORD"),
123 | tls: Deno.env.get("REDIS_TLS") === "true" ? {} : undefined,
124 | });
125 |
126 | const bot = createBot({
127 | username: "mybot",
128 | kv: new RedisKvStore(redis),
129 | });
130 | ~~~~
131 |
132 | ~~~~ typescript [Node.js] twoslash
133 | import { createBot } from "@fedify/botkit";
134 | import { RedisKvStore } from "@fedify/redis";
135 | import { Redis } from "ioredis";
136 |
137 | const redis = new Redis({
138 | host: process.env.REDIS_HOST,
139 | port: parseInt(process.env.REDIS_PORT ?? "6379"),
140 | password: process.env.REDIS_PASSWORD,
141 | tls: process.env.REDIS_TLS === "true" ? {} : undefined,
142 | });
143 |
144 | const bot = createBot({
145 | username: "mybot",
146 | kv: new RedisKvStore(redis),
147 | });
148 | ~~~~
149 |
150 | :::
151 |
152 | You need to install the *@fedify/redis* package to use the [`RedisKvStore`]:
153 |
154 | ::: code-group
155 |
156 | ~~~~ sh [Deno]
157 | deno add jsr:@fedify/redis
158 | ~~~~
159 |
160 | ~~~~ sh [npm]
161 | npm add @fedify/redis
162 | ~~~~
163 |
164 | ~~~~ sh [pnpm]
165 | pnpm add @fedify/redis
166 | ~~~~
167 |
168 | ~~~~ sh [Yarn]
169 | yarn add @fedify/redis
170 | ~~~~
171 |
172 | :::
173 |
174 | [Redis]: https://redis.io/
175 | [Valkey]: https://valkey.io/
176 | [`RedisKvStore`]: https://fedify.dev/manual/kv#rediskvstore
177 |
178 | ### [PostgreSQL]
179 |
180 | [PostgreSQL] is suitable for deployments needing complex queries or transactions.
181 | It provides ACID compliance, complex query support, robust backup solutions,
182 | and a mature ecosystem, making it an excellent choice when you need advanced
183 | database features.
184 |
185 | ::: code-group
186 |
187 | ~~~~ typescript [Deno] twoslash
188 | import { createBot } from "@fedify/botkit";
189 | import { PostgresKvStore } from "@fedify/postgres";
190 | import postgres from "postgres";
191 |
192 | const sql = postgres(Deno.env.get("DATABASE_URL")!);
193 |
194 | const bot = createBot({
195 | username: "mybot",
196 | kv: new PostgresKvStore(sql),
197 | });
198 | ~~~~
199 |
200 | ~~~~ typescript [Node.js] twoslash
201 | import { createBot } from "@fedify/botkit";
202 | import { PostgresKvStore } from "@fedify/postgres";
203 | import postgres from "postgres";
204 |
205 | const sql = postgres(process.env.DATABASE_URL!);
206 |
207 | const bot = createBot({
208 | username: "mybot",
209 | kv: new PostgresKvStore(sql),
210 | });
211 | ~~~~
212 |
213 | :::
214 |
215 | You need to install the *@fedify/postgres* package to use
216 | the [`PostgresKvStore`]:
217 |
218 | ::: code-group
219 |
220 | ~~~~ sh [Deno]
221 | deno add jsr:@fedify/postgres
222 | ~~~~
223 |
224 | ~~~~ sh [npm]
225 | npm add @fedify/postgres
226 | ~~~~
227 |
228 | ~~~~ sh [pnpm]
229 | pnpm add @fedify/postgres
230 | ~~~~
231 |
232 | ~~~~ sh [Yarn]
233 | yarn add @fedify/postgres
234 | ~~~~
235 |
236 | :::
237 |
238 | [PostgreSQL]: https://www.postgresql.org/
239 | [`PostgresKvStore`]: https://fedify.dev/manual/kv#postgreskvstore
240 |
241 |
242 | Message queues
243 | --------------
244 |
245 | Message queues are used to handle background tasks, such as sending messages
246 | and processing incoming activities. Usually you would want to pair a message
247 | queue with a key–value store for a compact and complete backend solution.
248 |
249 | ### [Deno KV Queue] (Deno Deploy)
250 |
251 | Built on top of [Deno KV], suitable for [Deno Deploy]. It requires no
252 | additional infrastructure, works seamlessly with Deno Deploy,
253 | and provides automatic scaling. However, it's only available in Deno
254 | environments and has limited throughput compared to dedicated message queue
255 | solutions.
256 |
257 | ~~~~ typescript
258 | import { DenoKvMessageQueue } from "@fedify/fedify/x/deno";
259 |
260 | const kv = await Deno.openKv();
261 |
262 | const bot = createBot({
263 | username: "mybot",
264 | kv: new DenoKvStore(kv),
265 | queue: new DenoKvMessageQueue(kv),
266 | });
267 |
268 | bot.federation.startQueue();
269 | ~~~~
270 |
271 | Since [`DenoKvMessageQueue`] is provided by [Fedify], you need to install the
272 | *@fedify/fedify* package to use it:
273 |
274 | ~~~~ sh [Deno]
275 | deno add jsr:@fedify/fedify
276 | ~~~~
277 |
278 | [Deno KV Queue]: https://docs.deno.com/deploy/kv/manual/queue_overview/
279 | [`DenoKvMessageQueue`]: https://fedify.dev/manual/mq#denokvmessagequeue-deno-only
280 |
281 | ### [Redis] or [Valkey]
282 |
283 | Recommended for production deployments, offering high performance,
284 | reliable message delivery, the ability to share infrastructure with your
285 | key–value store, and good monitoring tools.
286 |
287 | ::: code-group
288 |
289 | ~~~~ typescript [Deno] twoslash
290 | import { createBot } from "@fedify/botkit";
291 | import { RedisKvStore, RedisMessageQueue } from "@fedify/redis";
292 | import { Redis } from "ioredis";
293 |
294 | function getRedis(): Redis {
295 | return new Redis({
296 | host: Deno.env.get("REDIS_HOST"),
297 | port: parseInt(Deno.env.get("REDIS_PORT") ?? "6379"),
298 | password: Deno.env.get("REDIS_PASSWORD"),
299 | tls: Deno.env.get("REDIS_TLS") === "true" ? {} : undefined,
300 | });
301 | }
302 |
303 | const bot = createBot({
304 | username: "mybot",
305 | kv: new RedisKvStore(getRedis()),
306 | queue: new RedisMessageQueue(getRedis),
307 | });
308 | ~~~~
309 |
310 | ~~~~ typescript [Node.js] twoslash
311 | import { createBot } from "@fedify/botkit";
312 | import { RedisKvStore, RedisMessageQueue } from "@fedify/redis";
313 | import { Redis } from "ioredis";
314 |
315 | function getRedis(): Redis {
316 | return new Redis({
317 | host: process.env.REDIS_HOST,
318 | port: parseInt(process.env.REDIS_PORT ?? "6379"),
319 | password: process.env.REDIS_PASSWORD,
320 | tls: process.env.REDIS_TLS === "true" ? {} : undefined,
321 | });
322 | }
323 |
324 | const bot = createBot({
325 | username: "mybot",
326 | kv: new RedisKvStore(getRedis()),
327 | queue: new RedisMessageQueue(getRedis),
328 | });
329 | ~~~~
330 |
331 | :::
332 |
333 | You need to install the *@fedify/redis* package to use
334 | the [`RedisMessageQueue`]:
335 |
336 | ::: code-group
337 |
338 | ~~~~ sh [Deno]
339 | deno add jsr:@fedify/redis
340 | ~~~~
341 |
342 | ~~~~ sh [npm]
343 | npm add @fedify/redis
344 | ~~~~
345 |
346 | ~~~~ sh [pnpm]
347 | pnpm add @fedify/redis
348 | ~~~~
349 |
350 | ~~~~ sh [Yarn]
351 | yarn add @fedify/redis
352 | ~~~~
353 |
354 | :::
355 |
356 | [`RedisMessageQueue`]: https://fedify.dev/manual/mq#redismessagequeue
357 |
358 | ### [PostgreSQL]
359 |
360 | Suitable when already using [PostgreSQL] for storage. It provides ACID
361 | compliance, can share infrastructure with your key–value store,
362 | offers good long-term persistence, and supports transactions, making it ideal
363 | when you want to consolidate your backend infrastructure.
364 |
365 | ::: code-group
366 |
367 | ~~~~ typescript [Deno] twoslash
368 | import { createBot } from "@fedify/botkit";
369 | import { PostgresKvStore, PostgresMessageQueue } from "@fedify/postgres";
370 | import postgres from "postgres";
371 |
372 | const sql = postgres(Deno.env.get("DATABASE_URL")!);
373 |
374 | const bot = createBot({
375 | username: "mybot",
376 | kv: new PostgresKvStore(sql),
377 | queue: new PostgresMessageQueue(sql),
378 | });
379 | ~~~~
380 |
381 | ~~~~ typescript [Node.js] twoslash
382 | import { createBot } from "@fedify/botkit";
383 | import { PostgresKvStore, PostgresMessageQueue } from "@fedify/postgres";
384 | import postgres from "postgres";
385 |
386 | const sql = postgres(process.env.DATABASE_URL!);
387 |
388 | const bot = createBot({
389 | username: "mybot",
390 | kv: new PostgresKvStore(sql),
391 | queue: new PostgresMessageQueue(sql),
392 | });
393 | ~~~~
394 |
395 | :::
396 |
397 | You need to install the *@fedify/postgres* package to use
398 | the [`PostgresMessageQueue`]:
399 |
400 | ::: code-group
401 |
402 | ~~~~ sh [Deno]
403 | deno add jsr:@fedify/postgres
404 | ~~~~
405 |
406 | ~~~~ sh [npm]
407 | npm add @fedify/postgres
408 | ~~~~
409 |
410 | ~~~~ sh [pnpm]
411 | pnpm add @fedify/postgres
412 | ~~~~
413 |
414 | ~~~~ sh [Yarn]
415 | yarn add @fedify/postgres
416 | ~~~~
417 |
418 | :::
419 |
420 | [`PostgresMessageQueue`]: https://fedify.dev/manual/mq#postgresmessagequeue
421 |
422 |
423 |
--------------------------------------------------------------------------------
2 |
3 | [BotKit] by Fedify
4 | ==================
5 |
6 | [![JSR][JSR badge]][JSR]
7 | [![npm][npm badge]][npm]
8 | [![GitHub Actions][GitHub Actions badge]][GitHub Actions]
9 | [![Codecov][Codecov badge]][Codecov]
10 | [![Fediverse][Fediverse badge]][Fediverse]
11 |
12 | [BotKit] is a framework for creating [ActivityPub] bots. It is powered by
13 | [Fedify], a lower-level library for creating ActivityPub server applications.
14 | Unlike Mastodon bots, BotKit is designed to create a standalone ActivityPub bot,
15 | which is a complete ActivityPub server in itself and not limited to Mastodon's
16 | capabilities (such as the 500-character limit per post).
17 |
18 | BotKit's API is so simple and easy to use that you can create a complete bot in
19 | a single TypeScript file. Here's an example of a simple bot that just greets:
20 |
21 | ~~~~ typescript
22 | import { createBot, mention, text } from "@fedify/botkit";
23 | import { RedisKvStore } from "@fedify/redis";
24 | import { Redis } from "ioredis";
25 |
26 | // Create a bot instance:
27 | const bot = createBot
85 |
86 | [FediChatBot] is an LLM-powered chatbot for fediverse, of course, built on top
87 | of BotKit. It consists of about 350 lines of code, and it's a good example of
88 | how to build a chatbot with BotKit. You can find the source code at:
89 | 
world!',
32 | );
33 |
34 | // Test multiple emojis
35 | assert.equal(
36 | renderCustomEmojis("Good morning :smile: :laughing:", emojis),
37 | 'Good morning 
',
38 | );
39 |
40 | // Test emojis adjacent to text
41 | assert.equal(
42 | renderCustomEmojis("Hi:smile:! How are you:laughing:?", emojis),
43 | 'Hi
link.',
63 | );
64 |
65 | // Test emojis inside HTML attributes (should not be replaced)
66 | assert.equal(
67 | renderCustomEmojis('
', emojis),
68 | '
test',
75 | );
76 |
77 | // Test emojis with underscores
78 | assert.equal(
79 | renderCustomEmojis("Great job :thumbs_up:", emojis),
80 | 'Great job 
111 |