@agentforge/tools 0.3.8 → 0.4.0

package/dist/index.js

@@ -317,6 +317,352 @@ var urlQueryParser = toolBuilder().name("url-query-parser").description("Parse q
     count: Object.keys(params).length
   };
 }).build();
+var webSearchSchema = z.object({
+  query: z.string().min(1).describe("The search query"),
+  maxResults: z.number().min(1).max(50).default(10).describe("Maximum number of results to return (1-50)"),
+  preferSerper: z.boolean().default(false).describe("Prefer Serper API if available (requires SERPER_API_KEY)"),
+  timeout: z.number().min(1e3).max(6e4).default(3e4).describe("Request timeout in milliseconds (1000-60000, default: 30000)")
+});
+var searchResultSchema = z.object({
+  title: z.string(),
+  link: z.string().url(),
+  snippet: z.string(),
+  position: z.number().optional()
+});
+var webSearchOutputSchema = z.object({
+  success: z.boolean(),
+  source: z.enum(["duckduckgo", "serper"]),
+  query: z.string(),
+  results: z.array(searchResultSchema),
+  totalResults: z.number().optional(),
+  error: z.string().optional(),
+  metadata: z.object({
+    responseTime: z.number().optional(),
+    fallbackUsed: 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.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.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 = 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(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 = toolBuilder().name("json-parser").description("Parse JSON string into an object. Validates JSON syntax and returns parsed data or error details.").category(ToolCategory.UTILITY).tags(["json", "parse", "data"]).schema(z.object({
   json: z.string().describe("JSON string to parse"),
   strict: z.boolean().default(true).describe("Use strict JSON parsing (no trailing commas, etc.)")
@@ -1622,6 +1968,6 @@ var uuidValidator = toolBuilder().name("uuid-validator").description("Validate i
   };
 }).build();
 
-export { arrayFilter, arrayGroupBy, arrayMap, arraySort, calculator, creditCardValidator, csvGenerator, csvParser, csvToJson, currentDateTime, dateArithmetic, dateComparison, dateDifference, dateFormatter, directoryCreate, directoryDelete, directoryList, emailValidator, extractImages, extractLinks, fileAppend, fileDelete, fileExists, fileReader, fileSearch, fileWriter, htmlParser, httpClient, httpGet, httpPost, ipValidator, jsonMerge, jsonParser, jsonQuery, jsonStringify, jsonToCsv, jsonToXml, jsonValidator, mathFunctions, objectOmit, objectPick, pathBasename, pathDirname, pathExtension, pathJoin, pathNormalize, pathParse, pathRelative, pathResolve, phoneValidator, randomNumber, statistics, stringCaseConverter, stringJoin, stringLength, stringReplace, stringSplit, stringSubstring, stringTrim, urlBuilder, urlQueryParser, urlValidator, urlValidatorSimple, uuidValidator, webScraper, xmlGenerator, xmlParser, xmlToJson };
+export { DuckDuckGoProvider, SerperProvider, arrayFilter, arrayGroupBy, arrayMap, arraySort, calculator, createDuckDuckGoProvider, createSerperProvider, creditCardValidator, csvGenerator, csvParser, csvToJson, currentDateTime, dateArithmetic, dateComparison, dateDifference, dateFormatter, directoryCreate, directoryDelete, directoryList, emailValidator, extractImages, extractLinks, fileAppend, fileDelete, fileExists, fileReader, fileSearch, fileWriter, htmlParser, httpClient, httpGet, httpPost, ipValidator, jsonMerge, jsonParser, jsonQuery, jsonStringify, jsonToCsv, jsonToXml, jsonValidator, mathFunctions, objectOmit, objectPick, pathBasename, pathDirname, pathExtension, pathJoin, pathNormalize, pathParse, pathRelative, pathResolve, phoneValidator, randomNumber, searchResultSchema, statistics, stringCaseConverter, stringJoin, stringLength, stringReplace, stringSplit, stringSubstring, stringTrim, urlBuilder, urlQueryParser, urlValidator, urlValidatorSimple, uuidValidator, webScraper, webSearch, webSearchOutputSchema, webSearchSchema, xmlGenerator, xmlParser, xmlToJson };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map