@d-zero/beholder 2.0.1 → 2.1.0

package/dist/scraper.d.ts

@@ -0,0 +1,41 @@
+import type { ScraperEventTypes, ScraperOptions, ScrapeResult, ExURL } from './types.js';
+import type { Page } from 'puppeteer';
+import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
+/**
+ * Page-level scraper that extracts data from a single browser page.
+ *
+ * The scraper returns results as values from `scrapeStart()` rather than
+ * emitting them as events. Only streaming events (changePhase, resourceResponse)
+ * are emitted for progress monitoring.
+ *
+ * The Puppeteer `Page` object is injected externally, and page lifecycle
+ * (including `page.close()`) is managed by the caller.
+ * @example
+ * ```ts
+ * const scraper = new Scraper();
+ * scraper.on('changePhase', (e) => console.log(e.name));
+ * const result = await scraper.scrapeStart(page, url, { isExternal: false });
+ * ```
+ */
+export default class Scraper extends EventEmitter<ScraperEventTypes> {
+    #private;
+    /** Number of retries for `@retryable`-decorated methods. Set per-scrape from options. */
+    retries?: number;
+    /**
+     * Begins the scraping process for a given URL on the provided Puppeteer page.
+     *
+     * Returns a `ScrapeResult` containing the outcome:
+     * - `type: "success"` with `pageData` on success
+     * - `type: "skipped"` with `ignored` details when the page is excluded
+     * - `type: "error"` with `error` details when scraping fails
+     *
+     * Sub-resources are collected via the `resourceResponse` event and
+     * included in the returned `ScrapeResult.resources`.
+     * @param page - The Puppeteer page instance to use for navigation and DOM evaluation.
+     * @param url - The extended URL to scrape.
+     * @param options - Optional scraper configuration overriding defaults.
+     * @param isSkip - When `true`, the page is immediately skipped without any network requests.
+     * @returns The scrape result containing the outcome and captured resources.
+     */
+    scrapeStart(page: Page, url: ExURL, options?: Partial<ScraperOptions>, isSkip?: boolean): Promise<ScrapeResult>;
+}