@flagpool/sdk 0.1.0

package/README.md

@@ -0,0 +1,258 @@
+# Flagpool SDK - TypeScript / JavaScript
+
+Official TypeScript/JavaScript SDK for Flagpool feature flags with local evaluation, deterministic rollouts, and encrypted target lists.
+
+[![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)
+
+## Installation
+
+```bash
+npm install @flagpool/sdk
+```
+
+## Quick Start
+
+```typescript
+import { FlagpoolClient } from '@flagpool/sdk';
+
+const client = new FlagpoolClient({
+  apiKey: 'fp_production_xxx',
+  environment: 'production',
+  context: {
+    userId: 'user-123',
+    email: 'alice@example.com',
+    plan: 'pro',
+    country: 'US'
+  }
+});
+
+await client.init();
+
+// Boolean flag
+if (client.isEnabled('new-dashboard')) {
+  showNewDashboard();
+}
+
+// String flag (A/B test)
+const buttonColor = client.getValue('cta-button-color'); // 'blue' | 'green' | 'orange'
+
+// Number flag
+const maxUpload = client.getValue('max-upload-size-mb'); // 10 | 100 | 1000
+
+// JSON flag
+const config = client.getValue('checkout-config');
+// { showCoupons: true, maxItems: 50, paymentMethods: [...] }
+
+// Clean up when done
+client.close();
+```
+
+## Features
+
+- ✅ **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`
+
+#### Constructor Options
+
+```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
+}
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `init()` | Initialize client and fetch flags |
+| `isEnabled(key)` | Check if 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 |
+
+## Targeting Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `eq` | Equals | `plan == "enterprise"` |
+| `neq` | Not equals | `plan != "free"` |
+| `in` | In list | `country in ["US", "CA"]` |
+| `nin` | Not in list | `country not in ["CN", "RU"]` |
+| `contains` | String contains | `email contains "@company.com"` |
+| `startsWith` | String starts with | `userId startsWith "admin-"` |
+| `inTargetList` | In target list | `userId in beta-testers` |
+| `notInTargetList` | Not in target list | `userId not in blocked-users` |
+
+## Dynamic Context Updates
+
+```typescript
+// Initial context
+const client = new FlagpoolClient({
+  apiKey: 'fp_prod_xxx',
+  environment: 'production',
+  context: { userId: 'user-1', plan: 'free' }
+});
+
+await client.init();
+
+console.log(client.getValue('max-upload-size-mb')); // 10
+
+// User upgrades to pro
+client.updateContext({ plan: 'pro' });
+
+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.
+
+### Step 1: Create a Crypto Adapter
+
+```typescript
+// crypto-adapter.ts (YOUR CODE)
+import type { CryptoAdapter } from 'flagpool-sdk';
+
+export async function createNodeCryptoAdapter(): Promise<CryptoAdapter> {
+  const crypto = await import('crypto');
+  
+  return {
+    async decrypt(ciphertext, key, iv, tag) {
+      // Your AES-256-GCM decryption implementation
+      // See examples/src/crypto-adapter.ts for full implementation
+    }
+  };
+}
+```
+
+### Step 2: Register and Use
+
+```typescript
+import { FlagpoolClient, setCryptoAdapter } from 'flagpool-sdk';
+import { createNodeCryptoAdapter } from './crypto-adapter';
+
+// 1. Create and register your adapter
+const adapter = await createNodeCryptoAdapter();
+setCryptoAdapter(adapter);
+
+// 2. Create client with decryption enabled
+const client = new FlagpoolClient({
+  apiKey: 'fp_staging_xxx',
+  environment: 'staging',
+  context: { userId: 'beta-user-1' },
+  decryptionKey: 'your-secret-key',
+  clientSideTargetLists: true,
+});
+
+await client.init();
+
+// Target list rules are now evaluated locally
+client.isEnabled('beta-feature'); // true if userId is in beta-testers
+```
+
+## Real-time Updates
+
+```typescript
+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();
+
+// Listen to flag changes
+client.onChange((flagKey, newValue) => {
+  console.log(`Flag ${flagKey} changed to:`, newValue);
+});
+```
+
+## Examples
+
+See the `examples/` directory for working examples:
+
+```bash
+cd examples
+npm install
+
+# Start mock server (uses shared server from test-harness)
+npm run server
+
+# 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
+```
+
+## Flag Types
+
+### Boolean Flags
+
+```typescript
+if (client.isEnabled('feature-flag')) {
+  // Feature is enabled
+}
+```
+
+### String Flags (A/B Tests)
+
+```typescript
+const variant = client.getValue('button-color');
+// 'blue' | 'green' | 'orange'
+```
+
+### Number Flags
+
+```typescript
+const limit = client.getValue('rate-limit');
+// 100 | 1000 | 10000
+```
+
+### JSON Flags
+
+```typescript
+const config = client.getValue('checkout-config');
+// { showCoupons: true, maxItems: 50, ... }
+```
+
+## Conformance
+
+This SDK passes all 60 conformance tests defined in `/spec/test-vectors.json`.
+
+Run conformance tests:
+
+```bash
+cd ../../test-harness
+npm run test:typescript
+```
+
+## License
+
+MIT
+

package/dist/cache.d.ts

@@ -0,0 +1,6 @@
+export declare class Cache {
+    private key;
+    constructor(key: string);
+    load(): any | null;
+    save(data: any): void;
+}

package/dist/cache.js

@@ -0,0 +1,24 @@
+export class Cache {
+    constructor(key) {
+        this.key = key;
+    }
+    load() {
+        try {
+            if (typeof localStorage === "undefined")
+                return null;
+            const raw = localStorage.getItem(this.key);
+            return raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    save(data) {
+        try {
+            if (typeof localStorage === "undefined")
+                return;
+            localStorage.setItem(this.key, JSON.stringify(data));
+        }
+        catch { }
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import { FlagpoolClientOptions, FlagChangedCallback } from "./types";
+export declare class FlagpoolClient {
+    private options;
+    private flags;
+    private evaluator;
+    private cache;
+    private pollingTimer;
+    private realtimeConnection?;
+    private changeListeners;
+    private targetLists;
+    constructor(options: FlagpoolClientOptions);
+    init(): Promise<void>;
+    private refresh;
+    /**
+     * Process and decrypt target lists if needed
+     */
+    private processTargetLists;
+    private setupRealtime;
+    isEnabled(key: string, defaultValue?: boolean): boolean;
+    getValue(key: string): any;
+    getVariation(key: string): any;
+    getAllFlags(): Record<string, any>;
+    updateContext(newContext: Record<string, any>): void;
+    onChange(callback: FlagChangedCallback): () => boolean;
+    private notifyChanges;
+    close(): void;
+}

package/dist/client.js

@@ -0,0 +1,171 @@
+import { Evaluator } from "./evaluator";
+import { fetchFlags } from "./fetcher";
+import { Cache } from "./cache";
+import { RealtimeConnection } from "./realtime";
+import { decryptTargetLists, isEncryptedTargetLists } from "./crypto";
+export class FlagpoolClient {
+    constructor(options) {
+        this.flags = new Map();
+        this.evaluator = new Evaluator();
+        this.cache = new Cache("flagpool_flags");
+        this.changeListeners = new Set();
+        this.targetLists = null;
+        if (!options.apiKey)
+            throw new Error("apiKey is required");
+        if (!options.environment)
+            throw new Error("environment is required");
+        // Validate client-side target list requirements
+        if (options.clientSideTargetLists && !options.decryptionKey) {
+            throw new Error("decryptionKey is required when clientSideTargetLists is enabled");
+        }
+        this.options = options;
+    }
+    async init() {
+        // Try loading from cache
+        const cached = this.cache.load();
+        if (cached === null || cached === void 0 ? void 0 : cached.flags) {
+            Object.entries(cached.flags).forEach(([key, flag]) => {
+                this.flags.set(key, flag);
+            });
+        }
+        // Fetch fresh flags
+        try {
+            await this.refresh();
+        }
+        catch (err) {
+            // If fetch failed but we have cache, continue; otherwise throw
+            if (this.flags.size === 0)
+                throw err;
+        }
+        // Setup polling if configured
+        if (this.options.pollingInterval && !this.options.streaming) {
+            this.pollingTimer = setInterval(() => this.refresh().catch(() => { }), this.options.pollingInterval);
+        }
+        // Setup realtime streaming if enabled (uses polling internally)
+        if (this.options.streaming) {
+            this.setupRealtime();
+        }
+    }
+    async refresh() {
+        const response = await fetchFlags({
+            apiKey: this.options.apiKey,
+            environment: this.options.environment,
+            context: this.options.context,
+            urlOverride: this.options.urlOverride
+        });
+        // Update flags map
+        this.flags.clear();
+        response.flags.forEach(flag => {
+            this.flags.set(flag.key, flag);
+        });
+        // Handle target lists if client-side evaluation is enabled
+        if (this.options.clientSideTargetLists && this.options.decryptionKey && response.targetLists) {
+            await this.processTargetLists(response.targetLists);
+        }
+        // Cache the response
+        this.cache.save({
+            flags: Object.fromEntries(this.flags),
+            timestamp: response.timestamp
+        });
+        // Notify listeners of changes
+        this.notifyChanges();
+    }
+    /**
+     * Process and decrypt target lists if needed
+     */
+    async processTargetLists(targetLists) {
+        if (isEncryptedTargetLists(targetLists)) {
+            // Decrypt target lists
+            try {
+                this.targetLists = await decryptTargetLists(targetLists, this.options.decryptionKey);
+                this.evaluator.setTargetLists(this.targetLists, true);
+            }
+            catch (err) {
+                console.error("Failed to decrypt target lists:", err);
+                this.targetLists = null;
+                this.evaluator.setTargetLists(null, false);
+            }
+        }
+        else {
+            // Already decrypted (for testing/development)
+            this.targetLists = targetLists;
+            this.evaluator.setTargetLists(this.targetLists, true);
+        }
+    }
+    setupRealtime() {
+        var _a;
+        const endpoint = (_a = this.options.urlOverride) !== null && _a !== void 0 ? _a : `${process.env.SUPABASE_URL || 'http://localhost:54321'}/functions/v1/get-flags`;
+        this.realtimeConnection = new RealtimeConnection({
+            endpoint,
+            apiKey: this.options.apiKey,
+            environment: this.options.environment,
+            context: this.options.context,
+            onUpdate: () => {
+                // Flags changed, refresh
+                this.refresh().catch(() => { });
+            },
+            pollInterval: this.options.pollingInterval || 30000
+        });
+        this.realtimeConnection.start();
+    }
+    isEnabled(key, defaultValue = false) {
+        const value = this.getValue(key);
+        if (value === null || value === undefined)
+            return defaultValue;
+        return Boolean(value);
+    }
+    getValue(key) {
+        const flag = this.flags.get(key);
+        if (!flag)
+            return null;
+        const context = {
+            environment: this.options.environment,
+            ...this.options.context
+        };
+        return this.evaluator.evaluate(flag, context);
+    }
+    getVariation(key) {
+        return this.getValue(key);
+    }
+    getAllFlags() {
+        const result = {};
+        const context = {
+            environment: this.options.environment,
+            ...this.options.context
+        };
+        this.flags.forEach((flag, key) => {
+            result[key] = this.evaluator.evaluate(flag, context);
+        });
+        return result;
+    }
+    updateContext(newContext) {
+        var _a;
+        this.options.context = {
+            ...((_a = this.options.context) !== null && _a !== void 0 ? _a : {}),
+            ...newContext
+        };
+        // Notify listeners of potential changes
+        this.notifyChanges();
+    }
+    onChange(callback) {
+        this.changeListeners.add(callback);
+        return () => this.changeListeners.delete(callback);
+    }
+    notifyChanges() {
+        const allFlags = this.getAllFlags();
+        this.changeListeners.forEach(listener => {
+            Object.entries(allFlags).forEach(([key, value]) => {
+                listener(key, value);
+            });
+        });
+    }
+    close() {
+        if (this.pollingTimer) {
+            clearInterval(this.pollingTimer);
+        }
+        if (this.realtimeConnection) {
+            this.realtimeConnection.stop();
+        }
+        this.changeListeners.clear();
+    }
+}

package/dist/crypto.d.ts

@@ -0,0 +1,107 @@
+/**
+ * AES-256-GCM Encryption/Decryption for Target Lists
+ *
+ * This module provides secure encryption for target lists, allowing
+ * flag configurations to be shared publicly while keeping sensitive
+ * user data (like user IDs, emails) encrypted.
+ *
+ * ARCHITECTURE NOTE:
+ * ------------------
+ * This crypto module is OPTIONAL and only needed for client-side target list
+ * evaluation in offline/edge scenarios. The recommended approach is:
+ *
+ * 1. SERVER-SIDE EVALUATION (Default): Server evaluates inTargetList rules
+ *    before sending flags. SDK receives pre-filtered flags, no crypto needed.
+ *
+ * 2. CLIENT-SIDE EVALUATION (Optional): For offline/edge cases, inject a
+ *    crypto adapter. This keeps the core SDK dependency-free.
+ *
+ * To use client-side decryption, provide a CryptoAdapter implementation
+ * for your platform (Node.js, Browser, etc.)
+ */
+export interface EncryptedData {
+    _encrypted: true;
+    _algorithm: 'AES-256-GCM';
+    _iv: string;
+    _data: string;
+    _tag: string;
+}
+export interface TargetList {
+    attributeKey: string;
+    values: string[];
+}
+export interface DecryptedTargetLists {
+    [key: string]: TargetList;
+}
+/**
+ * Crypto Adapter Interface
+ *
+ * Implement this interface for your platform to enable client-side
+ * target list decryption. This keeps the core SDK dependency-free.
+ *
+ * Example implementations:
+ * - Node.js: Use built-in 'crypto' module
+ * - Browser: Use Web Crypto API
+ * - React Native: Use expo-crypto or react-native-crypto
+ */
+export interface CryptoAdapter {
+    /**
+     * Decrypt AES-256-GCM encrypted data
+     * @param ciphertext - Base64 encoded ciphertext
+     * @param key - Decryption key string
+     * @param iv - Base64 encoded initialization vector
+     * @param tag - Base64 encoded authentication tag
+     * @returns Decrypted plaintext string
+     */
+    decrypt(ciphertext: string, key: string, iv: string, tag: string): Promise<string>;
+    /**
+     * Encrypt plaintext with AES-256-GCM
+     * @param plaintext - String to encrypt
+     * @param key - Encryption key string
+     * @returns Encrypted data with IV and auth tag
+     */
+    encrypt?(plaintext: string, key: string): Promise<{
+        ciphertext: string;
+        iv: string;
+        tag: string;
+    }>;
+}
+/**
+ * Set the crypto adapter for client-side decryption
+ *
+ * Call this once at app startup if you need client-side target list evaluation.
+ * If not set, the SDK will rely on server-side evaluation (recommended).
+ *
+ * @example
+ * // Node.js
+ * import { setCryptoAdapter, createNodeCryptoAdapter } from 'flagpool-sdk';
+ * setCryptoAdapter(createNodeCryptoAdapter());
+ *
+ * @example
+ * // Browser
+ * import { setCryptoAdapter, createWebCryptoAdapter } from 'flagpool-sdk';
+ * setCryptoAdapter(createWebCryptoAdapter());
+ */
+export declare function setCryptoAdapter(adapter: CryptoAdapter): void;
+/**
+ * Get the current crypto adapter
+ */
+export declare function getCryptoAdapter(): CryptoAdapter | null;
+/**
+ * Check if a crypto adapter is available
+ */
+export declare function hasCryptoAdapter(): boolean;
+/**
+ * Decrypt target lists with AES-256-GCM
+ * Requires a crypto adapter to be set via setCryptoAdapter()
+ */
+export declare function decryptTargetLists(encryptedData: EncryptedData, decryptionKey: string): Promise<DecryptedTargetLists>;
+/**
+ * Encrypt target lists with AES-256-GCM
+ * Requires a crypto adapter with encrypt() support
+ */
+export declare function encryptTargetLists(targetLists: DecryptedTargetLists, encryptionKey: string): Promise<EncryptedData>;
+/**
+ * Check if an object is encrypted target lists
+ */
+export declare function isEncryptedTargetLists(obj: any): obj is EncryptedData;

package/dist/crypto.js

@@ -0,0 +1,99 @@
+/**
+ * AES-256-GCM Encryption/Decryption for Target Lists
+ *
+ * This module provides secure encryption for target lists, allowing
+ * flag configurations to be shared publicly while keeping sensitive
+ * user data (like user IDs, emails) encrypted.
+ *
+ * ARCHITECTURE NOTE:
+ * ------------------
+ * This crypto module is OPTIONAL and only needed for client-side target list
+ * evaluation in offline/edge scenarios. The recommended approach is:
+ *
+ * 1. SERVER-SIDE EVALUATION (Default): Server evaluates inTargetList rules
+ *    before sending flags. SDK receives pre-filtered flags, no crypto needed.
+ *
+ * 2. CLIENT-SIDE EVALUATION (Optional): For offline/edge cases, inject a
+ *    crypto adapter. This keeps the core SDK dependency-free.
+ *
+ * To use client-side decryption, provide a CryptoAdapter implementation
+ * for your platform (Node.js, Browser, etc.)
+ */
+// Global crypto adapter - set via setCryptoAdapter()
+let cryptoAdapter = null;
+/**
+ * Set the crypto adapter for client-side decryption
+ *
+ * Call this once at app startup if you need client-side target list evaluation.
+ * If not set, the SDK will rely on server-side evaluation (recommended).
+ *
+ * @example
+ * // Node.js
+ * import { setCryptoAdapter, createNodeCryptoAdapter } from 'flagpool-sdk';
+ * setCryptoAdapter(createNodeCryptoAdapter());
+ *
+ * @example
+ * // Browser
+ * import { setCryptoAdapter, createWebCryptoAdapter } from 'flagpool-sdk';
+ * setCryptoAdapter(createWebCryptoAdapter());
+ */
+export function setCryptoAdapter(adapter) {
+    cryptoAdapter = adapter;
+}
+/**
+ * Get the current crypto adapter
+ */
+export function getCryptoAdapter() {
+    return cryptoAdapter;
+}
+/**
+ * Check if a crypto adapter is available
+ */
+export function hasCryptoAdapter() {
+    return cryptoAdapter !== null;
+}
+/**
+ * Decrypt target lists with AES-256-GCM
+ * Requires a crypto adapter to be set via setCryptoAdapter()
+ */
+export async function decryptTargetLists(encryptedData, decryptionKey) {
+    if (!cryptoAdapter) {
+        throw new Error('No crypto adapter configured. Either:\n' +
+            '1. Use server-side target list evaluation (recommended)\n' +
+            '2. Call setCryptoAdapter() with a platform-specific adapter\n' +
+            '\n' +
+            'See documentation for available adapters:\n' +
+            '- createNodeCryptoAdapter() for Node.js\n' +
+            '- createWebCryptoAdapter() for browsers');
+    }
+    if (!encryptedData._encrypted || encryptedData._algorithm !== 'AES-256-GCM') {
+        throw new Error('Invalid encrypted data format');
+    }
+    const plaintext = await cryptoAdapter.decrypt(encryptedData._data, decryptionKey, encryptedData._iv, encryptedData._tag);
+    return JSON.parse(plaintext);
+}
+/**
+ * Encrypt target lists with AES-256-GCM
+ * Requires a crypto adapter with encrypt() support
+ */
+export async function encryptTargetLists(targetLists, encryptionKey) {
+    if (!(cryptoAdapter === null || cryptoAdapter === void 0 ? void 0 : cryptoAdapter.encrypt)) {
+        throw new Error('No crypto adapter with encryption support configured.\n' +
+            'Call setCryptoAdapter() with an adapter that implements encrypt().');
+    }
+    const plaintext = JSON.stringify(targetLists);
+    const { ciphertext, iv, tag } = await cryptoAdapter.encrypt(plaintext, encryptionKey);
+    return {
+        _encrypted: true,
+        _algorithm: 'AES-256-GCM',
+        _iv: iv,
+        _data: ciphertext,
+        _tag: tag
+    };
+}
+/**
+ * Check if an object is encrypted target lists
+ */
+export function isEncryptedTargetLists(obj) {
+    return obj && obj._encrypted === true && obj._algorithm === 'AES-256-GCM';
+}

package/dist/evaluator.d.ts

@@ -0,0 +1,26 @@
+import { FlagDefinition, DecryptedTargetLists } from "./types";
+export declare class Evaluator {
+    private targetLists;
+    private clientSideTargetLists;
+    /**
+     * Set target lists for client-side evaluation
+     */
+    setTargetLists(targetLists: DecryptedTargetLists | null, clientSideEnabled?: boolean): void;
+    /**
+     * Check if client-side target list evaluation is enabled
+     */
+    hasTargetLists(): boolean;
+    /**
+     * Evaluate a flag with priority-based rules.
+     * If clientSideTargetLists is enabled, inTargetList/notInTargetList rules
+     * are evaluated locally using decrypted target lists.
+     */
+    evaluate(flag: FlagDefinition, context?: Record<string, any>): any;
+    private matchesRule;
+    /**
+     * Evaluate inTargetList/notInTargetList rules
+     */
+    private evaluateTargetListRule;
+    private compare;
+    private inRollout;
+}

package/dist/evaluator.js

@@ -0,0 +1,107 @@
+import { hashString } from "./utils";
+export class Evaluator {
+    constructor() {
+        this.targetLists = null;
+        this.clientSideTargetLists = false;
+    }
+    /**
+     * Set target lists for client-side evaluation
+     */
+    setTargetLists(targetLists, clientSideEnabled = false) {
+        this.targetLists = targetLists;
+        this.clientSideTargetLists = clientSideEnabled;
+    }
+    /**
+     * Check if client-side target list evaluation is enabled
+     */
+    hasTargetLists() {
+        return this.clientSideTargetLists && this.targetLists !== null;
+    }
+    /**
+     * Evaluate a flag with priority-based rules.
+     * If clientSideTargetLists is enabled, inTargetList/notInTargetList rules
+     * are evaluated locally using decrypted target lists.
+     */
+    evaluate(flag, context = {}) {
+        var _a, _b, _c, _d, _e, _f;
+        // 1. Sort rules by priority (lower = higher priority)
+        const sortedRules = (flag.rules || []).sort((a, b) => a.priority - b.priority);
+        // 2. Evaluate rules in priority order
+        for (const rule of sortedRules) {
+            if (this.matchesRule(rule, context)) {
+                return (_b = (_a = flag.variations[rule.variation]) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : (_c = flag.variations[flag.defaultVariation]) === null || _c === void 0 ? void 0 : _c.value;
+            }
+        }
+        // 3. Check rollout percentage (if less than 100%)
+        if (flag.rolloutPercentage < 100) {
+            if (!this.inRollout(flag, context)) {
+                // Not in rollout - return "off" variation (assume index 1)
+                return (_e = (_d = flag.variations[1]) === null || _d === void 0 ? void 0 : _d.value) !== null && _e !== void 0 ? _e : false;
+            }
+        }
+        // 4. Fall back to default variation
+        return (_f = flag.variations[flag.defaultVariation]) === null || _f === void 0 ? void 0 : _f.value;
+    }
+    matchesRule(rule, context) {
+        const contextValue = context[rule.attribute];
+        // Handle target list operators
+        if (rule.operator === 'inTargetList' || rule.operator === 'notInTargetList') {
+            return this.evaluateTargetListRule(rule, context);
+        }
+        // Standard operators
+        return this.compare(contextValue, rule.operator, rule.value);
+    }
+    /**
+     * Evaluate inTargetList/notInTargetList rules
+     */
+    evaluateTargetListRule(rule, context) {
+        const targetListKey = rule.targetListKey;
+        if (!targetListKey) {
+            return false;
+        }
+        // If client-side target lists are enabled, evaluate locally
+        if (this.clientSideTargetLists && this.targetLists) {
+            const targetList = this.targetLists[targetListKey];
+            if (!targetList) {
+                // Target list not found - rule doesn't match
+                return false;
+            }
+            // Get the context value for the target list's attribute
+            const contextValue = context[targetList.attributeKey];
+            if (contextValue === undefined || contextValue === null) {
+                return rule.operator === 'notInTargetList';
+            }
+            const isInList = targetList.values.includes(String(contextValue));
+            return rule.operator === 'inTargetList' ? isInList : !isInList;
+        }
+        // Server-side evaluation fallback:
+        // If the rule exists here, assume server already filtered it
+        const contextValue = context[rule.attribute];
+        return contextValue !== undefined;
+    }
+    compare(contextValue, operator, ruleValue) {
+        switch (operator) {
+            case 'eq':
+                return contextValue === ruleValue;
+            case 'neq':
+                return contextValue !== ruleValue;
+            case 'in':
+                return Array.isArray(ruleValue) && ruleValue.includes(contextValue);
+            case 'nin':
+                return Array.isArray(ruleValue) && !ruleValue.includes(contextValue);
+            case 'contains':
+                return String(contextValue).includes(String(ruleValue));
+            case 'startsWith':
+                return String(contextValue).startsWith(String(ruleValue));
+            default:
+                return false;
+        }
+    }
+    inRollout(flag, context) {
+        const userId = context.userId || context.id;
+        if (!userId)
+            return true; // If no user ID, include in rollout
+        const hash = hashString(String(userId) + flag.key) % 100;
+        return hash < flag.rolloutPercentage;
+    }
+}

package/dist/fetcher.d.ts

@@ -0,0 +1,8 @@
+import { GetFlagsResponse } from "./types";
+export interface FetchFlagsOptions {
+    apiKey: string;
+    environment: string;
+    context?: Record<string, any>;
+    urlOverride?: string;
+}
+export declare function fetchFlags(options: FetchFlagsOptions): Promise<GetFlagsResponse>;

package/dist/fetcher.js

@@ -0,0 +1,23 @@
+export async function fetchFlags(options) {
+    var _a;
+    // Default to Supabase edge function endpoint
+    const url = (_a = options.urlOverride) !== null && _a !== void 0 ? _a : `${process.env.SUPABASE_URL || 'http://localhost:54321'}/functions/v1/get-flags`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            apiKey: options.apiKey,
+            context: {
+                environment: options.environment,
+                ...options.context
+            }
+        })
+    });
+    if (!res.ok) {
+        const error = await res.json().catch(() => ({ error: 'Failed to fetch flags' }));
+        throw new Error(error.error || `Failed to fetch flags: ${res.status}`);
+    }
+    return res.json();
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./client";
+export * from "./types";
+export { encryptTargetLists, decryptTargetLists, isEncryptedTargetLists, setCryptoAdapter, getCryptoAdapter, hasCryptoAdapter } from "./crypto";
+export type { EncryptedData, TargetList, DecryptedTargetLists, CryptoAdapter } from "./crypto";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./client";
+export * from "./types";
+export { encryptTargetLists, decryptTargetLists, isEncryptedTargetLists, setCryptoAdapter, getCryptoAdapter, hasCryptoAdapter } from "./crypto";

package/dist/realtime.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal real-time connection for flag updates
+ * Uses polling as a simple, dependency-free solution
+ */
+export interface RealtimeOptions {
+    endpoint: string;
+    apiKey: string;
+    environment: string;
+    context?: Record<string, any>;
+    onUpdate: () => void;
+    pollInterval?: number;
+}
+export declare class RealtimeConnection {
+    private options;
+    private pollTimer;
+    private lastTimestamp;
+    private isRunning;
+    constructor(options: RealtimeOptions);
+    start(): Promise<void>;
+    private poll;
+    stop(): void;
+    updateContext(context: Record<string, any>): void;
+}

package/dist/realtime.js

@@ -0,0 +1,62 @@
+/**
+ * Minimal real-time connection for flag updates
+ * Uses polling as a simple, dependency-free solution
+ */
+export class RealtimeConnection {
+    constructor(options) {
+        this.lastTimestamp = null;
+        this.isRunning = false;
+        this.options = {
+            pollInterval: 30000, // Default: 30 seconds
+            ...options
+        };
+    }
+    async start() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        // Poll immediately
+        await this.poll();
+        // Setup polling interval
+        this.pollTimer = setInterval(() => this.poll().catch(() => { }), this.options.pollInterval);
+    }
+    async poll() {
+        try {
+            const response = await fetch(this.options.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    apiKey: this.options.apiKey,
+                    context: {
+                        environment: this.options.environment,
+                        ...this.options.context
+                    },
+                    since: this.lastTimestamp // Server can optimize based on this
+                })
+            });
+            if (!response.ok)
+                return;
+            const data = await response.json();
+            // Check if data has changed
+            if (data.timestamp && data.timestamp !== this.lastTimestamp) {
+                this.lastTimestamp = data.timestamp;
+                this.options.onUpdate();
+            }
+        }
+        catch (err) {
+            // Silently fail - will retry on next interval
+        }
+    }
+    stop() {
+        this.isRunning = false;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    updateContext(context) {
+        this.options.context = context;
+    }
+}

package/dist/stream.d.ts

@@ -0,0 +1,3 @@
+export declare function startStream(): {
+    close: () => void;
+};

package/dist/stream.js

@@ -0,0 +1,6 @@
+// Legacy streaming support - replaced by Supabase Realtime
+// This file is kept for backward compatibility but is no longer used
+export function startStream() {
+    console.warn('startStream is deprecated - use Supabase Realtime streaming instead');
+    return { close: () => { } };
+}

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+export type FlagValue = boolean | string | number | object | null;
+export interface FlagpoolClientOptions {
+    apiKey: string;
+    environment: string;
+    context?: Record<string, any>;
+    pollingInterval?: number;
+    streaming?: boolean;
+    urlOverride?: string;
+    decryptionKey?: string;
+    clientSideTargetLists?: boolean;
+}
+export interface FlagVariation {
+    value: any;
+    name: string;
+}
+export interface FlagRule {
+    attribute: string;
+    operator: 'eq' | 'neq' | 'in' | 'nin' | 'contains' | 'startsWith' | 'inTargetList' | 'notInTargetList';
+    value: any;
+    targetListKey?: string;
+    variation: number;
+    priority: number;
+}
+export interface FlagDefinition {
+    key: string;
+    variations: FlagVariation[];
+    defaultVariation: number;
+    rolloutPercentage: number;
+    tags?: string[];
+    rules?: FlagRule[];
+}
+export interface GetFlagsResponse {
+    flags: FlagDefinition[];
+    environment: {
+        key: string;
+        name: string;
+    };
+    timestamp: string;
+    targetLists?: EncryptedTargetLists | DecryptedTargetLists;
+}
+export interface EncryptedTargetLists {
+    _encrypted: true;
+    _algorithm: 'AES-256-GCM';
+    _iv: string;
+    _data: string;
+    _tag: string;
+}
+export interface TargetList {
+    attributeKey: string;
+    values: string[];
+}
+export interface DecryptedTargetLists {
+    [key: string]: TargetList;
+}
+export type FlagChangedCallback = (key: string, newValue: any) => void;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1 @@
+export declare function hashString(str: string): number;

package/dist/utils.js

@@ -0,0 +1,8 @@
+export function hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        hash = (hash << 5) - hash + str.charCodeAt(i);
+        hash |= 0;
+    }
+    return Math.abs(hash);
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@flagpool/sdk",
+  "version": "0.1.0",
+  "description": "Official Flagpool SDK for TypeScript/JavaScript - feature flags with local evaluation, deterministic rollouts, and encrypted target lists",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flagpool/flagpool-sdk.git",
+    "directory": "sdks/typescript"
+  },
+  "homepage": "https://github.com/flagpool/flagpool-sdk/tree/main/sdks/typescript#readme",
+  "bugs": {
+    "url": "https://github.com/flagpool/flagpool-sdk/issues"
+  },
+  "author": "Flagpool",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "sdk",
+    "flagpool",
+    "ab-testing",
+    "rollouts",
+    "targeting"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.10",
+    "@vitest/ui": "^4.0.10",
+    "eventsource": "^4.1.0",
+    "typescript": "^5.5.2",
+    "vitest": "^4.0.10"
+  }
+}