arn-browser 0.0.3 → 0.0.5

package/src/utility/deleteDirectory.js

@@ -0,0 +1,105 @@
+import fs from "fs";
+import path from "path";
+import { setTimeout as sleep } from "timers/promises";
+
+/**
+ * Deletes a directory with built-in retry logic.
+ * Useful for browser profiles where files might still be locked by the OS process.
+ * * @param {string} targetPath - The absolute path to delete.
+ * @param {number} maxRetries - How many times to retry (default: 5).
+ * @param {number} retryDelayMs - Time to wait between retries (default: 2000ms).
+ */
+export async function deleteDirectoryWithRetries(targetPath, maxRetries = 5, retryDelayMs = 2000) {
+	if (!fs.existsSync(targetPath)) {
+		return true; // Already gone
+	}
+
+	let attempt = 0;
+
+	while (attempt < maxRetries) {
+		try {
+			// Force: true allows deleting files even if read-only
+			// Recursive: true deletes inner folders
+			await fs.promises.rm(targetPath, { recursive: true, force: true });
+
+			// Double check if it's actually gone
+			if (!fs.existsSync(targetPath)) {
+				return true;
+			}
+		} catch (error) {
+			const isLastAttempt = attempt === maxRetries - 1;
+
+			// If it's the last attempt, log error
+			if (isLastAttempt) {
+				console.error(`❌ Failed to delete directory after ${maxRetries} attempts: ${targetPath}`);
+				console.error(`   Error: ${error.message}`);
+				return false;
+			}
+
+			// Log warning and wait
+			console.warn(
+				`⚠️  Delete failed (Attempt ${attempt + 1}/${maxRetries}). File might be locked. Retrying in ${
+					retryDelayMs / 1000
+				}s...`
+			);
+			await sleep(retryDelayMs);
+		}
+		attempt++;
+	}
+
+	return false;
+}
+
+/**
+ * Deletes specific contents inside a directory but keeps the parent folder.
+ * (Optional utility if you need to clear cache without removing the profile folder itself)
+ */
+export async function deleteAllItemsInDirectory(directoryPath) {
+	try {
+		if (!fs.existsSync(directoryPath)) return;
+
+		const files = await fs.promises.readdir(directoryPath);
+		for (const file of files) {
+			const curPath = path.join(directoryPath, file);
+			await deleteDirectoryWithRetries(curPath);
+		}
+	} catch (error) {
+		console.error(`Error emptying directory ${directoryPath}:`, error);
+	}
+}
+
+/**
+ * Legacy utility: Scan a directory and delete folders older than X minutes.
+ * (Note: launchBrowser.js now has its own internal version of this, but keeping this
+ * here is useful if you want to run cleanup scripts independently).
+ */
+export function deleteOldDirectories({ directoryPath, ageLimitMinutes }) {
+	if (!fs.existsSync(directoryPath)) return;
+
+	const now = Date.now();
+	const limit = ageLimitMinutes * 60 * 1000;
+
+	try {
+		const files = fs.readdirSync(directoryPath);
+
+		files.forEach((file) => {
+			const curPath = path.join(directoryPath, file);
+			try {
+				const stats = fs.statSync(curPath);
+				if (stats.isDirectory()) {
+					const age = now - stats.mtimeMs;
+					if (age > limit) {
+						console.log(`Cleaning up old directory: ${file}`);
+						// We use the sync version of retry logic or just fire-and-forget async here
+						// For simplicity in a sync loop, we often just do a force removal:
+						fs.rmSync(curPath, { recursive: true, force: true });
+					}
+				}
+			} catch (e) {
+				// Ignore access errors on specific files
+			}
+		});
+	} catch (err) {
+		console.error("Error during old directory cleanup:", err);
+	}
+}

package/src/utility/launchBrowser.d.ts

