@proveanything/smartlinks-auth-ui 0.5.22 → 0.6.0

package/ACCOUNT_CACHING.md

@@ -0,0 +1,349 @@
+# Account Information Caching
+
+The auth module provides intelligent caching for Smartlinks account information, reducing API calls and improving performance.
+
+## Basic Usage
+
+### Get Account Information
+
+```typescript
+import { useAuth } from '@smartlinks/auth-ui';
+
+function MyComponent() {
+  const auth = useAuth();
+  
+  useEffect(() => {
+    const loadAccount = async () => {
+      try {
+        // Smart caching - uses cache if fresh, fetches if stale
+        const account = await auth.getAccount();
+        console.log('Account:', account);
+      } catch (error) {
+        console.error('Failed to load account:', error);
+      }
+    };
+    
+    if (auth.isAuthenticated) {
+      loadAccount();
+    }
+  }, [auth.isAuthenticated]);
+}
+```
+
+### Force Refresh
+
+```typescript
+// Bypass cache and fetch fresh data
+const account = await auth.getAccount(true);
+
+// Or use convenience method
+const account = await auth.refreshAccount();
+```
+
+### Access Cached Data Synchronously
+
+```typescript
+// Access cached account info without triggering API call
+const { accountInfo } = useAuth();
+
+if (accountInfo) {
+  console.log('Cached account:', accountInfo);
+}
+```
+
+## Configuration
+
+### Cache TTL
+
+Configure how long account data is cached:
+
+```typescript
+<AuthProvider accountCacheTTL={10 * 60 * 1000}> {/* 10 minutes */}
+  <App />
+</AuthProvider>
+```
+
+### Preload on Login
+
+Automatically fetch account info on login:
+
+```typescript
+<AuthProvider preloadAccountInfo={true}>
+  <App />
+</AuthProvider>
+```
+
+## Caching Strategy
+
+**When cache is used:**
+- Account info cached for 5 minutes by default (configurable)
+- Subsequent calls return cached data without API request
+- Cache persists across page refreshes (IndexedDB/localStorage)
+- Cache synchronized across browser tabs
+
+**When API is called:**
+- First `getAccount()` call after login
+- Cache has expired (past TTL)
+- `forceRefresh` parameter is true
+- Cache is cleared or missing
+
+**Fallback behavior:**
+- If API call fails, returns stale cached data if available
+- Logs warning when returning stale data
+- Throws error only if no cache exists and API fails
+
+## Cross-Tab Synchronization
+
+When one tab fetches fresh account info, all other tabs automatically receive the updated data:
+
+```typescript
+useEffect(() => {
+  const unsubscribe = auth.onAuthStateChange((event) => {
+    if (event.type === 'ACCOUNT_REFRESH') {
+      console.log('Account refreshed:', event.accountInfo);
+      // Update UI with fresh account data
+    }
+  });
+  
+  return unsubscribe;
+}, []);
+```
+
+## Best Practices
+
+### 1. Use Cached Data for Frequent Access
+
+```typescript
+// Good - uses cached data
+const { accountInfo } = useAuth();
+const userName = accountInfo?.name;
+
+// Avoid - triggers API call on every render if cache expired
+useEffect(() => {
+  auth.getAccount().then(account => setName(account.name));
+}, []);
+```
+
+### 2. Refresh on User-Initiated Actions
+
+```typescript
+function RefreshButton() {
+  const auth = useAuth();
+  
+  const handleRefresh = async () => {
+    await auth.refreshAccount(); // Force fresh fetch
+    toast.success('Account refreshed');
+  };
+  
+  return <button onClick={handleRefresh}>Refresh Account</button>;
+}
+```
+
+### 3. Clear Cache on Sensitive Operations
+
+```typescript
+// After updating user profile via separate API
+await updateUserProfile({ displayName: 'New Name' });
+
+// Clear account cache to ensure fresh data on next fetch
+await auth.clearAccountCache();
+
+// Fetch fresh data
+const updatedAccount = await auth.getAccount();
+```
+
+### 4. Handle Loading and Error States
+
+```typescript
+function AccountDisplay() {
+  const auth = useAuth();
+  const [account, setAccount] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  
+  useEffect(() => {
+    if (auth.isAuthenticated) {
+      auth.getAccount()
+        .then(setAccount)
+        .catch(setError)
+        .finally(() => setLoading(false));
+    }
+  }, [auth.isAuthenticated]);
+  
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!account) return <div>No account data</div>;
+  
+  return <div>Welcome, {account.name}!</div>;
+}
+```
+
+## Common Patterns
+
+### Dashboard Component
+
+```typescript
+function Dashboard() {
+  const auth = useAuth();
+  const [account, setAccount] = useState(auth.accountInfo); // Start with cached
+  
+  useEffect(() => {
+    // Load account info, using cache if available
+    auth.getAccount().then(setAccount);
+  }, []);
+  
+  return (
+    <div>
+      <h1>Welcome, {account?.name}</h1>
+      <p>Email: {account?.email}</p>
+      <p>Collections: {Object.keys(account?.sites || {}).length}</p>
+    </div>
+  );
+}
+```
+
+### Permission Check
+
+```typescript
+function AdminPanel() {
+  const auth = useAuth();
+  const [hasAccess, setHasAccess] = useState(false);
+  
+  useEffect(() => {
+    auth.getAccount().then(account => {
+      const isAdmin = account.features?.adminCollections === true;
+      setHasAccess(isAdmin);
+    });
+  }, []);
+  
+  if (!hasAccess) return <div>Access Denied</div>;
+  
+  return <div>Admin Content</div>;
+}
+```
+
+## Migration Guide
+
+### Before (Direct Smartlinks SDK)
+
+```typescript
+import * as smartlinks from '@proveanything/smartlinks';
+
+function MyComponent() {
+  useEffect(() => {
+    // Every call hits the API
+    smartlinks.auth.getAccount().then(account => {
+      console.log(account);
+    });
+  }, []);
+}
+```
+
+### After (Auth Module with Caching)
+
+```typescript
+import { useAuth } from '@smartlinks/auth-ui';
+
+function MyComponent() {
+  const auth = useAuth();
+  
+  useEffect(() => {
+    // Smart caching - much faster on subsequent calls
+    auth.getAccount().then(account => {
+      console.log(account);
+    });
+  }, []);
+}
+```
+
+## Performance Benefits
+
+- **Reduced API calls**: 5-minute cache means 1 API call instead of potentially dozens
+- **Faster response**: Cached data returns in <1ms vs 100-500ms API latency
+- **Better UX**: Instant data display on page navigation
+- **Cross-tab efficiency**: One tab fetches, all tabs benefit
+- **Offline resilience**: Stale cache returned when API unavailable
+
+## Troubleshooting
+
+### Cache Not Updating
+
+```typescript
+// Force refresh to bypass cache
+await auth.refreshAccount();
+```
+
+### Cross-Tab Sync Not Working
+
+Ensure BroadcastChannel is supported (modern browsers):
+
+```typescript
+if ('BroadcastChannel' in window) {
+  // Cross-tab sync available
+} else {
+  // Fallback: cache still works, just no cross-tab sync
+}
+```
+
+### Memory Concerns
+
+Account info is stored in IndexedDB/localStorage, not memory:
+- Minimal memory footprint
+- Persists across page refreshes
+- Automatically cleared on logout
+
+## API Reference
+
+### `getAccount(forceRefresh?: boolean): Promise<Record<string, any>>`
+
+Retrieves account information with intelligent caching.
+
+**Parameters:**
+- `forceRefresh` (optional): Set to `true` to bypass cache and fetch fresh data
+
+**Returns:** Promise resolving to account info object
+
+**Throws:** Error if not authenticated or API fails with no cache available
+
+### `refreshAccount(): Promise<Record<string, any>>`
+
+Convenience method to force refresh account info. Equivalent to `getAccount(true)`.
+
+**Returns:** Promise resolving to fresh account info
+
+### `clearAccountCache(): Promise<void>`
+
+Clears the cached account information. Next `getAccount()` call will fetch fresh data.
+
+**Returns:** Promise that resolves when cache is cleared
+
+### `accountInfo: Record<string, any> | null`
+
+Synchronously accessible cached account information. Returns `null` if no cache exists.
+
+## Implementation Details
+
+### Storage Architecture
+
+- **Primary storage**: IndexedDB for structured data and better capacity
+- **Fallback storage**: localStorage for browsers with limited IndexedDB support
+- **In-memory cache**: React state for synchronous access within components
+
+### Cache Structure
+
+```typescript
+{
+  data: Record<string, any>,    // The actual account info
+  cachedAt: number,              // Timestamp when data was cached
+  expiresAt: number              // Timestamp when cache expires
+}
+```
+
+### Cross-Tab Synchronization
+
+Uses BroadcastChannel API and storage events to notify all browser tabs when:
+- Account info is fetched/refreshed in any tab
+- Account cache is cleared
+- User logs out (clears all caches)
+
+All tabs automatically update their in-memory state without additional API calls.