arn-browser 0.0.3 → 0.0.4

package/src/utility/multilogin_token_manager.js

@@ -0,0 +1,186 @@
+// multilogin_token_manager.js
+
+import crypto from "crypto";
+import path from "path";
+import { pathToFileURL } from "url";
+import fs from "fs";
+
+let config = null;
+
+/**
+ * Dynamically loads 'browser_automation_env.js' from the user's project root.
+ */
+async function loadUserConfig() {
+	if (config) return config;
+
+	try {
+		const projectRoot = process.cwd();
+		const envPath = path.join(projectRoot, "utility", "browser_automation_env.js");
+
+		// Check if file exists before trying to import (cleaner error handling)
+		if (!fs.existsSync(envPath)) {
+			throw new Error(`Could not find configuration file at: ${envPath}`);
+		}
+
+		// Import dynamically
+		const envUrl = pathToFileURL(envPath).href;
+		const userEnv = await import(envUrl);
+
+		// Validate required fields
+		const requiredKeys = [
+			"arn",
+			"query",
+			"MULTILOGIN_EMAIL",
+			"MULTILOGIN_PASSWORD",
+			"MULTILOGIN_WORKSPACE_ID",
+			"ROW_ID",
+		];
+
+		const missing = requiredKeys.filter((key) => !userEnv[key]);
+
+		if (missing.length > 0) {
+			throw new Error(`[TokenManager] 'browser_automation_env.js' is missing exports: ${missing.join(", ")}`);
+		}
+
+		config = userEnv;
+		return config;
+	} catch (error) {
+		console.error("❌ Config Error:", error.message);
+		throw error;
+	}
+}
+
+async function saveTokens(tokens) {
+	const { arn, query, ROW_ID } = await loadUserConfig();
+
+	await arn.single(
+		query("api_multilogin_token")
+			.update({
+				data: JSON.stringify(tokens, null, 2),
+			})
+			.where({ id: ROW_ID })
+	);
+}
+
+async function loadTokens() {
+	try {
+		const { arn, query, ROW_ID } = await loadUserConfig();
+
+		const { data: [data] = [], error } = await arn.single(
+			query("api_multilogin_token").select("*").where({ id: ROW_ID }).limit(1)
+		);
+		if (error) {
+			console.error("Error loading tokens:", error);
+			return null;
+		}
+		if (!data || !data.data) {
+			return null;
+		}
+		return data.data;
+	} catch (err) {
+		return null;
+	}
+}
+
+function isJwtExpired(token) {
+	if (!token) return true;
+	try {
+		const [, payloadB64] = token.split(".");
+		const payload = JSON.parse(Buffer.from(payloadB64, "base64").toString());
+		return payload.exp * 1000 < Date.now() + 5 * 60 * 1000;
+	} catch (e) {
+		return true;
+	}
+}
+
+async function loginAndSaveTokens() {
+	// Destructure using the NEW names
+	const { MULTILOGIN_EMAIL, MULTILOGIN_PASSWORD, MULTILOGIN_WORKSPACE_ID } = await loadUserConfig();
+
+	const passwordHash = crypto.createHash("md5").update(MULTILOGIN_PASSWORD).digest("hex");
+	const data = {
+		email: MULTILOGIN_EMAIL,
+		password: passwordHash,
+	};
+
+	const res = await fetch("https://api.multilogin.com/user/signin", {
+		method: "POST",
+		headers: { "Content-Type": "application/json", Accept: "application/json" },
+		body: JSON.stringify(data),
+	});
+
+	if (!res.ok) {
+		const errData = await res.text();
+		throw new Error(`[LOGIN] HTTP ${res.status}: ${errData}`);
+	}
+
+	const json = await res.json();
+	const { token, refresh_token } = json.data;
+
+	await saveTokens({
+		token,
+		refresh_token,
+		email: MULTILOGIN_EMAIL,
+		workspace_id: MULTILOGIN_WORKSPACE_ID,
+	});
+
+	console.log("[LOGIN] Tokens updated and saved.");
+	return { token, refresh_token };
+}
+
+async function refreshAndSaveTokens(refresh_token) {
+	const { MULTILOGIN_EMAIL, MULTILOGIN_WORKSPACE_ID } = await loadUserConfig();
+
+	const data = {
+		email: MULTILOGIN_EMAIL,
+		refresh_token: refresh_token,
+		workspace_id: MULTILOGIN_WORKSPACE_ID,
+	};
+
+	const res = await fetch("https://api.multilogin.com/user/refresh_token", {
+		method: "POST",
+		headers: { "Content-Type": "application/json", Accept: "application/json" },
+		body: JSON.stringify(data),
+	});
+
+	if (!res.ok) {
+		const errData = await res.text();
+		throw new Error(`[REFRESH] HTTP ${res.status}: ${errData}`);
+	}
+
+	const json = await res.json();
+	const { token, refresh_token: new_refresh } = json.data;
+
+	await saveTokens({
+		token,
+		refresh_token: new_refresh,
+		email: MULTILOGIN_EMAIL,
+		workspace_id: MULTILOGIN_WORKSPACE_ID,
+	});
+
+	console.log("[REFRESH] Tokens refreshed and saved.");
+	return { token, refresh_token: new_refresh };
+}
+
+async function getMultiloginToken() {
+	await loadUserConfig();
+	let tokens = await loadTokens();
+
+	if (tokens && tokens.token && !isJwtExpired(tokens.token)) {
+		return tokens.token;
+	}
+
+	if (tokens && tokens.refresh_token) {
+		try {
+			const { token } = await refreshAndSaveTokens(tokens.refresh_token);
+			return token;
+		} catch (err) {
+			console.warn("[REFRESH FAILED] Will login again:", err.message);
+		}
+	}
+
+	const { token } = await loginAndSaveTokens();
+	return token;
+}
+
+export { getMultiloginToken };

