@opencraw/core 0.1.2 → 0.1.4

package/dist/captcha/captcha-guard.use-case.d.ts

@@ -0,0 +1,64 @@
+import type { Page } from 'playwright';
+import type { AccessLease } from '../access/index.js';
+import type { EventBus } from '../crawl-events/index.js';
+import type { CaptchaStep, InputRecipe } from '../recipe-schema/index.js';
+import type { BlockedError } from '../step-flow/index.js';
+import type { CaptchaBudget } from './captcha-budget.model.js';
+import type { CaptchaSolverRegistry } from './captcha-solver-registry.store.js';
+export interface CaptchaGuardOptions {
+    recipe: InputRecipe;
+    events: EventBus;
+    solvers: CaptchaSolverRegistry;
+    /** Shared by every runner of the recipe run, rotations and the bootstrap included. */
+    budget: CaptchaBudget;
+    /** The access the page goes through, handed to solvers. */
+    lease?: AccessLease;
+}
+/**
+ * Where a web runner meets captchas: after each navigation, click and key
+ * press (`session.captcha`), on a block page (`onBlock.solve`), and at a
+ * `captcha` step.
+ */
+export declare class CaptchaGuard {
+    private readonly options;
+    constructor(options: CaptchaGuardOptions);
+    private settings;
+    private solve;
+    /** Whether a block page is searched for a challenge before the block counts. */
+    get solvesBlocks(): boolean;
+    /**
+     * The automatic check: with `session.captcha`, solves the challenge the page
+     * shows, if any. Without it, nothing is looked for.
+     *
+     * @param page - The live page.
+     * @throws CaptchaError when the challenge could not be solved.
+     */
+    check(page: Page): Promise<void>;
+    /**
+     * A block page under `onBlock.solve`: solves the challenge it shows. A block
+     * without a challenge stays a block.
+     *
+     * @param page - The page showing the block.
+     * @param blocked - The block.
+     * @throws BlockedError (`blocked`) when the page shows no challenge; CaptchaError when it could not be solved.
+     */
+    solveBlock(page: Page, blocked: BlockedError): Promise<void>;
+    /**
+     * A `captcha` step: solves the challenge the page shows, reCAPTCHA v3
+     * included; a page without one is fine.
+     *
+     * @param page - The live page.
+     * @param step - The step.
+     * @throws CaptchaError when the challenge could not be solved.
+     */
+    step(page: Page, step: CaptchaStep): Promise<void>;
+}
+/**
+ * Every solver name a recipe uses (`session.captcha` and its `captcha`
+ * steps, the bootstrap's included), to check them before the run starts.
+ *
+ * @param recipe - The input recipe.
+ * @returns The names, without repeats.
+ */
+export declare function captchaSolverNames(recipe: InputRecipe): string[];
+//# sourceMappingURL=captcha-guard.use-case.d.ts.map

package/dist/captcha/captcha-solver-registry.store.d.ts

@@ -0,0 +1,19 @@
+import type { CaptchaSolver } from './captcha-solver.contract.js';
+/** The captcha solvers a crawler was given, by name. */
+export declare class CaptchaSolverRegistry {
+    private readonly solvers;
+    private readonly order;
+    constructor(solvers?: readonly CaptchaSolver[]);
+    /** The registered names. */
+    get names(): string[];
+    has(name: string): boolean;
+    /**
+     * The solver of that name.
+     *
+     * @param name - As a recipe names it.
+     * @returns The solver.
+     * @throws Error naming what is registered when it is not.
+     */
+    resolve(name: string): CaptchaSolver;
+}
+//# sourceMappingURL=captcha-solver-registry.store.d.ts.map

package/dist/captcha/captcha-solver.contract.d.ts

