types.d.ts

/**
 * @searchapi/sdk — TypeScript declarations
 */

export interface SearchAPIConfig {
  /** Your SearchAPI key. */
  apiKey: string;
  /** API base URL. Defaults to "https://search.ourweb.ink". */
  baseUrl?: string;
}

// ---------------------------------------------------------------------------
// Request option types
// ---------------------------------------------------------------------------

export interface SearchOptions {
  /** Search profile / category. */
  profile?: string;
  /** Page number (1-based). */
  page?: number;
  /** Comma-separated engine list. */
  engines?: string;
  /** Time filter: "day", "week", "month", or "year". */
  timeRange?: string;
  /** Response format. Defaults to "json". */
  format?: string;
}

export interface AskOptions {
  /** Search profile. */
  profile?: string;
  /** Maximum number of sources to consult. */
  maxSources?: number;
}

export interface ResearchOptions {
  /** Research depth: "quick", "standard", or "deep". */
  depth?: "quick" | "standard" | "deep";
  /** Maximum number of sources to consult. */
  maxSources?: number;
}

export interface ExtractOptions {
  /** Output format: "markdown", "text", or "html". */
  format?: "markdown" | "text" | "html";
}

export interface BatchSearchOptions {
  /** Search profile applied to all queries. */
  profile?: string;
}

// ---------------------------------------------------------------------------
// Response types
// ---------------------------------------------------------------------------

export interface SearchResultItem {
  title: string;
  url: string;
  snippet: string;
  engine?: string;
  score?: number;
}

export interface SearchResult {
  query: string;
  results: SearchResultItem[];
  suggestions?: string[];
  totalResults?: number;
}

export interface Source {
  title: string;
  url: string;
  snippet?: string;
}

export interface AskResult {
  answer: string;
  sources: Source[];
  confidence: number;
}

export interface Finding {
  title: string;
  summary: string;
  sources: Source[];
}

export interface ResearchResult {
  summary: string;
  findings: Finding[];
  sources: Source[];
  papers?: Source[];
}

export interface ExtractResult {
  title: string;
  content: string;
  metadata: Record<string, unknown>;
}

// ---------------------------------------------------------------------------
// Error
// ---------------------------------------------------------------------------

export class SearchAPIError extends Error {
  /** HTTP status code (0 for network errors). */
  status: number;
  /** Machine-readable error code. */
  code: string;
  constructor(message: string, status: number, code: string);
}

// ---------------------------------------------------------------------------
// Client
// ---------------------------------------------------------------------------

export class SearchAPI {
  constructor(config: SearchAPIConfig);

  /** Web search. */
  search(query: string, options?: SearchOptions): Promise<SearchResult>;

  /** AI-powered question answering. */
  ask(query: string, options?: AskOptions): Promise<AskResult>;

  /** Deep research on a topic. */
  research(query: string, options?: ResearchOptions): Promise<ResearchResult>;

  /** Extract structured content from a URL. */
  extract(url: string, options?: ExtractOptions): Promise<ExtractResult>;

  /** Run multiple search queries in a single request. */
  batchSearch(
    queries: string[],
    options?: BatchSearchOptions,
  ): Promise<SearchResult[]>;
}

export default SearchAPI;