@routstr/sdk 0.3.8 → 0.3.9

package/dist/discovery/index.d.mts

@@ -1,5 +1,6 @@
 import { D as DiscoveryAdapter } from '../interfaces-Cv1k2EUK.mjs';
 import { S as SdkLogger, e as Model, k as ProviderInfo } from '../types-_21yYFZG.mjs';
+import { EventStore } from 'applesauce-core';
 
 /**
  * ModelManager class for discovering, fetching, and managing models from providers
@@ -17,12 +18,17 @@ interface ModelManagerConfig {
     includeProviderUrls?: string[];
     /** Provider base URLs to exclude */
     excludeProviderUrls?: string[];
-    /** Cache TTL in milliseconds (default: 21 minutes) */
+    /** Cache TTL in milliseconds (default: 210 minutes) */
     cacheTTL?: number;
     /** Nostr pubkey for routstr review/model events (kind 38425/38423). Defaults to routstr's key. */
     routstrPubkey?: string;
     /** Optional injectable logger */
     logger?: SdkLogger;
+    /** Path to SQLite database for persistent Nostr event storage.
+     * If provided, events fetched by ModelManager from relays (kinds 38421,
+     * 38423, 38425) are persisted and survive process restarts. The underlying
+     * EventStore can also be accessed for advanced/manual event management. */
+    eventStoreDbPath?: string;
 }
 /**
  * ModelManager handles all model discovery and caching logic
@@ -37,12 +43,40 @@ declare class ModelManager {
     private readonly routstrPubkey;
     private readonly logger;
     private providerNodePubkeysByUrl;
+    /** Persistent event store for relay-fetched events (null if not configured/initialized) */
+    private eventStore;
+    private eventStoreDb;
+    private eventStoreInitPromise;
+    private readonly eventStoreDbPath?;
     constructor(adapter: DiscoveryAdapter, config?: ModelManagerConfig);
     /**
      * Get the list of bootstrapped provider base URLs
      * @returns Array of provider base URLs
      */
     getBaseUrls(): string[];
