arn-browser 0.1.31 → 0.1.33

package/src/utility/playwright/pwLaunch.js

@@ -18,7 +18,8 @@ import { FingerprintGenerator } from "fingerprint-generator";
 
 // Internal Utilities
 import { getMultiloginToken } from "../mlx_token.js";
-import { deleteDirectoryWithRetries } from "../deleteDirectory.js";
+import { deleteDirectoryWithRetries } from "./deleteDirectory.js";
+import { findBrowserPath } from "./findBrowserPath.js";
 
 // Human Cursor - for human-like mouse movements
 import { createCursor } from "./human-cursor/index.js";
@@ -70,7 +71,8 @@ function resolveProfilePath(nameOrPath, browserName) {
 
 	let prefix = browserName.toLowerCase();
 	if (prefix.includes("brave")) prefix = "brave";
-	else if (prefix.includes("chrome") || prefix.includes("chromium")) prefix = "chromium";
+	else if (prefix.includes("chromium")) prefix = "chromium";
+	else if (prefix.includes("chrome")) prefix = "chrome";
 	else if (prefix.includes("firefox")) prefix = "firefox";
 	else if (prefix.includes("camoufox")) prefix = "camoufox";
 
@@ -78,70 +80,8 @@ function resolveProfilePath(nameOrPath, browserName) {
 	return path.join(PERSISTENT_DIR, folderName);
 }
 
-/**
- * Locates binaries for manual browsers (Brave).
- * Uses ~/.arn-browser/browsers/{browser}/{executable}
- */
-function getBinaryPath(browserName) {
-	const isWindows = process.platform === "win32";
-	const browsersDir = path.join(ARN_BROWSER_DIR, "browsers");
-
-	const binaryMap = {
-		brave: isWindows
-			? path.join(browsersDir, "brave", "brave.exe")
-			: path.join(browsersDir, "brave", "brave"),
-	};
-
-	const binaryPath = binaryMap[browserName];
-	if (!binaryPath) {
-		throw new Error(
-			`░░░░░ [LaunchBrowser] Unknown browser for getBinaryPath: ${browserName}`
-		);
-	}
-
-	if (!fs.existsSync(binaryPath)) {
-		throw new Error(
-			`░░░░░ [LaunchBrowser] ${browserName} binary not found at: ${binaryPath}\n` +
-			`   Run "node bin/cli.js install" to install browsers.`
-		);
-	}
-
-	return binaryPath;
-}
-
-/**
- * Gets the executable path for Playwright-managed browsers (Chromium, Firefox).
- * Uses ~/.arn-browser/browsers/{browser}/{executable}
- */
-function getPlaywrightExePath(browserName) {
-	const isWindows = process.platform === "win32";
-	const browsersDir = path.join(ARN_BROWSER_DIR, "browsers");
-
-	const binaryMap = {
-		chromium: isWindows
-			? path.join(browsersDir, "chromium", "chrome.exe")
-			: path.join(browsersDir, "chromium", "chrome"),
-		firefox: isWindows
-			? path.join(browsersDir, "firefox", "firefox.exe")
-			: path.join(browsersDir, "firefox", "firefox"),
-	};
-
-	const binaryPath = binaryMap[browserName];
-	if (!binaryPath) {
-		throw new Error(
-			`░░░░░ [LaunchBrowser] Unknown browser: ${browserName}`
-		);
-	}
-
-	if (!fs.existsSync(binaryPath)) {
-		throw new Error(
-			`░░░░░ [LaunchBrowser] ${browserName} binary not found at: ${binaryPath}\n` +
-			`   Run "node bin/cli.js install" to install browsers.`
-		);
-	}
-
-	return binaryPath;
-}
+// Browser path resolution now uses OS-installed browsers via findBrowserPath.
+// See src/utility/findBrowserPath.js for detection logic.
 
 const PROFILE_META_FILE = "_profile_meta.json";
 
@@ -175,6 +115,31 @@ function writeProfileMeta(dirPath, type, cleanupMinutes) {
 	}
 }
 
