Web Search Tavily

#!/usr/bin/env -S deno run --allow-env --allow-net=api.tavily.com

/**
 * Web Search CLI - Tavily API Integration
 *
 * A standalone CLI script for searching the web using Tavily's AI-optimized search API.
 * Provides high-quality results designed for LLM consumption.
 *
 * Usage:
 *   deno run --allow-env --allow-net=api.tavily.com scripts/search.ts "query"
 *   deno run --allow-env --allow-net=api.tavily.com scripts/search.ts "query" --answer
 *   deno run --allow-env --allow-net=api.tavily.com scripts/search.ts "query" --depth advanced
 *   # Or if executable: ./scripts/search.ts "query"
 *
 * Environment Variables:
 *   TAVILY_API_KEY - Required. Your Tavily API key from https://tavily.com
 *
 * Permissions:
 *   --allow-env: Read TAVILY_API_KEY environment variable
 *   --allow-net=api.tavily.com: Make API requests to Tavily
 */

// === Constants ===
const VERSION = "1.0.0";
const SCRIPT_NAME = "search";

// === Types ===
export interface TavilyResult {
  title: string;
  url: string;
  content: string;
  score?: number;
  published_date?: string;
  raw_content?: string;
}

export interface TavilyResponse {
  results: TavilyResult[];
  answer?: string;
  query: string;
  response_time?: number;
}

export interface SearchOptions {
  query: string;
  maxResults?: number;
  topic?: "general" | "news" | "finance";
  includeAnswer?: boolean;
  includeRawContent?: boolean;
  searchDepth?: "basic" | "advanced";
  timeRange?: "day" | "week" | "month" | "year";
  days?: number;
  includeDomains?: string[];
  excludeDomains?: string[];
}

// === Core Logic ===
export async function tavilySearch(options: SearchOptions): Promise<TavilyResponse> {
  const apiKey = Deno.env.get("TAVILY_API_KEY");
  if (!apiKey) {
    throw new Error("TAVILY_API_KEY environment variable is not set");
  }

  const requestBody: Record<string, unknown> = {
    query: options.query,
    max_results: options.maxResults ?? 5,
    topic: options.topic ?? "general",
    include_answer: options.includeAnswer ?? false,
    include_raw_content: options.includeRawContent ?? false,
    search_depth: options.searchDepth ?? "basic",
  };

  if (options.timeRange) {
    requestBody.time_range = options.timeRange;
  }
  if (options.topic === "news" && options.days !== undefined) {
    requestBody.days = options.days;
  }
  if (options.includeDomains && options.includeDomains.length > 0) {
    requestBody.include_domains = options.includeDomains;
  }
  if (options.excludeDomains && options.excludeDomains.length > 0) {
    requestBody.exclude_domains = options.excludeDomains;
  }

  const startTime = Date.now();

  const response = await fetch("https://api.tavily.com/search", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      api_key: apiKey,
      ...requestBody,
    }),
  });

  if (!response.ok) {
    const errorText = await response.text();
    if (response.status === 401) {
      throw new Error("Invalid Tavily API key");
    } else if (response.status === 429) {
      throw new Error("Tavily API rate limit exceeded");
    } else if (response.status === 400) {
      throw new Error(`Bad request: ${errorText}`);
    }
    throw new Error(`Tavily API error (${response.status}): ${errorText}`);
  }

  const data = await response.json();
  const endTime = Date.now();

  return {
    results: data.results?.map((r: TavilyResult) => ({
      title: r.title || "",
      url: r.url || "",
      content: r.content || "",
      score: r.score,
      published_date: r.published_date,
      raw_content: r.raw_content,
    })) || [],
    answer: data.answer,
    query: data.query || options.query,
    response_time: endTime - startTime,
  };
}

// === Help Text ===
function printHelp(): void {
  console.log(`
${SCRIPT_NAME} v${VERSION} - Web search using Tavily API

Usage:
  deno run --allow-env --allow-net=api.tavily.com scripts/search.ts [options] "query"

Arguments:
  "query"          The search query (required