+    /**
+     * Lazily initialize the persistent event store.
+     * Returns null if no eventStoreDbPath was provided.
+     */
+    private ensureEventStore;
+    /**
+     * Get the persistent event store, initializing it if configured.
+     * Returns null if no eventStoreDbPath was provided.
+     */
+    getEventStore(): Promise<EventStore | null>;
+    private createPersistentEventDatabase;
+    /** Close the persistent event store database handle, if configured. */
+    closeEventStore(): void;
+    private initializeEventStoreMetadata;
+    private markEventFetched;
+    private getEventFetchedAt;
+    /**
+     * Check the persistent event store for fresh cached events.
+     * Returns events from SQLite if they were fetched within `maxAge`, otherwise
+     * returns empty array (caller should hit relays). Events without local fetch
+     * metadata fall back to Nostr created_at for backwards compatibility.
+     */
+    private getCachedNostrEvents;
     static init(adapter: DiscoveryAdapter, config?: ModelManagerConfig, options?: {
         torMode?: boolean;
         forceRefresh?: boolean;
@@ -57,7 +91,7 @@ declare class ModelManager {
      */
     bootstrapProviders(torMode?: boolean, forceRefresh?: boolean): Promise<string[]>;
     /**
-     * Bootstrap providers from Nostr network (kind 30421)
+     * Bootstrap providers from Nostr network (kind 38421)
      * @param kind The Nostr kind to fetch
      * @param torMode Whether running in Tor context
      * @returns Array of provider base URLs
@@ -81,7 +115,7 @@ declare class ModelManager {
      * @param baseUrls Current provider base URLs to evaluate
      * @returns Array of provider base URLs disabled by the review set
      */
-    syncReviewedProvidersFromNostr(baseUrls?: string[], providerNodes?: Map<string, Set<string>>): Promise<string[]>;
+    syncReviewedProvidersFromNostr(baseUrls?: string[], providerNodes?: Map<string, Set<string>>, forceRefresh?: boolean): Promise<string[]>;
     private addProviderNode;
     /**
      * Fetch models from all providers and select best-priced options

package/dist/discovery/index.d.ts

@@ -1,5 +1,6 @@
 import { D as DiscoveryAdapter } from '../interfaces-iL7CWeG5.js';
 import { S as SdkLogger, e as Model, k as ProviderInfo } from '../types-_21yYFZG.js';
+import { EventStore } from 'applesauce-core';
 
 /**
  * ModelManager class for discovering, fetching, and managing models from providers
@@ -17,12 +18,17 @@ interface ModelManagerConfig {
     includeProviderUrls?: string[];
     /** Provider base URLs to exclude */
     excludeProviderUrls?: string[];
-    /** Cache TTL in milliseconds (default: 21 minutes) */
+    /** Cache TTL in milliseconds (default: 210 minutes) */
     cacheTTL?: number;
     /** Nostr pubkey for routstr review/model events (kind 38425/38423). Defaults to routstr's key. */
     routstrPubkey?: string;
     /** Optional injectable logger */
     logger?: SdkLogger;
+    /** Path to SQLite database for persistent Nostr event storage.
+     * If provided, events fetched by ModelManager from relays (kinds 38421,
+     * 38423, 38425) are persisted and survive process restarts. The underlying
+     * EventStore can also be accessed for advanced/manual event management. */
+    eventStoreDbPath?: string;
 }
 /**
  * ModelManager handles all model discovery and caching logic
@@ -37,12 +43,40 @@ declare class ModelManager {
     private readonly routstrPubkey;
     private readonly logger;
     private providerNodePubkeysByUrl;
+    /** Persistent event store for relay-fetched events (null if not configured/initialized) */
+    private eventStore;
+    private eventStoreDb;
+    private eventStoreInitPromise;
+    private readonly eventStoreDbPath?;
     constructor(adapter: DiscoveryAdapter, config?: ModelManagerConfig);
     /**
      * Get the list of bootstrapped provider base URLs
      * @returns Array of provider base URLs
      */
     getBaseUrls(): string[];
+    /**
+     * Lazily initialize the persistent event store.
+     * Returns null if no eventStoreDbPath was provided.
+     */
+    private ensureEventStore;
+    /**
+     * Get the persistent event store, initializing it if configured.
+     * Returns null if no eventStoreDbPath was provided.
+     */
+    getEventStore(): Promise<EventStore | null>;
+    private createPersistentEventDatabase;
+    /** Close the persistent event store database handle, if configured. */
+    closeEventStore(): void;
+    private initializeEventStoreMetadata;
+    private markEventFetched;
+    private getEventFetchedAt;
+    /**
+     * Check the persistent event store for fresh cached events.
+     * Returns events from SQLite if they were fetched within `maxAge`, otherwise
+     * returns empty array (caller should hit relays). Events without local fetch
+     * metadata fall back to Nostr created_at for backwards compatibility.
+     */
+    private getCachedNostrEvents;
     static init(adapter: DiscoveryAdapter, config?: ModelManagerConfig, options?: {
         torMode?: boolean;
         forceRefresh?: boolean;
@@ -57,7 +91,7 @@ declare class ModelManager {
      */
     bootstrapProviders(torMode?: boolean, forceRefresh?: boolean): Promise<string[]>;
     /**
-     * Bootstrap providers from Nostr network (kind 30421)
+     * Bootstrap providers from Nostr network (kind 38421)
      * @param kind The Nostr kind to fetch
      * @param torMode Whether running in Tor context
      * @returns Array of provider base URLs
@@ -81,7 +115,7 @@ declare class ModelManager {
      * @param baseUrls Current provider base URLs to evaluate
      * @returns Array of provider base URLs disabled by the review set
      */
-    syncReviewedProvidersFromNostr(baseUrls?: string[], providerNodes?: Map<string, Set<string>>): Promise<string[]>;
+    syncReviewedProvidersFromNostr(baseUrls?: string[], providerNodes?: Map<string, Set<string>>, forceRefresh?: boolean): Promise<string[]>;
     private addProviderNode;
     /**
      * Fetch models from all providers and select best-priced options

package/dist/discovery/index.js

@@ -34,6 +34,9 @@ var NoProvidersAvailableError = class extends Error {
     this.name = "NoProvidersAvailableError";
   }
 };
+function isBunRuntime() {
+  return typeof Bun !== "undefined";
+}
 var ModelManager = class _ModelManager {
   constructor(adapter, config = {}) {
     this.adapter = adapter;
@@ -43,6 +46,7 @@ var ModelManager = class _ModelManager {
     this.excludeProviderUrls = config.excludeProviderUrls || [];
     this.routstrPubkey = config.routstrPubkey || "4ad6fa2d16e2a9b576c863b4cf7404a70d4dc320c0c447d10ad6ff58993eacc8";
     this.logger = (config.logger ?? consoleLogger).child("ModelManager");
+    this.eventStoreDbPath = config.eventStoreDbPath;
   }
   adapter;
   cacheTTL;
@@ -52,6 +56,11 @@ var ModelManager = class _ModelManager {
   routstrPubkey;
   logger;
   providerNodePubkeysByUrl = /* @__PURE__ */ new Map();
+  /** Persistent event store for relay-fetched events (null if not configured/initialized) */
+  eventStore = null;
+  eventStoreDb = null;
+  eventStoreInitPromise = null;
+  eventStoreDbPath;
   /**
    * Get the list of bootstrapped provider base URLs
    * @returns Array of provider base URLs
@@ -59,6 +68,104 @@ var ModelManager = class _ModelManager {
   getBaseUrls() {
     return this.adapter.getBaseUrlsList();
   }
+  /**
+   * Lazily initialize the persistent event store.
+   * Returns null if no eventStoreDbPath was provided.
+   */
+  async ensureEventStore() {
+    if (!this.eventStoreDbPath) return null;
+    if (this.eventStore) return this.eventStore;
+    if (!this.eventStoreInitPromise) {
+      this.eventStoreInitPromise = (async () => {
+        try {
+          const db = await this.createPersistentEventDatabase();
+          this.eventStoreDb = db;
+          this.eventStore = new applesauceCore.EventStore({ database: db });
+          this.initializeEventStoreMetadata();
+          this.logger.log(
+            `Persistent event store initialized at ${this.eventStoreDbPath}`
+          );
+          return this.eventStore;
+        } catch (error) {
+          this.eventStoreInitPromise = null;
+          throw new Error(
+            `applesauce-sqlite with a supported SQLite driver is required for persistent Nostr event storage. Bun uses bun:sqlite; Node.js uses better-sqlite3. Install optional dependencies or omit eventStoreDbPath. (${error})`
+          );
+        }
+      })();
+    }
+    return this.eventStoreInitPromise;
+  }
+  /**
+   * Get the persistent event store, initializing it if configured.
+   * Returns null if no eventStoreDbPath was provided.
+   */
+  async getEventStore() {
+    return this.ensureEventStore();
+  }
+  async createPersistentEventDatabase() {
+    if (isBunRuntime()) {
+      const { BunSqliteEventDatabase } = await import('applesauce-sqlite/bun');
+      return new BunSqliteEventDatabase(
+        this.eventStoreDbPath
+      );
+    }
+    const { BetterSqlite3EventDatabase } = await import('applesauce-sqlite/better-sqlite3');
+    return new BetterSqlite3EventDatabase(
+      this.eventStoreDbPath
+    );
+  }
+  /** Close the persistent event store database handle, if configured. */
+  closeEventStore() {
+    this.eventStoreDb?.close?.();
+    this.eventStore = null;
+    this.eventStoreDb = null;
+    this.eventStoreInitPromise = null;
+  }
+  initializeEventStoreMetadata() {
+    this.eventStoreDb?.db?.exec(
+      `CREATE TABLE IF NOT EXISTS routstr_event_cache_metadata (
+        event_id TEXT PRIMARY KEY,
+        fetched_at INTEGER NOT NULL
+      )`
+    );
+  }
+  markEventFetched(event, fetchedAt = Date.now()) {
+    const db = this.eventStoreDb?.db;
+    if (!db) return;
+    db.prepare(
+      `INSERT INTO routstr_event_cache_metadata (event_id, fetched_at)
+       VALUES (?, ?)
+       ON CONFLICT(event_id) DO UPDATE SET fetched_at = excluded.fetched_at`
+    ).run?.(event.id, fetchedAt);
+  }
+  getEventFetchedAt(event) {
+    const db = this.eventStoreDb?.db;
+    if (!db) return void 0;
+    const row = db.prepare(
+      `SELECT fetched_at FROM routstr_event_cache_metadata WHERE event_id = ?`
+    ).get?.(event.id);
+    return typeof row?.fetched_at === "number" ? row.fetched_at : void 0;
+  }
+  /**
+   * Check the persistent event store for fresh cached events.
+   * Returns events from SQLite if they were fetched within `maxAge`, otherwise
+   * returns empty array (caller should hit relays). Events without local fetch
+   * metadata fall back to Nostr created_at for backwards compatibility.
+   */
+  async getCachedNostrEvents(filter, maxAge, forceRefresh = false) {
+    const eventStore = await this.ensureEventStore();
+    if (forceRefresh) return [];
+    if (!eventStore) return [];
+    const timeline = eventStore.getTimeline(filter);
+    if (timeline.length === 0) return [];
+    const cutoff = Date.now() - maxAge;
+    const freshest = Math.max(
+      ...timeline.map((e) => this.getEventFetchedAt(e) ?? e.created_at * 1e3)
+    );
+    if (freshest < cutoff) return [];
+    return timeline;
+  }
   static async init(adapter, config = {}, options = {}) {
     const manager = new _ModelManager(adapter, config);
     const torMode = options.torMode ?? false;
@@ -87,19 +194,31 @@ var ModelManager = class _ModelManager {
             torMode
           );
           await this.fetchRoutstr21Models(forceRefresh);
-          await this.syncReviewedProvidersFromNostr(filteredCachedUrls);
+          await this.syncReviewedProvidersFromNostr(
+            filteredCachedUrls,
+            this.providerNodePubkeysByUrl,
+            forceRefresh
+          );
           return filteredCachedUrls;
         }
       }
     }
     try {
-      const nostrProviders = await this.bootstrapFromNostr(38421, torMode);
+      const nostrProviders = await this.bootstrapFromNostr(
+        38421,
+        torMode,
+        forceRefresh
+      );
       if (nostrProviders.length > 0) {
         const filtered = this.filterBaseUrlsForTor(nostrProviders, torMode);
         this.adapter.setBaseUrlsList(filtered);
         this.adapter.setBaseUrlsLastUpdate(Date.now());
         await this.fetchRoutstr21Models(forceRefresh);
-        await this.syncReviewedProvidersFromNostr(filtered);
+        await this.syncReviewedProvidersFromNostr(
+          filtered,
+          this.providerNodePubkeysByUrl,
+          forceRefresh
+        );
         return filtered;
       }
     } catch (e) {
@@ -108,42 +227,52 @@ var ModelManager = class _ModelManager {
     return this.bootstrapFromHttp(torMode, forceRefresh);
   }
   /**
-   * Bootstrap providers from Nostr network (kind 30421)
+   * Bootstrap providers from Nostr network (kind 38421)
    * @param kind The Nostr kind to fetch
    * @param torMode Whether running in Tor context
    * @returns Array of provider base URLs
    */
-  async bootstrapFromNostr(kind, torMode) {
+  async bootstrapFromNostr(kind, torMode, forceRefresh = false) {
     const DEFAULT_RELAYS = [
       "wss://relay.primal.net",
       "wss://nos.lol",
       "wss://relay.damus.io"
     ];
-    const pool = new applesauceRelay.RelayPool();
-    const localEventStore = new applesauceCore.EventStore();
-    const timeoutMs = 5e3;
-    await new Promise((resolve) => {
-      pool.req(DEFAULT_RELAYS, {
-        kinds: [kind],
-        limit: 100
-      }).pipe(
-        applesauceRelay.onlyEvents(),
-        rxjs.tap((event) => {
-          localEventStore.add(event);
-        })
-      ).subscribe({
-        complete: () => {
+    const cached = await this.getCachedNostrEvents(
+      { kinds: [kind] },
+      this.cacheTTL,
+      forceRefresh
+    );
+    let sessionEvents = cached;
+    if (cached.length === 0) {
+      const pool = new applesauceRelay.RelayPool();
+      const timeoutMs = 5e3;
+      await new Promise((resolve) => {
+        pool.req(DEFAULT_RELAYS, {
+          kinds: [kind],
+          limit: 100
+        }).pipe(
+          applesauceRelay.onlyEvents(),
+          rxjs.tap((event) => {
+            sessionEvents.push(event);
+            this.eventStore?.add(event);
+            this.markEventFetched(event);
+          })
+        ).subscribe({
+          complete: () => {
+            resolve();
+          }
+        });
+        setTimeout(() => {
           resolve();
-        }
+        }, timeoutMs);
       });
-      setTimeout(() => {
-        resolve();
-      }, timeoutMs);
-    });
-    const timeline = localEventStore.getTimeline({ kinds: [kind] });
+    } else {
+      this.logger.log(`Using ${cached.length} cached kind ${kind} events from persistent store`);
+    }
     const bases = /* @__PURE__ */ new Set();
     this.providerNodePubkeysByUrl = /* @__PURE__ */ new Map();
-    for (const event of timeline) {
+    for (const event of sessionEvents) {
       const eventUrls = [];
       for (const tag of event.tags) {
         if (tag[0] === "u" && typeof tag[1] === "string") {
@@ -251,7 +380,11 @@ var ModelManager = class _ModelManager {
         this.adapter.setBaseUrlsList(list);
         this.adapter.setBaseUrlsLastUpdate(Date.now());
         await this.fetchRoutstr21Models(forceRefresh);
-        await this.syncReviewedProvidersFromNostr(list);
+        await this.syncReviewedProvidersFromNostr(
+          list,
+          this.providerNodePubkeysByUrl,
+          forceRefresh
+        );
       }
       return list;
     } catch (e) {
@@ -270,7 +403,7 @@ var ModelManager = class _ModelManager {
    * @param baseUrls Current provider base URLs to evaluate
    * @returns Array of provider base URLs disabled by the review set
    */
-  async syncReviewedProvidersFromNostr(baseUrls = this.adapter.getBaseUrlsList(), providerNodes = this.providerNodePubkeysByUrl) {
+  async syncReviewedProvidersFromNostr(baseUrls = this.adapter.getBaseUrlsList(), providerNodes = this.providerNodePubkeysByUrl, forceRefresh = false) {
     if (baseUrls.length === 0) return [];
     if (!this.adapter.setDisabledProviders) {
       this.logger.warn(
@@ -278,30 +411,43 @@ var ModelManager = class _ModelManager {
       );
       return [];
     }
-    const LGTM_RELAYS = [
-      "wss://relay.primal.net",
-      "wss://nos.lol",
-      "wss://relay.damus.io",
-      "wss://relay.routstr.com"
-    ];
     const reviewedNodePubkeys = /* @__PURE__ */ new Set();
     {
-      const pool = new applesauceRelay.RelayPool();
-      const store = new applesauceCore.EventStore();
-      const timeoutMs = 5e3;
-      await new Promise((resolve) => {
-        pool.req(LGTM_RELAYS, {
-          kinds: [38425],
-          "#t": ["lgtm"],
-          limit: 500,
-          authors: [this.routstrPubkey]
-        }).pipe(
-          applesauceRelay.onlyEvents(),
-          rxjs.tap((event) => store.add(event))
-        ).subscribe({ complete: () => resolve() });
-        setTimeout(() => resolve(), timeoutMs);
-      });
-      for (const event of store.getTimeline({ kinds: [38425] })) {
+      const cached = await this.getCachedNostrEvents(
+        { kinds: [38425], "#t": ["lgtm"], authors: [this.routstrPubkey] },
+        this.cacheTTL,
+        forceRefresh
+      );
+      let sessionEvents = cached;
+      if (cached.length === 0) {
+        const LGTM_RELAYS = [
+          "wss://relay.primal.net",
+          "wss://nos.lol",
+          "wss://relay.damus.io",
+          "wss://relay.routstr.com"
+        ];
+        const pool = new applesauceRelay.RelayPool();
+        const timeoutMs = 5e3;
+        await new Promise((resolve) => {
+          pool.req(LGTM_RELAYS, {
+            kinds: [38425],
+            "#t": ["lgtm"],
+            limit: 500,
+            authors: [this.routstrPubkey]
+          }).pipe(
+            applesauceRelay.onlyEvents(),
+            rxjs.tap((event) => {
+              sessionEvents.push(event);
+              this.eventStore?.add(event);
+              this.markEventFetched(event);
+            })
+          ).subscribe({ complete: () => resolve() });
+          setTimeout(() => resolve(), timeoutMs);
+        });
+      } else {
+        this.logger.log(`Using ${cached.length} cached kind 38425 events from persistent store`);
+      }
+      for (const event of sessionEvents) {
         const hasLgtmTag = event.tags.some(
           (tag) => tag[0] === "t" && tag[1]?.toLowerCase() === "lgtm"
         );
@@ -410,7 +556,7 @@ var ModelManager = class _ModelManager {
         if (this.isProviderDownError(error)) {
           this.logger.warn(`Provider ${base} is down right now.`);
         } else {
-          this.logger.warn(`Failed to fetch models from ${base}:`, error);
+          this.logger.warn(`Provider ${base} unreachable: ${error.message}`);
         }
         this.adapter.setProviderLastUpdate(base, Date.now());
         return { success: false, base };
@@ -530,34 +676,44 @@ var ModelManager = class _ModelManager {
       "wss://nos.lol",
       "wss://relay.routstr.com"
     ];
-    const pool = new applesauceRelay.RelayPool();
-    const localEventStore = new applesauceCore.EventStore();
-    const timeoutMs = 5e3;
-    await new Promise((resolve) => {
-      pool.req(DEFAULT_RELAYS, {
-        kinds: [38423],
-        "#d": ["routstr-21-models"],
-        limit: 1,
-        authors: [this.routstrPubkey]
-      }).pipe(
-        applesauceRelay.onlyEvents(),
-        rxjs.tap((event2) => {
-          localEventStore.add(event2);
-        })
-      ).subscribe({
-        complete: () => {
+    const cached = await this.getCachedNostrEvents(
+      { kinds: [38423], "#d": ["routstr-21-models"], authors: [this.routstrPubkey] },
+      this.cacheTTL,
+      forceRefresh
+    );
+    let sessionEvents = cached;
+    if (cached.length === 0) {
+      const pool = new applesauceRelay.RelayPool();
+      const timeoutMs = 5e3;
+      await new Promise((resolve) => {
+        pool.req(DEFAULT_RELAYS, {
+          kinds: [38423],
+          "#d": ["routstr-21-models"],
+          limit: 1,
+          authors: [this.routstrPubkey]
+        }).pipe(
+          applesauceRelay.onlyEvents(),
+          rxjs.tap((event2) => {
+            sessionEvents.push(event2);
+            this.eventStore?.add(event2);
+            this.markEventFetched(event2);
+          })
+        ).subscribe({
+          complete: () => {
+            resolve();
+          }
+        });
+        setTimeout(() => {
           resolve();
-        }
+        }, timeoutMs);
       });
-      setTimeout(() => {
-        resolve();
-      }, timeoutMs);
-    });
-    const timeline = localEventStore.getTimeline({ kinds: [38423] });
-    if (timeline.length === 0) {
+    } else {
+      this.logger.log(`Using ${cached.length} cached kind 38423 events from persistent store`);
+    }
+    if (sessionEvents.length === 0) {
       return cachedModels.length > 0 ? cachedModels : [];
     }
-    const event = timeline[0];
+    const event = sessionEvents[0];
     try {
       const content = JSON.parse(event.content);
       const models = Array.isArray(content?.models) ? content.models : [];