@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/locator/selector.js

@@ -0,0 +1,113 @@
+function nonEmpty(value, what) {
+    if (value.trim() === "")
+        throw new TypeError(`${what} must not be empty`);
+    return value;
+}
+export function xpathSelector(value) {
+    return { kind: "xpath", value: nonEmpty(value, "an xpath") };
+}
+export function cssSelector(value) {
+    return { kind: "css", value: nonEmpty(value, "a css selector") };
+}
+export function textSelector(value, { match = "full", ignoreCase = false } = {}) {
+    return {
+        kind: "text",
+        value: nonEmpty(value, "the text"),
+        match,
+        ignoreCase,
+    };
+}
+export function labelSelector(value, { match = "full", ignoreCase = false } = {}) {
+    return {
+        kind: "label",
+        value: nonEmpty(value, "the label"),
+        match,
+        ignoreCase,
+    };
+}
+export function testIdSelector(value) {
+    return { kind: "testid", value: nonEmpty(value, "the test id") };
+}
+export function roleSelector(role, { name } = {}) {
+    nonEmpty(role, "the role");
+    return name === undefined
+        ? { kind: "role", role }
+        : { kind: "role", role, name };
+}
+/**
+ * Normalises an xpath. Relative xpaths get a leading `//` (`.//` when `scoped`, i.e. searching inside
+ * a parent match). Absolute (`/…`), grouped (`(…)`) and context (`./…`) paths are kept; in a scoped
+ * position `//…` is also made relative, so `parent.locator("//x")` means "x inside parent".
+ */
+export function normalizeXpath(xpath, scoped) {
+    if (scoped) {
+        if (xpath.startsWith("//"))
+            return "." + xpath;
+        return /^[/(.]/.test(xpath) ? xpath : ".//" + xpath;
+    }
+    return /^[/(.]/.test(xpath) ? xpath : "//" + xpath;
+}
+/** The BiDi locator for a step. `scoped` is true for every step after the first */
+export function toBiDiLocator(selector, scoped) {
+    switch (selector.kind) {
+        case "xpath":
+            return { type: "xpath", value: normalizeXpath(selector.value, scoped) };
+        case "css":
+            return { type: "css", value: selector.value };
+        case "text":
+            return {
+                type: "innerText",
+                value: selector.value,
+                matchType: selector.match,
+                ignoreCase: selector.ignoreCase,
+            };
+        case "role":
+            return {
+                type: "accessibility",
+                value: {
+                    ...(selector.role !== undefined && { role: selector.role }),
+                    ...(selector.name !== undefined && { name: selector.name }),
+                },
+            };
+        case "testid":
+            return {
+                type: "css",
+                value: `[data-testid="${selector.value.replace(/["\\]/g, "\\$&")}"]`,
+            };
+        case "label":
+            throw new Error("label is resolved by the framework, not by the browser");
+        case "nth":
+            throw new Error("nth is resolved by the framework, not by the browser");
+    }
+}
+/** A short name for error messages */
+export function describeSelector(selector, scoped) {
+    switch (selector.kind) {
+        case "xpath":
+            return normalizeXpath(selector.value, scoped);
+        case "css":
+            return `css=${selector.value}`;
+        case "label":
+        case "text": {
+            const flags = [
+                selector.match === "partial" && "partial",
+                selector.ignoreCase && "ignoring case",
+            ].filter(Boolean);
+            return `${selector.kind}=${JSON.stringify(selector.value)}${flags.length ? ` (${flags.join(", ")})` : ""}`;
+        }
+        case "testid":
+            return `testid=${JSON.stringify(selector.value)}`;
+        case "role":
+            return (`role=${selector.role ?? ""}` +
+                (selector.name === undefined
+                    ? ""
+                    : `[name=${JSON.stringify(selector.name)}]`));
+        case "nth":
+            return `nth=${selector.index}`;
+    }
+}
+export function describeChain(chain) {
+    return chain
+        .map((selector, index) => describeSelector(selector, index > 0))
+        .join(" >> ");
+}

package/dist/locator/text-locator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Function declaration run in the page as `(starts, value, match, ignoreCase)`; returns the elements
+ * whose text matches. Used when the browser does not implement BiDi's `innerText` locator
+ * (Firefox does not): same idea, done by the framework.
+ *
+ * - Searches the descendants of every start node (the whole document when there are none).
+ * - Text is `innerText`, whitespace collapsed and trimmed; `full` needs equality, `partial` a substring.
+ * - Only the innermost matches count, so a wrapper `<div>` around a matching `<button>` is not returned.
+ * - Results are unique and in document order.
+ *
+ * A string, so the transpiler cannot inject helpers that do not exist in the page.
+ */
+export declare const TEXT_LOCATE = "(starts, value, match, ignoreCase) => {\n  const skipped = new Set([\"SCRIPT\", \"STYLE\", \"NOSCRIPT\", \"TEMPLATE\", \"HEAD\", \"TITLE\", \"META\", \"LINK\"]);\n  const normalise = (text) => {\n    const collapsed = String(text).replace(/\\s+/g, \" \").trim();\n    return ignoreCase ? collapsed.toLowerCase() : collapsed;\n  };\n  const wanted = normalise(value);\n  const roots = starts.length > 0 ? starts : [document];\n  const seen = new Set();\n  const matches = [];\n  for (const root of roots) {\n    for (const el of root.querySelectorAll(\"*\")) {\n      if (seen.has(el) || skipped.has(el.tagName.toUpperCase())) continue;\n      seen.add(el);\n      const text = normalise(el.innerText ?? el.textContent ?? \"\");\n      if (match === \"full\" ? text === wanted : text.includes(wanted)) matches.push(el);\n    }\n  }\n  const hasMatchingDescendant = new Set();\n  for (const el of matches) {\n    for (let parent = el.parentElement; parent; parent = parent.parentElement) hasMatchingDescendant.add(parent);\n  }\n  return matches\n    .filter((el) => !hasMatchingDescendant.has(el))\n    .sort((a, b) => (a.compareDocumentPosition(b) & 4 ? -1 : 1));\n}";

package/dist/logger/index.d.ts

@@ -0,0 +1,2 @@
+declare const logger: import("winston").Logger;
+export default logger;

package/dist/logger/index.js

@@ -0,0 +1,30 @@
+import { createLogger, format, transports } from "winston";
+import { maskFormat } from "../config/mask.js";
+const logger = createLogger({
+    level: "debug",
+    format: format.combine(format.timestamp({
+        format: "DD-MM-YYYY HH:mm:ss",
+    }), format.errors({ stack: true }), format.splat(), format.metadata({ key: "meta" }), maskFormat(), format.json({ space: 2 })),
+    defaultMeta: { service: "samurai-framework" },
+    transports: [
+        //
+        // - Write to all logs with level `info` and below to `quick-start-combined.log`.
+        // - Write all logs error (and below) to `quick-start-error.log`.
+        //
+        new transports.Console({
+            // The `samurai` command quiets this to "warn"; the log files keep everything
+            level: process.env.SAMURAI_LOG_LEVEL ?? "debug",
+            // stdout stays free for a command's own output (`samurai run --json`)
+            stderrLevels: ["error", "warn", "info", "verbose", "debug"],
+            format: format.combine(format.timestamp(), format.errors({ stack: true }), format.printf(({ level, message, meta }) => {
+                return `${level.toUpperCase()}: ${message}${meta ? `\n${JSON.stringify(meta)}` : null}`;
+            })),
+        }),
+        new transports.File({
+            filename: `logs/error.log`,
+            level: "error",
+        }),
+        new transports.File({ filename: `logs/combined.log` }),
+    ],
+});
+export default logger;

package/dist/network/data-collector.d.ts

@@ -0,0 +1,26 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** The body of a response cannot be read */
+export declare class ResponseBodyUnavailableError extends Error {
+    readonly url: string;
+    readonly reason: string;
+    constructor(url: string, reason: string);
+}
+/**
+ * A browser only keeps response bodies for a request when a data collector was registered before the request
+ * started. This registers one for a page and reads bodies through it.
+ */
+export declare class DataCollector {
+    private connector;
+    private id;
+    private disposed;
+    private constructor();
+    static start(connector: BiDiConnector, contextId: string, options?: {
+        maxBodySize?: number;
+    }): Promise<DataCollector>;
+    /** The body of the response to request `requestId`; `url` only names it in errors */
+    read(requestId: string, url: string): Promise<Buffer>;
+    /** Lets the browser drop its copy of a body that has been read. Never throws */
+    release(requestId: string): Promise<void>;
+    /** Idempotent */
+    dispose(): Promise<void>;
+}

package/dist/network/data-collector.js

@@ -0,0 +1,77 @@
+import { BiDiError } from "../transport/bidi-error.js";
+/** How large a response body may be to be kept: 10 MiB */
+const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
+/** The body of a response cannot be read */
+export class ResponseBodyUnavailableError extends Error {
+    constructor(url, reason) {
+        super(`Response body of ${url} is unavailable: ${reason}`);
+        this.name = "ResponseBodyUnavailableError";
+        this.url = url;
+        this.reason = reason;
+    }
+}
+/**
+ * A browser only keeps response bodies for a request when a data collector was registered before the request
+ * started. This registers one for a page and reads bodies through it.
+ */
+export class DataCollector {
+    constructor(connector, id) {
+        this.connector = connector;
+        this.id = id;
+        this.disposed = false;
+    }
+    static async start(connector, contextId, options = {}) {
+        const { collector } = await connector.send("network.addDataCollector", {
+            dataTypes: ["response"],
+            maxEncodedDataSize: options.maxBodySize ?? DEFAULT_MAX_BODY_SIZE,
+            contexts: [contextId],
+        });
+        return new DataCollector(connector, collector);
+    }
+    /** The body of the response to request `requestId`; `url` only names it in errors */
+    async read(requestId, url) {
+        try {
+            const { bytes } = await this.connector.send("network.getData", {
+                dataType: "response",
+                request: requestId,
+                collector: this.id,
+            });
+            return bytes.type === "base64" ? Buffer.from(bytes.value, "base64") : Buffer.from(bytes.value, "utf8");
+        }
+        catch (err) {
+            if (err instanceof BiDiError && err.code === "no such network data") {
+                throw new ResponseBodyUnavailableError(url, "no body was collected: the collector started after the request, or the response is larger than maxBodySize");
+            }
+            if (err instanceof BiDiError && err.code === "unavailable network data") {
+                throw new ResponseBodyUnavailableError(url, "the body is not available yet");
+            }
+            throw err;
+        }
+    }
+    /** Lets the browser drop its copy of a body that has been read. Never throws */
+    async release(requestId) {
+        try {
+            await this.connector.send("network.disownData", {
+                dataType: "response",
+                collector: this.id,
+                request: requestId,
+            });
+        }
+        catch {
+            // Already gone: nothing left to free
+        }
+    }
+    /** Idempotent */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        try {
+            await this.connector.send("network.removeDataCollector", { collector: this.id });
+        }
+        catch (err) {
+            if (!(err instanceof BiDiError && err.code === "no such network collector"))
+                throw err;
+        }
+    }
+}

package/dist/network/network-tracker.d.ts

@@ -0,0 +1,94 @@
+import type { ContextTree } from "../browser/context-tree.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { Header, RequestData } from "../types/bidi-modules/network.js";
+import { WaitTimeoutError } from "../wait/wait-until.js";
+export interface NetworkRequest {
+    /** The browser's id; the same for every hop of a redirect chain */
+    id: string;
+    url: string;
+    method: string;
+    /** Header names lower-cased; repeated headers joined with ", " */
+    headers: Record<string, string>;
+    /** "document", "script", "image", …; falls back to the initiator type, then "other" */
+    resourceType: string;
+    navigation: string | null;
+    /** The request this one is the redirect of, or null */
+    redirectedFrom: NetworkRequest | null;
+    /** True while a network intercept holds it */
+    isBlocked: boolean;
+}
+export interface NetworkResponse {
+    url: string;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    fromCache: boolean;
+    request: NetworkRequest;
+}
+export type FailedRequest = NetworkRequest & {
+    errorText: string;
+};
+interface EventMap {
+    request: [NetworkRequest];
+    response: [NetworkResponse];
+    requestfailed: [FailedRequest];
+}
+export type NetworkEventName = keyof EventMap;
+export interface TrackerOptions {
+    /** Requests it returns true for are neither counted nor emitted. Default: none */
+    ignore?: (request: NetworkRequest) => boolean;
+}
+/** waitForIdle ran out of time with requests still in flight; `last` holds (up to five of) their URLs */
+export declare class NetworkIdleTimeoutError extends WaitTimeoutError<string[]> {
+    constructor(timeout: number, inflight: number, urls: string[]);
+}
+/**
+ * Follows the network activity of one page (its frames included): which requests are in flight,
+ * and `request` / `response` / `requestfailed` events. In-flight is keyed by `request id:redirect count`,
+ * so a redirect chain is one live request at a time.
+ */
+export declare class NetworkTracker {
+    private tree;
+    private contextId;
+    private ignore;
+    private connector;
+    private events;
+    private active;
+    /** Requests that may still be the source of a redirect, by hop key */
+    private hops;
+    private waiters;
+    private disposed;
+    private constructor();
+    static start(connector: BiDiConnector, tree: ContextTree, contextId: string, options?: TrackerOptions): Promise<NetworkTracker>;
+    private subscription;
+    /** Requests currently in flight */
+    get inflight(): number;
+    /** URLs of the requests currently in flight, oldest first */
+    get inflightUrls(): string[];
+    /** Waits that have not finished yet */
+    get waiting(): number;
+    on<E extends NetworkEventName>(event: E, listener: (...args: EventMap[E]) => void): void;
+    off<E extends NetworkEventName>(event: E, listener: (...args: EventMap[E]) => void): void;
+    /**
+     * Resolves once no request has been in flight for `idleTime` ms. A quiet page resolves after `idleTime`.
+     * Rejects with NetworkIdleTimeoutError after `timeout` ms, or with "page closed" when disposed.
+     */
+    waitForIdle({ idleTime, timeout }: {
+        idleTime: number;
+        timeout: number;
+    }): Promise<void>;
+    /** Stops tracking, unsubscribes and rejects pending waits. Idempotent */
+    dispose(): Promise<void>;
+    private removeListeners;
+    private owns;
+    private static key;
+    private onBeforeRequestSent;
+    private onResponseCompleted;
+    private onFetchError;
+    /** A listener that throws must not stop the tracker or the other listeners */
+    private emit;
+}
+export declare function toRequest(data: RequestData, navigation: string | null, isBlocked: boolean, redirectedFrom: NetworkRequest | null): NetworkRequest;
+/** Header list to a lower-cased record; repeated names are joined, base64 values decoded */
+export declare function toHeaders(headers: Header[]): Record<string, string>;
+export {};

package/dist/network/network-tracker.js

@@ -0,0 +1,198 @@
+import EventEmitter from "node:events";
+import logger from "../logger/index.js";
+import { WaitTimeoutError } from "../wait/wait-until.js";
+/** How many URLs a timeout message names */
+const URLS_IN_MESSAGE = 5;
+/** waitForIdle ran out of time with requests still in flight; `last` holds (up to five of) their URLs */
+export class NetworkIdleTimeoutError extends WaitTimeoutError {
+    constructor(timeout, inflight, urls) {
+        super(timeout, urls);
+        this.name = "NetworkIdleTimeoutError";
+        this.message = `waitForNetworkIdle(): still ${inflight} request(s) in flight after ${timeout}ms: ${urls.join(", ")}`;
+    }
+}
+/**
+ * Follows the network activity of one page (its frames included): which requests are in flight,
+ * and `request` / `response` / `requestfailed` events. In-flight is keyed by `request id:redirect count`,
+ * so a redirect chain is one live request at a time.
+ */
+export class NetworkTracker {
+    constructor(tree, contextId, ignore, connector) {
+        this.tree = tree;
+        this.contextId = contextId;
+        this.ignore = ignore;
+        this.connector = connector;
+        this.events = new EventEmitter();
+        this.active = new Map();
+        /** Requests that may still be the source of a redirect, by hop key */
+        this.hops = new Map();
+        this.waiters = new Set();
+        this.disposed = false;
+        this.onBeforeRequestSent = (params) => {
+            if (!this.owns(params.context))
+                return;
+            const key = NetworkTracker.key(params.request, params.redirectCount);
+            const redirectCount = Number(params.redirectCount);
+            const previousKey = `${params.request.request}:${redirectCount - 1}`;
+            const redirectedFrom = redirectCount > 0 ? (this.hops.get(previousKey) ?? null) : null;
+            this.hops.delete(previousKey);
+            const request = toRequest(params.request, params.navigation, params.isBlocked, redirectedFrom);
+            if (this.ignore(request))
+                return;
+            this.hops.set(key, request);
+            this.active.set(key, request.url);
+            this.emit("request", request);
+            this.events.emit("change");
+        };
+        this.onResponseCompleted = (params) => {
+            if (!this.owns(params.context))
+                return;
+            const key = NetworkTracker.key(params.request, params.redirectCount);
+            const request = this.hops.get(key);
+            if (!this.active.delete(key) || !request)
+                return;
+            const { response } = params;
+            // A redirect response keeps its request around: the next hop links back to it
+            if (response.status < 300 || response.status >= 400)
+                this.hops.delete(key);
+            this.emit("response", {
+                url: response.url,
+                status: response.status,
+                statusText: response.statusText,
+                headers: toHeaders(response.headers),
+                fromCache: response.fromCache,
+                request,
+            });
+            this.events.emit("change");
+        };
+        this.onFetchError = (params) => {
+            if (!this.owns(params.context))
+                return;
+            const key = NetworkTracker.key(params.request, params.redirectCount);
+            const request = this.hops.get(key);
+            if (!this.active.delete(key) || !request)
+                return;
+            this.hops.delete(key);
+            this.emit("requestfailed", Object.assign(request, { errorText: params.errorText }));
+            this.events.emit("change");
+        };
+    }
+    static async start(connector, tree, contextId, options = {}) {
+        const tracker = new NetworkTracker(tree, contextId, options.ignore ?? (() => false), connector);
+        // Listen first, then subscribe: nothing can arrive in between
+        connector.onEvent("network.beforeRequestSent", tracker.onBeforeRequestSent);
+        connector.onEvent("network.responseCompleted", tracker.onResponseCompleted);
+        connector.onEvent("network.fetchError", tracker.onFetchError);
+        try {
+            tracker.subscription = await connector.subscribe([
+                "network.beforeRequestSent",
+                "network.responseCompleted",
+                "network.fetchError",
+            ]);
+        }
+        catch (err) {
+            tracker.removeListeners();
+            throw err;
+        }
+        return tracker;
+    }
+    /** Requests currently in flight */
+    get inflight() {
+        return this.active.size;
+    }
+    /** URLs of the requests currently in flight, oldest first */
+    get inflightUrls() {
+        return [...this.active.values()];
+    }
+    /** Waits that have not finished yet */
+    get waiting() {
+        return this.waiters.size;
+    }
+    on(event, listener) {
+        this.events.on(event, listener);
+    }
+    off(event, listener) {
+        this.events.off(event, listener);
+    }
+    /**
+     * Resolves once no request has been in flight for `idleTime` ms. A quiet page resolves after `idleTime`.
+     * Rejects with NetworkIdleTimeoutError after `timeout` ms, or with "page closed" when disposed.
+     */
+    waitForIdle({ idleTime, timeout }) {
+        return new Promise((resolve, reject) => {
+            let idleTimer;
+            const waiter = { reject: (reason) => finish(() => reject(reason)) };
+            const finish = (settle) => {
+                clearTimeout(idleTimer);
+                clearTimeout(deadline);
+                this.events.off("change", check);
+                this.waiters.delete(waiter);
+                settle();
+            };
+            const check = () => {
+                clearTimeout(idleTimer);
+                if (this.active.size === 0)
+                    idleTimer = setTimeout(() => finish(resolve), idleTime);
+            };
+            const deadline = setTimeout(() => finish(() => reject(new NetworkIdleTimeoutError(timeout, this.active.size, this.inflightUrls.slice(0, URLS_IN_MESSAGE)))), timeout);
+            this.waiters.add(waiter);
+            this.events.on("change", check);
+            check();
+        });
+    }
+    /** Stops tracking, unsubscribes and rejects pending waits. Idempotent */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.removeListeners();
+        this.active.clear();
+        this.hops.clear();
+        [...this.waiters].forEach((waiter) => waiter.reject(new Error("page closed")));
+        await this.subscription?.unsubscribe();
+    }
+    removeListeners() {
+        this.connector.offEvent("network.beforeRequestSent", this.onBeforeRequestSent);
+        this.connector.offEvent("network.responseCompleted", this.onResponseCompleted);
+        this.connector.offEvent("network.fetchError", this.onFetchError);
+    }
+    owns(context) {
+        return context !== null && this.tree.isWithin(context, this.contextId);
+    }
+    static key(data, redirectCount) {
+        return `${data.request}:${Number(redirectCount)}`;
+    }
+    /** A listener that throws must not stop the tracker or the other listeners */
+    emit(event, ...args) {
+        for (const listener of this.events.listeners(event)) {
+            try {
+                listener(...args);
+            }
+            catch (err) {
+                logger.error("A network %s listener threw", event, { err });
+            }
+        }
+    }
+}
+export function toRequest(data, navigation, isBlocked, redirectedFrom) {
+    return {
+        id: data.request,
+        url: data.url,
+        method: data.method,
+        headers: toHeaders(data.headers),
+        resourceType: data.destination || data.initiatorType || "other",
+        navigation,
+        redirectedFrom,
+        isBlocked,
+    };
+}
+/** Header list to a lower-cased record; repeated names are joined, base64 values decoded */
+export function toHeaders(headers) {
+    const result = {};
+    for (const { name, value } of headers) {
+        const text = value.type === "base64" ? Buffer.from(value.value, "base64").toString("utf8") : value.value;
+        const key = name.toLowerCase();
+        result[key] = key in result ? `${result[key]}, ${text}` : text;
+    }
+    return result;
+}

