nothing-browser 0.0.3 → 0.0.4

package/README.md

@@ -1,3 +1,6 @@
+Here's the updated README with the `exposeFunction` feature documented:
+
+```markdown
 <p align="center">
   <img src="nothing_browser_pig_pink.svg" width="160" alt="Nothing Browser logo"/>
 </p>
@@ -17,6 +20,27 @@ A scraper-first headless browser library powered by the Nothing Browser Qt6/Chro
 
 ---
 
+## Why nothing-browser
+
+Yes, we are bragging. Here's why.
+
+| | nothing-browser | Puppeteer | Playwright |
+|---|---|---|---|
+| Imports | **1** | 5–10 | 5–10 |
+| Lines to scrape a site | **~20** | 80–200 | 80–200 |
+| Fingerprint spoofing | ✅ built in | ❌ plugin needed | ❌ plugin needed |
+| Network capture | ✅ built in | ❌ manual | ❌ manual |
+| Built-in API server | ✅ | ❌ | ❌ |
+| Cloudflare bypass | ✅ passes | ⚠️ often blocked | ⚠️ often blocked |
+| Headless detection bypass | ✅ built in | ❌ manual | ❌ manual |
+| Session persistence | ✅ built in | ❌ manual | ❌ manual |
+| Human mode | ✅ built in | ❌ manual | ❌ manual |
+| **Browser → Node.js RPC** | ✅ **exposeFunction** | ✅ page.exposeFunction | ✅ page.exposeFunction |
+
+One import. No middleware soup. No 47 plugins to avoid detection. No CAPTCHAs on sites that Puppeteer chokes on. Just write your scraper and go.
+
+---
+
 ## Requirements
 
 - [Bun](https://bun.sh) ≥ 1.0
@@ -26,7 +50,7 @@ A scraper-first headless browser library powered by the Nothing Browser Qt6/Chro
 
 ## Binaries
 
-There are three binaries. All are downloaded from the same place — [GitHub Releases](https://github.com/BunElysiaReact/nothing-browser/releases).
+There are three binaries. All downloaded from the same place — [GitHub Releases](https://github.com/BunElysiaReact/nothing-browser/releases).
 
 | Binary | What it is | Where it goes |
 |--------|-----------|---------------|
@@ -34,7 +58,7 @@ There are three binaries. All are downloaded from the same place — [GitHub Rel
 | `nothing-browser-headless` | No window, no GPU. Runs as a background daemon for the scraping lib. | **Your project root** |
 | `nothing-browser-headful` | Visible browser window, script-controlled. Useful when a site needs a real display. | **Your project root** |
 
-The `nothingbrowser` npm/Bun lib talks to whichever binary is in your project root over a local socket. You pick headless or headful depending on your use case.
+The lib talks to whichever binary is in your project root over a local socket. You pick headless or headful depending on your use case.
 
 ---
 
@@ -63,19 +87,15 @@ chmod +x nothing-browser-headful
 **Full browser** (system-wide install, for using the UI)
 ```bash
 sudo dpkg -i nothing-browser_*_amd64.deb
-# or
-tar -xzf nothing-browser-*-linux-x86_64.tar.gz
-cd nothing-browser-*-linux-x86_64
-./nothing-browser
 ```
 
 ### Windows
 
-Download the `.zip` for your chosen binary → extract → place `nothing-browser-headless.exe` or `nothing-browser-headful.exe` in your project root. The JRE is bundled in the full browser zip.
+Download the `.zip` → extract → place the exe in your project root.
 
 ### macOS
 
-Download the `.tar.gz` for your chosen binary → extract → place the binary in your project root.
+Download the `.tar.gz` → extract → place the binary in your project root.
 
 ---
 
@@ -101,45 +121,143 @@ console.log(books);
 await piggy.close();
 ```
 
+That's it. One import, one register, scrape, done.
+
 ---
 
-## Modes
+## Headless vs Headful
 
