nothing-browser 0.0.15 → 0.0.17

package/piggy.ts

@@ -2,324 +2,26 @@
 import { detectBinary, type BinaryMode } from "./piggy/launch/detect";
 import { spawnBrowser, killBrowser, spawnBrowserOnSocket } from "./piggy/launch/spawn";
 import { PiggyClient } from "./piggy/client";
-import { setClient, setHumanMode, createSiteObject } from "./piggy/register";
+import { setClient, setHumanMode, createSiteObject, type SiteObject } from "./piggy/register";
 import { routeRegistry, keepAliveSites, startServer, stopServer } from "./piggy/server";
+import { TabPool } from "./piggy/pool";
 import logger from "./piggy/logger";
-import type { Logger } from "ernest-logger";
-import type { Elysia } from "elysia";
-import type { RouteHandler, BeforeMiddleware, RouteConfig } from "./piggy/server";
 
-// ── Core types ───────────────────────────────────────────────────────────────
-
-export type TabMode = "tab" | "process";
-
-/** Returned by createSiteObject — full API surface of a registered site. */
-export interface SiteObject {
-  /** Internal name used when registering. */
-  _name: string;
-  /** Internal CDP / socket tab ID. */
-  _tabId: string;
-
-  // ── Navigation ─────────────────────────────────────────────────────────────
-  navigate(url?: string, opts?: { retries?: number }): Promise<void>;
-  reload(): Promise<void>;
-  goBack(): Promise<void>;
-  goForward(): Promise<void>;
-  waitForNavigation(): Promise<void>;
-
-  title(): Promise<string>;
-  /** Returns the last known URL (synchronous — does NOT hit the browser). */
-  url(): string;
-  content(): Promise<string>;
-
-  // ── Timing ────────────────────────────────────────────────────────────────
-  wait(ms: number): Promise<void>;
-  waitForSelector(selector: string, timeout?: number): Promise<void>;
-  waitForVisible(selector: string, timeout?: number): Promise<void>;
-  waitForResponse(pattern: string, timeout?: number): Promise<void>;
-
-  // ── Init script ───────────────────────────────────────────────────────────
-  addInitScript(js: string | (() => void)): Promise<SiteObject>;
-
-  // ── Event emitter ─────────────────────────────────────────────────────────
-  on(event: "navigate", handler: (url: string) => void): () => void;
-  on(event: string, handler: (data: unknown) => void): () => void;
-  off(event: string, handler: (data: unknown) => void): void;
-
-  // ── Interactions ──────────────────────────────────────────────────────────
-  click(selector: string, opts?: { retries?: number; timeout?: number }): Promise<boolean>;
-  doubleClick(selector: string): Promise<boolean>;
-  hover(selector: string): Promise<boolean>;
-  type(
-    selector: string,
-    text: string,
-    opts?: { delay?: number; retries?: number; fact?: boolean; wpm?: number }
-  ): Promise<boolean>;
-  select(selector: string, value: string): Promise<boolean>;
-  evaluate<T = unknown>(js: string | ((...args: unknown[]) => T), ...args: unknown[]): Promise<T>;
-
-  keyboard: {
-    press(key: string): Promise<boolean>;
-    combo(combo: string): Promise<boolean>;
-  };
-
-  mouse: {
-    move(x: number, y: number): Promise<boolean>;
-    drag(from: { x: number; y: number }, to: { x: number; y: number }): Promise<boolean>;
-  };
-
-  scroll: {
-    to(selector: string): Promise<boolean>;
-    by(px: number): Promise<boolean>;
-  };
-
-  // ── Fetch ─────────────────────────────────────────────────────────────────
-  fetchText(selector: string): Promise<string | null>;
-  fetchLinks(selector: string): Promise<string[]>;
-  fetchImages(selector: string): Promise<string[]>;
-
-  search: {
-    css(query: string): Promise<unknown>;
-    id(query: string): Promise<unknown>;
-  };
-
-  // ── Screenshot / PDF ──────────────────────────────────────────────────────
-  screenshot(filePath?: string): Promise<string>;
-  pdf(filePath?: string): Promise<string>;
-  blockImages(): Promise<void>;
-  unblockImages(): Promise<void>;
-
-  // ── Cookies ───────────────────────────────────────────────────────────────
-  cookies: {
-    set(name: string, value: string, domain: string, path?: string): Promise<void>;
-    get(name: string): Promise<unknown>;
-    delete(name: string): Promise<void>;
-    list(): Promise<unknown[]>;
-  };
-
-  // ── Interception ──────────────────────────────────────────────────────────
-  intercept: {
-    block(pattern: string): Promise<void>;
-    redirect(pattern: string, redirectUrl: string): Promise<void>;
-    headers(pattern: string, headers: Record<string, string>): Promise<void>;
-    respond(
-      pattern: string,
-      handlerOrResponse:
-        | { status?: number; contentType?: string; body: string }
-        | ((req: { url: string; method: string }) => {
-            status?: number;
-            contentType?: string;
-            body: string;
-          })
-    ): Promise<SiteObject>;
-    modifyResponse(
-      pattern: string,
-      handler: (response: {
-        body: string;
-        status: number;
-        headers: Record<string, string>;
-      }) => Promise<{ body?: string; status?: number; headers?: Record<string, string> } | void> | void
-    ): Promise<SiteObject>;
-    clear(): Promise<void>;
-  };
-
-  // ── Network capture ───────────────────────────────────────────────────────
-  capture: {
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    requests(): Promise<unknown[]>;
-    ws(): Promise<unknown[]>;
-    cookies(): Promise<unknown[]>;
-    storage(): Promise<unknown>;
-    clear(): Promise<void>;
-  };
-
-  // ── Session ───────────────────────────────────────────────────────────────
-  session: {
-    export(): Promise<unknown>;
-    import(data: unknown): Promise<void>;
-  };
-
-  // ── Expose / unexpose functions ───────────────────────────────────────────
-  exposeFunction(
-    fnName: string,
-    handler: (data: unknown) => Promise<unknown> | unknown
-  ): Promise<SiteObject>;
-  unexposeFunction(fnName: string): Promise<SiteObject>;
-  clearExposedFunctions(): Promise<SiteObject>;
-  exposeAndInject(
-    fnName: string,
-    handler: (data: unknown) => Promise<unknown> | unknown,
-    injectionJs: string | ((fnName: string) => string)
-  ): Promise<SiteObject>;
-
-  // ── Elysia route registration ─────────────────────────────────────────────
-  api(
-    path: string,
-    handler: RouteHandler,
-    opts?: {
-      ttl?: number;
-      before?: BeforeMiddleware[];
-      method?: "GET" | "POST" | "PUT" | "DELETE";
-    }
-  ): SiteObject;
-
-  noclose(): SiteObject;
-  close(): Promise<void>;
-}
-
-// ── Route summary returned by piggy.routes() ─────────────────────────────────
-
-export interface RouteSummary {
-  site: string;
-  method: RouteConfig["method"];
-  path: string;
-  ttl: number;
-  middlewareCount: number;
-}
-
-// ── Multi-site proxy helpers ──────────────────────────────────────────────────
-
-/**
- * Proxy that runs the same method on every site in parallel (Promise.all).
- * The return type mirrors the SiteObject API but every method returns
- * `Promise<ReturnType[]>` instead of a single value.
- */
-export type AllProxy = {
-  [K in keyof SiteObject]: SiteObject[K] extends (...args: infer A) => Promise<infer R>
-    ? (...args: A) => Promise<R[]>
-    : SiteObject[K] extends (...args: infer A) => infer R
-      ? (...args: A) => Promise<R[]>
-      : never;
-};
-
-/**
- * Proxy that runs the same method on every site in parallel and returns a
- * Record keyed by site `_name`.
- */
-export type DiffProxy = {
-  [K in keyof SiteObject]: SiteObject[K] extends (...args: infer A) => Promise<infer R>
-    ? (...args: A) => Promise<Record<string, R>>
-    : SiteObject[K] extends (...args: infer A) => infer R
-      ? (...args: A) => Promise<Record<string, R>>
-      : never;
-};
-
-// ── Launch / register option bags ────────────────────────────────────────────
-
-export interface LaunchOptions {
-  /** Whether to open a separate browser process per registered site or share a single one via tabs. Default: `"tab"`. */
-  mode?: TabMode;
-  /** Whether to run the browser binary in headed or headless mode. Default: `"headless"`. */
-  binary?: BinaryMode;
-}
-
-export interface RegisterOptions {
-  /** Override the binary mode for this site's dedicated process (only used when `mode === "process"`). */
-  binary?: BinaryMode;
-}
-
-export interface ServeOptions {
-  hostname?: string;
-}
-
-// ── The Piggy object type ─────────────────────────────────────────────────────
-
-export interface Piggy {
-  // ── Lifecycle ──────────────────────────────────────────────────────────────
-  /**
-   * Spawns the Nothing Browser binary and connects the internal socket client.
-   * Must be called before any other method.
-   */
-  launch(opts?: LaunchOptions): Promise<Piggy>;
-
-  /**
-   * Registers a named site at the given URL.
-   * After registration `piggy[name]` is available as a `SiteObject`.
-   */
-  register(name: string, url: string, opts?: RegisterOptions): Promise<Piggy>;
-
-  // ── Global controls ────────────────────────────────────────────────────────
-  /** Enables or disables human-simulation mode (random delays, typos, smooth scrolling). */
-  actHuman(enable: boolean): Piggy;
-
-  /** Changes the tab/process mode *before* the next `register()` call. */
-  mode(m: TabMode): Piggy;
-
-  // ── Global function exposure ───────────────────────────────────────────────
-  /** Exposes a Node.js function to the browser's global scope on the default (or specified) tab. */
-  expose(
-    name: string,
-    handler: (data: unknown) => Promise<unknown> | unknown,
-    tabId?: string
-  ): Promise<Piggy>;
-
-  /** Removes a previously exposed function from the browser. */
-  unexpose(name: string, tabId?: string): Promise<Piggy>;
-
-  // ── Elysia server ─────────────────────────────────────────────────────────
-  /** Starts an Elysia HTTP server that exposes all registered `.api()` routes. */
-  serve(port: number, opts?: ServeOptions): Promise<Elysia>;
-
-  /** Stops the running Elysia server. */
-  stopServer(): void;
-
-  // ── Introspection ─────────────────────────────────────────────────────────
-  /** Returns a summary of every mounted HTTP route. */
-  routes(): RouteSummary[];
-
-  // ── Multi-site helpers ────────────────────────────────────────────────────
-  /**
-   * Returns a proxy that calls the same method on **all** given sites in
-   * parallel (via `Promise.all`) and returns an array of results.
-   */
-  all(sites: SiteObject[]): AllProxy;
-
-  /**
-   * Returns a proxy that calls the same method on **all** given sites in
-   * parallel and returns a `Record<siteName, result>` object.
-   */
-  diff(sites: SiteObject[]): DiffProxy;
-
-  // ── Shutdown ──────────────────────────────────────────────────────────────
-  /**
-   * Gracefully shuts down all tabs and the browser process.
-   * Pass `{ force: true }` to skip graceful close and kill immediately.
-   */
-  close(opts?: { force?: boolean }): Promise<void>;
-
-  // ── Utilities ─────────────────────────────────────────────────────────────
-  /** Detects the Nothing Browser binary path for the given mode. */
-  detect(mode?: BinaryMode): string | null;
-
-  /** The ernest-logger instance used internally. */
-  logger: Logger;
-
-  // ── Dynamic site keys ─────────────────────────────────────────────────────
-  /**
-   * After `piggy.register("mysite", url)` you can access the site as
-   * `piggy.mysite`.  The index signature covers those dynamic properties.
-   */
-  [site: string]: SiteObject | unknown;
-}
-
-// ── Module-private state ──────────────────────────────────────────────────────
+type TabMode = "tab" | "process";
 
 let _client: PiggyClient | null = null;
 let _tabMode: TabMode = "tab";
 const _extraProcs: { socket: string; client: PiggyClient }[] = [];
