@proveanything/smartlinks 1.4.7 → 1.4.8

package/dist/cache.js

@@ -3,6 +3,27 @@
 // =============================================================================
 // In-memory cache store
 const memoryCache = new Map();
+/**
+ * Clear session-scoped caches on page load.
+ * SessionStorage persists across normal refreshes, so we explicitly clear it
+ * on load to ensure fresh data after F5/Ctrl+F5. LocalStorage is preserved
+ * for true offline/persistent caching scenarios.
+ */
+function clearSessionCacheOnLoad() {
+    if (typeof sessionStorage === 'undefined')
+        return;
+    try {
+        const sessionKeys = Object.keys(sessionStorage).filter(k => k.startsWith('smartlinks:cache:'));
+        sessionKeys.forEach(k => sessionStorage.removeItem(k));
+    }
+    catch (_a) {
+        // Storage may not be available
+    }
+}
+// Auto-clear session caches on page load (browser only)
+if (typeof window !== 'undefined') {
+    clearSessionCacheOnLoad();
+}
 /**
  * Get cached value or fetch fresh.
  *

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.4.7  |  Generated: 2026-02-21T14:49:14.374Z
+Version: 1.4.8  |  Generated: 2026-02-22T11:38:27.387Z
 
 This is a concise summary of all available API functions and types.
 
@@ -120,8 +120,9 @@ Returns true if the SDK currently has any auth credential set (bearer token or A
   persistence?: 'none' | 'indexeddb'
   persistenceTtlMs?: number
   serveStaleOnOffline?: boolean
+  clearOnPageLoad?: boolean
 }) → `void`
-Configure the SDK's built-in in-memory GET cache. The cache is transparent — it sits inside the HTTP layer and requires no changes to your existing API calls. All GET requests benefit automatically. Per-resource rules (collections/products → 1 h, proofs → 30 s, etc.) override this value. in-memory only (`'none'`, default). Ignored in Node.js. fallback, from the original fetch time (default: 7 days). `SmartlinksOfflineError` with stale data instead of propagating the network error. ```ts // Enable IndexedDB persistence for offline support configureSdkCache({ persistence: 'indexeddb' }) // Disable cache entirely in test environments configureSdkCache({ enabled: false }) ```
+Configure the SDK's built-in in-memory GET cache. The cache is transparent — it sits inside the HTTP layer and requires no changes to your existing API calls. All GET requests benefit automatically. Per-resource rules (collections/products → 1 h, proofs → 30 s, etc.) override this value. in-memory only (`'none'`, default). Ignored in Node.js. fallback, from the original fetch time (default: 7 days). `SmartlinksOfflineError` with stale data instead of propagating the network error. caches on page load/refresh. IndexedDB persists for offline. ```ts // Enable IndexedDB persistence for offline support configureSdkCache({ persistence: 'indexeddb' }) // Disable cache entirely in test environments configureSdkCache({ enabled: false }) // Keep caches across page refreshes (not recommended for production) configureSdkCache({ clearOnPageLoad: false }) ```
 
 **invalidateCache**(urlPattern?: string) → `void`
 Manually invalidate entries in the SDK's GET cache. *contains* this string is removed. Omit (or pass `undefined`) to wipe the entire cache. ```ts invalidateCache()                     // clear everything invalidateCache('/collection/abc123') // one specific collection invalidateCache('/product/')          // all product responses ```

package/dist/docs/caching.md

@@ -0,0 +1,186 @@
+# Caching Strategy
+
+## Overview
+
+The Smartlinks SDK implements a multi-tier caching system designed to balance performance with data freshness:
+
+1. **In-Memory Cache (L1)** - Fastest, cleared on page refresh
+2. **SessionStorage** - Cleared on page refresh (not tab close)
+3. **IndexedDB (L2)** - Persists across refreshes for offline support
+
+## Cache Behavior on Page Refresh
+
+### Default Behavior (Recommended)
+
+When you refresh the page (F5, Ctrl+F5, or window reload):
+
+- ✅ **In-memory cache** - Automatically cleared (module re-initialization)
+- ✅ **SessionStorage** - Explicitly cleared on page load
+- ✅ **IndexedDB** - Preserved for offline fallback only
+
+This ensures that **page refreshes always fetch fresh data from the server**, while maintaining offline capabilities.
+
+### How It Works
+
+1. **During browsing (same page load)**:
+   - API requests are cached in memory and sessionStorage
+   - Subsequent identical requests serve from cache (fast!)
+   - TTL rules determine cache freshness (30s - 1h depending on resource)
+
+2. **On page refresh**:
+   - Module re-initialization clears in-memory cache
+   - `clearSessionCacheOnLoad()` runs automatically
+   - SessionStorage caches are removed
+   - Fresh network requests are made
+
+3. **When offline** (with `persistence: 'indexeddb'`):
+   - Network request fails
+   - SDK checks IndexedDB for stale data
+   - If found and within 7-day TTL, throws `SmartlinksOfflineError` with data
+   - App can catch this and use stale data gracefully
+
+## Cache Configuration
+
+### Enable IndexedDB Persistence
+
+```typescript
+import { configureSdkCache } from '@smartlinks/sdk';
+
+// Enable offline support via IndexedDB
+configureSdkCache({
+  persistence: 'indexeddb',
+  persistenceTtlMs: 7 * 24 * 60 * 60_000, // 7 days
+  serveStaleOnOffline: true,
+});
+```
+
+### Disable Clear-on-Refresh (Not Recommended)
+
+```typescript
+// Keep caches across page refreshes
+// ⚠️ Not recommended for production - you'll serve stale data after refresh
+configureSdkCache({
+  clearOnPageLoad: false,
+});
+```
+
+### Disable Caching Entirely
+
+```typescript
+// Useful for testing or debugging
+configureSdkCache({
+  enabled: false,
+});
+```
+
+## Cache Storage Types
+
+### `storage: 'memory'` (Default)
+- Lives in JavaScript memory (Map)
+- Cleared on page refresh
+- Fastest access
+- No quota limits
+
+### `storage: 'session'`
+- Lives in `sessionStorage`
+- **Cleared on page load** (new behavior)
+- Survives navigation within same session
+- ~5-10MB quota
+
+### `storage: 'local'`
+- Lives in `localStorage`
+- Persists across browser restarts
+- Use sparingly for truly persistent data
+- ~5-10MB quota
+
+### `persistence: 'indexeddb'`
+- Lives in IndexedDB (L2 cache)
+- Persists across refreshes and restarts
+- **Only used as offline fallback**, not for normal requests
+- ~50MB+ quota
+
+## TTL Rules
+
+Different API resources have different cache lifetimes:
+
+| Resource | TTL | Reason |
+|----------|-----|--------|
+| `/proof/*` | 30 seconds | Proofs change frequently |
+| `/attestation/*` | 2 minutes | Attestations update regularly |
+| `/product/*` | 1 hour | Products are relatively stable |
+| `/variant/*` | 1 hour | Variants rarely change |
+| `/collection/*` | 1 hour | Collections are stable |
+| Everything else | 1 minute | Default safety |
+
+## Manual Cache Control
+
+### Invalidate Specific Resource
+
+```typescript
+import { invalidateCache } from '@smartlinks/sdk';
+
+// Clear cache for a specific collection
+invalidateCache('/collection/abc123');
+
+// Clear all product caches
+invalidateCache('/product/');
+```
+
+### Clear All Caches
+
+```typescript
+import { invalidateCache } from '@smartlinks/sdk';
+
+// Nuclear option - clear everything
+invalidateCache();
+```
+
+## Best Practices
+
+1. **Default is best** - The SDK defaults are designed for optimal behavior
+2. **Enable IndexedDB for PWAs** - If building offline-first apps
+3. **Don't disable clearOnPageLoad** - Users expect fresh data after refresh
+4. **Use invalidateCache() after mutations** - SDK does this automatically for you
+5. **Trust the TTL rules** - They're tuned for smartlinks.app API behavior
+
+## Offline Mode Example
+
+```typescript
+import { collection, SmartlinksOfflineError } from '@smartlinks/sdk';
+
+try {
+  const data = await collection.get('abc123');
+  // Fresh data from server
+} catch (error) {
+  if (error instanceof SmartlinksOfflineError) {
+    // Network failed, but we have stale data
+    console.warn('Offline - using stale data from', error.cachedAt);
+    const staleData = error.data;
+    // Display stale data with a banner
+  } else {
+    // Real error - no offline data available
+    throw error;
+  }
+}
+```
+
+## Migration from Old Behavior
+
+If you previously relied on caches persisting across refreshes:
+
+```typescript
+// Old (implicit) behavior:
+// - SessionStorage survived refreshes
+// - Apps might see stale data after F5
+
+// New (explicit) behavior:
+configureSdkCache({
+  clearOnPageLoad: true, // default - fresh data on refresh
+});
+
+// If you REALLY need old behavior (not recommended):
+configureSdkCache({
+  clearOnPageLoad: false,
+  persistence: 'indexeddb', // move to IndexedDB instead
+});
+```

package/dist/http.d.ts

@@ -82,6 +82,8 @@ export declare function hasAuthCredentials(): boolean;
  * @param options.serveStaleOnOffline - When `true` (default) and persistence is on, throw
  *                                      `SmartlinksOfflineError` with stale data instead of
  *                                      propagating the network error.
+ * @param options.clearOnPageLoad     - When `true` (default), clear in-memory and sessionStorage
+ *                                      caches on page load/refresh. IndexedDB persists for offline.
  *
  * @example
  * ```ts
@@ -90,6 +92,9 @@ export declare function hasAuthCredentials(): boolean;
  *
  * // Disable cache entirely in test environments
  * configureSdkCache({ enabled: false })
+ *
+ * // Keep caches across page refreshes (not recommended for production)
+ * configureSdkCache({ clearOnPageLoad: false })
  * ```
  */
 export declare function configureSdkCache(options: {
@@ -99,6 +104,7 @@ export declare function configureSdkCache(options: {
     persistence?: 'none' | 'indexeddb';
     persistenceTtlMs?: number;
     serveStaleOnOffline?: boolean;
+    clearOnPageLoad?: boolean;
 }): void;
 /**
  * Manually invalidate entries in the SDK's GET cache.

package/dist/http.js

@@ -31,6 +31,8 @@ let cacheDefaultTtlMs = 60000; // 60 seconds
 let cacheMaxEntries = 200;
 /** Persistence backend for the L2 cache. 'none' (default) disables IndexedDB persistence. */
 let cachePersistence = 'none';
+/** When true (default), clear in-memory and sessionStorage caches on page load/refresh. */
+let cacheClearOnPageLoad = true;
 /**
  * How long L2 (IndexedDB) entries are considered valid as an offline stale fallback,
  * measured from the original network fetch time (default: 7 days).
@@ -89,6 +91,31 @@ function evictLruIfNeeded() {
             break;
     }
 }
+/**
+ * Clear session-scoped caches (in-memory + sessionStorage) on page load.
+ * This ensures that a page refresh always fetches fresh data, while
+ * IndexedDB persists for true offline support.
+ *
+ * Automatically called once when this module loads in a browser environment.
+ */
+function clearSessionCachesOnPageLoad() {
+    if (typeof window === 'undefined')
+        return; // Node.js environment
+    httpCache.clear();
+    try {
+        if (typeof sessionStorage !== 'undefined') {
+            const sessionKeys = Object.keys(sessionStorage).filter(k => k.startsWith('smartlinks:cache:'));
+            sessionKeys.forEach(k => sessionStorage.removeItem(k));
+        }
+    }
+    catch (_a) {
+        // Storage may not be available (private browsing, etc.)
+    }
+}
+// Auto-clear session caches on page load (browser only)
+if (typeof window !== 'undefined' && cacheClearOnPageLoad) {
+    clearSessionCachesOnPageLoad();
+}
 /**
  * Return cached data for a key if it exists and is within TTL.
  * Promotes the hit to MRU position. Returns null when missing, expired, or in-flight.
@@ -416,6 +443,8 @@ export function hasAuthCredentials() {
  * @param options.serveStaleOnOffline - When `true` (default) and persistence is on, throw
  *                                      `SmartlinksOfflineError` with stale data instead of
  *                                      propagating the network error.
+ * @param options.clearOnPageLoad     - When `true` (default), clear in-memory and sessionStorage
+ *                                      caches on page load/refresh. IndexedDB persists for offline.
  *
  * @example
  * ```ts
@@ -424,6 +453,9 @@ export function hasAuthCredentials() {
  *
  * // Disable cache entirely in test environments
  * configureSdkCache({ enabled: false })
+ *
+ * // Keep caches across page refreshes (not recommended for production)
+ * configureSdkCache({ clearOnPageLoad: false })
  * ```
  */
 export function configureSdkCache(options) {
@@ -439,6 +471,8 @@ export function configureSdkCache(options) {
         cachePersistenceTtlMs = options.persistenceTtlMs;
     if (options.serveStaleOnOffline !== undefined)
         cacheServeStaleOnOffline = options.serveStaleOnOffline;
+    if (options.clearOnPageLoad !== undefined)
+        cacheClearOnPageLoad = options.clearOnPageLoad;
 }
 /**
  * Manually invalidate entries in the SDK's GET cache.

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.4.7  |  Generated: 2026-02-21T14:49:14.374Z
+Version: 1.4.8  |  Generated: 2026-02-22T11:38:27.387Z
 
 This is a concise summary of all available API functions and types.
 
@@ -120,8 +120,9 @@ Returns true if the SDK currently has any auth credential set (bearer token or A
   persistence?: 'none' | 'indexeddb'
   persistenceTtlMs?: number
   serveStaleOnOffline?: boolean
+  clearOnPageLoad?: boolean
 }) → `void`
-Configure the SDK's built-in in-memory GET cache. The cache is transparent — it sits inside the HTTP layer and requires no changes to your existing API calls. All GET requests benefit automatically. Per-resource rules (collections/products → 1 h, proofs → 30 s, etc.) override this value. in-memory only (`'none'`, default). Ignored in Node.js. fallback, from the original fetch time (default: 7 days). `SmartlinksOfflineError` with stale data instead of propagating the network error. ```ts // Enable IndexedDB persistence for offline support configureSdkCache({ persistence: 'indexeddb' }) // Disable cache entirely in test environments configureSdkCache({ enabled: false }) ```
+Configure the SDK's built-in in-memory GET cache. The cache is transparent — it sits inside the HTTP layer and requires no changes to your existing API calls. All GET requests benefit automatically. Per-resource rules (collections/products → 1 h, proofs → 30 s, etc.) override this value. in-memory only (`'none'`, default). Ignored in Node.js. fallback, from the original fetch time (default: 7 days). `SmartlinksOfflineError` with stale data instead of propagating the network error. caches on page load/refresh. IndexedDB persists for offline. ```ts // Enable IndexedDB persistence for offline support configureSdkCache({ persistence: 'indexeddb' }) // Disable cache entirely in test environments configureSdkCache({ enabled: false }) // Keep caches across page refreshes (not recommended for production) configureSdkCache({ clearOnPageLoad: false }) ```
 
 **invalidateCache**(urlPattern?: string) → `void`
 Manually invalidate entries in the SDK's GET cache. *contains* this string is removed. Omit (or pass `undefined`) to wipe the entire cache. ```ts invalidateCache()                     // clear everything invalidateCache('/collection/abc123') // one specific collection invalidateCache('/product/')          // all product responses ```

package/docs/caching.md

@@ -0,0 +1,186 @@
+# Caching Strategy
+
+## Overview
+
+The Smartlinks SDK implements a multi-tier caching system designed to balance performance with data freshness:
+
+1. **In-Memory Cache (L1)** - Fastest, cleared on page refresh
+2. **SessionStorage** - Cleared on page refresh (not tab close)
+3. **IndexedDB (L2)** - Persists across refreshes for offline support
+
+## Cache Behavior on Page Refresh
+
+### Default Behavior (Recommended)
+
+When you refresh the page (F5, Ctrl+F5, or window reload):
+
+- ✅ **In-memory cache** - Automatically cleared (module re-initialization)
+- ✅ **SessionStorage** - Explicitly cleared on page load
+- ✅ **IndexedDB** - Preserved for offline fallback only
+
+This ensures that **page refreshes always fetch fresh data from the server**, while maintaining offline capabilities.
+
+### How It Works
+
+1. **During browsing (same page load)**:
+   - API requests are cached in memory and sessionStorage
+   - Subsequent identical requests serve from cache (fast!)
+   - TTL rules determine cache freshness (30s - 1h depending on resource)
+
+2. **On page refresh**:
+   - Module re-initialization clears in-memory cache
+   - `clearSessionCacheOnLoad()` runs automatically
+   - SessionStorage caches are removed
+   - Fresh network requests are made
+
+3. **When offline** (with `persistence: 'indexeddb'`):
+   - Network request fails
+   - SDK checks IndexedDB for stale data
+   - If found and within 7-day TTL, throws `SmartlinksOfflineError` with data
+   - App can catch this and use stale data gracefully
+
+## Cache Configuration
+
+### Enable IndexedDB Persistence
+
+```typescript
+import { configureSdkCache } from '@smartlinks/sdk';
+
+// Enable offline support via IndexedDB
+configureSdkCache({
+  persistence: 'indexeddb',
+  persistenceTtlMs: 7 * 24 * 60 * 60_000, // 7 days
+  serveStaleOnOffline: true,
+});
+```
+
+### Disable Clear-on-Refresh (Not Recommended)
+
+```typescript
+// Keep caches across page refreshes
+// ⚠️ Not recommended for production - you'll serve stale data after refresh
+configureSdkCache({
+  clearOnPageLoad: false,
+});
+```
+
+### Disable Caching Entirely
+
+```typescript
+// Useful for testing or debugging
+configureSdkCache({
+  enabled: false,
+});
+```
+
+## Cache Storage Types
+
+### `storage: 'memory'` (Default)
+- Lives in JavaScript memory (Map)
+- Cleared on page refresh
+- Fastest access
+- No quota limits
+
+### `storage: 'session'`
+- Lives in `sessionStorage`
+- **Cleared on page load** (new behavior)
+- Survives navigation within same session
+- ~5-10MB quota
+
+### `storage: 'local'`
+- Lives in `localStorage`
+- Persists across browser restarts
+- Use sparingly for truly persistent data
+- ~5-10MB quota
+
+### `persistence: 'indexeddb'`
+- Lives in IndexedDB (L2 cache)
+- Persists across refreshes and restarts
+- **Only used as offline fallback**, not for normal requests
+- ~50MB+ quota
+
+## TTL Rules
+
+Different API resources have different cache lifetimes:
+
+| Resource | TTL | Reason |
+|----------|-----|--------|
+| `/proof/*` | 30 seconds | Proofs change frequently |
+| `/attestation/*` | 2 minutes | Attestations update regularly |
+| `/product/*` | 1 hour | Products are relatively stable |
+| `/variant/*` | 1 hour | Variants rarely change |
+| `/collection/*` | 1 hour | Collections are stable |
+| Everything else | 1 minute | Default safety |
+
+## Manual Cache Control
+
+### Invalidate Specific Resource
+
+```typescript
+import { invalidateCache } from '@smartlinks/sdk';
+
+// Clear cache for a specific collection
+invalidateCache('/collection/abc123');
+
+// Clear all product caches
+invalidateCache('/product/');
+```
+
+### Clear All Caches
+
+```typescript
+import { invalidateCache } from '@smartlinks/sdk';
+
+// Nuclear option - clear everything
+invalidateCache();
+```
+
+## Best Practices
+
+1. **Default is best** - The SDK defaults are designed for optimal behavior
+2. **Enable IndexedDB for PWAs** - If building offline-first apps
+3. **Don't disable clearOnPageLoad** - Users expect fresh data after refresh
+4. **Use invalidateCache() after mutations** - SDK does this automatically for you
+5. **Trust the TTL rules** - They're tuned for smartlinks.app API behavior
+
+## Offline Mode Example
+
+```typescript
+import { collection, SmartlinksOfflineError } from '@smartlinks/sdk';
+
+try {
+  const data = await collection.get('abc123');
+  // Fresh data from server
+} catch (error) {
+  if (error instanceof SmartlinksOfflineError) {
+    // Network failed, but we have stale data
+    console.warn('Offline - using stale data from', error.cachedAt);
+    const staleData = error.data;
+    // Display stale data with a banner
+  } else {
+    // Real error - no offline data available
+    throw error;
+  }
+}
+```
+
+## Migration from Old Behavior
+
+If you previously relied on caches persisting across refreshes:
+
+```typescript
+// Old (implicit) behavior:
+// - SessionStorage survived refreshes
+// - Apps might see stale data after F5
+
+// New (explicit) behavior:
+configureSdkCache({
+  clearOnPageLoad: true, // default - fresh data on refresh
+});
+
+// If you REALLY need old behavior (not recommended):
+configureSdkCache({
+  clearOnPageLoad: false,
+  persistence: 'indexeddb', // move to IndexedDB instead
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.4.7",
+  "version": "1.4.8",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",