@browserless.io/browserless 2.1.0 → 2.1.1

package/build/http.d.ts

@@ -119,6 +119,9 @@ export declare enum HTTPRoutes {
     content = "/content",
     download = "/download",
     function = "/function",
+    jsonList = "/json/list",
+    jsonNew = "/json/new",
+    jsonProtocol = "/json/protocol",
     jsonVersion = "/json/version",
     pdf = "/pdf",
     performance = "/performance",

package/build/http.js

@@ -83,6 +83,9 @@ export var HTTPRoutes;
     HTTPRoutes["content"] = "/content";
     HTTPRoutes["download"] = "/download";
     HTTPRoutes["function"] = "/function";
+    HTTPRoutes["jsonList"] = "/json/list";
+    HTTPRoutes["jsonNew"] = "/json/new";
+    HTTPRoutes["jsonProtocol"] = "/json/protocol";
     HTTPRoutes["jsonVersion"] = "/json/version";
     HTTPRoutes["pdf"] = "/pdf";
     HTTPRoutes["performance"] = "/performance";

package/build/routes/chromium/http/content-post.body.json

@@ -398,14 +398,14 @@
                 "length": {
                   "type": "number"
                 },
-                "__@toStringTag@10755": {
+                "__@toStringTag@10788": {
                   "type": "string",
                   "const": "Uint8Array"
                 }
               },
               "required": [
                 "BYTES_PER_ELEMENT",
-                "__@toStringTag@10755",
+                "__@toStringTag@10788",
                 "buffer",
                 "byteLength",
                 "byteOffset",
@@ -440,13 +440,13 @@
         "byteLength": {
           "type": "number"
         },
-        "__@toStringTag@10755": {
+        "__@toStringTag@10788": {
           "type": "string"
         }
       },
       "additionalProperties": false,
       "required": [
-        "__@toStringTag@10755",
+        "__@toStringTag@10788",
         "byteLength"
       ]
     },
@@ -456,18 +456,18 @@
         "byteLength": {
           "type": "number"
         },
-        "__@species@10856": {
+        "__@species@10889": {
           "$ref": "#/definitions/SharedArrayBuffer"
         },
-        "__@toStringTag@10755": {
+        "__@toStringTag@10788": {
           "type": "string",
           "const": "SharedArrayBuffer"
         }
       },
       "additionalProperties": false,
       "required": [
-        "__@species@10856",
-        "__@toStringTag@10755",
+        "__@species@10889",
+        "__@toStringTag@10788",
         "byteLength"
       ]
     },

package/build/routes/chromium/http/json-list.d.ts

@@ -0,0 +1,15 @@
+import { APITags, HTTPRoute, HTTPRoutes, Methods, Request, Response, contentTypes } from '@browserless.io/browserless';
+import { getCDPJSONPayload } from '../utils/cdp.js';
+export type ResponseSchema = Array<ReturnType<typeof getCDPJSONPayload>>;
+export default class GetJSONList extends HTTPRoute {
+    accepts: contentTypes[];
+    auth: boolean;
+    browser: null;
+    concurrency: boolean;
+    contentTypes: contentTypes[];
+    description: string;
+    method: Methods;
+    path: HTTPRoutes;
+    tags: APITags[];
+    handler: (_req: Request, res: Response) => Promise<void>;
+}

package/build/routes/chromium/http/json-list.js

@@ -0,0 +1,23 @@
+import { APITags, HTTPRoute, HTTPRoutes, Methods, contentTypes, dedent, jsonResponse, } from '@browserless.io/browserless';
+import { getCDPJSONPayload } from '../utils/cdp.js';
+export default class GetJSONList extends HTTPRoute {
+    accepts = [contentTypes.any];
+    auth = true;
+    browser = null;
+    concurrency = false;
+    contentTypes = [contentTypes.json];
+    description = dedent(`
+    Returns a JSON payload that acts as a pass-through to the DevTools /json/list HTTP API in Chromium.
+    Browserless mocks this payload so that remote clients can connect to the underlying "webSocketDebuggerUrl"
+    which will cause Browserless to start the browser and proxy that request into a blank page.
+  `);
+    method = Methods.get;
+    path = HTTPRoutes.jsonList;
+    tags = [APITags.browserAPI];
+    handler = async (_req, res) => {
+        const config = this.config();
+        const externalAddress = config.getExternalAddress();
+        const payload = getCDPJSONPayload(externalAddress);
+        return jsonResponse(res, 200, [payload]);
+    };
+}

package/build/routes/chromium/http/json-list.response.json

@@ -0,0 +1,52 @@
+{
+  "type": "array",
+  "items": {
+    "$ref": "#/definitions/CDPJSONPayload"
+  },
+  "definitions": {
+    "CDPJSONPayload": {
+      "type": "object",
+      "properties": {
+        "description": {
+          "description": "The description of the target. Generally the page's title.",
+          "type": "string"
+        },
+        "devtoolsFrontendUrl": {
+          "description": "The fully-qualified URL of the Devtools inspector app.",
+          "type": "string"
+        },
+        "id": {
+          "description": "A Unique Id for the underlying target.",
+          "type": "string"
+        },
+        "title": {
+          "description": "The title of the target. For pages this is the page's title.",
+          "type": "string"
+        },
+        "type": {
+          "description": "The type of target, generally \"page\" or \"background_page\".",
+          "type": "string"
+        },
+        "url": {
+          "description": "The current URL the target is consuming or visiting.",
+          "type": "string"
+        },
+        "webSocketDebuggerUrl": {
+          "description": "The target or page's WebSocket Debugger URL. Primarily used for legacy\nlibraries to connect and inspect or remote automate this target.",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "description",
+        "devtoolsFrontendUrl",
+        "id",
+        "title",
+        "type",
+        "url",
+        "webSocketDebuggerUrl"
+      ]
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/build/routes/chromium/http/json-new.d.ts

@@ -0,0 +1,15 @@
+import { APITags, HTTPRoute, HTTPRoutes, Methods, Request, Response, contentTypes } from '@browserless.io/browserless';
+import { getCDPJSONPayload } from '../utils/cdp.js';
+export type ResponseSchema = ReturnType<typeof getCDPJSONPayload>;
+export default class GetJSONList extends HTTPRoute {
+    accepts: contentTypes[];
+    auth: boolean;
+    browser: null;
+    concurrency: boolean;
+    contentTypes: contentTypes[];
+    description: string;
+    method: Methods;
+    path: HTTPRoutes;
+    tags: APITags[];
+    handler: (_req: Request, res: Response) => Promise<void>;
+}

package/build/routes/chromium/http/json-new.js

@@ -0,0 +1,23 @@
+import { APITags, HTTPRoute, HTTPRoutes, Methods, contentTypes, dedent, jsonResponse, } from '@browserless.io/browserless';
+import { getCDPJSONPayload } from '../utils/cdp.js';
+export default class GetJSONList extends HTTPRoute {
+    accepts = [contentTypes.any];
+    auth = true;
+    browser = null;
+    concurrency = false;
+    contentTypes = [contentTypes.json];
+    description = dedent(`
+    Returns a JSON payload that acts as a pass-through to the DevTools /json/list HTTP API in Chromium.
+    Browserless mocks this payload so that remote clients can connect to the underlying "webSocketDebuggerUrl"
+    which will cause Browserless to start the browser and proxy that request into a blank page.
+  `);
+    method = Methods.put;
+    path = HTTPRoutes.jsonNew;
+    tags = [APITags.browserAPI];
+    handler = async (_req, res) => {
+        const config = this.config();
+        const externalAddress = config.getExternalAddress();
+        const payload = getCDPJSONPayload(externalAddress);
+        return jsonResponse(res, 200, payload);
+    };
+}

package/build/routes/chromium/http/json-new.response.json

@@ -0,0 +1,44 @@
+{
+  "type": "object",
+  "properties": {
+    "description": {
+      "description": "The description of the target. Generally the page's title.",
+      "type": "string"
+    },
+    "devtoolsFrontendUrl": {
+      "description": "The fully-qualified URL of the Devtools inspector app.",
+      "type": "string"
+    },
+    "id": {
+      "description": "A Unique Id for the underlying target.",
+      "type": "string"
+    },
+    "title": {
+      "description": "The title of the target. For pages this is the page's title.",
+      "type": "string"
+    },
+    "type": {
+      "description": "The type of target, generally \"page\" or \"background_page\".",
+      "type": "string"
+    },
+    "url": {
+      "description": "The current URL the target is consuming or visiting.",
+      "type": "string"
+    },
+    "webSocketDebuggerUrl": {
+      "description": "The target or page's WebSocket Debugger URL. Primarily used for legacy\nlibraries to connect and inspect or remote automate this target.",
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "required": [
+    "description",
+    "devtoolsFrontendUrl",
+    "id",
+    "title",
+    "type",
+    "url",
+    "webSocketDebuggerUrl"
+  ],
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/build/routes/chromium/http/json-protocol-get.d.ts

@@ -0,0 +1,15 @@
+import { APITags, HTTPRoute, HTTPRoutes, Methods, Request, Response, contentTypes } from '@browserless.io/browserless';
+export type ResponseSchema = object;
+export default class GetJSONVersion extends HTTPRoute {
+    accepts: contentTypes[];
+    auth: boolean;
+    browser: null;
+    concurrency: boolean;
+    contentTypes: contentTypes[];
+    description: string;
+    method: Methods;
+    path: HTTPRoutes;
+    tags: APITags[];
+    private cachedProtocol;
+    handler: (_req: Request, res: Response) => Promise<void>;
+}

package/build/routes/chromium/http/json-protocol-get.js

@@ -0,0 +1,20 @@
+import { APITags, HTTPRoute, HTTPRoutes, Methods, contentTypes, jsonResponse, } from '@browserless.io/browserless';
+export default class GetJSONVersion extends HTTPRoute {
+    accepts = [contentTypes.any];
+    auth = true;
+    browser = null;
+    concurrency = false;
+    contentTypes = [contentTypes.json];
+    description = `Returns Protocol JSON meta-data that Chrome comes with.`;
+    method = Methods.get;
+    path = HTTPRoutes.jsonProtocol;
+    tags = [APITags.browserAPI];
+    cachedProtocol;
+    handler = async (_req, res) => {
+        const browserManager = this.browserManager();
+        if (!this.cachedProtocol) {
+            this.cachedProtocol = await browserManager.getProtocolJSON();
+        }
+        return jsonResponse(res, 200, this.cachedProtocol);
+    };
+}

package/build/routes/chromium/http/json-protocol-get.response.json

@@ -0,0 +1,6 @@
+{
+  "type": "object",
+  "properties": {},
+  "additionalProperties": true,
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/build/routes/chromium/http/json-version-get.d.ts

@@ -1,4 +1,4 @@
-import { APITags, BrowserManager, HTTPRoutes, HTTPRoute, Methods, Request, Response, UnwrapPromise, contentTypes } from '@browserless.io/browserless';
+import { APITags, BrowserManager, HTTPRoute, HTTPRoutes, Methods, Request, Response, UnwrapPromise, contentTypes } from '@browserless.io/browserless';
 export type ResponseSchema = UnwrapPromise<ReturnType<BrowserManager['getVersionJSON']>>;
 export default class GetJSONVersion extends HTTPRoute {
     accepts: contentTypes[];

package/build/routes/chromium/http/json-version-get.js

@@ -1,4 +1,4 @@
-import { APITags, HTTPRoutes, HTTPRoute, Methods, contentTypes, jsonResponse, writeResponse, } from '@browserless.io/browserless';
+import { APITags, HTTPRoute, HTTPRoutes, Methods, contentTypes, jsonResponse, writeResponse, } from '@browserless.io/browserless';
 export default class GetJSONVersion extends HTTPRoute {
     accepts = [contentTypes.any];
     auth = true;

package/build/routes/chromium/http/pdf-post.body.json

@@ -462,6 +462,10 @@
           "description": "Generate tagged (accessible) PDF.",
           "type": "boolean"
         },
+        "outline": {
+          "description": "Generate document outline.",
+          "type": "boolean"
+        },
         "timeout": {
           "description": "Timeout in milliseconds. Pass `0` to disable timeout.",
           "type": "number"
@@ -538,14 +542,14 @@
                 "length": {
                   "type": "number"
                 },
-                "__@toStringTag@53628": {
+                "__@toStringTag@75058": {
                   "type": "string",
                   "const": "Uint8Array"
                 }
               },
               "required": [
                 "BYTES_PER_ELEMENT",
-                "__@toStringTag@53628",
+                "__@toStringTag@75058",
                 "buffer",
                 "byteLength",
                 "byteOffset",
@@ -580,13 +584,13 @@
         "byteLength": {
           "type": "number"
         },
-        "__@toStringTag@53628": {
+        "__@toStringTag@75058": {
           "type": "string"
         }
       },
       "additionalProperties": false,
       "required": [
-        "__@toStringTag@53628",
+        "__@toStringTag@75058",
         "byteLength"
       ]
     },
@@ -596,18 +600,18 @@
         "byteLength": {
           "type": "number"
         },
-        "__@species@53729": {
+        "__@species@75159": {
           "$ref": "#/definitions/SharedArrayBuffer"
         },
-        "__@toStringTag@53628": {
+        "__@toStringTag@75058": {
           "type": "string",
           "const": "SharedArrayBuffer"
         }
       },
       "additionalProperties": false,
       "required": [
-        "__@species@53729",
-        "__@toStringTag@53628",
+        "__@species@75159",
+        "__@toStringTag@75058",
         "byteLength"
       ]
     },

package/build/routes/chromium/http/scrape-post.body.json

@@ -445,14 +445,14 @@
                 "length": {
                   "type": "number"
                 },
-                "__@toStringTag@64541": {
+                "__@toStringTag@107362": {
                   "type": "string",
                   "const": "Uint8Array"
                 }
               },
               "required": [
                 "BYTES_PER_ELEMENT",
-                "__@toStringTag@64541",
+                "__@toStringTag@107362",
                 "buffer",
                 "byteLength",
                 "byteOffset",
@@ -487,13 +487,13 @@
         "byteLength": {
           "type": "number"
         },
-        "__@toStringTag@64541": {
+        "__@toStringTag@107362": {
           "type": "string"
         }
       },
       "additionalProperties": false,
       "required": [
-        "__@toStringTag@64541",
+        "__@toStringTag@107362",
         "byteLength"
       ]
     },
@@ -503,18 +503,18 @@
         "byteLength": {
           "type": "number"
         },
-        "__@species@64642": {
+        "__@species@107463": {
           "$ref": "#/definitions/SharedArrayBuffer"
         },
-        "__@toStringTag@64541": {
+        "__@toStringTag@107362": {
           "type": "string",
           "const": "SharedArrayBuffer"
         }
       },
       "additionalProperties": false,
       "required": [
-        "__@species@64642",
-        "__@toStringTag@64541",
+        "__@species@107463",
+        "__@toStringTag@107362",
         "byteLength"
       ]
     },

package/build/routes/chromium/http/screenshot-post.body.json

@@ -488,14 +488,14 @@
                 "length": {
                   "type": "number"
                 },
-                "__@toStringTag@75532": {
+                "__@toStringTag@118386": {
                   "type": "string",
                   "const": "Uint8Array"
                 }
               },
               "required": [
                 "BYTES_PER_ELEMENT",
-                "__@toStringTag@75532",
+                "__@toStringTag@118386",
                 "buffer",
                 "byteLength",
                 "byteOffset",
@@ -530,13 +530,13 @@
         "byteLength": {
           "type": "number"
         },
-        "__@toStringTag@75532": {
+        "__@toStringTag@118386": {
           "type": "string"
         }
       },
       "additionalProperties": false,
       "required": [
-        "__@toStringTag@75532",
+        "__@toStringTag@118386",
         "byteLength"
       ]
     },
@@ -546,18 +546,18 @@
         "byteLength": {
           "type": "number"
         },
-        "__@species@75633": {
+        "__@species@118487": {
           "$ref": "#/definitions/SharedArrayBuffer"
         },
-        "__@toStringTag@75532": {
+        "__@toStringTag@118386": {
           "type": "string",
           "const": "SharedArrayBuffer"
         }
       },
       "additionalProperties": false,
       "required": [
-        "__@species@75633",
-        "__@toStringTag@75532",
+        "__@species@118487",
+        "__@toStringTag@118386",
         "byteLength"
       ]
     },

package/build/routes/chromium/utils/cdp.d.ts

@@ -0,0 +1,2 @@
+import { CDPJSONPayload } from '@browserless.io/browserless';
+export declare const getCDPJSONPayload: (externalAddress: string) => CDPJSONPayload;

package/build/routes/chromium/utils/cdp.js

@@ -0,0 +1,14 @@
+import { pageID } from '@browserless.io/browserless';
+export const getCDPJSONPayload = (externalAddress) => {
+    const id = pageID();
+    const { protocol, host, pathname, href } = new URL(`/devtools/page/${id}`, externalAddress);
+    return {
+        description: '',
+        devtoolsFrontendUrl: `/devtools/inspector.html?${protocol.replace(':', '')}=${host}${pathname}`,
+        id,
+        title: 'New Tab',
+        type: 'page',
+        url: 'about:blank',
+        webSocketDebuggerUrl: href,
+    };
+};

package/build/types.d.ts

@@ -438,4 +438,35 @@ export interface IBrowserlessStats {
     unhealthy: number;
     units: number;
 }
+export interface CDPJSONPayload {
+    /**
+     * The description of the target. Generally the page's title.
+     */
+    description: string;
+    /**
+     * The fully-qualified URL of the Devtools inspector app.
+     */
+    devtoolsFrontendUrl: string;
+    /**
+     * A Unique Id for the underlying target.
+     */
+    id: string;
+    /**
+     * The title of the target. For pages this is the page's title.
+     */
+    title: string;
+    /**
+     * The type of target, generally "page" or "background_page".
+     */
+    type: string;
+    /**
+     * The current URL the target is consuming or visiting.
+     */
+    url: string;
+    /**
+     * The target or page's WebSocket Debugger URL. Primarily used for legacy
+     * libraries to connect and inspect or remote automate this target.
+     */
+    webSocketDebuggerUrl: string;
+}
 export {};

package/build/utils.d.ts

@@ -12,6 +12,15 @@ export declare const tsExtension = ".d.ts";
 export declare const jsonExtension = ".json";
 export declare const jsExtension = ".js";
 export declare const id: () => string;
+/**
+ * Generates a random, Chrome-compliant page ID with "BLESS"
+ * prepended. This prepended text signals to other parts of the
+ * system that this is a Browserless-created ID so it can be appropriately
+ * handled.
+ *
+ * @returns {string} A random Page ID
+ */
+export declare const pageID: () => string;
 export declare const createLogger: (domain: string) => debug.Debugger;
 export declare const dedent: (strings: string | string[], ...values: string[]) => string;
 export declare const isConnected: (connection: Duplex | ServerResponse) => boolean;

package/build/utils.js

@@ -1,5 +1,5 @@
 import * as fs from 'fs/promises';
-import { CDPChromium, PlaywrightChromium, PlaywrightFirefox, PlaywrightWebkit, codes, contentTypes, encodings, encryptionAlgo, encryptionSep, } from '@browserless.io/browserless';
+import { BLESS_PAGE_IDENTIFIER, CDPChromium, PlaywrightChromium, PlaywrightFirefox, PlaywrightWebkit, codes, contentTypes, encodings, encryptionAlgo, encryptionSep, } from '@browserless.io/browserless';
 import playwright from 'playwright-core';
 import crypto from 'crypto';
 import debug from 'debug';
@@ -26,6 +26,21 @@ export const tsExtension = '.d.ts';
 export const jsonExtension = '.json';
 export const jsExtension = '.js';
 export const id = () => crypto.randomUUID();
+/**
+ * Generates a random, Chrome-compliant page ID with "BLESS"
+ * prepended. This prepended text signals to other parts of the
+ * system that this is a Browserless-created ID so it can be appropriately
+ * handled.
+ *
+ * @returns {string} A random Page ID
+ */
+export const pageID = () => {
+    const chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+    const id = Array.from({ length: 32 - BLESS_PAGE_IDENTIFIER.length })
+        .map(() => chars[Math.floor(Math.random() * chars.length)])
+        .join('');
+    return `${BLESS_PAGE_IDENTIFIER}${id}`;
+};
 export const createLogger = (domain) => {
     return debug(`browserless.io:${domain}`);
 };
@@ -158,7 +173,7 @@ export const removeNullStringify = (json, allowNull = true) => {
             return value;
         if (value !== null)
             return value;
-    });
+    }, '  ');
 };
 export const jsonOrString = (maybeJson) => safeParse(maybeJson) ?? maybeJson;
 export const readBody = async (req) => {