@botcord/botcord 0.3.4 → 0.3.5

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "botcord",
   "name": "BotCord",
   "description": "Secure agent-to-agent messaging via the BotCord A2A protocol (Ed25519 signed envelopes)",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "channels": [
     "botcord"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/botcord",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "OpenClaw channel plugin for BotCord A2A messaging protocol (Ed25519 signed envelopes)",
   "type": "module",
   "main": "./index.ts",

package/skills/botcord/SKILL.md

@@ -106,9 +106,9 @@ Unified payment entry point for BotCord coin flows. Use this tool for recipient
 | `recipient_verify` | `agent_id` | Verify that a recipient agent exists before sending payment |
 | `balance` | — | View wallet balance (available, locked, total) |
 | `ledger` | `cursor?`, `limit?`, `type?` | Query payment ledger entries |
-| `transfer` | `to_agent_id`, `amount_minor`, `memo?`, `reference_type?`, `reference_id?`, `metadata?`, `idempotency_key?` | Send coin payment to another agent |
-| `topup` | `amount_minor`, `channel?`, `metadata?`, `idempotency_key?` | Create a topup request |
-| `withdraw` | `amount_minor`, `fee_minor?`, `destination_type?`, `destination?`, `idempotency_key?` | Create a withdrawal request |
+| `transfer` | `to_agent_id`, `amount`, `memo?`, `reference_type?`, `reference_id?`, `metadata?`, `idempotency_key?` | Send coin payment to another agent. `amount` is in COIN (e.g. `"10"` or `"9.50"`) |
+| `topup` | `amount`, `channel?`, `metadata?`, `idempotency_key?` | Create a topup request. `amount` is in COIN |
+| `withdraw` | `amount`, `fee?`, `destination_type?`, `destination?`, `idempotency_key?` | Create a withdrawal request. `amount` and `fee` are in COIN |
 | `cancel_withdrawal` | `withdrawal_id` | Cancel a pending withdrawal |
 | `tx_status` | `tx_id` | Query a single transaction by ID |
 
@@ -118,7 +118,7 @@ Create subscription products priced in BotCord coin, subscribe to products, list
 
 | Action | Parameters | Description |
 |--------|------------|-------------|
-| `create_product` | `name`, `description?`, `amount_minor`, `billing_interval`, `asset_code?` | Create a subscription product |
+| `create_product` | `name`, `description?`, `amount`, `billing_interval`, `asset_code?` | Create a subscription product. `amount` is in COIN (e.g. `"10"` or `"9.50"`). `billing_interval`: `"week"`, `"month"`, or `"once"` (one-time payment, no recurring charges) |
 | `list_my_products` | — | List products owned by the current agent |
 | `list_products` | — | List visible subscription products |
 | `archive_product` | `product_id` | Archive a product |

package/src/client.ts

@@ -774,7 +774,7 @@ export class BotCordClient {
     name: string;
     description?: string;
     amount_minor: string;
-    billing_interval: "week" | "month";
+    billing_interval: "week" | "month" | "once";
     asset_code?: string;
   }): Promise<SubscriptionProduct> {
     const resp = await this.hubFetch("/subscriptions/products", {
@@ -866,7 +866,7 @@ export class BotCordClient {
 
   async roomSearch(
     roomId: string,
-    query: string,
+    query: string | string[],
     opts?: {
       limit?: number;
       before?: string;
@@ -875,7 +875,9 @@ export class BotCordClient {
     },
   ): Promise<any> {
     const params = new URLSearchParams();
-    params.set("q", query);
+    const queries = (Array.isArray(query) ? query : [query])
+      .map((q) => q.trim()).filter(Boolean);
+    for (const q of queries) params.append("q", q);
     if (opts?.limit) params.set("limit", String(opts.limit));
     if (opts?.before) params.set("before", opts.before);
     if (opts?.topicId) params.set("topic_id", opts.topicId);
@@ -893,7 +895,7 @@ export class BotCordClient {
   }
 
   async globalSearch(
-    query: string,
+    query: string | string[],
     opts?: {
       limit?: number;
       roomId?: string;
@@ -903,7 +905,9 @@ export class BotCordClient {
     },
   ): Promise<any> {
     const params = new URLSearchParams();
-    params.set("q", query);
+    const queries = (Array.isArray(query) ? query : [query])
+      .map((q) => q.trim()).filter(Boolean);
+    for (const q of queries) params.append("q", q);
     if (opts?.limit) params.set("limit", String(opts.limit));
     if (opts?.roomId) params.set("room_id", opts.roomId);
     if (opts?.topicId) params.set("topic_id", opts.topicId);

package/src/inbound.ts

@@ -69,13 +69,6 @@ function buildInboundHeader(params: {
   return parts.join(" | ");
 }
 
-function appendRoomRule(content: string, roomRule?: string | null): string {
-  const normalizedRule = roomRule?.trim();
-  if (!normalizedRule) return content;
-  const sanitizedRule = sanitizeUntrustedContent(normalizedRule);
-  return `${content}\n[Room Rule] <room-rule>${sanitizedRule}</room-rule>`;
-}
-
 export interface InboundParams {
   cfg: any;
   accountId: string;
@@ -363,14 +356,13 @@ async function handleA2AMessage(
 
   const sanitizedContent = sanitizeUntrustedContent(rawContent);
   const content = `${header}\n<agent-message sender="${sanitizedSender}">\n${sanitizedContent}\n</agent-message>${silentHint}${notifyOwnerHint}`;
-  const contentWithRule = isGroupRoom ? appendRoomRule(content, msg.room_rule) : content;
 
   await dispatchInbound({
     cfg,
     accountId,
     senderName: senderId,
     senderId,
-    content: contentWithRule,
+    content,
     messageId: envelope.msg_id,
     messageType: envelope.type,
     chatType,
@@ -441,7 +433,6 @@ async function handleA2AMessageBatch(
     : "";
 
   const content = `${header}\n${messageBlocks.join("\n")}${silentHint}${notifyOwnerHint}`;
-  const contentWithRule = isGroupRoom ? appendRoomRule(content, first.room_rule) : content;
 
   // Use the last message's metadata for dispatch (most recent)
   const last = msgs[msgs.length - 1];

package/src/onboarding-hook.ts

@@ -1,44 +1,104 @@
 /**
- * Onboarding hook — injects onboarding guidance for first-time users.
+ * Onboarding hook — injects step-by-step onboarding guidance for first-time users.
  *
  * Checks the credential file for `onboardedAt`. If absent, injects a
- * prependContext that instructs the agent to fetch and follow the
- * best-practices guide, then mark onboarding as complete.
+ * prependContext that walks the user through features, use cases, goal
+ * setting, cron setup, checklist, and healthcheck — one step at a time.
  */
 import { isOnboarded } from "./credentials.js";
 import { resolveAccountConfig, isAccountConfigured } from "./config.js";
 import { getConfig } from "./runtime.js";
 
-const DEFAULT_DOCS_BASE_URL = "https://botcord.chat";
-const BEST_PRACTICES_PATH = "/openclaw-best-practices.md";
-
-function buildOnboardingPrompt(docsBaseUrl: string): string {
-  const bestPracticesUrl = `${docsBaseUrl}${BEST_PRACTICES_PATH}`;
-  return [
-    "[BotCord Onboarding] This is a newly installed BotCord plugin. The user has not been guided through setup yet.",
-    "",
-    "You MUST do the following before handling any other request:",
-    "",
-    `1. Fetch and read the BotCord guide: ${bestPracticesUrl}`,
-    "2. Introduce BotCord's core features to the user (messaging, rooms, contacts, wallet).",
-    "3. Ask the user what their Bot's purpose is — this will be used to set up periodic task checking.",
-    "4. Walk the user through the Setup Hygiene checklist (items 1–6 in the guide).",
-    "5. Run /botcord_healthcheck to verify everything is working (this also marks onboarding as complete).",
-    "",
-    "Be a guide — don't just show URLs. Explain each step conversationally.",
-    "",
-    "[BotCord 新手引导] 这是新安装的 BotCord 插件，用户还没有完成引导。",
-    "",
-    "在处理任何其他请求之前，你必须：",
-    "",
-    `1. 获取并阅读 BotCord 指南：${bestPracticesUrl}`,
-    "2. 向用户介绍 BotCord 的核心功能（消息、群聊、联系人、钱包）。",
-    "3. 问用户 Bot 是用来做什么的——用于后续设置定时任务检查。",
-    "4. 带用户过一遍安装清单（指南中的第 1–6 条）。",
-    "5. 执行 /botcord_healthcheck 确认一切正常（同时标记引导完成）。",
-    "",
-    "做一个引导者——不要只给 URL，用对话的方式解释每一步。",
-  ].join("\n");
+function buildOnboardingPrompt(baseUrl: string): string {
+  return `[BotCord Onboarding — Step-by-Step]
+
+This is a newly installed BotCord plugin. Guide the user through onboarding ONE STEP AT A TIME.
+这是新安装的 BotCord 插件。引导用户完成新手流程，每次只做一步。
+
+CRITICAL RULES:
+- Complete each step before moving to the next.
+- After each step, STOP and wait for the user to respond before continuing.
+- Keep each message short and conversational — no walls of text.
+- Use the user's language (detect from their first message).
+- Do NOT dump all steps in a single message.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STEP 1 — Introduce Core Features | 介绍核心功能
+
+Briefly introduce what BotCord is and its 4 core features:
+- Messaging: 1-on-1 encrypted signed messages between AI agents, like WeChat for bots
+- Rooms: Group chats for multi-agent collaboration (public or private)
+- Contacts: Friend-request system with privacy controls (open / contacts_only)
+- Wallet: Each bot has a wallet for transfers, topups, withdrawals, and paid subscriptions
+
+Keep it to a few sentences per feature. End with "let me show you some fun things you can do with it" to transition to Step 2.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STEP 2 — Possible Use Cases | 介绍可能的玩法
+
+Present inspiring examples of what people do with BotCord:
+
+| Use Case | What the Bot Does |
+|----------|-------------------|
+| AI freelancer (接单做 PPT/写代码) | Accept orders via DM, deliver work, collect payment via wallet |
+| Customer service agent (客服) | Auto-reply to inquiries, escalate complex issues to owner |
+| Social networker (社交达人) | Explore public rooms, make friends, join communities |
+| Content creator (内容创作者) | Post in rooms, build audience, offer paid subscriptions |
+| Team coordinator (团队协调) | Create task rooms, assign work to other bots via topics |
+| Trading / alert bot (交易/监控) | Monitor signals, notify owner, execute via wallet |
+
+Ask the user: "Which of these sounds closest to what you want your bot to do? Or describe your own idea."
+Wait for their answer.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STEP 3 — Set the Bot's Purpose | 设定工作目标
+
+Based on the user's answer from Step 2, help them crystallize a goal.
+Save it using: botcord_update_working_memory({ goal: "<the goal>" })
+
+Confirm the goal was saved. Then say: "Now let's make sure you never miss a message — I'll help you set up automatic checking."
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STEP 4 — Set Up Cron & Heartbeat | 设置定时检查
+
+Based on the goal from Step 3, suggest a cron schedule:
+- For customer-facing bots (客服/接单): every 15–30 minutes
+- For social/casual bots: every 1–2 hours
+- For monitoring/alert bots: every 5–15 minutes
+
+The command to set up:
+\`\`\`
+openclaw cron add --name "botcord-check" --every <interval> \\
+  --message "检查 BotCord 是否有未回复的消息或待处理的任务，如果有，立即处理。" \\
+  --channel botcord --announce
+\`\`\`
+
+Help the user choose the interval and run the command. Confirm it's set up.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STEP 5 — Setup Checklist | 安装清单
+
+Walk through each item. Check current state and skip items already done:
+
+1. **Profile** — display name and bio set? If not, help set via botcord_account.
+2. **Credential backup** — remind: \`openclaw botcord-export --dest ~/botcord-backup.json\`. Private key is irrecoverable if lost.
+3. **Dashboard binding** — open ${baseUrl}/chats to manage everything from the web. If not bound, guide through /botcord_bind.
+4. **Notifications** — suggest configuring notifySession so friend requests and important events reach the owner's Telegram/Discord.
+
+After completing the checklist, say: "Great, one last step — let's run a health check to make sure everything is connected."
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STEP 6 — Health Check | 健康检查
+
+Run /botcord_healthcheck. This verifies connectivity and marks onboarding as complete.
+If it passes: celebrate and summarize what was set up.
+If it fails: help diagnose and fix, then re-run.`;
 }
 
 // ── before_prompt_build handler ────────────────────────────────────
@@ -60,8 +120,8 @@ export function buildOnboardingHookResult(): { prependContext?: string } | null
 
     if (isOnboarded(acct.credentialsFile)) return null;
 
-    const docsBaseUrl = (acct.docsBaseUrl || DEFAULT_DOCS_BASE_URL).replace(/\/+$/, "");
-    return { prependContext: buildOnboardingPrompt(docsBaseUrl) };
+    const baseUrl = (acct.docsBaseUrl || "https://botcord.chat").replace(/\/+$/, "");
+    return { prependContext: buildOnboardingPrompt(baseUrl) };
   } catch {
     return null;
   }

package/src/tools/bind.ts

@@ -1,5 +1,5 @@
 /**
- * [INPUT]: 依赖 runtime/config 读取当前 Agent 身份，依赖 BotCordClient 获取 agent_token 并访问 dashboard 绑定接口
+ * [INPUT]: 依赖 runtime/config 读取当前 Agent 身份，依赖 BotCordClient 获取 agent_token 并通过 Hub API 执行绑定
  * [OUTPUT]: 对外提供 botcord_bind 工具与 executeBind 助手，支持短认领码或原始 bind_ticket
  * [POS]: plugin dashboard 认领执行器，把命令行参数翻译成稳定的绑定请求
  * [PROTOCOL]: 变更时更新此头部，然后检查 README.md
@@ -18,7 +18,6 @@ import { getConfig as getAppConfig } from "../runtime.js";
  */
 export async function executeBind(
   bindCredential: string,
-  _dashboardUrl?: string,
 ): Promise<{ ok: true; [key: string]: unknown } | { error: string }> {
   const cfg = getAppConfig();
   if (!cfg) return { error: "No configuration available" };
@@ -40,9 +39,9 @@ export async function executeBind(
     const resolved = (await client.resolve(agentId)) as Record<string, unknown>;
     const displayName = (resolved.display_name as string) || agentId;
 
-    const baseUrl = client.getHubUrl().replace(/\/+$/, "");
+    const hubUrl = client.getHubUrl();
 
-    const res = await fetch(`${baseUrl}/api/users/me/agents/bind`, {
+    const res = await fetch(`${hubUrl}/api/users/me/agents/bind`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -59,8 +58,8 @@ export async function executeBind(
     const body = await res.json().catch(() => null);
 
     if (!res.ok) {
-      const msg = body?.error || body?.message || res.statusText;
-      return { error: `Dashboard bind failed (${res.status}): ${msg}` };
+      const msg = body?.error || body?.detail || body?.message || res.statusText;
+      return { error: `Bind failed (${res.status}): ${msg}` };
     }
 
     return { ok: true, ...body };
@@ -82,10 +81,6 @@ export function createBindTool() {
           type: "string" as const,
           description: "The short bind code or bind ticket from the BotCord web dashboard",
         },
-        dashboard_url: {
-          type: "string" as const,
-          description: "Dashboard base URL (unused, bind endpoint is resolved from Hub URL)",
-        },
       },
       required: ["bind_ticket"],
     },
@@ -93,7 +88,7 @@ export function createBindTool() {
       if (!args.bind_ticket) {
         return { error: "bind_ticket is required" };
       }
-      return executeBind(args.bind_ticket, args.dashboard_url);
+      return executeBind(args.bind_ticket);
     },
   };
 }

package/src/tools/coin-format.ts

@@ -10,3 +10,22 @@ export function formatCoinAmount(minorValue: string | number | null | undefined)
     maximumFractionDigits: 2,
   })} COIN`;
 }
+
+/**
+ * Convert a COIN-denominated string (e.g. "10", "9.50") to a minor-unit
+ * string suitable for the Hub API (1 COIN = 100 minor units).
+ * Accepts non-negative numbers with up to 2 decimal places.
+ * Returns null if the input is missing, malformed, negative, or has 3+ decimals.
+ */
+const COIN_PATTERN = /^(0|[1-9]\d*)(\.\d{1,2})?$/;
+
+export function parseCoinToMinor(coinValue: string | undefined | null): string | null {
+  if (coinValue == null || coinValue === "") return null;
+  const trimmed = coinValue.trim();
+  if (!COIN_PATTERN.test(trimmed)) return null;
+  const dotIndex = trimmed.indexOf(".");
+  if (dotIndex === -1) return String(Number.parseInt(trimmed, 10) * 100);
+  const intPart = trimmed.slice(0, dotIndex);
+  const fracPart = trimmed.slice(dotIndex + 1).padEnd(2, "0");
+  return String(Number.parseInt(intPart, 10) * 100 + Number.parseInt(fracPart, 10));
+}

package/src/tools/payment.ts

@@ -9,7 +9,7 @@ import {
 import { BotCordClient } from "../client.js";
 import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
-import { formatCoinAmount } from "./coin-format.js";
+import { formatCoinAmount, parseCoinToMinor } from "./coin-format.js";
 import { executeTransfer, isPeerContact, formatFollowUpDeliverySummary } from "./payment-transfer.js";
 
 function sanitizeBalance(summary: any): any {
@@ -223,9 +223,9 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           type: "string" as const,
           description: "Recipient agent ID (ag_...) — for transfer",
         },
-        amount_minor: {
+        amount: {
           type: "string" as const,
-          description: "Amount in minor units (1 COIN = 100 minor units). To transfer N coins, pass N × 100. Example: 10 COIN → \"1000\" — for transfer, topup, withdraw",
+          description: "Amount in COIN (supports up to 2 decimals, e.g. \"10\" or \"9.50\") — for transfer, topup, withdraw",
         },
         memo: {
           type: "string" as const,
@@ -259,9 +259,9 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           type: "object" as const,
           description: "Withdrawal destination details — for withdraw",
         },
-        fee_minor: {
+        fee: {
           type: "string" as const,
-          description: "Optional withdrawal fee in minor units (1 COIN = 100 minor units) — for withdraw",
+          description: "Optional withdrawal fee in COIN (e.g. \"1\" or \"0.50\") — for withdraw",
         },
         withdrawal_id: {
           type: "string" as const,
@@ -328,18 +328,20 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
 
           case "transfer": {
             if (!args.to_agent_id) return { error: "to_agent_id is required" };
-            if (!args.amount_minor) return { error: "amount_minor is required" };
+            if (!args.amount) return { error: "amount is required" };
+            const transferMinor = parseCoinToMinor(args.amount);
+            if (transferMinor === null) return { error: "amount must be a valid number (e.g. \"10\" or \"9.50\")" };
 
             const isContact = await isPeerContact(client, args.to_agent_id);
             if (!isContact && args.confirmed !== true) {
               return {
-                result: `\u26a0\ufe0f ${args.to_agent_id} is not in your contacts. This is a stranger transfer of ${formatCoinAmount(args.amount_minor)}. To proceed, call this tool again with confirmed: true. The transfer will create a chat room between you and the recipient.`,
+                result: `\u26a0\ufe0f ${args.to_agent_id} is not in your contacts. This is a stranger transfer of ${formatCoinAmount(transferMinor)}. To proceed, call this tool again with confirmed: true. The transfer will create a chat room between you and the recipient.`,
               };
             }
 
             const transfer = await executeTransfer(client, {
               to_agent_id: args.to_agent_id,
-              amount_minor: args.amount_minor,
+              amount_minor: transferMinor,
               memo: args.memo,
               reference_type: args.reference_type,
               reference_id: args.reference_id,
@@ -353,9 +355,11 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           }
 
           case "topup": {
-            if (!args.amount_minor) return { error: "amount_minor is required" };
+            if (!args.amount) return { error: "amount is required" };
+            const topupMinor = parseCoinToMinor(args.amount);
+            if (topupMinor === null) return { error: "amount must be a valid number (e.g. \"10\" or \"9.50\")" };
             const topup = await client.createTopup({
-              amount_minor: args.amount_minor,
+              amount_minor: topupMinor,
               channel: args.channel,
               metadata: args.metadata,
               idempotency_key: args.idempotency_key,
@@ -364,10 +368,17 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           }
 
           case "withdraw": {
-            if (!args.amount_minor) return { error: "amount_minor is required" };
+            if (!args.amount) return { error: "amount is required" };
+            const withdrawMinor = parseCoinToMinor(args.amount);
+            if (withdrawMinor === null) return { error: "amount must be a valid number (e.g. \"10\" or \"9.50\")" };
+            let feeMinor: string | undefined;
+            if (args.fee) {
+              feeMinor = parseCoinToMinor(args.fee) ?? undefined;
+              if (feeMinor === undefined) return { error: "fee must be a valid number (e.g. \"1\" or \"0.50\")" };
+            }
             const withdrawal = await client.createWithdrawal({
-              amount_minor: args.amount_minor,
-              fee_minor: args.fee_minor,
+              amount_minor: withdrawMinor,
+              fee_minor: feeMinor,
               destination_type: args.destination_type,
               destination: args.destination,
               idempotency_key: args.idempotency_key,

package/src/tools/room-context.ts

@@ -11,6 +11,23 @@ import { BotCordClient } from "../client.js";
 import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
+/** Normalize query input: accept a string or string[] from the LLM. */
+function _normalizeQuery(raw: unknown): string | string[] | null {
+  if (Array.isArray(raw)) {
+    const parts = raw
+      .filter((v) => typeof v === "string")
+      .map((s: string) => s.trim())
+      .filter(Boolean);
+    if (parts.length === 0) return null;
+    return parts.length === 1 ? parts[0] : parts;
+  }
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    return trimmed || null;
+  }
+  return null;
+}
+
 export function createRoomContextTool() {
   return {
     name: "botcord_room_context",
@@ -44,8 +61,9 @@ export function createRoomContextTool() {
             "Room ID (rm_...) — required for room_summary, room_messages, room_search; optional filter for global_search",
         },
         query: {
-          type: "string" as const,
-          description: "Search query text — required for room_search and global_search",
+          description:
+            "Search query — required for room_search and global_search. " +
+            "Pass a single string or an array of strings for OR search (e.g., ['deploy', 'release']).",
         },
         topic_id: {
           type: "string" as const,
@@ -104,8 +122,9 @@ export function createRoomContextTool() {
 
           case "room_search": {
             if (!args.room_id) return { error: "room_id is required for room_search" };
-            if (!args.query) return { error: "query is required for room_search" };
-            return await client.roomSearch(args.room_id, args.query, {
+            const rsQuery = _normalizeQuery(args.query);
+            if (!rsQuery) return { error: "query is required for room_search" };
+            return await client.roomSearch(args.room_id, rsQuery, {
               limit: args.limit,
               before: args.before,
               topicId: args.topic_id,
@@ -118,8 +137,9 @@ export function createRoomContextTool() {
           }
 
           case "global_search": {
-            if (!args.query) return { error: "query is required for global_search" };
-            return await client.globalSearch(args.query, {
+            const gsQuery = _normalizeQuery(args.query);
+            if (!gsQuery) return { error: "query is required for global_search" };
+            return await client.globalSearch(gsQuery, {
               limit: args.limit,
               roomId: args.room_id,
               topicId: args.topic_id,

package/src/tools/subscription.ts

@@ -9,7 +9,7 @@ import {
 import { BotCordClient } from "../client.js";
 import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
-import { formatCoinAmount } from "./coin-format.js";
+import { formatCoinAmount, parseCoinToMinor } from "./coin-format.js";
 
 function formatProduct(product: any): string {
   return [
@@ -98,14 +98,14 @@ export function createSubscriptionTool() {
           type: "string" as const,
           description: "Room rule/instructions — for create_subscription_room or bind_room_to_product",
         },
-        amount_minor: {
+        amount: {
           type: "string" as const,
-          description: "Price in minor coin units — for create_product",
+          description: "Price in COIN (supports up to 2 decimals, e.g. \"10\" or \"9.50\") — for create_product",
         },
         billing_interval: {
           type: "string" as const,
-          enum: ["week", "month"],
-          description: "Billing interval — for create_product",
+          enum: ["week", "month", "once"],
+          description: "Billing interval — for create_product. Use \"once\" for one-time payment (no recurring charges)",
         },
         asset_code: {
           type: "string" as const,
@@ -148,12 +148,14 @@ export function createSubscriptionTool() {
         switch (args.action) {
           case "create_product": {
             if (!args.name) return { error: "name is required" };
-            if (!args.amount_minor) return { error: "amount_minor is required" };
+            if (!args.amount) return { error: "amount is required" };
             if (!args.billing_interval) return { error: "billing_interval is required" };
+            const amountMinor = parseCoinToMinor(args.amount);
+            if (amountMinor === null) return { error: "amount must be a valid number (e.g. \"10\" or \"9.50\")" };
             const product = await client.createSubscriptionProduct({
               name: args.name,
               description: args.description,
-              amount_minor: args.amount_minor,
+              amount_minor: amountMinor,
               billing_interval: args.billing_interval,
               asset_code: args.asset_code,
             });

package/src/types.ts

@@ -220,7 +220,7 @@ export type WithdrawalResponse = {
   completed_at: string | null;
 };
 
-export type BillingInterval = "week" | "month";
+export type BillingInterval = "week" | "month" | "once";
 
 export type SubscriptionProductStatus = "active" | "archived";