arn-browser 0.1.13 → 0.1.15

package/package.json

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

package/src/index.d.ts

@@ -5,7 +5,7 @@ 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 as ppRetryNavigation, retryClick as ppRetryClick, checkPageConditions as ppCheckPageConditions } from "./utility/puppeteer/ppHelper";
 import { startProxyServer, fetchPublicIP, fetchProxyDetails } from "./utility/proxy-utility/proxy-chain";
 import {
     fetchAwsProxy, getInstanceStatus, getPublicIpAddress,
@@ -17,20 +17,71 @@ import {
 import { get_multilogin_proxy, get_packetstream_proxy, get_x_proxy, fetchNextProxy } from "./utility/proxy-utility/proxy-helper";
 import { generateOTP } from "./others/totp-generator";
 
+/** A single cookie object (CDP format) */
+interface SessionCookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: string;
+    [key: string]: any;
+}
+
+/** A single localStorage entry for one origin */
+interface LocalStorageEntry {
+    origin: string;
+    items: { name: string; value: string }[];
+}
+
+/** Session data result from export */
+interface SessionData {
+    cookies?: SessionCookie[];
+    localStorage?: LocalStorageEntry[];
+}
+
 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: (options: {
+        page: import('puppeteer-core').Page;
+        cookies?: boolean;
+        localStorage?: boolean;
+        logger?: boolean;
+    }) => Promise<SessionData>;
+    importSession: (options: {
+        page: import('puppeteer-core').Page;
+        cookies?: SessionCookie[];
+        localStorage?: LocalStorageEntry[];
+        logger?: boolean;
+    }) => Promise<void>;
 };
 
 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: (options: {
+        page: import('playwright-core').Page;
+        cookies?: boolean;
+        localStorage?: boolean;
+        logger?: boolean;
+    }) => Promise<SessionData>;
+    importSession: (options: {
+        page: import('playwright-core').Page;
+        cookies?: SessionCookie[];
+        localStorage?: LocalStorageEntry[];
+        logger?: boolean;
+    }) => Promise<void>;
 };
 
 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.d.ts

@@ -30,6 +30,55 @@ export interface RetryClickOptions {
 	timeout?: number;
 }
 
+/** A single cookie object (CDP format) */
+export interface SessionCookie {
+	name: string;
+	value: string;
+	domain?: string;
+	path?: string;
+	expires?: number;
+	httpOnly?: boolean;
+	secure?: boolean;
+	sameSite?: string;
+	[key: string]: any;
+}
+
+/** A single localStorage entry for one origin */
+export interface LocalStorageEntry {
+	origin: string;
+	items: { name: string; value: string }[];
+}
+
+/** Options for exportSession */
+export interface ExportSessionOptions {
+	/** Playwright Page */
+	page: Page;
+	/** Export cookies. Default: true */
+	cookies?: boolean;
+	/** Export localStorage. Default: false */
+	localStorage?: boolean;
+	/** Log export progress. Default: true */
+	logger?: boolean;
+}
+
+/** Options for importSession */
+export interface ImportSessionOptions {
+	/** Playwright Page */
+	page: Page;
+	/** Cookies to import */
+	cookies?: SessionCookie[];
+	/** localStorage entries to import */
+	localStorage?: LocalStorageEntry[];
+	/** Log import progress. Default: true */
+	logger?: boolean;
+}
+
+/** Session data result */
+export interface SessionData {
+	cookies?: SessionCookie[];
+	localStorage?: LocalStorageEntry[];
+}
+
 /**
  * Navigates to a URL with retry logic and incremental timeouts.
  * If navigation fails, it temporarily goes to "about:blank" before retrying.
@@ -59,3 +108,16 @@ export function checkPageConditions(
 	checksToPerform: Record<string, string | Locator | null>,
 	timeout: number
 ): Promise<string | null>;
+
+/**
+ * Exports browser session (cookies and/or localStorage) via CDP.
+ * Silent operation — no browser blinking.
+ * cookies default: true, localStorage default: false
+ */
+export function exportSession(options: ExportSessionOptions): Promise<SessionData>;
+
+/**
+ * Imports browser session (cookies and/or localStorage) into a Playwright Browser.
+ * Imports whatever is provided. Order: localStorage first, then cookies.
+ */
+export function importSession(options: ImportSessionOptions): Promise<void>;

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,112 @@ export const checkPageConditions = async (page, checksToPerform, timeout) => {
 		return null; // Return null if no match is found
 	}
 };
