@epsilon-asi/actors 0.0.3 → 0.0.5

package/src/extraction/Extractor.ts

@@ -0,0 +1,65 @@
+import { ExtractionError } from '../errors/ExtractionError.js';
+import type { PageAdapter } from '../interaction/PageAdapter.js';
+
+export interface TableData {
+  headers: string[];
+  rows: Array<Record<string, string>>;
+}
+
+export class Extractor {
+  constructor(private readonly page: PageAdapter) {}
+
+  text(selector: string): Promise<string> {
+    return this.page.text(selector);
+  }
+
+  textList(selector: string): Promise<string[]> {
+    return this.page.textAll(selector);
+  }
+
+  attr(selector: string, name: string): Promise<string | null> {
+    return this.page.attr(selector, name);
+  }
+
+  async hrefs(selector: string): Promise<string[]> {
+    const page = this.page.raw();
+    return page.$$eval(selector, elements =>
+      elements
+        .map(element => element.getAttribute('href'))
+        .filter((href): href is string => href !== null && href.length > 0)
+    );
+  }
+
+  async jsonLd<T = unknown>(): Promise<T[]> {
+    const page = this.page.raw();
+    return page.$$eval('script[type="application/ld+json"]', elements =>
+      elements.flatMap(element => {
+        try {
+          const text = element.textContent ?? '';
+          return text.length > 0 ? [JSON.parse(text)] : [];
+        } catch {
+          return [];
+        }
+      })
+    ) as Promise<T[]>;
+  }
+
+  async table(tableSelector: string): Promise<TableData> {
+    try {
+      return await this.page.raw().$eval(tableSelector, table => {
+        const headerCells = Array.from(table.querySelectorAll('thead th'));
+        const headers = headerCells.map(cell => (cell.textContent ?? '').replace(/\s+/g, ' ').trim());
+        const rows = Array.from(table.querySelectorAll('tbody tr')).map(row => {
+          const cells = Array.from(row.querySelectorAll('td'));
+          return Object.fromEntries(cells.map((cell, index) => [
+            headers[index] ?? `column_${index + 1}`,
+            (cell.textContent ?? '').replace(/\s+/g, ' ').trim()
+          ]));
+        });
+        return { headers, rows };
+      });
+    } catch (error) {
+      throw new ExtractionError(`Could not extract table from selector: ${tableSelector}`, { cause: error });
+    }
+  }
+}

package/src/extraction/Pagination.ts

@@ -0,0 +1,47 @@
+import type { HumanInteractor } from '../interaction/HumanInteractor.js';
+import type { PageAdapter } from '../interaction/PageAdapter.js';
+
+export interface CollectPagesOptions<T> {
+  nextSelector: string;
+  extractPage: () => Promise<T[]>;
+  maxPages?: number;
+  dedupeBy?: (item: T) => string;
+  waitAfterNextMs?: number;
+}
+
+export class Pagination {
+  constructor(
+    private readonly page: PageAdapter,
+    private readonly interactor: HumanInteractor
+  ) {}
+
+  async collectPages<T>(options: CollectPagesOptions<T>): Promise<T[]> {
+    const allItems: T[] = [];
+    const seen = new Set<string>();
+    const maxPages = options.maxPages ?? Number.POSITIVE_INFINITY;
+
+    for (let pageNumber = 1; pageNumber <= maxPages; pageNumber += 1) {
+      const pageItems = await options.extractPage();
+      for (const item of pageItems) {
+        const key = options.dedupeBy?.(item);
+        if (key !== undefined) {
+          if (seen.has(key)) continue;
+          seen.add(key);
+        }
+        allItems.push(item);
+      }
+
+      if (pageNumber >= maxPages) break;
+
+      const hasNext = await this.page.exists(options.nextSelector, { timeout: 500 });
+      if (!hasNext) break;
+
+      await this.interactor.click(options.nextSelector);
+      if ((options.waitAfterNextMs ?? 0) > 0) {
+        await new Promise(resolve => setTimeout(resolve, options.waitAfterNextMs));
+      }
+    }
+
+    return allItems;
+  }
+}

