cloakbrowser 0.2.0 → 0.2.2

package/README.md

@@ -75,7 +75,19 @@ const browser = await launch({
   args: ['--window-size=1920,1080'],
 });
 
-// Browser + context in one call
+// With timezone and locale (sets --timezone and --lang binary flags)
+const browser = await launch({
+  timezone: 'America/New_York',
+  locale: 'en-US',
+});
+
+// Auto-detect timezone/locale from proxy IP (requires: npm install mmdb-lib)
+const browser = await launch({
+  proxy: 'http://proxy:8080',
+  geoip: true,
+});
+
+// Browser + context in one call (timezone/locale set both binary flags AND context)
 const context = await launchContext({
   userAgent: 'Custom UA',
   viewport: { width: 1920, height: 1080 },
@@ -84,6 +96,27 @@ const context = await launchContext({
 });
 ```
 
+### Auto Timezone/Locale from Proxy IP
+
+When using a proxy, antibot systems check that your browser's timezone and locale match the proxy's location. Install `mmdb-lib` to enable auto-detection from an offline GeoIP database (~70 MB, downloaded on first use):
+
+```bash
+npm install mmdb-lib
+```
+
+```javascript
+// Auto-detect — timezone and locale set from proxy's IP geolocation
+const browser = await launch({ proxy: 'http://proxy:8080', geoip: true });
+
+// Works with launchContext too
+const context = await launchContext({ proxy: 'http://proxy:8080', geoip: true });
+
+// Explicit values always win over auto-detection
+const browser = await launch({ proxy: 'http://proxy:8080', geoip: true, timezone: 'Europe/London' });
+```
+
+> **Note:** For rotating residential proxies, the DNS-resolved IP may differ from the exit IP. Pass explicit `timezone`/`locale` in those cases.
+
 ### Utilities
 
 ```javascript
@@ -151,6 +184,28 @@ const page = await browser.newPage();
 - Node.js >= 18
 - One of: `playwright-core` >= 1.40 or `puppeteer-core` >= 21
 
+## Troubleshooting
+
+**reCAPTCHA v3 scores are low (0.1–0.3)**
+
+Avoid `page.waitForTimeout()` — it sends CDP protocol commands that reCAPTCHA detects. Use native sleep instead:
+
+```javascript
+// Bad — sends CDP commands, reCAPTCHA detects this
+await page.waitForTimeout(3000);
+
+// Good — invisible to the browser
+await new Promise(r => setTimeout(r, 3000));
+```
+
+Other tips for maximizing reCAPTCHA scores:
+- **Use Playwright, not Puppeteer** — Puppeteer sends more CDP protocol traffic that reCAPTCHA detects ([details](#puppeteer))
+- **Use residential proxies** — datacenter IPs are flagged by IP reputation, not browser fingerprint
+- **Spend 15+ seconds on the page** before triggering reCAPTCHA — short visits score lower
+- **Space out requests** — back-to-back `grecaptcha.execute()` calls from the same session get penalized. Wait 30+ seconds between pages with reCAPTCHA
+- **Use a fixed fingerprint seed** (`--fingerprint=12345`) for consistent device identity across sessions
+- **Minimize `page.evaluate()` calls** before the reCAPTCHA check fires — each one sends CDP traffic
+
 ## Links
 
 - 🌐 [Website](https://cloakbrowser.dev)

package/dist/geoip.d.ts

@@ -0,0 +1,24 @@
+/**
+ * GeoIP-based timezone and locale detection from proxy IP.
+ *
+ * Optional feature — requires `mmdb-lib` package:
+ *   npm install mmdb-lib
+ *
+ * Downloads GeoLite2-City.mmdb (~70 MB) on first use,
+ * caches in `~/.cloakbrowser/geoip/`.
+ */
+/** Country ISO code → BCP 47 locale (covers ~90% of proxy traffic). */
+export declare const COUNTRY_LOCALE_MAP: Record<string, string>;
+export interface GeoResult {
+    timezone: string | null;
+    locale: string | null;
+}
+/**
+ * Resolve timezone and locale from a proxy's IP address.
+ * Returns `{ timezone, locale }` — either may be null on failure.
+ * Never throws.
+ */
+export declare function resolveProxyGeo(proxyUrl: string): Promise<GeoResult>;
+/** @internal Exported for testing. */
+export declare function resolveProxyIp(proxyUrl: string): Promise<string | null>;
+//# sourceMappingURL=geoip.d.ts.map

package/dist/geoip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geoip.d.ts","sourceRoot":"","sources":["../src/geoip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAerD,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,CAAC,CA+BpB;AAMD,sCAAsC;AACtC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAexB"}

package/dist/geoip.js

@@ -0,0 +1,233 @@
+/**
+ * GeoIP-based timezone and locale detection from proxy IP.
+ *
+ * Optional feature — requires `mmdb-lib` package:
+ *   npm install mmdb-lib
+ *
+ * Downloads GeoLite2-City.mmdb (~70 MB) on first use,
+ * caches in `~/.cloakbrowser/geoip/`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createWriteStream } from "node:fs";
+import dns from "node:dns/promises";
+import net from "node:net";
+import { getCacheDir } from "./config.js";
+// P3TERX mirror of MaxMind GeoLite2-City — no license key needed
+const GEOIP_DB_URL = "https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-City.mmdb";
+const GEOIP_DB_FILENAME = "GeoLite2-City.mmdb";
+const GEOIP_UPDATE_INTERVAL_MS = 30 * 86_400_000; // 30 days
+/** Country ISO code → BCP 47 locale (covers ~90% of proxy traffic). */
+export const COUNTRY_LOCALE_MAP = {
+    US: "en-US", GB: "en-GB", AU: "en-AU", CA: "en-CA", NZ: "en-NZ",
+    IE: "en-IE", ZA: "en-ZA", SG: "en-SG",
+    DE: "de-DE", AT: "de-AT", CH: "de-CH",
+    FR: "fr-FR", BE: "fr-BE",
+    ES: "es-ES", MX: "es-MX", AR: "es-AR", CO: "es-CO", CL: "es-CL",
+    BR: "pt-BR", PT: "pt-PT",
+    IT: "it-IT", NL: "nl-NL",
+    JP: "ja-JP", KR: "ko-KR", CN: "zh-CN", TW: "zh-TW", HK: "zh-HK",
+    RU: "ru-RU", UA: "uk-UA", PL: "pl-PL", CZ: "cs-CZ", RO: "ro-RO",
+    IL: "he-IL", TR: "tr-TR", SA: "ar-SA", AE: "ar-AE", EG: "ar-EG",
+    IN: "hi-IN", ID: "id-ID", PH: "en-PH",
+    TH: "th-TH", VN: "vi-VN", MY: "ms-MY",
+    SE: "sv-SE", NO: "nb-NO", DK: "da-DK", FI: "fi-FI",
+    GR: "el-GR", HU: "hu-HU", BG: "bg-BG",
+};
+/**
+ * Resolve timezone and locale from a proxy's IP address.
+ * Returns `{ timezone, locale }` — either may be null on failure.
+ * Never throws.
+ */
+export async function resolveProxyGeo(proxyUrl) {
+    let Reader;
+    try {
+        const mmdb = await import("mmdb-lib");
+        Reader = mmdb.default?.Reader ?? mmdb.Reader;
+    }
+    catch {
+        throw new Error("mmdb-lib is required for geoip: true. Install it with:\n  npm install mmdb-lib");
+    }
+    const dbPath = await ensureGeoipDb();
+    if (!dbPath)
+        return { timezone: null, locale: null };
+    // Exit IP (through proxy) is most accurate — gateway DNS may differ from exit
+    let ip = await resolveExitIp(proxyUrl);
+    if (!ip)
+        ip = await resolveProxyIp(proxyUrl);
+    if (!ip)
+        return { timezone: null, locale: null };
+    try {
+        const buf = fs.readFileSync(dbPath);
+        const reader = new Reader(buf);
+        const result = reader.get(ip);
+        const timezone = result?.location?.time_zone ?? null;
+        const countryCode = result?.country?.iso_code ?? null;
+        const locale = countryCode ? (COUNTRY_LOCALE_MAP[countryCode] ?? null) : null;
+        return { timezone, locale };
+    }
+    catch {
+        return { timezone: null, locale: null };
+    }
+}
+// ---------------------------------------------------------------------------
+// Proxy IP resolution
+// ---------------------------------------------------------------------------
+/** @internal Exported for testing. */
+export async function resolveProxyIp(proxyUrl) {
+    try {
+        const url = new URL(proxyUrl);
+        const hostname = url.hostname;
+        if (!hostname)
+            return null;
+        // Already a literal IP?
+        if (net.isIP(hostname))
+            return hostname;
+        // DNS resolve
+        const { address } = await dns.lookup(hostname);
+        return address;
+    }
+    catch {
+        return null;
+    }
+}
+function isPrivateIp(ip) {
+    // Quick check for common private ranges
+    if (ip.startsWith("10.") || ip.startsWith("127.") || ip === "::1")
+        return true;
+    if (ip.startsWith("172.")) {
+        const second = parseInt(ip.split(".")[1], 10);
+        if (second >= 16 && second <= 31)
+            return true;
+    }
+    if (ip.startsWith("192.168."))
+        return true;
+    return false;
+}
+const IP_ECHO_URLS = [
+    "https://api.ipify.org",
+    "https://checkip.amazonaws.com",
+    "https://ifconfig.me/ip",
+];
+async function resolveExitIp(proxyUrl) {
+    // Node.js fetch doesn't support proxy natively — use a CONNECT tunnel via http
+    // For simplicity, use a direct HTTP request to a plain-text IP echo service
+    // through the proxy using Node's http module
+    try {
+        const { default: http } = await import("node:http");
+        const { default: https } = await import("node:https");
+        const proxyUrlObj = new URL(proxyUrl);
+        for (const echoUrl of IP_ECHO_URLS) {
+            try {
+                const ip = await new Promise((resolve, reject) => {
+                    const targetUrl = new URL(echoUrl);
+                    const connectReq = http.request({
+                        host: proxyUrlObj.hostname,
+                        port: parseInt(proxyUrlObj.port || "80", 10),
+                        method: "CONNECT",
+                        path: `${targetUrl.hostname}:443`,
+                        headers: proxyUrlObj.username
+                            ? {
+                                "Proxy-Authorization": "Basic " +
+                                    Buffer.from(`${decodeURIComponent(proxyUrlObj.username)}:${decodeURIComponent(proxyUrlObj.password || "")}`).toString("base64"),
+                            }
+                            : {},
+                        timeout: 10_000,
+                    });
+                    connectReq.on("connect", (_res, socket) => {
+                        const req = https.request(echoUrl, { socket, timeout: 5_000 }, (res) => {
+                            let data = "";
+                            res.on("data", (chunk) => (data += chunk.toString()));
+                            res.on("end", () => {
+                                const ip = data.trim();
+                                resolve(net.isIP(ip) ? ip : null);
+                            });
+                        });
+                        req.on("error", () => resolve(null));
+                        req.end();
+                    });
+                    connectReq.on("error", () => resolve(null));
+                    connectReq.on("timeout", () => {
+                        connectReq.destroy();
+                        resolve(null);
+                    });
+                    connectReq.end();
+                });
+                if (ip)
+                    return ip;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        // Fallback: couldn't import http modules
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// GeoIP database management
+// ---------------------------------------------------------------------------
+function getGeoipDir() {
+    return path.join(getCacheDir(), "geoip");
+}
+async function ensureGeoipDb() {
+    const dir = getGeoipDir();
+    const dbPath = path.join(dir, GEOIP_DB_FILENAME);
+    if (fs.existsSync(dbPath)) {
+        maybeTriggerUpdate(dbPath);
+        return dbPath;
+    }
+    try {
+        await downloadGeoipDb(dbPath);
+        return dbPath;
+    }
+    catch {
+        return null;
+    }
+}
+async function downloadGeoipDb(dest) {
+    const dir = path.dirname(dest);
+    fs.mkdirSync(dir, { recursive: true });
+    console.log("[cloakbrowser] Downloading GeoIP database (~70 MB)…");
+    const tmpPath = `${dest}.tmp.${Date.now()}`;
+    try {
+        const response = await fetch(GEOIP_DB_URL, { redirect: "follow" });
+        if (!response.ok || !response.body) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        const fileStream = createWriteStream(tmpPath);
+        const reader = response.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            fileStream.write(value);
+        }
+        await new Promise((resolve, reject) => {
+            fileStream.end(() => resolve());
+            fileStream.on("error", reject);
+        });
+        fs.renameSync(tmpPath, dest);
+        console.log(`[cloakbrowser] GeoIP database ready: ${dest}`);
+    }
+    catch (err) {
+        if (fs.existsSync(tmpPath))
+            fs.unlinkSync(tmpPath);
+        throw err;
+    }
+}
+function maybeTriggerUpdate(dbPath) {
+    try {
+        const age = Date.now() - fs.statSync(dbPath).mtimeMs;
+        if (age < GEOIP_UPDATE_INTERVAL_MS)
+            return;
+    }
+    catch {
+        return;
+    }
+    // Fire-and-forget background update
+    downloadGeoipDb(dbPath).catch(() => { });
+}
+//# sourceMappingURL=geoip.js.map

package/dist/geoip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geoip.js","sourceRoot":"","sources":["../src/geoip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,GAAG,MAAM,mBAAmB,CAAC;AACpC,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,iEAAiE;AACjE,MAAM,YAAY,GAChB,wEAAwE,CAAC;AAC3E,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAC/C,MAAM,wBAAwB,GAAG,EAAE,GAAG,UAAU,CAAC,CAAC,UAAU;AAE5D,uEAAuE;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IAC/D,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IACrC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IACrC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IACxB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IAC/D,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IACxB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IACxB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IAC/D,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IAC/D,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IAC/D,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IACrC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IACrC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;IAClD,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO;CACtC,CAAC;AAOF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB;IAEhB,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACtC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,gFAAgF,CACjF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;IACrC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAErD,8EAA8E;IAC9E,IAAI,EAAE,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,EAAE;QAAE,EAAE,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAEjD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAQ,CAAC;QACrC,MAAM,QAAQ,GAAkB,MAAM,EAAE,QAAQ,EAAE,SAAS,IAAI,IAAI,CAAC;QACpE,MAAM,WAAW,GAAkB,MAAM,EAAE,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC;QACrE,MAAM,MAAM,GACV,WAAW,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC1C,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,sCAAsC;AACtC,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAAgB;IAEhB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAE3B,wBAAwB;QACxB,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAC;QAExC,cAAc;QACd,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/C,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,EAAU;IAC7B,wCAAwC;IACxC,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC/E,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9C,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,IAAI,EAAE;YAAE,OAAO,IAAI,CAAC;IAChD,CAAC;IACD,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,YAAY,GAAG;IACnB,uBAAuB;IACvB,+BAA+B;IAC/B,wBAAwB;CACzB,CAAC;AAEF,KAAK,UAAU,aAAa,CAAC,QAAgB;IAC3C,+EAA+E;IAC/E,4EAA4E;IAC5E,6CAA6C;IAC7C,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QACpD,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QACtD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEtC,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,MAAM,IAAI,OAAO,CAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;oBAC9D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;oBACnC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC;wBAC9B,IAAI,EAAE,WAAW,CAAC,QAAQ;wBAC1B,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;wBAC5C,MAAM,EAAE,SAAS;wBACjB,IAAI,EAAE,GAAG,SAAS,CAAC,QAAQ,MAAM;wBACjC,OAAO,EAAE,WAAW,CAAC,QAAQ;4BAC3B,CAAC,CAAC;gCACE,qBAAqB,EACnB,QAAQ;oCACR,MAAM,CAAC,IAAI,CACT,GAAG,kBAAkB,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,kBAAkB,CAAC,WAAW,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAChG,CAAC,QAAQ,CAAC,QAAQ,CAAC;6BACvB;4BACH,CAAC,CAAC,EAAE;wBACN,OAAO,EAAE,MAAM;qBAChB,CAAC,CAAC;oBAEH,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;wBACxC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CACvB,OAAO,EACP,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAS,EACjC,CAAC,GAAG,EAAE,EAAE;4BACN,IAAI,IAAI,GAAG,EAAE,CAAC;4BACd,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;4BAC9D,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;gCACjB,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;gCACvB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;4BACpC,CAAC,CAAC,CAAC;wBACL,CAAC,CACF,CAAC;wBACF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;wBACrC,GAAG,CAAC,GAAG,EAAE,CAAC;oBACZ,CAAC,CAAC,CAAC;oBAEH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;oBAC5C,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;wBAC5B,UAAU,CAAC,OAAO,EAAE,CAAC;wBACrB,OAAO,CAAC,IAAI,CAAC,CAAC;oBAChB,CAAC,CAAC,CAAC;oBACH,UAAU,CAAC,GAAG,EAAE,CAAC;gBACnB,CAAC,CAAC,CAAC;gBAEH,IAAI,EAAE;oBAAE,OAAO,EAAE,CAAC;YACpB,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E,SAAS,WAAW;IAClB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,KAAK,UAAU,aAAa;IAC1B,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAEjD,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;QAC9B,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,IAAY;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,CAAC,qDAAqD,CAAC,CAAC;IAEnE,MAAM,OAAO,GAAG,GAAG,IAAI,QAAQ,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7C,CAAC;QAED,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QAEzC,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;YAChC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,wCAAwC,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC;QACrD,IAAI,GAAG,GAAG,wBAAwB;YAAE,OAAO;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,oCAAoC;IACpC,eAAe,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAC1C,CAAC"}

package/dist/playwright.d.ts

@@ -35,4 +35,6 @@ export declare function launch(options?: LaunchOptions): Promise<Browser>;
  * ```
  */
 export declare function launchContext(options?: LaunchContextOptions): Promise<BrowserContext>;
+/** @internal Exposed for unit tests only. */
+export declare function _buildArgsForTest(options: LaunchOptions): string[];
 //# sourceMappingURL=playwright.d.ts.map

package/dist/playwright.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright.d.ts","sourceRoot":"","sources":["../src/playwright.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAKtE;;;;;;;;;;;;GAYG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgB1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,cAAc,CAAC,CAwBzB"}
+{"version":3,"file":"playwright.d.ts","sourceRoot":"","sources":["../src/playwright.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAKtE;;;;;;;;;;;;GAYG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAiB1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,cAAc,CAAC,CA0BzB;AAoBD,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,EAAE,CAElE"}

package/dist/playwright.js

@@ -21,7 +21,8 @@ import { parseProxyUrl } from "./proxy.js";
 export async function launch(options = {}) {
     const { chromium } = await import("playwright-core");
     const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
-    const args = buildArgs(options);
+    const resolved = await maybeResolveGeoip(options);
+    const args = buildArgs({ ...options, ...resolved });
     const browser = await chromium.launch({
         executablePath: binaryPath,
         headless: options.headless ?? true,
@@ -49,14 +50,16 @@ export async function launch(options = {}) {
  * ```
  */
 export async function launchContext(options = {}) {
-    const browser = await launch(options);
+    // Resolve geoip BEFORE launch() to avoid double-resolution
+    const resolved = await maybeResolveGeoip(options);
+    const browser = await launch({ ...options, ...resolved, geoip: false });
     let context;
     try {
         context = await browser.newContext({
             ...(options.userAgent ? { userAgent: options.userAgent } : {}),
             ...(options.viewport ? { viewport: options.viewport } : {}),
-            ...(options.locale ? { locale: options.locale } : {}),
-            ...(options.timezoneId ? { timezoneId: options.timezoneId } : {}),
+            ...(resolved.locale ? { locale: resolved.locale } : {}),
+            ...(resolved.timezone ? { timezoneId: resolved.timezone } : {}),
         });
     }
     catch (err) {
@@ -74,6 +77,22 @@ export async function launchContext(options = {}) {
 // ---------------------------------------------------------------------------
 // Internal
 // ---------------------------------------------------------------------------
+async function maybeResolveGeoip(options) {
+    if (!options.geoip || !options.proxy)
+        return { timezone: options.timezone, locale: options.locale };
+    if (options.timezone && options.locale)
+        return { timezone: options.timezone, locale: options.locale };
+    const { resolveProxyGeo } = await import("./geoip.js");
+    const { timezone: geoTz, locale: geoLocale } = await resolveProxyGeo(options.proxy);
+    return {
+        timezone: options.timezone ?? geoTz ?? undefined,
+        locale: options.locale ?? geoLocale ?? undefined,
+    };
+}
+/** @internal Exposed for unit tests only. */
+export function _buildArgsForTest(options) {
+    return buildArgs(options);
+}
 function buildArgs(options) {
     const args = [];
     if (options.stealthArgs !== false) {
@@ -82,6 +101,13 @@ function buildArgs(options) {
     if (options.args) {
         args.push(...options.args);
     }
+    // Timezone/locale flags — always inject when set
+    if (options.timezone) {
+        args.push(`--timezone=${options.timezone}`);
+    }
+    if (options.locale) {
+        args.push(`--lang=${options.locale}`);
+    }
     return args;
 }
 //# sourceMappingURL=playwright.js.map

package/dist/playwright.js.map

@@ -1 +1 @@
-{"version":3,"file":"playwright.js","sourceRoot":"","sources":["../src/playwright.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,UAAyB,EAAE;IACtD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAErD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,CAAC,MAAM,YAAY,EAAE,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAEhC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;QACpC,cAAc,EAAE,UAAU;QAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;QAClC,IAAI;QACJ,iBAAiB,EAAE,CAAC,qBAAqB,CAAC;QAC1C,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,GAAG,OAAO,CAAC,aAAa;KACzB,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAgC,EAAE;IAElC,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;IAEtC,IAAI,OAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;YACjC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClE,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACtB,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,0CAA0C;IAC1C,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO,CAAC,KAAK,GAAG,KAAK,IAAI,EAAE;QACzB,MAAM,SAAS,EAAE,CAAC;QAClB,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,SAAS,SAAS,CAAC,OAAsB;IACvC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,OAAO,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,GAAG,qBAAqB,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"playwright.js","sourceRoot":"","sources":["../src/playwright.ts"],"names":[],"mappings":"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"}

package/dist/puppeteer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"puppeteer.d.ts","sourceRoot":"","sources":["../src/puppeteer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD;;;;;;;;;;;;GAYG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAsC1E"}
+{"version":3,"file":"puppeteer.d.ts","sourceRoot":"","sources":["../src/puppeteer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD;;;;;;;;;;;;GAYG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAuC1E"}

package/dist/puppeteer.js

@@ -21,7 +21,8 @@ import { parseProxyUrl } from "./proxy.js";
 export async function launch(options = {}) {
     const puppeteer = await import("puppeteer-core");
     const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
-    const args = buildArgs(options);
+    const resolved = await maybeResolveGeoip(options);
+    const args = buildArgs({ ...options, ...resolved });
     // Puppeteer handles proxy via CLI args, not a separate option.
     // Chromium's --proxy-server does NOT support inline credentials,
     // so we strip them and use page.authenticate() instead.
@@ -55,6 +56,18 @@ export async function launch(options = {}) {
 // ---------------------------------------------------------------------------
 // Internal
 // ---------------------------------------------------------------------------
+async function maybeResolveGeoip(options) {
+    if (!options.geoip || !options.proxy)
+        return { timezone: options.timezone, locale: options.locale };
+    if (options.timezone && options.locale)
+        return { timezone: options.timezone, locale: options.locale };
+    const { resolveProxyGeo } = await import("./geoip.js");
+    const { timezone: geoTz, locale: geoLocale } = await resolveProxyGeo(options.proxy);
+    return {
+        timezone: options.timezone ?? geoTz ?? undefined,
+        locale: options.locale ?? geoLocale ?? undefined,
+    };
+}
 function buildArgs(options) {
     const args = [];
     if (options.stealthArgs !== false) {
@@ -63,6 +76,12 @@ function buildArgs(options) {
     if (options.args) {
         args.push(...options.args);
     }
+    if (options.timezone) {
+        args.push(`--timezone=${options.timezone}`);
+    }
+    if (options.locale) {
+        args.push(`--lang=${options.locale}`);
+    }
     return args;
 }
 //# sourceMappingURL=puppeteer.js.map

package/dist/puppeteer.js.map

@@ -1 +1 @@
-{"version":3,"file":"puppeteer.js","sourceRoot":"","sources":["../src/puppeteer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,UAAyB,EAAE;IACtD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAEjD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,CAAC,MAAM,YAAY,EAAE,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAEhC,+DAA+D;IAC/D,iEAAiE;IACjE,wDAAwD;IACxD,IAAI,SAA6D,CAAC;IAClE,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpE,IAAI,CAAC,IAAI,CAAC,kBAAkB,MAAM,EAAE,CAAC,CAAC;QACtC,IAAI,QAAQ,EAAE,CAAC;YACb,SAAS,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC;QAC7C,cAAc,EAAE,UAAU;QAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;QAClC,IAAI;QACJ,iBAAiB,EAAE,CAAC,qBAAqB,CAAC;QAC1C,GAAG,OAAO,CAAC,aAAa;KACzB,CAAC,CAAC;IAEH,gEAAgE;IAChE,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAClD,MAAM,IAAI,GAAG,SAAS,CAAC;QACvB,OAAO,CAAC,OAAO,GAAG,KAAK,EAAE,GAAG,QAAwC,EAAE,EAAE;YACtE,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC;YAC5C,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,SAAS,SAAS,CAAC,OAAsB;IACvC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,OAAO,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,GAAG,qBAAqB,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"puppeteer.js","sourceRoot":"","sources":["../src/puppeteer.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -10,6 +10,12 @@ export interface LaunchOptions {
     args?: string[];
     /** Include default stealth fingerprint args (default: true). Set false to use custom --fingerprint flags. */
     stealthArgs?: boolean;
+    /** IANA timezone, e.g. "America/New_York". Sets --timezone binary flag. */
+    timezone?: string;
+    /** BCP 47 locale, e.g. "en-US". Sets --lang binary flag. */
+    locale?: string;
+    /** Auto-detect timezone/locale from proxy IP (requires: npm install mmdb-lib). */
+    geoip?: boolean;
     /** Raw options passed directly to playwright/puppeteer launch(). */
     launchOptions?: Record<string, unknown>;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,6GAA6G;IAC7G,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,6GAA6G;IAC7G,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloakbrowser",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Stealth Chromium that passes every bot detection test. Drop-in Playwright/Puppeteer replacement with source-level fingerprint patches.",
   "type": "module",
   "main": "dist/index.js",
@@ -43,6 +43,7 @@
     "node": ">=18.0.0"
   },
   "peerDependencies": {
+    "mmdb-lib": ">=2.0.0",
     "playwright-core": ">=1.40.0",
     "puppeteer-core": ">=21.0.0"
   },
@@ -52,6 +53,9 @@
     },
     "puppeteer-core": {
       "optional": true
+    },
+    "mmdb-lib": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -59,6 +63,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
+    "mmdb-lib": "^3.0.2",
     "playwright-core": "^1.40.0",
     "puppeteer-core": "^21.0.0",
     "typescript": "^5.3.0",