feat(core): adopt IBS utility patterns + opt-in login flow

Adopts non-login and login structural patterns from israeli-bank-scrapers
as pure additions — no existing adapters are affected.

Non-login utilities (waiting.ts, fetch-utils.ts, adapter-utils.ts):
- waitUntil / raceTimeout / runSerial / sleep / TimeoutError primitives
- fetchGetWithinPage / fetchPostWithinPage (in-page fetch using browser cookies)
- fetchGet / fetchPost / fetchGraphql (Node-side helpers)
- Navigation: waitForRedirect, waitForUrl, getCurrentUrl
- Element: fillInput, clickButton, setValue, elementPresentOnPage,
  waitUntilElementFound, waitUntilElementDisappear, waitUntilIframeFound,
  pageEval, pageEvalAll
- Misc: maskHeadlessUserAgent, getFromSessionStorage, chunk
- preparePage? lifecycle hook on SiteAdapter (wired in SessionManager)

Opt-in login flow (login-flow.ts, types.ts):
- AuthErrorType union + LoginError class for structured MCP error responses
- LoginOptions / PossibleLoginResults types (URL/regex/predicate matching)
- withLoginFlow() utility — form-fill + result detection
- getLoginOptions?() optional hook on SiteAdapter
- handleAuthFailure: tries automated login first when getLoginOptions defined;
  falls back to human-handoff on transient errors; throws LoginError on
  definitive failures (INVALID_PASSWORD, ACCOUNT_BLOCKED, etc.)
- wrapToolCall catches LoginError and returns typed MCP error to the client

CI: fix duplicate patchright instances causing TS2322 in E2E adapter build
by removing patchright from the adapter's devDeps before npm install,
letting npm deduplicate to core's instance.

Tests: 107 unit tests in core (16 login-flow, 22 adapter-utils-ibs,
13 waiting, 11 fetch-utils) — all passing.

Made-with: Cursor

Author: jonzarecki

.github/workflows/ci.yml

@@ -48,6 +48,9 @@ jobs:
             const pkg = JSON.parse(require('fs').readFileSync('package.json'));
             pkg.devDependencies['@browserkit/core'] = 'file:../core';
             pkg.peerDependencies['@browserkit/core'] = '>=0.1.0';
+            // Remove patchright from adapter devDeps so npm deduplicates to core's
+            // instance — prevents duplicate Page types causing TS2322 errors.
+            delete pkg.devDependencies['patchright'];
             require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2));
           "
           npm install

packages/core/src/adapter-server.ts

@@ -16,6 +16,7 @@ import { LockManager } from "./lock-manager.js";
 import { RateLimiter } from "./rate-limiter.js";
 import { buildHandoffResult, handleAuthFailure, isBackgroundLoginInProgress } from "./human-handoff.js";
 import { screenshotOnError, screenshotToContent, detectRateLimit } from "./adapter-utils.js";
+import { LoginError } from "./types.js";
 import { getLogger } from "./logger.js";
 
 const log = getLogger("adapter-server");
@@ -76,20 +77,30 @@ export async function createAdapterServer(
 
       let page: Page;
       try {
-        page = await sessionManager.getPage(sessionConfig);
+        page = await sessionManager.getPage(sessionConfig, adapter);
       } catch (err) {
         return errorResult(`Failed to get browser page: ${String(err)}`);
       }
 
       const loggedIn = await adapter.isLoggedIn(page);
       if (!loggedIn) {
-        const reauthed = await handleAuthFailure(sessionManager, sessionConfig, adapter);
+        let reauthed: boolean;
+        try {
+          reauthed = await handleAuthFailure(sessionManager, sessionConfig, adapter);
+        } catch (err) {
+          if (err instanceof LoginError) {
+            return errorResult(
+              `Login failed (${err.errorType}): ${err.message}`
+            );
+          }
+          throw err;
+        }
         if (!reauthed) {
           return buildHandoffResult(adapter, isBackgroundLoginInProgress(adapter.site)) as {
             content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: "image/png" }>;
           };
         }
-        page = await sessionManager.getPage(sessionConfig);
+        page = await sessionManager.getPage(sessionConfig, adapter);
       }
 
       const tool = adapter.tools().find((t) => t.name === toolName);

packages/core/src/adapter-utils.ts

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
-import type { Page, Locator } from "patchright";
+import type { Page, Locator, Frame } from "patchright";
 import type { SelectorReport, ToolContent } from "./types.js";
