arn-browser 0.1.5 → 0.1.7

package/src/{all_routes/routeWithSuperagent.d.ts → utility/playwright/routes/pwRoute.d.ts}

@@ -5,9 +5,9 @@ import { Browser, BrowserContext, Page } from "playwright";
 // ============================================================================
 
 /**
- * Options for the gotRoute function.
+ * Options for the pwRoute function.
  */
-export interface GotRouteOptions {
+export interface PwRouteOptions {
 	/** Playwright Context (provide either context or page) */
 	context?: BrowserContext | null;
 
@@ -57,11 +57,11 @@ export interface GotRouteOptions {
 /**
  * Sets up request interception, caching, and ad-blocking on a Playwright page or context.
  */
-export function gotRoute(options: GotRouteOptions): Promise<void>;
+export function pwRoute(options: PwRouteOptions): Promise<void>;
 
 /**
  * Starts logging cache statistics to the console at a set interval.
  * @param log_cache Optional NodeCache instance (uses global by default)
  * @param interval Interval in seconds (default: 10)
  */
-export function showCacheLogs(log_cache?: any, interval?: number): void;
+export function pwCacheLogs(log_cache?: any, interval?: number): void;

package/src/{all_routes/routeWithSuperagent.js → utility/playwright/routes/pwRoute.js}

@@ -20,7 +20,7 @@ const globalCache = new NodeCache({
  * @param {Object} log_cache - The cache instance to monitor
  * @param {number} interval - The interval in seconds between log outputs
  */
-export function showCacheLogs(log_cache = globalCache, interval = 10) {
+export function pwCacheLogs(log_cache = globalCache, interval = 10) {
 	if (interval > 0) {
 		setInterval(() => {
 			const stats = log_cache.stats;
@@ -109,7 +109,7 @@ async function fetchWithClient(useCache, url, requestHeaders, method, useFullUrl
  * @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.
  */
-export async function gotRoute({
+export async function pwRoute({
 	context = null,
 	page = null,
 	successLogs = false,

package/src/utility/proxy-utility/proxy-chain.js

@@ -217,9 +217,10 @@ export async function startProxyServer({
 		fetchProxyDetails(upstreamProxies.p2, ip2LocationKey),
 	]);
 
-	// Warn only if proxy was configured (URL exists) but details came back null (Connection failed)
-	if (upstreamProxies.p1 && !p1Details) console.warn("░░ Warning: PROXY_1 configured but unreachable.");
-	if (upstreamProxies.p2 && !p2Details) console.warn("░░ Warning: PROXY_2 configured but unreachable.");
+	// Throw error if proxy was configured (URL exists) but details came back null (Connection failed)
+	if (upstreamProxies.default && !defaultDetails) throw new Error("DEFAULT_PROXY configured but unreachable.");
+	if (upstreamProxies.p1 && !p1Details) throw new Error("PROXY_1 configured but unreachable.");
+	if (upstreamProxies.p2 && !p2Details) throw new Error("PROXY_2 configured but unreachable.");
 
 	// 5. Stats
 	const stats = {
@@ -239,6 +240,9 @@ export async function startProxyServer({
 	const connectionMap = {}; // Maps connectionId -> { type: "..." }
 	let serverRunning = false;
 
+	// Track all open sockets so we can force-destroy them on close
+	const activeSockets = new Set();
+
 	// 6. Server
 	const server = new ProxyChain.Server({
 		port: selectedPort,
@@ -327,6 +331,23 @@ export async function startProxyServer({
 	try {
 		await server.listen();
 		serverRunning = true;
+
+		// Track sockets so closeServer() can destroy them all
+		server.server.on('connection', (socket) => {
+			activeSockets.add(socket);
+			socket.once('close', () => activeSockets.delete(socket));
+
+			// Intercept pipe to catch the upstream target sockets created by proxy-chain
+			const originalPipe = socket.pipe;
+			socket.pipe = function(destination, options) {
+				if (destination && typeof destination.destroy === 'function') {
+					activeSockets.add(destination);
+					destination.once('close', () => activeSockets.delete(destination));
+				}
+				return originalPipe.apply(this, arguments);
+			};
+		});
+
 		console.log(`░░ Local Proxy Started: http://127.0.0.1:${selectedPort}`);
 	} catch (err) {
 		console.error("░░ Failed to start proxy server:", err);
@@ -397,6 +418,12 @@ export async function startProxyServer({
 			await server.close(true);
 			serverRunning = false;
 
+			// Force-destroy any lingering sockets so Node can exit
+			for (const socket of activeSockets) {
+				socket.destroy();
+			}
+			activeSockets.clear();
+
 			// Auto console.log stats on close
 			if (proxy_stats) {
 				console.log("░░ Proxy Stats:", getProxyStatsFormatted());

package/src/utility/proxy-utility/proxy-helper.js

@@ -1,6 +1,6 @@
 import { setTimeout as sleep } from "timers/promises";
 import randomstring from "randomstring";
-import { getMultiloginToken } from "../multilogin_token_manager.js";
+import { getMultiloginToken } from "../mlx_token.js";
 import { getActiveProxyWithStartStop as fetchAwsProxy } from "./custom-proxy.js";
 import { arn, query } from "arn-knexjs";
 

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

@@ -0,0 +1,199 @@
+import { Browser, Page } from "puppeteer-core";
+import type { ProxyConfig } from "../pwLaunch";
+
+/**
+ * Configuration options specific to Multilogin (Puppeteer CDP).
+ */
+export interface PpMultiloginOptions {
+	/**
+	 * Multilogin Profile ID. If provided, launches an existing profile.
+	 */
+	profileId?: string | null;
+
+	/**
+	 * OS Type for Multilogin profile creation.
+	 * Default: detected OS
+	 */
+	os_type?: "windows" | "macos" | "linux" | "android";
+
+	/**
+	 * Multilogin flag: Canvas noise masking.
+	 * Default: true
+	 */
+	canvas_noise?: boolean;
+
+	/**
+	 * Multilogin flag: Media devices masking.
+	 * Default: true
+	 */
+	media_masking?: boolean;
+
+	/**
+	 * Multilogin flag: Audio masking.
+	 * Default: true
+	 */
+	audio_masking?: boolean;
+}
+
+/**
+ * Options for launching a browser via Puppeteer CDP.
+ */
+export interface PpLaunchOptions {
+	// ========================================================================
+	// 1. BROWSER SELECTION
+	// ========================================================================
+
+	/**
+	 * Which browser to launch.
+	 *
+	 * - `"chrome"`: Chromium browser (locally installed)
+	 * - `"chromium"`: Alias for Chrome
+	 * - `"brave"`: Brave Browser (requires local binary)
+	 * - `"multilogin"`: Multilogin anti-detect browser (via API)
+	 *
+	 * Default: `"chrome"`
+	 */
+	which_browser?: "chrome" | "chromium" | "brave" | "multilogin";
+
+	// ========================================================================
+	// 2. STORAGE & PROFILES
+	// ========================================================================
+
+	/**
+	 * Path to a persistent profile.
+	 * - If absolute path: Uses that path exactly (no prefix added).
+	 * - If folder name: Creates inside `~/.arn-browser/pp/persistent/` with a browser prefix (e.g., `brave_myProfile`).
+	 * - If null: Creates a temporary, random profile in `~/.arn-browser/pp/temp/`.
+	 */
+	profile_path?: string | null;
+
+	/**
+	 * Auto-cleanup profiles after X minutes since last launch.
+	 *
+	 * **Persistent profiles:** Cleaned after X minutes since last launch. Default: 0 (never clean).
+	 * **Temp profiles:** Default: 15 minutes if not specified.
+	 *
+	 * Default: 0
+	 */
+	cleanupMinutes?: number;
+
+	// ========================================================================
+	// 3. NETWORK
+	// ========================================================================
+
+	/**
+	 * Proxy settings (URL string or config object).
+	 * Passed as `--proxy-server` flag to the browser.
+	 */
+	proxy?: ProxyConfig | string | null;
+
+	// ========================================================================
+	// 4. BROWSER ARGS
+	// ========================================================================
+
+	/**
+	 * Additional CLI arguments to pass to the browser process.
+	 * These are appended after the default args.
+	 *
+	 * @example ["--disable-gpu", "--window-size=1920,1080"]
+	 */
+	extraArgs?: string[];
+
+	// ========================================================================
+	// 5. ENGINE SPECIFIC
+	// ========================================================================
+
+	/**
+	 * Options specific to the Multilogin engine.
+	 */
+	multilogin_options?: PpMultiloginOptions;
+
+	// ========================================================================
+	// 6. FINGERPRINT SPOOFING
+	// ========================================================================
+
+	/**
+	 * Configuration for browser fingerprint spoofing (per-page via fingerprint-injector).
+	 *
+	 * - `false`: No fingerprint spoofing (default)
+	 * - `true`: Spoof fingerprint with default screen dimensions
+	 * - `{ minWidth?, maxWidth?, minHeight?, maxHeight? }`: Spoof fingerprint with screen constraints
+	 *
+	 * Default: false
+	 */
+	spoof_fingerprint?: boolean | {
+		minWidth?: number;
+		maxWidth?: number;
+		minHeight?: number;
+		maxHeight?: number;
+	};
+
+	// ========================================================================
+	// 7. LOGGING
+	// ========================================================================
+
+	/**
+	 * Enable launch-related console logs.
+	 * Default: false
+	 */
+	launch_logs?: boolean;
+
+	/**
+	 * Enable cleanup-related console logs.
+	 * Default: false
+	 */
+	cleanup_logs?: boolean;
+}
+
+/**
+ * Successful Puppeteer browser launch result.
+ * When launchError is null, browser/context/page are guaranteed to be valid.
+ */
+export interface PpBrowserControllerSuccess {
+	/** The Puppeteer Browser instance. */
+	browser: Browser;
+	/** The browser instance (alias for browser in Puppeteer, since there's no separate BrowserContext). */
+	context: Browser;
+	/** The initial Page object. */
+	page: Page;
+	/** Returns true if the browser is still connected. */
+	isBrowserRunning: () => boolean;
+	/** Safely closes the browser, kills the process, and cleans up temporary directories. */
+	closeBrowser: () => Promise<boolean>;
+	/** No error occurred during launch. */
+	launchError: null;
+}
+
+/**
+ * Failed Puppeteer browser launch result.
+ * When launchError is set, browser/context/page are null.
+ */
+export interface PpBrowserControllerError {
+	/** Null on launch failure. */
+	browser: null;
+	/** Null on launch failure. */
+	context: null;
+	/** Null on launch failure. */
+	page: null;
+	/** Returns false since the browser failed to launch. */
+	isBrowserRunning: () => boolean;
+	/** No-op cleanup function. */
+	closeBrowser: () => Promise<boolean>;
+	/** The error that occurred during launch. */
+	launchError: Error;
+}
+
+/**
+ * The object returned by launchPuppeteer.
+ * Check launchError to discriminate between success and failure states.
+ */
+export type PpBrowserController = PpBrowserControllerSuccess | PpBrowserControllerError;
+
+/**
+ * Launches a browser via Puppeteer CDP based on the provided options.
+ * Spawns the browser process, connects via Chrome DevTools Protocol.
+ *
+ * Supported browsers: Chrome, Brave, Multilogin.
+ * Profile directory: ~/.arn-browser/pp/
+ */
+export function ppLaunch(options?: PpLaunchOptions): Promise<PpBrowserController>;