@@ -0,0 +1,47 @@
+import type { Page } from 'playwright';
+import type { AccessLease } from '../access/index.js';
+/** The kinds of challenge detection tells apart. */
+export type CaptchaKind = 'recaptcha-v2' | 'recaptcha-v3' | 'hcaptcha' | 'turnstile' | 'image' | 'unknown';
+/** What the engine found on the page: enough for a token service, or for a solver that works on the page itself. */
+export interface CaptchaChallenge {
+    kind: CaptchaKind;
+    /** The page the challenge is on. */
+    url: string;
+    /** The widget's site key (`data-sitekey`, or the `k` / `sitekey` of its iframe), when it has one. */
+    siteKey?: string;
+    /** The widget's action (`data-action`), when it declares one. */
+    action?: string;
+    /** A Playwright selector for the widget, or for the image of an image captcha. */
+    selector?: string;
+}
+export type CaptchaLog = (level: 'debug' | 'info' | 'warn' | 'error', message: string, meta?: Record<string, unknown>) => void;
+/** What a solver gets besides the challenge. */
+export interface CaptchaContext {
+    /** The live page: the solver may inject a token, fill a field, click. */
+    page: Page;
+    /** The access in use: token services often need the same IP (proxy) as the browser. */
+    lease?: AccessLease;
+    /** 1, 2, … within one solve loop. */
+    attempt: number;
+    /** Aborted when the engine's timeout for this attempt runs out. */
+    signal: AbortSignal;
+    log: CaptchaLog;
+}
+/** A solver's report. The engine checks it: `solved` is a claim until the page confirms it. */
+export type CaptchaOutcome = {
+    status: 'solved';
+} | {
+    status: 'failed';
+    reason: string;
+};
+/**
+ * A captcha solver: solves a challenge and applies the answer on the page
+ * (injects a token and calls the widget's callback, types an image's text,
+ * submits). Detection, verification, retries, rotation and the budget are the
+ * engine's.
+ */
+export interface CaptchaSolver {
+    name: string;
+    solve: (challenge: CaptchaChallenge, context: CaptchaContext) => Promise<CaptchaOutcome> | CaptchaOutcome;
+}
+//# sourceMappingURL=captcha-solver.contract.d.ts.map

package/dist/captcha/captcha.error.d.ts

@@ -0,0 +1,13 @@
+import { BlockedError } from '../step-flow/index.js';
+/**
+ * A challenge the engine could not get past: the solver failed, the page did
+ * not confirm it, or the budget ran out. It is a block, so a recipe with
+ * `onBlock.rotate` retries the step on a new access lease (a new IP often
+ * means an easier challenge, or none), then the step's error policy applies.
+ */
+export declare class CaptchaError extends BlockedError {
+    readonly kind: string;
+    readonly attempts: number;
+    constructor(url: string, kind: string, attempts: number, reason: string);
+}
+//# sourceMappingURL=captcha.error.d.ts.map

package/dist/captcha/index.d.ts

@@ -0,0 +1,10 @@
+export type { CaptchaSolver, CaptchaChallenge, CaptchaContext, CaptchaOutcome, CaptchaKind, CaptchaLog } from './captcha-solver.contract.js';
+export { CaptchaError } from './captcha.error.js';
+export { CaptchaSolverRegistry } from './captcha-solver-registry.store.js';
+export { CaptchaBudget, DEFAULT_MAX_SOLVES } from './captcha-budget.model.js';
+export { DEFAULT_CAPTCHA_SELECTOR, detectChallenge } from './captcha-detection.client.js';
+export { resolveCaptcha, DEFAULT_CAPTCHA_ATTEMPTS, DEFAULT_CAPTCHA_TIMEOUT_MS } from './resolve-captcha.use-case.js';
+export type { CaptchaAttemptPlan } from './resolve-captcha.use-case.js';
+export { CaptchaGuard, captchaSolverNames } from './captcha-guard.use-case.js';
+export type { CaptchaGuardOptions } from './captcha-guard.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/captcha/resolve-captcha.use-case.d.ts

