npm - website-api - Versions diffs - 1.1.3 → 1.1.6 - Mend

website-api 1.1.3 → 1.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (66) hide show

package/README.md +141 -1
package/dist/bin/cli.js +209 -1
package/dist/src/capabilities/browser.d.ts +16 -2
package/dist/src/capabilities/browser.js +158 -1
package/dist/src/capabilities/cookies.d.ts +7 -1
package/dist/src/capabilities/cookies.js +68 -1
package/dist/src/capabilities/download.js +32 -1
package/dist/src/capabilities/fingerprint.js +62 -1
package/dist/src/capabilities/http.js +101 -1
package/dist/src/capabilities/login/login-helper.js +185 -1
package/dist/src/capabilities/login/login-strategy.js +36 -1
package/dist/src/challenges/perimeterx.d.ts +62 -0
package/dist/src/challenges/perimeterx.js +112 -0
package/dist/src/cli/ext.js +338 -1
package/dist/src/core/context.d.ts +2 -2
package/dist/src/core/context.js +138 -1
package/dist/src/core/define-site.js +74 -1
package/dist/src/core/loader.js +142 -1
package/dist/src/core/registry.js +332 -1
package/dist/src/core/runtime.d.ts +12 -4
package/dist/src/core/runtime.js +98 -1
package/dist/src/env.js +34 -1
package/dist/src/sites/bloomberg.com/index.d.ts +11 -0
package/dist/src/sites/bloomberg.com/index.js +49 -0
package/dist/src/sites/bloomberg.com/openapi.yaml +38 -0
package/dist/src/sites/chase.com/download-helper.js +266 -1
package/dist/src/sites/chase.com/index.js +87 -1
package/dist/src/sites/chase.com/openapi.yaml +76 -0
package/dist/src/sites/chatgpt.com/index.js +24 -1
package/dist/src/sites/chatgpt.com/openapi.yaml +29 -0
package/dist/src/sites/claude.ai/claude-helpers.js +26 -1
package/dist/src/sites/claude.ai/index.js +42 -1
package/dist/src/sites/claude.ai/openapi.yaml +54 -0
package/dist/src/sites/cursor.com/index.js +12 -1
package/dist/src/sites/cursor.com/openapi.yaml +39 -0
package/dist/src/sites/e-zpassny.com/index.d.ts +2 -0
package/dist/src/sites/e-zpassny.com/index.js +344 -0
package/dist/src/sites/e-zpassny.com/openapi.yaml +68 -0
package/dist/src/sites/gemini.google.com/index.js +80 -1
package/dist/src/sites/gemini.google.com/openapi.yaml +39 -0
package/dist/src/sites/google.com/google-helpers.js +255 -1
package/dist/src/sites/google.com/index.js +253 -1
package/dist/src/sites/google.com/openapi.yaml +59 -0
package/dist/src/sites/microcenter.com/openapi.yaml +44 -0
package/dist/src/sites/ollama.com/index.js +43 -1
package/dist/src/sites/ollama.com/openapi.yaml +39 -0
package/dist/src/sites/perplexity.ai/index.js +253 -1
package/dist/src/sites/perplexity.ai/openapi.yaml +51 -0
package/dist/src/sites/pseg.com/index.js +243 -1
package/dist/src/sites/pseg.com/openapi.yaml +42 -0
package/dist/src/sites/pseg.com/pseg-helpers.js +53 -1
package/dist/src/sites/voice.google.com/index.d.ts +2 -0
package/dist/src/sites/voice.google.com/index.js +122 -0
package/dist/src/sites/voice.google.com/openapi.yaml +67 -0
package/dist/src/sites/voice.google.com/voice-helpers.d.ts +105 -0
package/dist/src/sites/voice.google.com/voice-helpers.js +181 -0
package/dist/src/sites/zillow.com/index.d.ts +2 -0
package/dist/src/sites/zillow.com/index.js +303 -0
package/dist/src/sites/zillow.com/openapi.yaml +55 -0
package/dist/src/types.d.ts +7 -0
package/dist/src/types.js +1 -1
package/dist/src/util/args-parser.js +150 -1
package/dist/src/util/google-json.js +74 -1
package/dist/src/website-api.d.ts +7 -7
package/dist/src/website-api.js +13 -1
package/package.json +38 -10

package/dist/src/capabilities/download.js CHANGED Viewed

