@nitpicker/archive 0.0.0-stage → 0.25.0

package/lib/utils/array/each-splitted.js

@@ -0,0 +1,14 @@
+import { splitArray } from '@d-zero/shared/split-array';
+/**
+ * Splits an array into chunks of the specified size and executes a callback
+ * on each chunk in parallel using `Promise.all`.
+ * @template T - The element type of the array.
+ * @param a - The array to split into chunks.
+ * @param count - The maximum number of elements per chunk.
+ * @param callback - A function to invoke on each chunk. May be synchronous or asynchronous.
+ * @returns A promise that resolves when all chunk callbacks have completed.
+ */
+export async function eachSplitted(a, count, callback) {
+    const splitted = splitArray(a, count);
+    await Promise.all(splitted.map((items) => callback(items)));
+}

package/lib/utils/debug.d.ts

@@ -0,0 +1,8 @@
+import debug from 'debug';
+/**
+ * Debug logger for the archive layer's shared utilities. Namespace:
+ * `Nitpicker:Utils` — the same namespace as `@nitpicker/crawler`'s utility
+ * logger, so one `DEBUG=Nitpicker:Utils*` filter covers both packages
+ * (`../debug.ts` extends it to `Nitpicker:Utils:Archive`).
+ */
+export declare const log: debug.Debugger;

package/lib/utils/debug.js

@@ -0,0 +1,8 @@
+import debug from 'debug';
+/**
+ * Debug logger for the archive layer's shared utilities. Namespace:
+ * `Nitpicker:Utils` — the same namespace as `@nitpicker/crawler`'s utility
+ * logger, so one `DEBUG=Nitpicker:Utils*` filter covers both packages
+ * (`../debug.ts` extends it to `Nitpicker:Utils:Archive`).
+ */
+export const log = debug('Nitpicker:Utils');

package/lib/utils/error/emit-error-with-retry.d.ts

@@ -0,0 +1,40 @@
+import type { RetryCallOptions } from '@d-zero/shared/retry';
+/**
+ * Minimal object shape required by {@link emitErrorAndRetry}: an emitter
+ * able to publish an `'error'` event carrying an `Error` payload. Same
+ * contract as `emitError` — see {@link ./emit-error.js} for details.
+ */
+interface Emitter {
+    /**
+     * Emits the `'error'` event with the given `Error` payload.
+     * @param event - Event name; always `'error'` here.
+     * @param payload - The error instance to publish.
+     * @returns Anything; the caller ignores it.
+     */
+    emit(event: 'error', payload: Error): unknown;
+}
+/**
+ * Retries `fn` per `retryOptions`, then — if retries are exhausted with a
+ * final `Error` — logs and re-emits it as an `'error'` event on `emitter`
+ * before re-throwing. `label` is forwarded into `retryCall` so its own
+ * onWait / onGiveUp / timeout messages identify the call site (previously
+ * derived automatically by the `@retry` decorator via
+ * `ClassMethodDecoratorContext.name`).
+ *
+ * Inlined try/catch rather than composing `emitError` with a
+ * `() => retryCall(...)` closure to keep the per-invocation closure count
+ * at 1 — this method is called on the DB write hot path (`updatePage`,
+ * `insertResource`), where wrapping decorators previously ran with zero
+ * per-call allocation.
+ * @template T - The return type of `fn`.
+ * @param emitter - The event emitter that receives the `'error'` event.
+ * @param label - Human-readable label; forwarded into `retryCall`
+ *                (visible in retry timeouts / onWait / onGiveUp) and used
+ *                as the debug log prefix on final failure.
+ * @param fn - The async operation to retry.
+ * @param retryOptions - Retry configuration; `label` is overwritten
+ *                       with the `label` argument here.
+ * @returns The resolved value of `fn`.
+ */
+export declare function emitErrorAndRetry<T>(emitter: Emitter, label: string, fn: () => Promise<T>, retryOptions: RetryCallOptions): Promise<T>;
+export {};

package/lib/utils/error/emit-error-with-retry.js

