@featureflare/sdk-js 0.0.26 → 0.0.28

package/README.md

@@ -27,6 +27,9 @@ const featureflare = new FeatureFlareClient({
 
 const enabled = await featureflare.bool('new-nav', { id: 'user-123' }, false);
 console.log(enabled);
+
+const detailed = await featureflare.evaluate('new-nav', { id: 'user-123' }, false);
+console.log(detailed.value, detailed.metadata.reason, detailed.metadata.source);
 ```
 
 ### Environment Variables
@@ -42,6 +45,43 @@ The SDK automatically reads from environment variables if `sdkKey` is not provid
 const featureflare = new FeatureFlareClient();
 ```
 
+### Resilience options (cache/retry/timeout/bootstrap)
+
+```typescript
+const featureflare = new FeatureFlareClient({
+  sdkKey: 'featureflare_cli_...',
+  timeoutMs: 3000,
+  maxRetries: 2,
+  backoffMs: 200,
+  jitter: 0.25,
+  cacheTtlMs: 60_000,
+  staleTtlMs: 10_000,
+  bootstrap: {
+    flags: { 'new-nav': true },
+    killSwitches: ['dangerous-flow']
+  },
+  realtime: {
+    // optional: enabled defaults to true (SSE primary, polling fallback)
+    pollingIntervalMs: 15_000,
+    ssePath: '/api/v1/sdk/stream'
+  }
+});
+```
+
+- Cache-first evaluation order: fresh cache → stale cache (+ async revalidate) → bootstrap/persistent cache → default.
+- `bool(...)` and `evaluate(...)` are outage-safe and return deterministic defaults for expected network failures.
+- Hard kill switches have highest precedence and return `false` even when the API is unreachable.
+- Realtime updates are enabled by default: SSE is primary transport; polling is used automatically as fallback when SSE is unavailable.
+
+To explicitly disable realtime updates:
+
+```typescript
+const featureflare = new FeatureFlareClient({
+  sdkKey: 'featureflare_cli_...',
+  realtime: { enabled: false }
+});
+```
+
 ### API Base URL
 
 The SDK automatically determines the API base URL:
@@ -109,6 +149,15 @@ Evaluates a boolean feature flag for a user.
 
 Returns `Promise<boolean>` - The flag value for the user.
 
+##### `evaluate(flagKey: string, user: FeatureFlareUserPayload, defaultValue?: boolean): Promise<{ value: boolean; metadata: ... }>`
+
+Evaluates a flag with diagnostics metadata:
+
+- `reason`: `fresh_cache | stale_cache | bootstrap | default | network | kill_switch`
+- `isStale`
+- `latencyMs`
+- `source`, `updatedAt`, `staleAt`, `expiresAt`
+
 **Example:**
 
 ```typescript
@@ -132,15 +181,10 @@ const allFlags = await featureflare.flags({ id: 'user-123' }, false);
 
 ## Error Handling
 
-If the API request fails (network error, non-2xx status), the SDK returns the `defaultValue`. Network errors (DNS, timeout, connection refused) will throw; wrap calls in `try/catch` if you want to handle them.
+`bool(...)` and `evaluate(...)` are non-throwing for expected outage/network states. If the API request fails, the SDK falls back to stale/bootstrap/persistent/default values deterministically.
 
 ```typescript
-try {
-  const enabled = await featureflare.bool('flag', user, false);
-} catch (error) {
-  // Handle network errors
-  console.error('Failed to evaluate flag:', error);
-}
+const enabled = await featureflare.bool('flag', user, false);
 ```
 
 ## SDK Keys