@botcord/botcord 0.3.4 → 0.3.6-beta.20260413082920

package/src/hub-url.ts

@@ -1,41 +1 @@
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
-
-function isLoopbackHost(hostname: string): boolean {
-  const normalized = hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
-  return LOOPBACK_HOSTS.has(normalized) || normalized.endsWith(".localhost");
-}
-
-export function normalizeAndValidateHubUrl(hubUrl: string): string {
-  const trimmed = hubUrl.trim();
-  if (!trimmed) {
-    throw new Error("BotCord hubUrl is required");
-  }
-
-  let parsed: URL;
-  try {
-    parsed = new URL(trimmed);
-  } catch {
-    throw new Error(`BotCord hubUrl must be a valid absolute URL: ${hubUrl}`);
-  }
-
-  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-    throw new Error("BotCord hubUrl must use http:// or https://");
-  }
-
-  if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
-    throw new Error(
-      "BotCord hubUrl must use https:// unless it targets localhost, 127.0.0.1, or ::1 for local development",
-    );
-  }
-
-  return trimmed.replace(/\/$/, "");
-}
-
-export function buildHubWebSocketUrl(hubUrl: string): string {
-  const parsed = new URL(normalizeAndValidateHubUrl(hubUrl));
-  parsed.protocol = parsed.protocol === "https:" ? "wss:" : "ws:";
-  parsed.search = "";
-  parsed.hash = "";
-  parsed.pathname = `${parsed.pathname.replace(/\/$/, "")}/hub/ws`;
-  return parsed.toString();
-}
+export * from "@botcord/protocol-core";

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,115 @@
 /**
- * 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 (900000–1800000 ms)
+- For social/casual bots: every 1–2 hours (3600000–7200000 ms)
+- For monitoring/alert bots: every 5–15 minutes (300000–900000 ms)
+
+Use the **cron** tool (agent tool, NOT CLI) to create the job. The cron tool will automatically infer the delivery target from the current BotCord session — no need to specify channel or to.
+
+Example cron tool call:
+\`\`\`json
+{
+  "action": "add",
+  "job": {
+    "name": "botcord-check",
+    "schedule": { "kind": "every", "everyMs": <interval_in_ms> },
+    "payload": {
+      "kind": "agentTurn",
+      "message": "检查 BotCord 是否有未回复的消息或待处理的任务，如果有，立即处理。"
+    }
+  }
+}
+\`\`\`
+
+Help the user choose the interval, then call the cron tool with action "add". After it succeeds, use action "list" to verify. 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. Please type /botcord_healthcheck in the chat."
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STEP 6 — Health Check | 健康检查
+
+Ask the user to type \`/botcord_healthcheck\` in the chat. This is a slash command that only the user can trigger — you cannot run it yourself.
+Explain that it verifies connectivity and marks onboarding as complete.
+If the user reports it passed: celebrate and summarize what was set up.
+If the user reports it failed: help diagnose and fix, then ask them to re-run \`/botcord_healthcheck\`.`;
 }
 
 // ── before_prompt_build handler ────────────────────────────────────
@@ -60,8 +131,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/session-key.ts

@@ -1,59 +1 @@
-/**
- * Deterministic session key derivation.
- * Must match hub/forward.py build_session_key() exactly.
- */
-import { createHash } from "node:crypto";
-
-// UUID v5 namespace — must match hub/constants.py SESSION_KEY_NAMESPACE
-const SESSION_KEY_NAMESPACE = "d4e8f2a1-3b6c-4d5e-9f0a-1b2c3d4e5f6a";
-
-/**
- * RFC 4122 UUID v5 (SHA-1 based, deterministic).
- */
-function uuidV5(name: string, namespace: string): string {
-  // Parse namespace UUID to bytes
-  const nsHex = namespace.replace(/-/g, "");
-  const nsBytes = Buffer.from(nsHex, "hex");
-
-  const hash = createHash("sha1")
-    .update(nsBytes)
-    .update(Buffer.from(name, "utf-8"))
-    .digest();
-
-  // Set version (5) and variant (RFC 4122)
-  hash[6] = (hash[6] & 0x0f) | 0x50;
-  hash[8] = (hash[8] & 0x3f) | 0x80;
-
-  const hex = hash.subarray(0, 16).toString("hex");
-  return [
-    hex.slice(0, 8),
-    hex.slice(8, 12),
-    hex.slice(12, 16),
-    hex.slice(16, 20),
-    hex.slice(20, 32),
-  ].join("-");
-}
-
-/**
- * Derive a deterministic sessionKey from room_id, optional topic, and senderId.
- * Same inputs always produce the same key.
- *
- * - Group room: seed from room_id (+ optional topic)
- * - DM with room_id (rm_dm_*): seed from room_id (already unique per DM pair)
- * - DM without room_id: seed from senderId to isolate per-sender conversations
- */
-export function buildSessionKey(
-  roomId?: string,
-  topic?: string,
-  senderId?: string,
-): string {
-  let seed: string;
-  if (roomId) {
-    seed = topic ? `${roomId}:${topic}` : roomId;
-  } else if (senderId) {
-    seed = `dm:${senderId}`;
-  } else {
-    seed = "default";
-  }
-  return `botcord:${uuidV5(seed, SESSION_KEY_NAMESPACE)}`;
-}
+export * from "@botcord/protocol-core";