@@ -0,0 +1,40 @@
+import type { Page } from 'playwright';
+import type { AccessLease } from '../access/index.js';
+import type { EventBus } from '../crawl-events/index.js';
+import type { CaptchaCheck } from '../recipe-schema/index.js';
+import type { CaptchaBudget } from './captcha-budget.model.js';
+import type { CaptchaChallenge, CaptchaSolver } from './captcha-solver.contract.js';
+/** Default solves tried per challenge. */
+export declare const DEFAULT_CAPTCHA_ATTEMPTS = 3;
+/** Default time one solve may take: token services take 10 to 60 seconds. */
+export declare const DEFAULT_CAPTCHA_TIMEOUT_MS = 120000;
+/** One challenge to get past, and everything the loop needs for it. */
+export interface CaptchaAttemptPlan {
+    recipeId: string;
+    page: Page;
+    challenge: CaptchaChallenge;
+    solver: CaptchaSolver;
+    /** Where challenges are, to re-detect and to confirm one is gone. */
+    selector: string;
+    verify?: CaptchaCheck;
+    attempts: number;
+    timeoutMs: number;
+    budget: CaptchaBudget;
+    events: EventBus;
+    lease?: AccessLease;
+}
+/**
+ * Gets past one challenge: asks the solver, then checks the page (a solver's
+ * `solved` is a claim; the challenge must be gone and/or the `verify` element
+ * must appear), and tries again with what the page shows next, up to
+ * `attempts`. Each try spends one solve of the run's budget.
+ *
+ * A failed try re-detects the challenge (a widget re-renders after a wrong
+ * answer). When it is gone without the page confirming, the page is reloaded
+ * for a fresh one; when a reload shows none, there is nothing left to solve.
+ *
+ * @param plan - The challenge, the solver and the limits.
+ * @throws CaptchaError when every try failed, or the budget is spent.
+ */
+export declare function resolveCaptcha(plan: CaptchaAttemptPlan): Promise<void>;
+//# sourceMappingURL=resolve-captcha.use-case.d.ts.map

