@swarmclawai/swarmclaw 0.4.0 → 0.4.5

package/src/lib/server/connectors/bluebubbles.test.ts

@@ -0,0 +1,208 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import bluebubbles from './bluebubbles.ts'
+
+type FetchCall = {
+  url: string
+  init?: RequestInit
+}
+
+type MockResponse = {
+  ok: boolean
+  status: number
+  json: () => Promise<any>
+  text: () => Promise<string>
+}
+
+function jsonResponse(status: number, body: unknown): MockResponse {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  }
+}
+
+function textResponse(status: number, text: string): MockResponse {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => {
+      throw new Error('not json')
+    },
+    text: async () => text,
+  }
+}
+
+const originalFetch = globalThis.fetch
+
+test.afterEach(() => {
+  ;(globalThis as any).fetch = originalFetch
+})
+
+test('bluebubbles connector processes inbound webhook payloads and sends replies', async () => {
+  const calls: FetchCall[] = []
+  const queue: MockResponse[] = [
+    jsonResponse(200, { ok: true }), // ping
+    jsonResponse(200, { data: { guid: 'msg-1' } }), // send reply
+  ]
+
+  ;(globalThis as any).fetch = async (url: string, init?: RequestInit) => {
+    calls.push({ url: String(url), init })
+    const next = queue.shift()
+    assert.ok(next, 'unexpected fetch call')
+    return next as any
+  }
+
+  const received: any[] = []
+  const connector = {
+    id: 'bb-1',
+    name: 'BlueBubbles Test',
+    platform: 'bluebubbles',
+    agentId: 'agent-1',
+    credentialId: null,
+    config: {
+      serverUrl: 'http://127.0.0.1:1234',
+    },
+    isEnabled: true,
+    status: 'running',
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  } as any
+
+  const instance = await bluebubbles.start(connector, 'pw-test', async (msg) => {
+    received.push(msg)
+    return 'pong'
+  })
+
+  try {
+    const handler = (globalThis as any).__swarmclaw_bluebubbles_handler_bb_1__
+    assert.equal(typeof handler, 'undefined', 'sanity: wrong handler key should be undefined')
+    const validHandler = (globalThis as any)[`__swarmclaw_bluebubbles_handler_${connector.id}__`]
+    assert.equal(typeof validHandler, 'function')
+
+    await validHandler({
+      type: 'new-message',
+      data: {
+        guid: 'm-123',
+        text: 'hello there',
+        isFromMe: false,
+        isGroup: false,
+        handle: { address: '+15551234567', displayName: 'Alice' },
+        chatGuid: 'iMessage;-;+15551234567',
+      },
+    })
+
+    assert.equal(received.length, 1)
+    assert.equal(received[0].text, 'hello there')
+    assert.equal(received[0].senderId, '+15551234567')
+    assert.equal(received[0].channelId, 'iMessage;-;+15551234567')
+
+    assert.equal(calls.length, 2)
+    assert.ok(calls[0].url.includes('/api/v1/ping'))
+    assert.ok(calls[1].url.includes('/api/v1/message/text'))
+
+    const body = JSON.parse(String(calls[1].init?.body || '{}'))
+    assert.equal(body.chatGuid, 'iMessage;-;+15551234567')
+    assert.equal(body.message, 'pong')
+  } finally {
+    await instance.stop()
+  }
+})
+
+test('bluebubbles connector supports array-wrapped webhook payload and NO_MESSAGE suppression', async () => {
+  const calls: FetchCall[] = []
+  const queue: MockResponse[] = [
+    jsonResponse(200, { ok: true }), // ping
+  ]
+
+  ;(globalThis as any).fetch = async (url: string, init?: RequestInit) => {
+    calls.push({ url: String(url), init })
+    const next = queue.shift()
+    assert.ok(next, 'unexpected fetch call')
+    return next as any
+  }
+
+  const connector = {
+    id: 'bb-2',
+    name: 'BlueBubbles Test 2',
+    platform: 'bluebubbles',
+    agentId: 'agent-2',
+    credentialId: null,
+    config: {
+      serverUrl: 'http://127.0.0.1:1234',
+    },
+    isEnabled: true,
+    status: 'running',
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  } as any
+
+  const instance = await bluebubbles.start(connector, 'pw-test', async () => 'NO_MESSAGE')
+
+  try {
+    const handler = (globalThis as any)[`__swarmclaw_bluebubbles_handler_${connector.id}__`]
+    assert.equal(typeof handler, 'function')
+
+    await handler({
+      type: 'new-message',
+      data: [
+        {
+          guid: 'm-124',
+          text: '',
+          isFromMe: false,
+          handle: { address: 'test@example.com', displayName: 'Taylor' },
+          chatGuid: 'iMessage;-;test@example.com',
+          attachments: [{ mimeType: 'image/png', transferName: 'a.png', totalBytes: 128 }],
+        },
+      ],
+    })
+
+    assert.equal(calls.length, 1, 'should not call send endpoint when NO_MESSAGE is returned')
+  } finally {
+    await instance.stop()
+  }
+})
+
+test('bluebubbles sendMessage posts to message/text endpoint', async () => {
+  const calls: FetchCall[] = []
+  const queue: MockResponse[] = [
+    jsonResponse(200, { ok: true }), // ping
+    textResponse(200, ''), // send
+  ]
+
+  ;(globalThis as any).fetch = async (url: string, init?: RequestInit) => {
+    calls.push({ url: String(url), init })
+    const next = queue.shift()
+    assert.ok(next, 'unexpected fetch call')
+    return next as any
+  }
+
+  const connector = {
+    id: 'bb-3',
+    name: 'BlueBubbles Test 3',
+    platform: 'bluebubbles',
+    agentId: 'agent-3',
+    credentialId: null,
+    config: {
+      serverUrl: 'http://127.0.0.1:1234',
+    },
+    isEnabled: true,
+    status: 'running',
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  } as any
+
+  const instance = await bluebubbles.start(connector, 'pw-test', async () => 'ok')
+
+  try {
+    await instance.sendMessage?.('iMessage;-;+15550001111', 'hello outbound')
+    assert.equal(calls.length, 2)
+    assert.ok(calls[1].url.includes('/api/v1/message/text'))
+    const body = JSON.parse(String(calls[1].init?.body || '{}'))
+    assert.equal(body.chatGuid, 'iMessage;-;+15550001111')
+    assert.equal(body.message, 'hello outbound')
+  } finally {
+    await instance.stop()
+  }
+})

