holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/contracts/operations.js

@@ -1,9 +1,21 @@
 /**
- * ContractOperations - All contract functions exposed with clear parameters
- * Provides a unified interface for interacting with all Holosphere contract types
+ * @fileoverview Unified operations interface for all Holosphere contract types.
+ * Provides a clean API for member management, fund distribution, and contract-specific operations.
+ * @module contracts/operations
  */
 
+/**
+ * Provides a unified interface for interacting with all Holosphere contract types.
+ * Wraps contract functions with clear parameters and type checking.
+ * @class
+ */
 export class ContractOperations {
+  /**
+   * Create a new ContractOperations instance.
+   * @param {Object} contract - Ethers.js Contract instance
+   * @param {string} type - Contract type (Splitter, Managed, Zoned, Appreciative, Bundle)
+   * @param {ChainManager} chainManager - Chain manager instance
+   */
   constructor(contract, type, chainManager) {
     this.contract = contract;
     this.type = type;
@@ -12,8 +24,9 @@ export class ContractOperations {
   }
 
   /**
-   * Load ethers dynamically
+   * Load ethers.js library dynamically.
    * @private
+   * @returns {Promise<Object>} Ethers.js module
    */
   async _loadEthers() {
     if (!this.ethers) {
@@ -27,9 +40,9 @@ export class ContractOperations {
   // ========================================================================
 
   /**
-   * Add a single member to the contract
+   * Add a single member to the contract.
    * @param {string} userId - User identifier (string-based, e.g., 'alice', 'telegram_12345')
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async addMember(userId) {
     const tx = await this.contract.addMember(userId);
@@ -38,9 +51,9 @@ export class ContractOperations {
   }
 
   /**
-   * Add multiple members at once (batch operation)
+   * Add multiple members at once (batch operation).
    * @param {string[]} userIds - Array of user identifiers
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async addMembers(userIds) {
     const tx = await this.contract.addMembers(userIds);
@@ -49,8 +62,8 @@ export class ContractOperations {
   }
 
   /**
-   * Get all member user IDs
-   * @returns {Promise<string[]>}
+   * Get all member user IDs.
+   * @returns {Promise<string[]>} Array of user IDs
    */
   async getMembers() {
     const userIds = await this.contract.userIds();
@@ -75,9 +88,9 @@ export class ContractOperations {
   }
 
   /**
-   * Check if a user is a member
+   * Check if a user is a member.
    * @param {string} userId - User identifier
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} True if user is a member
    */
   async isMember(userId) {
     try {
@@ -92,7 +105,7 @@ export class ContractOperations {
   }
 
   /**
-   * Get the address associated with a user ID
+   * Get the Ethereum address associated with a user ID.
    * @param {string} userId - User identifier
    * @returns {Promise<string>} Ethereum address (or zero address if not set)
    */
@@ -105,10 +118,10 @@ export class ContractOperations {
   // ========================================================================
 
   /**
-   * Trigger reward distribution for ERC20 tokens
+   * Trigger reward distribution for ERC20 tokens.
    * @param {string} tokenAddress - ERC20 token contract address
    * @param {string|bigint} amount - Amount in wei (or token's smallest unit)
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async reward(tokenAddress, amount) {
     const ethers = await this._loadEthers();
@@ -119,9 +132,9 @@ export class ContractOperations {
   }
 
   /**
-   * Trigger reward distribution for ETH
+   * Trigger reward distribution for ETH.
    * @param {string} amount - Amount in ETH (e.g., '1.5' for 1.5 ETH)
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async rewardEth(amount) {
     const ethers = await this._loadEthers();
@@ -136,9 +149,9 @@ export class ContractOperations {
   }
 
   /**
-   * Send ETH directly to contract (triggers receive/fallback)
+   * Send ETH directly to contract (triggers receive/fallback).
    * @param {string} amount - Amount in ETH
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async sendEth(amount) {
     const ethers = await this._loadEthers();
@@ -153,10 +166,10 @@ export class ContractOperations {
   }
 
   /**
-   * Claim accumulated rewards for a user
+   * Claim accumulated rewards for a user.
    * @param {string} userId - User identifier
    * @param {string} beneficiaryAddress - Ethereum address to receive funds
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async claim(userId, beneficiaryAddress) {
     const tx = await this.contract.claim(userId, beneficiaryAddress);
@@ -165,9 +178,9 @@ export class ContractOperations {
   }
 
   /**
-   * Get ETH balance for a user
+   * Get ETH balance for a user.
    * @param {string} userId - User identifier
-   * @returns {Promise<string>} Balance in ETH
+   * @returns {Promise<string>} Balance in ETH as decimal string
    */
   async getEthBalance(userId) {
     const ethers = await this._loadEthers();
@@ -176,10 +189,10 @@ export class ContractOperations {
   }
 
   /**
-   * Get ERC20 token balance for a user
+   * Get ERC20 token balance for a user.
    * @param {string} userId - User identifier
    * @param {string} tokenAddress - ERC20 token address
-   * @returns {Promise<string>} Balance in tokens (18 decimals assumed)
+   * @returns {Promise<string>} Balance in tokens (18 decimals assumed) as decimal string
    */
   async getTokenBalance(userId, tokenAddress) {
     const ethers = await this._loadEthers();
@@ -188,18 +201,18 @@ export class ContractOperations {
   }
 
   /**
-   * Check if user has already claimed
+   * Check if user has already claimed rewards.
    * @param {string} userId - User identifier
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} True if user has claimed
    */
   async hasClaimed(userId) {
     return this.contract.hasClaimed(userId);
   }
 
   /**
-   * Get total deposited amount for a token
+   * Get total deposited amount for a token.
    * @param {string} tokenAddress - Token address (use zero address for ETH)
-   * @returns {Promise<string>}
+   * @returns {Promise<string>} Total deposited as decimal string
    */
   async getTotalDeposited(tokenAddress) {
     const ethers = await this._loadEthers();
@@ -212,10 +225,11 @@ export class ContractOperations {
   // ========================================================================
 
   /**
-   * Set the internal/external split percentages (Splitter only)
+   * Set the internal/external split percentages (Splitter only).
    * @param {number} internalPct - Internal percentage (0-100)
    * @param {number} externalPct - External percentage (0-100, must sum to 100 with internal)
-   * @returns {Promise<{txHash, receipt}>}
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
+   * @throws {Error} If percentages don't sum to 100 or not a Splitter contract
    */
   async setContractSplit(internalPct, externalPct) {
     this._requireType(['Splitter']);
@@ -228,8 +242,9 @@ export class ContractOperations {
   }
 
   /**
-   * Get current split percentages (Splitter only)
-   * @returns {Promise<{internal: number, external: number}>}
+   * Get current split percentages (Splitter only).
+   * @returns {Promise<{internal: number, external: number}>} Split percentages
+   * @throws {Error} If not a Splitter contract
    */
   async getContractSplit() {
     this._requireType(['Splitter']);
@@ -627,8 +642,10 @@ export class ContractOperations {
   // ========================================================================
 
   /**
-   * Require specific contract type(s)
+   * Require specific contract type(s).
    * @private
+   * @param {string[]} allowedTypes - Array of allowed contract types
+   * @throws {Error} If contract type doesn't match
    */
   _requireType(allowedTypes) {
     if (!allowedTypes.includes(this.type)) {
@@ -637,28 +654,28 @@ export class ContractOperations {
   }
 
   /**
-   * Get raw contract instance for advanced usage
-   * @returns {Contract}
+   * Get raw contract instance for advanced usage.
+   * @returns {Object} Ethers.js Contract instance
    */
   getRawContract() {
     return this.contract;
   }
 
   /**
-   * Execute a raw contract call
+   * Execute a raw contract call.
    * @param {string} method - Method name
-   * @param {Array} args - Method arguments
-   * @returns {Promise<any>}
+   * @param {...*} args - Method arguments
+   * @returns {Promise<*>} Method return value
    */
   async call(method, ...args) {
     return this.contract[method](...args);
   }
 
   /**
-   * Execute a raw contract transaction
+   * Execute a raw contract transaction.
    * @param {string} method - Method name
-   * @param {Array} args - Method arguments
-   * @returns {Promise<{txHash, receipt}>}
+   * @param {...*} args - Method arguments
+   * @returns {Promise<{txHash: string, receipt: Object}>} Transaction details
    */
   async send(method, ...args) {
     const tx = await this.contract[method](...args);

package/src/contracts/queries.js

@@ -1,8 +1,7 @@
 /**
- * Contract Query Utilities
- *
- * Utility kit for directly querying contract state:
- * zones, splits, appreciation, members, balances, etc.
+ * @fileoverview Contract query utilities for reading contract state.
+ * Provides read-only queries for zones, splits, appreciation, members, balances, and more.
+ * @module contracts/queries
  */
 
 import { ethers } from 'ethers';
@@ -24,35 +23,45 @@ const ContractABIs = {
 };
 
 /**
- * Helper to format wei to ETH
+ * Helper to format wei to ETH.
+ * @private
+ * @param {bigint} wei - Wei amount
+ * @returns {string} ETH as decimal string
  */
 function formatEth(wei) {
   return ethers.formatEther(wei);
 }
 
 /**
- * Helper to format wei to ETH as number
+ * Helper to format wei to ETH as number.
+ * @private
+ * @param {bigint} wei - Wei amount
+ * @returns {number} ETH as number
  */
 function formatEthNumber(wei) {
   return Number(ethers.formatEther(wei));
 }
 
 /**
- * ContractQueries - Query utilities for all contract types
+ * Query utilities for all Holosphere contract types.
+ * Provides read-only access to contract state without requiring a signer.
+ * @class
  */
 export class ContractQueries {
   /**
-   * @param {ethers.Provider} provider - ethers.js provider
+   * Create a new ContractQueries instance.
+   * @param {Object} provider - Ethers.js provider instance
    */
   constructor(provider) {
     this.provider = provider;
   }
 
   /**
-   * Get a contract instance with the appropriate ABI
+   * Get a contract instance with the appropriate ABI.
    * @param {string} address - Contract address
-   * @param {string} flavor - Contract flavor (Splitter, Managed, Zoned, Appreciative, Bundle)
-   * @returns {ethers.Contract}
+   * @param {string} flavor - Contract flavor (Splitter, Managed, Zoned, Appreciative, Bundle, Holons)
+   * @returns {Object} Ethers.js Contract instance
+   * @throws {Error} If unknown contract flavor
    */
   getContract(address, flavor) {
     const abi = ContractABIs[flavor];
@@ -63,9 +72,9 @@ export class ContractQueries {
   }
 
   /**
-   * Auto-detect contract flavor by calling flavor()
+   * Auto-detect contract flavor by calling flavor() method.
    * @param {string} address - Contract address
-   * @returns {Promise<string>} Contract flavor
+   * @returns {Promise<string>} Contract flavor or 'Unknown'
    */
   async detectFlavor(address) {
     // Try with a minimal ABI that has flavor()
@@ -84,7 +93,10 @@ export class ContractQueries {
   // ==================== COMMON QUERIES ====================
 
   /**
-   * Get basic contract info
+   * Get basic contract information.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @returns {Promise<{address: string, name: string, flavor: string, version: string, creator: string, memberCount: number}>} Contract info
    */
   async getContractInfo(address, flavor) {
     const contract = this.getContract(address, flavor);
@@ -107,7 +119,10 @@ export class ContractQueries {
   }
 
   /**
-   * Get all members (userIds)
+   * Get all member user IDs.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @returns {Promise<string[]>} Array of user IDs
    */
   async getMembers(address, flavor) {
     const contract = this.getContract(address, flavor);
@@ -121,7 +136,11 @@ export class ContractQueries {
   }
 
   /**
-   * Get user's ETH balance
+   * Get user's ETH balance in the contract.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} userId - User identifier
+   * @returns {Promise<{wei: string, eth: number}>} Balance in wei and ETH
    */
   async getUserEthBalance(address, flavor, userId) {
     const contract = this.getContract(address, flavor);
@@ -133,7 +152,12 @@ export class ContractQueries {
   }
 
   /**
-   * Get user's token balance
+   * Get user's ERC20 token balance in the contract.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} userId - User identifier
+   * @param {string} tokenAddress - ERC20 token address
+   * @returns {Promise<{wei: string, formatted: number}>} Token balance
    */
   async getUserTokenBalance(address, flavor, userId, tokenAddress) {
     const contract = this.getContract(address, flavor);
@@ -145,7 +169,11 @@ export class ContractQueries {
   }
 
   /**
-   * Get total deposited for a token
+   * Get total deposited amount for a token.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} [tokenAddress] - Token address (defaults to ETH/zero address)
+   * @returns {Promise<{wei: string, formatted: number}>} Total deposited
    */
   async getTotalDeposited(address, flavor, tokenAddress) {
     const contract = this.getContract(address, flavor);
@@ -159,7 +187,11 @@ export class ContractQueries {
   }
 
   /**
-   * Check if user has claimed
+   * Check if user has claimed their rewards.
+   * @param {string} address - Contract address
+   * @param {string} flavor - Contract flavor
+   * @param {string} userId - User identifier
+   * @returns {Promise<boolean>} True if claimed
    */
   async hasClaimed(address, flavor, userId) {
     const contract = this.getContract(address, flavor);
@@ -539,7 +571,9 @@ export class ContractQueries {
   // ==================== FULL SNAPSHOT ====================
 
   /**
-   * Get complete contract state snapshot
+   * Get complete contract state snapshot including all members and configuration.
+   * @param {string} address - Contract address
+   * @returns {Promise<Object>} Complete contract state
    */
   async getFullSnapshot(address) {
     const flavor = await this.detectFlavor(address);

package/src/core/holosphere.js

@@ -1,3 +1,14 @@
+/**
+ * @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';
@@ -5,12 +16,16 @@ import * as gunFederation from '../storage/gun-federation.js';
 import { GunDBBackend } from '../storage/backends/gundb-backend.js';
 import pkg from '../../package.json' with { type: 'json' };
 
-// Gun will be loaded dynamically when needed
+/** @type {Function|null} Gun constructor, loaded dynamically */
 let Gun = null;
+/** @type {Promise<Function>|null} Promise for Gun loading */
 let gunLoadPromise = null;
 
 /**
- * Load Gun module dynamically
+ * 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() {
@@ -50,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 {
   /**
@@ -712,7 +738,10 @@ export class HoloSphere {
   // ============================================================================
 
   /**
-   * Close the backend and clean up resources
+   * Closes the backend and cleans up resources.
+   * Should be called when done using the HoloSphere instance.
+   *
+   * @returns {void}
    */
   close() {
     if (this._backend) {