package/dist/crawl-events/crawl-event.contract.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Everything a crawl reports while it runs. Payloads are structural on purpose:
+ * this slice is a leaf, so it declares its own shapes instead of importing the
+ * richer record and error types from the slices above it.
+ */
+interface Base {
+    at: string;
+    recipeId: string;
+}
+export type CrawlEvent = (Base & {
+    type: 'recipe:start';
+    mode: 'web' | 'api';
+}) | (Base & {
+    type: 'recipe:finish';
+    emitted: number;
+    rejected: number;
+    duplicates: number;
+    skipped: number;
+    stepsSkipped?: number;
+    pages: number;
+    durationMs: number;
+    error?: string;
+}) | 
+/** `status` is the HTTP status of the navigation or request, when there was a response. */
+(Base & {
+    type: 'page:visit';
+    url: string;
+    number: number;
+    status?: number;
+}) | 
+/** How a recipe run reaches the network. Never carries credentials. */
+(Base & {
+    type: 'access:lease';
+    profile: string;
+    kind: string;
+    server?: string;
+    session?: string;
+}) | 
+/** A response matched the recipe's block rule. */
+(Base & {
+    type: 'access:blocked';
+    url: string;
+    status: number;
+    reason: string;
+}) | 
+/** The run gave up its access lease after a block and is taking a new one. */
+(Base & {
+    type: 'access:rotate';
+    attempt: number;
+    reason: string;
+}) | 
+/** A request failed in passing (a dropped connection, a 503, a 429) and is sent again after `delayMs`. */
+(Base & {
+    type: 'request:retry';
+    url: string;
+    attempt: number;
+    reason: string;
+    delayMs: number;
+}) | 
+/** A captcha challenge is on the page. */
+(Base & {
+    type: 'captcha:detected';
+    url: string;
+    kind: string;
+    siteKey?: string;
+}) | 
+/** A solver is trying (`attempt` counts from 1 per challenge). */
+(Base & {
+    type: 'captcha:solve';
+    url: string;
+    kind: string;
+    solver: string;
+    attempt: number;
+}) | 
+/** The page confirmed the solve. */
+(Base & {
+    type: 'captcha:solved';
+    url: string;
+    kind: string;
+    solver: string;
+    attempt: number;
+    durationMs: number;
+}) | 
+/** The solver failed, timed out, or the page still shows the challenge. */
+(Base & {
+    type: 'captcha:failed';
+    url: string;
+    kind: string;
+    solver: string;
+    attempt: number;
+    reason: string;
+}) | 
+/** A challenge was left unsolved: the run spent its `maxSolves`. */
+(Base & {
+    type: 'captcha:budget';
+    url: string;
+    kind: string;
+    max: number;
+}) | (Base & {
+    type: 'step:start';
+    stepType: string;
+    stepId?: string;
+    path: string;
+}) | (Base & {
+    type: 'step:finish';
+    stepType: string;
+    stepId?: string;
+    path: string;
+    durationMs: number;
+}) | (Base & {
+    type: 'step:retry';
+    stepType: string;
+    stepId?: string;
+    path: string;
+    attempt: number;
+    error: string;
+}) | (Base & {
+    type: 'step:skip';
+    stepType: string;
+    stepId?: string;
+    path: string;
+    error: string;
+}) | (Base & {
+    type: 'step:branch';
+    path: string;
+    branch: 'then' | 'else';
+}) | 
+/** `scope` (the snapshot the record was mapped from) is present only under `CrawlOptions.debug`. */
+(Base & {
+    type: 'record:emit';
+    url: string;
+    key: string | null;
+    data: Record<string, unknown>;
+    scope?: Record<string, unknown>;
+}) | (Base & {
+    type: 'record:reject';
+    url: string;
+    field: string;
+    reason: string;
+    scope?: Record<string, unknown>;
+}) | (Base & {
+    type: 'record:duplicate';
+    url: string;
+    key: string;
+}) | 
+/** A resumed run found the key already in the sink. */
+(Base & {
+    type: 'record:skipped';
+    url: string;
+    key: string;
+}) | (Base & {
+    type: 'warning';
+    message: string;
+    meta?: Record<string, unknown>;
+}) | (Base & {
+    type: 'error';
+    message: string;
+    meta?: Record<string, unknown>;
+});
+export type CrawlEventType = CrawlEvent['type'];
+/** An event without its timestamp; the bus stamps `at`. */
+export type CrawlEventInput = {
+    [K in CrawlEventType]: Omit<Extract<CrawlEvent, {
+        type: K;
+    }>, 'at'>;
+}[CrawlEventType];
+export type CrawlListener = (event: CrawlEvent) => void;
+export {};
+//# sourceMappingURL=crawl-event.contract.d.ts.map

package/dist/crawl-events/event-bus.store.d.ts

@@ -0,0 +1,10 @@
+import type { CrawlEventInput, CrawlListener } from './crawl-event.contract.js';
+/** Fans crawl events out to listeners. A listener that throws never breaks the crawl. */
+export declare class EventBus {
+    private readonly listeners;
+    constructor(listener?: CrawlListener);
+    /** @returns A function that removes the listener. */
+    subscribe(listener: CrawlListener): () => void;
+    emit(input: CrawlEventInput): void;
+}
+//# sourceMappingURL=event-bus.store.d.ts.map

package/dist/crawl-events/index.d.ts

@@ -0,0 +1,4 @@
+export type { CrawlEvent, CrawlEventType, CrawlEventInput, CrawlListener } from './crawl-event.contract.js';
+export { EventBus } from './event-bus.store.js';
+export { traceLine, depthOf } from './trace-line.mapper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/crawl-events/trace-line.mapper.d.ts