package/src/lib/server/connectors/bluebubbles.ts

@@ -0,0 +1,357 @@
+import crypto from 'node:crypto'
+import type { PlatformConnector, ConnectorInstance, InboundMessage, InboundMedia } from './types'
+import { isNoMessage } from './manager'
+
+const DEFAULT_TIMEOUT_MS = 10_000
+const DEFAULT_WEBHOOK_PATH = '/api/connectors/{id}/webhook'
+
+function getErrorMessage(err: unknown): string {
+  if (err instanceof Error && err.message) return err.message
+  return String(err)
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+}
+
+function readString(record: Record<string, unknown> | null, key: string): string | undefined {
+  if (!record) return undefined
+  const value = record[key]
+  return typeof value === 'string' ? value : undefined
+}
+
+function readNumberLike(record: Record<string, unknown> | null, key: string): number | undefined {
+  if (!record) return undefined
+  const value = record[key]
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && value.trim()) {
+    const parsed = Number.parseFloat(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return undefined
+}
+
+function readBoolean(record: Record<string, unknown> | null, key: string): boolean | undefined {
+  if (!record) return undefined
+  const value = record[key]
+  return typeof value === 'boolean' ? value : undefined
+}
+
+function extractPayloadMessage(payload: Record<string, unknown>): Record<string, unknown> | null {
+  const parseRecord = (value: unknown): Record<string, unknown> | null => {
+    const record = asRecord(value)
+    if (record) return record
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        const nested = parseRecord(item)
+        if (nested) return nested
+      }
+      return null
+    }
+    if (typeof value !== 'string') return null
+    const trimmed = value.trim()
+    if (!trimmed) return null
+    try {
+      return parseRecord(JSON.parse(trimmed))
+    } catch {
+      return null
+    }
+  }
+
+  const dataRaw = payload.data ?? payload.payload ?? payload.event
+  const data = parseRecord(dataRaw)
+  const messageRaw = payload.message ?? data?.message ?? data
+  return parseRecord(messageRaw)
+}
+
+function normalizeHandle(value: string): string {
+  return value.trim().toLowerCase()
+}
+
+function extractHandleFromChatGuid(chatGuid: string): string | null {
+  const parts = chatGuid.split(';')
+  if (parts.length < 3) return null
+  const handle = parts[2]?.trim()
+  return handle || null
+}
+
+function resolveGroupFlagFromChatGuid(chatGuid?: string): boolean | undefined {
+  const guid = chatGuid?.trim()
+  if (!guid) return undefined
+  const parts = guid.split(';')
+  if (parts.length >= 3) {
+    if (parts[1] === '+') return true
+    if (parts[1] === '-') return false
+  }
+  if (guid.includes(';+;')) return true
+  if (guid.includes(';-;')) return false
+  return undefined
+}
+
+function normalizeAttachmentType(mimeType?: string): InboundMedia['type'] {
+  const mime = (mimeType || '').trim().toLowerCase()
+  if (mime.startsWith('image/')) return 'image'
+  if (mime.startsWith('video/')) return 'video'
+  if (mime.startsWith('audio/')) return 'audio'
+  if (mime.startsWith('application/')) return 'document'
+  return 'file'
+}
+
+function normalizeAttachments(message: Record<string, unknown>): InboundMedia[] {
+  const raw = message.attachments
+  if (!Array.isArray(raw)) return []
+
+  const output: InboundMedia[] = []
+  for (const item of raw) {
+    const record = asRecord(item)
+    if (!record) continue
+
+    const mimeType = readString(record, 'mimeType') || readString(record, 'mime_type')
+    const fileName = readString(record, 'transferName') || readString(record, 'transfer_name')
+    const sizeBytes = readNumberLike(record, 'totalBytes') || readNumberLike(record, 'total_bytes')
+
+    output.push({
+      type: normalizeAttachmentType(mimeType),
+      mimeType,
+      fileName,
+      sizeBytes,
+    })
+  }
+
+  return output
+}
+
+function parseInboundMessage(payload: Record<string, unknown>): InboundMessage | null {
+  const eventType = readString(payload, 'type')?.trim().toLowerCase() || ''
+  if (eventType && !['new-message', 'created-message', 'message'].includes(eventType)) {
+    return null
+  }
+
+  const message = extractPayloadMessage(payload)
+  if (!message) return null
+
+  const fromMe = readBoolean(message, 'isFromMe') ?? readBoolean(message, 'is_from_me') ?? false
+  if (fromMe) return null
+
+  const text = (
+    readString(message, 'text')
+    || readString(message, 'body')
+    || readString(message, 'subject')
+    || ''
+  ).trim()
+
+  const handle = asRecord(message.handle) || asRecord(message.sender)
+  const rawSenderId = (
+    readString(handle, 'address')
+    || readString(handle, 'handle')
+    || readString(handle, 'id')
+    || readString(message, 'senderId')
+    || readString(message, 'sender')
+    || readString(message, 'from')
+    || ''
+  ).trim()
+
+  const chatGuid = (
+    readString(message, 'chatGuid')
+    || readString(message, 'chat_guid')
+    || ''
+  ).trim()
+
+  const inferredSender = !rawSenderId && chatGuid ? (extractHandleFromChatGuid(chatGuid) || '') : ''
+  const senderId = normalizeHandle(rawSenderId || inferredSender)
+  if (!senderId) return null
+
+  const chatIdentifier = (
+    readString(message, 'chatIdentifier')
+    || readString(message, 'chat_identifier')
+    || ''
+  ).trim()
+  const chatIdNum = readNumberLike(message, 'chatId') || readNumberLike(message, 'chat_id')
+  const chatId = chatGuid || chatIdentifier || (Number.isFinite(chatIdNum) ? String(chatIdNum) : senderId)
+  const channelName = (
+    readString(message, 'chatName')
+    || readString(message, 'displayName')
+    || chatId
+  ).trim()
+
+  const senderName = (
+    readString(handle, 'displayName')
+    || readString(handle, 'name')
+    || readString(message, 'senderName')
+    || senderId
+  ).trim()
+
+  const media = normalizeAttachments(message)
+  const fallbackText = media.length > 0 ? '<media:attachment>' : ''
+
+  const groupFlag = (
+    readBoolean(message, 'isGroup')
+    ?? readBoolean(message, 'is_group')
+    ?? resolveGroupFlagFromChatGuid(chatGuid)
+    ?? false
+  )
+
+  return {
+    platform: 'bluebubbles',
+    channelId: chatId,
+    channelName,
+    senderId,
+    senderName,
+    text: text || fallbackText,
+    media,
+    isGroup: groupFlag,
+  }
+}
+
+function resolveRequestUrl(baseUrl: string, path: string, password: string): string {
+  const base = new URL(baseUrl)
+  const url = new URL(path, base)
+  url.searchParams.set('password', password)
+  return url.toString()
+}
+
+async function fetchJsonWithTimeout(
+  input: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    return await fetch(input, { ...init, signal: controller.signal })
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function parseCsvList(raw: string | undefined): string[] {
+  if (!raw) return []
+  return raw.split(',').map((value) => value.trim()).filter(Boolean)
+}
+
+const bluebubbles: PlatformConnector = {
+  async start(connector, botToken, onMessage): Promise<ConnectorInstance> {
+    const serverUrl = connector.config.serverUrl?.trim()
+    const password = (botToken || connector.config.password || '').trim()
+
+    if (!serverUrl) throw new Error('Missing serverUrl in connector config')
+    if (!password) throw new Error('Missing BlueBubbles password (credential/token)')
+
+    const timeoutMsRaw = Number.parseInt(connector.config.timeoutMs || '', 10)
+    const timeoutMs = Number.isFinite(timeoutMsRaw)
+      ? Math.max(1_000, Math.min(60_000, timeoutMsRaw))
+      : DEFAULT_TIMEOUT_MS
+
+    const allowedChats = new Set(parseCsvList(connector.config.chatIds))
+
+    let stopped = false
+
+    const processWebhookEvent = async (payload: Record<string, unknown>) => {
+      if (stopped) throw new Error('Connector is stopped')
+      const inbound = parseInboundMessage(payload)
+      if (!inbound) return {}
+
+      if (allowedChats.size > 0) {
+        const id = inbound.channelId
+        const name = inbound.channelName || ''
+        const allowed = Array.from(allowedChats).some((needle) => id.includes(needle) || name.includes(needle))
+        if (!allowed) return {}
+      }
+
+      const response = await onMessage(inbound)
+      if (!response || isNoMessage(response)) return {}
+
+      await sendBlueBubblesText({
+        serverUrl,
+        password,
+        channelId: inbound.channelId,
+        text: response,
+        timeoutMs,
+      })
+      return {}
+    }
+
+    const handlerKey = `__swarmclaw_bluebubbles_handler_${connector.id}__`
+    ;(globalThis as any)[handlerKey] = processWebhookEvent
+
+    const pingUrl = resolveRequestUrl(serverUrl, '/api/v1/ping', password)
+    const pingRes = await fetchJsonWithTimeout(pingUrl, { method: 'GET' }, timeoutMs)
+    if (!pingRes.ok) {
+      throw new Error(`BlueBubbles ping failed (${pingRes.status})`)
+    }
+
+    console.log(`[bluebubbles] Connected to ${serverUrl}`)
+    console.log(`[bluebubbles] Inbound webhook endpoint: ${DEFAULT_WEBHOOK_PATH.replace('{id}', connector.id)}`)
+
+    return {
+      connector,
+      async sendMessage(channelId, text) {
+        if (stopped) throw new Error('Connector is stopped')
+        return await sendBlueBubblesText({
+          serverUrl,
+          password,
+          channelId,
+          text,
+          timeoutMs,
+        })
+      },
+      async stop() {
+        stopped = true
+        delete (globalThis as any)[handlerKey]
+        console.log(`[bluebubbles] Connector stopped`)
+      },
+    }
+  },
+}
+
+async function sendBlueBubblesText(params: {
+  serverUrl: string
+  password: string
+  channelId: string
+  text: string
+  timeoutMs: number
+}): Promise<{ messageId?: string }> {
+  const message = params.text.trim()
+  if (!message) return {}
+
+  const channel = params.channelId.trim()
+  if (!channel) throw new Error('BlueBubbles send requires channelId')
+
+  const payload: Record<string, unknown> = {
+    message,
+    tempGuid: crypto.randomUUID(),
+  }
+
+  // For inbound-driven replies we store chat GUID in channelId. If callers pass a phone/email,
+  // BlueBubbles can still attempt routing via chatGuid field when it already matches.
+  payload.chatGuid = channel
+
+  const url = resolveRequestUrl(params.serverUrl, '/api/v1/message/text', params.password)
+  const res = await fetchJsonWithTimeout(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  }, params.timeoutMs)
+
+  if (!res.ok) {
+    const errBody = await res.text().catch(() => '')
+    throw new Error(`BlueBubbles send failed (${res.status}): ${errBody || 'unknown'}`)
+  }
+
+  try {
+    const body = await res.json() as any
+    const id = body?.data?.guid || body?.guid || body?.data?.id || body?.id
+    return { messageId: typeof id === 'string' ? id : undefined }
+  } catch (err) {
+    // BlueBubbles may return empty body on success in some setups.
+    const message = getErrorMessage(err)
+    if (!message.toLowerCase().includes('json')) {
+      console.warn(`[bluebubbles] Unable to parse send response body: ${message}`)
+    }
+    return {}
+  }
+}
+
+export default bluebubbles