@@ -0,0 +1,248 @@
+import { Browser, BrowserContext, Page } from "playwright";
+import type { FingerprintGeneratorOptions } from "fingerprint-generator";
+import type { HumanPage, CreateCursorOptions } from "../human-cursor/index";
+type Screen = FingerprintGeneratorOptions["screen"];
+/**
+ * Proxy configuration object.
+ */
+export interface ProxyConfig {
+	type: "http" | "https" | "socks5" | "socks" | "socks4";
+	host: string;
+	port: number | string;
+	user?: string;
+	pass?: string;
+}
+
+
+/**
+ * Configuration options for human-like cursor movement.
+ * Only applicable for non-camoufox browsers (camoufox has its own humanize option).
+ */
+export interface HumanizeOptions extends CreateCursorOptions {
+	/** Enable/disable human-like cursor movement (default: true) */
+	humanize?: boolean;
+	/** Maximum movement time in seconds (default: 1.5) */
+	maxTime?: number;
+	/** Minimum movement time in seconds (default: 0.5) */
+	minTime?: number;
+	/** Auto-show cursor indicator after goto (default: true) */
+	showCursor?: boolean;
+}
+
+/**
+ * Configuration options specific to Camoufox.
+ * These are passed directly to camoufox-js.
+ */
+export interface CamoufoxOptions {
+	/** Firefox version to use. Defaults to the current Camoufox version.
+	 * To prevent leaks, only use this for special cases.
+	 */
+	ff_version?: number;
+	/** Whether to run the browser in headless mode. Defaults to `false`.
+	 */
+	headless?: boolean;
+	/**
+	 * Whether to use GeoIP to automatically detect timezone, locale, and geolocation based on IP.
+	 * If true, the proxy is passed to Camoufox internal config.
+	 * Default: false
+	 */
+	geoip?: boolean;
+
+	/**
+	 * Override the OS signature.
+	 * Can be a single OS or a list to randomly choose from.
+	 * If not provided, it defaults to the detected system OS.
+	 */
+	os?: "windows" | "macos" | "linux" | ("windows" | "macos" | "linux")[];
+
+	/** Whether to block all images. */
+	block_images?: boolean;
+
+	/** Whether to block WebRTC entirely. */
+	block_webrtc?: boolean;
+
+	/** Humanize the cursor movement.
+	 * Takes either `true`, or the MAX duration in seconds of the cursor movement.
+	 * The cursor typically takes up to 1.5 seconds to move across the window.
+	 */
+	humanize?: boolean | number;
+
+	/** Constrains the screen dimensions of the generated fingerprint. */
+	screen?: Screen;
+
+	/**
+	 * Allow arbitrary additional options supported by camoufox-js.
+	 */
+	[key: string]: any;
+}
+
+/**
+ * Configuration options specific to Multilogin.
+ */
+export interface MultiloginOptions {
+	/**
+	 * 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;
+
+	/**
+	 * Multilogin flag: Custom screen resolution.
+	 * Default: false
+	 */
+	custom_screen?: boolean;
+}
+
+/**
+ * Options for launching the browser.
+ */
+export interface LaunchOptions {
+	// ========================================================================
+	// 1. GENERAL & NETWORK
+	// ========================================================================
+
+	/**
+	 * Timezone ID (e.g., "America/New_York").
+	 * Ignored if `camoufox_options.geoip` is true.
+	 */
+	timezoneId?: string | null;
+
+	/**
+	 * Proxy settings (object or string).
+	 */
+	proxy?: ProxyConfig | string;
+
+	// ========================================================================
+	// 2. BROWSER SELECTION
+	// ========================================================================
+
+	/**
+	 * Which browser engine to launch.
+	 * Default: "chromium"
+	 */
+	which_browser?: "chromium" | "chrome" | "firefox" | "brave" | "braveLauncher" | "camoufox" | "multilogin";
+
+	// ========================================================================
+	// 3. STORAGE & PROFILES
+	// ========================================================================
+
+	/**
+	 * Path to a persistent profile.
+	 * - If absolute path: Uses that path exactly (no prefix added).
+	 * - If folder name: Creates inside `.data/browser_profiles/persistent/` AND adds a browser prefix (e.g., `brave_myProfile`).
+	 * - If null: Creates a temporary, random profile in `.data/browser_profiles/temp/`.
+	 */
+	profile_path?: string | null;
+
+	/**
+	 * If set to > 10, deletes temporary profiles older than X minutes.
+	 * Default: 0 (disabled)
+	 */
+	cleanupMinutes?: number;
+
+	// ========================================================================
+	// 4. STANDARD FINGERPRINTING (Chromium, Firefox, Brave, Camoufox)
+	// ========================================================================
+
+	/**
+	 * Whether to load the CapSolver extension (Chromium/Brave only).
+	 * Default: false
+	 */
+	CapSolver?: boolean;
+
+	/**
+	 * Maximum width constraint for fingerprint generation.
+	 * - If <= 10: Treated as multiplier of detected screen width (e.g. 1 = 100%, 0.8 = 80%).
+	 * - If > 10: Treated as specific pixel width.
+	 * Default: 1 (100% of detected screen width or 1920px fallback)
+	 */
+	maxWidth?: number;
+
+	// ========================================================================
+	// 5. ENGINE SPECIFIC GROUPS
+	// ========================================================================
+
+	/**
+	 * Options specific to the Camoufox engine.
+	 */
+	camoufox_options?: CamoufoxOptions;
+
+	/**
+	 * Options specific to the Multilogin engine.
+	 */
+	multilogin_options?: MultiloginOptions;
+
+	/**
+	 * Options for human-like cursor movement.
+	 * ENABLED BY DEFAULT for non-camoufox browsers!
+	 * To disable: set { humanize: false }
+	 * Camoufox uses its own humanize option in camoufox_options.
+	 */
+	humanize_options?: HumanizeOptions;
+}
+
+/**
+ * The object returned by launchBrowser.
+ */
+export interface BrowserController {
+	/**
+	 * The Playwright Browser or BrowserContext instance.
+	 * Note: Multilogin and Persistent profiles return a BrowserContext here.
+	 */
+	browser: Browser | BrowserContext | null;
+
+	/**
+	 * The active BrowserContext.
+	 */
+	context: BrowserContext | null;
+
+	/**
+	 * The initial Page object.
+	 * When humanize_options is provided, this will be a HumanPage with human-like cursor methods.
+	 * All standard Playwright Page methods are available.
+	 */
+	page: Page | HumanPage | null;
+
+	/**
+	 * Checks if the browser context is currently active.
+	 */
+	isBrowserRunning: () => boolean;
+
+	/**
+	 * Safely closes the browser and cleans up temporary directories if applicable.
+	 */
+	closeBrowser: () => Promise<boolean>;
+
+	/**
+	 * Captures any error that occurred during launch.
+	 */
+	launchError: Error | null;
+}
+
+/**
+ * Launches a browser based on the provided options.
+ */
+export function launchBrowser(options: LaunchOptions): Promise<BrowserController>;