arn-browser 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "arn-browser",
-	"version": "0.1.14",
+	"version": "0.1.16",
 	"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, 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 { retryNavigation, retryClick, checkPageConditions } from "./utility/playwright/pwHelper";
+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,6 +17,31 @@ 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;
@@ -24,8 +49,18 @@ export declare const ppBrowser: {
     Goto: typeof ppRetryNavigation;
     Click: typeof ppRetryClick;
     Conditions: typeof ppCheckPageConditions;
-    exportSession: typeof ppExportSession;
-    importSession: typeof ppImportSession;
+    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: {
@@ -35,8 +70,18 @@ export declare const pwBrowser: {
     Goto: typeof retryNavigation;
     Click: typeof retryClick;
     Conditions: typeof checkPageConditions;
-    exportSession: typeof exportSession;
-    importSession: typeof importSession;
+    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/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

@@ -129,81 +129,110 @@ export const checkPageConditions = async (page, checksToPerform, timeout) => {
 };
 
 /**
- * Exports browser session (cookies + localStorage) via CDP.
+ * Exports browser session (cookies and/or 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
+ * @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 (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();
+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`);
+	}
 
-	const localStorage = [];
-	for (const p of pages) {
-		const url = p.url();
-		if (!url || url === "about:blank" || url.startsWith("chrome")) continue;
+	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;
+				});
 
-		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) });
+				if (items.length > 0 && !result.localStorage.some((o) => o.origin === origin)) {
+					result.localStorage.push({ origin, items });
 				}
-				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
 			}
-		} catch (e) {
-			// Skip pages that can't be evaluated
 		}
+		if (logger) console.log(`░░░░░ exportSession: ${result.localStorage.length} localStorage origins exported`);
 	}
 
-	return { cookies, localStorage };
+	return result;
 };
 
 /**
- * Imports browser session (cookies + localStorage) via CDP.
- * Silent operation — no browser blinking.
+ * Imports browser session (cookies and/or localStorage) into a Playwright Browser.
+ * Imports whatever is provided. Order: localStorage first, then cookies.
  *
- * @param {import('playwright-core').BrowserContext} context - Playwright BrowserContext
- * @param {Object} data - Session data { cookies, localStorage }
+ * @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 (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 });
-	}
+export const importSession = async ({ page, cookies, localStorage, logger = true }) => {
+	const context = page.context();
 
-	if (data.localStorage?.length) {
-		await client.send("DOMStorage.enable");
-		for (const entry of data.localStorage) {
+	// localStorage first — navigate to each origin and set items
+	if (localStorage?.length) {
+		for (const entry of 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,
-				});
+			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`);
 	}
 
-	await client.detach();
+	// 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/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;
@@ -35,6 +32,13 @@ export interface PwRouteOptions {
 	/** Enable caching for requests */
 	useCache?: boolean;
 
+	/**
+	 * Proxy for custom fetch requests (only used when useGot is true).
+	 * String: "http://host:port", "socks5://user:pass@host:port"
+	 * Object: { type, host, port, user, pass }
+	 */
+	proxy?: string | { type?: string; host: string; port: number; user?: string; pass?: string } | null;
+
 	/** Data object for Doublelist message interception (POST logic) */
 	m4w_send_on_post?: Record<string, any> | null;
 

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

@@ -2,6 +2,8 @@
 import superagent from "superagent";
 import { FiltersEngine, Request } from "@ghostery/adblocker";
 import fetch from "node-fetch";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { SocksProxyAgent } from "socks-proxy-agent";
 import NodeCache from "node-cache";
 
 let AdBlockEngine;
@@ -37,6 +39,38 @@ export function pwCacheLogs(log_cache = globalCache, interval = 10) {
 	}
 }
 
+/**
+ * Normalizes proxy input (string or object) into a URL string.
+ * Accepts:
+ *   - String: "http://host:port", "socks5://user:pass@host:port", etc.
+ *   - Object: { type, host, port, user, pass }
+ * @param {string|Object|null} proxy
+ * @returns {string|null} - Proxy URL string or null
+ */
+function formatProxyUrl(proxy) {
+	if (!proxy) return null;
+	if (typeof proxy === "string") return proxy;
+	if (typeof proxy === "object") {
+		const { type = "http", host, port, user, pass } = proxy;
+		const auth = user && pass ? `${user}:${pass}@` : "";
+		return `${type}://${auth}${host}:${port}`;
+	}
+	return null;
+}
+
+/**
+ * Creates an HTTP agent for the given proxy URL.
+ * @param {string|null} proxyUrl
+ * @returns {Object|null} - HttpsProxyAgent or SocksProxyAgent instance
+ */
+function createProxyAgent(proxyUrl) {
+	if (!proxyUrl) return null;
+	if (proxyUrl.startsWith("socks")) {
+		return new SocksProxyAgent(proxyUrl);
+	}
+	return new HttpsProxyAgent(proxyUrl);
+}
+
 /**
  * Function to fetch resources using Superagent library with optional caching.
  * This mimics the browser's request but handles it in Node.js to allow caching or header manipulation.
@@ -45,11 +79,11 @@ 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)
+ * @param {Object|null} proxyAgent - Proxy agent to use for the request
  * @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, proxyAgent) {
 	// Determine the cache key based on configuration
 	let mainUrl = new URL(url).origin + new URL(url).pathname;
 	if (useFullUrl) {
@@ -60,7 +94,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;
 		}
 	}
@@ -68,18 +102,29 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 	try {
 		// Fetch the resource using superagent
 		// buffer(true) ensures we get the raw binary data (essential for images/fonts)
-		const response = await superagent(method, url).set(requestHeaders).buffer(true);
+		let request = superagent(method, url).set(requestHeaders).buffer(true);
+
+		// Apply proxy agent if provided
+		if (proxyAgent) {
+			request = request.agent(proxyAgent);
+		}
+
+		const response = await request;
 
 		// Determine the correct body type (Buffer for binary, text for others)
 		const responseBody = response.body instanceof Buffer ? response.body : response.text;
 
-		// Save to cache
-		globalCache.set(mainUrl, {
-			status: response.status,
-			headers: response.headers,
-			body: responseBody,
-		});
-		if (successLogs) console.log(`Success (cached): ${mainUrl}`);
+		// Save to cache only when caching is enabled
+		if (useCache) {
+			globalCache.set(mainUrl, {
+				status: response.status,
+				headers: response.headers,
+				body: responseBody,
+			});
+			if (logger === "info") console.log(`Success (cached): ${mainUrl}`);
+		} else {
+			if (logger === "info") console.log(`Success (not cached): ${mainUrl}`);
+		}
 
 		return {
 			status: response.status,
@@ -87,7 +132,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,13 +142,13 @@ 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
+ * @param {string|Object|null} options.proxy - Proxy for custom fetch. String: "http://host:port" or "socks5://user:pass@host:port". Object: { type, host, port, user, pass }
  * @param {Object} options.m4w_send_on_post - Custom handler data for Doublelist posts
  * @param {Object} options.m4w_send_on_message - Custom handler data for Doublelist messages
  * @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.
@@ -112,13 +157,13 @@ 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,
+	useGot = false,
 	useFullUrl = true,
 	useCache = true,
+	proxy = null,
 	m4w_send_on_post = null,
 	m4w_send_on_message = null,
 	allowImagePatterns = [], // Default empty, merged inside
@@ -152,6 +197,10 @@ export async function pwRoute({
 	// Define resource types to intercept for custom fetching (useGot)
 	const interceptedResourceTypes = ["stylesheet", "script", "font"];
 
+	// Create proxy agent once (reused for all requests in this route)
+	const proxyUrl = formatProxyUrl(proxy);
+	const proxyAgent = createProxyAgent(proxyUrl);
+
 	// If images are NOT blocked, we generally want to intercept/cache them too.
 	if (!blockImage) {
 		interceptedResourceTypes.push("image");
@@ -294,8 +343,8 @@ export async function pwRoute({
 					requestHeaders,
 					requestMethod,
 					useFullUrl,
-					successLogs,
-					errorLogs
+					logger,
+					proxyAgent
 				);
 
 				if (response) {
@@ -306,7 +355,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

@@ -34,6 +34,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 {
+	/** 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.
@@ -68,3 +117,16 @@ export function checkPageConditions(
 	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

@@ -151,77 +151,110 @@ export const checkPageConditions = async (page, checksToPerform, timeout) => {
 };
 
 /**
- * Exports browser session (cookies + localStorage) via CDP.
+ * Exports browser session (cookies and/or 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
+ * @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) => {
-	const client = await page.createCDPSession();
-	const { cookies } = await client.send("Network.getAllCookies");
-	await client.detach();
+export const exportSession = async ({ page, cookies = true, localStorage = false, logger = true }) => {
+	const result = {};
 
-	const localStorage = [];
-	const browser = page.browser();
-	const pages = await browser.pages();
+	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`);
+	}
 
-	for (const p of pages) {
-		const url = p.url();
-		if (!url || url === "about:blank" || url.startsWith("chrome")) continue;
+	if (localStorage) {
+		result.localStorage = [];
+		const browser = page.browser();
+		const pages = await browser.pages();
 
-		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;
-			});
+		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 });
+				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
 			}
-		} catch (e) {
-			// Skip pages that can't be evaluated
 		}
+		if (logger) console.log(`░░░░░ exportSession: ${result.localStorage.length} localStorage origins exported`);
 	}
 
-	return { cookies, localStorage };
+	return result;
 };
 
 /**
- * Imports browser session (cookies + localStorage) into a Puppeteer Browser.
+ * Imports browser session (cookies and/or localStorage) into a Puppeteer Browser.
+ * Imports whatever is provided. Order: localStorage first, then cookies.
  *
- * @param {import('puppeteer-core').Page} page - Any Puppeteer Page
- * @param {Object} data - Session data { cookies, localStorage }
+ * @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, 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) {
+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 data.localStorage) {
+		for (const entry of localStorage) {
 			if (!entry.items?.length) continue;
 
 			const p = await browser.newPage();
 			try {
-				await p.goto(entry.origin, { waitUntil: "domcontentloaded", timeout: 15000 });
+				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/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;
@@ -32,6 +29,13 @@ export interface PpRouteOptions {
 	/** Enable caching for requests */
 	useCache?: boolean;
 
+	/**
+	 * Proxy for custom fetch requests (only used when useGot is true).
+	 * String: "http://host:port", "socks5://user:pass@host:port"
+	 * Object: { type, host, port, user, pass }
+	 */
+	proxy?: string | { type?: string; host: string; port: number; user?: string; pass?: string } | null;
+
 	/** Data object for Doublelist message interception (POST logic) */
 	m4w_send_on_post?: Record<string, any> | null;
 

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

@@ -2,6 +2,8 @@
 import superagent from "superagent";
 import { FiltersEngine, Request } from "@ghostery/adblocker";
 import fetch from "node-fetch";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { SocksProxyAgent } from "socks-proxy-agent";
 import NodeCache from "node-cache";
 
 let AdBlockEngine;
@@ -37,6 +39,38 @@ export function ppCacheLogs(log_cache = globalCache, interval = 10) {
 	}
 }
 
+/**
+ * Normalizes proxy input (string or object) into a URL string.
+ * Accepts:
+ *   - String: "http://host:port", "socks5://user:pass@host:port", etc.
+ *   - Object: { type, host, port, user, pass }
+ * @param {string|Object|null} proxy
+ * @returns {string|null} - Proxy URL string or null
+ */
+function formatProxyUrl(proxy) {
+	if (!proxy) return null;
+	if (typeof proxy === "string") return proxy;
+	if (typeof proxy === "object") {
+		const { type = "http", host, port, user, pass } = proxy;
+		const auth = user && pass ? `${user}:${pass}@` : "";
+		return `${type}://${auth}${host}:${port}`;
+	}
+	return null;
+}
+
+/**
+ * Creates an HTTP agent for the given proxy URL.
+ * @param {string|null} proxyUrl
+ * @returns {Object|null} - HttpsProxyAgent or SocksProxyAgent instance
+ */
+function createProxyAgent(proxyUrl) {
+	if (!proxyUrl) return null;
+	if (proxyUrl.startsWith("socks")) {
+		return new SocksProxyAgent(proxyUrl);
+	}
+	return new HttpsProxyAgent(proxyUrl);
+}
+
 /**
  * Function to fetch resources using Superagent library with optional caching.
  * This mimics the browser's request but handles it in Node.js to allow caching or header manipulation.
@@ -45,11 +79,11 @@ 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)
+ * @param {Object|null} proxyAgent - Proxy agent to use for the request
  * @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, proxyAgent) {
 	// Determine the cache key based on configuration
 	let mainUrl = new URL(url).origin + new URL(url).pathname;
 	if (useFullUrl) {
@@ -60,7 +94,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;
 		}
 	}
@@ -68,18 +102,29 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 	try {
 		// Fetch the resource using superagent
 		// buffer(true) ensures we get the raw binary data (essential for images/fonts)
-		const response = await superagent(method, url).set(requestHeaders).buffer(true);
+		let request = superagent(method, url).set(requestHeaders).buffer(true);
+
+		// Apply proxy agent if provided
+		if (proxyAgent) {
+			request = request.agent(proxyAgent);
+		}
+
+		const response = await request;
 
 		// Determine the correct body type (Buffer for binary, text for others)
 		const responseBody = response.body instanceof Buffer ? response.body : response.text;
 
-		// Save to cache
-		globalCache.set(mainUrl, {
-			status: response.status,
-			headers: response.headers,
-			body: responseBody,
-		});
-		if (successLogs) console.log(`Success (cached): ${mainUrl}`);
+		// Save to cache only when caching is enabled
+		if (useCache) {
+			globalCache.set(mainUrl, {
+				status: response.status,
+				headers: response.headers,
+				body: responseBody,
+			});
+			if (logger === "info") console.log(`Success (cached): ${mainUrl}`);
+		} else {
+			if (logger === "info") console.log(`Success (not cached): ${mainUrl}`);
+		}
 
 		return {
 			status: response.status,
@@ -87,23 +132,22 @@ 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
 	}
 }
 
 /**
- * Main function to set up routing, ad blocking, and request interception in Playwright.
+ * Main function to set up routing, ad blocking, and request interception in Puppeteer.
  * @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 {Object} options.page - Puppeteer page (required)
  * @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
+ * @param {string|Object|null} options.proxy - Proxy for custom fetch. String: "http://host:port" or "socks5://user:pass@host:port". Object: { type, host, port, user, pass }
  * @param {Object} options.m4w_send_on_post - Custom handler data for Doublelist posts
  * @param {Object} options.m4w_send_on_message - Custom handler data for Doublelist messages
  * @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.
@@ -111,13 +155,13 @@ 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,
+	useGot = false,
 	useFullUrl = true,
 	useCache = true,
+	proxy = null,
 	m4w_send_on_post = null,
 	m4w_send_on_message = null,
 	allowImagePatterns = [], // Default empty, merged inside
@@ -150,6 +194,10 @@ export async function ppRoute({
 	// Define resource types to intercept for custom fetching (useGot)
 	const interceptedResourceTypes = ["stylesheet", "script", "font"];
 
+	// Create proxy agent once (reused for all requests in this route)
+	const proxyUrl = formatProxyUrl(proxy);
+	const proxyAgent = createProxyAgent(proxyUrl);
+
 	// If images are NOT blocked, we generally want to intercept/cache them too.
 	if (!blockImage) {
 		interceptedResourceTypes.push("image");
@@ -298,8 +346,8 @@ export async function ppRoute({
 					requestHeaders,
 					requestMethod,
 					useFullUrl,
-					successLogs,
-					errorLogs
+					logger,
+					proxyAgent
 				);
 
 				if (response) {
@@ -310,7 +358,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;
 				}