browser-debugger-cli 0.8.0 → 0.9.0

package/dist/session/sessionList.js

@@ -0,0 +1,199 @@
+/**
+ * Sessions across the default and named session directories (`bdg sessions`):
+ * running ones, and ones whose daemon died and left a Chrome or files behind.
+ */
+import * as fs from 'fs';
+import { getStatus } from '../ipc/client.js';
+import { isSessionChrome, readLiveDaemonPid } from './cleanup/staleSession.js';
+import { probeDaemonSocket } from './daemonSocket.js';
+import { SESSION_STATE_FILES, getNamedSessionDir, listSessionDirs, sessionFilePathIn, } from './paths.js';
+import { readPidFromFile } from './pid.js';
+import { readPortFile } from './portClaims.js';
+import { isValidSessionName, normalizeSessionName } from './sessionName.js';
+import { createLogger, logDebugError } from '../ui/logging/index.js';
+import { removeDirCommand, sessionCommand } from '../ui/messages/sessionCommand.js';
+import { isProcessAlive } from '../utils/process.js';
+const log = createLogger('session');
+/**
+ * Summarize a daemon's status response.
+ *
+ * @param name - Session name
+ * @param data - Status data
+ * @returns Session info
+ */
+export function toRunningSession(name, data) {
+    const meta = data.sessionMetadata;
+    const state = meta ? 'active' : data.ending ? 'ending' : 'starting';
+    const url = data.pageState?.url ?? data.starting?.url;
+    return {
+        name,
+        state,
+        ...(url !== undefined && { url }),
+        ...(meta && { port: meta.port }),
+        daemonPid: data.daemonPid,
+        ...(meta?.chromePid && { chromePid: meta.chromePid }),
+    };
+}
+/**
+ * Describe the session of a directory: a running daemon, or what a dead
+ * one left behind.
+ *
+ * @param entry - Session directory
+ * @returns Session info, or null when there is no session
+ */
+async function describeSession(entry) {
+    const { name, dir } = entry;
+    const socketPath = sessionFilePathIn(dir, 'DAEMON_SOCKET');
+    const probe = await probeDaemonSocket(socketPath);
+    if (probe !== 'alive')
+        return describeWithoutSocket(entry, probe);
+    try {
+        const response = await getStatus(socketPath);
+        if (response.status === 'ok' && response.data)
+            return toRunningSession(name, response.data);
+    }
+    catch (error) {
+        logDebugError(log, `get status of ${dir}`, error);
+    }
+    return { name, state: 'unresponsive' };
+}
+/**
+ * A session whose daemon socket does not answer: `starting` while its daemon
+ * (from daemon.pid, verified by command line) runs but has not bound the
+ * socket yet, otherwise see {@link describeLeftovers}.
+ *
+ * @param entry - Session directory
+ * @param probe - Result of probing its daemon socket
+ * @returns Session info, or null when the directory holds no session state
+ */
+function describeWithoutSocket(entry, probe) {
+    const daemonPid = readLiveDaemonPid(entry.dir);
+    if (daemonPid !== null)
+        return { name: entry.name, state: 'starting', daemonPid };
+    return describeLeftovers(entry, probe);
+}
+/**
+ * A session whose daemon is gone: `crashed` while the Chrome bdg launched for
+ * it still runs, `stale` when only its files are left. Nothing is changed on
+ * disk; `cleanup` names the command that removes them.
+ *
+ * @param entry - Session directory
+ * @param probe - Result of probing its daemon socket
+ * @returns Session info, or null when the directory holds no session state
+ */
+export function describeLeftovers({ name, dir }, probe) {
+    const chromePid = readPidFromFile(sessionFilePathIn(dir, 'CHROME_PID'));
+    const orphan = chromePid !== null && isProcessAlive(chromePid) && isSessionChrome(chromePid, dir);
+    const leftover = probe === 'stale' ||
+        SESSION_STATE_FILES.some((type) => fs.existsSync(sessionFilePathIn(dir, type)));
+    if (!orphan && !leftover)
+        return null;
+    const port = leftoverPort(dir);
+    return {
+        name,
+        state: orphan ? 'crashed' : 'stale',
+        ...(port !== null && { port }),
+        ...(orphan && { chromePid }),
+        cleanup: sessionCommand('bdg cleanup', name),
+    };
+}
+/**
+ * The port a dead session used: from its metadata, else its `port.txt`.
+ *
+ * @param dir - Session directory
+ * @returns Port, or null if unknown
+ */
+function leftoverPort(dir) {
+    try {
+        const meta = JSON.parse(fs.readFileSync(sessionFilePathIn(dir, 'METADATA'), 'utf8'));
+        if (typeof meta.port === 'number')
+            return meta.port;
+    }
+    catch (error) {
+        logDebugError(log, `read the metadata in ${dir}`, error);
+    }
+    return readPortFile(sessionFilePathIn(dir, 'PORT'));
+}
+/**
+ * Whether a directory entry is a session `--session` can select: the
+ * default session, or a valid lower-case name.
+ *
+ * @param entry - Session directory
+ * @returns True if selectable
+ */
+function isSelectable({ name }) {
+    return name === null || (isValidSessionName(name) && name === normalizeSessionName(name));
+}
+/**
+ * Whether two paths are the same directory (same inode and device), e.g.
+ * `sessions/ALPHA` and `sessions/alpha` on a case-insensitive file system.
+ *
+ * @param a - First path
+ * @param b - Second path
+ * @returns True if both exist and are the same directory
+ */
+function isSameDir(a, b) {
+    try {
+        const first = fs.statSync(a);
+        const second = fs.statSync(b);
+        return first.ino === second.ino && first.dev === second.dev;
+    }
+    catch (error) {
+        logDebugError(log, `compare ${a} with ${b}`, error);
+        return false;
+    }
+}
+/**
+ * The session `--session` reaches in a directory: the entry itself when its
+ * name is selectable, the lower-cased session when the name differs only in
+ * case and `--session <lower-case>` resolves to this very directory (a
+ * case-insensitive file system), else null.
+ *
+ * @param entry - Session directory
+ * @returns Selectable entry, or null
+ */
+function selectableEntry(entry) {
+    if (isSelectable(entry) || entry.name === null)
+        return entry;
+    const lower = normalizeSessionName(entry.name);
+    if (!isValidSessionName(lower))
+        return null;
+    return isSameDir(entry.dir, getNamedSessionDir(lower)) ? { name: lower, dir: entry.dir } : null;
+}
+/**
+ * A directory `--session` cannot reach (e.g. `--json`, or `ALPHA` on a
+ * case-sensitive file system, made by an earlier build): described like any
+ * session while its daemon answers, otherwise `stale` with the command that
+ * removes it by hand.
+ *
+ * @param entry - Session directory
+ * @returns Session info
+ */
+async function describeUnselectable(entry) {
+    const socketPath = sessionFilePathIn(entry.dir, 'DAEMON_SOCKET');
+    if ((await probeDaemonSocket(socketPath)) === 'alive')
+        return describeSession(entry);
+    return { name: entry.name, state: 'stale', cleanup: removeDirCommand(entry.dir) };
+}
+/**
+ * Every session: the default one first, then named sessions by name. Includes
+ * crashed and stale sessions, and directories `--session` cannot reach, so
+ * their leftovers can be cleaned up. A directory differing only in case
+ * (`ALPHA`) that `--session alpha` reaches is listed once, as `alpha`.
+ *
+ * @returns Sessions
+ */
+export async function listRunningSessions() {
+    const listed = new Set();
+    const sessions = await Promise.all(listSessionDirs().map((entry) => {
+        const selectable = selectableEntry(entry);
+        if (selectable === null)
+            return describeUnselectable(entry);
+        if (listed.has(selectable.name))
+            return Promise.resolve(null);
+        listed.add(selectable.name);
+        return describeSession(selectable);
+    }));
+    return sessions.filter((session) => session !== null);
+}
+//# sourceMappingURL=sessionList.js.map