package/src/utility/playwright-helper.d.ts

@@ -0,0 +1,61 @@
+import { Page, Locator } from "playwright";
+
+/**
+ * Options for the retryNavigation function.
+ */
+export interface RetryNavigationOptions {
+	/** The Playwright Page object. */
+	page: Page;
+	/** The target URL to navigate to. */
+	url: string;
+	/** Maximum number of retry attempts. Default: 5 */
+	maxRetries?: number;
+	/** Custom Referer header. Default: null */
+	referer?: string | null;
+	/** Base timeout in milliseconds. Default: 30000 */
+	timeout?: number;
+	/** When to consider operation succeeded. Default: "load" */
+	waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+}
+
+/**
+ * Options for the retryClick function.
+ */
+export interface RetryClickOptions {
+	/** The Playwright Locator to click. */
+	locator: Locator;
+	/** Maximum number of retry attempts. Default: 3 */
+	maxRetries?: number;
+	/** Timeout for waiting for element visibility/invisibility. Default: 15000 */
+	timeout?: number;
+}
+
+/**
+ * Navigates to a URL with retry logic and incremental timeouts.
+ * If navigation fails, it temporarily goes to "about:blank" before retrying.
+ * @returns True if navigation succeeded, throws error otherwise.
+ */
+export function retryNavigation(options: RetryNavigationOptions): Promise<boolean>;
+
+/**
+ * Retries clicking a locator.
+ * Warning: This function waits for the element to become HIDDEN after clicking.
+ * Use this for actions that close modals or navigate away.
+ */
+export function retryClick(options: RetryClickOptions): Promise<void>;
+
+/**
+ * Races multiple conditions (URL match or Element visibility) to see which happens first.
+ *
+ * NOTE: This function MUTATES the `checksToPerform` object by deleting the matched key.
+ *
+ * @param page - The Playwright Page object.
+ * @param checksToPerform - An object mapping keys (names) to either a URL string or a Playwright Locator.
+ * @param timeout - Maximum time to wait for a condition in milliseconds.
+ * @returns The key name of the matched condition, or null if timed out.
+ */
+export function checkPageConditions(
+	page: Page,
+	checksToPerform: Record<string, string | Locator | null>,
+	timeout: number
+): Promise<string | null>;

package/src/utility/playwright-helper.js