+
+/**
+ * Exports browser session (cookies and/or localStorage) via CDP.
+ * Silent operation — no browser blinking.
+ *
+ * @param {Object} options
+ * @param {import('playwright-core').Page} options.page - Playwright Page
+ * @param {boolean} [options.cookies=true] - Export cookies
+ * @param {boolean} [options.localStorage=false] - Export localStorage
+ * @param {boolean} [options.logger=true] - Log export progress
+ * @returns {Promise<{cookies?: Array, localStorage?: Array}>} Session data for JSONB storage
+ */
+export const exportSession = async ({ page, cookies = true, localStorage = false, logger = true }) => {
+	const context = page.context();
+	const result = {};
+
+	if (cookies) {
+		const client = await context.newCDPSession(page);
+		const { cookies: allCookies } = await client.send("Network.getAllCookies");
+		result.cookies = allCookies;
+		await client.detach();
+		if (logger) console.log(`░░░░░ exportSession: ${allCookies.length} cookies exported`);
+	}
+
+	if (localStorage) {
+		result.localStorage = [];
+		const pages = context.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 && !result.localStorage.some((o) => o.origin === origin)) {
+					result.localStorage.push({ origin, items });
+				}
+			} catch (e) {
+				// Skip pages that can't be evaluated
+			}
+		}
+		if (logger) console.log(`░░░░░ exportSession: ${result.localStorage.length} localStorage origins exported`);
+	}
+
+	return result;
+};
+
+/**
+ * Imports browser session (cookies and/or localStorage) into a Playwright Browser.
+ * Imports whatever is provided. Order: localStorage first, then cookies.
+ *
+ * @param {Object} options
+ * @param {import('playwright-core').Page} options.page - Playwright Page
+ * @param {Array} [options.cookies] - Cookies to import
+ * @param {Array} [options.localStorage] - localStorage entries to import
+ * @param {boolean} [options.logger=true] - Log import progress
+ */
+export const importSession = async ({ page, cookies, localStorage, logger = true }) => {
+	const context = page.context();
+
+	// localStorage first — navigate to each origin and set items
+	if (localStorage?.length) {
+		for (const entry of localStorage) {
+			if (!entry.items?.length) continue;
+
+			const p = await context.newPage();
+			try {
+				await p.goto(entry.origin, { waitUntil: "load", timeout: 15000 });
+				await p.waitForLoadState("domcontentloaded");
+				await p.evaluate((items) => {
+					for (const { name, value } of items) {
+						window.localStorage.setItem(name, value);
+					}
+				}, entry.items);
+			} catch (e) {
+				// Origin may redirect — try to set localStorage on the final page
+				try {
+					await p.waitForLoadState("load", { timeout: 10000 });
+					await p.evaluate((items) => {
+						for (const { name, value } of items) {
+							window.localStorage.setItem(name, value);
+						}
+					}, entry.items);
+				} catch (_) {
+					// Skip this origin if it can't be reached
+				}
+			} finally {
+				await p.close();
+			}
+		}
+		if (logger) console.log(`░░░░░ importSession: ${localStorage.length} localStorage origins imported`);
+	}
+
+	// Cookies via CDP — silent, no navigation needed
+	if (cookies?.length) {
+		const client = await context.newCDPSession(page);
+		await client.send("Network.setCookies", { cookies });
+		await client.detach();
+		if (logger) console.log(`░░░░░ importSession: ${cookies.length} cookies imported`);
+	}
+};

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/playwright/routes/pwRoute.d.ts