package/src/extraction/index.ts

@@ -0,0 +1,2 @@
+export * from './Extractor.js';
+export * from './Pagination.js';

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './auth/index.js';
+export * from './browser/index.js';
+export * from './core/index.js';
+export * from './errors/index.js';
+export * from './extraction/index.js';
+export * from './interaction/index.js';
+export * from './logging/index.js';
+export * from './sites/index.js';
+export * from './utils/index.js';

package/src/interaction/FieldClearer.ts

@@ -0,0 +1,73 @@
+import type { PageLike } from '../browser/PuppeteerLike.js';
+
+export type ClearFieldStrategy = 'select-delete' | 'dom-value';
+
+export interface ClearFieldOptions {
+  strategy?: ClearFieldStrategy;
+}
+
+export async function clearField(page: PageLike, selector: string, options: ClearFieldOptions = {}): Promise<void> {
+  const strategy = options.strategy ?? 'select-delete';
+
+  if (strategy === 'dom-value') {
+    await clearFieldValueInDom(page, selector);
+    return;
+  }
+
+  await selectFieldContents(page, selector);
+  await page.keyboard.press('Backspace');
+  await clearFieldValueInDom(page, selector);
+}
+
+async function selectFieldContents(page: PageLike, selector: string): Promise<void> {
+  await page.$eval(selector, element => {
+    const target = element as HTMLElement & {
+      value?: string;
+      select?: () => void;
+      setSelectionRange?: (start: number, end: number) => void;
+    };
+
+    target.focus();
+
+    if (typeof target.select === 'function') {
+      target.select();
+      target.dispatchEvent(new Event('select', { bubbles: true }));
+      return;
+    }
+
+    if (typeof target.value === 'string' && typeof target.setSelectionRange === 'function') {
+      target.setSelectionRange(0, target.value.length);
+      target.dispatchEvent(new Event('select', { bubbles: true }));
+      return;
+    }
+
+    if (target.isContentEditable) {
+      const range = document.createRange();
+      range.selectNodeContents(target);
+      const selection = window.getSelection();
+      selection?.removeAllRanges();
+      selection?.addRange(range);
+      target.dispatchEvent(new Event('select', { bubbles: true }));
+    }
+  });
+}
+
+async function clearFieldValueInDom(page: PageLike, selector: string): Promise<void> {
+  await page.$eval(selector, element => {
+    const target = element as HTMLElement & { value?: string };
+    let changed = false;
+
+    if (typeof target.value === 'string' && target.value.length > 0) {
+      target.value = '';
+      changed = true;
+    } else if (target.isContentEditable && (target.textContent ?? '').length > 0) {
+      target.textContent = '';
+      changed = true;
+    }
+
+    if (changed) {
+      target.dispatchEvent(new Event('input', { bubbles: true }));
+      target.dispatchEvent(new Event('change', { bubbles: true }));
+    }
+  });
+}

package/src/interaction/Forms.ts

@@ -0,0 +1,27 @@
+import { SelectorError } from '../errors/SelectorError.js';
+import type { HumanInteractor, HumanTypeOptions } from './HumanInteractor.js';
+import type { PageAdapter } from './PageAdapter.js';
+
+export interface FillTextOptions extends HumanTypeOptions {
+  required?: boolean;
+}
+
+export class FormFiller {
+  constructor(
+    private readonly page: PageAdapter,
+    private readonly interactor: HumanInteractor
+  ) {}
+
+  async fillText(selector: string, value: string, options: FillTextOptions = {}): Promise<void> {
+    const exists = await this.page.exists(selector, { timeout: options.timeoutMs ?? 5_000 });
+    if (!exists && (options.required ?? true)) {
+      throw new SelectorError(`Required form field not found: ${selector}`, selector);
+    }
+    if (!exists) return;
+    await this.interactor.type(selector, value, options);
+  }
+
+  async click(selector: string): Promise<void> {
+    await this.interactor.click(selector);
+  }
+}

package/src/interaction/GhostCursorAdapter.ts

