@featureflare/sdk-js 0.0.5 → 0.0.6-beta.259

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
@@ -35,12 +38,50 @@ The SDK automatically reads from environment variables if `sdkKey` is not provid
 
 - `FEATUREFLARE_CLIENT_KEY` - Client SDK key (for browser/mobile)
 - `FEATUREFLARE_SERVER_KEY` - Server SDK key (for backend)
+- `FEATUREFLARE_ENV_KEY` - Expected environment key binding (`development`, `staging`, `production`, etc.)
 
 ```typescript
 // In Node.js, this will use FEATUREFLARE_CLIENT_KEY or FEATUREFLARE_SERVER_KEY from env
 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:
@@ -94,6 +135,8 @@ new FeatureFlareClient(options?: FeatureFlareClientOptions)
 - `projectKey?: string` - Legacy: project key (requires `envKey`). Not recommended.
 - `envKey?: string` - Environment key (default: `'production'`). Only used with `projectKey`.
 
+When using `sdkKey`, `envKey` is sent as an expected environment binding. The API rejects requests if the key's actual environment does not match `envKey`.
+
 #### Methods
 
 ##### `bool(flagKey: string, user: FeatureFlareUserPayload, defaultValue?: boolean): Promise<boolean>`
@@ -106,23 +149,42 @@ 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
 const enabled = await featureflare.bool('new-nav', { id: 'user-123' }, false);
 ```
 
+##### `flags(user: FeatureFlareUserPayload, defaultValue?: boolean): Promise<Record<string, boolean>>`
+
+Fetches all boolean flags for the provided user.
+
+- `user`: User payload with `id` or `key` (required)
+- `defaultValue`: Default value to apply for missing/offline evaluations (default: `false`)
+
+Returns `Promise<Record<string, boolean>>` - A map of `flagKey -> value`.
+
+**Example:**
+
+```typescript
+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
@@ -134,6 +196,10 @@ Each environment has two SDK keys:
 
 Get your SDK keys from your FeatureFlare Console → Environments.
 
+## Security: Client-side flags are not authorization
+
+Client keys can be extracted from your frontend bundle. **Never gate truly sensitive operations solely with client-evaluated flags**—enforce authorization on your backend. Use client keys for non-sensitive UI toggles (e.g. feature visibility, A/B tests). For access control, billing gates, or data protection, always validate on the server.
+
 ## License
 
 MIT