package/dist/network/network-wait.d.ts

@@ -0,0 +1,16 @@
+import { WaitTimeoutError } from "../wait/wait-until.js";
+import { type UrlPattern } from "./url-match.js";
+/** What `page.waitForRequest` / `waitForResponse` match: a URL pattern, or a function */
+export type NetworkMatch<T> = UrlPattern | ((item: T) => boolean);
+/** No matching request or response arrived in time */
+export declare class NetworkWaitTimeoutError extends WaitTimeoutError<undefined> {
+    constructor(operation: "waitForRequest" | "waitForResponse", match: NetworkMatch<never>, timeout: number);
+}
+export declare class RequestTimeoutError extends NetworkWaitTimeoutError {
+}
+export declare class ResponseTimeoutError extends NetworkWaitTimeoutError {
+}
+/** The predicate for a match: a function as it is, a URL pattern tested on the item's url */
+export declare function toPredicate<T extends {
+    url: string;
+}>(match: NetworkMatch<T>): (item: T) => boolean;

package/dist/network/network-wait.js

@@ -0,0 +1,24 @@
+import { WaitTimeoutError } from "../wait/wait-until.js";
+import { matchUrl } from "./url-match.js";
+/** No matching request or response arrived in time */
+export class NetworkWaitTimeoutError extends WaitTimeoutError {
+    constructor(operation, match, timeout) {
+        super(timeout, undefined);
+        this.name = operation === "waitForRequest" ? "RequestTimeoutError" : "ResponseTimeoutError";
+        const kind = operation === "waitForRequest" ? "request" : "response";
+        this.message = `${operation}(): no ${kind} matching ${describeMatch(match)} within ${timeout}ms`;
+    }
+}
+export class RequestTimeoutError extends NetworkWaitTimeoutError {
+}
+export class ResponseTimeoutError extends NetworkWaitTimeoutError {
+}
+function describeMatch(match) {
+    if (typeof match === "function")
+        return "the given function";
+    return typeof match === "string" ? JSON.stringify(match) : String(match);
+}
+/** The predicate for a match: a function as it is, a URL pattern tested on the item's url */
+export function toPredicate(match) {
+    return typeof match === "function" ? match : (item) => matchUrl(match, item.url);
+}

