Bot.onQuote event for handling quoted messages

This commit implements the Bot.onQuote event handler which gets triggered when
someone quotes one of the bot's messages.  This feature allows bots to respond
when their messages are quoted in the fediverse.  The implementation includes
a test case and documentation for this new event handler.

Author: dahlia

CHANGES.md

@@ -40,6 +40,8 @@ To be released.
 
      -  Added `SessionPublishOptions.quoteTarget` option.
      -  Added `Message.quoteTarget` property.
+     -  Added `Bot.onQuote` event.
+     -  Added `QuoteEventHandler` type.
 
  -  Added `SessionGetOutboxOptions` interface.
 

docs/concepts/events.md

@@ -203,6 +203,29 @@ document.
 > };
 
 
+Quote
+-----
+
+*This API is available since BotKit 0.2.0.*
+
+The `~Bot.onQuote` event handler is called when someone quotes one of your bot's
+messages. It receives a `Message` object, which represents the message that
+quotes your bot's message, as the second argument.
+
+The following is an example of a quote event handler that responds to a message
+that quotes one of your bot's posts:
+
+~~~~ typescript
+bot.onQuote = async (session, quote) => {
+  await quote.reply(text`I see you quoted my post, ${quote.actor}!`);
+};
+~~~~
+
+If you want to get the quoted message, you can use the `~Message.quoteTarget`
+property.  See also the [*Quotes* section](./message.md#quotes) in the *Message*
+concept document.
+
+
 Message
 -------
 

docs/concepts/message.md

@@ -226,6 +226,12 @@ bot.onMention = async (session, message) => {
 };
 ~~~~
 
+> [!NOTE]
+> Quoting behavior can vary significantly between different ActivityPub
+> implementations.  Some platforms like Misskey display quotes prominently,
+> while others like Mastodon might implement quotes differently or not support
+> them at all.
+
 
 Extracting information from a message
 -------------------------------------

src/bot-impl.test.ts

@@ -1753,6 +1753,60 @@ Deno.test("BotImpl.onCreated()", async (t) => {
 
   mentioned = [];
   messaged = [];
+  ctx.forwardedRecipients = [];
+
+  await t.step("on quote", async () => {
+    const create = new Create({
+      id: new URL(
+        "https://example.com/ap/create/9cfd7129-4cf0-4505-90d8-3cac2dc42434",
+      ),
+      actor: new URL("https://example.com/ap/actor/john"),
+      to: PUBLIC_COLLECTION,
+      cc: new URL("https://example.com/ap/actor/john/followers"),
+      object: new Note({
+        id: new URL(
+          "https://example.com/ap/note/9cfd7129-4cf0-4505-90d8-3cac2dc42434",
+        ),
+        attribution: new Person({
+          id: new URL("https://example.com/ap/actor/john"),
+          preferredUsername: "john",
+        }),
+        to: PUBLIC_COLLECTION,
+        cc: new URL("https://example.com/ap/actor/john/followers"),
+        content: "It's a quote!",
+        quoteUrl: new URL(
+          "https://example.com/ap/note/a6358f1b-c978-49d3-8065-37a1df6168de",
+        ),
+      }),
+    });
+    let quoted: [Session<void>, Message<MessageClass, void>][] = [];
+    bot.onQuote = (session, msg) => void (quoted.push([session, msg]));
+
+    await bot.onCreated(ctx, create);
+
+    assertEquals(quoted.length, 1);
+    const [session, msg] = quoted[0];
+    assertEquals(session.bot, bot);
+    assertEquals(session.context, ctx);
+    assertInstanceOf(msg.raw, Note);
+    assertEquals(msg.raw.id, create.objectId);
+    assert(msg.quoteTarget != null);
+    assertEquals(
+      msg.quoteTarget.id,
+      new URL(
+        "https://example.com/ap/note/a6358f1b-c978-49d3-8065-37a1df6168de",
+      ),
+    );
+    assertEquals(replied, []);
+    assertEquals(mentioned, []);
+    assertEquals(messaged, quoted);
+    assertEquals(ctx.sentActivities, []);
+    assertEquals(ctx.forwardedRecipients, ["followers"]);
+
+    quoted = [];
+    messaged = [];
+    ctx.forwardedRecipients = [];
+  });
 
   await t.step("on message", async () => {
     const create = new Create({

src/bot-impl.ts

@@ -56,6 +56,7 @@ import {
 import { getXForwardedRequest } from "@hongminhee/x-forwarded-fetch";
 import { getLogger } from "@logtape/logtape";
 import { extension } from "@std/media-types/extension";
+import { parseMediaType } from "@std/media-types/parse-media-type";
 import metadata from "../deno.json" with { type: "json" };
 import type { Bot, CreateBotOptions, PagesOptions } from "./bot.ts";
 import {
@@ -70,6 +71,7 @@ import type {
   LikeEventHandler,
   MentionEventHandler,
   MessageEventHandler,
+  QuoteEventHandler,
   ReactionEventHandler,
   RejectEventHandler,
   ReplyEventHandler,
@@ -124,6 +126,7 @@ export class BotImpl<TContextData> implements Bot<TContextData> {
   onRejectFollow?: RejectEventHandler<TContextData>;
   onMention?: MentionEventHandler<TContextData>;
   onReply?: ReplyEventHandler<TContextData>;
+  onQuote?: QuoteEventHandler<TContextData>;
   onMessage?: MessageEventHandler<TContextData>;
   onSharedMessage?: SharedMessageEventHandler<TContextData>;
   onLike?: LikeEventHandler<TContextData>;
@@ -667,10 +670,52 @@ export class BotImpl<TContextData> implements Bot<TContextData> {
       if (
         message.visibility === "public" || message.visibility === "unlisted"
       ) {
-        await ctx.forwardActivity(this, "followers");
+        await ctx.forwardActivity(this, "followers", {
+          skipIfUnsigned: true,
+          preferSharedInbox: true,
+          excludeBaseUris: [new URL(ctx.origin)],
+        });
       }
       await this.onReply(session, message);
     }
+    let quoteUrl: URL | null = null;
+    // FIXME: eliminate this duplication
+    for await (const tag of object.getTags(ctx)) {
+      if (tag instanceof Link) {
+        const mediaType = tag.mediaType == null
+          ? null
+          : parseMediaType(tag.mediaType);
+        if (
+          tag.rel === "https://misskey-hub.net/ns#_misskey_quote" ||
+          mediaType?.[0] === "application/activity+json" ||
+          mediaType?.[0] === "application/ld+json" &&
+            mediaType[1]?.profile === "https://www.w3.org/ns/activitystreams"
+        ) {
+          quoteUrl = tag.href;
+          break;
+        }
+      }
+    }
+    if (quoteUrl == null) quoteUrl = object.quoteUrl;
+    const quoteTarget = ctx.parseUri(quoteUrl);
+    if (
+      this.onQuote != null &&
+      quoteTarget?.type === "object" &&
+      // @ts-ignore: quoteTarget.class satisfies (typeof messageClasses)[number]
+      messageClasses.includes(quoteTarget.class)
+    ) {
+      const message = await getMessage();
+      if (
+        message.visibility === "public" || message.visibility === "unlisted"
+      ) {
+        await ctx.forwardActivity(this, "followers", {
+          skipIfUnsigned: true,
+          preferSharedInbox: true,
+          excludeBaseUris: [new URL(ctx.origin)],
+        });
+      }
+      await this.onQuote(session, message);
+    }
     for await (const tag of object.getTags(ctx)) {
       if (
         tag instanceof Mention && tag.href != null && this.onMention != null

src/bot.ts

@@ -29,6 +29,7 @@ import type {
   LikeEventHandler,
   MentionEventHandler,
   MessageEventHandler,
+  QuoteEventHandler,
   ReactionEventHandler,
   RejectEventHandler,
   ReplyEventHandler,
@@ -137,6 +138,12 @@ export interface Bot<TContextData> {
    */
   onReply?: ReplyEventHandler<TContextData>;
 
+  /**
+   * An event handler for a quote of the bot's message.
+   * @since 0.2.0
+   */
+  onQuote?: QuoteEventHandler<TContextData>;
+
   /**
    * An event handler for a message shown to the bot's timeline.  To listen
    * to this event, your bot needs to follow others first.
@@ -425,6 +432,12 @@ export function createBot<TContextData = void>(
     set onReply(value) {
       bot.onReply = value;
     },
+    get onQuote() {
+      return bot.onQuote;
+    },
+    set onQuote(value) {
+      bot.onQuote = value;
+    },
     get onMessage() {
       return bot.onMessage;
     },

src/events.ts

@@ -85,6 +85,18 @@ export type ReplyEventHandler<TContextData> = (
   reply: Message<MessageClass, TContextData>,
 ) => void | Promise<void>;
 
+/**
+ * An event handler for a quote of the bot's message.
+ * @typeParam TContextData The type of the context data.
+ * @param session The session of the bot.
+ * @param quote The message which quotes the bot's message.
+ * @since 0.2.0
+ */
+export type QuoteEventHandler<TContextData> = (
+  session: Session<TContextData>,
+  quote: Message<MessageClass, TContextData>,
+) => void | Promise<void>;
+
 /**
  * An event handler for a message shown to the bot's timeline.  To listen to
  * this event, your bot needs to follow others first.

src/message-impl.ts

@@ -654,6 +654,7 @@ export async function createMessage<T extends MessageClass, TContextData>(
     } else if (tag instanceof Hashtag) {
       hashtags.push(tag);
     } else if (tag instanceof Link) {
+      // FIXME: eliminate this duplication
       const mediaType = tag.mediaType == null
         ? null
         : parseMediaType(tag.mediaType);