holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/storage/backend-interface.js

@@ -1,8 +1,27 @@
 /**
- * Abstract Storage Backend Interface
- * All storage backends must implement this interface
+ * @fileoverview Abstract Storage Backend Interface.
+ *
+ * Defines the contract that all storage backends must implement.
+ * Provides a consistent API for CRUD operations, subscriptions,
+ * and data migration across different storage technologies.
+ *
+ * @module storage/backend-interface
+ */
+
+/**
+ * Abstract base class for storage backends.
+ * All concrete backends (Nostr, GunDB, ActivityPub) must extend this class.
+ *
+ * @abstract
+ * @class StorageBackend
  */
 export class StorageBackend {
+  /**
+   * Creates a new StorageBackend instance.
+   *
+   * @param {Object} config - Backend-specific configuration
+   * @throws {Error} If instantiated directly (abstract class)
+   */
   constructor(config) {
     if (new.target === StorageBackend) {
       throw new Error('StorageBackend is abstract and cannot be instantiated directly');

package/src/storage/backends/activitypub/server.js

@@ -1,19 +1,41 @@
 /**
- * Self-hosted ActivityPub server for HoloSphere
- * Provides federation with Mastodon, Pleroma, and other ActivityPub servers
+ * @fileoverview Self-hosted ActivityPub server for HoloSphere federation.
+ * Provides complete ActivityPub protocol support for federation with Mastodon, Pleroma,
+ * and other fediverse servers. Includes WebFinger, NodeInfo, actor endpoints, and SSE subscriptions.
+ * @module storage/backends/activitypub/server
  */
 
 import express from 'express';
 import crypto from 'crypto';
 import { createPersistentStorage } from '../../persistent-storage.js';
 
+/** @constant {string} ActivityStreams JSON-LD context */
 const ACTIVITY_STREAMS_CONTEXT = 'https://www.w3.org/ns/activitystreams';
+/** @constant {string} Security vocabulary JSON-LD context */
 const SECURITY_CONTEXT = 'https://w3id.org/security/v1';
 
 /**
- * ActivityPub Server for HoloSphere
+ * Self-hosted ActivityPub server for HoloSphere data federation.
+ * Implements WebFinger discovery, actor endpoints, inbox/outbox, and HoloSphere data API.
+ *
+ * @class ActivityPubServer
+ * @example
+ * const server = new ActivityPubServer({
+ *   port: 3000,
+ *   domain: 'holon.example.com',
+ *   dataDir: './data'
+ * });
+ * await server.start();
  */
 export class ActivityPubServer {
+  /**
+   * Create a new ActivityPub server instance.
+   * @param {Object} [config={}] - Server configuration
+   * @param {number} [config.port=3000] - HTTP port to listen on
+   * @param {string} [config.domain='localhost'] - Server domain for URLs
+   * @param {string} [config.protocol='http'] - Protocol (http or https)
+   * @param {string} [config.dataDir] - Data directory for persistent storage
+   */
   constructor(config = {}) {
     this.config = {
       port: config.port || 3000,

package/src/storage/backends/activitypub-backend.js

@@ -1,11 +1,34 @@
 /**
- * ActivityPub Storage Backend
- * Client adapter for connecting to an ActivityPub server
+ * @fileoverview ActivityPub storage backend client adapter.
+ * Provides HTTP-based connectivity to an ActivityPub server for federated data storage
+ * and real-time subscriptions via Server-Sent Events.
+ * @module storage/backends/activitypub-backend
  */
 
 import { StorageBackend } from '../backend-interface.js';
 
+/**
+ * ActivityPub storage backend implementation.
+ * Client adapter for connecting to an ActivityPub server via HTTP API
+ * with SSE-based real-time subscriptions.
+ *
+ * @class ActivityPubBackend
+ * @extends StorageBackend
+ * @example
+ * const backend = await BackendFactory.create('activitypub', {
+ *   serverUrl: 'https://ap.example.com',
+ *   appName: 'myapp',
+ *   apiKey: 'secret-key'
+ * });
+ */
 export class ActivityPubBackend extends StorageBackend {
+  /**
+   * Create a new ActivityPub backend instance.
+   * @param {Object} config - Backend configuration
+   * @param {string} config.serverUrl - ActivityPub server URL
+   * @param {string} [config.appName='holosphere'] - Application/actor name
+   * @param {string} [config.apiKey] - Optional API key for authentication
+   */
   constructor(config) {
     super(config);
     this.serverUrl = config.serverUrl;

package/src/storage/backends/gundb-backend.js

@@ -1,6 +1,7 @@
 /**
- * GunDB Storage Backend
- * Full-featured backend with authentication, schema validation, references, and global tables
+ * @fileoverview GunDB storage backend with authentication, schema validation, references, and global tables.
+ * Provides full-featured P2P data storage using GunDB with write caching for immediate consistency.
+ * @module storage/backends/gundb-backend
  */
 
 import { StorageBackend } from '../backend-interface.js';
@@ -10,7 +11,33 @@ import { GunReferenceHandler } from '../gun-references.js';
 import { GunAuth } from '../gun-auth.js';
 import { GunSchemaValidator } from '../gun-schema.js';
 
+/**
+ * GunDB storage backend implementation with advanced features.
+ * Supports authentication, schema validation, references, global tables,
+ * and write caching for immediate consistency.
+ *
+ * @class GunDBBackend
+ * @extends StorageBackend
+ * @example
+ * const backend = await BackendFactory.create('gundb', {
+ *   appName: 'myapp',
+ *   peers: ['wss://gun-server.example.com/gun'],
+ *   radisk: true
+ * });
+ */
 export class GunDBBackend extends StorageBackend {
+  /**
+   * Create a new GunDB backend instance.
+   * @param {Object} config - Backend configuration
+   * @param {string} [config.appName='holosphere'] - Application namespace
+   * @param {string[]} [config.peers=[]] - Array of peer URLs
+   * @param {boolean} [config.radisk=true] - Enable radisk persistence
+   * @param {boolean} [config.localStorage=true] - Enable localStorage
+   * @param {string} [config.dataDir='radata'] - Data directory for Node.js
+   * @param {string} [config.privateKey] - Optional existing private key
+   * @param {string} [config.publicKey] - Optional existing public key
+   * @param {boolean} [config.strict=false] - Enable strict schema validation
+   */
   constructor(config) {
     super(config);
     this.gun = null;

package/src/storage/backends/nostr-backend.js

@@ -1,18 +1,52 @@
 /**
- * Nostr Storage Backend
+ * @fileoverview Nostr Storage Backend.
+ *
  * Wraps existing nostr-wrapper.js and nostr-client.js as a StorageBackend
+ * implementation. Provides Nostr-based distributed storage with relay support.
+ *
+ * @module storage/backends/nostr-backend
  */
 
 import { StorageBackend } from '../backend-interface.js';
 import { createClient } from '../nostr-client.js';
 import * as wrapper from '../nostr-wrapper.js';
 
+/**
+ * Nostr storage backend implementation.
+ *
+ * Provides distributed storage using Nostr relays with event-based data storage.
+ *
+ * @class NostrBackend
+ * @extends StorageBackend
+ * @example
+ * const backend = new NostrBackend({
+ *   relays: ['wss://relay.example.com'],
+ *   appName: 'myapp',
+ *   persistence: true
+ * });
+ * await backend.init();
+ */
 export class NostrBackend extends StorageBackend {
+  /**
+   * Create a new NostrBackend.
+   *
+   * @param {Object} config - Backend configuration
+   * @param {string[]} [config.relays] - Relay URLs
+   * @param {string} [config.privateKey] - Private key for signing
+   * @param {string} [config.appName] - Application name
+   * @param {boolean} [config.persistence=true] - Enable persistent storage
+   * @param {boolean} [config.backgroundSync] - Enable background sync
+   */
   constructor(config) {
     super(config);
     this.client = null;
   }
 
+  /**
+   * Initialize the backend.
+   *
+   * @returns {Promise<void>}
+   */
   async init() {
     this.client = createClient({
       relays: this.config.relays || ['wss://relay.holons.io'],
@@ -32,38 +66,102 @@ export class NostrBackend extends StorageBackend {
     this.publicKey = this.client.publicKey;
   }
 
+  /**
+   * Build path from components.
+   *
+   * @param {string} appName - Application name
+   * @param {string} holonId - Holon ID
+   * @param {string} lensName - Lens name
+   * @param {string} [key=null] - Optional key
+   * @returns {string} Built path
+   */
   buildPath(appName, holonId, lensName, key = null) {
     return wrapper.buildPath(appName, holonId, lensName, key);
   }
 
+  /**
+   * Write data to path.
+   *
+   * @param {string} path - Storage path
+   * @param {Object} data - Data to write
+   * @param {Object} [options={}] - Write options
+   * @returns {Promise<Object>} Write result
+   */
   async write(path, data, options = {}) {
     return wrapper.write(this.client, path, data);
   }
 
+  /**
+   * Read data from path.
+   *
+   * @param {string} path - Storage path
+   * @param {Object} [options={}] - Read options
+   * @returns {Promise<Object|null>} Data or null
+   */
   async read(path, options = {}) {
     return wrapper.read(this.client, path, options);
   }
 
+  /**
+   * Read all data under path.
+   *
+   * @param {string} path - Storage path prefix
+   * @param {Object} [options={}] - Read options
+   * @returns {Promise<Object[]>} Array of data objects
+   */
   async readAll(path, options = {}) {
     return wrapper.readAll(this.client, path, options);
   }
 
+  /**
+   * Update data at path.
+   *
+   * @param {string} path - Storage path
+   * @param {Object} updates - Fields to update
+   * @returns {Promise<Object>} Update result
+   */
   async update(path, updates) {
     return wrapper.update(this.client, path, updates);
   }
 
+  /**
+   * Delete data at path.
+   *
+   * @param {string} path - Storage path
+   * @returns {Promise<boolean>} Success indicator
+   */
   async delete(path) {
     return wrapper.deleteData(this.client, path);
   }
 
+  /**
+   * Delete all data under path.
+   *
+   * @param {string} path - Storage path prefix
+   * @returns {Promise<Object>} Deletion results
+   */
   async deleteAll(path) {
     return wrapper.deleteAll(this.client, path);
   }
 
+  /**
+   * Subscribe to changes at path.
+   *
+   * @param {string} path - Storage path
+   * @param {Function} callback - Callback function
+   * @param {Object} [options={}] - Subscribe options
+   * @returns {Promise<Object>} Subscription object with unsubscribe method
+   */
   async subscribe(path, callback, options = {}) {
     return wrapper.subscribe(this.client, path, callback, options);
   }
 
+  /**
+   * Export all data for this user.
+   *
+   * @param {string} [pathPrefix=''] - Optional path prefix filter
+   * @returns {Promise<Object[]>} Array of exported records
+   */
   async exportData(pathPrefix = '') {
     // Wait for client to be ready
     await this.client._initReady;
@@ -101,6 +199,13 @@ export class NostrBackend extends StorageBackend {
       .filter(record => !record.data._deleted); // Filter out deleted items
   }
 
+  /**
+   * Import data records.
+   *
+   * @param {Object[]} records - Array of records to import
+   * @param {Object} [options={}] - Import options
+   * @returns {Promise<Object>} Import results with success/failed counts
+   */
   async importData(records, options = {}) {
     const results = { success: 0, failed: 0, errors: [] };
 
@@ -117,12 +222,22 @@ export class NostrBackend extends StorageBackend {
     return results;
   }
 
+  /**
+   * Close the backend and cleanup resources.
+   *
+   * @returns {void}
+   */
   close() {
     if (this.client) {
       this.client.close();
     }
   }
 
+  /**
+   * Get backend status.
+   *
+   * @returns {Object} Status object with type, publicKey, relays, connected
+   */
   getStatus() {
     return {
       type: 'nostr',

package/src/storage/filesystem-storage-browser.js

@@ -1,40 +1,80 @@
 /**
- * Browser stub for FileSystemStorage
- * Throws an error if used in browser environment
+ * @fileoverview Browser stub for FileSystemStorage.
+ *
+ * This stub throws errors if FileSystemStorage is used in browser environments.
+ * Browsers should use IndexedDBStorage or MemoryStorage instead.
+ *
+ * @module storage/filesystem-storage-browser
  */
 
 import { PersistentStorage } from './persistent-storage.js';
 
+/**
+ * Browser stub for FileSystemStorage.
+ *
+ * All methods throw errors indicating filesystem storage is unavailable in browsers.
+ *
+ * @class FileSystemStorage
+ * @extends PersistentStorage
+ * @throws {Error} Always throws - not available in browser environments
+ */
 export class FileSystemStorage extends PersistentStorage {
+  /**
+   * Constructor throws error in browser.
+   *
+   * @param {string} [baseDir=null] - Ignored in browser
+   * @throws {Error} Always throws - not available in browser
+   */
   constructor(baseDir = null) {
     super();
     throw new Error('FileSystemStorage is not available in browser environments. Use IndexedDBStorage or MemoryStorage instead.');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async init(namespace) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async put(key, event) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async get(key) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async getAll(prefix) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async delete(key) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async clear() {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async close() {
     throw new Error('FileSystemStorage is not available in browser environments');
   }

package/src/storage/filesystem-storage.js

@@ -1,7 +1,10 @@
 /**
- * File system storage adapter for Node.js
- * Stores events as JSON files in a directory structure
- * This module is only loaded in Node.js environments
+ * @fileoverview File system storage adapter for Node.js.
+ *
+ * Stores events as JSON files in a directory structure.
+ * This module is only loaded in Node.js environments.
+ *
+ * @module storage/filesystem-storage
  */
 
 // Guard against browser environments
@@ -14,7 +17,24 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 
+/**
+ * File system storage adapter for Node.js.
+ *
+ * Stores events as JSON files in a directory structure for persistent storage.
+ *
+ * @class FileSystemStorage
+ * @extends PersistentStorage
+ * @example
+ * const storage = new FileSystemStorage('/custom/path');
+ * await storage.init('myapp');
+ * await storage.put('key1', { id: 'event1', data: 'test' });
+ */
 export class FileSystemStorage extends PersistentStorage {
+  /**
+   * Create a new FileSystemStorage instance.
+   *
+   * @param {string} [baseDir=null] - Base directory for storage (defaults to ~/.holosphere)
+   */
   constructor(baseDir = null) {
     super();
     this.baseDir = baseDir || path.join(os.homedir(), '.holosphere');
@@ -22,6 +42,12 @@ export class FileSystemStorage extends PersistentStorage {
     this.storageDir = null;
   }
 
+  /**
+   * Initialize storage with namespace.
+   *
+   * @param {string} namespace - Storage namespace (app name)
+   * @returns {Promise<void>}
+   */
   async init(namespace) {
     this.namespace = namespace;
     this.storageDir = path.join(this.baseDir, namespace);
@@ -37,8 +63,11 @@ export class FileSystemStorage extends PersistentStorage {
   }
 
   /**
-   * Convert key to safe filename
+   * Convert key to safe filename.
+   *
    * @private
+   * @param {string} key - Storage key
+   * @returns {string} Safe filename
    */
   _keyToFilename(key) {
     // Replace unsafe characters
@@ -46,19 +75,35 @@ export class FileSystemStorage extends PersistentStorage {
   }
 
   /**
-   * Get full file path for key
+   * Get full file path for key.
+   *
    * @private
+   * @param {string} key - Storage key
+   * @returns {string} Full file path
    */
   _getFilePath(key) {
     return path.join(this.storageDir, this._keyToFilename(key));
   }
 
+  /**
+   * Store an event.
+   *
+   * @param {string} key - Storage key
+   * @param {Object} event - Event data to store
+   * @returns {Promise<void>}
+   */
   async put(key, event) {
     const filePath = this._getFilePath(key);
     const data = JSON.stringify(event, null, 2);
     await fs.writeFile(filePath, data, 'utf8');
   }
 
+  /**
+   * Retrieve an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<Object|null>} Event data or null if not found
+   */
   async get(key) {
     const filePath = this._getFilePath(key);
     try {
@@ -72,6 +117,12 @@ export class FileSystemStorage extends PersistentStorage {
     }
   }
 
+  /**
+   * Retrieve all events matching a prefix.
+   *
+   * @param {string} prefix - Key prefix to match
+   * @returns {Promise<Object[]>} Array of matching events
+   */
   async getAll(prefix) {
     const results = [];
 
@@ -108,6 +159,12 @@ export class FileSystemStorage extends PersistentStorage {
     return results;
   }
 
+  /**
+   * Delete an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<void>}
+   */
   async delete(key) {
     const filePath = this._getFilePath(key);
     try {
@@ -119,6 +176,11 @@ export class FileSystemStorage extends PersistentStorage {
     }
   }
 
+  /**
+   * Clear all stored events.
+   *
+   * @returns {Promise<void>}
+   */
   async clear() {
     try {
       const files = await fs.readdir(this.storageDir);
@@ -132,6 +194,11 @@ export class FileSystemStorage extends PersistentStorage {
     }
   }
 
+  /**
+   * Close storage (no-op for filesystem).
+   *
+   * @returns {Promise<void>}
+   */
   async close() {
     // Nothing to close for file system storage
   }

package/src/storage/global-tables.js

@@ -1,6 +1,11 @@
 /**
- * Global Data Operations
- * Non-location-specific storage (FR-044, FR-045)
+ * @fileoverview Global Data Operations.
+ *
+ * Provides non-location-specific (non-holon) data storage operations.
+ * Used for storing application-wide data like federation configs, schemas,
+ * and user preferences that aren't tied to specific H3 cells.
+ *
+ * @module storage/global-tables
  */
 
 import { write, read, readAll, update, deleteData, deleteAll, subscribe } from './unified-storage.js';

package/src/storage/gun-async.js

@@ -1,13 +1,18 @@
 /**
- * Gun Async Utilities
- * Provides Promise-based wrappers and async patterns for Gun operations
+ * @fileoverview Gun Async Utilities.
+ *
+ * Provides Promise-based wrappers and async patterns for Gun operations.
+ * Includes utilities for promises, batch operations, retries, streams, and async iteration.
+ *
+ * @module storage/gun-async
  */
 
 /**
- * Get data from Gun using native .then() support
+ * Get data from Gun using native .then() support.
+ *
  * @param {Object} gunChain - Gun chain reference
- * @param {number} timeout - Timeout in ms (default 1000ms)
- * @returns {Promise<any>} Promise resolving to data
+ * @param {number} [timeout=1000] - Timeout in ms
+ * @returns {Promise<any>} Promise resolving to data or null on timeout
  */
 export function gunPromise(gunChain, timeout = 1000) {
   return new Promise((resolve, reject) => {
@@ -31,11 +36,13 @@ export function gunPromise(gunChain, timeout = 1000) {
 }
 
 /**
- * Wait for Gun write acknowledgement
+ * Wait for Gun write acknowledgement.
+ *
  * @param {Object} gunChain - Gun chain reference
  * @param {any} data - Data to write
- * @param {number} timeout - Timeout in ms (default 1000ms)
- * @returns {Promise<Object>} Promise resolving to ack object
+ * @param {number} [timeout=1000] - Timeout in ms
+ * @returns {Promise<Object>} Promise resolving to ack object { ok, timeout? }
+ * @throws {Error} If write fails with error
  */
 export function gunPut(gunChain, data, timeout = 1000) {
   return new Promise((resolve, reject) => {
@@ -63,10 +70,12 @@ export function gunPut(gunChain, data, timeout = 1000) {
 }
 
 /**
- * Get all items from a Gun map
- * First gets count of items, then collects until count is reached
+ * Get all items from a Gun map.
+ *
+ * First gets count of items, then collects until count is reached.
+ *
  * @param {Object} gunChain - Gun chain reference
- * @param {number} timeout - Timeout in ms (fallback, default 5000ms)
+ * @param {number} [timeout=5000] - Timeout in ms (fallback)
  * @returns {Promise<Object>} Promise resolving to map of items
  */
 export async function gunMap(gunChain, timeout = 5000) {

package/src/storage/gun-auth.js

@@ -1,19 +1,30 @@
 /**
- * GunDB Authentication Handler
- * Handles user authentication and private data storage using Gun's user system
+ * @fileoverview GunDB Authentication Handler.
  *
+ * Handles user authentication and private data storage using Gun's user system.
  * Private data is stored under: user.get('private').get(lens).get(key)
  * Usernames are namespaced: ${appname}:${holonId}
+ *
+ * @module storage/gun-auth
  */
 
 import { gunPromise, gunPut } from './gun-async.js';
 
 /**
- * Authentication handler for GunDB backend
+ * Authentication handler for GunDB backend.
+ *
+ * Manages user creation, authentication, and private data access.
+ *
+ * @class GunAuth
+ * @example
+ * const auth = new GunAuth(gun, 'myapp');
+ * await auth.createUser('holon123', 'password');
+ * await auth.authenticate('holon123', 'password');
  */
 export class GunAuth {
   /**
-   * Create a new authentication handler
+   * Create a new authentication handler.
+   *
    * @param {Object} gun - Gun instance
    * @param {string} appname - Application namespace
    */