arn-browser 0.1.15 → 0.1.16

package/package.json

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

package/src/utility/playwright/routes/pwRoute.d.ts

@@ -32,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.
@@ -46,9 +80,10 @@ export function pwCacheLogs(log_cache = globalCache, interval = 10) {
  * @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 {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, logger) {
+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) {
@@ -67,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 (logger === "info") 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,
@@ -102,6 +148,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
  * @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.
@@ -113,9 +160,10 @@ export async function pwRoute({
 	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
@@ -149,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");
@@ -291,7 +343,8 @@ export async function pwRoute({
 					requestHeaders,
 					requestMethod,
 					useFullUrl,
-					logger
+					logger,
+					proxyAgent
 				);
 
 				if (response) {

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

@@ -29,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.
@@ -46,9 +80,10 @@ export function ppCacheLogs(log_cache = globalCache, interval = 10) {
  * @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 {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, logger) {
+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) {
@@ -67,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 (logger === "info") 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,
@@ -92,16 +138,16 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 }
 
 /**
- * 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 {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.
@@ -112,9 +158,10 @@ export async function ppRoute({
 	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
@@ -147,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");
@@ -295,7 +346,8 @@ export async function ppRoute({
 					requestHeaders,
 					requestMethod,
 					useFullUrl,
-					logger
+					logger,
+					proxyAgent
 				);
 
 				if (response) {