package/dist/network/response.d.ts

@@ -0,0 +1,22 @@
+import type { NetworkRequest, NetworkResponse } from "./network-tracker.js";
+/** A response of the page, with access to its body */
+export declare class Response {
+    private loadBody;
+    readonly url: string;
+    readonly status: number;
+    readonly statusText: string;
+    /** Header names lower-cased */
+    readonly headers: Record<string, string>;
+    readonly fromCache: boolean;
+    readonly request: NetworkRequest;
+    private body_;
+    constructor(data: NetworkResponse, loadBody: (response: Response) => Promise<Buffer>);
+    /** The browser's id of the request; the same for every hop of a redirect chain */
+    get id(): string;
+    /** The body as bytes. Read once from the browser, then kept */
+    body(): Promise<Buffer>;
+    /** The body as UTF-8 text */
+    text(): Promise<string>;
+    /** The body parsed as JSON */
+    json<T = unknown>(): Promise<T>;
+}

package/dist/network/response.js

@@ -0,0 +1,42 @@
+import { ResponseBodyUnavailableError } from "./data-collector.js";
+/** A response of the page, with access to its body */
+export class Response {
+    constructor(data, loadBody) {
+        this.loadBody = loadBody;
+        this.url = data.url;
+        this.status = data.status;
+        this.statusText = data.statusText;
+        this.headers = data.headers;
+        this.fromCache = data.fromCache;
+        this.request = data.request;
+    }
+    /** The browser's id of the request; the same for every hop of a redirect chain */
+    get id() {
+        return this.request.id;
+    }
+    /** The body as bytes. Read once from the browser, then kept */
+    body() {
+        if (this.status >= 300 && this.status < 400 && "location" in this.headers) {
+            return Promise.reject(new ResponseBodyUnavailableError(this.url, "redirect response"));
+        }
+        this.body_ ??= this.loadBody(this).catch((err) => {
+            this.body_ = undefined; // let a later call try again
+            throw err;
+        });
+        return this.body_;
+    }
+    /** The body as UTF-8 text */
+    async text() {
+        return (await this.body()).toString("utf8");
+    }
+    /** The body parsed as JSON */
+    async json() {
+        const text = await this.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch (err) {
+            throw new Error(`Response body of ${this.url} is not JSON: ${err.message}`);
+        }
+    }
+}