@agentforge/tools 0.8.2 → 0.9.1

package/README.md

@@ -1,6 +1,6 @@
 # @agentforge/tools
 
-> Production-ready tools collection for AgentForge - 70 tools for web, data, file, utility, and agent operations
+> Production-ready tools collection for AgentForge - 74 tools for web, data, file, utility, and agent operations
 
 [![npm version](https://img.shields.io/npm/v/@agentforge/tools)](https://www.npmjs.com/package/@agentforge/tools)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
@@ -8,7 +8,7 @@
 
 ## 🎉 Status: Production Ready & Published
 
-**70 production-ready tools** | **Full TypeScript support** | **Comprehensive documentation** | **LangChain compatible**
+**74 production-ready tools** | **Full TypeScript support** | **Comprehensive documentation** | **LangChain compatible**
 
 ## 📦 Installation
 
@@ -22,9 +22,9 @@ yarn add @agentforge/tools
 
 ## 🎯 Overview
 
-This package provides **70 ready-to-use tools** organized into 5 categories:
+This package provides **74 ready-to-use tools** organized into 5 categories:
 
-- **🌐 Web Tools** (11 tools) - HTTP requests, web search, web scraping, HTML parsing, URL manipulation
+- **🌐 Web Tools** (15 tools) - HTTP requests, web search, web scraping, HTML parsing, URL manipulation, Slack integration
 - **📊 Data Tools** (18 tools) - JSON, CSV, XML processing and data transformation
 - **📁 File Tools** (18 tools) - File operations, directory management, path utilities
 - **🔧 Utility Tools** (22 tools) - Date/time, strings, math, validation
@@ -96,6 +96,13 @@ Tools for web interactions and HTTP operations.
 - **`urlBuilder`** - Build URLs from components
 - **`urlQueryParser`** - Parse query parameters
 
+#### Slack Tools
+- **`sendSlackMessage`** - Send messages to Slack channels
+- **`notifySlack`** - Send notifications with @mentions
+- **`getSlackChannels`** - List available Slack channels
+- **`getSlackMessages`** - Read message history from channels
+- **`createSlackTools()`** - Factory function for custom Slack configuration
+
 ### 📊 Data Tools (18 tools)
 
 Tools for data processing and transformation.
@@ -287,6 +294,71 @@ console.log(result.links);
 console.log(result.metadata);
 ```
 
+### Slack Integration Example
+
+```typescript
+import {
+  sendSlackMessage,
+  notifySlack,
+  getSlackChannels,
+  getSlackMessages,
+  createSlackTools
+} from '@agentforge/tools';
+
+// Send a simple message
+const message = await sendSlackMessage.execute({
+  channel: 'general',
+  message: 'Hello from AgentForge!'
+});
+
+// Send a notification with mentions
+const notification = await notifySlack.execute({
+  channel: 'alerts',
+  message: 'System alert: High CPU usage detected',
+  mentions: ['john', 'jane']  // Will send as: @john @jane System alert...
+});
+
+// List available channels
+const channels = await getSlackChannels.execute({
+  include_private: false  // Only public channels
+});
+console.log(channels.data?.channels);
+
+// Read message history
+const history = await getSlackMessages.execute({
+  channel: 'general',
+  limit: 50
+});
+console.log(`Found ${history.data?.count} messages`);
+
+// Custom configuration (for multiple workspaces or custom bot settings)
+const customTools = createSlackTools({
+  token: 'xoxb-your-custom-token',
+  botName: 'My Custom Bot',
+  botIcon: ':rocket:'
+});
+
+await customTools.sendMessage.execute({
+  channel: 'general',
+  message: 'Message from custom bot!'
+});
+```
+
+**Environment Setup:**
+```bash
+# Add to your .env file
+SLACK_USER_TOKEN=xoxp-your-user-token
+# OR
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+```
+
+**Getting a Slack Token:**
+1. Go to [Slack API](https://api.slack.com/apps)
+2. Create a new app or select existing
+3. Add OAuth scopes: `chat:write`, `channels:read`, `channels:history`
+4. Install app to workspace
+5. Copy the token (starts with `xoxb-` for bot or `xoxp-` for user)
+
 ### Data Processing Example
 
 ```typescript
@@ -522,12 +594,13 @@ pnpm lint
 
 ## 📊 Tool Statistics
 
-- **Total Tools**: 69
-- **Web Tools**: 11
+- **Total Tools**: 74
+- **Web Tools**: 15 (includes 4 Slack tools)
 - **Data Tools**: 18
 - **File Tools**: 18
 - **Utility Tools**: 22
-- **Lines of Code**: ~2,500
+- **Agent Tools**: 1
+- **Lines of Code**: ~3,200
 - **Full TypeScript Support**: ✅
 - **Zod Validation**: ✅
 - **LangChain Compatible**: ✅

package/dist/index.cjs

@@ -4,6 +4,7 @@ var core = require('@agentforge/core');
 var zod = require('zod');
 var axios = require('axios');
 var cheerio2 = require('cheerio');
+var webApi = require('@slack/web-api');
 var sync = require('csv-parse/sync');
 var sync$1 = require('csv-stringify/sync');
 var fastXmlParser = require('fast-xml-parser');
@@ -682,6 +683,381 @@ var webSearch = core.toolBuilder().name("web-search").description(
     };
   }
 }).build();
