@pagepocket/capture-http-puppeteer-unit 0.8.0

package/dist/capture-http-puppeteer-plugin.d.ts

@@ -0,0 +1,9 @@
+import { type PagePocketContext, type PagePocketPlugin } from "@pagepocket/lib";
+import { type PuppeteerAdapterOptions } from "./internal/puppeteer-adapter.js";
+export type CaptureHttpPuppeteerPluginOptions = PuppeteerAdapterOptions;
+export declare class CaptureHttpPuppeteerPlugin implements PagePocketPlugin {
+    readonly name = "plugin:capture-http-puppeteer";
+    private adapterOptions;
+    constructor(options?: CaptureHttpPuppeteerPluginOptions);
+    apply(ctx: PagePocketContext): void;
+}

package/dist/capture-http-puppeteer-plugin.js

@@ -0,0 +1,146 @@
+import { createMemoryContentStore } from "@pagepocket/lib";
+import { InflightTracker, networkIdle, normalizeCompletion, timeout } from "@pagepocket/lib";
+import { PuppeteerAdapter } from "./internal/puppeteer-adapter.js";
+const headersRecordToList = (headers) => {
+    if (!headers)
+        return [];
+    return Object.keys(headers).map((name) => ({ name, value: headers[name] }));
+};
+export class CaptureHttpPuppeteerPlugin {
+    constructor(options) {
+        this.name = "plugin:capture-http-puppeteer";
+        this.adapterOptions = options ?? {};
+    }
+    apply(ctx) {
+        const contentStore = createMemoryContentStore("capture-http-puppeteer");
+        const events = [];
+        const capabilities = {
+            requestHeaders: "approx",
+            responseHeaders: "approx",
+            requestBodies: false,
+            responseBodies: "decoded",
+            httpVersion: false,
+            remoteIp: false,
+            headerOrderPreserved: false
+        };
+        ctx.capture = {
+            events,
+            contentStore,
+            capabilities
+        };
+        const inflightTracker = new InflightTracker();
+        const handleNetworkEvent = async (event) => {
+            inflightTracker.handleEvent(event);
+            ctx.emitNetworkEvent?.(event);
+            if (event.type === "request") {
+                events.push({
+                    type: "http.request",
+                    requestId: event.requestId,
+                    url: event.url,
+                    method: event.method,
+                    headers: headersRecordToList(event.headers),
+                    timestamp: event.timestamp,
+                    frameId: event.frameId,
+                    resourceType: event.resourceType,
+                    initiator: event.initiator
+                });
+                return;
+            }
+            if (event.type === "failed") {
+                events.push({
+                    type: "http.failed",
+                    requestId: event.requestId,
+                    url: event.url,
+                    errorText: event.errorText,
+                    timestamp: event.timestamp
+                });
+                return;
+            }
+            const bodyRef = event.body
+                ? await contentStore.put(event.body, {
+                    url: event.url,
+                    mimeType: event.mimeType,
+                    sizeHint: undefined
+                })
+                : undefined;
+            events.push({
+                type: "http.response",
+                requestId: event.requestId,
+                url: event.url,
+                status: event.status,
+                statusText: event.statusText,
+                headers: headersRecordToList(event.headers),
+                timestamp: event.timestamp,
+                mimeType: event.mimeType,
+                fromDiskCache: event.fromDiskCache,
+                fromServiceWorker: event.fromServiceWorker,
+                bodyRef,
+                bodySize: undefined
+            });
+        };
+        const stateKey = "captureHttpPuppeteer.session";
+        ctx.onInit(async () => {
+            const target = ctx.entry.kind === "url"
+                ? { kind: "url", url: ctx.entry.url }
+                : ctx.entry.kind === "puppeteer-page"
+                    ? { kind: "puppeteer-page", page: ctx.entry.page }
+                    : ctx.entry.kind === "html-string"
+                        ? {
+                            kind: "html",
+                            htmlString: await ctx.whenHtml().then((h) => h.htmlString),
+                            baseUrl: ctx.entry.baseUrl,
+                            ...(ctx.entry.url ? { url: ctx.entry.url } : {})
+                        }
+                        : (() => {
+                            throw new Error(`CaptureHttpPuppeteerPlugin does not support entry kind: ${String(ctx.entry.kind)}`);
+                        })();
+            const adapter = new PuppeteerAdapter(this.adapterOptions);
+            const session = await adapter.start(target, {
+                onEvent(event) {
+                    void handleNetworkEvent(event);
+                },
+                onError(error) {
+                    // eslint-disable-next-line no-console
+                    console.warn("[pagepocket][capture-http-puppeteer] adapter error", error);
+                }
+            }, {
+                timeoutMs: ctx.options.timeoutMs,
+                maxDurationMs: ctx.options.maxDurationMs
+            });
+            ctx.state[stateKey] = session;
+            if (target.kind === "url" && session.navigate) {
+                await session.navigate(target.url);
+            }
+            if (!ctx.html) {
+                const html = await session.waitForHtml();
+                ctx.setHtml(html);
+            }
+        });
+        ctx.onBeforeNetwork(async () => {
+            const session = ctx.state[stateKey];
+            if (!session) {
+                throw new Error("CaptureHttpPuppeteerPlugin internal error: missing session");
+            }
+            await session.startCapture();
+            const completionStrategies = normalizeCompletion(ctx.options.completion);
+            const idleMs = ctx.options.timeoutMs ?? 5000;
+            const maxDurationMs = ctx.options.maxDurationMs;
+            const completion = completionStrategies.length > 0
+                ? completionStrategies
+                : [networkIdle(idleMs), ...(maxDurationMs !== undefined ? [timeout(maxDurationMs)] : [])];
+            if (completion.length === 1) {
+                await completion[0].wait({
+                    now: () => Date.now(),
+                    getStats: () => inflightTracker.getStats()
+                });
+            }
+            else {
+                await Promise.race(completion.map((strategy) => strategy.wait({
+                    now: () => Date.now(),
+                    getStats: () => inflightTracker.getStats()
+                })));
+            }
+            await session.stop();
+        });
+    }
+}