@@ -0,0 +1,14 @@
+import type { CrawlEvent } from './crawl-event.contract.js';
+/**
+ * One line of a crawl trace: the route a recipe takes (pages visited, steps
+ * run, records produced, policies fired), indented by how deep in the step
+ * tree the event happened. `step:start` yields nothing; `step:finish` carries
+ * the duration, so every step prints once.
+ *
+ * @param event - Any crawl event.
+ * @returns The line, or `undefined` for events a trace does not show.
+ */
+export declare function traceLine(event: CrawlEvent): string | undefined;
+/** How deep a step path such as `steps.8.steps.2` or `steps.1.else.0` sits: one level per nested `steps` or `else`. */
+export declare function depthOf(path: string): number;
+//# sourceMappingURL=trace-line.mapper.d.ts.map

package/dist/crawl-execution/bootstrap-session.use-case.d.ts

@@ -0,0 +1,79 @@
+import type { AccessLease } from '../access/index.js';
+import type { BrowserClient, BrowserProfiles, BrowserSession, SessionOptions, StorageState } from '../browser-session/index.js';
+import type { CaptchaGuard } from '../captcha/index.js';
+import type { EventBus } from '../crawl-events/index.js';
+import type { HookRegistry } from '../hooks/index.js';
+import type { InputRecipe } from '../recipe-schema/index.js';
+import type { HostThrottle } from '../step-flow/index.js';
+export interface BootstrapDependencies {
+    /** Launches (or returns) the shared browser; only called when a browser is needed. */
+    browser: () => Promise<BrowserClient>;
+    hooks: HookRegistry;
+    events: EventBus;
+    storageStateDir?: string;
+    /** The crawler's per-site throttle: the bootstrap's pages count too. */
+    hosts?: HostThrottle;
+    /** The runner's persistent browser profiles, for `session.browserProfile`. */
+    profiles?: BrowserProfiles;
+}
+/**
+ * The session options an access lease contributes: its proxy, TLS leniency,
+ * blocked resources, and its headers under the recipe's own.
+ *
+ * @param lease - The lease, if any.
+ * @param headers - The recipe's `session.headers`.
+ * @returns Options for `BrowserClient.newSession`.
+ */
+export declare function accessOptions(lease: AccessLease | undefined, headers: Record<string, string> | undefined): Pick<SessionOptions, 'proxy' | 'ignoreHTTPSErrors' | 'blockResources' | 'headers'>;
+/**
+ * The storage state a recipe starts from: a saved file, else what its
+ * `session.bootstrap` steps produce in a browser (filtered by `keep`, saved
+ * when asked), else nothing.
+ *
+ * The bootstrap runs through the same access lease as the crawl that follows,
+ * so a login and the requests that use its cookies come from one IP.
+ *
+ * With `session.browserProfile`, the bootstrap runs in that profile, and
+ * without a bootstrap the profile's own cookies and storage are the state: an
+ * api recipe picks up a login a browser left in the profile.
+ *
+ * @param recipe - The input recipe.
+ * @param deps - Browser, hooks, events.
+ * @param lease - The recipe run's access; direct when omitted.
+ * @param captcha - Solves the bootstrap's captchas (a login form's).
+ * @param owner - The recipe run, which a browser profile is held by.
+ * @returns The state, or `undefined` when the recipe declares none.
+ */
+export declare function resolveStorageState(recipe: InputRecipe, deps: BootstrapDependencies, lease?: AccessLease, captcha?: CaptchaGuard, owner?: object): Promise<StorageState | undefined>;
+/**
+ * Opens the recipe's `session.browserProfile` with its session options and
+ * the lease's proxy.
+ *
+ * @param recipe - A recipe with `session.browserProfile`.
+ * @param deps - For `profiles`.
+ * @param lease - The access lease.
+ * @param owner - The recipe run.
+ * @returns The session in the profile.
+ */
+export declare function openBrowserProfile(recipe: InputRecipe, deps: Pick<BootstrapDependencies, 'profiles'>, lease: AccessLease | undefined, owner: object): Promise<BrowserSession>;
+/**
+ * The storage state saved by an earlier bootstrap (`session.storageStatePath`), if the recipe names one.
+ *
+ * @param recipe - The input recipe.
+ * @param deps - For `storageStateDir`.
+ * @returns The state, or `undefined`.
+ */
+export declare function readSavedState(recipe: InputRecipe, deps: Pick<BootstrapDependencies, 'storageStateDir'>): Promise<StorageState | undefined>;
+/**
+ * Runs a recipe's bootstrap steps in a browser session, then captures what
+ * `keep` lists and saves it when `saveTo` asks. The session stays open: a
+ * remote browser keeps it for the crawl, a local one is closed by the caller.
+ *
+ * @param recipe - An input recipe with `session.bootstrap`.
+ * @param browserSession - Where the steps run.
+ * @param deps - Hooks, events, `storageStateDir`.
+ * @param captcha - Solves the bootstrap's captchas.
+ * @returns The kept state.
+ */
+export declare function runBootstrap(recipe: InputRecipe, browserSession: BrowserSession, deps: Omit<BootstrapDependencies, 'browser'>, captcha?: CaptchaGuard): Promise<StorageState>;
+//# sourceMappingURL=bootstrap-session.use-case.d.ts.map