@@ -0,0 +1,79 @@
+import { GhostCursor } from 'ghost-cursor';
+import type { WaitForSelectorOptions } from 'puppeteer-core';
+import type { PageLike } from '../browser/PuppeteerLike.js';
+import { clearField } from './FieldClearer.js';
+import type { HumanClickOptions, HumanInteractor, HumanMoveOptions, HumanTypeOptions } from './HumanInteractor.js';
+import { HumanTyper, mergeHumanTypingOptions, type HumanTypingOptions, type RandomFunction, type SleepFunction } from './HumanTyping.js';
+
+export interface GhostCursorLike {
+  click(selector?: string, options?: Record<string, unknown>): Promise<void>;
+  move(selector: string, options?: Record<string, unknown>): Promise<void>;
+}
+
+export interface GhostCursorAdapterOptions {
+  cursor?: GhostCursorLike;
+  cursorOptions?: Record<string, unknown>;
+  typing?: HumanTypingOptions;
+  typer?: HumanTyper;
+  sleep?: SleepFunction;
+  random?: RandomFunction;
+}
+
+function selectorWaitOptions(timeoutMs: number | undefined): WaitForSelectorOptions | undefined {
+  return timeoutMs === undefined ? undefined : { timeout: timeoutMs };
+}
+
+export class GhostCursorAdapter implements HumanInteractor {
+  private readonly cursor: GhostCursorLike;
+  private readonly typer: HumanTyper;
+  private readonly typingDefaults: HumanTypingOptions | undefined;
+
+  constructor(private readonly page: PageLike, options: GhostCursorAdapterOptions = {}) {
+    this.cursor = options.cursor ?? new GhostCursor(page as never, options.cursorOptions as never) as unknown as GhostCursorLike;
+    this.typingDefaults = options.typing;
+    this.typer = options.typer ?? new HumanTyper({
+      ...(options.typing !== undefined ? { defaults: options.typing } : {}),
+      ...(options.sleep !== undefined ? { sleep: options.sleep } : {}),
+      ...(options.random !== undefined ? { random: options.random } : {})
+    });
+  }
+
+  async click(selector: string, options: HumanClickOptions = {}): Promise<void> {
+    if (options.waitForSelector !== false) {
+      await this.page.waitForSelector(selector, selectorWaitOptions(options.timeoutMs));
+    }
+    await this.cursor.click(selector, options.cursorOptions);
+  }
+
+  async move(selector: string, options: HumanMoveOptions = {}): Promise<void> {
+    await this.page.waitForSelector(selector, selectorWaitOptions(options.timeoutMs));
+    await this.cursor.move(selector, options.cursorOptions);
+  }
+
+  async type(selector: string, value: string, options: HumanTypeOptions = {}): Promise<void> {
+    await this.page.waitForSelector(selector, selectorWaitOptions(options.timeoutMs));
+
+    if (options.clickBeforeTyping ?? true) {
+      await this.click(selector, options.timeoutMs === undefined ? undefined : { timeoutMs: options.timeoutMs });
+    } else {
+      await this.page.focus(selector);
+    }
+
+    if (options.clear ?? true) {
+      await clearField(this.page, selector, options.clearMethod === undefined ? undefined : { strategy: options.clearMethod });
+    }
+
+    await this.typer.type(
+      this.page.keyboard,
+      value,
+      mergeHumanTypingOptions(this.typingDefaults, options.typing),
+      options.delayMs
+    );
+  }
+
+  async scrollIntoView(selector: string): Promise<void> {
+    await this.page.$eval(selector, element => {
+      element.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
+    });
+  }
+}

package/src/interaction/HumanInteractor.ts