package/dist/capture-http-puppeteer-unit.d.ts

@@ -0,0 +1,19 @@
+import { Unit, type CaptureArtifacts } from "@pagepocket/lib";
+import { type PuppeteerAdapterOptions } from "./internal/puppeteer-adapter.js";
+export type CaptureHttpPuppeteerUnitOptions = PuppeteerAdapterOptions;
+export declare class CaptureHttpPuppeteerUnit extends Unit {
+    readonly id = "captureHttpPuppeteer";
+    readonly kind = "capture.http.puppeteer";
+    private adapterOptions;
+    constructor(options?: CaptureHttpPuppeteerUnitOptions);
+    run(ctx: import("@pagepocket/lib").UnitContext, rt: import("@pagepocket/lib").UnitRuntime): Promise<{
+        capture: CaptureArtifacts;
+        html: {};
+        domHtml: {
+            htmlString: string;
+            baseUrl: string;
+            url?: string;
+            contentType?: string;
+        };
+    }>;
+}

package/dist/capture-http-puppeteer-unit.js

@@ -0,0 +1,137 @@
+import { NETWORK } from "@pagepocket/contracts";
+import { Unit, createMemoryContentStore, InflightTracker, mapKind, networkIdle, normalizeCompletion, throwUnsupportedEntryKind, timeout } from "@pagepocket/lib";
+import { PuppeteerAdapter } from "./internal/puppeteer-adapter.js";
+const headersRecordToList = (headers) => {
+    if (!headers)
+        return [];
+    return Object.keys(headers).map((name) => ({ name, value: headers[name] }));
+};
+const targetBuilders = {
+    url: (entry) => ({
+        kind: "url",
+        url: entry.url
+    }),
+    "puppeteer-page": (entry) => ({
+        kind: "puppeteer-page",
+        page: entry.page
+    }),
+    "html-string": (entry) => ({
+        kind: "html",
+        htmlString: entry.htmlString,
+        baseUrl: entry.baseUrl,
+        ...(entry.url ? { url: entry.url } : {})
+    })
+};
+export class CaptureHttpPuppeteerUnit extends Unit {
+    constructor(options) {
+        super();
+        this.id = "captureHttpPuppeteer";
+        this.kind = "capture.http.puppeteer";
+        this.adapterOptions = options ?? {};
+    }
+    async run(ctx, rt) {
+        const contentStore = createMemoryContentStore("capture-http-puppeteer");
+        const events = [];
+        const capabilities = {
+            requestHeaders: "approx",
+            responseHeaders: "approx",
+            requestBodies: false,
+            responseBodies: "decoded",
+            httpVersion: false,
+            remoteIp: false,
+            headerOrderPreserved: false
+        };
+        const inflightTracker = new InflightTracker();
+        const handleNetworkEvent = async (event) => {
+            inflightTracker.handleEvent(event);
+            rt.publish(NETWORK, event);
+            if (event.type === "request") {
+                events.push({
+                    type: "http.request",
+                    requestId: event.requestId,
+                    url: event.url,
+                    method: event.method,
+                    headers: headersRecordToList(event.headers),
+                    timestamp: event.timestamp,
+                    frameId: event.frameId,
+                    resourceType: event.resourceType,
+                    initiator: event.initiator
+                });
+                return;
+            }
+            if (event.type === "failed") {
+                events.push({
+                    type: "http.failed",
+                    requestId: event.requestId,
+                    url: event.url,
+                    errorText: event.errorText,
+                    timestamp: event.timestamp
+                });
+                return;
+            }
+            const bodyRef = event.body
+                ? await contentStore.put(event.body, {
+                    url: event.url,
+                    mimeType: event.mimeType,
+                    sizeHint: undefined
+                })
+                : undefined;
+            events.push({
+                type: "http.response",
+                requestId: event.requestId,
+                url: event.url,
+                status: event.status,
+                statusText: event.statusText,
+                headers: headersRecordToList(event.headers),
+                timestamp: event.timestamp,
+                mimeType: event.mimeType,
+                fromDiskCache: event.fromDiskCache,
+                fromServiceWorker: event.fromServiceWorker,
+                bodyRef,
+                bodySize: undefined
+            });
+        };
+        const capture = { events, contentStore, capabilities };
+        const adapter = new PuppeteerAdapter(this.adapterOptions);
+        const target = mapKind(rt.entry, targetBuilders, {
+            onUnsupportedKind: throwUnsupportedEntryKind("CaptureHttpPuppeteerUnit")
+        });
+        const session = await adapter.start(target, {
+            onEvent: (event) => {
+                void handleNetworkEvent(event);
+            },
+            onError: (error) => {
+                console.warn("[pagepocket][capture-http-puppeteer] adapter error", error);
+            }
+        }, {
+            timeoutMs: rt.options.timeoutMs,
+            maxDurationMs: rt.options.maxDurationMs
+        });
+        if (target.kind === "url" && session.navigate) {
+            await session.navigate(target.url);
+        }
+        const html = ctx.value.html ?? (await session.waitForHtml());
+        await session.startCapture();
+        const completionStrategies = normalizeCompletion(rt.options.completion);
+        const idleMs = rt.options.timeoutMs ?? 5000;
+        const maxDurationMs = rt.options.maxDurationMs;
+        const completion = completionStrategies.length > 0
+            ? completionStrategies
+            : [networkIdle(idleMs), ...(maxDurationMs !== undefined ? [timeout(maxDurationMs)] : [])];
+        if (completion.length === 1) {
+            await completion[0].wait({
+                now: () => Date.now(),
+                getStats: () => inflightTracker.getStats()
+            });
+        }
+        else {
+            await Promise.race(completion.map((strategy) => strategy.wait({
+                now: () => Date.now(),
+                getStats: () => inflightTracker.getStats()
+            })));
+        }
+        const domHtml = session.getDomHtml ? await session.getDomHtml() : await session.waitForHtml();
+        await session.stop();
+        return { capture, html, domHtml };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { CaptureHttpPuppeteerUnit } from "./capture-http-puppeteer-unit.js";
+export type { CaptureHttpPuppeteerUnitOptions } from "./capture-http-puppeteer-unit.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { CaptureHttpPuppeteerUnit } from "./capture-http-puppeteer-unit.js";

package/dist/internal/puppeteer-adapter.d.ts

@@ -0,0 +1,29 @@
+import type { NetworkEventHandlers, NetworkInterceptorAdapter, TriggerAction, InterceptTarget, InterceptSession } from "@pagepocket/lib";
+import { type Browser, type GoToOptions, type LaunchOptions, type Page } from "puppeteer";
+export type PuppeteerAdapterOptions = {
+    browser?: Browser;
+    page?: Page;
+    launch?: (options?: LaunchOptions) => Promise<Browser>;
+    launchOptions?: LaunchOptions;
+    gotoOptions?: GoToOptions;
+    triggerActions?: TriggerAction[];
+};
+/**
+ * Internal adapter for the capture plugin.
+ *
+ * Note: this is intentionally NOT published as a separate package.
+ */
+export declare class PuppeteerAdapter implements NetworkInterceptorAdapter {
+    readonly name = "puppeteer";
+    readonly capabilities: {
+        canGetResponseBody: boolean;
+        canStreamResponseBody: boolean;
+        canGetRequestBody: boolean;
+        providesResourceType: boolean;
+        canWaitForHtml: boolean;
+        supportsStagedCapture: boolean;
+    };
+    private options;
+    constructor(options?: PuppeteerAdapterOptions);
+    start(target: InterceptTarget, handlers: NetworkEventHandlers, _options?: Record<string, unknown>): Promise<InterceptSession>;
+}

package/dist/internal/puppeteer-adapter.js

@@ -0,0 +1,261 @@
+import puppeteer from "puppeteer";
+import { readDomHtml } from "./utils/dom-html.js";
+import { getEnvString } from "./utils/env.js";
+import { buildMissingChromeHelp, isMissingChromeError, isResponseBodyUnavailableError } from "./utils/errors.js";
+import { getHeaderValue, normalizeHeaders } from "./utils/headers.js";
+import { getFrameId, getInitiator } from "./utils/puppeteer-internals.js";
+import { runTriggerActions } from "./utils/trigger-actions.js";
+const toResourceType = (request) => {
+    const type = request.resourceType?.();
+    return type ? type : undefined;
+};
+/**
+ * Internal adapter for the capture plugin.
+ *
+ * Note: this is intentionally NOT published as a separate package.
+ */
+export class PuppeteerAdapter {
+    constructor(options = {}) {
+        this.name = "puppeteer";
+        this.capabilities = {
+            canGetResponseBody: true,
+            canStreamResponseBody: false,
+            canGetRequestBody: false,
+            providesResourceType: true,
+            canWaitForHtml: true,
+            supportsStagedCapture: true
+        };
+        this.options = options;
+    }
+    async start(target, handlers, _options) {
+        let browser = this.options.browser;
+        let page = this.options.page;
+        let ownsBrowser = false;
+        let ownsPage = false;
+        if (target.kind === "puppeteer-page") {
+            page = target.page;
+        }
+        else if (target.kind === "url" || target.kind === "html") {
+            if (!page) {
+                if (!browser) {
+                    const doLaunch = this.options.launch ?? puppeteer.launch;
+                    const envExecutablePath = getEnvString("PUPPETEER_EXECUTABLE_PATH");
+                    const launchOptionsFromUser = this.options.launchOptions;
+                    const executablePath = launchOptionsFromUser?.executablePath ?? envExecutablePath;
+                    try {
+                        browser = await doLaunch({
+                            ...launchOptionsFromUser,
+                            ...(executablePath ? { executablePath } : {}),
+                            headless: false
+                        });
+                    }
+                    catch (error) {
+                        if (!isMissingChromeError(error)) {
+                            throw error;
+                        }
+                        const message = error && typeof error.message === "string"
+                            ? error.message
+                            : String(error);
+                        throw new Error(`${message}\n\n${buildMissingChromeHelp()}`);
+                    }
+                    ownsBrowser = true;
+                }
+                page = await browser.newPage();
+                ownsPage = true;
+            }
+        }
+        else {
+            throw new Error("PuppeteerAdapter only supports url, html, or puppeteer-page targets.");
+        }
+        if (!page || typeof page.on !== "function") {
+            throw new Error("PuppeteerAdapter requires a Puppeteer Page instance.");
+        }
+        const requestIds = new WeakMap();
+        let requestSequence = 0;
+        const getRequestId = (request) => {
+            const existing = requestIds.get(request);
+            if (existing) {
+                return existing;
+            }
+            const requestId = `pptr-${Date.now()}-${requestSequence++}`;
+            requestIds.set(request, requestId);
+            return requestId;
+        };
+        const emitRequest = (request, timestamp) => {
+            const requestEvent = {
+                type: "request",
+                requestId: getRequestId(request),
+                url: request.url(),
+                method: request.method(),
+                headers: normalizeHeaders(request.headers()),
+                frameId: getFrameId(request),
+                resourceType: toResourceType(request),
+                initiator: getInitiator(request),
+                timestamp
+            };
+            handlers.onEvent(requestEvent);
+        };
+        const onRequest = (request) => {
+            const timestamp = Date.now();
+            emitRequest(request, timestamp);
+        };
+        const onResponse = (response) => {
+            const timestamp = Date.now();
+            const request = response.request();
+            if (!requestIds.has(request)) {
+                emitRequest(request, timestamp);
+            }
+            const headers = normalizeHeaders(response.headers());
+            const isExpectedMissingBody = () => {
+                const method = request.method().toUpperCase();
+                if (method === "OPTIONS" || method === "HEAD") {
+                    return true;
+                }
+                const status = response.status();
+                if (status >= 100 && status < 200) {
+                    return true;
+                }
+                if (status >= 300 && status < 400) {
+                    return true;
+                }
+                if (status === 206) {
+                    // Range / streaming responses are frequently not retrievable via CDP.
+                    // Treat missing bodies as expected to avoid noisy adapter errors.
+                    const contentRange = getHeaderValue(headers, "content-range");
+                    const contentType = getHeaderValue(headers, "content-type") ?? "";
+                    if (contentRange) {
+                        return true;
+                    }
+                    if (/^video\//i.test(contentType) || /^audio\//i.test(contentType)) {
+                        return true;
+                    }
+                }
+                return status === 204 || status === 205 || status === 304;
+            };
+            const responseEvent = {
+                type: "response",
+                requestId: getRequestId(request),
+                url: response.url(),
+                status: response.status(),
+                statusText: response.statusText(),
+                headers,
+                mimeType: getHeaderValue(headers, "content-type"),
+                fromDiskCache: response.fromCache(),
+                fromServiceWorker: response.fromServiceWorker(),
+                timestamp,
+                body: {
+                    kind: "late",
+                    read: async () => {
+                        try {
+                            const buffer = await response.buffer();
+                            return new Uint8Array(buffer);
+                        }
+                        catch (error) {
+                            if (isResponseBodyUnavailableError(error)) {
+                                if (!isExpectedMissingBody()) {
+                                    const method = request.method();
+                                    const status = response.status();
+                                    const url = response.url();
+                                    handlers.onError?.(new Error(`Unexpected missing response body (method=${method} status=${status}) for ${url}`));
+                                }
+                                return new Uint8Array();
+                            }
+                            handlers.onError?.(error);
+                            return new Uint8Array();
+                        }
+                    }
+                }
+            };
+            handlers.onEvent(responseEvent);
+        };
+        const onRequestFailed = (request) => {
+            const timestamp = Date.now();
+            const failure = request.failure?.();
+            const hadRequest = requestIds.has(request);
+            const requestId = getRequestId(request);
+            if (!hadRequest) {
+                emitRequest(request, timestamp);
+            }
+            const failedEvent = {
+                type: "failed",
+                requestId,
+                url: request.url(),
+                errorText: failure?.errorText ?? "Request failed",
+                timestamp
+            };
+            handlers.onEvent(failedEvent);
+        };
+        page.on("request", onRequest);
+        page.on("response", onResponse);
+        page.on("requestfailed", onRequestFailed);
+        let navigationPromise = null;
+        const navigate = async (url, options) => {
+            navigationPromise = page.goto(url, {
+                ...this.options.gotoOptions,
+                ...options
+            });
+            await navigationPromise;
+        };
+        const ensureHtmlTargetLoaded = async () => {
+            if (target.kind !== "html") {
+                return;
+            }
+            const baseTag = `<base href="${target.baseUrl}">`;
+            const alreadyHasBase = /<base\s+/i.test(target.htmlString);
+            const htmlWithBase = alreadyHasBase
+                ? target.htmlString
+                : target.htmlString.replace(/<head(\s[^>]*)?>/i, (match) => `${match}${baseTag}`);
+            await page.setContent(htmlWithBase, { waitUntil: "domcontentloaded" });
+        };
+        let htmlLoaded = false;
+        const whenHtmlLoaded = async () => {
+            if (htmlLoaded) {
+                return;
+            }
+            if (target.kind === "url") {
+                await (navigationPromise ?? navigate(target.url));
+            }
+            else if (target.kind === "html") {
+                await ensureHtmlTargetLoaded();
+            }
+            htmlLoaded = true;
+        };
+        const waitForHtml = async () => {
+            if (target.kind === "html") {
+                return {
+                    htmlString: target.htmlString,
+                    baseUrl: target.baseUrl,
+                    url: target.url,
+                    contentType: "text/html"
+                };
+            }
+            await whenHtmlLoaded();
+            return readDomHtml(page);
+        };
+        const getDomHtml = async () => {
+            await whenHtmlLoaded();
+            return readDomHtml(page);
+        };
+        const startCapture = async () => {
+            await whenHtmlLoaded();
+            await runTriggerActions(page, this.options.triggerActions);
+        };
+        return {
+            navigate: target.kind === "url" ? navigate : undefined,
+            waitForHtml,
+            getDomHtml,
+            startCapture,
+            stop: async () => {
+                page.off("request", onRequest);
+                page.off("response", onResponse);
+                page.off("requestfailed", onRequestFailed);
+                if (ownsPage) {
+                    await page.close();
+                }
+                if (ownsBrowser && browser) {
+                    await browser.close();
+                }
+            }
+        };
+    }
+}

package/dist/internal/utils/dom-html.d.ts

@@ -0,0 +1,13 @@
+import type { Page } from "puppeteer";
+/**
+ * Reads the current page DOM as HTML.
+ *
+ * This is used both for the early HTML milestone (`html@1`) and the post-load
+ * DOM snapshot (`dom-html@1`).
+ */
+export declare const readDomHtml: (page: Page) => Promise<{
+    htmlString: string;
+    baseUrl: string;
+    url: string;
+    contentType: string;
+}>;

package/dist/internal/utils/dom-html.js

@@ -0,0 +1,15 @@
+/**
+ * Reads the current page DOM as HTML.
+ *
+ * This is used both for the early HTML milestone (`html@1`) and the post-load
+ * DOM snapshot (`dom-html@1`).
+ */
+export const readDomHtml = async (page) => {
+    const [url, htmlString] = await Promise.all([page.url(), page.content()]);
+    return {
+        htmlString,
+        baseUrl: url,
+        url,
+        contentType: "text/html"
+    };
+};

package/dist/internal/utils/env.d.ts

@@ -0,0 +1 @@
+export declare const getEnvString: (name: string) => string | undefined;

package/dist/internal/utils/env.js

@@ -0,0 +1,5 @@
+export const getEnvString = (name) => {
+    const value = globalThis.process
+        ?.env?.[name];
+    return value && value.trim().length > 0 ? value.trim() : undefined;
+};

package/dist/internal/utils/errors.d.ts

@@ -0,0 +1,10 @@
+export declare const isMissingChromeError: (error: unknown) => boolean;
+export declare const buildMissingChromeHelp: () => string;
+export declare const isNoDataForResourceError: (error: unknown) => boolean;
+/**
+ * True when Puppeteer/CDP signals the response body is not available.
+ *
+ * This is not always an error. For example, CORS preflight requests (OPTIONS)
+ * or 204/304 responses may legitimately have no retrievable body.
+ */
+export declare const isResponseBodyUnavailableError: (error: unknown) => boolean;

package/dist/internal/utils/errors.js

@@ -0,0 +1,52 @@
+export const isMissingChromeError = (error) => {
+    const message = error && typeof error.message === "string"
+        ? error.message
+        : "";
+    return message.includes("Could not find Chrome") || message.includes("Could not find Chromium");
+};
+export const buildMissingChromeHelp = () => {
+    return `Puppeteer could not find a compatible Chrome installation.
+
+Reason:
+  This machine does not have a Chrome executable available to Puppeteer.
+
+Fix options:
+  1) Install Chrome for Puppeteer (recommended):
+     - pnpm dlx puppeteer browsers install chrome
+     - or: npx puppeteer browsers install chrome
+
+  2) Use an existing system Chrome/Chromium:
+     - Set PUPPETEER_EXECUTABLE_PATH=/path/to/chrome
+`;
+};
+export const isNoDataForResourceError = (error) => {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const message = error.message;
+    if (typeof message !== "string") {
+        return false;
+    }
+    return message.includes("Network.getResponseBody") && message.includes("No data found");
+};
+/**
+ * True when Puppeteer/CDP signals the response body is not available.
+ *
+ * This is not always an error. For example, CORS preflight requests (OPTIONS)
+ * or 204/304 responses may legitimately have no retrievable body.
+ */
+export const isResponseBodyUnavailableError = (error) => {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const message = error.message;
+    if (typeof message !== "string") {
+        return false;
+    }
+    if (isNoDataForResourceError(error)) {
+        return true;
+    }
+    return (message.includes("Could not load body for this request") ||
+        message.includes("No resource with given identifier found") ||
+        message.includes("Response body is unavailable for redirect responses"));
+};

package/dist/internal/utils/headers.d.ts

@@ -0,0 +1,2 @@
+export declare const normalizeHeaders: (headers: Record<string, string | number | boolean | undefined>) => Record<string, string>;
+export declare const getHeaderValue: (headers: Record<string, string>, name: string) => string | undefined;

package/dist/internal/utils/headers.js

@@ -0,0 +1,19 @@
+export const normalizeHeaders = (headers) => {
+    const output = {};
+    for (const key in headers) {
+        const value = headers[key];
+        if (value === undefined)
+            continue;
+        output[key] = typeof value === "string" ? value : String(value);
+    }
+    return output;
+};
+export const getHeaderValue = (headers, name) => {
+    const target = name.toLowerCase();
+    for (const key in headers) {
+        if (key.toLowerCase() === target) {
+            return headers[key];
+        }
+    }
+    return undefined;
+};

package/dist/internal/utils/puppeteer-internals.d.ts

@@ -0,0 +1,6 @@
+import type { HTTPRequest } from "puppeteer";
+export declare const getFrameId: (request: HTTPRequest) => string | undefined;
+export declare const getInitiator: (request: HTTPRequest) => {
+    type: string | undefined;
+    url: string | undefined;
+} | undefined;

package/dist/internal/utils/puppeteer-internals.js

@@ -0,0 +1,23 @@
+export const getFrameId = (request) => {
+    const frame = request.frame();
+    if (!frame)
+        return undefined;
+    const frameRef = frame;
+    if (frameRef._id)
+        return frameRef._id;
+    if (frameRef._frameId)
+        return frameRef._frameId;
+    if (typeof frameRef.id === "function")
+        return frameRef.id();
+    return undefined;
+};
+export const getInitiator = (request) => {
+    const requestRef = request;
+    const initiator = requestRef.initiator?.();
+    if (!initiator)
+        return undefined;
+    return {
+        type: initiator.type,
+        url: initiator.url
+    };
+};

package/dist/internal/utils/trigger-actions.d.ts

@@ -0,0 +1,3 @@
+import type { TriggerAction } from "@pagepocket/lib";
+import type { Page } from "puppeteer";
+export declare const runTriggerActions: (page: Page, actions?: TriggerAction[]) => Promise<void>;

package/dist/internal/utils/trigger-actions.js

@@ -0,0 +1,36 @@
+export const runTriggerActions = async (page, actions = []) => {
+    if (actions.length === 0)
+        return;
+    await page.evaluate((actionsArg) => {
+        const hoverAll = () => {
+            const elements = Array.from(document.querySelectorAll("*"));
+            const trigger = (el) => {
+                const rect = el.getBoundingClientRect();
+                const x = rect.left + rect.width / 2;
+                const y = rect.top + rect.height / 2;
+                const event = new MouseEvent("mouseover", {
+                    bubbles: true,
+                    cancelable: true,
+                    clientX: x,
+                    clientY: y
+                });
+                el.dispatchEvent(event);
+            };
+            elements.forEach(trigger);
+        };
+        const scrollToEnd = () => {
+            const scrollHeight = document.documentElement?.scrollHeight ?? document.body?.scrollHeight;
+            if (typeof scrollHeight === "number") {
+                window.scrollTo({ top: scrollHeight, behavior: "instant" });
+            }
+        };
+        for (const action of actionsArg) {
+            if (action === "HOVER") {
+                hoverAll();
+            }
+            if (action === "SCROLL_TO_END") {
+                scrollToEnd();
+            }
+        }
+    }, actions);
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@pagepocket/capture-http-puppeteer-unit",
+  "version": "0.8.0",
+  "description": "PagePocket plugin: capture HTTP events (puppeteer adapter)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "puppeteer": "^22.12.1",
+    "@pagepocket/lib": "0.8.0",
+    "@pagepocket/contracts": "0.8.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node -e \"process.exit(0)\""
+  }
+}