@@ -1 +1,32 @@
-import t from"node:fs/promises";import e from"node:path";export function createSaver(r,o=process.cwd()){const n=e.resolve(o,r??".");let i=!1;return async function(r,o){i||(await t.mkdir(n,{recursive:!0}),i=!0);const s=e.join(n,e.basename(r));return await t.writeFile(s,o),s}}export function assertNotHtml(t,e){const r=String(t??"").trimStart();if(/^<!doctype html/i.test(r)||/^<html/i.test(r))throw new Error(`Download for ${e} returned HTML instead of data. The session may have expired.`);return t}
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Builds a `save(filename, content)` function bound to a target directory.
+ * Creates the directory on first write and returns the absolute path written.
+ * `outDir` of null means "current working directory".
+ */
+export function createSaver(outDir, cwd = process.cwd()) {
+    const targetDir = path.resolve(cwd, outDir ?? ".");
+    let ensured = false;
+    return async function save(filename, content) {
+        if (!ensured) {
+            await fs.mkdir(targetDir, { recursive: true });
+            ensured = true;
+        }
+        // Defend against path traversal: only the basename is honored.
+        const filePath = path.join(targetDir, path.basename(filename));
+        await fs.writeFile(filePath, content);
+        return filePath;
+    };
+}
+/**
+ * Guards a downloaded payload that should be data but may be an HTML error page
+ * (a common symptom of an expired session). Throws a clear, actionable error.
+ */
+export function assertNotHtml(text, label) {
+    const trimmed = String(text ?? "").trimStart();
+    if (/^<!doctype html/i.test(trimmed) || /^<html/i.test(trimmed)) {
+        throw new Error(`Download for ${label} returned HTML instead of data. The session may have expired.`);
+    }
+    return text;
+}

package/dist/src/capabilities/fingerprint.js CHANGED Viewed

@@ -1 +1,62 @@
-const n={languages:["en-US","en"]};export function buildFingerprintScript(n){return`(() => {\n    const cfg = ${JSON.stringify(n)};\n    const def = (obj, prop, get) => {\n      try { Object.defineProperty(obj, prop, { get, configurable: true }); } catch (_) {}\n    };\n    // Hide the automation flag.\n    def(navigator, "webdriver", () => undefined);\n    if (cfg.languages) {\n      def(navigator, "languages", () => cfg.languages);\n    }\n    if (cfg.platform) def(navigator, "platform", () => cfg.platform);\n    if (typeof cfg.hardwareConcurrency === "number") {\n      def(navigator, "hardwareConcurrency", () => cfg.hardwareConcurrency);\n    }\n    if (typeof cfg.deviceMemory === "number") {\n      def(navigator, "deviceMemory", () => cfg.deviceMemory);\n    }\n    // Present a non-empty plugins list, as headless/automation often reports none.\n    try {\n      if (!navigator.plugins || navigator.plugins.length === 0) {\n        def(navigator, "plugins", () => [1, 2, 3, 4, 5]);\n      }\n    } catch (_) {}\n    // Ensure window.chrome exists, as some sites probe for it.\n    try {\n      if (!window.chrome) { window.chrome = { runtime: {} }; }\n    } catch (_) {}\n  })();`}export function resolveFingerprint(e,r){if(!1===e)return null;const t="stealth"===e?{...n}:{...n,...e};return r&&!t.userAgent&&(t.userAgent=r),t}export async function applyFingerprint(n,e,r){const t=resolveFingerprint(e,r);t&&await n.addInitScript(buildFingerprintScript(t))}
+/**
+ * The default "stealth" profile: minimal, well-tested anti-bot evasions that
+ * keep an attached real-Chrome session from being flagged as automated.
+ */
+const STEALTH_DEFAULTS = {
+    languages: ["en-US", "en"],
+};
+/**
+ * Builds the init script that shapes the page's fingerprint. Pure and exported
+ * so it can be unit-tested without a real browser.
+ */
+export function buildFingerprintScript(config) {
+    // Serialized into the page; only plain data from `config` is interpolated.
+    const cfg = JSON.stringify(config);
+    return `(() => {
+    const cfg = ${cfg};
+    const def = (obj, prop, get) => {
+      try { Object.defineProperty(obj, prop, { get, configurable: true }); } catch (_) {}
+    };
+    // Hide the automation flag.
+    def(navigator, "webdriver", () => undefined);
+    if (cfg.languages) {
+      def(navigator, "languages", () => cfg.languages);
+    }
+    if (cfg.platform) def(navigator, "platform", () => cfg.platform);
+    if (typeof cfg.hardwareConcurrency === "number") {
+      def(navigator, "hardwareConcurrency", () => cfg.hardwareConcurrency);
+    }
+    if (typeof cfg.deviceMemory === "number") {
+      def(navigator, "deviceMemory", () => cfg.deviceMemory);
+    }
+    // Present a non-empty plugins list, as headless/automation often reports none.
+    try {
+      if (!navigator.plugins || navigator.plugins.length === 0) {
+        def(navigator, "plugins", () => [1, 2, 3, 4, 5]);
+      }
+    } catch (_) {}
+    // Ensure window.chrome exists, as some sites probe for it.
+    try {
+      if (!window.chrome) { window.chrome = { runtime: {} }; }
+    } catch (_) {}
+  })();`;
+}
+/** Resolves the effective fingerprint config from the site's option. */
+export function resolveFingerprint(option, userAgent) {
+    if (option === false)
+        return null;
+    const base = option === "stealth" ? { ...STEALTH_DEFAULTS } : { ...STEALTH_DEFAULTS, ...option };
+    if (userAgent && !base.userAgent)
+        base.userAgent = userAgent;
+    return base;
+}
+/**
+ * Applies the fingerprint to a page via an init script (runs before page
+ * scripts on the next navigation). No-op when fingerprinting is disabled.
+ */
+export async function applyFingerprint(page, option, userAgent) {
+    const config = resolveFingerprint(option, userAgent);
+    if (!config)
+        return;
+    await page.addInitScript(buildFingerprintScript(config));
+}

