@botcord/botcord 0.2.2 → 0.2.4-beta.20260329125010

package/src/tools/tool-result.ts

@@ -0,0 +1,122 @@
+/**
+ * Structured tool result types and builder helpers.
+ *
+ * Provides a unified response envelope for all BotCord tools:
+ * - Success: { ok: true, ...data }
+ * - Failure: { ok: false, error: { type, code, message, hint? } }
+ * - DryRun:  { ok: true, dry_run: true, request: { method, path, body? } }
+ */
+
+// ── Error types ─────────────────────────────────────────────────
+
+export type ToolErrorType = "config" | "auth" | "validation" | "api" | "network";
+
+export interface ToolError {
+  type: ToolErrorType;
+  code: string;
+  message: string;
+  hint?: string;
+}
+
+// ── Result types ────────────────────────────────────────────────
+
+export type ToolSuccess<T = Record<string, unknown>> = { ok: true } & T;
+export type ToolFailure = { ok: false; error: ToolError };
+export type ToolResult<T = Record<string, unknown>> = ToolSuccess<T> | ToolFailure;
+
+export interface DryRunRequest {
+  method: string;
+  path: string;
+  body?: unknown;
+  query?: Record<string, string>;
+}
+
+export type DryRunResult = { ok: true; dry_run: true; request: DryRunRequest };
+
+// ── Builder helpers ─────────────────────────────────────────────
+
+export function success<T extends Record<string, unknown>>(data: T): ToolSuccess<T> {
+  return { ok: true, ...data };
+}
+
+export function fail(
+  type: ToolErrorType,
+  code: string,
+  message: string,
+  hint?: string,
+): ToolFailure {
+  return { ok: false, error: { type, code, message, ...(hint ? { hint } : {}) } };
+}
+
+export function configError(message: string, hint?: string): ToolFailure {
+  return fail("config", "NOT_CONFIGURED", message, hint);
+}
+
+export function validationError(message: string, hint?: string): ToolFailure {
+  return fail("validation", "INVALID_INPUT", message, hint);
+}
+
+export function apiError(code: string, message: string, hint?: string): ToolFailure {
+  return fail("api", code, message, hint);
+}
+
+export function dryRunResult(method: string, path: string, body?: unknown, query?: Record<string, string>): DryRunResult {
+  return {
+    ok: true,
+    dry_run: true,
+    request: { method, path, ...(body !== undefined ? { body } : {}), ...(query ? { query } : {}) },
+  };
+}
+
+// ── Error classifier ────────────────────────────────────────────
+
+/**
+ * Classify a caught error into a structured ToolFailure.
+ * Recognises HTTP status codes attached by BotCordClient.
+ */
+export function classifyError(err: unknown): ToolFailure {
+  if (!(err instanceof Error)) {
+    return fail("api", "UNKNOWN", String(err));
+  }
+
+  const status = (err as any).status as number | undefined;
+  const message = err.message;
+
+  // Network-level failures
+  if (
+    err.name === "AbortError" ||
+    message.includes("fetch failed") ||
+    message.includes("ECONNREFUSED") ||
+    message.includes("ENOTFOUND") ||
+    message.includes("network")
+  ) {
+    return fail("network", "CONNECTION_FAILED", message, "Check Hub URL and network connectivity");
+  }
+
+  if (!status) {
+    return fail("api", "UNKNOWN", message);
+  }
+
+  switch (status) {
+    case 401:
+      return fail("auth", "TOKEN_EXPIRED", message, "Token refresh may have failed — try again or re-register");
+    case 403: {
+      const code = message.includes("BLOCKED")
+        ? "BLOCKED"
+        : message.includes("NOT_IN_CONTACTS")
+          ? "NOT_IN_CONTACTS"
+          : "FORBIDDEN";
+      return fail("auth", code, message);
+    }
+    case 404:
+      return fail("api", "NOT_FOUND", message, "Verify the target ID exists via botcord_directory(action=\"resolve\")");
+    case 409:
+      return fail("api", "CONFLICT", message);
+    case 422:
+      return fail("validation", "UNPROCESSABLE", message);
+    case 429:
+      return fail("api", "RATE_LIMITED", message, "Throttle requests — 20 msg/min global, 10 msg/min per conversation");
+    default:
+      return fail("api", `HTTP_${status}`, message);
+  }
+}

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,60 +44,66 @@ 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);
+      return withClient(async (client) => {
+        // Dry-run for write operations
+        if (args.dry_run) {
+          switch (args.action) {
+            case "create":
+              if (!args.title) return validationError("title is required");
+              return dryRunResult("POST", `/hub/rooms/${args.room_id}/topics`, { title: args.title, description: args.description, goal: args.goal }) as any;
+            case "update":
+              if (!args.topic_id) return validationError("topic_id is required");
+              return dryRunResult("PATCH", `/hub/rooms/${args.room_id}/topics/${args.topic_id}`, { title: args.title, status: args.status, goal: args.goal }) as any;
+            case "delete":
+              if (!args.topic_id) return validationError("topic_id is required");
+              return dryRunResult("DELETE", `/hub/rooms/${args.room_id}/topics/${args.topic_id}`) as any;
+            default:
+              break;
+          }
+        }
 
-      try {
         switch (args.action) {
           case "create":
-            if (!args.title) return { error: "title is required" };
+            if (!args.title) return validationError("title is required");
             return await client.createTopic(args.room_id, {
               title: args.title,
               description: args.description,
               goal: args.goal,
-            });
+            }) as any;
 
           case "list":
-            return await client.listTopics(args.room_id, args.status);
+            return { topics: await client.listTopics(args.room_id, args.status) } as any;
 
           case "get":
-            if (!args.topic_id) return { error: "topic_id is required" };
-            return await client.getTopic(args.room_id, args.topic_id);
+            if (!args.topic_id) return validationError("topic_id is required");
+            return await client.getTopic(args.room_id, args.topic_id) as any;
 
           case "update":
-            if (!args.topic_id) return { error: "topic_id is required" };
+            if (!args.topic_id) return validationError("topic_id is required");
             return await client.updateTopic(args.room_id, args.topic_id, {
               title: args.title,
               description: args.description,
               status: args.status,
               goal: args.goal,
-            });
+            }) as any;
 
           case "delete":
