nothing-qrcpp 1.0.0

package/README.md

@@ -0,0 +1,99 @@
+# nothing-qrcpp
+
+Typed event callbacks and manual control API for the C++ QR detector built into the Nothing Browser binary (`PiggyQRDetector`).
+
+The detector runs **automatically** — you do not need this package to receive QR events. It exists for discoverability, typed callbacks, and the `site.qr` control API.
+
+---
+
+## Install
+
+```bash
+npm install nothing-qrcpp
+```
+
+---
+
+## Usage
+
+```js
+const piggy  = require('nothing-browser').default;
+const qrcpp  = require('nothing-qrcpp');
+const fs     = require('fs');
+
+await piggy.launch({ mode: 'tab', binary: 'headless' });
+await piggy.register('whatsapp', 'https://web.whatsapp.com', { single: true });
+
+await piggy.extend(
+  qrcpp({
+    onQR:      (d) => console.log(`Scan this QR (attempt ${d.attempts}):`, d.qrData),
+    onScanned: ()  => console.log('Authenticated!'),
+    onTimeout: ()  => console.log('QR rotated — new one incoming...'),
+  })
+);
+
+await piggy.whatsapp.navigate();
+```
+
+### Without this package
+
+If you don't want the dependency, you can listen directly — the C++ emits these events regardless:
+
+```js
+piggy.whatsapp.on('qr',         (d) => console.log('Scan:', d.qrData));
+piggy.whatsapp.on('qr:scanned', ()  => console.log('Done!'));
+piggy.whatsapp.on('qr:timeout', ()  => console.log('Rotated'));
+```
+
+---
+
+## Options
+
+| Option | Type | When called |
+|---|---|---|
+| `onQR` | `function` | New or rotated QR is ready. `data.qrData` is `"data:image/png;base64,..."` |
+| `onScanned` | `function` | QR scanned, WAWeb authenticated |
+| `onTimeout` | `function` | QR expired and rotated (~every 20s) |
+
+---
+
+## Events
+
+| Event | Data | When |
+|---|---|---|
+| `qr` | `{ tabId, qrData, attempts }` | New QR ready — `qrData` is a base64 PNG data URL |
+| `qr:scanned` | `{ tabId }` | Canvas disappeared — auth succeeded |
+| `qr:timeout` | `{ tabId }` | QR rotated before being scanned |
+
+---
+
+## API (`site.qr`)
+
+```js
+// Check current QR state
+const state = await piggy.whatsapp.qr.status();
+// { waiting: true, attempts: 2 }
+
+// Force an immediate canvas check (skips the 500ms poll interval)
+await piggy.whatsapp.qr.force();
+```
+
+---
+
+## How the C++ detector works
+
+- Polls the page every 500ms for a `<canvas>` matching known WAWeb QR selectors
+- Extracts the canvas as a base64 PNG via `canvas.toDataURL()`
+- Hashes the image to detect rotation — only emits `qr` when the image actually changes
+- Prints the QR to the terminal automatically using iTerm2/Kitty inline image protocol with a plain data URL fallback
+- When the canvas disappears, emits `qr:scanned` and stops polling
+
+---
+
+## Notes
+
+- To force a fresh QR scan: call `site.storage.clear()` before navigating (requires `nothing-innerstorage`)
+- This plugin was made upon request — report any issues found
+- This plugin is tailored specifically for WhatsApp sessions. You can use it on other sites but there is no guarantee it will work, and that is not a bug. A general-purpose `nothing-storage` plugin will be released in the future to solve that
+- `qrData` is a `data:image/png;base64,...` URL — render it in a browser, pass it to a QR library, or display it in the terminal. The C++ already prints it automatically
+- The QR is canvas-based in WAWeb — there is no `<img>` tag. Do not try to read it with `find.css()` or `provide.text()`

package/index.d.ts