@@ -14,11 +14,8 @@ export interface PwRouteOptions {
 	/** Playwright Page (provide either context or page) */
 	page?: Page | null;
 
-	/** Log successful requests to console */
-	successLogs?: boolean;
-
-	/** Log failed requests to console */
-	errorLogs?: boolean;
+	/** Log level: "info" (success+error), "error" (errors only), false (no logs). Default: "error" */
+	logger?: "info" | "error" | false;
 
 	/** Block Ad requests (Ghostery engine) */
 	blockAds?: boolean;

package/src/utility/playwright/routes/pwRoute.js

@@ -45,11 +45,10 @@ export function pwCacheLogs(log_cache = globalCache, interval = 10) {
  * @param {Object} requestHeaders - Request headers from the original request
  * @param {string} method - HTTP method (GET, POST, etc.)
  * @param {boolean} useFullUrl - Whether to use the full URL as cache key or just origin+path
- * @param {boolean} successLogs - Whether to log successful requests
- * @param {boolean} errorLogs - Whether to log error requests
+ * @param {string|false} logger - Log level: "info" (success+error), "error" (errors only), false (no logs)
  * @returns {Promise<Object>} - The response object containing status, headers, and body
  */
-async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl, successLogs, errorLogs) {
+async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl, logger) {
 	// Determine the cache key based on configuration
 	let mainUrl = new URL(url).origin + new URL(url).pathname;
 	if (useFullUrl) {
@@ -60,7 +59,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 	if (useCache) {
 		const cachedResponse = globalCache.get(mainUrl);
 		if (cachedResponse) {
-			if (successLogs) console.log(`Serving from globalCache: ${mainUrl}`);
+			if (logger === "info") console.log(`Serving from globalCache: ${mainUrl}`);
 			return cachedResponse;
 		}
 	}
@@ -79,7 +78,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 			headers: response.headers,
 			body: responseBody,
 		});
-		if (successLogs) console.log(`Success (cached): ${mainUrl}`);
+		if (logger === "info") console.log(`Success (cached): ${mainUrl}`);
 
 		return {
 			status: response.status,
@@ -87,7 +86,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 			body: responseBody,
 		};
 	} catch (error) {
-		if (errorLogs) console.error(`Failed to fetch: ${url}`, error);
+		if (logger) console.error(`Failed to fetch: ${url}`, error);
 		// We return undefined on error, which signals the route handler to fall back to normal request
 	}
 }
@@ -97,10 +96,9 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
  * @param {Object} options - Configuration options
  * @param {Object} options.context - Playwright context (optional, one is required)
  * @param {Object} options.page - Playwright page (optional, one is required)
- * @param {boolean} options.successLogs - Enable logging for successful fetches
- * @param {boolean} options.errorLogs - Enable logging for failed fetches
  * @param {boolean} options.blockImage - Enable global image blocking
  * @param {boolean} options.blockAds - Enable Ghostery ad blocking
+ * @param {string|false} [options.logger="error"] - Log level: "info" (success+error), "error" (errors only), false (no logs)
  * @param {boolean} options.useGot - Enable custom fetching via Superagent (bypassing browser network stack for intercepted types)
  * @param {boolean} options.useFullUrl - Use full URL for cache keys
  * @param {boolean} options.useCache - Enable caching