@@ -0,0 +1,129 @@
+/**
+ * Navigates to a URL with retry logic and incremental timeouts.
+ * If navigation fails, it temporarily goes to "about:blank" before retrying.
+ *
+ * @param {Object} options
+ * @param {import('playwright').Page} options.page - Playwright Page object
+ * @param {string} options.url - Target URL
+ * @param {number} [options.maxRetries=5] - Maximum number of attempts
+ * @param {string|null} [options.referer=null] - Referer header
+ * @param {number} [options.timeout=30000] - Base timeout in ms
+ * @param {"load"|"domcontentloaded"|"networkidle"|"commit"} [options.waitUntil="load"] - Wait condition
+ * @returns {Promise<boolean>} True if successful
+ */
+export const retryNavigation = async ({
+	page,
+	url,
+	maxRetries = 5,
+	referer = null,
+	timeout = 30000,
+	waitUntil = "load",
+}) => {
+	for (let retryCount = 0; retryCount < maxRetries; retryCount++) {
+		// Apply incremental timeout only if the initial timeout is <= 30,000
+		const currentTimeout = timeout <= 30000 ? timeout + retryCount * 15000 : timeout;
+		try {
+			if (referer) {
+				await page.goto(url, {
+					referer: referer,
+					waitUntil: waitUntil,
+					timeout: currentTimeout,
+				});
+			} else {
+				await page.goto(url, {
+					waitUntil: waitUntil,
+					timeout: currentTimeout,
+				});
+			}
+
+			return true;
+		} catch (error) {
+			console.log(`Navigation attempt ${retryCount + 1} failed.`, url);
+			await page.goto("about:blank", { waitUntil: "load", timeout: timeout });
+			if (retryCount === maxRetries - 1) {
+				console.log("All retry attempts failed");
+				throw error;
+			}
+		}
+	}
+	return false;
+};
+
+/**
+ * Retries clicking a locator.
+ * EXPECTATION: The element should disappear (become hidden) after clicking.
+ *
+ * @param {Object} options
+ * @param {import('playwright').Locator} options.locator - The element to click
+ * @param {number} [options.maxRetries=3] - Max retries
+ * @param {number} [options.timeout=15000] - Timeout for visibility checks
+ */
+export const retryClick = async ({ locator, maxRetries = 3, timeout = 15000 }) => {
+	if (!locator) throw new Error("Element locator is required");
+
+	for (let retryCount = 0; retryCount < maxRetries; retryCount++) {
+		try {
+			await locator.waitFor({ state: "visible", timeout });
+			await locator.click();
+			// Note: This logic assumes the element disappears after clicking (e.g., submit button or modal close)
+			await locator.waitFor({ state: "hidden", timeout });
+			return; // Exit the function if successful
+		} catch (error) {
+			if (retryCount === maxRetries - 1) {
+				throw error; // Throw error if all retries fail
+			}
+		}
+	}
+};
+
+/**
+ * Races multiple conditions (URL or Element) to see which happens first.
+ * Modifies the input object by deleting the matched key.
+ *
+ * @param {import('playwright').Page} page
+ * @param {Object.<string, string|import('playwright').Locator|null>} checksToPerform - Map of names to URL strings or Locators
+ * @param {number} timeout - Timeout in ms
+ * @returns {Promise<string|null>} The key of the matched condition
+ */
+export const checkPageConditions = async (page, checksToPerform, timeout) => {
+	// Validate required parameters
+	if (!page) throw new Error("Page parameter is required");
+	if (!timeout) throw new Error("Timeout parameter is required");
+
+	let matchedKey = null;
+	try {
+		const promises = Object.entries(checksToPerform)
+			.filter(([_, value]) => value !== null) // Needed when setting value null after match
+			.map(([key, value]) => {
+				if (typeof value === "string") {
+					// Handle URL check
+					return page
+						.waitForURL(value, {
+							waitUntil: "load",
+							timeout: timeout,
+						})
+						.then(() => key);
+				} else {
+					// Handle XPath/element check
+					// Assuming value is a Locator
+					return value
+						.waitFor({
+							state: "visible",
+							timeout: timeout,
+						})
+						.then(() => key);
+				}
+			});
+
+		matchedKey = await Promise.race(promises);
+		if (matchedKey) {
+			// Remove the matched key from the original object
+			delete checksToPerform[matchedKey];
+			console.log(`${matchedKey} matched!`);
+		}
+		return matchedKey; // Return the matched key if found
+	} catch (error) {
+		console.log(`No match found - ${error.message}`);
+		return null; // Return null if no match is found
+	}
+};

