holosphere 1.1.21 → 1.3.0-alpha3

package/holosphere.d.ts

@@ -2,600 +2,323 @@
  * Federation propagation options interface
  */
 interface PropagationOptions {
-  /** Whether to use holograms instead of duplicating data (default: true) */
   useHolograms?: boolean;
-  /** Specific target spaces to propagate to (default: all federated spaces) */
   targetSpaces?: string[];
-  /** Password for accessing the source holon (if needed) */
   password?: string | null;
-  /** Whether to automatically propagate to parent hexagons (default: true) */
   propagateToParents?: boolean;
-  /** Maximum number of parent levels to propagate to (default: 15) */
   maxParentLevels?: number;
 }
 
-/**
- * Put options interface
- */
 interface PutOptions {
-  /** Whether to automatically propagate to federated spaces (default: false) */
   autoPropagate?: boolean;
-  /** Additional options to pass to propagate */
   propagationOptions?: PropagationOptions;
-  /** Whether to disable hologram redirection logic when putting data (default: false) */
   disableHologramRedirection?: boolean;
+  actingAs?: string;
+  password?: string | null;
 }
 
-/**
- * Get options interface
- */
 interface GetOptions {
-  /** Whether to automatically resolve holograms (default: true) */
   resolveHolograms?: boolean;
-  /** Options passed to the schema validator */
   validationOptions?: object;
 }
 
-/**
- * Resolve Hologram options interface
- */
 interface ResolveHologramOptions {
-  /** Whether to follow nested holograms (default: true) */
   followHolograms?: boolean;
-  /** Internal use: Tracks visited souls to prevent loops */
   visited?: Set<string>;
 }
 
-/**
- * Represents a Hologram object, typically containing an id and a soul path.
- */
 interface Hologram {
   id: string;
   soul: string;
-  [key: string]: any; // Allow other properties, e.g., _federation
+  [key: string]: any;
 }
 
 /**
- * Federation info interface
+ * Canonical envelope attached to data resolved from a hologram reference.
+ *
+ * Single source of truth for resolved-hologram metadata. Every read path that
+ * returns data resolved from a hologram (get, getAll, subscribe, getFederated,
+ * getGlobal, getAllGlobal) attaches this field via `attachHologramMeta`.
+ *
+ * On success: `isHologram === true` and source* fields point at the origin.
+ * On failure: `isHologram === false` and `error` describes why resolution failed.
  */
+interface ResolvedHologramMeta {
+  isHologram: boolean;
+  soul: string;
+  sourceHolon?: string | null;
+  sourceLens?: string | null;
+  sourceKey?: string | null;
+  resolvedAt: number;
+  error?: string;
+}
+
+interface ResolvedHologramData {
+  _hologram: ResolvedHologramMeta;
+  [key: string]: any;
+}
+
+/**
+ * Per-partner directional lens config. Directions are from the holding
+ * space's perspective: `inbound` lenses are received from the partner,
+ * `outbound` lenses are sent to the partner.
+ */
+interface FederationLensConfig {
+  inbound: string[];
+  outbound: string[];
+  timestamp: number;
+}
+
 interface FederationInfo {
-  /** Identifier of the holon */
   id: string;
-  /** Name of the holon */
   name: string;
-  /** List of federated space IDs (spaces this holon federates with) */
-  federation: string[];
-  /** List of spaces to notify about changes */
-  notify: string[];
-  /** Timestamp of last update */
+  /** Canonical list of all federation partners (any direction, including no lens flow yet). */
+  federated: string[];
+  /** Partners we receive data FROM (subset of `federated` with non-empty inbound lenses). */
+  inbound: string[];
+  /** Partners we send data TO (subset of `federated` with non-empty outbound lenses). */
+  outbound: string[];
+  /** Per-partner directional lens config. */
+  lensConfig: Record<string, FederationLensConfig>;
+  /** Optional display names for partners. */
+  partnerNames: Record<string, string>;
   timestamp: number;
 }
 
