agent-messenger 2.20.4 → 2.21.0

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

@@ -0,0 +1,234 @@
+import { describe, expect, it, mock } from 'bun:test'
+import { EventEmitter } from 'events'
+
+import type {
+  DecryptedMessage,
+  HandlerStatus,
+  MercuryActivity,
+  WebexMessageHandlerConfig,
+  WebexMessageHandlerEvents,
+} from 'webex-message-handler'
+
+import { WebexBotListener } 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('WebexBotListener', () => {
+  it('bridges handler message events and webex_event', async () => {
+    const handler = new FakeWebexMessageHandler()
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexBotListener(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)
+
+    expect(messageCreated).toHaveBeenCalledWith(MESSAGE)
+    expect(webexEvent).toHaveBeenCalledWith(MESSAGE)
+  })
+
+  it('stop calls handler disconnect', async () => {
+    const handler = new FakeWebexMessageHandler()
+    const client = { getToken: () => 'token123' }
+    const listener = new WebexBotListener(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 WebexBotListener(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 WebexBotListener(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 WebexBotListener(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 WebexBotListener(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 WebexBotListener(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 WebexBotListener(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 WebexBotListener(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 WebexBotListener(client, {
+      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+    })
+
+    const starting = listener.start()
+    const stopping = listener.stop()
+    resolveConnect()
+    await Promise.all([starting, stopping])
+
+    expect(handler.disconnect).toHaveBeenCalled()
+  })
+})

package/src/platforms/webexbot/listener.ts

@@ -0,0 +1,255 @@
+import { EventEmitter } from 'events'
+
+import { WebexMessageHandler } from 'webex-message-handler'
+import type {
+  AttachmentAction,
+  DecryptedMessage,
+  DeletedMessage,
+  HandlerStatus,
+  InjectedWebSocket,
+  MembershipActivity,
+  RoomActivity,
+  WebexMessageHandlerConfig,
+  WebexMessageHandlerEvents,
+} from 'webex-message-handler'
+import WebSocket from 'ws'
+
+import type { WebexBotClient } from './client'
+import type { WebexBotListenerEventMap } from './types'
+import { createWdmRewriteFetch, discoverWdmDevicesUrl } from './wdm-discovery'
+
+type EventKey = keyof WebexBotListenerEventMap
+type WebexBotClientLike = Pick<WebexBotClient, 'getToken'>
+
+interface WebexMessageHandlerLike {
+  connect(): Promise<void>
+  disconnect(): Promise<void>
+  status(): HandlerStatus
+  get connected(): boolean
+  on<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this
+  off<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this
+  once<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this
+}
+
+export interface WebexBotListenerOptions {
+  ignoreSelfMessages?: boolean
+  pingInterval?: number
+  pongTimeout?: number
+  reconnectBackoffMax?: number
+  maxReconnectAttempts?: number
+  _handlerFactory?: (config: WebexMessageHandlerConfig) => WebexMessageHandlerLike
+}
+
+export class WebexBotListener {
+  private client: WebexBotClientLike
+  private options: WebexBotListenerOptions
+  private running = false
+  private emitter = new EventEmitter()
+  private handler: WebexMessageHandlerLike | null = null
+  private generation = 0
+  private detachHandler: (() => void) | null = null
+  private startPromise: Promise<void> | null = null
+
+  constructor(client: WebexBotClientLike, options: WebexBotListenerOptions = {}) {
+    this.client = client
+    this.options = options
+  }
+
+  async start(): Promise<void> {
+    if (this.startPromise) return this.startPromise
+    if (this.running) return
+
+    this.running = true
+    const generation = ++this.generation
+
+    let startPromise!: Promise<void>
+    startPromise = (async () => {
+      let handler: WebexMessageHandlerLike | null = null
+      try {
+        handler = await this.createHandler()
+
+        if (!this.running || this.generation !== generation) {
+          await handler.disconnect().catch(() => undefined)
+          return
+        }
+        this.handler = handler
+        this.detachHandler = this.wireHandler(handler, generation)
+
+        await handler.connect()
+
+        if (!this.running || this.handler !== handler || this.generation !== generation) {
+          await handler.disconnect().catch(() => undefined)
+          return
+        }
+      } catch (error) {
+        if (this.handler === handler && this.generation === generation) {
+          this.detachHandler?.()
+          this.detachHandler = null
+          this.handler = null
+        }
+        if (this.generation === generation) {
+          this.running = false
+        }
+        await handler?.disconnect().catch(() => undefined)
+        throw error
+      } finally {
+        if (this.startPromise === startPromise) {
+          this.startPromise = null
+        }
+      }
+    })()
+
+    this.startPromise = startPromise
+    return startPromise
+  }
+
+  async stop(): Promise<void> {
+    const pendingStart = this.startPromise
+    this.startPromise = null
+
+    this.running = false
+    this.generation++
+
+    const detach = this.detachHandler
+    this.detachHandler = null
+    detach?.()
+
+    const handler = this.handler
+    this.handler = null
+    if (handler) {
+      await handler.disconnect().catch(() => undefined)
+    }
+
+    if (pendingStart) {
+      await pendingStart.catch(() => undefined)
+    }
+  }
+
+  on<K extends EventKey>(event: K, listener: (...args: WebexBotListenerEventMap[K]) => void): this {
+    this.emitter.on(event, listener as (...args: any[]) => void)
+    return this
+  }
+
+  off<K extends EventKey>(event: K, listener: (...args: WebexBotListenerEventMap[K]) => void): this {
+    this.emitter.off(event, listener as (...args: any[]) => void)
+    return this
+  }
+
+  once<K extends EventKey>(event: K, listener: (...args: WebexBotListenerEventMap[K]) => void): this {
+    this.emitter.once(event, listener as (...args: any[]) => void)
+    return this
+  }
+
+  private isCurrent(handler: WebexMessageHandlerLike, generation: number): boolean {
+    return this.running && this.handler === handler && this.generation === generation
+  }
+
+  // Node's EventEmitter throws synchronously if an 'error' event is emitted with
+  // no registered listener. Guard it so SDK consumers that only subscribe to
+  // message events are never crashed by a transient connection error.
+  private emitError(error: Error): void {
+    if (this.emitter.listenerCount('error') > 0) {
+      this.emitter.emit('error', error)
+    }
+  }
+
+  private async createHandler(): Promise<WebexMessageHandlerLike> {
+    const token = this.client.getToken()
+    const config: WebexMessageHandlerConfig = { token }
+    if (this.options.ignoreSelfMessages !== undefined) config.ignoreSelfMessages = this.options.ignoreSelfMessages
+    if (this.options.pingInterval !== undefined) config.pingInterval = this.options.pingInterval
+    if (this.options.pongTimeout !== undefined) config.pongTimeout = this.options.pongTimeout
+    if (this.options.reconnectBackoffMax !== undefined) config.reconnectBackoffMax = this.options.reconnectBackoffMax
+    if (this.options.maxReconnectAttempts !== undefined) config.maxReconnectAttempts = this.options.maxReconnectAttempts
+
+    if (this.options._handlerFactory) {
+      return this.options._handlerFactory(config)
+    }
+
+    const wdmDevicesUrl = await discoverWdmDevicesUrl(token)
+    config.mode = 'injected'
+    config.fetch = createWdmRewriteFetch(wdmDevicesUrl)
+    config.webSocketFactory = (url: string) => new WebSocket(url) as unknown as InjectedWebSocket
+    return new WebexMessageHandler(config)
+  }
+
+  private wireHandler(handler: WebexMessageHandlerLike, generation: number): () => void {
+    const onMessageCreated = (event: DecryptedMessage) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('message_created', event)
+      this.emitter.emit('webex_event', event)
+    }
+    const onMessageUpdated = (event: DecryptedMessage) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('message_updated', event)
+      this.emitter.emit('webex_event', event)
+    }
+    const onMessageDeleted = (event: DeletedMessage) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('message_deleted', event)
+      this.emitter.emit('webex_event', event)
+    }
+    const onMembershipCreated = (event: MembershipActivity) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('membership_created', event)
+      this.emitter.emit('webex_event', event)
+    }
+    const onAttachmentAction = (event: AttachmentAction) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('attachment_action', event)
+      this.emitter.emit('webex_event', event)
+    }
+    const onRoomCreated = (event: RoomActivity) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('room_created', event)
+      this.emitter.emit('webex_event', event)
+    }
+    const onRoomUpdated = (event: RoomActivity) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('room_updated', event)
+      this.emitter.emit('webex_event', event)
+    }
+    const onConnected = () => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('connected', { connected: handler.connected, status: handler.status() })
+    }
+    const onReconnecting = (attempt: number) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('reconnecting', attempt)
+    }
+    const onDisconnected = (reason: string) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitter.emit('disconnected', reason)
+    }
+    const onError = (error: Error) => {
+      if (!this.isCurrent(handler, generation)) return
+      this.emitError(error)
+    }
+
+    handler.on('message:created', onMessageCreated)
+    handler.on('message:updated', onMessageUpdated)
+    handler.on('message:deleted', onMessageDeleted)
+    handler.on('membership:created', onMembershipCreated)
+    handler.on('attachmentAction:created', onAttachmentAction)
+    handler.on('room:created', onRoomCreated)
+    handler.on('room:updated', onRoomUpdated)
+    handler.on('connected', onConnected)
+    handler.on('reconnecting', onReconnecting)
+    handler.on('disconnected', onDisconnected)
+    handler.on('error', onError)
+
+    return () => {
+      handler.off('message:created', onMessageCreated)
+      handler.off('message:updated', onMessageUpdated)
+      handler.off('message:deleted', onMessageDeleted)
+      handler.off('membership:created', onMembershipCreated)
+      handler.off('attachmentAction:created', onAttachmentAction)
+      handler.off('room:created', onRoomCreated)
+      handler.off('room:updated', onRoomUpdated)
+      handler.off('connected', onConnected)
+      handler.off('reconnecting', onReconnecting)
+      handler.off('disconnected', onDisconnected)
+      handler.off('error', onError)
+    }
+  }
+}