@@ -0,0 +1,44 @@
+import { retryCall } from '@d-zero/shared/retry';
+import { log } from '../debug.js';
+/**
+ * Debug logger for the ErrorEmitter helper family.
+ * Namespace: `Nitpicker:Utils:ErrorEmitter`. Kept identical to the namespace
+ * used by the deleted `@ErrorEmitter()` decorator so existing `DEBUG` env
+ * filters keep working after the decorator-to-HOF migration.
+ */
+const errorLog = log.extend('ErrorEmitter');
+/**
+ * Retries `fn` per `retryOptions`, then — if retries are exhausted with a
+ * final `Error` — logs and re-emits it as an `'error'` event on `emitter`
+ * before re-throwing. `label` is forwarded into `retryCall` so its own
+ * onWait / onGiveUp / timeout messages identify the call site (previously
+ * derived automatically by the `@retry` decorator via
+ * `ClassMethodDecoratorContext.name`).
+ *
+ * Inlined try/catch rather than composing `emitError` with a
+ * `() => retryCall(...)` closure to keep the per-invocation closure count
+ * at 1 — this method is called on the DB write hot path (`updatePage`,
+ * `insertResource`), where wrapping decorators previously ran with zero
+ * per-call allocation.
+ * @template T - The return type of `fn`.
+ * @param emitter - The event emitter that receives the `'error'` event.
+ * @param label - Human-readable label; forwarded into `retryCall`
+ *                (visible in retry timeouts / onWait / onGiveUp) and used
+ *                as the debug log prefix on final failure.
+ * @param fn - The async operation to retry.
+ * @param retryOptions - Retry configuration; `label` is overwritten
+ *                       with the `label` argument here.
+ * @returns The resolved value of `fn`.
+ */
+export async function emitErrorAndRetry(emitter, label, fn, retryOptions) {
+    try {
+        return await retryCall(fn, { ...retryOptions, label });
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            errorLog('%s: %O', label, error);
+            void emitter.emit('error', error);
+        }
+        throw error;
+    }
+}

package/lib/utils/error/emit-error.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Minimal object shape required by {@link emitError}: an emitter able to
+ * publish an `'error'` event carrying an `Error` payload. Any class that
+ * extends `TypedAwaitEventEmitter<{ error: Error, ... }>` satisfies this,
+ * and so does Node's built-in `EventEmitter`.
+ */
+interface Emitter {
+    /**
+     * Emits the `'error'` event with the given `Error` payload.
+     * The return value is intentionally unspecified — callers ignore it.
+     * @param event - Event name; always `'error'` here.
+     * @param payload - The error instance to publish.
+     * @returns Anything; the caller ignores it.
+     */
+    emit(event: 'error', payload: Error): unknown;
+}
+/**
+ * Wraps `fn` so that any thrown `Error` is logged with `label` and
+ * re-emitted as an `'error'` event on `emitter` before being re-thrown.
+ * Non-`Error` throws pass through unchanged — no log, no emit — matching
+ * the behaviour of the deleted `@ErrorEmitter()` decorator so that
+ * downstream `'error'` listeners (e.g. the crawler orchestrator that
+ * aborts on any emitted error) are only invoked with real `Error`
+ * instances.
+ *
+ * Kept as a standalone HOF (instead of a decorator) because Vite 8 /
+ * Vitest 4.1 switched from esbuild to Rolldown + oxc, which emit
+ * TC39 Stage 3 decorator syntax as-is and let it reach Node, causing
+ * `SyntaxError: Invalid or unexpected token` at test runtime.
+ * @template T - The return type of `fn`.
+ * @param emitter - The event emitter that receives the `'error'` event.
+ * @param label - Human-readable label included in the debug log line
+ *                (typically `'ClassName.methodName'`). Also useful as the
+ *                grep target when triaging failed crawls.
+ * @param fn - The async operation to wrap.
+ * @returns The resolved value of `fn`.
+ */
+export declare function emitError<T>(emitter: Emitter, label: string, fn: () => Promise<T>): Promise<T>;
+export {};

package/lib/utils/error/emit-error.js