+var logLevel = process.env.LOG_LEVEL?.toLowerCase() || core.LogLevel.INFO;
+var logger = core.createLogger("tools:slack", { level: logLevel });
+var defaultSlackClient = null;
+function getDefaultSlackClient() {
+  if (!defaultSlackClient) {
+    const token = process.env.SLACK_USER_TOKEN || process.env.SLACK_BOT_TOKEN;
+    if (!token) {
+      throw new Error(
+        "Slack token not configured. Please set SLACK_USER_TOKEN or SLACK_BOT_TOKEN environment variable."
+      );
+    }
+    defaultSlackClient = new webApi.WebClient(token);
+  }
+  return defaultSlackClient;
+}
+var sendSlackMessage = core.toolBuilder().name("send-slack-message").description("Send a message to a Slack channel for team communication and notifications").category(core.ToolCategory.WEB).tags(["slack", "messaging", "communication"]).usageNotes(
+  "Use this for general team communication. For notifications with @mentions, consider using notify-slack instead. Use get-slack-channels first if you need to find the right channel."
+).suggests(["get-slack-channels"]).schema(
+  zod.z.object({
+    channel: zod.z.string().describe("Channel name (e.g., 'general') or ID (e.g., 'C123456')"),
+    message: zod.z.string().describe("Message content to send")
+  })
+).implementSafe(async ({ channel, message }) => {
+  logger.info("send-slack-message called", { channel, messageLength: message.length });
+  try {
+    const slack = getDefaultSlackClient();
+    const result = await slack.chat.postMessage({
+      channel,
+      text: message,
+      username: "AgentForge Bot",
+      icon_emoji: ":robot_face:"
+    });
+    logger.info("send-slack-message result", {
+      channel: result.channel,
+      timestamp: result.ts,
+      messageLength: message.length,
+      success: true
+    });
+    return {
+      channel: result.channel,
+      message,
+      timestamp: result.ts,
+      message_id: result.ts
+    };
+  } catch (error) {
+    logger.error("send-slack-message failed", {
+      channel,
+      error: error.message,
+      data: error.data
+    });
+    throw error;
+  }
+}).build();
+var notifySlack = core.toolBuilder().name("notify-slack").description("Send a notification to a Slack channel with optional @mentions for urgent alerts").category(core.ToolCategory.WEB).tags(["slack", "notification", "alert"]).usageNotes(
+  "Use this for urgent notifications that require @mentions. For general messages without mentions, use send-slack-message instead."
+).suggests(["get-slack-channels"]).schema(
+  zod.z.object({
+    channel: zod.z.string().describe("Channel name or ID"),
+    message: zod.z.string().describe("Notification message"),
+    mentions: zod.z.array(zod.z.string()).optional().describe("List of usernames to mention (without @)")
+  })
+).implementSafe(async ({ channel, message, mentions = [] }) => {
+  logger.info("notify-slack called", {
+    channel,
+    messageLength: message.length,
+    mentionCount: mentions.length
+  });
+  const slack = getDefaultSlackClient();
+  const mentionText = mentions.length > 0 ? mentions.map((m) => `<@${m}>`).join(" ") + " " : "";
+  const fullMessage = `${mentionText}${message}`;
+  const result = await slack.chat.postMessage({
+    channel,
+    text: fullMessage,
+    username: "AgentForge Bot",
+    icon_emoji: ":robot_face:"
+  });
+  logger.info("notify-slack result", {
+    channel: result.channel,
+    timestamp: result.ts,
+    mentions: mentions.length
+  });
+  return {
+    channel: result.channel,
+    message: fullMessage,
+    mentions,
+    timestamp: result.ts,
+    notification_id: result.ts
+  };
+}).build();
+var getSlackChannels = core.toolBuilder().name("get-slack-channels").description("Get a list of available Slack channels to find the right channel for messaging").category(core.ToolCategory.WEB).tags(["slack", "channels", "list"]).usageNotes(
+  "Use this first to discover available channels before sending messages. Helps ensure you are sending to the correct channel."
+).follows(["send-slack-message", "notify-slack"]).schema(
+  zod.z.object({
+    include_private: zod.z.boolean().optional().describe("Include private channels (default: false)")
+  })
+).implementSafe(async ({ include_private = false }) => {
+  logger.info("get-slack-channels called", { include_private });
+  const slack = getDefaultSlackClient();
+  const publicChannels = await slack.conversations.list({
+    types: "public_channel",
+    exclude_archived: true
+  });
+  let allChannels = publicChannels.channels || [];
+  if (include_private) {
+    const privateChannels = await slack.conversations.list({
+      types: "private_channel",
+      exclude_archived: true
+    });
+    allChannels = [...allChannels, ...privateChannels.channels || []];
+  }
+  logger.info("get-slack-channels result", {
+    channelCount: allChannels.length,
+    includePrivate: include_private
+  });
+  return {
+    count: allChannels.length,
+    channels: allChannels.map((c) => ({
+      id: c.id,
+      name: c.name,
+      is_private: c.is_private || false,
+      num_members: c.num_members || 0
+    }))
+  };
+}).build();
+var getSlackMessages = core.toolBuilder().name("get-slack-messages").description("Retrieve message history from a Slack channel to read recent conversations").category(core.ToolCategory.WEB).tags(["slack", "messages", "history", "read"]).usageNotes(
+  "Use this to read recent messages from a channel. Use get-slack-channels first if you need to find the channel ID. Returns messages in reverse chronological order (newest first)."
+).suggests(["get-slack-channels"]).schema(
+  zod.z.object({
+    channel: zod.z.string().describe("Channel name (e.g., 'general') or ID (e.g., 'C123456')"),
+    limit: zod.z.number().int().min(1).max(100).optional().describe("Number of messages to retrieve (default: 20, max: 100)")
+  })
+).implementSafe(async ({ channel, limit = 20 }) => {
+  logger.info("get-slack-messages called", { channel, limit });
+  try {
+    const slack = getDefaultSlackClient();
+    let channelId = channel;
+    if (!channel.startsWith("C") && !channel.startsWith("D")) {
+      const channels = await slack.conversations.list({
+        types: "public_channel,private_channel",
+        exclude_archived: true
+      });
+      const found = channels.channels?.find((c) => c.name === channel);
+      if (!found) {
+        logger.error("get-slack-messages: channel not found", { channel });
+        throw new Error(
+          `Channel '${channel}' not found. Use get-slack-channels to see available channels.`
+        );
+      }
+      channelId = found.id;
+    }
+    const result = await slack.conversations.history({
+      channel: channelId,
+      limit: Math.min(limit, 100)
+      // Cap at 100 for performance
+    });
+    logger.info("get-slack-messages result", {
+      channel: channelId,
+      messageCount: result.messages?.length || 0,
+      limit
+    });
+    return {
+      channel: channelId,
+      count: result.messages?.length || 0,
+      messages: result.messages?.map((m) => ({
+        user: m.user || "unknown",
+        text: m.text || "",
+        timestamp: m.ts,
+        thread_ts: m.thread_ts,
+        type: m.type,
+        subtype: m.subtype
+      })) || []
+    };
+  } catch (error) {
+    logger.error("get-slack-messages failed", {
+      channel,
+      error: error.message,
+      data: error.data
+    });
+    throw error;
+  }
+}).build();
+function createSlackTools(config = {}) {
+  const {
+    token,
+    botName = "AgentForge Bot",
+    botIcon = ":robot_face:",
+    logLevel: customLogLevel
+  } = config;
+  let configuredClient = null;
+  function getConfiguredSlackClient() {
+    if (!configuredClient) {
+      const slackToken = token || process.env.SLACK_USER_TOKEN || process.env.SLACK_BOT_TOKEN;
+      if (!slackToken) {
+        throw new Error(
+          "Slack token not configured. Please provide a token in config or set SLACK_USER_TOKEN or SLACK_BOT_TOKEN environment variable."
+        );
+      }
+      configuredClient = new webApi.WebClient(slackToken);
+    }
+    return configuredClient;
+  }
+  const toolLogger = customLogLevel ? core.createLogger("tools:slack", { level: customLogLevel }) : logger;
+  const sendMessage = core.toolBuilder().name("send-slack-message").description("Send a message to a Slack channel for team communication and notifications").category(core.ToolCategory.WEB).tags(["slack", "messaging", "communication"]).usageNotes(
+    "Use this for general team communication. For notifications with @mentions, consider using notify-slack instead. Use get-slack-channels first if you need to find the right channel."
+  ).suggests(["get-slack-channels"]).schema(
+    zod.z.object({
+      channel: zod.z.string().describe("Channel name (e.g., 'general') or ID (e.g., 'C123456')"),
+      message: zod.z.string().describe("Message content to send")
+    })
+  ).implementSafe(async ({ channel, message }) => {
+    toolLogger.info("send-slack-message called", { channel, messageLength: message.length });
+    try {
+      const slack = getConfiguredSlackClient();
+      const result = await slack.chat.postMessage({
+        channel,
+        text: message,
+        username: botName,
+        icon_emoji: botIcon
+      });
+      toolLogger.info("send-slack-message result", {
+        channel: result.channel,
+        timestamp: result.ts,
+        messageLength: message.length,
+        success: true
+      });
+      return {
+        channel: result.channel,
+        message,
+        timestamp: result.ts,
+        message_id: result.ts
+      };
+    } catch (error) {
+      toolLogger.error("send-slack-message failed", {
+        channel,
+        error: error.message,
+        data: error.data
+      });
+      throw error;
+    }
+  }).build();
+  const notify = core.toolBuilder().name("notify-slack").description("Send a notification to a Slack channel with optional @mentions for urgent alerts").category(core.ToolCategory.WEB).tags(["slack", "notification", "alert"]).usageNotes(
+    "Use this for urgent notifications that require @mentions. For general messages without mentions, use send-slack-message instead."
+  ).suggests(["get-slack-channels"]).schema(
+    zod.z.object({
+      channel: zod.z.string().describe("Channel name or ID"),
+      message: zod.z.string().describe("Notification message"),
+      mentions: zod.z.array(zod.z.string()).optional().describe("List of usernames to mention (without @)")
+    })
+  ).implementSafe(async ({ channel, message, mentions = [] }) => {
+    toolLogger.info("notify-slack called", {
+      channel,
+      messageLength: message.length,
+      mentionCount: mentions.length
+    });
+    const slack = getConfiguredSlackClient();
+    const mentionText = mentions.length > 0 ? mentions.map((m) => `<@${m}>`).join(" ") + " " : "";
+    const fullMessage = `${mentionText}${message}`;
+    const result = await slack.chat.postMessage({
+      channel,
+      text: fullMessage,
+      username: botName,
+      icon_emoji: botIcon
+    });
+    toolLogger.info("notify-slack result", {
+      channel: result.channel,
+      timestamp: result.ts,
+      mentions: mentions.length
+    });
+    return {
+      channel: result.channel,
+      message: fullMessage,
+      mentions,
+      timestamp: result.ts,
+      notification_id: result.ts
+    };
+  }).build();
+  const getChannels = core.toolBuilder().name("get-slack-channels").description("Get a list of available Slack channels to find the right channel for messaging").category(core.ToolCategory.WEB).tags(["slack", "channels", "list"]).usageNotes(
+    "Use this first to discover available channels before sending messages. Helps ensure you are sending to the correct channel."
+  ).follows(["send-slack-message", "notify-slack"]).schema(
+    zod.z.object({
+      include_private: zod.z.boolean().optional().describe("Include private channels (default: false)")
+    })
+  ).implementSafe(async ({ include_private = false }) => {
+    toolLogger.info("get-slack-channels called", { include_private });
+    const slack = getConfiguredSlackClient();
+    const publicChannels = await slack.conversations.list({
+      types: "public_channel",
+      exclude_archived: true
+    });
+    let allChannels = publicChannels.channels || [];
+    if (include_private) {
+      const privateChannels = await slack.conversations.list({
+        types: "private_channel",
+        exclude_archived: true
+      });
+      allChannels = [...allChannels, ...privateChannels.channels || []];
+    }
+    toolLogger.info("get-slack-channels result", {
+      channelCount: allChannels.length,
+      includePrivate: include_private
+    });
+    return {
+      count: allChannels.length,
+      channels: allChannels.map((c) => ({
+        id: c.id,
+        name: c.name,
+        is_private: c.is_private || false,
+        num_members: c.num_members || 0
+      }))
+    };
+  }).build();
+  const getMessages = core.toolBuilder().name("get-slack-messages").description("Retrieve message history from a Slack channel to read recent conversations").category(core.ToolCategory.WEB).tags(["slack", "messages", "history", "read"]).usageNotes(
+    "Use this to read recent messages from a channel. Use get-slack-channels first if you need to find the channel ID. Returns messages in reverse chronological order (newest first)."
+  ).suggests(["get-slack-channels"]).schema(
+    zod.z.object({
+      channel: zod.z.string().describe("Channel name (e.g., 'general') or ID (e.g., 'C123456')"),
+      limit: zod.z.number().int().min(1).max(100).optional().describe("Number of messages to retrieve (default: 20, max: 100)")
+    })
+  ).implementSafe(async ({ channel, limit = 20 }) => {
+    toolLogger.info("get-slack-messages called", { channel, limit });
+    try {
+      const slack = getConfiguredSlackClient();
+      let channelId = channel;
+      if (!channel.startsWith("C") && !channel.startsWith("D")) {
+        const channels = await slack.conversations.list({
+          types: "public_channel,private_channel",
+          exclude_archived: true
+        });
+        const found = channels.channels?.find((c) => c.name === channel);
+        if (!found) {
+          toolLogger.error("get-slack-messages: channel not found", { channel });
+          throw new Error(
+            `Channel '${channel}' not found. Use get-slack-channels to see available channels.`
+          );
+        }
+        channelId = found.id;
+      }
+      const result = await slack.conversations.history({
+        channel: channelId,
+        limit: Math.min(limit, 100)
+      });
+      toolLogger.info("get-slack-messages result", {
+        channel: channelId,
+        messageCount: result.messages?.length || 0,
+        limit
+      });
+      return {
+        channel: channelId,
+        count: result.messages?.length || 0,
+        messages: result.messages?.map((m) => ({
+          user: m.user || "unknown",
+          text: m.text || "",
+          timestamp: m.ts,
+          thread_ts: m.thread_ts,
+          type: m.type,
+          subtype: m.subtype
+        })) || []
+      };
+    } catch (error) {
+      toolLogger.error("get-slack-messages failed", {
+        channel,
+        error: error.message,
+        data: error.data
+      });
+      throw error;
+    }
+  }).build();
+  return {
+    sendMessage,
+    notify,
+    getChannels,
+    getMessages
+  };
+}
+var slackTools = [sendSlackMessage, notifySlack, getSlackChannels, getSlackMessages];
 var jsonParser = core.toolBuilder().name("json-parser").description("Parse JSON string into an object. Validates JSON syntax and returns parsed data or error details.").category(core.ToolCategory.UTILITY).tags(["json", "parse", "data"]).schema(zod.z.object({
   json: zod.z.string().describe("JSON string to parse"),
   strict: zod.z.boolean().default(true).describe("Use strict JSON parsing (no trailing commas, etc.)")
@@ -1906,8 +2282,8 @@ var AskHumanInputSchema = zod.z.object({
    */
   suggestions: zod.z.array(zod.z.string()).optional().describe("Suggested responses for the human")
 });
-var logLevel = process.env.LOG_LEVEL?.toLowerCase() || core.LogLevel.INFO;
-var logger = core.createLogger("askHuman", { level: logLevel });
+var logLevel2 = process.env.LOG_LEVEL?.toLowerCase() || core.LogLevel.INFO;
+var logger2 = core.createLogger("askHuman", { level: logLevel2 });
 function createAskHumanTool() {
   return core.toolBuilder().name("ask-human").description(
     "Ask a human for input or approval. Use this when you need human guidance, approval for a critical action, or clarification on ambiguous requirements. The agent execution will pause until the human responds."
@@ -1940,13 +2316,13 @@ function createAskHumanTool() {
       suggestions: validatedInput.suggestions,
       status: "pending"
     };
-    logger.debug("About to call interrupt()", { humanRequest });
+    logger2.debug("About to call interrupt()", { humanRequest });
     let response;
     try {
       response = interrupt(humanRequest);
-      logger.debug("interrupt() returned successfully", { response, responseType: typeof response });
+      logger2.debug("interrupt() returned successfully", { response, responseType: typeof response });
     } catch (error) {
-      logger.debug("interrupt() threw error (expected for GraphInterrupt)", {
+      logger2.debug("interrupt() threw error (expected for GraphInterrupt)", {
         errorType: error?.constructor?.name,
         error: error instanceof Error ? error.message : String(error)
       });
@@ -1983,6 +2359,7 @@ exports.calculator = calculator;
 exports.createAskHumanTool = createAskHumanTool;
 exports.createDuckDuckGoProvider = createDuckDuckGoProvider;
 exports.createSerperProvider = createSerperProvider;
+exports.createSlackTools = createSlackTools;
 exports.creditCardValidator = creditCardValidator;
 exports.csvGenerator = csvGenerator;
 exports.csvParser = csvParser;
@@ -2004,6 +2381,8 @@ exports.fileExists = fileExists;
 exports.fileReader = fileReader;
 exports.fileSearch = fileSearch;
 exports.fileWriter = fileWriter;
+exports.getSlackChannels = getSlackChannels;
+exports.getSlackMessages = getSlackMessages;
 exports.htmlParser = htmlParser;
 exports.httpClient = httpClient;
 exports.httpGet = httpGet;
@@ -2017,6 +2396,7 @@ exports.jsonToCsv = jsonToCsv;
 exports.jsonToXml = jsonToXml;
 exports.jsonValidator = jsonValidator;
 exports.mathFunctions = mathFunctions;
+exports.notifySlack = notifySlack;
 exports.objectOmit = objectOmit;
 exports.objectPick = objectPick;
 exports.pathBasename = pathBasename;
@@ -2030,6 +2410,8 @@ exports.pathResolve = pathResolve;
 exports.phoneValidator = phoneValidator;
 exports.randomNumber = randomNumber;
 exports.searchResultSchema = searchResultSchema;
+exports.sendSlackMessage = sendSlackMessage;
+exports.slackTools = slackTools;
 exports.statistics = statistics;
 exports.stringCaseConverter = stringCaseConverter;
 exports.stringJoin = stringJoin;