@toothfairyai/cli 1.0.2

package/README.md

@@ -0,0 +1,57 @@
+# ToothFairy AI CLI (Node.js)
+
+A Node.js command-line interface for interacting with ToothFairy AI agents.
+
+## Installation
+
+### From NPM (when published)
+```bash
+npm install -g toothfairy-cli
+```
+
+### From Source
+```bash
+git clone <repository-url>
+cd toothfairy-cli-js
+npm install
+npm link  # Makes 'toothfairy' command available globally
+```
+
+## Quick Start
+
+1. **Configure your credentials:**
+```bash
+toothfairy configure \
+  --base-url "https://api.toothfairyai.com" \
+  --ai-url "https://ai.toothfairyai.com" \
+  --api-key "your-api-key" \
+  --workspace-id "your-workspace-id"
+```
+
+2. **Send a message to an agent:**
+```bash
+toothfairy send "Hello, I need help with my appointment" \
+  --agent-id "agent-123" \
+  --phone-number "+1234567890" \
+  --customer-id "customer-456" \
+  --provider-id "sms-provider-789"
+```
+
+3. **List your chats:**
+```bash
+toothfairy chats
+```
+
+For full documentation, see the main [README.md](../README.md) in the parent directory.
+
+## Development
+
+```bash
+npm install
+npm run lint
+npm test
+```
+
+## License
+
+MIT

package/bin/toothfairy.js