@@ -112,8 +110,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 export async function pwRoute({
 	context = null,
 	page = null,
-	successLogs = false,
-	errorLogs = false,
+	logger = false,
 	blockAds = true,
 	blockImage = true,
 	useGot = true,
@@ -294,8 +291,7 @@ export async function pwRoute({
 					requestHeaders,
 					requestMethod,
 					useFullUrl,
-					successLogs,
-					errorLogs
+					logger
 				);
 
 				if (response) {
@@ -306,7 +302,7 @@ export async function pwRoute({
 					});
 					return;
 				} else {
-					if (errorLogs) console.log("Continuing with normal request (fetchWithClient returned null):", url);
+					if (logger) console.log("Continuing with normal request (fetchWithClient returned null):", url);
 					await route.continue();
 					return;
 				}

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,115 @@ 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;
+}
+
+/** A single cookie object (CDP format) */
+export interface SessionCookie {
+	name: string;
+	value: string;
+	domain?: string;
+	path?: string;
+	expires?: number;
+	httpOnly?: boolean;
+	secure?: boolean;
+	sameSite?: string;
+	[key: string]: any;
+}
+
+/** A single localStorage entry for one origin */
+export interface LocalStorageEntry {
+	origin: string;
+	items: { name: string; value: string }[];
+}
+
+/** Options for exportSession */
+export interface ExportSessionOptions {
+	/** Any Puppeteer Page */
+	page: Page;
+	/** Export cookies. Default: true */
+	cookies?: boolean;
+	/** Export localStorage. Default: false */
+	localStorage?: boolean;
+	/** Log export progress. Default: true */
+	logger?: boolean;
+}
+
+/** Options for importSession */
+export interface ImportSessionOptions {
+	/** Any Puppeteer Page */
+	page: Page;
+	/** Cookies to import */
+	cookies?: SessionCookie[];
+	/** localStorage entries to import */
+	localStorage?: LocalStorageEntry[];
+	/** Log import progress. Default: true */
+	logger?: boolean;
+}
+
+/** Session data result */
+export interface SessionData {
+	cookies?: SessionCookie[];
+	localStorage?: LocalStorageEntry[];
+}
+
 /**
  * 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>;
+
+/**
+ * Exports browser session (cookies and/or localStorage) via CDP.
+ * Silent operation — no browser blinking.
+ * cookies default: true, localStorage default: false
+ */
+export function exportSession(options: ExportSessionOptions): Promise<SessionData>;
+
+/**
+ * Imports browser session (cookies and/or localStorage) into a Puppeteer Browser.
+ * Imports whatever is provided. Order: localStorage first, then cookies.
+ */
+export function importSession(options: ImportSessionOptions): Promise<void>;

package/src/utility/puppeteer/ppHelper.js

@@ -46,3 +46,215 @@ 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 and/or localStorage) via CDP.
+ * Silent operation — no browser blinking.
+ *
+ * @param {Object} options
+ * @param {import('puppeteer-core').Page} options.page - Any Puppeteer Page
+ * @param {boolean} [options.cookies=true] - Export cookies
+ * @param {boolean} [options.localStorage=false] - Export localStorage
+ * @param {boolean} [options.logger=true] - Log export progress
+ * @returns {Promise<{cookies?: Array, localStorage?: Array}>} Session data for JSONB storage
+ */
+export const exportSession = async ({ page, cookies = true, localStorage = false, logger = true }) => {
+	const result = {};
+
+	if (cookies) {
+		const client = await page.createCDPSession();
+		const { cookies: allCookies } = await client.send("Network.getAllCookies");
+		result.cookies = allCookies;
+		await client.detach();
+		if (logger) console.log(`░░░░░ exportSession: ${allCookies.length} cookies exported`);
+	}
+
+	if (localStorage) {
+		result.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 && !result.localStorage.some((o) => o.origin === origin)) {
+					result.localStorage.push({ origin, items });
+				}
+			} catch (e) {
+				// Skip pages that can't be evaluated
+			}
+		}
+		if (logger) console.log(`░░░░░ exportSession: ${result.localStorage.length} localStorage origins exported`);
+	}
+
+	return result;
+};
+
+/**
+ * Imports browser session (cookies and/or localStorage) into a Puppeteer Browser.
+ * Imports whatever is provided. Order: localStorage first, then cookies.
+ *
+ * @param {Object} options
+ * @param {import('puppeteer-core').Page} options.page - Any Puppeteer Page
+ * @param {Array} [options.cookies] - Cookies to import
+ * @param {Array} [options.localStorage] - localStorage entries to import
+ * @param {boolean} [options.logger=true] - Log import progress
+ */
+export const importSession = async ({ page, cookies, localStorage, logger = true }) => {
+	// localStorage first — navigate to each origin and set items
+	if (localStorage?.length) {
+		const browser = page.browser();
+
+		for (const entry of localStorage) {
+			if (!entry.items?.length) continue;
+
+			const p = await browser.newPage();
+			try {
+				await p.goto(entry.origin, { waitUntil: "load", timeout: 15000 });
+				await p.evaluate((items) => {
+					for (const { name, value } of items) {
+						window.localStorage.setItem(name, value);
+					}
+				}, entry.items);
+			} catch (e) {
+				// Origin may redirect — retry after load
+				try {
+					await p.waitForNavigation({ waitUntil: "load", timeout: 10000 }).catch(() => {});
+					await p.evaluate((items) => {
+						for (const { name, value } of items) {
+							window.localStorage.setItem(name, value);
+						}
+					}, entry.items);
+				} catch (_) {
+					// Skip this origin
+				}
+			} finally {
+				await p.close();
+			}
+		}
+		if (logger) console.log(`░░░░░ importSession: ${localStorage.length} localStorage origins imported`);
+	}
+
+	// Cookies via CDP — silent, no navigation needed
+	if (cookies?.length) {
+		const client = await page.createCDPSession();
+		await client.send("Network.setCookies", { cookies });
+		await client.detach();
+		if (logger) console.log(`░░░░░ importSession: ${cookies.length} cookies imported`);
+	}
+};

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",

