holosphere 2.0.0-alpha7 → 2.0.0-alpha9

package/src/ai/schema-extractor.js

@@ -1,9 +1,18 @@
 /**
- * Schema Extractor - Extract structured data from text using JSON schemas
+ * @fileoverview Extract structured data from unstructured text using JSON schemas.
+ * Provides schema-based data extraction, validation, and field completion.
+ * @module ai/schema-extractor
  */
 
 /**
- * Schema Extractor class
+ * Service class for extracting structured data from text using JSON schemas.
+ * Leverages LLM to parse unstructured content and map it to defined schemas.
+ *
+ * @class SchemaExtractor
+ * @example
+ * const extractor = new SchemaExtractor(llmService);
+ * const schema = { properties: { name: { type: "string" }, age: { type: "number" } } };
+ * const data = await extractor.extractToSchema(text, schema);
  */
 export class SchemaExtractor {
   /**
@@ -14,10 +23,13 @@ export class SchemaExtractor {
   }
 
   /**
-   * Extract data from text based on JSON schema
-   * @param {string} text - Text to extract from
-   * @param {Object} schema - JSON schema defining expected structure
-   * @param {Object} options - Extraction options
+   * Extract structured data from text according to a JSON schema.
+   * Uses LLM to intelligently parse unstructured text and map to schema fields.
+   *
+   * @param {string} text - Unstructured text to extract from
+   * @param {Object} schema - JSON schema defining target structure
+   * @param {Object} [options={}] - Extraction options
+   * @param {number} [options.maxTokens=2000] - Maximum tokens for response
    * @returns {Promise<Object>} Extracted data conforming to schema
    */
   async extractToSchema(text, schema, options = {}) {
@@ -157,10 +169,12 @@ Return JSON with ONLY the missing fields that you can extract. Do not modify exi
   }
 
   /**
-   * Validate extracted data against schema
-   * @param {Object} data - Extracted data
-   * @param {Object} schema - JSON schema
-   * @returns {{valid: boolean, errors: string[]}}
+   * Validate extracted data against a JSON schema.
+   * Performs basic type checking and required field validation.
+   *
+   * @param {Object} data - Extracted data to validate
+   * @param {Object} schema - JSON schema to validate against
+   * @returns {{valid: boolean, errors: string[]}} Validation result with error list
    */
   validateExtraction(data, schema) {
     const errors = [];

package/src/ai/spatial.js

@@ -1,9 +1,20 @@
 /**
- * Spatial Analysis - AI-powered analysis of data patterns across geographic regions
+ * @fileoverview AI-powered spatial analysis of data patterns across geographic regions.
+ * Provides region analysis, comparison, trend detection, hotspot identification, and reporting.
+ * @module ai/spatial
  */
 
 /**
- * Spatial Analysis class
+ * Service class for analyzing spatial data patterns across geographic regions.
+ * Identifies trends, compares regions, finds hotspots, and generates comprehensive
+ * spatial reports using AI-driven analysis.
+ *
+ * @class SpatialAnalysis
+ * @example
+ * const spatial = new SpatialAnalysis(llmService, holosphere);
+ * const analysis = await spatial.analyzeRegion(holonId, 'projects', 'activity');
+ * const comparison = await spatial.compareRegions(holon1, holon2, 'quests');
+ * const trends = await spatial.spatialTrends(holonId, 'events', { start: '2024-01-01' });
  */
 export class SpatialAnalysis {
   /**

package/src/ai/tts.js

@@ -1,9 +1,12 @@
 /**
- * Text-to-Speech - OpenAI TTS integration
+ * @fileoverview OpenAI text-to-speech integration for audio generation.
+ * Provides methods for converting text to speech with various voices and formats.
+ * @module ai/tts
  */
 
 /**
- * Available voices for TTS
+ * Available voice options for text-to-speech.
+ * @enum {string}
  */
 export const VOICES = {
   ALLOY: 'alloy',
@@ -15,7 +18,8 @@ export const VOICES = {
 };
 
 /**
- * Available TTS models
+ * Available TTS model options.
+ * @enum {string}
  */
 export const MODELS = {
   TTS_1: 'tts-1',
@@ -23,7 +27,14 @@ export const MODELS = {
 };
 
 /**
- * TTS class for text-to-speech conversion
+ * Service class for converting text to speech using OpenAI's TTS API.
+ * Supports multiple voices, output formats, and handles long text with automatic chunking.
+ *
+ * @class TTS
+ * @example
+ * const tts = new TTS(openaiClient);
+ * const audioBuffer = await tts.speak("Hello world", { voice: VOICES.NOVA });
+ * const dataUrl = await tts.speakDataUrl("Hello", { voice: VOICES.ECHO });
  */
 export class TTS {
   /**
@@ -36,10 +47,16 @@ export class TTS {
   }
 
   /**
-   * Convert text to speech
-   * @param {string} text - Text to convert
-   * @param {Object} options - TTS options
-   * @returns {Promise<Buffer>} Audio buffer (MP3)
+   * Convert text to speech audio.
+   *
+   * @param {string} text - Text to convert to speech
+   * @param {Object} [options={}] - TTS generation options
+   * @param {string} [options.voice] - Voice to use (from VOICES enum)
+   * @param {string} [options.model] - Model to use (from MODELS enum)
+   * @param {number} [options.speed=1.0] - Speech speed (0.25 to 4.0)
+   * @param {string} [options.responseFormat='mp3'] - Audio format (mp3, opus, aac, flac)
+   * @returns {Promise<Buffer>} Audio buffer
+   * @throws {Error} If TTS generation fails
    */
   async speak(text, options = {}) {
     const {

package/src/cdn-entry.js

@@ -0,0 +1,22 @@
+/**
+ * CDN Entry Point for HoloSphere
+ *
+ * This file creates a clean global API for browser usage.
+ * After including the script, use: new HoloSphere({ appName: 'my-app' })
+ *
+ * Also exposes h3 library as window.h3 for hexagon visualization.
+ */
+
+// Import the main class
+import { HoloSphere } from './index.js';
+
+// Import h3-js for hexagon boundary visualization
+import * as h3 from 'h3-js';
+
+// Expose h3 globally for widget use
+if (typeof window !== 'undefined') {
+  window.h3 = h3;
+}
+
+// Export only the main class as default
+export default HoloSphere;

package/src/content/social-protocols.js

@@ -1,16 +1,20 @@
 /**
- * Social Protocol Adapters (Nostr, ActivityPub)
+ * @fileoverview Social protocol adapters for Nostr (NIP-01) and ActivityPub formats.
+ * Provides validation, transformation, and filtering utilities for social content integration.
+ * @module content/social-protocols
  */
 
 // Import ValidationError from the validator module
 import { ValidationError } from '../schema/validator.js';
 
 /**
- * Validate Nostr NIP-01 event format
- * @param {Object} event - Nostr event
- * @param {boolean} partial - Allow partial events (missing id, pubkey, sig)
- * @returns {boolean} True if valid
- * @throws {ValidationError} If strict validation fails
+ * Validate Nostr NIP-01 event format.
+ * Checks required fields (kind, tags, content, created_at) and optionally id, pubkey, sig.
+ * @param {Object} event - Nostr event object to validate
+ * @param {boolean} [partial=true] - Allow partial events (missing id, pubkey, sig for signing)
+ * @param {boolean} [throwOnError=false] - Throw ValidationError on failure instead of returning false
+ * @returns {boolean} True if valid, false otherwise (unless throwOnError is true)
+ * @throws {ValidationError} If validation fails and throwOnError is true
  */
 export function validateNostrEvent(event, partial = true, throwOnError = false) {
   if (!event || typeof event !== 'object') {
@@ -56,12 +60,13 @@ export function validateNostrEvent(event, partial = true, throwOnError = false)
 }
 
 /**
- * Validate ActivityPub object format
- * @param {Object} object - ActivityPub object
- * @param {boolean} throwOnError - Throw ValidationError on failure
- * @param {boolean} requireId - Require id field (default: false, will be auto-generated)
- * @returns {boolean} True if valid
- * @throws {ValidationError} If strict validation fails
+ * Validate ActivityPub object format.
+ * Checks for required @context and type fields, optionally validates id field.
+ * @param {Object} object - ActivityPub object to validate
+ * @param {boolean} [throwOnError=false] - Throw ValidationError on failure instead of returning false
+ * @param {boolean} [requireId=false] - Require id field (default: false, will be auto-generated)
+ * @returns {boolean} True if valid, false otherwise (unless throwOnError is true)
+ * @throws {ValidationError} If validation fails and throwOnError is true
  */
 export function validateActivityPubObject(object, throwOnError = false, requireId = false) {
   if (!object || typeof object !== 'object') {
@@ -85,9 +90,10 @@ export function validateActivityPubObject(object, throwOnError = false, requireI
 }
 
 /**
- * Transform Nostr event to HoloSphere format
- * @param {Object} event - Nostr event
- * @returns {Object} HoloSphere data object
+ * Transform Nostr event to HoloSphere storage format.
+ * Normalizes Nostr events and adds metadata for HoloSphere compatibility.
+ * @param {Object} event - Nostr NIP-01 event object
+ * @returns {Object} HoloSphere data object with protocol metadata
  */
 export function transformNostrEvent(event) {
   // Generate missing fields if needed
@@ -115,9 +121,10 @@ export function transformNostrEvent(event) {
 }
 
 /**
- * Transform ActivityPub object to HoloSphere format
+ * Transform ActivityPub object to HoloSphere storage format.
+ * Normalizes ActivityPub objects and adds metadata for HoloSphere compatibility.
  * @param {Object} object - ActivityPub object
- * @returns {Object} HoloSphere data object
+ * @returns {Object} HoloSphere data object with protocol metadata
  */
 export function transformActivityPubObject(object) {
   // Generate ID if not provided
@@ -139,10 +146,11 @@ export function transformActivityPubObject(object) {
 }
 
 /**
- * Filter social content by access level
- * @param {Object[]} content - Social content array
- * @param {string} accessLevel - Access level filter
- * @returns {Object[]} Filtered content
+ * Filter social content by access level.
+ * Returns items matching the specified access level or all items if no level specified.
+ * @param {Object[]} content - Array of social content items
+ * @param {string} accessLevel - Access level to filter by (e.g., 'public', 'private')
+ * @returns {Object[]} Filtered content array
  */
 export function filterByAccessLevel(content, accessLevel) {
   if (!accessLevel) return content;
@@ -153,10 +161,11 @@ export function filterByAccessLevel(content, accessLevel) {
 }
 
 /**
- * Filter social content by protocol
- * @param {Object[]} content - Social content array
- * @param {string} protocol - Protocol filter ('nostr' or 'activitypub')
- * @returns {Object[]} Filtered content
+ * Filter social content by protocol type.
+ * Returns items matching the specified protocol or all items if 'all' is specified.
+ * @param {Object[]} content - Array of social content items
+ * @param {string} protocol - Protocol to filter by ('nostr', 'activitypub', or 'all')
+ * @returns {Object[]} Filtered content array
  */
 export function filterByProtocol(content, protocol) {
   if (!protocol || protocol === 'all') return content;

package/src/contracts/chain-manager.js

@@ -1,11 +1,21 @@
 /**
- * ChainManager - Multi-chain connection management for Holosphere contracts
- * Handles provider/signer setup, network switching, and wallet management
+ * @fileoverview Multi-chain connection manager for Holosphere smart contracts.
+ * Handles provider/signer setup, network switching, and wallet management across EVM chains.
+ * @module contracts/chain-manager
  */
 
 import { NETWORKS, getNetwork, isNetworkSupported } from './networks.js';
 
+/**
+ * Multi-chain connection manager for Holosphere contracts.
+ * Supports both RPC providers and browser wallets (MetaMask, etc.).
+ * @class
+ */
 export class ChainManager {
+  /**
+   * Create a new ChainManager instance.
+   * @param {Object} [config={}] - Configuration options
+   */
   constructor(config = {}) {
     this.config = config;
     this.provider = null;
@@ -17,8 +27,9 @@ export class ChainManager {
   }
 
   /**
-   * Initialize ethers.js (lazy load)
+   * Initialize ethers.js library (lazy load).
    * @private
+   * @returns {Promise<Object>} Ethers.js module
    */
   async _loadEthers() {
     if (!this.ethers) {
@@ -30,11 +41,12 @@ export class ChainManager {
   }
 
   /**
-   * Connect to a network
+   * Connect to a network using RPC provider.
    * @param {string} networkName - Network name (e.g., 'sepolia', 'polygon')
    * @param {string} [privateKey] - Private key for signing transactions
    * @param {string} [rpcUrl] - Custom RPC URL (overrides default)
-   * @returns {Promise<{provider, signer, network}>}
+   * @returns {Promise<{provider: Object, signer: Object|null, network: Object, networkName: string, config: Object}>} Connection details
+   * @throws {Error} If network is unsupported and no custom RPC URL provided
    */
   async connect(networkName, privateKey, rpcUrl) {
     const ethers = await this._loadEthers();
@@ -78,9 +90,10 @@ export class ChainManager {
   }
 
   /**
-   * Connect using browser wallet (MetaMask, etc.)
+   * Connect using browser wallet (MetaMask, etc.).
    * @param {string} [networkName] - Optionally switch to this network
-   * @returns {Promise<{provider, signer, network, address}>}
+   * @returns {Promise<{provider: Object, signer: Object, network: Object, address: string}>} Connection details including user address
+   * @throws {Error} If no browser wallet is detected
    */
   async connectBrowser(networkName) {
     const ethers = await this._loadEthers();
@@ -117,8 +130,11 @@ export class ChainManager {
   }
 
   /**
-   * Switch to a different network (browser wallet only)
+   * Switch to a different network (browser wallet only).
+   * Adds the network to the wallet if it doesn't exist.
    * @param {string} networkName - Target network name
+   * @returns {Promise<void>}
+   * @throws {Error} If not using a browser wallet or network is unknown
    */
   async switchNetwork(networkName) {
     if (typeof window === 'undefined' || !window.ethereum) {
@@ -165,8 +181,9 @@ export class ChainManager {
   }
 
   /**
-   * Get the current provider
-   * @returns {Provider}
+   * Get the current provider.
+   * @returns {Object} Ethers.js provider instance
+   * @throws {Error} If not initialized
    */
   getProvider() {
     this._requireInitialized();
@@ -174,8 +191,9 @@ export class ChainManager {
   }
 
   /**
-   * Get the current signer
-   * @returns {Signer}
+   * Get the current signer.
+   * @returns {Object} Ethers.js signer instance
+   * @throws {Error} If not initialized or no signer available
    */
   getSigner() {
     this._requireInitialized();
@@ -186,8 +204,9 @@ export class ChainManager {
   }
 
   /**
-   * Get the connected address
-   * @returns {Promise<string>}
+   * Get the connected wallet address.
+   * @returns {Promise<string>} Ethereum address
+   * @throws {Error} If no signer available
    */
   async getAddress() {
     const signer = this.getSigner();
@@ -195,9 +214,10 @@ export class ChainManager {
   }
 
   /**
-   * Get ETH balance of an address
+   * Get ETH balance of an address.
    * @param {string} [address] - Address to check (defaults to signer)
-   * @returns {Promise<string>} Balance in ETH
+   * @returns {Promise<string>} Balance in ETH as decimal string
+   * @throws {Error} If not initialized or no address/signer available
    */
   async getBalance(address) {
     this._requireInitialized();
@@ -211,8 +231,9 @@ export class ChainManager {
   }
 
   /**
-   * Get current network configuration
-   * @returns {Object}
+   * Get current network configuration.
+   * @returns {Object} Network configuration object
+   * @throws {Error} If not initialized
    */
   getNetworkConfig() {
     this._requireInitialized();
@@ -220,8 +241,9 @@ export class ChainManager {
   }
 
   /**
-   * Get current chain ID
-   * @returns {number}
+   * Get current chain ID.
+   * @returns {number} Chain ID as number
+   * @throws {Error} If not initialized
    */
   getChainId() {
     this._requireInitialized();
@@ -229,9 +251,9 @@ export class ChainManager {
   }
 
   /**
-   * Check if connected to the expected network
+   * Check if connected to the expected network.
    * @param {string} expectedNetwork - Expected network name
-   * @returns {boolean}
+   * @returns {boolean} True if on expected network
    */
   isOnNetwork(expectedNetwork) {
     if (!this._initialized) return false;
@@ -241,11 +263,12 @@ export class ChainManager {
   }
 
   /**
-   * Create a contract instance
+   * Create a contract instance.
    * @param {string} address - Contract address
    * @param {Array} abi - Contract ABI
    * @param {boolean} [useSigner=true] - Use signer for write operations
-   * @returns {Contract}
+   * @returns {Promise<Object>} Ethers.js Contract instance
+   * @throws {Error} If not initialized
    */
   async getContract(address, abi, useSigner = true) {
     this._requireInitialized();
@@ -255,11 +278,12 @@ export class ChainManager {
   }
 
   /**
-   * Deploy a contract
+   * Deploy a contract.
    * @param {Array} abi - Contract ABI
    * @param {string} bytecode - Contract bytecode
    * @param {Array} [constructorArgs=[]] - Constructor arguments
-   * @returns {Promise<{contract, address, deployTx}>}
+   * @returns {Promise<{contract: Object, address: string, deployTx: Object, txHash: string}>} Deployment details
+   * @throws {Error} If not initialized or no signer available
    */
   async deployContract(abi, bytecode, constructorArgs = []) {
     this._requireInitialized();
@@ -285,10 +309,11 @@ export class ChainManager {
   }
 
   /**
-   * Wait for a transaction to be mined
+   * Wait for a transaction to be mined.
    * @param {string} txHash - Transaction hash
    * @param {number} [confirmations=1] - Number of confirmations to wait for
-   * @returns {Promise<TransactionReceipt>}
+   * @returns {Promise<Object>} Transaction receipt
+   * @throws {Error} If not initialized
    */
   async waitForTransaction(txHash, confirmations = 1) {
     this._requireInitialized();
@@ -296,9 +321,10 @@ export class ChainManager {
   }
 
   /**
-   * Estimate gas for a transaction
+   * Estimate gas for a transaction.
    * @param {Object} tx - Transaction object
-   * @returns {Promise<bigint>}
+   * @returns {Promise<bigint>} Estimated gas amount
+   * @throws {Error} If not initialized
    */
   async estimateGas(tx) {
     this._requireInitialized();
@@ -306,8 +332,9 @@ export class ChainManager {
   }
 
   /**
-   * Get current gas price
-   * @returns {Promise<{gasPrice: string, maxFeePerGas: string, maxPriorityFeePerGas: string}>}
+   * Get current gas price and fee data.
+   * @returns {Promise<{gasPrice: string|null, maxFeePerGas: string|null, maxPriorityFeePerGas: string|null}>} Fee data in gwei
+   * @throws {Error} If not initialized
    */
   async getGasPrice() {
     this._requireInitialized();
@@ -321,10 +348,10 @@ export class ChainManager {
   }
 
   /**
-   * Parse units (e.g., ETH to wei)
+   * Parse units (e.g., ETH to wei).
    * @param {string|number} value - Value to parse
    * @param {string|number} [unit='ether'] - Unit name or decimals
-   * @returns {bigint}
+   * @returns {Promise<bigint>} Parsed value as bigint
    */
   async parseUnits(value, unit = 'ether') {
     const ethers = await this._loadEthers();
@@ -332,10 +359,10 @@ export class ChainManager {
   }
 
   /**
-   * Format units (e.g., wei to ETH)
+   * Format units (e.g., wei to ETH).
    * @param {bigint|string} value - Value to format
    * @param {string|number} [unit='ether'] - Unit name or decimals
-   * @returns {string}
+   * @returns {Promise<string>} Formatted value as decimal string
    */
   async formatUnits(value, unit = 'ether') {
     const ethers = await this._loadEthers();
@@ -343,8 +370,9 @@ export class ChainManager {
   }
 
   /**
-   * Check if manager is initialized
+   * Check if manager is initialized.
    * @private
+   * @throws {Error} If not initialized
    */
   _requireInitialized() {
     if (!this._initialized) {
@@ -353,15 +381,15 @@ export class ChainManager {
   }
 
   /**
-   * Check if connected
-   * @returns {boolean}
+   * Check if connected to a network.
+   * @returns {boolean} True if connected
    */
   isConnected() {
     return this._initialized && this.provider !== null;
   }
 
   /**
-   * Disconnect and clean up
+   * Disconnect and clean up resources.
    */
   disconnect() {
     this.provider = null;