Custom emojis

Author: dahlia

CHANGES.md

@@ -8,6 +8,21 @@ To be released.
 
  -  Image attachments in posts became shown in the web interface.
 
+ -  Added custom emoji support.
+
+     -  The return type of `Text.getTags()` method became
+         `AsyncIterable<Link | Object>` (was `AsyncIterable<Link>`).
+     -  Added `Bot.addCustomEmojis()` method.
+     -  Added `CustomEmojiText` class.
+     -  Added `customEmoji()` function.
+     -  Added `CustomEmojiBase` interface.
+     -  Added `CustomEmojiFromUrl` interface.
+     -  Added `CustomEmojiFromFile` interface.
+     -  Added `CustomEmoji` type.
+     -  Added `DeferredEmoji` type.
+     -  Added `Emoji` class.
+
+
 
 Version 0.1.1
 -------------

deno.json

@@ -9,6 +9,7 @@
   "exports": {
     ".": "./src/mod.ts",
     "./bot": "./src/bot.ts",
+    "./emoji": "./src/emoji.ts",
     "./events": "./src/events.ts",
     "./follow": "./src/follow.ts",
     "./message": "./src/message.ts",
@@ -26,6 +27,7 @@
     "@phensley/language-tag": "npm:@phensley/language-tag@^1.9.2",
     "@std/assert": "jsr:@std/assert@^1.0.10",
     "@std/html": "jsr:@std/html@^1.0.3",
+    "@std/media-types": "jsr:@std/media-types@^1.1.0",
     "@std/uuid": "jsr:@std/uuid@^1.0.4",
     "markdown-it": "npm:markdown-it@^14.1.0",
     "xss": "npm:xss@^1.0.15"

docs/concepts/text.md

@@ -401,6 +401,39 @@ The above code will create a text like this:
 > It is not a code block, but an inline code.
 
 
+Custom emojis
+-------------
+
+*This API is available since BotKit 0.2.0.*
+
+You can include a custom emoji in the text using the `customEmoji()` function.
+It is an inline construct.
+
+In order to use the `customEmoji()` function, you need to define custom emojis
+first.  You can define custom emojis by using the `Bot.addCustomEmojis()`
+method after creating the bot:
+
+~~~~ typescript
+// Define custom emojis:
+const emojis = bot.addCustomEmojis({
+  // Use a local image file:
+  botkit: { file: `${import.meta.dirname}/botkit.png`, type: "image/png" },
+  // Use a remote image URL:
+  fedify: { url: "https://fedify.dev/logo.png", type: "image/png" },
+});
+~~~~
+
+The `~Bot.addCustomEmojis()` method returns an object that contains the custom
+emojis.  You can use the keys of the object to refer to the custom emojis.
+For example:
+
+~~~~ typescript
+text`Here's a custom emoji:
+
+${customEmoji(emojis.botkit)} by ${customEmoji(emojis.fedify)}.`
+~~~~
+
+
 Markdown
 --------
 

examples/greet.ts

@@ -1,4 +1,12 @@
-import { createBot, hashtag, Image, link, mention, text } from "@fedify/botkit";
+import {
+  createBot,
+  customEmoji,
+  hashtag,
+  Image,
+  link,
+  mention,
+  text,
+} from "@fedify/botkit";
 import { DenoKvMessageQueue, DenoKvStore } from "@fedify/fedify/x/denokv";
 
 const kv = await Deno.openKv();
@@ -25,9 +33,18 @@ const bot = createBot<void>({
   pages: { color: "green" },
 });
 
+const emojis = bot.addCustomEmojis({
+  botkit: {
+    type: "image/png",
+    file: `${import.meta.dirname}/../docs/public/favicon-192x192.png`,
+  },
+});
+
 bot.onFollow = async (session, followRequest) => {
   await session.publish(
-    text`Thanks for following me, ${followRequest.follower}!`,
+    text`Thanks for following me, ${followRequest.follower}! ${
+      customEmoji(emojis.botkit)
+    }`,
     {
       visibility: "direct",
       attachments: [
@@ -46,15 +63,20 @@ bot.onFollow = async (session, followRequest) => {
 };
 
 bot.onUnfollow = async (session, follower) => {
-  await session.publish(text`Goodbye, ${follower}!`, {
-    visibility: "direct",
-  });
+  await session.publish(
+    text`Goodbye, ${follower}! ${customEmoji(emojis.botkit)}`,
+    { visibility: "direct" },
+  );
 };
 
 bot.onReply = async (session, message) => {
   const botUri = session.actorId.href;
   if (message.mentions.some((a) => a.id?.href === botUri)) return;
-  await message.reply(text`Thanks for your reply, ${message.actor}!`);
+  await message.reply(
+    text`Thanks for your reply, ${message.actor}! ${
+      customEmoji(emojis.botkit)
+    }`,
+  );
 };
 
 bot.onMention = async (_session, message) => {
@@ -64,9 +86,9 @@ bot.onMention = async (_session, message) => {
 const session = bot.getSession(Deno.env.get("ORIGIN") ?? "http://localhost");
 setInterval(async () => {
   const message = await session.publish(
-    text`Hi, folks! It's a minutely greeting. It will be deleted in 30 seconds.  ${
-      hashtag("greet")
-    }`,
+    text`Hi, folks! It's a minutely greeting. It will be deleted in 30 seconds. ${
+      customEmoji(emojis.botkit)
+    } ${hashtag("greet")}`,
   );
   setTimeout(async () => {
     await message.delete();

src/bot-impl.test.ts

@@ -22,6 +22,7 @@ import {
   Article,
   Create,
   CryptographicKey,
+  Emoji,
   Follow,
   Image,
   Like as RawLike,
@@ -40,8 +41,10 @@ import { assert } from "@std/assert/assert";
 import { assertEquals } from "@std/assert/equals";
 import { assertFalse } from "@std/assert/false";
 import { assertInstanceOf } from "@std/assert/instance-of";
+import { assertThrows } from "@std/assert/throws";
 import { BotImpl } from "./bot-impl.ts";
 import { parseSemVer } from "./bot.ts";
+import type { CustomEmoji } from "./emoji.ts";
 import type { FollowRequest } from "./follow.ts";
 import type { Message, MessageClass, SharedMessage } from "./message.ts";
 import type { Like } from "./reaction.ts";
@@ -1963,6 +1966,171 @@ Deno.test("BotImpl.fetch()", async () => {
   assertEquals(response2.status, 200);
 });
 
+// Test BotImpl.addCustomEmoji() and BotImpl.addCustomEmojis()
+Deno.test("BotImpl.addCustomEmoji(), BotImpl.addCustomEmojis()", async (t) => {
+  const bot = new BotImpl<void>({ kv: new MemoryKvStore(), username: "bot" });
+
+  await t.step("addCustomEmoji()", () => {
+    const emojiData: CustomEmoji = {
+      type: "image/png",
+      url: "https://example.com/emoji.png",
+    };
+    const deferredEmoji = bot.addCustomEmoji("testEmoji", emojiData);
+    assertEquals(typeof deferredEmoji, "function");
+    assertEquals(bot.customEmojis["testEmoji"], emojiData);
+
+    // Test invalid name
+    assertThrows(
+      () => bot.addCustomEmoji("invalid name", emojiData),
+      TypeError,
+      "Invalid custom emoji name",
+    );
+
+    // Test duplicate name
+    assertThrows(
+      () => bot.addCustomEmoji("testEmoji", emojiData),
+      TypeError,
+      "Duplicate custom emoji name",
+    );
+
+    // Test unsupported media type
+    assertThrows(
+      () =>
+        bot.addCustomEmoji("invalidType", {
+          // @ts-expect-error: Intended type error for testing runtime check
+          type: "text/plain",
+          url: "https://example.com/emoji.txt",
+        }),
+      TypeError,
+      "Unsupported media type",
+    );
+  });
+
+  await t.step("addCustomEmojis()", () => {
+    const emojisData = {
+      emoji1: { type: "image/png", url: "https://example.com/emoji1.png" },
+      emoji2: { type: "image/gif", file: "/path/to/emoji2.gif" },
+    } as const;
+    const deferredEmojis = bot.addCustomEmojis(emojisData);
+
+    assertEquals(typeof deferredEmojis["emoji1"], "function");
+    assertEquals(typeof deferredEmojis["emoji2"], "function");
+    assertEquals(bot.customEmojis["emoji1"], emojisData.emoji1);
+    assertEquals(bot.customEmojis["emoji2"], emojisData.emoji2);
+
+    // Test duplicate name within the batch
+    assertThrows(
+      () =>
+        bot.addCustomEmojis({
+          emoji1: { type: "image/png", url: "https://example.com/dup1.png" },
+        }),
+      TypeError,
+      "Duplicate custom emoji name: emoji1",
+    );
+  });
+});
+
+// Test BotImpl.getEmoji()
+Deno.test("BotImpl.getEmoji()", async () => {
+  const bot = new BotImpl<void>({ kv: new MemoryKvStore(), username: "bot" });
+  const ctx = bot.federation.createContext(
+    new URL("https://example.com"),
+    undefined,
+  );
+
+  // Test with remote URL
+  const remoteEmojiData: CustomEmoji = {
+    type: "image/png",
+    url: "https://remote.com/emoji.png",
+  };
+  bot.customEmojis["remoteEmoji"] = remoteEmojiData;
+  const remoteEmoji = bot.getEmoji(ctx, "remoteEmoji", remoteEmojiData);
+  assertInstanceOf(remoteEmoji, Emoji);
+  assertEquals(
+    remoteEmoji.id,
+    new URL("https://example.com/ap/emoji/remoteEmoji"),
+  );
+  assertEquals(remoteEmoji.name, ":remoteEmoji:");
+  const icon = await remoteEmoji.getIcon();
+  assertInstanceOf(icon, Image);
+  assertEquals(icon.mediaType, "image/png");
+  assertEquals(icon.url?.href, "https://remote.com/emoji.png");
+
+  // Test with local file
+  const localEmojiData: CustomEmoji = {
+    type: "image/gif",
+    file: "/path/to/local/emoji.gif",
+  };
+  bot.customEmojis["localEmoji"] = localEmojiData;
+  const localEmoji = bot.getEmoji(ctx, "localEmoji", localEmojiData);
+  assertInstanceOf(localEmoji, Emoji);
+  assertEquals(
+    localEmoji.id,
+    new URL("https://example.com/ap/emoji/localEmoji"),
+  );
+  assertEquals(localEmoji.name, ":localEmoji:");
+  const icon2 = await localEmoji.getIcon();
+  assertInstanceOf(icon2, Image);
+  assertEquals(icon2.mediaType, "image/gif");
+  assertEquals(
+    icon2.url?.href,
+    "https://example.com/emojis/localEmoji.gif",
+  );
+
+  // Test with local file without extension mapping
+  const localEmojiDataNoExt: CustomEmoji = {
+    type: "image/webp",
+    file: "/path/to/local/emoji",
+  };
+  bot.customEmojis["localEmojiNoExt"] = localEmojiDataNoExt;
+  const localEmojiNoExt = bot.getEmoji(
+    ctx,
+    "localEmojiNoExt",
+    localEmojiDataNoExt,
+  );
+  const icon3 = await localEmojiNoExt.getIcon();
+  assertInstanceOf(icon3, Image);
+  assertEquals(icon3.mediaType, "image/webp");
+  assertEquals(
+    icon3.url?.href,
+    "https://example.com/emojis/localEmojiNoExt.webp",
+  );
+});
+
+// Test BotImpl.dispatchEmoji()
+Deno.test("BotImpl.dispatchEmoji()", () => {
+  const bot = new BotImpl<void>({ kv: new MemoryKvStore(), username: "bot" });
+  const ctx = bot.federation.createContext(
+    new URL("https://example.com"),
+    undefined,
+  );
+  const emojiData: CustomEmoji = {
+    type: "image/png",
+    url: "https://example.com/emoji.png",
+  };
+  bot.customEmojis["testEmoji"] = emojiData;
+
+  // Test dispatching an existing emoji
+  const emoji = bot.dispatchEmoji(ctx, { name: "testEmoji" });
+  assertInstanceOf(emoji, Emoji);
+  assertEquals(emoji.id, new URL("https://example.com/ap/emoji/testEmoji"));
+  assertEquals(emoji.name, ":testEmoji:");
+
+  // Test dispatching a non-existent emoji
+  const nonExistent = bot.dispatchEmoji(ctx, { name: "nonExistent" });
+  assertEquals(nonExistent, null);
+});
+
+Deno.test("BotImpl.getFollowersFirstCursor()", () => {
+  const bot = new BotImpl<void>({ kv: new MemoryKvStore(), username: "bot" });
+  const ctx = bot.federation.createContext(
+    new URL("https://example.com"),
+    undefined,
+  );
+  assertEquals(bot.getFollowersFirstCursor(ctx, "non-existent"), null);
+  assertEquals(bot.getFollowersFirstCursor(ctx, "bot"), "0");
+});
+
 interface SentActivity {
   recipients: "followers" | Recipient[];
   activity: Activity;