@folotoy/folotoy-openclaw-plugin 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,11 @@
 # @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.
+Empower your FoloToy with OpenClaw AI capabilities.
+
+An [OpenClaw](https://openclaw.ai) channel plugin that bridges FoloToy smart toys with OpenClaw via MQTT.
 
 ```
-FoloToy 玩具  <──MQTT──>  FoloToy MQTT Broker  <──MQTT──>  This Plugin  <──>  OpenClaw
+FoloToy Toy  <──MQTT──>  FoloToy MQTT Broker  <──MQTT──>  Plugin  <──>  OpenClaw
 ```
 
 ## Installation
@@ -12,7 +14,7 @@ FoloToy 玩具  <──MQTT──>  FoloToy MQTT Broker  <──MQTT──>  Thi
 openclaw plugins install @folotoy/folotoy-openclaw-plugin
 ```
 
-Or install locally for development:
+For local development:
 
 ```bash
 openclaw plugins install -l .
@@ -20,19 +22,17 @@ openclaw plugins install -l .
 
 ## Configuration
 
-The plugin supports two authentication flows.
+The plugin supports two authentication flows. All fields are configured as flat key-value pairs in `openclaw.json` under `channels.folotoy`.
 
 ### 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` | `"direct"` |
+| `toy_sn` | Toy serial number |
+| `toy_key` | Toy key (used as MQTT password) |
+| `mqtt_host` | MQTT broker host (default: `198.19.249.25`) |
+| `mqtt_port` | MQTT broker port (default: `1883`) |
 
 ### Flow 1: HTTP API Login
 
@@ -40,22 +40,38 @@ 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`) |
+| `flow` | `"api"` |
+| `toy_sn` | Toy serial number |
+| `api_url` | FoloToy API base URL (default: `https://api.folotoy.cn`) |
+| `api_key` | Bearer token |
+| `mqtt_host` | MQTT broker host |
+| `mqtt_port` | MQTT broker port (default: `1883`) |
+
+Example `openclaw.json`:
+
+```json
+{
+  "channels": {
+    "folotoy": {
+      "flow": "direct",
+      "toy_sn": "your-toy-sn",
+      "toy_key": "your-toy-key",
+      "mqtt_host": "198.19.249.25"
+    }
+  }
+}
+```
 
 ## MQTT
 
-Both inbound and outbound messages use the same topic:
+Inbound and outbound use separate topics:
 
 ```
-/openapi/folotoy/{sn}/thing/data/post
+Inbound  (Toy → Plugin):  /openapi/folotoy/{sn}/thing/command/call
+Outbound (Plugin → Toy):  /openapi/folotoy/{sn}/thing/command/callAck
 ```
 
-The plugin connects to the MQTT broker with an `openapi:` prefix on the username to distinguish itself from the toy's own connection:
+The plugin connects with an `openapi:` prefix on the username to distinguish itself from the toy's own connection:
 
 ```
 username: openapi:{toy_sn}
@@ -78,8 +94,6 @@ password: {toy_key}
 
 **Plugin → Toy (outbound)**
 
-Single response message with `msgId` matching the inbound request:
-
 ```json
 {
   "msgId": 1,
@@ -90,20 +104,26 @@ Single response message with `msgId` matching the inbound request:
 }
 ```
 
+`msgId` starts at 1 per session and auto-increments.
+
 ## Environments
 
 | Environment | MQTT Host | Port |
 |-------------|-----------|------|
-| Development | `192.168.10.138` | 1883 |
+| Development | `198.19.249.25` | 1883 |
 | Testing | `f.qrc92.cn` | 1883 |
 | Production | `f.folotoy.cn` | 1883 |
 
-Switch environments via the `FOLOTOY_MQTT_HOST` environment variable.
+Switch environments via the `FOLOTOY_MQTT_HOST` environment variable or `mqtt_host` config field.
 
 ## Development
 
 ```bash
 npm install
-npm run build
 npm test
+npm run build
 ```
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -1,5 +1,52 @@
 {
-  "id": "folotoy",
-  "type": "channel",
-  "channels": ["folotoy"]
+  "id": "folotoy-openclaw-plugin",
+  "name": "FoloToy",
+  "description": "Empower your FoloToy with OpenClaw AI capabilities.",
+  "version": "0.1.2",
+  "channels": ["folotoy"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "flow": {
+        "type": "string",
+        "enum": ["direct", "api"],
+        "description": "Authentication flow",
+        "default": "direct"
+      },
+      "toy_sn": {
+        "type": "string",
+        "description": "Toy serial number"
+      },
+      "toy_key": {
+        "type": "string",
+        "description": "Toy key (direct flow)"
+      },
+      "api_url": {
+        "type": "string",
+        "description": "FoloToy API base URL (api flow)"
+      },
+      "api_key": {
+        "type": "string",
+        "description": "FoloToy API key (api flow)"
+      },
+      "mqtt_host": {
+        "type": "string",
+        "description": "MQTT broker host"
+      },
+      "mqtt_port": {
+        "type": "number",
+        "description": "MQTT broker port"
+      }
+    }
+  },
+  "uiHints": {
+    "flow": { "label": "Auth Flow" },
+    "toy_sn": { "label": "Toy SN" },
+    "toy_key": { "label": "Toy Key", "sensitive": true },
+    "api_url": { "label": "API URL", "placeholder": "https://api.folotoy.cn" },
+    "api_key": { "label": "API Key", "sensitive": true },
+    "mqtt_host": { "label": "MQTT Host", "placeholder": "198.19.249.25" },
+    "mqtt_port": { "label": "MQTT Port", "placeholder": "1883" }
+  }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@folotoy/folotoy-openclaw-plugin",
-  "version": "0.1.0",
-  "description": "OpenClaw channel plugin for FoloToy smart toys via MQTT",
+  "version": "0.1.2",
+  "description": "Empower your FoloToy with OpenClaw AI capabilities.",
   "keywords": [
     "folotoy",
     "openclaw"
@@ -55,7 +55,7 @@
       "label": "FoloToy",
       "selectionLabel": "FoloToy",
       "docsPath": "/channels/folotoy",
-      "blurb": "Connect FoloToy smart toys via MQTT."
+      "blurb": "Empower your FoloToy with OpenClaw AI capabilities."
     }
   }
 }

package/src/__tests__/channel.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest'
 import { EventEmitter } from 'events'
-import { buildTopic } from '../mqtt.js'
+import { buildInboundTopic, buildOutboundTopic } from '../mqtt.js'
 
 // Replicate the message parsing logic from index.ts for unit testing
 type InboundMessage = {
@@ -24,7 +24,7 @@ function makeMockClient() {
 }
 
 function setupSubscriber(client: ReturnType<typeof makeMockClient>, toy_sn: string, onMessage: (msgId: number, text: string) => void) {
-  const topic = buildTopic(toy_sn)
+  const topic = buildInboundTopic(toy_sn)
   client.subscribe(topic, () => {})
   client.on('message', (_topic: string, payload: Buffer) => {
     if (_topic !== topic) return
@@ -40,7 +40,7 @@ function setupSubscriber(client: ReturnType<typeof makeMockClient>, toy_sn: stri
 
 describe('inbound message parsing', () => {
   const toy_sn = 'SN001'
-  const topic = buildTopic(toy_sn)
+  const inboundTopic = buildInboundTopic(toy_sn)
 
   it('calls onMessage with msgId and text on valid chat_input', () => {
     const client = makeMockClient()
@@ -48,7 +48,7 @@ describe('inbound message parsing', () => {
     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)))
+    client.emit('message', inboundTopic, Buffer.from(JSON.stringify(msg)))
 
     expect(onMessage).toHaveBeenCalledWith(42, 'hello')
   })
@@ -59,7 +59,7 @@ describe('inbound message parsing', () => {
     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)))
+    client.emit('message', '/openapi/folotoy/OTHER/thing/command/call', Buffer.from(JSON.stringify(msg)))
 
     expect(onMessage).not.toHaveBeenCalled()
   })
@@ -69,7 +69,7 @@ describe('inbound message parsing', () => {
     const onMessage = vi.fn()
     setupSubscriber(client, toy_sn, onMessage)
 
-    client.emit('message', topic, Buffer.from(JSON.stringify({ msgId: 1, identifier: 'other', outParams: { text: 'hi' } })))
+    client.emit('message', inboundTopic, Buffer.from(JSON.stringify({ msgId: 1, identifier: 'other', outParams: { text: 'hi' } })))
 
     expect(onMessage).not.toHaveBeenCalled()
   })
@@ -79,7 +79,7 @@ describe('inbound message parsing', () => {
     const onMessage = vi.fn()
     setupSubscriber(client, toy_sn, onMessage)
 
-    client.emit('message', topic, Buffer.from('not json'))
+    client.emit('message', inboundTopic, Buffer.from('not json'))
 
     expect(onMessage).not.toHaveBeenCalled()
   })
@@ -87,7 +87,7 @@ describe('inbound message parsing', () => {
 
 describe('outbound message format', () => {
   const toy_sn = 'SN001'
-  const topic = buildTopic(toy_sn)
+  const outboundTopic = buildOutboundTopic(toy_sn)
 
   it('publishes chat_output with correct msgId and content', () => {
     const client = makeMockClient()
@@ -98,11 +98,11 @@ describe('outbound message format', () => {
       identifier: 'chat_output',
       outParams: { content },
     }
-    client.publish(topic, JSON.stringify(outMsg))
+    client.publish(outboundTopic, JSON.stringify(outMsg))
 
     expect(client.publish).toHaveBeenCalledOnce()
     const [t, payload] = client.publish.mock.calls[0] as [string, string]
-    expect(t).toBe(topic)
+    expect(t).toBe(outboundTopic)
     expect(JSON.parse(payload)).toEqual({ msgId: 42, identifier: 'chat_output', outParams: { content: 'world' } })
   })
 })

package/src/__tests__/mqtt.test.ts

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

package/src/config.ts

@@ -19,5 +19,32 @@ export type PluginConfig = {
   }
 }
 
+/** Flat config as stored in openclaw.json channels.folotoy */
+export type FlatChannelConfig = {
+  flow?: string
+  toy_sn?: string
+  toy_key?: string
+  api_url?: string
+  api_key?: string
+  mqtt_host?: string
+  mqtt_port?: number
+}
+
+export const DEFAULT_API_URL = 'https://api.folotoy.cn'
 export const DEFAULT_MQTT_HOST = process.env.FOLOTOY_MQTT_HOST ?? '198.19.249.25'
 export const DEFAULT_MQTT_PORT = 1883
+
+export function flatToPluginConfig(flat: FlatChannelConfig): PluginConfig {
+  const flow = flat.flow ?? 'direct'
+  const auth = flow === 'api'
+    ? { flow: 'api' as const, api_url: flat.api_url ?? DEFAULT_API_URL, api_key: flat.api_key ?? '', toy_sn: flat.toy_sn ?? '' }
+    : { flow: 'direct' as const, toy_sn: flat.toy_sn ?? '', toy_key: flat.toy_key ?? '' }
+
+  return {
+    auth,
+    mqtt: {
+      host: flat.mqtt_host ?? DEFAULT_MQTT_HOST,
+      port: flat.mqtt_port ?? DEFAULT_MQTT_PORT,
+    },
+  }
+}

package/src/index.ts

@@ -1,11 +1,9 @@
 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 { resolveCredentials, createMqttClient, buildInboundTopic, buildOutboundTopic } from './mqtt.js'
+import { DEFAULT_MQTT_HOST, DEFAULT_MQTT_PORT, flatToPluginConfig } from './config.js'
+import type { FlatChannelConfig } from './config.js'
 import type { MqttClient } from 'mqtt'
 
-type FoloToyAccount = PluginConfig
-
 type InboundMessage = {
   msgId: number
   identifier: 'chat_input'
@@ -18,17 +16,17 @@ type OutboundMessage = {
   outParams: { content: string }
 }
 
-// Per-account MQTT clients, kept for proactive outbound sends
-const activeClients = new Map<string, { client: MqttClient; toy_sn: string }>()
+// Per-account MQTT clients and msgId counters
+const activeClients = new Map<string, { client: MqttClient; toy_sn: string; nextMsgId: number }>()
 
-const folotoyChannel: ChannelPlugin<FoloToyAccount> = {
+const folotoyChannel: ChannelPlugin<FlatChannelConfig> = {
   id: 'folotoy',
   meta: {
     id: 'folotoy',
     label: 'FoloToy',
     selectionLabel: 'FoloToy',
     docsPath: '/channels/folotoy',
-    blurb: 'Connect FoloToy smart toys via MQTT.',
+    blurb: 'Empower your FoloToy with OpenClaw AI capabilities.',
   },
   capabilities: {
     chatTypes: ['direct'],
@@ -37,60 +35,35 @@ const folotoyChannel: ChannelPlugin<FoloToyAccount> = {
     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 },
-          },
-        },
+        flow: { type: 'string', enum: ['direct', 'api'], default: 'direct' },
+        toy_sn: { type: 'string' },
+        toy_key: { type: 'string' },
+        api_url: { type: 'string', default: 'https://api.folotoy.cn' },
+        api_key: { type: 'string' },
+        mqtt_host: { type: 'string', default: DEFAULT_MQTT_HOST },
+        mqtt_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' },
+      flow: { label: 'Auth Flow' },
+      toy_sn: { label: 'Toy SN' },
+      toy_key: { label: 'Toy Key', sensitive: true },
+      api_url: { label: 'API URL', placeholder: 'https://api.folotoy.com' },
+      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)
+      const folotoy = (cfg as Record<string, unknown> & { channels?: { folotoy?: FlatChannelConfig } })
+        .channels?.folotoy
+      return folotoy ? ['default'] : []
     },
-    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)
+    resolveAccount: (cfg, _accountId) => {
+      const folotoy = (cfg as Record<string, unknown> & { channels?: { folotoy?: FlatChannelConfig } })
+        .channels?.folotoy
+      return folotoy ?? ({} as FlatChannelConfig)
     },
   },
   gateway: {
@@ -102,22 +75,21 @@ const folotoyChannel: ChannelPlugin<FoloToyAccount> = {
         return
       }
 
-      const mqttConfig: PluginConfig = {
-        auth: account.auth,
-        mqtt: {
-          host: account.mqtt?.host ?? DEFAULT_MQTT_HOST,
-          port: account.mqtt?.port ?? DEFAULT_MQTT_PORT,
-        },
+      if (!account.toy_sn) {
+        log?.warn?.('toy_sn not configured — skipping MQTT connection')
+        return
       }
 
+      const mqttConfig = flatToPluginConfig(account)
       const credentials = await resolveCredentials(mqttConfig)
       const client = await createMqttClient(mqttConfig, credentials)
-      const topic = buildTopic(credentials.toy_sn)
+      const inboundTopic = buildInboundTopic(credentials.toy_sn)
+      const outboundTopic = buildOutboundTopic(credentials.toy_sn)
 
-      activeClients.set(accountId, { client, toy_sn: credentials.toy_sn })
-      log?.info?.(`Connected to MQTT broker, subscribed to ${topic}`)
+      activeClients.set(accountId, { client, toy_sn: credentials.toy_sn, nextMsgId: 1 })
+      log?.info?.(`Connected to MQTT broker, subscribed to ${inboundTopic}`)
 
-      client.subscribe(topic, (err) => {
+      client.subscribe(inboundTopic, (err) => {
         if (err) log?.error?.(`Failed to subscribe: ${err.message}`)
       })
 
@@ -153,17 +125,21 @@ const folotoyChannel: ChannelPlugin<FoloToyAccount> = {
                 identifier: 'chat_output',
                 outParams: { content: replyPayload.text },
               }
-              client.publish(topic, JSON.stringify(outMsg))
+              client.publish(outboundTopic, JSON.stringify(outMsg))
             },
             onError: (err) => log?.error?.(`Dispatch error: ${String(err)}`),
           },
         })
       })
 
-      abortSignal.addEventListener('abort', () => {
-        activeClients.delete(accountId)
-        client.end()
-        log?.info?.('MQTT client disconnected')
+      // Keep the account alive until aborted
+      return new Promise<void>((resolve) => {
+        abortSignal.addEventListener('abort', () => {
+          activeClients.delete(accountId)
+          client.end()
+          log?.info?.('MQTT client disconnected')
+          resolve()
+        })
       })
     },
 
@@ -179,14 +155,14 @@ const folotoyChannel: ChannelPlugin<FoloToyAccount> = {
       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 outboundTopic = buildOutboundTopic(entry.toy_sn)
+      const msgId = entry.nextMsgId++
       const outMsg: OutboundMessage = {
         msgId,
         identifier: 'chat_output',
         outParams: { content: text },
       }
-      entry.client.publish(topic, JSON.stringify(outMsg))
+      entry.client.publish(outboundTopic, JSON.stringify(outMsg))
       return { channel: 'folotoy', messageId: String(msgId) }
     },
   },

package/src/mqtt.ts

@@ -44,8 +44,12 @@ export async function resolveCredentials(config: PluginConfig): Promise<MqttCred
   return directCredentials(config.auth)
 }
 
-export function buildTopic(toy_sn: string): string {
-  return `/openapi/folotoy/${toy_sn}/thing/data/post`
+export function buildInboundTopic(toy_sn: string): string {
+  return `/openapi/folotoy/${toy_sn}/thing/command/call`
+}
+
+export function buildOutboundTopic(toy_sn: string): string {
+  return `/openapi/folotoy/${toy_sn}/thing/command/callAck`
 }
 
 export async function createMqttClient(config: PluginConfig, credentials: MqttCredentials): Promise<MqttClient> {