package/src/tools/account.ts

@@ -1,14 +1,8 @@
 /**
  * botcord_account — Manage the agent's own identity, profile, and settings.
  */
-import {
-  getSingleAccountModeError,
-  resolveAccountConfig,
-  isAccountConfigured,
-} from "../config.js";
-import { BotCordClient } from "../client.js";
-import { attachTokenPersistence } from "../credentials.js";
-import { getConfig as getAppConfig } from "../runtime.js";
+import { withClient } from "./with-client.js";
+import { validationError, dryRunResult } from "./tool-result.js";
 
 export function createAccountTool() {
   return {
@@ -41,35 +35,25 @@ export function createAccountTool() {
           type: "string" as const,
           description: "Message ID — for message_status",
         },
+        dry_run: {
+          type: "boolean" as const,
+          description: "Preview the request without executing. Returns the API call that would be made.",
+        },
       },
       required: ["action"],
     },
     execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
-      const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      const singleAccountError = getSingleAccountModeError(cfg);
-      if (singleAccountError) return { error: singleAccountError };
-
-      const acct = resolveAccountConfig(cfg);
-      if (!isAccountConfigured(acct)) {
-        return { error: "BotCord is not configured." };
-      }
-
-      const client = new BotCordClient(acct);
-      attachTokenPersistence(client, acct);
-
-      try {
+      return withClient(async (client) => {
         switch (args.action) {
           case "whoami":
             return await client.resolve(client.getAgentId());
 
           case "update_profile": {
-            if (!args.display_name && !args.bio) {
-              return { error: "At least one of display_name or bio is required" };
-            }
+            if (!args.display_name && !args.bio) return validationError("At least one of display_name or bio is required");
             const params: { display_name?: string; bio?: string } = {};
             if (args.display_name) params.display_name = args.display_name;
             if (args.bio) params.bio = args.bio;
+            if (args.dry_run) return dryRunResult("PATCH", `/registry/agents/${client.getAgentId()}/profile`, params);
             await client.updateProfile(params);
             return { ok: true, updated: params };
           }
@@ -77,21 +61,21 @@ export function createAccountTool() {
           case "get_policy":
             return await client.getPolicy();
 
-          case "set_policy":
-            if (!args.policy) return { error: "policy is required (open or contacts_only)" };
+          case "set_policy": {
+            if (!args.policy) return validationError("policy is required (open or contacts_only)");
+            if (args.dry_run) return dryRunResult("PATCH", `/registry/agents/${client.getAgentId()}/policy`, { message_policy: args.policy });
             await client.setPolicy(args.policy);
             return { ok: true, policy: args.policy };
+          }
 
           case "message_status":
-            if (!args.msg_id) return { error: "msg_id is required" };
+            if (!args.msg_id) return validationError("msg_id is required");
             return await client.getMessageStatus(args.msg_id);
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Account action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/api.ts

@@ -0,0 +1,112 @@
+/**
+ * botcord_api — Raw Hub API access for advanced use cases.
+ *
+ * This is the "escape hatch" tool: when the structured tools don't cover
+ * a particular endpoint, agents can call the Hub API directly.
+ */
+import { withClient } from "./with-client.js";
+import { validationError } from "./tool-result.js";
+
+export function createApiTool() {
+  return {
+    name: "botcord_api",
+    label: "Raw API",
+    description:
+      "Execute a raw authenticated request against the BotCord Hub API. " +
+      "Use this when the structured tools (botcord_send, botcord_rooms, etc.) " +
+      "don't cover the endpoint you need. The request is automatically authenticated with your agent's JWT.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        method: {
+          type: "string" as const,
+          enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+          description: "HTTP method",
+        },
+        path: {
+          type: "string" as const,
+          description: "API path (e.g. /hub/inbox, /registry/agents/ag_xxx)",
+        },
+        query: {
+          type: "object" as const,
+          description: "Query parameters as key-value pairs",
+        },
+        data: {
+          type: "object" as const,
+          description: "Request body (for POST/PUT/PATCH)",
+        },
+        confirm: {
+          type: "boolean" as const,
+          description: "Must be true for write operations (POST/PUT/PATCH/DELETE). Safety gate to prevent unintended mutations.",
+        },
+      },
+      required: ["method", "path"],
+    },
+    execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
+      if (!args.method) return validationError("method is required");
+      if (!args.path) return validationError("path is required");
+
+      const method = (args.method as string).toUpperCase();
+      const path = args.path as string;
+
+      // Validate path to prevent SSRF / path traversal.
+      const ALLOWED_PREFIXES = ["/hub/", "/registry/", "/wallet/", "/subscriptions/", "/app/"];
+
+      // Reject absolute URLs (scheme://...) — path must be relative to Hub
+      if (/^[a-z][a-z0-9+.-]*:/i.test(path)) {
+        return validationError(
+          "Absolute URLs are not allowed — provide a path like /hub/inbox",
+          "Path traversal and arbitrary URLs are not allowed.",
+        );
+      }
+
+      // Reject query strings embedded in path — callers must use the query field.
+      // URL normalization strips ?… from path, so silently accepting them would
+      // drop parameters the caller intended to send.
+      if (path.includes("?")) {
+        return validationError(
+          "Query strings in path are not allowed — use the query parameter instead",
+          'e.g. path: "/hub/search", query: { q: "deploy" }',
+        );
+      }
+
+      // Resolve against dummy base to normalize percent-encoded traversal
+      // (e.g. /%2e%2e/ → /../ → resolved away by URL constructor)
+      let resolvedPath: string;
+      try {
+        resolvedPath = new URL(path, "http://localhost").pathname;
+      } catch {
+        return validationError("Invalid path", "Could not parse the provided path as a URL.");
+      }
+      const normalized = resolvedPath.replace(/\/+/g, "/"); // collapse duplicate slashes
+      if (normalized.includes("..") || !ALLOWED_PREFIXES.some((p) => normalized.startsWith(p))) {
+        return validationError(
+          `path must start with one of: ${ALLOWED_PREFIXES.join(", ")}`,
+          "Path traversal and arbitrary URLs are not allowed.",
+        );
+      }
+
+      // Write operations require explicit confirmation via confirm param
+      if (method !== "GET" && !args.confirm) {
+        return {
+          ok: false,
+          error: {
+            type: "validation" as const,
+            code: "confirmation_required",
+            message: `${method} ${path} is a write operation — set confirm: true to proceed`,
+            hint: "Raw API write operations bypass structured tool safeguards. Review the request carefully before confirming.",
+          },
+        };
+      }
+
+      return withClient(async (client) => {
+        // Use the normalized path so the request matches what was validated
+        const result = await client.request(method, normalized, {
+          body: args.data,
+          query: args.query,
+        });
+        return { response: result };
+      });
+    },
+  };
+}

package/src/tools/bind.ts

@@ -1,39 +1,20 @@
 /**
- * [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
  */
-import {
-  getSingleAccountModeError,
-  resolveAccountConfig,
-  isAccountConfigured,
-} from "../config.js";
-import { BotCordClient } from "../client.js";
-import { attachTokenPersistence } from "../credentials.js";
-import { getConfig as getAppConfig } from "../runtime.js";
+import { withClient } from "./with-client.js";
+import { validationError } from "./tool-result.js";
+import { HubApiError } from "../client.js";
 
 /**
  * Shared bind logic used by both the tool and the command.
  */
 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" };
-  const singleAccountError = getSingleAccountModeError(cfg);
-  if (singleAccountError) return { error: singleAccountError };
-
-  const acct = resolveAccountConfig(cfg);
-  if (!isAccountConfigured(acct)) {
-    return { error: "BotCord is not configured." };
-  }
-
-  const client = new BotCordClient(acct);
-  attachTokenPersistence(client, acct);
-
-  try {
+) {
+  return withClient(async (client) => {
     const agentToken = await client.ensureToken();
     const agentId = client.getAgentId();
 
@@ -59,14 +40,12 @@ 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;
+      throw new HubApiError(res.status, JSON.stringify({ detail: msg }), "/api/users/me/agents/bind");
     }
 
     return { ok: true, ...body };
-  } catch (err: any) {
-    return { error: `Bind failed: ${err.message}` };
-  }
+  });
 }
 
 export function createBindTool() {
@@ -82,18 +61,14 @@ 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"],
     },
     execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
       if (!args.bind_ticket) {
-        return { error: "bind_ticket is required" };
+        return validationError("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));
+}