package/dist/session/sessionName.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Named sessions (`--session <name>` / `BDG_SESSION`).
+ *
+ * A named session lives in `<base>/sessions/<name>/` with its own daemon,
+ * socket, Chrome and port, so several agents can run bdg side by side.
+ * Names are case-insensitive: they are lower-cased when selected, so `ALPHA`
+ * and `alpha` are the same session (and directory) on every file system.
+ */
+/** Longest session name */
+export declare const MAX_SESSION_NAME_LENGTH = 40;
+/**
+ * Whether a name has the allowed characters and length (case-insensitive).
+ *
+ * @param name - Session name
+ * @returns True for a valid name
+ */
+export declare function isValidSessionName(name: string): boolean;
+/**
+ * The canonical form of a session name: lower case.
+ *
+ * @param name - Session name as given
+ * @returns Lower-cased name
+ */
+export declare function normalizeSessionName(name: string): string;
+/**
+ * Check a session name: allowed characters, length, and a daemon socket path
+ * the OS accepts. When even the shortest name would make the socket path too
+ * long, the base directory is blamed instead of the name.
+ *
+ * @param name - Session name
+ * @throws CommandError (81) for an invalid name or a too-long socket path
+ */
+export declare function validateSessionName(name: string): void;
+/**
+ * Select the session the command acts on.
+ *
+ * `--session` wins over `BDG_SESSION`; the choice is stored in `BDG_SESSION`
+ * so the rest of the process (and a daemon it spawns) resolves the same
+ * session directory. The name is stored lower-cased. An empty `BDG_SESSION`
+ * means the default session.
+ *
+ * @param optionValue - Value of `--session`, if given
+ * @throws CommandError (81) for an invalid name
+ */
+export declare function selectSession(optionValue: string | undefined): void;
+//# sourceMappingURL=sessionName.d.ts.map