package/dist/crawl-execution/crawl-options.config.d.ts

@@ -0,0 +1,67 @@
+import type { AccessConfig, AccessPlugin } from '../access/index.js';
+import type { BrowserSessionConfig } from '../browser-session/index.js';
+import type { CaptchaSolver } from '../captcha/index.js';
+import type { CrawlListener } from '../crawl-events/index.js';
+import type { HookMap } from '../hooks/index.js';
+import type { ThrottleConfig } from '../step-flow/index.js';
+import type { RetryRule } from '../recipe-schema/index.js';
+import type { DedupeScope, RecordSink } from '../record-sink/index.js';
+/** How a crawler is created. Everything is optional. */
+export interface CrawlOptions {
+    /** Browser launch settings for web recipes and bootstraps. */
+    browser?: BrowserSessionConfig;
+    /** Handlers recipes reference by name. */
+    hooks?: HookMap;
+    /** Where records go; default: kept in memory and returned in the report. */
+    sink?: RecordSink;
+    onEvent?: CrawlListener;
+    /** Default `run`: a key seen once is dropped for the rest of the run. */
+    dedupe?: DedupeScope;
+    /**
+     * How many input recipes of a set run at once; default 1, one after
+     * another. Each has its own browser context or HTTP session; the browser,
+     * the sink and the per-site `throttle` are shared.
+     */
+    parallel?: number;
+    /** Whether a failed input recipe stops the run; default `continue`. */
+    onRecipeError?: 'continue' | 'stop';
+    /** Base directory for relative `storageStatePath` and `saveTo` values. */
+    storageStateDir?: string;
+    /**
+     * Where `session.browserProfile` profiles live, one directory each. Default:
+     * `.opencraw/profiles` under `storageStateDir` (or the working directory).
+     */
+    profilesDir?: string;
+    /**
+     * Skip records whose key the sink already has (`sink.has`), reporting them as
+     * `skipped`. Needs a sink that can answer, such as `jsonLinesSink(path, { append: true })`.
+     */
+    resume?: boolean;
+    /** Attach the scope snapshot to `record:emit` and `record:reject` events, for inspecting what a mapping saw. */
+    debug?: boolean;
+    /**
+     * Where traffic goes: named proxy profiles (presets for common providers,
+     * credentials as `{{env.NAME}}`) and the default one. Recipes pick a profile
+     * with `session.access.profile`. Without it every recipe goes direct.
+     */
+    access?: AccessConfig;
+    /**
+     * How gently each site is crawled, across every recipe this crawler runs:
+     * `delayMs` between request starts and `concurrency` requests in flight,
+     * per site, with `domains` for site-specific rules. Defaults to
+     * `access.throttle`; without either, only each recipe's `limits` apply.
+     */
+    throttle?: ThrottleConfig;
+    /**
+     * How a request that fails in passing (a dropped connection, a timeout, a
+     * 503, a 429) is sent again, for recipes whose `limits.retry` says
+     * nothing: `{ attempts?, backoffMs?, maxDelayMs?, statuses? }`. Default:
+     * three tries, one then two seconds apart, `Retry-After` honoured.
+     */
+    retry?: RetryRule;
+    /** Plugins `{ kind: 'plugin', name }` profiles refer to. */
+    accessPlugins?: AccessPlugin[];
+    /** Solvers recipes name in `session.captcha.solver` and `captcha` steps. */
+    captchaSolvers?: CaptchaSolver[];
+}
+//# sourceMappingURL=crawl-options.config.d.ts.map

