@agentforge/tools 0.3.9 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # @agentforge/tools
 
-> Production-ready tools collection for AgentForge - 68 tools for web, data, file, and utility operations
+> Production-ready tools collection for AgentForge - 69 tools for web, data, file, and utility 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
 
-**68 production-ready tools** | **Full TypeScript support** | **Comprehensive documentation** | **LangChain compatible**
+**69 production-ready tools** | **Full TypeScript support** | **Comprehensive documentation** | **LangChain compatible**
 
 ## 📦 Installation
 
@@ -22,9 +22,9 @@ yarn add @agentforge/tools
 
 ## 🎯 Overview
 
-This package provides **68 ready-to-use tools** organized into 4 categories:
+This package provides **69 ready-to-use tools** organized into 4 categories:
 
-- **🌐 Web Tools** (10 tools) - HTTP requests, web scraping, HTML parsing, URL manipulation
+- **🌐 Web Tools** (11 tools) - HTTP requests, web search, web scraping, HTML parsing, URL manipulation
 - **📊 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
@@ -68,10 +68,17 @@ const result = await calculator.execute({
 
 ## 📚 Tool Categories
 
-### 🌐 Web Tools (10 tools)
+### 🌐 Web Tools (11 tools)
 
 Tools for web interactions and HTTP operations.
 
+#### Web Search
+- **`webSearch`** - Search the web using DuckDuckGo (free) or Serper API (optional premium)
+  - No API key required for basic searches (uses DuckDuckGo)
+  - Optional Serper API for premium Google search results
+  - Smart fallback: automatically switches providers when needed
+  - Returns structured results with titles, links, and snippets
+
 #### HTTP Client Tools
 - **`httpClient`** - Full-featured HTTP client with all methods (GET, POST, PUT, DELETE, PATCH)
 - **`httpGet`** - Simple GET requests
@@ -182,6 +189,85 @@ General utility tools for common operations.
 
 ## 💡 Usage Examples
 
+### Web Search Example
+
+```typescript
+import { webSearch } from '@agentforge/tools';
+
+// Basic search (no API key needed - uses DuckDuckGo)
+const result = await webSearch.execute({
+  query: 'TypeScript programming language',
+  maxResults: 10
+});
+
+console.log(`Found ${result.results.length} results from ${result.source}`);
+result.results.forEach(r => {
+  console.log(`${r.title}: ${r.link}`);
+  console.log(`  ${r.snippet}`);
+});
+
+// Premium search with Serper API (requires SERPER_API_KEY env var)
+// Get your API key at: https://serper.dev
+const premiumResult = await webSearch.execute({
+  query: 'Latest AI developments 2026',
+  maxResults: 5,
+  preferSerper: true  // Use Serper for Google search results
+});
+
+// Check metadata
+console.log(`Source: ${premiumResult.source}`);
+console.log(`Fallback used: ${premiumResult.metadata?.fallbackUsed}`);
+console.log(`Response time: ${premiumResult.metadata?.responseTime}ms`);
+```
+
+**Environment Setup:**
+```bash
+# Optional: Add to your .env file for premium Google search
+SERPER_API_KEY=your-serper-api-key-here
+```
+
+**Input Schema:**
+```typescript
+{
+  query: string;           // Search query (required)
+  maxResults?: number;     // Max results to return (default: 10)
+  preferSerper?: boolean;  // Prefer Serper over DuckDuckGo (default: false)
+}
+```
+
+**Output Schema:**
+```typescript
+{
+  results: Array<{
+    title: string;      // Result title
+    link: string;       // Result URL
+    snippet: string;    // Result description/snippet
+    position: number;   // Result position (1-based)
+  }>;
+  source: 'duckduckgo' | 'serper';  // Which provider was used
+  metadata?: {
+    fallbackUsed: boolean;    // Whether fallback to DuckDuckGo occurred
+    responseTime: number;     // Response time in milliseconds
+  };
+}
+```
+
+**DuckDuckGo vs Serper:**
+
+| Feature | DuckDuckGo (Free) | Serper (Premium) |
+|---------|-------------------|------------------|
+| **API Key** | ❌ Not required | ✅ Required ([get key](https://serper.dev)) |
+| **Cost** | 🆓 Free | 💰 Paid (see [pricing](https://serper.dev/pricing)) |
+| **Search Engine** | DuckDuckGo | Google |
+| **Rate Limits** | Generous | Based on plan |
+| **Result Quality** | Good | Excellent (Google results) |
+| **Use Case** | Development, testing, low-volume | Production, high-quality results |
+| **Fallback** | N/A | Auto-fallback to DuckDuckGo on error |
+
+**When to use each:**
+- **DuckDuckGo**: Default choice, no setup needed, great for development and testing
+- **Serper**: Production use cases requiring Google-quality results, set `preferSerper: true`
+
 ### Web Scraping Example
 
 ```typescript
@@ -435,8 +521,8 @@ pnpm lint
 
 ## 📊 Tool Statistics
 
-- **Total Tools**: 68
-- **Web Tools**: 10
+- **Total Tools**: 69
+- **Web Tools**: 11
 - **Data Tools**: 18
 - **File Tools**: 18
 - **Utility Tools**: 22

package/dist/index.cjs

@@ -343,6 +343,352 @@ var urlQueryParser = core.toolBuilder().name("url-query-parser").description("Pa
     count: Object.keys(params).length
   };
 }).build();
+var webSearchSchema = zod.z.object({
+  query: zod.z.string().min(1).describe("The search query"),
+  maxResults: zod.z.number().min(1).max(50).default(10).describe("Maximum number of results to return (1-50)"),
+  preferSerper: zod.z.boolean().default(false).describe("Prefer Serper API if available (requires SERPER_API_KEY)"),
+  timeout: zod.z.number().min(1e3).max(6e4).default(3e4).describe("Request timeout in milliseconds (1000-60000, default: 30000)")
+});
+var searchResultSchema = zod.z.object({
+  title: zod.z.string(),
+  link: zod.z.string().url(),
+  snippet: zod.z.string(),
+  position: zod.z.number().optional()
+});
+var webSearchOutputSchema = zod.z.object({
+  success: zod.z.boolean(),
+  source: zod.z.enum(["duckduckgo", "serper"]),
+  query: zod.z.string(),
+  results: zod.z.array(searchResultSchema),
+  totalResults: zod.z.number().optional(),
+  error: zod.z.string().optional(),
+  metadata: zod.z.object({
+    responseTime: zod.z.number().optional(),
+    fallbackUsed: zod.z.boolean().optional()
+  }).optional()
+});
+
+// src/web/web-search/utils.ts
+function getSerperApiKey() {
+  return process.env.SERPER_API_KEY;
+}
+async function measureTime(fn) {
+  const start = Date.now();
+  const result = await fn();
+  const duration = Date.now() - start;
+  return { result, duration };
+}
+function sanitizeQuery(query) {
+  return query.trim().replace(/\s+/g, " ");
+}
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  initialDelay: 1e3,
+  // 1 second
+  maxDelay: 1e4,
+  // 10 seconds
+  backoffMultiplier: 2
+};
+var DEFAULT_TIMEOUT = 3e4;
+function isRetryableError(error) {
+  if (error.code === "ECONNRESET" || error.code === "ETIMEDOUT" || error.code === "ENOTFOUND") {
+    return true;
+  }
+  if (error.code === "ECONNABORTED" || error.message?.includes("timeout")) {
+    return true;
+  }
+  if (error.response?.status >= 500 && error.response?.status < 600) {
+    return true;
+  }
+  if (error.response?.status === 429) {
+    return true;
+  }
+  return false;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function retryWithBackoff(fn, config = DEFAULT_RETRY_CONFIG) {
+  let lastError;
+  let delay = config.initialDelay;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (!isRetryableError(error)) {
+        throw error;
+      }
+      if (attempt === config.maxRetries) {
+        break;
+      }
+      await sleep(delay);
+      delay = Math.min(delay * config.backoffMultiplier, config.maxDelay);
+    }
+  }
+  throw lastError;
+}
+
+// src/web/web-search/providers/duckduckgo.ts
+var DuckDuckGoProvider = class {
+  name = "duckduckgo";
+  /**
+   * DuckDuckGo is always available (no API key required)
+   */
+  isAvailable() {
+    return true;
+  }
+  /**
+   * Search using DuckDuckGo Instant Answer API
+   * @param query - Search query
+   * @param maxResults - Maximum number of results to return
+   * @param timeout - Request timeout in milliseconds (default: 30000)
+   */
+  async search(query, maxResults, timeout = DEFAULT_TIMEOUT) {
+    return retryWithBackoff(async () => {
+      try {
+        const response = await axios__default.default.get(
+          "https://api.duckduckgo.com/",
+          {
+            params: {
+              q: query,
+              format: "json"
+            },
+            headers: {
+              "User-Agent": "Mozilla/5.0 (compatible; AgentForge/1.0; +https://github.com/agentforge)"
+            },
+            timeout
+          }
+        );
+        return this.normalizeResults(response.data, maxResults);
+      } catch (error) {
+        throw new Error(`DuckDuckGo search failed: ${error.message}`);
+      }
+    });
+  }
+  /**
+   * Normalize DuckDuckGo response to SearchResult[]
+   * Optimized for performance with large result sets
+   */
+  normalizeResults(data, maxResults) {
+    const results = [];
+    if (maxResults <= 0) {
+      return results;
+    }
+    if (data.Abstract && data.AbstractURL) {
+      results.push({
+        title: data.Heading || "Result",
+        link: data.AbstractURL,
+        snippet: data.Abstract,
+        position: 1
+      });
+      if (results.length >= maxResults) {
+        return results;
+      }
+    }
+    if (data.RelatedTopics && data.RelatedTopics.length > 0) {
+      const remaining = maxResults - results.length;
+      const topicsToProcess = data.RelatedTopics.slice(0, remaining);
+      for (const topic of topicsToProcess) {
+        if (topic.Text && topic.FirstURL) {
+          const titleParts = topic.Text.split(" - ");
+          results.push({
+            title: titleParts[0] || topic.Text,
+            link: topic.FirstURL,
+            snippet: topic.Text,
+            position: results.length + 1
+          });
+        }
+      }
+      if (results.length >= maxResults) {
+        return results;
+      }
+    }
+    if (data.Results && data.Results.length > 0) {
+      const remaining = maxResults - results.length;
+      const resultsToProcess = data.Results.slice(0, remaining);
+      for (const result of resultsToProcess) {
+        if (result.Text && result.FirstURL) {
+          const titleParts = result.Text.split(" - ");
+          results.push({
+            title: titleParts[0] || result.Text,
+            link: result.FirstURL,
+            snippet: result.Text,
+            position: results.length + 1
+          });
+        }
+      }
+    }
+    return results;
+  }
+};
+function createDuckDuckGoProvider() {
+  return new DuckDuckGoProvider();
+}
+var SerperProvider = class {
+  name = "serper";
+  apiKey;
+  constructor() {
+    this.apiKey = getSerperApiKey();
+  }
+  /**
+   * Serper is available if API key is set
+   */
+  isAvailable() {
+    return !!this.apiKey;
+  }
+  /**
+   * Search using Serper API
+   * @param query - Search query
+   * @param maxResults - Maximum number of results to return
+   * @param timeout - Request timeout in milliseconds (default: 30000)
+   */
+  async search(query, maxResults, timeout = DEFAULT_TIMEOUT) {
+    if (!this.apiKey) {
+      throw new Error(
+        "Serper API key not found. Set SERPER_API_KEY environment variable. Get your key at https://serper.dev"
+      );
+    }
+    return retryWithBackoff(async () => {
+      try {
+        const response = await axios__default.default.post(
+          "https://google.serper.dev/search",
+          {
+            q: query,
+            num: maxResults
+          },
+          {
+            headers: {
+              "X-API-KEY": this.apiKey,
+              "Content-Type": "application/json"
+            },
+            timeout
+          }
+        );
+        return this.normalizeResults(response.data, maxResults);
+      } catch (error) {
+        if (error.response?.status === 401) {
+          throw new Error(
+            "Invalid Serper API key. Get your key at https://serper.dev"
+          );
+        }
+        if (error.response?.status === 429) {
+          throw new Error(
+            "Serper API rate limit exceeded. Please try again later or upgrade your plan at https://serper.dev"
+          );
+        }
+        throw new Error(`Serper search failed: ${error.message}`);
+      }
+    });
+  }
+  /**
+   * Normalize Serper response to SearchResult[]
+   * Optimized for performance with large result sets
+   */
+  normalizeResults(data, maxResults) {
+    if (!data.organic || data.organic.length === 0 || maxResults <= 0) {
+      return [];
+    }
+    const results = [];
+    const itemsToProcess = Math.min(data.organic.length, maxResults);
+    for (let i = 0; i < itemsToProcess; i++) {
+      const item = data.organic[i];
+      if (!item.title || !item.link || !item.snippet) {
+        continue;
+      }
+      results.push({
+        title: item.title,
+        link: item.link,
+        snippet: item.snippet,
+        position: item.position ?? i + 1
+      });
+      if (results.length >= maxResults) {
+        break;
+      }
+    }
+    return results;
+  }
+};
+function createSerperProvider() {
+  return new SerperProvider();
+}
+
+// src/web/web-search/index.ts
+var webSearch = core.toolBuilder().name("web-search").description(
+  "Search the web for information using DuckDuckGo (free) or Serper API (optional). Returns structured search results with titles, links, and snippets. Automatically falls back to Serper if DuckDuckGo returns no results and API key is available."
+).category(core.ToolCategory.WEB).tags(["search", "web", "google", "duckduckgo", "serper", "internet"]).schema(webSearchSchema).implement(async (input) => {
+  const {
+    query,
+    maxResults = 10,
+    preferSerper = false,
+    timeout = DEFAULT_TIMEOUT
+  } = input;
+  const sanitizedQuery = sanitizeQuery(query);
+  const duckduckgo = createDuckDuckGoProvider();
+  const serper = createSerperProvider();
+  let primaryProvider;
+  let fallbackProvider = null;
+  if (preferSerper && serper.isAvailable()) {
+    primaryProvider = serper;
+    fallbackProvider = duckduckgo;
+  } else {
+    primaryProvider = duckduckgo;
+    fallbackProvider = serper.isAvailable() ? serper : null;
+  }
+  try {
+    const { result: results, duration } = await measureTime(
+      () => primaryProvider.search(sanitizedQuery, maxResults, timeout)
+    );
+    if (results.length > 0) {
+      return {
+        success: true,
+        source: primaryProvider.name,
+        query: sanitizedQuery,
+        results,
+        totalResults: results.length,
+        metadata: {
+          responseTime: duration,
+          fallbackUsed: false
+        }
+      };
+    }
+    if (fallbackProvider) {
+      const { result: fallbackResults, duration: fallbackDuration } = await measureTime(
+        () => fallbackProvider.search(sanitizedQuery, maxResults, timeout)
+      );
+      return {
+        success: true,
+        source: fallbackProvider.name,
+        query: sanitizedQuery,
+        results: fallbackResults,
+        totalResults: fallbackResults.length,
+        metadata: {
+          responseTime: fallbackDuration,
+          fallbackUsed: true
+        }
+      };
+    }
+    return {
+      success: true,
+      source: primaryProvider.name,
+      query: sanitizedQuery,
+      results: [],
+      totalResults: 0,
+      metadata: {
+        responseTime: duration,
+        fallbackUsed: false
+      }
+    };
+  } catch (error) {
+    return {
+      success: false,
+      source: primaryProvider.name,
+      query: sanitizedQuery,
+      results: [],
+      error: error.message
+    };
+  }
+}).build();
 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.)")
@@ -1648,11 +1994,15 @@ var uuidValidator = core.toolBuilder().name("uuid-validator").description("Valid
   };
 }).build();
 
+exports.DuckDuckGoProvider = DuckDuckGoProvider;
+exports.SerperProvider = SerperProvider;
 exports.arrayFilter = arrayFilter;
 exports.arrayGroupBy = arrayGroupBy;
 exports.arrayMap = arrayMap;
 exports.arraySort = arraySort;
 exports.calculator = calculator;
+exports.createDuckDuckGoProvider = createDuckDuckGoProvider;
+exports.createSerperProvider = createSerperProvider;
 exports.creditCardValidator = creditCardValidator;
 exports.csvGenerator = csvGenerator;
 exports.csvParser = csvParser;
@@ -1699,6 +2049,7 @@ exports.pathRelative = pathRelative;
 exports.pathResolve = pathResolve;
 exports.phoneValidator = phoneValidator;
 exports.randomNumber = randomNumber;
+exports.searchResultSchema = searchResultSchema;
 exports.statistics = statistics;
 exports.stringCaseConverter = stringCaseConverter;
 exports.stringJoin = stringJoin;
@@ -1713,6 +2064,9 @@ exports.urlValidator = urlValidator;
 exports.urlValidatorSimple = urlValidatorSimple;
 exports.uuidValidator = uuidValidator;
 exports.webScraper = webScraper;
+exports.webSearch = webSearch;
+exports.webSearchOutputSchema = webSearchOutputSchema;
+exports.webSearchSchema = webSearchSchema;
 exports.xmlGenerator = xmlGenerator;
 exports.xmlParser = xmlParser;
 exports.xmlToJson = xmlToJson;