agent-messenger 2.20.5 → 2.22.0

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]
+}

package/src/platforms/webexbot/wdm-discovery.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, it, mock } from 'bun:test'
+
+import { createWdmRewriteFetch, discoverWdmDevicesUrl } from './wdm-discovery'
+
+const realFetch = globalThis.fetch
+
+afterEach(() => {
+  globalThis.fetch = realFetch
+})
+
+function jsonResponse(body: unknown, ok = true, status = 200): Response {
+  return { ok, status, json: () => Promise.resolve(body) } as unknown as Response
+}
+
+describe('discoverWdmDevicesUrl', () => {
+  it('returns the U2C wdm serviceLink with /devices appended', async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(jsonResponse({ serviceLinks: { wdm: 'https://wdm-r.wbx2.com/wdm/api/v1' } })),
+    )
+
+    const url = await discoverWdmDevicesUrl('token123')
+
+    expect(url).toBe('https://wdm-r.wbx2.com/wdm/api/v1/devices')
+  })
+
+  it('strips a trailing slash before appending /devices', async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(jsonResponse({ serviceLinks: { wdm: 'https://wdm-r.wbx2.com/wdm/api/v1/' } })),
+    )
+
+    const url = await discoverWdmDevicesUrl('token123')
+
+    expect(url).toBe('https://wdm-r.wbx2.com/wdm/api/v1/devices')
+  })
+
+  it('throws when the catalog request fails', async () => {
+    globalThis.fetch = mock(() => Promise.resolve(jsonResponse({}, false, 401)))
+
+    await expect(discoverWdmDevicesUrl('bad')).rejects.toThrow('Failed to discover Webex WDM cluster')
+  })
+
+  it('throws when the catalog lacks serviceLinks.wdm', async () => {
+    globalThis.fetch = mock(() => Promise.resolve(jsonResponse({ serviceLinks: {} })))
+
+    await expect(discoverWdmDevicesUrl('token123')).rejects.toThrow('did not include serviceLinks.wdm')
+  })
+})
+
+describe('createWdmRewriteFetch', () => {
+  it('rewrites the hardcoded WDM device-registration URL to the discovered cluster', async () => {
+    const seen: string[] = []
+    globalThis.fetch = mock((url: string) => {
+      seen.push(url)
+      return Promise.resolve(jsonResponse({ ok: true }))
+    })
+
+    const fetchFn = createWdmRewriteFetch('https://wdm-r.wbx2.com/wdm/api/v1/devices')
+    await fetchFn({
+      url: 'https://wdm-a.wbx2.com/wdm/api/v1/devices',
+      method: 'POST',
+      headers: { Authorization: 'Bearer x' },
+      body: '{}',
+    })
+
+    expect(seen[0]).toBe('https://wdm-r.wbx2.com/wdm/api/v1/devices')
+  })
+
+  it('rewrites WDM device sub-paths too', async () => {
+    const seen: string[] = []
+    globalThis.fetch = mock((url: string) => {
+      seen.push(url)
+      return Promise.resolve(jsonResponse({}))
+    })
+
+    const fetchFn = createWdmRewriteFetch('https://wdm-r.wbx2.com/wdm/api/v1/devices')
+    await fetchFn({
+      url: 'https://wdm-a.wbx2.com/wdm/api/v1/devices/abc-123',
+      method: 'DELETE',
+      headers: {},
+    })
+
+    expect(seen[0]).toBe('https://wdm-r.wbx2.com/wdm/api/v1/devices/abc-123')
+  })
+
+  it('leaves non-WDM URLs untouched', async () => {
+    const seen: string[] = []
+    globalThis.fetch = mock((url: string) => {
+      seen.push(url)
+      return Promise.resolve(jsonResponse({}))
+    })
+
+    const fetchFn = createWdmRewriteFetch('https://wdm-r.wbx2.com/wdm/api/v1/devices')
+    await fetchFn({ url: 'https://webexapis.com/v1/people/me', method: 'GET', headers: {} })
+
+    expect(seen[0]).toBe('https://webexapis.com/v1/people/me')
+  })
+})

package/src/platforms/webexbot/wdm-discovery.ts

@@ -0,0 +1,43 @@
+import type { FetchFunction, FetchRequest, FetchResponse } from 'webex-message-handler'
+
+import { WebexBotError } from './types'
+
+const U2C_CATALOG_URL = 'https://u2c.wbx2.com/u2c/api/v1/catalog?format=hostmap'
+const HARDCODED_WDM_DEVICES_URL = 'https://wdm-a.wbx2.com/wdm/api/v1/devices'
+
+// webex-message-handler hardcodes the WDM cluster to wdm-a. A bot whose org lives
+// on another cluster (e.g. wdm-r) registers its device on the wrong cluster, so
+// Webex never routes conversation activities to its Mercury socket — the socket
+// connects but no messages arrive. The U2C catalog returns the correct WDM cluster
+// for the token; rewriting the device-registration request to it makes the bot
+// receive real-time events.
+export async function discoverWdmDevicesUrl(token: string): Promise<string> {
+  const response = await fetch(U2C_CATALOG_URL, { headers: { Authorization: `Bearer ${token}` } })
+  if (!response.ok) {
+    throw new WebexBotError(`Failed to discover Webex WDM cluster: HTTP ${response.status}`, 'wdm_discovery_failed')
+  }
+
+  const catalog = (await response.json()) as { serviceLinks?: { wdm?: string } }
+  const wdm = catalog.serviceLinks?.wdm
+  if (!wdm) {
+    throw new WebexBotError('Webex U2C catalog did not include serviceLinks.wdm', 'wdm_discovery_failed')
+  }
+
+  return `${wdm.replace(/\/$/, '')}/devices`
+}
+
+export function createWdmRewriteFetch(wdmDevicesUrl: string): FetchFunction {
+  return async (req: FetchRequest): Promise<FetchResponse> => {
+    const url = req.url.startsWith(HARDCODED_WDM_DEVICES_URL)
+      ? wdmDevicesUrl + req.url.slice(HARDCODED_WDM_DEVICES_URL.length)
+      : req.url
+
+    const res = await fetch(url, { method: req.method, headers: req.headers, body: req.body })
+    return {
+      status: res.status,
+      ok: res.ok,
+      json: () => res.json(),
+      text: () => res.text(),
+    }
+  }
+}