nothing-browser 0.0.13 → 0.0.15

package/piggy.ts

@@ -5,24 +5,321 @@ import { PiggyClient } from "./piggy/client";
 import { setClient, setHumanMode, createSiteObject } from "./piggy/register";
 import { routeRegistry, keepAliveSites, startServer, stopServer } from "./piggy/server";
 import logger from "./piggy/logger";
+import type { Logger } from "ernest-logger";
+import type { Elysia } from "elysia";
+import type { RouteHandler, BeforeMiddleware, RouteConfig } from "./piggy/server";
 
-type TabMode = "tab" | "process";
-type SiteObject = ReturnType<typeof createSiteObject>;
+// ── 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 ──────────────────────────────────────────────────────
 
 let _client: PiggyClient | null = null;
 let _tabMode: TabMode = "tab";
 const _extraProcs: { socket: string; client: PiggyClient }[] = [];
 const _sites: Record<string, SiteObject> = {};
 
-// CREATE THE PIGGY OBJECT AS A PLAIN OBJECT - NOT A PROXY
-const piggy: any = {
+// ── The piggy singleton ───────────────────────────────────────────────────────
+
+const piggy: Piggy = {
   // ── Lifecycle ───────────────────────────────────────────────────────────────
 
-  launch: async (opts?: { mode?: TabMode; binary?: BinaryMode }) => {
+  launch: async (opts?: LaunchOptions): Promise<Piggy> => {
     _tabMode = opts?.mode ?? "tab";
     const binaryMode: BinaryMode = opts?.binary ?? "headless";
     await spawnBrowser(binaryMode);
-    await new Promise(r => setTimeout(r, 500));
+    await new Promise<void>((r) => setTimeout(r, 500));
     _client = new PiggyClient();
     await _client.connect();
     setClient(_client);
@@ -30,7 +327,7 @@ const piggy: any = {
     return piggy;
   },
 
-  register: async (name: string, url: string, opts?: { binary?: BinaryMode }) => {
+  register: async (name: string, url: string, opts?: RegisterOptions): Promise<Piggy> => {
     if (!url?.trim()) throw new Error(`No URL for site "${name}"`);
     const binaryMode: BinaryMode = opts?.binary ?? "headless";
 
@@ -38,21 +335,20 @@ const piggy: any = {
     if (_tabMode === "tab") {
       if (!_client) throw new Error("No client. Call piggy.launch() first.");
       tabId = await _client.newTab();
-      // HERE IT IS - CREATE SITE OBJECT AND ASSIGN DIRECTLY
-      const siteObj = createSiteObject(name, url, _client, tabId);
+      const siteObj: SiteObject = createSiteObject(name, url, _client, tabId);
       _sites[name] = siteObj;
-      piggy[name] = siteObj;  // DIRECT ASSIGNMENT - NO PROXY
+      (piggy as Record<string, unknown>)[name] = siteObj;
       logger.success(`[${name}] registered as tab ${tabId}`);
     } else {
       const socketName = `piggy_${name}`;
       await spawnBrowserOnSocket(socketName, binaryMode);
-      await new Promise(r => setTimeout(r, 500));
+      await new Promise<void>((r) => setTimeout(r, 500));
       const c = new PiggyClient(socketName);
       await c.connect();
       _extraProcs.push({ socket: socketName, client: c });
-      const siteObj = createSiteObject(name, url, c, "default");
+      const siteObj: SiteObject = createSiteObject(name, url, c, "default");
       _sites[name] = siteObj;
-      piggy[name] = siteObj;  // DIRECT ASSIGNMENT - NO PROXY
+      (piggy as Record<string, unknown>)[name] = siteObj;
       logger.success(`[${name}] registered as process on "${socketName}"`);
     }
 
@@ -61,24 +357,31 @@ const piggy: any = {
 
   // ── Global controls ─────────────────────────────────────────────────────────
 
-  actHuman: (enable: boolean) => {
+  actHuman: (enable: boolean): Piggy => {
     setHumanMode(enable);
     logger.info(`[piggy] actHuman: ${enable}`);
     return piggy;
   },
 
-  mode: (m: TabMode) => { _tabMode = m; return piggy; },
+  mode: (m: TabMode): Piggy => {
+    _tabMode = m;
+    return piggy;
+  },
 
   // ── Expose Function (global) ─────────────────────────────────────────────────
 
-  expose: async (name: string, handler: (data: any) => Promise<any> | any, tabId = "default") => {
+  expose: async (
+    name: string,
+    handler: (data: unknown) => Promise<unknown> | unknown,
+    tabId = "default"
+  ): Promise<Piggy> => {
     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") => {
+  unexpose: async (name: string, tabId = "default"): Promise<Piggy> => {
     if (!_client) throw new Error("No client. Call piggy.launch() first.");
     await _client.unexposeFunction(name, tabId);
     logger.info(`[piggy] unexposed function: ${name}`);
@@ -87,18 +390,18 @@ const piggy: any = {
 
   // ── Elysia server ────────────────────────────────────────────────────────────
 
-  serve: (port: number, opts?: { hostname?: string }) =>
+  serve: (port: number, opts?: ServeOptions): Promise<Elysia> =>
     startServer(port, opts?.hostname),
 
   stopServer,
 
   // ── Route listing ────────────────────────────────────────────────────────────
 
-  routes: () =>
-    Array.from(routeRegistry.entries()).map(([key, cfg]) => {
+  routes: (): RouteSummary[] =>
+    Array.from(routeRegistry.entries()).map(([key, cfg]): RouteSummary => {
       const [site] = key.split(":");
       return {
-        site,
+        site: site ?? key,
         method: cfg.method,
         path: `/${site}${cfg.path}`,
         ttl: cfg.ttl,
@@ -108,24 +411,33 @@ const piggy: any = {
 
   // ── Multi-site ───────────────────────────────────────────────────────────────
 
-  all: (sites: SiteObject[]) =>
-    new Proxy({} as any, {
-      get: (_, method: string) =>
-        (...args: any[]) => Promise.all(sites.map((s: any) => s[method]?.(...args))),
+  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)
+            )
+          ),
     }),
 
-  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]]));
+  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]]));
         },
     }),
 
   // ── Shutdown ─────────────────────────────────────────────────────────────────
 
-  close: async (opts?: { force?: boolean }) => {
+  close: async (opts?: { force?: boolean }): Promise<void> => {
     stopServer();
     if (opts?.force) {
       for (const { client: c } of _extraProcs) c.disconnect();
@@ -153,6 +465,5 @@ const piggy: any = {
   logger,
 };
 
-// NO PROXY WRAPPER - EXPORT THE PLAIN OBJECT DIRECTLY
 export default piggy;
 export { piggy };