-### Tab mode (default)
-All sites share one browser process, each in its own tab.
+**Headless** — no display needed, runs anywhere including CI.
 
 ```ts
-await piggy.launch({ mode: "tab" });
+await piggy.launch({ mode: "tab", binary: "headless" }); // default
 ```
 
-### Process mode
-Each site gets its own browser process on a dedicated socket. More isolation, more RAM.
+**Headful** — opens a real visible Chromium window your script drives. Use this when a site detects headless or requires a real display.
 
 ```ts
-await piggy.launch({ mode: "process" });
+await piggy.launch({ mode: "tab", binary: "headful" });
 ```
 
+Same API either way. Switching is just changing one word.
+
 ---
 
-## Headless vs Headful
+## Examples
 
-**Headless** — no display needed, runs anywhere including CI. Use this by default.
+### 🔥 NEW: Browser → Node.js RPC with `exposeFunction`
 
-```
-nothing-browser-headless        ← in your project root
+Call Node.js functions directly from browser JavaScript. Perfect for:
+- Processing data in real-time as the user navigates
+- Handling authentication callbacks
+- Streaming WebSocket messages to your backend
+- Building browser extensions with Node.js power
+
+```ts
+import piggy from "nothing-browser";
+
+await piggy.launch({ mode: "tab" });
+await piggy.register("whatsapp", "https://web.whatsapp.com");
+
+// Expose a function that WhatsApp Web can call
+await piggy.whatsapp.exposeFunction("onNewMessage", async (message) => {
+  console.log("📱 New message:", message);
+  
+  // Save to database
+  await db.messages.insert({
+    text: message.text,
+    sender: message.sender,
+    timestamp: message.timestamp,
+  });
+  
+  // Return value goes back to the browser
+  return { saved: true, id: crypto.randomUUID() };
+});
+
+// Inject the listener that calls our exposed function
+await piggy.whatsapp.evaluate(() => {
+  const observer = new MutationObserver(() => {
+    document.querySelectorAll('.message-in:not([data-seen])').forEach(el => {
+      el.dataset.seen = '1';
+      
+      // Call the exposed function - returns a Promise!
+      window.onNewMessage({
+        text: el.innerText,
+        timestamp: Date.now(),
+        sender: el.querySelector('.sender')?.innerText,
+      }).then(result => {
+        console.log('Message saved with ID:', result.id);
+        el.style.borderLeft = '3px solid green';
+      });
+    });
+  });
+  
+  observer.observe(document.body, { childList: true, subtree: true });
+});
+
+console.log("Listening for WhatsApp messages...");
 ```
 
-**Headful** — opens a real visible Chromium window that your script drives. Use this when a site detects headless mode or requires a real display (canvas fingerprinting, certain login flows, etc).
+### Expose + Inject convenience method
 
+```ts
+await piggy.whatsapp.exposeAndInject(
+  "onNewMessage",
+  async (message) => {
+    await saveToDatabase(message);
+    return { ok: true };
+  },
+  (fnName) => `
+    // This runs in the browser
+    setInterval(() => {
+      const msgs = document.querySelectorAll('.new-message');
+      msgs.forEach(msg => {
+        window.${fnName}({ text: msg.innerText });
+      });
+    }, 2000);
+  `
+);
 ```
-nothing-browser-headful         ← in your project root
+
+### Structured API with multiple methods
+
+```ts
+import { createExposedAPI } from "nothing-browser/register";
+
+await createExposedAPI(piggy.whatsapp, "whatsappAPI", {
+  onMessage: async (msg) => {
+    await db.messages.insert(msg);
+    return { saved: true };
+  },
+  
+  getContacts: async () => {
+    return await db.contacts.findAll();
+  },
+  
+  sendReply: async ({ to, text }) => {
+    // Your sending logic here
+    return { sent: true };
+  }
+});
+
+// In browser JS:
+const result = await window.whatsappAPI({ 
+  method: 'sendReply', 
+  args: { to: '+1234567890', text: 'Hello!' } 
+});
 ```
 
-Both binaries expose the exact same socket API. Switching is just swapping which binary is in your project root.
+### Global expose (available to all sites)
 
----
+```ts
+await piggy.expose("logToServer", async (data) => {
+  console.log("[Browser]", data);
+  await analytics.track(data.event, data.properties);
+  return { logged: true };
+});
 