package/dist/session/sessionName.js

@@ -0,0 +1,97 @@
+/**
+ * Named sessions (`--session <name>` / `BDG_SESSION`).
+ *
+ * A named session lives in `<base>/sessions/<name>/` with its own daemon,
+ * socket, Chrome and port, so several agents can run bdg side by side.
+ * Names are case-insensitive: they are lower-cased when selected, so `ALPHA`
+ * and `alpha` are the same session (and directory) on every file system.
+ */
+import { CommandError } from '../errors/index.js';
+import { invalidSessionNameError, sessionNameSocketTooLongError, socketPathTooLongError, } from '../errors/messages.js';
+import { MAX_DAEMON_SOCKET_PATH_BYTES, SESSION_NAME_ENV, getNamedSessionDir, sessionFilePathIn, } from './paths.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+/** Longest session name */
+export const MAX_SESSION_NAME_LENGTH = 40;
+/**
+ * Characters allowed in a session name: a letter or digit first (so a name
+ * never looks like an option), then letters, digits, `-` or `_`.
+ */
+const SESSION_NAME_PATTERN = new RegExp(`^[A-Za-z0-9][A-Za-z0-9_-]{0,${MAX_SESSION_NAME_LENGTH - 1}}$`);
+/**
+ * Whether a name has the allowed characters and length (case-insensitive).
+ *
+ * @param name - Session name
+ * @returns True for a valid name
+ */
+export function isValidSessionName(name) {
+    return SESSION_NAME_PATTERN.test(name);
+}
+/**
+ * The canonical form of a session name: lower case.
+ *
+ * @param name - Session name as given
+ * @returns Lower-cased name
+ */
+export function normalizeSessionName(name) {
+    return name.toLowerCase();
+}
+/**
+ * Check a session name: allowed characters, length, and a daemon socket path
+ * the OS accepts. When even the shortest name would make the socket path too
+ * long, the base directory is blamed instead of the name.
+ *
+ * @param name - Session name
+ * @throws CommandError (81) for an invalid name or a too-long socket path
+ */
+export function validateSessionName(name) {
+    if (!isValidSessionName(name)) {
+        throwInvalid(invalidSessionNameError(name, MAX_SESSION_NAME_LENGTH));
+    }
+    const shortest = namedSocketPath('a');
+    if (Buffer.byteLength(shortest) > MAX_DAEMON_SOCKET_PATH_BYTES) {
+        throwInvalid(socketPathTooLongError(shortest, MAX_DAEMON_SOCKET_PATH_BYTES));
+    }
+    const socketPath = namedSocketPath(name);
+    if (Buffer.byteLength(socketPath) > MAX_DAEMON_SOCKET_PATH_BYTES) {
+        throwInvalid(sessionNameSocketTooLongError(name, socketPath, MAX_DAEMON_SOCKET_PATH_BYTES));
+    }
+}
+/**
+ * Daemon socket path of a named session.
+ *
+ * @param name - Session name
+ * @returns Socket path
+ */
+function namedSocketPath(name) {
+    return sessionFilePathIn(getNamedSessionDir(name), 'DAEMON_SOCKET');
+}
+/**
+ * Throw an invalid-arguments error (81).
+ *
+ * @param err - Message and suggestion
+ * @throws CommandError always
+ */
+function throwInvalid(err) {
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/**
+ * Select the session the command acts on.
+ *
+ * `--session` wins over `BDG_SESSION`; the choice is stored in `BDG_SESSION`
+ * so the rest of the process (and a daemon it spawns) resolves the same
+ * session directory. The name is stored lower-cased. An empty `BDG_SESSION`
+ * means the default session.
+ *
+ * @param optionValue - Value of `--session`, if given
+ * @throws CommandError (81) for an invalid name
+ */
+export function selectSession(optionValue) {
+    const name = optionValue ?? process.env[SESSION_NAME_ENV]?.trim();
+    if (name === undefined || (optionValue === undefined && name === '')) {
+        delete process.env[SESSION_NAME_ENV];
+        return;
+    }
+    validateSessionName(name);
+    process.env[SESSION_NAME_ENV] = normalizeSessionName(name);
+}
+//# sourceMappingURL=sessionName.js.map

package/dist/telemetry/a11y.d.ts

@@ -28,6 +28,8 @@ export declare function collectA11yTree(): Promise<A11yTree>;
  * Queries accessibility tree by pattern (role, name, description).
  *
  * Performs case-insensitive matching with AND logic for multiple fields.
+ * An element reported more than once (by the page's tree and its frame's)
+ * is listed once.
  *
  * @param tree - Accessibility tree to search
  * @param pattern - Query pattern with optional role, name, description
@@ -50,18 +52,21 @@ export declare function queryA11yTree(tree: A11yTree, pattern: A11yQueryPattern)
  * Parses query pattern string into A11yQueryPattern object.
  *
  * Fields are `key:value` or `key=value`, separated by spaces or commas.
- * Values may contain spaces (quote them if they contain `key:`-like text).
- * Keys: role, name, description (desc). Case-insensitive.
+ * Keys: role, name, description (desc). Case-insensitive. A role ends at the
+ * next `key:`; a name or description runs to the next role/name/description
+ * field with a value, or to the end, so it may contain spaces and colons
+ * (`name=E-mail address:`). Quote a value to end it explicitly.
  *
  * @param patternString - Query pattern string
  * @returns Parsed query pattern
- * @throws CommandError (81) for unknown keys
+ * @throws CommandError (81) for unknown keys, also a misspelled one inside a name
  *
  * @example
  * ```typescript
  * parseQueryPattern('role:button name:Submit')     // { role: 'button', name: 'Submit' }
  * parseQueryPattern('role=link,name=Google Chrome') // { role: 'link', name: 'Google Chrome' }
  * parseQueryPattern('name:"Sign in" role:button')  // { name: 'Sign in', role: 'button' }
+ * parseQueryPattern('name=E-mail address:')        // { name: 'E-mail address:' }
  * ```
  */
 export declare function parseQueryPattern(patternString: string): A11yQueryPattern;

package/dist/telemetry/a11y.js

@@ -1,7 +1,9 @@
 import { CommandError } from '../errors/index.js';
 import { unknownQueryFieldError } from '../errors/messages.js';
 import { callCDP } from '../ipc/client.js';
+import { childFrameIds } from '../runtime/dom/frameLayout.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+import { levenshteinDistance } from '../utils/levenshtein.js';
 /**
  * Builds accessibility tree from raw CDP nodes.
  *
@@ -98,22 +100,13 @@ async function collectFrameNodes(pageNodes) {
     const tree = (await callCDP('Page.getFrameTree', {})).data?.result;
     const known = [...pageNodes];
     const collected = [];
-    for (const [index, frameId] of childFrames(tree?.frameTree).entries()) {
+    for (const [index, frameId] of childFrameIds(tree?.frameTree).entries()) {
         const nodes = await frameNodes(frameId, `f${index}:`, known);
         known.push(...nodes);
         collected.push(...nodes);
     }
     return collected;
 }
-/**
- * Ids of all frames below a frame tree's root.
- *
- * @param tree - Frame tree
- * @returns Frame ids, depth-first
- */
-function childFrames(tree) {
-    return (tree?.childFrames ?? []).flatMap((child) => [child.frame.id, ...childFrames(child)]);
-}
 /**
  * One frame's nodes, with ids prefixed, its root attached to the node of its
  * `<iframe>` element.
@@ -234,6 +227,8 @@ const TEXT_ROLES = new Set(['statictext', 'inlinetextbox']);
  * Queries accessibility tree by pattern (role, name, description).
  *
  * Performs case-insensitive matching with AND logic for multiple fields.
+ * An element reported more than once (by the page's tree and its frame's)
+ * is listed once.
  *
  * @param tree - Accessibility tree to search
  * @param pattern - Query pattern with optional role, name, description
@@ -253,13 +248,19 @@ const TEXT_ROLES = new Set(['statictext', 'inlinetextbox']);
  */
 export function queryA11yTree(tree, pattern) {
     const matches = [];
+    const seenElements = new Set();
     const wantsText = pattern.role !== undefined && TEXT_ROLES.has(pattern.role.toLowerCase());
     for (const node of tree.nodes.values()) {
         if (!wantsText && TEXT_ROLES.has(node.role.toLowerCase()))
             continue;
-        if (matchesPattern(node, pattern)) {
-            matches.push(node);
+        if (!matchesPattern(node, pattern))
+            continue;
+        if (node.backendDOMNodeId !== undefined) {
+            if (seenElements.has(node.backendDOMNodeId))
+                continue;
+            seenElements.add(node.backendDOMNodeId);
         }
+        matches.push(node);
     }
     return {
         nodes: matches,
@@ -317,47 +318,110 @@ const QUERY_FIELDS = {
     description: 'description',
     desc: 'description',
 };
+/** The next `key:`/`key=` anywhere (fields may follow other text). */
+const QUERY_KEY = /([a-z]+)\s*[:=]/i;
+/** A quoted value (it may contain anything but its own quote). */
+const QUOTED_QUERY_VALUE = /^\s*("[^"]*"|'[^']*')/;
+/** Where a role value ends: at the next `key:` after a space or comma. */
+const NEXT_QUERY_FIELD = /[\s,]+[a-z]+\s*[:=]/i;
 /**
- * One `key:value` (or `key=value`) field: the value is quoted, or runs until
- * the next `key:`/`key=` after a space or comma.
+ * Where a name or description ends: only at a known field that has a value,
+ * so names keep their spaces and colons (`name=E-mail address:`).
  */
-const QUERY_FIELD = /([a-z]+)\s*[:=](?:\s*("[^"]*"|'[^']*')|((?:(?![\s,]+[a-z]+\s*[:=]).)*))/gis;
+const NEXT_KNOWN_QUERY_FIELD = /[\s,]+(?:role|name|description|desc)\s*[:=](?=\s*[^\s,])/i;
+/**
+ * Read one field value.
+ *
+ * @param text - Text after `key:`
+ * @param field - Field the value is for
+ * @returns The value, where it ends in `text`, and whether it was quoted
+ */
+function readQueryValue(text, field) {
+    const quoted = QUOTED_QUERY_VALUE.exec(text);
+    if (quoted?.[1])
+        return { value: quoted[1].slice(1, -1), end: quoted[0].length, quoted: true };
+    const next = (field === 'role' ? NEXT_QUERY_FIELD : NEXT_KNOWN_QUERY_FIELD).exec(text);
+    const end = next ? next.index : text.length;
+    const value = text
+        .slice(0, end)
+        .trim()
+        .replace(/,+$/, '')
+        .replace(/^(["'])(.*)\1$/s, '$2');
+    return { value, end, quoted: false };
+}
 /**
  * Parses query pattern string into A11yQueryPattern object.
  *
  * Fields are `key:value` or `key=value`, separated by spaces or commas.
- * Values may contain spaces (quote them if they contain `key:`-like text).
- * Keys: role, name, description (desc). Case-insensitive.
+ * Keys: role, name, description (desc). Case-insensitive. A role ends at the
+ * next `key:`; a name or description runs to the next role/name/description
+ * field with a value, or to the end, so it may contain spaces and colons
+ * (`name=E-mail address:`). Quote a value to end it explicitly.
  *
  * @param patternString - Query pattern string
  * @returns Parsed query pattern
- * @throws CommandError (81) for unknown keys
+ * @throws CommandError (81) for unknown keys, also a misspelled one inside a name
  *
  * @example
  * ```typescript
  * parseQueryPattern('role:button name:Submit')     // { role: 'button', name: 'Submit' }
  * parseQueryPattern('role=link,name=Google Chrome') // { role: 'link', name: 'Google Chrome' }
  * parseQueryPattern('name:"Sign in" role:button')  // { name: 'Sign in', role: 'button' }
+ * parseQueryPattern('name=E-mail address:')        // { name: 'E-mail address:' }
  * ```
  */
 export function parseQueryPattern(patternString) {
     const pattern = {};
-    for (const [, rawKey = '', quoted, plain = ''] of patternString.matchAll(QUERY_FIELD)) {
-        const rawValue = quoted ?? plain;
+    let rest = patternString;
+    for (let key = QUERY_KEY.exec(rest); key; key = QUERY_KEY.exec(rest)) {
+        const rawKey = key[1] ?? '';
         const field = QUERY_FIELDS[rawKey.toLowerCase()];
-        if (!field) {
-            const err = unknownQueryFieldError(rawKey);
-            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
-        }
-        const value = rawValue
-            .trim()
-            .replace(/,+$/, '')
-            .replace(/^(["'])(.*)\1$/s, '$2');
+        if (!field)
+            throwUnknownField(rawKey);
+        const valueText = rest.slice(key.index + key[0].length);
+        const { value, end, quoted } = readQueryValue(valueText, field);
+        if (!quoted && field !== 'role')
+            checkMisspelledField(value, field);
         if (value)
             pattern[field] = value;
+        rest = valueText.slice(end);
     }
     return pattern;
 }
+/**
+ * Throw the exit-81 error for an unknown query field.
+ *
+ * @param field - The unrecognized key
+ * @param similar - A known field it looks like a typo of
+ * @param value - The name or description that absorbed it
+ * @throws CommandError (81)
+ */
+function throwUnknownField(field, similar, value) {
+    const err = unknownQueryFieldError(field, similar, value);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/** A `word:`/`word=` inside a name or description. */
+const ABSORBED_KEY = /[\s,]([a-z]+)\s*[:=]/gi;
+/**
+ * Reject a name or description that swallowed a misspelled field
+ * (`name:Save rol:button`): a `word:` within edit distance 1 of role, name or
+ * desc (2 of description). Wider distances would catch common label words
+ * (`Date:`, `Note:`, `Code:`).
+ *
+ * @param value - Unquoted name or description
+ * @param field - Field it is the value of
+ * @throws CommandError (81) with a "did you mean" suggestion
+ */
+function checkMisspelledField(value, field) {
+    for (const [, word = ''] of value.matchAll(ABSORBED_KEY)) {
+        const lower = word.toLowerCase();
+        if (QUERY_FIELDS[lower])
+            continue;
+        const similar = Object.keys(QUERY_FIELDS).find((name) => levenshteinDistance(lower, name) <= (name.length > 4 ? 2 : 1));
+        if (similar)
+            throwUnknownField(word, similar, `${field}=${value}`);
+    }
+}
 /**
  * Resolve accessibility properties for a DOM node via IPC.
  *

package/dist/telemetry/requestKinds.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Which requests an action is about (pages, API calls, sockets) and which
+ * are static assets loaded along the way (stylesheets, scripts, fonts,
+ * images), by CDP resource type.
+ */
+/** Fields a request needs to be classified */
+interface ClassifiedRequest {
+    method?: string | undefined;
+    resourceType?: string | undefined;
+    status?: number | undefined;
+    failed?: true | undefined;
+}
+/**
+ * Whether a request is worth its own line after an action: one of the
+ * {@link ACTIVITY_RESOURCE_TYPES}, one of unknown type, any request that is
+ * not a GET (a `sendBeacon` POST typed `Other`), or an asset that failed (an
+ * HTTP error or no response).
+ *
+ * @param request - Request with its method and CDP resource type
+ * @returns False for assets fetched with GET that loaded normally
+ */
+export declare function isNotableRequest(request: ClassifiedRequest): boolean;
+/**
+ * Short names of the asset types among requests, e.g. `["css", "js", "images"]`
+ * (types without a short name are lowercased, after the known ones).
+ *
+ * @param requests - Asset requests
+ * @returns Distinct names, known types first
+ */
+export declare function assetTypeNames(requests: ClassifiedRequest[]): string[];
+export {};
+//# sourceMappingURL=requestKinds.d.ts.map

package/dist/telemetry/requestKinds.js

@@ -0,0 +1,61 @@
+/**
+ * Which requests an action is about (pages, API calls, sockets) and which
+ * are static assets loaded along the way (stylesheets, scripts, fonts,
+ * images), by CDP resource type.
+ */
+/**
+ * Resource types listed one by one after an action: pages, API calls,
+ * sockets, and the requests a page sends about itself (pings, beacons,
+ * preflights, CSP reports)
+ */
+const ACTIVITY_RESOURCE_TYPES = new Set([
+    'Document',
+    'XHR',
+    'Fetch',
+    'WebSocket',
+    'EventSource',
+    'Ping',
+    'Preflight',
+    'CSPViolationReport',
+]);
+/** Short names of asset types, in the order summaries list them */
+const ASSET_TYPE_NAMES = [
+    ['Stylesheet', 'css'],
+    ['Script', 'js'],
+    ['Font', 'fonts'],
+    ['Image', 'images'],
+    ['Media', 'media'],
+];
+/**
+ * Whether a request is worth its own line after an action: one of the
+ * {@link ACTIVITY_RESOURCE_TYPES}, one of unknown type, any request that is
+ * not a GET (a `sendBeacon` POST typed `Other`), or an asset that failed (an
+ * HTTP error or no response).
+ *
+ * @param request - Request with its method and CDP resource type
+ * @returns False for assets fetched with GET that loaded normally
+ */
+export function isNotableRequest(request) {
+    if (request.resourceType === undefined || ACTIVITY_RESOURCE_TYPES.has(request.resourceType)) {
+        return true;
+    }
+    if (request.method !== undefined && request.method.toUpperCase() !== 'GET')
+        return true;
+    return request.failed === true || (request.status ?? 0) >= 400;
+}
+/**
+ * Short names of the asset types among requests, e.g. `["css", "js", "images"]`
+ * (types without a short name are lowercased, after the known ones).
+ *
+ * @param requests - Asset requests
+ * @returns Distinct names, known types first
+ */
+export function assetTypeNames(requests) {
+    const types = new Set(requests.map((request) => request.resourceType ?? 'Other'));
+    const known = ASSET_TYPE_NAMES.filter(([type]) => types.has(type)).map(([, name]) => name);
+    const others = [...types]
+        .filter((type) => !ASSET_TYPE_NAMES.some(([known]) => known === type))
+        .map((type) => type.toLowerCase());
+    return [...known, ...others];
+}
+//# sourceMappingURL=requestKinds.js.map