package/dist/src/capabilities/http.js CHANGED Viewed

@@ -1 +1,101 @@
-export function parseSSE(t){const e=[],s=t.replace(/\r\n/g,"\n");for(const t of s.split("\n\n")){const s=[];for(const e of t.split("\n"))e.startsWith("data:")&&s.push(e.slice(5).trimStart());if(s.length)try{const t=JSON.parse(s.join("\n"));t&&("object"!=typeof t||Object.keys(t).length>0)&&e.push(t)}catch{}}return e}export function createHttp(t){const e=t.fetchImpl??fetch;function s(e){const s=new Headers(e?.headers);if(!s.has("Cookie")){const e=t.cookieString();e&&s.set("Cookie",e)}return s.has("User-Agent")||s.set("User-Agent",t.userAgent()),s}async function n(n,a){const r={...a,headers:s(a)};t.debug&&console.log("[debug] Request:",{url:n,init:r});const o=await e(n,r),c=await o.text();if(t.debug&&console.log("[debug] Response:",{url:n,status:o.status,statusText:o.statusText,headers:Array.from(o.headers.entries()),body:c}),!o.ok)throw new Error(`HTTP ${o.status}: ${o.statusText}`);return{response:o,text:c}}return{raw:n,text:async(t,e)=>(await n(t,e)).text,async html(t,e){const s=new Headers(e?.headers);return s.has("Accept")||s.set("Accept","text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"),(await n(t,{...e,headers:s})).text},async json(t,e){const s=new Headers(e?.headers);s.has("Accept")||s.set("Accept","application/json, text/plain, */*");const{text:a}=await n(t,{...e,headers:s});try{return JSON.parse(a)}catch{return{response:a}}},async sse(t,e){const s=new Headers(e?.headers);s.has("Accept")||s.set("Accept","text/event-stream");const{response:a,text:r}=await n(t,{...e,headers:s});return{status:a.status,contentType:a.headers.get("content-type")||"",frames:parseSSE(r),raw:r}}}}
+/** Parses an SSE body into the JSON payloads of its `data:` frames. */
+export function parseSSE(raw) {
+    const frames = [];
+    const normalized = raw.replace(/\r\n/g, "\n");
+    for (const block of normalized.split("\n\n")) {
+        const dataLines = [];
+        for (const line of block.split("\n")) {
+            if (line.startsWith("data:"))
+                dataLines.push(line.slice(5).trimStart());
+        }
+        if (!dataLines.length)
+            continue;
+        try {
+            const data = JSON.parse(dataLines.join("\n"));
+            if (data && (typeof data !== "object" || Object.keys(data).length > 0)) {
+                frames.push(data);
+            }
+        }
+        catch {
+            // Skip non-JSON frames (comments, keep-alives, partials).
+        }
+    }
+    return frames;
+}
+/**
+ * Builds the HTTP capability. Every request merges the resolved Chrome cookie
+ * string and User-Agent unless the caller already set those headers.
+ */
+export function createHttp(deps) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    function mergeHeaders(init) {
+        const headers = new Headers(init?.headers);
+        if (!headers.has("Cookie")) {
+            const cookie = deps.cookieString();
+            if (cookie)
+                headers.set("Cookie", cookie);
+        }
+        if (!headers.has("User-Agent")) {
+            headers.set("User-Agent", deps.userAgent());
+        }
+        return headers;
+    }
+    async function raw(url, init) {
+        const request = { ...init, headers: mergeHeaders(init) };
+        if (deps.debug)
+            console.log("[debug] Request:", { url, init: request });
+        const response = await fetchImpl(url, request);
+        const text = await response.text();
+        if (deps.debug) {
+            console.log("[debug] Response:", {
+                url,
+                status: response.status,
+                statusText: response.statusText,
+                headers: Array.from(response.headers.entries()),
+                body: text,
+            });
+        }
+        if (!response.ok) {
+            const reason = response.statusText || text.slice(0, 200) || "request failed";
+            throw new Error(`HTTP ${response.status}: ${reason}`);
+        }
+        return { response, text };
+    }
+    return {
+        raw,
+        async text(url, init) {
+            return (await raw(url, init)).text;
+        },
+        async html(url, init) {
+            const headers = new Headers(init?.headers);
+            if (!headers.has("Accept")) {
+                headers.set("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8");
+            }
+            return (await raw(url, { ...init, headers })).text;
+        },
+        async json(url, init) {
+            const headers = new Headers(init?.headers);
+            if (!headers.has("Accept"))
+                headers.set("Accept", "application/json, text/plain, */*");
+            const { text } = await raw(url, { ...init, headers });
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return { response: text };
+            }
+        },
+        async sse(url, init) {
+            const headers = new Headers(init?.headers);
+            if (!headers.has("Accept"))
+                headers.set("Accept", "text/event-stream");
+            const { response, text } = await raw(url, { ...init, headers });
+            return {
+                status: response.status,
+                contentType: response.headers.get("content-type") || "",
+                frames: parseSSE(text),
+                raw: text,
+            };
+        },
+    };
+}

