agent-messenger 2.23.2 → 2.23.4

package/src/platforms/webex/commands/message.test.ts

@@ -11,22 +11,28 @@ const personId = toRestId('person_789', 'PEOPLE')
 
 const mockMessage = {
   id: messageId,
+  ref: 'msg_123',
   roomId,
+  roomRef: 'space_456',
   roomType: 'group' as const,
   text: 'Hello world',
   html: '<p>Hello <a href="https://example.com">world</a></p>',
   personId,
+  personRef: 'person_789',
   personEmail: 'user@example.com',
   created: '2025-01-29T10:00:00.000Z',
 }
 
 const mockMessage2 = {
   id: message2Id,
+  ref: 'msg_124',
   roomId,
+  roomRef: 'space_456',
   roomType: 'group' as const,
   text: 'Second message',
   html: '<p>Second message</p>',
   personId,
+  personRef: 'person_789',
   personEmail: 'user@example.com',
   created: '2025-01-29T10:01:00.000Z',
 }

package/src/platforms/webex/commands/message.ts

@@ -4,15 +4,14 @@ import { handleError } from '@/shared/utils/error-handler'
 import { formatOutput } from '@/shared/utils/output'
 
 import { WebexClient } from '../client'
-import { toRef } from '../id-normalizer'
 import type { WebexMessage } from '../types'
 
 function formatMessageOutput(message: WebexMessage) {
   return {
     id: message.id,
-    ref: toRef(message.id),
+    ref: message.ref,
     roomId: message.roomId,
-    roomRef: toRef(message.roomId),
+    roomRef: message.roomRef,
     text: message.text,
     html: message.html,
     personEmail: message.personEmail,

package/src/platforms/webex/commands/whoami.test.ts

@@ -10,6 +10,7 @@ const personId = toRestId('person-123', 'PEOPLE')
 
 const mockUser = {
   id: personId,
+  ref: 'person-123',
   emails: ['test@example.com'],
   displayName: 'Test User',
   nickName: 'Testy',
@@ -17,6 +18,7 @@ const mockUser = {
   lastName: 'User',
   avatar: 'https://example.com/avatar.jpg',
   orgId,
+  orgRef: 'org-123',
   type: 'person' as const,
   created: '2024-01-01T00:00:00.000Z',
 }

package/src/platforms/webex/commands/whoami.ts

@@ -4,7 +4,6 @@ import { handleError } from '@/shared/utils/error-handler'
 import { formatOutput } from '@/shared/utils/output'
 
 import { WebexClient } from '../client'
-import { toRef } from '../id-normalizer'
 
 export async function whoamiAction(options: { pretty?: boolean }): Promise<void> {
   try {
@@ -13,7 +12,7 @@ export async function whoamiAction(options: { pretty?: boolean }): Promise<void>
 
     const output = {
       id: user.id,
-      ref: toRef(user.id),
+      ref: user.ref,
       emails: user.emails,
       displayName: user.displayName,
       nickName: user.nickName,
@@ -21,7 +20,7 @@ export async function whoamiAction(options: { pretty?: boolean }): Promise<void>
       lastName: user.lastName,
       avatar: user.avatar,
       orgId: user.orgId,
-      orgRef: toRef(user.orgId),
+      orgRef: user.orgRef,
       type: user.type,
     }
     console.log(formatOutput(output, options.pretty))

package/src/platforms/webex/id-normalizer.test.ts

@@ -16,9 +16,13 @@ import {
   normalizeMembership,
   normalizeMessage,
   normalizeRoomActivity,
+  normalizeSdkMembership,
+  normalizeSdkMessage,
+  normalizeSdkPerson,
   toRestId,
   toRef,
 } from './id-normalizer'
+import type { WebexMembership, WebexMessage, WebexPerson } from './types'
 
 const RAW: MercuryActivity = {
   id: 'activity-uuid',
@@ -122,6 +126,23 @@ describe('normalizeMessage', () => {
     expect(result.mentionedPeople).toEqual([toRestId('mention-uuid-1', 'PEOPLE'), toRestId('mention-uuid-2', 'PEOPLE')])
   })
 
+  it('adds a raw uuid ref alongside every id', () => {
+    const result = normalizeMessage(message)
+
+    expect(result.ref).toBe('msg-uuid')
+    expect(result.parentRef).toBe('parent-uuid')
+    expect(result.roomRef).toBe('room-uuid')
+    expect(result.personRef).toBe('person-uuid')
+    expect(result.mentionedPeopleRefs).toEqual(['mention-uuid-1', 'mention-uuid-2'])
+  })
+
+  it('omits parentRef when parentId is absent', () => {
+    const { parentId: _omit, ...withoutParent } = message
+    const result = normalizeMessage(withoutParent)
+
+    expect(result.parentRef).toBeUndefined()
+  })
+
   it('leaves non-id fields and raw untouched', () => {
     const result = normalizeMessage(message)
 
@@ -157,8 +178,11 @@ describe('normalizeDeletedMessage', () => {
 
     expect(normalizeDeletedMessage(deleted)).toEqual({
       messageId: toRestId('msg-uuid', 'MESSAGE'),
+      messageRef: 'msg-uuid',
       roomId: toRestId('room-uuid', 'ROOM'),
+      roomRef: 'room-uuid',
       personId: toRestId('person-uuid', 'PEOPLE'),
+      personRef: 'person-uuid',
     })
   })
 })
@@ -183,6 +207,25 @@ describe('normalizeMembership', () => {
     expect(result.roomId).toBe(toRestId('room-uuid', 'ROOM'))
     expect(result.raw).toBe(RAW)
   })
+
+  it('sets ref to the raw activity id and adds refs for the rest', () => {
+    const membership: MembershipActivity = {
+      id: 'activity-uuid',
+      actorId: 'actor-uuid',
+      personId: 'member-uuid',
+      roomId: 'room-uuid',
+      action: 'add',
+      created: '2024-01-01T00:00:00Z',
+      raw: RAW,
+    }
+
+    const result = normalizeMembership(membership)
+
+    expect(result.ref).toBe('activity-uuid')
+    expect(result.actorRef).toBe('actor-uuid')
+    expect(result.personRef).toBe('member-uuid')
+    expect(result.roomRef).toBe('room-uuid')
+  })
 })
 
 describe('normalizeAttachmentAction', () => {
@@ -207,7 +250,27 @@ describe('normalizeAttachmentAction', () => {
     expect(result.inputs).toEqual({ choice: 'yes' })
   })
 
-  it('preserves an empty messageId', () => {
+  it('adds a raw uuid ref alongside every id', () => {
+    const action: AttachmentAction = {
+      id: 'action-uuid',
+      messageId: 'msg-uuid',
+      personId: 'person-uuid',
+      personEmail: 'user@example.com',
+      roomId: 'room-uuid',
+      inputs: { choice: 'yes' },
+      created: '2024-01-01T00:00:00Z',
+      raw: RAW,
+    }
+
+    const result = normalizeAttachmentAction(action)
+
+    expect(result.ref).toBe('action-uuid')
+    expect(result.messageRef).toBe('msg-uuid')
+    expect(result.personRef).toBe('person-uuid')
+    expect(result.roomRef).toBe('room-uuid')
+  })
+
+  it('preserves an empty messageId and its ref', () => {
     const action: AttachmentAction = {
       id: 'action-uuid',
       messageId: '',
@@ -219,7 +282,9 @@ describe('normalizeAttachmentAction', () => {
       raw: RAW,
     }
 
-    expect(normalizeAttachmentAction(action).messageId).toBe('')
+    const result = normalizeAttachmentAction(action)
+    expect(result.messageId).toBe('')
+    expect(result.messageRef).toBe('')
   })
 })
 
@@ -241,4 +306,182 @@ describe('normalizeRoomActivity', () => {
     expect(result.actorId).toBe(toRestId('actor-uuid', 'PEOPLE'))
     expect(result.raw).toBe(RAW)
   })
+
+  it('sets ref to the raw activity id and adds refs for the rest', () => {
+    const room: RoomActivity = {
+      id: 'activity-uuid',
+      roomId: 'room-uuid',
+      actorId: 'actor-uuid',
+      action: 'created',
+      created: '2024-01-01T00:00:00Z',
+      raw: RAW,
+    }
+
+    const result = normalizeRoomActivity(room)
+
+    expect(result.ref).toBe('activity-uuid')
+    expect(result.roomRef).toBe('room-uuid')
+    expect(result.actorRef).toBe('actor-uuid')
+  })
+})
+
+describe('normalizeSdkPerson', () => {
+  const person: WebexPerson = {
+    id: restId('PEOPLE', 'person-uuid'),
+    ref: '',
+    emails: ['user@example.com'],
+    displayName: 'User',
+    orgId: restId('ORGANIZATION', 'org-uuid'),
+    orgRef: '',
+    type: 'person',
+    created: '2024-01-01T00:00:00Z',
+  }
+
+  it('decodes the bot identity id and orgId into raw uuid refs', () => {
+    const result = normalizeSdkPerson(person)
+
+    expect(result.ref).toBe('person-uuid')
+    expect(result.orgRef).toBe('org-uuid')
+  })
+
+  it('does not re-encode the already-REST ids', () => {
+    const result = normalizeSdkPerson(person)
+
+    expect(result.id).toBe(restId('PEOPLE', 'person-uuid'))
+    expect(result.orgId).toBe(restId('ORGANIZATION', 'org-uuid'))
+  })
+
+  it('leaves empty ids and refs empty', () => {
+    const result = normalizeSdkPerson({ ...person, id: '', orgId: '' })
+
+    expect(result.ref).toBe('')
+    expect(result.orgRef).toBe('')
+  })
+
+  it('returns a new object without mutating the input', () => {
+    const result = normalizeSdkPerson(person)
+
+    expect(result).not.toBe(person)
+    expect(person.ref).toBe('')
+  })
+})
+
+describe('normalizeSdkMessage', () => {
+  const message: WebexMessage = {
+    id: restId('MESSAGE', 'msg-uuid'),
+    ref: '',
+    roomId: restId('ROOM', 'room-uuid'),
+    roomRef: '',
+    roomType: 'group',
+    text: 'hello',
+    personId: restId('PEOPLE', 'person-uuid'),
+    personRef: '',
+    personEmail: 'user@example.com',
+    created: '2024-01-01T00:00:00Z',
+    parentId: restId('MESSAGE', 'parent-uuid'),
+    mentionedPeople: [restId('PEOPLE', 'mention-1'), restId('PEOPLE', 'mention-2')],
+  }
+
+  it('decodes id, roomId, personId and parentId into raw uuid refs', () => {
+    const result = normalizeSdkMessage(message)
+
+    expect(result.ref).toBe('msg-uuid')
+    expect(result.roomRef).toBe('room-uuid')
+    expect(result.personRef).toBe('person-uuid')
+    expect(result.parentRef).toBe('parent-uuid')
+  })
+
+  it('adds a mentionedPeopleRefs array of raw uuids', () => {
+    const result = normalizeSdkMessage(message)
+
+    expect(result.mentionedPeopleRefs).toEqual(['mention-1', 'mention-2'])
+  })
+
+  it('omits parentRef when parentId is absent', () => {
+    const { parentId: _omit, ...withoutParent } = message
+    const result = normalizeSdkMessage(withoutParent)
+
+    expect(result.parentRef).toBeUndefined()
+  })
+
+  it('omits mentionedPeopleRefs when mentionedPeople is absent', () => {
+    const { mentionedPeople: _omit, ...withoutMentions } = message
+    const result = normalizeSdkMessage(withoutMentions)
+
+    expect(result.mentionedPeopleRefs).toBeUndefined()
+  })
+
+  it('does not re-encode the already-REST ids', () => {
+    const result = normalizeSdkMessage(message)
+
+    expect(result.id).toBe(restId('MESSAGE', 'msg-uuid'))
+    expect(result.roomId).toBe(restId('ROOM', 'room-uuid'))
+  })
+})
+
+describe('normalizeSdkMembership', () => {
+  const membership: WebexMembership = {
+    id: restId('MEMBERSHIP', 'membership-uuid'),
+    ref: '',
+    roomId: restId('ROOM', 'room-uuid'),
+    roomRef: '',
+    personId: restId('PEOPLE', 'person-uuid'),
+    personRef: '',
+    personEmail: 'user@example.com',
+    personDisplayName: 'User',
+    isModerator: false,
+    created: '2024-01-01T00:00:00Z',
+  }
+
+  it('decodes id, roomId and personId into raw uuid refs', () => {
+    const result = normalizeSdkMembership(membership)
+
+    expect(result.ref).toBe('membership-uuid')
+    expect(result.roomRef).toBe('room-uuid')
+    expect(result.personRef).toBe('person-uuid')
+  })
+
+  it('does not re-encode the already-REST ids', () => {
+    const result = normalizeSdkMembership(membership)
+
+    expect(result.id).toBe(restId('MEMBERSHIP', 'membership-uuid'))
+    expect(result.personId).toBe(restId('PEOPLE', 'person-uuid'))
+  })
+})
+
+describe('SDK and event refs agree for the same person', () => {
+  it('matches the bot identity ref against an event mention ref so self/mention detection holds', () => {
+    const personUuid = 'bot-person-uuid'
+
+    // given: the bot identity from a REST response (testAuth path)
+    const bot = normalizeSdkPerson({
+      id: restId('PEOPLE', personUuid),
+      ref: '',
+      emails: ['bot@webex.bot'],
+      displayName: 'Bot',
+      orgId: restId('ORGANIZATION', 'org-uuid'),
+      orgRef: '',
+      type: 'bot',
+      created: '2024-01-01T00:00:00Z',
+    })
+
+    // when: an event carries the same person as a raw Mercury uuid
+    const event = normalizeMessage({
+      id: 'msg-uuid',
+      roomId: 'room-uuid',
+      personId: personUuid,
+      personEmail: 'bot@webex.bot',
+      text: 'hi',
+      created: '2024-01-01T00:00:00Z',
+      mentionedPeople: [personUuid],
+      mentionedGroups: [],
+      files: [],
+      raw: RAW,
+    })
+
+    // then: both paths decode to the same raw uuid ref
+    expect(bot.ref).toBe(personUuid)
+    expect(event.personRef).toBe(personUuid)
+    expect(event.mentionedPeopleRefs.includes(bot.ref)).toBe(true)
+  })
 })

package/src/platforms/webex/id-normalizer.ts

@@ -7,6 +7,17 @@ import type {
   RoomActivity,
 } from 'webex-message-handler'
 
+import type {
+  WebexAttachmentActionEvent,
+  WebexDeletedMessageEvent,
+  WebexMembership,
+  WebexMembershipEvent,
+  WebexMessage,
+  WebexMessageEvent,
+  WebexPerson,
+  WebexRoomEvent,
+} from './types'
+
 export { fromRestId }
 
 // Superset of webex-message-handler's toRestId union, which omits ATTACHMENT_ACTION
@@ -20,7 +31,9 @@ export interface DecodedWebexId {
 }
 
 export function toRef(id: string): string {
-  if (!id) return id
+  // fromRestId throws on values that are not base64-encoded ciscospark ids; fail
+  // open so a non-REST id (legacy/sentinel) yields the id itself instead of crashing.
+  if (!id || !decodeWebexId(id)) return id
   return fromRestId(id)
 }
 
@@ -47,51 +60,118 @@ export function toRestId(uuid: string, type: WebexRestIdType): string {
   return Buffer.from(`ciscospark://us/${type}/${uuid}`).toString('base64url')
 }
 
-export function normalizeMessage(message: DecryptedMessage): DecryptedMessage {
+export function normalizeMessage(message: DecryptedMessage): WebexMessageEvent {
+  const id = toRestId(message.id, 'MESSAGE')
+  const parentId = message.parentId ? toRestId(message.parentId, 'MESSAGE') : message.parentId
+  const roomId = toRestId(message.roomId, 'ROOM')
+  const personId = toRestId(message.personId, 'PEOPLE')
+  const mentionedPeople = message.mentionedPeople.map((person) => toRestId(person, 'PEOPLE'))
   return {
     ...message,
-    id: toRestId(message.id, 'MESSAGE'),
-    parentId: message.parentId ? toRestId(message.parentId, 'MESSAGE') : message.parentId,
-    roomId: toRestId(message.roomId, 'ROOM'),
-    personId: toRestId(message.personId, 'PEOPLE'),
-    mentionedPeople: message.mentionedPeople.map((id) => toRestId(id, 'PEOPLE')),
+    id,
+    ref: toRef(id),
+    parentId,
+    parentRef: parentId ? toRef(parentId) : parentId,
+    roomId,
+    roomRef: toRef(roomId),
+    personId,
+    personRef: toRef(personId),
+    mentionedPeople,
+    mentionedPeopleRefs: mentionedPeople.map(toRef),
   }
 }
 
-export function normalizeDeletedMessage(message: DeletedMessage): DeletedMessage {
+export function normalizeDeletedMessage(message: DeletedMessage): WebexDeletedMessageEvent {
+  const messageId = toRestId(message.messageId, 'MESSAGE')
+  const roomId = toRestId(message.roomId, 'ROOM')
+  const personId = toRestId(message.personId, 'PEOPLE')
   return {
-    messageId: toRestId(message.messageId, 'MESSAGE'),
-    roomId: toRestId(message.roomId, 'ROOM'),
-    personId: toRestId(message.personId, 'PEOPLE'),
+    messageId,
+    messageRef: toRef(messageId),
+    roomId,
+    roomRef: toRef(roomId),
+    personId,
+    personRef: toRef(personId),
   }
 }
 
-export function normalizeMembership(activity: MembershipActivity): MembershipActivity {
-  // `id` stays raw: it is a Mercury activity UUID, not a REST membership ID.
+export function normalizeMembership(activity: MembershipActivity): WebexMembershipEvent {
+  // `id` stays raw: it is a Mercury activity UUID, not a REST membership ID, so
+  // its ref is the id itself rather than a decoded REST id.
+  const actorId = toRestId(activity.actorId, 'PEOPLE')
+  const personId = toRestId(activity.personId, 'PEOPLE')
+  const roomId = toRestId(activity.roomId, 'ROOM')
   return {
     ...activity,
-    actorId: toRestId(activity.actorId, 'PEOPLE'),
-    personId: toRestId(activity.personId, 'PEOPLE'),
-    roomId: toRestId(activity.roomId, 'ROOM'),
+    ref: activity.id,
+    actorId,
+    actorRef: toRef(actorId),
+    personId,
+    personRef: toRef(personId),
+    roomId,
+    roomRef: toRef(roomId),
   }
 }
 
-export function normalizeAttachmentAction(action: AttachmentAction): AttachmentAction {
+export function normalizeAttachmentAction(action: AttachmentAction): WebexAttachmentActionEvent {
+  const id = toRestId(action.id, 'ATTACHMENT_ACTION')
+  const messageId = action.messageId ? toRestId(action.messageId, 'MESSAGE') : action.messageId
+  const personId = toRestId(action.personId, 'PEOPLE')
+  const roomId = toRestId(action.roomId, 'ROOM')
   return {
     ...action,
-    id: toRestId(action.id, 'ATTACHMENT_ACTION'),
-    messageId: action.messageId ? toRestId(action.messageId, 'MESSAGE') : action.messageId,
-    personId: toRestId(action.personId, 'PEOPLE'),
-    roomId: toRestId(action.roomId, 'ROOM'),
+    id,
+    ref: toRef(id),
+    messageId,
+    messageRef: toRef(messageId),
+    personId,
+    personRef: toRef(personId),
+    roomId,
+    roomRef: toRef(roomId),
   }
 }
 
-export function normalizeRoomActivity(activity: RoomActivity): RoomActivity {
-  // `id` stays raw: the Mercury conversation activity UUID has no
-  // consumer-facing REST resource (the comparable REST ID is `roomId`).
+export function normalizeRoomActivity(activity: RoomActivity): WebexRoomEvent {
+  // `id` stays raw: the Mercury conversation activity UUID has no consumer-facing
+  // REST resource, so its ref is the id itself (the comparable REST id is `roomId`).
+  const roomId = toRestId(activity.roomId, 'ROOM')
+  const actorId = toRestId(activity.actorId, 'PEOPLE')
   return {
     ...activity,
-    roomId: toRestId(activity.roomId, 'ROOM'),
-    actorId: toRestId(activity.actorId, 'PEOPLE'),
+    ref: activity.id,
+    roomId,
+    roomRef: toRef(roomId),
+    actorId,
+    actorRef: toRef(actorId),
+  }
+}
+
+// SDK REST responses (people/messages/memberships) already carry REST-encoded ids,
+// so unlike the event normalizers above we only attach raw uuid refs — no re-encoding.
+export function normalizeSdkPerson(person: WebexPerson): WebexPerson {
+  return {
+    ...person,
+    ref: toRef(person.id),
+    orgRef: toRef(person.orgId),
+  }
+}
+
+export function normalizeSdkMessage(message: WebexMessage): WebexMessage {
+  return {
+    ...message,
+    ref: toRef(message.id),
+    roomRef: toRef(message.roomId),
+    personRef: toRef(message.personId),
+    parentRef: message.parentId ? toRef(message.parentId) : message.parentId,
+    mentionedPeopleRefs: message.mentionedPeople?.map(toRef),
+  }
+}
+
+export function normalizeSdkMembership(membership: WebexMembership): WebexMembership {
+  return {
+    ...membership,
+    ref: toRef(membership.id),
+    roomRef: toRef(membership.roomId),
+    personRef: toRef(membership.personId),
   }
 }

package/src/platforms/webex/index.ts

@@ -9,7 +9,19 @@ export type { PasswordLoginOptions, PasswordLoginResult } from './password-login
 export { WebexTokenExtractor } from './token-extractor'
 export type { ExtractedWebexToken } from './token-extractor'
 export { WebexError } from './types'
-export type { WebexConfig, WebexMembership, WebexMessage, WebexPerson, WebexSpace } from './types'
+export type {
+  WebexAttachmentActionEvent,
+  WebexConfig,
+  WebexDeletedMessageEvent,
+  WebexMembership,
+  WebexMembershipEvent,
+  WebexMessage,
+  WebexMessageEvent,
+  WebexPerson,
+  WebexRealtimeEvent,
+  WebexRoomEvent,
+  WebexSpace,
+} from './types'
 export {
   WebexConfigSchema,
   WebexMembershipSchema,

package/src/platforms/webex/listener.test.ts

@@ -81,8 +81,11 @@ describe('WebexListener', () => {
 
     const expected = expect.objectContaining({
       id: toRestId('message-123', 'MESSAGE'),
+      ref: 'message-123',
       roomId: toRestId('room-123', 'ROOM'),
+      roomRef: 'room-123',
       personId: toRestId('person-123', 'PEOPLE'),
+      personRef: 'person-123',
       personEmail: 'user@example.com',
       text: 'hello',
       raw: RAW_ACTIVITY,

package/src/platforms/webex/listener.ts

@@ -21,6 +21,14 @@ import {
   normalizeMessage,
   normalizeRoomActivity,
 } from './id-normalizer'
+import type {
+  WebexAttachmentActionEvent,
+  WebexDeletedMessageEvent,
+  WebexMembershipEvent,
+  WebexMessageEvent,
+  WebexRealtimeEvent,
+  WebexRoomEvent,
+} from './types'
 import { createWdmRewriteFetch, discoverWdmDevicesUrl } from './wdm-discovery'
 
 type EventKey = keyof WebexListenerEventMap
@@ -49,14 +57,14 @@ export interface WebexListenerOptions {
 }
 
 export interface WebexListenerEventMap {
-  message_created: [event: DecryptedMessage]
-  message_updated: [event: DecryptedMessage]
-  message_deleted: [event: DeletedMessage]
-  membership_created: [event: MembershipActivity]
-  attachment_action: [event: AttachmentAction]
-  room_created: [event: RoomActivity]
-  room_updated: [event: RoomActivity]
-  webex_event: [event: DecryptedMessage | DeletedMessage | MembershipActivity | AttachmentAction | RoomActivity]
+  message_created: [event: WebexMessageEvent]
+  message_updated: [event: WebexMessageEvent]
+  message_deleted: [event: WebexDeletedMessageEvent]
+  membership_created: [event: WebexMembershipEvent]
+  attachment_action: [event: WebexAttachmentActionEvent]
+  room_created: [event: WebexRoomEvent]
+  room_updated: [event: WebexRoomEvent]
+  webex_event: [event: WebexRealtimeEvent]
   connected: [info: { connected: boolean; status: HandlerStatus }]
   reconnecting: [attempt: number]
   disconnected: [reason: string]