package/src/utility/puppeteer/routes/ppRoute.d.ts

@@ -11,11 +11,8 @@ export interface PpRouteOptions {
 	/** Puppeteer Page */
 	page?: Page | null;
 
-	/** Log successful requests to console */
-	successLogs?: boolean;
-
-	/** Log failed requests to console */
-	errorLogs?: boolean;
+	/** Log level: "info" (success+error), "error" (errors only), false (no logs). Default: "error" */
+	logger?: "info" | "error" | false;
 
 	/** Block Ad requests (Ghostery engine) */
 	blockAds?: boolean;

package/src/utility/puppeteer/routes/ppRoute.js

@@ -45,11 +45,10 @@ export function ppCacheLogs(log_cache = globalCache, interval = 10) {
  * @param {Object} requestHeaders - Request headers from the original request
  * @param {string} method - HTTP method (GET, POST, etc.)
  * @param {boolean} useFullUrl - Whether to use the full URL as cache key or just origin+path
- * @param {boolean} successLogs - Whether to log successful requests
- * @param {boolean} errorLogs - Whether to log error requests
+ * @param {string|false} logger - Log level: "info" (success+error), "error" (errors only), false (no logs)
  * @returns {Promise<Object>} - The response object containing status, headers, and body
  */
-async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl, successLogs, errorLogs) {
+async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl, logger) {
 	// Determine the cache key based on configuration
 	let mainUrl = new URL(url).origin + new URL(url).pathname;
 	if (useFullUrl) {
@@ -60,7 +59,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 	if (useCache) {
 		const cachedResponse = globalCache.get(mainUrl);
 		if (cachedResponse) {
-			if (successLogs) console.log(`Serving from globalCache: ${mainUrl}`);
+			if (logger === "info") console.log(`Serving from globalCache: ${mainUrl}`);
 			return cachedResponse;
 		}
 	}
@@ -79,7 +78,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 			headers: response.headers,
 			body: responseBody,
 		});
-		if (successLogs) console.log(`Success (cached): ${mainUrl}`);
+		if (logger === "info") console.log(`Success (cached): ${mainUrl}`);
 
 		return {
 			status: response.status,
@@ -87,7 +86,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 			body: responseBody,
 		};
 	} catch (error) {
-		if (errorLogs) console.error(`Failed to fetch: ${url}`, error);
+		if (logger) console.error(`Failed to fetch: ${url}`, error);
 		// We return undefined on error, which signals the route handler to fall back to normal request
 	}
 }
@@ -97,10 +96,9 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
  * @param {Object} options - Configuration options
  * @param {Object} options.context - Playwright context (optional, one is required)
  * @param {Object} options.page - Playwright page (optional, one is required)
- * @param {boolean} options.successLogs - Enable logging for successful fetches
- * @param {boolean} options.errorLogs - Enable logging for failed fetches
  * @param {boolean} options.blockImage - Enable global image blocking
  * @param {boolean} options.blockAds - Enable Ghostery ad blocking
+ * @param {string|false} [options.logger="error"] - Log level: "info" (success+error), "error" (errors only), false (no logs)
  * @param {boolean} options.useGot - Enable custom fetching via Superagent (bypassing browser network stack for intercepted types)
  * @param {boolean} options.useFullUrl - Use full URL for cache keys
  * @param {boolean} options.useCache - Enable caching
@@ -111,8 +109,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
  */
 export async function ppRoute({
 	page = null,
-	successLogs = false,
-	errorLogs = false,
+	logger = false,
 	blockAds = true,
 	blockImage = true,
 	useGot = true,
@@ -298,8 +295,7 @@ export async function ppRoute({
 					requestHeaders,
 					requestMethod,
 					useFullUrl,
-					successLogs,
-					errorLogs
+					logger
 				);
 
 				if (response) {
@@ -310,7 +306,7 @@ export async function ppRoute({
 					});
 					return;
 				} else {
-					if (errorLogs) console.log("Continuing with normal request (fetchWithClient returned null):", url);
+					if (logger) console.log("Continuing with normal request (fetchWithClient returned null):", url);
 					await request.continue();
 					return;
 				}