arn-browser 0.1.6 → 0.1.8

package/src/utility/{launchBrowser.d.ts → playwright/pwLaunch.d.ts}

@@ -1,6 +1,6 @@
 import { Browser, BrowserContext, Page } from "playwright";
 import type { FingerprintGeneratorOptions } from "fingerprint-generator";
-import type { HumanPage, CreateCursorOptions } from "../human-cursor/index";
+import type { HumanPage, CreateCursorOptions } from "./human-cursor/index";
 type Screen = FingerprintGeneratorOptions["screen"];
 /**
  * Proxy configuration object.
@@ -119,7 +119,7 @@ export interface MultiloginOptions {
 /**
  * Options for launching the browser.
  */
-export interface LaunchOptions {
+export interface PwLaunchOptions {
 	// ========================================================================
 	// 1. GENERAL & NETWORK
 	// ========================================================================
@@ -141,7 +141,15 @@ export interface LaunchOptions {
 
 	/**
 	 * Which browser engine to launch.
-	 * Default: "chromium"
+	 *
+	 * - `"chromium"`: Playwright's bundled Chromium
+	 * - `"chrome"`: Alias for Chromium
+	 * - `"firefox"`: Playwright's bundled Firefox
+	 * - `"brave"`: Brave Browser (requires local binary)
+	 * - `"camoufox"`: Camoufox anti-detect Firefox (requires local binary)
+	 * - `"multilogin"`: Multilogin anti-detect browser (via API)
+	 *
+	 * Default: `"chromium"`
 	 */
 	which_browser?: "chromium" | "chrome" | "firefox" | "brave" | "braveLauncher" | "camoufox" | "multilogin";
 
@@ -152,8 +160,8 @@ export interface LaunchOptions {
 	/**
 	 * Path to a persistent profile.
 	 * - If absolute path: Uses that path exactly (no prefix added).
-	 * - If folder name: Creates inside `~/.arn-browser/persistent/` AND adds a browser prefix (e.g., `brave_myProfile`).
-	 * - If null: Creates a temporary, random profile in `~/.arn-browser/temp/`.
+	 * - If folder name: Creates inside `~/.arn-browser/pw/persistent/` AND adds a browser prefix (e.g., `brave_myProfile`).
+	 * - If null: Creates a temporary, random profile in `~/.arn-browser/pw/temp/`.
 	 */
 	profile_path?: string | null;
 
@@ -293,9 +301,9 @@ export interface BrowserControllerError {
  * The object returned by launchBrowser.
  * Check launchError to discriminate between success and failure states.
  */
-export type BrowserController = BrowserControllerSuccess | BrowserControllerError;
+export type PwBrowserController = BrowserControllerSuccess | BrowserControllerError;
 
 /**
  * Launches a browser based on the provided options.
  */
-export function launchBrowser(options: LaunchOptions): Promise<BrowserController>;
+export function pwLaunch(options?: PwLaunchOptions): Promise<PwBrowserController>;

package/src/utility/{launchBrowser.js → playwright/pwLaunch.js}

@@ -17,11 +17,11 @@ import { newInjectedContext, FingerprintInjector } from "fingerprint-injector";
 import { FingerprintGenerator } from "fingerprint-generator";
 
 // Internal Utilities
-import { getMultiloginToken } from "./multilogin_token_manager.js";
-import { deleteDirectoryWithRetries } from "./deleteDirectory.js";
+import { getMultiloginToken } from "../mlx_token.js";
+import { deleteDirectoryWithRetries } from "../deleteDirectory.js";
 
 // Human Cursor - for human-like mouse movements
-import { createCursor } from "../human-cursor/index.js";
+import { createCursor } from "./human-cursor/index.js";
 
 // Camoufox Special
 import { launchOptions } from "camoufox-js";
@@ -40,7 +40,8 @@ const detectedOs = osMap[process.platform] || "windows";
 const MULTILOGIN_LAUNCHER_URL = "https://launcher.mlx.yt:45001";
 const MULTILOGIN_FOLDER_ID = "bad9e7e1-cfab-4c8d-bd19-91aa82929711";
 
-const BASE_PROFILE_DIR = path.join(os.homedir(), ".arn-browser");
+const ARN_BROWSER_DIR = path.join(os.homedir(), ".arn-browser");
+const BASE_PROFILE_DIR = path.join(ARN_BROWSER_DIR, "profiles", "pw");
 const PERSISTENT_DIR = path.join(BASE_PROFILE_DIR, "persistent");
 const TEMP_DIR = path.join(BASE_PROFILE_DIR, "temp");
 
@@ -75,37 +76,63 @@ function resolveProfilePath(nameOrPath, browserName) {
 
 /**
  * Locates binaries for manual browsers (Brave).
+ * Uses ~/.arn-browser/browsers/{browser}/{executable}
  */
 function getBinaryPath(browserName) {
 	const isWindows = process.platform === "win32";
-	const homeDir = os.homedir();
+	const browsersDir = path.join(ARN_BROWSER_DIR, "browsers");
 
-	let binaryPath = "";
+	const binaryMap = {
+		brave: isWindows
+			? path.join(browsersDir, "brave", "brave.exe")
+			: path.join(browsersDir, "brave", "brave"),
+	};
 
-	if (browserName === "brave") {
-		if (isWindows) {
-			// Windows: Standard custom install path in Downloads
-			binaryPath = path.join(homeDir, "Downloads", "brave", "brave.exe");
-		} else {
-			// Linux: Primary check in .cache (common for script installs)
-			const cachePath = path.join(homeDir, ".cache", "brave", "brave");
-			const downloadsPath = path.join(homeDir, "Downloads", "brave", "brave");
-
-			if (fs.existsSync(cachePath)) {
-				binaryPath = cachePath;
-			} else if (fs.existsSync(downloadsPath)) {
-				binaryPath = downloadsPath;
-			} else {
-				// Default to cache path for the error message if neither is found
-				binaryPath = cachePath;
-			}
-		}
+	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 (!binaryPath || !fs.existsSync(binaryPath)) {
+	if (!fs.existsSync(binaryPath)) {
 		throw new Error(
-			`░░░░░ [LaunchBrowser] Binary not found for ${browserName} at: ${binaryPath}\n` +
-			`   Linux checked: ~/.cache/brave/brave AND ~/Downloads/brave/brave`
+			`░░░░░ [LaunchBrowser] ${browserName} binary not found at: ${binaryPath}\n` +
+			`   Run "node bin/cli.js install" to install browsers.`
 		);
 	}
 
@@ -237,7 +264,7 @@ function getFingerprintConfig(browserType, screenOptions = null) {
 // 3. MAIN LAUNCHER ENTRY POINT
 // ==========================================================================
 
-export async function launchBrowser({
+export async function pwLaunch({
 	// Common
 	timezoneId = null,
 	proxy,
@@ -407,7 +434,7 @@ async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, hum
 	const ignoreDefaultArgs = ["--enable-automation"];
 
 	if (CapSolver) {
-		const extPath = path.resolve(`./utility/browser-fingerprint/CapSolver`);
+		const extPath = path.resolve(`./src/utility/browser-fingerprint/CapSolver`);
 		args.push(`--disable-extensions-except=${extPath}`, `--load-extension=${extPath}`);
 	}
 
@@ -428,6 +455,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"),
 				proxy: proxyObj,
 				args: args,
 				ignoreDefaultArgs: ignoreDefaultArgs,
@@ -469,6 +497,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"),
 				proxy: proxyObj,
 				args: args,
 				timezoneId: tz,
@@ -524,6 +553,7 @@ async function firefoxLauncher({ profilePath, proxy, timezoneId, humanize_option
 
 			const browser = await firefox.launch({
 				headless: false,
+				executablePath: getPlaywrightExePath("firefox"),
 				proxy: proxyObj,
 				ignoreDefaultArgs: ["--enable-automation"],
 				firefoxUserPrefs: firefoxUserPrefs,
@@ -565,6 +595,7 @@ async function firefoxLauncher({ profilePath, proxy, timezoneId, humanize_option
 
 			const context = await firefox.launchPersistentContext(activePath, {
 				headless: false,
+				executablePath: getPlaywrightExePath("firefox"),
 				proxy: proxyObj,
 				timezoneId: tz,
 				ignoreDefaultArgs: ["--enable-automation"],
@@ -701,7 +732,7 @@ async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, humani
 	];
 	const ignoreDefaultArgs = ["--enable-automation"];
 	if (CapSolver) {
-		const extPath = path.resolve(`./utility/browser-fingerprint/CapSolver`);
+		const extPath = path.resolve(`./src/utility/browser-fingerprint/CapSolver`);
 		args.push(`--load-extension=${extPath}`);
 	}
 

package/src/{all_routes/routeWithSuperagent.d.ts → utility/playwright/routes/pwRoute.d.ts}

@@ -5,9 +5,9 @@ import { Browser, BrowserContext, Page } from "playwright";
 // ============================================================================
 
 /**
- * Options for the gotRoute function.
+ * Options for the pwRoute function.
  */
-export interface GotRouteOptions {
+export interface PwRouteOptions {
 	/** Playwright Context (provide either context or page) */
 	context?: BrowserContext | null;
 
@@ -57,11 +57,11 @@ export interface GotRouteOptions {
 /**
  * Sets up request interception, caching, and ad-blocking on a Playwright page or context.
  */
-export function gotRoute(options: GotRouteOptions): Promise<void>;
+export function pwRoute(options: PwRouteOptions): Promise<void>;
 
 /**
  * Starts logging cache statistics to the console at a set interval.
  * @param log_cache Optional NodeCache instance (uses global by default)
  * @param interval Interval in seconds (default: 10)
  */
-export function showCacheLogs(log_cache?: any, interval?: number): void;
+export function pwCacheLogs(log_cache?: any, interval?: number): void;

package/src/{all_routes/routeWithSuperagent.js → utility/playwright/routes/pwRoute.js}

@@ -20,7 +20,7 @@ const globalCache = new NodeCache({
  * @param {Object} log_cache - The cache instance to monitor
  * @param {number} interval - The interval in seconds between log outputs
  */
-export function showCacheLogs(log_cache = globalCache, interval = 10) {
+export function pwCacheLogs(log_cache = globalCache, interval = 10) {
 	if (interval > 0) {
 		setInterval(() => {
 			const stats = log_cache.stats;
@@ -109,7 +109,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
  * @param {Array<string>} options.allowImagePatterns - Array of strings/patterns. If a URL contains any of these, it will NOT be blocked even if blockImage is true.
  * @param {Array<string>} options.skipGotPatterns - Array of strings/patterns. If a URL contains any of these, it will skip the custom Superagent fetch.
  */
-export async function gotRoute({
+export async function pwRoute({
 	context = null,
 	page = null,
 	successLogs = false,

package/src/utility/proxy-utility/proxy-chain.js

@@ -217,9 +217,10 @@ export async function startProxyServer({
 		fetchProxyDetails(upstreamProxies.p2, ip2LocationKey),
 	]);
 
-	// Warn only if proxy was configured (URL exists) but details came back null (Connection failed)
-	if (upstreamProxies.p1 && !p1Details) console.warn("░░ Warning: PROXY_1 configured but unreachable.");
-	if (upstreamProxies.p2 && !p2Details) console.warn("░░ Warning: PROXY_2 configured but unreachable.");
+	// Return null if any configured proxy is unreachable
+	if (upstreamProxies.default && !defaultDetails) { console.warn("░░ Warning: DEFAULT_PROXY configured but unreachable."); return null; }
+	if (upstreamProxies.p1 && !p1Details) { console.warn("░░ Warning: PROXY_1 configured but unreachable."); return null; }
+	if (upstreamProxies.p2 && !p2Details) { console.warn("░░ Warning: PROXY_2 configured but unreachable."); return null; }
 
 	// 5. Stats
 	const stats = {

package/src/utility/proxy-utility/proxy-helper.js

@@ -1,6 +1,6 @@
 import { setTimeout as sleep } from "timers/promises";
 import randomstring from "randomstring";
-import { getMultiloginToken } from "../multilogin_token_manager.js";
+import { getMultiloginToken } from "../mlx_token.js";
 import { getActiveProxyWithStartStop as fetchAwsProxy } from "./custom-proxy.js";
 import { arn, query } from "arn-knexjs";
 

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

@@ -0,0 +1,199 @@
+import { Browser, Page } from "puppeteer-core";
+import type { ProxyConfig } from "../pwLaunch";
+
+/**
+ * Configuration options specific to Multilogin (Puppeteer CDP).
+ */
+export interface PpMultiloginOptions {
+	/**
+	 * Multilogin Profile ID. If provided, launches an existing profile.
+	 */
+	profileId?: string | null;
+
+	/**
+	 * OS Type for Multilogin profile creation.
+	 * Default: detected OS
+	 */
+	os_type?: "windows" | "macos" | "linux" | "android";
+
+	/**
+	 * Multilogin flag: Canvas noise masking.
+	 * Default: true
+	 */
+	canvas_noise?: boolean;
+
+	/**
+	 * Multilogin flag: Media devices masking.
+	 * Default: true
+	 */
+	media_masking?: boolean;
+
+	/**
+	 * Multilogin flag: Audio masking.
+	 * Default: true
+	 */
+	audio_masking?: boolean;
+}
+
+/**
+ * Options for launching a browser via Puppeteer CDP.
+ */
+export interface PpLaunchOptions {
+	// ========================================================================
+	// 1. BROWSER SELECTION
+	// ========================================================================
+
+	/**
+	 * Which browser to launch.
+	 *
+	 * - `"chrome"`: Chromium browser (locally installed)
+	 * - `"chromium"`: Alias for Chrome
+	 * - `"brave"`: Brave Browser (requires local binary)
+	 * - `"multilogin"`: Multilogin anti-detect browser (via API)
+	 *
+	 * Default: `"chrome"`
+	 */
+	which_browser?: "chrome" | "chromium" | "brave" | "multilogin";
+
+	// ========================================================================
+	// 2. STORAGE & PROFILES
+	// ========================================================================
+
+	/**
+	 * Path to a persistent profile.
+	 * - If absolute path: Uses that path exactly (no prefix added).
+	 * - If folder name: Creates inside `~/.arn-browser/pp/persistent/` with a browser prefix (e.g., `brave_myProfile`).
+	 * - If null: Creates a temporary, random profile in `~/.arn-browser/pp/temp/`.
+	 */
+	profile_path?: string | null;
+
+	/**
+	 * Auto-cleanup profiles after X minutes since last launch.
+	 *
+	 * **Persistent profiles:** Cleaned after X minutes since last launch. Default: 0 (never clean).
+	 * **Temp profiles:** Default: 15 minutes if not specified.
+	 *
+	 * Default: 0
+	 */
+	cleanupMinutes?: number;
+
+	// ========================================================================
+	// 3. NETWORK
+	// ========================================================================
+
+	/**
+	 * Proxy settings (URL string or config object).
+	 * Passed as `--proxy-server` flag to the browser.
+	 */
+	proxy?: ProxyConfig | string | null;
+
+	// ========================================================================
+	// 4. BROWSER ARGS
+	// ========================================================================
+
+	/**
+	 * Additional CLI arguments to pass to the browser process.
+	 * These are appended after the default args.
+	 *
+	 * @example ["--disable-gpu", "--window-size=1920,1080"]
+	 */
+	extraArgs?: string[];
+
+	// ========================================================================
+	// 5. ENGINE SPECIFIC
+	// ========================================================================
+
+	/**
+	 * Options specific to the Multilogin engine.
+	 */
+	multilogin_options?: PpMultiloginOptions;
+
+	// ========================================================================
+	// 6. FINGERPRINT SPOOFING
+	// ========================================================================
+
+	/**
+	 * Configuration for browser fingerprint spoofing (per-page via fingerprint-injector).
+	 *
+	 * - `false`: No fingerprint spoofing (default)
+	 * - `true`: Spoof fingerprint with default screen dimensions
+	 * - `{ minWidth?, maxWidth?, minHeight?, maxHeight? }`: Spoof fingerprint with screen constraints
+	 *
+	 * Default: false
+	 */
+	spoof_fingerprint?: boolean | {
+		minWidth?: number;
+		maxWidth?: number;
+		minHeight?: number;
+		maxHeight?: number;
+	};
+
+	// ========================================================================
+	// 7. LOGGING
+	// ========================================================================
+
+	/**
+	 * Enable launch-related console logs.
+	 * Default: false
+	 */
+	launch_logs?: boolean;
+
+	/**
+	 * Enable cleanup-related console logs.
+	 * Default: false
+	 */
+	cleanup_logs?: boolean;
+}
+
+/**
+ * Successful Puppeteer browser launch result.
+ * When launchError is null, browser/context/page are guaranteed to be valid.
+ */
+export interface PpBrowserControllerSuccess {
+	/** The Puppeteer Browser instance. */
+	browser: Browser;
+	/** The browser instance (alias for browser in Puppeteer, since there's no separate BrowserContext). */
+	context: Browser;
+	/** The initial Page object. */
+	page: Page;
+	/** Returns true if the browser is still connected. */
+	isBrowserRunning: () => boolean;
+	/** Safely closes the browser, kills the process, and cleans up temporary directories. */
+	closeBrowser: () => Promise<boolean>;
+	/** No error occurred during launch. */
+	launchError: null;
+}
+
+/**
+ * Failed Puppeteer browser launch result.
+ * When launchError is set, browser/context/page are null.
+ */
+export interface PpBrowserControllerError {
+	/** Null on launch failure. */
+	browser: null;
+	/** Null on launch failure. */
+	context: null;
+	/** Null on launch failure. */
+	page: null;
+	/** Returns false since the browser failed to launch. */
+	isBrowserRunning: () => boolean;
+	/** No-op cleanup function. */
+	closeBrowser: () => Promise<boolean>;
+	/** The error that occurred during launch. */
+	launchError: Error;
+}
+
+/**
+ * The object returned by launchPuppeteer.
+ * Check launchError to discriminate between success and failure states.
+ */
+export type PpBrowserController = PpBrowserControllerSuccess | PpBrowserControllerError;
+
+/**
+ * Launches a browser via Puppeteer CDP based on the provided options.
+ * Spawns the browser process, connects via Chrome DevTools Protocol.
+ *
+ * Supported browsers: Chrome, Brave, Multilogin.
+ * Profile directory: ~/.arn-browser/pp/
+ */
+export function ppLaunch(options?: PpLaunchOptions): Promise<PpBrowserController>;