+/**
+ * Writes per-host notification permissions into the Chrome Preferences object.
+ * Accepts plain hostnames (e.g. "web.whatsapp.com") and converts them
+ * to Chrome's internal format: "https://host:443,*" with setting=1 (Allow).
+ * If hosts array is empty, does nothing (Chrome default "Ask" behavior).
+ */
+function writeNotificationPermissions(prefs, hosts) {
+	if (!hosts || hosts.length === 0) return;
+
+	if (!prefs.profile) prefs.profile = {};
+	if (!prefs.profile.content_settings) prefs.profile.content_settings = {};
+	if (!prefs.profile.content_settings.exceptions) prefs.profile.content_settings.exceptions = {};
+	if (!prefs.profile.content_settings.exceptions.notifications) prefs.profile.content_settings.exceptions.notifications = {};
+
+	const now = String(Date.now());
+	for (const host of hosts) {
+		const origin = host.startsWith("http") ? host : `https://${host}:443`;
+		const key = `${origin},*`;
+		prefs.profile.content_settings.exceptions.notifications[key] = {
+			last_modified: now,
+			setting: 1, // 1 = Allow
+		};
+	}
+}
+
 /**
  * Scans both persistent and temp profile directories.
  * Deletes profiles whose `_profile_meta.json` indicates they are expired.
@@ -339,6 +304,10 @@ export async function pwLaunch({
 	camoufox_options = {}, // { geoip, humanize, ... }
 	multilogin_options = {}, // { profileId, os_type, canvas_noise, ... }
 
+	// Notifications — per-host allow list
+	// Pass plain hostnames: ["web.whatsapp.com", "messages.google.com"]
+	notification_hosts = [],
+
 	// Logging
 	launch_logs = false,
 	cleanup_logs = false,
@@ -385,6 +354,8 @@ export async function pwLaunch({
 					humanize_options: effectiveHumanizeOptions,
 					spoof_fingerprint,
 					cleanupMinutes: effectiveCleanupMinutes,
+					browserType: which_browser, // "chrome" or "chromium"
+					notification_hosts,
 				});
 				break;
 			case "firefox":
@@ -407,6 +378,7 @@ export async function pwLaunch({
 					humanize_options: effectiveHumanizeOptions,
 					spoof_fingerprint,
 					cleanupMinutes: effectiveCleanupMinutes,
+					notification_hosts,
 				});
 				break;
 			case "camoufox":
@@ -442,7 +414,7 @@ export async function pwLaunch({
 // ==========================================================================
 // 4. ENGINE: CHROMIUM
 // ==========================================================================
-async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, humanize_options, spoof_fingerprint, cleanupMinutes }) {
+async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, humanize_options, spoof_fingerprint, cleanupMinutes, browserType = "chromium", notification_hosts = [] }) {
 	const isPersistent = !!profilePath;
 
 	// 1. Determine Path (Temp needs it for fingerprint storage, Persistent needs it for data)
@@ -471,6 +443,8 @@ async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, hum
 		// --- Silence & Networking ---
 		"--disable-background-networking",
 		"--disable-background-timer-throttling",
+		"--disable-backgrounding-occluded-windows",
+		"--disable-renderer-backgrounding",
 		"--disable-breakpad",
 		"--disable-crash-reporter",
 		"--disable-component-update",
@@ -504,7 +478,7 @@ async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, hum
 			// Launch standard browser (not persistent context)
 			const browser = await chromium.launch({
 				headless: false,
-				executablePath: getPlaywrightExePath("chromium"),
+				executablePath: findBrowserPath(browserType),
 				proxy: proxyObj,
 				args: args,
 				ignoreDefaultArgs: ignoreDefaultArgs,
@@ -558,6 +532,7 @@ async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, hum
 
 				if (!prefs.profile) prefs.profile = {};
 				prefs.profile.exit_type = "Normal";
+				writeNotificationPermissions(prefs, notification_hosts);
 
 				if (!prefs.session) prefs.session = {};
 				prefs.session.restore_on_startup = 4;
@@ -571,7 +546,7 @@ async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, hum
 			// Logic: Native Persistent Launch. No fingerprint-injector.
 			const context = await chromium.launchPersistentContext(activePath, {
 				headless: false,
-				executablePath: getPlaywrightExePath("chromium"),
+				executablePath: findBrowserPath(browserType),
 				proxy: proxyObj,
 				args: args,
 				timezoneId: tz,
@@ -625,7 +600,7 @@ async function firefoxLauncher({ profilePath, proxy, timezoneId, humanize_option
 
 			const browser = await firefox.launch({
 				headless: false,
-				executablePath: getPlaywrightExePath("firefox"),
+				executablePath: findBrowserPath("firefox"),
 				proxy: proxyObj,
 				ignoreDefaultArgs: ["--enable-automation"],
 				firefoxUserPrefs: firefoxUserPrefs,
@@ -667,7 +642,7 @@ async function firefoxLauncher({ profilePath, proxy, timezoneId, humanize_option
 
 			const context = await firefox.launchPersistentContext(activePath, {
 				headless: false,
-				executablePath: getPlaywrightExePath("firefox"),
+				executablePath: findBrowserPath("firefox"),
 				proxy: proxyObj,
 				timezoneId: tz,
 				ignoreDefaultArgs: ["--enable-automation"],
@@ -691,7 +666,7 @@ async function firefoxLauncher({ profilePath, proxy, timezoneId, humanize_option
 // ==========================================================================
 // 6. ENGINE: BRAVE
 // ==========================================================================
-async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, humanize_options, spoof_fingerprint, cleanupMinutes }) {
+async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, humanize_options, spoof_fingerprint, cleanupMinutes, notification_hosts = [] }) {
 	const isPersistent = !!profilePath;
 	const activePath = isPersistent ? profilePath : path.join(TEMP_DIR, crypto.randomUUID());
 
@@ -744,7 +719,7 @@ async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, humani
 		}
 	}
 
-	const braveBin = getBinaryPath("brave");
+	const braveBin = findBrowserPath("brave");
 
 	// ======================================================
 	// Disable Brave Sidebar via Preferences
@@ -766,6 +741,7 @@ async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, humani
 		// Prevent tab restore (saves proxy bandwidth)
 		if (!prefs.profile) prefs.profile = {};
 		prefs.profile.exit_type = "Normal";
+		writeNotificationPermissions(prefs, notification_hosts);
 
 		if (!prefs.session) prefs.session = {};
 		prefs.session.restore_on_startup = 4;
@@ -819,6 +795,8 @@ async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, humani
 		// --- Silence & Networking ---
 		"--disable-background-networking",
 		"--disable-background-timer-throttling",
+		"--disable-backgrounding-occluded-windows",
+		"--disable-renderer-backgrounding",
 		"--disable-breakpad",
 		"--disable-crash-reporter",
 		"--disable-component-update",

package/src/utility/puppeteer/deleteDirectory.js

@@ -0,0 +1,104 @@
+import fs from "fs";
+import path from "path";
+import { setTimeout as sleep } from "timers/promises";
+
+/**
+ * Deletes a directory with built-in retry logic.
+ * Useful for browser profiles where files might still be locked by the OS process.
+ * * @param {string} targetPath - The absolute path to delete.
+ * @param {number} maxRetries - How many times to retry (default: 5).
+ * @param {number} retryDelayMs - Time to wait between retries (default: 2000ms).
+ */
+export async function deleteDirectoryWithRetries(targetPath, maxRetries = 5, retryDelayMs = 2000) {
+	if (!fs.existsSync(targetPath)) {
+		return true; // Already gone
+	}
+
+	let attempt = 0;
+
+	while (attempt < maxRetries) {
+		try {
+			// Force: true allows deleting files even if read-only
+			// Recursive: true deletes inner folders
+			await fs.promises.rm(targetPath, { recursive: true, force: true });
+
+			// Double check if it's actually gone
+			if (!fs.existsSync(targetPath)) {
+				return true;
+			}
+		} catch (error) {
+			const isLastAttempt = attempt === maxRetries - 1;
+
+			// If it's the last attempt, log error
+			if (isLastAttempt) {
+				console.error(`░░░░░ Failed to delete directory after ${maxRetries} attempts: ${targetPath}`);
+				console.error(`   Error: ${error.message}`);
+				return false;
+			}
+
+			// Log warning and wait
+			console.warn(
+				`░░░░░  Delete failed (Attempt ${attempt + 1}/${maxRetries}). File might be locked. Retrying in ${retryDelayMs / 1000
+				}s...`
+			);
+			await sleep(retryDelayMs);
+		}
+		attempt++;
+	}
+
+	return false;
+}
+
+/**
+ * Deletes specific contents inside a directory but keeps the parent folder.
+ * (Optional utility if you need to clear cache without removing the profile folder itself)
+ */
+export async function deleteAllItemsInDirectory(directoryPath) {
+	try {
+		if (!fs.existsSync(directoryPath)) return;
+
+		const files = await fs.promises.readdir(directoryPath);
+		for (const file of files) {
+			const curPath = path.join(directoryPath, file);
+			await deleteDirectoryWithRetries(curPath);
+		}
+	} catch (error) {
+		console.error(`Error emptying directory ${directoryPath}:`, error);
+	}
+}
+
+/**
+ * Legacy utility: Scan a directory and delete folders older than X minutes.
+ * (Note: launchBrowser.js now has its own internal version of this, but keeping this
+ * here is useful if you want to run cleanup scripts independently).
+ */
+export function deleteOldDirectories({ directoryPath, ageLimitMinutes }) {
+	if (!fs.existsSync(directoryPath)) return;
+
+	const now = Date.now();
+	const limit = ageLimitMinutes * 60 * 1000;
+
+	try {
+		const files = fs.readdirSync(directoryPath);
+
+		files.forEach((file) => {
+			const curPath = path.join(directoryPath, file);
+			try {
+				const stats = fs.statSync(curPath);
+				if (stats.isDirectory()) {
+					const age = now - stats.mtimeMs;
+					if (age > limit) {
+						console.log(`Cleaning up old directory: ${file}`);
+						// We use the sync version of retry logic or just fire-and-forget async here
+						// For simplicity in a sync loop, we often just do a force removal:
+						fs.rmSync(curPath, { recursive: true, force: true });
+					}
+				}
+			} catch (e) {
+				// Ignore access errors on specific files
+			}
+		});
+	} catch (err) {
+		console.error("Error during old directory cleanup:", err);
+	}
+}

