Web Search Package

This package provides a client for searching the web via the Tavily API.

Installation

npm install @packages/tavily

Usage

import { WebSearch, WebSearchParams } from "@packages/tavily";

// Create a new client with your app ID
const webSearch = new WebSearch("your-app-id");

// Or with an API key
const webSearchWithKey = new WebSearch("your-app-id", "your-api-key");

// Search the web
const searchParams: WebSearchParams = {
  query: "How does photosynthesis work?",
  max_results: 5,
  include_answer: true
};

async function searchWeb() {
  try {
    const results = await webSearch.search(searchParams);
    console.log(results.answer);
    console.log(results.results);
  } catch (error) {
    console.error("Error searching the web:", error);
  }
}

searchWeb();

API

WebSearch

The main class for interacting with the web search API.

Constructor

new WebSearch(appId: string, apiKey?: string)

• appId: Your application ID
• apiKey: Optional API key for authentication

Methods

search(params: WebSearchParams): Promise<WebSearchOutput>

Search the web using the provided parameters.

Types

WebSearchParams

Parameters for the web search.

interface WebSearchParams {
  /** The search query string */
  query: string;
  /** Maximum number of results to return (default: 5) */
  max_results?: number;
  /** Include images in search results (default: false) */
  include_images?: boolean;
  /** Include answer in search results (default: true) */
  include_answer?: boolean;
  /** Search depth ("basic" or "advanced", default: "basic") */
  search_depth?: "basic" | "advanced";
}

WebSearchOutput

Output from the web search.

interface WebSearchOutput {
  /** The query that was searched */
  query: string;
  /** List of search results */
  results: WebSearchResult[];
  /** Generated answer from search results (if include_answer is true) */
  answer?: string;
}

WebSearchResult

A single search result.

interface WebSearchResult {
  /** Unique identifier for the search result */
  id: string;
  /** The URL of the search result */
  url: string;
  /** The title of the search result */
  title: string;
  /** A snippet of content from the search result */
  content: string;
  /** The source domain of the search result */
  domain: string;
  /** The score/relevance of the result (0-1) */
  score: number;
}

WebSearchError

Error thrown when the web search fails.

class WebSearchError extends Error {
  readonly statusCode: number;
  readonly body: string;
}

Error Handling

import { WebSearch, WebSearchError } from "@packages/tavily";

const webSearch = new WebSearch("your-app-id");

async function searchWeb() {
  try {
    const results = await webSearch.search({ query: "How tall is Mount Everest?" });
    console.log(results);
  } catch (error) {
    if (error instanceof WebSearchError) {
      if (error.isRateLimited()) {
        console.error("Rate limit exceeded. Please try again later.");
      } else if (error.isAuthError()) {
        console.error("Authentication error. Check your app ID or API key.");
      } else if (error.isInputError()) {
        console.error("Invalid input parameters.");
      } else if (error.isServerError()) {
        console.error("Server error. Please try again later.");
      } else {
        console.error("Web search error:", error.message);
      }
    } else {
      console.error("Unexpected error:", error);
    }
  }
}