-/**
- * Options for federated data retrieval
- */
 interface GetFederatedOptions {
-  /** Whether to aggregate results by ID */
   aggregate?: boolean;
-  /** Field to use as ID */
   idField?: string;
-  /** Fields to sum during aggregation */
   sumFields?: string[];
-  /** Array fields to concatenate during aggregation */
   concatArrays?: string[];
-  /** Whether to remove duplicates in concatenated arrays */
   removeDuplicates?: boolean;
-  /** Custom merge function for aggregation */
   mergeStrategy?: (items: any[]) => any;
-  /** Whether to include local data */
   includeLocal?: boolean;
-  /** Whether to include federated data */
   includeFederated?: boolean;
-  /** Whether to resolve federation references */
   resolveReferences?: boolean;
-  /** Maximum number of federated spaces to query */
   maxFederatedSpaces?: number;
-  /** Timeout in milliseconds for federated queries */
   timeout?: number;
 }
 
-/**
- * Results from a propagation operation
- */
 interface PropagationResult {
-  /** Number of successfully propagated items */
   success: number;
-  /** Number of errors encountered */
   errors: number;
-  /** Details about errors */
   errorDetails: Array<{ space: string, error: string }>;
-  /** Whether any propagation occurred */
   propagated: boolean;
-  /** Whether references were used */
   referencesUsed: boolean;
-  /** Error message if applicable */
   error?: string;
-  /** Information message if applicable */
   message?: string;
-  /** Parent propagation results */
   parentPropagation?: {
-    /** Number of successfully propagated items to parents */
     success: number;
-    /** Number of errors encountered during parent propagation */
     errors: number;
-    /** Number of parent propagations skipped */
     skipped: number;
-    /** Messages from parent propagation */
     messages: string[];
   };
 }
 
-/**
- * Result from a put operation
- */
 interface PutResult {
-  /** Indicates if the put operation was successful */
   success: boolean;
-  /** Indicates if the data ultimately put at the path was a hologram */
   isHologramAtPath?: boolean;
-  /** The final holon where data was put (after potential redirection) */
   pathHolon: string;
-  /** The final lens where data was put (after potential redirection) */
   pathLens: string;
-  /** The final key under which data was put (after potential redirection) */
   pathKey: string;
-  /** Result of any automatic propagation, if it occurred */
   propagationResult?: PropagationResult | null;
-  /** Error message if the put operation failed at some point */
   error?: string;
 }
 
