@routstr/sdk 0.3.7 → 0.3.9

package/dist/discovery/index.d.mts

@@ -0,0 +1,247 @@
+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
+ * Core responsibility: fetching models from providers, caching them, and selecting the best option
+ * (lowest cost) across multiple providers
+ */
+
+/**
+ * Configuration for ModelManager
+ */
+interface ModelManagerConfig {
+    /** URL to fetch provider directory from */
+    providerDirectoryUrl?: string;
+    /** Additional provider base URLs to include */
+    includeProviderUrls?: string[];
+    /** Provider base URLs to exclude */
+    excludeProviderUrls?: string[];
+    /** 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
+ * Abstracts away storage details via DiscoveryAdapter
+ */
+declare class ModelManager {
+    private adapter;
+    private readonly cacheTTL;
+    private readonly providerDirectoryUrl;
+    private readonly includeProviderUrls;
+    private readonly excludeProviderUrls;
+    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;
+    }): Promise<ModelManager>;
+    /**
+     * Bootstrap provider list from the provider directory
+     * First tries to fetch from Nostr (kind 30421), falls back to HTTP
+     * @param torMode Whether running in Tor context
+     * @param forceRefresh Ignore provider cache and refresh provider sources
+     * @returns Array of provider base URLs
+     * @throws ProviderBootstrapError if all providers fail to fetch
+     */
+    bootstrapProviders(torMode?: boolean, forceRefresh?: boolean): Promise<string[]>;
+    /**
+     * 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
+     */
+    private bootstrapFromNostr;
+    /**
+     * Bootstrap providers from HTTP endpoint
+     * @param torMode Whether running in Tor context
+     * @param forceRefresh Ignore routstr21 cache and fetch fresh data
+     * @returns Array of provider base URLs
+     */
+    private bootstrapFromHttp;
+    /**
+     * Fetch Routstr review events from Nostr (kind 38425) and disable providers
+     * whose 38421 node pubkey does not have at least one review tagged `t=lgtm`.
+     *
+     * Review events are expected to have:
+     * - `node`: the reviewed 38421 provider event pubkey
+     * - `t`: review label, where `lgtm` means the node looks good
+     *
+     * @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>>, forceRefresh?: boolean): Promise<string[]>;
+    private addProviderNode;
+    /**
+     * Fetch models from all providers and select best-priced options
+     * Uses cache if available and not expired
+     * @param baseUrls List of provider base URLs to fetch from
+     * @param forceRefresh Ignore cache and fetch fresh data
+     * @param onProgress Callback fired after each provider completes with current combined models
+     * @returns Array of unique models with best prices selected
+     */
+    fetchModels(baseUrls: string[], forceRefresh?: boolean, onProgress?: (models: Model[]) => void): Promise<Model[]>;
+    /**
+     * Fetch models from a single provider
+     * @param baseUrl Provider base URL
+     * @returns Array of models from provider
+     */
+    private fetchModelsFromProvider;
+    private isProviderDownError;
+    /**
+     * Get all cached models from all providers
+     * @returns Record mapping baseUrl -> models
+     */
+    getAllCachedModels(): Record<string, Model[]>;
+    /**
+     * Clear cache for a specific provider
+     * @param baseUrl Provider base URL
+     */
+    clearProviderCache(baseUrl: string): void;
+    /**
+     * Clear all model caches
+     */
+    clearAllCache(): void;
+    /**
+     * Filter base URLs based on Tor context
+     * @param baseUrls Provider URLs to filter
+     * @param torMode Whether in Tor context
+     * @returns Filtered URLs appropriate for Tor mode
+     */
+    filterBaseUrlsForTor(baseUrls: string[], torMode: boolean): string[];
+    /**
+     * Get provider endpoints from provider info
+     * @param provider Provider object from directory
+     * @param torMode Whether in Tor context
+     * @returns Array of endpoint URLs
+     */
+    private getProviderEndpoints;
+    /**
+     * Normalize provider URL with trailing slash
+     * @param url URL to normalize
+     * @returns Normalized URL
+     */
+    private normalizeUrl;
+    /**
+     * Fetch routstr21 models from Nostr network (kind 38423)
+     * Uses cache if available and not expired
+     * @returns Array of model IDs or empty array if not found
+     */
+    fetchRoutstr21Models(forceRefresh?: boolean): Promise<string[]>;
+}
+
+/**
+ * MintDiscovery class for discovering mints and provider info
+ * Core responsibility: fetching mint information from providers and caching it
+ */
+
+/**
+ * Configuration for MintDiscovery
+ */
+interface MintDiscoveryConfig {
+    /** Cache TTL in milliseconds (default: 21 minutes) */
+    cacheTTL?: number;
+    /** Optional injectable logger */
+    logger?: SdkLogger;
+}
+/**
+ * MintDiscovery handles mint and provider info discovery
+ * Abstracts away storage details via DiscoveryAdapter
+ */
+declare class MintDiscovery {
+    private adapter;
+    private readonly cacheTTL;
+    private readonly logger;
+    constructor(adapter: DiscoveryAdapter, config?: MintDiscoveryConfig);
+    /**
+     * Fetch mints from all providers via their /v1/info endpoints
+     * Caches mints and full provider info for later access
+     * @param baseUrls List of provider base URLs to fetch from
+     * @returns Object with mints and provider info from all providers
+     */
+    discoverMints(baseUrls: string[], options?: {
+        forceRefresh?: boolean;
+    }): Promise<{
+        mintsFromProviders: Record<string, string[]>;
+        infoFromProviders: Record<string, ProviderInfo>;
+    }>;
+    /**
+     * Get cached mints from all providers
+     * @returns Record mapping baseUrl -> mint URLs
+     */
+    getCachedMints(): Record<string, string[]>;
+    /**
+     * Get cached provider info from all providers
+     * @returns Record mapping baseUrl -> provider info
+     */
+    getCachedProviderInfo(): Record<string, ProviderInfo>;
+    /**
+     * Get mints for a specific provider
+     * @param baseUrl Provider base URL
+     * @returns Array of mint URLs for the provider
+     */
+    getProviderMints(baseUrl: string): string[];
+    /**
+     * Get info for a specific provider
+     * @param baseUrl Provider base URL
+     * @returns Provider info object or null if not found
+     */
+    getProviderInfo(baseUrl: string): ProviderInfo | null;
+    /**
+     * Clear mint cache for a specific provider
+     * @param baseUrl Provider base URL
+     */
+    clearProviderMintCache(baseUrl: string): void;
+    /**
+     * Clear all mint caches
+     */
+    clearAllCache(): void;
+    private isProviderDownError;
+}
+
+export { DiscoveryAdapter, MintDiscovery, ModelManager, type ModelManagerConfig, ProviderInfo };