package/src/utility/proxy-utility/custom-proxy.d.ts

@@ -0,0 +1,93 @@
+// custom-proxy.d.ts
+
+/**
+ * Common parameter interface for functions requiring an instance name.
+ */
+export interface InstanceParams {
+	instance_name: string;
+}
+
+/**
+ * Gets the current state name of the instance (e.g., 'running', 'stopped', 'pending').
+ */
+export function getInstanceStatus(params: InstanceParams): Promise<string>;
+
+/**
+ * Gets the Public IP address currently assigned to the instance.
+ */
+export function getPublicIpAddress(params: InstanceParams): Promise<string>;
+
+/**
+ * Stops the EC2 instance.
+ * Waits for pending states to resolve before attempting to stop.
+ * @returns The Instance ID if successful, or undefined if maximum retries reached/already stopped.
+ */
+export function manageInstanceStop(params: InstanceParams): Promise<string | undefined>;
+
+/**
+ * Starts the EC2 instance.
+ * Waits for pending states to resolve before attempting to start.
+ * @returns The Instance ID if successful, or undefined if maximum retries reached/already running.
+ */
+export function manageInstanceStart(params: InstanceParams): Promise<string | undefined>;
+
+/**
+ * Associates an existing Elastic IP or allocates a new one if none exist.
+ * @returns True if successful, false on error.
+ */
+export function AssociateAddress(params: InstanceParams): Promise<boolean>;
+
+/**
+ * Disassociates the Elastic IP from the instance.
+ * @returns True if successful or not found, false on error.
+ */
+export function DisassociateAddress(params: InstanceParams): Promise<boolean>;
+
+/**
+ * Deletes (Releases) any Elastic IPs that are not currently attached to an instance.
+ * @returns True if successful, false on error.
+ */
+export function DeleteUnassociatedElasticIPs(params: InstanceParams): Promise<boolean>;
+
+/**
+ * Resets servers that haven't been updated in 25+ minutes.
+ * Stops the instance and releases IPs.
+ */
+export function resetServersAndIp(): Promise<void>;
+
+/**
+ * FLOW 1: Standard Active Proxy.
+ * Starts instance, cycles IPs by associating/disassociating until a working one is found.
+ * @returns The working Public IP string, or null if failed.
+ */
+export function getActiveProxy(params: InstanceParams): Promise<string | null>;
+
+/**
+ * FLOW 2: Hard Reset Proxy.
+ * Stops the instance completely, then starts it to get a new IP.
+ * @returns The working Public IP string, or null if failed.
+ */
+export function getActiveProxyWithStartStop(params: InstanceParams): Promise<string | null>;
+
+/**
+ * FLOW 3: Conditional Proxy.
+ * Checks if IP exists; if so, refreshes it. If not, allocates new.
+ * @returns The working Public IP string, or null if failed.
+ */
+export function getActiveProxyConditional(params: InstanceParams): Promise<string | null>;
+
+/**
+ * Checks if the proxy is functioning by attempting to reach an external endpoint.
+ * @param proxyHost - IP address of the proxy.
+ * @param proxyPort - Port of the proxy (default usually 9002).
+ * @returns The proxyHost if alive, or null if dead/timeout.
+ */
+export function isProxyAlive(proxyHost: string, proxyPort: number): Promise<string | null>;
+
+/**
+ * Helper to fetch a URL using native Node.js HTTP/HTTPS modules.
+ * @param url - The URL to fetch.
+ * @param agent - The proxy agent (optional).
+ * @param timeout - Request timeout in ms.
+ */
+export function nativeGet(url: string, agent?: any, timeout?: number): Promise<string>;