-## Examples
+// Any page can call: window.logToServer({ event: 'pageview' })
+```
 
 ### Scrape a site and expose it as an API
 
@@ -151,7 +269,6 @@ await piggy.register("books", "https://books.toscrape.com");
 
 await piggy.books.intercept.block("*google-analytics*");
 await piggy.books.intercept.block("*doubleclick*");
-await piggy.books.intercept.block("*facebook*");
 
 piggy.books.api("/list", async (_params, query) => {
   const page = query.page ? parseInt(query.page) : 1;
@@ -179,6 +296,8 @@ piggy.books.api("/list", async (_params, query) => {
 
 piggy.books.noclose();
 await piggy.serve(3000);
+// GET http://localhost:3000/books/list
+// GET http://localhost:3000/books/list?page=2
 ```
 
 ---
@@ -186,37 +305,16 @@ await piggy.serve(3000);
 ### Middleware — auth + logging
 
 ```ts
-const logMiddleware = async ({ query, params }: any) => {
-  console.log("[middleware] incoming request", { params, query });
-};
-
 const authMiddleware = async ({ headers, set }: any) => {
-  const key = headers["x-api-key"];
-  if (!key || key !== "piggy-secret") {
+  if (headers["x-api-key"] !== "secret") {
     set.status = 401;
-    throw new Error("Unauthorized: missing or invalid x-api-key");
+    throw new Error("Unauthorized");
   }
 };
 
 piggy.books.api("/search", async (_params, query) => {
-  if (!query.q) return { error: "query param 'q' required" };
-
-  await piggy.books.navigate("https://books.toscrape.com");
-  await piggy.books.waitForSelector(".product_pod", 10000);
-
-  const books = await piggy.books.evaluate((q: string) =>
-    Array.from(document.querySelectorAll(".product_pod"))
-      .filter(el =>
-        el.querySelector("h3 a")?.getAttribute("title")?.toLowerCase().includes(q.toLowerCase())
-      )
-      .map(el => ({
-        title: el.querySelector("h3 a")?.getAttribute("title") ?? "",
-        price: el.querySelector(".price_color")?.textContent?.trim() ?? "",
-      }))
-  , query.q);
-
-  return { query: query.q, count: books.length, books };
-}, { ttl: 120_000, before: [logMiddleware, authMiddleware] });
+  // handler
+}, { ttl: 120_000, before: [authMiddleware] });
 ```
 
 ---
@@ -236,8 +334,8 @@ await piggy.books.capture.stop();
 
 const requests = await piggy.books.capture.requests();
 const ws       = await piggy.books.capture.ws();
-const storage  = await piggy.books.capture.storage();
 const cookies  = await piggy.books.capture.cookies();
+const storage  = await piggy.books.capture.storage();
 
 console.log(`${requests.length} requests, ${ws.length} WS frames`);
 ```
@@ -276,6 +374,8 @@ await piggy.books.type("#search", "mystery novels");
 await piggy.books.scroll.by(400);
 ```
 
+Affects `click`, `type`, `hover`, `scroll.by`, `wait` — random delays, simulated typos, self-correction.
+
 ---
 
 ### Screenshot / PDF
@@ -284,7 +384,7 @@ await piggy.books.scroll.by(400);
 await piggy.books.screenshot("./out/page.png");
 await piggy.books.pdf("./out/page.pdf");
 