package/dist/src/capabilities/login/login-helper.js CHANGED Viewed

@@ -1 +1,185 @@
-const t=['input[type="password"]'],e=['button[type="submit"]','input[type="submit"]'];async function i(t,e){for(const i of e)try{if(await t.locator(i).first().isVisible())return i}catch{}return null}function o(t,...e){const i=[t,...e.flatMap(t=>t??[])];return Array.from(new Set(i.filter(Boolean)))}export async function performFormLogin(a){const{page:r,emailSelector:n,passwordSelector:l,submitButtonSelector:s,delayMs:c=1e3,intendedUrl:w,expectedRedirectUrlPattern:f=w,debug:g=!1,pwdSelector:d='input[type="password"]',dashboardSelectors:u=[]}=a;if(w){if(!r.url().includes(w)){g&&console.log(`[LoginHelper] Navigating to intended URL: ${w}`);try{await r.goto(w,{waitUntil:"domcontentloaded"})}catch(t){g&&console.warn(`[LoginHelper] Warning navigating to ${w}:`,t)}}}try{await r.waitForLoadState("domcontentloaded")}catch{}let p=!1,m=r;g&&console.log("[LoginHelper] Waiting for session state to settle...");const b=Date.now();let y=!1;for(;Date.now()-b<15e3;){let t=!1;for(const e of u)try{if(await r.locator(e).first().isVisible()){p=!1,t=!0;break}}catch{}if(t){y=!0;break}try{if(await r.locator(d).first().isVisible()){p=!0,m=r,y=!0;break}}catch{}let e=!1;for(const t of r.frames())try{if(await t.locator(d).first().isVisible()){p=!0,m=t,e=!0;break}}catch{}if(e){y=!0;break}await r.waitForTimeout(500)}if(!y)try{await r.waitForSelector(n,{state:"visible",timeout:1e3}),p=!0,m=r}catch{try{await r.waitForSelector(l,{state:"visible",timeout:1e3}),p=!0,m=r}catch{p=!1}}if(!p)return g&&console.log("[LoginHelper] Already logged in. Skipping login flow."),!1;let L=a.emailValue,h=a.passwordValue;if((!L||!h)&&a.getCredentials){const t=a.getCredentials();L=t.username,h=t.password}if(!L||!h)throw new Error("[LoginHelper] Login required but no credentials were provided");const S=await i(m,o(n,a.usernameSelectors))||n,k=await i(m,o(l,a.passwordSelectors,t))||l,H=await i(m,o(s,a.submitSelectors,e))||s;if(g&&console.log(`[LoginHelper] Login form detected. email='${S}', password='${k}', submit='${H}'`),await m.fill(S,L),await m.fill(k,h),c>0&&(g&&console.log(`[LoginHelper] Waiting ${c}ms before submission...`),await m.waitForTimeout(c)),g&&console.log(`[LoginHelper] Clicking submit '${H}'...`),await m.click(H),f){g&&console.log(`[LoginHelper] Waiting for redirection matching '${f}'...`);try{await r.waitForURL(f,{timeout:15e3})}catch{try{await r.waitForNavigation({waitUntil:"networkidle",timeout:8e3})}catch{}}}return!0}
+// IMPORTANT: This helper is universal and shared across every site. Do NOT
+// hardcode site-specific selectors here. Sites that need extra resilience pass
+// their own fallbacks via the *Selectors arrays.
+//
+// SCOPE: single-page username+password forms (both fields visible at once). It
+// does NOT handle identifier-first multi-step flows (email -> Next -> password,
+// e.g. Google/Microsoft/Okta) or 2FA/OTP — those need a dedicated LoginStrategy.
+/**
+ * Genuinely cross-site-safe fallbacks. A visible password input is almost
+ * always THE password input; a submit button is rarely ambiguous. There is no
+ * safe universal *username* fallback (a bare text input could be search, OTP,
+ * etc.), so username relies solely on adapter-provided selectors.
+ */
+const UNIVERSAL_PASSWORD_SELECTORS = ['input[type="password"]'];
+const UNIVERSAL_SUBMIT_SELECTORS = ['button[type="submit"]', 'input[type="submit"]'];
+/** Returns the first visible selector from the candidate list, or null. */
+async function firstVisibleSelector(frame, candidates) {
+    for (const candidate of candidates) {
+        try {
+            if (await frame.locator(candidate).first().isVisible())
+                return candidate;
+        }
+        catch { }
+    }
+    return null;
+}
+/** Builds an ordered, de-duplicated candidate list: primary, then fallbacks. */
+function buildCandidates(primary, ...fallbackGroups) {
+    const all = [primary, ...fallbackGroups.flatMap((group) => group ?? [])];
+    return Array.from(new Set(all.filter(Boolean)));
+}
+/**
+ * Automates a form login via Playwright: detects whether login is required,
+ * fills credentials, waits, submits, and awaits redirection. Idempotent — when
+ * a dashboard is already showing it skips login and returns false.
+ */
+export async function performFormLogin(options) {
+    const { page, emailSelector, passwordSelector, submitButtonSelector, delayMs = 1000, intendedUrl, expectedRedirectUrlPattern = intendedUrl, debug = false, pwdSelector = 'input[type="password"]', dashboardSelectors = [], } = options;
+    if (intendedUrl) {
+        const currentUrl = page.url();
+        if (!currentUrl.includes(intendedUrl)) {
+            if (debug)
+                console.log(`[LoginHelper] Navigating to intended URL: ${intendedUrl}`);
+            try {
+                await page.goto(intendedUrl, { waitUntil: "domcontentloaded" });
+            }
+            catch (err) {
+                if (debug)
+                    console.warn(`[LoginHelper] Warning navigating to ${intendedUrl}:`, err);
+            }
+        }
+    }
+    try {
+        await page.waitForLoadState("domcontentloaded");
+    }
+    catch (err) {
+        if (debug)
+            console.warn(`[LoginHelper] waitForLoadState failed (continuing):`, err);
+    }
+    let needsLogin = false;
+    let activeFrame = page;
+    if (debug)
+        console.log(`[LoginHelper] Waiting for session state to settle...`);
+    const startTime = Date.now();
+    const maxWaitMs = 15000;
+    let settled = false;
+    while (Date.now() - startTime < maxWaitMs) {
+        if (typeof page.isClosed === "function" && page.isClosed()) {
+            throw new Error("[LoginHelper] Page closed while waiting for the session state to settle");
+        }
+        // A. Dashboard markers win.
+        let foundDashboard = false;
+        for (const dashSel of dashboardSelectors) {
+            try {
+                if (await page.locator(dashSel).first().isVisible()) {
+                    needsLogin = false;
+                    foundDashboard = true;
+                    break;
+                }
+            }
+            catch { }
+        }
+        if (foundDashboard) {
+            settled = true;
+            break;
+        }
+        // B. Login form in the main frame?
+        try {
+            if (await page.locator(pwdSelector).first().isVisible()) {
+                needsLogin = true;
+                activeFrame = page;
+                settled = true;
+                break;
+            }
+        }
+        catch { }
+        // C. Login form in any subframe?
+        let foundInFrame = false;
+        for (const frame of page.frames()) {
+            try {
+                if (await frame.locator(pwdSelector).first().isVisible()) {
+                    needsLogin = true;
+                    activeFrame = frame;
+                    foundInFrame = true;
+                    break;
+                }
+            }
+            catch { }
+        }
+        if (foundInFrame) {
+            settled = true;
+            break;
+        }
+        await page.waitForTimeout(500);
+    }
+    if (!settled) {
+        try {
+            await page.waitForSelector(emailSelector, { state: "visible", timeout: 1000 });
+            needsLogin = true;
+            activeFrame = page;
+        }
+        catch {
+            try {
+                await page.waitForSelector(passwordSelector, { state: "visible", timeout: 1000 });
+                needsLogin = true;
+                activeFrame = page;
+            }
+            catch {
+                needsLogin = false;
+            }
+        }
+    }
+    if (!needsLogin) {
+        if (debug)
+            console.log(`[LoginHelper] Already logged in. Skipping login flow.`);
+        return false;
+    }
+    // Resolve credentials lazily, only now that login is confirmed necessary.
+    let emailValue = options.emailValue;
+    let passwordValue = options.passwordValue;
+    if ((!emailValue || !passwordValue) && options.getCredentials) {
+        const credentials = options.getCredentials();
+        emailValue = credentials.username;
+        passwordValue = credentials.password;
+    }
+    if (!emailValue || !passwordValue) {
+        throw new Error("[LoginHelper] Login required but no credentials were provided");
+    }
+    const activeEmailSelector = (await firstVisibleSelector(activeFrame, buildCandidates(emailSelector, options.usernameSelectors))) ||
+        emailSelector;
+    const activePasswordSelector = (await firstVisibleSelector(activeFrame, buildCandidates(passwordSelector, options.passwordSelectors, UNIVERSAL_PASSWORD_SELECTORS))) || passwordSelector;
+    const activeSubmitSelector = (await firstVisibleSelector(activeFrame, buildCandidates(submitButtonSelector, options.submitSelectors, UNIVERSAL_SUBMIT_SELECTORS))) || submitButtonSelector;
+    if (debug) {
+        console.log(`[LoginHelper] Login form detected. email='${activeEmailSelector}', password='${activePasswordSelector}', submit='${activeSubmitSelector}'`);
+    }
+    await activeFrame.fill(activeEmailSelector, emailValue);
+    await activeFrame.fill(activePasswordSelector, passwordValue);
+    if (delayMs > 0) {
+        if (debug)
+            console.log(`[LoginHelper] Waiting ${delayMs}ms before submission...`);
+        await activeFrame.waitForTimeout(delayMs);
+    }
+    if (debug)
+        console.log(`[LoginHelper] Clicking submit '${activeSubmitSelector}'...`);
+    await activeFrame.click(activeSubmitSelector);
+    if (expectedRedirectUrlPattern) {
+        if (debug)
+            console.log(`[LoginHelper] Waiting for redirection matching '${expectedRedirectUrlPattern}'...`);
+        try {
+            await page.waitForURL(expectedRedirectUrlPattern, { timeout: 15000 });
+        }
+        catch (urlErr) {
+            if (debug)
+                console.warn(`[LoginHelper] No redirect to '${expectedRedirectUrlPattern}':`, urlErr);
+            try {
+                await page.waitForNavigation({ waitUntil: "networkidle", timeout: 8000 });
+            }
+            catch (navErr) {
+                if (debug)
+                    console.warn(`[LoginHelper] No post-submit navigation either (continuing):`, navErr);
+            }
+        }
+    }
+    return true;
+}