@@ -0,0 +1,32 @@
+import type { ClearFieldStrategy } from './FieldClearer.js';
+import type { HumanTypingOptions } from './HumanTyping.js';
+
+export interface HumanClickOptions {
+  waitForSelector?: boolean;
+  timeoutMs?: number;
+  cursorOptions?: Record<string, unknown>;
+}
+
+export interface HumanMoveOptions {
+  timeoutMs?: number;
+  cursorOptions?: Record<string, unknown>;
+}
+
+export interface HumanTypeOptions {
+  /** Legacy Puppeteer keyboard delay. Used as key-hold delay for human typing, or bulk delay when human typing is disabled. */
+  delayMs?: number;
+  clear?: boolean;
+  /** Defaults to selecting the field contents and pressing Backspace before typing. */
+  clearMethod?: ClearFieldStrategy;
+  clickBeforeTyping?: boolean;
+  timeoutMs?: number;
+  /** Human-like key-by-key typing configuration. Enabled by default at approximately 65 WPM. */
+  typing?: HumanTypingOptions;
+}
+
+export interface HumanInteractor {
+  click(selector: string, options?: HumanClickOptions): Promise<void>;
+  move(selector: string, options?: HumanMoveOptions): Promise<void>;
+  type(selector: string, value: string, options?: HumanTypeOptions): Promise<void>;
+  scrollIntoView(selector: string): Promise<void>;
+}

package/src/interaction/HumanTyping.ts

