@riverbankcms/sdk 0.7.5 → 0.8.0

package/README.md

@@ -90,9 +90,95 @@ const client = createRiverbankClient({
     ttl?: number;        // Default: 300 (seconds)
     maxSize?: number;    // Default: 100
   };
+  resilience?: ResilienceConfig;  // See "Resilience & Caching" section
 });
 ```
 
+### Resilience & Caching
+
+The SDK provides a multi-layer resilience strategy to keep your site running even during CMS outages:
+
+1. **In-Memory Cache** - Fast cache with configurable TTL
+2. **Stale-If-Error** - Serves stale cached data when live fetch fails
+3. **Circuit Breaker** - Fail-fast after repeated failures (5 by default)
+4. **Prebuild Fallback** - Static build artifacts as last resort
+5. **Retry with Backoff** - Automatic retry for transient errors
+
+**Basic Configuration:**
+
+```ts
+const client = createRiverbankClient({
+  apiKey: process.env.RIVERBANK_API_KEY!,
+  baseUrl: process.env.RIVERBANK_BASE_URL!,
+  cache: {
+    enabled: true,
+    ttl: 300,           // 5 minutes fresh cache
+    maxSize: 100,
+  },
+  resilience: {
+    enabled: true,
+    staleIfError: true,
+    staleTtlSec: 300,   // Additional 5 minutes for stale data
+    prebuildDir: '.riverbank-cache',  // Enable prebuild fallback
+    maxPrebuildAgeSec: 86400,         // 24 hours max prebuild age
+  },
+});
+```
+
+**Monitoring Callbacks:**
+
+```ts
+resilience: {
+  // Called on every request with status information
+  onStatusChange: (status) => {
+    console.log('SDK request:', {
+      source: status.source,        // 'live' | 'cache' | 'stale' | 'prebuild' | 'error'
+      circuit: status.circuit.state, // 'closed' | 'open' | 'half-open'
+      staleAgeSec: status.staleAgeSec,
+      prebuildAgeSec: status.prebuildAgeSec,
+      error: status.error?.message,
+    });
+  },
+
+  // Called only when entering/exiting degraded mode
+  onDegradedMode: (degraded, status) => {
+    if (degraded) {
+      console.warn('CMS degraded mode:', status.source);
+      // Alert monitoring system
+    }
+  },
+}
+```
+
+**Programmatic State Access:**
+
+```ts
+// Get the last request status
+const lastStatus = client.getLastEmittedStatus();
+
+// Get current circuit breaker state
+const circuitState = client.getCircuitState();
+// { state: 'closed', failureCount: 0 }
+```
+
+**Full Configuration Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `resilience.enabled` | `true` | Enable resilience features |
+| `resilience.staleIfError` | `true` | Serve stale data on failure |
+| `resilience.staleTtlSec` | `300` | Additional stale window after cache TTL |
+| `resilience.requestTimeoutMs` | `8000` | Request timeout (5000 in browser) |
+| `resilience.prebuildDir` | - | Path to prebuild cache (enables fallback) |
+| `resilience.maxPrebuildAgeSec` | `86400` | Maximum prebuild age (24h) |
+| `resilience.retry.maxAttempts` | `3` | Total attempts including initial |
+| `resilience.retry.baseDelayMs` | `200` | Base delay between retries |
+| `resilience.retry.maxDelayMs` | `2000` | Maximum retry delay |
+| `resilience.circuitBreaker.failureThreshold` | `5` | Failures before circuit opens |
+| `resilience.circuitBreaker.resetTimeoutMs` | `30000` | Time before half-open |
+
+For detailed testing and verification steps, see [`docs/resilience-verification.md`](./docs/resilience-verification.md).
+
 ### Server-Side API
 
 ```tsx
@@ -2768,5 +2854,6 @@ import {
 - `@riverbankcms/sdk/navigation` - Navigation helpers and types
 - `@riverbankcms/sdk/analytics` - Analytics tracking helpers
 - `@riverbankcms/sdk/config` - Site configuration utilities (includes `defineConfig`, `defineContentConfig`, `RiverbankSiteConfig`, `ContentConfig`, etc.)
-- `@riverbankcms/sdk/next` - Next.js integration utilities (`createCatchAllPage`)
+- `@riverbankcms/sdk/next` - Next.js integration utilities (`createCatchAllPage`, ISR helpers, `generateStaticParams`)
+- `@riverbankcms/sdk/prebuild` - Prebuild cache generation (`generatePrebuildCache`, `PrebuildLoader`)
 - `@riverbankcms/sdk/spam-protection` - ALTCHA spam protection (`useSpamProtection`, `getChallengeUrl`, `AltchaWidget`)