@@ -0,0 +1,666 @@
+#!/usr/bin/env node
+
+const { Command } = require("commander");
+const chalk = require("chalk");
+const ora = require("ora");
+const { table } = require("table");
+require("dotenv").config();
+
+const ToothFairyAPI = require("../src/api");
+const {
+  loadConfig,
+  saveConfig,
+  ToothFairyConfig,
+  getConfigPath,
+  validateConfiguration,
+} = require("../src/config");
+
+const program = new Command();
+
+program
+  .name("toothfairy")
+  .description(
+    "ToothFairy AI CLI - Interact with ToothFairy AI agents via command line"
+  )
+  .version("1.0.0");
+
+program
+  .option("-c, --config <path>", "path to configuration file")
+  .option("-v, --verbose", "enable verbose logging");
+
+// Configure command
+program
+  .command("configure")
+  .description("Configure ToothFairy CLI credentials and settings")
+  .option(
+    "--base-url <url>",
+    "ToothFairy API base URL",
+    "https://api.toothfairyai.com"
+  )
+  .option("--ai-url <url>", "ToothFairy AI URL", "https://ai.toothfairyai.com")
+  .requiredOption("--api-key <key>", "API key")
+  .requiredOption("--workspace-id <id>", "Workspace ID")
+  .option("--config-path <path>", "Path to save config file")
+  .action(async (options) => {
+    try {
+      const config = new ToothFairyConfig(
+        options.baseUrl,
+        options.aiUrl,
+        options.apiKey,
+        options.workspaceId
+      );
+
+      saveConfig(config, options.configPath);
+      console.log(chalk.green("Configuration saved successfully!"));
+      if (!options.configPath) {
+        console.log(`Config saved to: ${getConfigPath()}`);
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error saving configuration: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Send command
+program
+  .command("send")
+  .description("Send a message to a ToothFairy AI agent")
+  .argument("<message>", "message to send")
+  .requiredOption("--agent-id <id>", "Agent ID to send message to")
+  .option("--phone-number <number>", "Phone number for SMS channel")
+  .option("--customer-id <id>", "Customer ID")
+  .option("--provider-id <id>", "SMS provider ID")
+  .option("--customer-info <json>", "Customer info as JSON string")
+  .option("-o, --output <format>", "Output format (json|text)", "text")
+  .option("-v, --verbose", "Show detailed response information")
+  .action(async (message, options, command) => {
+    try {
+      const globalOptions = command.parent.opts();
+      const config = loadConfig(globalOptions.config);
+      validateConfiguration(config);
+
+      const api = new ToothFairyAPI(
+        config.baseUrl,
+        config.aiUrl,
+        config.apiKey,
+        config.workspaceId,
+        globalOptions.verbose || options.verbose
+      );
+
+      // Parse customer info if provided
+      let customerInfo = {};
+      if (options.customerInfo) {
+        try {
+          customerInfo = JSON.parse(options.customerInfo);
+        } catch (error) {
+          console.error(chalk.red("Invalid JSON in customer-info"));
+          process.exit(1);
+        }
+      }
+
+      const spinner = ora("Sending message to agent...").start();
+
+      const response = await api.sendMessageToAgent(
+        message,
+        options.agentId,
+        options.phoneNumber,
+        options.customerId,
+        options.providerId,
+        customerInfo
+      );
+
+      spinner.stop();
+
+      if (options.output === "json") {
+        console.log(JSON.stringify(response, null, 2));
+      } else {
+        const agentResp = response.agentResponse;
+
+        if (options.verbose) {
+          // Verbose mode: show all details
+          console.log(chalk.green.bold("Message sent successfully!"));
+          console.log();
+
+          const data = [
+            ["Field", "Value"],
+            ["Chat ID", response.chatId],
+            ["Message ID", response.messageId],
+          ];
+
+          console.log(
+            table(data, {
+              header: {
+                alignment: "center",
+                content: "Response Details",
+              },
+            })
+          );
+
+          // Show full agent response
+          console.log(chalk.blue.bold("Agent Response (Full):"));
+          console.log("─".repeat(50));
+          console.log(JSON.stringify(agentResp, null, 2));
+          console.log("─".repeat(50));
+        } else {
+          // Default mode: show only the clean agent text
+          if (agentResp.contents && agentResp.contents.content) {
+            // Extract clean content from the response
+            const cleanContent = agentResp.contents.content.trim();
+            console.log(cleanContent);
+          } else if (agentResp.text) {
+            console.log(agentResp.text);
+          } else {
+            // Fallback if no recognizable text format
+            console.log(
+              chalk.yellow(
+                "No text response found. Use --verbose for full details."
+              )
+            );
+          }
+        }
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error sending message: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Search command
+program
+  .command("search")
+  .description("Search for documents in the knowledge hub")
+  .argument("<query>", "search query text")
+  .option(
+    "-k, --top-k <number>",
+    "Number of documents to retrieve (1-50)",
+    "10"
+  )
+  .option(
+    "--status <status>",
+    "Filter by document status (published|suspended)"
+  )
+  .option("--document-id <id>", "Search within specific document ID")
+  .option("--topics <topics>", "Comma-separated topic IDs to filter by")
+  .option("-o, --output <format>", "Output format (json|text)", "text")
+  .option("-v, --verbose", "Show detailed search information")
+  .action(async (query, options, command) => {
+    try {
+      const globalOptions = command.parent.opts();
+      const config = loadConfig(globalOptions.config);
+      validateConfiguration(config);
+
+      const api = new ToothFairyAPI(
+        config.baseUrl,
+        config.aiUrl,
+        config.apiKey,
+        config.workspaceId,
+        globalOptions.verbose || options.verbose
+      );
+
+      // Validate top-k parameter
+      const topK = parseInt(options.topK);
+      if (isNaN(topK) || topK < 1 || topK > 50) {
+        console.error(
+          chalk.red("Error: --top-k must be a number between 1 and 50")
+        );
+        process.exit(1);
+      }
+
+      // Build metadata filters
+      const metadata = {};
+      if (options.status) {
+        if (!["published", "suspended"].includes(options.status)) {
+          console.error(
+            chalk.red(
+              'Error: --status must be either "published" or "suspended"'
+            )
+          );
+          process.exit(1);
+        }
+        metadata.status = options.status;
+      }
+      if (options.documentId) {
+        metadata.documentId = options.documentId;
+      }
+      if (options.topics) {
+        const topicList = options.topics
+          .split(",")
+          .map((t) => t.trim())
+          .filter((t) => t);
+        if (topicList.length > 0) {
+          metadata.topic = topicList;
+        }
+      }
+
+      const spinner = ora("Searching knowledge hub...").start();
+
+      const results = await api.searchDocuments(
+        query,
+        topK,
+        Object.keys(metadata).length > 0 ? metadata : null
+      );
+
+      spinner.stop();
+
+      if (options.output === "json") {
+        console.log(JSON.stringify(results, null, 2));
+      } else {
+        // Handle different response formats - results might be array or dict
+        const documents = Array.isArray(results)
+          ? results
+          : results.results || [];
+
+        if (!documents || documents.length === 0) {
+          console.log(chalk.yellow("No documents found for your query"));
+          return;
+        }
+
+        console.log(chalk.green.bold(`Found ${documents.length} document(s)`));
+        console.log("=".repeat(50));
+
+        documents.forEach((doc, index) => {
+          const score = doc.cosinesim || 0;
+          const docId = doc.doc_id || doc.chunk_id || "N/A";
+
+          // Extract text content directly from document
+          const textContent = doc.raw_text || "No content available";
+          const docStatus = doc.status || "unknown";
+          const docTopics = doc.topics || [];
+          const docTitle = doc.title || "Untitled";
+
+          console.log(
+            chalk.cyan.bold(`\n${docTitle}`),
+            chalk.gray(`(Score: ${score.toFixed(3)})`)
+          );
+
+          if (options.verbose) {
+            // Verbose mode: show all details
+            const data = [
+              ["Field", "Value"],
+              ["Document ID", docId],
+              ["Title", docTitle],
+              ["Relevance Score", score.toFixed(4)],
+              ["Status", docStatus],
+              ["Topics", docTopics.length > 0 ? docTopics.join(", ") : "None"],
+              [
+                "Content Preview",
+                textContent.length > 200
+                  ? textContent.substring(0, 200) + "..."
+                  : textContent,
+              ],
+            ];
+
+            console.log(table(data));
+          } else {
+            // Default mode: show clean content
+            console.log("─".repeat(50));
+            const displayContent =
+              textContent.length > 500
+                ? textContent.substring(0, 500) + "..."
+                : textContent;
+            console.log(displayContent);
+            console.log("─".repeat(50));
+          }
+        });
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error searching documents: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Chats command
+program
+  .command("chats")
+  .description("List all chats in the workspace")
+  .option("-o, --output <format>", "Output format (json|text)", "text")
+  .action(async (options, command) => {
+    try {
+      const globalOptions = command.parent.opts();
+      const config = loadConfig(globalOptions.config);
+      validateConfiguration(config);
+
+      const api = new ToothFairyAPI(
+        config.baseUrl,
+        config.aiUrl,
+        config.apiKey,
+        config.workspaceId,
+        globalOptions.verbose || options.verbose
+      );
+
+      const spinner = ora("Fetching chats...").start();
+      const chatsData = await api.getAllChats();
+      spinner.stop();
+
+      if (options.output === "json") {
+        console.log(JSON.stringify(chatsData, null, 2));
+      } else {
+        if (
+          !chatsData ||
+          (Array.isArray(chatsData) && chatsData.length === 0)
+        ) {
+          console.log(chalk.yellow("No chats found"));
+          return;
+        }
+
+        const chatList = Array.isArray(chatsData)
+          ? chatsData
+          : chatsData.items || [];
+
+        const data = [["Chat ID", "Name", "Customer ID", "Created"]];
+
+        chatList.forEach((chat) => {
+          data.push([
+            chat.id || "N/A",
+            chat.name || "N/A",
+            chat.customerId || "N/A",
+            chat.createdAt || "N/A",
+          ]);
+        });
+
+        console.log(
+          table(data, {
+            header: {
+              alignment: "center",
+              content: "Workspace Chats",
+            },
+          })
+        );
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error fetching chats: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Chat command (get specific chat)
+program
+  .command("chat")
+  .description("Get details of a specific chat")
+  .argument("<chat-id>", "Chat ID to retrieve")
+  .option("-o, --output <format>", "Output format (json|text)", "text")
+  .action(async (chatId, options, command) => {
+    try {
+      const globalOptions = command.parent.opts();
+      const config = loadConfig(globalOptions.config);
+      validateConfiguration(config);
+
+      const api = new ToothFairyAPI(
+        config.baseUrl,
+        config.aiUrl,
+        config.apiKey,
+        config.workspaceId,
+        globalOptions.verbose || options.verbose
+      );
+
+      const spinner = ora(`Fetching chat ${chatId}...`).start();
+      const chatData = await api.getChat(chatId);
+      spinner.stop();
+
+      if (options.output === "json") {
+        console.log(JSON.stringify(chatData, null, 2));
+      } else {
+        console.log(chalk.green.bold("Chat Details"));
+        console.log();
+
+        const data = [["Field", "Value"]];
+
+        Object.entries(chatData).forEach(([key, value]) => {
+          let displayValue = value;
+          if (typeof value === "object" && value !== null) {
+            displayValue = JSON.stringify(value, null, 2);
+          }
+          data.push([key, String(displayValue)]);
+        });
+
+        console.log(table(data));
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error fetching chat: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Config show command
+program
+  .command("config-show")
+  .description("Show current configuration")
+  .action(async (options, command) => {
+    try {
+      const globalOptions = command.parent.opts();
+      const config = loadConfig(globalOptions.config);
+
+      const data = [
+        ["Setting", "Value"],
+        ["Base URL", config.baseUrl],
+        ["AI URL", config.aiUrl],
+        [
+          "API Key",
+          config.apiKey
+            ? `${"*".repeat(20)}...${config.apiKey.slice(-4)}`
+            : "Not set",
+        ],
+        ["Workspace ID", config.workspaceId],
+      ];
+
+      console.log(
+        table(data, {
+          header: {
+            alignment: "center",
+            content: "Current Configuration",
+          },
+        })
+      );
+    } catch (error) {
+      console.error(chalk.red(`Configuration error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Help guide command
+program
+  .command("help-guide")
+  .description("Show detailed help and usage examples")
+  .action(() => {
+    console.log(chalk.cyan.bold("🚀 ToothFairy AI CLI - Quick Start Guide"));
+    console.log("=".repeat(50));
+
+    console.log(chalk.green.bold("\n🚀 Getting Started"));
+    console.log("1. First, configure your credentials:");
+    console.log(
+      chalk.dim(
+        "   tf configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE"
+      )
+    );
+
+    console.log("\n2. Send a message to an agent:");
+    console.log(
+      chalk.dim('   tf send "Hello, I need help" --agent-id YOUR_AGENT_ID')
+    );
+
+    console.log("\n3. Search the knowledge hub:");
+    console.log(chalk.dim('   tf search "AI configuration help"'));
+
+    console.log("\n4. Explore your workspace:");
+    console.log(
+      chalk.dim("   tf chats                    # List all conversations")
+    );
+    console.log(
+      chalk.dim("   tf config-show              # View current settings")
+    );
+
+    console.log(chalk.blue.bold("\n💬 Agent Communication Examples"));
+
+    const agentExamples = [
+      [
+        "Simple message",
+        'tf send "What are your hours?" --agent-id "info-agent"',
+      ],
+      [
+        "With customer info",
+        'tf send "Schedule appointment" --agent-id "scheduler" --customer-info \'{"name": "John"}\'',
+      ],
+      ["Verbose output", 'tf send "Hello" --agent-id "agent-123" --verbose'],
+      [
+        "JSON for scripting",
+        'tf send "Help" --agent-id "agent-123" --output json',
+      ],
+    ];
+
+    const agentData = [["Use Case", "Command"], ...agentExamples];
+    console.log(
+      table(agentData, {
+        header: {
+          alignment: "center",
+          content: "Agent Communication",
+        },
+      })
+    );
+
+    console.log(chalk.magenta.bold("\n🔍 Knowledge Hub Search Examples"));
+
+    const searchExamples = [
+      ["Basic search", 'tf search "AI agent configuration"'],
+      ["Filter by status", 'tf search "machine learning" --status published'],
+      ["Limit results", 'tf search "troubleshooting" --top-k 3'],
+      [
+        "Topic filtering",
+        'tf search "automation" --topics "topic_123,topic_456"',
+      ],
+      ["Specific document", 'tf search "settings" --document-id "doc_550..."'],
+      ["Verbose details", 'tf search "deployment" --verbose'],
+      ["JSON output", 'tf search "API docs" --output json'],
+    ];
+
+    const searchData = [["Use Case", "Command"], ...searchExamples];
+    console.log(
+      table(searchData, {
+        header: {
+          alignment: "center",
+          content: "Knowledge Hub Search",
+        },
+      })
+    );
+
+    console.log(chalk.green.bold("\n📋 Workspace Management Examples"));
+
+    const mgmtExamples = [
+      ["List all chats", "tf chats"],
+      ["View chat details", "tf chat CHAT_ID"],
+      ["Show config", "tf config-show"],
+      ["Detailed help", "tf help-guide"],
+    ];
+
+    const mgmtData = [["Use Case", "Command"], ...mgmtExamples];
+    console.log(
+      table(mgmtData, {
+        header: {
+          alignment: "center",
+          content: "Workspace Management",
+        },
+      })
+    );
+
+    console.log(chalk.yellow.bold("\n🔧 Configuration Options"));
+    const configOptions = [
+      ["Method", "Description", "Example"],
+      [
+        "Environment",
+        "Set environment variables",
+        "export TF_API_KEY=your_key",
+      ],
+      [
+        "Config file",
+        "Use ~/.toothfairy/config.yml",
+        "api_key: your_key\\nworkspace_id: your_workspace",
+      ],
+      [
+        "CLI arguments",
+        "Pass config file path",
+        "tf --config /path/to/config.yml send ...",
+      ],
+    ];
+
+    console.log(table(configOptions));
+
+    console.log(chalk.red.bold("\n⚠️  Common Issues & Solutions"));
+    const issues = [
+      ["Issue", "Solution"],
+      [
+        "Configuration incomplete",
+        "Run: tf configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE",
+      ],
+      [
+        "No text response found",
+        "Use --verbose flag to see full response details",
+      ],
+      ["Agent not responding", "Check agent-id is correct and agent is active"],
+      [
+        "Network errors",
+        "Verify API endpoints are accessible and credentials are valid",
+      ],
+    ];
+
+    console.log(table(issues));
+
+    console.log(chalk.cyan.bold("\n🔍 Search Filtering Guide"));
+    console.log("Knowledge Hub search supports powerful filtering options:");
+    console.log(
+      "• " +
+        chalk.cyan("--status") +
+        ": Filter documents by 'published' or 'suspended' status"
+    );
+    console.log(
+      "• " +
+        chalk.cyan("--topics") +
+        ": Use topic IDs from ToothFairyAI (comma-separated)"
+    );
+    console.log(
+      "• " + chalk.cyan("--document-id") + ": Search within a specific document"
+    );
+    console.log(
+      "• " + chalk.cyan("--top-k") + ": Control number of results (1-50)"
+    );
+    console.log(
+      "• " + chalk.cyan("--verbose") + ": Show relevance scores and metadata"
+    );
+
+    console.log(chalk.magenta.bold("\n📖 More Help"));
+    console.log(
+      "• Use " + chalk.cyan("tf COMMAND --help") + " for command-specific help"
+    );
+    console.log(
+      "• Use " +
+        chalk.cyan("--verbose") +
+        " flag to see detailed request/response information"
+    );
+    console.log(
+      "• Use " + chalk.cyan("--output json") + " for machine-readable output"
+    );
+    console.log(
+      "• Configuration is loaded from: environment variables → ~/.toothfairy/config.yml → CLI args"
+    );
+
+    console.log(chalk.green.bold("\n✨ Pro Tips"));
+    const tips = [
+      "💾 Save time: Configure once with 'tf configure', then just use 'tf send' and 'tf search'",
+      "🔍 Debug issues: Use '--verbose' to see full API responses and troubleshoot",
+      "📝 Scripting: Use '--output json' and tools like 'jq' to parse responses",
+      "⚡ Quick tests: Only --agent-id is required for send, only query for search",
+      "🎯 Better search: Use --status, --topics, and --document-id for targeted results",
+      "🔧 Multiple environments: Use different config files with '--config' flag",
+    ];
+
+    tips.forEach((tip) => {
+      console.log(`  ${tip}`);
+    });
+
+    console.log(
+      chalk.dim(
+        "\nToothFairy CLI v1.0.0 - For more help, visit the documentation"
+      )
+    );
+  });
+
+// Parse command line arguments
+program.parse();

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@toothfairyai/cli",
+  "version": "1.0.2",
+  "description": "Command-line interface for ToothFairy AI API",
+  "main": "index.js",
+  "bin": {
+    "toothfairy": "./bin/toothfairy.js",
+    "tf": "./bin/toothfairy.js"
+  },
+  "scripts": {
+    "start": "node bin/toothfairy.js",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch --passWithNoTests",
+    "lint": "eslint src/**/*.js bin/**/*.js || true",
+    "lint:fix": "eslint src/**/*.js bin/**/*.js --fix || true",
+    "prepack": "npm run test"
+  },
+  "keywords": [
+    "toothfairy",
+    "ai",
+    "cli",
+    "api",
+    "chatbot",
+    "agent"
+  ],
+  "author": "ToothFairy AI <support@toothfairyai.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitea.your-domain.com/toothfairyai/toothfairy-cli.git"
+  },
+  "bugs": {
+    "url": "https://gitea.your-domain.com/toothfairyai/toothfairy-cli/issues"
+  },
+  "homepage": "https://gitea.your-domain.com/toothfairyai/toothfairy-cli#readme",
+  "dependencies": {
+    "commander": "^9.4.1",
+    "axios": "^1.4.0",
+    "chalk": "^4.1.2",
+    "dotenv": "^16.0.3",
+    "js-yaml": "^4.1.0",
+    "ora": "^5.4.1",
+    "table": "^6.8.1"
+  },
+  "devDependencies": {
+    "eslint": "^8.32.0",
+    "jest": "^29.3.1"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/api.js

@@ -0,0 +1,247 @@
+const axios = require("axios");
+
+class ToothFairyAPI {
+  constructor(baseUrl, aiUrl, apiKey, workspaceId, verbose = false) {
+    this.baseUrl = baseUrl;
+    this.aiUrl = aiUrl;
+    this.workspaceId = workspaceId;
+    this.verbose = verbose;
+    this.headers = {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+    };
+  }
+
+  async _makeRequest(method, endpoint, data = null) {
+    const config = {
+      method,
+      url: `${this.baseUrl}/${endpoint}`,
+      headers: this.headers,
+    };
+
+    if (method === "POST" || method === "PUT") {
+      if (data) {
+        data = { workspaceid: this.workspaceId, ...data };
+      }
+      config.data = data;
+    } else if (method === "GET" && data) {
+      // For GET requests with data, add as query parameters
+      const params = new URLSearchParams(data);
+      config.url += `?${params.toString()}`;
+    }
+
+    if (this.verbose) {
+      const chalk = require("chalk");
+      console.error(chalk.dim("\n--- API Request Debug ---"));
+      console.error(chalk.dim(`Method: ${method}`));
+      console.error(chalk.dim(`URL: ${config.url}`));
+      console.error(chalk.dim(`Headers: ${JSON.stringify(config.headers, null, 2)}`));
+      if (config.data) {
+        console.error(chalk.dim(`Data: ${JSON.stringify(config.data, null, 2)}`));
+      }
+      console.error(chalk.dim("----------------------\n"));
+    }
+
+    try {
+      const response = await axios(config);
+      
+      if (this.verbose) {
+        const chalk = require("chalk");
+        console.error(chalk.dim("\n--- API Response Debug ---"));
+        console.error(chalk.dim(`Status: ${response.status} ${response.statusText}`));
+        console.error(chalk.dim(`Response Headers: ${JSON.stringify(response.headers, null, 2)}`));
+        console.error(chalk.dim(`Response Data: ${JSON.stringify(response.data, null, 2)}`));
+        console.error(chalk.dim("------------------------\n"));
+      }
+      
+      return response.data;
+    } catch (error) {
+      if (this.verbose) {
+        const chalk = require("chalk");
+        console.error(chalk.red("\n--- API Error Debug ---"));
+        console.error(chalk.red(`Error: ${error.message}`));
+        if (error.response) {
+          console.error(chalk.red(`Status: ${error.response.status} ${error.response.statusText}`));
+          console.error(chalk.red(`Response Headers: ${JSON.stringify(error.response.headers, null, 2)}`));
+          console.error(chalk.red(`Response Data: ${JSON.stringify(error.response.data, null, 2)}`));
+        }
+        if (error.request) {
+          console.error(chalk.red(`Request Config: ${JSON.stringify(error.config, null, 2)}`));
+        }
+        console.error(chalk.red("---------------------\n"));
+      }
+      
+      if (error.response) {
+        throw new Error(
+          `HTTP ${error.response.status}: ${
+            error.response.data.message || "API request failed"
+          }`
+        );
+      }
+      throw error;
+    }
+  }
+
+  async createChat(chatData) {
+    return this._makeRequest("POST", "chat/create", chatData);
+  }
+
+  async updateChat(chatData) {
+    return this._makeRequest("POST", "chat/update", chatData);
+  }
+
+  async getChat(chatId) {
+    return this._makeRequest("GET", `chat/get/${chatId}`);
+  }
+
+  async createMessage(messageData) {
+    return this._makeRequest("POST", "chat_message/create", messageData);
+  }
+
+  async getMessage(messageId) {
+    return this._makeRequest("GET", `chat_message/get/${messageId}`);
+  }
+
+  async getAllChats() {
+    return this._makeRequest("GET", "chat/list", {
+      workspaceid: this.workspaceId,
+    });
+  }
+
+  async getAgentResponse(agentData) {
+    const config = {
+      method: "POST",
+      url: `${this.aiUrl}/chatter`,
+      headers: this.headers,
+      data: { workspaceid: this.workspaceId, ...agentData },
+    };
+
+    try {
+      const response = await axios(config);
+      return response.data;
+    } catch (error) {
+      if (error.response) {
+        throw new Error(
+          `HTTP ${error.response.status}: ${
+            error.response.data.message || "Agent request failed"
+          }`
+        );
+      }
+      throw error;
+    }
+  }
+
+  async sendMessageToAgent(
+    message,
+    agentId,
+    phoneNumber = null,
+    customerId = null,
+    providerId = null,
+    customerInfo = {}
+  ) {
+    try {
+      // Use defaults for optional parameters
+      customerId =
+        customerId ||
+        `cli-user-${
+          Math.abs(
+            message.split("").reduce((a, b) => {
+              a = (a << 5) - a + b.charCodeAt(0);
+              return a & a;
+            }, 0)
+          ) % 10000
+        }`;
+      phoneNumber = phoneNumber || "+1234567890";
+      providerId = providerId || "default-sms-provider";
+
+      const chatData = {
+        name: customerId,
+        primaryRole: agentId,
+        externalParticipantId: phoneNumber,
+        channelSettings: {
+          sms: {
+            isEnabled: true,
+            recipient: phoneNumber,
+            providerID: providerId,
+          },
+        },
+        customerId: customerId,
+        customerInfo: customerInfo,
+        isAIReplying: true,
+      };
+
+      const createdChat = await this.createChat(chatData);
+      // console.log(`Chat created: ${createdChat.id}`);
+
+      const messageData = {
+        chatID: createdChat.id,
+        text: message,
+        role: "user",
+        userID: "CLI",
+      };
+      const createdMessage = await this.createMessage(messageData);
+      // console.log(`Message created: ${createdMessage.id}`);;
+
+      const agentData = {
+        chatid: createdChat.id,
+        messages: [
+          {
+            text: createdMessage.text,
+            role: createdMessage.role,
+            userID: createdMessage.userID || "System User",
+          },
+        ],
+        agentid: agentId,
+      };
+      const agentResponse = await this.getAgentResponse(agentData);
+      // console.log('Agent response received');
+
+      return {
+        chatId: createdChat.id,
+        messageId: createdMessage.id,
+        agentResponse: agentResponse,
+      };
+    } catch (error) {
+      console.error(`Error in sendMessageToAgent: ${error.message}`);
+      throw error;
+    }
+  }
+
+  async searchDocuments(text, topK = 10, metadata = null) {
+    if (topK < 1 || topK > 50) {
+      throw new Error("topK must be between 1 and 50");
+    }
+
+    const searchData = {
+      text: text,
+      topK: topK,
+    };
+
+    if (metadata) {
+      searchData.metadata = metadata;
+    }
+
+    const config = {
+      method: "POST",
+      url: `${this.aiUrl}/searcher`,
+      headers: this.headers,
+      data: { workspaceid: this.workspaceId, ...searchData },
+    };
+
+    try {
+      const response = await axios(config);
+      return response.data;
+    } catch (error) {
+      if (error.response) {
+        throw new Error(
+          `HTTP ${error.response.status}: ${
+            error.response.data.message || "Search request failed"
+          }`
+        );
+      }
+      throw error;
+    }
+  }
+}
+
+module.exports = ToothFairyAPI;

package/src/config.js

@@ -0,0 +1,146 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const yaml = require('js-yaml');
+
+class ToothFairyConfig {
+    constructor(baseUrl, aiUrl, apiKey, workspaceId) {
+        this.baseUrl = baseUrl;
+        this.aiUrl = aiUrl;
+        this.apiKey = apiKey;
+        this.workspaceId = workspaceId;
+    }
+
+    static fromEnv() {
+        return new ToothFairyConfig(
+            process.env.TF_BASE_URL || 'https://api.toothfairyai.com',
+            process.env.TF_AI_URL || 'https://ai.toothfairyai.com',
+            process.env.TF_API_KEY || '',
+            process.env.TF_WORKSPACE_ID || ''
+        );
+    }
+
+    static fromFile(configPath) {
+        if (!fs.existsSync(configPath)) {
+            throw new Error(`Config file not found: ${configPath}`);
+        }
+
+        const content = fs.readFileSync(configPath, 'utf8');
+        let data;
+
+        if (configPath.endsWith('.yml') || configPath.endsWith('.yaml')) {
+            data = yaml.load(content);
+        } else {
+            data = JSON.parse(content);
+        }
+
+        return new ToothFairyConfig(
+            data.base_url || 'https://api.toothfairyai.com',
+            data.ai_url || 'https://ai.toothfairyai.com',
+            data.api_key || '',
+            data.workspace_id || ''
+        );
+    }
+
+    validate() {
+        return !!(this.apiKey && this.workspaceId);
+    }
+
+    toObject() {
+        return {
+            base_url: this.baseUrl,
+            ai_url: this.aiUrl,
+            api_key: this.apiKey,
+            workspace_id: this.workspaceId
+        };
+    }
+}
+
+function getConfigPath() {
+    return path.join(os.homedir(), '.toothfairy', 'config.yml');
+}
+
+function loadConfig(configPath = null) {
+    // Priority order:
+    // 1. Provided config file path
+    // 2. Default config file (~/.toothfairy/config.yml)
+    // 3. Environment variables
+
+    if (configPath) {
+        return ToothFairyConfig.fromFile(configPath);
+    }
+
+    const defaultConfig = getConfigPath();
+    if (fs.existsSync(defaultConfig)) {
+        return ToothFairyConfig.fromFile(defaultConfig);
+    }
+
+    const config = ToothFairyConfig.fromEnv();
+    if (!config.validate()) {
+        throw new Error(
+            'Configuration incomplete. Please provide configuration via:\n' +
+            '1. Config file at ~/.toothfairy/config.yml\n' +
+            '2. Environment variables: TF_API_KEY, TF_WORKSPACE_ID\n' +
+            '3. CLI arguments\n' +
+            'Note: TF_BASE_URL and TF_AI_URL default to production endpoints'
+        );
+    }
+
+    return config;
+}
+
+function saveConfig(config, configPath = null) {
+    const filePath = configPath || getConfigPath();
+    const dir = path.dirname(filePath);
+
+    // Create directory if it doesn't exist
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const content = yaml.dump(config.toObject());
+    fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function validateConfiguration(config) {
+    const missingFields = [];
+    
+    if (!config.apiKey) {
+        missingFields.push('API Key');
+    }
+    if (!config.workspaceId) {
+        missingFields.push('Workspace ID');
+    }
+    
+    if (missingFields.length > 0) {
+        const missingStr = missingFields.join(' and ');
+        const chalk = require('chalk');
+        
+        console.error(chalk.red(`Error: Missing required configuration: ${missingStr}`));
+        console.error();
+        console.error(chalk.yellow('To fix this, run the configure command:'));
+        console.error(chalk.dim('tf configure --api-key YOUR_API_KEY --workspace-id YOUR_WORKSPACE_ID'));
+        console.error();
+        console.error(chalk.yellow('Or set environment variables:'));
+        if (!config.apiKey) {
+            console.error(chalk.dim('export TF_API_KEY=\'your-api-key\''));
+        }
+        if (!config.workspaceId) {
+            console.error(chalk.dim('export TF_WORKSPACE_ID=\'your-workspace-id\''));
+        }
+        console.error();
+        console.error(chalk.yellow('Or create a config file at ~/.toothfairy/config.yml:'));
+        console.error(chalk.dim('api_key: your-api-key'));
+        console.error(chalk.dim('workspace_id: your-workspace-id'));
+        
+        throw new Error(`Configuration incomplete: missing ${missingStr}`);
+    }
+}
+
+module.exports = {
+    ToothFairyConfig,
+    loadConfig,
+    saveConfig,
+    getConfigPath,
+    validateConfiguration
+};