arn-browser 0.1.34 → 0.1.35

package/package.json

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

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

@@ -4,6 +4,38 @@ import { Browser, BrowserContext, Page } from "playwright-core";
 // ROUTING & CACHE TYPES
 // ============================================================================
 
+/**
+ * Supported browser resource types for interception.
+ *
+ * - `"document"` — HTML pages
+ * - `"stylesheet"` — CSS files
+ * - `"image"` — Images (png, jpg, svg, etc.)
+ * - `"media"` — Audio/Video
+ * - `"font"` — Web fonts (woff, woff2, ttf, etc.)
+ * - `"script"` — JavaScript files
+ * - `"xhr"` — XMLHttpRequest calls
+ * - `"fetch"` — Fetch API calls
+ */
+export type ResourceType = "document" | "stylesheet" | "image" | "media" | "font" | "script" | "xhr" | "fetch";
+
+/** Control object returned by pwRoute for runtime resource management */
+export interface RouteControl {
+	/**
+	 * Add a resource type to intercept via Superagent at runtime.
+	 *
+	 * Supported: `"document"` | `"stylesheet"` | `"image"` | `"media"` | `"font"` | `"script"` | `"xhr"` | `"fetch"`
+	 */
+	addResource(type: ResourceType): void;
+	/**
+	 * Remove a resource type from Superagent interception at runtime.
+	 *
+	 * Supported: `"document"` | `"stylesheet"` | `"image"` | `"media"` | `"font"` | `"script"` | `"xhr"` | `"fetch"`
+	 */
+	removeResource(type: ResourceType): void;
+	/** Get currently intercepted resource types */
+	getResources(): ResourceType[];
+}
+
 /**
  * Options for the pwRoute function.
  */
@@ -62,12 +94,47 @@ export interface PwRouteOptions {
 	 * Playwright network stack will be used instead.
 	 */
 	skipGotPatterns?: string[];
+
+	/**
+	 * Additional resource types to intercept via Superagent.
+	 * These are added on top of the defaults: `["stylesheet", "script", "font"]`
+	 *
+	 * - `"document"` — HTML pages
+	 * - `"stylesheet"` — CSS files
+	 * - `"image"` — Images (png, jpg, svg, etc.)
+	 * - `"media"` — Audio/Video
+	 * - `"font"` — Web fonts (woff, woff2, ttf, etc.)
+	 * - `"script"` — JavaScript files
+	 * - `"xhr"` — XMLHttpRequest calls
+	 * - `"fetch"` — Fetch API calls
+	 *
+	 * @example `gotAddResources: ["document", "xhr"]`
+	 */
+	gotAddResources?: ResourceType[];
+
+	/**
+	 * Resource types to exclude from Superagent interception.
+	 * These are removed from the defaults: `["stylesheet", "script", "font"]`
+	 *
+	 * - `"document"` — HTML pages
+	 * - `"stylesheet"` — CSS files
+	 * - `"image"` — Images (png, jpg, svg, etc.)
+	 * - `"media"` — Audio/Video
+	 * - `"font"` — Web fonts (woff, woff2, ttf, etc.)
+	 * - `"script"` — JavaScript files
+	 * - `"xhr"` — XMLHttpRequest calls
+	 * - `"fetch"` — Fetch API calls
+	 *
+	 * @example `gotRemoveResources: ["font"]`
+	 */
+	gotRemoveResources?: ResourceType[];
 }
 
 /**
  * Sets up request interception, caching, and ad-blocking on a Playwright page or context.
+ * Returns a control object for runtime resource management.
  */
-export function pwRoute(options: PwRouteOptions): Promise<void>;
+export function pwRoute(options: PwRouteOptions): Promise<RouteControl>;
 
 /**
  * Starts logging cache statistics to the console at a set interval.

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

@@ -76,7 +76,7 @@ function createProxyAgent(proxyUrl) {
  * Only keeps essential headers needed for the server to respond correctly.
  * Everything else (cookies, auth, fingerprint hints, HTTP/2 pseudo-headers, etc.) is stripped.
  */
