browser-commander 0.2.0

package/src/factory.js

@@ -0,0 +1,192 @@
+/**
+ * Browser Commander - Factory Function
+ * This module provides the makeBrowserCommander factory function that creates
+ * a browser commander instance with all bound methods.
+ */
+
+import { createLogger } from './core/logger.js';
+import { detectEngine } from './core/engine-detection.js';
+import { createNetworkTracker } from './core/network-tracker.js';
+import { createNavigationManager } from './core/navigation-manager.js';
+import { createPageSessionFactory } from './core/page-session.js';
+import {
+  createPageTriggerManager,
+  ActionStoppedError,
+  isActionStoppedError,
+  makeUrlCondition,
+  allConditions,
+  anyCondition,
+  notCondition,
+} from './core/page-trigger-manager.js';
+import { createBoundFunctions } from './bindings.js';
+
+/**
+ * Create a browser commander instance for a specific page
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Playwright or Puppeteer page object
+ * @param {boolean} options.verbose - Enable verbose logging
+ * @param {boolean} options.enableNetworkTracking - Enable network request tracking (default: true)
+ * @param {boolean} options.enableNavigationManager - Enable navigation manager (default: true)
+ * @returns {Object} - Browser commander API
+ */
+export function makeBrowserCommander(options = {}) {
+  const {
+    page,
+    verbose = false,
+    enableNetworkTracking = true,
+    enableNavigationManager = true,
+  } = options;
+
+  if (!page) {
+    throw new Error('page is required in options');
+  }
+
+  const engine = detectEngine(page);
+  const log = createLogger({ verbose });
+
+  // Create NetworkTracker if enabled
+  // Use 30 second idle timeout to ensure page is fully loaded
+  let networkTracker = null;
+  if (enableNetworkTracking) {
+    networkTracker = createNetworkTracker({
+      page,
+      engine,
+      log,
+      idleTimeout: 30000, // Wait 30 seconds without requests before considering network idle
+    });
+    networkTracker.startTracking();
+  }
+
+  // Create NavigationManager if enabled
+  let navigationManager = null;
+  let sessionFactory = null;
+
+  // PageTriggerManager (will be initialized after commander is created)
+  let pageTriggerManager = null;
+
+  if (enableNavigationManager) {
+    navigationManager = createNavigationManager({
+      page,
+      engine,
+      log,
+      networkTracker,
+    });
+    navigationManager.startListening();
+
+    // Create PageSession factory
+    sessionFactory = createPageSessionFactory({
+      navigationManager,
+      networkTracker,
+      log,
+    });
+
+    // Create PageTriggerManager
+    pageTriggerManager = createPageTriggerManager({
+      navigationManager,
+      log,
+    });
+  }
+
+  // Create all bound functions
+  const boundFunctions = createBoundFunctions({
+    page,
+    engine,
+    log,
+    verbose,
+    navigationManager,
+    networkTracker,
+  });
+
+  // Cleanup function
+  const destroy = async () => {
+    if (pageTriggerManager) {
+      await pageTriggerManager.destroy();
+    }
+    if (networkTracker) {
+      networkTracker.stopTracking();
+    }
+    if (navigationManager) {
+      navigationManager.stopListening();
+    }
+    if (sessionFactory) {
+      await sessionFactory.endAllSessions();
+    }
+  };
+
+  // Build commander object
+  const commander = {
+    // Core properties
+    engine,
+    page,
+    log,
+
+    // Navigation management components
+    networkTracker,
+    navigationManager,
+    sessionFactory,
+    pageTriggerManager,
+
+    // All bound functions
+    ...boundFunctions,
+
+    // Lifecycle
+    destroy,
+
+    // Convenience methods for page sessions (legacy API)
+    createSession: sessionFactory
+      ? (opts) => sessionFactory.createSession(opts)
+      : null,
+    getActiveSessions: sessionFactory
+      ? () => sessionFactory.getActiveSessions()
+      : () => [],
+
+    // Subscribe to navigation events (legacy API)
+    onNavigationStart: navigationManager
+      ? (fn) => navigationManager.on('onNavigationStart', fn)
+      : () => {},
+    onNavigationComplete: navigationManager
+      ? (fn) => navigationManager.on('onNavigationComplete', fn)
+      : () => {},
+    onUrlChange: navigationManager
+      ? (fn) => navigationManager.on('onUrlChange', fn)
+      : () => {},
+    onPageReady: navigationManager
+      ? (fn) => navigationManager.on('onPageReady', fn)
+      : () => {},
+
+    // Abort handling - check these to stop operations when navigation occurs
+    shouldAbort: navigationManager
+      ? () => navigationManager.shouldAbort()
+      : () => false,
+    getAbortSignal: navigationManager
+      ? () => navigationManager.getAbortSignal()
+      : () => null,
+
+    // Page Trigger API
+    // Register a trigger: commander.pageTrigger({ condition, action, name })
+    // condition receives context: { url, commander }
+    // action receives context: { url, commander, checkStopped, forEach, wait, onCleanup, ... }
+    pageTrigger: pageTriggerManager
+      ? (config) => pageTriggerManager.pageTrigger(config)
+      : () => {
+          throw new Error('pageTrigger requires enableNavigationManager: true');
+        },
+
+    // URL condition helpers
+    makeUrlCondition,
+    allConditions,
+    anyCondition,
+    notCondition,
+
+    // Error classes for action control flow
+    ActionStoppedError,
+    isActionStoppedError,
+  };
+
+  // Initialize PageTriggerManager with the commander
+  if (pageTriggerManager) {
+    pageTriggerManager.initialize(commander);
+  }
+
+  return commander;
+}