package/dist/crawl-execution/crawl-report.model.d.ts

@@ -0,0 +1,33 @@
+import type { SinkSummary } from '../record-sink/index.js';
+/** What one input recipe did. */
+export interface RecipeReport {
+    recipeId: string;
+    mode: 'web' | 'api';
+    emitted: number;
+    rejected: number;
+    duplicates: number;
+    /** Records a resumed run found in the sink already. */
+    skipped: number;
+    /** Steps whose `onError: skip` policy swallowed a failure: a check that found nothing, a value a page lacked. */
+    stepsSkipped: number;
+    pages: number;
+    durationMs: number;
+    /** Captcha challenges met, solved, and solve attempts that failed; present when any was met. */
+    captchas?: {
+        detected: number;
+        solved: number;
+        failed: number;
+    };
+    /** Set when the recipe stopped on a failure. */
+    error?: string;
+}
+/** What a whole run did. */
+export interface CrawlReport {
+    outputId: string;
+    recipes: RecipeReport[];
+    /** Records written to the sink across every recipe. */
+    records: number;
+    sink: SinkSummary;
+    durationMs: number;
+}
+//# sourceMappingURL=crawl-report.model.d.ts.map

package/dist/crawl-execution/create-crawler.use-case.d.ts

@@ -0,0 +1,20 @@
+import type { RecipeSet } from '../recipe-loading/index.js';
+import type { CrawlOptions } from './crawl-options.config.js';
+import type { CrawlReport } from './crawl-report.model.js';
+/** A configured engine: run recipe sets, then close it to release the browser. */
+export interface Crawler {
+    run: (set: RecipeSet) => Promise<CrawlReport>;
+    /** Closes the browser if one was launched. Safe to call more than once. */
+    close: () => Promise<void>;
+}
+/**
+ * Creates a crawler. The browser is launched lazily, on the first recipe or
+ * bootstrap that needs it, and shared by every run until `close`.
+ *
+ * @param options - Hooks, sink, events, browser settings, access, captcha solvers, policies.
+ * @returns The crawler.
+ * @throws AccessConfigError when the access config cannot work.
+ * @throws Error when two captcha solvers share a name.
+ */
+export declare function createCrawler(options?: CrawlOptions): Crawler;
+//# sourceMappingURL=create-crawler.use-case.d.ts.map

package/dist/crawl-execution/index.d.ts

@@ -0,0 +1,8 @@
+export { createCrawler } from './create-crawler.use-case.js';
+export type { Crawler } from './create-crawler.use-case.js';
+export type { CrawlOptions } from './crawl-options.config.js';
+export type { CrawlReport, RecipeReport } from './crawl-report.model.js';
+export { runInputRecipe } from './run-input-recipe.use-case.js';
+export { runCrawl } from './run-crawl.use-case.js';
+export { resolveStorageState, readSavedState, runBootstrap } from './bootstrap-session.use-case.js';
+//# sourceMappingURL=index.d.ts.map