browserclaw 0.11.6 → 0.12.0

package/dist/index.cjs

@@ -1573,6 +1573,7 @@ ${stderrOutput.slice(0, 2e3)}` : "";
     userDataDir,
     cdpPort,
     startedAt,
+    launchMs: Date.now() - startedAt,
     proc
   };
 }
@@ -6327,6 +6328,137 @@ var CrawlPage = class {
       pollMs: opts?.pollMs
     });
   }
+  // ── Auth Health ──────────────────────────────────────────────
+  /**
+   * Check whether the current page session appears authenticated.
+   *
+   * Evaluates one or more rules against the page state. All rules must pass
+   * for `authenticated` to be `true`. Returns per-rule details for debugging.
+   *
+   * @param rules - Array of auth check rules (url, cookie, selector, text, textGone, fn)
+   * @returns Authentication status and per-rule check details
+   *
+   * @example
+   * ```ts
+   * // Check by URL and absence of login text
+   * const result = await page.isAuthenticated([
+   *   { url: '/dashboard' },
+   *   { textGone: 'Sign in' },
+   * ]);
+   * if (!result.authenticated) {
+   *   console.log('Auth failed:', result.checks.filter(c => !c.passed));
+   * }
+   *
+   * // Check by cookie presence
+   * const result = await page.isAuthenticated([{ cookie: 'session_id' }]);
+   *
+   * // Check with custom JS function
+   * const result = await page.isAuthenticated([
+   *   { fn: '() => !!document.querySelector("[data-user-id]")' },
+   * ]);
+   * ```
+   */
+  async isAuthenticated(rules) {
+    if (!rules.length) return { authenticated: true, checks: [] };
+    const page = await getRestoredPageForTarget({ cdpUrl: this.cdpUrl, targetId: this.targetId });
+    const checks = [];
+    for (const rule of rules) {
+      if (rule.url !== void 0) {
+        const currentUrl = page.url();
+        const passed = currentUrl.includes(rule.url);
+        checks.push({ rule: "url", passed, detail: passed ? currentUrl : `expected "${rule.url}" in "${currentUrl}"` });
+      }
+      if (rule.cookie !== void 0) {
+        const cookies = await page.context().cookies();
+        const found = cookies.some((c) => c.name === rule.cookie && c.value !== "");
+        checks.push({
+          rule: "cookie",
+          passed: found,
+          detail: found ? `cookie "${rule.cookie}" present` : `cookie "${rule.cookie}" missing or empty`
+        });
+      }
+      if (rule.selector !== void 0) {
+        try {
+          const count = await page.locator(rule.selector).count();
+          const passed = count > 0;
+          checks.push({
+            rule: "selector",
+            passed,
+            detail: passed ? `"${rule.selector}" found (${String(count)})` : `"${rule.selector}" not found`
+          });
+        } catch (err) {
+          console.warn(
+            `[browserclaw] isAuthenticated selector check failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+          checks.push({ rule: "selector", passed: false, detail: `"${rule.selector}" error during evaluation` });
+        }
+      }
+      if (rule.text !== void 0 || rule.textGone !== void 0) {
+        let bodyText = null;
+        try {
+          const raw = await evaluateViaPlaywright({
+            cdpUrl: this.cdpUrl,
+            targetId: this.targetId,
+            fn: '() => { const b = document.body; return b ? b.innerText : ""; }'
+          });
+          bodyText = typeof raw === "string" ? raw : null;
+        } catch (err) {
+          console.warn(
+            `[browserclaw] isAuthenticated body text fetch failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        if (rule.text !== void 0) {
+          if (bodyText === null) {
+            checks.push({ rule: "text", passed: false, detail: `"${rule.text}" error during evaluation` });
+          } else {
+            const passed = bodyText.includes(rule.text);
+            checks.push({
+              rule: "text",
+              passed,
+              detail: passed ? `"${rule.text}" found` : `"${rule.text}" not found in page text`
+            });
+          }
+        }
+        if (rule.textGone !== void 0) {
+          if (bodyText === null) {
+            checks.push({ rule: "textGone", passed: false, detail: `"${rule.textGone}" error during evaluation` });
+          } else {
+            const passed = !bodyText.includes(rule.textGone);
+            checks.push({
+              rule: "textGone",
+              passed,
+              detail: passed ? `"${rule.textGone}" absent (good)` : `"${rule.textGone}" still present`
+            });
+          }
+        }
+      }
+      if (rule.fn !== void 0) {
+        try {
+          const result = await evaluateViaPlaywright({
+            cdpUrl: this.cdpUrl,
+            targetId: this.targetId,
+            fn: rule.fn
+          });
+          const passed = result !== null && result !== void 0 && result !== false && result !== 0 && result !== "";
+          checks.push({
+            rule: "fn",
+            passed,
+            detail: passed ? "function returned truthy" : `function returned ${JSON.stringify(result)}`
+          });
+        } catch (err) {
+          checks.push({
+            rule: "fn",
+            passed: false,
+            detail: `function threw: ${err instanceof Error ? err.message : String(err)}`
+          });
+        }
+      }
+    }
+    return {
+      authenticated: checks.length > 0 && checks.every((c) => c.passed),
+      checks
+    };
+  }
   // ── Playwright Escape Hatches ─────────────────────────────────
   /**
    * Get the underlying Playwright `Page` object for this tab.
@@ -6385,9 +6517,11 @@ var BrowserClaw = class _BrowserClaw {
   ssrfPolicy;
   recordVideo;
   chrome;
-  constructor(cdpUrl, chrome, ssrfPolicy, recordVideo) {
+  _telemetry;
+  constructor(cdpUrl, chrome, telemetry, ssrfPolicy, recordVideo) {
     this.cdpUrl = cdpUrl;
     this.chrome = chrome;
+    this._telemetry = telemetry;
     this.ssrfPolicy = ssrfPolicy;
     this.recordVideo = recordVideo;
   }
@@ -6416,13 +6550,21 @@ var BrowserClaw = class _BrowserClaw {
    * ```
    */
   static async launch(opts = {}) {
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const chrome = await launchChrome(opts);
     const cdpUrl = `http://127.0.0.1:${String(chrome.cdpPort)}`;
     const ssrfPolicy = opts.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
-    const browser = new _BrowserClaw(cdpUrl, chrome, ssrfPolicy, opts.recordVideo);
+    const telemetry = {
+      launchMs: chrome.launchMs,
+      timestamps: { startedAt, launchedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    };
+    const browser = new _BrowserClaw(cdpUrl, chrome, telemetry, ssrfPolicy, opts.recordVideo);
     if (opts.url !== void 0 && opts.url !== "") {
       const page = await browser.currentPage();
+      const navT0 = Date.now();
       await page.goto(opts.url);
+      telemetry.navMs = Date.now() - navT0;
+      telemetry.timestamps.navigatedAt = (/* @__PURE__ */ new Date()).toISOString();
     }
     return browser;
   }
@@ -6441,6 +6583,8 @@ var BrowserClaw = class _BrowserClaw {
    * ```
    */
   static async connect(cdpUrl, opts) {
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const connectT0 = Date.now();
     let resolvedUrl = cdpUrl;
     if (resolvedUrl === void 0 || resolvedUrl === "") {
       const discovered = await discoverChromeCdpUrl();
@@ -6456,7 +6600,11 @@ var BrowserClaw = class _BrowserClaw {
     }
     await connectBrowser(resolvedUrl, opts?.authToken);
     const ssrfPolicy = opts?.allowInternal === true ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts?.ssrfPolicy;
-    return new _BrowserClaw(resolvedUrl, null, ssrfPolicy, opts?.recordVideo);
+    const telemetry = {
+      connectMs: Date.now() - connectT0,
+      timestamps: { startedAt, connectedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    };
+    return new _BrowserClaw(resolvedUrl, null, telemetry, ssrfPolicy, opts?.recordVideo);
   }
   /**
    * Open a URL in a new tab and return the page handle.
@@ -6485,7 +6633,12 @@ var BrowserClaw = class _BrowserClaw {
    * @returns CrawlPage for the first/active page
    */
   async currentPage() {
+    const connectT0 = Date.now();
     const { browser } = await connectBrowser(this.cdpUrl);
+    if (this._telemetry.connectMs === void 0) {
+      this._telemetry.connectMs = Date.now() - connectT0;
+      this._telemetry.timestamps.connectedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
     const pages = getAllPages(browser);
     if (!pages.length) throw new Error("No pages available. Use browser.open(url) to create a tab.");
     const tid = await pageTargetId(pages[0]).catch(() => null);
@@ -6562,15 +6715,61 @@ var BrowserClaw = class _BrowserClaw {
    * If the browser was launched by `BrowserClaw.launch()`, the Chrome process
    * will be terminated. If connected via `BrowserClaw.connect()`, only the
    * Playwright connection is closed.
+   *
+   * @param exitReason - Optional structured reason for stopping (e.g. `'success'`, `'auth_failed'`, `'timeout'`)
    */
-  async stop() {
-    clearRecordingContext(this.cdpUrl);
-    await disconnectBrowser();
-    if (this.chrome) {
-      await stopChrome(this.chrome);
-      this.chrome = null;
+  async stop(exitReason) {
+    this._telemetry.timestamps.stoppedAt = (/* @__PURE__ */ new Date()).toISOString();
+    if (exitReason !== void 0) this._telemetry.exitReason = exitReason;
+    try {
+      clearRecordingContext(this.cdpUrl);
+      await disconnectBrowser();
+      if (this.chrome) {
+        await stopChrome(this.chrome);
+        this.chrome = null;
+      }
+      this._telemetry.cleanupOk = true;
+    } catch (err) {
+      this._telemetry.cleanupOk = false;
+      throw err;
     }
   }
+  /**
+   * Get structured telemetry for this browser session.
+   *
+   * Returns timing data, timestamps, and exit information collected
+   * throughout the session lifecycle. Useful for diagnosing startup
+   * latency, auth failures, and cleanup issues in cron/unattended runs.
+   *
+   * @returns Telemetry envelope with launch/connect/nav timings and exit info
+   *
+   * @example
+   * ```ts
+   * const browser = await BrowserClaw.launch({ url: 'https://example.com' });
+   * const page = await browser.currentPage();
+   *
+   * // ... do work ...
+   *
+   * const auth = await page.isAuthenticated([{ cookie: 'session' }]);
+   * browser.recordAuthResult(auth.authenticated);
+   *
+   * await browser.stop(auth.authenticated ? 'success' : 'auth_failed');
+   * console.log(browser.telemetry());
+   * // { launchMs: 1823, connectMs: 45, navMs: 620, authOk: true,
+   * //   exitReason: 'success', cleanupOk: true, timestamps: { ... } }
+   * ```
+   */
+  telemetry() {
+    return this._telemetry;
+  }
+  /**
+   * Record the result of an authentication check in the telemetry envelope.
+   *
+   * @param ok - Whether authentication was successful
+   */
+  recordAuthResult(ok) {
+    this._telemetry.authOk = ok;
+  }
 };
 
 exports.BlockedBrowserTargetError = BlockedBrowserTargetError;