@wenathlan/saddle 1.8.17 → 2.0.2

package/dist/webscrape.d.ts

@@ -0,0 +1,720 @@
+/**
+ * webscrape.ts — the legacy WebScrape toolkit generation.
+ *
+ * This file carries the complete legacy scrape sub-project of the former
+ * repository (thirty sections: types, errors, utils, port, tokens,
+ * chunking, formats, serialize, headers, session, pool, proxy, proxypool,
+ * rate-limiter, retry, middleware, events, renderer, sitemap, agent,
+ * llms-txt, fetch, batch, browser, scrape, crawler, server, cli and
+ * dev-server) consolidated into the single root-level file of the grand
+ * merge. The optional npm runtimes of the toolkit (emittery, p-limit,
+ * p-retry, cheerio, playwright, hono, commander) load lazily so nothing is
+ * required at module load that the package does not ship; the CLI,
+ * dev-server and hono API bootstraps are exported factories.
+ */
+import { z } from "zod";
+import type Emittery from "emittery";
+export declare const ScrapeFormatSchema: z.ZodEnum<{
+    html: "html";
+    json: "json";
+    markdown: "markdown";
+    redis: "redis";
+    text: "text";
+    xml: "xml";
+}>;
+export type ScrapeFormat = z.infer<typeof ScrapeFormatSchema>;
+export declare const SerializeTargetSchema: z.ZodEnum<{
+    json: "json";
+    markdown: "markdown";
+    redis: "redis";
+    text: "text";
+    xml: "xml";
+}>;
+export type SerializeTarget = z.infer<typeof SerializeTargetSchema>;
+export declare const ScrapeOptionsSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    html: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodPrefault<z.ZodEnum<{
+        auto: "auto";
+        browser: "browser";
+        fetch: "fetch";
+    }>>>;
+    waitUntil: z.ZodOptional<z.ZodPrefault<z.ZodEnum<{
+        commit: "commit";
+        domcontentloaded: "domcontentloaded";
+        load: "load";
+        networkidle: "networkidle";
+    }>>>;
+    timeout: z.ZodOptional<z.ZodPrefault<z.ZodNumber>>;
+    scroll: z.ZodOptional<z.ZodPrefault<z.ZodBoolean>>;
+    scrollDelay: z.ZodOptional<z.ZodPrefault<z.ZodNumber>>;
+    maxScrolls: z.ZodOptional<z.ZodPrefault<z.ZodNumber>>;
+    removeSelectors: z.ZodOptional<z.ZodPrefault<z.ZodArray<z.ZodString>>>;
+    extractImages: z.ZodOptional<z.ZodPrefault<z.ZodBoolean>>;
+    extractLinks: z.ZodOptional<z.ZodPrefault<z.ZodBoolean>>;
+    extractTables: z.ZodOptional<z.ZodPrefault<z.ZodBoolean>>;
+    maxContentLength: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodPrefault<z.ZodEnum<{
+        html: "html";
+        json: "json";
+        markdown: "markdown";
+        redis: "redis";
+        text: "text";
+        xml: "xml";
+    }>>>;
+    language: z.ZodOptional<z.ZodString>;
+    proxy: z.ZodOptional<z.ZodString>;
+    retries: z.ZodOptional<z.ZodPrefault<z.ZodNumber>>;
+    retryDelay: z.ZodOptional<z.ZodPrefault<z.ZodNumber>>;
+    userAgent: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodPrefault<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    cache: z.ZodOptional<z.ZodPrefault<z.ZodBoolean>>;
+    cacheTtlMs: z.ZodOptional<z.ZodPrefault<z.ZodNumber>>;
+    readable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ScrapeOptions = z.infer<typeof ScrapeOptionsSchema>;
+export interface ScrapeResult {
+    url: string;
+    title: string;
+    content: string;
+    format: ScrapeFormat;
+    text: string;
+    links: LegacyLinkInfo[];
+    images: LegacyImageInfo[];
+    tables: LegacyTableInfo[];
+    metadata: LegacyPageMetadata;
+    extractedAt: string;
+    duration: number;
+    size: number;
+}
+export interface LegacyPageMetadata {
+    title: string;
+    description?: string;
+    favicon?: string;
+    charset?: string;
+    language?: string;
+    author?: string;
+    publishedDate?: string;
+    ogImage?: string;
+    ogType?: string;
+    keywords?: string[];
+}
+export interface LegacyLinkInfo {
+    href: string;
+    text: string;
+    isInternal: boolean;
+    isExternal: boolean;
+}
+export interface LegacyImageInfo {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+}
+export interface LegacyTableInfo {
+    headers: string[];
+    rows: string[][];
+    caption?: string;
+}
+export declare const BrowserAgentConfigSchema: z.ZodObject<{
+    headless: z.ZodOptional<z.ZodPrefault<z.ZodBoolean>>;
+    userAgent: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodPrefault<z.ZodObject<{
+        width: z.ZodPrefault<z.ZodNumber>;
+        height: z.ZodPrefault<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    locale: z.ZodOptional<z.ZodPrefault<z.ZodString>>;
+    geolocation: z.ZodOptional<z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+    }, z.core.$strict>>;
+    timeout: z.ZodOptional<z.ZodPrefault<z.ZodNumber>>;
+    recordVideo: z.ZodOptional<z.ZodPrefault<z.ZodBoolean>>;
+    proxy: z.ZodOptional<z.ZodPrefault<z.ZodString>>;
+    storageState: z.ZodOptional<z.ZodPrefault<z.ZodString>>;
+    blockAds: z.ZodOptional<z.ZodPrefault<z.ZodBoolean>>;
+    stealth: z.ZodOptional<z.ZodPrefault<z.ZodBoolean>>;
+}, z.core.$strict>;
+export type BrowserAgentConfig = z.infer<typeof BrowserAgentConfigSchema>;
+export interface LegacyExtractOptions {
+    readable?: boolean;
+    stripTags?: string[];
+    preserveLinks?: boolean;
+    preserveImages?: boolean;
+    preserveTables?: boolean;
+    maxLength?: number;
+    removeSelectors?: string[];
+    baseUrl?: string;
+}
+export interface SerializeOptions {
+    format: SerializeTarget;
+    pretty?: boolean;
+    maxChunkSize?: number;
+    includeMetadata?: boolean;
+    redisKey?: string;
+    xmlRoot?: string;
+}
+export interface SerializedOutput {
+    format: SerializeTarget;
+    content: string;
+    chunks?: string[];
+    size: number;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentOutput {
+    summary: string;
+    content: string;
+    keyPoints: string[];
+    relevantUrls: string[];
+    structured?: Record<string, unknown>;
+    tokens: number;
+}
+export interface RenderOptions {
+    width?: number;
+    height?: number;
+    fullPage?: boolean;
+    type?: 'png' | 'jpeg';
+    quality?: number;
+    output?: string;
+}
+export interface ChromeCommand {
+    action: 'goto' | 'click' | 'type' | 'screenshot' | 'evaluate' | 'wait' | 'scroll' | 'extract';
+    args?: Record<string, unknown>;
+}
+export interface CliOptions {
+    url?: string;
+    file?: string;
+    format?: ScrapeFormat;
+    output?: string;
+    'no-headless'?: boolean;
+    timeout?: number;
+    scroll?: boolean;
+    readable?: boolean;
+    agent?: boolean;
+    pretty?: boolean;
+    proxy?: string;
+    retries?: number;
+    mode?: 'auto' | 'fetch' | 'browser';
+}
+export interface RetryConfig {
+    retries: number;
+    delay: number;
+    backoff: 'exponential' | 'linear' | 'constant';
+    maxDelay?: number;
+    statusCodes?: number[];
+}
+export interface ProxyConfig {
+    url: string;
+    username?: string;
+    password?: string;
+}
+export interface LegacyCacheConfig {
+    enabled: boolean;
+    ttlMs?: number;
+    maxEntries?: number;
+    storage?: 'memory' | 'redis' | 'sqlite' | 'indexeddb';
+}
+export interface CrawlStats {
+    totalUrls: number;
+    successful: number;
+    failed: number;
+    skipped: number;
+    duration: number;
+    avgResponseTime: number;
+}
+export interface BatchOptions {
+    urls: string[];
+    concurrency?: number;
+    mode?: 'auto' | 'fetch' | 'browser';
+    format?: ScrapeFormat;
+    onProgress?: (completed: number, total: number, currentUrl: string) => void;
+    onError?: (url: string, error: Error) => void;
+}
+export declare const ErrorCode: {
+    readonly VALIDATION_FAILED: 'VALIDATION_FAILED';
+    readonly INVALID_URL: 'INVALID_URL';
+    readonly TIMEOUT: 'TIMEOUT';
+    readonly BLOCKED: 'BLOCKED';
+    readonly RATE_LIMITED: 'RATE_LIMITED';
+    readonly PROXY_ERROR: 'PROXY_ERROR';
+    readonly PARSE_ERROR: 'PARSE_ERROR';
+    readonly AUTH_REQUIRED: 'AUTH_REQUIRED';
+    readonly NETWORK_ERROR: 'NETWORK_ERROR';
+    readonly BROWSER_NOT_AVAILABLE: 'BROWSER_NOT_AVAILABLE';
+    readonly CRAWL_DEPTH_EXCEEDED: 'CRAWL_DEPTH_EXCEEDED';
+    readonly MAX_RETRIES_EXCEEDED: 'MAX_RETRIES_EXCEEDED';
+};
+export type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
+export declare class WebScrapeError extends Error {
+    readonly code: ErrorCode;
+    readonly statusCode: number;
+    readonly isRetryable: boolean;
+    readonly timestamp: string;
+    readonly details?: Record<string, unknown>;
+    readonly cause?: Error;
+    constructor(message: string, code: ErrorCode, statusCode: number, isRetryable: boolean, details?: Record<string, unknown>, cause?: Error);
+    toJSON(): {
+        error: {
+            name: string;
+            code: ErrorCode;
+            message: string;
+            statusCode: number;
+            isRetryable: boolean;
+            timestamp: string;
+            details: Record<string, unknown>;
+        };
+    };
+}
+export declare class ValidationError extends WebScrapeError {
+    constructor(message: string, details?: Record<string, unknown>, cause?: Error);
+}
+export declare class TimeoutError extends WebScrapeError {
+    constructor(message: string, details?: Record<string, unknown>, cause?: Error);
+}
+export declare class BlockedError extends WebScrapeError {
+    constructor(message: string, details?: Record<string, unknown>, cause?: Error);
+}
+export declare class RateLimitError extends WebScrapeError {
+    readonly retryAfterMs?: number;
+    constructor(message: string, retryAfterMs?: number, details?: Record<string, unknown>, cause?: Error);
+}
+export declare class ProxyError extends WebScrapeError {
+    constructor(message: string, details?: Record<string, unknown>, cause?: Error);
+}
+export declare class ParseError extends WebScrapeError {
+    constructor(message: string, details?: Record<string, unknown>, cause?: Error);
+}
+export declare class AuthError extends WebScrapeError {
+    constructor(message: string, details?: Record<string, unknown>, cause?: Error);
+}
+export declare class NetworkError extends WebScrapeError {
+    constructor(message: string, details?: Record<string, unknown>, cause?: Error);
+}
+export declare class BrowserNotAvailableError extends WebScrapeError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+export declare function ensureDir(path: string): void;
+export declare function writeOutput(path: string, content: string): void;
+export declare function slugify(text: string): string;
+export declare function truncate(text: string, max: number, suffix?: string): string;
+export declare function legacyestimatetokens(text: string): number;
+export declare function legacychunktext(text: string, chunkSize: number): string[];
+export declare function delay(ms: number): Promise<void>;
+export declare function isValidUrl(url: string): boolean;
+export declare function normalizeUrl(url: string, base?: string): string;
+export declare function isInternalUrl(href: string, base: string): boolean;
+export declare function randomPort(): number;
+/**
+ * Reset the cached port (for testing).
+ */
+export declare function resetPort(): void;
+export type ModelType = 'gpt-4o' | 'gpt-4' | 'gpt-3.5-turbo' | 'claude' | 'gemini' | 'default';
+export declare function estimateTokens(text: string, model?: ModelType): number;
+export declare function countTokens(text: string, model?: ModelType): number;
+export declare function fitsInContext(text: string, maxTokens: number, model?: ModelType): boolean;
+export declare function truncateToTokens(text: string, maxTokens: number, model?: ModelType): string;
+export declare function tokenCost(text: string, model: ModelType, pricePer1kTokens: number): number;
+export declare const MODEL_PRICES: Record<string, {
+    input: number;
+    output: number;
+}>;
+export interface ChunkOptions {
+    maxTokens?: number;
+    overlapTokens?: number;
+    preserveCodeBlocks?: boolean;
+    includeHeadingPath?: boolean;
+}
+export interface Chunk {
+    content: string;
+    headingPath: string[];
+    tokenCount: number;
+    index: number;
+}
+export declare function chunkMarkdown(markdown: string, options?: ChunkOptions): Chunk[];
+export declare function chunkText(text: string, options?: ChunkOptions): Chunk[];
+export declare function formatChunksForRAG(chunks: Chunk[]): string;
+export declare function resolveFormat(format: string): ScrapeFormat;
+export declare function formatFromExtension(ext: string): ScrapeFormat | null;
+export declare function extensionForFormat(format: ScrapeFormat): string;
+export declare function detectContentType(html: string): 'article' | 'list' | 'page' | 'other';
+export declare function buildSerializeOptions(format: ScrapeFormat, pretty?: boolean): SerializeOptions;
+export declare function convertResult(result: ScrapeResult, targetFormat: ScrapeFormat): Promise<ScrapeResult>;
+export declare function serializeResult(result: ScrapeResult, options: SerializeOptions): SerializedOutput;
+export declare function serializeHtml(html: string, options: SerializeOptions): SerializedOutput;
+export interface HeaderProfile {
+    userAgent: string;
+    accept: string;
+    acceptLanguage: string;
+    secChUa: string;
+    secChUaPlatform: string;
+}
+export declare function getRandomProfile(): HeaderProfile;
+export declare function getHeaders(profile?: HeaderProfile): Record<string, string>;
+export declare function mergeHeaders(base: Record<string, string>, override: Record<string, string>): Record<string, string>;
+export interface Cookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+}
+export declare class CookieJar {
+    private cookies;
+    set(cookie: Cookie): void;
+    get(name: string, domain?: string, _path?: string): Cookie | undefined;
+    getAll(domain?: string): Cookie[];
+    toString(domain?: string): string;
+    parseSetCookie(header: string, defaultDomain?: string): void;
+    clear(): void;
+}
+export declare class ScrapingSession {
+    readonly cookieJar: CookieJar;
+    readonly id: string;
+    private data;
+    constructor(id?: string);
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    clear(): void;
+}
+export declare function createSession(id?: string): ScrapingSession;
+export interface PoolConfig {
+    maxSize?: number;
+    acquireTimeoutMs?: number;
+}
+export declare class BrowserPool {
+    private pool;
+    private waitQueue;
+    private config;
+    private browserConfig;
+    constructor(config?: PoolConfig, browserConfig?: BrowserAgentConfig);
+    acquire(): Promise<AgentBrowser>;
+    release(browser: AgentBrowser): void;
+    destroy(): Promise<void>;
+    getStatus(): {
+        total: number;
+        idle: number;
+        inUse: number;
+        waiting: number;
+    };
+}
+export declare function createPool(config?: PoolConfig, browserConfig?: BrowserAgentConfig): BrowserPool;
+export type ProxyRotationStrategy = 'round-robin' | 'random';
+export interface ProxyPoolConfig {
+    maxFailures?: number;
+    reviveAfterMs?: number;
+    strategy?: ProxyRotationStrategy;
+}
+export declare class ProxyPool {
+    private proxies;
+    private stats;
+    private currentIndex;
+    private config;
+    constructor(proxies: ProxyConfig[], config?: Partial<ProxyPoolConfig>);
+    private getActiveProxies;
+    next(): ProxyConfig | null;
+    reportSuccess(proxy: ProxyConfig): void;
+    reportFailure(proxy: ProxyConfig): void;
+    getStatus(): {
+        total: number;
+        active: number;
+        disabled: number;
+    };
+}
+export declare function createProxyPool(proxies: ProxyConfig[], config?: Partial<ProxyPoolConfig>): ProxyPool;
+/**
+ * proxy pool chooses healthy least used entries and never rotates blindly.
+ */
+export declare function proxypool(options?: {}): {
+    choose: () => any;
+    report: (id: any, result?: {}) => any;
+    list(): any;
+};
+export interface RateLimiterConfig {
+    maxTokensPerInterval: number;
+    intervalMs: number;
+    maxConcurrent?: number;
+}
+export declare class RateLimiter {
+    private buckets;
+    private active;
+    private config;
+    constructor(config?: Partial<RateLimiterConfig>);
+    private getBucket;
+    private refill;
+    acquire(key: string): Promise<void>;
+    release(key: string): void;
+    getStats(key: string): {
+        tokens: number;
+        active: number;
+    };
+    clear(): void;
+}
+export declare function createRateLimiter(config?: Partial<RateLimiterConfig>): RateLimiter;
+export declare const DEFAULT_RETRY_CONFIG: Required<RetryConfig>;
+export declare function isRetryableError(error: Error): boolean;
+export declare function withRetry<T>(fn: (attemptNumber: number) => Promise<T>, config?: Partial<RetryConfig>, onRetry?: (error: Error, attempt: number) => void): Promise<T>;
+/**
+ * Loads the p-retry AbortError class lazily (the class was a value re-export
+ * of the former scrape/retry.ts module; the grand merge keeps it reachable
+ * without requiring p-retry at module load time).
+ */
+export declare function loadaborterror(): Promise<any>;
+export interface MiddlewareContext<T = Record<string, unknown>> {
+    data: T;
+    state: Record<string, unknown>;
+    startTime: number;
+    aborted: boolean;
+    abort(): void;
+}
+export type MiddlewareNext = () => Promise<void>;
+export type Middleware<T = Record<string, unknown>> = (ctx: MiddlewareContext<T>, next: MiddlewareNext) => Promise<void>;
+export declare class MiddlewarePipeline<T = Record<string, unknown>> {
+    private middlewares;
+    use(middleware: Middleware<T>): this;
+    execute(initialData: T): Promise<MiddlewareContext<T>>;
+    clear(): void;
+}
+export declare function loggingMiddleware(logger?: {
+    info: (msg: string) => void;
+}): Middleware;
+export declare function timeoutMiddleware(timeoutMs: number): Middleware;
+export declare function retryMiddleware(maxRetries: number, delayMs: number): Middleware;
+export declare function createPipeline<T = Record<string, unknown>>(): MiddlewarePipeline<T>;
+export interface WebScrapeEvents {
+    'request:start': {
+        url: string;
+        options: ScrapeOptions;
+        timestamp: number;
+    };
+    'request:response': {
+        url: string;
+        status: number;
+        attempt: number;
+        duration: number;
+    };
+    'request:error': {
+        url: string;
+        error: Error;
+        attempt: number;
+    };
+    'request:retry': {
+        url: string;
+        attempt: number;
+        maxRetries: number;
+        delayMs: number;
+    };
+    'request:complete': {
+        url: string;
+        duration: number;
+        success: boolean;
+    };
+    'cache:hit': {
+        key: string;
+    };
+    'cache:miss': {
+        key: string;
+    };
+    'cache:set': {
+        key: string;
+        ttlMs?: number;
+    };
+    'proxy:rotate': {
+        proxy: string;
+        reason: string;
+    };
+    'proxy:error': {
+        proxy: string;
+        error: Error;
+    };
+    'proxy:disabled': {
+        proxy: string;
+        reason: string;
+    };
+    'crawl:discover': {
+        url: string;
+        depth: number;
+        parentUrl?: string;
+    };
+    'crawl:complete': {
+        totalUrls: number;
+        successful: number;
+        failed: number;
+        duration: number;
+    };
+}
+export type EventEmitter = Emittery<WebScrapeEvents>;
+/**
+ * Creates a fresh emittery event bus. Emittery joined the lazy-loading
+ * contract of the grand merge: the optional runtime dependency is imported
+ * on first use, so loading this module never requires it to be installed.
+ */
+export declare function createEventEmitter(): Promise<EventEmitter>;
+export declare function globalEmitter(): any;
+interface PygameConfig {
+    pythonPath?: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    fullscreen?: boolean;
+}
+export declare class PygameRenderer {
+    private config;
+    private process;
+    private tempDir;
+    private screenDir;
+    constructor(config?: PygameConfig);
+    renderScreenshot(imageBuffer: Buffer): Promise<void>;
+    renderDoom(): Promise<void>;
+    private runScript;
+    close(): void;
+}
+export declare function createRenderer(config?: PygameConfig): PygameRenderer;
+export interface SitemapUrl {
+    loc: string;
+    lastmod?: string;
+    changefreq?: string;
+    priority?: number;
+}
+export interface SitemapResult {
+    urls: SitemapUrl[];
+    sitemaps: string[];
+    duration: number;
+}
+export declare function fetchSitemap(url: string, options?: {
+    timeout?: number;
+    headers?: Record<string, string>;
+    fetcher?: typeof fetch;
+}): Promise<SitemapResult>;
+export declare function discoverSitemaps(siteUrl: string): Promise<string[]>;
+export declare function parseSitemap(url: string, options?: {
+    timeout?: number;
+    headers?: Record<string, string>;
+    fetcher?: typeof fetch;
+    followIndexes?: boolean;
+    maxUrls?: number;
+    maxDepth?: number;
+}): Promise<SitemapUrl[]>;
+export interface AgentFormatOptions {
+    includeSummary?: boolean;
+    includeKeyPoints?: boolean;
+    includeUrls?: boolean;
+    includeRaw?: boolean;
+    maxTokens?: number;
+    chunkSize?: number;
+    model?: 'gpt-4o' | 'gpt-4' | 'gpt-3.5-turbo' | 'claude' | 'gemini' | 'default';
+}
+export declare function formatForAgent(result: ScrapeResult, options?: AgentFormatOptions): AgentOutput;
+export declare function buildContext(result: ScrapeResult): string;
+export interface LlmsTxtOptions {
+    siteName?: string;
+    description?: string;
+    includeOptional?: boolean;
+}
+export declare function generateLlmsTxt(results: ScrapeResult[], options?: LlmsTxtOptions): string;
+export declare function generateLlmsFullTxt(results: ScrapeResult[]): string;
+export interface FetchResult {
+    html: string;
+    url: string;
+    status: number;
+    headers: Record<string, string>;
+    duration: number;
+}
+export declare function fetchHtml(url: string, options?: {
+    timeout?: number;
+    headers?: Record<string, string>;
+    userAgent?: string;
+    proxy?: string;
+    signal?: AbortSignal;
+}): Promise<FetchResult>;
+export declare function fetchAndParse(url: string, options?: Partial<ScrapeOptions>): Promise<FetchResult>;
+export declare function detectRenderingMode(html: string): Promise<'static' | 'spa' | 'hydrated'>;
+export interface BatchResult {
+    results: ScrapeResult[];
+    errors: {
+        url: string;
+        error: Error;
+    }[];
+    successful: number;
+    failed: number;
+    duration: number;
+}
+export declare function batchScrape(options: BatchOptions, scrapeOpts?: ScrapeOptions): Promise<BatchResult>;
+export declare function batchScrapeSequential(urls: string[], options?: ScrapeOptions, callbacks?: {
+    onResult?: (result: ScrapeResult, index: number) => void;
+    onError?: (url: string, error: Error, index: number) => void;
+    delayMs?: number;
+}): Promise<BatchResult>;
+export declare class AgentBrowser {
+    private browser;
+    private context;
+    private page;
+    private config;
+    private static DEFAULTS;
+    constructor(config?: Partial<BrowserAgentConfig>);
+    launch(browserType?: 'chromium' | 'firefox' | 'webkit'): Promise<void>;
+    navigate(url: string, waitUntil?: 'load' | 'domcontentloaded' | 'networkidle'): Promise<void>;
+    screenshot(opts?: RenderOptions): Promise<Buffer>;
+    evaluate<T = unknown>(fn: string | (() => T), args?: unknown[]): Promise<T>;
+    click(selector: string): Promise<void>;
+    type(selector: string, text: string, delayMs?: number): Promise<void>;
+    scrollToBottom(step?: number, delayMs?: number, maxScrolls?: number): Promise<number>;
+    scrollTo(x: number, y: number): Promise<void>;
+    waitFor(selector: string, timeout?: number): Promise<void>;
+    waitForLoad(): Promise<void>;
+    html(): Promise<string>;
+    text(): Promise<string>;
+    title(): Promise<string>;
+    url(): Promise<string>;
+    executeCommands(commands: ChromeCommand[]): Promise<unknown[]>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+}
+export declare function createBrowser(config?: BrowserAgentConfig): AgentBrowser;
+export declare function scrapeUrl(url: string, options?: ScrapeOptions): Promise<ScrapeResult>;
+export declare function scrapeHtml(html: string, options?: ScrapeOptions): Promise<ScrapeResult>;
+export declare function scrapeWithBrowser(browser: AgentBrowser, url: string, options?: ScrapeOptions): Promise<ScrapeResult>;
+export interface CrawlOptions extends ScrapeOptions {
+    maxDepth?: number;
+    maxPages?: number;
+    maxConcurrent?: number;
+    sameDomain?: boolean;
+    delayMs?: number;
+    onDiscover?: (url: string, depth: number) => void;
+    onResult?: (result: ScrapeResult) => void;
+    onError?: (url: string, error: Error) => void;
+}
+export declare function legacycrawl(startUrl: string, options?: CrawlOptions): Promise<{
+    results: ScrapeResult[];
+    stats: CrawlStats;
+}>;
+export interface ServerConfig {
+    port?: number;
+    host?: string;
+    apiKey?: string;
+}
+/**
+ * Creates the self-hosted scrape API surface. The factory became async with
+ * the grand merge: the hono application is built on first call and the port
+ * draw keeps using the process-wide random port helper.
+ */
+export declare function createServer(config?: ServerConfig): Promise<{
+    fetch: any;
+    port: number;
+    host: string;
+}>;
+/**
+ * Runs the webscrape CLI. The former top-level commander construction of
+ * scrape/cli.ts became this exported factory in the grand merge: commander
+ * is imported on first call and loading the module never requires it.
+ */
+export declare function runscrapecli(): Promise<void>;
+/**
+ * Starts the local scrape API dev server. The former top-level bootstrap
+ * of scrape/dev-server.ts became this exported factory in the grand merge
+ * (a merged module must never bind a port as an import side effect).
+ */
+export declare function startdevserver(): import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>;
+export {};
+//# sourceMappingURL=webscrape.d.ts.map