@taodigital/crawler 0.0.0-stage → 1.2.1

package/dist/session-capture.js

@@ -0,0 +1,274 @@
+import { chromium } from "playwright";
+import { randomBytes } from "node:crypto";
+import { login } from "./auth.js";
+import { generateTOTP } from "./job-queue.js";
+import { getNonHeadlessUserAgent } from "./crawler.js";
+const activeSessions = /* @__PURE__ */ new Map();
+async function startSessionCapture(appUrl) {
+  const inDocker = process.env.PLAYWRIGHT_IN_DOCKER === "true";
+  const noDisplay = process.platform === "linux" && !process.env.DISPLAY;
+  if (inDocker || noDisplay) {
+    throw new Error("HEADLESS_ENV");
+  }
+  const id = randomBytes(16).toString("hex");
+  const browser = await chromium.launch({ headless: false });
+  const userAgent = await getNonHeadlessUserAgent(chromium.executablePath());
+  const context = await browser.newContext({ userAgent });
+  const page = await context.newPage();
+  await page.goto(appUrl, { waitUntil: "domcontentloaded" }).catch(() => {
+  });
+  const timer = setTimeout(() => cancelSessionCapture(id).catch(() => {
+  }), 10 * 60 * 1e3);
+  activeSessions.set(id, { browser, context, timer });
+  return id;
+}
+async function completeSessionCapture(captureId) {
+  const session = activeSessions.get(captureId);
+  if (!session) throw new Error("Capture session not found or expired.");
+  clearTimeout(session.timer);
+  const state = await session.context.storageState();
+  await session.browser.close().catch(() => {
+  });
+  activeSessions.delete(captureId);
+  return JSON.stringify(state);
+}
+async function cancelSessionCapture(captureId) {
+  const session = activeSessions.get(captureId);
+  if (!session) return;
+  clearTimeout(session.timer);
+  await session.browser.close().catch(() => {
+  });
+  activeSessions.delete(captureId);
+}
+async function exploreAppAfterLogin(page) {
+  const sleep = (ms) => page.waitForTimeout(ms).catch(() => {
+  });
+  const isVisible = `
+    function isVisible(el) {
+      const s = window.getComputedStyle(el);
+      if (s.display === 'none' || s.visibility === 'hidden' || parseFloat(s.opacity) < 0.1) return false;
+      const r = el.getBoundingClientRect();
+      return r.width > 4 && r.height > 4;
+    }
+  `;
+  try {
+    const origin = await page.evaluate(() => location.origin).catch(() => "");
+    const startUrl = await page.evaluate(() => location.href).catch(() => "");
+    await page.evaluate(new Function(`
+      ${isVisible}
+      const inBadCtx = el => {
+        let p = el.parentElement;
+        while (p) {
+          const role = p.getAttribute('role') ?? '';
+          if (['dialog','alertdialog','combobox','listbox'].includes(role)) return true;
+          p = p.parentElement;
+        }
+        return false;
+      };
+      const targets = new Set();
+      document.querySelectorAll('[aria-haspopup]:not([aria-expanded="true"])').forEach(el => {
+        if (isVisible(el) && !inBadCtx(el)) targets.add(el);
+      });
+      document.querySelectorAll('[aria-expanded="false"]').forEach(el => {
+        if ((el.tagName === 'BUTTON' || el.getAttribute('role') === 'button') && isVisible(el) && !inBadCtx(el)) targets.add(el);
+      });
+      document.querySelectorAll('[data-state="closed"],[data-headlessui-state="closed"]').forEach(el => {
+        if ((el.tagName === 'BUTTON' || el.getAttribute('role') === 'button') && isVisible(el) && !inBadCtx(el)) targets.add(el);
+      });
+      targets.forEach(el => { try { el.click(); } catch {} });
+    `)).catch(() => {
+    });
+    await sleep(600);
+    const navLinks = await page.evaluate(new Function(`
+      ${isVisible}
+      const links = new Set();
+      const navEls = document.querySelectorAll('nav a, [role="navigation"] a, aside a, header a');
+      navEls.forEach(a => {
+        const href = a.getAttribute('href');
+        if (!href || href.startsWith('#') || href.startsWith('mailto:') || href.startsWith('tel:')) return;
+        if (!isVisible(a)) return;
+        try {
+          const url = new URL(href, location.href);
+          if (url.origin === location.origin) links.add(url.href);
+        } catch {}
+      });
+      return [...links].slice(0, 10); // cap at 10 nav pages
+    `)).catch(() => []);
+    await page.keyboard?.press("Escape").catch(() => {
+    });
+    await sleep(200);
+    for (const link of navLinks) {
+      try {
+        if (link === startUrl) continue;
+        await page.goto(link, { waitUntil: "networkidle", timeout: 15e3 }).catch(() => {
+        });
+        await sleep(400);
+        await interactWithCurrentPage(page, isVisible, sleep);
+      } catch {
+      }
+    }
+    if (navLinks.length > 0) {
+      await page.goto(startUrl, { waitUntil: "networkidle", timeout: 15e3 }).catch(() => {
+      });
+      await sleep(400);
+    }
+    await interactWithCurrentPage(page, isVisible, sleep);
+    await page.waitForLoadState("networkidle", { timeout: 5e3 }).catch(() => {
+    });
+  } catch {
+  }
+}
+async function interactWithCurrentPage(page, isVisible, sleep) {
+  await page.evaluate(new Function(`
+    ${isVisible}
+    const tabs = [...document.querySelectorAll('[role="tab"]')].filter(isVisible);
+    tabs.forEach(tab => { try { tab.click(); } catch {} });
+  `)).catch(() => {
+  });
+  await sleep(400);
+  await page.evaluate(new Function(`
+    ${isVisible}
+    const nextBtns = [...document.querySelectorAll(
+      'button[aria-label*="next" i], button[aria-label*="forward" i], button[aria-label*="right" i], ' +
+      '[class*="carousel" i] button, [class*="slider" i] button, [data-direction="next"]'
+    )].filter(isVisible);
+    // Click next up to 3 times per carousel
+    for (let i = 0; i < 3; i++) {
+      nextBtns.forEach(btn => { try { btn.click(); } catch {} });
+    }
+  `)).catch(() => {
+  });
+  await sleep(400);
+  await page.evaluate(new Function(`
+    ${isVisible}
+    document.querySelectorAll(
+      '[data-state="closed"] button, [aria-expanded="false"], ' +
+      'details:not([open]) > summary, [class*="accordion" i] button'
+    ).forEach(el => {
+      if (isVisible(el)) { try { el.click(); } catch {} }
+    });
+  `)).catch(() => {
+  });
+  await sleep(300);
+  await page.evaluate(() => {
+    window.scrollTo({ top: document.body.scrollHeight, behavior: "instant" });
+  }).catch(() => {
+  });
+  await sleep(300);
+  await page.evaluate(() => {
+    window.scrollTo({ top: 0, behavior: "instant" });
+  }).catch(() => {
+  });
+}
+async function validateAndCaptureSession(appUrl, creds, llmConfig, captchaOpts, loginInstructions) {
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const userAgent = await getNonHeadlessUserAgent(chromium.executablePath());
+    const contextOpts = { userAgent };
+    if (creds.httpBasicUsername && creds.httpBasicPassword) {
+      contextOpts.httpCredentials = { username: creds.httpBasicUsername, password: creds.httpBasicPassword };
+    }
+    const context = await browser.newContext(contextOpts);
+    const page = await context.newPage();
+    const getOneTimeCode = creds.totpSecret ? async () => generateTOTP(creds.totpSecret) : void 0;
+    let loggedIn;
+    try {
+      loggedIn = await login(page, appUrl, {
+        username: creds.username,
+        password: creds.password,
+        getOneTimeCode
+      });
+    } catch (loginErr) {
+      const shotBuf = await page.screenshot({ type: "jpeg", quality: 60, fullPage: false }).catch(() => null);
+      throw Object.assign(loginErr, {
+        failureScreenshot: shotBuf ? shotBuf.toString("base64") : null
+      });
+    }
+    if (!loggedIn && llmConfig) {
+      let sh = null;
+      try {
+        const { Stagehand } = await import("@browserbasehq/stagehand");
+        const { loginWithStagehand } = await import("./ai-login.js");
+        sh = new Stagehand({
+          env: "LOCAL",
+          model: { modelName: llmConfig.modelName, apiKey: llmConfig.apiKey },
+          serverCache: false,
+          verbose: 0,
+          localBrowserLaunchOptions: { headless: true, args: [`--user-agent=${userAgent}`] }
+        });
+        await sh.init();
+        const shPage = await sh.resolvePage();
+        await shPage.goto(appUrl, { waitUntil: "networkidle", timeout: 3e4 }).catch(() => {
+        });
+        const shLoggedIn = await loginWithStagehand(
+          sh,
+          { username: creds.username, password: creds.password, getOneTimeCode },
+          appUrl,
+          captchaOpts,
+          void 0,
+          loginInstructions
+        );
+        if (shLoggedIn) {
+          const shCtx = sh.context ?? sh.browserContext;
+          if (shCtx) {
+            const shState = await shCtx.storageState();
+            const shCookies = shState.cookies?.length ?? 0;
+            const shLocalStorage = shState.origins?.reduce((s, o) => s + (o.localStorage?.length ?? 0), 0) ?? 0;
+            if (shCookies > 0 || shLocalStorage > 0) {
+              await sh.close().catch(() => {
+              });
+              sh = null;
+              return { storageState: JSON.stringify(shState), cookies: shCookies, localStorage: shLocalStorage };
+            }
+          }
+          loggedIn = true;
+        }
+      } catch (shErr) {
+        const msg = String(shErr?.message ?? shErr);
+        if (msg.includes("CAPTCHA") || shErr?.isSSOError) throw shErr;
+      } finally {
+        if (sh) await sh.close().catch(() => {
+        });
+      }
+    }
+    if (!loggedIn) {
+      const shotBuf = await page.screenshot({ type: "jpeg", quality: 60, fullPage: false }).catch(() => null);
+      const challenge = await page.evaluate(() => {
+        const text = (document.body?.innerText ?? "").toLowerCase();
+        const hasCloudflare = /verify you are human|checking your browser|cloudflare|cf-challenge|turnstile/.test(text) || !!document.querySelector('iframe[src*="challenges.cloudflare.com"], .cf-turnstile, [data-sitekey]');
+        const hasCaptcha = hasCloudflare || /captcha|recaptcha|hcaptcha/.test(text) || !!document.querySelector('iframe[src*="recaptcha"], iframe[src*="hcaptcha"], #captcha, .captcha, [id*="captcha"], [class*="captcha"]');
+        return { hasCloudflare, hasCaptcha };
+      }).catch(() => ({ hasCloudflare: false, hasCaptcha: false }));
+      const message = challenge.hasCloudflare ? "Cloudflare human verification blocked headless validation. This cannot be bypassed reliably in code; use Live Browser or manual session capture, configure a CAPTCHA solver, or allowlist the crawler IP." : challenge.hasCaptcha ? "A CAPTCHA blocked headless validation. Configure CAPTCHA Auto-Solve or use Live Browser/manual session capture." : "Login failed \u2014 credentials rejected or the login flow requires a manual/SSO step. Check credentials, saved login instructions, or use Live Browser session capture.";
+      const err = Object.assign(new Error(message), {
+        failureScreenshot: shotBuf ? shotBuf.toString("base64") : null,
+        reason: challenge.hasCloudflare ? "CLOUDFLARE_CHALLENGE" : challenge.hasCaptcha ? "CAPTCHA_CHALLENGE" : "LOGIN_NOT_CONFIRMED"
+      });
+      throw err;
+    }
+    await page.waitForLoadState("networkidle", { timeout: 8e3 }).catch(() => {
+    });
+    const finalUrl = page.url();
+    await exploreAppAfterLogin(page);
+    const state = await context.storageState();
+    const cookies = state.cookies?.length ?? 0;
+    const localStorage = state.origins?.reduce(
+      (sum, o) => sum + (o.localStorage?.length ?? 0),
+      0
+    ) ?? 0;
+    if (cookies === 0 && localStorage === 0) {
+      throw new Error("Login appeared to succeed but no session data was captured \u2014 try manual session capture instead");
+    }
+    return { storageState: JSON.stringify(state), cookies, localStorage, finalUrl };
+  } finally {
+    await browser.close().catch(() => {
+    });
+  }
+}
+export {
+  cancelSessionCapture,
+  completeSessionCapture,
+  startSessionCapture,
+  validateAndCaptureSession
+};
+//# sourceMappingURL=session-capture.js.map