@@ -0,0 +1,157 @@
+import type { KeyboardLike } from '../browser/PuppeteerLike.js';
+import { delay as defaultDelay } from '../utils/delay.js';
+
+export type SleepFunction = (ms: number) => Promise<void>;
+export type RandomFunction = () => number;
+
+export interface HumanTypingOptions {
+  /** Defaults to true. When false, the whole value is sent through keyboard.type. */
+  enabled?: boolean;
+  /** Target words per minute. Defaults to 65. */
+  targetWordsPerMinute?: number;
+  /** Standard typing-speed word length. Defaults to 5 characters. */
+  averageWordLength?: number;
+  /** Symmetric per-keystroke jitter around the target interval. Defaults to ±18 ms. */
+  intervalJitterMs?: number;
+  /** Minimum inter-key interval after jitter is applied. Defaults to 20 ms. */
+  minimumIntervalMs?: number;
+  /** Optional keydown-to-keyup hold delay passed to Puppeteer's keyboard.type per character. */
+  keyHoldMs?: number;
+}
+
+export interface NormalizedHumanTypingOptions {
+  enabled: boolean;
+  targetWordsPerMinute: number;
+  averageWordLength: number;
+  intervalJitterMs: number;
+  minimumIntervalMs: number;
+  keyHoldMs: number;
+}
+
+export interface HumanTyperOptions {
+  sleep?: SleepFunction;
+  random?: RandomFunction;
+  defaults?: HumanTypingOptions;
+}
+
+export const DEFAULT_HUMAN_TYPING_OPTIONS: NormalizedHumanTypingOptions = {
+  enabled: true,
+  targetWordsPerMinute: 65,
+  averageWordLength: 5,
+  intervalJitterMs: 18,
+  minimumIntervalMs: 20,
+  keyHoldMs: 0
+};
+
+export function characterIntervalMsForWordsPerMinute(
+  targetWordsPerMinute: number,
+  averageWordLength = DEFAULT_HUMAN_TYPING_OPTIONS.averageWordLength
+): number {
+  if (!Number.isFinite(targetWordsPerMinute) || targetWordsPerMinute <= 0) {
+    throw new RangeError('targetWordsPerMinute must be greater than 0.');
+  }
+  if (!Number.isFinite(averageWordLength) || averageWordLength <= 0) {
+    throw new RangeError('averageWordLength must be greater than 0.');
+  }
+  return 60_000 / (targetWordsPerMinute * averageWordLength);
+}
+
+export function normalizeHumanTypingOptions(options: HumanTypingOptions = {}): NormalizedHumanTypingOptions {
+  const normalized = {
+    enabled: options.enabled ?? DEFAULT_HUMAN_TYPING_OPTIONS.enabled,
+    targetWordsPerMinute: options.targetWordsPerMinute ?? DEFAULT_HUMAN_TYPING_OPTIONS.targetWordsPerMinute,
+    averageWordLength: options.averageWordLength ?? DEFAULT_HUMAN_TYPING_OPTIONS.averageWordLength,
+    intervalJitterMs: options.intervalJitterMs ?? DEFAULT_HUMAN_TYPING_OPTIONS.intervalJitterMs,
+    minimumIntervalMs: options.minimumIntervalMs ?? DEFAULT_HUMAN_TYPING_OPTIONS.minimumIntervalMs,
+    keyHoldMs: options.keyHoldMs ?? DEFAULT_HUMAN_TYPING_OPTIONS.keyHoldMs
+  } satisfies NormalizedHumanTypingOptions;
+
+  if (!Number.isFinite(normalized.targetWordsPerMinute) || normalized.targetWordsPerMinute <= 0) {
+    throw new RangeError('targetWordsPerMinute must be greater than 0.');
+  }
+  if (!Number.isFinite(normalized.averageWordLength) || normalized.averageWordLength <= 0) {
+    throw new RangeError('averageWordLength must be greater than 0.');
+  }
+  if (!Number.isFinite(normalized.intervalJitterMs) || normalized.intervalJitterMs < 0) {
+    throw new RangeError('intervalJitterMs must be greater than or equal to 0.');
+  }
+  if (!Number.isFinite(normalized.minimumIntervalMs) || normalized.minimumIntervalMs < 0) {
+    throw new RangeError('minimumIntervalMs must be greater than or equal to 0.');
+  }
+  if (!Number.isFinite(normalized.keyHoldMs) || normalized.keyHoldMs < 0) {
+    throw new RangeError('keyHoldMs must be greater than or equal to 0.');
+  }
+
+  return normalized;
+}
+
+export function mergeHumanTypingOptions(
+  defaults: HumanTypingOptions | undefined,
+  overrides: HumanTypingOptions | undefined
+): HumanTypingOptions {
+  return {
+    ...(defaults ?? {}),
+    ...(overrides ?? {})
+  };
+}
+
+export function jitteredIntervalMs(
+  baseIntervalMs: number,
+  jitterMs: number,
+  minimumIntervalMs: number,
+  random: RandomFunction
+): number {
+  const normalizedRandom = Math.min(1, Math.max(0, random()));
+  const jitter = (normalizedRandom * 2 - 1) * jitterMs;
+  return Math.max(minimumIntervalMs, Math.round(baseIntervalMs + jitter));
+}
+
+function keyboardTypeOptions(delayMs: number): { delay: number } | undefined {
+  return delayMs > 0 ? { delay: delayMs } : undefined;
+}
+
+export class HumanTyper {
+  private readonly sleep: SleepFunction;
+  private readonly random: RandomFunction;
+  private readonly defaults: HumanTypingOptions | undefined;
+
+  constructor(options: HumanTyperOptions = {}) {
+    this.sleep = options.sleep ?? defaultDelay;
+    this.random = options.random ?? Math.random;
+    this.defaults = options.defaults;
+  }
+
+  async type(
+    keyboard: KeyboardLike,
+    text: string,
+    options: HumanTypingOptions = {},
+    legacyDelayMs?: number
+  ): Promise<void> {
+    const normalized = normalizeHumanTypingOptions(mergeHumanTypingOptions(this.defaults, options));
+    const keyHoldMs = options.keyHoldMs ?? this.defaults?.keyHoldMs ?? legacyDelayMs ?? normalized.keyHoldMs;
+
+    if (!normalized.enabled) {
+      await keyboard.type(text, keyboardTypeOptions(keyHoldMs));
+      return;
+    }
+
+    const baseIntervalMs = characterIntervalMsForWordsPerMinute(
+      normalized.targetWordsPerMinute,
+      normalized.averageWordLength
+    );
+    const characters = Array.from(text);
+
+    for (let index = 0; index < characters.length; index += 1) {
+      if (index > 0) {
+        await this.sleep(jitteredIntervalMs(
+          baseIntervalMs,
+          normalized.intervalJitterMs,
+          normalized.minimumIntervalMs,
+          this.random
+        ));
+      }
+
+      await keyboard.type(characters[index]!, keyboardTypeOptions(keyHoldMs));
+    }
+  }
+}

package/src/interaction/NativePuppeteerInteractor.ts

