@botcord/botcord 0.3.4 → 0.3.6-beta.20260413082920

package/src/tools/rooms.ts

@@ -1,14 +1,8 @@
 /**
  * botcord_rooms — Room lifecycle and membership management.
  */
-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 createRoomsTool() {
   return {
@@ -102,27 +96,19 @@ export function createRoomsTool() {
           type: "boolean" as const,
           description: "Mute or unmute the current member in a room — for mute",
         },
+        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":
-            if (!args.name) return { error: "name is required" };
+            if (!args.name) return validationError("name is required");
+            if (args.dry_run) return dryRunResult("POST", "/hub/rooms", { name: args.name, visibility: args.visibility || "private", join_policy: args.join_policy, member_ids: args.member_ids });
             return await client.createRoom({
               name: args.name,
               description: args.description,
@@ -138,14 +124,15 @@ export function createRoomsTool() {
             });
 
           case "list":
-            return await client.listMyRooms();
+            return { rooms: await client.listMyRooms() };
 
           case "info":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
             return await client.getRoomInfo(args.room_id);
 
           case "update":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("PATCH", `/hub/rooms/${args.room_id}`, { name: args.name, description: args.description, 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 });
             return await client.updateRoom(args.room_id, {
               name: args.name,
               description: args.description,
@@ -160,10 +147,11 @@ export function createRoomsTool() {
             });
 
           case "discover":
-            return await client.discoverRooms(args.name);
+            return await client.discoverPublicRooms(args.name);
 
           case "join":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/members`, { agent_id: "{self}" });
             await client.joinRoom(args.room_id, {
               can_send: args.can_send,
               can_invite: args.can_invite,
@@ -171,21 +159,24 @@ export function createRoomsTool() {
             return { ok: true, joined: args.room_id };
 
           case "leave":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/leave`);
             await client.leaveRoom(args.room_id);
             return { ok: true, left: args.room_id };
 
           case "dissolve":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("DELETE", `/hub/rooms/${args.room_id}`);
             await client.dissolveRoom(args.room_id);
             return { ok: true, dissolved: args.room_id };
 
           case "members":
-            if (!args.room_id) return { error: "room_id is required" };
-            return await client.getRoomMembers(args.room_id);
+            if (!args.room_id) return validationError("room_id is required");
+            return { members: await client.getRoomMembers(args.room_id) };
 
           case "invite":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/members`, { agent_id: args.agent_id, can_send: args.can_send, can_invite: args.can_invite });
             await client.inviteToRoom(args.room_id, args.agent_id, {
               can_send: args.can_send,
               can_invite: args.can_invite,
@@ -193,22 +184,26 @@ export function createRoomsTool() {
             return { ok: true, invited: args.agent_id, room: args.room_id };
 
           case "remove_member":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("DELETE", `/hub/rooms/${args.room_id}/members/${args.agent_id}`);
             await client.removeMember(args.room_id, args.agent_id);
             return { ok: true, removed: args.agent_id, room: args.room_id };
 
           case "promote":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/promote`, { agent_id: args.agent_id, role: args.role || "admin" });
             await client.promoteMember(args.room_id, args.agent_id, args.role || "admin");
             return { ok: true, promoted: args.agent_id, role: args.role || "admin", room: args.room_id };
 
           case "transfer":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/transfer`, { new_owner_id: args.agent_id });
             await client.transferOwnership(args.room_id, args.agent_id);
             return { ok: true, new_owner: args.agent_id, room: args.room_id };
 
           case "permissions":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/permissions`, { agent_id: args.agent_id, can_send: args.can_send, can_invite: args.can_invite });
             await client.setMemberPermissions(args.room_id, args.agent_id, {
               can_send: args.can_send,
               can_invite: args.can_invite,
@@ -216,16 +211,15 @@ 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" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/mute`, { muted: args.muted ?? true });
             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}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Room action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/subscription.ts

@@ -1,15 +1,9 @@
 /**
  * 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 { formatCoinAmount } from "./coin-format.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 {
   return [
@@ -98,14 +92,14 @@ export function createSubscriptionTool() {
           type: "string" as const,
           description: "Room rule/instructions — for create_subscription_room or bind_room_to_product",
         },
-        amount_minor: {
+        amount: {
           type: "string" as const,
-          description: "Price in minor coin units — for create_product",
+          description: "Price in COIN (supports up to 2 decimals, e.g. \"10\" or \"9.50\") — for create_product",
         },
         billing_interval: {
           type: "string" as const,
-          enum: ["week", "month"],
-          description: "Billing interval — for create_product",
+          enum: ["week", "month", "once"],
+          description: "Billing interval — for create_product. Use \"once\" for one-time payment (no recurring charges)",
         },
         asset_code: {
           type: "string" as const,
@@ -127,33 +121,27 @@ 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_minor) return { error: "amount_minor 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 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,
-              amount_minor: args.amount_minor,
+              amount_minor: amountMinor,
               billing_interval: args.billing_interval,
               asset_code: args.asset_code,
             });
@@ -171,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,
@@ -198,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,
@@ -219,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 };
           }
@@ -230,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}` };
-      }
+      });
     },
   };
 }