-const b64 = await piggy.books.screenshot();
+const b64 = await piggy.books.screenshot(); // base64
 ```
 
 ---
@@ -309,6 +409,7 @@ const h1s    = await piggy.diff([piggy.site1, piggy.site2]).fetchText("h1");
 | Option | Type | Default |
 |--------|------|---------|
 | `mode` | `"tab" \| "process"` | `"tab"` |
+| `binary` | `"headless" \| "headful"` | `"headless"` |
 
 ### `piggy.register(name, url)`
 Registers a site. Accessible as `piggy.<name>` after registration.
@@ -316,6 +417,12 @@ Registers a site. Accessible as `piggy.<name>` after registration.
 ### `piggy.actHuman(enable)`
 Toggles human-like interaction timing globally.
 
+### `piggy.expose(name, handler, tabId?)`
+Exposes a function globally (available to all tabs). The handler receives data from the browser and can return a value that resolves the Promise in the browser.
+
+### `piggy.unexpose(name, tabId?)`
+Removes a globally exposed function.
+
 ### `piggy.serve(port, opts?)`
 Starts the Elysia HTTP server. Built-in routes: `GET /health`, `GET /cache/keys`, `DELETE /cache`.
 
@@ -325,7 +432,7 @@ Returns all registered API routes with method, path, TTL, and middleware count.
 ### `piggy.close(opts?)`
 
 ```ts
-await piggy.close();                // graceful — respects noclose()
+await piggy.close();                // graceful
 await piggy.close({ force: true }); // kills everything immediately
 ```
 
@@ -346,10 +453,10 @@ site.wait(ms)
 ```ts
 site.click(selector, opts?)
 site.doubleClick(selector) / site.hover(selector)
-site.type(selector, text, opts?)     // opts: { delay?, wpm?, fact? }
+site.type(selector, text, opts?)
 site.select(selector, value)
 site.keyboard.press(key)
-site.keyboard.combo(combo)           // e.g. "Ctrl+A"
+site.keyboard.combo(combo)
 site.mouse.move(x, y)
 site.mouse.drag(from, to)
 site.scroll.to(selector) / site.scroll.by(px)
@@ -357,13 +464,30 @@ site.scroll.to(selector) / site.scroll.by(px)
 
 #### Data
 ```ts
-site.fetchText(selector)             // → string | null
-site.fetchLinks(selector)            // → string[]
-site.fetchImages(selector)           // → string[]
+site.fetchText(selector)
+site.fetchLinks(selector)
+site.fetchImages(selector)
 site.search.css(query) / site.search.id(query)
 site.evaluate(js | fn, ...args)
 ```
 
+#### 🔥 Expose Function (RPC)
+```ts
+// Expose a function that browser JS can call
+site.exposeFunction(name, handler)
+// handler: (data: any) => Promise<any> | any
+
+// Remove an exposed function
+site.unexposeFunction(name)
+
+// Remove all exposed functions for this site
+site.clearExposedFunctions()
+
+// Expose and inject in one call
+site.exposeAndInject(name, handler, injectionJs)
+// injectionJs: string | ((fnName: string) => string)
+```
+
 #### Network
 ```ts
 site.capture.start() / .stop() / .clear()
@@ -386,12 +510,38 @@ site.session.export() / site.session.import(data)
 ```ts
 site.api(path, handler, opts?)
 // opts: { ttl?, method?, before?: middleware[] }