+interface CanWriteResult {
+  canWrite: boolean;
+  reason: string;
+  accessType: string;
+}
+
+interface HoloSphereConfig {
+  appName?: string;
+  appname?: string;
+  privateKey?: Uint8Array | string | null;
+  strict?: boolean;
+  backend?: string;
+  openaiKey?: string | null;
+  nostr?: {
+    peers?: string[];
+    relays?: string[];
+    persistence?: boolean;
+  };
+}
+
 declare class HoloSphere {
-    private appname;
-    private strict;
-    private validator;
-    public gun;
-    private sea;
-    private openai?;
-    private subscriptions;
-
-    /**
-     * Initializes a new instance of the HoloSphere class.
-     * @param {string} appname - The name of the application.
-     * @param {boolean} strict - Whether to enforce strict schema validation.
-     * @param {string|null} openaikey - The OpenAI API key.
-     * @param {object|null} gunInstance - The Gun instance to use.
-     */
-    constructor(appname: string, strict?: boolean, openaikey?: string | null, gunInstance?: any);
-
-    /**
-     * Gets the Gun instance.
-     * @returns {any} - The Gun instance.
-     */
-    getGun(): any;
+    appname: string;
+    config: HoloSphereConfig;
+    client: { publicKey: string };
+    gun: any;
+    subscriptions: Record<string, any>;
+
+    constructor(config: HoloSphereConfig);
+    constructor(appname: string, strict?: boolean, openaikey?: string | null, gunOptions?: any);
 
-    // ================================ SCHEMA FUNCTIONS ================================
+    ready(): Promise<HoloSphere>;
+    getGun(): any;
 
-    /**
-     * Sets the JSON schema for a specific lens.
-     * @param {string} lens - The lens identifier.
-     * @param {object} schema - The JSON schema to set.
-     * @returns {Promise<boolean>} - Resolves when the schema is set.
-     */
+    // Schema
     setSchema(lens: string, schema: object): Promise<boolean>;
+    getSchema(lens: string, options?: { useCache?: boolean; maxCacheAge?: number }): Promise<object | null>;
+    clearSchemaCache(lens?: string | null): boolean;
 
-    /**
-     * Retrieves the JSON schema for a specific lens.
-     * @param {string} lens - The lens identifier.
-     * @returns {Promise<object|null>} - The retrieved schema or null if not found.
-     */
-    getSchema(lens: string): Promise<object | null>;
-
-    // ================================ CONTENT FUNCTIONS ================================
-
-    /**
-     * 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} data - The data to store.
-     * @param {string} [password] - Optional password for private holon.
-     * @param {PutOptions} [options] - Additional options
-     * @returns {Promise<any>} - Returns result object if successful
-     */
+    // Content - v2-compatible signatures
+    put(holon: string, lens: string, data: object, options?: PutOptions): Promise<PutResult>;
     put(holon: string, lens: string, data: object, password?: string | null, options?: PutOptions): Promise<PutResult>;
-
-    /**
-     * Retrieves content from the specified holon and lens.
-     * @param {string} holon - The holon identifier.
-     * @param {string} lens - The lens from which to retrieve content.
-     * @param {string} key - The specific key to retrieve.
-     * @param {string} [password] - Optional password for private holon.
-     * @param {GetOptions} [options] - Additional options
-     * @returns {Promise<any|null>} - The retrieved content or null if not found.
-     */
+    get(holon: string, lens: string): Promise<any | null>;
     get(holon: string, lens: string, key: string, password?: string | null, options?: GetOptions): Promise<any | null>;
-
-    /**
-     * Retrieves a node directly using its soul path
-     * @param {string} soul - The soul path of the node
-     * @returns {Promise<any>} - The retrieved node or null if not found.
-     */
-    getNodeBySoul(soul: string): Promise<any>;
-
-    /**
-     * Propagates data to federated holons
-     * @param {string} holon - The holon identifier
-     * @param {string} lens - The lens identifier
-     * @param {object} data - The data to propagate
-     * @param {PropagationOptions} [options] - Propagation options
-     * @returns {Promise<PropagationResult>} - Result with success count and errors
-     */
-    propagate(holon: string, lens: string, data: object, options?: PropagationOptions): Promise<PropagationResult>;
-
-    /**
-     * Retrieves all content from the specified holon and lens.
-     * @param {string} holon - The holon identifier.
-     * @param {string} lens - The lens from which to retrieve content.
-     * @param {string} [password] - Optional password for private holon.
-     * @returns {Promise<Array<any>>} - The retrieved content.
-     */
     getAll(holon: string, lens: string, password?: string | null): Promise<Array<any>>;
-
-    /**
-     * Deletes a specific key from a given holon and lens.
-     * @param {string} holon - The holon identifier.
-     * @param {string} lens - The lens from which to delete the key.
-     * @param {string} key - The specific key to delete.
-     * @param {string} [password] - Optional password for private holon.
-     * @returns {Promise<boolean>} - Returns true if successful
-     */
+    parse(rawData: any): Promise<object | null>;
     delete(holon: string, lens: string, key: string, password?: string | null): Promise<boolean>;
-
-    /**
-     * Deletes all keys from a given holon and lens.
-     * @param {string} holon - The holon identifier.
-     * @param {string} lens - The lens from which to delete all keys.
-     * @param {string} [password] - Optional password for private holon.
-     * @returns {Promise<boolean>} - Returns true if successful
-     */
     deleteAll(holon: string, lens: string, password?: string | null): Promise<boolean>;
 
-    // ================================ NODE FUNCTIONS ================================
-
-    /**
-     * Stores a specific gun node in a given holon and lens.
-     * @param {string} holon - The holon identifier.
-     * @param {string} lens - The lens under which to store the node.
-     * @param {object} data - The node to store.
-     * @returns {Promise<boolean>} - Returns true if successful
-     */
+    // Node
     putNode(holon: string, lens: string, data: object): Promise<boolean>;
-
-    /**
-     * Retrieves a specific gun node from the specified holon and lens.
-     * @param {string} holon - The holon identifier.
-     * @param {string} lens - The lens identifier.
-     * @param {string} key - The specific key to retrieve.
-     * @returns {Promise<any|null>} - The retrieved node or null if not found.
-     */
     getNode(holon: string, lens: string, key: string): Promise<any | null>;
-
-    /**
-     * Gets a Gun reference to a node by its soul
-     * @param {string} soul - The soul path
-     * @returns {any} - A Gun reference to the node
-     */
     getNodeRef(soul: string): any;
-
-    /**
-     * Deletes a specific gun node from a given holon and lens.
-     * @param {string} holon - The holon identifier.
-     * @param {string} lens - The lens identifier.
-     * @param {string} key - The key of the node to delete.
-     * @returns {Promise<boolean>} - Returns true if successful
-     */
+    getNodeBySoul(soul: string): Promise<any>;
     deleteNode(holon: string, lens: string, key: string): Promise<boolean>;
 
-    // ================================ HOLOGRAM FUNCTIONS ================================
-
-    /**
-     * Creates a soul hologram object for a data item.
-     * @param {string} holon - The holon where the original data is stored.
-     * @param {string} lens - The lens where the original data is stored.
-     * @param {object} data - The data to create a hologram for. Must have an 'id' field.
-     * @returns {Hologram} - A hologram object containing id and soul.
-     */
-    createHologram(holon: string, lens: string, data: { id: string, [key: string]: any }): Hologram;
-
-    /**
-     * Checks if an object is a hologram (has id and soul).
-     * @param {any} data - The data to check.
-     * @returns {boolean} - True if the object is considered a hologram.
-     */
-    isHologram(data: any): data is Hologram;
-
-    /**
-     * Resolves a hologram to its actual data by following its soul path.
-     * @param {Hologram} hologram - The hologram object to resolve.
-     * @param {ResolveHologramOptions} [options] - Options for resolution.
-     * @returns {Promise<object|null>} - The resolved data, null if not found, or the original hologram in case of loops/errors.
-     */
-    resolveHologram(hologram: Hologram, options?: ResolveHologramOptions): Promise<object | null>;
-
-    // ================================ GLOBAL FUNCTIONS ================================
-
-    /**
-     * Stores data in a global (non-holon-specific) table.
-     * @param {string} tableName - 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.
-     * @param {string} [password] - Optional password for private holon.
-     * @returns {Promise<void>}
-     */
+    // Global
     putGlobal(tableName: string, data: object, password?: string | null): Promise<void>;
-
-    /**
-     * Retrieves a specific key from a global table.
-     * @param {string} tableName - The table name to retrieve from.
-     * @param {string} key - The key to retrieve.
-     * @param {string} [password] - Optional password for private holon.
-     * @returns {Promise<any|null>} - The parsed data for the key or null if not found.
-     */
+    writeGlobal(tableName: string, data: object): Promise<void>;
     getGlobal(tableName: string, key: string, password?: string | null): Promise<any | null>;
-
-    /**
-     * Retrieves all data from a global table.
-     * @param {string} tableName - The table name to retrieve data from.
-     * @param {string} [password] - Optional password for private holon.
-     * @returns {Promise<Array<any>>} - The parsed data from the table as an array.
-     */
     getAllGlobal(tableName: string, password?: string | null): Promise<Array<any>>;
-
-    /**
-     * Deletes a specific key from a global table.
-     * @param {string} tableName - The table name to delete from.
-     * @param {string} key - The key to delete.
-     * @param {string} [password] - Optional password for private holon.
-     * @returns {Promise<boolean>} - Returns true if successful
-     */
     deleteGlobal(tableName: string, key: string, password?: string | null): Promise<boolean>;
-
-    /**
-     * Deletes an entire global table.
-     * @param {string} tableName - The table name to delete.
-     * @param {string} [password] - Optional password for private holon.
-     * @returns {Promise<boolean>} - Returns true if successful
-     */
     deleteAllGlobal(tableName: string, password?: string | null): Promise<boolean>;
+    subscribeGlobal(lens: string, key: string | null, callback: (data: any, key?: string) => void, options?: { realtimeOnly?: boolean }): Promise<{ unsubscribe: () => void }>;
+    subscribeGlobal(lens: string, callback: (data: any, key?: string) => void): Promise<{ unsubscribe: () => void }>;
 
-    // ================================ COMPUTE FUNCTIONS ================================
-
-    /**
-     * Computes operations across multiple layers up the hierarchy
-     * @param {string} holon - Starting holon identifier
-     * @param {string} lens - The lens to compute
-     * @param {object} options - Computation options
-     * @param {number} [maxLevels=15] - Maximum levels to compute up
-     * @param {string} [password] - Optional password for private holons
-     * @returns {Promise<Array<any>>} - Computation results
-     */
-    computeHierarchy(holon: string, lens: string, options: object, maxLevels?: number, password?: string | null): Promise<Array<any>>;
+    // Hologram
+    createHologram(holon: string, lens: string, data: { id: string, [key: string]: any }): Hologram;
+    isHologram(data: any): data is Hologram;
+    parseSoulPath(soul: string): { appname: string, holon: string, lens: string, key: string } | null;
+    resolveHologram(hologram: Hologram, options?: ResolveHologramOptions): Promise<ResolvedHologramData | null>;
+    attachHologramMeta<T extends object>(originalData: T, hologramSoul: string): T & ResolvedHologramData;
 
-    /**
-     * Computes operations on content within a holon and lens for one layer up.
-     * @param {string} holon - The holon identifier.
-     * @param {string} lens - The lens to compute.
-     * @param {object|string} options - Computation options or operation name
-     * @param {string} [password] - Optional password for private holons
-     * @returns {Promise<any>} - Computation result
-     */
-    compute(holon: string, lens: string, options: object|string, password?: string | null): Promise<any>;
-
-    /**
-     * Upcasts content to parent holonagons recursively using federation and soul references.
-     * @param {string} holon - The current holon identifier.
-     * @param {string} lens - The lens under which to upcast.
-     * @param {object} content - The content to upcast.
-     * @param {number} [maxLevels=15] - Maximum levels to upcast.
-     * @returns {Promise<object>} - The original content.
-     */
+    // Compute
+    computeHierarchy(holon: string, lens: string, options: object, maxLevels?: number, password?: string | null): Promise<Array<any>>;
+    compute(holon: string, lens: string, options: object | string, password?: string | null): Promise<any>;
+    summarize(history: string): Promise<string>;
     upcast(holon: string, lens: string, content: object, maxLevels?: number): Promise<object>;
-
-    /**
-     * Updates the parent holon 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.
-     */
     updateParent(id: string, report: string): Promise<object>;
+    propagate(holon: string, lens: string, data: object, options?: PropagationOptions): Promise<PropagationResult>;
 
-    // ================================ LOCATION FUNCTIONS ================================
-
-    /**
-     * 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 holon identifier.
-     */
+    // Location
     getHolon(lat: number, lng: number, resolution: number): Promise<string>;
-
-    /**
-     * 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 holon identifiers.
-     */
     getScalespace(lat: number, lng: number): string[];
-
-    /**
-     * Retrieves all containing holonagons at all scales for a given holon.
-     * @param {string} holon - The holon identifier.
-     * @returns {Array<string>} - List of holon identifiers.
-     */
     getHolonScalespace(holon: string): string[];
 
-    // ================================ SUBSCRIPTION FUNCTIONS ================================
-
-    /**
-     * 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.
-     * @returns {Promise<object>} - Subscription object with unsubscribe method
-     */
+    // Subscription
     subscribe(holon: string, lens: string, callback: (data: any, key?: string) => void): Promise<{ unsubscribe: () => void }>;
 
-    // ================================ FEDERATION FUNCTIONS ================================
-
-    /**
-     * Creates a federation relationship between two holons
-     * @param {string} holonId1 - The first holon ID
-     * @param {string} holonId2 - The second holon ID
-     * @param {string} [password1] - Optional password for the first holon
-     * @param {string} [password2] - Optional password for the second holon
-     * @param {boolean} [bidirectional=true] - Whether to set up bidirectional notifications automatically
-     * @param {object} [lensConfig] - Optional lens-specific configuration
-     * @param {string[]} [lensConfig.federate] - List of lenses to federate (default: all)
-     * @param {string[]} [lensConfig.notify] - List of lenses to notify (default: all)
-     * @returns {Promise<boolean>} - True if federation was created successfully
-     */
-    federate(holonId1: string, holonId2: string, password1?: string | null, password2?: string | null, bidirectional?: boolean, lensConfig?: { federate?: string[], notify?: string[] }): Promise<boolean>;
-
-    /**
-     * Subscribes to federation notifications for a holon
-     * @param {string} holonId - The holon ID to subscribe to
-     * @param {string} [password] - Optional password for the holon
-     * @param {function} callback - The callback to execute on notifications
-     * @param {object} [options] - Subscription options
-     * @returns {Promise<object>} - Subscription object with unsubscribe() method
-     */
-    subscribeFederation(holonId: string, password: string | null, callback: (data: any, federatedSpace?: string, lens?: string) => void, options?: { lenses?: string[], throttle?: number }): Promise<{ unsubscribe: () => void, getSubscriptionCount: () => number }>;
-
-    /**
-     * Gets federation info for a holon
-     * @param {string} holonId - The holon ID
-     * @param {string} [password] - Optional password for the holon
-     * @returns {Promise<FederationInfo|null>} - Federation info or null if not found
-     */
-    getFederation(holonId: string, password?: string | null): Promise<FederationInfo | null>;
-
-    /**
-     * Retrieves the lens-specific configuration for a federation link between two holons.
-     * @param {string} holonId - The ID of the source holon.
-     * @param {string} targetHolonId - The ID of the target holon in the federation link.
-     * @param {string} [password] - Optional password for the source holon.
-     * @returns {Promise<{ federate: string[], notify: string[] } | null>} - An object with 'federate' and 'notify' arrays, or null if not found.
-     */
-    getFederatedConfig(holonId: string, targetHolonId: string, password?: string | null): Promise<{ federate: string[], notify: string[] } | null>;
-
-    /**
-     * Removes a federation relationship between holons
-     * @param {string} holonId1 - The first holon ID
-     * @param {string} holonId2 - The second holon ID
-     * @param {string} [password1] - Optional password for the first holon
-     * @param {string} [password2] - Optional password for the second holon
-     * @returns {Promise<boolean>} - True if federation was removed successfully
-     */
+    // Federation - v1 style
+    federate(holonId1: string, holonId2: string, password1?: string | null, password2?: string | null, bidirectional?: boolean, lensConfig?: { inbound?: string[], outbound?: string[] }): Promise<boolean>;
     unfederate(holonId1: string, holonId2: string, password1?: string | null, password2?: string | null): Promise<boolean>;
 
-    /**
-     * Removes a notification relationship between two spaces
-     * @param {string} holonId1 - The space to modify (remove from its notify list)
-     * @param {string} holonId2 - The space to be removed from notifications
-     * @param {string} [password1] - Optional password for the first space
-     * @returns {Promise<boolean>} - True if notification was removed successfully
-     */
-    removeNotify(holonId1: string, holonId2: string, password1?: string | null): Promise<boolean>;
+    // Federation - v2 style
+    federateHolon(sourceHolon: string, targetHolon: string, options?: { lensConfig?: { inbound?: string[]; outbound?: string[] }; partnerName?: string }): Promise<boolean>;
+    unfederateHolon(sourceHolon: string, targetHolon: string): Promise<boolean>;
 
-    /**
-     * Get and aggregate data from federated holons
-     * @param {string} holon - The holon name
-     * @param {string} lens - The lens name
-     * @param {GetFederatedOptions} [options] - Options for retrieval and aggregation
-     * @returns {Promise<Array<any>>} - Combined array of local and federated data
-     */
+    subscribeFederation(holonId: string, password: string | null, callback: (data: any, federatedSpace?: string, lens?: string) => void, options?: { lenses?: string[], throttle?: number }): Promise<{ unsubscribe: () => void, getSubscriptionCount: () => number }>;
+    getFederation(holonId: string, password?: string | null): Promise<FederationInfo | null>;
+    getFederatedConfig(holonId: string, targetHolonId: string, password?: string | null): Promise<{ inbound: string[], outbound: string[] } | null>;
+    removeNotify(holonId1: string, holonId2: string, password1?: string | null): Promise<boolean>;
     getFederated(holon: string, lens: string, options?: GetFederatedOptions): Promise<Array<any>>;
-
-    /**
-     * Tracks a federated message across different chats
-     * @param {string} originalChatId - The ID of the original chat
-     * @param {string} messageId - The ID of the original message
-     * @param {string} federatedChatId - The ID of the federated chat
-     * @param {string} federatedMessageId - The ID of the message in the federated chat
-     * @param {string} [type] - The type of message (e.g., 'quest', 'announcement')
-     * @returns {Promise<void>}
-     */
     federateMessage(originalChatId: string, messageId: string, federatedChatId: string, federatedMessageId: string, type?: string): Promise<void>;
-
-    /**
-     * Gets all federated messages for a given original message
-     * @param {string} originalChatId - The ID of the original chat
-     * @param {string} messageId - The ID of the original message
-     * @returns {Promise<object|null>} - The tracking information for the message
-     */
     getFederatedMessages(originalChatId: string, messageId: string): Promise<object | null>;
-
-    /**
-     * Updates a federated message across all federated chats
-     * @param {string} originalChatId - The ID of the original chat
-     * @param {string} messageId - The ID of the original message
-     * @param {Function} updateCallback - Function to update the message in each chat
-     * @returns {Promise<void>}
-     */
     updateFederatedMessages(originalChatId: string, messageId: string, updateCallback: (chatId: string, messageId: string) => Promise<void>): Promise<void>;
-
-    /**
-     * Resets the federation settings for a holon
-     * @param {string} holonId - The holon ID
-     * @param {string} [password] - Optional password for the holon
-     * @returns {Promise<boolean>} - True if federation was reset successfully
-     */
     resetFederation(holonId: string, password?: string | null): Promise<boolean>;
 
-    // ================================ UTILITY FUNCTIONS ================================
+    // Authorization
+    canWrite(holonId: string, lensName: string, actingAs: string, options?: any): Promise<CanWriteResult>;
+    addAllowedAuthor(pubkey: string): void;
+    removeAllowedAuthor(pubkey: string): void;
+    listAllowedAuthors(): string[];
 
-    /**
-     * Generates a unique ID for data items
-     * @returns {string} A unique ID
-     */
+    // Utility
     generateId(): string;
-
-    /**
-     * Closes the HoloSphere instance and cleans up resources.
-     * @returns {Promise<void>}
-     */
     close(): Promise<void>;
-
-    /**
-     * Configures radisk storage options for GunDB.
-     * @param {object} options - Radisk configuration options
-     * @param {string} [options.file='./radata'] - Directory for radisk storage
-     * @param {boolean} [options.radisk=true] - Whether to enable radisk storage
-     * @param {number} [options.until] - Timestamp until which to keep data
-     * @param {number} [options.retry] - Number of retries for failed operations
-     * @param {number} [options.timeout] - Timeout for operations in milliseconds
-     */
-    configureRadisk(options?: {
-        file?: string;
-        radisk?: boolean;
-        until?: number | null;
-        retry?: number;
-        timeout?: number;
-    }): void;
-
-    /**
-     * Gets radisk storage statistics and information.
-     * @returns {object} Radisk statistics including file path, enabled status, and storage info
-     */
-    getRadiskStats(): {
-        enabled: boolean;
-        filePath: string;
-        retry: number;
-        timeout: number;
-        until: number | null;
-        peers: any[];
-        localStorage: boolean;
-    } | { error: string };
+    getVersion(): string;
+    userName(holonId: string): string;
+    configureRadisk(options?: { file?: string; radisk?: boolean; until?: number | null; retry?: number; timeout?: number }): void;
+    getRadiskStats(): { enabled: boolean; filePath: string; retry: number; timeout: number; until: number | null; peers: any[]; localStorage: boolean } | { error: string };
 }
 
