nothing-innerstorage 1.0.0

package/Readme.MD

@@ -0,0 +1,91 @@
+# nothing-innerstorage
+
+Persists WhatsApp Web's `localStorage` to disk on every write, and re-injects it before WAWeb JS runs on the next restart — so your session survives process restarts without re-scanning the QR code.
+
+The C++ side (`PiggyInnerStorage`) handles all timing. This package is a thin JS wrapper.
+
+---
+
+## Install
+
+```bash
+npm install nothing-innerstorage
+```
+
+---
+
+## Usage
+
+```js
+const piggy        = require('nothing-browser').default;
+const innerstorage = require('nothing-innerstorage');
+
+await piggy.launch({ mode: 'tab', binary: 'headless' });
+await piggy.register('whatsapp', 'https://web.whatsapp.com', { single: true });
+
+await piggy.extend(
+  innerstorage({ path: './wa-storage.json' })
+);
+
+piggy.whatsapp.on('storage:loaded', (d) =>
+  console.log(`Session restored: ${d.keys} keys`)
+);
+
+piggy.whatsapp.on('storage:saved', (d) =>
+  console.log(`Session saved: ${d.keys} keys`)
+);
+
+await piggy.whatsapp.navigate();
+```
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `path` | `string` | `'./wa-storage.json'` | Where to persist the localStorage snapshot |
+| `onLoaded` | `function` | — | Called when C++ restores a session into the page |
+| `onSaved` | `function` | — | Called when C++ snapshots localStorage to disk |
+
+---
+
+## Events
+
+Listen via `site.on(event, handler)`:
+
+| Event | Data | When |
+|---|---|---|
+| `storage:loaded` | `{ tabId, keys }` | Every page load — C++ injected saved keys |
+| `storage:saved` | `{ tabId, keys }` | Every localStorage write — C++ saved snapshot |
+
+---
+
+## API (`site.storage`)
+
+```js
+// Read one key from the live page localStorage
+const val = await piggy.whatsapp.storage.get('wa-secret-bundle');
+
+// Dump all keys from the live page localStorage
+const all = await piggy.whatsapp.storage.dump();
+
+// Wipe localStorage in-page AND delete the snapshot file (forces new QR)
+await piggy.whatsapp.storage.clear();
+```
+
+---
+
+## How it works
+
+- C++ hooks `loadFinished` → injects saved snapshot into `localStorage` before WAWeb reads it
+- C++ installs a JS hook that intercepts every `localStorage.setItem/removeItem/clear` call
+- On each change, C++ snapshots the full localStorage and writes it to the file at `path`
+- On restart, snapshot is re-injected — WAWeb sees its session as intact
+
+## Notes
+
+- Do **not** call `session.reload()` after installing this plugin — it uses older timing and will conflict
+- To force a fresh QR scan: call `site.storage.clear()` before navigating
+- This plugin was made upon request and need report any issues found
+-This plugin is tailord specificaly for whatsap sessions you can use it on other sites but no guarantee of working and that is not a bug sonner or later nothing-storage plugin will be released to solve that

package/index.d.ts

@@ -0,0 +1,46 @@
+export interface InnerStorageOptions {
+  /** Path where localStorage is persisted to disk. Default: './wa-storage.json' */
+  path?: string;
+  /** Called when C++ restores a saved session into the page (fires on every page load). */
+  onLoaded?: (data: { tabId: string; keys: number }) => void;
+  /** Called when C++ snapshots localStorage to disk (fires on every localStorage write). */
+  onSaved?: (data: { tabId: string; keys: number }) => void;
+}
+
+export interface StorageAPI {
+  /** Read a single key directly from the live localStorage in-page. */
+  get(key: string): Promise<string | null>;
+  /** Dump all localStorage keys from the live page. */
+  dump(): Promise<Record<string, string>>;
+  /**
+   * Wipe localStorage in-page AND delete the persisted snapshot file.
+   * Forces a fresh QR scan on the next restart.
+   */
+  clear(): Promise<void>;
+}
+
+/**
+ * nothing-innerstorage plugin factory.
+ *
+ * Returns an installer function. Pass it to `piggy.extend()` or call it manually:
+ *
+ * ```js
+ * // via extend (recommended)
+ * await piggy.extend(innerstorage({ path: './wa-storage.json' }));
+ *
+ * // manually
+ * await innerstorage({ path: './wa-storage.json' })(piggy.mysite);
+ * ```
+ */
+declare function innerstorage(opts?: InnerStorageOptions): (site: any) => Promise<any>;
+
+export default innerstorage;
+export = innerstorage;
+
+// Augment the site object type produced by nothing-browser
+declare module 'nothing-browser' {
+  interface PiggySite {
+    /** localStorage persistence API — added by nothing-innerstorage */
+    storage: StorageAPI;
+  }
+}

