@bluefields/fetcher 0.2.0

package/dist/fetcher-patchright.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Patchright fetcher adapter (chunks 8 + Phase A real wiring).
+ *
+ * Patchright is a Chromium fork with CDP-leak patches that defeat many
+ * naive bot-detection signals (navigator.webdriver, console.debug
+ * fingerprinting, etc.). API is Playwright-compatible — drop-in.
+ *
+ * Production wiring is gated on IPROYAL_* env vars: when they're set,
+ * the factory (`tryCreatePatchrightAdapter`) returns a real adapter
+ * that launches Chromium with the IPRoyal residential proxy. Without
+ * them, callers fall back to the HTTP adapter (`fetcher-http.ts`).
+ *
+ * Per-fetch lifecycle: launch fresh browser → newContext → newPage →
+ * goto → wait → content + (optional) screenshot → close. One browser
+ * per fetch keeps fingerprint state isolated; pooling can ship later
+ * if launch overhead becomes load-bearing (~500ms per fetch today).
+ *
+ * Fingerprint rotation: v1 uses a small pool of (UA, viewport, locale,
+ * timezone) tuples picked randomly per fetch. Full diversity (Review #4)
+ * comes later — we just need basic variation to defeat per-tuple
+ * fingerprint blocklists.
+ *
+ * Egress IP: deferred. IPRoyal residential proxies rotate per-session;
+ * resolving the actual egress IP requires an extra eval to api.ipify.org
+ * which we don't want to pay on every fetch. Logged as a placeholder for
+ * now; revisit in M14-17 when attestation needs it (Review #3 manifest).
+ */
+import type { ActionResults, PageAction, RequestCookie, WarmableFetcherAdapter } from './types.js';
+export declare const PATCHRIGHT_REQUIRED_ENV: readonly ["IPROYAL_GATEWAY"];
+/** Subset of a Playwright Route we use to abort/continue intercepted requests. */
+export interface PatchrightRoute {
+    request(): {
+        resourceType(): string;
+    };
+    abort(): Promise<void>;
+    continue(): Promise<void>;
+}
+/** Subset of a Playwright Response we read for transferred-byte accounting. */
+export interface PatchrightResponse {
+    headers(): Record<string, string>;
+}
+/**
+ * Pure predicate: should the browser tier abort this request's download?
+ * Extracted so it's unit-tested without a live browser. The caller is
+ * responsible for skipping interception entirely when a screenshot is
+ * requested (a screenshot needs the full visual render).
+ */
+export declare function shouldBlockResource(resourceType: string, opts?: {
+    blockStylesheet?: boolean;
+}): boolean;
+/**
+ * Subset of Playwright's Page surface we actually call. Kept narrow so
+ * the test mock stays small.
+ */
+export interface PatchrightPage {
+    goto(url: string, opts: {
+        waitUntil: 'load' | 'networkidle' | 'domcontentloaded';
+        timeout: number;
+    }): Promise<{
+        status(): number;
+        headers(): Record<string, string>;
+        url(): string;
+    } | null>;
+    waitForSelector(selector: string, opts: {
+        timeout: number;
+    }): Promise<unknown>;
+    waitForTimeout(ms: number): Promise<void>;
+    /**
+     * Wait for a Playwright load state (we use 'networkidle'). Optional: the real
+     * Playwright Page always has it, but the test mock may omit it, and the
+     * full-render path calls it best-effort (skips when absent, swallows timeout).
+     */
+    waitForLoadState?(state: 'load' | 'domcontentloaded' | 'networkidle', opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    content(): Promise<string>;
+    screenshot(opts: {
+        fullPage: boolean;
+    }): Promise<Buffer>;
+    url(): string;
+    /** Click a CSS selector (Phase F actions). */
+    click(selector: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** Fill a selector with text (Phase F actions). */
+    fill(selector: string, text: string): Promise<void>;
+    /** Keyboard namespace — type free-form text or press a single key. */
+    keyboard: {
+        type(text: string): Promise<void>;
+        press(key: string): Promise<void>;
+    };
+    /** Evaluate JS in the page context — used for scroll. */
+    evaluate(fn: string | ((arg?: unknown) => unknown), arg?: unknown): Promise<unknown>;
+    /**
+     * Intercept network requests (optional — real Playwright always has it; the
+     * test mock may omit it, so callers guard with a typeof check). We use it to
+     * abort image/media/font downloads we discard, cutting metered proxy egress.
+     */
+    route?(urlPattern: string, handler: (route: PatchrightRoute) => Promise<void> | void): Promise<void>;
+    /** Subscribe to page events (optional). We use `response` to sum bytes. */
+    on?(event: 'response', handler: (response: PatchrightResponse) => void): void;
+}
+/**
+ * Subset of a Playwright BrowserContext we use. `close()` is optional only so
+ * the narrow test mock can omit it; the adapter always calls it best-effort in
+ * `finally` so a pooled (reused) browser never accumulates one context per fetch.
+ */
+export interface PatchrightBrowserContext {
+    addCookies(cookies: RequestCookie[]): Promise<void>;
+    newPage(): Promise<PatchrightPage>;
+    /** Close the context and all its pages. */
+    close?(): Promise<void>;
+}
+/**
+ * Minimal subset of patchright/playwright's chromium namespace that we
+ * actually use. Tests inject a mock that implements just these methods.
+ */
+export interface ChromiumLauncher {
+    launch(opts: {
+        proxy: {
+            server: string;
+            username: string;
+            password: string;
+        };
+        headless?: boolean;
+        /**
+         * Chromium command-line args. We pass --no-sandbox in Docker because
+         * Chromium's setuid sandbox can't initialize when the process is
+         * root and seccomp isn't configured — the launch silently hangs
+         * otherwise.
+         */
+        args?: string[];
+        /** Hard timeout for the launch step. Default 30s in Playwright. */
+        timeout?: number;
+    }): Promise<{
+        newContext(opts: {
+            userAgent: string;
+            viewport: {
+                width: number;
+                height: number;
+            };
+            locale: string;
+            timezoneId: string;
+            extraHTTPHeaders?: Record<string, string>;
+        }): Promise<PatchrightBrowserContext>;
+        close(): Promise<void>;
+    }>;
+}
+export interface PatchrightAdapterConfig {
+    proxy: {
+        server: string;
+        username: string;
+        password: string;
+    };
+    /** Test seam: inject a mock chromium launcher. */
+    chromiumImpl?: ChromiumLauncher;
+    /** Test seam: deterministic random for fingerprint picking. */
+    rand?: () => number;
+    /** Override the default user agent (rare — fingerprint pool usually wins). */
+    defaultUserAgent?: string;
+    /**
+     * Number of pooled browsers to keep warm. When 0 (default), every fetch
+     * launches and closes a fresh browser (~500ms-1.5s overhead). When > 0,
+     * the first `pool` fetches each take the launch hit, subsequent fetches
+     * reuse a browser and only pay newContext (~30ms).
+     *
+     * Each browser still gets a fresh `newContext` per fetch, so reused
+     * browsers don't leak cookies / localStorage / fingerprint state across
+     * customers.
+     */
+    pool?: number;
+}
+/**
+ * Returns the env-gated Patchright adapter when the required env vars
+ * are set; null otherwise. Callers (the factory in `index.ts`) fall
+ * back to the HTTP adapter when this returns null.
+ */
+export declare function tryCreatePatchrightAdapter(env?: NodeJS.ProcessEnv): WarmableFetcherAdapter | null;
+/**
+ * Direct constructor — bypass the env gate. Useful in tests + when the
+ * caller has the proxy creds from somewhere other than env vars.
+ */
+export declare function createPatchrightAdapter(config: PatchrightAdapterConfig): WarmableFetcherAdapter;
+export interface FullRenderOptions {
+    /** Absolute wall-clock deadline (ms, Date.now-based). Full render never runs past it. */
+    deadlineMs: number;
+    /** Test seam: clock. Default Date.now. */
+    nowMs?: () => number;
+    /** Override the hard iteration cap (test seam). Default FULL_RENDER_MAX_STEPS. */
+    maxSteps?: number;
+}
+/**
+ * Fully render a JS app before its content is read: a best-effort `networkidle`
+ * wait, then a bounded autoscroll + content-settle loop. Used on escalation
+ * re-fetches of a SPA shell (no customer waitFor) so we capture hydrated content
+ * instead of the empty mount point tier-0 returned.
+ *
+ * Hard-bounded so it can never hang: the loop stops
+ * at the FIRST of — the page looks rendered (>= FULL_RENDER_MIN_CHARS visible text
+ * AND the DOM stopped growing), `maxSteps` reached, or the `deadlineMs` passed.
+ * Every page call is best-effort (errors swallowed): a flaky settle must never
+ * fail an otherwise-good fetch. Fetcher-layer only — it issues no new outbound
+ * request of ours; sub-resource loads happen inside the already-proxied browser,
+ * so the SSRF posture is unchanged.
+ */
+export declare function fullyRenderPage(page: PatchrightPage, opts: FullRenderOptions): Promise<void>;
+/**
+ * Execute Phase F actions sequentially against an open page. Throws on
+ * the first failure with the action index included for easier debugging
+ * — the route surfaces this in the 502 response detail.
+ */
+export declare function runActions(page: PatchrightPage, actions: PageAction[]): Promise<ActionResults>;