package/src/lib/server/connectors/connector-routing.test.ts

@@ -9,7 +9,7 @@ import type { InboundMessage, InboundMedia } from './types.ts'
 // 1. Connector module resolution (getPlatform)
 // ---------------------------------------------------------------------------
 describe('getPlatform — connector module resolution', () => {
-  const newPlatforms = ['matrix', 'googlechat', 'teams', 'signal'] as const
+  const newPlatforms = ['matrix', 'googlechat', 'teams', 'signal', 'bluebubbles'] as const
 
   for (const name of newPlatforms) {
     it(`returns a valid module for "${name}"`, async () => {

package/src/lib/server/connectors/googlechat.ts

@@ -1,7 +1,8 @@
-import type { PlatformConnector, ConnectorInstance } from './types'
+import type { PlatformConnector, ConnectorInstance, InboundMessage } from './types'
+import { isNoMessage } from './manager'
 
 const googlechat: PlatformConnector = {
-  async start(connector, botToken, _onMessage): Promise<ConnectorInstance> {
+  async start(connector, botToken, onMessage): Promise<ConnectorInstance> {
     const pkg = 'googleapis'
     const { google } = await import(/* webpackIgnore: true */ pkg)
 
@@ -25,17 +26,54 @@ const googlechat: PlatformConnector = {
       ? connector.config.spaceIds.split(',').map((s: string) => s.trim()).filter(Boolean)
       : null
 
-    // Google Chat requires a webhook or Pub/Sub for real-time inbound messages.
-    // This connector supports outbound messaging. For inbound messages, configure
-    // a webhook endpoint at /api/connectors/[id]/webhook that POSTs events here.
-    // Polling is not supported by the Google Chat API for bot messages.
+    const handlerKey = `__swarmclaw_googlechat_handler_${connector.id}__`
     let stopped = false
 
     console.log(`[googlechat] Bot authenticated via service account`)
     if (allowedSpaces) {
       console.log(`[googlechat] Filtering to spaces: ${allowedSpaces.join(', ')}`)
     }
-    console.log(`[googlechat] Note: Inbound messages require a webhook or Pub/Sub subscription. This connector supports outbound sends.`)
+    console.log(`[googlechat] Inbound webhook endpoint: /api/connectors/${connector.id}/webhook`)
+
+    function cleanInboundText(raw: unknown): string {
+      const txt = typeof raw === 'string' ? raw : ''
+      // Google Chat mentions often look like <users/123456789>
+      return txt.replace(/<users\/[^>]+>/g, '').trim()
+    }
+
+    async function processWebhookEvent(event: any): Promise<Record<string, unknown>> {
+      if (stopped) throw new Error('Connector is stopped')
+
+      const msg = event?.message
+      if (!msg) return {}
+
+      const spaceName: string = msg?.space?.name || event?.space?.name || ''
+      if (allowedSpaces && !allowedSpaces.some((s) => spaceName.includes(s))) {
+        return {}
+      }
+
+      const rawText = msg?.argumentText || msg?.text || ''
+      const text = cleanInboundText(rawText)
+      if (!text) return {}
+
+      const sender = msg?.sender || event?.user || {}
+      const senderName = sender?.displayName || sender?.name || 'Google Chat User'
+      const senderId = sender?.name || ''
+      const inbound: InboundMessage = {
+        platform: 'googlechat',
+        channelId: spaceName || (msg?.thread?.name || 'space:unknown'),
+        channelName: msg?.space?.displayName || spaceName || 'Google Chat',
+        senderId,
+        senderName,
+        text,
+      }
+
+      const response = await onMessage(inbound)
+      if (!response || isNoMessage(response)) return {}
+      return { text: response }
+    }
+
+    ;(globalThis as any)[handlerKey] = processWebhookEvent
 
     return {
       connector,
@@ -57,6 +95,7 @@ const googlechat: PlatformConnector = {
       },
       async stop() {
         stopped = true
+        delete (globalThis as any)[handlerKey]
         console.log(`[googlechat] Bot disconnected`)
       },
     }