@elisym/sdk 0.3.2 → 0.3.3

package/dist/index.d.cts

@@ -35,7 +35,22 @@ declare class NostrPool {
     private pool;
     private relays;
     private activeSubscriptions;
+    private resetListeners;
     constructor(relays?: string[]);
+    /**
+     * Register a callback to run after `reset()` completes (new SimplePool in place).
+     * Services that cache pool-derived state (e.g. ping results) must clear it here,
+     * otherwise stale values survive the reconnect. Returns an unsubscribe function.
+     *
+     * Contract:
+     * - Listeners are invoked **synchronously** at the end of `reset()`, in
+     *   registration order. Do not rely on async work inside a listener having
+     *   completed before `reset()` returns.
+     * - Listener exceptions are caught and swallowed so that one faulty listener
+     *   cannot prevent the others from running (or abort the reset itself).
+     *   If a listener needs to surface errors, it must do so out-of-band.
+     */
+    onReset(listener: () => void): () => void;
     /** Query relays synchronously. Returns `[]` on timeout (no error thrown). */
     querySync(filter: Filter): Promise<Event[]>;
     queryBatched(filter: Omit<Filter, 'authors'>, keys: string[], batchSize?: number, maxConcurrency?: number): Promise<Event[]>;
@@ -189,6 +204,20 @@ declare class MediaService {
  * this instance - recreating the service generates a new keypair.
  *
  * Requires `globalThis.crypto` (Node 20+, Bun, browsers).
+ *
+ * Lifetime / cleanup:
+ * - The constructor registers a listener on `pool.onReset()` and never
+ *   unsubscribes. This is intentional: PingService is expected to share its
+ *   lifetime with the NostrPool it is bound to (both live for the lifetime
+ *   of an ElisymClient). If you ever construct a PingService that outlives
+ *   its pool - or vice versa - add an explicit `dispose()` that calls the
+ *   unsubscribe function returned by `pool.onReset()` to avoid leaking a
+ *   reference to this instance through the pool's listener set.
+ * - `clearCache()` drops cached online results but does NOT cancel in-flight
+ *   pings in `pendingPings`. An in-flight ping started before a pool reset
+ *   may return `online: false` even if the new pool is healthy; the next
+ *   ping attempt will go through the fresh subscription and resolve
+ *   correctly.
  */
 declare class PingService {
     private pool;
@@ -197,6 +226,9 @@ declare class PingService {
     private pingCache;
     private pendingPings;
     constructor(pool: NostrPool);
+    /** Drop cached online results. In-flight pings are left alone - they'll
+     * resolve via their own timeouts and remove themselves from `pendingPings`. */
+    clearCache(): void;
     /**
      * Ping an agent via ephemeral Nostr events (kind 20200/20201).
      * Uses a persistent session identity to avoid relay rate-limiting.

package/dist/index.d.ts

@@ -35,7 +35,22 @@ declare class NostrPool {
     private pool;
     private relays;
     private activeSubscriptions;
+    private resetListeners;
     constructor(relays?: string[]);
+    /**
+     * Register a callback to run after `reset()` completes (new SimplePool in place).
+     * Services that cache pool-derived state (e.g. ping results) must clear it here,
+     * otherwise stale values survive the reconnect. Returns an unsubscribe function.
+     *
+     * Contract:
+     * - Listeners are invoked **synchronously** at the end of `reset()`, in
+     *   registration order. Do not rely on async work inside a listener having
+     *   completed before `reset()` returns.
+     * - Listener exceptions are caught and swallowed so that one faulty listener
+     *   cannot prevent the others from running (or abort the reset itself).
+     *   If a listener needs to surface errors, it must do so out-of-band.
+     */
+    onReset(listener: () => void): () => void;
     /** Query relays synchronously. Returns `[]` on timeout (no error thrown). */
     querySync(filter: Filter): Promise<Event[]>;
     queryBatched(filter: Omit<Filter, 'authors'>, keys: string[], batchSize?: number, maxConcurrency?: number): Promise<Event[]>;
@@ -189,6 +204,20 @@ declare class MediaService {
  * this instance - recreating the service generates a new keypair.
  *
  * Requires `globalThis.crypto` (Node 20+, Bun, browsers).
+ *
+ * Lifetime / cleanup:
+ * - The constructor registers a listener on `pool.onReset()` and never
+ *   unsubscribes. This is intentional: PingService is expected to share its
+ *   lifetime with the NostrPool it is bound to (both live for the lifetime
+ *   of an ElisymClient). If you ever construct a PingService that outlives
+ *   its pool - or vice versa - add an explicit `dispose()` that calls the
+ *   unsubscribe function returned by `pool.onReset()` to avoid leaking a
+ *   reference to this instance through the pool's listener set.
+ * - `clearCache()` drops cached online results but does NOT cancel in-flight
+ *   pings in `pendingPings`. An in-flight ping started before a pool reset
+ *   may return `online: false` even if the new pool is healthy; the next
+ *   ping attempt will go through the fresh subscription and resolve
+ *   correctly.
  */
 declare class PingService {
     private pool;
@@ -197,6 +226,9 @@ declare class PingService {
     private pingCache;
     private pendingPings;
     constructor(pool: NostrPool);
+    /** Drop cached online results. In-flight pings are left alone - they'll
+     * resolve via their own timeouts and remove themselves from `pendingPings`. */
+    clearCache(): void;
     /**
      * Ping an agent via ephemeral Nostr events (kind 20200/20201).
      * Uses a persistent session identity to avoid relay rate-limiting.

package/dist/index.js

@@ -1571,12 +1571,18 @@ var PingService = class _PingService {
   constructor(pool) {
     this.pool = pool;
     this.sessionIdentity = ElisymIdentity.generate();
+    pool.onReset(() => this.clearCache());
   }
   static PING_CACHE_MAX = 1e3;
   sessionIdentity;
   pingCache = /* @__PURE__ */ new Map();
   // pubkey - timestamp of last online result
   pendingPings = /* @__PURE__ */ new Map();
+  /** Drop cached online results. In-flight pings are left alone - they'll
+   * resolve via their own timeouts and remove themselves from `pendingPings`. */
+  clearCache() {
+    this.pingCache.clear();
+  }
   /**
    * Ping an agent via ephemeral Nostr events (kind 20200/20201).
    * Uses a persistent session identity to avoid relay rate-limiting.
@@ -1775,10 +1781,28 @@ var NostrPool = class {
   pool;
   relays;
   activeSubscriptions = /* @__PURE__ */ new Set();
+  resetListeners = /* @__PURE__ */ new Set();
   constructor(relays = RELAYS) {
     this.pool = new SimplePool();
     this.relays = relays;
   }
+  /**
+   * Register a callback to run after `reset()` completes (new SimplePool in place).
+   * Services that cache pool-derived state (e.g. ping results) must clear it here,
+   * otherwise stale values survive the reconnect. Returns an unsubscribe function.
+   *
+   * Contract:
+   * - Listeners are invoked **synchronously** at the end of `reset()`, in
+   *   registration order. Do not rely on async work inside a listener having
+   *   completed before `reset()` returns.
+   * - Listener exceptions are caught and swallowed so that one faulty listener
+   *   cannot prevent the others from running (or abort the reset itself).
+   *   If a listener needs to surface errors, it must do so out-of-band.
+   */
+  onReset(listener) {
+    this.resetListeners.add(listener);
+    return () => this.resetListeners.delete(listener);
+  }
   /** Query relays synchronously. Returns `[]` on timeout (no error thrown). */
   async querySync(filter) {
     let timer;
@@ -1786,13 +1810,12 @@ var NostrPool = class {
     query.catch(() => {
     });
     try {
-      const result = await Promise.race([
+      return await Promise.race([
         query,
         new Promise((resolve) => {
           timer = setTimeout(() => resolve([]), DEFAULTS.QUERY_TIMEOUT_MS);
         })
       ]);
-      return result;
     } finally {
       clearTimeout(timer);
     }
@@ -1974,6 +1997,12 @@ var NostrPool = class {
     } catch {
     }
     this.pool = new SimplePool();
+    for (const listener of this.resetListeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
   }
   /**
    * Lightweight connectivity probe. Returns true if at least one relay responds.