webpeel 0.7.0 → 0.8.0

package/dist/core/strategies.js

@@ -1,44 +1,73 @@
 /**
- * Smart escalation strategy: try simple fetch first, escalate to browser if needed
+ * Smart escalation strategy: try simple fetch first, escalate to browser if needed.
+ *
+ * Premium server-side optimisations (SWR cache, domain intelligence, parallel
+ * race) are injected via the hook system in `strategy-hooks.ts`.  When no hooks
+ * are registered the strategy degrades gracefully to a simple escalation path
+ * that works great for CLI / npm library usage.
  */
 import { simpleFetch, browserFetch, retryFetch } from './fetcher.js';
+import { getCached, setCached as setBasicCache } from './cache.js';
+import { resolveAndCache } from './dns-cache.js';
 import { BlockedError, NetworkError } from '../types.js';
-/**
- * Smart fetch with automatic escalation
- *
- * Strategy:
- * 1. Try simple HTTP fetch first (fast, ~200ms)
- * 2. If blocked (403, 503, Cloudflare, empty body) → try browser
- * 3. If browser gets blocked (403, CAPTCHA) → try stealth mode
- * 4. If stealth mode is explicitly requested → skip to stealth
- *
- * Returns the result along with which method worked
- */
-export async function smartFetch(url, options = {}) {
-    const { forceBrowser = false, stealth = false, waitMs = 0, userAgent, timeoutMs = 30000, screenshot = false, screenshotFullPage = false, headers, cookies, actions, keepPageOpen = false, } = options;
-    // If stealth is requested, force browser mode (stealth requires browser)
-    const shouldUseBrowser = forceBrowser || screenshot || stealth;
-    // Strategy 1: Simple fetch (unless browser is forced or screenshot is requested)
-    if (!shouldUseBrowser) {
-        try {
-            const result = await retryFetch(() => simpleFetch(url, userAgent, timeoutMs, headers), 3);
-            return {
-                ...result,
-                method: 'simple',
-            };
+import { getStrategyHooks, } from './strategy-hooks.js';
+/* ---------- hardcoded domain rules -------------------------------------- */
+function shouldForceBrowser(url) {
+    try {
+        const hostname = new URL(url).hostname.toLowerCase();
+        // Reddit often returns an HTML shell via simple fetch
+        if (hostname === 'reddit.com' || hostname.endsWith('.reddit.com')) {
+            return { mode: 'browser' };
         }
-        catch (error) {
-            // If blocked or needs JS, escalate to browser
-            if (error instanceof BlockedError) {
-                // Fall through to browser strategy
-            }
-            else {
-                // Re-throw other errors (timeout, network errors)
-                throw error;
-            }
+        // npmjs blocks simple fetch with 403 frequently
+        if (hostname === 'npmjs.com' ||
+            hostname === 'www.npmjs.com' ||
+            hostname.endsWith('.npmjs.com')) {
+            return { mode: 'browser' };
+        }
+        // These are known to aggressively block automation
+        if (hostname === 'glassdoor.com' || hostname.endsWith('.glassdoor.com')) {
+            return { mode: 'stealth' };
+        }
+        if (hostname === 'bloomberg.com' || hostname.endsWith('.bloomberg.com')) {
+            return { mode: 'stealth' };
+        }
+        if (hostname === 'indeed.com' || hostname.endsWith('.indeed.com')) {
+            return { mode: 'stealth' };
         }
     }
-    // Strategy 2: Browser fetch (with or without stealth)
+    catch {
+        // Ignore URL parsing errors; validation happens inside fetchers.
+    }
+    return null;
+}
+/* ---------- helpers ------------------------------------------------------ */
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function shouldEscalateSimpleError(error) {
+    if (error instanceof BlockedError)
+        return true;
+    return error instanceof NetworkError && error.message.includes('TLS/SSL');
+}
+function looksLikeShellPage(result) {
+    const ct = (result.contentType || '').toLowerCase();
+    if (!ct.includes('html'))
+        return false;
+    const text = result.html.replace(/<[^>]*>/g, '').trim();
+    return text.length < 500 && result.html.length > 1000;
+}
+function prefetchDns(url) {
+    try {
+        const hostname = new URL(url).hostname;
+        void resolveAndCache(hostname).catch(() => { });
+    }
+    catch {
+        // Ignore invalid URL.
+    }
+}
+async function fetchWithBrowserStrategy(url, options) {
+    const { userAgent, waitMs, timeoutMs, screenshot, screenshotFullPage, headers, cookies, actions, keepPageOpen, effectiveStealth, signal, } = options;
     try {
         const result = await browserFetch(url, {
             userAgent,
@@ -48,62 +77,274 @@ export async function smartFetch(url, options = {}) {
             screenshotFullPage,
             headers,
             cookies,
-            stealth,
+            stealth: effectiveStealth,
             actions,
             keepPageOpen,
+            signal,
         });
         return {
             ...result,
-            method: stealth ? 'stealth' : 'browser',
+            method: effectiveStealth ? 'stealth' : 'browser',
         };
     }
     catch (error) {
-        // Strategy 3: If browser gets blocked, try stealth mode as fallback (unless already using stealth)
-        if (!stealth && error instanceof BlockedError) {
-            try {
-                const result = await browserFetch(url, {
-                    userAgent,
-                    waitMs,
-                    timeoutMs,
-                    screenshot,
-                    screenshotFullPage,
-                    headers,
-                    cookies,
-                    stealth: true, // Escalate to stealth mode
-                    actions,
-                    keepPageOpen,
-                });
-                return {
-                    ...result,
-                    method: 'stealth',
-                };
-            }
-            catch (stealthError) {
-                // If stealth also fails, throw the original error
-                throw stealthError;
-            }
+        if (isAbortError(error))
+            throw error;
+        // If browser gets blocked, try stealth as fallback (unless already stealth)
+        if (!effectiveStealth && error instanceof BlockedError) {
+            const result = await browserFetch(url, {
+                userAgent,
+                waitMs,
+                timeoutMs,
+                screenshot,
+                screenshotFullPage,
+                headers,
+                cookies,
+                stealth: true,
+                actions,
+                keepPageOpen,
+                signal,
+            });
+            return { ...result, method: 'stealth' };
         }
-        // If browser encounters Cloudflare, retry with extra wait time
+        // If Cloudflare detected, retry with extra wait time
         if (error instanceof NetworkError &&
             error.message.toLowerCase().includes('cloudflare')) {
             const result = await browserFetch(url, {
                 userAgent,
-                waitMs: 5000, // Wait 5s for Cloudflare challenge
+                waitMs: 5000,
                 timeoutMs,
                 screenshot,
                 screenshotFullPage,
                 headers,
                 cookies,
-                stealth, // Keep stealth setting
+                stealth: effectiveStealth,
                 actions,
                 keepPageOpen,
+                signal,
             });
-            return {
-                ...result,
-                method: stealth ? 'stealth' : 'browser',
-            };
+            return { ...result, method: effectiveStealth ? 'stealth' : 'browser' };
         }
         throw error;
     }
 }
+/* ---------- main entry point -------------------------------------------- */
+/**
+ * Smart fetch with automatic escalation.
+ *
+ * Without hooks: simple fetch → browser → stealth escalation.
+ * With premium hooks: SWR cache → domain intel → parallel race → escalation.
+ */
+export async function smartFetch(url, options = {}) {
+    const { forceBrowser = false, stealth = false, waitMs = 0, userAgent, timeoutMs = 30000, screenshot = false, screenshotFullPage = false, headers, cookies, actions, keepPageOpen = false, noCache = false, raceTimeoutMs = 2000, } = options;
+    const hooks = getStrategyHooks();
+    const fetchStartMs = Date.now();
+    const recordMethod = (method) => {
+        if (method === 'cached')
+            return;
+        hooks.recordDomainResult?.(url, method, Date.now() - fetchStartMs);
+    };
+    /* ---- determine effective mode ---------------------------------------- */
+    // Hardcoded rules always take priority, then hook-based domain intelligence.
+    const forced = shouldForceBrowser(url);
+    const recommended = hooks.getDomainRecommendation?.(url) ?? null;
+    const selected = forced ?? recommended;
+    let effectiveForceBrowser = forceBrowser;
+    let effectiveStealth = stealth;
+    if (selected) {
+        effectiveForceBrowser = true;
+        if (selected.mode === 'stealth')
+            effectiveStealth = true;
+    }
+    prefetchDns(url);
+    /* ---- cache eligibility ----------------------------------------------- */
+    const canUseCache = !noCache &&
+        !effectiveForceBrowser &&
+        !effectiveStealth &&
+        !screenshot &&
+        !keepPageOpen &&
+        !actions?.length &&
+        !headers &&
+        !cookies &&
+        waitMs === 0 &&
+        !userAgent;
+    /* ---- hook-based cache check (premium) -------------------------------- */
+    if (canUseCache && hooks.checkCache) {
+        const cached = hooks.checkCache(url);
+        if (cached) {
+            if (cached.stale && hooks.markRevalidating?.(url)) {
+                // Background revalidation — fire-and-forget
+                void (async () => {
+                    try {
+                        const fresh = await simpleFetch(url, userAgent, timeoutMs);
+                        if (!looksLikeShellPage(fresh)) {
+                            hooks.setCache?.(url, { ...fresh, method: 'simple' });
+                        }
+                    }
+                    catch {
+                        // Stale entry continues serving.
+                    }
+                })();
+            }
+            return { ...cached.value, method: 'cached' };
+        }
+    }
+    /* ---- basic cache check (non-premium fallback) ------------------------ */
+    if (canUseCache && !hooks.checkCache) {
+        const basicCached = getCached(url);
+        if (basicCached) {
+            return { ...basicCached, method: 'cached' };
+        }
+    }
+    /* ---- browser-level options ------------------------------------------- */
+    let shouldUseBrowser = effectiveForceBrowser || screenshot || effectiveStealth;
+    const browserOptions = {
+        userAgent,
+        waitMs,
+        timeoutMs,
+        screenshot,
+        screenshotFullPage,
+        headers,
+        cookies,
+        actions,
+        keepPageOpen,
+        effectiveStealth,
+    };
+    /* ---- Strategy: simple fetch (with optional race) --------------------- */
+    if (!shouldUseBrowser) {
+        const simpleAbortController = new AbortController();
+        const simplePromise = retryFetch(() => simpleFetch(url, userAgent, timeoutMs, headers, simpleAbortController.signal), 3).then((result) => {
+            if (looksLikeShellPage(result)) {
+                throw new BlockedError('Shell page detected. Browser rendering required.');
+            }
+            return result;
+        });
+        // Determine race timeout — hooks can override
+        const useRace = hooks.shouldRace?.() ?? false;
+        const effectiveRaceTimeout = useRace
+            ? (hooks.getRaceTimeoutMs?.() ?? raceTimeoutMs)
+            : raceTimeoutMs;
+        let raceTimer;
+        const simpleOrTimeout = await Promise.race([
+            simplePromise
+                .then((result) => ({ type: 'simple-success', result }))
+                .catch((error) => ({ type: 'simple-error', error })),
+            new Promise((resolve) => {
+                raceTimer = setTimeout(() => resolve({ type: 'race-timeout' }), Math.max(effectiveRaceTimeout, 0));
+            }),
+        ]);
+        if (raceTimer)
+            clearTimeout(raceTimer);
+        if (simpleOrTimeout.type === 'simple-success') {
+            const strategyResult = {
+                ...simpleOrTimeout.result,
+                method: 'simple',
+            };
+            if (canUseCache) {
+                hooks.setCache?.(url, strategyResult) ?? setBasicCache(url, strategyResult);
+            }
+            recordMethod('simple');
+            return strategyResult;
+        }
+        if (simpleOrTimeout.type === 'simple-error') {
+            if (!shouldEscalateSimpleError(simpleOrTimeout.error)) {
+                throw simpleOrTimeout.error;
+            }
+            shouldUseBrowser = true;
+        }
+        else {
+            // Race timeout — only start parallel browser if hooks say to race
+            if (useRace) {
+                // Parallel race: simple still running, start browser too
+                const browserAbortController = new AbortController();
+                let simpleError;
+                let browserError;
+                const simpleCandidate = simplePromise
+                    .then((result) => ({ source: 'simple', result }))
+                    .catch((error) => {
+                    simpleError = error;
+                    throw error;
+                });
+                const browserCandidate = fetchWithBrowserStrategy(url, {
+                    ...browserOptions,
+                    signal: browserAbortController.signal,
+                })
+                    .then((result) => ({ source: 'browser', result }))
+                    .catch((error) => {
+                    browserError = error;
+                    throw error;
+                });
+                try {
+                    const winner = await Promise.any([
+                        simpleCandidate,
+                        browserCandidate,
+                    ]);
+                    if (winner.source === 'simple') {
+                        browserAbortController.abort();
+                        const strategyResult = {
+                            ...winner.result,
+                            method: 'simple',
+                        };
+                        if (canUseCache) {
+                            hooks.setCache?.(url, strategyResult) ?? setBasicCache(url, strategyResult);
+                        }
+                        recordMethod('simple');
+                        return strategyResult;
+                    }
+                    simpleAbortController.abort();
+                    if (canUseCache) {
+                        hooks.setCache?.(url, winner.result) ?? setBasicCache(url, winner.result);
+                    }
+                    recordMethod(winner.result.method);
+                    return winner.result;
+                }
+                catch {
+                    if (simpleError &&
+                        !shouldEscalateSimpleError(simpleError) &&
+                        !isAbortError(simpleError)) {
+                        throw simpleError;
+                    }
+                    if (browserError)
+                        throw browserError;
+                    if (simpleError)
+                        throw simpleError;
+                    throw new Error('Both simple and browser fetch attempts failed');
+                }
+            }
+            else {
+                // No race — just wait for the simple fetch to finish
+                const simpleResult = await simplePromise
+                    .then((result) => ({ type: 'simple-success', result }))
+                    .catch((error) => ({ type: 'simple-error', error }));
+                if (simpleResult.type === 'simple-success') {
+                    const strategyResult = {
+                        ...simpleResult.result,
+                        method: 'simple',
+                    };
+                    if (canUseCache) {
+                        hooks.setCache?.(url, strategyResult) ?? setBasicCache(url, strategyResult);
+                    }
+                    recordMethod('simple');
+                    return strategyResult;
+                }
+                if (!shouldEscalateSimpleError(simpleResult.error)) {
+                    throw simpleResult.error;
+                }
+                shouldUseBrowser = true;
+            }
+        }
+    }
+    /* ---- browser / stealth fallback -------------------------------------- */
+    const browserResult = await fetchWithBrowserStrategy(url, browserOptions);
+    if (canUseCache) {
+        hooks.setCache?.(url, browserResult) ?? setBasicCache(url, browserResult);
+    }
+    recordMethod(browserResult.method);
+    return browserResult;
+}
+/* ---------- legacy export for tests ------------------------------------- */
+/**
+ * @deprecated Use `clearStrategyHooks()` from strategy-hooks.ts instead.
+ */
+export { clearStrategyHooks as clearDomainIntel } from './strategy-hooks.js';
 //# sourceMappingURL=strategies.js.map

package/dist/core/strategies.js.map

@@ -1 +1 @@
-{"version":3,"file":"strategies.js","sourceRoot":"","sources":["../../src/core/strategies.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"strategies.js","sourceRoot":"","sources":["../../src/core/strategies.ts"],"names":[],"mappings":"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"}

package/dist/core/strategy-hooks.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Strategy hooks — plugin interface for premium server-side optimizations.
+ *
+ * The base `smartFetch()` in strategies.ts provides solid simple→browser→stealth
+ * escalation.  Hooks allow the server (or any host) to layer on caching, domain
+ * intelligence, and parallel-race strategies *without* shipping that logic in
+ * the npm package.
+ *
+ * Register hooks once at startup via `registerStrategyHooks()`.
+ * All hook methods are optional — unset hooks are simply skipped.
+ */
+import type { FetchResult } from './fetcher.js';
+export interface StrategyResult extends FetchResult {
+    method: 'simple' | 'browser' | 'stealth' | 'cached';
+}
+export interface DomainRecommendation {
+    mode: 'browser' | 'stealth';
+}
+export interface CacheCheckResult {
+    /** Cached response to serve immediately. */
+    value: StrategyResult;
+    /** When true the caller should trigger a background revalidation. */
+    stale: boolean;
+}
+export interface StrategyHooks {
+    /**
+     * Look up `url` in the cache.
+     * Return `null` for a cache miss.
+     * When `stale` is true the result can be served but should be refreshed.
+     */
+    checkCache?(url: string): CacheCheckResult | null;
+    /**
+     * Attempt to mark `url` as "currently revalidating" so that only one
+     * background refresh runs at a time.  Return `true` if this call won
+     * the race (caller should revalidate), `false` otherwise.
+     */
+    markRevalidating?(url: string): boolean;
+    /**
+     * Store a fresh result in the cache.
+     */
+    setCache?(url: string, result: StrategyResult): void;
+    /**
+     * Return a recommendation for how to fetch `url` based on historical
+     * success/failure data for the domain.  Return `null` to let the default
+     * escalation logic decide.
+     */
+    getDomainRecommendation?(url: string): DomainRecommendation | null;
+    /**
+     * Record the outcome of a fetch so the intelligence layer can learn.
+     */
+    recordDomainResult?(url: string, method: 'simple' | 'browser' | 'stealth', latencyMs: number): void;
+    /**
+     * Whether to use the parallel race strategy (fire browser after a short
+     * timeout if simple fetch hasn't resolved).  Default: false (no race).
+     */
+    shouldRace?(): boolean;
+    /**
+     * Timeout (ms) before the race starts a parallel browser fetch.
+     * Only called when `shouldRace()` returns true.  Default: 2000.
+     */
+    getRaceTimeoutMs?(): number;
+}
+/**
+ * Register premium strategy hooks.  Should be called once at server startup.
+ * Calling again replaces the previous hooks entirely.
+ */
+export declare function registerStrategyHooks(hooks: StrategyHooks): void;
+/**
+ * Clear all registered hooks (useful in tests).
+ */
+export declare function clearStrategyHooks(): void;
+/**
+ * Retrieve the current hooks (internal — used by strategies.ts).
+ */
+export declare function getStrategyHooks(): Readonly<StrategyHooks>;
+//# sourceMappingURL=strategy-hooks.d.ts.map

package/dist/core/strategy-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-hooks.d.ts","sourceRoot":"","sources":["../../src/core/strategy-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAIhD,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;CACrD;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,KAAK,EAAE,cAAc,CAAC;IACtB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAG5B;;;;OAIG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAElD;;;;OAIG;IACH,gBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAIrD;;;;OAIG;IACH,uBAAuB,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAAC;IAEnE;;OAEG;IACH,kBAAkB,CAAC,CACjB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,EACxC,SAAS,EAAE,MAAM,GAChB,IAAI,CAAC;IAIR;;;OAGG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC;IAEvB;;;OAGG;IACH,gBAAgB,CAAC,IAAI,MAAM,CAAC;CAC7B;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,QAAQ,CAAC,aAAa,CAAC,CAE1D"}

package/dist/core/strategy-hooks.js

@@ -0,0 +1,33 @@
+/**
+ * Strategy hooks — plugin interface for premium server-side optimizations.
+ *
+ * The base `smartFetch()` in strategies.ts provides solid simple→browser→stealth
+ * escalation.  Hooks allow the server (or any host) to layer on caching, domain
+ * intelligence, and parallel-race strategies *without* shipping that logic in
+ * the npm package.
+ *
+ * Register hooks once at startup via `registerStrategyHooks()`.
+ * All hook methods are optional — unset hooks are simply skipped.
+ */
+/* ---------- singleton registry ------------------------------------------- */
+let registeredHooks = {};
+/**
+ * Register premium strategy hooks.  Should be called once at server startup.
+ * Calling again replaces the previous hooks entirely.
+ */
+export function registerStrategyHooks(hooks) {
+    registeredHooks = { ...hooks };
+}
+/**
+ * Clear all registered hooks (useful in tests).
+ */
+export function clearStrategyHooks() {
+    registeredHooks = {};
+}
+/**
+ * Retrieve the current hooks (internal — used by strategies.ts).
+ */
+export function getStrategyHooks() {
+    return registeredHooks;
+}
+//# sourceMappingURL=strategy-hooks.js.map

package/dist/core/strategy-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-hooks.js","sourceRoot":"","sources":["../../src/core/strategy-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA4EH,+EAA+E;AAE/E,IAAI,eAAe,GAAkB,EAAE,CAAC;AAExC;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAoB;IACxD,eAAe,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,eAAe,GAAG,EAAE,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,eAAe,CAAC;AACzB,CAAC"}

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Main library export
  */
-import { cleanup } from './core/fetcher.js';
+import { cleanup, warmup, closePool } from './core/fetcher.js';
 import type { PeelOptions, PeelResult } from './types.js';
 export * from './types.js';
 export { crawl, type CrawlOptions, type CrawlResult, type CrawlProgress } from './core/crawler.js';
@@ -12,8 +12,13 @@ export { mapDomain, type MapOptions, type MapResult } from './core/map.js';
 export { extractBranding, type BrandingProfile } from './core/branding.js';
 export { trackChange, getSnapshot, clearSnapshots, type ChangeResult, type Snapshot } from './core/change-tracking.js';
 export { extractWithLLM } from './core/extract.js';
-export { runAgent, type AgentOptions, type AgentResult, type AgentProgress } from './core/agent.js';
+export { extractDocumentToFormat, isPdfContentType, isDocxContentType, type DocumentExtractionResult } from './core/documents.js';
+export { extractInlineJson, type InlineExtractOptions, type InlineExtractResult } from './core/extract-inline.js';
+export { runAgent, type AgentOptions, type AgentResult, type AgentProgress, type AgentStreamEvent, type AgentDepth, type AgentTopic } from './core/agent.js';
 export { summarizeContent, type SummarizeOptions } from './core/summarize.js';
+export { getSearchProvider, DuckDuckGoProvider, BraveSearchProvider, type SearchProvider, type SearchProviderId, type WebSearchResult, type WebSearchOptions, } from './core/search-provider.js';
+export { answerQuestion, type AnswerRequest, type AnswerResponse, type AnswerCitation, type LLMProviderId, type TokensUsed, } from './core/answer.js';
+export { searchJobs, type JobCard, type JobDetail, type JobSearchOptions, type JobSearchResult } from './core/jobs.js';
 /**
  * Fetch and extract content from a URL
  *
@@ -56,5 +61,6 @@ export declare function peelBatch(urls: string[], options?: PeelOptions & {
  * Clean up any browser resources
  * Call this when you're done using WebPeel
  */
-export { cleanup };
+export { cleanup, warmup, closePool };
+export { getCached, setCached, clearCache, setCacheTTL } from './core/cache.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAa,MAAM,YAAY,CAAC;AAErE,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACvH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CA+RtF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,WAAW,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,OAAO,CAAC,CAAC,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,CAAC,CAwB1D;AAED;;;GAGG;AACH,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAa,MAAM,YAAY,CAAC;AAErE,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACvH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAClI,OAAO,EAAE,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAClH,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7J,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,UAAU,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEvH;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAyTtF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,WAAW,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,OAAO,CAAC,CAAC,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,CAAC,CAwB1D;AAED;;;GAGG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}