+import { waitUntil, sleep } from "./waiting.js";
 
 /**
  * Validate a map of named CSS selector strings against the current page state.
@@ -136,10 +137,6 @@ export async function screenshotOnError(
   return filePath;
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 /**
  * Detect rate limiting or security challenges after a navigation.
  *
@@ -378,3 +375,276 @@ export async function detectAuthBarrier(page: Page, quick = true): Promise<strin
     return null; // never throw — page errors should not break callers
   }
 }
+
+// ── Navigation utilities ──────────────────────────────────────────────────────
+// Ported from israeli-bank-scrapers helpers/navigation.ts — adapted for Playwright/Patchright.
+
+/**
+ * Get the current page URL. When `clientSide` is true, reads from
+ * `window.location.href` instead of the Playwright/Patchright URL — necessary
+ * for SPAs that use the History API, where the framework URL lags behind.
+ */
+export function getCurrentUrl(page: Page | Frame, clientSide = false): Promise<string> {
+  if (clientSide) {
+    return page.evaluate(() => window.location.href);
+  }
+  return Promise.resolve(page.url());
+}
+
+/**
+ * Poll until the page URL changes from its current value.
+ *
+ * `ignoreList` lets you skip intermediate redirect URLs (e.g. a loading page
+ * that appears between the start URL and the final destination).
+ *
+ * Use `clientSide: true` for SPAs where `page.waitForNavigation()` never fires
+ * because there is no real HTTP navigation.
+ */
+export async function waitForRedirect(
+  page: Page | Frame,
+  timeout = 20_000,
+  clientSide = false,
+  ignoreList: string[] = [],
+): Promise<void> {
+  const initial = await getCurrentUrl(page, clientSide);
+  await waitUntil(
+    async () => {
+      const current = await getCurrentUrl(page, clientSide);
+      return current !== initial && !ignoreList.includes(current);
+    },
+    `waiting for redirect from ${initial}`,
+    timeout,
+    1_000,
+  );
+}
+
+/**
+ * Poll until the page URL exactly matches `url` (string) or matches the
+ * regex pattern. Useful for confirming SPA navigation completed.
+ */
+export async function waitForUrl(
+  page: Page | Frame,
+  url: string | RegExp,
+  timeout = 20_000,
+  clientSide = false,
+): Promise<void> {
+  await waitUntil(
+    async () => {
+      const current = await getCurrentUrl(page, clientSide);
+      return url instanceof RegExp ? url.test(current) : url === current;
+    },
+    `waiting for url to be ${String(url)}`,
+    timeout,
+    1_000,
+  );
+}
+
+// ── Element interaction helpers ───────────────────────────────────────────────
+// Ported from israeli-bank-scrapers helpers/elements-interactions.ts.
+// These wrap Playwright's Locator API with ergonomic defaults.
+
+/**
+ * Fill an input field with `value`, replacing any existing content.
+ * Triggers input and change events (correct for React controlled components).
+ */
+export async function fillInput(
+  page: Page | Frame,
+  selector: string,
+  value: string,
+): Promise<void> {
+  await page.locator(selector).fill(value);
+}
+
+/**
+ * Click a button or element by selector.
+ */
+export async function clickButton(
+  page: Page | Frame,
+  selector: string,
+): Promise<void> {
+  await page.locator(selector).click();
+}
+
+/**
+ * Set an input's `.value` property directly without firing keyboard events.
+ * Use this when the site reads `.value` directly rather than listening for
+ * input/change events (non-React forms, legacy apps).
+ */
+export async function setValue(
+  page: Page | Frame,
+  selector: string,
+  value: string,
+): Promise<void> {
+  await page.locator(selector).evaluate(
+    (el, v) => { (el as HTMLInputElement).value = v; },
+    value,
+  );
+}
+
+/**
+ * Return true if at least one element matching `selector` exists in the DOM
+ * right now. Does not wait — use `waitUntilElementFound` for polling.
+ */
+export async function elementPresentOnPage(
+  page: Page | Frame,
+  selector: string,
+): Promise<boolean> {
+  return (await page.locator(selector).count()) > 0;
+}
+
+/**
+ * Wait until an element matching `selector` is present in the DOM.
+ *
+ * @param isVisible  When true, also waits for the element to be visible.
+ * @param timeout    Override the default Playwright timeout (ms).
+ */
+export async function waitUntilElementFound(
+  page: Page | Frame,
+  selector: string,
+  isVisible = false,
+  timeout?: number,
+): Promise<void> {
+  await page.waitForSelector(selector, {
+    state: isVisible ? "visible" : "attached",
+    ...(timeout !== undefined ? { timeout } : {}),
+  });
+}
+
+/**
+ * Wait until an element matching `selector` disappears from the DOM (or
+ * becomes hidden). Useful for waiting out loading spinners.
+ */
+export async function waitUntilElementDisappear(
+  page: Page | Frame,
+  selector: string,
+  timeout?: number,
+): Promise<void> {
+  await page.waitForSelector(selector, {
+    state: "hidden",
+    ...(timeout !== undefined ? { timeout } : {}),
+  });
+}
+
+/**
+ * Wait until a frame matching `framePredicate` appears among the page's frames.
+ * Returns the matched frame.
+ *
+ * Uses `waitUntil` internally so it respects `timeout` and `description`.
+ */
+export async function waitUntilIframeFound(
+  page: Page,
+  framePredicate: (frame: Frame) => boolean,
+  description = "waiting for iframe",
+  timeout = 30_000,
+): Promise<Frame> {
+  let found: Frame | undefined;
+  await waitUntil(
+    () => {
+      found = page.frames().find(framePredicate);
+      return Promise.resolve(found ?? null);
+    },
+    description,
+    timeout,
+    1_000,
+  );
+  if (!found) throw new Error("failed to find iframe");
+  return found;
+}
+
+/**
+ * Typed `$eval` with graceful missing-element handling.
+ *
+ * When no element matches `selector`, returns `defaultResult` instead of
+ * throwing — eliminating the try/catch boilerplate every adapter needs.
+ */
+export async function pageEval<R>(
+  page: Page | Frame,
+  selector: string,
+  defaultResult: R,
+  callback: (element: Element) => R,
+): Promise<R> {
+  try {
+    const locator = page.locator(selector);
+    if ((await locator.count()) === 0) return defaultResult;
+    return await locator.first().evaluate(callback);
+  } catch {
+    return defaultResult;
+  }
+}
+
+/**
+ * Typed `$$eval` with graceful missing-element handling.
+ *
+ * Calls `callback` with all matching elements. When the selector matches
+ * nothing, `evaluateAll` passes an empty array to the callback. On any
+ * error, returns `defaultResult`.
+ */
+export async function pageEvalAll<R>(
+  page: Page | Frame,
+  selector: string,
+  defaultResult: R,
+  callback: (elements: Element[]) => R,
+): Promise<R> {
+  try {
+    return await page.locator(selector).evaluateAll(callback);
+  } catch {
+    return defaultResult;
+  }
+}
+
+// ── Miscellaneous browser utilities ──────────────────────────────────────────
+// Ported from israeli-bank-scrapers helpers/browser.ts and helpers/storage.ts.
+
+/**
+ * Strip "HeadlessChrome/" from the navigator user agent string so headless
+ * Chrome reports as regular Chrome. Call from `preparePage` to apply once at
+ * startup before any navigation.
+ *
+ * Uses `addInitScript` so the override takes effect in every frame and
+ * survives cross-origin navigations.
+ */
+export async function maskHeadlessUserAgent(page: Page): Promise<void> {
+  const raw = await page.evaluate(() => navigator.userAgent);
+  const masked = raw.replace("HeadlessChrome/", "Chrome/");
+  await page.addInitScript(
+    (ua: string) => {
+      Object.defineProperty(navigator, "userAgent", { get: () => ua });
+    },
+    masked,
+  );
+}
+
+/**
+ * Read and JSON-parse a value from the page's `sessionStorage`.
+ * Returns null if the key is absent or the value is not valid JSON.
+ *
+ * Useful for sites (e.g. Visa Cal) that store auth tokens in sessionStorage
+ * rather than cookies.
+ */
+export async function getFromSessionStorage<T>(
+  page: Page,
+  key: string,
+): Promise<T | null> {
+  const raw = await page.evaluate((k: string) => sessionStorage.getItem(k), key);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Split an array into chunks of at most `size` elements.
+ *
+ * @example
+ * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
+ */
+export function chunk<T>(array: T[], size: number): T[][] {
+  if (size <= 0) throw new Error(`chunk size must be positive, got ${size}`);
+  const chunks: T[][] = [];
+  for (let i = 0; i < array.length; i += size) {
+    chunks.push(array.slice(i, i + size));
+  }
+  return chunks;
+}