@invago/mixin 1.0.9 → 1.0.10

package/README.md

@@ -24,6 +24,18 @@ openclaw plugins install @invago/mixin
 
 `@invago/mixin` is the published npm package name. The OpenClaw runtime/plugin name remains `mixin`.
 
+If the plugin is already installed, upgrade it with the plugin id:
+
+```bash
+openclaw plugins update mixin
+```
+
+To install a specific version for the first time:
+
+```bash
+openclaw plugins install @invago/mixin@<version>
+```
+
 Then confirm the plugin is installed:
 
 ```bash
@@ -64,7 +76,6 @@ Edit your `openclaw.json` file manually and add both the channel configuration a
 {
   "channels": {
     "mixin": {
-      "enabled": true,
       "defaultAccount": "default",
       "appId": "YOUR_APP_ID",
       "sessionId": "YOUR_SESSION_ID",
@@ -78,6 +89,16 @@ Edit your `openclaw.json` file manually and add both the channel configuration a
       "audioSendAsVoiceByDefault": true,
       "audioAutoDetectDuration": true,
       "audioRequireFfprobe": false,
+      "mixpay": {
+        "enabled": true,
+        "payeeId": "YOUR_MIXPAY_PAYEE_ID",
+        "defaultSettlementAssetId": "YOUR_SETTLEMENT_ASSET_ID",
+        "expireMinutes": 15,
+        "pollIntervalSec": 30,
+        "allowedCreators": ["AUTHORIZED_USER_UUID"],
+        "notifyOnPending": false,
+        "notifyOnPaidLess": true
+      },
       "proxy": {
         "enabled": true,
         "url": "socks5://127.0.0.1:10808",
@@ -143,11 +164,105 @@ Recommended configuration:
 
 Use `per-account-channel-peer` instead if you run multiple Mixin accounts and want direct-message sessions isolated by both channel and account.
 
+## Multi-Agent Routing Per Bot Account
+
+OpenClaw supports routing different channel accounts to different agents through `bindings[].match.accountId`.
+
+Recommended pattern:
+
+- One Mixin bot account = one `accountId`
+- One `accountId` = one agent binding
+- Keep session isolation at `per-account-channel-peer` when you run multiple bot accounts
+
+Example:
+
+```json
+{
+  "session": {
+    "dmScope": "per-account-channel-peer"
+  },
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "workspace": "E:/AI/workspace-main",
+        "default": true
+      },
+      {
+        "id": "sales",
+        "workspace": "E:/AI/workspace-sales"
+      },
+      {
+        "id": "support",
+        "workspace": "E:/AI/workspace-support"
+      }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "main",
+      "match": {
+        "channel": "mixin",
+        "accountId": "default"
+      }
+    },
+    {
+      "agentId": "sales",
+      "match": {
+        "channel": "mixin",
+        "accountId": "sales"
+      }
+    },
+    {
+      "agentId": "support",
+      "match": {
+        "channel": "mixin",
+        "accountId": "support"
+      }
+    }
+  ],
+  "channels": {
+    "mixin": {
+      "defaultAccount": "default",
+      "accounts": {
+        "default": {
+          "name": "Main Bot",
+          "appId": "APP_ID_1",
+          "sessionId": "SESSION_ID_1",
+          "serverPublicKey": "SERVER_PUBLIC_KEY_1",
+          "sessionPrivateKey": "SESSION_PRIVATE_KEY_1"
+        },
+        "sales": {
+          "name": "Sales Bot",
+          "appId": "APP_ID_2",
+          "sessionId": "SESSION_ID_2",
+          "serverPublicKey": "SERVER_PUBLIC_KEY_2",
+          "sessionPrivateKey": "SESSION_PRIVATE_KEY_2"
+        },
+        "support": {
+          "name": "Support Bot",
+          "appId": "APP_ID_3",
+          "sessionId": "SESSION_ID_3",
+          "serverPublicKey": "SERVER_PUBLIC_KEY_3",
+          "sessionPrivateKey": "SESSION_PRIVATE_KEY_3"
+        }
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- `match.accountId` binds one Mixin bot account to one agent.
+- If `accountId` is omitted in a binding, OpenClaw treats it as the default account only.
+- Use `accountId: "*"` only when you want one fallback agent for all Mixin accounts.
+- If you need one specific group or DM to override the account-level routing, add a more specific `match.peer` binding. Peer matches win over `accountId` matches.
+
 ## Configuration Reference
 
 | Parameter | Required | Default | Description |
 |-----------|----------|---------|-------------|
-| `enabled` | No | `true` | Enable or disable this channel account |
 | `defaultAccount` | No | `default` | Default account ID used when `accounts` is configured |
 | `appId` | Yes | - | Mixin App UUID |
 | `sessionId` | Yes | - | Session UUID |
@@ -157,12 +272,21 @@ Use `per-account-channel-peer` instead if you run multiple Mixin accounts and wa
 | `allowFrom` | No | `[]` | Authorized user UUID whitelist |
 | `groupPolicy` | No | OpenClaw default | Group-message policy: `open`, `allowlist`, or `disabled` |
 | `groupAllowFrom` | No | `[]` | Authorized sender UUID whitelist for group messages when `groupPolicy` uses allowlisting |
-| `requireMentionInGroup` | No | `true` | Require trigger words in group chats |
+| `requireMentionInGroup` | No | `true` | Apply plugin-side trigger-word filtering to group messages that have already been delivered to the bot |
 | `mediaBypassMentionInGroup` | No | `true` | Allow inbound group file/audio messages through even without trigger text |
 | `mediaMaxMb` | No | `30` | Max inbound and outbound media size in MB |
 | `audioSendAsVoiceByDefault` | No | `true` | Send OpenClaw native outbound audio as Mixin voice when possible |
 | `audioAutoDetectDuration` | No | `true` | Detect native outbound audio duration with `ffprobe` before sending voice |
 | `audioRequireFfprobe` | No | `false` | Fail native outbound audio instead of falling back to file when duration detection is unavailable |
+| `mixpay.enabled` | No | `false` | Enable MixPay collect support for this Mixin account |
+| `mixpay.payeeId` | Required when enabled | - | MixPay merchant/payee ID used to create one-time payment orders |
+| `mixpay.defaultQuoteAssetId` | No | - | Default quote asset ID for collect templates or future collect commands |
+| `mixpay.defaultSettlementAssetId` | No | - | Default settlement asset ID for MixPay orders |
+| `mixpay.expireMinutes` | No | `15` | Default MixPay order expiration time in minutes |
+| `mixpay.pollIntervalSec` | No | `30` | Poll interval in seconds for pending MixPay orders |
+| `mixpay.allowedCreators` | No | `[]` | Optional sender UUID allowlist for creating MixPay collect orders |
+| `mixpay.notifyOnPending` | No | `false` | Notify the chat when MixPay reports `pending` |
+| `mixpay.notifyOnPaidLess` | No | `true` | Notify the chat when MixPay indicates an underpayment |
 | `conversations.<conversationId>.enabled` | No | `true` | Enable or disable a specific group conversation |
 | `conversations.<conversationId>.requireMention` | No | Inherit account | Override group trigger-word requirement for a specific conversation |
 | `conversations.<conversationId>.allowFrom` | No | Inherit account | Override group sender allowlist for a specific conversation |
@@ -189,6 +313,13 @@ Mixin now supports formal group access controls in addition to direct-message `d
 - `groupPolicy: "disabled"` blocks the entire conversation.
 - `conversations.<conversationId>` overrides account-level group settings for that single conversation.
 
+Important delivery boundary:
+
+- In practice, Mixin group bots reliably receive messages when the bot is explicitly mentioned.
+- `requireMentionInGroup: false` only disables this plugin's own post-delivery filtering.
+- It does not guarantee that Mixin will deliver every non-mention group message to the bot.
+- If a non-mention group message produces no read receipt and no inbound log, the message most likely was not delivered to the plugin by Mixin in the first place.
+
 Example:
 
 ```json
@@ -212,6 +343,34 @@ Example:
 }
 ```
 
+How to get these values:
+
+- `conversations.<conversationId>`: use the group's `conversation_id`. In practice, the easiest way is to let the group send a message to the bot once, then read the `conversationId` from the plugin logs or inbound event context. Mixin's conversation APIs also use the same `conversation_id` field for group conversations.
+- `groupAllowFrom` or `conversations.<conversationId>.allowFrom`: use the sender's Mixin `user_id` UUID. Mixin user IDs can be learned when the user messages the bot, adds the bot as a contact, or authorizes the application.
+- If you manage the group through Mixin APIs, the returned conversation payload also includes group participants with their `user_id` fields.
+
+Recommended operational approach:
+
+- Let the target group send one message to the bot
+- Copy the logged `conversationId`
+- Let the target member send one message, then copy that sender's `user_id`
+- Put those values into `conversations.<conversationId>` and `groupAllowFrom` / `allowFrom`
+
+Pairing-style group authorization:
+
+- An unauthorized user can send `/mixin-group-auth` in the target group
+- The plugin replies with a temporary approval code for that `conversationId`
+- An operator must approve it in the OpenClaw terminal with `openclaw pairing approve mixin <code>`
+- For non-default accounts, use `openclaw pairing approve --account <accountId> mixin <code>`
+- Once approved, that entire group conversation is allowed without changing `openclaw.json`
+- Repeated `/mixin-group-auth` requests from the same unauthorized group are rate-limited to avoid spam
+
+Where to look in logs:
+
+- The plugin logs route resolution like `peer.kind=group, peer.id=<conversationId>`, which gives you the group `conversationId`
+- Unauthorized or filtered group logs include `group sender <user_id>` and `conversationId=<conversationId>`
+- If needed, temporarily enable a stricter group policy and let one member send a message once; the rejection log is often the fastest way to collect both values
+
 ## Usage
 
 - Direct message: `/status` or `Hello`
@@ -224,6 +383,7 @@ Useful OpenClaw commands:
 ```bash
 openclaw plugins list
 openclaw plugins info mixin
+openclaw plugins update mixin
 openclaw channels status --probe
 openclaw status
 ```
@@ -232,10 +392,15 @@ Plugin-specific command:
 
 - Send `/mixin-outbox` to inspect the current pending queue size, next retry time, and latest error.
 - Send `/mixin-outbox purge-invalid` to remove old `APP_CARD` / `APP_BUTTON_GROUP` entries that are stuck on permanent invalid-field errors.
+- Send `/mixin-group-auth` in a group to create a pending group-authorization request.
+- Approve a pending group-authorization request in the OpenClaw terminal with `openclaw pairing approve mixin <code>`.
+- For non-default accounts, use `openclaw pairing approve --account <accountId> mixin <code>`.
+- Send `/collect status <orderId>` to refresh and inspect a stored MixPay collect order.
+- Send `/collect recent` or `/collect recent 10` to list recent MixPay collect orders for the current conversation.
 
 Companion onboarding CLI:
 
-- This repository also includes a companion CLI at [tools/mixin-plugin-onboard/README.md](/E:/AI/mixin-claw/tools/mixin-plugin-onboard/README.md).
+- This repository also includes a companion CLI at `tools/mixin-plugin-onboard/README.md`.
 - It is bundled into the same npm package, `@invago/mixin`.
 - It currently provides `info`, `doctor`, `install`, and `update` commands for local OpenClaw + Mixin plugin maintenance.
 - Local examples:
@@ -278,6 +443,99 @@ Manual test guide:
 
 - See [docs/media-testing.md](docs/media-testing.md) for ready-to-run prompts and expected results.
 
+## MixPay Collect
+
+Mixin now supports MixPay collection through one-time payment orders.
+
+Current capabilities:
+
+- `mixin-collect` explicit reply template creates a MixPay collect order
+- Collect orders are stored locally under the OpenClaw state directory
+- Pending orders are polled in the background
+- Success and terminal status changes are sent back to the original conversation
+- `/collect status <orderId>` refreshes the order from MixPay before replying
+- `assetId` in the template can be omitted when `mixpay.defaultQuoteAssetId` is configured
+
+Template example:
+
+````text
+```mixin-collect
+{
+  "amount": "1",
+  "assetId": "c6d0c728-2624-429b-8e0d-d9d19b6592fa",
+  "memo": "Order #1001"
+}
+```
+````
+
+Rules:
+
+- `amount` is required; `assetId` is required unless `mixpay.defaultQuoteAssetId` is configured
+- `settlementAssetId`, `memo`, `orderId`, and `expireMinutes` are optional
+- Payment success is confirmed from MixPay server-side query results, not only from the client page
+- `mixpay.allowedCreators` can restrict who is allowed to create collect orders
+
+Where funds arrive:
+
+- For MixPay `Mixin account`, funds settle into the linked Mixin Wallet
+- For MixPay `Mixin Robot account`, funds settle into the linked Mixin Robot Wallet
+- Other MixPay account types settle into their own linked wallet types
+
+Recommended setup for this plugin:
+
+- Use a MixPay `Mixin account` or `Mixin Robot account`
+- Use that account's UUID as `mixpay.payeeId`
+- Set both `mixpay.defaultQuoteAssetId` and `mixpay.defaultSettlementAssetId` if you want templates to stay short
+
+How to get the required values:
+
+- `mixpay.payeeId`: get the UUID from the [MixPay Dashboard](https://dashboard.mixpay.me) settings page, or use the MixPay helper bot described in the official getting-started guide
+- `mixpay.defaultQuoteAssetId`: choose the asset ID you want to quote prices in
+- `mixpay.defaultSettlementAssetId`: choose the asset ID you want funds to settle into
+
+Minimal recommended config:
+
+```json
+{
+  "channels": {
+    "mixin": {
+      "mixpay": {
+        "enabled": true,
+        "payeeId": "YOUR_MIXPAY_UUID",
+        "defaultQuoteAssetId": "YOUR_QUOTE_ASSET_ID",
+        "defaultSettlementAssetId": "YOUR_SETTLEMENT_ASSET_ID"
+      }
+    }
+  }
+}
+```
+
+Where to put it:
+
+- Single-account setup: put `mixpay` under `channels.mixin.mixpay`
+- Multi-account setup: put it under `channels.mixin.accounts.<accountId>.mixpay`
+- `mixpay` is account-scoped, so different Mixin bot accounts can use different MixPay settings
+
+Field reference:
+
+- `mixpay.enabled`: enable MixPay collect support for this Mixin account
+- `mixpay.apiBaseUrl`: optional custom MixPay API base URL; normally leave it empty and use the default official endpoint
+- `mixpay.payeeId`: the MixPay payee/merchant UUID that actually receives the funds; required when MixPay collect is enabled
+- `mixpay.defaultQuoteAssetId`: default quoted asset ID; when set, `mixin-collect` can omit `assetId`
+- `mixpay.defaultSettlementAssetId`: default settlement asset ID; controls which asset the order prefers to settle into
+- `mixpay.expireMinutes`: default expiration time for newly created collect orders
+- `mixpay.pollIntervalSec`: background polling interval for pending orders; shorter values detect paid orders faster but create more MixPay API traffic
+- `mixpay.allowedCreators`: optional sender UUID allowlist; when non-empty, only these users can create collect orders in chat
+- `mixpay.notifyOnPending`: whether to send a conversation update when MixPay reports the order as `pending`
+- `mixpay.notifyOnPaidLess`: whether to send a conversation update when MixPay reports an underpayment
+
+Practical guidance:
+
+- If you only want the smallest working setup, configure `enabled`, `payeeId`, `defaultQuoteAssetId`, and `defaultSettlementAssetId`
+- If you do not want everyone in an authorized chat to create collect orders, set `allowedCreators`
+- If you do not run a private MixPay gateway, leave `apiBaseUrl` unset
+- If you want fewer status messages in chat, keep `notifyOnPending: false`
+
 ## Explicit Reply Templates
 
 When you want deterministic Mixin output instead of heuristic auto-selection, have the agent reply with exactly one fenced template block.