package/src/utility/puppeteer/findBrowserPath.js

@@ -0,0 +1,211 @@
+/**
+ * @file findBrowserPath.js
+ * @description Cross-platform utility to find OS-installed browser executables.
+ * Supports: chrome, chromium, firefox, brave
+ * Works on: Linux (x64/arm64), macOS (arm64), Windows (x64)
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+// ==========================================================================
+// KNOWN BINARY PATHS PER PLATFORM
+// ==========================================================================
+
+const BROWSER_PATHS = {
+	chrome: {
+		linux: [
+			"google-chrome-stable",
+			"google-chrome",
+			"/opt/google/chrome/google-chrome",
+			"/usr/bin/google-chrome-stable",
+			"/usr/bin/google-chrome",
+		],
+		darwin: [
+			"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+		],
+		win32: [
+			path.join(process.env.PROGRAMFILES || "C:\\Program Files", "Google", "Chrome", "Application", "chrome.exe"),
+			path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Google", "Chrome", "Application", "chrome.exe"),
+			path.join(process.env.LOCALAPPDATA || "", "Google", "Chrome", "Application", "chrome.exe"),
+		],
+	},
+	chromium: {
+		linux: [
+			"chromium-browser",
+			"chromium",
+			"/usr/bin/chromium-browser",
+			"/usr/bin/chromium",
+			"/snap/bin/chromium",
+		],
+		darwin: [
+			"/Applications/Chromium.app/Contents/MacOS/Chromium",
+		],
+		win32: [
+			path.join(process.env.PROGRAMFILES || "C:\\Program Files", "Chromium", "Application", "chrome.exe"),
+			path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Chromium", "Application", "chrome.exe"),
+			path.join(process.env.LOCALAPPDATA || "", "Chromium", "Application", "chrome.exe"),
+		],
+	},
+	firefox: {
+		linux: [
+			"firefox",
+			"/usr/bin/firefox",
+			"/snap/bin/firefox",
+			"/usr/lib/firefox/firefox",
+		],
+		darwin: [
+			"/Applications/Firefox.app/Contents/MacOS/firefox",
+		],
+		win32: [
+			path.join(process.env.PROGRAMFILES || "C:\\Program Files", "Mozilla Firefox", "firefox.exe"),
+			path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Mozilla Firefox", "firefox.exe"),
+		],
+	},
+	brave: {
+		linux: [
+			"brave-browser",
+			"brave-browser-stable",
+			"/opt/brave.com/brave/brave-browser",
+			"/usr/bin/brave-browser",
+			"/usr/bin/brave-browser-stable",
+			"/snap/bin/brave",
+		],
+		darwin: [
+			"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+		],
+		win32: [
+			path.join(process.env.PROGRAMFILES || "C:\\Program Files", "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+			path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+			path.join(process.env.LOCALAPPDATA || "", "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+		],
+	},
+};
+
+// Friendly display names for error messages
+const BROWSER_DISPLAY_NAMES = {
+	chrome: "Google Chrome",
+	chromium: "Chromium",
+	firefox: "Mozilla Firefox",
+	brave: "Brave Browser",
+};
+
+// Install hints per platform
+const INSTALL_HINTS = {
+	chrome: {
+		linux: "sudo apt install google-chrome-stable  OR  download from https://www.google.com/chrome/",
+		darwin: "Download from https://www.google.com/chrome/",
+		win32: "Download from https://www.google.com/chrome/",
+	},
+	chromium: {
+		linux: "sudo apt install chromium-browser  OR  sudo snap install chromium",
+		darwin: "brew install --cask chromium  OR  download from https://www.chromium.org/",
+		win32: "Download from https://www.chromium.org/getting-involved/download-chromium/",
+	},
+	firefox: {
+		linux: "sudo apt install firefox  OR  sudo snap install firefox",
+		darwin: "brew install --cask firefox  OR  download from https://www.mozilla.org/firefox/",
+		win32: "Download from https://www.mozilla.org/firefox/",
+	},
+	brave: {
+		linux: "See https://brave.com/linux/  OR  sudo apt install brave-browser",
+		darwin: "brew install --cask brave-browser  OR  download from https://brave.com/",
+		win32: "Download from https://brave.com/",
+	},
+};
+
+// ==========================================================================
+// DETECTION LOGIC
+// ==========================================================================
+
+/**
+ * Try to resolve a command name using `which` (Unix) or `where` (Windows).
+ * Returns the absolute path if found, null otherwise.
+ */
+function resolveFromPath(command) {
+	const isWindows = process.platform === "win32";
+	try {
+		const cmd = isWindows ? `where "${command}"` : `which "${command}"`;
+		const result = execSync(cmd, { stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8" }).trim();
+		// `where` on Windows may return multiple lines — take the first
+		const firstLine = result.split("\n")[0].trim();
+		if (firstLine && fs.existsSync(firstLine)) {
+			return firstLine;
+		}
+	} catch {
+		// Command not found in PATH
+	}
+	return null;
+}
+
+/**
+ * Find the OS-installed executable path for a given browser.
+ *
+ * @param {string} browserName - One of: "chrome", "chromium", "firefox", "brave"
+ * @returns {string} Absolute path to the browser executable
+ * @throws {Error} If the browser is not found on the system
+ */
+export function findBrowserPath(browserName) {
+	const name = browserName.toLowerCase();
+	const candidates = BROWSER_PATHS[name];
+
+	if (!candidates) {
+		throw new Error(
+			`❌ [findBrowserPath] Unknown browser: "${browserName}"\n` +
+			`   Supported: chrome, chromium, firefox, brave`
+		);
+	}
+
+	const platform = process.platform; // 'linux', 'darwin', 'win32'
+	const paths = candidates[platform];
+
+	if (!paths || paths.length === 0) {
+		throw new Error(
+			`❌ [findBrowserPath] ${BROWSER_DISPLAY_NAMES[name]} is not supported on platform: ${platform}`
+		);
+	}
+
+	// Strategy 1: Try PATH lookup first (works for short names like "google-chrome", "firefox")
+	for (const candidate of paths) {
+		// If it's not an absolute path, try resolving from PATH
+		if (!path.isAbsolute(candidate)) {
+			const resolved = resolveFromPath(candidate);
+			if (resolved) return resolved;
+		}
+	}
+
+	// Strategy 2: Check known absolute paths
+	for (const candidate of paths) {
+		if (path.isAbsolute(candidate) && fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+
+	// Not found — throw descriptive error
+	const displayName = BROWSER_DISPLAY_NAMES[name];
+	const hint = INSTALL_HINTS[name]?.[platform] || `Install ${displayName} from its official website.`;
+
+	throw new Error(
+		`❌ [findBrowserPath] ${displayName} not found on this system.\n` +
+		`   Platform: ${platform}\n` +
+		`   Searched: ${paths.filter(p => path.isAbsolute(p)).join(", ") || "(PATH lookup only)"}\n\n` +
+		`   To install:\n` +
+		`   ${hint}`
+	);
+}
+
+/**
+ * Check if a browser is available without throwing.
+ *
+ * @param {string} browserName - One of: "chrome", "chromium", "firefox", "brave"
+ * @returns {{ found: boolean, path: string|null, error: string|null }}
+ */
+export function checkBrowserAvailability(browserName) {
+	try {
+		const p = findBrowserPath(browserName);
+		return { found: true, path: p, error: null };
+	} catch (err) {
+		return { found: false, path: null, error: err.message };
+	}
+}

package/src/utility/puppeteer/ppLaunch.d.ts

@@ -180,7 +180,24 @@ export interface PpLaunchOptions {
 	};
 
 	// ========================================================================
-	// 8. LOGGING
+	// 8. NOTIFICATIONS
+	// ========================================================================
+
+	/**
+	 * List of hostnames to auto-grant notification permissions for.
+	 * Pass plain hostnames — they are auto-converted to `https://host:443` internally.
+	 *
+	 * If empty (default), Chrome's default "Ask" behavior is used.
+	 *
+	 * @example
+	 * notification_hosts: ["web.whatsapp.com", "messages.google.com"]
+	 *
+	 * Default: []
+	 */
+	notification_hosts?: string[];
+
+	// ========================================================================
+	// 9. LOGGING
 	// ========================================================================
 
 	/**