@botcord/openclaw-plugin 0.0.4 → 0.0.6

package/src/tools/payment-transfer.ts

@@ -0,0 +1,153 @@
+import type { BotCordClient } from "../client.js";
+import type { WalletTransaction } from "../types.js";
+import { formatCoinAmount } from "./coin-format.js";
+
+type FollowUpDeliveryResult = {
+  attempted: true;
+  sent: boolean;
+  hub_msg_id?: string;
+  error?: string;
+};
+
+export type ContactOnlyTransferResult = {
+  tx: WalletTransaction;
+  transfer_record_message: FollowUpDeliveryResult;
+  notifications: {
+    payer: FollowUpDeliveryResult;
+    payee: FollowUpDeliveryResult;
+  };
+};
+
+function extractTransferMetadata(tx: WalletTransaction): Record<string, unknown> | null {
+  if (!tx.metadata_json) return null;
+  try {
+    return typeof tx.metadata_json === "string"
+      ? JSON.parse(tx.metadata_json)
+      : tx.metadata_json;
+  } catch {
+    return null;
+  }
+}
+
+function formatOptionalLine(label: string, value: string | null | undefined): string | null {
+  return value ? `${label}: ${value}` : null;
+}
+
+export async function assertTransferPeerIsContact(client: BotCordClient, toAgentId: string): Promise<void> {
+  const contacts = await client.listContacts();
+  const isContact = contacts.some((contact) => contact.contact_agent_id === toAgentId);
+  if (!isContact) {
+    throw new Error("Transfer is only allowed between contacts. Please add this agent as a contact first.");
+  }
+}
+
+export function buildTransferRecordMessage(tx: WalletTransaction): string {
+  const metadata = extractTransferMetadata(tx);
+  return [
+    "[BotCord Transfer]",
+    `Status: ${tx.status}`,
+    `Transaction: ${tx.tx_id}`,
+    `Amount: ${formatCoinAmount(tx.amount_minor)}`,
+    `Asset: ${tx.asset_code}`,
+    formatOptionalLine("From", tx.from_agent_id),
+    formatOptionalLine("To", tx.to_agent_id),
+    formatOptionalLine("Memo", typeof metadata?.memo === "string" ? metadata.memo : undefined),
+    formatOptionalLine("Reference type", tx.reference_type),
+    formatOptionalLine("Reference id", tx.reference_id),
+    `Created: ${tx.created_at}`,
+  ].filter(Boolean).join("\n");
+}
+
+export function buildTransferNotificationMessage(
+  tx: WalletTransaction,
+  role: "payer" | "payee",
+): string {
+  if (role === "payer") {
+    return `[BotCord Notice] Transfer sent: ${formatCoinAmount(tx.amount_minor)} to ${tx.to_agent_id} (tx: ${tx.tx_id})`;
+  }
+  return `[BotCord Notice] Payment received: ${formatCoinAmount(tx.amount_minor)} from ${tx.from_agent_id} (tx: ${tx.tx_id})`;
+}
+
+export function formatFollowUpDeliverySummary(result: ContactOnlyTransferResult): string {
+  const lines = [
+    `Transfer record message: ${result.transfer_record_message.sent ? "sent" : "failed"}`,
+    `Payer notification: ${result.notifications.payer.sent ? "sent" : "failed"}`,
+    `Payee notification: ${result.notifications.payee.sent ? "sent" : "failed"}`,
+  ];
+  const failures = [
+    result.transfer_record_message.error,
+    result.notifications.payer.error,
+    result.notifications.payee.error,
+  ].filter(Boolean);
+  if (failures.length > 0) {
+    lines.push("Warning: some follow-up messages failed to send.");
+  }
+  return lines.join("\n");
+}
+
+async function sendRecordMessage(
+  client: BotCordClient,
+  tx: WalletTransaction,
+): Promise<FollowUpDeliveryResult> {
+  try {
+    const response = await client.sendMessage(tx.to_agent_id || "", buildTransferRecordMessage(tx));
+    return { attempted: true, sent: true, hub_msg_id: response.hub_msg_id };
+  } catch (err: any) {
+    return { attempted: true, sent: false, error: err?.message ?? String(err) };
+  }
+}
+
+async function sendNotification(
+  client: BotCordClient,
+  to: string,
+  tx: WalletTransaction,
+  role: "payer" | "payee",
+): Promise<FollowUpDeliveryResult> {
+  try {
+    const response = await client.sendSystemMessage(to, buildTransferNotificationMessage(tx, role), {
+      event: "wallet_transfer_notice",
+      role,
+      tx_id: tx.tx_id,
+      amount_minor: tx.amount_minor,
+      asset_code: tx.asset_code,
+      from_agent_id: tx.from_agent_id,
+      to_agent_id: tx.to_agent_id,
+      reference_type: tx.reference_type,
+      reference_id: tx.reference_id,
+    });
+    return { attempted: true, sent: true, hub_msg_id: response.hub_msg_id };
+  } catch (err: any) {
+    return { attempted: true, sent: false, error: err?.message ?? String(err) };
+  }
+}
+
+export async function executeContactOnlyTransfer(
+  client: BotCordClient,
+  params: {
+    to_agent_id: string;
+    amount_minor: string;
+    memo?: string;
+    reference_type?: string;
+    reference_id?: string;
+    metadata?: Record<string, unknown>;
+    idempotency_key?: string;
+  },
+): Promise<ContactOnlyTransferResult> {
+  await assertTransferPeerIsContact(client, params.to_agent_id);
+
+  const tx = await client.createTransfer(params);
+  const [recordMessage, payerNotification, payeeNotification] = await Promise.all([
+    sendRecordMessage(client, tx),
+    sendNotification(client, client.getAgentId(), tx, "payer"),
+    sendNotification(client, params.to_agent_id, tx, "payee"),
+  ]);
+
+  return {
+    tx,
+    transfer_record_message: recordMessage,
+    notifications: {
+      payer: payerNotification,
+      payee: payeeNotification,
+    },
+  };
+}

