holosphere 1.1.19 → 2.0.0-alpha0

package/src/storage/nostr-async.js

@@ -0,0 +1,811 @@
+/**
+ * Nostr Async Utilities
+ * Provides Promise-based wrappers and async patterns for Nostr operations
+ */
+
+/**
+ * Global subscription manager to prevent duplicate subscriptions
+ * Maps: pathPrefix -> subscription object
+ */
+const globalSubscriptions = new Map();
+
+/**
+ * Write data as Nostr event (parameterized replaceable event)
+ * @param {Object} client - NostrClient instance
+ * @param {string} path - Path identifier (encoded in d-tag)
+ * @param {Object} data - Data to store
+ * @param {number} kind - Event kind (default: 30000 for parameterized replaceable)
+ * @returns {Promise<Object>} Published event result
+ */
+export async function nostrPut(client, path, data, kind = 30000) {
+  const dataEvent = {
+    kind,
+    created_at: Math.floor(Date.now() / 1000),
+    tags: [
+      ['d', path], // d-tag for parameterized replaceable events
+    ],
+    content: JSON.stringify(data),
+  };
+
+  const result = await client.publish(dataEvent);
+  return result;
+}
+
+/**
+ * Read data from Nostr (query by d-tag)
+ * LOCAL-FIRST: Checks persistent storage first, never blocks on network
+ * @param {Object} client - NostrClient instance
+ * @param {string} path - Path identifier
+ * @param {number} kind - Event kind (default: 30000)
+ * @param {Object} options - Query options
+ * @param {string[]} options.authors - Array of public keys to query (default: [client.publicKey])
+ * @param {boolean} options.includeAuthor - If true, adds _author field to returned data
+ * @param {boolean} options.skipPersistent - If true, skip persistent storage check (default: false)
+ * @returns {Promise<Object|null>} Data or null if not found
+ */
+export async function nostrGet(client, path, kind = 30000, options = {}) {
+  const timeout = options.timeout !== undefined ? options.timeout : 30000;
+  const authors = options.authors || [client.publicKey];
+
+  // LOCAL-FIRST: Check persistent storage FIRST (never blocks on network)
+  if (!options.skipPersistent && client.persistentGet) {
+    const persistedEvent = await client.persistentGet(path);
+    if (persistedEvent && persistedEvent.content) {
+      try {
+        const data = JSON.parse(persistedEvent.content);
+
+        // Skip deleted items
+        if (data._deleted) {
+          return null;
+        }
+
+        // Optionally include author information
+        if (options.includeAuthor) {
+          data._author = persistedEvent.pubkey;
+        }
+
+        // Trigger background refresh from relays (fire-and-forget)
+        if (client.refreshPathInBackground) {
+          client.refreshPathInBackground(path, kind, { authors, timeout });
+        }
+
+        return data;
+      } catch (error) {
+        // Fall through to relay query if parsing fails
+        console.warn('[nostrGet] Failed to parse persisted event:', error);
+      }
+    }
+  }
+
+  // Fallback to relay query (existing logic)
+  const filter = {
+    kinds: [kind],
+    authors: authors, // Support multiple authors for cross-holosphere queries
+    '#d': [path],
+    limit: authors.length, // Increase limit to get events from all authors
+  };
+
+  const events = await client.query(filter, { timeout });
+
+  if (events.length === 0) {
+    return null;
+  }
+
+  // Get most recent event (across all authors)
+  const event = events.sort((a, b) => b.created_at - a.created_at)[0];
+
+  try {
+    const data = JSON.parse(event.content);
+    // Optionally include author information
+    if (options.includeAuthor) {
+      data._author = event.pubkey;
+    }
+    return data;
+  } catch (error) {
+    console.error('Failed to parse event content:', error);
+    return null;
+  }
+}
+
+/**
+ * Query all events under a path prefix
+ * LOCAL-FIRST: Checks persistent storage first, never blocks on network
+ * @param {Object} client - NostrClient instance
+ * @param {string} pathPrefix - Path prefix to match
+ * @param {number} kind - Event kind (default: 30000)
+ * @param {Object} options - Query options
+ * @param {string[]} options.authors - Array of public keys to query (default: [client.publicKey])
+ * @param {boolean} options.includeAuthor - If true, adds _author field to returned data
+ * @param {boolean} options.skipPersistent - If true, skip persistent storage check (default: false)
+ * @returns {Promise<Array>} Array of data objects
+ */
+export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}) {
+  const timeout = options.timeout !== undefined ? options.timeout : 30000;
+  const limit = options.limit || 1000; // Increased limit to get more events
+  const authors = options.authors || [client.publicKey];
+
+  // LOCAL-FIRST: Check persistent storage FIRST (never blocks on network)
+  if (!options.skipPersistent && client.persistentGetAll) {
+    const persistedEvents = await client.persistentGetAll(pathPrefix);
+    if (persistedEvents.length > 0) {
+      // Parse content and group by d-tag (keep latest only)
+      const byPath = new Map();
+      for (const event of persistedEvents) {
+        if (!event || !event.tags) continue;
+
+        const dTag = event.tags.find(t => t[0] === 'd');
+        if (!dTag || !dTag[1] || !dTag[1].startsWith(pathPrefix)) continue;
+
+        const path = dTag[1];
+        const existing = byPath.get(path);
+
+        if (!existing || event.created_at > existing.created_at) {
+          try {
+            const data = JSON.parse(event.content);
+
+            // Skip deleted items
+            if (data._deleted) continue;
+
+            // Optionally include author information
+            if (options.includeAuthor) {
+              data._author = event.pubkey;
+            }
+            byPath.set(path, { data, created_at: event.created_at });
+          } catch (error) {
+            // Skip invalid events
+          }
+        }
+      }
+
+      // Trigger background refresh from relays (fire-and-forget)
+      if (client.refreshPrefixInBackground) {
+        client.refreshPrefixInBackground(pathPrefix, kind, { authors, timeout, limit });
+      }
+
+      // Return array of data objects
+      return Array.from(byPath.values()).map(item => item.data);
+    }
+  }
+
+  // Fallback to relay query (existing logic)
+  const filter = {
+    kinds: [kind],
+    authors: authors,
+    limit,
+  };
+
+  const events = await client.query(filter, { timeout });
+
+  // Filter by path prefix in application layer
+  const matching = events.filter(event => {
+    const dTag = event.tags.find(t => t[0] === 'd');
+    return dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+  });
+
+  // Parse content and group by d-tag (keep latest only, across all authors)
+  const byPath = new Map();
+  for (const event of matching) {
+    const dTag = event.tags.find(t => t[0] === 'd')[1];
+    const existing = byPath.get(dTag);
+
+    if (!existing || event.created_at > existing.created_at) {
+      try {
+        const data = JSON.parse(event.content);
+
+        // Skip deleted items
+        if (data._deleted) continue;
+
+        // Optionally include author information
+        if (options.includeAuthor) {
+          data._author = event.pubkey;
+        }
+        byPath.set(dTag, { data, created_at: event.created_at });
+      } catch (error) {
+        console.error('Failed to parse event content:', error);
+      }
+    }
+  }
+
+  // Return array of data objects
+  return Array.from(byPath.values()).map(item => item.data);
+}
+
+/**
+ * Query all events under a path prefix (HYBRID MODE - local + relay)
+ * Checks local cache first, then merges with relay data
+ * @param {Object} client - NostrClient instance
+ * @param {string} pathPrefix - Path prefix to match
+ * @param {number} kind - Event kind (default: 30000)
+ * @param {Object} options - Query options
+ * @param {string[]} options.authors - Array of public keys to query (default: [client.publicKey])
+ * @param {boolean} options.includeAuthor - If true, adds _author field to returned data
+ * @returns {Promise<Array>} Array of data objects (merged from local + relay)
+ */
+export async function nostrGetAllHybrid(client, pathPrefix, kind = 30000, options = {}) {
+  const timeout = options.timeout !== undefined ? options.timeout : 30000;
+  const limit = options.limit || 1000;
+  const authors = options.authors || [client.publicKey];
+
+  // Use hybrid query if available
+  const queryMethod = client.queryHybrid || client.query;
+
+  const filter = {
+    kinds: [kind],
+    authors: authors,
+    limit,
+  };
+
+  const events = await queryMethod.call(client, filter, { timeout });
+
+  // Filter by path prefix in application layer
+  const matching = events.filter(event => {
+    const dTag = event.tags.find(t => t[0] === 'd');
+    return dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+  });
+
+  // Parse content and group by d-tag (keep latest only)
+  const byPath = new Map();
+  for (const event of matching) {
+    const dTag = event.tags.find(t => t[0] === 'd')[1];
+    const existing = byPath.get(dTag);
+
+    if (!existing || event.created_at > existing.created_at) {
+      try {
+        const data = JSON.parse(event.content);
+        // Optionally include author information
+        if (options.includeAuthor) {
+          data._author = event.pubkey;
+        }
+        byPath.set(dTag, { data, created_at: event.created_at });
+      } catch (error) {
+        console.error('Failed to parse event content:', error);
+      }
+    }
+  }
+
+  // Return array of data objects
+  return Array.from(byPath.values()).map(item => item.data);
+}
+
+/**
+ * Delete data (publish deletion event - NIP-09)
+ * @param {Object} client - NostrClient instance
+ * @param {string} path - Path identifier
+ * @param {number} kind - Original event kind (default: 30000)
+ * @returns {Promise<Object>} Deletion event result
+ */
+export async function nostrDelete(client, path, kind = 30000) {
+  // Read existing data first
+  const existing = await nostrGet(client, path, kind);
+
+  if (!existing) {
+    return { reason: 'not_found', results: [] };
+  }
+
+  // Create minimal tombstone - just the deleted flag, no original data
+  const tombstone = {
+    _deleted: true,
+    _deletedAt: Date.now()
+  };
+
+  // Publish tombstone as replacement event
+  // This ensures reads will see _deleted flag
+  const result = await nostrPut(client, path, tombstone, kind);
+
+  // Also delete from persistent storage to prevent resurrection on restart
+  if (client.persistentStorage) {
+    try {
+      await client.persistentStorage.delete(path);
+    } catch (e) {
+      // Ignore storage deletion errors
+    }
+  }
+
+  // Clear from memory cache
+  if (client.clearCache) {
+    client.clearCache(path);
+  }
+
+  // Also publish NIP-09 deletion event for relay compliance
+  const coordinate = `${kind}:${client.publicKey}:${path}`;
+  const deletionEvent = {
+    kind: 5, // NIP-09 deletion event
+    created_at: Math.floor(Date.now() / 1000),
+    tags: [
+      ['a', coordinate], // 'a' tag for parameterized replaceable events
+    ],
+    content: '', // Optional deletion reason/note
+  };
+
+  // Publish deletion event (best effort, don't block on failure)
+  try {
+    const publishResult = await client.publish(deletionEvent);
+    console.log(`✅ NIP-09 deletion event published for ${path}:`, {
+      coordinate,
+      relays: publishResult?.relays?.length || 0,
+      successful: publishResult?.successful || []
+    });
+  } catch (error) {
+    console.error(`❌ Failed to publish NIP-09 deletion event for ${path}:`, error.message);
+  }
+
+  return result;
+}
+
+/**
+ * Delete all data with path prefix (publish deletion events - NIP-09)
+ * @param {Object} client - NostrClient instance
+ * @param {string} pathPrefix - Path prefix to delete all items under
+ * @param {number} kind - Original event kind (default: 30000)
+ * @returns {Promise<Object>} Deletion results
+ */
+export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
+  // Query events from relay
+  const filter = {
+    kinds: [kind],
+    authors: [client.publicKey],
+    limit: 1000,
+  };
+
+  const relayEvents = await client.query(filter, { timeout: 30000 });
+
+  // Also get events from persistent storage (may have events not yet synced to relay)
+  let persistentEvents = [];
+  if (client.persistentStorage) {
+    try {
+      persistentEvents = await client.persistentStorage.getAll(pathPrefix);
+    } catch (e) {
+      // Ignore storage read errors
+    }
+  }
+
+  // Merge events from both sources, using d-tag as key
+  const eventsByDTag = new Map();
+
+  // Add relay events
+  for (const event of relayEvents) {
+    const dTag = event.tags?.find(t => t[0] === 'd');
+    if (dTag && dTag[1] && dTag[1].startsWith(pathPrefix)) {
+      eventsByDTag.set(dTag[1], event);
+    }
+  }
+
+  // Add persistent storage events (these might be newer or only exist locally)
+  for (const event of persistentEvents) {
+    const dTag = event.tags?.find(t => t[0] === 'd');
+    if (dTag && dTag[1] && dTag[1].startsWith(pathPrefix)) {
+      const existing = eventsByDTag.get(dTag[1]);
+      // Use the persistent event if it's newer or doesn't exist in relay results
+      if (!existing || event.created_at > existing.created_at) {
+        eventsByDTag.set(dTag[1], event);
+      }
+    }
+  }
+
+  const matching = Array.from(eventsByDTag.values());
+
+  if (matching.length === 0) {
+    return { success: true, count: 0, results: [] };
+  }
+
+  // Publish tombstone events for each matching item
+  const tombstoneResults = [];
+  for (const event of matching) {
+    const dTag = event.tags.find(t => t[0] === 'd')[1];
+
+    try {
+      // Create minimal tombstone - just the deleted flag, no original data
+      const tombstone = {
+        _deleted: true,
+        _deletedAt: Date.now()
+      };
+
+      // Publish tombstone replacement
+      const result = await nostrPut(client, dTag, tombstone, kind);
+      tombstoneResults.push(result);
+
+      // Also delete from persistent storage to prevent resurrection on restart
+      if (client.persistentStorage) {
+        try {
+          await client.persistentStorage.delete(dTag);
+        } catch (e) {
+          // Ignore storage deletion errors
+        }
+      }
+
+      // Clear from memory cache
+      if (client.clearCache) {
+        client.clearCache(dTag);
+      }
+    } catch (error) {
+      console.error(`Failed to delete item ${dTag}:`, error);
+    }
+  }
+
+  // Collect all coordinates for NIP-09 deletion event
+  const coordinates = matching.map(event => {
+    const dTag = event.tags.find(t => t[0] === 'd')[1];
+    return `${kind}:${client.publicKey}:${dTag}`;
+  });
+
+  // Publish a single kind 5 deletion event with all coordinates
+  // This is for relay compliance (best effort)
+  try {
+    const deletionEvent = {
+      kind: 5, // NIP-09 deletion event
+      created_at: Math.floor(Date.now() / 1000),
+      tags: coordinates.map(coord => ['a', coord]),
+      content: '', // Optional deletion reason/note
+    };
+
+    const publishResult = await client.publish(deletionEvent);
+    console.log(`✅ NIP-09 bulk deletion event published for ${pathPrefix}:`, {
+      itemsDeleted: matching.length,
+      coordinates: coordinates.length,
+      relays: publishResult?.relays?.length || 0,
+      successful: publishResult?.successful || []
+    });
+  } catch (error) {
+    console.error(`❌ Failed to publish NIP-09 bulk deletion event for ${pathPrefix}:`, error.message);
+  }
+
+  return {
+    success: true,
+    count: matching.length,
+    results: tombstoneResults,
+  };
+}
+
+/**
+ * Subscribe to path changes
+ * @param {Object} client - NostrClient instance
+ * @param {string} path - Path to subscribe to
+ * @param {Function} callback - Callback function (data, event) => void
+ * @param {Object} options - Subscription options
+ * @returns {Object} Subscription object with unsubscribe method
+ */
+export function nostrSubscribe(client, path, callback, options = {}) {
+  const kind = options.kind || 30000;
+  const includeInitial = options.includeInitial !== false;
+
+  const filter = {
+    kinds: [kind],
+    authors: [client.publicKey], // Filter by our public key
+    '#d': [path],
+    limit: 10, // Limit results for single item subscription
+  };
+
+  let initialLoadComplete = false;
+
+  const subscription = client.subscribe(
+    filter,
+    (event) => {
+      // Verify event is from our public key (relay may not respect author filter)
+      if (event.pubkey !== client.publicKey) {
+        console.warn('[nostrSubscribe] Rejecting event from different author:', {
+          expected: client.publicKey,
+          received: event.pubkey,
+          eventId: event.id
+        });
+        return;
+      }
+
+      try {
+        const data = JSON.parse(event.content);
+        callback(data, event);
+      } catch (error) {
+        console.error('Failed to parse event in subscription:', error);
+      }
+    },
+    {
+      onEOSE: () => {
+        initialLoadComplete = true;
+      },
+    }
+  );
+
+  return subscription;
+}
+
+/**
+ * Subscribe to path prefix (multiple paths)
+ *
+ * Subscribes to data events and uses Page Visibility API to refresh when tab becomes visible.
+ * Note: Nostr relays do not broadcast replaceable event updates to active subscriptions.
+ *
+ * @param {Object} client - NostrClient instance
+ * @param {string} pathPrefix - Path prefix to match
+ * @param {Function} callback - Callback function (data, path, event) => void
+ * @param {Object} options - Subscription options
+ * @returns {Promise<Object>} Subscription object with unsubscribe method
+ */
+export async function nostrSubscribeMany(client, pathPrefix, callback, options = {}) {
+  const kind = options.kind || 30000;
+
+  // Create unique key for this subscription
+  const subscriptionKey = `${client.publicKey}:${kind}:${pathPrefix}`;
+
+  // Check if we already have an active subscription for this path
+  const existingSub = globalSubscriptions.get(subscriptionKey);
+  if (existingSub) {
+    // Register this callback with the existing subscription
+    existingSub.callbacks.push(callback);
+
+    // Return a wrapper that removes only this callback on unsubscribe
+    return {
+      unsubscribe: () => {
+        const idx = existingSub.callbacks.indexOf(callback);
+        if (idx > -1) {
+          existingSub.callbacks.splice(idx, 1);
+        }
+
+        // If no more callbacks, unsubscribe the whole thing
+        if (existingSub.callbacks.length === 0) {
+          existingSub.actualSubscription.unsubscribe();
+          globalSubscriptions.delete(subscriptionKey);
+        }
+      }
+    };
+  }
+
+  const seenEventIds = new Set(); // Track event IDs to prevent duplicate callbacks
+  const callbacks = [callback]; // Array of callbacks to notify
+
+  // Track rejected events for metrics
+  let rejectedCount = 0;
+  let acceptedCount = 0;
+  let lastLogTime = Date.now();
+  const LOG_INTERVAL = 10000; // Log summary every 10 seconds
+
+  // Handler for data events (kind 30000)
+  const handleDataEvent = (event) => {
+    // Skip duplicates
+    if (seenEventIds.has(event.id)) {
+      return;
+    }
+    seenEventIds.add(event.id);
+
+    // Check if event is from a different author (relay not respecting filter)
+    if (event.pubkey !== client.publicKey) {
+      rejectedCount++;
+
+      // Only log periodically to avoid spam
+      const now = Date.now();
+      if (now - lastLogTime > LOG_INTERVAL) {
+        console.warn('[nostrSubscribeMany] ⚠️ Relay not respecting authors filter!', {
+          rejectedCount,
+          acceptedCount,
+          expected: client.publicKey,
+          message: 'Consider using a different relay or implementing private relay'
+        });
+        lastLogTime = now;
+      }
+      return; // Skip events from other authors
+    }
+
+    // Extract d-tag
+    const dTagArray = event.tags.find(t => t[0] === 'd');
+    const dTag = dTagArray?.[1];
+
+    // Client-side prefix filter
+    if (dTag && dTag.startsWith(pathPrefix)) {
+      acceptedCount++;
+      try {
+        const data = JSON.parse(event.content);
+        // Notify all registered callbacks
+        for (const cb of callbacks) {
+          cb(data, dTag, event);
+        }
+      } catch (error) {
+        console.error('[nostrSubscribeMany] Failed to parse event:', error);
+      }
+    }
+  };
+
+  // Subscribe to data events (kind 30000) for initial load
+  // Use 'since' to only get events from subscription time onward for real-time updates
+  const subscriptionStartTime = Math.floor(Date.now() / 1000);
+  const dataFilter = {
+    kinds: [kind],
+    authors: [client.publicKey],
+    since: subscriptionStartTime  // Only get new events after subscription
+  };
+  const dataSubscription = await client.subscribe(dataFilter, handleDataEvent);
+
+  // Use Page Visibility API to refresh when tab becomes visible
+  let isDocumentHidden = typeof document !== 'undefined' && document.hidden;
+  let lastVisibilityCheck = subscriptionStartTime;
+
+  const handleVisibilityChange = async () => {
+    if (typeof document === 'undefined') return;
+
+    const wasHidden = isDocumentHidden;
+    isDocumentHidden = document.hidden;
+
+    // Tab became visible - only check for new events since we were hidden
+    if (wasHidden && !isDocumentHidden) {
+      const now = Math.floor(Date.now() / 1000);
+      try {
+        const visibilityFilter = {
+          ...dataFilter,
+          since: lastVisibilityCheck,  // Only events since last check
+          until: now
+        };
+        const events = await client.query(visibilityFilter, { timeout: 30000 });
+
+        for (const event of events) {
+          handleDataEvent(event);
+        }
+        lastVisibilityCheck = now;
+      } catch (error) {
+        // Silently handle visibility refresh errors
+      }
+    }
+  };
+
+  // Only add listener in browser environment
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+  }
+
+  // Store subscription info for reuse
+  const actualSubscription = {
+    unsubscribe: () => {
+      if (dataSubscription && dataSubscription.unsubscribe) {
+        dataSubscription.unsubscribe();
+      }
+      if (typeof document !== 'undefined') {
+        document.removeEventListener('visibilitychange', handleVisibilityChange);
+      }
+      globalSubscriptions.delete(subscriptionKey);
+    }
+  };
+
+  const subscriptionInfo = {
+    callbacks,
+    actualSubscription
+  };
+
+  globalSubscriptions.set(subscriptionKey, subscriptionInfo);
+
+  return actualSubscription;
+}
+
+/**
+ * Update data (merge with existing)
+ * @param {Object} client - NostrClient instance
+ * @param {string} path - Path identifier
+ * @param {Object} updates - Fields to update
+ * @param {number} kind - Event kind (default: 30000)
+ * @returns {Promise<Object>} Updated event result
+ */
+export async function nostrUpdate(client, path, updates, kind = 30000) {
+  // Read existing data
+  const existing = await nostrGet(client, path, kind);
+
+  if (!existing) {
+    throw new Error(`No data found at path: ${path}`);
+  }
+
+  // Merge updates
+  const merged = { ...existing, ...updates };
+
+  // Publish updated event
+  return nostrPut(client, path, merged, kind);
+}
+
+/**
+ * Batch read multiple paths
+ * @param {Object} client - NostrClient instance
+ * @param {string[]} paths - Array of paths
+ * @param {number} kind - Event kind (default: 30000)
+ * @returns {Promise<Object>} Object mapping paths to data
+ */
+export async function nostrBatchGet(client, paths, kind = 30000) {
+  const filter = {
+    kinds: [kind],
+    '#d': paths,
+    limit: paths.length,
+  };
+
+  const events = await client.query(filter);
+
+  // Group by d-tag (keep latest only)
+  const byPath = new Map();
+  for (const event of events) {
+    const dTag = event.tags.find(t => t[0] === 'd');
+    if (!dTag || !dTag[1]) continue;
+
+    const path = dTag[1];
+    const existing = byPath.get(path);
+
+    if (!existing || event.created_at > existing.created_at) {
+      try {
+        const data = JSON.parse(event.content);
+        byPath.set(path, data);
+      } catch (error) {
+        console.error('Failed to parse event content:', error);
+      }
+    }
+  }
+
+  // Return object mapping paths to data
+  const result = {};
+  for (const path of paths) {
+    result[path] = byPath.get(path) || null;
+  }
+
+  return result;
+}
+
+/**
+ * Batch write multiple paths
+ * @param {Object} client - NostrClient instance
+ * @param {Object} pathDataMap - Object mapping paths to data
+ * @param {number} kind - Event kind (default: 30000)
+ * @returns {Promise<Array>} Array of publish results
+ */
+export async function nostrBatchPut(client, pathDataMap, kind = 30000) {
+  const promises = Object.entries(pathDataMap).map(([path, data]) =>
+    nostrPut(client, path, data, kind)
+  );
+
+  return Promise.all(promises);
+}
+
+/**
+ * Retry operation with exponential backoff
+ * @param {Function} operation - Async function to retry
+ * @param {number} maxRetries - Max retry attempts (default: 3)
+ * @param {number} baseDelay - Base delay in ms (default: 100ms)
+ * @returns {Promise<any>} Promise resolving to operation result
+ */
+export async function nostrRetry(operation, maxRetries = 3, baseDelay = 100) {
+  let lastError;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxRetries) {
+        const delay = baseDelay * Math.pow(2, attempt);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Wait for specific condition on data
+ * @param {Object} client - NostrClient instance
+ * @param {string} path - Path to watch
+ * @param {Function} predicate - Condition function (data) => boolean
+ * @param {number} timeout - Timeout in ms (default: 5000ms)
+ * @returns {Promise<any>} Promise resolving when condition is met
+ */
+export async function nostrWaitFor(client, path, predicate, timeout = 5000) {
+  return new Promise((resolve, reject) => {
+    let timeoutId;
+    let subscription;
+
+    const cleanup = () => {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (subscription) subscription.unsubscribe();
+    };
+
+    subscription = nostrSubscribe(client, path, (data) => {
+      if (predicate(data)) {
+        cleanup();
+        resolve(data);
+      }
+    });
+
+    timeoutId = setTimeout(() => {
+      cleanup();
+      reject(new Error('Timeout waiting for condition'));
+    }, timeout);
+  });
+}