package/dist/session-capture.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/session-capture.ts"],
+  "sourcesContent": ["import { chromium } from 'playwright';\nimport { randomBytes } from 'node:crypto';\nimport { login } from './auth.js';\nimport { generateTOTP } from './job-queue.js';\nimport { getNonHeadlessUserAgent } from './crawler.js';\n\ninterface CaptureSession {\n  browser: any;\n  context: any;\n  timer: ReturnType<typeof setTimeout>;\n}\n\nconst activeSessions = new Map<string, CaptureSession>();\n\n/**\n * Opens a headed (visible) browser at appUrl and returns a captureId.\n * The user logs in manually, then calls completeSessionCapture() to harvest storageState.\n * Sessions expire after 10 minutes if not completed.\n *\n * Throws 'HEADLESS_ENV' if running in Docker/Linux without a display server.\n * The API route surfaces this as a 503 so the frontend can switch to manual JSON paste.\n */\nexport async function startSessionCapture(appUrl: string): Promise<string> {\n  const inDocker = process.env.PLAYWRIGHT_IN_DOCKER === 'true';\n  const noDisplay = process.platform === 'linux' && !process.env.DISPLAY;\n  if (inDocker || noDisplay) {\n    throw new Error('HEADLESS_ENV');\n  }\n\n  const id = randomBytes(16).toString('hex');\n  const browser = await chromium.launch({ headless: false });\n  const userAgent = await getNonHeadlessUserAgent(chromium.executablePath());\n  const context = await browser.newContext({ userAgent });\n  const page = await context.newPage();\n  await page.goto(appUrl, { waitUntil: 'domcontentloaded' }).catch(() => {});\n  const timer = setTimeout(() => cancelSessionCapture(id).catch(() => {}), 10 * 60 * 1000);\n  activeSessions.set(id, { browser, context, timer });\n  return id;\n}\n\n/** Captures storageState from the open browser, closes it, and returns the JSON string. */\nexport async function completeSessionCapture(captureId: string): Promise<string> {\n  const session = activeSessions.get(captureId);\n  if (!session) throw new Error('Capture session not found or expired.');\n  clearTimeout(session.timer);\n  const state = await session.context.storageState();\n  await session.browser.close().catch(() => {});\n  activeSessions.delete(captureId);\n  return JSON.stringify(state);\n}\n\n/** Closes the browser without capturing \u2014 called on Cancel. */\nexport async function cancelSessionCapture(captureId: string): Promise<void> {\n  const session = activeSessions.get(captureId);\n  if (!session) return;\n  clearTimeout(session.timer);\n  await session.browser.close().catch(() => {});\n  activeSessions.delete(captureId);\n}\n\n/**\n * Post-login exploration: navigates nav links, cycles tabs, advances carousels,\n * opens accordions, scrolls \u2014 so the browser accumulates full session state before capture.\n * All best-effort: never throws, never fails the capture.\n */\nasync function exploreAppAfterLogin(page: any): Promise<void> {\n  const sleep = (ms: number) => page.waitForTimeout(ms).catch(() => {});\n\n  const isVisible = `\n    function isVisible(el) {\n      const s = window.getComputedStyle(el);\n      if (s.display === 'none' || s.visibility === 'hidden' || parseFloat(s.opacity) < 0.1) return false;\n      const r = el.getBoundingClientRect();\n      return r.width > 4 && r.height > 4;\n    }\n  `;\n\n  try {\n    const origin = await page.evaluate(() => location.origin).catch(() => '');\n    const startUrl = await page.evaluate(() => location.href).catch(() => '');\n\n    // \u2500\u2500 1. Expand collapsed nav menus / hamburgers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    await page.evaluate(new Function(`\n      ${isVisible}\n      const inBadCtx = el => {\n        let p = el.parentElement;\n        while (p) {\n          const role = p.getAttribute('role') ?? '';\n          if (['dialog','alertdialog','combobox','listbox'].includes(role)) return true;\n          p = p.parentElement;\n        }\n        return false;\n      };\n      const targets = new Set();\n      document.querySelectorAll('[aria-haspopup]:not([aria-expanded=\"true\"])').forEach(el => {\n        if (isVisible(el) && !inBadCtx(el)) targets.add(el);\n      });\n      document.querySelectorAll('[aria-expanded=\"false\"]').forEach(el => {\n        if ((el.tagName === 'BUTTON' || el.getAttribute('role') === 'button') && isVisible(el) && !inBadCtx(el)) targets.add(el);\n      });\n      document.querySelectorAll('[data-state=\"closed\"],[data-headlessui-state=\"closed\"]').forEach(el => {\n        if ((el.tagName === 'BUTTON' || el.getAttribute('role') === 'button') && isVisible(el) && !inBadCtx(el)) targets.add(el);\n      });\n      targets.forEach(el => { try { el.click(); } catch {} });\n    `) as () => void).catch(() => {});\n    await sleep(600);\n\n    // \u2500\u2500 2. Collect nav links from the expanded DOM \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    const navLinks: string[] = await page.evaluate(new Function(`\n      ${isVisible}\n      const links = new Set();\n      const navEls = document.querySelectorAll('nav a, [role=\"navigation\"] a, aside a, header a');\n      navEls.forEach(a => {\n        const href = a.getAttribute('href');\n        if (!href || href.startsWith('#') || href.startsWith('mailto:') || href.startsWith('tel:')) return;\n        if (!isVisible(a)) return;\n        try {\n          const url = new URL(href, location.href);\n          if (url.origin === location.origin) links.add(url.href);\n        } catch {}\n      });\n      return [...links].slice(0, 10); // cap at 10 nav pages\n    `) as () => string[]).catch(() => []);\n\n    // Dismiss opened menus before navigating\n    await page.keyboard?.press('Escape').catch(() => {});\n    await sleep(200);\n\n    // \u2500\u2500 3. Visit each nav link, interact, return \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    for (const link of navLinks) {\n      try {\n        if (link === startUrl) continue;\n        await page.goto(link, { waitUntil: 'networkidle', timeout: 15_000 }).catch(() => {});\n        await sleep(400);\n        await interactWithCurrentPage(page, isVisible, sleep);\n      } catch { /* skip broken page */ }\n    }\n\n    // Return to start page\n    if (navLinks.length > 0) {\n      await page.goto(startUrl, { waitUntil: 'networkidle', timeout: 15_000 }).catch(() => {});\n      await sleep(400);\n    }\n\n    // \u2500\u2500 4. Final interaction pass on landing page \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    await interactWithCurrentPage(page, isVisible, sleep);\n\n    await page.waitForLoadState('networkidle', { timeout: 5_000 }).catch(() => {});\n  } catch {\n    // Exploration is best-effort\n  }\n}\n\n/** Interacts with tabs, carousels, accordions, and scrolls on the current page. */\nasync function interactWithCurrentPage(page: any, isVisible: string, sleep: (ms: number) => Promise<void>): Promise<void> {\n  // Cycle through tabs\n  await page.evaluate(new Function(`\n    ${isVisible}\n    const tabs = [...document.querySelectorAll('[role=\"tab\"]')].filter(isVisible);\n    tabs.forEach(tab => { try { tab.click(); } catch {} });\n  `) as () => void).catch(() => {});\n  await sleep(400);\n\n  // Advance carousels (next buttons)\n  await page.evaluate(new Function(`\n    ${isVisible}\n    const nextBtns = [...document.querySelectorAll(\n      'button[aria-label*=\"next\" i], button[aria-label*=\"forward\" i], button[aria-label*=\"right\" i], ' +\n      '[class*=\"carousel\" i] button, [class*=\"slider\" i] button, [data-direction=\"next\"]'\n    )].filter(isVisible);\n    // Click next up to 3 times per carousel\n    for (let i = 0; i < 3; i++) {\n      nextBtns.forEach(btn => { try { btn.click(); } catch {} });\n    }\n  `) as () => void).catch(() => {});\n  await sleep(400);\n\n  // Open closed accordions / disclosure panels\n  await page.evaluate(new Function(`\n    ${isVisible}\n    document.querySelectorAll(\n      '[data-state=\"closed\"] button, [aria-expanded=\"false\"], ' +\n      'details:not([open]) > summary, [class*=\"accordion\" i] button'\n    ).forEach(el => {\n      if (isVisible(el)) { try { el.click(); } catch {} }\n    });\n  `) as () => void).catch(() => {});\n  await sleep(300);\n\n  // Scroll to bottom then back to top\n  await page.evaluate(() => { window.scrollTo({ top: document.body.scrollHeight, behavior: 'instant' }); }).catch(() => {});\n  await sleep(300);\n  await page.evaluate(() => { window.scrollTo({ top: 0, behavior: 'instant' }); }).catch(() => {});\n}\n\n/**\n * Headless login + session capture \u2014 works on Docker/cloud (no display needed).\n * Tries DOM-based login first (fast, free). If it fails and llmConfig is provided,\n * falls back to Stagehand AI-guided login (handles modals, multi-step, marketing pages).\n *\n * Returns { storageState, cookies, localStorage } on success.\n * Throws a human-readable error on failure.\n */\nexport async function validateAndCaptureSession(\n  appUrl: string,\n  creds: {\n    username: string; password: string; totpSecret?: string;\n    httpBasicUsername?: string; httpBasicPassword?: string;\n  },\n  llmConfig?: { modelName: string; apiKey: string },\n  captchaOpts?: { apiKey?: string; provider?: '2captcha' | 'capsolver' },\n  loginInstructions?: string,\n): Promise<{ storageState: string; cookies: number; localStorage: number; finalUrl?: string }> {\n  const browser = await chromium.launch({ headless: true });\n  try {\n    const userAgent = await getNonHeadlessUserAgent(chromium.executablePath());\n    const contextOpts: any = { userAgent };\n    if (creds.httpBasicUsername && creds.httpBasicPassword) {\n      contextOpts.httpCredentials = { username: creds.httpBasicUsername, password: creds.httpBasicPassword };\n    }\n    const context = await browser.newContext(contextOpts);\n    const page = await context.newPage();\n\n    const getOneTimeCode = creds.totpSecret\n      ? async () => generateTOTP(creds.totpSecret!)\n      : undefined;\n\n    let loggedIn: boolean;\n    try {\n      loggedIn = await login(page, appUrl, {\n        username: creds.username,\n        password: creds.password,\n        getOneTimeCode,\n      });\n    } catch (loginErr: any) {\n      // login() throws when it can read a real error message from the page\n      const shotBuf = await page.screenshot({ type: 'jpeg', quality: 60, fullPage: false }).catch(() => null);\n      throw Object.assign(loginErr, {\n        failureScreenshot: shotBuf ? shotBuf.toString('base64') : null,\n      });\n    }\n\n    // Stagehand AI fallback when DOM login fails and LLM config is available\n    if (!loggedIn && llmConfig) {\n      let sh: any = null;\n      try {\n        const { Stagehand } = await import('@browserbasehq/stagehand');\n        const { loginWithStagehand } = await import('./ai-login.js');\n        sh = new Stagehand({\n          env: 'LOCAL',\n          model: { modelName: llmConfig.modelName as any, apiKey: llmConfig.apiKey },\n          serverCache: false,\n          verbose: 0,\n          localBrowserLaunchOptions: { headless: true, args: [`--user-agent=${userAgent}`] },\n        });\n        await sh.init();\n        const shPage = await (sh as any).resolvePage();\n        await shPage.goto(appUrl, { waitUntil: 'networkidle', timeout: 30_000 }).catch(() => {});\n        const shLoggedIn = await loginWithStagehand(\n          sh,\n          { username: creds.username, password: creds.password, getOneTimeCode },\n          appUrl,\n          captchaOpts,\n          undefined,\n          loginInstructions,\n        );\n        if (shLoggedIn) {\n          const shCtx = (sh as any).context ?? (sh as any).browserContext;\n          if (shCtx) {\n            const shState = await shCtx.storageState();\n            const shCookies = shState.cookies?.length ?? 0;\n            const shLocalStorage = shState.origins?.reduce((s: number, o: any) => s + (o.localStorage?.length ?? 0), 0) ?? 0;\n            if (shCookies > 0 || shLocalStorage > 0) {\n              await sh.close().catch(() => {});\n              sh = null;\n              return { storageState: JSON.stringify(shState), cookies: shCookies, localStorage: shLocalStorage };\n            }\n          }\n          loggedIn = true; // Stagehand succeeded but we'll capture from the plain browser context below\n        }\n      } catch (shErr: any) {\n        const msg = String(shErr?.message ?? shErr);\n        if (msg.includes('CAPTCHA') || shErr?.isSSOError) throw shErr;\n        // Stagehand failed silently \u2014 fall through to \"credentials rejected\"\n      } finally {\n        if (sh) await sh.close().catch(() => {});\n      }\n    }\n\n    if (!loggedIn) {\n      const shotBuf = await page.screenshot({ type: 'jpeg', quality: 60, fullPage: false }).catch(() => null);\n      const challenge = await page.evaluate(() => {\n        const text = (document.body?.innerText ?? '').toLowerCase();\n        const hasCloudflare = /verify you are human|checking your browser|cloudflare|cf-challenge|turnstile/.test(text) ||\n          !!document.querySelector('iframe[src*=\"challenges.cloudflare.com\"], .cf-turnstile, [data-sitekey]');\n        const hasCaptcha = hasCloudflare || /captcha|recaptcha|hcaptcha/.test(text) ||\n          !!document.querySelector('iframe[src*=\"recaptcha\"], iframe[src*=\"hcaptcha\"], #captcha, .captcha, [id*=\"captcha\"], [class*=\"captcha\"]');\n        return { hasCloudflare, hasCaptcha };\n      }).catch(() => ({ hasCloudflare: false, hasCaptcha: false }));\n      const message = challenge.hasCloudflare\n        ? 'Cloudflare human verification blocked headless validation. This cannot be bypassed reliably in code; use Live Browser or manual session capture, configure a CAPTCHA solver, or allowlist the crawler IP.'\n        : challenge.hasCaptcha\n          ? 'A CAPTCHA blocked headless validation. Configure CAPTCHA Auto-Solve or use Live Browser/manual session capture.'\n          : 'Login failed \u2014 credentials rejected or the login flow requires a manual/SSO step. Check credentials, saved login instructions, or use Live Browser session capture.';\n      const err = Object.assign(new Error(message), {\n        failureScreenshot: shotBuf ? shotBuf.toString('base64') : null,\n        reason: challenge.hasCloudflare ? 'CLOUDFLARE_CHALLENGE' : challenge.hasCaptcha ? 'CAPTCHA_CHALLENGE' : 'LOGIN_NOT_CONFIRMED',\n      });\n      throw err;\n    }\n\n    // Wait for post-login navigation to settle before capturing session\n    await page.waitForLoadState('networkidle', { timeout: 8_000 }).catch(() => {});\n\n    // Capture post-login landing URL before exploration navigates away\n    const finalUrl = page.url();\n\n    // Post-login exploration: navigate tabs, expand menus, scroll to trigger lazy-loaded state\n    await exploreAppAfterLogin(page);\n\n    const state = await context.storageState();\n    const cookies = state.cookies?.length ?? 0;\n    const localStorage = state.origins?.reduce(\n      (sum, o) => sum + (o.localStorage?.length ?? 0), 0\n    ) ?? 0;\n\n    if (cookies === 0 && localStorage === 0) {\n      throw new Error('Login appeared to succeed but no session data was captured \u2014 try manual session capture instead');\n    }\n\n    return { storageState: JSON.stringify(state), cookies, localStorage, finalUrl };\n  } finally {\n    await browser.close().catch(() => {});\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/session-export.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a Playwright storageState (the format ZeTa already captures via
+ * session-capture.ts/live-view.ts and stores per-project) into snippets for
+ * other automation frameworks. Playwright's storageState is the de-facto
+ * standard for browser session export — see docs/UNIVERSAL-SESSION-CAPTURE-
+ * STRATEGY.md — so every other framework's import mechanism is a small,
+ * mechanical conversion away, not a new capture flow.
+ *
+ * Pure, dependency-free functions — no I/O, no network, fully unit-testable.
+ */
+export interface StorageStateCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+export interface StorageStateOrigin {
+    origin: string;
+    localStorage: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+export interface StorageState {
+    cookies: StorageStateCookie[];
+    origins: StorageStateOrigin[];
+}
+export type SessionExportFormat = 'cypress' | 'selenium-python' | 'webdriverio';
+/** cy.setCookie() + localStorage.setItem() inside a reusable custom command,
+ *  following Cypress's documented cy.session() pattern (see references in
+ *  docs/UNIVERSAL-SESSION-CAPTURE-STRATEGY.md). */
+export declare function toCypressSnippet(state: StorageState): string;
+/** driver.add_cookie() (Selenium requires the browser already be on the
+ *  cookie's domain before adding it) + execute_script() for localStorage,
+ *  per Selenium's documented Cookie API. */
+export declare function toSeleniumPythonDict(state: StorageState): string;
+/** browser.setCookies() accepts an array shape very close to Playwright's own
+ *  cookie objects (per WebdriverIO's documented API) — closest 1:1 mapping
+ *  of the three target formats. */
+export declare function toWebdriverIOSnippet(state: StorageState): string;
+export declare function exportSessionAs(format: SessionExportFormat, state: StorageState): {
+    content: string;
+    filename: string;
+    mimeType: string;
+};

package/dist/session-export.js

@@ -0,0 +1,117 @@
+function jsStringLiteral(s) {
+  return JSON.stringify(s);
+}
+function pythonDictLiteral(obj) {
+  const parts = Object.entries(obj).map(([k, v]) => {
+    let repr;
+    if (typeof v === "boolean") repr = v ? "True" : "False";
+    else if (v === null || v === void 0) repr = "None";
+    else if (typeof v === "number") repr = String(v);
+    else repr = JSON.stringify(v);
+    return `${JSON.stringify(k)}: ${repr}`;
+  });
+  return `{${parts.join(", ")}}`;
+}
+function toCypressSnippet(state) {
+  const cookieLines = state.cookies.map((c) => {
+    const opts = [`domain: ${jsStringLiteral(c.domain)}`, `path: ${jsStringLiteral(c.path)}`];
+    if (c.secure) opts.push("secure: true");
+    if (c.httpOnly) opts.push("httpOnly: true");
+    if (c.sameSite) opts.push(`sameSite: ${jsStringLiteral(c.sameSite.toLowerCase())}`);
+    return `  cy.setCookie(${jsStringLiteral(c.name)}, ${jsStringLiteral(c.value)}, { ${opts.join(", ")} });`;
+  });
+  const localStorageBlocks = state.origins.filter((o) => o.localStorage.length > 0).map((o) => {
+    const sets = o.localStorage.map((kv) => `      window.localStorage.setItem(${jsStringLiteral(kv.name)}, ${jsStringLiteral(kv.value)});`).join("\n");
+    return `  cy.visit(${jsStringLiteral(o.origin)});
+  cy.window().then((window) => {
+${sets}
+  });`;
+  });
+  return [
+    "// Generated by ZeTa-AI \u2014 restores a captured browser session in Cypress.",
+    "// Usage: import this file and call restoreZetaSession() inside cy.session(), e.g.:",
+    "//   cy.session('zeta-session', restoreZetaSession)",
+    "Cypress.Commands.add('restoreZetaSession', () => {",
+    ...cookieLines,
+    ...localStorageBlocks,
+    "});"
+  ].join("\n");
+}
+function toSeleniumPythonDict(state) {
+  const byDomain = /* @__PURE__ */ new Map();
+  for (const c of state.cookies) {
+    const list = byDomain.get(c.domain) ?? [];
+    list.push(c);
+    byDomain.set(c.domain, list);
+  }
+  const lines = [
+    "# Generated by ZeTa-AI \u2014 restores a captured browser session in Selenium.",
+    "# Selenium requires the driver to already be on a matching domain before",
+    "# add_cookie() will accept a cookie for it \u2014 navigate first, then restore.",
+    "def restore_zeta_session(driver):"
+  ];
+  for (const [domain, cookies] of byDomain) {
+    lines.push(`    driver.get(${JSON.stringify(`https://${domain.replace(/^\./, "")}`)})`);
+    for (const c of cookies) {
+      const cookieDict = { name: c.name, value: c.value, path: c.path };
+      if (c.expires && c.expires > 0) cookieDict.expiry = Math.floor(c.expires);
+      if (c.secure) cookieDict.secure = true;
+      lines.push(`    driver.add_cookie(${pythonDictLiteral(cookieDict)})`);
+    }
+  }
+  for (const o of state.origins) {
+    if (o.localStorage.length === 0) continue;
+    lines.push(`    driver.get(${JSON.stringify(o.origin)})`);
+    for (const kv of o.localStorage) {
+      lines.push(
+        `    driver.execute_script(${JSON.stringify(`window.localStorage.setItem(arguments[0], arguments[1]);`)}, ${JSON.stringify(kv.name)}, ${JSON.stringify(kv.value)})`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+function toWebdriverIOSnippet(state) {
+  const cookies = state.cookies.map((c) => ({
+    name: c.name,
+    value: c.value,
+    domain: c.domain,
+    path: c.path,
+    secure: !!c.secure,
+    httpOnly: !!c.httpOnly,
+    ...c.expires && c.expires > 0 ? { expiry: Math.floor(c.expires) } : {}
+  }));
+  const localStorageSets = state.origins.filter((o) => o.localStorage.length > 0).map((o) => {
+    const sets = o.localStorage.map((kv) => `    localStorage.setItem(${jsStringLiteral(kv.name)}, ${jsStringLiteral(kv.value)});`).join("\n");
+    return `  await browser.url(${jsStringLiteral(o.origin)});
+  await browser.execute(() => {
+${sets}
+  });`;
+  });
+  return [
+    "// Generated by ZeTa-AI \u2014 restores a captured browser session in WebdriverIO.",
+    "async function restoreZetaSession(browser) {",
+    `  await browser.setCookies(${JSON.stringify(cookies, null, 2).split("\n").join("\n  ")});`,
+    ...localStorageSets,
+    "}",
+    "module.exports = { restoreZetaSession };"
+  ].join("\n");
+}
+function exportSessionAs(format, state) {
+  switch (format) {
+    case "cypress":
+      return { content: toCypressSnippet(state), filename: "zeta-session.cy-commands.js", mimeType: "application/javascript" };
+    case "selenium-python":
+      return { content: toSeleniumPythonDict(state), filename: "zeta_session.py", mimeType: "text/x-python" };
+    case "webdriverio":
+      return { content: toWebdriverIOSnippet(state), filename: "zeta-session.wdio.js", mimeType: "application/javascript" };
+    default:
+      throw new Error(`Unknown session export format: ${format}`);
+  }
+}
+export {
+  exportSessionAs,
+  toCypressSnippet,
+  toSeleniumPythonDict,
+  toWebdriverIOSnippet
+};
+//# sourceMappingURL=session-export.js.map

package/dist/session-export.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/session-export.ts"],
+  "sourcesContent": ["/**\n * Converts a Playwright storageState (the format ZeTa already captures via\n * session-capture.ts/live-view.ts and stores per-project) into snippets for\n * other automation frameworks. Playwright's storageState is the de-facto\n * standard for browser session export \u2014 see docs/UNIVERSAL-SESSION-CAPTURE-\n * STRATEGY.md \u2014 so every other framework's import mechanism is a small,\n * mechanical conversion away, not a new capture flow.\n *\n * Pure, dependency-free functions \u2014 no I/O, no network, fully unit-testable.\n */\n\nexport interface StorageStateCookie {\n  name: string;\n  value: string;\n  domain: string;\n  path: string;\n  expires?: number;\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: 'Strict' | 'Lax' | 'None';\n}\n\nexport interface StorageStateOrigin {\n  origin: string;\n  localStorage: Array<{ name: string; value: string }>;\n}\n\nexport interface StorageState {\n  cookies: StorageStateCookie[];\n  origins: StorageStateOrigin[];\n}\n\nexport type SessionExportFormat = 'cypress' | 'selenium-python' | 'webdriverio';\n\nfunction jsStringLiteral(s: string): string {\n  return JSON.stringify(s);\n}\n\n/** Python dict-literal repr \u2014 JSON.stringify's `true`/`false`/`null` aren't\n *  valid Python (Python needs `True`/`False`/`None`), so a plain\n *  JSON.stringify would emit syntactically invalid Python for any cookie\n *  with a boolean field. */\nfunction pythonDictLiteral(obj: Record<string, unknown>): string {\n  const parts = Object.entries(obj).map(([k, v]) => {\n    let repr: string;\n    if (typeof v === 'boolean') repr = v ? 'True' : 'False';\n    else if (v === null || v === undefined) repr = 'None';\n    else if (typeof v === 'number') repr = String(v);\n    else repr = JSON.stringify(v);\n    return `${JSON.stringify(k)}: ${repr}`;\n  });\n  return `{${parts.join(', ')}}`;\n}\n\n/** cy.setCookie() + localStorage.setItem() inside a reusable custom command,\n *  following Cypress's documented cy.session() pattern (see references in\n *  docs/UNIVERSAL-SESSION-CAPTURE-STRATEGY.md). */\nexport function toCypressSnippet(state: StorageState): string {\n  const cookieLines = state.cookies.map((c) => {\n    const opts: string[] = [`domain: ${jsStringLiteral(c.domain)}`, `path: ${jsStringLiteral(c.path)}`];\n    if (c.secure) opts.push('secure: true');\n    if (c.httpOnly) opts.push('httpOnly: true');\n    if (c.sameSite) opts.push(`sameSite: ${jsStringLiteral(c.sameSite.toLowerCase())}`);\n    return `  cy.setCookie(${jsStringLiteral(c.name)}, ${jsStringLiteral(c.value)}, { ${opts.join(', ')} });`;\n  });\n\n  const localStorageBlocks = state.origins\n    .filter((o) => o.localStorage.length > 0)\n    .map((o) => {\n      const sets = o.localStorage\n        .map((kv) => `      window.localStorage.setItem(${jsStringLiteral(kv.name)}, ${jsStringLiteral(kv.value)});`)\n        .join('\\n');\n      return `  cy.visit(${jsStringLiteral(o.origin)});\\n  cy.window().then((window) => {\\n${sets}\\n  });`;\n    });\n\n  return [\n    '// Generated by ZeTa-AI \u2014 restores a captured browser session in Cypress.',\n    '// Usage: import this file and call restoreZetaSession() inside cy.session(), e.g.:',\n    \"//   cy.session('zeta-session', restoreZetaSession)\",\n    \"Cypress.Commands.add('restoreZetaSession', () => {\",\n    ...cookieLines,\n    ...localStorageBlocks,\n    '});',\n  ].join('\\n');\n}\n\n/** driver.add_cookie() (Selenium requires the browser already be on the\n *  cookie's domain before adding it) + execute_script() for localStorage,\n *  per Selenium's documented Cookie API. */\nexport function toSeleniumPythonDict(state: StorageState): string {\n  const byDomain = new Map<string, StorageStateCookie[]>();\n  for (const c of state.cookies) {\n    const list = byDomain.get(c.domain) ?? [];\n    list.push(c);\n    byDomain.set(c.domain, list);\n  }\n\n  const lines: string[] = [\n    '# Generated by ZeTa-AI \u2014 restores a captured browser session in Selenium.',\n    '# Selenium requires the driver to already be on a matching domain before',\n    '# add_cookie() will accept a cookie for it \u2014 navigate first, then restore.',\n    'def restore_zeta_session(driver):',\n  ];\n\n  for (const [domain, cookies] of byDomain) {\n    lines.push(`    driver.get(${JSON.stringify(`https://${domain.replace(/^\\./, '')}`)})`);\n    for (const c of cookies) {\n      const cookieDict: Record<string, unknown> = { name: c.name, value: c.value, path: c.path };\n      if (c.expires && c.expires > 0) cookieDict.expiry = Math.floor(c.expires);\n      if (c.secure) cookieDict.secure = true;\n      lines.push(`    driver.add_cookie(${pythonDictLiteral(cookieDict)})`);\n    }\n  }\n\n  for (const o of state.origins) {\n    if (o.localStorage.length === 0) continue;\n    lines.push(`    driver.get(${JSON.stringify(o.origin)})`);\n    for (const kv of o.localStorage) {\n      lines.push(\n        `    driver.execute_script(${JSON.stringify(`window.localStorage.setItem(arguments[0], arguments[1]);`)}, ${JSON.stringify(kv.name)}, ${JSON.stringify(kv.value)})`,\n      );\n    }\n  }\n\n  return lines.join('\\n');\n}\n\n/** browser.setCookies() accepts an array shape very close to Playwright's own\n *  cookie objects (per WebdriverIO's documented API) \u2014 closest 1:1 mapping\n *  of the three target formats. */\nexport function toWebdriverIOSnippet(state: StorageState): string {\n  const cookies = state.cookies.map((c) => ({\n    name: c.name,\n    value: c.value,\n    domain: c.domain,\n    path: c.path,\n    secure: !!c.secure,\n    httpOnly: !!c.httpOnly,\n    ...(c.expires && c.expires > 0 ? { expiry: Math.floor(c.expires) } : {}),\n  }));\n\n  const localStorageSets = state.origins\n    .filter((o) => o.localStorage.length > 0)\n    .map((o) => {\n      const sets = o.localStorage\n        .map((kv) => `    localStorage.setItem(${jsStringLiteral(kv.name)}, ${jsStringLiteral(kv.value)});`)\n        .join('\\n');\n      return `  await browser.url(${jsStringLiteral(o.origin)});\\n  await browser.execute(() => {\\n${sets}\\n  });`;\n    });\n\n  return [\n    '// Generated by ZeTa-AI \u2014 restores a captured browser session in WebdriverIO.',\n    'async function restoreZetaSession(browser) {',\n    `  await browser.setCookies(${JSON.stringify(cookies, null, 2).split('\\n').join('\\n  ')});`,\n    ...localStorageSets,\n    '}',\n    'module.exports = { restoreZetaSession };',\n  ].join('\\n');\n}\n\nexport function exportSessionAs(format: SessionExportFormat, state: StorageState): { content: string; filename: string; mimeType: string } {\n  switch (format) {\n    case 'cypress':\n      return { content: toCypressSnippet(state), filename: 'zeta-session.cy-commands.js', mimeType: 'application/javascript' };\n    case 'selenium-python':\n      return { content: toSeleniumPythonDict(state), filename: 'zeta_session.py', mimeType: 'text/x-python' };\n    case 'webdriverio':\n      return { content: toWebdriverIOSnippet(state), filename: 'zeta-session.wdio.js', mimeType: 'application/javascript' };\n    default:\n      throw new Error(`Unknown session export format: ${format}`);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/shadow-dom-crawler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shadow DOM crawler — enumerate shadow hosts and detect web component libraries.
+ *
+ * Walks the live DOM recursively (up to depth 8) to find all open shadow roots
+ * and custom elements with closed shadow roots, then classifies the component
+ * framework in use. Results feed ZeTa's test generator so it can account for
+ * elements that are invisible to standard Playwright locators.
+ */
+export interface ShadowInteractiveEl {
+    role: string;
+    label: string;
+    type: string;
+    tagName: string;
+}
+export interface ShadowHostInfo {
+    tagName: string;
+    hostId: string;
+    shadowMode: 'open' | 'closed';
+    depth: number;
+    interactiveCount: number;
+    interactiveElements: ShadowInteractiveEl[];
+    slotNames: string[];
+    childShadowHosts: number;
+}
+export interface ShadowDomCrawlResult {
+    shadowHostCount: number;
+    openShadowCount: number;
+    closedShadowCount: number;
+    maxNestingDepth: number;
+    hosts: ShadowHostInfo[];
+    totalInteractiveInShadow: number;
+    detectedLibraries: string[];
+    blindSpots: string[];
+}
+export declare function crawlShadowDom(page: any): Promise<ShadowDomCrawlResult>;