nothing-cookiesinject 1.0.0

package/Readme.Md

@@ -0,0 +1,108 @@
+# nothing-cookiesinject
+
+Injects cookies from a JSON file into the browser **before page JS runs**, solving the WhatsApp Web authentication race condition that `SessionManager` alone cannot fix.
+
+The C++ side (`PiggyCookieInject`) hooks `loadStarted` — not `loadFinished` — so cookies are in the store before WAWeb's WebSocket auth check fires.
+
+---
+
+## Install
+
+```bash
+npm install nothing-cookiesinject
+```
+
+---
+
+## Usage
+
+```js
+const piggy         = require('nothing-browser').default;
+const cookiesinject = require('nothing-cookiesinject');
+const fs            = require('fs');
+
+await piggy.launch({ mode: 'tab', binary: 'headless' });
+await piggy.register('whatsapp', 'https://web.whatsapp.com', { single: true });
+
+await piggy.extend(
+  cookiesinject({ cookieFile: './wa-cookies.json' })
+);
+
+// Save cookies after first authentication so they're available on next restart
+piggy.whatsapp.on('authenticated', async () => {
+  const cookies = await piggy.whatsapp.cookies.list();
+  fs.writeFileSync('./wa-cookies.json', JSON.stringify(cookies, null, 2));
+  console.log('Cookies saved — next restart will skip the QR code');
+});
+
+piggy.whatsapp.on('cookies:injected', (d) =>
+  console.log(`${d.count} cookies injected (${d.skipped} skipped)`)
+);
+
+await piggy.whatsapp.navigate();
+```
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cookieFile` | `string` | `'./wa-cookies.json'` | Path to the cookies JSON file |
+| `onInjected` | `function` | — | Called every time C++ injects cookies |
+
+---
+
+## Events
+
+| Event | Data | When |
+|---|---|---|
+| `cookies:injected` | `{ tabId, count, skipped, file }` | Every page load — C++ injected cookies before WAWeb booted |
+
+---
+
+## API (`site.cookieinject`)
+
+```js
+// Re-read file and inject into current tab right now
+await piggy.whatsapp.cookieinject.reload();
+
+// Check plugin status
+const status = await piggy.whatsapp.cookieinject.status();
+// { active: true, file: './wa-cookies.json', injected: 14 }
+
+// Swap cookie file without restarting
+await piggy.whatsapp.cookieinject.setFile('./backup-cookies.json');
+```
+
+---
+
+## Cookie file format
+
+The file must be a JSON array. Domain **must** have a leading dot:
+
+```json
+[
+  {
+    "name": "sid",
+    "value": "abc123",
+    "domain": ".whatsapp.net",
+    "path": "/",
+    "secure": true,
+    "httpOnly": true,
+    "expires": 1735689600
+  }
+]
+```
+
+> ⚠️ `.whatsapp.net` not `whatsapp.net` — the C++ normalises this automatically, but your exported file should already have the dot to avoid confusion.
+
+---
+
+## 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
+- Do **not** call `session.reload()` alongside this plugin — it injects at the wrong timing and will conflict
+- On first run, if `wa-cookies.json` does not exist yet, the plugin loads silently and activates automatically once the file appears after your first QR scan

package/index.d.ts

@@ -0,0 +1,36 @@
+export interface CookieInjectOptions {
+  /** Path to the cookies JSON file. Default: './wa-cookies.json' */
+  cookieFile?: string;
+  /** Called every time C++ injects cookies into the page. */
+  onInjected?: (data: { tabId: string; count: number; skipped: number; file: string }) => void;
+}
+
+export interface CookieInjectAPI {
+  /** Re-read the cookie file from disk and inject immediately into the current tab. */
+  reload(): Promise<string>;
+  /** Alias for reload — force-inject cookies right now. */
+  inject(): Promise<string>;
+  /** Check plugin status: whether it's active and how many cookies it last injected. */
+  status(): Promise<{ active: boolean; file: string; injected: number }>;
+  /** Point the C++ plugin at a different cookie file without restarting. */
+  setFile(file: string): Promise<string>;
+}
+
+/**
+ * nothing-cookiesinject plugin factory.
+ *
+ * ```js
+ * await piggy.extend(cookiesinject({ cookieFile: './wa-cookies.json' }));
+ * ```
+ */
+declare function cookiesinject(opts?: CookieInjectOptions): (site: any) => Promise<any>;
+
+export default cookiesinject;
+export = cookiesinject;
+
+declare module 'nothing-browser' {
+  interface PiggySite {
+    /** Cookie injection API — added by nothing-cookiesinject */
+    cookieinject: CookieInjectAPI;
+  }
+}

package/index.ts

@@ -0,0 +1,105 @@
+'use strict';
+
+// nothing-cookiesinject
+// Wraps the C++ PiggyCookieInject plugin already compiled into the binary.
+// Injects cookies from a JSON file into the browser BEFORE page JS runs,
+// solving the WAWeb authentication race condition that SessionManager alone
+// cannot fix (it injects too late — after WAWeb's auth check fires).
+//
+// C++ events this listens for:
+//   cookies:injected  { tabId, count, skipped, file }
+//
+// C++ commands this sends:
+//   cookieinject.setFile  { file }  → "cookie file updated: path"
+//   cookieinject.reload   {}        → "re-injected N cookies"
+//   cookieinject.inject   {}        → "injected N cookies into tab X"
+//   cookieinject.status   {}        → { active, file, injected }
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.cookieFile='./wa-cookies.json']  Path to the cookies JSON file.
+ * @param {function} [opts.onInjected]                    Called when C++ injects cookies.
+ * @returns {function} Plugin installer — pass to piggy.extend() or call manually.
+ */
+module.exports = function cookiesinject(opts) {
+  opts = opts || {};
+
+  var cookieFile = opts.cookieFile || './wa-cookies.json';
+
+  return async function install(site) {
+    if (!site || typeof site.on !== 'function') {
+      throw new Error(
+        '[nothing-cookiesinject] install() received an invalid site object. ' +
+        'Make sure you registered the site with { single: true } and called piggy.extend() after piggy.register().'
+      );
+    }
+
+    // _send is guaranteed by piggy.extend() before any installer runs.
+    // If you're calling install() manually (without extend()), wire it yourself:
+    //   site._send = (cmd, payload) => yourClient.send(cmd, { tabId: 'default', ...payload });
+    if (typeof site._send !== 'function') {
+      throw new Error(
+        '[nothing-cookiesinject] site._send is not available. ' +
+        'Use piggy.extend() to install plugins — it wires _send automatically. ' +
+        'If installing manually, attach site._send before calling install().'
+      );
+    }
+
+    // Tell C++ which file to use. Only if the file already exists —
+    // on a first run there are no cookies yet, so we skip this.
+    // C++ will still activate when the file appears (after first QR auth).
+    var fs = require('fs');
+    if (fs.existsSync(cookieFile)) {
+      await site._send('cookieinject.setFile', { file: cookieFile });
+    }
+
+    // ── Event listeners ──────────────────────────────────────────────────────
+
+    site.on('cookies:injected', function(data) {
+      if (typeof opts.onInjected === 'function') opts.onInjected(data);
+    });
+
+    // ── Attach API to site ───────────────────────────────────────────────────
+
+    site.cookieinject = {
+      /**
+       * Re-read the cookie file from disk and inject immediately into the current tab.
+       * @returns {Promise<string>}
+       */
+      reload: function() {
+        return site._send('cookieinject.reload', {});
+      },
+
+      /**
+       * Alias for reload — force-inject cookies into the tab right now.
+       * @returns {Promise<string>}
+       */
+      inject: function() {
+        return site._send('cookieinject.inject', {});
+      },
+
+      /**
+       * Check whether the C++ plugin is active and how many cookies it last injected.
+       * @returns {Promise<{ active: boolean, file: string, injected: number }>}
+       */
+      status: function() {
+        return site._send('cookieinject.status', {});
+      },
+
+      /**
+       * Point the C++ plugin at a different cookie file without restarting.
+       * File must be a JSON array — see README for the required format.
+       * @param {string} file
+       * @returns {Promise<string>}
+       */
+      setFile: function(file) {
+        if (!file || typeof file !== 'string') {
+          return Promise.reject(new Error('[nothing-cookiesinject] setFile() requires a non-empty file path'));
+        }
+        return site._send('cookieinject.setFile', { file: file });
+      },
+    };
+
+    return site;
+  };
+};

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "nothing-cookiesinject",
+  "version": "1.0.0",
+  "description": "nothing-browser plugin — injects cookies before page JS runs via the C++ PiggyCookieInject engine, fixing the WAWeb auth race condition",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "keywords": ["nothing-browser", "piggy", "whatsapp", "cookies", "session", "plugin"],
+  "peerDependencies": {
+    "nothing-browser": "*"
+  }
+}