flagmint-js-sdk 1.2.20 → 1.2.22

package/README.md

@@ -1,8 +1,8 @@
 # Flagmint JavaScript SDK
 
-**Version: 1.2.5**
+**Version: 1.2.21**
 
-This SDK provides a framework-agnostic client for evaluating feature flags, with pluggable caching (sync or async) and transport strategies (WebSocket or long-polling). It's designed for both browser and server-side Node.js environments.
+This SDK provides a javascript framework-agnostic client for evaluating feature flags, with pluggable caching (sync or async) and transport strategies (WebSocket or long-polling). It's designed for both browser and server-side Node.js environments.
 
 ## ✨ Key Features
 
@@ -21,10 +21,10 @@ npm install flagmint-js-sdk
 yarn add flagmint-js-sdk
 ```
 
-## � Quick Start
+## Quick Start
 
 ```ts
-import { FlagClient } from 'flagmint-sdk';
+import { FlagClient } from 'flagmint-js-sdk';
 
 // Create a client instance
 const client = new FlagClient({
@@ -36,7 +36,7 @@ const client = new FlagClient({
   }
 });
 
-// Wait for initial connection
+// Wait for initial connection and flag synchronization
 await client.ready();
 
 // Get flag values
@@ -44,7 +44,10 @@ const showBanner = client.getFlag('show_banner', false);
 const featureVersion = client.getFlag('feature_version', 'v1');
 
 // Update context and re-evaluate
-client.updateContext({ user_id: 'user456' });
+await client.updateContext({
+  kind: "user",
+  user: { kind: "user", key: 'user456', email: 'user456@example.com' }
+});
 ```
 
 ## FlagClientOptions
@@ -53,14 +56,14 @@ client.updateContext({ user_id: 'user456' });
 | --------------------- | ----------------------------------------- | ------------------ | --------------------------------------------------------------------- |
 | `apiKey`              | `string`                                  | **Required**       | Your environment API key.                                             |
 | `context`             | `Record<string, any>`                     | `{}`               | Initial evaluation context (e.g. user attributes).                    |
-| `enableOfflineCache`  | `boolean`                                 | `false`             | Enable caching of flags locally.                                      |
+| `enableOfflineCache`  | `boolean`                                 | `true`              | Enable caching of flags locally.                                      |
 | `persistContext`      | `boolean`                                 | `false`            | Persist evaluation context across sessions.                           |                                        |
 | `cacheAdapter`        | `CacheAdapter<C>`                         | Sync `cacheHelper` | Custom cache implementation (see examples).                           |
 | `transportMode`       | `'auto' \| 'websocket' \| 'long-polling'` | `'auto'`           | How to fetch flags: prefer WebSocket, or use long-polling transport.  |
-| `onError`             | `(error: Error) => void`                  | —                  | Callback for transport or initialization errors.                      |
+| `onError`             | `(error: Error) => void`                  | —                  | Callback for transport or initialization errors. Called when operating in degraded mode with cached flags. |
 | `previewMode`         | `boolean`                                 | `false`            | Evaluate using `rawFlags` only, bypassing remote fetch.               |
 | `rawFlags`            | `Record<string, FlagValue>`               | —                  | Local-only flag definitions used when `previewMode: true`.            |
-| `deferInitialization` | `boolean`                                 | `false`            | If `true`, client initialization is deferred until you call `init()`. |
+| `deferInitialization` | `boolean`                                 | `false`            | If `true`, client initialization is deferred until you call `ready()`. |
 
 ## 🔧 Cache Adapters
 
@@ -69,10 +72,9 @@ client.updateContext({ user_id: 'user456' });
 By default, the SDK uses a **sync** `localStorage`-based helper in browsers or a `Map` in Node.js:
 
 ```ts
-import { FlagClient } from 'flagmint-sdk';
+import { FlagClient, syncCache } from 'flagmint-js-sdk';
 // No setup needed for browser; for Node you can override:
-import { setCacheStorage } from 'flagmint-sdk/core/cacheHelper';
-setCacheStorage({
+syncCache.setCacheStorage({
   getItem:   key => myMap.get(key) ?? null,
   setItem:   (key, val) => myMap.set(key, val),
 });
@@ -83,8 +85,7 @@ setCacheStorage({
 Use the **async** helper for server-side or React Native:
 
 ```ts
-import { FlagClient } from 'flagmint-sdk';
-import * as asyncCache from 'flagmint-sdk/core/cacheHelper.async';
+import { FlagClient, asyncCache } from 'flagmint-js-sdk';
 
 const client = new FlagClient({
   apiKey: '...',
@@ -125,7 +126,7 @@ The SDK includes utilities to evaluate flag targeting rules and rollouts:
 ### `evaluateFlagValue(flag, context)`
 
 ```ts
-import { evaluateFlagValue } from 'flagmint-sdk/core/evaluation';
+import { evaluateFlagValue } from 'flagmint-js-sdk';
 
 const result = evaluateFlagValue(flagValue, userContext);
 ```
@@ -137,7 +138,7 @@ const result = evaluateFlagValue(flagValue, userContext);
 ### `evaluateRollout(rollout, context)`
 
 ```ts
-import { evaluateRollout } from 'flagmint-sdk/core/evaluation';
+import { evaluateRollout } from 'flagmint-js-sdk';
 
 const rolloutValue = evaluateRollout(rolloutConfig, userContext);
 ```
@@ -148,16 +149,16 @@ const rolloutValue = evaluateRollout(rolloutConfig, userContext);
 ### `rolloutUtils`
 
 * `hashToPercentage(value: string): number`
-* `pickVariant(value: string, variants: VariantRollout): T | null`
+* `pickVariant(value: string, variants: VariantOption[]): string | number | boolean | null`
 
 These helpers underpin reliable, deterministic assignment of users to flag variants.
 
-### `isInSegment(context, segment)`
+### `isInSegment(segment, context)`
 
 ```ts
-import { isInSegment } from 'flagmint-sdk/core/evaluation';
+import { isInSegment } from 'flagmint-js-sdk';
 
-const inBetaSegment = isInSegment(userContext, betaSegment);
+const inBetaSegment = isInSegment(betaSegment, userContext);
 ```
 
 Evaluates whether a user context matches a segment's criteria.
@@ -168,7 +169,7 @@ Evaluates whether a user context matches a segment's criteria.
 
 ```tsx
 import { useEffect, useState } from 'react';
-import { FlagClient } from 'flagmint-sdk';
+import { FlagClient } from 'flagmint-js-sdk';
 
 const client = new FlagClient({
   apiKey: 'ff_...',
@@ -189,6 +190,16 @@ export function App() {
         theme: client.getFlag('theme', 'light')
       });
     });
+
+    // Subscribe to flag updates
+    const unsubscribe = client.subscribe((updatedFlags) => {
+      setFlags({
+        showBeta: client.getFlag('show_beta', false),
+        theme: client.getFlag('theme', 'light')
+      });
+    });
+    
+    return () => unsubscribe();
   }, []);
 
   return (
@@ -202,8 +213,7 @@ export function App() {
 ### Node.js / Express
 
 ```ts
-import { FlagClient } from 'flagmint-sdk';
-import * as asyncCache from 'flagmint-sdk/core/cacheHelper.async';
+import { FlagClient, asyncCache } from 'flagmint-js-sdk';
 
 const client = new FlagClient({
   apiKey: 'ff_...',
@@ -215,9 +225,26 @@ const client = new FlagClient({
   }
 });
 
+// Wait for initialization
+await client.ready();
+
 app.get('/api/feature', async (req, res) => {
-  const userContext = { userId: req.user.id, plan: req.user.plan };
-  const isEnabled = client.getFlag('new_api', false, userContext);
+  // Update context with proper structure
+  await client.updateContext({ 
+    kind: "multi",
+    user: {
+      kind: "user",
+      key: req.user.id,
+      email: req.user.email
+    },
+    organization: {
+      kind: "organization",
+      key: req.user.orgId,
+      plan: req.user.plan
+    }
+  });
+  
+  const isEnabled = client.getFlag('new_api', false);
   
   res.json({ enabled: isEnabled });
 });
@@ -231,14 +258,26 @@ app.get('/api/feature', async (req, res) => {
 // Initial context
 const client = new FlagClient({
   apiKey: '...',
-  context: { user_id: 'user123' }
+  context: {
+    kind: "user",
+    user: { kind: "user", key: 'user123' }
+  }
 });
 
-// Update context later
-client.updateContext({ 
-  user_id: 'user123',
-  plan: 'premium',
-  country: 'CA'
+// Update context later (e.g., after user upgrades)
+await client.updateContext({ 
+  kind: "multi",
+  user: {
+    kind: "user",
+    key: 'user123',
+    email: 'user@example.com'
+  },
+  organization: {
+    kind: "organization",
+    key: 'org456',
+    plan: 'premium',
+    country: 'CA'
+  }
 });
 ```
 
@@ -248,7 +287,10 @@ client.updateContext({
 const client = new FlagClient({
   apiKey: '...',
   persistContext: true, // Saves to localStorage/AsyncStorage
-  context: { user_id: 'user123' }
+  context: {
+    kind: "user",
+    user: { kind: "user", key: 'user123', email: 'user@example.com' }
+  }
 });
 ```
 
@@ -263,8 +305,11 @@ const client = new FlagClient({
 });
 
 // Later, when context is ready:
-client.updateContext({ user_id: 'user123' });
-await client.init();
+await client.updateContext({
+  kind: "user",
+  user: { kind: "user", key: 'user123', email: 'user@example.com' }
+});
+await client.ready(); // Initializes and connects
 ```
 
 ## 🌍 Advanced Usage
@@ -282,6 +327,42 @@ const client = new FlagClient({
 });
 ```
 
+**Important: Offline Fallback & Cache Behavior**
+
+The SDK gracefully handles connection failures using cached flags as a fallback:
+
+**When the server is unreachable:**
+
+| Scenario | `ready()` Promise | Behavior |
+|----------|-------------------|----------|
+| ✅ Cached flags available | Resolves | Operates in degraded mode with cached flags |
+| ❌ No cached flags | Rejects | Initialization fails |
+| ✅ Connected successfully | Resolves | Normal operation with live updates |
+
+**Degraded Mode:** When `ready()` resolves but the connection failed, the `onError` callback is triggered to notify you:
+
+```ts
+const client = new FlagClient({
+  apiKey: '...',
+  enableOfflineCache: true,
+  onError: (error) => {
+    // Called when operating in degraded mode with cached flags
+    console.warn('⚠️ Degraded mode - using cached flags:', error.message);
+    // Optionally report to monitoring service
+  }
+});
+
+try {
+  await client.ready();
+  // ✅ Resolves successfully even if server is down (when cached flags exist)
+  console.log('Client ready');
+  const feature = client.getFlag('my_feature', false); // Always works
+} catch (error) {
+  // ❌ Only throws if NO cached flags AND server is unreachable
+  console.error('Completely offline:', error);
+}
+```
+
 ### Preview Mode
 
 For testing or preview environments where you want to bypass remote flag fetching:
@@ -304,7 +385,7 @@ const checkout = client.getFlag('new_checkout', false); // true
 ### Custom Cache Implementations
 
 ```ts
-import { FlagClient } from 'flagmint-sdk';
+import { FlagClient } from 'flagmint-js-sdk';
 import redis from 'redis';
 
 const redisClient = redis.createClient();
@@ -343,17 +424,26 @@ const client = new FlagClient({
 ### `FlagClient`
 
 **Methods:**
-- `ready(): Promise<void>` - Wait for initial connection
-- `getFlag<T>(key: string, defaultValue: T, context?: Record<string, any>): T` - Get flag value
-- `updateContext(context: Record<string, any>): void` - Update evaluation context
-- `init(): Promise<void>` - Initialize client (if deferred)
-- `disconnect(): void` - Close transport connection
-
-**Events:**
-- `flagsUpdated` - Fired when flags change
-- `contextUpdated` - Fired when context changes
-- `connected` - Fired when transport connects
-- `disconnected` - Fired when transport disconnects
+- `ready(timeoutMs?: number): Promise<void>` - Wait for initial connection (default timeout: 3000ms)
+- `getFlag<K>(key: K, fallback?: T): T` - Get flag value with optional fallback
+- `getFlags(): FeatureFlags<T>` - Get all flags as an object
+- `updateContext(context: Record<string, any>): Promise<void>` - Update evaluation context (async)
+- `subscribe(callback: (flags) => void): () => void` - Subscribe to flag updates, returns unsubscribe function
+- `destroy(): void` - Close transport connection and cleanup resources
+
+### Subscribing to Flag Updates
+
+Instead of event listeners, use the `subscribe()` method:
+
+```ts
+const unsubscribe = client.subscribe((flags) => {
+  console.log('Flags updated:', flags);
+  // Handle flag updates
+});
+
+// Later, to unsubscribe:
+unsubscribe();
+```
 
 ### Cache Adapter Interface
 
@@ -403,9 +493,20 @@ sdk/
 
 ### Flags not updating
 
-- Confirm `enableOfflineCache: false` or cache is working correctly
+- Confirm `enableOfflineCache` setting matches your needs
 - Check transport mode (WebSocket vs long-polling)
-- Verify context is properly set with `updateContext()`
+- Verify context is properly set with `await updateContext()`
+- Use `subscribe()` to listen for flag changes instead of polling
+
+### Cache behavior when server is down
+
+**Important**: When `enableOfflineCache: true` (default):
+- Cached flags are loaded even if the server is unreachable
+- `ready()` will still throw an error on connection failure
+- You can still access cached flags via `getFlag()` after catching the error
+- Consider wrapping `ready()` in try/catch and continuing with cached data
+
+See the "Error Handling with Cache" section above for examples.
 
 ### Performance issues
 
@@ -419,14 +520,9 @@ sdk/
 - **Issues**: Report on [GitHub](https://github.com/flagmint/js-sdk/issues)
 - **Email**: support@flagmint.io
 
-## 🚀 Changelog
+## 🚀 Releases & Changelog
 
-### v1.2.5
-- Enhanced async cache helper for better server-side support
-- Improved WebSocket connection stability
-- Better error reporting and handling
-- Added support for context persistence
-- Performance optimizations for large flag sets
+See [GitHub Releases](https://github.com/flagmint/js-sdk/releases) for the complete version history, changelog, and upgrade guides.
 
 ## 📖 References