@folotoy/folotoy-openclaw-plugin 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# @folotoy/folotoy-openclaw-plugin
+
+FoloToy channel plugin for [OpenClaw](https://openclaw.ai). Bridges FoloToy smart toys with OpenClaw via MQTT, allowing users to interact with OpenClaw through their FoloToy devices.
+
+```
+FoloToy 玩具  <──MQTT──>  FoloToy MQTT Broker  <──MQTT──>  This Plugin  <──>  OpenClaw
+```
+
+## Installation
+
+```bash
+openclaw plugins install @folotoy/folotoy-openclaw-plugin
+```
+
+Or install locally for development:
+
+```bash
+openclaw plugins install -l .
+```
+
+## Configuration
+
+The plugin supports two authentication flows.
+
+### Flow 2: Direct SN + Key (Default)
+
+Configure your toy SN and key directly:
+
+| Field | Description |
+|-------|-------------|
+| `auth.flow` | `"direct"` |
+| `auth.toy_sn` | Toy serial number |
+| `auth.toy_key` | Toy key (used as MQTT password) |
+| `mqtt.host` | MQTT broker host (default: `192.168.10.138`) |
+| `mqtt.port` | MQTT broker port (default: `1883`) |
+
+### Flow 1: HTTP API Login
+
+Exchange an API key for MQTT credentials via the FoloToy API:
+
+| Field | Description |
+|-------|-------------|
+| `auth.flow` | `"api"` |
+| `auth.api_url` | FoloToy API base URL, e.g. `https://api.folotoy.com` |
+| `auth.api_key` | Bearer token |
+| `auth.toy_sn` | Toy serial number |
+| `mqtt.host` | MQTT broker host |
+| `mqtt.port` | MQTT broker port (default: `1883`) |
+
+## MQTT
+
+Both inbound and outbound messages use the same topic:
+
+```
+/openapi/folotoy/{sn}/thing/data/post
+```
+
+The plugin connects to the MQTT broker with an `openapi:` prefix on the username to distinguish itself from the toy's own connection:
+
+```
+username: openapi:{toy_sn}
+password: {toy_key}
+```
+
+## Message Format
+
+**Toy → Plugin (inbound)**
+
+```json
+{
+  "msgId": 1,
+  "identifier": "chat_input",
+  "outParams": {
+    "text": "hello"
+  }
+}
+```
+
+**Plugin → Toy (outbound)**
+
+Single response message with `msgId` matching the inbound request:
+
+```json
+{
+  "msgId": 1,
+  "identifier": "chat_output",
+  "outParams": {
+    "content": "hello"
+  }
+}
+```
+
+## Environments
+
+| Environment | MQTT Host | Port |
+|-------------|-----------|------|
+| Development | `192.168.10.138` | 1883 |
+| Testing | `f.qrc92.cn` | 1883 |
+| Production | `f.folotoy.cn` | 1883 |
+
+Switch environments via the `FOLOTOY_MQTT_HOST` environment variable.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```

package/openclaw.plugin.json

@@ -0,0 +1,5 @@
+{
+  "id": "folotoy",
+  "type": "channel",
+  "channels": ["folotoy"]
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@folotoy/folotoy-openclaw-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw channel plugin for FoloToy smart toys via MQTT",
+  "keywords": [
+    "folotoy",
+    "openclaw"
+  ],
+  "homepage": "https://github.com/FoloToy/folotoy-openclaw-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/FoloToy/folotoy-openclaw-plugin/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FoloToy/folotoy-openclaw-plugin.git"
+  },
+  "license": "MIT",
+  "author": "Larry Wang",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "mqtt": "^5.10.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "openclaw": "^2026.3.8",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.7"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "channel": {
+      "id": "folotoy",
+      "label": "FoloToy",
+      "selectionLabel": "FoloToy",
+      "docsPath": "/channels/folotoy",
+      "blurb": "Connect FoloToy smart toys via MQTT."
+    }
+  }
+}

package/src/__tests__/channel.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi } from 'vitest'
+import { EventEmitter } from 'events'
+import { buildTopic } from '../mqtt.js'
+
+// Replicate the message parsing logic from index.ts for unit testing
+type InboundMessage = {
+  msgId: number
+  identifier: 'chat_input'
+  outParams: { text: string }
+}
+
+type OutboundMessage = {
+  msgId: number
+  identifier: 'chat_output'
+  outParams: { content: string }
+}
+
+function makeMockClient() {
+  const emitter = new EventEmitter()
+  return Object.assign(emitter, {
+    subscribe: vi.fn((_topic: string, cb: (err: null) => void) => cb(null)),
+    publish: vi.fn(),
+  })
+}
+
+function setupSubscriber(client: ReturnType<typeof makeMockClient>, toy_sn: string, onMessage: (msgId: number, text: string) => void) {
+  const topic = buildTopic(toy_sn)
+  client.subscribe(topic, () => {})
+  client.on('message', (_topic: string, payload: Buffer) => {
+    if (_topic !== topic) return
+    try {
+      const msg = JSON.parse(payload.toString()) as InboundMessage
+      if (msg.identifier !== 'chat_input' || typeof msg.outParams?.text !== 'string') return
+      onMessage(msg.msgId, msg.outParams.text)
+    } catch {
+      // ignore
+    }
+  })
+}
+
+describe('inbound message parsing', () => {
+  const toy_sn = 'SN001'
+  const topic = buildTopic(toy_sn)
+
+  it('calls onMessage with msgId and text on valid chat_input', () => {
+    const client = makeMockClient()
+    const onMessage = vi.fn()
+    setupSubscriber(client, toy_sn, onMessage)
+
+    const msg: InboundMessage = { msgId: 42, identifier: 'chat_input', outParams: { text: 'hello' } }
+    client.emit('message', topic, Buffer.from(JSON.stringify(msg)))
+
+    expect(onMessage).toHaveBeenCalledWith(42, 'hello')
+  })
+
+  it('ignores messages on other topics', () => {
+    const client = makeMockClient()
+    const onMessage = vi.fn()
+    setupSubscriber(client, toy_sn, onMessage)
+
+    const msg: InboundMessage = { msgId: 1, identifier: 'chat_input', outParams: { text: 'hi' } }
+    client.emit('message', '/openapi/folotoy/OTHER/thing/data/post', Buffer.from(JSON.stringify(msg)))
+
+    expect(onMessage).not.toHaveBeenCalled()
+  })
+
+  it('ignores messages with unknown identifier', () => {
+    const client = makeMockClient()
+    const onMessage = vi.fn()
+    setupSubscriber(client, toy_sn, onMessage)
+
+    client.emit('message', topic, Buffer.from(JSON.stringify({ msgId: 1, identifier: 'other', outParams: { text: 'hi' } })))
+
+    expect(onMessage).not.toHaveBeenCalled()
+  })
+
+  it('ignores malformed JSON', () => {
+    const client = makeMockClient()
+    const onMessage = vi.fn()
+    setupSubscriber(client, toy_sn, onMessage)
+
+    client.emit('message', topic, Buffer.from('not json'))
+
+    expect(onMessage).not.toHaveBeenCalled()
+  })
+})
+
+describe('outbound message format', () => {
+  const toy_sn = 'SN001'
+  const topic = buildTopic(toy_sn)
+
+  it('publishes chat_output with correct msgId and content', () => {
+    const client = makeMockClient()
+    const msgId = 42
+    const content = 'world'
+    const outMsg: OutboundMessage = {
+      msgId,
+      identifier: 'chat_output',
+      outParams: { content },
+    }
+    client.publish(topic, JSON.stringify(outMsg))
+
+    expect(client.publish).toHaveBeenCalledOnce()
+    const [t, payload] = client.publish.mock.calls[0] as [string, string]
+    expect(t).toBe(topic)
+    expect(JSON.parse(payload)).toEqual({ msgId: 42, identifier: 'chat_output', outParams: { content: 'world' } })
+  })
+})

package/src/__tests__/mqtt.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from 'vitest'
+import { buildTopic } from '../mqtt.js'
+
+describe('buildTopic', () => {
+  it('builds the correct topic for a given SN', () => {
+    expect(buildTopic('SN001')).toBe('/openapi/folotoy/SN001/thing/data/post')
+  })
+})

package/src/config.ts

@@ -0,0 +1,23 @@
+export type AuthFlow1Config = {
+  flow: 'api'
+  api_url: string
+  api_key: string
+  toy_sn: string
+}
+
+export type AuthFlow2Config = {
+  flow: 'direct'
+  toy_sn: string
+  toy_key: string
+}
+
+export type PluginConfig = {
+  auth: AuthFlow1Config | AuthFlow2Config
+  mqtt: {
+    host: string
+    port: number
+  }
+}
+
+export const DEFAULT_MQTT_HOST = process.env.FOLOTOY_MQTT_HOST ?? '198.19.249.25'
+export const DEFAULT_MQTT_PORT = 1883

package/src/index.ts

@@ -0,0 +1,197 @@
+import type { OpenClawPluginApi, ChannelPlugin } from 'openclaw/plugin-sdk/core'
+import { resolveCredentials, createMqttClient, buildTopic } from './mqtt.js'
+import { DEFAULT_MQTT_HOST, DEFAULT_MQTT_PORT } from './config.js'
+import type { PluginConfig } from './config.js'
+import type { MqttClient } from 'mqtt'
+
+type FoloToyAccount = PluginConfig
+
+type InboundMessage = {
+  msgId: number
+  identifier: 'chat_input'
+  outParams: { text: string }
+}
+
+type OutboundMessage = {
+  msgId: number
+  identifier: 'chat_output'
+  outParams: { content: string }
+}
+
+// Per-account MQTT clients, kept for proactive outbound sends
+const activeClients = new Map<string, { client: MqttClient; toy_sn: string }>()
+
+const folotoyChannel: ChannelPlugin<FoloToyAccount> = {
+  id: 'folotoy',
+  meta: {
+    id: 'folotoy',
+    label: 'FoloToy',
+    selectionLabel: 'FoloToy',
+    docsPath: '/channels/folotoy',
+    blurb: 'Connect FoloToy smart toys via MQTT.',
+  },
+  capabilities: {
+    chatTypes: ['direct'],
+  },
+  configSchema: {
+    schema: {
+      type: 'object',
+      properties: {
+        auth: {
+          type: 'object',
+          oneOf: [
+            {
+              title: 'Flow 2: SN + Key (Default)',
+              properties: {
+                flow: { type: 'string', const: 'direct' },
+                toy_sn: { type: 'string' },
+                toy_key: { type: 'string' },
+              },
+              required: ['flow', 'toy_sn', 'toy_key'],
+            },
+            {
+              title: 'Flow 1: HTTP API Login',
+              properties: {
+                flow: { type: 'string', const: 'api' },
+                api_url: { type: 'string' },
+                api_key: { type: 'string' },
+                toy_sn: { type: 'string' },
+              },
+              required: ['flow', 'api_url', 'api_key', 'toy_sn'],
+            },
+          ],
+          default: { flow: 'direct' },
+        },
+        mqtt: {
+          type: 'object',
+          properties: {
+            host: { type: 'string', default: DEFAULT_MQTT_HOST },
+            port: { type: 'number', default: DEFAULT_MQTT_PORT },
+          },
+        },
+      },
+      required: ['auth'],
+    },
+    uiHints: {
+      'auth.toy_sn': { label: 'Toy SN' },
+      'auth.toy_key': { label: 'Toy Key', sensitive: true },
+      'auth.api_url': { label: 'API URL', placeholder: 'https://api.folotoy.com' },
+      'auth.api_key': { label: 'API Key', sensitive: true },
+      'mqtt.host': { label: 'MQTT Host', placeholder: DEFAULT_MQTT_HOST },
+      'mqtt.port': { label: 'MQTT Port' },
+    },
+  },
+  config: {
+    listAccountIds: (cfg) => {
+      const accounts = (cfg as Record<string, unknown> & { channels?: { folotoy?: { accounts?: Record<string, unknown> } } })
+        .channels?.folotoy?.accounts ?? {}
+      return Object.keys(accounts)
+    },
+    resolveAccount: (cfg, accountId) => {
+      const accounts = (cfg as Record<string, unknown> & { channels?: { folotoy?: { accounts?: Record<string, FoloToyAccount> } } })
+        .channels?.folotoy?.accounts ?? {}
+      return accounts[accountId ?? 'default'] ?? ({} as FoloToyAccount)
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const { account, cfg, accountId, abortSignal, channelRuntime, log } = ctx
+
+      if (!channelRuntime) {
+        log?.warn?.('channelRuntime not available — skipping MQTT connection')
+        return
+      }
+
+      const mqttConfig: PluginConfig = {
+        auth: account.auth,
+        mqtt: {
+          host: account.mqtt?.host ?? DEFAULT_MQTT_HOST,
+          port: account.mqtt?.port ?? DEFAULT_MQTT_PORT,
+        },
+      }
+
+      const credentials = await resolveCredentials(mqttConfig)
+      const client = await createMqttClient(mqttConfig, credentials)
+      const topic = buildTopic(credentials.toy_sn)
+
+      activeClients.set(accountId, { client, toy_sn: credentials.toy_sn })
+      log?.info?.(`Connected to MQTT broker, subscribed to ${topic}`)
+
+      client.subscribe(topic, (err) => {
+        if (err) log?.error?.(`Failed to subscribe: ${err.message}`)
+      })
+
+      client.on('message', (_topic, payload) => {
+        let msg: InboundMessage
+        try {
+          msg = JSON.parse(payload.toString()) as InboundMessage
+        } catch {
+          return
+        }
+        if (msg.identifier !== 'chat_input' || typeof msg.outParams?.text !== 'string') return
+
+        const { msgId, outParams: { text } } = msg
+
+        const inboundCtx = channelRuntime.reply.finalizeInboundContext({
+          Body: text,
+          From: credentials.toy_sn,
+          To: credentials.toy_sn,
+          SessionKey: `folotoy-${accountId}-${credentials.toy_sn}`,
+          AccountId: accountId,
+          Provider: 'folotoy',
+        })
+
+        // fire-and-forget: OpenClaw handles queuing internally
+        void channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+          ctx: inboundCtx,
+          cfg,
+          dispatcherOptions: {
+            deliver: async (replyPayload) => {
+              if (!replyPayload.text) return
+              const outMsg: OutboundMessage = {
+                msgId,
+                identifier: 'chat_output',
+                outParams: { content: replyPayload.text },
+              }
+              client.publish(topic, JSON.stringify(outMsg))
+            },
+            onError: (err) => log?.error?.(`Dispatch error: ${String(err)}`),
+          },
+        })
+      })
+
+      abortSignal.addEventListener('abort', () => {
+        activeClients.delete(accountId)
+        client.end()
+        log?.info?.('MQTT client disconnected')
+      })
+    },
+
+    stopAccount: async (_ctx) => {
+      // cleanup handled by abortSignal listener in startAccount
+    },
+  },
+
+  outbound: {
+    deliveryMode: 'direct',
+    sendText: async ({ text, accountId }) => {
+      const key = accountId ?? 'default'
+      const entry = activeClients.get(key)
+      if (!entry) throw new Error(`No active MQTT client for account "${key}"`)
+
+      const topic = buildTopic(entry.toy_sn)
+      const msgId = Date.now()
+      const outMsg: OutboundMessage = {
+        msgId,
+        identifier: 'chat_output',
+        outParams: { content: text },
+      }
+      entry.client.publish(topic, JSON.stringify(outMsg))
+      return { channel: 'folotoy', messageId: String(msgId) }
+    },
+  },
+}
+
+export default (api: OpenClawPluginApi) => {
+  api.registerChannel({ plugin: folotoyChannel })
+}

package/src/mqtt.ts

@@ -0,0 +1,65 @@
+import mqtt, { MqttClient } from 'mqtt'
+import { AuthFlow1Config, AuthFlow2Config, PluginConfig } from './config.js'
+
+export type MqttCredentials = {
+  username: string
+  password: string
+  toy_sn: string
+}
+
+async function fetchCredentials(auth: AuthFlow1Config): Promise<MqttCredentials> {
+  const res = await fetch(`${auth.api_url}/v1/openapi/create_mqtt_token`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${auth.api_key}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ toy_sn: auth.toy_sn }),
+  })
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch MQTT token: ${res.status} ${res.statusText}`)
+  }
+
+  const data = await res.json() as { username: string; password: string }
+  return {
+    username: data.username,
+    password: data.password,
+    toy_sn: auth.toy_sn,
+  }
+}
+
+function directCredentials(auth: AuthFlow2Config): MqttCredentials {
+  return {
+    username: auth.toy_sn,
+    password: auth.toy_key,
+    toy_sn: auth.toy_sn,
+  }
+}
+
+export async function resolveCredentials(config: PluginConfig): Promise<MqttCredentials> {
+  if (config.auth.flow === 'api') {
+    return fetchCredentials(config.auth)
+  }
+  return directCredentials(config.auth)
+}
+
+export function buildTopic(toy_sn: string): string {
+  return `/openapi/folotoy/${toy_sn}/thing/data/post`
+}
+
+export async function createMqttClient(config: PluginConfig, credentials: MqttCredentials): Promise<MqttClient> {
+  const { host, port } = config.mqtt
+  const { username, password } = credentials
+
+  return new Promise((resolve, reject) => {
+    const client = mqtt.connect(`mqtt://${host}:${port}`, {
+      username: `openapi:${username}`,
+      password,
+      clean: true,
+    })
+
+    client.once('connect', () => resolve(client))
+    client.once('error', reject)
+  })
+}