package/src/tools/payment.ts

@@ -0,0 +1,384 @@
+/**
+ * botcord_payment — Unified payment and transaction tool for BotCord coin flows.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+import { formatCoinAmount } from "./coin-format.js";
+import { executeContactOnlyTransfer, formatFollowUpDeliverySummary } from "./payment-transfer.js";
+
+function sanitizeBalance(summary: any): any {
+  return {
+    agent_id: summary.agent_id,
+    asset_code: summary.asset_code,
+    available_balance: formatCoinAmount(summary.available_balance_minor),
+    locked_balance: formatCoinAmount(summary.locked_balance_minor),
+    total_balance: formatCoinAmount(summary.total_balance_minor),
+    updated_at: summary.updated_at,
+  };
+}
+
+function formatBalance(summary: any): string {
+  const available = summary.available_balance_minor ?? "0";
+  const locked = summary.locked_balance_minor ?? "0";
+  const total = summary.total_balance_minor ?? "0";
+  return [
+    `Asset: ${summary.asset_code}`,
+    `Available: ${formatCoinAmount(available)}`,
+    `Locked:    ${formatCoinAmount(locked)}`,
+    `Total:     ${formatCoinAmount(total)}`,
+    `Updated:   ${summary.updated_at}`,
+  ].join("\n");
+}
+
+function formatRecipient(agent: any): string {
+  return [
+    `Agent: ${agent.agent_id}`,
+    `Name: ${agent.display_name || "(none)"}`,
+    `Policy: ${agent.message_policy || "(unknown)"}`,
+    `Endpoints: ${Array.isArray(agent.endpoints) ? agent.endpoints.length : 0}`,
+  ].join("\n");
+}
+
+function extractMetadata(tx: any): Record<string, unknown> | null {
+  if (!tx?.metadata_json) return null;
+  try {
+    return typeof tx.metadata_json === "string"
+      ? JSON.parse(tx.metadata_json)
+      : tx.metadata_json;
+  } catch {
+    return null;
+  }
+}
+
+function sanitizeTransaction(tx: any): any {
+  const metadata = extractMetadata(tx);
+  return {
+    tx_id: tx.tx_id,
+    type: tx.type,
+    status: tx.status,
+    asset_code: tx.asset_code,
+    amount: formatCoinAmount(tx.amount_minor),
+    fee: formatCoinAmount(tx.fee_minor),
+    from_agent_id: tx.from_agent_id,
+    to_agent_id: tx.to_agent_id,
+    reference_type: tx.reference_type,
+    reference_id: tx.reference_id,
+    idempotency_key: tx.idempotency_key,
+    metadata: metadata ?? undefined,
+    created_at: tx.created_at,
+    updated_at: tx.updated_at,
+    completed_at: tx.completed_at,
+  };
+}
+
+function sanitizeTransferResult(transfer: any): any {
+  return {
+    tx: sanitizeTransaction(transfer.tx),
+    transfer_record_message: transfer.transfer_record_message,
+    notifications: transfer.notifications,
+  };
+}
+
+function formatTransaction(tx: any): string {
+  const lines = [
+    `Transaction: ${tx.tx_id}`,
+    `Type:   ${tx.type}`,
+    `Status: ${tx.status}`,
+    `Amount: ${formatCoinAmount(tx.amount_minor)}`,
+    `Fee:    ${formatCoinAmount(tx.fee_minor)}`,
+  ];
+  if (tx.from_agent_id) lines.push(`From: ${tx.from_agent_id}`);
+  if (tx.to_agent_id) lines.push(`To:   ${tx.to_agent_id}`);
+  if (tx.reference_type) lines.push(`Reference type: ${tx.reference_type}`);
+  if (tx.reference_id) lines.push(`Reference id:   ${tx.reference_id}`);
+  const metadata = extractMetadata(tx);
+  if (metadata?.memo) lines.push(`Memo: ${String(metadata.memo)}`);
+  if (tx.idempotency_key) lines.push(`Idempotency: ${tx.idempotency_key}`);
+  lines.push(`Created: ${tx.created_at}`);
+  if (tx.completed_at) lines.push(`Completed: ${tx.completed_at}`);
+  return lines.join("\n");
+}
+
+function formatTopup(topup: any): string {
+  return [
+    `Topup: ${topup.topup_id}`,
+    `Status: ${topup.status}`,
+    `Amount: ${formatCoinAmount(topup.amount_minor)}`,
+    `Channel: ${topup.channel}`,
+    `Created: ${topup.created_at}`,
+    topup.completed_at ? `Completed: ${topup.completed_at}` : null,
+  ].filter(Boolean).join("\n");
+}
+
+function sanitizeTopup(topup: any): any {
+  return {
+    topup_id: topup.topup_id,
+    status: topup.status,
+    asset_code: topup.asset_code,
+    amount: formatCoinAmount(topup.amount_minor),
+    channel: topup.channel,
+    idempotency_key: topup.idempotency_key,
+    created_at: topup.created_at,
+    updated_at: topup.updated_at,
+    completed_at: topup.completed_at,
+  };
+}
+
+function formatWithdrawal(withdrawal: any): string {
+  return [
+    `Withdrawal: ${withdrawal.withdrawal_id}`,
+    `Status: ${withdrawal.status}`,
+    `Amount: ${formatCoinAmount(withdrawal.amount_minor)}`,
+    `Fee: ${formatCoinAmount(withdrawal.fee_minor)}`,
+    withdrawal.destination_type ? `Destination type: ${withdrawal.destination_type}` : null,
+    `Created: ${withdrawal.created_at}`,
+    withdrawal.reviewed_at ? `Reviewed: ${withdrawal.reviewed_at}` : null,
+    withdrawal.completed_at ? `Completed: ${withdrawal.completed_at}` : null,
+  ].filter(Boolean).join("\n");
+}
+
+function sanitizeWithdrawal(withdrawal: any): any {
+  return {
+    withdrawal_id: withdrawal.withdrawal_id,
+    status: withdrawal.status,
+    asset_code: withdrawal.asset_code,
+    amount: formatCoinAmount(withdrawal.amount_minor),
+    fee: formatCoinAmount(withdrawal.fee_minor),
+    destination_type: withdrawal.destination_type,
+    destination: withdrawal.destination,
+    idempotency_key: withdrawal.idempotency_key,
+    created_at: withdrawal.created_at,
+    updated_at: withdrawal.updated_at,
+    reviewed_at: withdrawal.reviewed_at,
+    completed_at: withdrawal.completed_at,
+  };
+}
+
+function formatLedger(data: any): string {
+  const entries = data.entries ?? [];
+  if (entries.length === 0) return "No payment ledger entries found.";
+
+  const lines = entries.map((e: any) => {
+    const dir = e.direction === "credit" ? "+" : "-";
+    return `${e.created_at} | ${dir}${formatCoinAmount(e.amount_minor)} | bal=${formatCoinAmount(e.balance_after_minor)} | tx=${e.tx_id}`;
+  });
+
+  if (data.has_more) {
+    lines.push(`\n(More entries available — use cursor: "${data.next_cursor}")`);
+  }
+  return lines.join("\n");
+}
+
+function sanitizeLedger(data: any): any {
+  const entries = (data.entries ?? []).map((entry: any) => ({
+    entry_id: entry.entry_id,
+    tx_id: entry.tx_id,
+    direction: entry.direction,
+    amount: formatCoinAmount(entry.amount_minor),
+    balance_after: formatCoinAmount(entry.balance_after_minor),
+    created_at: entry.created_at,
+  }));
+
+  return {
+    entries,
+    next_cursor: data.next_cursor,
+    has_more: data.has_more,
+  };
+}
+
+export function createPaymentTool(opts?: { name?: string; description?: string }) {
+  return {
+    name: opts?.name || "botcord_payment",
+    description:
+      opts?.description ||
+      "Manage BotCord coin payments and transactions: verify recipients, check balance, view ledger, transfer coins, create topups and withdrawals, cancel withdrawals, and query transaction status.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        action: {
+          type: "string" as const,
+          enum: [
+            "recipient_verify",
+            "balance",
+            "ledger",
+            "transfer",
+            "topup",
+            "withdraw",
+            "cancel_withdrawal",
+            "tx_status",
+          ],
+          description: "Payment action to perform",
+        },
+        agent_id: {
+          type: "string" as const,
+          description: "Agent ID (ag_...) — for recipient_verify",
+        },
+        to_agent_id: {
+          type: "string" as const,
+          description: "Recipient agent ID (ag_...) — for transfer",
+        },
+        amount_minor: {
+          type: "string" as const,
+          description: "Amount in minor units (string) — for transfer, topup, withdraw",
+        },
+        memo: {
+          type: "string" as const,
+          description: "Optional payment memo — for transfer",
+        },
+        reference_type: {
+          type: "string" as const,
+          description: "Optional business reference type — for transfer",
+        },
+        reference_id: {
+          type: "string" as const,
+          description: "Optional business reference ID — for transfer",
+        },
+        metadata: {
+          type: "object" as const,
+          description: "Optional metadata object — for transfer or topup",
+        },
+        idempotency_key: {
+          type: "string" as const,
+          description: "Optional idempotency key — for transfer, topup, withdraw",
+        },
+        channel: {
+          type: "string" as const,
+          description: "Topup channel (e.g. 'mock') — for topup",
+        },
+        destination_type: {
+          type: "string" as const,
+          description: "Withdrawal destination type — for withdraw",
+        },
+        destination: {
+          type: "object" as const,
+          description: "Withdrawal destination details — for withdraw",
+        },
+        fee_minor: {
+          type: "string" as const,
+          description: "Optional withdrawal fee in minor units — for withdraw",
+        },
+        withdrawal_id: {
+          type: "string" as const,
+          description: "Withdrawal ID — for cancel_withdrawal",
+        },
+        tx_id: {
+          type: "string" as const,
+          description: "Transaction ID — for tx_status",
+        },
+        cursor: {
+          type: "string" as const,
+          description: "Pagination cursor — for ledger",
+        },
+        limit: {
+          type: "number" as const,
+          description: "Max entries to return — for ledger",
+        },
+        type: {
+          type: "string" as const,
+          description: "Filter by transaction type — for ledger",
+        },
+      },
+      required: ["action"],
+    },
+    execute: async (_toolCallId: any, args: 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);
+
+      try {
+        switch (args.action) {
+          case "recipient_verify": {
+            if (!args.agent_id) return { error: "agent_id is required" };
+            const agent = await client.resolve(args.agent_id);
+            return { result: formatRecipient(agent), data: agent };
+          }
+
+          case "balance": {
+            const summary = await client.getWallet();
+            return { result: formatBalance(summary), data: sanitizeBalance(summary) };
+          }
+
+          case "ledger": {
+            const opts: { cursor?: string; limit?: number; type?: string } = {};
+            if (args.cursor) opts.cursor = args.cursor;
+            if (args.limit) opts.limit = args.limit;
+            if (args.type) opts.type = args.type;
+            const ledger = await client.getWalletLedger(opts);
+            return { result: formatLedger(ledger), data: sanitizeLedger(ledger) };
+          }
+
+          case "transfer": {
+            if (!args.to_agent_id) return { error: "to_agent_id is required" };
+            if (!args.amount_minor) return { error: "amount_minor is required" };
+            const transfer = await executeContactOnlyTransfer(client, {
+              to_agent_id: args.to_agent_id,
+              amount_minor: args.amount_minor,
+              memo: args.memo,
+              reference_type: args.reference_type,
+              reference_id: args.reference_id,
+              metadata: args.metadata,
+              idempotency_key: args.idempotency_key,
+            });
+            return {
+              result: `${formatTransaction(transfer.tx)}\n${formatFollowUpDeliverySummary(transfer)}`,
+              data: sanitizeTransferResult(transfer),
+            };
+          }
+
+          case "topup": {
+            if (!args.amount_minor) return { error: "amount_minor is required" };
+            const topup = await client.createTopup({
+              amount_minor: args.amount_minor,
+              channel: args.channel,
+              metadata: args.metadata,
+              idempotency_key: args.idempotency_key,
+            });
+            return { result: formatTopup(topup), data: sanitizeTopup(topup) };
+          }
+
+          case "withdraw": {
+            if (!args.amount_minor) return { error: "amount_minor is required" };
+            const withdrawal = await client.createWithdrawal({
+              amount_minor: args.amount_minor,
+              fee_minor: args.fee_minor,
+              destination_type: args.destination_type,
+              destination: args.destination,
+              idempotency_key: args.idempotency_key,
+            });
+            return { result: formatWithdrawal(withdrawal), data: sanitizeWithdrawal(withdrawal) };
+          }
+
+          case "cancel_withdrawal": {
+            if (!args.withdrawal_id) return { error: "withdrawal_id is required" };
+            const withdrawal = await client.cancelWithdrawal(args.withdrawal_id);
+            return { result: formatWithdrawal(withdrawal), data: sanitizeWithdrawal(withdrawal) };
+          }
+
+          case "tx_status": {
+            if (!args.tx_id) return { error: "tx_id is required" };
+            const tx = await client.getWalletTransaction(args.tx_id);
+            return { result: formatTransaction(tx), data: sanitizeTransaction(tx) };
+          }
+
+          default:
+            return { error: `Unknown action: ${args.action}` };
+        }
+      } catch (err: any) {
+        return { error: `Payment action failed: ${err.message}` };
+      }
+    },
+  };
+}

package/src/tools/rooms.ts

@@ -24,7 +24,7 @@ export function createRoomsTool() {
             "create", "list", "info", "update", "discover",
             "join", "leave", "dissolve",
             "members", "invite", "remove_member",
-            "promote", "transfer", "permissions",
+            "promote", "transfer", "permissions", "mute",
           ],
           description: "Room action to perform",
         },
@@ -58,6 +58,27 @@ export function createRoomsTool() {
           type: "boolean" as const,
           description: "Whether all members can post — for create, update",
         },
+        default_invite: {
+          type: "boolean" as const,
+          description: "Whether members can invite by default — for create, update",
+        },
+        max_members: {
+          type: "number" as const,
+          description: "Maximum room members — for create, update",
+        },
+        slow_mode_seconds: {
+          type: "number" as const,
+          description: "Slow mode interval in seconds — for create, update",
+        },
+        required_subscription_product_id: {
+          type: "string" as const,
+          description: "Subscription product required to access this room — for create, update",
+        },
+        member_ids: {
+          type: "array" as const,
+          items: { type: "string" as const },
+          description: "Initial member agent IDs — for create",
+        },
         agent_id: {
           type: "string" as const,
           description: "Agent ID — for invite, remove_member, promote, transfer, permissions",
@@ -75,6 +96,10 @@ export function createRoomsTool() {
           type: "boolean" as const,
           description: "Invite permission override — for permissions",
         },
+        muted: {
+          type: "boolean" as const,
+          description: "Mute or unmute the current member in a room — for mute",
+        },
       },
       required: ["action"],
     },
@@ -101,7 +126,12 @@ export function createRoomsTool() {
               rule: args.rule,
               visibility: args.visibility || "private",
               join_policy: args.join_policy,
+              required_subscription_product_id: args.required_subscription_product_id,
+              max_members: args.max_members,
               default_send: args.default_send,
+              default_invite: args.default_invite,
+              slow_mode_seconds: args.slow_mode_seconds,
+              member_ids: args.member_ids,
             });
 
           case "list":
@@ -119,7 +149,11 @@ export function createRoomsTool() {
               rule: args.rule,
               visibility: args.visibility,
               join_policy: args.join_policy,
+              required_subscription_product_id: args.required_subscription_product_id,
+              max_members: args.max_members,
               default_send: args.default_send,
+              default_invite: args.default_invite,
+              slow_mode_seconds: args.slow_mode_seconds,
             });
 
           case "discover":
@@ -127,7 +161,10 @@ export function createRoomsTool() {
 
           case "join":
             if (!args.room_id) return { error: "room_id is required" };
-            await client.joinRoom(args.room_id);
+            await client.joinRoom(args.room_id, {
+              can_send: args.can_send,
+              can_invite: args.can_invite,
+            });
             return { ok: true, joined: args.room_id };
 
           case "leave":
@@ -146,7 +183,10 @@ export function createRoomsTool() {
 
           case "invite":
             if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
-            await client.inviteToRoom(args.room_id, args.agent_id);
+            await client.inviteToRoom(args.room_id, args.agent_id, {
+              can_send: args.can_send,
+              can_invite: args.can_invite,
+            });
             return { ok: true, invited: args.agent_id, room: args.room_id };
 
           case "remove_member":
@@ -172,6 +212,11 @@ export function createRoomsTool() {
             });
             return { ok: true, agent: args.agent_id, room: args.room_id };
 
+          case "mute":
+            if (!args.room_id) return { error: "room_id is required" };
+            await client.muteRoom(args.room_id, args.muted ?? true);
+            return { ok: true, room: args.room_id, muted: args.muted ?? true };
+
           default:
             return { error: `Unknown action: ${args.action}` };
         }