@opencraw/core 0.1.0

package/dist/src/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/src/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/src/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/src/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/src/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/src/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/src/access/access-profile.contract.d.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+/**
+ * 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;
+}
+export declare const accessProfileSchema: z.ZodType<AccessProfile>;
+export declare const accessConfigSchema: z.ZodType<AccessConfig>;
+export {};
+//# sourceMappingURL=access-profile.contract.d.ts.map

package/dist/src/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, 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/src/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/src/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/src/api-steps/extract-from-document.use-case.d.ts

@@ -0,0 +1,27 @@
+import type { ExtractionScope } 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, `jsonpath`
+ * reads JSON; `xpath` needs a live page and is refused here.
+ *
+ * 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;
+//# sourceMappingURL=extract-from-document.use-case.d.ts.map

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

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

package/dist/src/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/src/api-steps/send-request.use-case.d.ts

@@ -0,0 +1,22 @@
+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, 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; 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, or the markup / text. */
+export declare function documentValue(body: HttpBody): unknown;
+//# sourceMappingURL=send-request.use-case.d.ts.map

package/dist/src/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/src/browser-session/browser.client.d.ts

@@ -0,0 +1,67 @@
+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>;
+}
+/** 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/src/browser-session/index.d.ts

@@ -0,0 +1,5 @@
+export { BrowserClient, BrowserSession } from './browser.client.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/src/crawl-events/crawl-event.contract.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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;
+    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;
+}) | (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/src/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/src/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/src/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