shogun-core 6.9.7 → 6.9.9

package/README.md

@@ -6,18 +6,13 @@
 
 ## Overview
 
-Shogun Core is a comprehensive SDK for building decentralized applications (dApps) that simplifies authentication, wallet management, and decentralized data storage. It combines GunDB's or Holster's peer-to-peer networking with modern authentication standards and blockchain integration.
-
-**Now supports both Gun and Holster!** You can use either database backend - Gun for maximum compatibility or Holster for modern ES modules and improved performance.
+Shogun Core is a comprehensive SDK for building decentralized applications (dApps) that simplifies authentication, wallet management, and decentralized data storage. It utilizes GunDB's peer-to-peer networking with modern authentication standards and blockchain integration.
 
 ## Features
 
 - 🔐 **Multiple Authentication Methods**: Password, WebAuthn (biometrics), Web3 (MetaMask), Nostr, Challenge (Server-Signed)
-- 🌐 **Decentralized Storage**: Built on GunDB or Holster for peer-to-peer data synchronization
-- 🔄 **Dual Database Support**: Use Gun (maximum compatibility) or Holster (modern ES modules, improved performance)
+- 🌐 **Decentralized Storage**: Built on GunDB for peer-to-peer data synchronization
 - 🔌 **Plugin System**: Extensible architecture with built-in plugins
-
-- 📱 **Reactive Programming**: RxJS integration for real-time data streams
 - 🛡️ **Security**: End-to-end encryption and secure key management
 - 🎯 **TypeScript**: Full TypeScript support with comprehensive type definitions
 
@@ -31,7 +26,7 @@ yarn add shogun-core
 
 ## Quick Start
 
-### Using Gun (Default)
+### Basic Initialization
 
 ```typescript
 import { ShogunCore } from 'shogun-core';
@@ -61,120 +56,93 @@ const shogun = new ShogunCore({
 });
 ```
 
-### Using Holster (Alternative)
 
-```typescript
-import { ShogunCore } from 'shogun-core';
-import Holster from '@mblaney/holster';
 
-// Create Holster instance first
-const holster = Holster({
-  peers: ['ws://localhost:8765'],
-});
+## Database API Reference
 
-// Initialize Shogun Core with the Holster instance
-const shogun = new ShogunCore({
-  holsterInstance: holster, // Use Holster instead of Gun
+The `shogun.db` instance provides a high-level API for interacting with the decentralized database.
 
-  // Enable authentication plugins (same as Gun)
-  web3: { enabled: true },
-  webauthn: {
-    enabled: true,
-    rpName: 'My Awesome App',
-    rpId: window.location.hostname,
-  },
-  nostr: { enabled: true },
-});
+### 1. Connection & Session Management
 
-// All other APIs work the same way!
-```
+- `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`.
 
-## Basic Database Operations
+### 2. Promise-based Advanced Utilities (Firegun API)
+*Note: These methods provide full Promise support and auto-retries.*
 
 ```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;
+// Listen to changes with an identifier for easy unsubscription
+db.On('public/feed', (data) => console.log('Update:', data), 'myListener');
 
-// Promise-based Root GET with auto-retry
-const data = await db.Get('public/posts/123');
+// Stop listening
+db.Off('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!',
-});
-
-// --- 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
+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
+- **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
+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();
 }
 ```
 
@@ -345,41 +313,7 @@ console.log('Chat Pub:', chatPair.pub);
 </html>
 ```
 
-### With Holster (ES Modules)
 
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>Shogun Core with Holster</title>
-  </head>
-  <body>
-    <h1>My dApp</h1>
-    <script type="module">
-      import Holster from 'https://cdn.jsdelivr.net/npm/@mblaney/holster/build/holster.js';
-      import { ShogunCore } from 'https://cdn.jsdelivr.net/npm/shogun-core/dist/src/index.js';
-
-      // Create Holster instance
-      const holster = Holster({
-        peers: ['ws://localhost:8765'],
-      });
-
-      // Initialize Shogun Core
-      const shogunCore = new ShogunCore({
-        holsterInstance: holster,
-        web3: { enabled: true },
-        webauthn: {
-          enabled: true,
-          rpName: 'My Browser dApp',
-          rpId: window.location.hostname,
-        },
-      });
-
-      console.log('Shogun Core initialized with Holster!', shogunCore);
-    </script>
-  </body>
-</html>
-```
 
 ## Event System
 
@@ -404,36 +338,13 @@ shogun.on('error', (error) => {
 });
 ```
 
-## Database Backend: Gun vs Holster
-
-Shogun Core supports both Gun and Holster as database backends. Choose based on your needs:
 
-### Gun (Default)
-
-- **Pros**: Maximum compatibility, large ecosystem, battle-tested
-- **Cons**: Older codebase, CommonJS modules
-- **Best for**: Existing projects, maximum compatibility
-
-### Holster
-
-- **Pros**: Modern ES modules, improved performance, cleaner API
-- **Cons**: Newer project, smaller ecosystem
-- **Best for**: New projects, modern build systems, performance-critical apps
-
-**Note**: The API is identical regardless of which backend you choose. Shogun Core handles all the differences internally.
-
-### Differences to be aware of:
-
-- **Pair-based authentication**: Currently only supported with Gun (username/password works with both)
-- **Event system**: Gun has native events, Holster uses polling (handled automatically)
-- **Chaining API**: Gun uses `.get().get()`, Holster uses `.get().next()` (handled automatically via proxy)
 
 ## Configuration Options
 
 ```typescript
 interface ShogunCoreConfig {
-  gunInstance?: IGunInstance<any>; // Optional: existing Gun instance (required if holsterInstance not provided)
-  holsterInstance?: any; // Optional: existing Holster instance (required if gunInstance not provided)
+  gunInstance?: IGunInstance<any>; // Optional: existing Gun instance
 
   // Plugin configurations
   webauthn?: {
@@ -470,45 +381,7 @@ interface ShogunCoreConfig {
 }
 ```
 
-**Note**:
-
-- Either `gunInstance` or `holsterInstance` must be provided (but not both)
-
-## Migration Guide
-
-### From Gun to Holster
-
-If you're currently using Gun and want to switch to Holster:
-
-1. **Install Holster**:
-
-   ```bash
-   npm install @mblaney/holster
-   # or
-   yarn add @mblaney/holster
-   ```
-
-2. **Update your initialization**:
-
-   ```typescript
-   // Before (Gun)
-   import Gun from "gun";
-   const gun = Gun({ peers: [...] });
-   const shogun = new ShogunCore({ gunInstance: gun });
-
-   // After (Holster)
-   import Holster from "@mblaney/holster";
-   const holster = Holster({ peers: [...] });
-   const shogun = new ShogunCore({ holsterInstance: holster });
-   ```
-
-3. **That's it!** All other code remains the same. The API is identical.
-
-### Limitations when using Holster
 
-- Pair-based authentication (`loginWithPair()`) is not yet supported - use username/password instead
-- Some advanced Gun features may not be available
-- Event system uses polling instead of native events (handled automatically)
 
 ## Testing