-const _sites: Record<string, SiteObject> = {};
+const _sites: Record<string, SiteObject> = [];
 
-// ── The piggy singleton ───────────────────────────────────────────────────────
+const piggy: any = {
+  // ── Lifecycle ─────────────────────────────────────────────────────────────
 
-const piggy: Piggy = {
-  // ── Lifecycle ───────────────────────────────────────────────────────────────
-
-  launch: async (opts?: LaunchOptions): Promise<Piggy> => {
+  launch: async (opts?: { mode?: TabMode; binary?: BinaryMode }) => {
     _tabMode = opts?.mode ?? "tab";
     const binaryMode: BinaryMode = opts?.binary ?? "headless";
     await spawnBrowser(binaryMode);
-    await new Promise<void>((r) => setTimeout(r, 500));
+    await new Promise(r => setTimeout(r, 500));
     _client = new PiggyClient();
     await _client.connect();
     setClient(_client);
@@ -327,81 +29,104 @@ const piggy: Piggy = {
     return piggy;
   },
 
-  register: async (name: string, url: string, opts?: RegisterOptions): Promise<Piggy> => {
+  register: async (
+    name: string,
+    url: string,
+    opts?: {
+      binary?: BinaryMode;
+      pool?: number;          // number of tabs to pool — enables concurrent requests
+    }
+  ) => {
     if (!url?.trim()) throw new Error(`No URL for site "${name}"`);
     const binaryMode: BinaryMode = opts?.binary ?? "headless";
+    const poolSize = opts?.pool ?? 0;
 
-    let tabId = "default";
     if (_tabMode === "tab") {
       if (!_client) throw new Error("No client. Call piggy.launch() first.");
-      tabId = await _client.newTab();
-      const siteObj: SiteObject = createSiteObject(name, url, _client, tabId);
-      _sites[name] = siteObj;
-      (piggy as Record<string, unknown>)[name] = siteObj;
-      logger.success(`[${name}] registered as tab ${tabId}`);
+
+      if (poolSize > 1) {
+        // Pool mode — create N tabs, wrap in TabPool
+        const pool = new TabPool(_client, poolSize, url, name);
+        await pool.init();
+
+        // Use first tab as the "default" tabId for event subscriptions
+        const firstTabId = "default";
+        const siteObj = createSiteObject(name, url, _client, firstTabId, pool);
+        _sites[name] = siteObj;
+        piggy[name] = siteObj;
+        logger.success(`[${name}] registered with pool of ${poolSize} tabs`);
+      } else {
+        // Single tab mode
+        const tabId = await _client.newTab();
+        const siteObj = createSiteObject(name, url, _client, tabId);
+        _sites[name] = siteObj;
+        piggy[name] = siteObj;
+        logger.success(`[${name}] registered as tab ${tabId}`);
+      }
     } else {
       const socketName = `piggy_${name}`;
       await spawnBrowserOnSocket(socketName, binaryMode);
-      await new Promise<void>((r) => setTimeout(r, 500));
+      await new Promise(r => setTimeout(r, 500));
       const c = new PiggyClient(socketName);
       await c.connect();
       _extraProcs.push({ socket: socketName, client: c });
-      const siteObj: SiteObject = createSiteObject(name, url, c, "default");
+      const siteObj = createSiteObject(name, url, c, "default");
       _sites[name] = siteObj;
-      (piggy as Record<string, unknown>)[name] = siteObj;
+      piggy[name] = siteObj;
       logger.success(`[${name}] registered as process on "${socketName}"`);
     }
 
     return piggy;
   },
 
-  // ── Global controls ─────────────────────────────────────────────────────────
+  // ── Global controls ───────────────────────────────────────────────────────
 
-  actHuman: (enable: boolean): Piggy => {
+  actHuman: (enable: boolean) => {
     setHumanMode(enable);
     logger.info(`[piggy] actHuman: ${enable}`);
     return piggy;
   },
 
-  mode: (m: TabMode): Piggy => {
-    _tabMode = m;
-    return piggy;
-  },
+  mode: (m: TabMode) => { _tabMode = m; return piggy; },
 
-  // ── Expose Function (global) ─────────────────────────────────────────────────
+  // ── Expose Function ───────────────────────────────────────────────────────
 
-  expose: async (
-    name: string,
-    handler: (data: unknown) => Promise<unknown> | unknown,
-    tabId = "default"
-  ): Promise<Piggy> => {
+  expose: async (name: string, handler: (data: any) => Promise<any> | any, tabId = "default") => {
     if (!_client) throw new Error("No client. Call piggy.launch() first.");
     await _client.exposeFunction(name, handler, tabId);
     logger.success(`[piggy] exposed global function: ${name}`);
     return piggy;
   },
 
-  unexpose: async (name: string, tabId = "default"): Promise<Piggy> => {
+  unexpose: async (name: string, tabId = "default") => {
     if (!_client) throw new Error("No client. Call piggy.launch() first.");
     await _client.unexposeFunction(name, tabId);
     logger.info(`[piggy] unexposed function: ${name}`);
     return piggy;
   },
 
-  // ── Elysia server ────────────────────────────────────────────────────────────
+  // ── Elysia server ─────────────────────────────────────────────────────────
 
-  serve: (port: number, opts?: ServeOptions): Promise<Elysia> =>
-    startServer(port, opts?.hostname),
+  serve: (
+    port: number,
+    opts?: {
+      hostname?: string;
+      title?: string;
+      version?: string;
+      description?: string;
+      path?: string;
+    }
+  ) => startServer(port, opts?.hostname, opts),
 
   stopServer,
 
-  // ── Route listing ────────────────────────────────────────────────────────────
+  // ── Route listing ─────────────────────────────────────────────────────────
 
-  routes: (): RouteSummary[] =>
-    Array.from(routeRegistry.entries()).map(([key, cfg]): RouteSummary => {
+  routes: () =>
+    Array.from(routeRegistry.entries()).map(([key, cfg]) => {
       const [site] = key.split(":");
       return {
-        site: site ?? key,
+        site,
         method: cfg.method,
         path: `/${site}${cfg.path}`,
         ttl: cfg.ttl,
@@ -409,35 +134,26 @@ const piggy: Piggy = {
       };
     }),
 
-  // ── Multi-site ───────────────────────────────────────────────────────────────
+  // ── Multi-site ────────────────────────────────────────────────────────────
 
-  all: (sites: SiteObject[]): AllProxy =>
-    new Proxy({} as AllProxy, {
-      get: (_target, method: string) =>
-        (...args: unknown[]) =>
-          Promise.all(
-            sites.map((s) =>
-              (s as unknown as Record<string, (...a: unknown[]) => unknown>)[method]?.(...args)
-            )
-          ),
+  all: (sites: SiteObject[]) =>
+    new Proxy({} as any, {
+      get: (_, method: string) =>
+        (...args: any[]) => Promise.all(sites.map((s: any) => s[method]?.(...args))),
     }),
 
-  diff: (sites: SiteObject[]): DiffProxy =>
-    new Proxy({} as DiffProxy, {
-      get: (_target, method: string) =>
-        async (...args: unknown[]) => {
-          const results = await Promise.all(
-            sites.map((s) =>
-              (s as unknown as Record<string, (...a: unknown[]) => unknown>)[method]?.(...args)
-            )
-          );
-          return Object.fromEntries(sites.map((s, i) => [s._name ?? i, results[i]]));
+  diff: (sites: SiteObject[]) =>
+    new Proxy({} as any, {
+      get: (_, method: string) =>
+        async (...args: any[]) => {
+          const results = await Promise.all(sites.map((s: any) => s[method]?.(...args)));
+          return Object.fromEntries(sites.map((s: any, i) => [s._name ?? i, results[i]]));
         },
     }),
 
-  // ── Shutdown ─────────────────────────────────────────────────────────────────
+  // ── Shutdown ──────────────────────────────────────────────────────────────
 
-  close: async (opts?: { force?: boolean }): Promise<void> => {
+  close: async (opts?: { force?: boolean }) => {
     stopServer();
     if (opts?.force) {
       for (const { client: c } of _extraProcs) c.disconnect();
@@ -447,7 +163,7 @@ const piggy: Piggy = {
       keepAliveSites.clear();
     } else {
       for (const [name, site] of Object.entries(_sites)) {
-        if (!keepAliveSites.has(name)) await site.close?.();
+        if (!keepAliveSites.has(name)) await (site as any).close?.();
       }
       if (keepAliveSites.size === 0) {
         for (const { client: c } of _extraProcs) c.disconnect();
@@ -465,5 +181,18 @@ const piggy: Piggy = {
   logger,
 };
 
+// ── usePiggy ──────────────────────────────────────────────────────────────────
+// Typed accessor — call AFTER register() so sites exist on piggy.
+// const { amazon, ebay } = usePiggy<"amazon" | "ebay">()
+
+type TypedPiggy<Sites extends string> = typeof piggy & {
+  [K in Sites]: SiteObject;
+};
+
+export function usePiggy<Sites extends string>(): TypedPiggy<Sites> {
+  return piggy as TypedPiggy<Sites>;
+}
+
+export type { SiteObject };
 export default piggy;
 export { piggy };