holosphere 1.0.7 → 1.0.8

package/README.md

@@ -2,205 +2,175 @@
 
 HoloSphere is a decentralized geospatial data management system that combines hierarchical hexagonal tiling (H3) with distributed data storage (GunDB) and AI-powered processing of information.
 
-## Features
+## Installation
 
-- **Hierarchical Spatial Data**: Uses Uber's H3 spatial indexing system for efficient geospatial data organization
-- **Decentralized Storage**: Built on GunDB for peer-to-peer data storage and synchronization
-- **Schema Validation**: JSON Schema validation for data integrity
-- **AI Processing**: Extensible AI-powered content analysis and summarization across hexagonal regions
-- **Voting System**: Built-in delegation and voting mechanisms for collaborative decision-making
-- **Multi-scale Operations**: Automatic content propagation across different spatial resolutions
+```bash
+npm install holosphere
+```
 
-## License
+## Basic Usage
+
+```javascript
+import HoloSphere from 'holosphere';
 
-GNU Lesser General Public License v3.0 (LGPL-3.0)
+// Initialize HoloSphere
+const holo = new HoloSphere('my-app');
 
-This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
+// Optional: Initialize with OpenAI
+const holoAI = new HoloSphere('my-app', 'your-openai-key');
+```
 
-This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+## Core Features
 
-You should have received a copy of the GNU Lesser General Public License along with this library; if not, see <https://www.gnu.org/licenses/>.
+### User Management
 
-### Key Points of LGPL-3.0
+```javascript
+// Create a new user
+await holo.createUser('username', 'password');
 
-- You can use this library in proprietary applications
-- Any modifications to the library itself must be distributed under LGPL
-- Applications that use the library don't have to be LGPL
-- If you modify the library, you must make the source code available
-- You must provide a way for users to relink with a modified version of the library
+// Login
+await holo.login('username', 'password');
 
-## Dependencies
+// Logout
+await holo.logout();
+```
 
-### Core Dependencies
-- **h3-js**: Uber's H3 geospatial indexing system
-- **gun**: Decentralized graph database
-- **ajv**: JSON Schema validation
-- **lodash**: Utility functions
+### Schema Operations
 
-### Optional Dependencies
-- **langchain**: AI/LLM integration framework
-- **openai**: OpenAI API client (optional)
+```javascript
+// Define a schema for a lens
+const schema = {
+    type: 'object',
+    properties: {
+        id: { type: 'string' },
+        data: { type: 'string' }
+    },
+    required: ['id', 'data']
+};
 
-## Getting Started
+// Set schema for a lens
+await holo.setLensSchema('myLens', schema);
 
-```bash
-npm install holosphere
+// Get schema for a lens
+const lensSchema = await holo.getLensSchema('myLens');
 ```
 
-## Basic Usage
+### Global Data Operations
 
 ```javascript
