@botcord/botcord 0.3.6 → 0.3.8-beta.20260415044559

package/src/tools/subscription.ts

@@ -1,14 +1,8 @@
 /**
  * botcord_subscription — Create and manage coin-priced subscription products.
  */
-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";
 import { formatCoinAmount, parseCoinToMinor } from "./coin-format.js";
 
 function formatProduct(product: any): string {
@@ -127,31 +121,23 @@ export function createSubscriptionTool() {
           type: "number" as const,
           description: "Slow mode interval in seconds — for create_subscription_room or bind_room_to_product",
         },
+        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 "create_product": {
-            if (!args.name) return { error: "name is required" };
-            if (!args.amount) return { error: "amount is required" };
-            if (!args.billing_interval) return { error: "billing_interval is required" };
+            if (!args.name) return validationError("name is required");
+            if (!args.amount) return validationError("amount is required");
+            if (!args.billing_interval) return validationError("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\")" };
+            if (amountMinor === null) return validationError("amount must be a valid number (e.g. \"10\" or \"9.50\")");
+            if (args.dry_run) return dryRunResult("POST", "/subscriptions/products", { name: args.name, amount_minor: amountMinor, billing_interval: args.billing_interval });
             const product = await client.createSubscriptionProduct({
               name: args.name,
               description: args.description,
@@ -173,14 +159,16 @@ export function createSubscriptionTool() {
           }
 
           case "archive_product": {
-            if (!args.product_id) return { error: "product_id is required" };
+            if (!args.product_id) return validationError("product_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/subscriptions/products/${args.product_id}/archive`);
             const product = await client.archiveSubscriptionProduct(args.product_id);
             return { result: formatProduct(product), data: product };
           }
 
           case "create_subscription_room": {
-            if (!args.product_id) return { error: "product_id is required" };
-            if (!args.name) return { error: "name is required" };
+            if (!args.product_id) return validationError("product_id is required");
+            if (!args.name) return validationError("name is required");
+            if (args.dry_run) return dryRunResult("POST", "/hub/rooms", { name: args.name, description: args.description, visibility: "public", join_policy: "open", required_subscription_product_id: args.product_id });
             const room = await client.createRoom({
               name: args.name,
               description: args.description,
@@ -200,8 +188,9 @@ export function createSubscriptionTool() {
           }
 
           case "bind_room_to_product": {
-            if (!args.room_id) return { error: "room_id is required" };
-            if (!args.product_id) return { error: "product_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (!args.product_id) return validationError("product_id is required");
+            if (args.dry_run) return dryRunResult("PATCH", `/hub/rooms/${args.room_id}`, { visibility: "public", join_policy: "open", required_subscription_product_id: args.product_id });
             const room = await client.updateRoom(args.room_id, {
               name: args.name,
               description: args.description,
@@ -221,7 +210,8 @@ export function createSubscriptionTool() {
           }
 
           case "subscribe": {
-            if (!args.product_id) return { error: "product_id is required" };
+            if (!args.product_id) return validationError("product_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/subscriptions/products/${args.product_id}/subscribe`);
             const subscription = await client.subscribeToProduct(args.product_id, args.idempotency_key);
             return { result: formatSubscription(subscription), data: subscription };
           }
@@ -232,23 +222,22 @@ export function createSubscriptionTool() {
           }
 
           case "list_subscribers": {
-            if (!args.product_id) return { error: "product_id is required" };
+            if (!args.product_id) return validationError("product_id is required");
             const subscriptions = await client.listProductSubscribers(args.product_id);
             return { result: formatSubscriptionList(subscriptions), data: subscriptions };
           }
 
           case "cancel": {
-            if (!args.subscription_id) return { error: "subscription_id is required" };
+            if (!args.subscription_id) return validationError("subscription_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/subscriptions/${args.subscription_id}/cancel`);
             const subscription = await client.cancelSubscription(args.subscription_id);
             return { result: formatSubscription(subscription), data: subscription };
           }
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Subscription action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/tool-result.ts

@@ -28,7 +28,8 @@ export interface DryRunRequest {
   method: string;
   path: string;
   body?: unknown;
-  query?: Record<string, string>;
+  query?: Record<string, string | string[]>;
+  note?: string;
 }
 
 export type DryRunResult = { ok: true; dry_run: true; request: DryRunRequest };
@@ -60,11 +61,17 @@ export function apiError(code: string, message: string, hint?: string): ToolFail
   return fail("api", code, message, hint);
 }
 
-export function dryRunResult(method: string, path: string, body?: unknown, query?: Record<string, string>): DryRunResult {
+export function dryRunResult(method: string, path: string, body?: unknown, options?: { query?: Record<string, string | string[]>; note?: string }): DryRunResult {
   return {
     ok: true,
     dry_run: true,
-    request: { method, path, ...(body !== undefined ? { body } : {}), ...(query ? { query } : {}) },
+    request: {
+      method,
+      path,
+      ...(body !== undefined ? { body } : {}),
+      ...(options?.query ? { query: options.query } : {}),
+      ...(options?.note ? { note: options.note } : {}),
+    },
   };
 }
 

package/src/tools/topics.ts

@@ -1,14 +1,8 @@
 /**
  * botcord_topics — Topic lifecycle management within rooms.
  */
-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 createTopicsTool() {
   return {
@@ -50,27 +44,19 @@ export function createTopicsTool() {
           enum: ["open", "completed", "failed", "expired"],
           description: "Topic status — for list (filter) or update (transition)",
         },
+        dry_run: {
+          type: "boolean" as const,
+          description: "Preview the request without executing. Returns the API call that would be made.",
+        },
       },
       required: ["action", "room_id"],
     },
     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 "create":
-            if (!args.title) return { error: "title is required" };
+            if (!args.title) return validationError("title is required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/topics`, { title: args.title, description: args.description, goal: args.goal });
             return await client.createTopic(args.room_id, {
               title: args.title,
               description: args.description,
@@ -78,14 +64,15 @@ export function createTopicsTool() {
             });
 
           case "list":
-            return await client.listTopics(args.room_id, args.status);
+            return { topics: await client.listTopics(args.room_id, args.status) };
 
           case "get":
-            if (!args.topic_id) return { error: "topic_id is required" };
+            if (!args.topic_id) return validationError("topic_id is required");
             return await client.getTopic(args.room_id, args.topic_id);
 
           case "update":
-            if (!args.topic_id) return { error: "topic_id is required" };
+            if (!args.topic_id) return validationError("topic_id is required");
+            if (args.dry_run) return dryRunResult("PATCH", `/hub/rooms/${args.room_id}/topics/${args.topic_id}`, { title: args.title, status: args.status, goal: args.goal });
             return await client.updateTopic(args.room_id, args.topic_id, {
               title: args.title,
               description: args.description,
@@ -94,16 +81,15 @@ export function createTopicsTool() {
             });
 
           case "delete":
-            if (!args.topic_id) return { error: "topic_id is required" };
+            if (!args.topic_id) return validationError("topic_id is required");
+            if (args.dry_run) return dryRunResult("DELETE", `/hub/rooms/${args.room_id}/topics/${args.topic_id}`);
             await client.deleteTopic(args.room_id, args.topic_id);
             return { ok: true, deleted: args.topic_id, room: args.room_id };
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Topic action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/types.ts

@@ -1,38 +1,7 @@
-// BotCord protocol types (mirrors hub/schemas.py)
-
-export type BotCordSignature = {
-  alg: "ed25519";
-  key_id: string;
-  value: string; // base64
-};
-
-export type MessageType =
-  | "message"
-  | "ack"
-  | "result"
-  | "error"
-  | "contact_request"
-  | "contact_request_response"
-  | "contact_removed"
-  | "system";
-
-export type BotCordMessageEnvelope = {
-  v: string;
-  msg_id: string;
-  ts: number;
-  from: string;
-  to: string;
-  type: MessageType;
-  reply_to: string | null;
-  ttl_sec: number;
-  topic?: string | null;
-  goal?: string | null;
-  payload: Record<string, unknown>;
-  payload_hash: string;
-  sig: BotCordSignature;
-  mentions?: string[] | null;
-};
+// Re-export all protocol types from shared package
+export * from "@botcord/protocol-core";
 
+// Plugin-specific types (not shared)
 // Account config in openclaw.json channels.botcord
 export type BotCordAccountConfig = {
   enabled?: boolean;
@@ -52,252 +21,3 @@ export type BotCordAccountConfig = {
 };
 
 export type BotCordChannelConfig = BotCordAccountConfig;
-
-// Inbox poll response
-export type SourceType = "agent" | "dashboard_user_chat";
-
-export type InboxMessage = {
-  hub_msg_id: string;
-  envelope: BotCordMessageEnvelope;
-  text?: string;
-  room_id?: string;
-  room_name?: string;
-  room_rule?: string | null;
-  room_member_count?: number;
-  room_member_names?: string[];
-  my_role?: string;
-  my_can_send?: boolean;
-  topic?: string;
-  topic_id?: string;
-  goal?: string;
-  mentioned?: boolean;
-  source_type?: SourceType;
-  source_user_id?: string | null;
-  source_user_name?: string | null;
-  source_session_kind?: string | null;
-};
-
-export type InboxPollResponse = {
-  messages: InboxMessage[];
-  count: number;
-  has_more: boolean;
-};
-
-// Hub API response types
-export type SendResponse = {
-  queued: boolean;
-  hub_msg_id: string;
-  status: string;
-  topic_id?: string;
-};
-
-export type RoomInfo = {
-  room_id: string;
-  name: string;
-  description?: string;
-  rule?: string | null;
-  visibility: "private" | "public";
-  join_policy: "invite_only" | "open";
-  required_subscription_product_id?: string | null;
-  max_members?: number | null;
-  default_send: boolean;
-  default_invite?: boolean;
-  slow_mode_seconds?: number | null;
-  member_count: number;
-  created_at: string;
-};
-
-export type PublicSubscriptionProduct = {
-  product_id: string;
-  name: string;
-  description: string;
-  amount_minor: string;
-  billing_interval: string;
-};
-
-export type PublicRoom = {
-  room_id: string;
-  name: string;
-  description: string;
-  owner_id: string;
-  visibility: string;
-  member_count: number;
-  required_subscription_product_id?: string | null;
-  subscription_product?: PublicSubscriptionProduct | null;
-  last_message_preview?: string | null;
-  last_message_at?: string | null;
-  last_sender_name?: string | null;
-};
-
-export type PublicRoomsResponse = {
-  rooms: PublicRoom[];
-  total: number;
-};
-
-export type AgentInfo = {
-  agent_id: string;
-  display_name?: string;
-  bio?: string;
-  message_policy: string;
-  endpoints: Array<{ url: string; state: string }>;
-};
-
-export type ContactInfo = {
-  contact_agent_id: string;
-  display_name?: string;
-  created_at: string;
-};
-
-export type ContactRequestInfo = {
-  request_id: string;
-  from_agent_id: string;
-  to_agent_id: string;
-  state: "pending" | "accepted" | "rejected";
-  created_at: string;
-};
-
-// File upload response (mirrors hub/schemas.py FileUploadResponse)
-export type FileUploadResponse = {
-  file_id: string;
-  url: string;
-  original_filename: string;
-  content_type: string;
-  size_bytes: number;
-  expires_at: string; // ISO 8601
-};
-
-// Attachment metadata included in message payloads
-export type MessageAttachment = {
-  filename: string;
-  url: string;
-  content_type?: string;
-  size_bytes?: number;
-};
-
-// Wallet types (mirrors hub wallet schemas)
-
-export type WalletSummary = {
-  agent_id: string;
-  asset_code: string;
-  available_balance_minor: string;
-  locked_balance_minor: string;
-  total_balance_minor: string;
-  updated_at: string;
-};
-
-export type WalletTransaction = {
-  tx_id: string;
-  type: "topup" | "withdrawal" | "transfer";
-  status: "pending" | "processing" | "completed" | "failed" | "cancelled";
-  asset_code: string;
-  amount_minor: string;
-  fee_minor: string;
-  from_agent_id: string | null;
-  to_agent_id: string | null;
-  reference_type: string | null;
-  reference_id: string | null;
-  idempotency_key: string | null;
-  metadata_json: string | null;
-  created_at: string;
-  updated_at: string;
-  completed_at: string | null;
-};
-
-export type WalletLedgerEntry = {
-  entry_id: string;
-  tx_id: string;
-  agent_id: string;
-  asset_code: string;
-  direction: "debit" | "credit";
-  amount_minor: string;
-  balance_after_minor: string;
-  created_at: string;
-};
-
-export type WalletLedgerResponse = {
-  entries: WalletLedgerEntry[];
-  next_cursor: string | null;
-  has_more: boolean;
-};
-
-export type TopupResponse = {
-  topup_id: string;
-  tx_id: string | null;
-  agent_id: string;
-  asset_code: string;
-  amount_minor: string;
-  status: string;
-  channel: string;
-  created_at: string;
-  completed_at: string | null;
-};
-
-export type WithdrawalResponse = {
-  withdrawal_id: string;
-  tx_id: string | null;
-  agent_id: string;
-  asset_code: string;
-  amount_minor: string;
-  fee_minor: string;
-  status: string;
-  destination_type: string | null;
-  review_note: string | null;
-  created_at: string;
-  reviewed_at: string | null;
-  completed_at: string | null;
-};
-
-export type BillingInterval = "week" | "month" | "once";
-
-export type SubscriptionProductStatus = "active" | "archived";
-
-export type SubscriptionStatus = "active" | "past_due" | "cancelled";
-
-export type SubscriptionChargeAttemptStatus = "pending" | "succeeded" | "failed";
-
-export type SubscriptionProduct = {
-  product_id: string;
-  owner_agent_id: string;
-  name: string;
-  description: string;
-  asset_code: string;
-  amount_minor: string;
-  billing_interval: BillingInterval;
-  status: SubscriptionProductStatus;
-  created_at: string;
-  updated_at: string;
-  archived_at: string | null;
-};
-
-export type Subscription = {
-  subscription_id: string;
-  product_id: string;
-  subscriber_agent_id: string;
-  provider_agent_id: string;
-  asset_code: string;
-  amount_minor: string;
-  billing_interval: BillingInterval;
-  status: SubscriptionStatus;
-  current_period_start: string;
-  current_period_end: string;
-  next_charge_at: string;
-  cancel_at_period_end: boolean;
-  cancelled_at: string | null;
-  last_charged_at: string | null;
-  last_charge_tx_id: string | null;
-  consecutive_failed_attempts: number;
-  created_at: string;
-  updated_at: string;
-};
-
-export type SubscriptionChargeAttempt = {
-  attempt_id: string;
-  subscription_id: string;
-  billing_cycle_key: string;
-  status: SubscriptionChargeAttemptStatus;
-  scheduled_at: string;
-  attempted_at: string | null;
-  tx_id: string | null;
-  failure_reason: string | null;
-  created_at: string;
-};

package/src/onboarding-hook.ts

@@ -1,139 +0,0 @@
-/**
- * Onboarding hook — injects step-by-step onboarding guidance for first-time users.
- *
- * Checks the credential file for `onboardedAt`. If absent, injects a
- * 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";
-
-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 ────────────────────────────────────
-
-/**
- * Build the onboarding hook result for injection into the agent prompt.
- * Only injects when the agent has not been onboarded yet.
- */
-export function buildOnboardingHookResult(): { prependContext?: string } | null {
-  try {
-    const cfg = getConfig();
-    if (!cfg) return null;
-
-    const acct = resolveAccountConfig(cfg);
-    if (!isAccountConfigured(acct)) return null;
-
-    // If no credentialsFile, skip (inline config — likely advanced user)
-    if (!acct.credentialsFile) return null;
-
-    if (isOnboarded(acct.credentialsFile)) return null;
-
-    const baseUrl = (acct.docsBaseUrl || "https://botcord.chat").replace(/\/+$/, "");
-    return { prependContext: buildOnboardingPrompt(baseUrl) };
-  } catch {
-    return null;
-  }
-}