package/dist/src/capabilities/login/login-strategy.js CHANGED Viewed

@@ -1 +1,36 @@
-import{performFormLogin as e}from"./login-helper.js";export class FormLoginStrategy{config;constructor(e){this.config=e}ensureLoggedIn(t){return e({...this.config,page:t.page,debug:t.debug,getCredentials:t.getCredentials})}}export function isLoginStrategy(e){return"object"==typeof e&&null!==e&&"function"==typeof e.ensureLoggedIn}export function toLoginStrategy(e){return isLoginStrategy(e)?e:new FormLoginStrategy(e)}
+// Login strategies (Strategy pattern).
+//
+// A LoginStrategy encapsulates *how* a site authenticates. Sites declare a
+// strategy declaratively (selectors / URLs only) — or just pass a plain
+// FormLoginConfig as `auth` and let the framework wrap it. The runtime drives
+// it from the browser capability; sites never resolve credentials themselves.
+import { performFormLogin } from "./login-helper.js";
+/**
+ * Standard username/password form login. Wraps the universal `performFormLogin`
+ * engine, which auto-detects whether the form is present and skips login when a
+ * dashboard is already showing.
+ */
+export class FormLoginStrategy {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    ensureLoggedIn(ctx) {
+        return performFormLogin({
+            ...this.config,
+            page: ctx.page,
+            debug: ctx.debug,
+            getCredentials: ctx.getCredentials,
+        });
+    }
+}
+/** Type guard: distinguishes a ready strategy from a plain config object. */
+export function isLoginStrategy(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.ensureLoggedIn === "function");
+}
+/** Normalizes `auth` (config or strategy) into a LoginStrategy. */
+export function toLoginStrategy(auth) {
+    return isLoginStrategy(auth) ? auth : new FormLoginStrategy(auth);
+}