@@ -0,0 +1,41 @@
+export interface QRCppOptions {
+  /** Called when a new or rotated QR code is ready to scan. */
+  onQR?: (data: { tabId: string; qrData: string; attempts: number }) => void;
+  /** Called when the QR is scanned and WhatsApp Web authenticates successfully. */
+  onScanned?: (data: { tabId: string }) => void;
+  /** Called when the QR expires and rotates before being scanned (~every 20s). */
+  onTimeout?: (data: { tabId: string }) => void;
+}
+
+export interface QRApi {
+  /** Check whether C++ is waiting for a QR scan and how many have been shown. */
+  status(): Promise<{ waiting: boolean; attempts: number }>;
+  /** Force an immediate canvas check without waiting for the next poll interval. */
+  force(): Promise<string>;
+}
+
+/**
+ * nothing-qrcpp plugin factory.
+ *
+ * The QR detector runs automatically inside the binary — this package adds
+ * typed event callbacks and the `site.qr` API for manual control.
+ *
+ * ```js
+ * await piggy.extend(qrcpp({
+ *   onQR:      (d) => console.log('Scan this:', d.qrData),
+ *   onScanned: ()  => console.log('Authenticated!'),
+ *   onTimeout: ()  => console.log('QR rotated, new one incoming...'),
+ * }));
+ * ```
+ */
+declare function qrcpp(opts?: QRCppOptions): (site: any) => Promise<any>;
+
+export default qrcpp;
+export = qrcpp;
+
+declare module 'nothing-browser' {
+  interface PiggySite {
+    /** QR code control API — added by nothing-qrcpp */
+    qr: QRApi;
+  }
+}

package/index.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// nothing-qrcpp
+// Wraps the C++ PiggyQRDetector built into the Nothing Browser binary.
+// The QR detector runs automatically — no activation needed.
+// This package is a thin event/API wrapper for discoverability and convenience.
+//
+// C++ events this listens for:
+//   qr          { tabId, qrData, attempts }  — new or rotated QR ready to scan
+//   qr:scanned  { tabId }                    — QR canvas disappeared, auth done
+//   qr:timeout  { tabId }                    — QR rotated (~every 20s), new one incoming
+//
+// C++ commands this sends:
+//   qr.status  {}  → { waiting: bool, attempts: int }
+//   qr.force   {}  → "qr check triggered"
+
+/**
+ * @param {object} opts
+ * @param {function} [opts.onQR]       Called when a new QR code is ready. Receives { tabId, qrData, attempts }.
+ * @param {function} [opts.onScanned]  Called when the QR is scanned and auth succeeds.
+ * @param {function} [opts.onTimeout]  Called when the QR rotates before being scanned.
+ * @returns {function} Plugin installer — pass to piggy.extend() or call manually.
+ */
+module.exports = function qrcpp(opts) {
+  opts = opts || {};
+
+  return async function install(site) {
+    if (!site || typeof site.on !== 'function') {
+      throw new Error(
+        '[nothing-qrcpp] install() received an invalid site object. ' +
+        'Make sure you registered the site with { single: true } and called piggy.extend() after piggy.register().'
+      );
+    }
+
+    if (typeof site._send !== 'function') {
+      throw new Error(
+        '[nothing-qrcpp] site._send is not available. ' +
+        'Use piggy.extend() to install plugins — it wires _send automatically. ' +
+        'If installing manually, attach site._send before calling install().'
+      );
+    }
+
+    // ── Event listeners ──────────────────────────────────────────────────────
+
+    site.on('qr', function(data) {
+      if (typeof opts.onQR === 'function') opts.onQR(data);
+    });
+
+    site.on('qr:scanned', function(data) {
+      if (typeof opts.onScanned === 'function') opts.onScanned(data);
+    });
+
+    site.on('qr:timeout', function(data) {
+      if (typeof opts.onTimeout === 'function') opts.onTimeout(data);
+    });
+
+    // ── Attach API to site ───────────────────────────────────────────────────
+
+    site.qr = {
+      /**
+       * Check whether the C++ detector is currently waiting for a QR scan
+       * and how many QR codes have been shown this session.
+       * @returns {Promise<{ waiting: boolean, attempts: number }>}
+       */
+      status: function() {
+        return site._send('qr.status', {});
+      },
+
+      /**
+       * Force the C++ detector to run a canvas check immediately,
+       * without waiting for the next poll interval (500ms).
+       * @returns {Promise<string>}
+       */
+      force: function() {
+        return site._send('qr.force', {});
+      },
+    };
+
+    return site;
+  };
+};

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "nothing-qrcpp",
+  "version": "1.0.0",
+  "description": "nothing-browser plugin — typed event wrapper and control API for the C++ PiggyQRDetector built into the Nothing Browser binary",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "keywords": ["nothing-browser", "piggy", "whatsapp", "qr", "qrcode", "plugin"],
+  "peerDependencies": {
+    "nothing-browser": "*"
+  }
+}