@push.rocks/smartpuppeteer 2.0.7 → 2.2.0

package/ts/smartpuppeteer.classes.smartpuppeteer.ts

@@ -2,9 +2,18 @@ import * as plugins from './smartpuppeteer.plugins.js';
 
 export interface IEnvAwareOptions {
   forceNoSandbox?: boolean;
+  requireSandbox?: boolean;
   usePipe?: boolean;
+  launchOptions?: plugins.puppeteer.LaunchOptions;
 }
 
+const sandboxDisablingArguments = [
+  '--disable-gpu-sandbox',
+  '--disable-seccomp-filter-sandbox',
+  '--disable-setuid-sandbox',
+  '--no-sandbox',
+];
+
 export const resolveBrowserExecutablePath = (
   candidateNamesArg: string[] = [
     'google-chrome',
@@ -28,23 +37,47 @@ export const getEnvAwareBrowserInstance = async (
 ): Promise<plugins.puppeteer.Browser> => {
   const options: IEnvAwareOptions = {
     forceNoSandbox: false,
+    requireSandbox: false,
     ...optionsArg,
   };
 
-  let chromeArgs: string[] = [];
-  if (
-    process.env.CI ||
-    options.forceNoSandbox ||
-    plugins.os.userInfo().username === 'root'
+  if (options.forceNoSandbox && options.requireSandbox) {
+    throw new Error('forceNoSandbox and requireSandbox are mutually exclusive');
+  }
+
+  const launchOptions = options.launchOptions ?? {};
+  let chromeArgs: string[] = [...(launchOptions.args ?? [])];
+  if (options.requireSandbox) {
+    const forbiddenArgument = chromeArgs.find((argument) => (
+      sandboxDisablingArguments.includes(argument.split('=', 1)[0]!)
+    ));
+    if (forbiddenArgument) {
+      throw new Error(`Sandbox-required browser launch rejects argument: ${forbiddenArgument}`);
+    }
+    if (process.platform === 'linux' && process.getuid?.() === 0) {
+      throw new Error('Sandbox-required Chromium cannot be launched as root');
+    }
+  } else if (
+    process.env.CI
+    || options.forceNoSandbox
+    || plugins.os.userInfo().username === 'root'
   ) {
-    chromeArgs = chromeArgs.concat(['--no-sandbox', '--disable-setuid-sandbox']);
+    for (const sandboxArg of ['--no-sandbox', '--disable-setuid-sandbox']) {
+      if (!chromeArgs.includes(sandboxArg)) {
+        chromeArgs.push(sandboxArg);
+      }
+    }
     console.warn('********************************************************');
     console.warn('WARNING: Launching browser without sandbox. This can be insecure!');
     console.warn('********************************************************');
   }
 
-  // Automatically choose an executable if available: prefer google-chrome, then chromium, then chromium-browser.
-  const execPath = resolveBrowserExecutablePath();
+  // Automatically choose an executable only when the caller did not select one.
+  const callerSelectedBrowser =
+    launchOptions.browser !== undefined
+    || launchOptions.channel !== undefined
+    || launchOptions.executablePath !== undefined;
+  const execPath = callerSelectedBrowser ? undefined : resolveBrowserExecutablePath();
 
   const executablePathOptions = execPath ? { executablePath: execPath } : {};
 
@@ -52,14 +85,17 @@ export const getEnvAwareBrowserInstance = async (
   console.log(chromeArgs);
   if (execPath) {
     console.log(`Using executable: ${execPath}`);
+  } else if (callerSelectedBrowser) {
+    console.log('Using browser selection from caller launch options.');
   } else {
     console.log('No specific browser executable found; falling back to Puppeteer default.');
   }
 
   const headlessBrowser = await plugins.puppeteer.launch({
-    args: chromeArgs,
-    pipe: options.usePipe ?? true,
     headless: true,
+    ...launchOptions,
+    args: chromeArgs,
+    pipe: options.usePipe ?? launchOptions.pipe ?? true,
     ...executablePathOptions,
   });
 

package/ts/smartpuppeteer.interfaces.livebrowser.ts

@@ -0,0 +1,267 @@
+import type { IEnvAwareOptions } from './smartpuppeteer.classes.smartpuppeteer.js';
+
+export type TLiveBrowserStatus = 'stopped' | 'starting' | 'running' | 'stopping';
+export type TLiveBrowserImageFormat = 'jpeg' | 'png';
+export type TLiveBrowserTabStatus = 'open' | 'crashed';
+export type TLiveBrowserWaitUntil =
+  | 'load'
+  | 'domcontentloaded'
+  | 'networkidle0'
+  | 'networkidle2';
+
+export interface ILiveBrowserViewport {
+  width: number;
+  height: number;
+  deviceScaleFactor: number;
+}
+
+export interface ILiveBrowserScreencastOptions {
+  format?: TLiveBrowserImageFormat;
+  quality?: number;
+  maxWidth?: number;
+  maxHeight?: number;
+  everyNthFrame?: number;
+}
+
+export interface ILiveBrowserSecurityOptions {
+  denyDownloads?: boolean;
+  denyFileChoosers?: boolean;
+  denyPermissions?: boolean;
+  httpNavigationOnly?: boolean;
+}
+
+export interface ILiveBrowserOperationOptions {
+  signal?: AbortSignal;
+}
+
+export type TLiveBrowserJsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | TLiveBrowserJsonValue[]
+  | { [key: string]: TLiveBrowserJsonValue };
+
+export interface ILiveBrowserEvaluateOptions {
+  tabId?: string;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  maxDepth?: number;
+  maxNodes?: number;
+  maxStringBytes?: number;
+  maxArrayLength?: number;
+  maxObjectKeys?: number;
+}
+
+export type TLiveBrowserLaunchOptions = Omit<
+  NonNullable<IEnvAwareOptions['launchOptions']>,
+  'signal'
+>;
+
+export interface ILiveBrowserSessionOptions extends Omit<IEnvAwareOptions, 'launchOptions'> {
+  launchOptions?: TLiveBrowserLaunchOptions;
+  viewport?: ILiveBrowserViewport;
+  screencast?: ILiveBrowserScreencastOptions;
+  security?: ILiveBrowserSecurityOptions;
+  allowEvaluation?: boolean;
+}
+
+export interface ILiveBrowserTabState {
+  id: string;
+  url: string;
+  title: string;
+  active: boolean;
+  status: TLiveBrowserTabStatus;
+  generation: number;
+  appliedViewportRevision: number;
+  streaming: boolean;
+}
+
+export interface ILiveBrowserError {
+  code: string;
+  message: string;
+  fatal: boolean;
+  tabId?: string;
+}
+
+export interface ILiveBrowserState {
+  status: TLiveBrowserStatus;
+  activeTabId: string | null;
+  viewportRevision: number;
+  viewport: ILiveBrowserViewport;
+  tabs: ILiveBrowserTabState[];
+  lastError?: ILiveBrowserError;
+}
+
+export interface ILiveBrowserScreencastMetadata {
+  offsetTop: number;
+  pageScaleFactor: number;
+  deviceWidth: number;
+  deviceHeight: number;
+  scrollOffsetX: number;
+  scrollOffsetY: number;
+  timestamp?: number;
+}
+
+export interface ILiveBrowserFrame {
+  tabId: string;
+  sequence: number;
+  generation: number;
+  viewportRevision: number;
+  viewport: ILiveBrowserViewport;
+  format: TLiveBrowserImageFormat;
+  mimeType: 'image/jpeg' | 'image/png';
+  width: number;
+  height: number;
+  metadata: ILiveBrowserScreencastMetadata;
+  data: Uint8Array;
+}
+
+export interface ILiveBrowserSnapshot {
+  tabId: string;
+  viewportRevision: number;
+  viewport: ILiveBrowserViewport;
+  format: TLiveBrowserImageFormat;
+  mimeType: 'image/jpeg' | 'image/png';
+  width: number;
+  height: number;
+  data: Uint8Array;
+}
+
+export interface ILiveBrowserStateEvent {
+  type: 'state';
+  state: ILiveBrowserState;
+}
+
+export interface ILiveBrowserFrameEvent {
+  type: 'frame';
+  frame: ILiveBrowserFrame;
+}
+
+export interface ILiveBrowserErrorEvent {
+  type: 'error';
+  error: ILiveBrowserError;
+}
+
+export type TLiveBrowserEvent =
+  | ILiveBrowserStateEvent
+  | ILiveBrowserFrameEvent
+  | ILiveBrowserErrorEvent;
+
+export type TLiveBrowserEventListener = (event: TLiveBrowserEvent) => void;
+
+export interface ILiveBrowserFrameAcknowledgement {
+  accepted: boolean;
+}
+
+export interface ILiveBrowserFrameAcknowledgementRequest {
+  tabId: string;
+  sequence: number;
+  generation: number;
+  viewportRevision: number;
+}
+
+export interface ILiveBrowserCreateTabOptions {
+  url?: string;
+  activate?: boolean;
+  timeoutMs?: number;
+  waitUntil?: TLiveBrowserWaitUntil;
+}
+
+export interface ILiveBrowserNavigationOptions {
+  tabId?: string;
+  timeoutMs?: number;
+  waitUntil?: TLiveBrowserWaitUntil;
+}
+
+export interface ILiveBrowserNavigateOptions extends ILiveBrowserNavigationOptions {
+  url: string;
+}
+
+export interface ILiveBrowserModifierState {
+  alt?: boolean;
+  control?: boolean;
+  meta?: boolean;
+  shift?: boolean;
+}
+
+export interface ILiveBrowserInputBase {
+  tabId: string;
+  generation: number;
+  viewportRevision: number;
+}
+
+export interface ILiveBrowserMouseInput extends ILiveBrowserInputBase {
+  type: 'move' | 'down' | 'up';
+  x: number;
+  y: number;
+  button?: 'none' | 'left' | 'middle' | 'right' | 'back' | 'forward';
+  buttons?: number;
+  clickCount?: number;
+  modifiers?: ILiveBrowserModifierState;
+}
+
+export interface ILiveBrowserWheelInput extends ILiveBrowserInputBase {
+  x: number;
+  y: number;
+  deltaX: number;
+  deltaY: number;
+  modifiers?: ILiveBrowserModifierState;
+}
+
+export interface ILiveBrowserKeyInput extends ILiveBrowserInputBase {
+  type: 'down' | 'up';
+  key: string;
+  code?: string;
+  text?: string;
+  unmodifiedText?: string;
+  windowsVirtualKeyCode?: number;
+  nativeVirtualKeyCode?: number;
+  autoRepeat?: boolean;
+  isKeypad?: boolean;
+  location?: number;
+  modifiers?: ILiveBrowserModifierState;
+}
+
+export interface ILiveBrowserInsertTextInput extends ILiveBrowserInputBase {
+  text: string;
+}
+
+export interface ILiveBrowserSemanticActionBase extends ILiveBrowserInputBase {
+  selector: string;
+  timeoutMs?: number;
+}
+
+export interface ILiveBrowserClickOptions extends ILiveBrowserSemanticActionBase {
+  button?: 'left' | 'middle' | 'right';
+  clickCount?: number;
+}
+
+export interface ILiveBrowserFillOptions extends ILiveBrowserSemanticActionBase {
+  text: string;
+}
+
+export interface ILiveBrowserPressOptions extends ILiveBrowserSemanticActionBase {
+  key: string;
+}
+
+export interface ILiveBrowserSnapshotOptions {
+  tabId?: string;
+  format?: TLiveBrowserImageFormat;
+  quality?: number;
+}
+
+export interface ILiveBrowserObserveOptions {
+  tabId?: string;
+  maxCharacters?: number;
+}
+
+export interface ILiveBrowserObservation {
+  tabId: string;
+  url: string;
+  title: string;
+  tab: ILiveBrowserTabState;
+  state: ILiveBrowserState;
+  text: string;
+  truncated: boolean;
+}

package/ts/smartpuppeteer.plugins.ts

@@ -1,7 +1,8 @@
 // node native scope
+import { Buffer } from 'node:buffer';
 import * as os from 'os';
 
-export { os };
+export { Buffer, os };
 
 // @pushrocks scope
 import * as smartdelay from '@push.rocks/smartdelay';
@@ -10,7 +11,7 @@ import * as smartshell from '@push.rocks/smartshell';
 export { smartdelay, smartshell };
 
 // third party scope
-import puppeteer from 'puppeteer';
+import * as puppeteer from 'puppeteer';
 import treeKill from 'tree-kill';
 
 export { puppeteer, treeKill };

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-import puppeteer from 'puppeteer';
-export declare const getEnvAwareBrowserInstance: () => Promise<puppeteer.Browser>;
-export { puppeteer };

package/dist/index.js

@@ -1,18 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const puppeteer_1 = __importDefault(require("puppeteer"));
-exports.puppeteer = puppeteer_1.default;
-exports.getEnvAwareBrowserInstance = async () => {
-    let chromeArgs = [];
-    if (process.env.CI) {
-        chromeArgs = chromeArgs.concat(['--no-sandbox', '--disable-setuid-sandbox']);
-    }
-    const headlessBrowser = await puppeteer_1.default.launch({
-        args: chromeArgs
-    });
-    return headlessBrowser;
-};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7OztBQUFBLDBEQUFrQztBQWF6QixvQkFiRixtQkFBUyxDQWFFO0FBWEwsUUFBQSwwQkFBMEIsR0FBRyxLQUFLLElBQWdDLEVBQUU7SUFDL0UsSUFBSSxVQUFVLEdBQWEsRUFBRSxDQUFDO0lBQzlCLElBQUksT0FBTyxDQUFDLEdBQUcsQ0FBQyxFQUFFLEVBQUU7UUFDbEIsVUFBVSxHQUFHLFVBQVUsQ0FBQyxNQUFNLENBQUMsQ0FBQyxjQUFjLEVBQUUsMEJBQTBCLENBQUMsQ0FBQyxDQUFDO0tBQzlFO0lBQ0QsTUFBTSxlQUFlLEdBQUcsTUFBTSxtQkFBUyxDQUFDLE1BQU0sQ0FBQztRQUM3QyxJQUFJLEVBQUUsVUFBVTtLQUNqQixDQUFDLENBQUM7SUFDSCxPQUFPLGVBQWUsQ0FBQztBQUN6QixDQUFDLENBQUMifQ==