arn-browser 0.1.13 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "arn-browser",
-	"version": "0.1.13",
+	"version": "0.1.14",
 	"description": "A lightweight, browser autmation helper.",
 	"main": "src/index.js",
 	"types": "src/index.d.ts",

package/src/index.d.ts

@@ -4,8 +4,8 @@ import { ppLaunch } from "./utility/puppeteer/ppLaunch";
 import { ppRoute, ppCacheLogs } from "./utility/puppeteer/routes/ppRoute";
 import { pwLaunch } from "./utility/playwright/pwLaunch";
 import { pwRoute, pwCacheLogs } from "./utility/playwright/routes/pwRoute";
-import { retryNavigation, retryClick, checkPageConditions } from "./utility/playwright/pwHelper";
-import { retryNavigation as ppRetryNavigation } from "./utility/puppeteer/ppHelper";
+import { retryNavigation, retryClick, checkPageConditions, exportSession, importSession } from "./utility/playwright/pwHelper";
+import { retryNavigation as ppRetryNavigation, retryClick as ppRetryClick, checkPageConditions as ppCheckPageConditions, exportSession as ppExportSession, importSession as ppImportSession } from "./utility/puppeteer/ppHelper";
 import { startProxyServer, fetchPublicIP, fetchProxyDetails } from "./utility/proxy-utility/proxy-chain";
 import {
     fetchAwsProxy, getInstanceStatus, getPublicIpAddress,
@@ -21,16 +21,22 @@ export declare const ppBrowser: {
     launch: typeof ppLaunch;
     route: typeof ppRoute;
     cacheLogs: typeof ppCacheLogs;
-    ppGoto: typeof ppRetryNavigation;
+    Goto: typeof ppRetryNavigation;
+    Click: typeof ppRetryClick;
+    Conditions: typeof ppCheckPageConditions;
+    exportSession: typeof ppExportSession;
+    importSession: typeof ppImportSession;
 };
 
 export declare const pwBrowser: {
     launch: typeof pwLaunch;
     route: typeof pwRoute;
     cacheLogs: typeof pwCacheLogs;
-    pwGoto: typeof retryNavigation;
-    pwClick: typeof retryClick;
-    pwConditions: typeof checkPageConditions;
+    Goto: typeof retryNavigation;
+    Click: typeof retryClick;
+    Conditions: typeof checkPageConditions;
+    exportSession: typeof exportSession;
+    importSession: typeof importSession;
 };
 
 export declare const proxyUtil: {

package/src/index.js

@@ -5,27 +5,33 @@
 // --- Puppeteer ---
 import { ppLaunch } from "./utility/puppeteer/ppLaunch.js";
 import { ppRoute, ppCacheLogs } from "./utility/puppeteer/routes/ppRoute.js";
-import { retryNavigation as ppRetryNavigation } from "./utility/puppeteer/ppHelper.js";
+import { retryNavigation as ppRetryNavigation, retryClick as ppRetryClick, checkPageConditions as ppCheckPageConditions, exportSession as ppExportSession, importSession as ppImportSession } from "./utility/puppeteer/ppHelper.js";
 
 export const ppBrowser = {
 	launch: ppLaunch,
 	route: ppRoute,
 	cacheLogs: ppCacheLogs,
-	ppGoto: ppRetryNavigation,
+	Goto: ppRetryNavigation,
+	Click: ppRetryClick,
+	Conditions: ppCheckPageConditions,
+	exportSession: ppExportSession,
+	importSession: ppImportSession,
 };
 
 // --- Playwright ---
 import { pwLaunch } from "./utility/playwright/pwLaunch.js";
 import { pwRoute, pwCacheLogs } from "./utility/playwright/routes/pwRoute.js";
-import { retryNavigation, retryClick, checkPageConditions } from "./utility/playwright/pwHelper.js";
+import { retryNavigation, retryClick, checkPageConditions, exportSession, importSession } from "./utility/playwright/pwHelper.js";
 
 export const pwBrowser = {
 	launch: pwLaunch,
 	route: pwRoute,
 	cacheLogs: pwCacheLogs,
-	pwGoto: retryNavigation,
-	pwClick: retryClick,
-	pwConditions: checkPageConditions,
+	Goto: retryNavigation,
+	Click: retryClick,
+	Conditions: checkPageConditions,
+	exportSession,
+	importSession,
 };
 
 // --- Proxy ---

package/src/utility/playwright/human-cursor/HumanCursor.js

@@ -43,21 +43,7 @@ function gaussianRandom(mean = 0.5, stdDev = 0.15) {
     return Math.max(0.1, Math.min(0.9, z0 * stdDev + mean));
 }
 
-/**
- * Simple mutex for serializing keyboard operations
- */
-let typingLock = Promise.resolve();
-async function withTypingLock(fn) {
-    const previousLock = typingLock;
-    let releaseLock;
-    typingLock = new Promise(resolve => { releaseLock = resolve; });
-    await previousLock;
-    try {
-        return await fn();
-    } finally {
-        releaseLock();
-    }
-}
+
 
 /**
  * Creates a HumanLocator that wraps a Playwright Locator
@@ -144,7 +130,7 @@ function createHumanLocator(cursor, locator) {
             if (!cursor.config.humanize) {
                 return await locator.fill(value, options);
             }
-            return await withTypingLock(async () => {
+            return await cursor._withTypingLock(async () => {
                 await this.click(options);
                 // Clear field reliably using fill('') before human typing
                 await locator.fill('');
@@ -158,7 +144,7 @@ function createHumanLocator(cursor, locator) {
             if (!cursor.config.humanize) {
                 return await locator.type(text, options);
             }
-            return await withTypingLock(async () => {
+            return await cursor._withTypingLock(async () => {
                 await this.click(options);
                 await cursor._type(text, options);
             });
@@ -212,7 +198,7 @@ function createHumanLocator(cursor, locator) {
             if (!cursor.config.humanize) {
                 return await locator.pressSequentially(text, options);
             }
-            return await withTypingLock(async () => {
+            return await cursor._withTypingLock(async () => {
                 await this.click(options);
                 await locator.clear();
                 await cursor._type(text, options);
@@ -292,9 +278,26 @@ export function createCursor(page, options = {}) {
     // Internal state
     const cursor = {
         _page: page,
+        _typingLock: Promise.resolve(),
+        _viewportSize: null,
         originCoordinates: [0, 0],
         config,
 
+        /**
+         * Per-cursor mutex for serializing keyboard operations
+         */
+        async _withTypingLock(fn) {
+            const previousLock = this._typingLock;
+            let releaseLock;
+            this._typingLock = new Promise(resolve => { releaseLock = resolve; });
+            await previousLock;
+            try {
+                return await fn();
+            } finally {
+                releaseLock();
+            }
+        },
+
         /**
          * Move cursor to locator with human-like behavior
          * Includes overshoot/correction and pre-movement jitter
@@ -367,7 +370,11 @@ export function createCursor(page, options = {}) {
          * Move cursor to a specific point with variable speed and micro-pauses
          */
         async _moveToPoint(destination, options = {}) {
-            const viewport = page.viewportSize() || { width: 1280, height: 720 };
+            if (!this._viewportSize) {
+                this._viewportSize = page.viewportSize()
+                    || await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
+            }
+            const viewport = this._viewportSize;
 
             const params = generateRandomCurveParameters(
                 viewport,

package/src/utility/playwright/pwHelper.js

@@ -94,7 +94,7 @@ export const checkPageConditions = async (page, checksToPerform, timeout) => {
 	try {
 		const promises = Object.entries(checksToPerform)
 			.filter(([_, value]) => value !== null) // Needed when setting value null after match
-			.map(([key, value]) => {
+			.map(async ([key, value]) => {
 				if (typeof value === "string") {
 					// Handle URL check
 					return page
@@ -127,3 +127,83 @@ export const checkPageConditions = async (page, checksToPerform, timeout) => {
 		return null; // Return null if no match is found
 	}
 };
+
+/**
+ * Exports browser session (cookies + localStorage) via CDP.
+ * Silent operation — no browser blinking.
+ *
+ * @param {import('playwright-core').BrowserContext} context - Playwright BrowserContext
+ * @returns {Promise<{cookies: Array, localStorage: Array}>} Session data for JSONB storage
+ */
+export const exportSession = async (context) => {
+	const pages = context.pages();
+	const page = pages[0];
+	if (!page) throw new Error("No page available for exportSession");
+
+	const client = await context.newCDPSession(page);
+	const { cookies } = await client.send("Network.getAllCookies");
+	await client.detach();
+
+	const localStorage = [];
+	for (const p of pages) {
+		const url = p.url();
+		if (!url || url === "about:blank" || url.startsWith("chrome")) continue;
+
+		try {
+			const origin = new URL(url).origin;
+			const items = await p.evaluate(() => {
+				const data = [];
+				for (let i = 0; i < window.localStorage.length; i++) {
+					const key = window.localStorage.key(i);
+					data.push({ name: key, value: window.localStorage.getItem(key) });
+				}
+				return data;
+			});
+
+			if (items.length > 0 && !localStorage.some((o) => o.origin === origin)) {
+				localStorage.push({ origin, items });
+			}
+		} catch (e) {
+			// Skip pages that can't be evaluated
+		}
+	}
+
+	return { cookies, localStorage };
+};
+
+/**
+ * Imports browser session (cookies + localStorage) via CDP.
+ * Silent operation — no browser blinking.
+ *
+ * @param {import('playwright-core').BrowserContext} context - Playwright BrowserContext
+ * @param {Object} data - Session data { cookies, localStorage }
+ */
+export const importSession = async (context, data) => {
+	const pages = context.pages();
+	const page = pages[0];
+	if (!page) throw new Error("No page available for importSession");
+
+	const client = await context.newCDPSession(page);
+
+	if (data.cookies?.length) {
+		await client.send("Network.setCookies", { cookies: data.cookies });
+	}
+
+	if (data.localStorage?.length) {
+		await client.send("DOMStorage.enable");
+		for (const entry of data.localStorage) {
+			if (!entry.items?.length) continue;
+
+			const storageId = { securityOrigin: entry.origin, isLocalStorage: true };
+			for (const { name, value } of entry.items) {
+				await client.send("DOMStorage.setDOMStorageItem", {
+					storageId,
+					key: name,
+					value: value,
+				});
+			}
+		}
+	}
+
+	await client.detach();
+};

package/src/utility/playwright/pwLaunch.js

@@ -494,6 +494,31 @@ async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, hum
 		try {
 			if (!fs.existsSync(activePath)) fs.mkdirSync(activePath, { recursive: true });
 
+			// ======================================================
+			// Prevent Tab Restore via Preferences
+			// ======================================================
+			try {
+				const prefsFilePath = path.join(activePath, "Default", "Preferences");
+				const prefsDir = path.dirname(prefsFilePath);
+				if (!fs.existsSync(prefsDir)) fs.mkdirSync(prefsDir, { recursive: true });
+
+				let prefs = {};
+				if (fs.existsSync(prefsFilePath)) {
+					prefs = JSON.parse(fs.readFileSync(prefsFilePath, "utf-8"));
+				}
+
+				if (!prefs.profile) prefs.profile = {};
+				prefs.profile.exit_type = "Normal";
+
+				if (!prefs.session) prefs.session = {};
+				prefs.session.restore_on_startup = 4;
+				prefs.session.startup_urls = ["about:blank"];
+
+				fs.writeFileSync(prefsFilePath, JSON.stringify(prefs, null, 2), "utf-8");
+			} catch (e) {
+				// Non-critical
+			}
+
 			// Logic: Native Persistent Launch. No fingerprint-injector.
 			const context = await chromium.launchPersistentContext(activePath, {
 				headless: false,
@@ -690,6 +715,15 @@ async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, humani
 		if (!prefs.brave) prefs.brave = {};
 		if (!prefs.brave.sidebar) prefs.brave.sidebar = {};
 		prefs.brave.sidebar.sidebar_show_option = 3;
+
+		// Prevent tab restore (saves proxy bandwidth)
+		if (!prefs.profile) prefs.profile = {};
+		prefs.profile.exit_type = "Normal";
+
+		if (!prefs.session) prefs.session = {};
+		prefs.session.restore_on_startup = 4;
+		prefs.session.startup_urls = ["about:blank"];
+
 		fs.writeFileSync(prefsFilePath, JSON.stringify(prefs, null, 2), "utf-8");
 	} catch (e) {
 		console.warn("░░░░░ Could not modify Brave preferences:", e.message);
@@ -729,7 +763,6 @@ async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, humani
 		// --- Brave Specific Silence ---
 		"--disable-features=Translate,BraveRewards,BraveWallet,BraveNews,Sidebar,SidePanel,BraveNTPBrandedWallpaper,NTPBackgroundImages",
 		"--disable-infobars",
-		"about:blank",
 	];
 	const ignoreDefaultArgs = ["--enable-automation"];
 	if (CapSolver) {

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

@@ -1,4 +1,4 @@
-import { Page } from "puppeteer-core";
+import { Page, Locator } from "puppeteer-core";
 
 /**
  * Options for the retryNavigation function.
@@ -18,9 +18,53 @@ export interface RetryNavigationOptions {
 	waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
 }
 
+/**
+ * Options for the retryClick function.
+ */
+export interface RetryClickOptions {
+	/** The Puppeteer Page object. Required when using selector. */
+	page?: Page;
+	/** CSS/aria/xpath selector string (old-style). Provide either selector or locator. */
+	selector?: string;
+	/** Puppeteer Locator (new-style). Provide either selector or locator. */
+	locator?: Locator<Node>;
+	/** Maximum number of retry attempts. Default: 3 */
+	maxRetries?: number;
+	/** Timeout for waiting for element visibility/invisibility. Default: 15000 */
+	timeout?: number;
+}
+
 /**
  * Navigates to a URL with retry logic and incremental timeouts.
  * If navigation fails, it temporarily goes to "about:blank" before retrying.
  * @returns True if navigation succeeded, throws error otherwise.
  */
 export function retryNavigation(options: RetryNavigationOptions): Promise<boolean>;
+
+/**
+ * Retries clicking an element (by selector or locator).
+ * Warning: This function waits for the element to become HIDDEN after clicking.
+ * Use this for actions that close modals or navigate away.
+ */
+export function retryClick(options: RetryClickOptions): Promise<void>;
+
+/**
+ * Races multiple conditions (URL match or Locator visibility) to see which happens first.
+ *
+ * Value types in checksToPerform:
+ * - string → URL check (exact match, startsWith, or glob with *)
+ * - Locator → Element check via page.locator() (new-style API)
+ * - null → skipped
+ *
+ * NOTE: This function MUTATES the `checksToPerform` object by deleting the matched key.
+ *
+ * @param page - The Puppeteer Page object.
+ * @param checksToPerform - An object mapping keys (names) to URL strings, Locators, or null.
+ * @param timeout - Maximum time to wait for a condition in milliseconds.
+ * @returns The key name of the matched condition, or null if timed out.
+ */
+export function checkPageConditions(
+	page: Page,
+	checksToPerform: Record<string, string | Locator<Node> | null>,
+	timeout: number
+): Promise<string | null>;

package/src/utility/puppeteer/ppHelper.js

@@ -46,3 +46,182 @@ export const retryNavigation = async ({
 	}
 	return false;
 };
+
+/**
+ * Retries clicking an element (by selector or locator).
+ * EXPECTATION: The element should disappear (become hidden/detached) after clicking.
+ *
+ * @param {Object} options
+ * @param {import('puppeteer-core').Page} options.page - Puppeteer Page object (required when using selector)
+ * @param {string} [options.selector] - CSS/aria/xpath selector string (old-style)
+ * @param {import('puppeteer-core').Locator} [options.locator] - Puppeteer Locator (new-style)
+ * @param {number} [options.maxRetries=3] - Max retries
+ * @param {number} [options.timeout=15000] - Timeout for visibility checks
+ */
+export const retryClick = async ({ page, selector, locator, maxRetries = 3, timeout = 15000 }) => {
+	if (!selector && !locator) throw new Error("Either selector or locator is required");
+	if (selector && !page) throw new Error("Page is required when using selector");
+
+	for (let retryCount = 0; retryCount < maxRetries; retryCount++) {
+		try {
+			if (locator) {
+				// New-style: use Locator API
+				await locator.setTimeout(timeout).setVisibility("visible").click();
+				// Wait for element to disappear
+				await locator.setTimeout(timeout).setVisibility("hidden").wait().catch(() => {});
+			} else {
+				// Old-style: use waitForSelector
+				const el = await page.waitForSelector(selector, { visible: true, timeout });
+				await el.click();
+				// Wait for element to disappear
+				await page.waitForSelector(selector, { hidden: true, timeout }).catch(() => {});
+			}
+			return; // Exit if successful
+		} catch (error) {
+			if (retryCount === maxRetries - 1) {
+				throw error;
+			}
+		}
+	}
+};
+
+/**
+ * Races multiple conditions (URL or Locator) to see which happens first.
+ * Modifies the input object by deleting the matched key.
+ *
+ * Value types in checksToPerform:
+ * - string → URL check (exact match, startsWith, or glob with *)
+ * - Locator → Element check via page.locator() (new-style API)
+ * - null → skipped
+ *
+ * @param {import('puppeteer-core').Page} page
+ * @param {Object.<string, string|import('puppeteer-core').Locator|null>} checksToPerform - Map of names to URL strings or Locators
+ * @param {number} timeout - Timeout in ms
+ * @returns {Promise<string|null>} The key of the matched condition
+ */
+export const checkPageConditions = async (page, checksToPerform, timeout) => {
+	// Validate required parameters
+	if (!page) throw new Error("Page parameter is required");
+	if (!timeout) throw new Error("Timeout parameter is required");
+
+	let matchedKey = null;
+	try {
+		const promises = Object.entries(checksToPerform)
+			.filter(([_, value]) => value !== null) // Needed when setting value null after match
+			.map(async ([key, value]) => {
+				if (typeof value === "string") {
+					// Handle URL check — poll with waitForFunction
+					const urlPattern = value;
+					return page
+						.waitForFunction(
+							(pattern) => {
+								const url = window.location.href;
+								if (pattern.includes("*")) {
+									// Convert glob to regex: ** → .*, * → [^/]*
+									const regexStr = pattern.replace(/\*\*/g, ".*").replace(/(?<!\.\*)\*/g, "[^/]*");
+									return new RegExp("^" + regexStr + "$").test(url);
+								}
+								return url === pattern || url.startsWith(pattern);
+							},
+							{ timeout },
+							urlPattern
+						)
+						.then(() => key);
+				} else {
+					// Handle Locator check (from page.locator())
+					return value
+						.setTimeout(timeout)
+						.setVisibility("visible")
+						.wait()
+						.then(() => key);
+				}
+			});
+
+		matchedKey = await Promise.race(promises);
+		if (matchedKey) {
+			// Remove the matched key from the original object
+			delete checksToPerform[matchedKey];
+			console.log(`${matchedKey} matched!`);
+		}
+		return matchedKey; // Return the matched key if found
+	} catch (error) {
+		console.log(`No match found - ${error.message}`);
+		return null; // Return null if no match is found
+	}
+};
+
+/**
+ * Exports browser session (cookies + localStorage) via CDP.
+ * Silent operation — no browser blinking.
+ *
+ * @param {import('puppeteer-core').Page} page - Any Puppeteer Page
+ * @returns {Promise<{cookies: Array, localStorage: Array}>} Session data for JSONB storage
+ */
+export const exportSession = async (page) => {
+	const client = await page.createCDPSession();
+	const { cookies } = await client.send("Network.getAllCookies");
+	await client.detach();
+
+	const localStorage = [];
+	const browser = page.browser();
+	const pages = await browser.pages();
+
+	for (const p of pages) {
+		const url = p.url();
+		if (!url || url === "about:blank" || url.startsWith("chrome")) continue;
+
+		try {
+			const origin = new URL(url).origin;
+			const items = await p.evaluate(() => {
+				const data = [];
+				for (let i = 0; i < window.localStorage.length; i++) {
+					const key = window.localStorage.key(i);
+					data.push({ name: key, value: window.localStorage.getItem(key) });
+				}
+				return data;
+			});
+
+			if (items.length > 0 && !localStorage.some((o) => o.origin === origin)) {
+				localStorage.push({ origin, items });
+			}
+		} catch (e) {
+			// Skip pages that can't be evaluated
+		}
+	}
+
+	return { cookies, localStorage };
+};
+
+/**
+ * Imports browser session (cookies + localStorage) into a Puppeteer Browser.
+ *
+ * @param {import('puppeteer-core').Page} page - Any Puppeteer Page
+ * @param {Object} data - Session data { cookies, localStorage }
+ */
+export const importSession = async (page, data) => {
+	if (data.cookies?.length) {
+		const client = await page.createCDPSession();
+		await client.send("Network.setCookies", { cookies: data.cookies });
+		await client.detach();
+	}
+
+	if (data.localStorage?.length) {
+		const browser = page.browser();
+
+		for (const entry of data.localStorage) {
+			if (!entry.items?.length) continue;
+
+			const p = await browser.newPage();
+			try {
+				await p.goto(entry.origin, { waitUntil: "domcontentloaded", timeout: 15000 });
+				await p.evaluate((items) => {
+					for (const { name, value } of items) {
+						window.localStorage.setItem(name, value);
+					}
+				}, entry.items);
+			} finally {
+				await p.close();
+			}
+		}
+	}
+};

package/src/utility/puppeteer/ppLaunch.js

@@ -348,6 +348,15 @@ async function braveLauncher({ profilePath, proxy, extraArgs, spoof_fingerprint,
 		if (!prefs.brave) prefs.brave = {};
 		if (!prefs.brave.sidebar) prefs.brave.sidebar = {};
 		prefs.brave.sidebar.sidebar_show_option = 3;
+
+		// Prevent tab restore (saves proxy bandwidth)
+		if (!prefs.profile) prefs.profile = {};
+		prefs.profile.exit_type = "Normal";
+
+		if (!prefs.session) prefs.session = {};
+		prefs.session.restore_on_startup = 4;
+		prefs.session.startup_urls = ["about:blank"];
+
 		fs.writeFileSync(prefsFilePath, JSON.stringify(prefs, null, 2), "utf-8");
 	} catch (e) {
 		console.warn("░░░░░ Could not modify Brave preferences:", e.message);
@@ -380,6 +389,35 @@ async function spawnAndConnect({ binaryPath, profilePath, isPersistent, proxy, e
 	let closing = false;
 	let signalHandler;
 
+	// ======================================================
+	// Prevent Tab Restore via Preferences
+	// Sets exit_type to "Normal" and startup to open about:blank
+	// This prevents old tabs from loading (saves proxy bandwidth)
+	// ======================================================
+	try {
+		const prefsFilePath = path.join(profilePath, "Default", "Preferences");
+		const prefsDir = path.dirname(prefsFilePath);
+		if (!fs.existsSync(prefsDir)) fs.mkdirSync(prefsDir, { recursive: true });
+
+		let prefs = {};
+		if (fs.existsSync(prefsFilePath)) {
+			prefs = JSON.parse(fs.readFileSync(prefsFilePath, "utf-8"));
+		}
+
+		// Prevent "Restore pages?" prompt after crash
+		if (!prefs.profile) prefs.profile = {};
+		prefs.profile.exit_type = "Normal";
+
+		// Set startup to open about:blank instead of restoring tabs
+		if (!prefs.session) prefs.session = {};
+		prefs.session.restore_on_startup = 4;
+		prefs.session.startup_urls = ["about:blank"];
+
+		fs.writeFileSync(prefsFilePath, JSON.stringify(prefs, null, 2), "utf-8");
+	} catch (e) {
+		// Non-critical — don't break the launch
+	}
+
 	// Random 5-digit port (10000–65535)
 	const debugPort = Math.floor(Math.random() * 55535) + 10000;
 
@@ -394,8 +432,10 @@ async function spawnAndConnect({ binaryPath, profilePath, isPersistent, proxy, e
 		// Very Important for Vps
 		"--no-sandbox",
 		// --- Stealth & Anti-Detection ---
+		// Suppresses "unsupported command-line flag" warning bar
 		"--test-type",
-		"--disable-blink-features=AutomationControlled",
+		// Not needed for CDP — navigator.webdriver is not set when using --remote-debugging-port
+		// "--disable-blink-features=AutomationControlled",
 
 		// --- PREVENT EXTRA TABS ---
 		"--disable-restore-session-state",