holosphere 2.0.0-alpha1 → 2.0.0-alpha10

package/src/core/holosphere.js

@@ -1,7 +1,45 @@
+/**
+ * @fileoverview Core HoloSphere class providing the foundational infrastructure
+ * for holonic geospatial communication.
+ *
+ * This module implements the core HoloSphere class that supports multiple storage
+ * backends (Nostr, GunDB, ActivityPub) and provides essential operations for
+ * distributed P2P communication and data management.
+ *
+ * @module core/holosphere
+ */
+
 import { createClient } from '../storage/nostr-client.js';
 import { BackendFactory } from '../storage/backend-factory.js';
+import * as gunWrapper from '../storage/gun-wrapper.js';
+import * as gunFederation from '../storage/gun-federation.js';
+import { GunDBBackend } from '../storage/backends/gundb-backend.js';
 import pkg from '../../package.json' with { type: 'json' };
 
+/** @type {Function|null} Gun constructor, loaded dynamically */
+let Gun = null;
+/** @type {Promise<Function>|null} Promise for Gun loading */
+let gunLoadPromise = null;
+
+/**
+ * Dynamically loads the Gun module.
+ * Uses lazy loading to reduce initial bundle size and improve startup time.
+ *
+ * @private
+ * @returns {Promise<Function>} Gun constructor
+ */
+async function loadGun() {
+  if (Gun) return Gun;
+  if (gunLoadPromise) return gunLoadPromise;
+
+  gunLoadPromise = import('gun').then(module => {
+    Gun = module.default || module;
+    return Gun;
+  });
+
+  return gunLoadPromise;
+}
+
 /**
  * Get environment variable (works in Node.js, returns undefined in browser)
  * @param {string} name - Environment variable name
@@ -27,9 +65,20 @@ function getDefaultRelays() {
 }
 
 /**
- * HoloSphere - Holonic Geospatial Communication Infrastructure
- * Combines H3 hexagonal indexing with distributed P2P storage
- * Supports multiple storage backends: nostr, gundb, activitypub
+ * HoloSphere - Holonic Geospatial Communication Infrastructure.
+ *
+ * The core class that combines H3 hexagonal indexing with distributed P2P storage.
+ * Supports multiple storage backends including Nostr, GunDB, and ActivityPub.
+ *
+ * @class HoloSphere
+ * @example
+ * // Create with Nostr backend (default)
+ * const hs = new HoloSphere({ appName: 'myapp', relays: ['wss://relay.example.com'] });
+ *
+ * @example
+ * // Create with GunDB backend
+ * const hs = new HoloSphere({ appName: 'myapp', backend: 'gundb' });
+ * await hs.ready(); // Wait for async initialization
  */
 export class HoloSphere {
   /**
@@ -38,7 +87,7 @@ export class HoloSphere {
    * @param {string} config.backend - Storage backend: 'nostr' | 'gundb' | 'activitypub' (default: 'nostr')
    * @param {string[]} config.relays - Nostr relay URLs (default from HOLOSPHERE_RELAYS env or ['wss://relay.holons.io', 'wss://relay.nostr.band'])
    * @param {string} config.privateKey - Private key for signing (hex format, optional)
-   * @param {string} config.logLevel - Log verbosity: ERROR|WARN|INFO|DEBUG (default: 'WARN')
+   * @param {string} config.logLevel - Log verbosity: ERROR|WARN|INFO|DEBUG (default: 'INFO')
    * @param {boolean} config.hybridMode - Enable hybrid mode (local + relay queries) (default: true)
    * @param {Object} config.gundb - GunDB-specific configuration
    * @param {Object} config.activitypub - ActivityPub-specific configuration
@@ -74,7 +123,7 @@ export class HoloSphere {
       backend: config.backend || 'nostr',
       relays: config.relays || getDefaultRelays(),
       privateKey: config.privateKey || getEnv('HOLOSPHERE_PRIVATE_KEY'),
-      logLevel: config.logLevel || getEnv('HOLOSPHERE_LOG_LEVEL') || 'WARN',
+      logLevel: config.logLevel || getEnv('HOLOSPHERE_LOG_LEVEL') || 'INFO',
       hybridMode: config.hybridMode !== false, // Enable by default
     };
 
@@ -89,9 +138,12 @@ export class HoloSphere {
     this._backend = null;
 
     // For backward compatibility with Nostr, initialize synchronously
-    // Other backends use async initialization via _backendReady
+    // GunDB and other backends use async initialization via _backendReady
     if (this.config.backend === 'nostr') {
       this._initNostrSync(config);
+    } else if (this.config.backend === 'gundb') {
+      // GunDB uses async init due to dynamic import
+      this._backendReady = this._initGunDBAsync(config);
     } else {
       // Async initialization for other backends
       this._backendReady = this._initBackendAsync(config);
@@ -143,6 +195,68 @@ export class HoloSphere {
     }
   }
 
+  /**
+   * Initialize GunDB backend asynchronously (for browser compatibility with dynamic import)
+   * @private
+   */
+  async _initGunDBAsync(config) {
+    try {
+      const gundbConfig = config.gundb || {};
+
+      // Create the full-featured GunDB backend
+      this._backend = new GunDBBackend({
+        appName: this.config.appName,
+        peers: gundbConfig.peers || [],
+        radisk: gundbConfig.radisk !== false,
+        localStorage: gundbConfig.localStorage !== false,
+        dataDir: config.dataDir,
+        privateKey: this.config.privateKey,
+        strict: gundbConfig.strict || false,
+        schemaCacheMaxAge: gundbConfig.schemaCacheMaxAge || 3600000,
+      });
+
+      // Initialize the backend
+      await this._backend.init();
+
+      // Set public key from backend
+      this.publicKey = this._backend.publicKey;
+
+      // Store Gun instance for direct access
+      this._gun = this._backend.gun;
+
+      // Create a client-like interface for compatibility
+      this.client = {
+        publicKey: this.publicKey,
+        gun: this._gun,
+        write: (path, data) => this._backend.write(path, data),
+        read: (path, options) => this._backend.read(path, options),
+        readAll: (path, options) => this._backend.readAll(path, options),
+        update: (path, updates) => this._backend.update(path, updates),
+        delete: (path) => this._backend.delete(path),
+        subscribe: (path, callback, options) => this._backend.subscribe(path, callback, options),
+        buildPath: gunWrapper.buildPath,
+      };
+
+      // Store Gun wrapper functions for direct access
+      this._gunWrapper = gunWrapper;
+
+      // Log startup information
+      this._logStartup({
+        version: pkg.version,
+        appName: this.config.appName,
+        backend: 'gundb',
+        peers: gundbConfig.peers || [],
+        publicKey: this.publicKey,
+        logLevel: this.config.logLevel,
+        persistence: gundbConfig.radisk !== false,
+        dataDir: config.dataDir,
+      });
+    } catch (error) {
+      this._log('ERROR', 'GunDB client initialization failed', { error: error.message });
+      throw new Error(`GunDB client initialization failed: ${error.message}`);
+    }
+  }
+
   /**
    * Initialize non-Nostr backends asynchronously
    * @private
@@ -270,4 +384,371 @@ export class HoloSphere {
   metrics() {
     return { ...this._metrics };
   }
+
+  // ============================================================================
+  // GUNDB-SPECIFIC METHODS
+  // These methods are only available when using the 'gundb' backend
+  // ============================================================================
+
+  /**
+   * Check if using GunDB backend
+   * @private
+   */
+  _requireGunDB() {
+    if (this.config.backend !== 'gundb') {
+      throw new Error('This method requires the GunDB backend');
+    }
+    if (!this._backend) {
+      throw new Error('Backend not initialized. Call ready() first.');
+    }
+  }
+
+  // ============================================================================
+  // GLOBAL TABLE OPERATIONS
+  // ============================================================================
+
+  /**
+   * Write data to a global table
+   * @param {string} tableName - Global table name (e.g., 'federation', 'schemas')
+   * @param {Object} data - Data to write (must have 'id' field)
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async putGlobal(tableName, data) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.writeGlobal(tableName, data);
+  }
+
+  /**
+   * Read data from a global table
+   * @param {string} tableName - Global table name
+   * @param {string} key - Data key
+   * @returns {Promise<Object|null>} Data or null if not found
+   */
+  async getGlobal(tableName, key) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.readGlobal(tableName, key);
+  }
+
+  /**
+   * Read all data from a global table
+   * @param {string} tableName - Global table name
+   * @returns {Promise<Object[]>} Array of data objects
+   */
+  async getAllGlobal(tableName) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.readAllGlobal(tableName);
+  }
+
+  /**
+   * Delete data from a global table
+   * @param {string} tableName - Global table name
+   * @param {string} key - Data key
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async deleteGlobal(tableName, key) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.deleteGlobal(tableName, key);
+  }
+
+  // ============================================================================
+  // REFERENCE OPERATIONS
+  // ============================================================================
+
+  /**
+   * Create a reference to data
+   * @param {string} holon - Holon ID
+   * @param {string} lens - Lens name
+   * @param {Object} data - Data object (must have 'id' field)
+   * @returns {Object} Reference object with id and soul
+   */
+  createReference(holon, lens, data) {
+    this._requireGunDB();
+    return this._backend.createReference(holon, lens, data);
+  }
+
+  /**
+   * Check if data is a reference
+   * @param {Object} data - Data to check
+   * @returns {boolean} True if data is a reference
+   */
+  isReference(data) {
+    this._requireGunDB();
+    return this._backend.isReference(data);
+  }
+
+  /**
+   * Resolve a reference to get actual data
+   * @param {Object} reference - Reference object
+   * @param {Object} options - Resolution options
+   * @returns {Promise<Object|null>} Resolved data or null
+   */
+  async resolveReference(reference, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.resolveReference(reference, options);
+  }
+
+  // ============================================================================
+  // AUTHENTICATION OPERATIONS
+  // ============================================================================
+
+  /**
+   * Authenticate for a holon
+   * @param {string} holonId - Holon ID
+   * @param {string} password - Password
+   * @returns {Promise<Object>} Authenticated user object
+   */
+  async authenticate(holonId, password) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.authenticate(holonId, password);
+  }
+
+  /**
+   * Create a new user for a holon
+   * @param {string} holonId - Holon ID
+   * @param {string} password - Password
+   * @returns {Promise<Object>} Created user object
+   */
+  async createUser(holonId, password) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.createUser(holonId, password);
+  }
+
+  /**
+   * Logout current user
+   */
+  logout() {
+    this._requireGunDB();
+    this._backend.logout();
+  }
+
+  /**
+   * Check if authenticated
+   * @returns {boolean} True if authenticated
+   */
+  isAuthenticated() {
+    this._requireGunDB();
+    return this._backend.isAuthenticated();
+  }
+
+  /**
+   * Write to private storage (requires authentication)
+   * @param {string} lens - Lens name
+   * @param {string} key - Data key
+   * @param {Object} data - Data to write
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async writePrivate(lens, key, data) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.writePrivate(lens, key, data);
+  }
+
+  /**
+   * Read from private storage (requires authentication)
+   * @param {string} lens - Lens name
+   * @param {string} key - Data key
+   * @returns {Promise<Object|null>} Data or null
+   */
+  async readPrivate(lens, key) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.readPrivate(lens, key);
+  }
+
+  // ============================================================================
+  // SCHEMA OPERATIONS
+  // ============================================================================
+
+  /**
+   * Set a schema for a lens
+   * @param {string} lens - Lens name
+   * @param {Object} schema - JSON Schema definition
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async setSchema(lens, schema) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.setSchema(lens, schema);
+  }
+
+  /**
+   * Get a schema for a lens
+   * @param {string} lens - Lens name
+   * @returns {Promise<Object|null>} Schema or null
+   */
+  async getSchema(lens) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.getSchema(lens);
+  }
+
+  /**
+   * Validate data against a lens schema
+   * @param {string} lens - Lens name
+   * @param {Object} data - Data to validate
+   * @returns {Promise<Object>} Validation result { valid: boolean, errors: Array }
+   */
+  async validateData(lens, data) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.validateData(lens, data);
+  }
+
+  // ============================================================================
+  // FEDERATION OPERATIONS
+  // ============================================================================
+
+  /**
+   * Create a federation relationship between two spaces
+   * @param {string} spaceId1 - First space ID
+   * @param {string} spaceId2 - Second space ID
+   * @param {boolean} bidirectional - Whether to set up bidirectional notifications (default: true)
+   * @returns {Promise<boolean>} True if federation was created
+   */
+  async federate(spaceId1, spaceId2, bidirectional = true) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.federate(this._backend, spaceId1, spaceId2, bidirectional);
+  }
+
+  /**
+   * Remove a federation relationship
+   * @param {string} spaceId1 - First space ID
+   * @param {string} spaceId2 - Second space ID
+   * @returns {Promise<boolean>} True if federation was removed
+   */
+  async unfederate(spaceId1, spaceId2) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.unfederate(this._backend, spaceId1, spaceId2);
+  }
+
+  /**
+   * Get federation info for a space
+   * @param {string} spaceId - Space ID
+   * @returns {Promise<Object|null>} Federation info or null
+   */
+  async getFederation(spaceId) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.getFederation(this._backend, spaceId);
+  }
+
+  /**
+   * Reset all federation relationships for a space
+   * @param {string} spaceId - Space ID
+   * @param {Object} options - Reset options
+   * @returns {Promise<Object>} Result object
+   */
+  async resetFederation(spaceId, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.resetFederation(this._backend, spaceId, options);
+  }
+
+  /**
+   * Propagate data to federated spaces
+   * @param {string} holon - Holon identifier
+   * @param {string} lens - Lens identifier
+   * @param {Object} data - Data to propagate
+   * @param {Object} options - Propagation options
+   * @returns {Promise<Object>} Result with success count and errors
+   */
+  async propagate(holon, lens, data, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.propagate(this._backend, holon, lens, data, options);
+  }
+
+  /**
+   * Get combined data from local and federated sources
+   * @param {string} holon - Local holon name
+   * @param {string} lens - Lens to query
+   * @param {Object} options - Options for data retrieval and aggregation
+   * @returns {Promise<Array>} Combined array of local and federated data
+   */
+  async getFederated(holon, lens, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.getFederated(this._backend, holon, lens, options);
+  }
+
+  /**
+   * Subscribe to federation notifications for a space
+   * @param {string} spaceId - Space ID to subscribe to
+   * @param {Function} callback - Callback to execute on notifications
+   * @param {Object} options - Subscription options
+   * @returns {Promise<Object>} Subscription object with unsubscribe() method
+   */
+  async subscribeFederation(spaceId, callback, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.subscribeFederation(this._backend, spaceId, callback, options);
+  }
+
+  /**
+   * Track a federated message across different chats
+   * @param {string} originalChatId - Original chat ID
+   * @param {string} messageId - Original message ID
+   * @param {string} federatedChatId - Federated chat ID
+   * @param {string} federatedMessageId - Federated message ID
+   * @param {string} type - Message type
+   * @returns {Promise<void>}
+   */
+  async federateMessage(originalChatId, messageId, federatedChatId, federatedMessageId, type = 'generic') {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.federateMessage(this._backend, originalChatId, messageId, federatedChatId, federatedMessageId, type);
+  }
+
+  /**
+   * Get all federated messages for a given original message
+   * @param {string} originalChatId - Original chat ID
+   * @param {string} messageId - Original message ID
+   * @returns {Promise<Object|null>} Tracking information for the message
+   */
+  async getFederatedMessages(originalChatId, messageId) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.getFederatedMessages(this._backend, originalChatId, messageId);
+  }
+
+  /**
+   * Update a federated message across all federated chats
+   * @param {string} originalChatId - Original chat ID
+   * @param {string} messageId - Original message ID
+   * @param {Function} updateCallback - Function to update the message in each chat
+   * @returns {Promise<void>}
+   */
+  async updateFederatedMessages(originalChatId, messageId, updateCallback) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.updateFederatedMessages(this._backend, originalChatId, messageId, updateCallback);
+  }
+
+  // ============================================================================
+  // LIFECYCLE
+  // ============================================================================
+
+  /**
+   * Closes the backend and cleans up resources.
+   * Should be called when done using the HoloSphere instance.
+   *
+   * @returns {void}
+   */
+  close() {
+    if (this._backend) {
+      this._backend.close();
+    }
+    if (this.client && typeof this.client.close === 'function') {
+      this.client.close();
+    }
+  }
 }