nothing-browser 0.0.15 → 0.0.16

package/dist/piggy.d.ts

@@ -3,12 +3,10 @@ import type { Logger } from "ernest-logger";
 import type { Elysia } from "elysia";
 import type { RouteHandler, BeforeMiddleware, RouteConfig } from "./piggy/server";
 export type TabMode = "tab" | "process";
-/** Returned by createSiteObject — full API surface of a registered site. */
+/** Full API surface of a registered site. */
 export interface SiteObject {
-    /** Internal name used when registering. */
-    _name: string;
-    /** Internal CDP / socket tab ID. */
-    _tabId: string;
+    readonly _name: string;
+    readonly _tabId: string;
     navigate(url?: string, opts?: {
         retries?: number;
     }): Promise<void>;
@@ -136,87 +134,45 @@ export interface RouteSummary {
     ttl: number;
     middlewareCount: number;
 }
-/**
- * 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;
 };
 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;
 }
-export interface Piggy {
-    /**
-     * 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>;
-    /** 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;
-    /** 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>;
-    /** Starts an Elysia HTTP server that exposes all registered `.api()` routes. */
+export interface PiggyBase {
+    launch(opts?: LaunchOptions): Promise<PiggyBase>;
+    register(name: string, url: string, opts?: RegisterOptions): Promise<PiggyBase>;
+    actHuman(enable: boolean): PiggyBase;
+    mode(m: TabMode): PiggyBase;
+    expose(name: string, handler: (data: unknown) => Promise<unknown> | unknown, tabId?: string): Promise<PiggyBase>;
+    unexpose(name: string, tabId?: string): Promise<PiggyBase>;
     serve(port: number, opts?: ServeOptions): Promise<Elysia>;
-    /** Stops the running Elysia server. */
     stopServer(): void;
-    /** Returns a summary of every mounted HTTP route. */
     routes(): RouteSummary[];
-    /**
-     * 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;
-    /**
-     * 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>;
-    /** Detects the Nothing Browser binary path for the given mode. */
     detect(mode?: BinaryMode): string | null;
-    /** The ernest-logger instance used internally. */
     logger: Logger;
-    /**
-     * After `piggy.register("mysite", url)` you can access the site as
-     * `piggy.mysite`.  The index signature covers those dynamic properties.
-     */
-    [site: string]: SiteObject | unknown;
 }
-declare const piggy: Piggy;
+export type PiggyWithSites<S extends string> = PiggyBase & {
+    [K in S]: SiteObject;
+};
+export declare function usePiggy<S extends string>(): PiggyWithSites<S>;
+declare const piggy: PiggyBase;
 export default piggy;
 export { piggy };
 //# sourceMappingURL=piggy.d.ts.map

package/dist/piggy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"piggy.d.ts","sourceRoot":"","sources":["../piggy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"piggy.d.ts","sourceRoot":"","sources":["../piggy.ts"],"names":[],"mappings":"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"}

package/dist/piggy.js

@@ -21759,6 +21759,9 @@ function createSiteObject(name, registeredUrl, client, tabId) {
 }
 
 // piggy.ts
+function usePiggy() {
+  return piggy;
+}
 var _client = null;
 var _tabMode = "tab";
 var _extraProcs = [];
@@ -21779,14 +21782,12 @@ var piggy = {
     if (!url?.trim())
       throw new Error(`No URL for site "${name}"`);
     const binaryMode = opts?.binary ?? "headless";
-    let tabId = "default";
+    let siteObj;
     if (_tabMode === "tab") {
       if (!_client)
         throw new Error("No client. Call piggy.launch() first.");
-      tabId = await _client.newTab();
-      const siteObj = createSiteObject(name, url, _client, tabId);
-      _sites[name] = siteObj;
-      piggy[name] = siteObj;
+      const tabId = await _client.newTab();
+      siteObj = createSiteObject(name, url, _client, tabId);
       logger_default.success(`[${name}] registered as tab ${tabId}`);
     } else {
       const socketName = `piggy_${name}`;
@@ -21795,11 +21796,11 @@ var piggy = {
       const c = new PiggyClient(socketName);
       await c.connect();
       _extraProcs.push({ socket: socketName, client: c });
-      const siteObj = createSiteObject(name, url, c, "default");
-      _sites[name] = siteObj;
-      piggy[name] = siteObj;
+      siteObj = createSiteObject(name, url, c, "default");
       logger_default.success(`[${name}] registered as process on "${socketName}"`);
     }
+    _sites[name] = siteObj;
+    piggy[name] = siteObj;
     return piggy;
   },
   actHuman: (enable) => {
@@ -21877,6 +21878,7 @@ var piggy = {
 };
 var piggy_default = piggy;
 export {
+  usePiggy,
   piggy,
   piggy_default as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nothing-browser",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Browser automation library powered by Nothing Browser",
   "homepage": "https://github.com/ernest-tech-house-co-operation/nothing-browser#readme",
   "repository": {

package/piggy.ts

@@ -13,12 +13,10 @@ import type { RouteHandler, BeforeMiddleware, RouteConfig } from "./piggy/server
 
 export type TabMode = "tab" | "process";
 
-/** Returned by createSiteObject — full API surface of a registered site. */
+/** Full API surface of a registered site. */
 export interface SiteObject {
-  /** Internal name used when registering. */
-  _name: string;
-  /** Internal CDP / socket tab ID. */
-  _tabId: string;
+  readonly _name: string;
+  readonly _tabId: string;
 
   // ── Navigation ─────────────────────────────────────────────────────────────
   navigate(url?: string, opts?: { retries?: number }): Promise<void>;
@@ -26,7 +24,6 @@ export interface SiteObject {
   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;
@@ -62,12 +59,10 @@ export interface SiteObject {
     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>;
@@ -77,7 +72,6 @@ export interface SiteObject {
   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>;
@@ -140,7 +134,7 @@ export interface SiteObject {
     import(data: unknown): Promise<void>;
   };
 
-  // ── Expose / unexpose functions ───────────────────────────────────────────
+  // ── Expose / unexpose ─────────────────────────────────────────────────────
   exposeFunction(
     fnName: string,
     handler: (data: unknown) => Promise<unknown> | unknown
@@ -168,7 +162,7 @@ export interface SiteObject {
   close(): Promise<void>;
 }
 
-// ── Route summary returned by piggy.routes() ─────────────────────────────────
+// ── Route summary ─────────────────────────────────────────────────────────────
 
 export interface RouteSummary {
   site: string;
@@ -180,11 +174,6 @@ export interface RouteSummary {
 
 // ── 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[]>
@@ -193,10 +182,6 @@ export type AllProxy = {
       : 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>>
@@ -205,17 +190,14 @@ export type DiffProxy = {
       : never;
 };
 
-// ── Launch / register option bags ────────────────────────────────────────────
+// ── 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;
 }
 
@@ -223,84 +205,67 @@ 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;
+// ── PiggyBase — named methods, no index signature ─────────────────────────────
 
-  // ── Global function exposure ───────────────────────────────────────────────
-  /** Exposes a Node.js function to the browser's global scope on the default (or specified) tab. */
+export interface PiggyBase {
+  launch(opts?: LaunchOptions): Promise<PiggyBase>;
+  register(name: string, url: string, opts?: RegisterOptions): Promise<PiggyBase>;
+  actHuman(enable: boolean): PiggyBase;
+  mode(m: TabMode): PiggyBase;
   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. */
+  ): Promise<PiggyBase>;
+  unexpose(name: string, tabId?: string): Promise<PiggyBase>;
   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;
+}
+
+// ── PiggyWithSites<S> — PiggyBase + typed site keys ──────────────────────────
 
-  // ── 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;
+export type PiggyWithSites<S extends string> = PiggyBase & {
+  [K in S]: SiteObject;
+};
+
+// ── usePiggy — takes the piggy import, returns it typed ──────────────────────
+//
+// The variable is ALWAYS called `piggy`. No rename. No new variable.
+// Just pass the import in, get it back fully typed.
+//
+//   import piggy, { usePiggy } from 'nothing-browser';
+//   usePiggy<"amazon" | "walmart" | "ebay">(piggy);
+//
+//   await piggy.launch({ mode: "tab" });
+//   await piggy.register("amazon",  "https://www.amazon.com/");
+//   await piggy.register("walmart", "https://www.walmart.com/");
+//   await piggy.register("ebay",    "https://www.ebay.com/");
+//
+//   await piggy.amazon.navigate();    // ✅ full autocomplete
+//   await piggy.walmart.click("..."); // ✅
+//   await piggy.ebay.screenshot();    // ✅
+//
+// How it works: TypeScript narrows the type of `piggy` at the call site
+// via the returned typed reference. Assign back to `piggy` with `let`:
+//
+//   import piggyRaw, { usePiggy } from 'nothing-browser';
+//   const piggy = usePiggy<"amazon" | "walmart" | "ebay">(piggyRaw);
+//
+// OR use the reassignment pattern with `let` for maximum cleanliness:
+//
+//   import { piggy as _piggy, usePiggy } from 'nothing-browser';
+//   const piggy = usePiggy<"amazon" | "walmart" | "ebay">(_piggy);
+//
+// Either way: `piggy` is the word in your code, always.
+
+export function usePiggy<S extends string>(): PiggyWithSites<S> {
+  return piggy as unknown as PiggyWithSites<S>;
 }
 
 // ── Module-private state ──────────────────────────────────────────────────────
@@ -312,10 +277,8 @@ const _sites: Record<string, SiteObject> = {};
 
 // ── The piggy singleton ───────────────────────────────────────────────────────
 
-const piggy: Piggy = {
-  // ── Lifecycle ───────────────────────────────────────────────────────────────
-
-  launch: async (opts?: LaunchOptions): Promise<Piggy> => {
+const piggy: PiggyBase = {
+  launch: async (opts?: LaunchOptions): Promise<PiggyBase> => {
     _tabMode = opts?.mode ?? "tab";
     const binaryMode: BinaryMode = opts?.binary ?? "headless";
     await spawnBrowser(binaryMode);
@@ -327,17 +290,16 @@ const piggy: Piggy = {
     return piggy;
   },
 
-  register: async (name: string, url: string, opts?: RegisterOptions): Promise<Piggy> => {
+  register: async (name: string, url: string, opts?: RegisterOptions): Promise<PiggyBase> => {
     if (!url?.trim()) throw new Error(`No URL for site "${name}"`);
     const binaryMode: BinaryMode = opts?.binary ?? "headless";
 
-    let tabId = "default";
+    let siteObj: SiteObject;
+
     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;
+      const tabId = await _client.newTab();
+      siteObj = createSiteObject(name, url, _client, tabId) as SiteObject;
       logger.success(`[${name}] registered as tab ${tabId}`);
     } else {
       const socketName = `piggy_${name}`;
@@ -346,57 +308,49 @@ const piggy: Piggy = {
       const c = new PiggyClient(socketName);
       await c.connect();
       _extraProcs.push({ socket: socketName, client: c });
-      const siteObj: SiteObject = createSiteObject(name, url, c, "default");
-      _sites[name] = siteObj;
-      (piggy as Record<string, unknown>)[name] = siteObj;
+      siteObj = createSiteObject(name, url, c, "default") as SiteObject;
       logger.success(`[${name}] registered as process on "${socketName}"`);
     }
 
+    _sites[name] = siteObj;
+    (piggy as unknown as Record<string, unknown>)[name] = siteObj;
     return piggy;
   },
 
-  // ── Global controls ─────────────────────────────────────────────────────────
-
-  actHuman: (enable: boolean): Piggy => {
+  actHuman: (enable: boolean): PiggyBase => {
     setHumanMode(enable);
     logger.info(`[piggy] actHuman: ${enable}`);
     return piggy;
   },
 
-  mode: (m: TabMode): Piggy => {
+  mode: (m: TabMode): PiggyBase => {
     _tabMode = m;
     return piggy;
   },
 
-  // ── Expose Function (global) ─────────────────────────────────────────────────
-
   expose: async (
     name: string,
     handler: (data: unknown) => Promise<unknown> | unknown,
     tabId = "default"
-  ): Promise<Piggy> => {
+  ): Promise<PiggyBase> => {
     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"): Promise<PiggyBase> => {
     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 ────────────────────────────────────────────────────────────
-
   serve: (port: number, opts?: ServeOptions): Promise<Elysia> =>
     startServer(port, opts?.hostname),
 
   stopServer,
 
-  // ── Route listing ────────────────────────────────────────────────────────────
-
   routes: (): RouteSummary[] =>
     Array.from(routeRegistry.entries()).map(([key, cfg]): RouteSummary => {
       const [site] = key.split(":");
@@ -409,8 +363,6 @@ const piggy: Piggy = {
       };
     }),
 
-  // ── Multi-site ───────────────────────────────────────────────────────────────
-
   all: (sites: SiteObject[]): AllProxy =>
     new Proxy({} as AllProxy, {
       get: (_target, method: string) =>
@@ -435,8 +387,6 @@ const piggy: Piggy = {
         },
     }),
 
-  // ── Shutdown ─────────────────────────────────────────────────────────────────
-
   close: async (opts?: { force?: boolean }): Promise<void> => {
     stopServer();
     if (opts?.force) {