@shubhamcodess/tiny-browse 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,279 @@
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/** Anything console-like: only the methods you provide are used. */
+interface Logger {
+    error?(message: string, extra?: unknown): void;
+    warn?(message: string, extra?: unknown): void;
+    info?(message: string, extra?: unknown): void;
+    debug?(message: string, extra?: unknown): void;
+}
+
+type SearchProviderName = "google" | "duckduckgo" | "bing";
+interface Config {
+    browser: {
+        /** Explicit browser executable. Empty = auto-discover. */
+        path: string;
+        /**
+         * `launch` our own Chrome, `attach` to one at `cdpUrl`, or `off`: no Chrome
+         * at all (plain HTTP search and reading; faster, lower coverage).
+         */
+        mode: "launch" | "attach" | "off";
+        cdpUrl: string;
+        headless: boolean;
+        /** Launch at server start (Chrome-first). */
+        eager: boolean;
+        idleTimeoutMs: number;
+        /** On CAPTCHA: answer from the next provider, or show a window for the user. */
+        onChallenge: "fallback" | "show";
+        profileDir: string;
+    };
+    search: {
+        /** Ordered chain: first is primary, rest are fallbacks. */
+        providers: SearchProviderName[];
+        /**
+         * Per-engine request budgets, overriding the strict defaults in
+         * search/budget.ts, e.g. { "google": { "perHour": 10 } }.
+         */
+        limits: Record<string, Partial<{
+            minGapMs: number;
+            jitterMs: number;
+            perMinute: number;
+            perHour: number;
+            perDay: number;
+        }>>;
+        maxResults: number;
+        read: number;
+    };
+    fetch: {
+        timeoutMs: number;
+        maxBytes: number;
+        concurrency: number;
+        allowPrivateNetwork: boolean;
+        /** Private hosts to allow anyway, as "host" or "host:port". */
+        allowHosts: string[];
+    };
+    output: {
+        maxTokens: number;
+        links: "inline" | "reference" | "text";
+    };
+    images: {
+        mode: "off" | "urls" | "inline";
+        max: number;
+        maxBytes: number;
+    };
+    ranking: {
+        prefer: string[];
+        block: string[];
+    };
+    cache: {
+        enabled: boolean;
+        dir: string;
+        pageTtlMs: number;
+        serpTtlMs: number;
+    };
+    /** Hard deadline for one tool call; partial results are returned after it. */
+    callTimeoutMs: number;
+    logLevel: LogLevel;
+}
+/** A recursively partial config, as found in files, env and flags. */
+type ConfigInput = {
+    [K in keyof Config]?: Config[K] extends object ? Partial<Config[K]> : Config[K];
+};
+
+/**
+ * The engine does the actual work (search, fetch, extract, rank). Transports
+ * (MCP, CLI, later HTTP) only translate to and from these types.
+ */
+type Freshness = "any" | "day" | "week" | "month" | "year";
+type RenderMode = "auto" | "http" | "browser";
+
+/**
+ * The one source of truth for tool inputs: the JSON Schemas the MCP tools
+ * advertise, the TypeScript types the library exports, and the conversion to
+ * engine requests. Change a parameter here and every surface follows.
+ */
+
+/** Input of `web_search` (MCP) and `webSearch()` (library). */
+interface WebSearchInput {
+    /** What to search for, in plain words. Google operators like site: and "quotes" work. */
+    query: string;
+    /** How many search results to consider (1-10). */
+    max_results?: number;
+    /** How many of the top results to open and read (0-10). 0 returns only the result list. */
+    read?: number;
+    /** Size limit for the whole answer, in tokens (200-200000). A hard limit. */
+    max_tokens?: number;
+    /** Only return results from this domain, e.g. "docs.python.org". */
+    site?: string;
+    /** Only return results published within this period. */
+    freshness?: Freshness;
+    /** Also return the main images of the pages read (for vision models). */
+    return_images?: boolean;
+}
+/** Input of `web_fetch` (MCP) and `webFetch()` (library). Give `urls` or `cursor`. */
+interface WebFetchInput {
+    /** Absolute http(s) URLs to read (1-10). */
+    urls?: string[];
+    /** Size limit for the whole answer, in tokens (200-200000). A hard limit. */
+    max_tokens?: number;
+    /** Return only the sections most relevant to this question. */
+    focus?: string;
+    /** Continue a page that was cut short, using the cursor from a previous result. */
+    cursor?: string;
+    /** auto picks the fastest way that works; browser forces Chrome; http skips Chrome. */
+    render?: RenderMode;
+    /** Also return the pages' main images (for vision models). */
+    return_images?: boolean;
+}
+
+type TinyBrowseErrorCode = 
+/** No usable Chrome/Chromium/Edge/Brave (or it would not start). */
+"chrome_not_found"
+/** The call ran out of time (`timeoutMs`). */
+ | "timeout"
+/** A site or every search engine refused (CAPTCHA, bot check, rate budget). */
+ | "blocked"
+/** DNS, connection, HTTP or other network failure. */
+ | "network"
+/** The URL points at this computer or a private network. */
+ | "private_address"
+/** The caller's AbortSignal fired. */
+ | "aborted"
+/** The input or options are not valid; the message says how to fix them. */
+ | "invalid_input";
+declare class TinyBrowseError extends Error {
+    readonly code: TinyBrowseErrorCode;
+    name: string;
+    constructor(code: TinyBrowseErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+type TinyBrowseConfig = ConfigInput;
+interface ClientOptions {
+    /** Aborts every call made through this client (or this one call). */
+    signal?: AbortSignal;
+    /** Deadline for each call, in milliseconds (default 20000). */
+    timeoutMs?: number;
+    /**
+     * Settings, merged over the defaults. When given, no config files and no
+     * TINY_BROWSE_* environment variables are read.
+     */
+    config?: TinyBrowseConfig;
+    /** Folder for caches, rate budgets and the Chrome profile (default: the OS cache folder). */
+    cacheDir?: string;
+    /** Chrome/Chromium/Edge/Brave executable to use instead of auto-detecting one. */
+    chromePath?: string;
+    /** Use an already running Chrome with remote debugging (ws:// or http://host:port). */
+    cdpUrl?: string;
+    /**
+     * "chrome" (default): Google in your Chrome, falling back to other engines;
+     * pages read over HTTP or in Chrome as needed.
+     * "http": no Chrome at all. Faster to start and works without Chrome, but
+     * Google is skipped and pages that need JavaScript come back thin.
+     */
+    mode?: "chrome" | "http";
+    /**
+     * "auto": if a `tiny-browse serve --http` is running (found through the
+     * cache folder), send calls to it and reuse its warm Chrome; otherwise run
+     * in this process. "never" (default): always run in this process.
+     */
+    useServer?: "auto" | "never";
+    /** Receives log messages. Default: silent; nothing is ever written to stdout or stderr. */
+    logger?: Logger;
+    /** Lowest level passed to `logger` (default "info"). */
+    logLevel?: LogLevel;
+}
+/** Per-call options for a client created with createClient(). */
+interface CallOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+interface SearchHit {
+    rank: number;
+    title: string;
+    url: string;
+    snippet: string;
+}
+interface Page {
+    /** The URL that was asked for. */
+    url: string;
+    /** Where it ended up after redirects. */
+    finalUrl: string;
+    title: string;
+    /** Clean, heading-structured Markdown of the page (within the token budget). */
+    markdown: string;
+    tokens: number;
+    /** True if parts of the page were left out to fit the budget. */
+    truncated: boolean;
+    /** Pass to webFetch({ cursor }) to read the parts left out. */
+    cursor?: string;
+    /** 0..1 estimate of how cleanly the content was extracted. */
+    quality?: number;
+}
+interface PageFailure {
+    url: string;
+    code: TinyBrowseErrorCode;
+    message: string;
+}
+interface Image {
+    id: string;
+    mimeType: string;
+    /** base64 */
+    data: string;
+}
+interface SearchResult {
+    query: string;
+    /** Which engine answered. */
+    provider: "google" | "duckduckgo" | "bing";
+    /** True if served from the cache (no engine was contacted). */
+    cached: boolean;
+    /** Set when the results may not match the query (degraded engine). */
+    warning?: string;
+    /** The result list. Empty when the engine found nothing (not an error). */
+    results: SearchHit[];
+    /** Pages read from the top results (see `read`). */
+    pages: Page[];
+    /** Results that were picked for reading but could not be read. */
+    failed: PageFailure[];
+    /** Every engine tried, in order, and what happened. */
+    attempts: {
+        provider: string;
+        status: string;
+        note?: string;
+    }[];
+    /** Everything above as Markdown, within max_tokens: what an LLM should read. */
+    markdown: string;
+    images: Image[];
+}
+interface FetchResult {
+    pages: Page[];
+    failed: PageFailure[];
+    markdown: string;
+    images: Image[];
+}
+interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+interface Client {
+    webSearch(input: WebSearchInput, opts?: CallOptions): Promise<SearchResult>;
+    webFetch(input: WebFetchInput, opts?: CallOptions): Promise<FetchResult>;
+    /** Stop Chrome (if this client started it) and release everything. Safe to call twice. */
+    close(): Promise<void>;
+}
+/** A client that reuses one Chrome across calls. Call close() when done. */
+declare function createClient(opts?: ClientOptions): Promise<Client>;
+/** Search the web and read the top results. One-shot: everything is shut down afterwards. */
+declare function webSearch(input: WebSearchInput, opts?: ClientOptions): Promise<SearchResult>;
+/** Read pages as clean Markdown. One-shot: everything is shut down afterwards. */
+declare function webFetch(input: WebFetchInput, opts?: ClientOptions): Promise<FetchResult>;
+/** Check the environment: Node version, browser, a test Chrome start, rate budgets. */
+declare function doctor(opts?: ClientOptions & {
+    startChrome?: boolean;
+}): Promise<DoctorCheck[]>;
+
+/** Package version, injected at build time by tsup (and by vitest in tests). */
+declare const VERSION: string;
+
+export { type CallOptions, type Client, type ClientOptions, type DoctorCheck, type FetchResult, type Freshness, type Image, type LogLevel, type Logger, type Page, type PageFailure, type RenderMode, type SearchHit, type SearchResult, type TinyBrowseConfig, TinyBrowseError, type TinyBrowseErrorCode, VERSION, type WebFetchInput, type WebSearchInput, createClient, doctor, webFetch, webSearch };