@routstr/sdk 0.1.0 → 0.1.2

package/dist/discovery/index.d.mts

@@ -0,0 +1,186 @@
+import { D as DiscoveryAdapter } from '../interfaces-nanJOqdW.mjs';
+import { M as Model, P as ProviderInfo } from '../types-BlHjmWRK.mjs';
+
+/**
+ * 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: 21 minutes) */
+    cacheTTL?: number;
+}
+/**
+ * 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;
+    constructor(adapter: DiscoveryAdapter, config?: ModelManagerConfig);
+    /**
+     * Get the list of bootstrapped provider base URLs
+     * @returns Array of provider base URLs
+     */
+    getBaseUrls(): string[];
+    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
+     * @returns Array of provider base URLs
+     * @throws ProviderBootstrapError if all providers fail to fetch
+     */
+    bootstrapProviders(torMode?: boolean): Promise<string[]>;
+    /**
+     * Bootstrap providers from Nostr network (kind 30421)
+     * @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
+     * @returns Array of provider base URLs
+     */
+    private bootstrapFromHttp;
+    /**
+     * 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
+     * @returns Array of unique models with best prices selected
+     */
+    fetchModels(baseUrls: string[], forceRefresh?: boolean): 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)
+     * @returns Array of model IDs or empty array if not found
+     */
+    fetchRoutstr21Models(): 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;
+}
+/**
+ * MintDiscovery handles mint and provider info discovery
+ * Abstracts away storage details via DiscoveryAdapter
+ */
+declare class MintDiscovery {
+    private adapter;
+    private readonly cacheTTL;
+    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,186 @@
+import { D as DiscoveryAdapter } from '../interfaces-Dnrvxr6N.js';
+import { M as Model, P as ProviderInfo } from '../types-BlHjmWRK.js';
+
+/**
+ * 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: 21 minutes) */
+    cacheTTL?: number;
+}
+/**
+ * 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;
+    constructor(adapter: DiscoveryAdapter, config?: ModelManagerConfig);
+    /**
+     * Get the list of bootstrapped provider base URLs
+     * @returns Array of provider base URLs
+     */
+    getBaseUrls(): string[];
+    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
+     * @returns Array of provider base URLs
+     * @throws ProviderBootstrapError if all providers fail to fetch
+     */
+    bootstrapProviders(torMode?: boolean): Promise<string[]>;
+    /**
+     * Bootstrap providers from Nostr network (kind 30421)
+     * @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
+     * @returns Array of provider base URLs
+     */
+    private bootstrapFromHttp;
+    /**
+     * 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
+     * @returns Array of unique models with best prices selected
+     */
+    fetchModels(baseUrls: string[], forceRefresh?: boolean): 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)
+     * @returns Array of model IDs or empty array if not found
+     */
+    fetchRoutstr21Models(): 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;
+}
+/**
+ * MintDiscovery handles mint and provider info discovery
+ * Abstracts away storage details via DiscoveryAdapter
+ */
+declare class MintDiscovery {
+    private adapter;
+    private readonly cacheTTL;
+    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 };