@agentforge/tools 0.3.8 → 0.4.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import * as _agentforge_core from '@agentforge/core';
+import { z } from 'zod';
 
 /**
  * HTTP Client Tool
@@ -216,6 +217,252 @@ declare const urlQueryParser: _agentforge_core.Tool<{
     count: number;
 }>;
 
+/**
+ * Web Search Tool - Type Definitions
+ */
+/**
+ * Individual search result
+ */
+interface SearchResult {
+    title: string;
+    link: string;
+    snippet: string;
+    position?: number;
+}
+/**
+ * Web search input parameters
+ */
+interface WebSearchInput {
+    query: string;
+    maxResults?: number;
+    preferSerper?: boolean;
+    timeout?: number;
+}
+/**
+ * Web search output
+ */
+interface WebSearchOutput {
+    success: boolean;
+    source: 'duckduckgo' | 'serper';
+    query: string;
+    results: SearchResult[];
+    totalResults?: number;
+    error?: string;
+    metadata?: {
+        responseTime?: number;
+        fallbackUsed?: boolean;
+    };
+}
+/**
+ * Search provider interface
+ */
+interface SearchProvider {
+    name: 'duckduckgo' | 'serper';
+    search(query: string, maxResults: number, timeout?: number): Promise<SearchResult[]>;
+    isAvailable(): boolean;
+}
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    maxRetries: number;
+    initialDelay: number;
+    maxDelay: number;
+    backoffMultiplier: number;
+}
+
+/**
+ * Web Search Tool - Zod Schemas
+ */
+
+/**
+ * Web search input schema
+ */
+declare const webSearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodDefault<z.ZodNumber>;
+    preferSerper: z.ZodDefault<z.ZodBoolean>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    timeout: number;
+    query: string;
+    maxResults: number;
+    preferSerper: boolean;
+}, {
+    query: string;
+    timeout?: number | undefined;
+    maxResults?: number | undefined;
+    preferSerper?: boolean | undefined;
+}>;
+/**
+ * Search result schema
+ */
+declare const searchResultSchema: z.ZodObject<{
+    title: z.ZodString;
+    link: z.ZodString;
+    snippet: z.ZodString;
+    position: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    link: string;
+    title: string;
+    snippet: string;
+    position?: number | undefined;
+}, {
+    link: string;
+    title: string;
+    snippet: string;
+    position?: number | undefined;
+}>;
+/**
+ * Web search output schema
+ */
+declare const webSearchOutputSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    source: z.ZodEnum<["duckduckgo", "serper"]>;
+    query: z.ZodString;
+    results: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        link: z.ZodString;
+        snippet: z.ZodString;
+        position: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        link: string;
+        title: string;
+        snippet: string;
+        position?: number | undefined;
+    }, {
+        link: string;
+        title: string;
+        snippet: string;
+        position?: number | undefined;
+    }>, "many">;
+    totalResults: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        responseTime: z.ZodOptional<z.ZodNumber>;
+        fallbackUsed: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        responseTime?: number | undefined;
+        fallbackUsed?: boolean | undefined;
+    }, {
+        responseTime?: number | undefined;
+        fallbackUsed?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    results: {
+        link: string;
+        title: string;
+        snippet: string;
+        position?: number | undefined;
+    }[];
+    query: string;
+    success: boolean;
+    source: "duckduckgo" | "serper";
+    error?: string | undefined;
+    totalResults?: number | undefined;
+    metadata?: {
+        responseTime?: number | undefined;
+        fallbackUsed?: boolean | undefined;
+    } | undefined;
+}, {
+    results: {
+        link: string;
+        title: string;
+        snippet: string;
+        position?: number | undefined;
+    }[];
+    query: string;
+    success: boolean;
+    source: "duckduckgo" | "serper";
+    error?: string | undefined;
+    totalResults?: number | undefined;
+    metadata?: {
+        responseTime?: number | undefined;
+        fallbackUsed?: boolean | undefined;
+    } | undefined;
+}>;
+
+/**
+ * DuckDuckGo Search Provider
+ *
+ * Free search provider using DuckDuckGo's Instant Answer API.
+ * No API key required.
+ */
+
+/**
+ * DuckDuckGo search provider implementation
+ */
+declare class DuckDuckGoProvider implements SearchProvider {
+    name: "duckduckgo";
+    /**
+     * DuckDuckGo is always available (no API key required)
+     */
+    isAvailable(): boolean;
+    /**
+     * 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)
+     */
+    search(query: string, maxResults: number, timeout?: number): Promise<SearchResult[]>;
+    /**
+     * Normalize DuckDuckGo response to SearchResult[]
+     * Optimized for performance with large result sets
+     */
+    private normalizeResults;
+}
+/**
+ * Create a new DuckDuckGo provider instance
+ */
+declare function createDuckDuckGoProvider(): DuckDuckGoProvider;
+
+/**
+ * Serper Search Provider
+ *
+ * Premium search provider using Serper API (Google results).
+ * Requires SERPER_API_KEY environment variable.
+ * Get your API key at: https://serper.dev
+ */
+
+/**
+ * Serper search provider implementation
+ */
+declare class SerperProvider implements SearchProvider {
+    name: "serper";
+    private apiKey;
+    constructor();
+    /**
+     * Serper is available if API key is set
+     */
+    isAvailable(): boolean;
+    /**
+     * Search using Serper API
+     * @param query - Search query
+     * @param maxResults - Maximum number of results to return
+     * @param timeout - Request timeout in milliseconds (default: 30000)
+     */
+    search(query: string, maxResults: number, timeout?: number): Promise<SearchResult[]>;
+    /**
+     * Normalize Serper response to SearchResult[]
+     * Optimized for performance with large result sets
+     */
+    private normalizeResults;
+}
+/**
+ * Create a new Serper provider instance
+ */
+declare function createSerperProvider(): SerperProvider;
+
+/**
+ * Web search tool implementation
+ */
+declare const webSearch: _agentforge_core.Tool<{
+    query: string;
+    timeout?: number | undefined;
+    maxResults?: number | undefined;
+    preferSerper?: boolean | undefined;
+}, WebSearchOutput>;
+
 /**
  * JSON Processor Tool
  *
@@ -1142,4 +1389,4 @@ declare const uuidValidator: _agentforge_core.Tool<{
     message: string;
 }>;
 
-export { type HttpResponse, type ScraperResult, type UrlValidationResult, 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, type HttpResponse, type RetryConfig, type ScraperResult, type SearchProvider, type SearchResult, SerperProvider, type UrlValidationResult, type WebSearchInput, type WebSearchOutput, 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 };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as _agentforge_core from '@agentforge/core';
+import { z } from 'zod';
 
 /**
  * HTTP Client Tool
@@ -216,6 +217,252 @@ declare const urlQueryParser: _agentforge_core.Tool<{
     count: number;
 }>;
 
+/**
+ * Web Search Tool - Type Definitions
+ */
+/**
+ * Individual search result
+ */
+interface SearchResult {
+    title: string;
+    link: string;
+    snippet: string;
+    position?: number;
+}
+/**
+ * Web search input parameters
+ */
+interface WebSearchInput {
+    query: string;
+    maxResults?: number;
+    preferSerper?: boolean;
+    timeout?: number;
+}
+/**
+ * Web search output
+ */
+interface WebSearchOutput {
+    success: boolean;
+    source: 'duckduckgo' | 'serper';
+    query: string;
+    results: SearchResult[];
+    totalResults?: number;
+    error?: string;
+    metadata?: {
+        responseTime?: number;
+        fallbackUsed?: boolean;
+    };
+}
+/**
+ * Search provider interface
+ */
+interface SearchProvider {
+    name: 'duckduckgo' | 'serper';
+    search(query: string, maxResults: number, timeout?: number): Promise<SearchResult[]>;
+    isAvailable(): boolean;
+}
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    maxRetries: number;
+    initialDelay: number;
+    maxDelay: number;
+    backoffMultiplier: number;
+}
+
+/**
+ * Web Search Tool - Zod Schemas
+ */
+
+/**
+ * Web search input schema
+ */
+declare const webSearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodDefault<z.ZodNumber>;
+    preferSerper: z.ZodDefault<z.ZodBoolean>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    timeout: number;
+    query: string;
+    maxResults: number;
+    preferSerper: boolean;
+}, {
+    query: string;
+    timeout?: number | undefined;
+    maxResults?: number | undefined;
+    preferSerper?: boolean | undefined;
+}>;
+/**
+ * Search result schema
+ */
+declare const searchResultSchema: z.ZodObject<{
+    title: z.ZodString;
+    link: z.ZodString;
+    snippet: z.ZodString;
+    position: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    link: string;
+    title: string;
+    snippet: string;
+    position?: number | undefined;
+}, {
+    link: string;
+    title: string;
+    snippet: string;
+    position?: number | undefined;
+}>;
+/**
+ * Web search output schema
+ */
+declare const webSearchOutputSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    source: z.ZodEnum<["duckduckgo", "serper"]>;
+    query: z.ZodString;
+    results: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        link: z.ZodString;
+        snippet: z.ZodString;
+        position: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        link: string;
+        title: string;
+        snippet: string;
+        position?: number | undefined;
+    }, {
+        link: string;
+        title: string;
+        snippet: string;
+        position?: number | undefined;
+    }>, "many">;
+    totalResults: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        responseTime: z.ZodOptional<z.ZodNumber>;
+        fallbackUsed: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        responseTime?: number | undefined;
+        fallbackUsed?: boolean | undefined;
+    }, {
+        responseTime?: number | undefined;
+        fallbackUsed?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    results: {
+        link: string;
+        title: string;
+        snippet: string;
+        position?: number | undefined;
+    }[];
+    query: string;
+    success: boolean;
+    source: "duckduckgo" | "serper";
+    error?: string | undefined;
+    totalResults?: number | undefined;
+    metadata?: {
+        responseTime?: number | undefined;
+        fallbackUsed?: boolean | undefined;
+    } | undefined;
+}, {
+    results: {
+        link: string;
+        title: string;
+        snippet: string;
+        position?: number | undefined;
+    }[];
+    query: string;
+    success: boolean;
+    source: "duckduckgo" | "serper";
+    error?: string | undefined;
+    totalResults?: number | undefined;
+    metadata?: {
+        responseTime?: number | undefined;
+        fallbackUsed?: boolean | undefined;
+    } | undefined;
+}>;
+
+/**
+ * DuckDuckGo Search Provider
+ *
+ * Free search provider using DuckDuckGo's Instant Answer API.
+ * No API key required.
+ */
+
+/**
+ * DuckDuckGo search provider implementation
+ */
+declare class DuckDuckGoProvider implements SearchProvider {
+    name: "duckduckgo";
+    /**
+     * DuckDuckGo is always available (no API key required)
+     */
+    isAvailable(): boolean;
+    /**
+     * 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)
+     */
+    search(query: string, maxResults: number, timeout?: number): Promise<SearchResult[]>;
+    /**
+     * Normalize DuckDuckGo response to SearchResult[]
+     * Optimized for performance with large result sets
+     */
+    private normalizeResults;
+}
+/**
+ * Create a new DuckDuckGo provider instance
+ */
+declare function createDuckDuckGoProvider(): DuckDuckGoProvider;
+
+/**
+ * Serper Search Provider
+ *
+ * Premium search provider using Serper API (Google results).
+ * Requires SERPER_API_KEY environment variable.
+ * Get your API key at: https://serper.dev
+ */
+
+/**
+ * Serper search provider implementation
+ */
+declare class SerperProvider implements SearchProvider {
+    name: "serper";
+    private apiKey;
+    constructor();
+    /**
+     * Serper is available if API key is set
+     */
+    isAvailable(): boolean;
+    /**
+     * Search using Serper API
+     * @param query - Search query
+     * @param maxResults - Maximum number of results to return
+     * @param timeout - Request timeout in milliseconds (default: 30000)
+     */
+    search(query: string, maxResults: number, timeout?: number): Promise<SearchResult[]>;
+    /**
+     * Normalize Serper response to SearchResult[]
+     * Optimized for performance with large result sets
+     */
+    private normalizeResults;
+}
+/**
+ * Create a new Serper provider instance
+ */
+declare function createSerperProvider(): SerperProvider;
+
+/**
+ * Web search tool implementation
+ */
+declare const webSearch: _agentforge_core.Tool<{
+    query: string;
+    timeout?: number | undefined;
+    maxResults?: number | undefined;
+    preferSerper?: boolean | undefined;
+}, WebSearchOutput>;
+
 /**
  * JSON Processor Tool
  *
@@ -1142,4 +1389,4 @@ declare const uuidValidator: _agentforge_core.Tool<{
     message: string;
 }>;
 
-export { type HttpResponse, type ScraperResult, type UrlValidationResult, 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, type HttpResponse, type RetryConfig, type ScraperResult, type SearchProvider, type SearchResult, SerperProvider, type UrlValidationResult, type WebSearchInput, type WebSearchOutput, 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 };