@opencraw/core 0.1.0

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

@@ -0,0 +1,55 @@
+import type { AccessLease } from '../access/index.js';
+import type { BrowserClient, BrowserSession, SessionOptions, StorageState } from '../browser-session/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';
+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 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.
+ *
+ * @param recipe - The input recipe.
+ * @param deps - Browser, hooks, events.
+ * @param lease - The recipe run's access; direct when omitted.
+ * @returns The state, or `undefined` when the recipe declares none.
+ */
+export declare function resolveStorageState(recipe: InputRecipe, deps: BootstrapDependencies, lease?: AccessLease): Promise<StorageState | undefined>;
+/**
+ * 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`.
+ * @returns The kept state.
+ */
+export declare function runBootstrap(recipe: InputRecipe, browserSession: BrowserSession, deps: Omit<BootstrapDependencies, 'browser'>): Promise<StorageState>;
+//# sourceMappingURL=bootstrap-session.use-case.d.ts.map

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

@@ -0,0 +1,37 @@
+import type { AccessConfig, AccessPlugin } from '../access/index.js';
+import type { BrowserSessionConfig } from '../browser-session/index.js';
+import type { CrawlListener } from '../crawl-events/index.js';
+import type { HookMap } from '../hooks/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;
+    /** Whether a failed input recipe stops the run; default `continue`. */
+    onRecipeError?: 'continue' | 'stop';
+    /** Base directory for relative `storageStatePath` and `saveTo` values. */
+    storageStateDir?: 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;
+    /** Plugins `{ kind: 'plugin', name }` profiles refer to. */
+    accessPlugins?: AccessPlugin[];
+}
+//# sourceMappingURL=crawl-options.config.d.ts.map

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

@@ -0,0 +1,25 @@
+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;
+    pages: number;
+    durationMs: 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/src/crawl-execution/create-crawler.use-case.d.ts

@@ -0,0 +1,19 @@
+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, policies.
+ * @returns The crawler.
+ * @throws AccessConfigError when the access config cannot work.
+ */
+export declare function createCrawler(options?: CrawlOptions): Crawler;
+//# sourceMappingURL=create-crawler.use-case.d.ts.map

package/dist/src/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

package/dist/src/crawl-execution/rotating-runner.use-case.d.ts

