feat(bots): improve mention behavior dx (#4569)

Author: miguel-nascimento

packages/bot/src/bot.test.ts

@@ -24,6 +24,7 @@ import {
     isDefined,
     genIdBlob,
     ParsedEvent,
+    type ChannelMessageEvent,
 } from '@towns-protocol/sdk'
 import { describe, it, expect, beforeAll, vi } from 'vitest'
 import type { BasePayload, Bot, BotPayload, DecryptedInteractionResponse } from './bot'
@@ -744,6 +745,60 @@ describe('Bot', { sequential: true }, () => {
         )
     })
 
+    it('bot can mention bob', async () => {
+        await setForwardSetting(ForwardSettingValue.FORWARD_SETTING_ALL_MESSAGES)
+        const { eventId: messageId } = await bot.sendMessage(channelId, 'Hello @bob', {
+            mentions: [
+                {
+                    userId: bob.userId,
+                    displayName: 'bob',
+                },
+            ],
+        })
+        await waitFor(() =>
+            expect(
+                bobDefaultChannel.timeline.events.value.find((x) => x.eventId === messageId)
+                    ?.content?.kind,
+            ).toBe(RiverTimelineEvent.ChannelMessage),
+        )
+        const channelMessage = bobDefaultChannel.timeline.events.value.find(
+            (x) => x.eventId === messageId,
+        )?.content as ChannelMessageEvent
+
+        expect(channelMessage.mentions).toBeDefined()
+        expect(channelMessage.mentions?.length).toBe(1)
+        expect(channelMessage.mentions?.[0].userId).toBe(bob.userId)
+        expect(channelMessage.mentions?.[0].displayName).toBe('bob')
+    })
+
+    it('bot can mention channel', async () => {
+        await setForwardSetting(ForwardSettingValue.FORWARD_SETTING_ALL_MESSAGES)
+        const { eventId: messageId } = await bot.sendMessage(channelId, 'Hello @channel', {
+            mentions: [{ atChannel: true }],
+        })
+        await waitFor(() =>
+            expect(
+                bobDefaultChannel.timeline.events.value.find((x) => x.eventId === messageId)
+                    ?.content?.kind,
+            ).toBe(RiverTimelineEvent.ChannelMessage),
+        )
+        const channelMessage = bobDefaultChannel.timeline.events.value.find(
+            (x) => x.eventId === messageId,
+        )
+        let channelMessageEvent: ChannelMessageEvent | undefined
+        if (channelMessage?.content?.kind === RiverTimelineEvent.ChannelMessage) {
+            channelMessageEvent = channelMessage.content
+        } else {
+            throw new Error('Message is not a channel message')
+        }
+
+        expect(channelMessageEvent.mentions).toBeDefined()
+        expect(channelMessageEvent.mentions?.length).toBe(1)
+        // @ts-expect-error - types of timeline is wrong
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        expect(channelMessageEvent.mentions?.[0].mentionBehavior?.case).toBe('atChannel')
+    })
+
     it('bot can fetch existing decryption keys when sending a message', async () => {
         // on a fresh boot the bot won't have any keys in cache, so it should fetch them from the app server if they exist
         await setForwardSetting(ForwardSettingValue.FORWARD_SETTING_ALL_MESSAGES)

packages/bot/src/bot.ts

@@ -81,6 +81,7 @@ import {
     ChannelMessage_Post_AttachmentSchema,
     type AppMetadata,
     StreamEvent,
+    ChannelMessage_Post_MentionSchema,
 } from '@towns-protocol/proto'
 import {
     bin_equal,
@@ -118,6 +119,7 @@ import { getSmartAccountFromUserIdImpl } from './smart-account'
 import type { BotIdentityConfig, BotIdentityMetadata, ERC8004Endpoint } from './identity-types'
 import channelsFacetAbi from '@towns-protocol/generated/dev/abis/Channels.abi'
 import rolesFacetAbi from '@towns-protocol/generated/dev/abis/Roles.abi'
+import { EmptySchema } from '@bufbuild/protobuf/wkt'
 
 type BotActions = ReturnType<typeof buildBotActions>
 
@@ -192,7 +194,9 @@ export type MessageOpts = {
 }
 
 export type PostMessageOpts = MessageOpts & {
-    mentions?: PlainMessage<ChannelMessage_Post_Mention>[]
+    mentions?: Array<
+        { userId: string; displayName: string } | { roleId: number } | { atChannel: true }
+    >
     attachments?: Array<
         | ImageAttachment
         | ChunkedMediaAttachment
@@ -1831,7 +1835,7 @@ const buildBotActions = (
                         value: {
                             body: message,
                             attachments: processedAttachments.filter((x) => x !== null),
-                            mentions: opts?.mentions || [],
+                            mentions: processMentions(opts?.mentions),
                         },
                     },
                 },
@@ -1895,7 +1899,7 @@ const buildBotActions = (
                             case: 'text',
                             value: {
                                 body: message,
-                                mentions: opts?.mentions || [],
+                                mentions: processMentions(opts?.mentions),
                                 attachments: processedAttachments.filter((x) => x !== null),
                             },
                         },
@@ -2440,3 +2444,37 @@ const parseMentions = (
             ? [{ userId: m.userId, displayName: m.displayName }]
             : [],
     )
+
+const processMentions = (
+    mentions: PostMessageOpts['mentions'],
+): PlainMessage<ChannelMessage_Post_Mention>[] => {
+    if (!mentions) {
+        return []
+    }
+    return mentions.map((mention) => {
+        if ('userId' in mention) {
+            return create(ChannelMessage_Post_MentionSchema, {
+                userId: mention.userId,
+                displayName: mention.displayName,
+            })
+        } else if ('roleId' in mention) {
+            return create(ChannelMessage_Post_MentionSchema, {
+                mentionBehavior: {
+                    case: 'atRole',
+                    value: {
+                        roleId: mention.roleId,
+                    },
+                },
+            })
+        } else if ('atChannel' in mention) {
+            return create(ChannelMessage_Post_MentionSchema, {
+                mentionBehavior: {
+                    case: 'atChannel',
+                    value: create(EmptySchema, {}),
+                },
+            })
+        } else {
+            throw new Error(`Invalid mention type: ${JSON.stringify(mention)}`)
+        }
+    })
+}