@teracrafts/flagkit 1.0.0

package/README.md

@@ -0,0 +1,443 @@
+# @teracrafts/flagkit
+
+Official TypeScript SDK for [FlagKit](https://flagkit.dev) - Feature flag management made simple.
+
+## Features
+
+- **Zero runtime dependencies** - No external packages required
+- **Universal** - Browser and Node.js support
+- **TypeScript-first** - Full type safety with comprehensive type definitions
+- **Tiny bundle** - < 20KB gzipped
+- **Resilient** - Automatic retry with exponential backoff, circuit breaker
+- **Event tracking** - Analytics with batching
+- **Offline mode** - Works without network
+- **Security** - PII detection, bootstrap verification, timing attack protection, error sanitization
+
+## Installation
+
+```bash
+npm install @teracrafts/flagkit
+# or
+yarn add @teracrafts/flagkit
+# or
+pnpm add @teracrafts/flagkit
+```
+
+## Quick Start
+
+```typescript
+import FlagKit from '@teracrafts/flagkit';
+
+// Initialize the SDK
+const client = await FlagKit.initialize({
+  apiKey: 'sdk_your_api_key',
+  onReady: () => console.log('FlagKit ready!'),
+});
+
+// Wait for SDK to be ready
+await client.waitForReady();
+
+// Identify user
+client.identify('user-123', {
+  email: 'user@example.com',
+  custom: { plan: 'premium' },
+});
+
+// Evaluate flags
+const darkMode = client.getBooleanValue('dark-mode', false);
+const welcomeMsg = client.getStringValue('welcome-message', 'Hello!');
+const maxItems = client.getNumberValue('max-items', 10);
+const config = client.getJsonValue('feature-config', { enabled: false });
+
+// Track events
+client.track('button_clicked', { button: 'signup' });
+
+// Cleanup when done
+await client.close();
+```
+
+## Architecture
+
+The SDK is organized into clean, modular components:
+
+```
+@teracrafts/flagkit/
+├── index.ts            # Public exports
+├── flagkit.ts          # Static FlagKit factory
+├── client.ts           # FlagKitClient implementation
+├── types/              # Type definitions
+│   ├── config.ts       # FlagKitOptions, BootstrapConfig
+│   ├── context.ts      # EvaluationContext
+│   ├── flag.ts         # FlagState, EvaluationResult
+│   └── events.ts       # Event types
+├── errors/             # Error types and codes
+│   ├── flagkit-error.ts
+│   ├── error-codes.ts
+│   └── sanitizer.ts    # Error message sanitization
+├── http/               # HTTP client, circuit breaker, retry
+│   ├── http-client.ts
+│   └── circuit-breaker.ts
+├── core/               # Core components
+│   ├── cache.ts        # In-memory cache with TTL
+│   ├── context-manager.ts
+│   ├── polling-manager.ts
+│   └── event-queue.ts  # Event batching
+├── storage/            # Storage implementations
+│   └── storage.ts
+└── utils/              # Utilities
+    ├── logger.ts
+    └── security.ts     # PII detection, HMAC signing
+```
+
+## Configuration Options
+
+```typescript
+interface FlagKitOptions {
+  // Required
+  apiKey: string;                    // Your FlagKit API key
+
+  // Optional
+  pollingInterval?: number;          // Default: 30000 (ms)
+  enablePolling?: boolean;           // Default: true
+  cacheEnabled?: boolean;            // Default: true
+  cacheTTL?: number;                 // Default: 300000 (ms)
+  offline?: boolean;                 // Default: false
+  timeout?: number;                  // Default: 5000 (ms)
+  retries?: number;                  // Default: 3
+  debug?: boolean;                   // Default: false
+  localPort?: number;                // Uses http://localhost:{port}/api/v1
+  bootstrap?: BootstrapData;         // Fallback values (with optional signature)
+
+  // Callbacks
+  onReady?: () => void;
+  onError?: (error: FlagKitError) => void;
+  onUpdate?: (flags: FlagState[]) => void;
+}
+```
+
+## API Reference
+
+### Flag Evaluation
+
+```typescript
+// Boolean flags
+getBooleanValue(key: string, defaultValue: boolean, context?: EvaluationContext): boolean
+
+// String flags
+getStringValue(key: string, defaultValue: string, context?: EvaluationContext): string
+
+// Number flags
+getNumberValue(key: string, defaultValue: number, context?: EvaluationContext): number
+
+// JSON flags
+getJsonValue<T>(key: string, defaultValue: T, context?: EvaluationContext): T
+
+// Full evaluation result
+evaluate(key: string, context?: EvaluationContext): EvaluationResult
+
+// Evaluate all flags
+evaluateAll(context?: EvaluationContext): Record<string, EvaluationResult>
+
+// Check if flag exists
+hasFlag(key: string): boolean
+
+// Get all flag keys
+getAllFlagKeys(): string[]
+```
+
+### Context Management
+
+```typescript
+// Set global context
+setContext(context: EvaluationContext): void
+
+// Get current context
+getContext(): EvaluationContext | null
+
+// Clear context
+clearContext(): void
+
+// Identify user
+identify(userId: string, attributes?: Partial<EvaluationContext>): void
+
+// Reset to anonymous
+reset(): void
+```
+
+### Event Tracking
+
+```typescript
+// Track custom event
+track(eventType: string, eventData?: Record<string, unknown>): void
+
+// Flush events immediately
+flush(): Promise<void>
+```
+
+### Lifecycle
+
+```typescript
+// Check if ready
+isReady(): boolean
+
+// Wait for ready
+waitForReady(): Promise<void>
+
+// Force refresh flags
+refresh(): Promise<void>
+
+// Close and cleanup
+close(): Promise<void>
+```
+
+## Evaluation Context
+
+```typescript
+interface EvaluationContext {
+  userId?: string;
+  userKey?: string;
+  email?: string;
+  name?: string;
+  anonymous?: boolean;
+  country?: string;
+  ip?: string;
+  userAgent?: string;
+  custom?: Record<string, unknown>;
+  privateAttributes?: string[];  // Attributes not sent to server
+}
+```
+
+## Error Handling
+
+The SDK uses specific error classes for different error types:
+
+```typescript
+import {
+  FlagKitError,
+  InitializationError,
+  AuthenticationError,
+  NetworkError,
+  EvaluationError,
+} from '@teracrafts/flagkit';
+
+try {
+  await FlagKit.initialize({ apiKey: 'invalid' });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof NetworkError) {
+    console.error('Network issue:', error.message);
+  }
+}
+```
+
+All errors include:
+- `code`: Error code string (e.g., "NETWORK_TIMEOUT")
+- `numericCode`: Numeric error code (e.g., 1301)
+- `recoverable`: Whether the operation can be retried
+- `retryAfter`: Seconds to wait before retrying (if applicable)
+
+## Offline Mode
+
+Enable offline mode for environments without network access:
+
+```typescript
+const client = await FlagKit.initialize({
+  apiKey: 'sdk_your_api_key',
+  offline: true,
+  bootstrap: {
+    'dark-mode': false,
+    'max-items': 10,
+  },
+});
+```
+
+## Local Development
+
+Enable local development mode to connect to a local FlagKit server:
+
+```typescript
+const client = await FlagKit.initialize({
+  apiKey: 'sdk_your_api_key',
+  localPort: 8200,
+});
+```
+
+## Browser Usage
+
+The SDK includes a browser bundle that exposes `FlagKit` globally:
+
+```html
+<script src="https://unpkg.com/@teracrafts/flagkit"></script>
+<script>
+  FlagKit.initialize({ apiKey: 'sdk_your_api_key' })
+    .then(client => {
+      const darkMode = client.getBooleanValue('dark-mode', false);
+    });
+</script>
+```
+
+## Advanced: Direct Client Access
+
+For more control, you can use the client directly:
+
+```typescript
+import { FlagKitClient, HttpClient, FlagCache } from '@teracrafts/flagkit';
+
+const client = new FlagKitClient({
+  apiKey: 'sdk_your_api_key',
+});
+
+await client.initialize();
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import type {
+  FlagKitOptions,
+  EvaluationContext,
+  EvaluationResult,
+  FlagState,
+  FlagKitError,
+} from '@teracrafts/flagkit';
+```
+
+## Security Features
+
+### PII Detection
+
+The SDK can detect and warn about potential PII (Personally Identifiable Information) in contexts and events:
+
+```typescript
+// Enable strict PII mode - throws errors instead of warnings
+const client = await FlagKit.initialize({
+  apiKey: 'sdk_...',
+  strictPIIMode: true,
+});
+
+// Attributes containing PII will throw SecurityError
+try {
+  client.identify('user-123', {
+    email: 'user@example.com',  // PII detected!
+  });
+} catch (error) {
+  if (error instanceof SecurityError) {
+    console.error('PII error:', error.message);
+  }
+}
+
+// Use privateAttributes to mark fields as intentionally containing PII
+client.setContext({
+  userId: 'user-123',
+  email: 'user@example.com',
+  privateAttributes: ['email'],  // Marks email as intentionally private
+});
+```
+
+### Bootstrap Signature Verification
+
+Verify bootstrap data integrity using HMAC signatures:
+
+```typescript
+import { createBootstrapSignature } from '@teracrafts/flagkit';
+
+// Create signed bootstrap data
+const bootstrap = createBootstrapSignature(
+  { 'feature-a': true, 'feature-b': 'value' },
+  'sdk_your_api_key'
+);
+
+// Use signed bootstrap with verification
+const client = await FlagKit.initialize({
+  apiKey: 'sdk_...',
+  bootstrap,
+  bootstrapVerification: {
+    enabled: true,
+    maxAge: 86400000,  // 24 hours in milliseconds
+    onFailure: 'error',  // 'warn' (default), 'error', or 'ignore'
+  },
+});
+```
+
+### Evaluation Jitter (Timing Attack Protection)
+
+Add random delays to flag evaluations to prevent cache timing attacks:
+
+```typescript
+const client = await FlagKit.initialize({
+  apiKey: 'sdk_...',
+  evaluationJitter: {
+    enabled: true,
+    minMs: 5,
+    maxMs: 15,
+  },
+});
+```
+
+### Error Sanitization
+
+Automatically redact sensitive information from error messages:
+
+```typescript
+const client = await FlagKit.initialize({
+  apiKey: 'sdk_...',
+  errorSanitization: {
+    enabled: true,
+    preserveOriginal: false,  // Set true for debugging
+  },
+});
+// Errors will have paths, IPs, API keys, and emails redacted
+```
+
+## Key Rotation
+
+Support seamless API key rotation:
+
+```typescript
+const client = await FlagKit.initialize({
+  apiKey: 'sdk_primary_key',
+  secondaryApiKey: 'sdk_secondary_key',
+  keyRotationGracePeriod: 300000,  // 5 minutes
+});
+// SDK will automatically failover to secondary key on 401 errors
+```
+
+## All Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | Required | API key for authentication |
+| `secondaryApiKey` | string | - | Secondary key for rotation |
+| `keyRotationGracePeriod` | number | 300000 | Grace period in ms |
+| `pollingInterval` | number | 30000 | Polling interval in ms |
+| `enablePolling` | boolean | true | Enable background polling |
+| `cacheEnabled` | boolean | true | Enable local caching |
+| `cacheTTL` | number | 300000 | Cache TTL in ms |
+| `persistCache` | boolean | false | Persist cache to storage |
+| `cacheStorageKey` | string | 'flagkit_cache' | Storage key for cache |
+| `offline` | boolean | false | Offline mode |
+| `timeout` | number | 5000 | Request timeout in ms |
+| `retries` | number | 3 | Number of retry attempts |
+| `bootstrap` | BootstrapData | {} | Initial flag values |
+| `bootstrapVerification` | object | enabled | Bootstrap verification settings |
+| `localPort` | number | - | Local development port |
+| `debug` | boolean | false | Enable debug logging |
+| `logger` | Logger | - | Custom logger |
+| `onReady` | function | - | Ready callback |
+| `onError` | function | - | Error callback |
+| `onUpdate` | function | - | Update callback |
+| `strictPIIMode` | boolean | false | Error on PII detection |
+| `evaluationJitter` | object | disabled | Timing attack protection |
+| `errorSanitization` | object | enabled | Sanitize error messages |
+
+## Requirements
+
+- Node.js 18+ (for server-side)
+- Modern browser with `fetch` support (for client-side)
+
+## License
+
+MIT