package/src/high-level/universal-logic.js

@@ -0,0 +1,206 @@
+/**
+ * Universal high-level functions following DRY principles
+ * These are pure functions that work with any browser automation engine
+ */
+
+import {
+  isNavigationError,
+  withNavigationSafety,
+} from '../core/navigation-safety.js';
+
+/**
+ * Wait indefinitely for a URL condition with custom check function
+ * @param {Object} options - Configuration options
+ * @param {Function} options.getUrl - Function to get current URL
+ * @param {Function} options.wait - Wait function
+ * @param {Function} options.evaluate - Evaluate function
+ * @param {string} options.targetUrl - Target URL to wait for
+ * @param {string} options.description - Description for logging
+ * @param {Function} options.customCheck - Optional custom check function (async)
+ * @param {Function} options.pageClosedCallback - Callback to check if page closed
+ * @param {number} options.pollingInterval - Polling interval in ms (default: 1000)
+ * @returns {Promise<any>} - Result from customCheck or true if URL matched
+ */
+export async function waitForUrlCondition(options = {}) {
+  const {
+    getUrl,
+    wait,
+    evaluate,
+    targetUrl,
+    description,
+    customCheck,
+    pageClosedCallback = () => false,
+    pollingInterval = 1000,
+  } = options;
+
+  if (description) {
+    console.log(`⏳ ${description}...`);
+  }
+
+  while (true) {
+    if (pageClosedCallback()) {
+      return null;
+    }
+
+    try {
+      // Run custom check if provided
+      if (customCheck) {
+        const customResult = await customCheck(getUrl());
+        if (customResult !== undefined && customResult !== null) {
+          return customResult;
+        }
+      }
+
+      // Check if target URL reached
+      const currentUrl = getUrl();
+      if (currentUrl.startsWith(targetUrl)) {
+        return true;
+      }
+    } catch (error) {
+      if (pageClosedCallback()) {
+        return null;
+      }
+
+      // Handle navigation errors gracefully
+      if (isNavigationError(error)) {
+        console.log(
+          '⚠️  Navigation detected during URL check, continuing to wait...'
+        );
+      } else {
+        console.log(
+          `⚠️  Temporary error while checking URL: ${error.message.substring(0, 100)}... (retrying)`
+        );
+      }
+    }
+
+    await wait({
+      ms: pollingInterval,
+      reason: 'polling interval before next URL check',
+    });
+  }
+}
+
+/**
+ * Install click detection listener on page
+ * @param {Object} options - Configuration options
+ * @param {Function} options.evaluate - Evaluate function
+ * @param {string} options.buttonText - Text to detect
+ * @param {string} options.storageKey - SessionStorage key to set
+ * @returns {Promise<boolean>} - True if installed, false on navigation
+ */
+export async function installClickListener(options = {}) {
+  const { evaluate, buttonText, storageKey } = options;
+
+  const safeEvaluate = withNavigationSafety(evaluate, {
+    onNavigationError: () => {
+      console.log(
+        '⚠️  Navigation detected during installClickListener, skipping'
+      );
+      return false;
+    },
+  });
+
+  const result = await safeEvaluate({
+    fn: (text, key) => {
+      document.addEventListener(
+        'click',
+        (event) => {
+          let element = event.target;
+          while (element && element !== document.body) {
+            const elementText = element.textContent?.trim() || '';
+            if (
+              elementText === text ||
+              ((element.tagName === 'A' || element.tagName === 'BUTTON') &&
+                elementText.includes(text))
+            ) {
+              console.log(`[Click Listener] Detected click on ${text} button!`);
+              window.sessionStorage.setItem(key, 'true');
+              break;
+            }
+            element = element.parentElement;
+          }
+        },
+        true
+      );
+    },
+    args: [buttonText, storageKey],
+  });
+
+  return result === false ? false : true;
+}
+
+/**
+ * Check and clear session storage flag
+ * @param {Object} options - Configuration options
+ * @param {Function} options.evaluate - Evaluate function
+ * @param {string} options.storageKey - SessionStorage key
+ * @returns {Promise<boolean>} - True if flag was set, false otherwise or on navigation
+ */
+export async function checkAndClearFlag(options = {}) {
+  const { evaluate, storageKey } = options;
+
+  const safeEvaluate = withNavigationSafety(evaluate, {
+    onNavigationError: () => {
+      console.log(
+        '⚠️  Navigation detected during checkAndClearFlag, returning false'
+      );
+      return false;
+    },
+  });
+
+  return await safeEvaluate({
+    fn: (key) => {
+      const flag = window.sessionStorage.getItem(key);
+      if (flag === 'true') {
+        window.sessionStorage.removeItem(key);
+        return true;
+      }
+      return false;
+    },
+    args: [storageKey],
+  });
+}
+
+/**
+ * Find toggle button using multiple strategies
+ * @param {Object} options - Configuration options
+ * @param {Function} options.count - Count function
+ * @param {Function} options.findByText - FindByText function
+ * @param {Array<string>} options.dataQaSelectors - Data-qa selectors to try
+ * @param {string} options.textToFind - Text to search for
+ * @param {Array<string>} options.elementTypes - Element types to search
+ * @returns {Promise<string|null>} - Selector or null
+ */
+export async function findToggleButton(options = {}) {
+  const {
+    count,
+    findByText,
+    dataQaSelectors = [],
+    textToFind,
+    elementTypes = ['button', 'a', 'span'],
+  } = options;
+
+  // Try data-qa selectors first
+  for (const sel of dataQaSelectors) {
+    const elemCount = await count({ selector: sel });
+    if (elemCount > 0) {
+      return sel;
+    }
+  }
+
+  // Fallback to text search
+  if (textToFind) {
+    for (const elementType of elementTypes) {
+      const selector = await findByText({
+        text: textToFind,
+        selector: elementType,
+      });
+      const elemCount = await count({ selector });
+      if (elemCount > 0) {
+        return selector;
+      }
+    }
+  }
+
+  return null;
+}

package/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * Browser Commander - Universal browser automation library
+ * Supports both Playwright and Puppeteer with a unified API
+ * All functions use options objects for easy maintenance
+ *
+ * Key features:
+ * - Automatic network request tracking
+ * - Navigation-aware operations (wait for page ready after navigations)
+ * - Event-based page lifecycle management
+ * - Session management for per-page automation logic
+ */
+
+// Export the factory function
+export { makeBrowserCommander } from './factory.js';
+
+// Re-export all public APIs from exports module
+export * from './exports.js';