package/index.ts

@@ -0,0 +1,101 @@
+'use strict';
+
+// nothing-innerstorage
+// Wraps the C++ PiggyInnerStorage plugin already compiled into the binary.
+// Persists WhatsApp Web's localStorage to disk on every write,
+// and re-injects it before WAWeb JS runs on the next restart.
+//
+// C++ events this listens for:
+//   storage:loaded  { tabId, keys }  — session restored into page
+//   storage:saved   { tabId, keys }  — snapshot written to disk
+//
+// C++ commands this sends:
+//   storage.get   { key }    → string | null
+//   storage.dump  {}         → { key: value, ... }
+//   storage.clear {}         → "storage cleared"
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.path='./wa-storage.json']  Path where localStorage is persisted.
+ * @param {function} [opts.onLoaded]                Called when C++ restores a session.
+ * @param {function} [opts.onSaved]                 Called when C++ snapshots localStorage.
+ * @returns {function} Plugin installer — pass to piggy.extend() or call manually.
+ */
+module.exports = function innerstorage(opts) {
+  opts = opts || {};
+
+  const storagePath = opts.path || './wa-storage.json';
+
+  return async function install(site) {
+    if (!site || typeof site.on !== 'function' || typeof site.evaluate !== 'function') {
+      throw new Error(
+        '[nothing-innerstorage] install() received an invalid site object. ' +
+        'Make sure you registered the site with { single: true } and called piggy.extend() after piggy.register().'
+      );
+    }
+
+    // ── Event listeners ──────────────────────────────────────────────────────
+
+    site.on('storage:loaded', function(data) {
+      if (typeof opts.onLoaded === 'function') opts.onLoaded(data);
+    });
+
+    site.on('storage:saved', function(data) {
+      if (typeof opts.onSaved === 'function') opts.onSaved(data);
+    });
+
+    // ── Attach API to site ───────────────────────────────────────────────────
+    // The C++ side already handles injection timing (after loadFinished) and
+    // snapshotting (on every localStorage write via the installed JS hook).
+    // These commands let you read/inspect the persisted state from Node if needed.
+
+    site.storage = {
+      /**
+       * Read a single key from the persisted localStorage snapshot.
+       * @param {string} key
+       * @returns {Promise<string|null>}
+       */
+      get: function(key) {
+        if (!key || typeof key !== 'string') {
+          return Promise.reject(new Error('[nothing-innerstorage] storage.get() requires a non-empty string key'));
+        }
+        return site.evaluate(
+          `(function(k){ return localStorage.getItem(k); })(${JSON.stringify(key)})`
+        );
+      },
+
+      /**
+       * Dump the entire persisted localStorage snapshot from disk.
+       * @returns {Promise<Record<string, string>>}
+       */
+      dump: function() {
+        return site.evaluate(
+          `(function(){
+            var out = {};
+            for (var i = 0; i < localStorage.length; i++) {
+              var k = localStorage.key(i);
+              out[k] = localStorage.getItem(k);
+            }
+            return out;
+          })()`
+        );
+      },
+
+      /**
+       * Wipe the persisted snapshot from disk AND clear localStorage in-page.
+       * Use this to force a fresh QR scan on next boot.
+       * @returns {Promise<void>}
+       */
+      clear: function() {
+        return site.evaluate(
+          `(function(){ localStorage.clear(); return 'cleared'; })()`
+        ).then(function() {
+          var fs = require('fs');
+          try { fs.unlinkSync(storagePath); } catch (_) { /* file may not exist yet */ }
+        });
+      },
+    };
+
+    return site;
+  };
+};

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "nothing-innerstorage",
+  "version": "1.0.0",
+  "description": "nothing-browser plugin — persists WhatsApp Web localStorage to disk via the C++ PiggyInnerStorage engine",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "keywords": ["nothing-browser", "piggy", "whatsapp", "localStorage", "session", "plugin"],
+  "peerDependencies": {
+    "nothing-browser": "*"
+  }
+}