Repository Public
1export type SearchType = "web" | "images" | "videos";2export type TimeRange = "day" | "week" | "month" | "year";34export interface SearchRequest {5 query: string;6 type: SearchType;7 language?: string; // ISO 639-18 region?: string; // ISO 3166-1 alpha-29 page: number; // 1-based10 timeRange?: TimeRange;11 safeSearch: boolean;12 summary: boolean;13 /** Restrict video results to one platform. */14 source?: "youtube" | "vimeo" | "dailymotion";15}1617export interface WebResult {18 id: string;19 title: string;20 url: string;21 domain: string;22 favicon: string | null;23 snippet: string;24 publishedDate: string | null;25 score: number | null;26}2728export interface ImageResult {29 id: string;30 imageURL: string;31 imageDomain: string;32 description: string | null;33 /** Page the image was found on, when the provider attributes it. */34 sourceURL: string | null;35 sourceTitle: string | null;36 sourceDomain: string | null;37 /** Smaller rendition for the grid, when the provider offers one. */38 thumbnailURL: string | null;39 /** Pixel size reported by the provider; null means the app measures it once the image is loaded. */40 width: number | null;41 height: number | null;42 author: string | null;43 license: string | null;44 provider: "tavily" | "wikimedia-commons";45}4647export interface VideoResult {48 id: string;49 url: string;50 title: string;51 platform: "youtube" | "vimeo" | "dailymotion";52 channel: string | null;53 channelURL: string | null;54 thumbnail: string | null;55 durationSeconds: number | null;56 publishedDate: string | null;57 description: string | null;58 embedURL: string | null;59 /** How the video metadata was confirmed: the platform's oEmbed endpoint or its official data API. */60 verifiedBy: "oembed" | "youtube-data-api";61}6263export interface SearchResponse {64 query: string;65 type: SearchType;66 page: number;67 pageSize: number;68 hasMore: boolean;69 provider: string;70 cached: boolean;71 tookMs: number;72 answer: { text: string; generatedBy: string } | null;73 results: (WebResult | ImageResult | VideoResult)[];74 /** Machine-readable remarks about what the provider could not supply (e.g. "video-duration-unavailable"). */75 notices: string[];76}7778/** One provider round-trip: up to ~20 raw items that pages are then cut from. */79export interface Batch<T> {80 items: T[];81 answer: string | null;82 credits: number;83 provider: string;84 notices: string[];85 /** Domains seen in this batch; excluded when fetching the next one. */86 domains: string[];87 /** False when the provider returned fewer items than asked: there is nothing further to fetch. */88 exhausted: boolean;89 /** Opaque continuation for providers with real pagination (YouTube). */90 nextToken?: string | null;91 /** True when the batch is known to be incomplete for a transient reason: it is served but not cached. */92 volatile?: boolean;93}9495export class ProviderError extends Error {96 status: number;97 code: string;98 retryAfter?: number;99 constructor(status: number, code: string, message: string, retryAfter?: number) {100 super(message);101 this.status = status;102 this.code = code;103 this.retryAfter = retryAfter;104 }105}106