package/dist/src/challenges/perimeterx.d.ts ADDED Viewed

@@ -0,0 +1,62 @@
+import type { Page } from "playwright-core";
+/**
+ * PerimeterX / HUMAN bot-challenge handling.
+ *
+ * Sites fronted by PerimeterX (e.g. bloomberg.com) intermittently interrupt a
+ * navigation with one of two interstitials:
+ *
+ *   • "press & hold"  — a `#px-captcha` widget the user must hold for a few
+ *     seconds. Solvable from a real (CDP-attached) browser by synthesizing a
+ *     human-like press-and-hold.
+ *   • "hard block"    — a flat deny page carrying a "Block reference ID". Not
+ *     solvable by interaction; the IP reputation has to cool down.
+ *
+ * This module auto-detects which one is showing and solves the press-and-hold.
+ */
+export type ChallengeKind = "none" | "press-and-hold" | "hard-block";
+export interface ChallengeStatus {
+    kind: ChallengeKind;
+    /** Block reference ID, when a hard block is shown. */
+    referenceId?: string;
+    /**
+     * True when the press-&-hold renders inside the cross-origin "Human
+     * verification challenge" iframe — HUMAN's hardened deployment (e.g. Zillow).
+     * These analyze pointer-event biometrics and reject CDP-synthesized holds, so
+     * `solvePerimeterX` will usually fail and you must fall back to
+     * {@link waitForManualSolve} (a real human hold in the attached browser).
+     * The lighter inline variant (e.g. Bloomberg) is solvable synthetically.
+     */
+    hardened?: boolean;
+}
+export interface SolveOptions {
+    /** Total hold duration in ms. PerimeterX fills over a few seconds; ~11s is safe. */
+    holdMs?: number;
+    /** How many detect→solve cycles to attempt before giving up. */
+    attempts?: number;
+    /** Optional logger (e.g. console.log when ctx.debug). */
+    log?: (msg: string) => void;
+}
+export interface SolveResult extends ChallengeStatus {
+    /** True once no challenge remains on the page. */
+    cleared: boolean;
+    /** Number of press-and-hold attempts performed. */
+    tries: number;
+}
+/** Inspect the current page and classify any PerimeterX interstitial. */
+export declare function detectChallenge(page: Page): Promise<ChallengeStatus>;
+/**
+ * Detect and solve a PerimeterX challenge on the current page. Returns once the
+ * page is clear, after exhausting attempts, or immediately on a hard block
+ * (which interaction cannot resolve).
+ */
+export declare function solvePerimeterX(page: Page, opts?: SolveOptions): Promise<SolveResult>;
+/**
+ * Fallback for hardened HUMAN challenges that reject synthetic holds: poll until
+ * the page is clear because a human completed the press-&-hold in the attached
+ * browser (or the cookie otherwise resolved). Returns true once cleared.
+ */
+export declare function waitForManualSolve(page: Page, opts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+    log?: (msg: string) => void;
+}): Promise<boolean>;

