@opencraw/core 0.1.2 → 0.1.4

package/README.md

@@ -16,7 +16,7 @@ npx playwright install chromium   # web recipes and browser bootstraps only
 | `loadRecipes(source)` | Reads, validates and binds recipes from one source holding all of them, the output recipe found by its `kind`. The source is any of the forms below. Throws `RecipeValidationError` / `RecipeBindingError` with every problem and its JSON path. |
 | `loadRecipeSet({ output, inputs })` | The same, with the output recipe given apart; each part is any of the forms below. |
 | `readRecipeSource(source)` | Decodes recipes without validating them, each with where it came from, for tooling. |
-| `createCrawler(options)` | Builds an engine: `hooks`, `sink` (`memorySink()` default, `jsonLinesSink(path, { append? })`), `onEvent`, `browser` settings, `dedupe` (`run` / `recipe` / `off`), `onRecipeError` (`continue` / `stop`), `resume` (skip keys the sink already has), `access` + `accessPlugins` (proxy profiles, see [access.md](../../docs/recipes/access.md)), `captchaSolvers` (see [captcha.md](../../docs/recipes/captcha.md)). |
+| `createCrawler(options)` | Builds an engine: `hooks`, `sink` (`memorySink()` default, `jsonLinesSink(path, { append? })`), `onEvent`, `browser` settings, `dedupe` (`run` / `recipe` / `off`), `onRecipeError` (`continue` / `stop`), `resume` (skip keys the sink already has), `access` + `accessPlugins` (proxy profiles, see [access.md](../../docs/recipes/access.md)), `captchaSolvers` (see [captcha.md](../../docs/recipes/captcha.md)), `throttle` (per-site politeness), `retry` (requests that fail in passing), `parallel` (input recipes at once), `profilesDir` (persistent browser profiles). |
 | `loadAccessConfig(path)`, `AccessBroker`, `ACCESS_PRESETS` | Access configs: load and validate one, lease a profile outside a crawl (the cli's `probe` does), list the provider presets. |
 | `crawler.run(set)` | Runs every input recipe in sequence; returns a `CrawlReport`. |
 | `crawler.close()` | Closes the browser, if one was launched. |

package/dist/access/access-broker.use-case.d.ts

@@ -0,0 +1,43 @@
+import type { AccessLease, AccessPlugin, LeaseRequest } from './access-plugin.contract.js';
+type Env = Record<string, string | undefined>;
+/**
+ * Turns the runner's access config into leases: one per recipe run, shared by
+ * its bootstrap and its runner, and a new one on every rotation. The config is
+ * checked when the broker is built (profiles, presets, their parameters,
+ * plugin names); environment variables are checked when a profile is leased,
+ * so a config listing several providers only needs the variables of the one in
+ * use.
+ */
+export declare class AccessBroker {
+    private readonly env;
+    private readonly config;
+    private readonly plugins;
+    private readonly poolCursor;
+    /**
+     * @param config - The access config; none means every recipe goes direct.
+     * @param plugins - Plugins `{ kind: 'plugin' }` profiles may name.
+     * @param env - Where `{{env.X}}` reads from; the process environment by default.
+     * @throws AccessConfigError when the config cannot work.
+     */
+    constructor(config?: unknown, plugins?: readonly AccessPlugin[], env?: Env);
+    /** The profile names, for messages and tools. */
+    get profileNames(): string[];
+    /**
+     * A lease for one recipe run.
+     *
+     * @param request - The recipe, the profile it asks for, country and stickiness.
+     * @returns How the run reaches the network.
+     * @throws AccessConfigError for an unknown profile or a missing environment variable.
+     */
+    lease(request: LeaseRequest): Promise<AccessLease>;
+}
+/**
+ * An endpoint as events may show it: scheme, host and path, without the
+ * credentials or tokens remote-browser URLs carry.
+ *
+ * @param endpoint - A proxy server or CDP endpoint.
+ * @returns The redacted form.
+ */
+export declare function redactEndpoint(endpoint: string): string;
+export {};
+//# sourceMappingURL=access-broker.use-case.d.ts.map

package/dist/access/access-config.error.d.ts

@@ -0,0 +1,5 @@
+/** An access config that cannot work: a bad profile, an unknown preset or plugin, a missing parameter or environment variable. */
+export declare class AccessConfigError extends Error {
+    readonly name = "AccessConfigError";
+}
+//# sourceMappingURL=access-config.error.d.ts.map

package/dist/access/access-config.repository.d.ts

@@ -0,0 +1,11 @@
+import type { AccessConfig } from './access-profile.contract.js';
+/**
+ * Reads an access config file. Secrets stay out of it: profiles reference
+ * them as `{{env.NAME}}`, resolved when a profile is leased.
+ *
+ * @param path - A JSON file.
+ * @returns The validated config.
+ * @throws AccessConfigError when the file is not JSON or not a valid config.
+ */
+export declare function loadAccessConfig(path: string): Promise<AccessConfig>;
+//# sourceMappingURL=access-config.repository.d.ts.map

package/dist/access/access-json-schema.mapper.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The JSON Schema for access config files, for editors: point `$schema` at
+ * `schemas/access-config.schema.json`.
+ *
+ * @returns A draft 2020-12 document.
+ */
+export declare function accessConfigJsonSchema(): Record<string, unknown>;
+//# sourceMappingURL=access-json-schema.mapper.d.ts.map

package/dist/access/access-plugin.contract.d.ts

@@ -0,0 +1,48 @@
+import type { BlockableResource, ProxySettings } from './access-profile.contract.js';
+/** What a recipe run asks the access layer for. */
+export interface LeaseRequest {
+    recipeId: string;
+    /** The profile to use; the config's default when omitted, `direct` when there is none. */
+    profile?: string;
+    /** ISO country code the recipe wants its traffic to come from. */
+    country?: string;
+    /** Overrides the profile's `session.rotate`: `true` keeps one IP for the run, `false` lets the provider rotate. */
+    sticky?: boolean;
+    /** 1 for the first lease of a run, higher after a rotation. */
+    attempt?: number;
+}
+/** How one recipe run reaches the network: applied to its browser context, its HTTP context and its bootstrap alike. */
+export interface AccessLease {
+    profile: string;
+    kind: string;
+    proxy?: ProxySettings;
+    /** The sticky session id, when the lease has one. */
+    session?: string;
+    headers?: Record<string, string>;
+    ignoreHTTPSErrors?: boolean;
+    blockResources?: BlockableResource[];
+    /** A remote browser to connect to instead of launching one (web recipes and bootstraps only). */
+    cdp?: {
+        endpoint: string;
+        headers?: Record<string, string>;
+    };
+    /** Called when the run ends or rotates away from this lease. */
+    release?: () => Promise<void>;
+}
+/** What a plugin receives: the request plus its profile's options, every string rendered. */
+export interface PluginLeaseRequest extends LeaseRequest {
+    profile: string;
+    options: Record<string, unknown>;
+    attempt: number;
+}
+/**
+ * The extension point for access that config cannot express: a remote browser
+ * whose URL comes from a REST call, a proxy list fetched from an API, a
+ * rotating credential. Registered on the crawler, referenced by name from a
+ * `{ kind: 'plugin', name }` profile.
+ */
+export interface AccessPlugin {
+    name: string;
+    lease: (request: PluginLeaseRequest) => Promise<Omit<AccessLease, 'profile' | 'kind'>> | Omit<AccessLease, 'profile' | 'kind'>;
+}
+//# sourceMappingURL=access-plugin.contract.d.ts.map

package/dist/access/access-preset.store.d.ts

@@ -0,0 +1,19 @@
+import type { ProxyProfile } from './access-profile.contract.js';
+/**
+ * Provider presets. Providers all speak plain HTTP proxy with basic auth; they
+ * differ in where targeting and session tokens go (username, password, headers)
+ * and in whether they intercept HTTPS. A preset is only that knowledge, as
+ * templates: adding a provider is adding an entry here, never code.
+ *
+ * Templates read `params.*` (the profile's parameters, which may themselves
+ * read `env.*`), `country` and `session` (absent when the lease is not sticky).
+ */
+export interface AccessPreset {
+    /** One line for docs and error messages. */
+    description: string;
+    /** `params` the profile must set. */
+    requiredParams: string[];
+    profile: Omit<ProxyProfile, 'kind' | 'preset' | 'params'>;
+}
+export declare const ACCESS_PRESETS: Record<string, AccessPreset>;
+//# sourceMappingURL=access-preset.store.d.ts.map

package/dist/access/access-profile.contract.d.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import type { ThrottleConfig } from '../step-flow/index.js';
+/**
+ * Where a crawl's traffic goes. Profiles live in the runner's access config,
+ * never in a recipe: they hold the user's accounts. Every string may use
+ * `{{ }}` templates over `env.*` (the process environment), `params.*` (the
+ * profile's own parameters), `session`, `country` and `recipe.id`.
+ */
+/** A proxy in Playwright's shape; used for browser contexts and HTTP request contexts alike. */
+export interface ProxySettings {
+    server: string;
+    username?: string;
+    password?: string;
+    /** Comma-separated hosts that skip the proxy. */
+    bypass?: string;
+}
+/** Resource types a page may skip loading, to save bandwidth on per-GB proxies. */
+export declare const BLOCKABLE_RESOURCES: readonly ['image', 'media', 'font', 'stylesheet', 'script', 'texttrack', 'xhr', 'fetch', 'eventsource', 'websocket', 'manifest', 'other'];
+export type BlockableResource = typeof BLOCKABLE_RESOURCES[number];
+/** How a sticky session id is generated: character class and length, such as `alnum8` or `digits6`. */
+export declare const SESSION_ID_FORMAT: RegExp;
+export interface ProxySessionSettings {
+    /** Default `alnum10`. Providers constrain it: IPRoyal wants exactly 8 characters, NetNut digits. */
+    idFormat?: string;
+    /** `per-recipe` (default): one sticky session per recipe run. `per-request`: no session id, the provider rotates. */
+    rotate?: 'per-recipe' | 'per-request';
+}
+interface ProfileCommon {
+    /** Headers sent with every request: provider controls such as `x-oxylabs-geo-location`. Templates allowed; empty values are dropped. */
+    headers?: Record<string, string>;
+    /** Needed by providers that intercept HTTPS (unblockers, Bright Data residential). */
+    ignoreHTTPSErrors?: boolean;
+    /** Resource types pages skip (web mode). */
+    blockResources?: BlockableResource[];
+}
+export interface DirectProfile {
+    kind: 'direct';
+}
+export interface ProxyProfile extends ProfileCommon {
+    kind: 'proxy';
+    /** A built-in preset that fills `server`, `username`, `password`, `headers` and defaults; explicit fields override it. */
+    preset?: string;
+    /** Values the preset's templates read as `params.*`. */
+    params?: Record<string, string>;
+    server?: string;
+    username?: string;
+    password?: string;
+    bypass?: string;
+    session?: ProxySessionSettings;
+}
+export interface PoolProfile extends ProfileCommon {
+    kind: 'pool';
+    proxies: ProxySettings[];
+    /** Default `round-robin`. The pool advances per lease: per recipe run, and on every rotation. */
+    rotate?: 'round-robin' | 'random';
+}
+/**
+ * A remote browser reached over the Chrome DevTools Protocol (Bright Data
+ * Browser API, Browserless, Oxylabs, Zyte...): web recipes and bootstraps run
+ * in it, and it handles IPs, fingerprints and challenges. Api recipes cannot
+ * use it.
+ */
+export interface CdpProfile {
+    kind: 'cdp';
+    /** `wss://...` or `http://host:port`; a template, usually carrying the token or credentials. */
+    endpoint: string;
+    /** Headers sent with the connection, such as `Authorization`. Templates. */
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    session?: {
+        idFormat?: string;
+    };
+    blockResources?: BlockableResource[];
+}
+export interface PluginProfile {
+    kind: 'plugin';
+    /** The name an `AccessPlugin` was registered under. */
+    name: string;
+    /** Passed to the plugin with every string rendered. */
+    options?: Record<string, unknown>;
+}
+export type AccessProfile = DirectProfile | ProxyProfile | PoolProfile | CdpProfile | PluginProfile;
+/** The runner's access config: named profiles and the one used when a recipe names none. */
+export interface AccessConfig {
+    $schema?: string;
+    profiles: Record<string, AccessProfile>;
+    default?: string;
+    /** How gently each site is crawled, across every recipe: `{ delayMs?, concurrency?, domains? }`. */
+    throttle?: ThrottleConfig;
+}
+export declare const accessProfileSchema: z.ZodType<AccessProfile>;
+export declare const throttleConfigSchema: z.ZodType<ThrottleConfig>;
+export declare const accessConfigSchema: z.ZodType<AccessConfig>;
+export {};
+//# sourceMappingURL=access-profile.contract.d.ts.map

package/dist/access/index.d.ts

@@ -0,0 +1,11 @@
+export { AccessBroker, redactEndpoint } from './access-broker.use-case.js';
+export { loadAccessConfig } from './access-config.repository.js';
+export { AccessConfigError } from './access-config.error.js';
+export { ACCESS_PRESETS } from './access-preset.store.js';
+export type { AccessPreset } from './access-preset.store.js';
+export { accessConfigSchema, accessProfileSchema, throttleConfigSchema, BLOCKABLE_RESOURCES } from './access-profile.contract.js';
+export type { AccessConfig, AccessProfile, ProxyProfile, PoolProfile, CdpProfile, PluginProfile, DirectProfile, ProxySettings, BlockableResource } from './access-profile.contract.js';
+export type { AccessPlugin, AccessLease, LeaseRequest, PluginLeaseRequest } from './access-plugin.contract.js';
+export { newSessionId } from './session-id.algorithm.js';
+export { accessConfigJsonSchema } from './access-json-schema.mapper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/access/render-access.mapper.d.ts

@@ -0,0 +1,41 @@
+/** What access templates can read. */
+export interface AccessTemplateContext {
+    env: Record<string, string | undefined>;
+    params?: Record<string, string>;
+    session?: string;
+    country?: string;
+    recipe?: {
+        id: string;
+    };
+}
+/**
+ * Renders one access template. An `env.*` path that is not set fails loudly:
+ * an empty password would otherwise reach the provider and fail as a 407.
+ *
+ * @param template - The text.
+ * @param context - What `{{ }}` can read.
+ * @param where - The profile field, for the error.
+ * @returns The rendered text.
+ * @throws AccessConfigError naming the missing environment variable.
+ */
+export declare function renderAccessText(template: string, context: AccessTemplateContext, where: string): string;
+/**
+ * Renders every string inside a value, keeping its shape.
+ *
+ * @param value - Plugin options, a header map...
+ * @param context - What `{{ }}` can read.
+ * @param where - For errors.
+ * @returns The rendered copy.
+ */
+export declare function renderAccessDeep(value: unknown, context: AccessTemplateContext, where: string): unknown;
+/**
+ * Renders a header map and drops headers that render empty, so a template
+ * such as `{{country ? upper(country) : ''}}` can leave a header out.
+ *
+ * @param headers - The templated headers.
+ * @param context - What `{{ }}` can read.
+ * @param where - For errors.
+ * @returns The headers to send, or `undefined` when none remain.
+ */
+export declare function renderHeaders(headers: Record<string, string> | undefined, context: AccessTemplateContext, where: string): Record<string, string> | undefined;
+//# sourceMappingURL=render-access.mapper.d.ts.map

package/dist/access/session-id.algorithm.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A new random session id in a provider's format.
+ *
+ * @param format - `alnum8`, `digits6`, `hex16`...
+ * @returns The id. A `digits` id never starts with 0, so providers that read it as a number keep its length.
+ */
+export declare function newSessionId(format?: string): string;
+//# sourceMappingURL=session-id.algorithm.d.ts.map

package/dist/api-steps/extract-from-document.use-case.d.ts

@@ -0,0 +1,41 @@
+import type { ExtractionScope, ScopeDocument } from '../extraction-scope/index.js';
+import type { ExtractStep } from '../recipe-schema/index.js';
+/**
+ * Runs an `extract` step against a static document: the value bound under
+ * `from`, else the scope's current document. `css` reads HTML (or XML),
+ * `xpath` reads XML (a feed, a sitemap) or HTML parsed as a browser parses
+ * it, `jsonpath` reads JSON (or a read PDF, workbook or deck as data), `table`
+ * reads the tables of a PDF, a workbook (a spreadsheet, a CSV), a deck (a
+ * presentation) or HTML (its `<table>`s), `regex` reads any document as text.
+ *
+ * A `jsonpath` extract whose `from` is text parses that text as JSON, and a
+ * list of texts (every `<script type="application/ld+json">` of a page) becomes
+ * an array of the entries that parse, so `$[*].actors[*].name` finds the block
+ * that has actors wherever it sits.
+ *
+ * @param step - The extract step.
+ * @param scope - Where the document and the result live.
+ * @throws NoMatchError when a single extract matches nothing.
+ */
+export declare function extractFromDocument(step: ExtractStep, scope: ExtractionScope): void;
+/**
+ * A selector may carry `{{ }}` placeholders (a trim name, an id): they render
+ * against the scope before the selector runs.
+ *
+ * @param selector - The recipe's selector.
+ * @param scope - The current scope.
+ * @returns The selector to run.
+ */
+export declare function renderSelector(selector: string, scope: ExtractionScope): string;
+/**
+ * The tables a `table` extract finds in a document: a PDF's, a workbook's, a
+ * deck's, or an HTML document's `<table>`s (a fetched page, rendered Markdown,
+ * a live page's content).
+ *
+ * @param document - The document.
+ * @param step - The extract step.
+ * @param scope - Where its selector renders.
+ * @returns The tables.
+ */
+export declare function tablesIn(document: ScopeDocument, step: ExtractStep, scope: ExtractionScope): unknown[];
+//# sourceMappingURL=extract-from-document.use-case.d.ts.map

package/dist/api-steps/index.d.ts

@@ -0,0 +1,4 @@
+export { ApiStepRunner } from './run-api-step.use-case.js';
+export { extractFromDocument, renderSelector, tablesIn } from './extract-from-document.use-case.js';
+export { sendRequest, documentValue } from './send-request.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/api-steps/run-api-step.use-case.d.ts

@@ -0,0 +1,20 @@
+import type { EventBus } from '../crawl-events/index.js';
+import type { ExtractionScope } from '../extraction-scope/index.js';
+import type { HttpSender } from '../http-session/index.js';
+import type { InputRecipe, PaginateNext, Step } from '../recipe-schema/index.js';
+import { RunGate } from '../step-flow/index.js';
+import type { NextPageResult, StepRunner } from '../step-flow/index.js';
+/** Runs api-mode leaf steps against an HTTP sender. */
+export declare class ApiStepRunner implements StepRunner {
+    private readonly client;
+    private readonly recipe;
+    private readonly events;
+    private readonly gate;
+    constructor(client: HttpSender & {
+        dispose?: () => Promise<void>;
+    }, recipe: InputRecipe, events: EventBus, gate?: RunGate);
+    runLeaf(step: Step, scope: ExtractionScope): Promise<void>;
+    nextPage(next: PaginateNext, scope: ExtractionScope): Promise<NextPageResult>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=run-api-step.use-case.d.ts.map

package/dist/api-steps/send-request.use-case.d.ts

@@ -0,0 +1,23 @@
+import type { EventBus } from '../crawl-events/index.js';
+import type { ExtractionScope } from '../extraction-scope/index.js';
+import type { HttpBody, HttpSender } from '../http-session/index.js';
+import type { InputRecipe, RequestStep } from '../recipe-schema/index.js';
+import type { RunGate } from '../step-flow/index.js';
+/**
+ * Sends a `request` step: renders its templates, waits for the gate's throttle,
+ * sends (again, after a pause, while it fails in passing: `limits.retry`),
+ * checks the response against the recipe's block rule, then binds it as the
+ * scope's current document (and under the step id).
+ *
+ * @param step - The request step.
+ * @param scope - The scope to render in and bind into.
+ * @param client - The HTTP sender.
+ * @param recipe - The recipe: its limits, block rule and id.
+ * @param gate - Spaces request starts by `delayMs`.
+ * @param events - Where to report the visit.
+ * @throws BlockedError when the response is a block, or a captcha page under `session.captcha`; HttpError for any other 4xx/5xx.
+ */
+export declare function sendRequest(step: RequestStep, scope: ExtractionScope, client: HttpSender, recipe: InputRecipe, gate: RunGate, events: EventBus): Promise<void>;
+/** What a step id holds for a document: parsed JSON, the read PDF, workbook or deck, or the markup / text. */
+export declare function documentValue(body: HttpBody): unknown;
+//# sourceMappingURL=send-request.use-case.d.ts.map

package/dist/browser-session/browser-profile.store.d.ts

@@ -0,0 +1,52 @@
+import type { BrowserSessionConfig } from './browser-session.config.js';
+import { BrowserSession } from './browser.client.js';
+import type { SessionOptions } from './browser.client.js';
+/** A browser profile name: it becomes a directory, so no separators or dots. */
+export declare const BROWSER_PROFILE_NAME: RegExp;
+/**
+ * Browser profiles that persist between runs: each is a directory of a real
+ * browser's user data (cookies, local storage, IndexedDB, cache, service
+ * workers), so a login, a consent choice or a site's trust in a returning
+ * visitor carries over to the next run. The browser equivalent of a user who
+ * never clears their history.
+ *
+ * A profile directory can be open in one browser at a time. Within this
+ * crawler, a second use waits for the first to close; the same owner (one
+ * recipe run reopening after a rotation) takes it over instead. Another
+ * crawler holding it, in this process or another, is reported, not waited
+ * for: a lock file in the profile names the process, and one left by a
+ * process that died is taken over. (Chromium's own profile lock is not
+ * enough: headless builds do not take it.)
+ */
+export declare class BrowserProfiles {
+    readonly directory: string;
+    private readonly config;
+    private readonly held;
+    private readonly waiting;
+    /**
+     * @param directory - Where the profiles live, one subdirectory each.
+     * @param config - The crawler's browser settings (type, binary, headless, timeouts).
+     */
+    constructor(directory: string, config?: BrowserSessionConfig);
+    private take;
+    private free;
+    private launch;
+    /**
+     * The profile's directory.
+     *
+     * @param name - A profile name.
+     * @returns The absolute path.
+     */
+    pathOf(name: string): string;
+    /**
+     * Opens a profile in its own browser, waiting while another run of this
+     * crawler uses it.
+     *
+     * @param name - The profile.
+     * @param options - Proxy, headers, viewport, cookies to add. `storageState` is ignored: the profile has its own.
+     * @param owner - Who opens it; the same owner reopening closes its previous session first.
+     * @returns The session; closing it frees the profile.
+     */
+    open(name: string, options: SessionOptions, owner: object): Promise<BrowserSession>;
+}
+//# sourceMappingURL=browser-profile.store.d.ts.map

package/dist/browser-session/browser-session.config.d.ts

@@ -0,0 +1,21 @@
+/** How the browser is launched. Everything is optional; the default is headless chromium. */
+export interface BrowserSessionConfig {
+    browserType?: 'chromium' | 'firefox' | 'webkit';
+    /** Default `true`. */
+    headless?: boolean;
+    /** Milliseconds added to every action, for watching a crawl. */
+    slowMo?: number;
+    /** A browser binary other than the one `playwright install` fetched. */
+    executablePath?: string;
+    proxy?: {
+        server: string;
+        username?: string;
+        password?: string;
+        bypass?: string;
+    };
+    /** Default navigation and action timeout in milliseconds. */
+    timeoutMs?: number;
+    ignoreHTTPSErrors?: boolean;
+}
+export declare const DEFAULT_BROWSER_CONFIG: Required<Pick<BrowserSessionConfig, 'browserType' | 'headless'>>;
+//# sourceMappingURL=browser-session.config.d.ts.map

package/dist/browser-session/browser.client.d.ts

@@ -0,0 +1,75 @@
+import type { BrowserContext, Page } from 'playwright';
+import type { BrowserSessionConfig } from './browser-session.config.js';
+/** Playwright's storage state: cookies plus per-origin local storage. */
+export type StorageState = Awaited<ReturnType<BrowserContext['storageState']>>;
+/** What a session starts from. */
+export interface SessionOptions {
+    storageState?: StorageState;
+    cookies?: Parameters<BrowserContext['addCookies']>[0];
+    headers?: Record<string, string>;
+    userAgent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** A proxy for this context only; overrides the launch-level `proxy`. */
+    proxy?: {
+        server: string;
+        username?: string;
+        password?: string;
+        bypass?: string;
+    };
+    /** Also accept invalid certificates in this context (a proxy that intercepts HTTPS). */
+    ignoreHTTPSErrors?: boolean;
+    /** Resource types this context never loads (`image`, `font`, `media`...), to save proxy bandwidth. */
+    blockResources?: readonly string[];
+}
+/** One browser context with one page: the unit a recipe runs in. */
+export declare class BrowserSession {
+    readonly context: BrowserContext;
+    readonly page: Page;
+    private readonly closer?;
+    /**
+     * @param context - The browser context.
+     * @param page - Its page.
+     * @param closer - How to end the session; closing the context by default. A remote browser disconnects instead.
+     */
+    constructor(context: BrowserContext, page: Page, closer?: (() => Promise<void>) | undefined);
+    /** The cookies and storage this session holds now, in the shape an HTTP client or a later run can reuse. */
+    storageState(): Promise<StorageState>;
+    close(): Promise<void>;
+}
+/**
+ * What a context gets after it opened: the cookies to add and the resource
+ * types to skip.
+ *
+ * @param context - The context.
+ * @param options - The session options.
+ */
+export declare function applySessionExtras(context: BrowserContext, options: SessionOptions): Promise<void>;
+/** A launched browser; sessions are opened from it and closed independently. */
+export declare class BrowserClient {
+    private readonly browser;
+    private readonly config;
+    static launch(config?: BrowserSessionConfig): Promise<BrowserClient>;
+    /**
+     * A session in a remote browser, over the Chrome DevTools Protocol. The
+     * provider's own context is reused when it offers one (several providers
+     * pin the proxy and fingerprint to it); cookies, headers, blocked resources
+     * and the viewport are applied to it. Closing the session disconnects,
+     * which ends it on the provider's side.
+     *
+     * @param cdp - The endpoint and connection headers.
+     * @param options - What the session starts from. `userAgent` cannot change on an existing context and is ignored.
+     * @param timeoutMs - For the connection and every action.
+     * @returns The session.
+     */
+    static connectOverCDP(cdp: {
+        endpoint: string;
+        headers?: Record<string, string>;
+    }, options?: SessionOptions, timeoutMs?: number): Promise<BrowserSession>;
+    private constructor();
+    newSession(options?: SessionOptions): Promise<BrowserSession>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=browser.client.d.ts.map

package/dist/browser-session/index.d.ts

@@ -0,0 +1,6 @@
+export { BrowserClient, BrowserSession } from './browser.client.js';
+export { BrowserProfiles, BROWSER_PROFILE_NAME } from './browser-profile.store.js';
+export type { StorageState, SessionOptions } from './browser.client.js';
+export { DEFAULT_BROWSER_CONFIG } from './browser-session.config.js';
+export type { BrowserSessionConfig } from './browser-session.config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/captcha/captcha-budget.model.d.ts

@@ -0,0 +1,21 @@
+/** Default solves a recipe run may spend. */
+export declare const DEFAULT_MAX_SOLVES = 10;
+/**
+ * The solves a recipe run may still spend. Every solve costs money: a detector
+ * that matches the wrong element would drain a balance without it. Shared by
+ * every runner of the run, rotations included.
+ */
+export declare class CaptchaBudget {
+    readonly max: number;
+    private used;
+    constructor(max?: number);
+    /** Solves spent so far. */
+    get spent(): number;
+    /**
+     * Spends one solve.
+     *
+     * @returns Whether one was left.
+     */
+    take(): boolean;
+}
+//# sourceMappingURL=captcha-budget.model.d.ts.map

package/dist/captcha/captcha-detection.client.d.ts

@@ -0,0 +1,28 @@
+import type { Page } from 'playwright';
+import type { CaptchaChallenge } from './captcha-solver.contract.js';
+/** The widgets detection looks for when a recipe names none: reCAPTCHA v2, hCaptcha and Turnstile, as a container or as their iframe. */
+export declare const DEFAULT_CAPTCHA_SELECTOR: string;
+/**
+ * The first visible challenge on the page, if any. An element counts only
+ * when visible: sites keep hidden widgets around after a solve, and an
+ * invisible reCAPTCHA shows nothing until it challenges.
+ *
+ * @param page - The live page.
+ * @param selector - Where challenges are; `DEFAULT_CAPTCHA_SELECTOR` when omitted.
+ * @param options - `v3`: also report a reCAPTCHA v3 script (a `captcha` step asks for it; the automatic checks do not, since v3 never blocks a page by itself).
+ * @returns The challenge, or `undefined`.
+ */
+export declare function detectChallenge(page: Page, selector?: string, options?: {
+    v3?: boolean;
+}): Promise<CaptchaChallenge | undefined>;
+/**
+ * Whether the page is clear of challenges, tolerating a page that is
+ * navigating (a solve often submits a form): an evaluation cut short by the
+ * navigation counts as not clear yet.
+ *
+ * @param page - The live page.
+ * @param selector - Where challenges are.
+ * @returns Whether no challenge is visible.
+ */
+export declare function isClear(page: Page, selector: string): Promise<boolean>;
+//# sourceMappingURL=captcha-detection.client.d.ts.map