+// Named exports
+export declare const version: string;
+
+export declare const nostrUtils: {
+    generatePrivateKey(): string;
+    getPublicKey(privateKeyHex: string): string;
+    getPublicKeyFromBytes(privateKeyBytes: Uint8Array): string;
+    parseNsecOrHex(input: string): string | null;
+    parseNpubOrHex(input: string): string | null;
+    hexToNpub(hex: string): string;
+    hexToNsec(hex: string): string;
+    npubToHex(npub: string): string;
+    nsecToHex(nsec: string): string;
+    hexToBytes(hex: string): Uint8Array;
+    bytesToHex(bytes: Uint8Array): string;
+    shortenPubKey(pubkey: string, len?: number): string;
+    shortenNpub(npub: string, len?: number): string;
+    generateNonce(): string;
+};
+
+export declare function buildLensPath(appName: string, holonId: string, lens: string): string;
+
+export declare const subscriptions: {
+    createSubscription(client: HoloSphere, path: string, callback: (data: any, key?: string) => void, options?: { realtimeOnly?: boolean; resolveHolograms?: boolean; appname?: string }): { unsubscribe: () => void; stop: () => void };
+};
+
+export declare const registry: {
+    storeInboundCapability(client: HoloSphere, appName: string, holonId: string, capability: any): Promise<{ success: boolean; id?: string; error?: string }>;
+    getInboundCapabilities(client: HoloSphere, appName: string, holonId: string): Promise<any[]>;
+    removeInboundCapability(client: HoloSphere, appName: string, holonId: string, capabilityId: string): Promise<boolean>;
+};
+
+export declare const handshake: {
+    subscribeToFederationDMs(holosphere: HoloSphere, privateKey: any, publicKey: string, handlers: {
+        onRequest?: (request: any, senderPubKey: string) => void;
+        onResponse?: (response: any, senderPubKey: string) => void;
+        onUpdate?: (update: any, senderPubKey: string) => void;
+        onUpdateResponse?: (response: any, senderPubKey: string) => void;
+    }): () => void;
+    initiateFederationHandshake(holosphere: HoloSphere, privateKey: any, params: {
+        partnerPubKey: string;
+        holonId: string;
+        holonName: string;
+        lensConfig?: any;
+        message?: string;
+    }): Promise<{ success: boolean; requestId?: string }>;
+    acceptFederationRequest(holosphere: HoloSphere, privateKey: any, params: {
+        requesterPubKey: string;
+        holonId: string;
+        holonName: string;
+        lensConfig?: any;
+        requestId?: string;
+    }): Promise<{ success: boolean }>;
+    rejectFederationRequest(holosphere: HoloSphere, privateKey: any, params: {
+        requesterPubKey: string;
+        holonId: string;
+        reason?: string;
+        requestId?: string;
+    }): Promise<{ success: boolean }>;
+    processFederationResponse(holosphere: HoloSphere, response: any, senderPubKey: string, options?: {
+        holonId: string;
+        inboundLenses?: string[];
+    }): Promise<{ success: boolean; responderHolonId?: string; error?: string }>;
+    requestFederationUpdate(holosphere: HoloSphere, privateKey: any, params: {
+        partnerPubKey: string;
+        holonId: string;
+        holonName: string;
+        newLensConfig?: any;
+        message?: string;
+    }): Promise<{ success: boolean }>;
+    acceptFederationUpdate(holosphere: HoloSphere, privateKey: any, params: any): Promise<{ success: boolean }>;
+    rejectFederationUpdate(holosphere: HoloSphere, privateKey: any, params: any): Promise<{ success: boolean }>;
+};
+
 export default HoloSphere;
+export { HoloSphere };