-function sanitizeRequestHeaders(headers, logger, url) {
+function sanitizeRequestHeaders(headers, logger, url, resourceType) {
 	// Allowlist of essential request headers to keep
 	const allowedHeaders = new Set([
 		"accept",
@@ -93,6 +93,16 @@ function sanitizeRequestHeaders(headers, logger, url) {
 		"sec-fetch-site",
 	]);
 
+	// For document/xhr/fetch types, preserve session-critical headers
+	const sessionTypes = new Set(["document", "xhr", "fetch"]);
+	if (sessionTypes.has(resourceType)) {
+		allowedHeaders.add("cookie");
+		allowedHeaders.add("authorization");
+		allowedHeaders.add("origin");
+		allowedHeaders.add("content-type");
+		allowedHeaders.add("x-requested-with");
+	}
+
 	const cleaned = {};
 	const stripped = [];
 
@@ -160,7 +170,7 @@ function sanitizeResponseHeaders(headers, logger, url) {
  * @param {boolean} stripLogger - Whether to log stripped headers
  * @returns {Promise<Object>} - The response object containing status, headers, and body
  */
-async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl, logger, proxyAgent, stripHeaders, stripLogger) {
+async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl, logger, proxyAgent, stripHeaders, stripLogger, resourceType) {
 	// Determine the cache key based on configuration
 	let mainUrl = new URL(url).origin + new URL(url).pathname;
 	if (useFullUrl) {
@@ -180,7 +190,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 
 	try {
 		// Sanitize outgoing request headers if stripHeaders is enabled
-		const finalHeaders = stripHeaders ? sanitizeRequestHeaders(requestHeaders, stripLogger, url) : requestHeaders;
+		const finalHeaders = stripHeaders ? sanitizeRequestHeaders(requestHeaders, stripLogger, url, resourceType) : requestHeaders;
 
 		// Fetch the resource using superagent
 		// buffer(true) ensures we get the raw binary data (essential for images/fonts)
@@ -238,6 +248,8 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
  * @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.
  * @param {Array<string>} options.skipGotPatterns - Array of strings/patterns. If a URL contains any of these, it will skip the custom Superagent fetch.
+ * @param {Array<string>} options.gotAddResources - Additional resource types to intercept via Superagent, e.g. ["document", "xhr", "fetch"]
+ * @param {Array<string>} options.gotRemoveResources - Resource types to exclude from Superagent interception, e.g. ["font"]
  */
 export async function pwRoute({
 	context = null,
@@ -255,6 +267,8 @@ export async function pwRoute({
 	m4w_send_on_message = null,
 	allowImagePatterns = [], // Default empty, merged inside
 	skipGotPatterns = [], // Default empty, merged inside
+	gotAddResources = [], // Default empty, add to intercepted types
+	gotRemoveResources = [], // Default empty, remove from intercepted types
 }) {
 	// Validation: Ensure we have a target to attach the route to
 	if (!context && !page) {
@@ -289,16 +303,25 @@ export async function pwRoute({
 		}
 	}
 
+	// Supported resource types reference (for documentation)
+	// "document", "stylesheet", "image", "media", "font", "script",
+	// "texttrack", "xhr", "fetch", "eventsource", "websocket", "manifest", "other"
+
 	// Define resource types to intercept for custom fetching (useGot)
-	const interceptedResourceTypes = ["stylesheet", "script", "font"];
+	// Start with defaults, add user extras, then remove user exclusions
+	const defaultResourceTypes = ["stylesheet", "script", "font"];
+	const interceptedResourceTypes = new Set([...defaultResourceTypes, ...gotAddResources]);
+	for (const type of gotRemoveResources) {
+		interceptedResourceTypes.delete(type);
+	}
 
 	// 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");
+	if (!blockImage && !gotRemoveResources.includes("image")) {
+		interceptedResourceTypes.add("image");
 	}
 
 	// Set up the global route interception
@@ -424,7 +447,7 @@ export async function pwRoute({
 		// ============================================================
 		// Group 6: Resource Interception (Custom Fetch/Cache)
 		// ============================================================
-		if (useGot && interceptedResourceTypes.includes(resourceType) && !url.startsWith("data:")) {
+		if (useGot && interceptedResourceTypes.has(resourceType) && !url.startsWith("data:")) {
 			// Check against the normalized host list (defaults + user input)
 			let shouldSkipGot = false;
 			try {
@@ -444,7 +467,8 @@ export async function pwRoute({
 					logger,
 					proxyAgent,
 					stripGotHeaders,
-					stripGotLogger
+					stripGotLogger,
+					resourceType
 				);
 
 				if (response) {
@@ -468,4 +492,20 @@ export async function pwRoute({
 		await route.continue();
 		return;
 	});
+
+	// Return control object for runtime resource management
+	return {
+		/** Add a resource type to intercept via Superagent at runtime */
+		addResource(type) {
+			interceptedResourceTypes.add(type);
+		},
+		/** Remove a resource type from Superagent interception at runtime */
+		removeResource(type) {
+			interceptedResourceTypes.delete(type);
+		},
+		/** Get currently intercepted resource types */
+		getResources() {
+			return [...interceptedResourceTypes];
+		},
+	};
 }

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

@@ -4,6 +4,38 @@ import { Browser, Page } from "puppeteer-core";
 // ROUTING & CACHE TYPES
 // ============================================================================
 
+/**
+ * Supported browser resource types for interception.
+ *
+ * - `"document"` — HTML pages
+ * - `"stylesheet"` — CSS files
+ * - `"image"` — Images (png, jpg, svg, etc.)
+ * - `"media"` — Audio/Video
+ * - `"font"` — Web fonts (woff, woff2, ttf, etc.)
+ * - `"script"` — JavaScript files
+ * - `"xhr"` — XMLHttpRequest calls
+ * - `"fetch"` — Fetch API calls
+ */
+export type ResourceType = "document" | "stylesheet" | "image" | "media" | "font" | "script" | "xhr" | "fetch";
+
+/** Control object returned by ppRoute for runtime resource management */
+export interface RouteControl {
+	/**
+	 * Add a resource type to intercept via Superagent at runtime.
+	 *
+	 * Supported: `"document"` | `"stylesheet"` | `"image"` | `"media"` | `"font"` | `"script"` | `"xhr"` | `"fetch"`
+	 */
+	addResource(type: ResourceType): void;
+	/**
+	 * Remove a resource type from Superagent interception at runtime.
+	 *
+	 * Supported: `"document"` | `"stylesheet"` | `"image"` | `"media"` | `"font"` | `"script"` | `"xhr"` | `"fetch"`
+	 */
+	removeResource(type: ResourceType): void;
+	/** Get currently intercepted resource types */
+	getResources(): ResourceType[];
+}
+
 /**
  * Options for the ppRoute function.
  */
@@ -59,12 +91,47 @@ export interface PpRouteOptions {
 	 * Playwright network stack will be used instead.
 	 */
 	skipGotPatterns?: string[];
+
+	/**
+	 * Additional resource types to intercept via Superagent.
+	 * These are added on top of the defaults: `["stylesheet", "script", "font"]`
+	 *
+	 * - `"document"` — HTML pages
+	 * - `"stylesheet"` — CSS files
+	 * - `"image"` — Images (png, jpg, svg, etc.)
+	 * - `"media"` — Audio/Video
+	 * - `"font"` — Web fonts (woff, woff2, ttf, etc.)
+	 * - `"script"` — JavaScript files
+	 * - `"xhr"` — XMLHttpRequest calls
+	 * - `"fetch"` — Fetch API calls
+	 *
+	 * @example `gotAddResources: ["document", "xhr"]`
+	 */
+	gotAddResources?: ResourceType[];
+
+	/**
+	 * Resource types to exclude from Superagent interception.
+	 * These are removed from the defaults: `["stylesheet", "script", "font"]`
+	 *
+	 * - `"document"` — HTML pages
+	 * - `"stylesheet"` — CSS files
+	 * - `"image"` — Images (png, jpg, svg, etc.)
+	 * - `"media"` — Audio/Video
+	 * - `"font"` — Web fonts (woff, woff2, ttf, etc.)
+	 * - `"script"` — JavaScript files
+	 * - `"xhr"` — XMLHttpRequest calls
+	 * - `"fetch"` — Fetch API calls
+	 *
+	 * @example `gotRemoveResources: ["font"]`
+	 */
+	gotRemoveResources?: ResourceType[];
 }
 
 /**
  * Sets up request interception, caching, and ad-blocking on a Puppeteer page.
+ * Returns a control object for runtime resource management.
  */
-export function ppRoute(options: PpRouteOptions): Promise<void>;
+export function ppRoute(options: PpRouteOptions): Promise<RouteControl>;
 
 /**
  * Starts logging cache statistics to the console at a set interval.

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

@@ -76,7 +76,7 @@ function createProxyAgent(proxyUrl) {
  * Only keeps essential headers needed for the server to respond correctly.
  * Everything else (cookies, auth, fingerprint hints, HTTP/2 pseudo-headers, etc.) is stripped.
  */
-function sanitizeRequestHeaders(headers, logger, url) {
+function sanitizeRequestHeaders(headers, logger, url, resourceType) {
 	// Allowlist of essential request headers to keep
 	const allowedHeaders = new Set([
 		"accept",
@@ -93,6 +93,16 @@ function sanitizeRequestHeaders(headers, logger, url) {
 		"sec-fetch-site",
 	]);
 
+	// For document/xhr/fetch types, preserve session-critical headers
+	const sessionTypes = new Set(["document", "xhr", "fetch"]);
+	if (sessionTypes.has(resourceType)) {
+		allowedHeaders.add("cookie");
+		allowedHeaders.add("authorization");
+		allowedHeaders.add("origin");
+		allowedHeaders.add("content-type");
+		allowedHeaders.add("x-requested-with");
+	}
+
 	const cleaned = {};
 	const stripped = [];
 
@@ -163,7 +173,7 @@ function sanitizeResponseHeaders(headers, logger, url) {
  * @param {boolean} stripLogger - Whether to log stripped headers
  * @returns {Promise<Object>} - The response object containing status, headers, and body
  */
-async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl, logger, proxyAgent, stripHeaders, stripLogger) {
+async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl, logger, proxyAgent, stripHeaders, stripLogger, resourceType) {
 	// Determine the cache key based on configuration
 	let mainUrl = new URL(url).origin + new URL(url).pathname;
 	if (useFullUrl) {
@@ -183,7 +193,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
 
 	try {
 		// Sanitize outgoing request headers if stripHeaders is enabled
-		const finalHeaders = stripHeaders ? sanitizeRequestHeaders(requestHeaders, stripLogger, url) : requestHeaders;
+		const finalHeaders = stripHeaders ? sanitizeRequestHeaders(requestHeaders, stripLogger, url, resourceType) : requestHeaders;
 
 		// Fetch the resource using superagent
 		// buffer(true) ensures we get the raw binary data (essential for images/fonts)
@@ -240,6 +250,8 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
  * @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.
  * @param {Array<string>} options.skipGotPatterns - Array of strings/patterns. If a URL contains any of these, it will skip the custom Superagent fetch.
+ * @param {Array<string>} options.gotAddResources - Additional resource types to intercept via Superagent, e.g. ["document", "xhr", "fetch"]
+ * @param {Array<string>} options.gotRemoveResources - Resource types to exclude from Superagent interception, e.g. ["font"]
  */
 export async function ppRoute({
 	page = null,
@@ -256,6 +268,8 @@ export async function ppRoute({
 	m4w_send_on_message = null,
 	allowImagePatterns = [], // Default empty, merged inside
 	skipGotPatterns = [], // Default empty, merged inside
+	gotAddResources = [], // Default empty, add to intercepted types
+	gotRemoveResources = [], // Default empty, remove from intercepted types
 }) {
 	// Validation: Ensure we have a page
 	if (!page) {
@@ -289,16 +303,25 @@ export async function ppRoute({
 		}
 	}
 
+	// Supported resource types reference (for documentation)
+	// "document", "stylesheet", "image", "media", "font", "script",
+	// "texttrack", "xhr", "fetch", "eventsource", "websocket", "manifest", "other"
+
 	// Define resource types to intercept for custom fetching (useGot)
-	const interceptedResourceTypes = ["stylesheet", "script", "font"];
+	// Start with defaults, add user extras, then remove user exclusions
+	const defaultResourceTypes = ["stylesheet", "script", "font"];
+	const interceptedResourceTypes = new Set([...defaultResourceTypes, ...gotAddResources]);
+	for (const type of gotRemoveResources) {
+		interceptedResourceTypes.delete(type);
+	}
 
 	// 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");
+	if (!blockImage && !gotRemoveResources.includes("image")) {
+		interceptedResourceTypes.add("image");
 	}
 
 	// Enable request interception in Puppeteer
@@ -430,7 +453,7 @@ export async function ppRoute({
 		// ============================================================
 		// Group 6: Resource Interception (Custom Fetch/Cache)
 		// ============================================================
-		if (useGot && interceptedResourceTypes.includes(resourceType) && !url.startsWith("data:")) {
+		if (useGot && interceptedResourceTypes.has(resourceType) && !url.startsWith("data:")) {
 			// Check against the normalized host list (defaults + user input)
 			let shouldSkipGot = false;
 			try {
@@ -450,7 +473,8 @@ export async function ppRoute({
 					logger,
 					proxyAgent,
 					stripGotHeaders,
-					stripGotLogger
+					stripGotLogger,
+					resourceType
 				);
 
 				if (response) {
@@ -474,4 +498,20 @@ export async function ppRoute({
 		await request.continue();
 		return;
 	});
+
+	// Return control object for runtime resource management
+	return {
+		/** Add a resource type to intercept via Superagent at runtime */
+		addResource(type) {
+			interceptedResourceTypes.add(type);
+		},
+		/** Remove a resource type from Superagent interception at runtime */
+		removeResource(type) {
+			interceptedResourceTypes.delete(type);
+		},
+		/** Get currently intercepted resource types */
+		getResources() {
+			return [...interceptedResourceTypes];
+		},
+	};
 }