@@ -0,0 +1,68 @@
+import type { WaitForSelectorOptions } from 'puppeteer-core';
+import type { PageLike } from '../browser/PuppeteerLike.js';
+import { clearField } from './FieldClearer.js';
+import type { HumanClickOptions, HumanInteractor, HumanMoveOptions, HumanTypeOptions } from './HumanInteractor.js';
+import { HumanTyper, mergeHumanTypingOptions, type HumanTypingOptions, type RandomFunction, type SleepFunction } from './HumanTyping.js';
+
+export interface NativePuppeteerInteractorOptions {
+  typing?: HumanTypingOptions;
+  typer?: HumanTyper;
+  sleep?: SleepFunction;
+  random?: RandomFunction;
+}
+
+function selectorWaitOptions(timeoutMs: number | undefined): WaitForSelectorOptions | undefined {
+  return timeoutMs === undefined ? undefined : { timeout: timeoutMs };
+}
+
+export class NativePuppeteerInteractor implements HumanInteractor {
+  private readonly typer: HumanTyper;
+  private readonly typingDefaults: HumanTypingOptions | undefined;
+
+  constructor(private readonly page: PageLike, options: NativePuppeteerInteractorOptions = {}) {
+    this.typingDefaults = options.typing;
+    this.typer = options.typer ?? new HumanTyper({
+      ...(options.typing !== undefined ? { defaults: options.typing } : {}),
+      ...(options.sleep !== undefined ? { sleep: options.sleep } : {}),
+      ...(options.random !== undefined ? { random: options.random } : {})
+    });
+  }
+
+  async click(selector: string, options: HumanClickOptions = {}): Promise<void> {
+    if (options.waitForSelector !== false) {
+      await this.page.waitForSelector(selector, selectorWaitOptions(options.timeoutMs));
+    }
+    await this.page.click(selector);
+  }
+
+  async move(selector: string, options: HumanMoveOptions = {}): Promise<void> {
+    await this.page.waitForSelector(selector, selectorWaitOptions(options.timeoutMs));
+  }
+
+  async type(selector: string, value: string, options: HumanTypeOptions = {}): Promise<void> {
+    await this.page.waitForSelector(selector, selectorWaitOptions(options.timeoutMs));
+
+    if (options.clickBeforeTyping ?? true) {
+      await this.page.click(selector);
+    } else {
+      await this.page.focus(selector);
+    }
+
+    if (options.clear ?? true) {
+      await clearField(this.page, selector, options.clearMethod === undefined ? undefined : { strategy: options.clearMethod });
+    }
+
+    await this.typer.type(
+      this.page.keyboard,
+      value,
+      mergeHumanTypingOptions(this.typingDefaults, options.typing),
+      options.delayMs
+    );
+  }
+
+  async scrollIntoView(selector: string): Promise<void> {
+    await this.page.$eval(selector, element => {
+      element.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
+    });
+  }
+}

package/src/interaction/Navigation.ts

@@ -0,0 +1,37 @@
+import type { WaitForOptions } from 'puppeteer-core';
+import type { HumanInteractor } from './HumanInteractor.js';
+import type { PageAdapter } from './PageAdapter.js';
+import { resolveUrl } from '../utils/url.js';
+
+export interface ClickNavigationOptions {
+  waitForNavigation?: boolean;
+  navigationOptions?: WaitForOptions;
+}
+
+export class Navigator {
+  constructor(
+    private readonly page: PageAdapter,
+    private readonly interactor: HumanInteractor,
+    private readonly baseUrl: string
+  ) {}
+
+  resolve(urlOrPath: string): string {
+    return resolveUrl(this.baseUrl, urlOrPath);
+  }
+
+  async goto(urlOrPath: string, options: WaitForOptions = { waitUntil: 'domcontentloaded' }): Promise<void> {
+    await this.page.goto(this.resolve(urlOrPath), options);
+  }
+
+  async click(selector: string, options: ClickNavigationOptions = {}): Promise<void> {
+    if (options.waitForNavigation) {
+      await Promise.all([
+        this.page.waitForNavigation(options.navigationOptions ?? { waitUntil: 'domcontentloaded' }),
+        this.interactor.click(selector)
+      ]);
+      return;
+    }
+
+    await this.interactor.click(selector);
+  }
+}