agent-messenger 2.22.0 → 2.23.0

package/src/platforms/webex/credential-manager.test.ts

@@ -326,6 +326,46 @@ describe('WebexCredentialManager', () => {
     globalThis.fetch = originalFetch
   })
 
+  it('getToken refreshes password tokens with stored web credentials', async () => {
+    const originalFetch = globalThis.fetch
+    let capturedBody = ''
+    globalThis.fetch = mock((_url: string, init?: RequestInit) => {
+      capturedBody = String(init?.body ?? '')
+      return Promise.resolve(
+        new Response(
+          JSON.stringify({
+            access_token: 'refreshed-password-token',
+            refresh_token: 'new-password-refresh',
+            expires_in: 3600,
+          }),
+          { status: 200 },
+        ),
+      )
+    }) as typeof fetch
+
+    await credManager.saveConfig({
+      accessToken: 'expired-password-token',
+      refreshToken: 'password-refresh',
+      expiresAt: Date.now() - 1000,
+      tokenType: 'password',
+      clientId: 'fake-client-id',
+      clientSecret: 'fake-client-secret',
+    })
+
+    const token = await credManager.getToken()
+    const params = new URLSearchParams(capturedBody)
+
+    expect(token).toBe('refreshed-password-token')
+    expect(params.get('client_id')).toBe('fake-client-id')
+    expect(params.get('client_secret')).toBe('fake-client-secret')
+
+    const config = await credManager.loadConfig()
+    expect(config?.tokenType).toBe('password')
+    expect(config?.accessToken).toBe('refreshed-password-token')
+
+    globalThis.fetch = originalFetch
+  })
+
   it('getToken returns expired extracted token when refresh fails', async () => {
     const originalFetch = globalThis.fetch
     globalThis.fetch = mock(() =>

package/src/platforms/webex/credential-manager.ts

@@ -51,12 +51,15 @@ export class WebexCredentialManager {
 
     const isExpired = config.expiresAt > 0 && config.expiresAt < Date.now() + 5 * 60 * 1000
 
-    if (config.tokenType === 'extracted') {
+    if (config.tokenType === 'extracted' || config.tokenType === 'password') {
       if (isExpired && config.refreshToken) {
-        const builtinCreds = getWebexAppCredentials()
-        const refreshed = await this.refreshToken(config.refreshToken, builtinCreds.clientId, builtinCreds.clientSecret)
+        const builtinCreds = config.tokenType === 'password' ? null : getWebexAppCredentials()
+        const resolvedClientId = config.clientId ?? builtinCreds?.clientId
+        const resolvedClientSecret = config.clientSecret ?? builtinCreds?.clientSecret
+        if (!resolvedClientId || !resolvedClientSecret) return null
+        const refreshed = await this.refreshToken(config.refreshToken, resolvedClientId, resolvedClientSecret)
         if (refreshed) {
-          await this.saveConfig({ ...config, ...refreshed, tokenType: 'extracted' })
+          await this.saveConfig({ ...config, ...refreshed, tokenType: config.tokenType })
           return refreshed.accessToken
         }
       }

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

@@ -0,0 +1,207 @@
+import { describe, expect, it } from 'bun:test'
+
+import type {
+  AttachmentAction,
+  DecryptedMessage,
+  DeletedMessage,
+  MembershipActivity,
+  MercuryActivity,
+  RoomActivity,
+} from 'webex-message-handler'
+
+import {
+  fromRestId,
+  normalizeAttachmentAction,
+  normalizeDeletedMessage,
+  normalizeMembership,
+  normalizeMessage,
+  normalizeRoomActivity,
+  toRestId,
+} from './id-normalizer'
+
+const RAW: MercuryActivity = {
+  id: 'activity-uuid',
+  verb: 'post',
+  actor: { id: 'person-uuid', objectType: 'person', emailAddress: 'user@example.com' },
+  object: { id: 'object-uuid', objectType: 'comment', displayName: 'hi' },
+  target: { id: 'room-uuid', objectType: 'conversation' },
+  published: '2024-01-01T00:00:00Z',
+}
+
+describe('toRestId / fromRestId', () => {
+  it('encodes a uuid into a ciscospark REST id round-trippable to the uuid', () => {
+    const restId = toRestId('abc-123', 'PEOPLE')
+    expect(Buffer.from(restId, 'base64').toString('utf-8')).toBe('ciscospark://us/PEOPLE/abc-123')
+    expect(fromRestId(restId)).toBe('abc-123')
+  })
+
+  it('supports ATTACHMENT_ACTION which the upstream helper omits', () => {
+    expect(Buffer.from(toRestId('a-1', 'ATTACHMENT_ACTION'), 'base64').toString('utf-8')).toBe(
+      'ciscospark://us/ATTACHMENT_ACTION/a-1',
+    )
+  })
+
+  it('emits unpadded base64url ids matching the Webex REST API', () => {
+    // 36-char UUID -> 59-byte URI, which exposes the padding bug; a URI length
+    // that is a multiple of 3 produces no padding and would hide the regression.
+    const uuid = '12345678-1234-1234-1234-1234567890ab'
+    const restId = toRestId(uuid, 'PEOPLE')
+
+    expect(restId).toBe(Buffer.from(`ciscospark://us/PEOPLE/${uuid}`).toString('base64url'))
+    expect(restId).not.toContain('=')
+    expect(restId).not.toMatch(/[+/]/)
+    expect(fromRestId(restId)).toBe(uuid)
+  })
+
+  it('returns empty input unchanged', () => {
+    expect(toRestId('', 'MESSAGE')).toBe('')
+  })
+})
+
+describe('normalizeMessage', () => {
+  const message: DecryptedMessage = {
+    id: 'msg-uuid',
+    parentId: 'parent-uuid',
+    roomId: 'room-uuid',
+    personId: 'person-uuid',
+    personEmail: 'user@example.com',
+    text: 'hello',
+    html: '<p>hello</p>',
+    created: '2024-01-01T00:00:00Z',
+    roomType: 'group',
+    mentionedPeople: ['mention-uuid-1', 'mention-uuid-2'],
+    mentionedGroups: ['all'],
+    files: ['https://files.example.com/a.png'],
+    raw: RAW,
+  }
+
+  it('encodes message, room, person and mention ids to REST form', () => {
+    const result = normalizeMessage(message)
+
+    expect(result.id).toBe(toRestId('msg-uuid', 'MESSAGE'))
+    expect(result.parentId).toBe(toRestId('parent-uuid', 'MESSAGE'))
+    expect(result.roomId).toBe(toRestId('room-uuid', 'ROOM'))
+    expect(result.personId).toBe(toRestId('person-uuid', 'PEOPLE'))
+    expect(result.mentionedPeople).toEqual([toRestId('mention-uuid-1', 'PEOPLE'), toRestId('mention-uuid-2', 'PEOPLE')])
+  })
+
+  it('leaves non-id fields and raw untouched', () => {
+    const result = normalizeMessage(message)
+
+    expect(result.mentionedGroups).toEqual(['all'])
+    expect(result.files).toEqual(['https://files.example.com/a.png'])
+    expect(result.personEmail).toBe('user@example.com')
+    expect(result.text).toBe('hello')
+    expect(result.raw).toBe(RAW)
+  })
+
+  it('returns a new object without mutating the input', () => {
+    const result = normalizeMessage(message)
+
+    expect(result).not.toBe(message)
+    expect(message.personId).toBe('person-uuid')
+  })
+
+  it('preserves an absent parentId', () => {
+    const { parentId: _omit, ...withoutParent } = message
+    const result = normalizeMessage(withoutParent)
+
+    expect(result.parentId).toBeUndefined()
+  })
+})
+
+describe('normalizeDeletedMessage', () => {
+  it('encodes messageId, roomId and personId to REST form', () => {
+    const deleted: DeletedMessage = {
+      messageId: 'msg-uuid',
+      roomId: 'room-uuid',
+      personId: 'person-uuid',
+    }
+
+    expect(normalizeDeletedMessage(deleted)).toEqual({
+      messageId: toRestId('msg-uuid', 'MESSAGE'),
+      roomId: toRestId('room-uuid', 'ROOM'),
+      personId: toRestId('person-uuid', 'PEOPLE'),
+    })
+  })
+})
+
+describe('normalizeMembership', () => {
+  it('encodes person and room ids but leaves the activity id raw', () => {
+    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.id).toBe('activity-uuid')
+    expect(result.actorId).toBe(toRestId('actor-uuid', 'PEOPLE'))
+    expect(result.personId).toBe(toRestId('member-uuid', 'PEOPLE'))
+    expect(result.roomId).toBe(toRestId('room-uuid', 'ROOM'))
+    expect(result.raw).toBe(RAW)
+  })
+})
+
+describe('normalizeAttachmentAction', () => {
+  it('encodes the action id as ATTACHMENT_ACTION and the resource ids to REST form', () => {
+    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.id).toBe(toRestId('action-uuid', 'ATTACHMENT_ACTION'))
+    expect(result.messageId).toBe(toRestId('msg-uuid', 'MESSAGE'))
+    expect(result.personId).toBe(toRestId('person-uuid', 'PEOPLE'))
+    expect(result.roomId).toBe(toRestId('room-uuid', 'ROOM'))
+    expect(result.inputs).toEqual({ choice: 'yes' })
+  })
+
+  it('preserves an empty messageId', () => {
+    const action: AttachmentAction = {
+      id: 'action-uuid',
+      messageId: '',
+      personId: 'person-uuid',
+      personEmail: 'user@example.com',
+      roomId: 'room-uuid',
+      inputs: {},
+      created: '2024-01-01T00:00:00Z',
+      raw: RAW,
+    }
+
+    expect(normalizeAttachmentAction(action).messageId).toBe('')
+  })
+})
+
+describe('normalizeRoomActivity', () => {
+  it('encodes room and actor ids but leaves the activity id raw', () => {
+    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.id).toBe('activity-uuid')
+    expect(result.roomId).toBe(toRestId('room-uuid', 'ROOM'))
+    expect(result.actorId).toBe(toRestId('actor-uuid', 'PEOPLE'))
+    expect(result.raw).toBe(RAW)
+  })
+})

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

@@ -0,0 +1,76 @@
+import { fromRestId } from 'webex-message-handler'
+import type {
+  AttachmentAction,
+  DecryptedMessage,
+  DeletedMessage,
+  MembershipActivity,
+  RoomActivity,
+} from 'webex-message-handler'
+
+export { fromRestId }
+
+// Superset of webex-message-handler's toRestId union, which omits ATTACHMENT_ACTION
+// (the resource type behind GET /v1/attachment/actions).
+export type WebexRestIdType = 'MESSAGE' | 'PEOPLE' | 'ROOM' | 'ATTACHMENT_ACTION'
+
+/**
+ * Encode a raw Mercury UUID as a Webex REST ID. Empty input is returned unchanged
+ * so an absent ID never becomes a bogus `ciscospark://us/{TYPE}/` value.
+ *
+ * Webex REST IDs are unpadded base64url. Padded base64 (trailing `=`) would not
+ * equal the ID the REST API returns for the same resource (e.g. the bot's own
+ * `/people/me` id), silently breaking equality checks such as mention detection.
+ */
+export function toRestId(uuid: string, type: WebexRestIdType): string {
+  if (!uuid) return uuid
+  return Buffer.from(`ciscospark://us/${type}/${uuid}`).toString('base64url')
+}
+
+export function normalizeMessage(message: DecryptedMessage): DecryptedMessage {
+  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')),
+  }
+}
+
+export function normalizeDeletedMessage(message: DeletedMessage): DeletedMessage {
+  return {
+    messageId: toRestId(message.messageId, 'MESSAGE'),
+    roomId: toRestId(message.roomId, 'ROOM'),
+    personId: toRestId(message.personId, 'PEOPLE'),
+  }
+}
+
+export function normalizeMembership(activity: MembershipActivity): MembershipActivity {
+  // `id` stays raw: it is a Mercury activity UUID, not a REST membership ID.
+  return {
+    ...activity,
+    actorId: toRestId(activity.actorId, 'PEOPLE'),
+    personId: toRestId(activity.personId, 'PEOPLE'),
+    roomId: toRestId(activity.roomId, 'ROOM'),
+  }
+}
+
+export function normalizeAttachmentAction(action: AttachmentAction): AttachmentAction {
+  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'),
+  }
+}
+
+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`).
+  return {
+    ...activity,
+    roomId: toRestId(activity.roomId, 'ROOM'),
+    actorId: toRestId(activity.actorId, 'PEOPLE'),
+  }
+}

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

@@ -15,6 +15,12 @@ describe('webex barrel exports', () => {
     expect(webex.WebexError).toBeDefined()
   })
 
+  it('exports WebexListener', () => {
+    expect(webex.WebexListener).toBeDefined()
+    expect(webex.toRestId).toBeDefined()
+    expect(webex.fromRestId).toBeDefined()
+  })
+
   it('exports Zod schemas', () => {
     expect(webex.WebexSpaceSchema).toBeDefined()
     expect(webex.WebexMessageSchema).toBeDefined()

package/src/platforms/webex/index.ts

@@ -1,5 +1,9 @@
 export { WebexClient } from './client'
 export { WebexCredentialManager } from './credential-manager'
+export { fromRestId, toRestId } from './id-normalizer'
+export type { WebexRestIdType } from './id-normalizer'
+export { WebexListener } from './listener'
+export type { WebexListenerClient, WebexListenerEventMap, WebexListenerOptions } from './listener'
 export { WebexTokenExtractor } from './token-extractor'
 export type { ExtractedWebexToken } from './token-extractor'
 export { WebexError } from './types'

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

@@ -0,0 +1,243 @@
+import { describe, expect, it, mock } from 'bun:test'
+import { EventEmitter } from 'events'
+
+import type {
+  DecryptedMessage,
+  HandlerStatus,
+  MercuryActivity,
+  WebexMessageHandlerConfig,
+  WebexMessageHandlerEvents,
+} from 'webex-message-handler'
+
+import { toRestId } from './id-normalizer'
+import { WebexListener } from './listener'
+
+const STATUS: HandlerStatus = {
+  status: 'connected',
+  webSocketOpen: true,
+  kmsInitialized: true,
+  deviceRegistered: true,
+  reconnectAttempt: 0,
+}
+
+const RAW_ACTIVITY: MercuryActivity = {
+  id: 'activity-123',
+  verb: 'post',
+  actor: { id: 'person-123', objectType: 'person', emailAddress: 'user@example.com' },
+  object: { id: 'object-123', objectType: 'comment', displayName: 'hello' },
+  target: { id: 'room-123', objectType: 'conversation' },
+  published: '2024-01-01T00:00:00Z',
+}
+
+const MESSAGE: DecryptedMessage = {
+  id: 'message-123',
+  roomId: 'room-123',
+  personId: 'person-123',
+  personEmail: 'user@example.com',
+  text: 'hello',
+  created: '2024-01-01T00:00:00Z',
+  mentionedPeople: [],
+  mentionedGroups: [],
+  files: [],
+  raw: RAW_ACTIVITY,
+}
+
+class FakeWebexMessageHandler extends EventEmitter {
+  connect = mock(() => Promise.resolve())
+  disconnect = mock(() => Promise.resolve())
+  connected = true
+
+  status(): HandlerStatus {
+    return STATUS
+  }
+
+  override on<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this {
+    return super.on(event, listener)
+  }
+
+  override off<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this {
+    return super.off(event, listener)
+  }
+
+  override once<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this {
+    return super.once(event, listener)
+  }
+}
+
+describe('WebexListener', () => {
+  it('bridges handler message events and webex_event', async () => {
+    const handler = new FakeWebexMessageHandler()
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+    })
+    const messageCreated = mock((_event: DecryptedMessage) => undefined)
+    const webexEvent = mock((_event: DecryptedMessage) => undefined)
+    listener.on('message_created', messageCreated)
+    listener.on('webex_event', webexEvent)
+
+    await listener.start()
+    handler.emit('message:created', MESSAGE)
+
+    const expected = expect.objectContaining({
+      id: toRestId('message-123', 'MESSAGE'),
+      roomId: toRestId('room-123', 'ROOM'),
+      personId: toRestId('person-123', 'PEOPLE'),
+      personEmail: 'user@example.com',
+      text: 'hello',
+      raw: RAW_ACTIVITY,
+    })
+    expect(messageCreated).toHaveBeenCalledWith(expected)
+    expect(webexEvent).toHaveBeenCalledWith(expected)
+  })
+
+  it('stop calls handler disconnect', async () => {
+    const handler = new FakeWebexMessageHandler()
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+    })
+
+    await listener.start()
+    await listener.stop()
+
+    expect(handler.disconnect).toHaveBeenCalled()
+  })
+
+  it('start is idempotent', async () => {
+    const handler = new FakeWebexMessageHandler()
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+    })
+
+    await listener.start()
+    await listener.start()
+
+    expect(handler.connect).toHaveBeenCalledTimes(1)
+  })
+
+  it('start rethrows and resets state when connect fails, allowing retry', async () => {
+    const failing = new FakeWebexMessageHandler()
+    failing.connect = mock(() => Promise.reject(new Error('device registration failed')))
+    const ok = new FakeWebexMessageHandler()
+    const handlers = [failing, ok]
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handlers.shift()!,
+    })
+
+    await expect(listener.start()).rejects.toThrow('device registration failed')
+    expect(failing.disconnect).toHaveBeenCalled()
+
+    await listener.start()
+    expect(ok.connect).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not throw when handler emits error with no error listener', async () => {
+    const handler = new FakeWebexMessageHandler()
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+    })
+    listener.on('message_created', () => undefined)
+
+    await listener.start()
+
+    expect(() => handler.emit('error', new Error('boom'))).not.toThrow()
+  })
+
+  it('ignores stale handler events after stop', async () => {
+    const handler = new FakeWebexMessageHandler()
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+    })
+    const messageCreated = mock((_event: DecryptedMessage) => undefined)
+    listener.on('message_created', messageCreated)
+
+    await listener.start()
+    await listener.stop()
+    handler.emit('message:created', MESSAGE)
+
+    expect(messageCreated).not.toHaveBeenCalled()
+  })
+
+  it('start-stop-start does not cross-talk between handlers', async () => {
+    const first = new FakeWebexMessageHandler()
+    const second = new FakeWebexMessageHandler()
+    const handlers = [first, second]
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handlers.shift()!,
+    })
+    const messageCreated = mock((_event: DecryptedMessage) => undefined)
+    listener.on('message_created', messageCreated)
+
+    await listener.start()
+    await listener.stop()
+    await listener.start()
+
+    first.emit('message:created', MESSAGE)
+    expect(messageCreated).not.toHaveBeenCalled()
+
+    second.emit('message:created', MESSAGE)
+    expect(messageCreated).toHaveBeenCalledTimes(1)
+  })
+
+  it('preserves disconnected reason', async () => {
+    const handler = new FakeWebexMessageHandler()
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+    })
+    const disconnected = mock((_reason: string) => undefined)
+    listener.on('disconnected', disconnected)
+
+    await listener.start()
+    handler.emit('disconnected', 'network lost')
+
+    expect(disconnected).toHaveBeenCalledWith('network lost')
+  })
+
+  it('concurrent start() calls share the same connect failure', async () => {
+    const handler = new FakeWebexMessageHandler()
+    handler.connect = mock(() => Promise.reject(new Error('connect failed')))
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+    })
+
+    const first = listener.start()
+    const second = listener.start()
+    const firstResult = first.then(
+      () => 'ok',
+      (e: Error) => e.message,
+    )
+    const secondResult = second.then(
+      () => 'ok',
+      (e: Error) => e.message,
+    )
+
+    expect(await firstResult).toBe('connect failed')
+    expect(await secondResult).toBe('connect failed')
+    expect(handler.connect).toHaveBeenCalledTimes(1)
+  })
+
+  it('disconnects a handler whose connect resolves after stop', async () => {
+    const handler = new FakeWebexMessageHandler()
+    let resolveConnect: () => void = () => undefined
+    handler.connect = mock(() => new Promise<void>((resolve) => (resolveConnect = resolve)))
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+    })
+
+    const starting = listener.start()
+    const stopping = listener.stop()
+    resolveConnect()
+    await Promise.all([starting, stopping])
+
+    expect(handler.disconnect).toHaveBeenCalled()
+  })
+})