@mcpsovereign/sdk 0.2.2 → 0.2.4

package/dist/index.d.ts

@@ -8,10 +8,13 @@ export { OnboardingWizard } from './onboarding/wizard.js';
 export { AgentHelperMCP, HELPER_TOOLS } from './mcp-helper/index.js';
 export type { MCPTool } from './mcp-helper/index.js';
 export { SOVEREIGN_STARTER_PACK, STARTER_CREDITS, PRODUCT_IDEAS, FEE_STRUCTURE, PLATFORM_CREDENTIALS, DEMO_PURCHASE_FLOW } from './onboarding/starter-kit.js';
+export { LocalCache, createLocalCache, conditionalFetch, batchFetch, prefetchCommonData, CACHE_TTLS, } from './local-cache.js';
 export interface SovereignConfig {
     baseUrl?: string;
     authToken?: string;
     localStorePath?: string;
+    enableLocalCache?: boolean;
+    prefetchOnInit?: boolean;
 }
 export interface ApiResponse<T> {
     success: boolean;
@@ -263,8 +266,33 @@ export declare class SovereignClient {
     private baseUrl;
     private authToken;
     localStore: LocalStoreManager;
+    private localCache;
+    private enableLocalCache;
+    private prefetchOnInit;
+    private initialized;
     constructor(config?: SovereignConfig);
+    /**
+     * Initialize SDK with prefetching
+     * Call this after setting auth token to prefetch common data
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get cache statistics (for debugging/monitoring)
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        entries: string[];
+    } | null;
+    /**
+     * Clear local cache (useful after logout or data changes)
+     */
+    clearCache(): void;
     private request;
+    /**
+     * Cached request - uses local cache with stale-while-revalidate
+     */
+    private cachedRequest;
     authenticate(walletAddress: string, signMessage?: (message: string) => Promise<string>): Promise<ApiResponse<{
         token: string;
         agent: Agent;
@@ -316,7 +344,14 @@ export declare class SovereignClient {
         total_cost: string;
         discount: number;
     }>>;
+    /**
+     * Get product categories (cached locally for 1 hour)
+     */
     getCategories(): Promise<ApiResponse<ProductCategory[]>>;
+    /**
+     * Browse products (cached locally for 5 minutes)
+     * Uses stale-while-revalidate for smooth UX
+     */
     browseProducts(options?: {
         category?: string;
         search?: string;
@@ -329,6 +364,9 @@ export declare class SovereignClient {
         page: number;
         limit: number;
     }>>;
+    /**
+     * Get product details (cached locally for 5 minutes)
+     */
     getProductDetails(productId: string): Promise<ApiResponse<Product & {
         reviews: object[];
     }>>;

package/dist/index.js

@@ -16,6 +16,10 @@ export { OnboardingWizard } from './onboarding/wizard.js';
 export { AgentHelperMCP, HELPER_TOOLS } from './mcp-helper/index.js';
 // Re-export starter kit
 export { SOVEREIGN_STARTER_PACK, STARTER_CREDITS, PRODUCT_IDEAS, FEE_STRUCTURE, PLATFORM_CREDENTIALS, DEMO_PURCHASE_FLOW } from './onboarding/starter-kit.js';
+// Re-export local cache (client-side load offloading)
+export { LocalCache, createLocalCache, conditionalFetch, batchFetch, prefetchCommonData, CACHE_TTLS, } from './local-cache.js';
+// Import for internal use
+import { createLocalCache, prefetchCommonData, CACHE_TTLS } from './local-cache.js';
 // =============================================================================
 // Local Store Manager (runs locally, no credits needed)
 // =============================================================================
@@ -225,33 +229,89 @@ export class SovereignClient {
     baseUrl;
     authToken;
     localStore;
+    localCache = null;
+    enableLocalCache;
+    prefetchOnInit;
+    initialized = false;
     constructor(config = {}) {
         this.baseUrl = config.baseUrl || 'http://localhost:3100/api/v1';
         this.authToken = config.authToken || null;
         this.localStore = new LocalStoreManager(config.localStorePath);
+        this.enableLocalCache = config.enableLocalCache !== false; // Default true
+        this.prefetchOnInit = config.prefetchOnInit !== false; // Default true
+        // Initialize local cache for client-side load offloading
+        if (this.enableLocalCache) {
+            this.localCache = createLocalCache({
+                maxEntries: 500,
+                defaultTTL: CACHE_TTLS.listings,
+                staleWindow: 60 * 1000, // 1 minute stale-while-revalidate
+            });
+        }
+    }
+    /**
+     * Initialize SDK with prefetching
+     * Call this after setting auth token to prefetch common data
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        // Load local store from disk
+        await this.localStore.load();
+        // Prefetch common data to reduce server calls
+        if (this.enableLocalCache && this.localCache && this.prefetchOnInit) {
+            await prefetchCommonData(this.localCache, this.baseUrl.replace('/api/v1', ''), this.authToken || undefined);
+        }
+        this.initialized = true;
+    }
+    /**
+     * Get cache statistics (for debugging/monitoring)
+     */
+    getCacheStats() {
+        return this.localCache?.getStats() || null;
+    }
+    /**
+     * Clear local cache (useful after logout or data changes)
+     */
+    clearCache() {
+        this.localCache?.clear();
     }
     // ---------------------------------------------------------------------------
     // HTTP Methods
     // ---------------------------------------------------------------------------
-    async request(method, path, body) {
+    async request(method, path, body, options) {
         const headers = {
             'Content-Type': 'application/json',
         };
         if (this.authToken) {
             headers['Authorization'] = `Bearer ${this.authToken}`;
         }
+        // Add ETag for conditional requests
+        if (options?.etag) {
+            headers['If-None-Match'] = options.etag;
+        }
         try {
             const response = await fetch(`${this.baseUrl}${path}`, {
                 method,
                 headers,
                 body: body ? JSON.stringify(body) : undefined,
             });
+            // Handle 304 Not Modified (ETag match)
+            if (response.status === 304) {
+                return {
+                    success: true,
+                    data: null,
+                    notModified: true,
+                    etag: options?.etag,
+                };
+            }
             const json = await response.json();
-            // Extract billing info from headers
+            // Extract billing info and ETag from headers
             const creditsCharged = response.headers.get('X-Credits-Charged');
             const creditsRemaining = response.headers.get('X-Credits-Remaining');
+            const newEtag = response.headers.get('ETag') || undefined;
             return {
                 ...json,
+                etag: newEtag,
                 headers: {
                     creditsCharged: creditsCharged ? parseInt(creditsCharged) : undefined,
                     creditsRemaining: creditsRemaining ? parseInt(creditsRemaining) : undefined
@@ -269,6 +329,27 @@ export class SovereignClient {
             };
         }
     }
+    /**
+     * Cached request - uses local cache with stale-while-revalidate
+     */
+    async cachedRequest(cacheKey, path, ttl = CACHE_TTLS.listings) {
+        if (!this.localCache) {
+            return this.request('GET', path);
+        }
+        // Try cache first with stale-while-revalidate
+        const cachedData = await this.localCache.get(cacheKey, async () => {
+            const response = await this.request('GET', path);
+            if (response.success && response.data) {
+                return response.data;
+            }
+            throw new Error(response.error?.message || 'Request failed');
+        }, ttl);
+        if (cachedData) {
+            return { success: true, data: cachedData };
+        }
+        // Fallback to direct request
+        return this.request('GET', path);
+    }
     // ---------------------------------------------------------------------------
     // Authentication (FREE)
     // ---------------------------------------------------------------------------
@@ -365,11 +446,18 @@ export class SovereignClient {
         return this.request('POST', `/plots/${plotId}/rent`, { months });
     }
     // ---------------------------------------------------------------------------
-    // Products (Remote Marketplace)
+    // Products (Remote Marketplace) - Uses local cache for browse operations
     // ---------------------------------------------------------------------------
+    /**
+     * Get product categories (cached locally for 1 hour)
+     */
     async getCategories() {
-        return this.request('GET', '/products/categories');
+        return this.cachedRequest('categories', '/products/categories', CACHE_TTLS.static);
     }
+    /**
+     * Browse products (cached locally for 5 minutes)
+     * Uses stale-while-revalidate for smooth UX
+     */
     async browseProducts(options = {}) {
         const params = new URLSearchParams();
         if (options.category)
@@ -382,10 +470,15 @@ export class SovereignClient {
             params.set('limit', options.limit.toString());
         if (options.sort)
             params.set('sort', options.sort);
-        return this.request('GET', `/products?${params}`);
+        // Cache key includes all filter params
+        const cacheKey = `products:${options.category || 'all'}:${options.search || ''}:${options.page || 1}:${options.limit || 20}:${options.sort || 'newest'}`;
+        return this.cachedRequest(cacheKey, `/products?${params}`, CACHE_TTLS.listings);
     }
+    /**
+     * Get product details (cached locally for 5 minutes)
+     */
     async getProductDetails(productId) {
-        return this.request('GET', `/products/${productId}`);
+        return this.cachedRequest(`product:${productId}`, `/products/${productId}`, CACHE_TTLS.listings);
     }
     async purchaseProduct(productId) {
         return this.request('POST', `/products/${productId}/purchase`);

package/dist/local-cache.d.ts

@@ -0,0 +1,86 @@
+interface CacheConfig {
+    defaultTTL: number;
+    maxEntries: number;
+    staleWindow: number;
+}
+export declare const CACHE_TTLS: {
+    readonly static: number;
+    readonly catalog: number;
+    readonly listings: number;
+    readonly realtime: number;
+    readonly user: number;
+};
+/**
+ * Local cache for SDK - reduces server calls by caching on the client
+ */
+export declare class LocalCache {
+    private cache;
+    private config;
+    private pendingRequests;
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Get from cache, optionally fetching if stale/missing
+     */
+    get<T>(key: string, fetcher?: () => Promise<T>, ttl?: number): Promise<T | null>;
+    /**
+     * Fetch with request deduplication
+     */
+    private fetchAndCache;
+    /**
+     * Set a value in cache
+     */
+    set<T>(key: string, data: T, ttl?: number, etag?: string): void;
+    /**
+     * Check if cache has fresh data for key
+     */
+    has(key: string): boolean;
+    /**
+     * Get the ETag for conditional requests
+     */
+    getETag(key: string): string | undefined;
+    /**
+     * Invalidate specific key
+     */
+    invalidate(key: string): void;
+    /**
+     * Invalidate all keys matching prefix
+     */
+    invalidatePrefix(prefix: string): void;
+    /**
+     * Clear entire cache
+     */
+    clear(): void;
+    /**
+     * Get cache stats
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        entries: string[];
+    };
+}
+/**
+ * Make a conditional request using ETag
+ * Server returns 304 Not Modified if data hasn't changed
+ */
+export declare function conditionalFetch<T>(url: string, etag: string | undefined, options?: RequestInit): Promise<{
+    data: T | null;
+    etag: string | undefined;
+    modified: boolean;
+}>;
+interface BatchItem<T> {
+    key: string;
+    fetcher: () => Promise<T>;
+}
+/**
+ * Batch multiple requests into one with local caching
+ * Reduces round trips to server
+ */
+export declare function batchFetch<T>(cache: LocalCache, items: BatchItem<T>[], ttl?: number): Promise<Map<string, T>>;
+/**
+ * Prefetch common data on SDK initialization
+ * Reduces latency for common operations
+ */
+export declare function prefetchCommonData(cache: LocalCache, apiBase: string, token?: string): Promise<void>;
+export declare const createLocalCache: (config?: Partial<CacheConfig>) => LocalCache;
+export {};

package/dist/local-cache.js

@@ -0,0 +1,257 @@
+// =============================================================================
+// SDK Local Cache - Client-Side Load Offloading
+// =============================================================================
+// Push browsing/catalog data to the client to reduce server load.
+// The SDK maintains a local cache that syncs efficiently with the server.
+// =============================================================================
+const DEFAULT_CONFIG = {
+    defaultTTL: 5 * 60 * 1000, // 5 minutes
+    maxEntries: 1000,
+    staleWindow: 60 * 1000, // 1 minute stale-while-revalidate
+};
+// TTLs by data type
+export const CACHE_TTLS = {
+    // Static data - levels, achievements, tiers (cache for hours)
+    static: 60 * 60 * 1000, // 1 hour
+    // Semi-static - cosmetics, loot crates, categories
+    catalog: 30 * 60 * 1000, // 30 minutes
+    // Dynamic - product listings, clan lists
+    listings: 5 * 60 * 1000, // 5 minutes
+    // Frequently changing - leaderboards, dashboards
+    realtime: 60 * 1000, // 1 minute
+    // User-specific - balance, profile
+    user: 30 * 1000, // 30 seconds
+};
+/**
+ * Local cache for SDK - reduces server calls by caching on the client
+ */
+export class LocalCache {
+    cache = new Map();
+    config;
+    pendingRequests = new Map();
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Get from cache, optionally fetching if stale/missing
+     */
+    async get(key, fetcher, ttl = this.config.defaultTTL) {
+        const entry = this.cache.get(key);
+        const now = Date.now();
+        // Fresh cache hit
+        if (entry && (now - entry.timestamp) < entry.ttl) {
+            return entry.data;
+        }
+        // Stale-while-revalidate: return stale data while fetching fresh
+        if (entry && (now - entry.timestamp) < (entry.ttl + this.config.staleWindow)) {
+            if (fetcher) {
+                // Background refresh (don't await)
+                this.fetchAndCache(key, fetcher, ttl).catch(() => { });
+            }
+            return entry.data;
+        }
+        // Cache miss or expired - fetch if we have a fetcher
+        if (fetcher) {
+            return this.fetchAndCache(key, fetcher, ttl);
+        }
+        return null;
+    }
+    /**
+     * Fetch with request deduplication
+     */
+    async fetchAndCache(key, fetcher, ttl) {
+        // Check if request is already in flight (deduplication)
+        const pending = this.pendingRequests.get(key);
+        if (pending) {
+            return pending;
+        }
+        // Start the fetch
+        const fetchPromise = (async () => {
+            try {
+                const data = await fetcher();
+                this.set(key, data, ttl);
+                return data;
+            }
+            finally {
+                this.pendingRequests.delete(key);
+            }
+        })();
+        this.pendingRequests.set(key, fetchPromise);
+        return fetchPromise;
+    }
+    /**
+     * Set a value in cache
+     */
+    set(key, data, ttl = this.config.defaultTTL, etag) {
+        // Enforce max entries (LRU eviction)
+        if (this.cache.size >= this.config.maxEntries) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        this.cache.set(key, {
+            data,
+            timestamp: Date.now(),
+            ttl,
+            etag,
+        });
+    }
+    /**
+     * Check if cache has fresh data for key
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        return (Date.now() - entry.timestamp) < entry.ttl;
+    }
+    /**
+     * Get the ETag for conditional requests
+     */
+    getETag(key) {
+        return this.cache.get(key)?.etag;
+    }
+    /**
+     * Invalidate specific key
+     */
+    invalidate(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Invalidate all keys matching prefix
+     */
+    invalidatePrefix(prefix) {
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /**
+     * Clear entire cache
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache stats
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.config.maxEntries,
+            entries: Array.from(this.cache.keys()),
+        };
+    }
+}
+// =============================================================================
+// Conditional Request Helpers
+// =============================================================================
+/**
+ * Make a conditional request using ETag
+ * Server returns 304 Not Modified if data hasn't changed
+ */
+export async function conditionalFetch(url, etag, options = {}) {
+    const headers = {
+        ...(options.headers || {}),
+    };
+    if (etag) {
+        headers['If-None-Match'] = etag;
+    }
+    const response = await fetch(url, {
+        ...options,
+        headers,
+    });
+    // Not modified - use cached data
+    if (response.status === 304) {
+        return {
+            data: null,
+            etag,
+            modified: false,
+        };
+    }
+    const data = await response.json();
+    const newEtag = response.headers.get('ETag') || undefined;
+    return {
+        data: data,
+        etag: newEtag,
+        modified: true,
+    };
+}
+/**
+ * Batch multiple requests into one with local caching
+ * Reduces round trips to server
+ */
+export async function batchFetch(cache, items, ttl = CACHE_TTLS.listings) {
+    const results = new Map();
+    const toFetch = [];
+    // Check cache first
+    for (const item of items) {
+        const cached = await cache.get(item.key);
+        if (cached) {
+            results.set(item.key, cached);
+        }
+        else {
+            toFetch.push(item);
+        }
+    }
+    // Fetch missing items in parallel
+    if (toFetch.length > 0) {
+        const fetchPromises = toFetch.map(async (item) => {
+            try {
+                const data = await item.fetcher();
+                cache.set(item.key, data, ttl);
+                results.set(item.key, data);
+            }
+            catch (error) {
+                // Individual failures don't break the batch
+                console.warn(`Failed to fetch ${item.key}:`, error);
+            }
+        });
+        await Promise.all(fetchPromises);
+    }
+    return results;
+}
+// =============================================================================
+// Prefetch Strategy
+// =============================================================================
+/**
+ * Prefetch common data on SDK initialization
+ * Reduces latency for common operations
+ */
+export async function prefetchCommonData(cache, apiBase, token) {
+    const headers = token
+        ? { Authorization: `Bearer ${token}` }
+        : {};
+    const prefetchItems = [
+        // Static data - fetch once, cache long
+        { key: 'levels', url: '/api/v1/gamification/levels', ttl: CACHE_TTLS.static },
+        { key: 'achievements', url: '/api/v1/gamification/achievements', ttl: CACHE_TTLS.static },
+        { key: 'trades', url: '/api/v1/trades', ttl: CACHE_TTLS.static },
+        { key: 'clan-tiers', url: '/api/v1/clans/tiers', ttl: CACHE_TTLS.static },
+        { key: 'clan-roles', url: '/api/v1/clans/roles', ttl: CACHE_TTLS.static },
+        // Catalog data - cache moderately
+        { key: 'categories', url: '/api/v1/products/categories', ttl: CACHE_TTLS.catalog },
+        { key: 'cosmetics', url: '/api/v1/monetization/cosmetics', ttl: CACHE_TTLS.catalog },
+        { key: 'loot-crates', url: '/api/v1/monetization/loot', ttl: CACHE_TTLS.catalog },
+        { key: 'subscriptions', url: '/api/v1/monetization/subscriptions', ttl: CACHE_TTLS.catalog },
+    ];
+    // Fetch in parallel but don't fail if some fail
+    await Promise.allSettled(prefetchItems.map(async (item) => {
+        try {
+            const response = await fetch(`${apiBase}${item.url}`, { headers });
+            if (response.ok) {
+                const json = await response.json();
+                cache.set(item.key, json.data ?? json, item.ttl);
+            }
+        }
+        catch {
+            // Silent fail - prefetch is best-effort
+        }
+    }));
+}
+// =============================================================================
+// Exports
+// =============================================================================
+export const createLocalCache = (config) => new LocalCache(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpsovereign/sdk",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "TypeScript SDK for mcpSovereign - The AI Agent Marketplace",
   "type": "module",
   "main": "dist/index.js",