-import { HoloSphere } from 'holosphere';
-
-// Initialize HoloSphere with your configuration
-const holo = new HoloSphere({
-  peers: ['http://localhost:8765/gun'],
-  aiProvider: 'local' // or 'openai', 'azure', etc.
+// Store data globally
+await holo.putGlobalData('settings', {
+    id: 'config1',
+    theme: 'dark'
 });
 
-// Create or access a hexagonal region
-const hex = await holo.getHex('8928308280fffff');
+// Get all data from a table
+const allSettings = await holo.getGlobalData('settings');
 
-// Store data in the region
-await hex.put({
-  type: 'observation',
-  data: {
-    temperature: 22.5,
-    timestamp: Date.now()
-  }
-});
+// Get specific data by key
+const config = await holo.getGlobalDataKey('settings', 'config1');
 
-// Subscribe to changes
-hex.subscribe(data => {
-  console.log('New data:', data);
-});
+// Delete a global table
+await holo.deleteGlobalData('settings');
 ```
 
-## Advanced Features
-
-### Spatial Queries
+### Hex Data Operations
 
 ```javascript
-// Find all hexagons within a radius
-const hexagons = await holo.findWithin({
-  lat: 37.7749,
-  lng: -122.4194,
-  radius: 5000 // meters
+// Store data in a hex
+await holo.putHexData('hex123', 'observations', {
+    id: 'obs1',
+    data: 'value'
 });
 
-// Query data across multiple resolutions
-const aggregatedData = await holo.aggregate({
-  hexIds: hexagons,
-  resolution: 7,
-  method: 'average'
-});
-```
+// Get all data from a hex/lens
+const data = await holo.getHexData('hex123', 'observations');
 
-### AI Processing
+// Get specific data by key
+const item = await holo.getHexKey('hex123', 'observations', 'obs1');
 
-```javascript
-// Process content with AI
-const summary = await hex.processContent({
-  processor: 'summarize',
-  options: {
-    maxLength: 100
-  }
-});
+// Get raw GunDB node
+const node = await holo.getHexNode('hex123', 'observations', 'obs1');
 
-// Analyze trends across regions
-const analysis = await holo.analyzeRegion({
-  hexIds: hexagons,
-  timeRange: '7d',
-  metrics: ['sentiment', 'topics']
-});
+// Delete specific data
+await holo.deleteHexData('hex123', 'observations', 'obs1');
+
+// Delete a node by tag
+await holo.deleteNode('nodeId', 'tag');
+
+// Clear all data in a lens
+await holo.clearlens('hex123', 'observations');
 ```
 
-### Voting and Governance
+### Encrypted Data
 
 ```javascript
-// Create a proposal
-const proposal = await hex.createProposal({
-  title: 'Update Data Schema',
-  description: 'Add new fields for environmental metrics',
-  changes: {
-    schema: newSchemaDefinition
-  }
-});
+// Store encrypted data (requires authenticated user)
+await holo.putHexData('hex123', 'private', {
+    id: 'secret1',
+    data: 'sensitive'
+}, true, 'encryption-key');
 
-// Cast a vote
-await proposal.vote({
-  support: true,
-  weight: 1.0
-});
-```
+// Encrypt specific data
+const encrypted = await holo.encrypt(data, 'secret-key');
 
-## Configuration
+// Decrypt data
+const decrypted = await holo.decrypt(encrypted, 'secret-key');
+```
 
-HoloSphere can be configured with various options:
+### Geospatial Operations
 
 ```javascript
-const config = {
-  // Network configuration
-  peers: ['https://peer1.example.com/gun', 'https://peer2.example.com/gun'],
-  
-  // Storage options
-  storage: {
-    type: 'indexeddb',
-    namespace: 'my-app'
-  },
-  
-  // AI processing configuration
-  ai: {
-    provider: 'local',
-    model: 'gpt-3.5-turbo',
-    apiKey: process.env.AI_API_KEY
-  },
-  
-  // Schema validation
-  schema: {
-    strict: true,
-    customValidators: {}
-  }
-};
+// Get hex from coordinates
+const hex = await holo.getHex(37.7749, -74.0060, 7);
+
+// Get all scales for coordinates
+const scales = holo.getScalespace(37.7749, -74.0060);
+
+// Get all parent hexes
+const parents = holo.getHexScalespace('hex123');
 
-const holo = new HoloSphere(config);
+// Compute operations on hex data
+await holo.compute('hex123', 'observations', 'summarize');
+
+// Upcast data to parent hexes
+await holo.upcast('hex123', 'observations', data);
 ```
 
-## Documentation
+### Real-time Subscriptions
 
-For detailed documentation, please visit our [documentation site](https://docs.holons.io).
+```javascript
+// Subscribe to changes
+holo.subscribe('hex123', 'observations', (data, key) => {
+    console.log('Updated data:', data);
+    console.log('Key:', key);
+});
+```
 
-## Contributing
+### Voting System
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
-- Code of Conduct
-- Development setup
-- Testing guidelines
-- Pull request process
+```javascript
+// Get final vote (including delegations)
+const finalVote = holo.getFinalVote(userId, topic, votes);
 
-## Support
+// Get aggregated votes for a hex
+const results = holo.aggregateVotes(hexId, topic);
 
-- [GitHub Issues](https://github.com/liminalvillage/holosphere/issues)
-- [Discord Community](https://discord.gg/liminalvillage)
+// Delegate voting power
+await holo.delegateVote(userId, topic, delegateId);
 
-## Roadmap
+// Cast a vote
+await holo.vote(userId, hexId, topic, voteChoice);
+```
 
-- [ ] Enhanced spatial indexing algorithms
-- [ ] Additional AI model integrations
-- [ ] Improved data replication strategies
-- [ ] Extended governance mechanisms
-- [ ] Mobile SDK development
+## License
 
-## Citation
+GPL-3.0-or-later
 
-If you use HoloSphere in your research, please cite:
+## Dependencies
 
-```bibtex
-@software{holosphere2024,
-  author = {Roberto Valenti},
-  title = {HoloSphere: Decentralized Geospatial Data Management},
-  year = {2024},
-  url = {https://github.com/holosphere/holosphere}
-}
-```
+- h3-js: Uber's H3 geospatial indexing system
+- gun: Decentralized graph database
+- ajv: JSON Schema validation
+- openai: OpenAI API client (optional)
 

package/babel.config.json

@@ -0,0 +1,12 @@
+{
+  "presets": [
+    [
+      "@babel/preset-env",
+      {
+        "targets": {
+          "node": "current"
+        }
+      }
+    ]
+  ]
+} 

package/holosphere.d.ts

@@ -1,20 +1,47 @@
 declare module 'holosphere' {
     export default class HoloSphere {
-        constructor(name: string, openaikey?: string | null);
-        subscribe(hex: string, lense: string, callback: (item: any, key: string) => void): void;
-        put(hex: string, lense: string, content: any): Promise<void>;
-        delete(id: string, tag: string): Promise<void>;
-        get(hex: string, lense: string): Promise<any[]>;
-        getKey(hex: string, lense: string, key: string): Promise<any | null>;
-        getNode(hex: string, lense: string, key: string): Promise<any | null>;
-        compute(hex: string, lense: string, operation: string): Promise<void>;
-        clearlense(hex: string, lense: string): Promise<void>;
-        summarize(history: string): Promise<string>;
-        upcast(hex: string, lense: string, content: any): Promise<any>;
-        updateParent(id: string, report: string): Promise<any>;
+        constructor(appName: string, openaikey?: string | null);
+
+        // User Management
+        createUser(username: string, password: string): Promise<object>;
+        login(username: string, password: string): Promise<object>;
+        logout(): Promise<void>;
+
+        // Schema Operations
+        setLensSchema(lens: string, schema: object): Promise<void>;
+        getLensSchema(lens: string): Promise<object | null>;
+
+        // Encryption Operations
+        encrypt(data: any, secret: string): Promise<string>;
+        decrypt(encryptedData: string, secret: string): Promise<any>;
+
+        // Global Data Operations
+        putGlobalData(tableName: string, data: object): Promise<void>;
+        getGlobalData(tableName: string): Promise<object | null>;
+        getGlobalDataKey(tableName: string, key: string): Promise<object | null>;
+        deleteGlobalData(tableName: string): Promise<void>;
+
+        // Hex Data Operations
+        putHexData(hexId: string, lens: string, content: object, encrypt?: boolean, secret?: string | null): Promise<void>;
+        getHexData(hexId: string, lens: string, secret?: string | null): Promise<Array<any>>;
+        getHexKey(hexId: string, lens: string, key: string): Promise<any | null>;
+        getHexNode(hexId: string, lens: string, key: string): Promise<any>;
+        deleteHexData(hexId: string, lens: string, contentId: string): Promise<void>;
+        deleteNode(nodeId: string, tag: string): Promise<void>;
+        clearlens(hex: string, lens: string): Promise<void>;
+
+        // Geospatial Operations
         getHex(lat: number, lng: number, resolution: number): Promise<string>;
         getScalespace(lat: number, lng: number): string[];
         getHexScalespace(hex: string): string[];
+        compute(hex: string, lens: string, operation: string): Promise<void>;
+        upcast(hex: string, lens: string, content: any): Promise<any>;
+
+        // Subscription
+        subscribe(hex: string, lens: string, callback: (data: any, key: string) => void): void;
+
+        // Voting System
+        getFinalVote(userId: string, topic: string, votes: object, visited?: Set<string>): string | null;
         aggregateVotes(hexId: string, topic: string): object;
         delegateVote(userId: string, topic: string, delegateTo: string): Promise<void>;
         vote(userId: string, hexId: string, topic: string, vote: string): Promise<void>;

package/holosphere.js

@@ -12,7 +12,7 @@ class HoloSphere {
     constructor(appname, openaikey = null) {
         this.validator = new Ajv2019({ allErrors: false, strict: false });
         this.gun = Gun({
-            peers: ['https://59.src.eco/gun'],
+            peers: ['http://gun.holons.io','https://59.src.eco/gun'],
             axe: false,
             // uuid: (content) => { // generate a unique id for each node
             //     console.log('uuid', content);
@@ -21,7 +21,7 @@ class HoloSphere {
 
         this.gun = this.gun.get(appname)
         this.users = {}; // Initialize users
-        this.hexagonVotes = {}; // Initialize hexagonVotes
+        this.holonagonVotes = {}; // Initialize holonagonVotes
 
         if (openaikey != null) {
             this.openai = new OpenAI({
@@ -82,14 +82,14 @@ class HoloSphere {
     }
 
     /**
-     * Stores content in the specified hex and lens.
-     * @param {string} hex - The hex identifier.
+     * Stores content in the specified holon and lens.
+     * @param {string} holon - The holon identifier.
      * @param {string} lens - The lens under which to store the content.
      * @param {object} content - The content to store.
      */
-    async put(hex, lens, content) {
-        if (!hex || !lens || !content) return;
-        console.error('Error in put:', hex, lens, content);
+    async put(holon, lens, content) {
+        if (!holon || !lens || !content) return;
+        console.error('Error in put:', holon, lens, content);
         // Retrieve the schema for the lens
         let schema = await this.getSchema(lens)
         if (schema) {
@@ -108,19 +108,19 @@ class HoloSphere {
 
         if (content.id) { //use the user-defined id. Important to be able to send updates using put
             noderef = this.gun.get(lens).get(content.id).put(payload)
-            this.gun.get(hex.toString()).get(lens).get(content.id).put(payload)
+            this.gun.get(holon.toString()).get(lens).get(content.id).put(payload)
         } else { // create a content-addressable reference like IPFS. Note: no updates possible using put
             const hashBuffer = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(payload));
             const hashArray = Array.from(new Uint8Array(hashBuffer));
-            const hashHex = hashArray.map(byte => byte.toString(16).padStart(2, "0")).join("");
-            noderef = this.gun.get(lens).get(hashHex).put(payload)
-            this.gun.get(hex.toString()).get(lens).get(hashHex).put(payload)
+            const hashholon = hashArray.map(byte => byte.toString(16).padStart(2, "0")).join("");
+            noderef = this.gun.get(lens).get(hashholon).put(payload)
+            this.gun.get(holon.toString()).get(lens).get(hashholon).put(payload)
         }
 
     }
 
-    async putNode(hex, lens, node) {
-        this.gun.get(hex).get(lens).set(node)
+    async putNode(holon, lens, node) {
+        this.gun.get(holon).get(lens).set(node)
     }
 
     async parse(data) {
@@ -130,12 +130,12 @@ class HoloSphere {
             if (data._ && data._["#"]) {
                 // If the data is a reference, fetch the actual content
                 let query = data._['#'].split('/');
-                let hex = query[1];
+                let holon = query[1];
                 let lens = query[2];
                 let key = query[3];
-                parsed = await this.getKey(hex, lens, key);
+                parsed = await this.getKey(holon, lens, key);
             } else if (data._ && data._['>']) {
-                // This might be a GunDB node, try to get its value
+                // This might be a gun node, try to get its value
                 const nodeValue = Object.values(data).find(v => typeof v !== 'object' && v !== '_');
                 if (nodeValue) {
                     try {
@@ -145,7 +145,7 @@ class HoloSphere {
                         parsed = nodeValue; // return the raw data
                     }
                 } else {
-                    console.log('Unable to parse GunDB node:', data);
+                    console.log('Unable to parse gun node:', data);
                     parsed = data; // return the original data
                 }
             } else {
@@ -166,17 +166,17 @@ class HoloSphere {
     }
 
     /**
-     * Retrieves content from the specified hex and lens.
-     * @param {string} hex - The hex identifier.
+     * Retrieves content from the specified holon and lens.
+     * @param {string} holon - The holon identifier.
      * @param {string} lens - The lens from which to retrieve content.
      * @returns {Promise<Array<object>>} - The retrieved content.
      */
-    async get(hex, lens) {
-        if (!hex || !lens) {
-            console.log('Wrong get:', hex, lens)
+    async get(holon, lens) {
+        if (!holon || !lens) {
+            console.log('Wrong get:', holon, lens)
             return;
         }
-        // Wrap the GunDB operation in a promise
+        // Wrap the gun operation in a promise
         //retrieve lens schema
         const schema = await this.getSchema(lens);
 
@@ -188,11 +188,11 @@ class HoloSphere {
         return new Promise(async (resolve, reject) => {
             let output = []
             let counter = 0
-            this.gun.get(hex.toString()).get(lens).once((data, key) => {
+            this.gun.get(holon.toString()).get(lens).once((data, key) => {
                 if (data) {
                     const maplenght = Object.keys(data).length - 1
                     console.log('Map length:', maplenght)
-                    this.gun.get(hex.toString()).get(lens).map().once(async (itemdata, key) => {
+                    this.gun.get(holon.toString()).get(lens).map().once(async (itemdata, key) => {
                         counter += 1
                         if (itemdata) {
                             let parsed = await this.parse (itemdata)
@@ -202,7 +202,7 @@ class HoloSphere {
                                 let valid = this.validator.validate(schema, parsed);
                                 if (!valid || parsed == null || parsed == undefined) {
                                     console.log('Removing Invalid content:', this.validator.errors);
-                                    this.gun.get(hex).get(lens).get(key).put(null);
+                                    this.gun.get(holon).get(lens).get(key).put(null);
 
                                 } else {
                                     output.push(parsed);
@@ -225,16 +225,16 @@ class HoloSphere {
     }
 
        /**
-     * Retrieves a specific key from the specified hex and lens.
-     * @param {string} hex - The hex identifier.
+     * Retrieves a specific key from the specified holon and lens.
+     * @param {string} holon - The holon identifier.
      * @param {string} lens - The lens from which to retrieve the key.
      * @param {string} key - The specific key to retrieve.
      * @returns {Promise<object|null>} - The retrieved content or null if not found.
      */
-       async getKey(hex, lens, key) {
+       async getKey(holon, lens, key) {
         return new Promise((resolve) => {
             // Use Gun to get the data
-            this.gun.get(hex).get(lens).get(key).once((data, key) => {
+            this.gun.get(holon).get(lens).get(key).once((data, key) => {
                 if (data) {
                     console.log('Data getting parsed:', data)
                     try {
@@ -254,33 +254,132 @@ class HoloSphere {
     }
 
     /**
-   * Retrieves a specific gundb node from the specified hex and lens.
-   * @param {string} hex - The hex identifier.
+   * Retrieves a specific gun node from the specified holon and lens.
+   * @param {string} holon - The holon identifier.
    * @param {string} lens - The lens from which to retrieve the key.
    * @param {string} key - The specific key to retrieve.
    * @returns {Promise<object|null>} - The retrieved content or null if not found.
    */
-     getNode(hex, lens, key) {
+     getNode(holon, lens, key) {
         // Use Gun to get the data
-        return this.gun.get(hex).get(lens).get(key)
+        return this.gun.get(holon).get(lens).get(key)
     }
 
+    //GLOBAL FUNCTIONS
+    async deleteNode(nodeId, tag) {
+        await this.gun.get(nodeId).get(tag).put(null)
+    }
+    // ================================ GLOBAL FUNCTIONS ================================
+    /**
+     * Stores data in a global (non-holon-specific) table.
+     * @param {string} table - The table name to store data in.
+     * @param {object} data - The data to store. If it has an 'id' field, it will be used as the key.
+     * @returns {Promise<void>}
+     */
+    async putGlobal(tableName, data) {
+        return new Promise((resolve, reject) => {
+            if (!tableName || !data) {
+                reject(new Error('Table name and data are required'));
+                return;
+            }
+
+            if (data.id) {
+                this.gun.get(tableName).get(data.id).put(JSON.stringify(data), ack => {
+                    if (ack.err) {
+                        reject(new Error(ack.err));
+                    } else {
+                        resolve();
+                    }
+                });
+            } else {
+                this.gun.get(tableName).put(JSON.stringify(data), ack => {
+                    if (ack.err) {
+                        reject(new Error(ack.err));
+                    } else {
+                        resolve();
+                    }
+                });
+            }
+        });
+    }
 
+     /**
+     * Retrieves a specific key from a global table.
+     * @param {string} tableName - The table name to retrieve from.
+     * @param {string} key - The key to retrieve.
+     * @returns {Promise<object|null>} - The parsed data for the key or null if not found.
+     */
+     async getGlobal(tableName, key) {
+        return new Promise((resolve) => {
+            this.gun.get(tableName).get(key).once((data) => {
+                if (!data) {
+                    resolve(null);
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(data);
+                    resolve(parsed);
+                } catch (e) {
+                    resolve(null);
+                }
+            });
+        });
+    }
 
     /**
-     * Computes summaries based on the content within a hex and lens.
-     * @param {string} hex - The hex identifier.
+     * Retrieves all data from a global table.
+     * @param {string} tableName - The table name to retrieve data from.
+     * @returns {Promise<object|null>} - The parsed data from the table or null if not found.
+     */
+    async getAllGlobal(tableName) {
+        return new Promise((resolve) => {
+            this.gun.get(tableName).once((data) => {
+                if (!data) {
+                    resolve(null);
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(data);
+                    resolve(parsed);
+                } catch (e) {
+                    resolve(null);
+                }
+            });
+        });
+    }
+
+   
+
+    /**
+     * Deletes an entire global table.
+     * @param {string} table - The table name to delete.
+     * @returns {Promise<void>}
+     */
+    async deleteAllGlobal(tableName) {
+   
+        return new Promise((resolve) => {
+            this.gun.get(tableName).map().put(null)
+            this.gun.get(tableName).put(null, ack => {
+                resolve();
+            });
+        });
+    }
+
+    // ================================ COMPUTE FUNCTIONS ================================
+    /**
+     * Computes summaries based on the content within a holon and lens.
+     * @param {string} holon - The holon identifier.
      * @param {string} lens - The lens to compute.
      * @param {string} operation - The operation to perform.
      */
-    async compute(hex, lens, operation) {
+    async compute(holon, lens, operation) {
 
-        let res = h3.getResolution(hex);
+        let res = h3.getResolution(holon);
         if (res < 1 || res > 15) return;
         console.log(res)
-        let parent = h3.cellToParent(hex, res - 1);
+        let parent = h3.cellToParent(holon, res - 1);
         let siblings = h3.cellToChildren(parent, res);
-        console.log(hex, parent, siblings, res)
+        console.log(holon, parent, siblings, res)
 
         let content = [];
         let promises = [];
@@ -313,18 +412,18 @@ class HoloSphere {
     }
 
     /**
-     * Clears all entities under a specific hex and lens.
-     * @param {string} hex - The hex identifier.
+     * Clears all entities under a specific holon and lens.
+     * @param {string} holon - The holon identifier.
      * @param {string} lens - The lens to clear.
      */
-    async clearlens(hex, lens) {
+    async clearlens(holon, lens) {
         let entities = {};
 
         // Get list out of Gun
-        this.gun.get(hex).get(lens).map().once((data, key) => {
+        this.gun.get(holon).get(lens).map().once((data, key) => {
             //entities = data;
             //const id = Object.keys(entities)[0] // since this would be in object form, you can manipulate it as you would like. 
-            this.gun.get(hex).get(lens).put({ [key]: null })
+            this.gun.get(holon).get(lens).put({ [key]: null })
         })
     }
 
@@ -367,30 +466,30 @@ class HoloSphere {
     }
 
     /**
-     * Upcasts content to parent hexagons recursively.
-     * @param {string} hex - The current hex identifier.
+     * Upcasts content to parent holonagons recursively.
+     * @param {string} holon - The current holon identifier.
      * @param {string} lens - The lens under which to upcast.
      * @param {object} content - The content to upcast.
      * @returns {Promise<object>} - The upcasted content.
      */
-    async upcast(hex, lens, content) {
-        let res = h3.getResolution(hex)
+    async upcast(holon, lens, content) {
+        let res = h3.getResolution(holon)
         if (res == 0) {
-            await this.putNode(hex, lens, content)
+            await this.putNode(holon, lens, content)
             return content
         }
         else {
-            console.log('Upcasting ', hex, lens, content, res)
-            await this.putNode(hex, lens, content)
-            let parent = h3.cellToParent(hex, res - 1)
+            console.log('Upcasting ', holon, lens, content, res)
+            await this.putNode(holon, lens, content)
+            let parent = h3.cellToParent(holon, res - 1)
             return this.upcast(parent, lens, content)
         }
     }
 
 
     /**
-     * Updates the parent hexagon with a new report.
-     * @param {string} id - The child hex identifier.
+     * Updates the parent holonagon with a new report.
+     * @param {string} id - The child holon identifier.
      * @param {string} report - The report to update.
      * @returns {Promise<object>} - The updated parent information.
      */
@@ -410,21 +509,21 @@ class HoloSphere {
 
 
     /**
-     * Converts latitude and longitude to a hex identifier.
+     * Converts latitude and longitude to a holon identifier.
      * @param {number} lat - The latitude.
      * @param {number} lng - The longitude.
      * @param {number} resolution - The resolution level.
-     * @returns {Promise<string>} - The resulting hex identifier.
+     * @returns {Promise<string>} - The resulting holon identifier.
      */
-    async getHex(lat, lng, resolution) {
+    async getHolon(lat, lng, resolution) {
         return h3.latLngToCell(lat, lng, resolution);
     }
 
     /**
-     * Retrieves all containing hexagons at all scales for given coordinates.
+     * Retrieves all containing holonagons at all scales for given coordinates.
      * @param {number} lat - The latitude.
      * @param {number} lng - The longitude.
-     * @returns {Array<string>} - List of hex identifiers.
+     * @returns {Array<string>} - List of holon identifiers.
      */
     getScalespace(lat, lng) {
         let list = []
@@ -437,31 +536,32 @@ class HoloSphere {
     }
 
     /**
-     * Retrieves all containing hexagons at all scales for a given hex.
-     * @param {string} hex - The hex identifier.
-     * @returns {Array<string>} - List of hex identifiers.
+     * Retrieves all containing holonagons at all scales for a given holon.
+     * @param {string} holon - The holon identifier.
+     * @returns {Array<string>} - List of holon identifiers.
      */
-    getHexScalespace(hex) {
+    getHolonScalespace(holon) {
         let list = []
-        let res = h3.getResolution(hex)
+        let res = h3.getResolution(holon)
         for (let i = res; i >= 0; i--) {
-            list.push(h3.cellToParent(hex, i))
+            list.push(h3.cellToParent(holon, i))
         }
         return list
     }
 
     /**
-     * Subscribes to changes in a specific hex and lens.
-     * @param {string} hex - The hex identifier.
+     * Subscribes to changes in a specific holon and lens.
+     * @param {string} holon - The holon identifier.
      * @param {string} lens - The lens to subscribe to.
      * @param {function} callback - The callback to execute on changes.
      */
-    subscribe(hex, lens, callback) {
-        this.gun.get(hex).get(lens).map().on((data, key) => {
+    subscribe(holon, lens, callback) {
+        this.gun.get(holon).get(lens).map().on((data, key) => {
             callback(data, key)
         })
     }
 
+    // ================================ GOVERNANCE FUNCTIONS ================================
     /**
      * Retrieves the final vote for a user, considering delegations.
      * @param {string} userId - The user's identifier.
@@ -488,16 +588,16 @@ class HoloSphere {
     }
 
     /**
-     * Aggregates votes for a specific hex and topic.
-     * @param {string} hexId - The hex identifier.
+     * Aggregates votes for a specific holon and topic.
+     * @param {string} holonId - The holon identifier.
      * @param {string} topic - The voting topic.
      * @returns {object} - Aggregated vote counts.
      */
-    aggregateVotes(hexId, topic) {
-        if (!this.hexagonVotes[hexId] || !this.hexagonVotes[hexId][topic]) {
+    aggregateVotes(holonId, topic) {
+        if (!this.holonagonVotes[holonId] || !this.holonagonVotes[holonId][topic]) {
             return {}; // Handle undefined votes
         }
-        const votes = this.hexagonVotes[hexId][topic];
+        const votes = this.holonagonVotes[holonId][topic];
         const aggregatedVotes = {};
 
         Object.keys(votes).forEach(userId => {
@@ -526,24 +626,21 @@ class HoloSphere {
     }
 
     /**
-     * Casts a vote for a user on a specific topic and hex.
+     * Casts a vote for a user on a specific topic and holon.
      * @param {string} userId - The user's identifier.
-     * @param {string} hexId - The hex identifier.
+     * @param {string} holonId - The holon identifier.
      * @param {string} topic - The voting topic.
      * @param {string} vote - The vote choice.
      */
-    async vote(userId, hexId, topic, vote) {
+    async vote(userId, holonId, topic, vote) {
         const response = await fetch('/vote', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ userId, hexId, topic, vote })
+            body: JSON.stringify({ userId, holonId, topic, vote })
         });
         alert(await response.text());
     }
 
-
-
-
 }
 
 export default HoloSphere;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "holosphere",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Holonic Geospatial Communication Infrastructure",
   "main": "holosphere.js",
   "types": "holosphere.d.ts",
   "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
   },
   "author": "Roberto Valenti",
   "license": "GPL-3.0-or-later",
@@ -15,5 +15,16 @@
     "gun": "^0.2020.1240",
     "h3-js": "^4.1.0",
     "openai": "^4.29.2"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "jest-environment-node": "^29.7.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {},
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    }
   }
 }

package/test/holosphere.test.js

@@ -1,32 +1,199 @@
 import HoloSphere from '../holosphere.js';
+import * as h3 from 'h3-js';
 
 describe('HoloSphere', () => {
     let holoSphere;
-
+    const testAppName = 'test-app';
+    
     beforeEach(() => {
-        holoSphere = new HoloSphere('test-app', {
-            gunPeers: ['http://localhost:8765/gun'],
+        holoSphere = new HoloSphere(testAppName);
+    });
+
+    describe('Constructor', () => {
+        test('should create instance with app name', () => {
+            expect(holoSphere).toBeInstanceOf(HoloSphere);
+            expect(holoSphere.gunDb).toBeDefined();
+            expect(holoSphere.validator).toBeDefined();
+            expect(holoSphere.aiClient).toBeUndefined();
+        });
+
+        test('should initialize with OpenAI when key provided', () => {
+            const hsWithAI = new HoloSphere(testAppName, 'fake-key');
+            expect(hsWithAI.aiClient).toBeDefined();
+        });
+    });
+
+    describe('Schema Operations', () => {
+        const testLens = 'testLens';
+        const validSchema = {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                data: { type: 'string' }
+            },
+            required: ['id', 'data']
+        };
+
+        test('should set and get lens schema', async () => {
+            await holoSphere.setLensSchema(testLens, validSchema);
+            const result = await holoSphere.getLensSchema(testLens);
+            expect(result).toEqual(validSchema);
+        });
+
+        test('should validate data against schema', async () => {
+            const validData = { id: 'test123', data: 'test data' };
+            const invalidData = { id: 123, data: ['wrong type'] };
+
+            await holoSphere.setLensSchema(testLens, validSchema);
+
+            const validResult = holoSphere.validator.validate(validSchema, validData);
+            expect(validResult).toBe(true);
+
+            const invalidResult = holoSphere.validator.validate(validSchema, invalidData);
+            expect(invalidResult).toBe(false);
+        });
+    });
+
+    describe('Data Operations', () => {
+        const testHex = h3.latLngToCell(40.7128, -74.0060, 7);
+        const testLens = 'testLens';
+        const testContent = { id: '123', data: 'test' };
+
+        test('should put and get hex data', async () => {
+            await holoSphere.putHexData(testHex, testLens, testContent);
+            const result = await holoSphere.getHexData(testHex, testLens);
+            expect(Array.isArray(result)).toBeTruthy();
+            expect(result.some(item => item.id === testContent.id)).toBeTruthy();
+        }, 10000);
+
+        test('should get hex key', async () => {
+            await holoSphere.putHexData(testHex, testLens, testContent);
+            const result = await holoSphere.getHexKey(testHex, testLens, testContent.id);
+            expect(result).toBeDefined();
+            expect(result.id).toBe(testContent.id);
+        }, 10000);
+
+        test('should delete hex data', async () => {
+            await holoSphere.putHexData(testHex, testLens, testContent);
+            await holoSphere.deleteHexData(testHex, testLens, testContent.id);
+            const result = await holoSphere.getHexKey(testHex, testLens, testContent.id);
+            expect(result).toBeNull();
+        }, 10000);
+    });
+
+    describe('Global Data Operations', () => {
+        const tableName = 'testTable';
+        const testData = { id: 'test1', value: 'testValue' };
+
+        test('should put and get global data', async () => {
+            await holoSphere.putGlobalData(tableName, testData);
+            // Add delay to allow Gun to process
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            
+            const result = await holoSphere.getGlobalData(tableName);
+            expect(result).toBeDefined();
+            if (result) {
+                expect(result.id).toBe(testData.id);
+            }
+        }, 15000);
+
+        test('should get global data key', async () => {
+            await holoSphere.putGlobalData(tableName, testData);
+            // Add delay to allow Gun to process
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            
+            const result = await holoSphere.getGlobalDataKey(tableName, testData.id);
+            expect(result).toBeDefined();
+            if (result) {
+                expect(result.id).toBe(testData.id);
+            }
+        }, 15000);
+
+        test('should delete global data', async () => {
+            await holoSphere.putGlobalData(tableName, testData);
+            // Add delay to allow Gun to process
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            
+            await holoSphere.deleteGlobalData(tableName);
+            // Add delay to allow Gun to process
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            
+            const result = await holoSphere.getGlobalData(tableName);
+            expect(result).toBeNull();
+        }, 15000);
+
+        afterEach(async () => {
+            // Clean up after each test
+            await holoSphere.deleteGlobalData(tableName);
+            await new Promise(resolve => setTimeout(resolve, 1000));
         });
     });
 
-    test('initialization', () => {
-        expect(holoSphere).toBeDefined();
-        expect(holoSphere.users).toEqual({});
-        expect(holoSphere.hexagonVotes).toEqual({});
+    describe('Encryption Operations', () => {
+        const testSecret = 'secret123';
+        const testData = { message: 'secret message' };
+
+        test('should encrypt and decrypt data', async () => {
+            const encrypted = await holoSphere.encrypt(testData, testSecret);
+            expect(encrypted).toBeDefined();
+            
+            const decrypted = await holoSphere.decrypt(encrypted, testSecret);
+            expect(decrypted).toEqual(testData);
+        });
+
+        test('should handle encrypted hex data', async () => {
+            const testHex = h3.latLngToCell(40.7128, -74.0060, 7);
+            const testLens = 'testLens';
+            const testContent = { id: 'test123', data: 'secret data' };
+
+            // Create and login test user
+            try {
+                await holoSphere.createUser('testuser', 'testpass');
+                await holoSphere.login('testuser', 'testpass');
+            } catch (error) {
+                console.log('User already exists or login failed');
+            }
+
+            await holoSphere.putHexData(testHex, testLens, testContent, true, testSecret);
+            const result = await holoSphere.getHexData(testHex, testLens, testSecret);
+            
+            expect(Array.isArray(result)).toBeTruthy();
+            await holoSphere.logout();
+        }, 15000);
     });
 
-    test('voting system', async () => {
-        const userId = 'test-user';
-        const hexId = '8928308280fffff';
-        const topic = 'test-topic';
-        const vote = 'yes';
+    describe('Geospatial Operations', () => {
+        const lat = 40.7128;
+        const lng = -74.0060;
+        const resolution = 7;
 
-        await holoSphere.initializeUser(userId);
-        await holoSphere.vote(userId, hexId, topic, vote);
+        test('should get hex from coordinates', async () => {
+            const hex = await holoSphere.getHex(lat, lng, resolution);
+            expect(hex).toBeDefined();
+            expect(typeof hex).toBe('string');
+        });
 
-        const votes = holoSphere.aggregateVotes(hexId, topic);
-        expect(votes).toHaveProperty('yes', 1);
+        test('should get scalespace from coordinates', () => {
+            const scales = holoSphere.getScalespace(lat, lng);
+            expect(Array.isArray(scales)).toBeTruthy();
+            expect(scales.length).toBe(15);
+        });
+
+        test('should get hex scalespace', () => {
+            const hex = h3.latLngToCell(lat, lng, resolution);
+            const scales = holoSphere.getHexScalespace(hex);
+            expect(Array.isArray(scales)).toBeTruthy();
+            expect(scales.length).toBe(resolution + 1);
+        });
     });
 
-    // Add more tests...
+    afterAll(async () => {
+        // Clean up test data
+        const testLens = 'testLens';
+        const testHex = h3.latLngToCell(40.7128, -74.0060, 7);
+        await holoSphere.clearlens(testHex, testLens);
+        
+        // Allow time for Gun to process
+        await new Promise(resolve => setTimeout(resolve, 1000));
+    });
 });