@@ -0,0 +1,41 @@
+import { log } from '../debug.js';
+/**
+ * Debug logger for the ErrorEmitter helper family.
+ * Namespace: `Nitpicker:Utils:ErrorEmitter`. Kept identical to the namespace
+ * used by the deleted `@ErrorEmitter()` decorator so existing `DEBUG` env
+ * filters keep working after the decorator-to-HOF migration.
+ */
+const errorLog = log.extend('ErrorEmitter');
+/**
+ * Wraps `fn` so that any thrown `Error` is logged with `label` and
+ * re-emitted as an `'error'` event on `emitter` before being re-thrown.
+ * Non-`Error` throws pass through unchanged — no log, no emit — matching
+ * the behaviour of the deleted `@ErrorEmitter()` decorator so that
+ * downstream `'error'` listeners (e.g. the crawler orchestrator that
+ * aborts on any emitted error) are only invoked with real `Error`
+ * instances.
+ *
+ * Kept as a standalone HOF (instead of a decorator) because Vite 8 /
+ * Vitest 4.1 switched from esbuild to Rolldown + oxc, which emit
+ * TC39 Stage 3 decorator syntax as-is and let it reach Node, causing
+ * `SyntaxError: Invalid or unexpected token` at test runtime.
+ * @template T - The return type of `fn`.
+ * @param emitter - The event emitter that receives the `'error'` event.
+ * @param label - Human-readable label included in the debug log line
+ *                (typically `'ClassName.methodName'`). Also useful as the
+ *                grep target when triaging failed crawls.
+ * @param fn - The async operation to wrap.
+ * @returns The resolved value of `fn`.
+ */
+export async function emitError(emitter, label, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            errorLog('%s: %O', label, error);
+            void emitter.emit('error', error);
+        }
+        throw error;
+    }
+}

package/lib/utils/object/parse-response-headers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parse a JSON-serialized HTTP response headers column from the archive
+ * database.
+ *
+ * The columns hold JSON produced by `JSON.stringify` at insert time; absent,
+ * malformed, or non-object JSON (the string `"null"`, arrays, primitives)
+ * degrades to `null` instead of throwing because a missing header set only
+ * loses fidelity — callers decide their own fallback (`?? {}` etc.).
+ * @param json - The raw column value.
+ * @returns The parsed header record, or `null` when absent or malformed.
+ */
+export declare function parseResponseHeaders(json: string | null): Record<string, string | string[] | undefined> | null;

package/lib/utils/object/parse-response-headers.js

