shogun-core 6.9.7 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shogun-core",
-  "version": "6.9.7",
+  "version": "6.9.8",
   "type": "module",
   "description": "SHOGUN CORE - Core library for Shogun Ecosystem",
   "main": "./dist/src/index.js",