package/src/platforms/webexbot/types.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'bun:test'
+
+import { WebexBotConfigSchema, WebexBotCredentialsSchema, WebexBotEntrySchema, WebexBotError } from './types'
+
+describe('WebexBotError', () => {
+  it('creates error with message and code', () => {
+    const error = new WebexBotError('Test error', 'TEST_CODE')
+    expect(error.message).toBe('Test error')
+    expect(error.code).toBe('TEST_CODE')
+    expect(error.name).toBe('WebexBotError')
+  })
+})
+
+describe('WebexBotEntrySchema', () => {
+  it('validates correct bot entry', () => {
+    const data = {
+      bot_id: 'bot123',
+      bot_name: 'My Bot',
+      token: 'token123',
+    }
+
+    const result = WebexBotEntrySchema.safeParse(data)
+
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects missing token', () => {
+    const data = {
+      bot_id: 'bot123',
+      bot_name: 'My Bot',
+    }
+
+    const result = WebexBotEntrySchema.safeParse(data)
+
+    expect(result.success).toBe(false)
+  })
+})
+
+describe('WebexBotConfigSchema', () => {
+  it('validates correct config with bots', () => {
+    const data = {
+      current: { bot_id: 'bot123' },
+      bots: {
+        bot123: {
+          bot_id: 'bot123',
+          bot_name: 'My Bot',
+          token: 'token123',
+        },
+      },
+    }
+
+    const result = WebexBotConfigSchema.safeParse(data)
+
+    expect(result.success).toBe(true)
+  })
+
+  it('validates config with null current', () => {
+    const result = WebexBotConfigSchema.safeParse({ current: null, bots: {} })
+
+    expect(result.success).toBe(true)
+  })
+})
+
+describe('WebexBotCredentialsSchema', () => {
+  it('validates credentials with required fields', () => {
+    const data = {
+      token: 'token123',
+      bot_id: 'bot123',
+      bot_name: 'My Bot',
+    }
+
+    const result = WebexBotCredentialsSchema.safeParse(data)
+
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects missing bot_id', () => {
+    const data = {
+      token: 'token123',
+      bot_name: 'My Bot',
+    }
+
+    const result = WebexBotCredentialsSchema.safeParse(data)
+
+    expect(result.success).toBe(false)
+  })
+})

