holosphere 1.1.20 → 2.0.0-alpha0

package/src/storage/nostr-client.js

@@ -0,0 +1,939 @@
+/**
+ * Nostr Client - SimplePool wrapper for relay management
+ * Provides connection pooling and relay management
+ */
+
+import { SimplePool, finalizeEvent, getPublicKey } from 'nostr-tools';
+import { OutboxQueue } from './outbox-queue.js';
+import { SyncService } from './sync-service.js';
+
+// Lazy-load WebSocket polyfill for Node.js environment
+let webSocketPolyfillPromise = null;
+function ensureWebSocket() {
+  if (typeof globalThis.WebSocket !== 'undefined') {
+    return Promise.resolve();
+  }
+
+  if (!webSocketPolyfillPromise) {
+    webSocketPolyfillPromise = (async () => {
+      try {
+        const { default: WebSocket } = await import('ws');
+        globalThis.WebSocket = WebSocket;
+      } catch (e) {
+        // WebSocket polyfill not available, will use mock pool
+      }
+    })();
+  }
+
+  return webSocketPolyfillPromise;
+}
+import { createPersistentStorage } from './persistent-storage.js';
+
+/**
+ * NostrClient - Manages connections to Nostr relays
+ */
+export class NostrClient {
+  /**
+   * @param {Object} config - Configuration options
+   * @param {string[]} config.relays - Array of relay URLs
+   * @param {string} config.privateKey - Private key for signing (hex format)
+   * @param {boolean} config.enableReconnect - Auto-reconnect on disconnect (default: true)
+   * @param {boolean} config.enablePing - Auto-ping relays (default: true)
+   * @param {string} config.appName - Application name for storage namespace
+   * @param {boolean} config.persistence - Enable persistent storage (default: true)
+   */
+  constructor(config = {}) {
+    if (config.relays && !Array.isArray(config.relays)) {
+      throw new Error('Relays must be an array');
+    }
+
+    this.relays = config.relays || [];
+
+    // Generate or use provided private key
+    // IMPORTANT: If you want keys to persist across restarts, you MUST provide
+    // a privateKey in config. Otherwise, a new key is generated each time.
+    this.privateKey = config.privateKey || this._generatePrivateKey();
+    this.publicKey = getPublicKey(this.privateKey);
+    this.config = config;
+
+    this._subscriptions = new Map();
+    this._eventCache = new Map(); // In-memory cache for recent events
+    this.persistentStorage = null;
+
+    // Initialize pool and storage asynchronously
+    this._initReady = this._initialize();
+  }
+
+  /**
+   * Initialize WebSocket polyfill and pool
+   * @private
+   */
+  async _initialize() {
+    // Ensure WebSocket is available before initializing pool
+    await ensureWebSocket();
+
+    // Initialize SimplePool with options (only if relays exist)
+    if (this.relays.length > 0) {
+      this.pool = new SimplePool({
+        enableReconnect: this.config.enableReconnect !== false,
+        enablePing: this.config.enablePing !== false,
+      });
+    } else {
+      // Mock pool for testing - returns mock promise that resolves immediately
+      this.pool = {
+        publish: (relays, event) => [Promise.resolve()],
+        querySync: (relays, filter, options) => Promise.resolve([]),
+        subscribeMany: (relays, filters, opts) => ({ close: () => {} }),
+        close: (relays) => {},
+      };
+    }
+
+    // Initialize persistent storage
+    await this._initPersistentStorage();
+  }
+
+  /**
+   * Initialize persistent storage
+   * @private
+   */
+  async _initPersistentStorage() {
+    // Only enable persistence if explicitly requested or radisk is true
+    if (this.config.persistence !== false && (this.config.radisk || this.config.appName)) {
+      try {
+        const namespace = this.config.appName || 'holosphere_default';
+        this.persistentStorage = await createPersistentStorage(namespace, {
+          dataDir: this.config.dataDir
+        });
+
+        // Load cached events from persistent storage
+        await this._loadFromPersistentStorage();
+
+        // Initialize outbox queue for guaranteed delivery
+        this.outboxQueue = new OutboxQueue(this.persistentStorage, {
+          maxRetries: this.config.maxRetries || 5,
+          baseDelay: this.config.retryBaseDelay || 1000,
+          maxDelay: this.config.retryMaxDelay || 60000,
+          failedTTL: this.config.failedTTL || 24 * 60 * 60 * 1000, // 24 hours
+        });
+
+        // Start background sync service
+        if (this.config.backgroundSync !== false) {
+          this.syncService = new SyncService(this, {
+            interval: this.config.syncInterval || 10000, // 10 seconds
+            autoStart: true,
+          });
+        }
+      } catch (error) {
+        console.warn('Failed to initialize persistent storage:', error);
+        // Continue without persistence
+      }
+    }
+  }
+
+  /**
+   * Load events from persistent storage into cache
+   * @private
+   */
+  async _loadFromPersistentStorage() {
+    if (!this.persistentStorage) return;
+
+    try {
+      // Load all events (excluding outbox queue entries)
+      const events = await this.persistentStorage.getAll('');
+      for (const event of events) {
+        // Skip outbox queue entries
+        if (event && event.id && !event.status) {
+          // Add to cache
+          this._cacheEventSync(event);
+        }
+      }
+    } catch (error) {
+      console.warn('Failed to load from persistent storage:', error);
+    }
+  }
+
+  /**
+   * Get a single event from persistent storage by path (d-tag)
+   * @param {string} path - The d-tag path to look up
+   * @returns {Promise<Object|null>} The event or null if not found
+   */
+  async persistentGet(path) {
+    await this._initReady;
+    if (!this.persistentStorage) return null;
+    try {
+      const event = await this.persistentStorage.get(path);
+      return event || null;
+    } catch (error) {
+      console.warn('[nostr] Persistent storage read failed:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Get all events from persistent storage matching a prefix
+   * @param {string} prefix - The path prefix to match
+   * @returns {Promise<Array>} Array of events
+   */
+  async persistentGetAll(prefix) {
+    await this._initReady;
+    if (!this.persistentStorage) return [];
+    try {
+      const events = await this.persistentStorage.getAll(prefix);
+      // Filter out outbox queue entries and null values
+      return events.filter(e => e && e.id && !e.status);
+    } catch (error) {
+      console.warn('[nostr] Persistent storage read failed:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Generate random private key
+   * @private
+   */
+  _generatePrivateKey() {
+    const bytes = new Uint8Array(32);
+    if (typeof window !== 'undefined' && window.crypto) {
+      window.crypto.getRandomValues(bytes);
+    } else {
+      // Node.js - use dynamic import
+      try {
+        // Use crypto.randomFillSync if available
+        const crypto = globalThis.crypto || global.crypto;
+        if (crypto && crypto.getRandomValues) {
+          crypto.getRandomValues(bytes);
+        } else {
+          // Fallback to Math.random (less secure, but works in testing)
+          for (let i = 0; i < 32; i++) {
+            bytes[i] = Math.floor(Math.random() * 256);
+          }
+        }
+      } catch (e) {
+        // Fallback to Math.random
+        for (let i = 0; i < 32; i++) {
+          bytes[i] = Math.floor(Math.random() * 256);
+        }
+      }
+    }
+    return Array.from(bytes)
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  /**
+   * Publish event to relays
+   * @param {Object} event - Unsigned event object
+   * @param {Object} options - Publish options
+   * @param {boolean} options.waitForRelays - Wait for relay confirmation (default: false for speed)
+   * @returns {Promise<Object>} Signed event with relay publish results
+   */
+  async publish(event, options = {}) {
+    // Ensure initialization is complete
+    await this._initReady;
+
+    const waitForRelays = options.waitForRelays || false;
+
+    // Sign the event
+    const signedEvent = finalizeEvent(event, this.privateKey);
+
+    // 1. Cache the event locally first (this makes reads instant)
+    await this._cacheEvent(signedEvent);
+
+    // 2. Enqueue for guaranteed delivery (if outbox queue available)
+    if (this.outboxQueue) {
+      await this.outboxQueue.enqueue(signedEvent, this.relays);
+    }
+
+    // 3. Publish to relays
+    if (waitForRelays) {
+      // Wait for relay confirmation if explicitly requested
+      const deliveryResult = await this._attemptDelivery(signedEvent, this.relays);
+
+      return {
+        event: signedEvent,
+        results: deliveryResult.results,
+        queued: !!this.outboxQueue,
+      };
+    } else {
+      // Fire and forget - publish in background, return immediately
+      this._attemptDelivery(signedEvent, this.relays).catch(err => {
+        console.warn('[nostr] Immediate delivery failed, queued for retry:', err.message);
+      });
+
+      // Return immediately (data is in local cache and queued for delivery)
+      return {
+        event: signedEvent,
+        results: [],
+        queued: !!this.outboxQueue,
+      };
+    }
+  }
+
+  /**
+   * Attempt to deliver event to relays
+   * Updates outbox queue with delivery status
+   * @param {Object} event - Signed event to deliver
+   * @param {string[]} relays - Target relay URLs
+   * @returns {Promise<Object>} Delivery result with successful/failed relays
+   */
+  async _attemptDelivery(event, relays) {
+    const results = await Promise.allSettled(
+      this.pool.publish(relays, event)
+    );
+
+    const successful = [];
+    const failed = [];
+    const formattedResults = [];
+
+    results.forEach((r, i) => {
+      formattedResults.push({
+        relay: relays[i],
+        status: r.status,
+        value: r.value,
+        reason: r.reason,
+      });
+
+      if (r.status === 'fulfilled') {
+        successful.push(relays[i]);
+      } else {
+        failed.push(relays[i]);
+      }
+    });
+
+    // Update outbox queue with delivery status
+    if (this.outboxQueue) {
+      await this.outboxQueue.markSent(event.id, successful);
+    }
+
+    // Log failures for debugging
+    if (failed.length > 0) {
+      const reasons = results
+        .filter(r => r.status === 'rejected')
+        .map(f => f.reason?.message || f.reason || 'unknown')
+        .join(', ');
+      console.warn(`[nostr] ${failed.length}/${relays.length} relays failed for ${event.id.slice(0, 8)}: ${reasons}`);
+    }
+
+    return { successful, failed, results: formattedResults };
+  }
+
+  /**
+   * Query events from relays
+   * @param {Object} filter - Nostr filter object
+   * @param {Object} options - Query options
+   * @param {number} options.timeout - Query timeout in ms (default: 30000, set to 0 for no timeout)
+   * @param {boolean} options.localFirst - Return local cache immediately, refresh in background (default: true)
+   * @returns {Promise<Array>} Array of events
+   */
+  async query(filter, options = {}) {
+    // Ensure initialization is complete
+    await this._initReady;
+
+    const timeout = options.timeout !== undefined ? options.timeout : 30000;
+    const localFirst = options.localFirst !== false; // Default to true for speed
+
+    // If no relays, query from cache only
+    if (this.relays.length === 0) {
+      const matchingEvents = this._getMatchingCachedEvents(filter);
+      return matchingEvents;
+    }
+
+    // Check d-tag cache first for single-item queries (most common case)
+    // This ensures recently written data is returned immediately
+    if (filter['#d'] && filter['#d'].length === 1 && filter.kinds && filter.kinds.length === 1) {
+      const dTagKey = `d:${filter.kinds[0]}:${filter['#d'][0]}`;
+      const dTagCached = this._eventCache.get(dTagKey);
+      if (dTagCached && Date.now() - dTagCached.timestamp < 5000) {
+        return dTagCached.events;
+      }
+    }
+
+    const cacheKey = JSON.stringify(filter);
+    const cached = this._eventCache.get(cacheKey);
+
+    // Return fresh cache immediately
+    if (cached && Date.now() - cached.timestamp < 5000) {
+      return cached.events;
+    }
+
+    // If we have stale cache and localFirst is enabled, return it immediately
+    // and refresh in background
+    if (localFirst && cached) {
+      // Refresh cache in background
+      this._refreshCacheInBackground(filter, cacheKey, timeout);
+      return cached.events;
+    }
+
+    // No cache available or localFirst disabled - must query relays
+    return this._queryRelaysAndCache(filter, cacheKey, timeout);
+  }
+
+  /**
+   * Query relays and update cache
+   * @private
+   */
+  async _queryRelaysAndCache(filter, cacheKey, timeout) {
+    let events = await this.pool.querySync(this.relays, filter, { timeout });
+
+    // CRITICAL: Filter out events from other authors (relay may not respect filter)
+    if (filter.authors && filter.authors.length > 0) {
+      events = events.filter(event => filter.authors.includes(event.pubkey));
+    }
+
+    // Cache results
+    this._eventCache.set(cacheKey, {
+      events,
+      timestamp: Date.now(),
+    });
+
+    // Limit cache size
+    if (this._eventCache.size > 100) {
+      const firstKey = this._eventCache.keys().next().value;
+      this._eventCache.delete(firstKey);
+    }
+
+    return events;
+  }
+
+  /**
+   * Refresh cache in background (fire and forget)
+   * @private
+   */
+  _refreshCacheInBackground(filter, cacheKey, timeout) {
+    this._queryRelaysAndCache(filter, cacheKey, timeout).catch(err => {
+      // Silently ignore background refresh errors - we have stale cache as fallback
+      console.debug('[nostr] Background cache refresh failed:', err.message);
+    });
+  }
+
+  /**
+   * Refresh a single path from relays in the background
+   * Used for persistent-first reads to update local data
+   * @param {string} path - The d-tag path to refresh
+   * @param {number} kind - Event kind (default: 30000)
+   * @param {Object} options - Query options
+   */
+  refreshPathInBackground(path, kind = 30000, options = {}) {
+    this._doBackgroundPathRefresh(path, kind, options).catch(err => {
+      console.debug('[nostr] Background path refresh failed:', err.message);
+    });
+  }
+
+  /**
+   * Internal method to refresh a path from relays
+   * @private
+   */
+  async _doBackgroundPathRefresh(path, kind, options) {
+    if (this.relays.length === 0) return;
+
+    const filter = {
+      kinds: [kind],
+      authors: options.authors || [this.publicKey],
+      '#d': [path],
+      limit: 1,
+    };
+
+    const timeout = options.timeout || 30000;
+    const events = await this.pool.querySync(this.relays, filter, { timeout });
+
+    // Filter by author (relays may not respect filter)
+    const authorFiltered = events.filter(e =>
+      (options.authors || [this.publicKey]).includes(e.pubkey)
+    );
+
+    if (authorFiltered.length > 0) {
+      // Update cache and persistent storage
+      await this._cacheEvent(authorFiltered[0]);
+    }
+  }
+
+  /**
+   * Refresh all paths with a prefix from relays in the background
+   * Used for persistent-first collection reads
+   * @param {string} prefix - The d-tag prefix to refresh
+   * @param {number} kind - Event kind (default: 30000)
+   * @param {Object} options - Query options
+   */
+  refreshPrefixInBackground(prefix, kind = 30000, options = {}) {
+    this._doBackgroundPrefixRefresh(prefix, kind, options).catch(err => {
+      console.debug('[nostr] Background prefix refresh failed:', err.message);
+    });
+  }
+
+  /**
+   * Internal method to refresh a prefix from relays
+   * @private
+   */
+  async _doBackgroundPrefixRefresh(prefix, kind, options) {
+    if (this.relays.length === 0) return;
+
+    // Query with wildcard-ish filter (relays handle d-tag prefix matching)
+    const filter = {
+      kinds: [kind],
+      authors: options.authors || [this.publicKey],
+      limit: options.limit || 1000,
+    };
+
+    const timeout = options.timeout || 30000;
+    let events = await this.pool.querySync(this.relays, filter, { timeout });
+
+    // Filter by author
+    events = events.filter(e =>
+      (options.authors || [this.publicKey]).includes(e.pubkey)
+    );
+
+    // Filter by d-tag prefix (client-side since relays don't support prefix matching)
+    events = events.filter(e => {
+      const dTag = e.tags.find(t => t[0] === 'd');
+      return dTag && dTag[1] && dTag[1].startsWith(prefix);
+    });
+
+    // Update cache and persistent storage for each event
+    for (const event of events) {
+      await this._cacheEvent(event);
+    }
+  }
+
+  /**
+   * Hybrid query: Check local cache first, then query relays for missing data
+   * Merges local and relay results, preferring newer events
+   * @param {Object} filter - Nostr filter object
+   * @param {Object} options - Query options
+   * @param {number} options.timeout - Query timeout in ms (default: 30000)
+   * @returns {Promise<Array>} Array of events (merged from local + relay)
+   */
+  async queryHybrid(filter, options = {}) {
+    // Ensure initialization is complete
+    await this._initReady;
+
+    const timeout = options.timeout !== undefined ? options.timeout : 30000;
+
+    // Step 1: Get events from local cache
+    const localEvents = this._getMatchingCachedEvents(filter);
+
+    // If no relays configured, return local only
+    if (this.relays.length === 0) {
+      return localEvents;
+    }
+
+    // Step 2: Query relays
+    let relayEvents = [];
+    try {
+      relayEvents = await this.pool.querySync(this.relays, filter, { timeout });
+
+      // Filter out events from other authors
+      if (filter.authors && filter.authors.length > 0) {
+        relayEvents = relayEvents.filter(event => filter.authors.includes(event.pubkey));
+      }
+    } catch (error) {
+      console.warn('Relay query failed, using local cache only:', error.message);
+    }
+
+    // Step 3: Merge results (prefer newer events for replaceable events)
+    const merged = new Map();
+
+    // Add local events first
+    for (const event of localEvents) {
+      const key = this._getEventKey(event);
+      merged.set(key, event);
+    }
+
+    // Add or update with relay events (relay events are authoritative)
+    for (const event of relayEvents) {
+      const key = this._getEventKey(event);
+      const existing = merged.get(key);
+
+      // For replaceable events, prefer newer
+      if (event.kind >= 30000 && event.kind < 40000 && existing) {
+        if (event.created_at >= existing.created_at) {
+          merged.set(key, event);
+        }
+      } else {
+        // For non-replaceable or if no existing, just add
+        merged.set(key, event);
+      }
+    }
+
+    const result = Array.from(merged.values());
+
+    // Cache the merged results
+    const cacheKey = JSON.stringify(filter);
+    this._eventCache.set(cacheKey, {
+      events: result,
+      timestamp: Date.now(),
+    });
+
+    return result;
+  }
+
+  /**
+   * Get unique key for event (for merging)
+   * @private
+   */
+  _getEventKey(event) {
+    // For replaceable events with d-tag, use kind:dtag
+    if (event.kind >= 30000 && event.kind < 40000) {
+      const dTag = event.tags.find(t => t[0] === 'd');
+      if (dTag && dTag[1]) {
+        return `${event.kind}:${dTag[1]}`;
+      }
+    }
+    // Otherwise use event id
+    return event.id;
+  }
+
+  /**
+   * Subscribe to events
+   * @param {Object} filter - Nostr filter object
+   * @param {Function} onEvent - Callback for each event
+   * @param {Object} options - Subscription options
+   * @returns {Object} Subscription object with unsubscribe method
+   */
+  async subscribe(filter, onEvent, options = {}) {
+    // Ensure initialization is complete
+    await this._initReady;
+
+    const subId = `sub-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+    // If no relays, check cache for matching events and trigger callbacks
+    if (this.relays.length === 0) {
+      // Trigger with cached events that match the filter
+      const matchingEvents = this._getMatchingCachedEvents(filter);
+
+      // Create a mock subscription that watches for new cache entries
+      const mockSub = {
+        filter,
+        onEvent,
+        active: true
+      };
+
+      this._subscriptions.set(subId, mockSub);
+
+      // Trigger callbacks asynchronously to mimic real subscription behavior
+      // Check active flag to avoid triggering if unsubscribed immediately
+      setTimeout(() => {
+        if (mockSub.active) {
+          matchingEvents.forEach(event => onEvent(event));
+          if (options.onEOSE) options.onEOSE();
+        }
+      }, 10);
+
+      return {
+        id: subId,
+        unsubscribe: () => {
+          mockSub.active = false;
+          this._subscriptions.delete(subId);
+          // Clear the subscription's onEvent to prevent any further calls
+          mockSub.onEvent = () => {};
+          // Note: active flag is checked before triggering callbacks
+        },
+      };
+    }
+
+    const sub = this.pool.subscribeMany(
+      this.relays,
+      [filter],
+      {
+        onevent: (event) => {
+          // CRITICAL: Filter out events from other authors immediately
+          // Many relays don't respect the authors filter, so we must do it client-side
+          if (filter.authors && filter.authors.length > 0) {
+            if (!filter.authors.includes(event.pubkey)) {
+              // Silently reject events from other authors
+              return;
+            }
+          }
+
+          this._cacheEvent(event);
+          onEvent(event);
+        },
+        oneose: () => {
+          if (options.onEOSE) options.onEOSE();
+        },
+      }
+    );
+
+    this._subscriptions.set(subId, sub);
+
+    return {
+      id: subId,
+      unsubscribe: () => {
+        if (sub.close) sub.close();
+        this._subscriptions.delete(subId);
+      },
+    };
+  }
+
+  /**
+   * Cache event in memory (synchronous version for loading)
+   * @private
+   */
+  _cacheEventSync(event) {
+    const key = event.id;
+    this._eventCache.set(key, {
+      events: [event],
+      timestamp: Date.now(),
+    });
+
+    // For replaceable events (kind 30000-39999), also cache by d-tag
+    if (event.kind >= 30000 && event.kind < 40000) {
+      const dTag = event.tags.find(t => t[0] === 'd');
+      if (dTag && dTag[1]) {
+        const dTagKey = `d:${event.kind}:${dTag[1]}`;
+        const existing = this._eventCache.get(dTagKey);
+
+        // Replace if newer, or if same timestamp but different event ID (for events in same second)
+        const shouldReplace = !existing || !existing.events[0] ||
+                             event.created_at > existing.events[0].created_at ||
+                             (event.created_at === existing.events[0].created_at && event.id !== existing.events[0].id);
+
+        if (shouldReplace) {
+          this._eventCache.set(dTagKey, {
+            events: [event],
+            timestamp: Date.now(),
+          });
+
+          // Remove old event from cache if it exists
+          if (existing && existing.events[0]) {
+            this._eventCache.delete(existing.events[0].id);
+          }
+
+          // Invalidate any query caches that might contain stale data for this d-tag
+          // Query caches are JSON-stringified filters, so we look for any that match this event
+          this._invalidateQueryCachesForEvent(event);
+        }
+      }
+    }
+  }
+
+  /**
+   * Invalidate query caches that might be affected by a new event
+   * @private
+   */
+  _invalidateQueryCachesForEvent(event) {
+    // Find and remove query cache entries that could match this event
+    // Query cache keys are JSON-stringified filters
+    const keysToDelete = [];
+
+    for (const [cacheKey, cached] of this._eventCache.entries()) {
+      // Skip non-query caches (event IDs and d-tag keys)
+      if (!cacheKey.startsWith('{')) continue;
+
+      try {
+        const filter = JSON.parse(cacheKey);
+        // Check if this event would match the filter
+        if (this._eventMatchesFilter(event, filter)) {
+          keysToDelete.push(cacheKey);
+        }
+      } catch {
+        // Not a JSON key, skip
+      }
+    }
+
+    for (const key of keysToDelete) {
+      this._eventCache.delete(key);
+    }
+  }
+
+  /**
+   * Cache event in memory and persist
+   * @private
+   */
+  async _cacheEvent(event) {
+    // Cache in memory
+    this._cacheEventSync(event);
+
+    // Persist to storage
+    if (this.persistentStorage) {
+      try {
+        // For replaceable events, use d-tag as key
+        let storageKey = event.id;
+        if (event.kind >= 30000 && event.kind < 40000) {
+          const dTag = event.tags.find(t => t[0] === 'd');
+          if (dTag && dTag[1]) {
+            storageKey = dTag[1]; // Use d-tag as key for replaceable events
+          }
+        }
+
+        await this.persistentStorage.put(storageKey, event);
+      } catch (error) {
+        console.warn('Failed to persist event:', error);
+      }
+    }
+
+    // Trigger any active subscriptions that match this event
+    if (this.relays.length === 0) {
+      for (const sub of this._subscriptions.values()) {
+        if (sub.active && this._eventMatchesFilter(event, sub.filter)) {
+          // Trigger callback asynchronously, but check active status again
+          setTimeout(() => {
+            if (sub.active) {
+              sub.onEvent(event);
+            }
+          }, 10);
+        }
+      }
+    }
+  }
+
+  /**
+   * Get cached events matching a filter
+   * @private
+   */
+  _getMatchingCachedEvents(filter) {
+    const matchingEvents = [];
+    const seenDTags = new Map(); // For deduplicating replaceable events
+
+    for (const cached of this._eventCache.values()) {
+      for (const event of (cached.events || [])) {
+        if (this._eventMatchesFilter(event, filter)) {
+          // For replaceable events (kind 30000-39999), keep only the newest
+          if (event.kind >= 30000 && event.kind < 40000) {
+            const dTag = event.tags.find(t => t[0] === 'd');
+            if (dTag && dTag[1]) {
+              const dTagKey = `${event.kind}:${dTag[1]}`;
+              const existing = seenDTags.get(dTagKey);
+
+              // Replace if newer, or if same timestamp with _deleted flag (tombstones)
+              const shouldReplace = !existing ||
+                                   event.created_at > existing.created_at ||
+                                   (event.created_at === existing.created_at &&
+                                    JSON.parse(event.content)?._deleted &&
+                                    !JSON.parse(existing.content)?._deleted);
+
+              if (shouldReplace) {
+                // Remove old event if exists
+                if (existing) {
+                  const idx = matchingEvents.indexOf(existing);
+                  if (idx > -1) matchingEvents.splice(idx, 1);
+                }
+                seenDTags.set(dTagKey, event);
+                matchingEvents.push(event);
+              }
+              continue;
+            }
+          }
+
+          // Regular events or replaceable events without d-tag
+          matchingEvents.push(event);
+        }
+      }
+    }
+
+    return matchingEvents;
+  }
+
+  /**
+   * Check if event matches filter
+   * @private
+   */
+  _eventMatchesFilter(event, filter) {
+    // Check kinds
+    if (filter.kinds && !filter.kinds.includes(event.kind)) {
+      return false;
+    }
+
+    // Check IDs
+    if (filter.ids && !filter.ids.includes(event.id)) {
+      return false;
+    }
+
+    // Check authors
+    if (filter.authors && !filter.authors.includes(event.pubkey)) {
+      return false;
+    }
+
+    // Check #d tag (for replaceable events)
+    if (filter['#d']) {
+      const dTag = event.tags.find(t => t[0] === 'd');
+      if (!dTag || !filter['#d'].includes(dTag[1])) {
+        return false;
+      }
+    }
+
+    // Check since/until
+    if (filter.since && event.created_at < filter.since) {
+      return false;
+    }
+    if (filter.until && event.created_at > filter.until) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get single event by ID
+   * @param {string} eventId - Event ID (hex)
+   * @returns {Promise<Object|null>} Event or null
+   */
+  async getEvent(eventId) {
+    const events = await this.query({ ids: [eventId] });
+    return events.length > 0 ? events[0] : null;
+  }
+
+  /**
+   * Clear the event cache (or specific entries matching a pattern)
+   * @param {string} [pattern] - Optional d-tag pattern to match (clears all if not provided)
+   */
+  clearCache(pattern = null) {
+    if (!pattern) {
+      this._eventCache.clear();
+      return;
+    }
+
+    // Clear entries matching the pattern
+    for (const key of this._eventCache.keys()) {
+      if (key.includes(pattern)) {
+        this._eventCache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Close all connections and subscriptions
+   */
+  close() {
+    // Stop background sync service
+    if (this.syncService) {
+      this.syncService.stop();
+    }
+
+    // Close all subscriptions
+    for (const sub of this._subscriptions.values()) {
+      if (sub.close) {
+        sub.close();
+      } else if (sub.active !== undefined) {
+        // Mock subscription
+        sub.active = false;
+      }
+    }
+    this._subscriptions.clear();
+
+    // Close pool
+    this.pool.close(this.relays);
+
+    // Clear cache
+    this._eventCache.clear();
+  }
+
+  /**
+   * Get relay status
+   * @returns {Array} Relay connection statuses
+   */
+  getRelayStatus() {
+    return this.relays.map(relay => ({
+      url: relay,
+      connected: true, // SimplePool manages this internally
+    }));
+  }
+}
+
+/**
+ * Create NostrClient instance
+ * @param {Object} config - Configuration options
+ * @returns {NostrClient} Client instance
+ */
+export function createClient(config) {
+  return new NostrClient(config);
+}