package/dist/src/challenges/perimeterx.js ADDED Viewed

@@ -0,0 +1,112 @@
+const REL = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Inspect the current page and classify any PerimeterX interstitial. */
+export async function detectChallenge(page) {
+    return page.evaluate(() => {
+        const px = document.querySelector("#px-captcha");
+        if (px) {
+            // Hardened HUMAN renders the button inside a cross-origin iframe titled
+            // "Human verification challenge"; the lighter variant is inline.
+            const hardened = !!px.querySelector('iframe[title*="erification" i], iframe[title*="uman" i]');
+            return { kind: "press-and-hold", hardened };
+        }
+        const bodyText = document.body?.innerText ?? "";
+        const blocked = /detected unusual activity|Are you a robot|Block reference ID/i.test(bodyText) ||
+            /Are you a robot/i.test(document.title);
+        if (blocked) {
+            const m = bodyText.match(/Block reference ID:\s*([\w-]+)/i);
+            return { kind: "hard-block", referenceId: m?.[1] };
+        }
+        return { kind: "none" };
+    });
+}
+/** Center the mouse on `#px-captcha`, press, hold with jitter, release. */
+async function pressAndHold(page, holdMs) {
+    const box = await page.evaluate(() => {
+        const el = document.querySelector("#px-captcha");
+        if (!el)
+            return null;
+        const r = el.getBoundingClientRect();
+        return { cx: Math.round(r.x + r.width / 2), cy: Math.round(r.y + r.height / 2) };
+    });
+    if (!box)
+        return false;
+    const { cx, cy } = box;
+    // Approach the button along a short, non-linear path so it doesn't read as a teleport.
+    await page.mouse.move(cx - 240, cy + 130, { steps: 8 });
+    await page.mouse.move(cx - 50, cy + 35, { steps: 6 });
+    await page.mouse.move(cx, cy, { steps: 5 });
+    await page.mouse.down();
+    const start = Date.now();
+    while (Date.now() - start < holdMs) {
+        const dx = Math.floor(Math.random() * 3) - 1;
+        const dy = Math.floor(Math.random() * 3) - 1;
+        await page.mouse.move(cx + dx, cy + dy);
+        await REL(450 + Math.floor(Math.random() * 250));
+    }
+    await page.mouse.up();
+    return true;
+}
+/**
+ * Detect and solve a PerimeterX challenge on the current page. Returns once the
+ * page is clear, after exhausting attempts, or immediately on a hard block
+ * (which interaction cannot resolve).
+ */
+export async function solvePerimeterX(page, opts = {}) {
+    const holdMs = opts.holdMs ?? 11_000;
+    const attempts = opts.attempts ?? 2;
+    const log = opts.log ?? (() => { });
+    let status = await detectChallenge(page);
+    if (status.kind === "none")
+        return { ...status, cleared: true, tries: 0 };
+    if (status.kind === "hard-block") {
+        log(`[perimeterx] hard block (reference ${status.referenceId ?? "?"}) — cannot solve by interaction.`);
+        return { ...status, cleared: false, tries: 0 };
+    }
+    let tries = 0;
+    for (let i = 0; i < attempts; i++) {
+        log(`[perimeterx] press-&-hold challenge detected${status.hardened ? " (hardened iframe variant)" : ""}` +
+            ` — solving (attempt ${i + 1}/${attempts})`);
+        tries++;
+        const pressed = await pressAndHold(page, holdMs);
+        if (!pressed)
+            break;
+        await REL(3000); // let the page reload/settle after release
+        status = await detectChallenge(page);
+        if (status.kind === "none") {
+            log("[perimeterx] cleared.");
+            return { ...status, cleared: true, tries };
+        }
+        if (status.kind === "hard-block") {
+            log(`[perimeterx] escalated to hard block (reference ${status.referenceId ?? "?"}).`);
+            return { ...status, cleared: false, tries };
+        }
+    }
+    if (status.hardened) {
+        log("[perimeterx] hardened HUMAN press-&-hold rejected the synthetic hold. " +
+            "Fall back to waitForManualSolve() — a real human hold in the attached browser " +
+            "sets the _px3/_pxhd clearance cookies for the session.");
+    }
+    return { ...status, cleared: false, tries };
+}
+/**
+ * Fallback for hardened HUMAN challenges that reject synthetic holds: poll until
+ * the page is clear because a human completed the press-&-hold in the attached
+ * browser (or the cookie otherwise resolved). Returns true once cleared.
+ */
+export async function waitForManualSolve(page, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 120_000;
+    const pollMs = opts.pollMs ?? 1500;
+    const log = opts.log ?? (() => { });
+    log("[perimeterx] waiting for a human to complete the press-&-hold in the browser...");
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const status = await detectChallenge(page);
+        if (status.kind === "none") {
+            log("[perimeterx] cleared by human.");
+            return true;
+        }
+        await REL(pollMs);
+    }
+    log("[perimeterx] timed out waiting for the human hold.");
+    return false;
+}