shogun-core 6.9.6 → 6.9.8

package/README.md

@@ -89,92 +89,93 @@ const shogun = new ShogunCore({
 // All other APIs work the same way!
 ```
 
-## Basic Database Operations
+## Database API Reference
+
+The `shogun.db` instance provides a high-level API for interacting with the decentralized database. Shogun Core automatically handles the differences between **Gun** and **Holster** backends.
+
+### 1. Connection & Session Management
+These methods work with both backends.
+
+- `db.isLoggedIn(): boolean`: Returns `true` if a user is currently authenticated.
+- `db.getCurrentUser(): { pub: string; user?: any } | null`: Returns the current user's public key and instance.
+- `db.getUserPub(): string | null`: Returns the current user's public key.
+- `db.onAuth(callback: (user: any) => void): () => void`: Listens for authentication changes. Returns an unsubscribe function.
+- `db.restoreSession(): Promise<RestoreResult>`: Attempts to restore a previous session from `sessionStorage`.
+
+### 2. Promise-based Advanced Utilities (Firegun API)
+*Note: These methods currently provide full Promise support and auto-retries primarily when using the **Gun** backend.*
 
 ```typescript
 const db = shogun.db;
 
-// Store data using Gun chaining (Traditional Method)
-await db.get('users').get('alice').get('profile').put({
-  name: 'Alice Smith',
-  email: 'alice@example.com',
-});
+// Fetch data with auto-retry and 5s timeout
+const data = await db.Get('public/posts/123');
 
-// Read data
-const profile = await db.get('users').get('alice').get('profile').once().then();
+// Save data (supports deep object merging)
+await db.Put('public/settings', { theme: 'dark' });
 
-// Update specific fields
-await db
-  .get('users')
-  .get('alice')
-  .get('profile')
-  .get('name')
-  .put('Alice Johnson');
+// Insert into a collection with a random key
+await db.Set('public/logs', { event: 'login', time: Date.now() });
 
-// Iterate over collections with .map()
-db.get('users').map((user, userId) => {
-  console.log(`User ${userId}:`, user);
-});
-```
+// Recursive load of nested nodes
+const fullData = await db.Load('public/complex-node');
 
-### Promise-based Advanced Utilities (Firegun API)
+// "Delete" a node (Tombstoning)
+await db.Del('public/temp-data');
 
-Shogun Core includes built-in Promise wrappers, timeouts, and user-space utilities directly in the `DataBase` class:
+// Deeply nullify all keys in a node
+await db.purge('public/old-config');
+```
 
+### 3. Real-time Subscriptions
 ```typescript
-const db = shogun.db;
-
-// Promise-based Root GET with auto-retry
-const data = await db.Get('public/posts/123');
+// Listen to changes with an identifier for easy unsubscription
+db.On('public/feed', (data) => console.log('Update:', data), 'myListener');
 
-// Promise-based Root PUT (supports deep object merging)
-await db.Put('public/settings', { theme: 'dark' }, true);
-
-// Listen to node changes with easy unsubscribe
-await db.On(
-  'public/feed',
-  (data) => console.log('Feed updated:', data),
-  'myFeedListener',
-);
-await db.Off('myFeedListener'); // Cleanly remove the listener
-
-// Content Addressed Storage (CAS)
-// Hashes the data automatically using SHA-256 and saves it immutably
-const ack = await db.addContentAdressing('#immutable-posts', {
-  text: 'Hello Web3!',
-});
+// Stop listening
+db.Off('myListener');
 
-// --- User Space Operations ---
-// These automatically prefix the path with `~pubkey/` of the logged-in user
+// One-time fetch of initial state + future changes
+db.Listen('public/status', (status) => console.log('Status:', status));
+```
 
-// Read from current user's graph
-const userSettings = await db.userGet('settings');
+### 4. User-Space Operations (Gun Only)
+These methods automatically prefix the path with `~pubkey/` of the logged-in user.
 
-// Write to current user's graph
-await db.userPut('profile', { name: 'Alice' });
+- `db.userGet(path: string)`: Read from current user's graph.
+- `db.userPut(path: string, data: any)`: Write to current user's graph.
+- `db.userDel(path: string)`: Delete node from user's graph.
+- `db.userLoad(path: string)`: Recursively load user-space data.
 
-// Delete user node (Tombstoning)
-await db.userDel('old-post');
+### 5. Advanced Features
+- **Reactive Streams**: `db.rx()` returns an RxJS helper for observable-based data handling.
+- **Content Addressing**: `db.addContentAdressing('#key', data)` hashes data using SHA-256 for immutable storage.
+- **Security**: `db.generatePublicCert()` creates a public certificate for P2P interactions.
+- **Cleanup**: `db.aggressiveAuthCleanup()` forcefully clears all local auth state.
 
-// Purge (nullify all keys in a node)
-await db.purge('~pubkey/public/posts/123');
-```
+## Authentication API
 
-## Authentication Methods
+Shogun Core provides a unified authentication interface. Plugins (Web3, WebAuthn, etc.) extend this system.
 
-### 1. Traditional Authentication
+### Core Methods
 
 ```typescript
-// Sign up
-const signUpResult = await shogun.signUp('username', 'password');
-if (signUpResult.success) {
-  console.log('User created:', signUpResult.username);
-}
-
-// Login
-const loginResult = await shogun.login('username', 'password');
-if (loginResult.success) {
-  console.log('Logged in as:', loginResult.username);
+// 1. Traditional Signup/Login
+await shogun.signUp('alice', 'Password123!');
+await shogun.login('alice', 'Password123!');
+
+// 2. Pair-based Authentication (Gun Only)
+const pair = await shogun.db.crypto.createPair();
+await shogun.loginWithPair('alice', pair);
+
+// 3. Mnemonic Seed Authentication
+const mnemonic = 'word1 word2 ...';
+await shogun.loginWithSeed('alice', mnemonic);
+
+// 4. Session Check & Logout
+if (shogun.isLoggedIn()) {
+  console.log('User Pub:', shogun.db.getUserPub());
+  shogun.logout();
 }
 ```
 

package/dist/browser/shogun-core.js

@@ -61676,6 +61676,8 @@ var DataBaseHolster = /** @class */ (function () {
         var _a;
         /** Cached user instance or `null` if not logged in */
         this.user = null;
+        this.prefix = '';
+        this.ev = {};
         /** Registered callbacks for auth state changes */
         this.onAuthCallbacks = [];
         /** Whether the database instance has been destroyed */
@@ -62724,6 +62726,85 @@ var DataBaseHolster = /** @class */ (function () {
     DataBaseHolster.prototype.emit = function (event, data) {
         return this.eventEmitter.emit(event, data);
     };
+    // --- Firegun Methods Stubs ---
+    DataBaseHolster.prototype._timeout = function (ms) {
+        return db_holster_awaiter(this, void 0, void 0, function () {
+            return db_holster_generator(this, function (_a) {
+                return [2 /*return*/, new Promise(function (resolve) { return setTimeout(resolve, ms); })];
+            });
+        });
+    };
+    DataBaseHolster.prototype.Off = function (ev) {
+        if (ev === void 0) { ev = 'default'; }
+        console.warn('Off not implemented in DataBaseHolster');
+    };
+    DataBaseHolster.prototype.Listen = function (path, callback, prefix) {
+        if (prefix === void 0) { prefix = this.prefix; }
+        console.warn('Listen not implemented in DataBaseHolster');
+    };
+    DataBaseHolster.prototype.On = function (path, callback, ev, different, prefix) {
+        if (ev === void 0) { ev = 'default'; }
+        if (different === void 0) { different = true; }
+        if (prefix === void 0) { prefix = this.prefix; }
+        console.warn('On not implemented in DataBaseHolster');
+    };
+    DataBaseHolster.prototype.addContentAdressing = function (key, data) {
+        return Promise.reject(new Error('addContentAdressing not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.userGet = function (path, repeat, prefix) {
+        if (repeat === void 0) { repeat = 1; }
+        if (prefix === void 0) { prefix = this.prefix; }
+        return Promise.reject(new Error('userGet not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.userLoad = function (path, async, repeat, prefix) {
+        if (async === void 0) { async = false; }
+        if (repeat === void 0) { repeat = 1; }
+        if (prefix === void 0) { prefix = this.prefix; }
+        return Promise.reject(new Error('userLoad not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.Get = function (path, repeat, prefix) {
+        if (repeat === void 0) { repeat = 1; }
+        if (prefix === void 0) { prefix = this.prefix; }
+        return Promise.reject(new Error('Get not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.userPut = function (path, data, async, prefix) {
+        if (async === void 0) { async = false; }
+        if (prefix === void 0) { prefix = this.prefix; }
+        return Promise.reject(new Error('userPut not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.Set = function (path, data, async, prefix, opt) {
+        if (async === void 0) { async = false; }
+        if (prefix === void 0) { prefix = this.prefix; }
+        if (opt === void 0) { opt = undefined; }
+        return Promise.reject(new Error('Set not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.Put = function (path, data, async, prefix, opt) {
+        if (async === void 0) { async = false; }
+        if (prefix === void 0) { prefix = this.prefix; }
+        if (opt === void 0) { opt = undefined; }
+        return Promise.reject(new Error('Put not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.purge = function (path) {
+        return Promise.reject(new Error('purge not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.userDel = function (path, putNull) {
+        if (putNull === void 0) { putNull = true; }
+        return Promise.reject(new Error('userDel not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.Del = function (path, putNull, cert) {
+        if (putNull === void 0) { putNull = true; }
+        if (cert === void 0) { cert = ''; }
+        return Promise.reject(new Error('Del not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.Load = function (path, async, repeat, prefix) {
+        if (async === void 0) { async = false; }
+        if (repeat === void 0) { repeat = 1; }
+        if (prefix === void 0) { prefix = this.prefix; }
+        return Promise.reject(new Error('Load not implemented in DataBaseHolster'));
+    };
+    DataBaseHolster.prototype.generatePublicCert = function () {
+        return Promise.reject(new Error('generatePublicCert not implemented in DataBaseHolster'));
+    };
     Object.defineProperty(DataBaseHolster.prototype, "gun", {
         /**
          * Get the Holster instance (for backward compatibility with gun property).