@flagpool/sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
-# Flagpool SDK - TypeScript / JavaScript
+# Flagpool SDK for TypeScript / JavaScript
 
-Official TypeScript/JavaScript SDK for Flagpool feature flags with local evaluation, deterministic rollouts, and encrypted target lists.
+Official TypeScript/JavaScript SDK for [Flagpool](https://flagpool.io) - the modern feature flag platform for teams who want control without complexity.
 
 [![npm version](https://img.shields.io/npm/v/@flagpool/sdk.svg)](https://www.npmjs.com/package/@flagpool/sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@flagpool/sdk.svg)](https://www.npmjs.com/package/@flagpool/sdk)
@@ -17,7 +17,7 @@ npm install @flagpool/sdk
 import { FlagpoolClient } from '@flagpool/sdk';
 
 const client = new FlagpoolClient({
-  apiKey: 'fp_production_xxx',
+  apiKey: 'fp_production_xxx',      // Get from Flagpool dashboard
   environment: 'production',
   context: {
     userId: 'user-123',
@@ -35,10 +35,12 @@ if (client.isEnabled('new-dashboard')) {
 }
 
 // String flag (A/B test)
-const buttonColor = client.getValue('cta-button-color'); // 'blue' | 'green' | 'orange'
+const buttonColor = client.getValue('cta-button-color');
+// 'blue' | 'green' | 'orange'
 
 // Number flag
-const maxUpload = client.getValue('max-upload-size-mb'); // 10 | 100 | 1000
+const maxUpload = client.getValue('max-upload-size-mb');
+// 10 | 100 | 1000
 
 // JSON flag
 const config = client.getValue('checkout-config');
@@ -53,45 +55,85 @@ client.close();
 - ✅ **Local evaluation** - No server roundtrip per flag check
 - ✅ **Deterministic rollouts** - Same user always gets same variation
 - ✅ **Multiple flag types** - Boolean, string, number, JSON
-- ✅ **8 targeting operators** - eq, neq, in, nin, contains, startsWith, inTargetList, notInTargetList
-- ✅ **Priority-based rules** - First matching rule wins
-- ✅ **Encrypted target lists** - Optional client-side decryption
-- ✅ **Real-time updates** - Polling for flag changes
-- ✅ **Zero dependencies** - Core SDK has no external dependencies
-
-## API Reference
-
-### `FlagpoolClient`
+- ✅ **Advanced targeting** - 8 operators including target lists
+- ✅ **Real-time updates** - Automatic polling for flag changes
+- ✅ **Offline support** - Works with cached flags when offline
+- ✅ **Zero dependencies** - Lightweight, no external dependencies
 
-#### Constructor Options
+## Configuration
 
 ```typescript
-interface FlagpoolClientOptions {
-  apiKey: string;                    // Environment-specific API key
-  environment: string;               // Environment name (required)
-  context?: Record<string, any>;     // User context for targeting
-  pollingInterval?: number;          // Polling interval in ms (default: 30000)
-  streaming?: boolean;               // Enable real-time updates (default: false)
-  urlOverride?: string;              // Override API endpoint
-  decryptionKey?: string;            // Key for client-side target list decryption
-  clientSideTargetLists?: boolean;   // Enable client-side target list evaluation
-}
+const client = new FlagpoolClient({
+  // Required
+  apiKey: 'fp_production_xxx',       // Your environment API key
+  environment: 'production',          // Environment name
+
+  // Optional
+  context: {                          // User context for targeting
+    userId: 'user-123',
+    email: 'user@example.com',
+    plan: 'pro',
+    // Add any attributes for targeting
+  },
+  pollingInterval: 30000,             // Auto-refresh interval (ms), default: 30000
+  urlOverride: undefined,             // Override API endpoint (for self-hosted)
+});
 ```
 
-#### Methods
+## API Reference
+
+### Methods
 
 | Method | Description |
 |--------|-------------|
-| `init()` | Initialize client and fetch flags |
-| `isEnabled(key)` | Check if boolean flag is enabled |
+| `init()` | Initialize client and fetch flags (required before evaluation) |
+| `isEnabled(key)` | Check if a boolean flag is enabled |
 | `getValue(key)` | Get flag value (any type) |
 | `getVariation(key)` | Alias for getValue |
-| `getAllFlags()` | Get all evaluated flag values |
-| `updateContext(context)` | Update user context and re-evaluate |
-| `onChange(callback)` | Subscribe to flag changes |
-| `close()` | Clean up timers and connections |
+| `updateContext(ctx)` | Update user context and re-evaluate flags |
+| `onChange(callback)` | Subscribe to flag value changes |
+| `close()` | Clean up resources (stop polling) |
+
+### Flag Types
+
+#### Boolean Flags
+
+```typescript
+if (client.isEnabled('feature-flag')) {
+  // Feature is enabled for this user
+}
+```
+
+#### String Flags
+
+Perfect for A/B tests and feature variants:
+
+```typescript
+const variant = client.getValue('button-color');
+// Returns: 'blue' | 'green' | 'orange'
+```
+
+#### Number Flags
 
-## Targeting Operators
+Great for limits, thresholds, and configurations:
+
+```typescript
+const limit = client.getValue('rate-limit');
+// Returns: 100 | 1000 | 10000
+```
+
+#### JSON Flags
+
+For complex configurations:
+
+```typescript
+const config = client.getValue('checkout-config');
+// Returns: { showCoupons: true, maxItems: 50, ... }
+```
+
+## Targeting Rules
+
+Flagpool supports powerful targeting with 8 operators:
 
 | Operator | Description | Example |
 |----------|-------------|---------|
@@ -106,8 +148,9 @@ interface FlagpoolClientOptions {
 
 ## Dynamic Context Updates
 
+Update user context on the fly - flags re-evaluate automatically:
+
 ```typescript
-// Initial context
 const client = new FlagpoolClient({
   apiKey: 'fp_prod_xxx',
   environment: 'production',
@@ -116,143 +159,166 @@ const client = new FlagpoolClient({
 
 await client.init();
 
+// User on free plan
 console.log(client.getValue('max-upload-size-mb')); // 10
 
 // User upgrades to pro
 client.updateContext({ plan: 'pro' });
 
+// Instantly gets pro limits
 console.log(client.getValue('max-upload-size-mb')); // 100
 ```
 
-## Encrypted Target Lists
-
-For offline/edge scenarios, you can decrypt and evaluate target lists client-side.
-
-> **Note:** The SDK has NO crypto dependencies. You provide the adapter.
+## Real-time Updates
 
-### Step 1: Create a Crypto Adapter
+Flags automatically refresh in the background:
 
 ```typescript
-// crypto-adapter.ts (YOUR CODE)
-import type { CryptoAdapter } from 'flagpool-sdk';
+const client = new FlagpoolClient({
+  apiKey: 'fp_prod_xxx',
+  environment: 'production',
+  context: { userId: 'user-1' },
+  pollingInterval: 30000  // Refresh every 30 seconds
+});
+
+await client.init();
 
-export async function createNodeCryptoAdapter(): Promise<CryptoAdapter> {
-  const crypto = await import('crypto');
+// Listen for flag changes
+client.onChange((flagKey, newValue) => {
+  console.log(`Flag ${flagKey} changed to:`, newValue);
   
-  return {
-    async decrypt(ciphertext, key, iv, tag) {
-      // Your AES-256-GCM decryption implementation
-      // See examples/src/crypto-adapter.ts for full implementation
-    }
-  };
-}
+  // React to changes (e.g., update UI)
+  if (flagKey === 'maintenance-mode' && newValue === true) {
+    showMaintenanceBanner();
+  }
+});
 ```
 
-### Step 2: Register and Use
+## Offline Support
 
-```typescript
-import { FlagpoolClient, setCryptoAdapter } from 'flagpool-sdk';
-import { createNodeCryptoAdapter } from './crypto-adapter';
-
-// 1. Create and register your adapter
-const adapter = await createNodeCryptoAdapter();
-setCryptoAdapter(adapter);
+The SDK caches flags locally. If the network is unavailable, it uses cached values:
 
-// 2. Create client with decryption enabled
+```typescript
 const client = new FlagpoolClient({
-  apiKey: 'fp_staging_xxx',
-  environment: 'staging',
-  context: { userId: 'beta-user-1' },
-  decryptionKey: 'your-secret-key',
-  clientSideTargetLists: true,
+  apiKey: 'fp_prod_xxx',
+  environment: 'production',
+  context: { userId: 'user-1' }
 });
 
+// Works even if network fails (uses cache from last successful fetch)
 await client.init();
 
-// Target list rules are now evaluated locally
-client.isEnabled('beta-feature'); // true if userId is in beta-testers
+// Always returns a value (from cache if offline)
+const feature = client.isEnabled('my-feature');
 ```
 
-## Real-time Updates
+## Framework Examples
+
+### React
 
 ```typescript
+import { useEffect, useState } from 'react';
+import { FlagpoolClient } from '@flagpool/sdk';
+
 const client = new FlagpoolClient({
   apiKey: 'fp_prod_xxx',
   environment: 'production',
-  context: { userId: 'user-1' },
-  streaming: true,
-  pollingInterval: 30000  // Poll every 30 seconds
 });
 
-await client.init();
+export function useFeatureFlag(key: string) {
+  const [value, setValue] = useState<any>(null);
 
-// Listen to flag changes
-client.onChange((flagKey, newValue) => {
-  console.log(`Flag ${flagKey} changed to:`, newValue);
-});
-```
+  useEffect(() => {
+    client.init().then(() => {
+      setValue(client.getValue(key));
+    });
 
-## Examples
+    const unsubscribe = client.onChange((changedKey, newValue) => {
+      if (changedKey === key) setValue(newValue);
+    });
 
-See the `examples/` directory for working examples:
+    return () => unsubscribe?.();
+  }, [key]);
 
-```bash
-cd examples
-npm install
-
-# Start mock server (uses shared server from test-harness)
-npm run server
+  return value;
+}
 
-# Run tests
-npm run test:dev           # Development environment
-npm run test:staging       # Staging environment  
-npm run test:evaluator     # Comprehensive evaluator tests
-npm run test:client-side   # Client-side target list evaluation
+// Usage
+function MyComponent() {
+  const showNewFeature = useFeatureFlag('new-feature');
+  
+  if (showNewFeature) {
+    return <NewFeature />;
+  }
+  return <OldFeature />;
+}
 ```
 
-## Flag Types
-
-### Boolean Flags
+### Next.js
 
 ```typescript
-if (client.isEnabled('feature-flag')) {
-  // Feature is enabled
+// lib/flagpool.ts
+import { FlagpoolClient } from '@flagpool/sdk';
+
+let client: FlagpoolClient | null = null;
+
+export async function getFlags(userId: string) {
+  if (!client) {
+    client = new FlagpoolClient({
+      apiKey: process.env.FLAGPOOL_API_KEY!,
+      environment: process.env.NODE_ENV,
+      context: { userId }
+    });
+    await client.init();
+  }
+  
+  return {
+    newDashboard: client.isEnabled('new-dashboard'),
+    buttonColor: client.getValue('button-color'),
+  };
 }
 ```
 
-### String Flags (A/B Tests)
+### Node.js / Express
 
 ```typescript
-const variant = client.getValue('button-color');
-// 'blue' | 'green' | 'orange'
-```
+import express from 'express';
+import { FlagpoolClient } from '@flagpool/sdk';
 
-### Number Flags
+const app = express();
 
-```typescript
-const limit = client.getValue('rate-limit');
-// 100 | 1000 | 10000
-```
+const flagpool = new FlagpoolClient({
+  apiKey: process.env.FLAGPOOL_API_KEY!,
+  environment: 'production',
+});
 
-### JSON Flags
+// Initialize on startup
+await flagpool.init();
 
-```typescript
-const config = client.getValue('checkout-config');
-// { showCoupons: true, maxItems: 50, ... }
+app.get('/api/data', (req, res) => {
+  // Update context per-request
+  flagpool.updateContext({ userId: req.user.id });
+  
+  if (flagpool.isEnabled('new-api-response')) {
+    return res.json({ version: 'v2', data: newData });
+  }
+  return res.json({ version: 'v1', data: legacyData });
+});
 ```
 
-## Conformance
+## Documentation
 
-This SDK passes all 60 conformance tests defined in `/spec/test-vectors.json`.
+For complete documentation, guides, and best practices, visit:
 
-Run conformance tests:
+📚 **[flagpool.io/docs](https://flagpool.io/docs)**
 
-```bash
-cd ../../test-harness
-npm run test:typescript
-```
+## Support
+
+- 📖 [Documentation](https://flagpool.io/docs)
+- 🐛 [Report Issues](https://github.com/flagpool/flagpool-sdk/issues)
+- ✉️ [Email Support](mailto:support@flagpool.io)
 
 ## License
 
-MIT
+MIT © [Flagpool](https://flagpool.io)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flagpool/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official Flagpool SDK for TypeScript/JavaScript - feature flags with local evaluation, deterministic rollouts, and encrypted target lists",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,7 @@
     "url": "git+https://github.com/flagpool/flagpool-sdk.git",
     "directory": "sdks/typescript"
   },
-  "homepage": "https://github.com/flagpool/flagpool-sdk/tree/main/sdks/typescript#readme",
+  "homepage": "https://flagpool.io/docs/sdks/typescript",
   "bugs": {
     "url": "https://github.com/flagpool/flagpool-sdk/issues"
   },