-            if (!args.topic_id) return { error: "topic_id is required" };
+            if (!args.topic_id) return validationError("topic_id is required");
             await client.deleteTopic(args.room_id, args.topic_id);
-            return { ok: true, deleted: args.topic_id, room: args.room_id };
+            return { ok: true, deleted: args.topic_id, room: args.room_id } as any;
 
           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/tools/with-client.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared tool wrapper that eliminates boilerplate across all BotCord tools.
+ *
+ * Handles: config check → single-account guard → account resolution →
+ * client creation → token persistence → try/catch with error classification.
+ */
+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 type { BotCordAccountConfig } from "../types.js";
+import { configError, classifyError, type ToolFailure, type ToolSuccess } from "./tool-result.js";
+
+/**
+ * Run a tool action with a fully-configured BotCordClient.
+ *
+ * The callback receives the client and resolved account config.
+ * If it returns a plain object, it is automatically wrapped in `{ ok: true, ... }`.
+ * If it returns an object that already has `ok` set, it is passed through as-is.
+ */
+export async function withClient<T extends Record<string, unknown>>(
+  fn: (client: BotCordClient, acct: BotCordAccountConfig) => Promise<T | ToolSuccess<T> | ToolFailure>,
+): Promise<ToolSuccess<T> | ToolFailure> {
+  const cfg = getAppConfig();
+  if (!cfg) {
+    return configError("No configuration available", "Run /botcord_healthcheck to diagnose");
+  }
+
+  const singleErr = getSingleAccountModeError(cfg);
+  if (singleErr) {
+    return configError(singleErr);
+  }
+
+  const acct = resolveAccountConfig(cfg);
+  if (!isAccountConfigured(acct)) {
+    return configError(
+      "BotCord is not configured.",
+      "Run botcord-register to create an identity or botcord-import to restore one",
+    );
+  }
+
+  try {
+    const client = new BotCordClient(acct);
+    attachTokenPersistence(client, acct);
+    const result = await fn(client, acct);
+
+    // If the callback already returned a structured result, pass through
+    if (result && typeof result === "object" && "ok" in result) {
+      return result as ToolSuccess<T> | ToolFailure;
+    }
+
+    // Otherwise wrap in success envelope
+    return { ok: true, ...result } as ToolSuccess<T>;
+  } catch (err: unknown) {
+    return classifyError(err);
+  }
+}
+
+/**
+ * Lightweight version that only checks config availability (no client creation).
+ * Used by tools that don't need a BotCordClient (e.g. register, notify).
+ */
+export async function withConfig<T extends Record<string, unknown>>(
+  fn: (cfg: any, acct: BotCordAccountConfig) => Promise<T | ToolSuccess<T> | ToolFailure>,
+): Promise<ToolSuccess<T> | ToolFailure> {
+  const cfg = getAppConfig();
+  if (!cfg) {
+    return configError("No configuration available", "Run /botcord_healthcheck to diagnose");
+  }
+
+  const singleErr = getSingleAccountModeError(cfg);
+  if (singleErr) {
+    return configError(singleErr);
+  }
+
+  const acct = resolveAccountConfig(cfg);
+
+  try {
+    const result = await fn(cfg, acct);
+
+    if (result && typeof result === "object" && "ok" in result) {
+      return result as ToolSuccess<T> | ToolFailure;
+    }
+
+    return { ok: true, ...result } as ToolSuccess<T>;
+  } catch (err: unknown) {
+    return classifyError(err);
+  }
+}