browser.ts

/**
 * Helper module for connecting to a remote headless browser
 * 
 * Usage:
 *   import { connectBrowser, getPage } from './browser';
 *   
 *   // Connect and get a page
 *   const { browser, page } = await getPage();
 *   await page.goto('https://example.com');
 *   
 *   // Or just connect
 *   const browser = await connectBrowser();
 *   const page = await browser.newPage();
 */

import puppeteer, { type Browser, type Page } from 'puppeteer-core';

/**
 * Get the browser WebSocket URL from environment
 */
export function getBrowserUrl(): string {
  const url = process.env.BROWSER_URL;
  if (!url) {
    throw new Error(
      'BROWSER_URL environment variable is required.\n' +
      'Usage: BROWSER_URL=$(./spawn-headless-browser.sh) bun your-script.ts'
    );
  }
  return url;
}

/**
 * Connect to the remote browser
 */
export async function connectBrowser(wsEndpoint?: string): Promise<Browser> {
  const url = wsEndpoint || getBrowserUrl();
  return puppeteer.connect({ browserWSEndpoint: url });
}

/**
 * Connect to browser and create a new page
 */
export async function getPage(wsEndpoint?: string): Promise<{ browser: Browser; page: Page }> {
  const browser = await connectBrowser(wsEndpoint);
  const page = await browser.newPage();
  return { browser, page };
}

/**
 * Run a function with a browser page, automatically cleaning up
 */
export async function withPage<T>(
  fn: (page: Page, browser: Browser) => Promise<T>,
  wsEndpoint?: string
): Promise<T> {
  const { browser, page } = await getPage(wsEndpoint);
  try {
    return await fn(page, browser);
  } finally {
    await page.close();
    browser.disconnect();
  }
}

// Re-export puppeteer types for convenience
export { type Browser, type Page } from 'puppeteer-core';
export { default as puppeteer } from 'puppeteer-core';