-// handler: (params, query, body) => Promise<any>
 
 site.noclose()
 site.screenshot(filePath?) / site.pdf(filePath?)
 ```
 
+### Helper Functions
+
+```ts
+import { createExposedAPI } from "nothing-browser/register";
+
+// Create a structured API with multiple methods
+await createExposedAPI(site, apiName, {
+  method1: async (args) => { /* ... */ },
+  method2: async (args) => { /* ... */ },
+});
+
+// Browser calls: window[apiName]({ method: 'method1', args: {...} })
+```
+
+---
+
+## How `exposeFunction` Works
+
+1. **Browser injects stub**: `window.fnName` becomes a Promise-returning function
+2. **Browser queues calls**: Arguments are pushed to `__NOTHING_QUEUE__`
+3. **C++ picks up queue**: 250ms poll timer reads the queue
+4. **Signal to Node.js**: Server broadcasts event to all connected clients
+5. **Your handler runs**: TypeScript handler processes the data
+6. **Result returns**: Promise in browser resolves with your return value
+
+The function survives page navigations (injected at `DocumentCreation`) and works with both tab and process modes.
+
 ---
 
 ## Binary download
@@ -409,4 +559,4 @@ site.screenshot(filePath?) / site.pdf(filePath?)
 
 ## License
 
-MIT © [Ernest Tech House](https://github.com/BunElysiaReact/nothing-browser)
+MIT © [Ernest Tech House](https://github.com/BunElysiaReact/nothing-browser)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nothing-browser",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Scraper-first headless browser library — control real tabs, intercept network traffic, capture WebSockets, spoof fingerprints. Powered by Qt6/Chromium.",
   "module": "piggy.ts",
   "main": "piggy.ts",

package/piggy/client/index.ts

@@ -10,9 +10,12 @@ export class PiggyClient {
   private reqId = 0;
   private pending = new Map<string, { resolve: (v: any) => void; reject: (e: Error) => void }>();
   private buf = "";
+  private eventBuffer = "";
+  private eventHandlers = new Map<string, Map<string, (data: any) => Promise<any>>>();
 
   constructor(socketPath = "/tmp/piggy") {
     this.socketPath = socketPath;
+    this.eventHandlers.set("default", new Map());
   }
 
   connect(): Promise<void> {
@@ -28,13 +31,22 @@ export class PiggyClient {
       });
 
       sock.on("data", (chunk: string) => {
-        this.buf += chunk;
-        const lines = this.buf.split("\n");
-        this.buf = lines.pop()!;
+        this.eventBuffer += chunk;
+        const lines = this.eventBuffer.split("\n");
+        this.eventBuffer = lines.pop()!;
+        
         for (const line of lines) {
           if (!line.trim()) continue;
           try {
             const msg = JSON.parse(line);
+            
+            // Handle events
+            if (msg.type === "event") {
+              this.handleEvent(msg);
+              continue;
+            }
+            
+            // Handle command responses
             const p = this.pending.get(msg.id);
             if (p) {
               this.pending.delete(msg.id);
@@ -59,6 +71,56 @@ export class PiggyClient {
     });
   }
 
+  private handleEvent(event: any) {
+    if (event.event === "exposed_call") {
+      const { tabId, name, callId, data } = event;
+      const effectiveTabId = tabId || "default";
+      const handlers = this.eventHandlers.get(effectiveTabId);
+      const handler = handlers?.get(name);
+      
+      if (handler) {
+        Promise.resolve(handler(JSON.parse(data || "null")))
+          .then(response => {
+            if (response && typeof response === "object" && "success" in response) {
+              if (response.success) {
+                this.send("exposed.result", {
+                  tabId: effectiveTabId,
+                  callId,
+                  result: JSON.stringify(response.result),
+                  isError: false
+                }).catch(e => logger.error(`Failed to send exposed result: ${e}`));
+              } else {
+                this.send("exposed.result", {
+                  tabId: effectiveTabId,
+                  callId,
+                  result: response.error || "Unknown error",
+                  isError: true
+                }).catch(e => logger.error(`Failed to send exposed error: ${e}`));
+              }
+            } else {
+              // Handler returned raw value
+              this.send("exposed.result", {
+                tabId: effectiveTabId,
+                callId,
+                result: JSON.stringify(response),
+                isError: false
+              }).catch(e => logger.error(`Failed to send exposed result: ${e}`));
+            }
+          })
+          .catch(err => {
+            this.send("exposed.result", {
+              tabId: effectiveTabId,
+              callId,
+              result: err.message || "Handler error",
+              isError: true
+            }).catch(e => logger.error(`Failed to send exposed error: ${e}`));
+          });
+      } else {
+        logger.warn(`No handler for exposed function: ${name} in tab ${effectiveTabId}`);
+      }
+    }
+  }
+
   disconnect() {
     this.socket?.destroy();
     this.socket = null;
@@ -327,4 +389,48 @@ export class PiggyClient {
   async sessionImport(data: any, tabId = "default"): Promise<void> {
     await this.send("session.import", { data, tabId });
   }
+
+  // ── Expose Function ───────────────────────────────────────────────────────────
+
+  async exposeFunction(
+    name: string,
+    handler: (data: any) => Promise<any> | any,
+    tabId = "default"
+  ): Promise<void> {
+    // Initialize handlers map for this tab if needed
+    if (!this.eventHandlers.has(tabId)) {
+      this.eventHandlers.set(tabId, new Map());
+    }
+    
+    // Store the handler
+    this.eventHandlers.get(tabId)!.set(name, async (data: any) => {
+      try {
+        const result = await handler(data);
+        // Return in expected format
+        if (result && typeof result === "object" && ("success" in result || "error" in result)) {
+          return result;
+        }
+        return { success: true, result };
+      } catch (err: any) {
+        return { success: false, error: err.message || String(err) };
+      }
+    });
+    
+    // Register with server
+    await this.send("expose.function", { name, tabId });
+    logger.success(`[${tabId}] exposed function: ${name}`);
+  }
+
+  async unexposeFunction(name: string, tabId = "default"): Promise<void> {
+    const handlers = this.eventHandlers.get(tabId);
+    if (handlers) {
+      handlers.delete(name);
+    }
+    logger.info(`[${tabId}] unexposed function: ${name}`);
+  }
+
+  async clearExposedFunctions(tabId = "default"): Promise<void> {
+    this.eventHandlers.set(tabId, new Map());
+    logger.info(`[${tabId}] cleared all exposed functions`);
+  }
 }

package/piggy/register/index.ts

@@ -278,6 +278,42 @@ export function createSiteObject(
       },
     },
 
+    // ── Expose Function ─────────────────────────────────────────────────────────
+
+    exposeFunction: async (fnName: string, handler: (data: any) => Promise<any> | any) => {
+      await client.exposeFunction(fnName, handler, tabId);
+      logger.success(`[${name}] exposed function: ${fnName}`);
+      return site;
+    },
+
+    unexposeFunction: async (fnName: string) => {
+      await client.unexposeFunction(fnName, tabId);
+      logger.info(`[${name}] unexposed function: ${fnName}`);
+      return site;
+    },
+
+    clearExposedFunctions: async () => {
+      await client.clearExposedFunctions(tabId);
+      logger.info(`[${name}] cleared all exposed functions`);
+      return site;
+    },
+
+    exposeAndInject: async (
+      fnName: string,
+      handler: (data: any) => Promise<any> | any,
+      injectionJs: string | ((fnName: string) => string)
+    ) => {
+      await client.exposeFunction(fnName, handler, tabId);
+      
+      const js = typeof injectionJs === "function" 
+        ? injectionJs(fnName) 
+        : injectionJs;
+        
+      await client.evaluate(js, tabId);
+      logger.success(`[${name}] exposed and injected: ${fnName}`);
+      return site;
+    },
+
     // ── Elysia API ─────────────────────────────────────────────────────────────
 
     api: (
@@ -313,4 +349,30 @@ export function createSiteObject(
   };
 
   return site;
+}
+
+// ── Helper for creating structured APIs ───────────────────────────────────────
+
+export function createExposedAPI<T extends Record<string, (data: any) => any>>(
+  site: any,
+  apiName: string,
+  handlers: T
+): Promise<void> {
+  const wrappedHandler = async (call: any) => {
+    const { method, args } = call;
+    const handler = handlers[method as keyof T];
+    
+    if (!handler) {
+      throw new Error(`Unknown method: ${method}`);
+    }
+    
+    try {
+      return await handler(args);
+    } catch (err) {
+      logger.error(`[${site._name}] API error in ${method}:`, err);
+      throw err;
+    }
+  };
+  
+  return site.exposeFunction(apiName, wrappedHandler);
 }

package/piggy.ts

@@ -64,6 +64,22 @@ const piggy: any = {
 
   mode: (m: TabMode) => { _tabMode = m; return piggy; },
 
+  // ── Expose Function (global) ─────────────────────────────────────────────────
+
+  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") => {
+    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?: { hostname?: string }) =>