@@ -0,0 +1,57 @@
+import type { AccessLease } from '../access/index.js';
+import type { EventBus } from '../crawl-events/index.js';
+import type { ExtractionScope, LiveElement } from '../extraction-scope/index.js';
+import type { InputRecipe, PaginateNext, Step } from '../recipe-schema/index.js';
+import { BlockedError } from '../step-flow/index.js';
+import type { NextPageResult, StepRunner } from '../step-flow/index.js';
+/** A runner and the access lease it was opened with. */
+export interface LeasedRunner {
+    runner: StepRunner;
+    lease: AccessLease;
+}
+export interface RotatingRunnerOptions {
+    recipe: InputRecipe;
+    events: EventBus;
+    /** How many rotations the run may use; 0 disables rotation. */
+    maxRotations: number;
+    /** Opens a runner on a fresh lease: attempt 1 first, then 2, 3... */
+    open: (attempt: number) => Promise<LeasedRunner>;
+}
+/**
+ * The runner a recipe run uses. It delegates to a runner opened on an access
+ * lease, reports every block as an `access:blocked` event and, when the recipe
+ * allows it, rotates: takes a new lease, opens a new runner on it (re-running
+ * the bootstrap) and tells the step walk to retry the blocked step.
+ *
+ * Under concurrency several iterations can be blocked by the same lease at
+ * once. Each block remembers the generation of runner that produced it, so
+ * only the first one rotates; the rest just retry on the new runner. Replaced
+ * runners are kept until the run ends, because other iterations may still have
+ * requests in flight on them.
+ */
+export declare class RotatingRunner implements StepRunner {
+    private readonly options;
+    /**
+     * Opens the first runner.
+     *
+     * @param options - The recipe, events, rotation budget and how to open a runner.
+     * @returns The rotating runner.
+     */
+    static open(options: RotatingRunnerOptions): Promise<RotatingRunner>;
+    private current;
+    private readonly retired;
+    private readonly blockedAt;
+    private generation;
+    private rotations;
+    private rotating;
+    private constructor();
+    private get inner();
+    private swap;
+    private note;
+    runLeaf(step: Step, scope: ExtractionScope): Promise<void>;
+    nextPage(next: PaginateNext, scope: ExtractionScope): Promise<NextPageResult>;
+    elements(selector: string, scope: ExtractionScope): Promise<LiveElement[]>;
+    rotate(error: BlockedError): Promise<boolean>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=rotating-runner.use-case.d.ts.map

package/dist/src/crawl-execution/run-crawl.use-case.d.ts

@@ -0,0 +1,13 @@
+import type { RecipeSet } from '../recipe-loading/index.js';
+import type { CrawlReport } from './crawl-report.model.js';
+import type { RecipeRunDependencies } from './run-input-recipe.use-case.js';
+/**
+ * Runs every input recipe of a set, one after another, into one sink.
+ *
+ * @param set - The bound recipes.
+ * @param deps - Shared browser, hooks, events, sink and de-duplication.
+ * @param onRecipeError - Whether a failed recipe stops the run.
+ * @returns The report.
+ */
+export declare function runCrawl(set: RecipeSet, deps: RecipeRunDependencies, onRecipeError: 'continue' | 'stop'): Promise<CrawlReport>;
+//# sourceMappingURL=run-crawl.use-case.d.ts.map

package/dist/src/crawl-execution/run-input-recipe.use-case.d.ts

@@ -0,0 +1,40 @@
+import type { AccessBroker } from '../access/index.js';
+import { BrowserClient } from '../browser-session/index.js';
+import type { EventBus } from '../crawl-events/index.js';
+import type { HookRegistry } from '../hooks/index.js';
+import type { InputRecipe, OutputRecipe } from '../recipe-schema/index.js';
+import type { DedupePolicy, RecordSink } from '../record-sink/index.js';
+import type { RecipeReport } from './crawl-report.model.js';
+export interface RecipeRunDependencies {
+    browser: () => Promise<BrowserClient>;
+    hooks: HookRegistry;
+    events: EventBus;
+    sink: RecordSink;
+    dedupe: DedupePolicy;
+    storageStateDir?: string;
+    /** Accept invalid TLS certificates in api mode too (sandbox proxies); mirrors `browser.ignoreHTTPSErrors`. */
+    ignoreHTTPSErrors?: boolean;
+    /** Skip records the sink already has (`sink.has`). */
+    resume?: boolean;
+    /** Attach the scope snapshot to record events. */
+    debug?: boolean;
+    /** Leases each recipe run its network access. */
+    access: AccessBroker;
+}
+/**
+ * Runs one input recipe end to end: session, runner, the step walk, and for
+ * every emitted scope the mapping, de-duplication and the sink. A step or
+ * mapping failure under the `fail` policy ends the recipe and is reported,
+ * never thrown: the caller decides whether the run goes on.
+ *
+ * Emits are serialised through one promise chain whatever the concurrency, so
+ * the sink sees one record at a time and `maxRecords` is exact: once reached,
+ * every later emit returns `stop` before mapping.
+ *
+ * @param input - The input recipe.
+ * @param output - The output recipe it feeds.
+ * @param deps - Shared browser, hooks, events, sink and de-duplication.
+ * @returns What happened.
+ */
+export declare function runInputRecipe(input: InputRecipe, output: OutputRecipe, deps: RecipeRunDependencies): Promise<RecipeReport>;
+//# sourceMappingURL=run-input-recipe.use-case.d.ts.map

package/dist/src/extraction-scope/extraction-scope.model.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The values a recipe has extracted so far, by id, with the lexical nesting the
+ * steps create: `forEach` and `paginate` open a child scope per iteration or page
+ * and drop it afterwards, so nothing from one page leaks into the next. A read
+ * walks up the chain; a write lands in the scope it is made on.
+ *
+ * Page state (the current URL, page number and the document `extract` reads by
+ * default) is scope state too, bound in the innermost scope that navigated.
+ */
+/** A fetched or rendered document a later `extract` can read. */
+export type ScopeDocument = {
+    kind: 'json';
+    data: unknown;
+} | {
+    kind: 'html';
+    html: string;
+} | {
+    kind: 'text';
+    text: string;
+};
+/** Where the crawl is: bound by whichever scope last navigated. */
+export interface PageState {
+    url: string;
+    number: number;
+    document?: ScopeDocument;
+}
+/** Paths a template can read besides ids: `page.url`, `page.number`, `start.url`, `vars.*`. */
+export declare const RESERVED_ROOTS: readonly ["page", "start", "vars"];
+export declare class ExtractionScope {
+    private readonly parent?;
+    private readonly values;
+    private page;
+    constructor(parent?: ExtractionScope | undefined);
+    /** Opens a nested scope; reads fall through to this one. */
+    child(): ExtractionScope;
+    /** Binds a value in this scope, shadowing any parent binding of the same id. */
+    set(id: string, value: unknown): void;
+    /**
+     * Appends to the list the id is bound to, in whichever scope binds it (this
+     * one or a parent), as a new list: a snapshot emitted earlier keeps what it saw.
+     *
+     * @param id - The id of a list bound in this scope or a parent.
+     * @param items - What to add, in order.
+     * @throws Error when no scope binds the id, or it holds something other than a list.
+     */
+    append(id: string, items: readonly unknown[]): void;
+    /** Whether the id is bound here or in a parent. */
+    has(id: string): boolean;
+    /** The nearest binding of the id; `undefined` when unbound. */
+    get(id: string): unknown;
+    /** Records a navigation in this scope. Missing fields inherit from the nearest page state. */
+    setPage(state: Partial<PageState>): void;
+    /** Replaces only the current document, keeping URL and number. */
+    setDocument(document: ScopeDocument): void;
+    /** The nearest page state up the chain, if any scope navigated. */
+    get pageState(): PageState | undefined;
+    /** The document `extract` reads when no `from` is given. */
+    get document(): ScopeDocument | undefined;
+    /**
+     * Every binding visible from here, child shadowing parent, plus `page` as
+     * `{ url, number }`. This is what `emit` hands to the mapping.
+     */
+    snapshot(): Record<string, unknown>;
+    /**
+     * Resolves a dotted path the way templates do: the first segment is an id (or
+     * `page`), the rest walks into the value.
+     *
+     * @param path - A dotted path such as `item.href` or `page.url`.
+     * @returns The value, or `undefined`.
+     */
+    lookup(path: string): unknown;
+}
+//# sourceMappingURL=extraction-scope.model.d.ts.map

package/dist/src/extraction-scope/index.d.ts

@@ -0,0 +1,5 @@
+export { ExtractionScope, RESERVED_ROOTS } from './extraction-scope.model.js';
+export type { PageState, ScopeDocument } from './extraction-scope.model.js';
+export { isLiveElement } from './live-element.model.js';
+export type { LiveElement } from './live-element.model.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/extraction-scope/live-element.model.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A snapshot of one element a `forEach` over `selector` iterates: what it held
+ * when the loop started, plus where to find it again. The engine never keeps a
+ * handle to the element itself: `selector` and `index` re-resolve it on every
+ * use, so a re-render between iterations does not break the loop.
+ */
+export interface LiveElement {
+    /** The selector the loop matched, already rendered. */
+    selector: string;
+    /** Position among the matches, from 0. */
+    index: number;
+    /** Text content, whitespace collapsed. */
+    text: string;
+    /** Inner HTML. */
+    html: string;
+    /** Every attribute, by name. */
+    attrs: Record<string, string>;
+    /** The `value` of an input, option or select; absent otherwise. */
+    value?: string;
+}
+/**
+ * Whether a value is a live element snapshot (a `target` template rendered to one).
+ *
+ * @param value - Anything a template rendered.
+ * @returns `true` for an object with a `selector` string and an `index` number.
+ */
+export declare function isLiveElement(value: unknown): value is LiveElement;
+//# sourceMappingURL=live-element.model.d.ts.map

package/dist/src/hooks/hook-registry.store.d.ts

@@ -0,0 +1,16 @@
+import type { Hook, HookMap } from './hook.contract.js';
+/** The hooks a crawler was created with, resolved by name at run time. */
+export declare class HookRegistry {
+    private readonly hooks;
+    constructor(hooks?: HookMap);
+    register(name: string, hook: Hook): void;
+    has(name: string): boolean;
+    names(): string[];
+    /**
+     * @param name - The name a recipe used.
+     * @returns The hook.
+     * @throws UnknownHookError when nothing was registered under that name.
+     */
+    resolve(name: string): Hook;
+}
+//# sourceMappingURL=hook-registry.store.d.ts.map

package/dist/src/hooks/hook.contract.d.ts

@@ -0,0 +1,17 @@
+/** Severity of a message a hook logs. Typed here so hooks stay a leaf slice. */
+export type HookLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** What a hook knows about where it runs. */
+export interface HookContext {
+    recipeId: string;
+    /** The extracted values visible at the call site, child scopes shadowing parents. */
+    scope: Record<string, unknown>;
+    log: (level: HookLogLevel, message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * A programmatic handler a recipe references by name, from a `hook` step
+ * (`input` is `undefined`) or a `hook` transform (`input` is the value so far).
+ */
+export type Hook = (input: unknown, args: Record<string, unknown>, context: HookContext) => unknown;
+/** Hooks by the name recipes use. */
+export type HookMap = Record<string, Hook>;
+//# sourceMappingURL=hook.contract.d.ts.map

package/dist/src/hooks/hook.error.d.ts

@@ -0,0 +1,7 @@
+/** A recipe named a hook nothing registered. */
+export declare class UnknownHookError extends Error {
+    readonly hookName: string;
+    readonly name = "UnknownHookError";
+    constructor(hookName: string, known: readonly string[]);
+}
+//# sourceMappingURL=hook.error.d.ts.map

package/dist/src/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export type { Hook, HookMap, HookContext, HookLogLevel } from './hook.contract.js';
+export { HookRegistry } from './hook-registry.store.js';
+export { UnknownHookError } from './hook.error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/http-session/http-response.contract.d.ts

@@ -0,0 +1,44 @@
+import type { BodyKind, HttpMethod } from '../recipe-schema/index.js';
+/** One HTTP request as the api runner sends it, templates already rendered. */
+export interface HttpRequest {
+    method?: HttpMethod;
+    url: string;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    body?: unknown;
+    /** How to read the body; default: from the response content type. */
+    as?: BodyKind;
+    timeoutMs?: number;
+}
+/** A parsed response body. Structurally the same as a scope document, on purpose. */
+export type HttpBody = {
+    kind: 'json';
+    data: unknown;
+} | {
+    kind: 'html';
+    html: string;
+} | {
+    kind: 'text';
+    text: string;
+};
+export interface HttpResponse {
+    status: number;
+    /** The final URL after redirects. */
+    url: string;
+    headers: Record<string, string>;
+    body: HttpBody;
+}
+/** The part of the client the api runner needs; tests fake it. */
+export interface HttpSender {
+    send: (request: HttpRequest) => Promise<HttpResponse>;
+}
+/** A response with a 4xx or 5xx status. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly body: HttpBody;
+    readonly headers: Record<string, string>;
+    readonly name = "HttpError";
+    constructor(status: number, url: string, body: HttpBody, headers?: Record<string, string>);
+}
+//# sourceMappingURL=http-response.contract.d.ts.map

package/dist/src/http-session/http.client.d.ts

@@ -0,0 +1,42 @@
+import type { APIRequestContext } from 'playwright';
+import type { HttpRequest, HttpResponse, HttpSender } from './http-response.contract.js';
+/** Playwright's storage state: cookies plus per-origin local storage. */
+export type StorageState = Awaited<ReturnType<APIRequestContext['storageState']>>;
+export interface HttpClientOptions {
+    /** Cookies and storage captured by a browser session, or loaded from a file. */
+    storageState?: StorageState;
+    headers?: Record<string, string>;
+    userAgent?: string;
+    timeoutMs?: number;
+    ignoreHTTPSErrors?: boolean;
+    /** Send every request through this proxy. */
+    proxy?: {
+        server: string;
+        username?: string;
+        password?: string;
+        bypass?: string;
+    };
+}
+/**
+ * HTTP through Playwright's request context: cookies, redirects and storage
+ * state behave exactly as they do in the browser, so a session captured by a
+ * browser bootstrap can be reused without translation. No browser is launched.
+ */
+export declare class HttpClient implements HttpSender {
+    private readonly context;
+    private readonly timeoutMs;
+    static open(options?: HttpClientOptions): Promise<HttpClient>;
+    private constructor();
+    /**
+     * Sends a request and parses the body.
+     *
+     * @param httpRequest - What to send.
+     * @returns The response.
+     * @throws HttpError for a 4xx or 5xx status.
+     */
+    send(httpRequest: HttpRequest): Promise<HttpResponse>;
+    /** The cookies and storage this context holds now. */
+    storageState(): Promise<StorageState>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=http.client.d.ts.map

package/dist/src/http-session/index.d.ts

@@ -0,0 +1,5 @@
+export { HttpClient } from './http.client.js';
+export type { HttpClientOptions, StorageState } from './http.client.js';
+export { HttpError } from './http-response.contract.js';
+export type { HttpRequest, HttpResponse, HttpBody, HttpSender } from './http-response.contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts

@@ -0,0 +1,24 @@
+export { createCrawler } from './crawl-execution/index.js';
+export { AccessBroker, AccessConfigError, ACCESS_PRESETS, loadAccessConfig, accessConfigSchema, accessConfigJsonSchema } from './access/index.js';
+export type { AccessConfig, AccessProfile, AccessPlugin, AccessLease, LeaseRequest, PluginLeaseRequest, ProxySettings, AccessPreset } from './access/index.js';
+export type { Crawler, CrawlOptions, CrawlReport, RecipeReport } from './crawl-execution/index.js';
+export { loadRecipeSet, loadRecipes, readRecipeSource, bindRecipeSet, RecipeSet, RecipeBindingError, validateBinding } from './recipe-loading/index.js';
+export type { RecipeSetSource, RecipeSource, RecipeBytes, RecipeDocument, BindingIssue } from './recipe-loading/index.js';
+export { parseInputRecipe, parseOutputRecipe, RecipeValidationError, inputRecipeJsonSchema, outputRecipeJsonSchema, inputRecipeSchema, outputRecipeSchema } from './recipe-schema/index.js';
+export type { InputRecipe, OutputRecipe, FieldSpec, Step, StepType, MappingRule, TransformRule, ErrorPolicy, PaginateNext, SessionSpec, SessionAccess, RecipeIssue } from './recipe-schema/index.js';
+export type { Hook, HookMap, HookContext } from './hooks/index.js';
+export { UnknownHookError } from './hooks/index.js';
+export type { OutputRecord } from './output-mapping/index.js';
+export { RecordRejectedError, MappingFailedError } from './output-mapping/index.js';
+export type { RecordSink, SinkSummary, MemorySink, DedupeScope } from './record-sink/index.js';
+export { memorySink, jsonLinesSink } from './record-sink/index.js';
+export type { CrawlEvent, CrawlListener } from './crawl-events/index.js';
+export { traceLine } from './crawl-events/index.js';
+export type { BrowserSessionConfig, SessionOptions } from './browser-session/index.js';
+export { BrowserClient, BrowserSession } from './browser-session/index.js';
+export { HttpClient, HttpError } from './http-session/index.js';
+export type { HttpClientOptions, HttpRequest, HttpResponse, HttpBody } from './http-session/index.js';
+export { tryParseJson } from './selection/index.js';
+export { StepFailure } from './step-flow/index.js';
+export { TransformError } from './transformation/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/output-mapping/coerce-field.mapper.d.ts

@@ -0,0 +1,19 @@
+import type { FieldSpec } from '../recipe-schema/index.js';
+/** A value that cannot become the field's type. */
+export declare class CoercionError extends Error {
+    readonly path: string;
+    readonly name = "CoercionError";
+    constructor(path: string, reason: string);
+}
+/**
+ * Converts a transformed value into the field's declared type.
+ * `null` and `undefined` pass through: missing-value policies decide about them.
+ *
+ * @param value - The value after its transform chain.
+ * @param field - The output field.
+ * @param path - Where the field is, for messages.
+ * @returns The coerced value.
+ * @throws CoercionError when the conversion is impossible.
+ */
+export declare function coerceValue(value: unknown, field: FieldSpec, path: string): unknown;
+//# sourceMappingURL=coerce-field.mapper.d.ts.map

package/dist/src/output-mapping/generated-field.mapper.d.ts

@@ -0,0 +1,16 @@
+import type { GeneratedValue } from '../recipe-schema/index.js';
+/** What generated fields are produced from. */
+export interface GenerationSource {
+    recipeId: string;
+    url: string;
+    emittedAt: string;
+}
+/**
+ * The engine-supplied value of a generated field.
+ *
+ * @param kind - Which value.
+ * @param source - Where the record came from.
+ * @returns The value.
+ */
+export declare function generatedValue(kind: GeneratedValue, source: GenerationSource): unknown;
+//# sourceMappingURL=generated-field.mapper.d.ts.map

package/dist/src/output-mapping/index.d.ts

@@ -0,0 +1,9 @@
+export { mapRecord } from './map-record.use-case.js';
+export type { MapRecordRequest } from './map-record.use-case.js';
+export type { OutputRecord } from './output-record.model.js';
+export { recordKey } from './output-record.model.js';
+export { RecordRejectedError, MappingFailedError } from './mapping.error.js';
+export { coerceValue, CoercionError } from './coerce-field.mapper.js';
+export { validateField } from './output-field.validator.js';
+export { resolveMissingPolicy, isMissing } from './missing-value.policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/output-mapping/map-record.use-case.d.ts

@@ -0,0 +1,27 @@
+import type { HookRegistry } from '../hooks/index.js';
+import type { InputRecipe, OutputRecipe } from '../recipe-schema/index.js';
+import type { TransformContext } from '../transformation/index.js';
+import type { OutputRecord } from './output-record.model.js';
+/** Everything needed to turn one emitted scope snapshot into a record. */
+export interface MapRecordRequest {
+    snapshot: Record<string, unknown>;
+    input: InputRecipe;
+    output: OutputRecipe;
+    hooks: HookRegistry;
+    /** The page URL at emit time. */
+    url: string;
+    emittedAt?: string;
+    log?: TransformContext['log'];
+}
+/**
+ * Maps an emitted scope snapshot to a validated output record: resolves every
+ * mapping rule, runs its transform chain, fills generated fields, then coerces
+ * and validates each output field and applies the missing-value policy.
+ *
+ * @param request - The snapshot and the recipes.
+ * @returns The record.
+ * @throws RecordRejectedError when a field's policy is `skip-record`.
+ * @throws MappingFailedError when a field's policy is `fail`, or a transform throws.
+ */
+export declare function mapRecord(request: MapRecordRequest): Promise<OutputRecord>;
+//# sourceMappingURL=map-record.use-case.d.ts.map

package/dist/src/output-mapping/mapping.error.d.ts

@@ -0,0 +1,17 @@
+/** A record that does not satisfy its output recipe and is dropped (policy `skip-record`). */
+export declare class RecordRejectedError extends Error {
+    readonly field: string;
+    readonly reason: string;
+    readonly name = "RecordRejectedError";
+    constructor(field: string, reason: string);
+}
+/** A record that does not satisfy its output recipe under policy `fail`: the recipe stops. */
+export declare class MappingFailedError extends Error {
+    readonly field: string;
+    readonly reason: string;
+    readonly name = "MappingFailedError";
+    constructor(field: string, reason: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=mapping.error.d.ts.map