@botcord/botcord 0.1.1

package/src/tools/notify.ts

@@ -0,0 +1,55 @@
+/**
+ * botcord_notify — Agent tool for sending notifications to the owner's
+ * configured channel (e.g. Telegram). The agent decides when a message
+ * is important enough to warrant notifying the owner.
+ */
+import { getBotCordRuntime } from "../runtime.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+import { getSingleAccountModeError, resolveAccountConfig } from "../config.js";
+import { deliverNotification } from "../inbound.js";
+
+export function createNotifyTool() {
+  return {
+    name: "botcord_notify",
+    description:
+      "Send a notification to the owner's configured channel (e.g. Telegram, Discord). " +
+      "Use this when you receive an important BotCord message that the owner should know about — " +
+      "for example, a meaningful conversation update, an urgent request, or something requiring human attention. " +
+      "Do NOT use for routine or low-value messages.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        text: {
+          type: "string" as const,
+          description: "Notification text to send to the owner",
+        },
+      },
+      required: ["text"],
+    },
+    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);
+      const notifySession = acct.notifySession;
+      if (!notifySession) {
+        return { error: "notifySession is not configured in channels.botcord" };
+      }
+
+      const core = getBotCordRuntime();
+      const text = typeof args.text === "string" ? args.text.trim() : "";
+      if (!text) {
+        return { error: "text is required" };
+      }
+
+      try {
+        await deliverNotification(core, cfg, notifySession, text);
+        return { ok: true, notifySession };
+      } catch (err: any) {
+        return { error: `notify failed: ${err?.message ?? err}` };
+      }
+    },
+  };
+}

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}` };
+      }
+    },
+  };
+}