npm package: @superdevhq/web-search
Description: Web search client for Tavily API integration
Latest version: 0.1.0

# Web Search Package

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

## Installation

```bash
npm install @packages/tavily
```

## Usage

```typescript
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

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

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

## Error Handling

```typescript
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);
    }
  }
}
```