@@ -0,0 +1,26 @@
+/**
+ * Parse a JSON-serialized HTTP response headers column from the archive
+ * database.
+ *
+ * The columns hold JSON produced by `JSON.stringify` at insert time; absent,
+ * malformed, or non-object JSON (the string `"null"`, arrays, primitives)
+ * degrades to `null` instead of throwing because a missing header set only
+ * loses fidelity — callers decide their own fallback (`?? {}` etc.).
+ * @param json - The raw column value.
+ * @returns The parsed header record, or `null` when absent or malformed.
+ */
+export function parseResponseHeaders(json) {
+    if (json == null) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(json);
+        if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/lib/utils/object/redact-request-headers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns a copy of `config` whose `requestHeaders` values are replaced with
+ * `***`, leaving the header names visible. Use it before a config object is
+ * logged or printed.
+ *
+ * WHY: request header values are credentials. The runtime config that flows
+ * through the orchestrator carries them, and it is dumped by `debug` logs and
+ * the crawl-start header — neither may show a token.
+ * @param config - Any config object that may carry `requestHeaders`.
+ * @returns The same object when it has no `requestHeaders`, otherwise a shallow copy with masked values.
+ * @example
+ * redactRequestHeaders({ userAgent: 'x', requestHeaders: { Authorization: 'Bearer t' } });
+ * // => { userAgent: 'x', requestHeaders: { Authorization: '***' } }
+ */
+export declare function redactRequestHeaders<T extends object>(config: T): T;

package/lib/utils/object/redact-request-headers.js

@@ -0,0 +1,27 @@
+/** Placeholder shown instead of a request header value. */
+const REDACTED = '***';
+/**
+ * Returns a copy of `config` whose `requestHeaders` values are replaced with
+ * `***`, leaving the header names visible. Use it before a config object is
+ * logged or printed.
+ *
+ * WHY: request header values are credentials. The runtime config that flows
+ * through the orchestrator carries them, and it is dumped by `debug` logs and
+ * the crawl-start header — neither may show a token.
+ * @param config - Any config object that may carry `requestHeaders`.
+ * @returns The same object when it has no `requestHeaders`, otherwise a shallow copy with masked values.
+ * @example
+ * redactRequestHeaders({ userAgent: 'x', requestHeaders: { Authorization: 'Bearer t' } });
+ * // => { userAgent: 'x', requestHeaders: { Authorization: '***' } }
+ */
+export function redactRequestHeaders(config) {
+    const { requestHeaders } = config;
+    if (!requestHeaders) {
+        return config;
+    }
+    const masked = {};
+    for (const name of Object.keys(requestHeaders)) {
+        masked[name] = REDACTED;
+    }
+    return { ...config, requestHeaders: masked };
+}

package/lib/utils/types/types.d.ts

@@ -0,0 +1,383 @@
+/**
+ * Scrape-result shapes the archive layer persists.
+ *
+ * Structurally equivalent mirrors of `@d-zero/beholder`'s exported types
+ * (`PageData`, `Resource`, `MainContentsData`, `ConsoleLogEntry`, …) so
+ * that `@nitpicker/archive` — and every read-only consumer that depends on
+ * it (query / viewer / mcp-server / report-*) — does not pull in beholder,
+ * puppeteer or dealer. The crawler passes beholder's values straight
+ * through: TypeScript's structural typing accepts them without conversion.
+ * Structural typing alone would NOT catch a field beholder adds, so
+ * `@nitpicker/crawler`'s `beholder-type-mirror-parity.ts` asserts at build
+ * time that every mirror here is identical to the installed beholder's —
+ * update this file in the same change that bumps `@d-zero/beholder`.
+ *
+ * The only intentional widening is `ConsoleLogEntry.type` (puppeteer's
+ * `ConsoleMessageType` union becomes `string`), because naming the union
+ * would require a `puppeteer` dependency. `Meta` and its sub-types live in
+ * `../../meta/types.ts`.
+ * @module
+ */
+import type { Meta } from '../../meta/types.js';
+import type { CDNType } from '@d-zero/shared/detect-cdn';
+import type { CompressType } from '@d-zero/shared/detect-compress';
+import type { ExURL } from '@d-zero/shared/parse-url';
+/**
+ * Numeric outcome code for one device preset's `<img>` scan, mirroring
+ * `@d-zero/beholder`'s `ImageScanCode` (`IMAGE_SCAN_CODE`: 0=ok /
+ * 1=degraded / 2=nav-unsettled / 3=frame-lost / 4=scroll-height-exceeded /
+ * 255=unknown).
+ */
+export type ImageScanCode = 0 | 1 | 2 | 3 | 4 | 255;
+/**
+ * Scraped page data returned by the scraper after successfully processing a page.
+ */
+export interface PageData {
+    /** The parsed URL of the page. */
+    url: ExURL;
+    /** Chain of redirect URLs traversed to reach the final destination. */
+    redirectPaths: string[];
+    /** Whether this page is a target page (internal and within the crawl scope). */
+    isTarget: boolean;
+    /** Whether this page is external to the crawl scope. */
+    isExternal: boolean;
+    /** HTTP status code of the response. */
+    status: number;
+    /** HTTP status text of the response. */
+    statusText: string;
+    /** The Content-Type header value, or `null` if unavailable. */
+    contentType: string | null;
+    /** The Content-Length header value in bytes, or `null` if unavailable. */
+    contentLength: number | null;
+    /** Raw HTTP response headers, or `null` if unavailable. */
+    responseHeaders: Record<string, string | string[] | undefined> | null;
+    /** Extracted metadata from the page (title, description, OGP, etc.). */
+    meta: Meta;
+    /** List of anchor elements found on the page. */
+    anchorList: AnchorData[];
+    /** List of image elements found on the page. */
+    imageList: ImageElement[];
+    /** HTML snapshot of the rendered DOM. */
+    html: string;
+    /**
+     * Quantitative main-content metrics extracted in the browser after load.
+     * `null` when the page is non-HTML, external, non-HTTP, or otherwise not fully scraped.
+     * When HTML is scraped but no main region is found, this is still an object with empty arrays and `wordCount: 0`.
+     */
+    mainContents: MainContentsData | null;
+    /**
+     * `document.body.scrollHeight` at desktop-compact and mobile-small viewports.
+     * `null` when not measured (non-HTML, external, non-HTTP, or skipped).
+     */
+    scrollHeight: ScrollHeightData | null;
+    /**
+     * Per-device-preset outcome of the `<img>` element scan performed by
+     * `Scraper#fetchImages`, keyed the same way as {@link ScrollHeightData}.
+     * A field is `null` when that device preset's image scan was never
+     * attempted (non-HTML, external, non-HTTP page, or `captureImages: false`);
+     * otherwise it is an {@link ImageScanCode} recording why the scan
+     * succeeded, degraded, or was abandoned. See `@d-zero/beholder`'s `IMAGE_SCAN_CODE`.
+     * @example
+     * ```ts
+     * if (pageData.imageScan.mobile === IMAGE_SCAN_CODE.SCROLL_HEIGHT_EXCEEDED) {
+     *   // mobile images were skipped due to an oversized scrollHeight
+     * }
+     * ```
+     */
+    imageScan: ImageScanData;
+    /** Always `false` for successfully scraped pages. Skipped pages are never passed to the archive as `PageData`. */
+    isSkipped: false;
+}
+/**
+ * `document.body.scrollHeight` measured at the scraper's desktop and mobile device presets.
+ */
+export interface ScrollHeightData {
+    /** Height at `desktop-compact` (width 1280), or `null` if that preset failed. */
+    desktop: number | null;
+    /** Height at `mobile-small` (width 320 @ 2x), or `null` if that preset failed. */
+    mobile: number | null;
+}
+/**
+ * Per-device-preset {@link ImageScanCode} outcome of `Scraper#fetchImages`,
+ * mirroring {@link ScrollHeightData}'s desktop/mobile shape.
+ */
+export interface ImageScanData {
+    /** Outcome for `desktop-compact` (width 1280), or `null` if not attempted. */
+    desktop: ImageScanCode | null;
+    /** Outcome for `mobile-small` (width 320 @ 2x), or `null` if not attempted. */
+    mobile: ImageScanCode | null;
+}
+/**
+ * Quantitative metrics for the detected main content region of a page.
+ * @example
+ * ```ts
+ * const { mainContents } = pageData;
+ * if (mainContents) {
+ *   console.log(mainContents.wordCount, mainContents.headings.length);
+ * }
+ * ```
+ */
+export interface MainContentsData {
+    /** `document.title` trimmed. Empty string when the title is empty. */
+    title: string;
+    /**
+     * Identifying info for the detected main region element.
+     * `null` when no selector matched (arrays are empty and `wordCount` is `0`).
+     */
+    main: MainContentsMainTag | null;
+    /**
+     * Character count of the main region's `textContent` after whitespace removal.
+     * `0` when no main region was found or the text is whitespace-only.
+     */
+    wordCount: number;
+    /**
+     * Character count of `document.body` `textContent` after whitespace removal.
+     * Measured even when no main region is found (`0` if `body` is missing).
+     */
+    bodyWordCount: number;
+    /** Headings (`h1`–`h6`) inside the main region, in DOM order. */
+    headings: MainContentsHeading[];
+    /** Images (`img`, `input[type=image]`) inside the main region, in DOM order. */
+    images: MainContentsImage[];
+    /** Tables inside the main region, in DOM order. */
+    tables: MainContentsTable[];
+    /** Button-like elements inside the main region, in DOM order. */
+    buttons: MainContentsButton[];
+    /** Iframes inside the main region, in DOM order. */
+    iframes: MainContentsIframe[];
+    /** Videos inside the main region, in DOM order. */
+    videos: MainContentsVideo[];
+    /** Audios inside the main region, in DOM order. */
+    audios: MainContentsAudio[];
+    /** Canvases inside the main region, in DOM order. */
+    canvases: MainContentsCanvas[];
+}
+/**
+ * Identifying information about the DOM element used as the main content area.
+ */
+export interface MainContentsMainTag {
+    /** Element tag name (e.g. `"MAIN"`, `"DIV"`), as reported by `nodeName`. */
+    nodeName: string;
+    /** The element's `id`, or `null` when empty/absent. */
+    id: string | null;
+    /** CSS class names on the element. */
+    classList: string[];
+    /** The WAI-ARIA `role` attribute value, or `null` when absent. */
+    role: string | null;
+    /**
+     * A simple diagnostic CSS selector built from tag + id + classes
+     * (not `@medv/finder`). // cspell:disable-line
+     */
+    selector: string;
+}
+/**
+ * A heading element (`h1`–`h6`) found within the main content area.
+ */
+export interface MainContentsHeading {
+    /** Heading text after whitespace removal, or `null` when empty. */
+    text: string | null;
+    /** Heading level from the tag name. */
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+}
+/**
+ * An `<img>` or `<input type="image">` element found in the main content.
+ */
+export interface MainContentsImage {
+    /** Resolved absolute `src` URL. */
+    src: string;
+    /** `alt` attribute value (may be an empty string). */
+    alt: string;
+}
+/**
+ * Structural summary of a `<table>` found within the main content.
+ */
+export interface MainContentsTable {
+    /** Number of `<tr>` elements. */
+    rows: number;
+    /** Number of `th`/`td` cells in the first row, or `0` when there is no row. */
+    cols: number;
+    /** Whether the table contains a `<thead>`. */
+    hasHeader: boolean;
+    /** Whether the table contains a `<tfoot>`. */
+    hasFooter: boolean;
+    /** Whether any cell uses `colspan` or `rowspan`. */
+    hasMergedCell: boolean;
+}
+/**
+ * A button-like element found in the main content
+ * (`button`, `[role=button]`, `[class*=button]`, `[class*=btn]`).
+ */
+export interface MainContentsButton {
+    /** Element tag name (e.g. `"BUTTON"`, `"A"`, `"DIV"`). */
+    nodeName: string;
+    /** `role` attribute, or `null` when absent. */
+    role: string | null;
+    /** `type` for `<button>` / `<input>`, otherwise `null`. */
+    type: string | null;
+    /** Label text after whitespace removal, or `null` when empty. */
+    text: string | null;
+    /** `true` when `disabled` or `aria-disabled="true"`. */
+    disabled: boolean;
+}
+/**
+ * An `<iframe>` found in the main content.
+ */
+export interface MainContentsIframe {
+    /** Resolved absolute `src` URL (empty string when unset). */
+    src: string;
+    /** `title` attribute, or `null` when the attribute is absent. */
+    title: string | null;
+    /** Raw `width` attribute string, or `null` when absent. */
+    width: string | null;
+    /** Raw `height` attribute string, or `null` when absent. */
+    height: string | null;
+}
+/**
+ * A `<video>` found in the main content.
+ */
+export interface MainContentsVideo {
+    /**
+     * Resolved media URL: `currentSrc`, else `src` attribute, else first `source[src]`, else `""`.
+     */
+    src: string;
+    /** Resolved `poster` URL, or `null` when unset. */
+    poster: string | null;
+    /** IDL `width` in pixels. */
+    width: number;
+    /** IDL `height` in pixels. */
+    height: number;
+}
+/**
+ * An `<audio>` found in the main content.
+ */
+export interface MainContentsAudio {
+    /**
+     * Resolved media URL: `currentSrc`, else `src` attribute, else first `source[src]`, else `""`.
+     */
+    src: string;
+}
+/**
+ * A `<canvas>` found in the main content.
+ */
+export interface MainContentsCanvas {
+    /** IDL bitmap width. */
+    width: number;
+    /** IDL bitmap height. */
+    height: number;
+}
+/**
+ * Information about an image element found on a page.
+ */
+export interface ImageElement {
+    /** The `src` attribute value of the image element. */
+    src: string;
+    /** The `currentSrc` property value (the actual URL loaded by the browser). */
+    currentSrc: string;
+    /** The `alt` attribute value of the image element. */
+    alt: string;
+    /** The CSS layout width of the image in pixels. */
+    width: number;
+    /** The CSS layout height of the image in pixels. */
+    height: number;
+    /** The intrinsic width of the image in pixels. */
+    naturalWidth: number;
+    /** The intrinsic height of the image in pixels. */
+    naturalHeight: number;
+    /** Whether the image uses lazy loading (`loading="lazy"` or IntersectionObserver). */
+    isLazy: boolean;
+    /** The viewport width at which this image was captured. */
+    viewportWidth: number;
+    /** The outer HTML source code of the image element. */
+    sourceCode: string;
+}
+/**
+ * A network resource (CSS, JS, image, etc.) captured during page scraping.
+ */
+export interface Resource {
+    /** The URL of the resource. */
+    url: ExURL;
+    /** Whether the resource is from an external domain. */
+    isExternal: boolean;
+    /** Whether the resource request resulted in an error. */
+    isError: boolean;
+    /** HTTP status code, or `null` if the request failed. */
+    status: number | null;
+    /** HTTP status text, or `null` if the request failed. */
+    statusText: string | null;
+    /** The Content-Type header value, or `null` if unavailable. */
+    contentType: string | null;
+    /** The Content-Length header value in bytes, or `null` if unavailable. */
+    contentLength: number | null;
+    /** The compression algorithm used, or `false` if uncompressed. */
+    compress: false | CompressType;
+    /** The CDN provider detected from response headers, or `false` if none detected. */
+    cdn: false | CDNType;
+    /** Raw HTTP response headers, or `null` if unavailable. */
+    headers: Record<string, string | string[] | undefined> | null;
+}
+/**
+ * Data extracted from an anchor element (`<a>` or `<area>`) on a page.
+ */
+export interface AnchorData {
+    /**
+     * Extracts the value of the `href` attribute from anchor element (`<a>` `<area>`)
+     */
+    href: ExURL;
+    /**
+     * The accessible name of the anchor element
+     */
+    textContent: string;
+    /**
+     * Whether the anchor points to an external URL.
+     * Set by `processAnchors()` in the crawler; not available in the sub-process.
+     */
+    isExternal?: boolean;
+}
+/**
+ * A single console message or uncaught page error captured during page scraping.
+ * Captured via Puppeteer's `console` and `pageerror` page events; internal pages only.
+ */
+export interface ConsoleLogEntry {
+    /** The URL (without hash) of the page that produced this message. */
+    pageUrl: string;
+    /**
+     * The console message type (Puppeteer's `ConsoleMessageType`, e.g. `"log"`, `"warn"`, `"error"`),
+     * or `"pageerror"` for an uncaught exception / unhandled Promise rejection.
+     * Widened to `string` so the archive does not depend on `puppeteer`.
+     */
+    type: string;
+    /** The message text, or the error's `message` for `"pageerror"` entries. */
+    text: string;
+    /**
+     * Arguments passed to the console call, resolved via `JSHandle.jsonValue()`.
+     * An individual argument is `undefined` when it could not be resolved (e.g. a
+     * destroyed execution context or a value `jsonValue()` cannot serialize).
+     * Always empty for `"pageerror"` entries.
+     */
+    args: unknown[];
+    /** Source location of the message, or `undefined` when unavailable (always `undefined` for `"pageerror"`). */
+    location?: {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+    /** Stack trace text, present only for `"pageerror"` entries. */
+    stack?: string;
+    /** Timestamp (ms since epoch) when the message was captured. */
+    ts: number;
+}
+/**
+ * An error event emitted during crawling or scraping.
+ */
+export interface CrawlerError {
+    /** The process ID where the error occurred. */
+    pid: number;
+    /** Whether the error occurred in the main process (as opposed to a sub-process). */
+    isMainProcess: boolean;
+    /** The URL being processed when the error occurred, or `null` if not applicable. */
+    url: string | null;
+    /** Whether the error occurred while processing an external (out-of-scope) URL. */
+    isExternal: boolean;
+    /** The error object. */
+    error: Error;
+}

package/lib/utils/types/types.js

@@ -0,0 +1 @@
+export {};