@pagepocket/capture-http-cdp-unit 0.8.0

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

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

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

@@ -0,0 +1,132 @@
+import { createMemoryContentStore } from "@pagepocket/lib";
+import { InflightTracker, networkIdle, normalizeCompletion, timeout } from "@pagepocket/lib";
+import { CdpAdapter } from "./internal/cdp-adapter.js";
+const headersRecordToList = (headers) => {
+    if (!headers)
+        return [];
+    return Object.keys(headers).map((name) => ({ name, value: headers[name] }));
+};
+export class CaptureHttpCdpPlugin {
+    constructor(options) {
+        this.name = "plugin:capture-http-cdp";
+        this.adapterOptions = options ?? {};
+    }
+    apply(ctx) {
+        const contentStore = createMemoryContentStore("capture-http-cdp");
+        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 = "captureHttpCdp.session";
+        ctx.onInit(async () => {
+            if (ctx.entry.kind !== "cdp-tab") {
+                throw new Error(`CaptureHttpCdpPlugin requires entry kind "cdp-tab" (got ${String(ctx.entry.kind)})`);
+            }
+            const adapter = new CdpAdapter(this.adapterOptions);
+            const session = await adapter.start({ kind: "cdp-tab", tabId: ctx.entry.tabId }, {
+                onEvent(event) {
+                    void handleNetworkEvent(event);
+                },
+                onError(error) {
+                    // eslint-disable-next-line no-console
+                    console.warn("[pagepocket][capture-http-cdp] adapter error", error);
+                }
+            }, {
+                timeoutMs: ctx.options.timeoutMs,
+                maxDurationMs: ctx.options.maxDurationMs
+            });
+            ctx.state[stateKey] = session;
+            if (!ctx.html) {
+                const html = await session.waitForHtml();
+                ctx.setHtml(html);
+            }
+        });
+        ctx.onBeforeNetwork(async () => {
+            const session = ctx.state[stateKey];
+            if (!session) {
+                throw new Error("CaptureHttpCdpPlugin 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-cdp-unit.d.ts

@@ -0,0 +1,13 @@
+import { Unit, type CaptureArtifacts } from "@pagepocket/lib";
+import { type CdpAdapterOptions } from "./internal/cdp-adapter.js";
+export type CaptureHttpCdpUnitOptions = CdpAdapterOptions;
+export declare class CaptureHttpCdpUnit extends Unit {
+    readonly id = "captureHttpCdp";
+    readonly kind = "capture.http.cdp";
+    private adapterOptions;
+    constructor(options?: CaptureHttpCdpUnitOptions);
+    run(ctx: import("@pagepocket/lib").UnitContext, rt: import("@pagepocket/lib").UnitRuntime): Promise<{
+        capture: CaptureArtifacts;
+        html: {};
+    }>;
+}

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

@@ -0,0 +1,123 @@
+import { NETWORK } from "@pagepocket/contracts";
+import { Unit, createMemoryContentStore, InflightTracker, mapKind, networkIdle, normalizeCompletion, throwRequiredEntryKind, timeout } from "@pagepocket/lib";
+import { CdpAdapter } from "./internal/cdp-adapter.js";
+const headersRecordToList = (headers) => {
+    if (!headers)
+        return [];
+    return Object.keys(headers).map((name) => ({ name, value: headers[name] }));
+};
+const targetBuilders = {
+    "cdp-tab": (entry) => ({
+        kind: "cdp-tab",
+        tabId: entry.tabId
+    })
+};
+export class CaptureHttpCdpUnit extends Unit {
+    constructor(options) {
+        super();
+        this.id = "captureHttpCdp";
+        this.kind = "capture.http.cdp";
+        this.adapterOptions = options ?? {};
+    }
+    async run(ctx, rt) {
+        const target = mapKind(rt.entry, targetBuilders, {
+            onUnsupportedKind: throwRequiredEntryKind("CaptureHttpCdpUnit", "cdp-tab")
+        });
+        const contentStore = createMemoryContentStore("capture-http-cdp");
+        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 CdpAdapter(this.adapterOptions);
+        const session = await adapter.start(target, {
+            onEvent: (event) => {
+                void handleNetworkEvent(event);
+            },
+            onError: (error) => {
+                console.warn("[pagepocket][capture-http-cdp] adapter error", error);
+            }
+        }, {
+            timeoutMs: rt.options.timeoutMs,
+            maxDurationMs: rt.options.maxDurationMs
+        });
+        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()
+            })));
+        }
+        await session.stop();
+        return { capture, html };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { CaptureHttpCdpUnit } from "./capture-http-cdp-unit.js";
+export type { CaptureHttpCdpUnitOptions } from "./capture-http-cdp-unit.js";

package/dist/index.js

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

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

@@ -0,0 +1,29 @@
+import type { InterceptSession, InterceptTarget, NetworkEventHandlers, NetworkInterceptorAdapter, TriggerAction } from "@pagepocket/lib";
+import type { CdpClient } from "./types.js";
+export type CdpAdapterOptions = {
+    protocolVersion?: string;
+    clientFactory?: (options?: {
+        tabId: number;
+        protocolVersion: string;
+    }) => Promise<CdpClient> | CdpClient;
+    triggerActions?: TriggerAction[];
+};
+/**
+ * Internal adapter for the capture plugin.
+ *
+ * Note: this is intentionally NOT published as a separate package.
+ */
+export declare class CdpAdapter implements NetworkInterceptorAdapter {
+    readonly name = "cdp";
+    readonly capabilities: {
+        canGetResponseBody: boolean;
+        canStreamResponseBody: boolean;
+        canGetRequestBody: boolean;
+        providesResourceType: boolean;
+        canWaitForHtml: boolean;
+        supportsStagedCapture: boolean;
+    };
+    private options;
+    constructor(options?: CdpAdapterOptions);
+    start(target: InterceptTarget, handlers: NetworkEventHandlers, _options?: Record<string, unknown>): Promise<InterceptSession>;
+}

package/dist/internal/cdp-adapter.js

@@ -0,0 +1,40 @@
+import { createChromeDebuggerClient } from "./chrome-debugger-client.js";
+import { createCdpSession } from "./session.js";
+/**
+ * Internal adapter for the capture plugin.
+ *
+ * Note: this is intentionally NOT published as a separate package.
+ */
+export class CdpAdapter {
+    constructor(options = {}) {
+        this.name = "cdp";
+        this.capabilities = {
+            canGetResponseBody: true,
+            canStreamResponseBody: false,
+            canGetRequestBody: false,
+            providesResourceType: true,
+            canWaitForHtml: true,
+            supportsStagedCapture: true
+        };
+        this.options = options;
+    }
+    async start(target, handlers, _options) {
+        if (target.kind !== "cdp-tab") {
+            throw new Error("CdpAdapter only supports cdp-tab targets.");
+        }
+        const protocolVersion = this.options.protocolVersion ?? "1.3";
+        const clientFactory = this.options.clientFactory;
+        const client = (await clientFactory?.({ tabId: target.tabId, protocolVersion })) ??
+            createChromeDebuggerClient({ tabId: target.tabId }, protocolVersion);
+        const ownsClient = true;
+        const base = await createCdpSession({
+            client,
+            handlers,
+            ownsClient,
+            triggerActions: this.options.triggerActions
+        });
+        // `cdp-tab` sessions already support `waitForHtml()` and `startCapture()`.
+        // This wrapper exists to keep this adapter entry point contained.
+        return base;
+    }
+}

package/dist/internal/cdp-utils.d.ts

@@ -0,0 +1,11 @@
+import type { ResourceType } from "@pagepocket/lib";
+import type { CdpClient } from "./types.js";
+export declare const decodeBase64: (input: string) => Uint8Array<ArrayBuffer>;
+export declare const encodeUtf8: (input: string) => Uint8Array<ArrayBuffer>;
+export declare const normalizeHeaders: (headers?: Record<string, unknown>) => Record<string, string>;
+export declare const mapResourceType: (input?: string) => ResourceType | undefined;
+export declare const inferResourceTypeFromMime: (mimeType?: string) => ResourceType | undefined;
+export declare const callCdp: <T>(client: CdpClient, method: string, params?: Record<string, unknown>) => Promise<T>;
+export declare const subscribe: (client: CdpClient, eventName: string, handler: (payload: unknown) => void) => () => void | undefined;
+export declare const isNoBodyError: (error: unknown) => boolean;
+export declare const logInfo: (label: string, data: Record<string, unknown>) => void;

package/dist/internal/cdp-utils.js

@@ -0,0 +1,112 @@
+export const decodeBase64 = (input) => {
+    const bufferCtor = globalThis.Buffer;
+    if (bufferCtor) {
+        return new Uint8Array(bufferCtor.from(input, "base64"));
+    }
+    const binary = atob(input);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+};
+export const encodeUtf8 = (input) => new TextEncoder().encode(input);
+export const normalizeHeaders = (headers) => {
+    const output = {};
+    if (!headers)
+        return output;
+    for (const key of Object.keys(headers)) {
+        const value = headers[key];
+        if (value === undefined || value === null)
+            continue;
+        output[key] = Array.isArray(value) ? value.join(", ") : String(value);
+    }
+    return output;
+};
+export const mapResourceType = (input) => {
+    if (!input)
+        return undefined;
+    const normalized = input.toLowerCase();
+    switch (normalized) {
+        case "document":
+            return "document";
+        case "stylesheet":
+            return "stylesheet";
+        case "script":
+            return "script";
+        case "image":
+            return "image";
+        case "font":
+            return "font";
+        case "media":
+            return "media";
+        case "xhr":
+            return "xhr";
+        case "fetch":
+            return "fetch";
+        case "other":
+            return "other";
+        default:
+            return normalized;
+    }
+};
+export const inferResourceTypeFromMime = (mimeType) => {
+    if (!mimeType)
+        return undefined;
+    const normalized = mimeType.toLowerCase();
+    if (normalized.includes("text/html") || normalized.includes("application/xhtml+xml")) {
+        return "document";
+    }
+    if (normalized.includes("text/css")) {
+        return "stylesheet";
+    }
+    if (normalized.includes("javascript") || normalized.includes("ecmascript")) {
+        return "script";
+    }
+    if (normalized.startsWith("image/")) {
+        return "image";
+    }
+    if (normalized.startsWith("font/") ||
+        normalized.includes("woff") ||
+        normalized.includes("ttf") ||
+        normalized.includes("otf")) {
+        return "font";
+    }
+    if (normalized.startsWith("audio/") || normalized.startsWith("video/")) {
+        return "media";
+    }
+    return undefined;
+};
+export const callCdp = async (client, method, params) => {
+    if (typeof client.send === "function") {
+        return (await client.send(method, params));
+    }
+    const [domain, command] = method.split(".");
+    const domainApi = client[domain];
+    const fn = domainApi?.[command];
+    if (typeof fn === "function") {
+        return (await fn(params));
+    }
+    throw new Error(`CDP session missing method ${method}.`);
+};
+export const subscribe = (client, eventName, handler) => {
+    if (typeof client.on === "function") {
+        client.on(eventName, handler);
+        return () => client.off?.(eventName, handler);
+    }
+    const [domain, event] = eventName.split(".");
+    const domainApi = client[domain];
+    const fn = domainApi?.[event];
+    if (typeof fn === "function") {
+        fn(handler);
+        return () => undefined;
+    }
+    throw new Error(`CDP session missing event ${eventName}.`);
+};
+export const isNoBodyError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("No data found for resource with given identifier");
+};
+export const logInfo = (label, data) => {
+    console.info(`[pagepocket][cdp-adapter] ${label} ${JSON.stringify(data)}`);
+};

package/dist/internal/chrome-debugger-client.d.ts

@@ -0,0 +1,2 @@
+import type { CdpClient, ChromeDebuggerTarget } from "./types.js";
+export declare const createChromeDebuggerClient: (target: ChromeDebuggerTarget, protocolVersion: string) => CdpClient;

package/dist/internal/chrome-debugger-client.js

@@ -0,0 +1,89 @@
+const getChromeGlobal = () => globalThis.chrome;
+export const createChromeDebuggerClient = (target, protocolVersion) => {
+    const chromeGlobal = getChromeGlobal();
+    const chromeDebugger = chromeGlobal?.debugger;
+    if (!chromeDebugger) {
+        throw new Error("chrome.debugger API is not available in this environment.");
+    }
+    const chromeRuntime = chromeGlobal?.runtime;
+    let attached = false;
+    let closed = false;
+    const listeners = new Map();
+    const assertNoLastError = (action) => {
+        const lastError = chromeRuntime?.lastError;
+        if (lastError?.message) {
+            throw new Error(`${action} failed: ${lastError.message}`);
+        }
+    };
+    const attach = () => new Promise((resolve, reject) => {
+        chromeDebugger.attach(target, protocolVersion, () => {
+            try {
+                assertNoLastError("chrome.debugger.attach");
+                attached = true;
+                resolve();
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+    const detach = () => new Promise((resolve, reject) => {
+        chromeDebugger.detach(target, () => {
+            try {
+                assertNoLastError("chrome.debugger.detach");
+                attached = false;
+                resolve();
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+    const ensureAttached = async () => {
+        if (attached)
+            return;
+        await attach();
+    };
+    return {
+        send: async (method, params) => {
+            await ensureAttached();
+            return new Promise((resolve, reject) => {
+                chromeDebugger.sendCommand(target, method, params ?? {}, (result) => {
+                    try {
+                        assertNoLastError(`chrome.debugger.sendCommand(${method})`);
+                        resolve(result);
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                });
+            });
+        },
+        on: (event, listener) => {
+            const handler = (source, method, params) => {
+                if (source.tabId !== target.tabId)
+                    return;
+                if (method !== event)
+                    return;
+                listener(params);
+            };
+            listeners.set(listener, handler);
+            chromeDebugger.onEvent.addListener(handler);
+        },
+        off: (_event, listener) => {
+            const handler = listeners.get(listener);
+            if (!handler)
+                return;
+            listeners.delete(listener);
+            chromeDebugger.onEvent.removeListener(handler);
+        },
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            if (!attached)
+                return;
+            await detach();
+        }
+    };
+};

package/dist/internal/page-actions.d.ts

@@ -0,0 +1,6 @@
+import { type NetworkEventHandlers, type TriggerAction } from "@pagepocket/lib";
+import type { CdpClient } from "./types.js";
+export declare const createPageActions: (client: CdpClient, handlers: NetworkEventHandlers) => {
+    ensurePageEnabled: () => Promise<void>;
+    runTriggerActions: (actions?: TriggerAction[]) => Promise<void>;
+};

package/dist/internal/page-actions.js

@@ -0,0 +1,58 @@
+import { TriggerActionValues } from "@pagepocket/lib";
+import { callCdp } from "./cdp-utils.js";
+export const createPageActions = (client, handlers) => {
+    const ensurePageEnabled = async () => {
+        try {
+            await callCdp(client, "Page.enable");
+        }
+        catch {
+            // Page domain may be unavailable; ignore.
+        }
+    };
+    const runTriggerActions = async (actions = []) => {
+        if (actions.length === 0) {
+            return;
+        }
+        await ensurePageEnabled();
+        for (const action of actions) {
+            if (action === TriggerActionValues.HOVER) {
+                try {
+                    await callCdp(client, "Runtime.evaluate", {
+                        expression: `(() => {
+              const elements = Array.from(document.querySelectorAll('*'));
+              for (const el of elements) {
+                const rect = el.getBoundingClientRect();
+                const x = rect.left + rect.width / 2;
+                const y = rect.top + rect.height / 2;
+                const ev = new MouseEvent('mouseover', { bubbles: true, cancelable: true, clientX: x, clientY: y });
+                el.dispatchEvent(ev);
+              }
+            })();`
+                    });
+                }
+                catch (error) {
+                    handlers.onError?.(error);
+                }
+            }
+            if (action === TriggerActionValues.SCROLL_TO_END) {
+                try {
+                    await callCdp(client, "Runtime.evaluate", {
+                        expression: `(() => {
+              const scrollHeight = document.documentElement?.scrollHeight ?? document.body?.scrollHeight;
+              if (typeof scrollHeight === 'number') {
+                window.scrollTo({ top: scrollHeight, behavior: 'instant' });
+              }
+            })();`
+                    });
+                }
+                catch (error) {
+                    handlers.onError?.(error);
+                }
+            }
+        }
+    };
+    return {
+        ensurePageEnabled,
+        runTriggerActions
+    };
+};

package/dist/internal/session/html-milestone.d.ts

@@ -0,0 +1,16 @@
+type HtmlArtifact = {
+    htmlString: string;
+    baseUrl: string;
+    url?: string;
+    contentType?: string;
+};
+export declare const createHtmlMilestone: () => {
+    htmlPromise: Promise<never>;
+    tryResolveHtml: (input: {
+        url: string;
+        contentType?: string;
+        bodyBytes: Uint8Array | null;
+    }) => void;
+    getHtmlArtifact: () => HtmlArtifact | null;
+};
+export {};

package/dist/internal/session/html-milestone.js

@@ -0,0 +1,29 @@
+export const createHtmlMilestone = () => {
+    let htmlArtifact = null;
+    let resolveHtml = null;
+    const htmlPromise = new Promise((resolve, _reject) => {
+        resolveHtml = resolve;
+    });
+    const tryResolveHtml = (input) => {
+        if (htmlArtifact) {
+            return;
+        }
+        if (!input.bodyBytes || input.bodyBytes.byteLength === 0) {
+            return;
+        }
+        const htmlString = new TextDecoder().decode(input.bodyBytes);
+        htmlArtifact = {
+            htmlString,
+            baseUrl: input.url,
+            url: input.url,
+            contentType: input.contentType
+        };
+        resolveHtml?.(htmlArtifact);
+        resolveHtml = null;
+    };
+    return {
+        htmlPromise,
+        tryResolveHtml,
+        getHtmlArtifact: () => htmlArtifact
+    };
+};

package/dist/internal/session/request-state.d.ts

@@ -0,0 +1,27 @@
+import type { NetworkEventHandlers, NetworkRequestEvent } from "@pagepocket/lib";
+import type { RequestInfo, RequestWillBeSent, ResponseReceived } from "../types.js";
+export declare const createRequestState: (handlers: NetworkEventHandlers) => {
+    activeRequestId: Map<string, string>;
+    requestUrls: Map<string, string>;
+    requestInfo: Map<string, RequestInfo>;
+    requestEvents: Map<string, NetworkRequestEvent>;
+    getLogicalRequestId: (cdpRequestId: string) => string;
+    handleRequestWillBeSent: (payload: RequestWillBeSent, timestampMs: number) => {
+        cdpRequestId: string;
+        logicalRequestId: string;
+    };
+    handleResponseReceived: (payload: ResponseReceived, timestampMs: number) => {
+        cdpRequestId: string;
+        logicalRequestId: string;
+        response: {
+            url: string;
+            status: number;
+            statusText?: string;
+            headers?: Record<string, unknown>;
+            mimeType?: string;
+            fromDiskCache?: boolean;
+            fromServiceWorker?: boolean;
+        };
+        resolvedType: import("@pagepocket/lib").ResourceType | undefined;
+    };
+};

package/dist/internal/session/request-state.js

@@ -0,0 +1,110 @@
+import { inferResourceTypeFromMime, mapResourceType, normalizeHeaders } from "../cdp-utils.js";
+export const createRequestState = (handlers) => {
+    const activeRequestId = new Map();
+    const requestSequence = new Map();
+    const requestUrls = new Map();
+    const requestInfo = new Map();
+    const requestEvents = new Map();
+    const getLogicalRequestId = (cdpRequestId) => activeRequestId.get(cdpRequestId) ?? `${cdpRequestId}:0`;
+    const handleRequestWillBeSent = (payload, timestampMs) => {
+        const cdpRequestId = payload.requestId;
+        if (payload.redirectResponse) {
+            const previousRequestId = getLogicalRequestId(cdpRequestId);
+            const redirectResponse = payload.redirectResponse;
+            const redirectEvent = {
+                type: "response",
+                requestId: previousRequestId,
+                url: redirectResponse.url,
+                status: redirectResponse.status,
+                statusText: redirectResponse.statusText ?? "",
+                headers: normalizeHeaders(redirectResponse.headers),
+                mimeType: redirectResponse.mimeType,
+                fromDiskCache: redirectResponse.fromDiskCache,
+                fromServiceWorker: redirectResponse.fromServiceWorker,
+                timestamp: timestampMs
+            };
+            handlers.onEvent(redirectEvent);
+        }
+        const sequence = (requestSequence.get(cdpRequestId) ?? -1) + 1;
+        requestSequence.set(cdpRequestId, sequence);
+        const logicalRequestId = `${cdpRequestId}:${sequence}`;
+        activeRequestId.set(cdpRequestId, logicalRequestId);
+        const url = payload.request.url;
+        requestUrls.set(logicalRequestId, url);
+        requestInfo.set(cdpRequestId, {
+            url,
+            frameId: payload.frameId,
+            resourceType: mapResourceType(payload.type),
+            initiator: payload.initiator
+        });
+        const requestEvent = {
+            type: "request",
+            requestId: logicalRequestId,
+            url,
+            method: payload.request.method || "GET",
+            headers: normalizeHeaders(payload.request.headers),
+            frameId: payload.frameId,
+            resourceType: mapResourceType(payload.type),
+            initiator: payload.initiator,
+            timestamp: timestampMs
+        };
+        requestEvents.set(cdpRequestId, requestEvent);
+        handlers.onEvent(requestEvent);
+        return { cdpRequestId, logicalRequestId };
+    };
+    const handleResponseReceived = (payload, timestampMs) => {
+        const cdpRequestId = payload.requestId;
+        const logicalRequestId = getLogicalRequestId(cdpRequestId);
+        const response = payload.response;
+        if (!requestUrls.has(logicalRequestId)) {
+            requestUrls.set(logicalRequestId, response.url);
+        }
+        const storedRequest = requestEvents.get(cdpRequestId);
+        const existingInfo = requestInfo.get(cdpRequestId);
+        const responseType = mapResourceType(payload.type);
+        const inferred = inferResourceTypeFromMime(response.mimeType);
+        const resolvedType = responseType ?? inferred;
+        if ((!existingInfo || !existingInfo.resourceType) && resolvedType) {
+            requestInfo.set(cdpRequestId, {
+                url: response.url,
+                frameId: existingInfo?.frameId ?? payload.frameId,
+                resourceType: resolvedType,
+                initiator: existingInfo?.initiator
+            });
+        }
+        if (!storedRequest && resolvedType) {
+            const synthesizedRequest = {
+                type: "request",
+                requestId: logicalRequestId,
+                url: response.url,
+                method: "GET",
+                headers: {},
+                frameId: payload.frameId,
+                resourceType: resolvedType,
+                initiator: undefined,
+                timestamp: timestampMs
+            };
+            requestEvents.set(cdpRequestId, synthesizedRequest);
+            handlers.onEvent(synthesizedRequest);
+        }
+        else if (storedRequest && resolvedType && !storedRequest.resourceType) {
+            const updatedRequest = {
+                ...storedRequest,
+                resourceType: resolvedType,
+                timestamp: timestampMs
+            };
+            requestEvents.set(cdpRequestId, updatedRequest);
+            handlers.onEvent(updatedRequest);
+        }
+        return { cdpRequestId, logicalRequestId, response, resolvedType };
+    };
+    return {
+        activeRequestId,
+        requestUrls,
+        requestInfo,
+        requestEvents,
+        getLogicalRequestId,
+        handleRequestWillBeSent,
+        handleResponseReceived
+    };
+};

package/dist/internal/session/time.d.ts

@@ -0,0 +1,6 @@
+export declare const createTimestampResolver: () => {
+    resolveTimestampMs: (payload: {
+        timestamp?: number;
+        wallTime?: number;
+    }, requestId?: string) => number;
+};

package/dist/internal/session/time.js

@@ -0,0 +1,24 @@
+export const createTimestampResolver = () => {
+    const requestTimeOffsets = new Map();
+    let globalTimeOffset = null;
+    const resolveTimestampMs = (payload, requestId) => {
+        if (typeof payload.wallTime === "number") {
+            if (typeof payload.timestamp === "number") {
+                const offset = payload.wallTime - payload.timestamp;
+                if (requestId) {
+                    requestTimeOffsets.set(requestId, offset);
+                }
+                globalTimeOffset = offset;
+            }
+            return payload.wallTime * 1000;
+        }
+        if (typeof payload.timestamp === "number") {
+            const offset = (requestId ? requestTimeOffsets.get(requestId) : undefined) ?? globalTimeOffset;
+            if (typeof offset === "number") {
+                return (payload.timestamp + offset) * 1000;
+            }
+        }
+        return Date.now();
+    };
+    return { resolveTimestampMs };
+};

package/dist/internal/session.d.ts

@@ -0,0 +1,10 @@
+import type { InterceptSession, NetworkEventHandlers, TriggerAction } from "@pagepocket/lib";
+import type { CdpClient } from "./types.js";
+type CreateSessionOptions = {
+    client: CdpClient;
+    handlers: NetworkEventHandlers;
+    ownsClient: boolean;
+    triggerActions?: TriggerAction[];
+};
+export declare const createCdpSession: ({ client, handlers, ownsClient, triggerActions }: CreateSessionOptions) => Promise<InterceptSession>;
+export {};

package/dist/internal/session.js

@@ -0,0 +1,191 @@
+import { callCdp, decodeBase64, encodeUtf8, inferResourceTypeFromMime, isNoBodyError, logInfo, normalizeHeaders, subscribe } from "./cdp-utils.js";
+import { createPageActions } from "./page-actions.js";
+import { createHtmlMilestone } from "./session/html-milestone.js";
+import { createRequestState } from "./session/request-state.js";
+import { createTimestampResolver } from "./session/time.js";
+export const createCdpSession = async ({ client, handlers, ownsClient, triggerActions }) => {
+    await callCdp(client, "Network.enable");
+    const { ensurePageEnabled, runTriggerActions } = createPageActions(client, handlers);
+    const { htmlPromise, tryResolveHtml } = createHtmlMilestone();
+    const requestState = createRequestState(handlers);
+    const responses = new Map();
+    const { resolveTimestampMs } = createTimestampResolver();
+    const handleRequestWillBeSent = (payload) => {
+        const cdpRequestId = payload.requestId;
+        const eventTimestamp = resolveTimestampMs(payload, cdpRequestId);
+        requestState.handleRequestWillBeSent(payload, eventTimestamp);
+    };
+    const handleResponseReceived = (payload) => {
+        const cdpRequestId = payload.requestId;
+        const eventTimestamp = resolveTimestampMs(payload, cdpRequestId);
+        const result = requestState.handleResponseReceived(payload, eventTimestamp);
+        logInfo("response received", {
+            requestId: cdpRequestId,
+            url: result.response.url,
+            status: result.response.status,
+            mimeType: result.response.mimeType,
+            fromDiskCache: result.response.fromDiskCache,
+            fromServiceWorker: result.response.fromServiceWorker
+        });
+        responses.set(cdpRequestId, {
+            requestId: result.logicalRequestId,
+            response: result.response
+        });
+    };
+    const tryGetResponseBody = async (cdpRequestId) => {
+        try {
+            const result = await callCdp(client, "Network.getResponseBody", { requestId: cdpRequestId });
+            if (result.base64Encoded) {
+                return decodeBase64(result.body);
+            }
+            return encodeUtf8(result.body);
+        }
+        catch (error) {
+            if (isNoBodyError(error)) {
+                return null;
+            }
+            throw error;
+        }
+    };
+    const tryGetPageResourceContent = async (info) => {
+        if (!info.frameId || !info.url) {
+            return null;
+        }
+        try {
+            const result = await callCdp(client, "Page.getResourceContent", {
+                frameId: info.frameId,
+                url: info.url
+            });
+            if (result.base64Encoded) {
+                return decodeBase64(result.content);
+            }
+            return encodeUtf8(result.content);
+        }
+        catch {
+            return null;
+        }
+    };
+    const handleLoadingFinished = async (payload) => {
+        const cdpRequestId = payload.requestId;
+        const eventTimestamp = resolveTimestampMs(payload, cdpRequestId);
+        const storedResponse = responses.get(cdpRequestId);
+        if (!storedResponse) {
+            logInfo("loadingFinished without response", {
+                requestId: cdpRequestId
+            });
+            return;
+        }
+        const inferred = inferResourceTypeFromMime(storedResponse.response.mimeType);
+        const infoFromMime = requestState.requestInfo.get(cdpRequestId);
+        if ((!infoFromMime || !infoFromMime.resourceType) && inferred) {
+            requestState.requestInfo.set(cdpRequestId, {
+                url: storedResponse.response.url,
+                frameId: infoFromMime?.frameId,
+                resourceType: inferred,
+                initiator: infoFromMime?.initiator
+            });
+            const storedRequest = requestState.requestEvents.get(cdpRequestId);
+            if (storedRequest && !storedRequest.resourceType) {
+                const updatedRequest = {
+                    ...storedRequest,
+                    resourceType: inferred
+                };
+                requestState.requestEvents.set(cdpRequestId, updatedRequest);
+                handlers.onEvent(updatedRequest);
+            }
+        }
+        let bodyBytes = null;
+        try {
+            bodyBytes = await tryGetResponseBody(cdpRequestId);
+        }
+        catch (error) {
+            handlers.onError?.(error instanceof Error ? error : new Error(String(error)));
+        }
+        if (bodyBytes && bodyBytes.byteLength === 0) {
+            bodyBytes = null;
+        }
+        if (!bodyBytes) {
+            const fallbackInfo = requestState.requestInfo.get(cdpRequestId);
+            if (fallbackInfo?.frameId) {
+                bodyBytes = await tryGetPageResourceContent(fallbackInfo);
+            }
+        }
+        logInfo("response body status", {
+            requestId: cdpRequestId,
+            url: storedResponse.response.url,
+            resourceType: requestState.requestInfo.get(cdpRequestId)?.resourceType,
+            bodyBytes: bodyBytes ? bodyBytes.byteLength : 0
+        });
+        const responseEvent = {
+            type: "response",
+            requestId: storedResponse.requestId,
+            url: storedResponse.response.url,
+            status: storedResponse.response.status,
+            statusText: storedResponse.response.statusText,
+            headers: normalizeHeaders(storedResponse.response.headers),
+            mimeType: storedResponse.response.mimeType,
+            fromDiskCache: storedResponse.response.fromDiskCache,
+            fromServiceWorker: storedResponse.response.fromServiceWorker,
+            timestamp: eventTimestamp,
+            body: bodyBytes ? { kind: "buffer", data: bodyBytes } : undefined
+        };
+        handlers.onEvent(responseEvent);
+        const infoForHtml = requestState.requestInfo.get(cdpRequestId);
+        if (infoForHtml?.resourceType === "document") {
+            tryResolveHtml({
+                url: storedResponse.response.url,
+                contentType: storedResponse.response.mimeType,
+                bodyBytes
+            });
+        }
+    };
+    const handleLoadingFailed = (payload) => {
+        const cdpRequestId = payload.requestId;
+        const logicalRequestId = requestState.getLogicalRequestId(cdpRequestId);
+        const url = requestState.requestUrls.get(logicalRequestId) ?? "";
+        const failedEvent = {
+            type: "failed",
+            requestId: logicalRequestId,
+            url,
+            errorText: payload.errorText,
+            timestamp: resolveTimestampMs(payload, cdpRequestId)
+        };
+        handlers.onEvent(failedEvent);
+    };
+    const cleanupHandlers = [];
+    try {
+        cleanupHandlers.push(subscribe(client, "Network.requestWillBeSent", (payload) => handleRequestWillBeSent(payload)));
+        cleanupHandlers.push(subscribe(client, "Network.responseReceived", (payload) => handleResponseReceived(payload)));
+        cleanupHandlers.push(subscribe(client, "Network.loadingFailed", (payload) => handleLoadingFailed(payload)));
+        cleanupHandlers.push(subscribe(client, "Network.loadingFinished", (payload) => {
+            void handleLoadingFinished(payload);
+        }));
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            handlers.onError?.(error);
+        }
+        throw error;
+    }
+    return {
+        navigate: async (url) => {
+            await ensurePageEnabled();
+            await callCdp(client, "Page.navigate", { url });
+        },
+        waitForHtml: async () => {
+            return htmlPromise;
+        },
+        startCapture: async () => {
+            await runTriggerActions(triggerActions);
+        },
+        stop: async () => {
+            for (const cleanup of cleanupHandlers) {
+                cleanup();
+            }
+            await callCdp(client, "Network.disable").catch(() => undefined);
+            if (ownsClient) {
+                await client.close?.();
+            }
+        }
+    };
+};

package/dist/internal/types.d.ts

@@ -0,0 +1,113 @@
+import type { ResourceType } from "@pagepocket/lib";
+export type ChromeDebuggerTarget = {
+    tabId: number;
+};
+export type ChromeDebuggerEvent = (source: ChromeDebuggerTarget, method: string, params?: Record<string, unknown>) => void;
+export type ChromeDebuggerApi = {
+    attach: (target: ChromeDebuggerTarget, version: string, callback: () => void) => void;
+    detach: (target: ChromeDebuggerTarget, callback: () => void) => void;
+    sendCommand: (target: ChromeDebuggerTarget, method: string, params: Record<string, unknown>, callback: (result?: unknown) => void) => void;
+    onEvent: {
+        addListener: (listener: ChromeDebuggerEvent) => void;
+        removeListener: (listener: ChromeDebuggerEvent) => void;
+    };
+};
+export type ChromeRuntimeApi = {
+    lastError?: {
+        message?: string;
+    };
+};
+export type ChromeGlobal = {
+    debugger?: ChromeDebuggerApi;
+    runtime?: ChromeRuntimeApi;
+};
+export type CdpClient = {
+    send?: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+    on?: (event: string, listener: (payload: unknown) => void) => void;
+    off?: (event: string, listener: (payload: unknown) => void) => void;
+    close?: () => Promise<void>;
+    Network?: {
+        enable?: (params?: Record<string, unknown>) => Promise<void>;
+        disable?: () => Promise<void>;
+        getResponseBody?: (params: {
+            requestId: string;
+        }) => Promise<{
+            body: string;
+            base64Encoded?: boolean;
+        }>;
+        requestWillBeSent?: (listener: (payload: unknown) => void) => void;
+        responseReceived?: (listener: (payload: unknown) => void) => void;
+        loadingFailed?: (listener: (payload: unknown) => void) => void;
+        loadingFinished?: (listener: (payload: unknown) => void) => void;
+    };
+    Page?: {
+        enable?: () => Promise<void>;
+        navigate?: (params: {
+            url: string;
+        }) => Promise<void>;
+        getResourceContent?: (params: {
+            frameId: string;
+            url: string;
+        }) => Promise<{
+            content: string;
+            base64Encoded?: boolean;
+        }>;
+    };
+};
+export type RequestWillBeSent = {
+    requestId: string;
+    frameId?: string;
+    timestamp?: number;
+    wallTime?: number;
+    type?: string;
+    initiator?: {
+        type?: string;
+        url?: string;
+    };
+    request: {
+        url: string;
+        method: string;
+        headers?: Record<string, unknown>;
+    };
+    redirectResponse?: ResponseReceived["response"];
+};
+export type ResponseReceived = {
+    requestId: string;
+    frameId?: string;
+    timestamp?: number;
+    wallTime?: number;
+    type?: string;
+    response: {
+        url: string;
+        status: number;
+        statusText?: string;
+        headers?: Record<string, unknown>;
+        mimeType?: string;
+        fromDiskCache?: boolean;
+        fromServiceWorker?: boolean;
+    };
+};
+export type LoadingFailed = {
+    requestId: string;
+    timestamp?: number;
+    wallTime?: number;
+    errorText: string;
+};
+export type LoadingFinished = {
+    requestId: string;
+    timestamp?: number;
+    wallTime?: number;
+};
+export type StoredResponse = {
+    requestId: string;
+    response: ResponseReceived["response"];
+};
+export type RequestInfo = {
+    url: string;
+    frameId?: string;
+    resourceType?: ResourceType;
+    initiator?: {
+        type?: string;
+        url?: string;
+    };
+};

package/dist/internal/types.js

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

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@pagepocket/capture-http-cdp-unit",
+  "version": "0.8.0",
+  "description": "PagePocket plugin: capture HTTP events (CDP)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "@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)\""
+  }
+}