package/src/platforms/webexbot/types.ts

@@ -0,0 +1,72 @@
+import type {
+  AttachmentAction,
+  DecryptedMessage,
+  DeletedMessage,
+  HandlerStatus,
+  MembershipActivity,
+  RoomActivity,
+} from 'webex-message-handler'
+import { z } from 'zod'
+
+export interface WebexBotEntry {
+  bot_id: string
+  bot_name: string
+  token: string
+}
+
+export interface WebexBotConfig {
+  current: { bot_id: string } | null
+  bots: Record<string, WebexBotEntry>
+}
+
+export interface WebexBotCredentials {
+  token: string
+  bot_id: string
+  bot_name: string
+}
+
+export class WebexBotError extends Error {
+  code: string
+
+  constructor(message: string, code: string) {
+    super(message)
+    this.name = 'WebexBotError'
+    this.code = code
+  }
+}
+
+export const WebexBotEntrySchema = z.object({
+  bot_id: z.string(),
+  bot_name: z.string(),
+  token: z.string(),
+})
+
+export const WebexBotConfigSchema = z.object({
+  current: z
+    .object({
+      bot_id: z.string(),
+    })
+    .nullable(),
+  bots: z.record(z.string(), WebexBotEntrySchema),
+})
+
+export const WebexBotCredentialsSchema = z.object({
+  token: z.string(),
+  bot_id: z.string(),
+  bot_name: z.string(),
+})
+
+export interface WebexBotListenerEventMap {
+  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]
+  connected: [info: { connected: boolean; status: HandlerStatus }]
+  reconnecting: [attempt: number]
+  disconnected: [reason: string]
+  error: [error: Error]
+}