package/dist/discovery/index.d.ts

@@ -0,0 +1,247 @@
+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
+ * Core responsibility: fetching models from providers, caching them, and selecting the best option
+ * (lowest cost) across multiple providers
+ */
+
+/**
+ * Configuration for ModelManager
+ */
+interface ModelManagerConfig {
+    /** URL to fetch provider directory from */
+    providerDirectoryUrl?: string;
+    /** Additional provider base URLs to include */
+    includeProviderUrls?: string[];
+    /** Provider base URLs to exclude */
+    excludeProviderUrls?: string[];
+    /** 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
+ * Abstracts away storage details via DiscoveryAdapter
+ */
+declare class ModelManager {
+    private adapter;
+    private readonly cacheTTL;
+    private readonly providerDirectoryUrl;
+    private readonly includeProviderUrls;
+    private readonly excludeProviderUrls;
+    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;
+    }): Promise<ModelManager>;
+    /**
+     * Bootstrap provider list from the provider directory
+     * First tries to fetch from Nostr (kind 30421), falls back to HTTP
+     * @param torMode Whether running in Tor context
+     * @param forceRefresh Ignore provider cache and refresh provider sources
+     * @returns Array of provider base URLs
+     * @throws ProviderBootstrapError if all providers fail to fetch
+     */
+    bootstrapProviders(torMode?: boolean, forceRefresh?: boolean): Promise<string[]>;
+    /**
+     * 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
+     */
+    private bootstrapFromNostr;
+    /**
+     * Bootstrap providers from HTTP endpoint
+     * @param torMode Whether running in Tor context
+     * @param forceRefresh Ignore routstr21 cache and fetch fresh data
+     * @returns Array of provider base URLs
+     */
+    private bootstrapFromHttp;
+    /**
+     * Fetch Routstr review events from Nostr (kind 38425) and disable providers
+     * whose 38421 node pubkey does not have at least one review tagged `t=lgtm`.
+     *
+     * Review events are expected to have:
+     * - `node`: the reviewed 38421 provider event pubkey
+     * - `t`: review label, where `lgtm` means the node looks good
+     *
+     * @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>>, forceRefresh?: boolean): Promise<string[]>;
+    private addProviderNode;
+    /**
+     * Fetch models from all providers and select best-priced options
+     * Uses cache if available and not expired
+     * @param baseUrls List of provider base URLs to fetch from
+     * @param forceRefresh Ignore cache and fetch fresh data
+     * @param onProgress Callback fired after each provider completes with current combined models
+     * @returns Array of unique models with best prices selected
+     */
+    fetchModels(baseUrls: string[], forceRefresh?: boolean, onProgress?: (models: Model[]) => void): Promise<Model[]>;
+    /**
+     * Fetch models from a single provider
+     * @param baseUrl Provider base URL
+     * @returns Array of models from provider
+     */
+    private fetchModelsFromProvider;
+    private isProviderDownError;
+    /**
+     * Get all cached models from all providers
+     * @returns Record mapping baseUrl -> models
+     */
+    getAllCachedModels(): Record<string, Model[]>;
+    /**
+     * Clear cache for a specific provider
+     * @param baseUrl Provider base URL
+     */
+    clearProviderCache(baseUrl: string): void;
+    /**
+     * Clear all model caches
+     */
+    clearAllCache(): void;
+    /**
+     * Filter base URLs based on Tor context
+     * @param baseUrls Provider URLs to filter
+     * @param torMode Whether in Tor context
+     * @returns Filtered URLs appropriate for Tor mode
+     */
+    filterBaseUrlsForTor(baseUrls: string[], torMode: boolean): string[];
+    /**
+     * Get provider endpoints from provider info
+     * @param provider Provider object from directory
+     * @param torMode Whether in Tor context
+     * @returns Array of endpoint URLs
+     */
+    private getProviderEndpoints;
+    /**
+     * Normalize provider URL with trailing slash
+     * @param url URL to normalize
+     * @returns Normalized URL
+     */
+    private normalizeUrl;
+    /**
+     * Fetch routstr21 models from Nostr network (kind 38423)
+     * Uses cache if available and not expired
+     * @returns Array of model IDs or empty array if not found
+     */
+    fetchRoutstr21Models(forceRefresh?: boolean): Promise<string[]>;
+}
+
+/**
+ * MintDiscovery class for discovering mints and provider info
+ * Core responsibility: fetching mint information from providers and caching it
+ */
+
+/**
+ * Configuration for MintDiscovery
+ */
+interface MintDiscoveryConfig {
+    /** Cache TTL in milliseconds (default: 21 minutes) */
+    cacheTTL?: number;
+    /** Optional injectable logger */
+    logger?: SdkLogger;
+}
+/**
+ * MintDiscovery handles mint and provider info discovery
+ * Abstracts away storage details via DiscoveryAdapter
+ */
+declare class MintDiscovery {
+    private adapter;
+    private readonly cacheTTL;
+    private readonly logger;
+    constructor(adapter: DiscoveryAdapter, config?: MintDiscoveryConfig);
+    /**
+     * Fetch mints from all providers via their /v1/info endpoints
+     * Caches mints and full provider info for later access
+     * @param baseUrls List of provider base URLs to fetch from
+     * @returns Object with mints and provider info from all providers
+     */
+    discoverMints(baseUrls: string[], options?: {
+        forceRefresh?: boolean;
+    }): Promise<{
+        mintsFromProviders: Record<string, string[]>;
+        infoFromProviders: Record<string, ProviderInfo>;
+    }>;
+    /**
+     * Get cached mints from all providers
+     * @returns Record mapping baseUrl -> mint URLs
+     */
+    getCachedMints(): Record<string, string[]>;
+    /**
+     * Get cached provider info from all providers
+     * @returns Record mapping baseUrl -> provider info
+     */
+    getCachedProviderInfo(): Record<string, ProviderInfo>;
+    /**
+     * Get mints for a specific provider
+     * @param baseUrl Provider base URL
+     * @returns Array of mint URLs for the provider
+     */
+    getProviderMints(baseUrl: string): string[];
+    /**
+     * Get info for a specific provider
+     * @param baseUrl Provider base URL
+     * @returns Provider info object or null if not found
+     */
+    getProviderInfo(baseUrl: string): ProviderInfo | null;
+    /**
+     * Clear mint cache for a specific provider
+     * @param baseUrl Provider base URL
+     */
+    clearProviderMintCache(baseUrl: string): void;
+    /**
+     * Clear all mint caches
+     */
+    clearAllCache(): void;
+    private isProviderDownError;
+}
+
+export { DiscoveryAdapter, MintDiscovery, ModelManager, type ModelManagerConfig, ProviderInfo };