@featureflip/js 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+# @featureflip/sdk
+
+Server-side JavaScript/TypeScript SDK for [Featureflip](https://github.com/featureflip/featureflip) - evaluate feature flags locally with near-zero latency.
+
+## Installation
+
+```bash
+npm install @featureflip/sdk
+```
+
+## Quick Start
+
+```ts
+import { FeatureflipClient } from '@featureflip/sdk';
+
+const client = new FeatureflipClient({
+  sdkKey: 'your-sdk-key',
+});
+
+await client.waitForInitialization();
+
+const enabled = client.boolVariation('my-feature', { user_id: '123' }, false);
+
+if (enabled) {
+  console.log('Feature is enabled!');
+}
+
+await client.close();
+```
+
+## Configuration
+
+```ts
+const client = new FeatureflipClient({
+  sdkKey: 'your-sdk-key',
+  baseUrl: 'https://eval.featureflip.io', // Evaluation API URL (default)
+  streaming: true,           // Use SSE for real-time updates (default)
+  pollInterval: 30000,       // Polling interval in ms if streaming=false
+  flushInterval: 30000,      // Event flush interval in ms
+  flushBatchSize: 100,       // Events per batch
+  initTimeout: 10000,        // Max ms to wait for initialization
+  maxStreamRetries: 5,       // SSE retries before falling back to polling
+});
+```
+
+The SDK key can also be set via the `FEATUREFLIP_SDK_KEY` environment variable.
+
+## Evaluation
+
+```ts
+const context = { user_id: '123', email: 'user@example.com' };
+
+// Boolean flag
+const enabled = client.boolVariation('feature-key', context, false);
+
+// String flag
+const tier = client.stringVariation('pricing-tier', context, 'free');
+
+// Number flag
+const limit = client.numberVariation('rate-limit', context, 100);
+
+// JSON flag
+const config = client.jsonVariation('ui-config', context, { theme: 'light' });
+```
+
+### Detailed Evaluation
+
+```ts
+const detail = client.variationDetail('feature-key', { user_id: '123' }, false);
+
+console.log(detail.value);   // The evaluated value
+console.log(detail.reason);  // "RuleMatch", "Fallthrough", "FlagDisabled", etc.
+console.log(detail.ruleId);  // Rule ID if reason is "RuleMatch"
+```
+
+## Event Tracking
+
+```ts
+// Track custom events
+client.track('checkout-completed', { user_id: '123' }, { total: 99.99 });
+
+// Identify users for segment building
+client.identify({ user_id: '123', email: 'user@example.com', plan: 'pro' });
+
+// Force flush pending events
+await client.flush();
+```
+
+## Testing
+
+Use `forTesting()` to create a client with predetermined flag values -- no network calls.
+
+```ts
+const client = FeatureflipClient.forTesting({
+  'my-feature': true,
+  'pricing-tier': 'pro',
+});
+
+client.boolVariation('my-feature', {}, false);     // true
+client.stringVariation('pricing-tier', {}, 'free'); // 'pro'
+client.boolVariation('unknown', {}, false);         // false (default)
+```
+
+## Features
+
+- **Local evaluation** - Near-zero latency after initialization
+- **Real-time updates** - SSE streaming with automatic polling fallback
+- **Event tracking** - Automatic batching and background flushing
+- **Test support** - `forTesting()` factory for deterministic unit tests
+- **TypeScript** - Full type definitions included
+
+## Requirements
+
+- Node.js 18+
+
+## License
+
+MIT

package/dist/browser.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./client-Bf3tS17L.cjs`);function t(){return{md5(e){return i(e)},createEventSource(e,t){let n=new EventSource(e);return{addEventListener:(e,t)=>{n.addEventListener(e,e=>t(e))},close:()=>n.close(),get readyState(){return n.readyState}}},async fetch(e,t){return globalThis.fetch(e,t)}}}var n=[7,12,17,22,7,12,17,22,7,12,17,22,7,12,17,22,5,9,14,20,5,9,14,20,5,9,14,20,5,9,14,20,4,11,16,23,4,11,16,23,4,11,16,23,4,11,16,23,6,10,15,21,6,10,15,21,6,10,15,21,6,10,15,21],r=new Uint32Array(64);for(let e=0;e<64;e++)r[e]=Math.floor(2**32*Math.abs(Math.sin(e+1)))>>>0;function i(e){let t=new TextEncoder().encode(e),i=t.length*8,a=(56-(t.length+1)%64+64)%64,o=new Uint8Array(t.length+1+a+8);o.set(t),o[t.length]=128;let s=new DataView(o.buffer);s.setUint32(o.length-8,i>>>0,!0),s.setUint32(o.length-4,0,!0);let c=1732584193,l=4023233417,u=2562383102,d=271733878;for(let e=0;e<o.length;e+=64){let t=new Uint32Array(16);for(let n=0;n<16;n++)t[n]=s.getUint32(e+n*4,!0);let i=c,a=l,o=u,f=d;for(let e=0;e<64;e++){let s,c;e<16?(s=a&o|~a&f,c=e):e<32?(s=f&a|~f&o,c=(5*e+1)%16):e<48?(s=a^o^f,c=(3*e+5)%16):(s=o^(a|~f),c=7*e%16),s=s+i+r[e]+t[c]>>>0,i=f,f=o,o=a,a=a+(s<<n[e]|s>>>32-n[e])>>>0}c=c+i>>>0,l=l+a>>>0,u=u+o>>>0,d=d+f>>>0}let f=new Uint8Array(16),p=new DataView(f.buffer);return p.setUint32(0,c,!0),p.setUint32(4,l,!0),p.setUint32(8,u,!0),p.setUint32(12,d,!0),f}exports.FeatureflipClient=e.t,exports.createBrowserPlatform=t;

package/dist/browser.d.ts

@@ -0,0 +1,117 @@
+export declare function createBrowserPlatform(): Platform;
+
+export declare type EvaluationContext = Record<string, unknown>;
+
+export declare interface EvaluationDetail<T = unknown> {
+    value: T;
+    variationKey?: string;
+    reason: EvaluationReason;
+    ruleId?: string;
+}
+
+export declare type EvaluationReason = 'RuleMatch' | 'Fallthrough' | 'FlagDisabled' | 'FlagNotFound' | 'Error';
+
+declare interface EventSourceLike {
+    addEventListener(type: string, listener: (event: {
+        data: string;
+    }) => void): void;
+    close(): void;
+    readonly readyState: number;
+}
+
+export declare class FeatureflipClient {
+    private readonly config;
+    private readonly store;
+    private readonly events;
+    private readonly platform;
+    private initialized;
+    private initPromise;
+    private eventSource;
+    private pollTimer;
+    private closed;
+    private streamRetryCount;
+    private streamRetryTimer;
+    constructor(config: FeatureflipConfig, platform: Platform);
+    /** Whether the client has successfully loaded initial flag data. */
+    get isInitialized(): boolean;
+    /**
+     * Wait for the client to finish initialization.
+     * Rejects after initTimeout if initial flag fetch fails.
+     */
+    waitForInitialization(): Promise<void>;
+    /**
+     * Evaluate a boolean flag.
+     * Returns defaultValue if flag not found or evaluation fails.
+     */
+    boolVariation(key: string, context: EvaluationContext, defaultValue: boolean): boolean;
+    /**
+     * Evaluate a string flag.
+     */
+    stringVariation(key: string, context: EvaluationContext, defaultValue: string): string;
+    /**
+     * Evaluate a number flag.
+     */
+    numberVariation(key: string, context: EvaluationContext, defaultValue: number): number;
+    /**
+     * Evaluate a JSON flag.
+     */
+    jsonVariation<T>(key: string, context: EvaluationContext, defaultValue: T): T;
+    /**
+     * Evaluate a flag and return the full detail including reason.
+     */
+    variationDetail<T>(key: string, context: EvaluationContext, defaultValue: T): EvaluationDetail<T>;
+    /**
+     * Track a custom event.
+     */
+    track(eventKey: string, context: EvaluationContext, metadata?: Record<string, unknown>): void;
+    /**
+     * Send an identify event for the given context.
+     */
+    identify(context: EvaluationContext): void;
+    /**
+     * Flush any pending events immediately.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the client, flushing pending events and stopping all connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Create a test client with hardcoded flag values. No network calls.
+     */
+    static forTesting(flags: Record<string, unknown>): FeatureflipClient;
+    private evaluateFlag;
+    private initialize;
+    private fetchFlags;
+    private startDataSource;
+    private startStreaming;
+    private startPolling;
+    private fetchSingleFlag;
+    private recordEvaluation;
+    private headers;
+}
+
+export declare interface FeatureflipConfig {
+    sdkKey: string;
+    baseUrl: string;
+    streaming?: boolean;
+    pollInterval?: number;
+    flushInterval?: number;
+    flushBatchSize?: number;
+    initTimeout?: number;
+    maxStreamRetries?: number;
+}
+
+export declare type FlagType = 'Boolean' | 'String' | 'Number' | 'Json';
+
+export declare interface Platform {
+    md5(input: string): Uint8Array;
+    createEventSource(url: string, headers: Record<string, string>): EventSourceLike;
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** Extra headers the platform can inject (e.g. User-Agent on Node). */
+    readonly extraHeaders?: Record<string, string>;
+    /** Whether the platform's EventSource implementation supports custom headers. */
+    readonly sseSupportsHeaders?: boolean;
+}
+
+export { }

package/dist/browser.mjs

@@ -0,0 +1,112 @@
+import { t as e } from "./client-ChXPtrh5.js";
+//#region src/platform/browser.ts
+function t() {
+	return {
+		md5(e) {
+			return i(e);
+		},
+		createEventSource(e, t) {
+			let n = new EventSource(e);
+			return {
+				addEventListener: (e, t) => {
+					n.addEventListener(e, (e) => t(e));
+				},
+				close: () => n.close(),
+				get readyState() {
+					return n.readyState;
+				}
+			};
+		},
+		async fetch(e, t) {
+			return globalThis.fetch(e, t);
+		}
+	};
+}
+var n = [
+	7,
+	12,
+	17,
+	22,
+	7,
+	12,
+	17,
+	22,
+	7,
+	12,
+	17,
+	22,
+	7,
+	12,
+	17,
+	22,
+	5,
+	9,
+	14,
+	20,
+	5,
+	9,
+	14,
+	20,
+	5,
+	9,
+	14,
+	20,
+	5,
+	9,
+	14,
+	20,
+	4,
+	11,
+	16,
+	23,
+	4,
+	11,
+	16,
+	23,
+	4,
+	11,
+	16,
+	23,
+	4,
+	11,
+	16,
+	23,
+	6,
+	10,
+	15,
+	21,
+	6,
+	10,
+	15,
+	21,
+	6,
+	10,
+	15,
+	21,
+	6,
+	10,
+	15,
+	21
+], r = new Uint32Array(64);
+for (let e = 0; e < 64; e++) r[e] = Math.floor(2 ** 32 * Math.abs(Math.sin(e + 1))) >>> 0;
+function i(e) {
+	let t = new TextEncoder().encode(e), i = t.length * 8, a = (56 - (t.length + 1) % 64 + 64) % 64, o = new Uint8Array(t.length + 1 + a + 8);
+	o.set(t), o[t.length] = 128;
+	let s = new DataView(o.buffer);
+	s.setUint32(o.length - 8, i >>> 0, !0), s.setUint32(o.length - 4, 0, !0);
+	let c = 1732584193, l = 4023233417, u = 2562383102, d = 271733878;
+	for (let e = 0; e < o.length; e += 64) {
+		let t = new Uint32Array(16);
+		for (let n = 0; n < 16; n++) t[n] = s.getUint32(e + n * 4, !0);
+		let i = c, a = l, o = u, f = d;
+		for (let e = 0; e < 64; e++) {
+			let s, c;
+			e < 16 ? (s = a & o | ~a & f, c = e) : e < 32 ? (s = f & a | ~f & o, c = (5 * e + 1) % 16) : e < 48 ? (s = a ^ o ^ f, c = (3 * e + 5) % 16) : (s = o ^ (a | ~f), c = 7 * e % 16), s = s + i + r[e] + t[c] >>> 0, i = f, f = o, o = a, a = a + (s << n[e] | s >>> 32 - n[e]) >>> 0;
+		}
+		c = c + i >>> 0, l = l + a >>> 0, u = u + o >>> 0, d = d + f >>> 0;
+	}
+	let f = new Uint8Array(16), p = new DataView(f.buffer);
+	return p.setUint32(0, c, !0), p.setUint32(4, l, !0), p.setUint32(8, u, !0), p.setUint32(12, d, !0), f;
+}
+//#endregion
+export { e as FeatureflipClient, t as createBrowserPlatform };

package/dist/client-Bf3tS17L.cjs

@@ -0,0 +1 @@
+var e={streaming:!0,pollInterval:3e4,flushInterval:3e4,flushBatchSize:100,initTimeout:1e4,maxStreamRetries:5};function t(t){if(!t.sdkKey)throw Error(`sdkKey is required`);if(!t.baseUrl)throw Error(`baseUrl is required`);let n=t.baseUrl.replace(/\/+$/,``);return{sdkKey:t.sdkKey,baseUrl:n,streaming:t.streaming??e.streaming,pollInterval:t.pollInterval??e.pollInterval,flushInterval:t.flushInterval??e.flushInterval,flushBatchSize:t.flushBatchSize??e.flushBatchSize,initTimeout:t.initTimeout??e.initTimeout,maxStreamRetries:t.maxStreamRetries??e.maxStreamRetries}}var n=class{flags=new Map;segments=new Map;listeners=[];version=0;getFlag(e){return this.flags.get(e)}getSegment(e){return this.segments.get(e)}getAllFlags(){return Array.from(this.flags.values())}getVersion(){return this.version}init(e,t,n){this.flags.clear(),this.segments.clear();for(let t of e)this.flags.set(t.key,t);for(let e of t)this.segments.set(e.key,e);this.version=n;for(let t of e)this.notifyListeners(t.key)}upsert(e){let t=this.flags.get(e.key);t&&t.version>=e.version||(this.flags.set(e.key,e),this.notifyListeners(e.key))}delete(e){this.flags.delete(e)&&this.notifyListeners(e)}onChange(e){return this.listeners.push(e),()=>{let t=this.listeners.indexOf(e);t>=0&&this.listeners.splice(t,1)}}notifyListeners(e){for(let t of this.listeners)try{t(e)}catch{}}};function r(e,t,n){let r=n(`${e}:${t}`);return((r[0]|r[1]<<8|r[2]<<16|r[3]<<24>>>0)>>>0)%100}function i(e,t){let n=e[t];if(n!==void 0)return n;if(t===`userId`)return e.user_id;if(t===`user_id`)return e.userId}function a(e,t,n){switch(e){case`Equals`:return n.some(e=>t===e);case`NotEquals`:return n.every(e=>t!==e);case`Contains`:return n.some(e=>t.includes(e));case`NotContains`:return n.every(e=>!t.includes(e));case`StartsWith`:return n.some(e=>t.startsWith(e));case`EndsWith`:return n.some(e=>t.endsWith(e));case`In`:return n.includes(t);case`NotIn`:return!n.includes(t);case`MatchesRegex`:return n.some(e=>{try{return new RegExp(e,`i`).test(t)}catch{return!1}});case`GreaterThan`:return o(t,n[0],`>`);case`GreaterThanOrEqual`:return o(t,n[0],`>=`);case`LessThan`:return o(t,n[0],`<`);case`LessThanOrEqual`:return o(t,n[0],`<=`);case`Before`:return t<n[0];case`After`:return t>n[0];default:return!1}}function o(e,t,n){let r=parseFloat(e),i=parseFloat(t);if(isNaN(r)||isNaN(i))return!1;switch(n){case`>`:return r>i;case`<`:return r<i;case`>=`:return r>=i;case`<=`:return r<=i}}function s(e,t){let n=i(t,e.attribute);if(n==null)return e.negate;let r=String(n).toLowerCase(),o=e.values.map(e=>e.toLowerCase()),s=a(e.operator,r,o);return e.negate?!s:s}function c(e,t,n){return e.length===0?!0:t===`And`?e.every(e=>s(e,n)):e.some(e=>s(e,n))}function l(e,t){return e.length===0?!0:e.every(e=>c(e.conditions,e.operator,t))}function u(e,t,n){if(e.type===`Fixed`)return e.variation??``;let a=i(t,e.bucketBy??`userId`),o=a==null?``:String(a),s=r(e.salt??``,o,n),c=0;for(let t of e.variations??[])if(c+=t.weight,s<c)return t.key;let l=e.variations??[];return l.length>0?l[l.length-1].key:``}function d(e,t,n){if(!e.enabled)return{value:e.variations.find(t=>t.key===e.offVariation)?.value??null,variationKey:e.offVariation,reason:`FlagDisabled`};let r=[...e.rules].sort((e,t)=>e.priority-t.priority);for(let i of r){let r;if(i.segmentKey&&n.getSegment){let e=n.getSegment(i.segmentKey);r=e?c(e.conditions,e.conditionLogic,t):!1}else r=l(i.conditionGroups,t);if(r){let r=u(i.serve,t,n.md5);return{value:e.variations.find(e=>e.key===r)?.value??null,variationKey:r,reason:`RuleMatch`,ruleId:i.id}}}let i=u(e.fallthrough,t,n.md5);return{value:e.variations.find(e=>e.key===i)?.value??null,variationKey:i,reason:`Fallthrough`}}var f=class{queue=[];flushTimer=null;closed=!1;flushPromise=null;constructor(e,t,n){this.sender=e,this.flushInterval=t,this.flushBatchSize=n}start(){this.flushTimer||=setInterval(()=>{this.flush()},this.flushInterval)}enqueue(e){this.closed||(this.queue.push(e),this.queue.length>=this.flushBatchSize&&this.flush())}async flush(){if(this.queue.length!==0)return this.flushPromise||=(async()=>{for(;this.queue.length>0;){let e=this.queue.splice(0,this.flushBatchSize);try{await this.sender.sendEvents({events:e})}catch{}}})().finally(()=>{this.flushPromise=null}),this.flushPromise}async close(){for(this.closed=!0,this.flushTimer&&=(clearInterval(this.flushTimer),null);this.queue.length>0;)await this.flush()}},p=class e{config;store;events;platform;initialized=!1;initPromise=null;eventSource=null;pollTimer=null;closed=!1;streamRetryCount=0;streamRetryTimer=null;constructor(e,r){this.config=t(e),this.store=new n,this.platform=r,this.events=new f({sendEvents:async e=>{await this.platform.fetch(`${this.config.baseUrl}/v1/sdk/events`,{method:`POST`,headers:this.headers(),body:JSON.stringify(e)})}},this.config.flushInterval,this.config.flushBatchSize)}get isInitialized(){return this.initialized}async waitForInitialization(){if(!this.initialized)return this.initPromise||=this.initialize(),this.initPromise}boolVariation(e,t,n){return this.evaluateFlag(e,t,n)}stringVariation(e,t,n){return this.evaluateFlag(e,t,n)}numberVariation(e,t,n){return this.evaluateFlag(e,t,n)}jsonVariation(e,t,n){return this.evaluateFlag(e,t,n)}variationDetail(e,t,n){let r=this.store.getFlag(e);if(!r)return this.recordEvaluation(e,t,void 0),{value:n,reason:`FlagNotFound`};try{let i=d(r,t,{md5:e=>this.platform.md5(e),getSegment:e=>this.store.getSegment(e)}),a=i.value!==void 0&&i.value!==null?i.value:n;return this.recordEvaluation(e,t,i.variationKey),{value:a,reason:i.reason,ruleId:i.ruleId}}catch{return this.recordEvaluation(e,t,void 0),{value:n,reason:`Error`}}}track(e,t,n){let r=t.user_id==null?void 0:String(t.user_id);this.events.enqueue({type:`Custom`,flagKey:e,userId:r,timestamp:new Date().toISOString(),metadata:n})}identify(e){let t=e.user_id==null?void 0:String(e.user_id),{user_id:n,...r}=e;this.events.enqueue({type:`Identify`,flagKey:`$identify`,userId:t,timestamp:new Date().toISOString(),metadata:Object.keys(r).length>0?r:void 0})}async flush(){await this.events.flush()}async close(){this.closed=!0,this.eventSource?.close(),this.eventSource=null,this.streamRetryTimer&&=(clearTimeout(this.streamRetryTimer),null),this.pollTimer&&=(clearInterval(this.pollTimer),null),await this.events.close()}static forTesting(t){let n=Object.entries(t).map(([e,t])=>({key:e,version:1,type:typeof t==`boolean`?`Boolean`:typeof t==`number`?`Number`:typeof t==`string`?`String`:`Json`,enabled:!0,variations:[{key:`default`,value:t}],rules:[],fallthrough:{type:`Fixed`,variation:`default`},offVariation:`default`})),r=new e({sdkKey:`test-key`,baseUrl:`http://localhost`},{md5:()=>new Uint8Array(16),createEventSource:()=>({addEventListener:()=>{},close:()=>{},readyState:2}),fetch:async()=>new Response});return r.store.init(n,[],1),r.initialized=!0,r}evaluateFlag(e,t,n){return this.variationDetail(e,t,n).value}async initialize(){let e,t=new Promise((t,n)=>{e=setTimeout(()=>n(Error(`Initialization timed out`)),this.config.initTimeout)}),n=(async()=>{await this.fetchFlags(),this.initialized=!0,this.events.start(),this.startDataSource()})();try{await Promise.race([n,t])}finally{clearTimeout(e)}}async fetchFlags(){let e=await this.platform.fetch(`${this.config.baseUrl}/v1/sdk/flags`,{headers:this.headers()});if(!e.ok)throw Error(`Failed to fetch flags: ${e.status}`);let t=await e.json();this.store.init(t.flags,t.segments,t.version)}startDataSource(){this.closed||(this.config.streaming?this.startStreaming():this.startPolling())}startStreaming(){if(this.closed)return;let e=this.platform.sseSupportsHeaders?`${this.config.baseUrl}/v1/sdk/stream`:`${this.config.baseUrl}/v1/sdk/stream?authorization=${encodeURIComponent(this.config.sdkKey)}`;this.eventSource=this.platform.createEventSource(e,this.headers());for(let e of[`flag.created`,`flag.updated`])this.eventSource.addEventListener(e,e=>{try{let t=JSON.parse(e.data);t.key&&this.fetchSingleFlag(t.key)}catch{}});this.eventSource.addEventListener(`flag.deleted`,e=>{try{let t=JSON.parse(e.data);t.key&&this.store.delete(t.key)}catch{}}),this.eventSource.addEventListener(`segment.updated`,()=>{this.fetchFlags().catch(()=>{})}),this.eventSource.addEventListener(`open`,()=>{this.streamRetryCount=0}),this.eventSource.addEventListener(`error`,()=>{if(this.eventSource?.close(),this.eventSource=null,this.closed)return;if(this.streamRetryCount>=this.config.maxStreamRetries){console.warn(`[featureflip] SSE connection failed after ${this.config.maxStreamRetries} retries, falling back to polling`),this.startPolling();return}let e=Math.min(1e3*2**this.streamRetryCount,3e4);this.streamRetryCount++,this.streamRetryTimer=setTimeout(()=>{this.streamRetryTimer=null,this.startStreaming()},e)})}startPolling(){this.pollTimer=setInterval(()=>{this.fetchFlags().catch(()=>{})},this.config.pollInterval)}async fetchSingleFlag(e){try{let t=await this.platform.fetch(`${this.config.baseUrl}/v1/sdk/flags/${encodeURIComponent(e)}`,{headers:this.headers()});if(t.ok){let e=await t.json();this.store.upsert(e)}}catch{}}recordEvaluation(e,t,n){let r=t.user_id==null?void 0:String(t.user_id);this.events.enqueue({type:`Evaluation`,flagKey:e,userId:r,variation:n,timestamp:new Date().toISOString()})}headers(){return{Authorization:this.config.sdkKey,"Content-Type":`application/json`,...this.platform.extraHeaders}}};Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return p}});

package/dist/client-ChXPtrh5.js

@@ -0,0 +1,406 @@
+//#region src/config.ts
+var e = {
+	streaming: !0,
+	pollInterval: 3e4,
+	flushInterval: 3e4,
+	flushBatchSize: 100,
+	initTimeout: 1e4,
+	maxStreamRetries: 5
+};
+function t(t) {
+	if (!t.sdkKey) throw Error("sdkKey is required");
+	if (!t.baseUrl) throw Error("baseUrl is required");
+	let n = t.baseUrl.replace(/\/+$/, "");
+	return {
+		sdkKey: t.sdkKey,
+		baseUrl: n,
+		streaming: t.streaming ?? e.streaming,
+		pollInterval: t.pollInterval ?? e.pollInterval,
+		flushInterval: t.flushInterval ?? e.flushInterval,
+		flushBatchSize: t.flushBatchSize ?? e.flushBatchSize,
+		initTimeout: t.initTimeout ?? e.initTimeout,
+		maxStreamRetries: t.maxStreamRetries ?? e.maxStreamRetries
+	};
+}
+//#endregion
+//#region src/core/store.ts
+var n = class {
+	flags = /* @__PURE__ */ new Map();
+	segments = /* @__PURE__ */ new Map();
+	listeners = [];
+	version = 0;
+	getFlag(e) {
+		return this.flags.get(e);
+	}
+	getSegment(e) {
+		return this.segments.get(e);
+	}
+	getAllFlags() {
+		return Array.from(this.flags.values());
+	}
+	getVersion() {
+		return this.version;
+	}
+	init(e, t, n) {
+		this.flags.clear(), this.segments.clear();
+		for (let t of e) this.flags.set(t.key, t);
+		for (let e of t) this.segments.set(e.key, e);
+		this.version = n;
+		for (let t of e) this.notifyListeners(t.key);
+	}
+	upsert(e) {
+		let t = this.flags.get(e.key);
+		t && t.version >= e.version || (this.flags.set(e.key, e), this.notifyListeners(e.key));
+	}
+	delete(e) {
+		this.flags.delete(e) && this.notifyListeners(e);
+	}
+	onChange(e) {
+		return this.listeners.push(e), () => {
+			let t = this.listeners.indexOf(e);
+			t >= 0 && this.listeners.splice(t, 1);
+		};
+	}
+	notifyListeners(e) {
+		for (let t of this.listeners) try {
+			t(e);
+		} catch {}
+	}
+};
+//#endregion
+//#region src/core/evaluator.ts
+function r(e, t, n) {
+	let r = n(`${e}:${t}`);
+	return ((r[0] | r[1] << 8 | r[2] << 16 | r[3] << 24 >>> 0) >>> 0) % 100;
+}
+function i(e, t) {
+	let n = e[t];
+	if (n !== void 0) return n;
+	if (t === "userId") return e.user_id;
+	if (t === "user_id") return e.userId;
+}
+function a(e, t, n) {
+	switch (e) {
+		case "Equals": return n.some((e) => t === e);
+		case "NotEquals": return n.every((e) => t !== e);
+		case "Contains": return n.some((e) => t.includes(e));
+		case "NotContains": return n.every((e) => !t.includes(e));
+		case "StartsWith": return n.some((e) => t.startsWith(e));
+		case "EndsWith": return n.some((e) => t.endsWith(e));
+		case "In": return n.includes(t);
+		case "NotIn": return !n.includes(t);
+		case "MatchesRegex": return n.some((e) => {
+			try {
+				return new RegExp(e, "i").test(t);
+			} catch {
+				return !1;
+			}
+		});
+		case "GreaterThan": return o(t, n[0], ">");
+		case "GreaterThanOrEqual": return o(t, n[0], ">=");
+		case "LessThan": return o(t, n[0], "<");
+		case "LessThanOrEqual": return o(t, n[0], "<=");
+		case "Before": return t < n[0];
+		case "After": return t > n[0];
+		default: return !1;
+	}
+}
+function o(e, t, n) {
+	let r = parseFloat(e), i = parseFloat(t);
+	if (isNaN(r) || isNaN(i)) return !1;
+	switch (n) {
+		case ">": return r > i;
+		case "<": return r < i;
+		case ">=": return r >= i;
+		case "<=": return r <= i;
+	}
+}
+function s(e, t) {
+	let n = i(t, e.attribute);
+	if (n == null) return e.negate;
+	let r = String(n).toLowerCase(), o = e.values.map((e) => e.toLowerCase()), s = a(e.operator, r, o);
+	return e.negate ? !s : s;
+}
+function c(e, t, n) {
+	return e.length === 0 ? !0 : t === "And" ? e.every((e) => s(e, n)) : e.some((e) => s(e, n));
+}
+function l(e, t) {
+	return e.length === 0 ? !0 : e.every((e) => c(e.conditions, e.operator, t));
+}
+function u(e, t, n) {
+	if (e.type === "Fixed") return e.variation ?? "";
+	let a = i(t, e.bucketBy ?? "userId"), o = a == null ? "" : String(a), s = r(e.salt ?? "", o, n), c = 0;
+	for (let t of e.variations ?? []) if (c += t.weight, s < c) return t.key;
+	let l = e.variations ?? [];
+	return l.length > 0 ? l[l.length - 1].key : "";
+}
+function d(e, t, n) {
+	if (!e.enabled) return {
+		value: e.variations.find((t) => t.key === e.offVariation)?.value ?? null,
+		variationKey: e.offVariation,
+		reason: "FlagDisabled"
+	};
+	let r = [...e.rules].sort((e, t) => e.priority - t.priority);
+	for (let i of r) {
+		let r;
+		if (i.segmentKey && n.getSegment) {
+			let e = n.getSegment(i.segmentKey);
+			r = e ? c(e.conditions, e.conditionLogic, t) : !1;
+		} else r = l(i.conditionGroups, t);
+		if (r) {
+			let r = u(i.serve, t, n.md5);
+			return {
+				value: e.variations.find((e) => e.key === r)?.value ?? null,
+				variationKey: r,
+				reason: "RuleMatch",
+				ruleId: i.id
+			};
+		}
+	}
+	let i = u(e.fallthrough, t, n.md5);
+	return {
+		value: e.variations.find((e) => e.key === i)?.value ?? null,
+		variationKey: i,
+		reason: "Fallthrough"
+	};
+}
+//#endregion
+//#region src/core/events.ts
+var f = class {
+	queue = [];
+	flushTimer = null;
+	closed = !1;
+	flushPromise = null;
+	constructor(e, t, n) {
+		this.sender = e, this.flushInterval = t, this.flushBatchSize = n;
+	}
+	start() {
+		this.flushTimer ||= setInterval(() => {
+			this.flush();
+		}, this.flushInterval);
+	}
+	enqueue(e) {
+		this.closed || (this.queue.push(e), this.queue.length >= this.flushBatchSize && this.flush());
+	}
+	async flush() {
+		if (this.queue.length !== 0) return this.flushPromise ||= (async () => {
+			for (; this.queue.length > 0;) {
+				let e = this.queue.splice(0, this.flushBatchSize);
+				try {
+					await this.sender.sendEvents({ events: e });
+				} catch {}
+			}
+		})().finally(() => {
+			this.flushPromise = null;
+		}), this.flushPromise;
+	}
+	async close() {
+		for (this.closed = !0, this.flushTimer &&= (clearInterval(this.flushTimer), null); this.queue.length > 0;) await this.flush();
+	}
+}, p = class e {
+	config;
+	store;
+	events;
+	platform;
+	initialized = !1;
+	initPromise = null;
+	eventSource = null;
+	pollTimer = null;
+	closed = !1;
+	streamRetryCount = 0;
+	streamRetryTimer = null;
+	constructor(e, r) {
+		this.config = t(e), this.store = new n(), this.platform = r, this.events = new f({ sendEvents: async (e) => {
+			await this.platform.fetch(`${this.config.baseUrl}/v1/sdk/events`, {
+				method: "POST",
+				headers: this.headers(),
+				body: JSON.stringify(e)
+			});
+		} }, this.config.flushInterval, this.config.flushBatchSize);
+	}
+	get isInitialized() {
+		return this.initialized;
+	}
+	async waitForInitialization() {
+		if (!this.initialized) return this.initPromise ||= this.initialize(), this.initPromise;
+	}
+	boolVariation(e, t, n) {
+		return this.evaluateFlag(e, t, n);
+	}
+	stringVariation(e, t, n) {
+		return this.evaluateFlag(e, t, n);
+	}
+	numberVariation(e, t, n) {
+		return this.evaluateFlag(e, t, n);
+	}
+	jsonVariation(e, t, n) {
+		return this.evaluateFlag(e, t, n);
+	}
+	variationDetail(e, t, n) {
+		let r = this.store.getFlag(e);
+		if (!r) return this.recordEvaluation(e, t, void 0), {
+			value: n,
+			reason: "FlagNotFound"
+		};
+		try {
+			let i = d(r, t, {
+				md5: (e) => this.platform.md5(e),
+				getSegment: (e) => this.store.getSegment(e)
+			}), a = i.value !== void 0 && i.value !== null ? i.value : n;
+			return this.recordEvaluation(e, t, i.variationKey), {
+				value: a,
+				reason: i.reason,
+				ruleId: i.ruleId
+			};
+		} catch {
+			return this.recordEvaluation(e, t, void 0), {
+				value: n,
+				reason: "Error"
+			};
+		}
+	}
+	track(e, t, n) {
+		let r = t.user_id == null ? void 0 : String(t.user_id);
+		this.events.enqueue({
+			type: "Custom",
+			flagKey: e,
+			userId: r,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			metadata: n
+		});
+	}
+	identify(e) {
+		let t = e.user_id == null ? void 0 : String(e.user_id), { user_id: n, ...r } = e;
+		this.events.enqueue({
+			type: "Identify",
+			flagKey: "$identify",
+			userId: t,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			metadata: Object.keys(r).length > 0 ? r : void 0
+		});
+	}
+	async flush() {
+		await this.events.flush();
+	}
+	async close() {
+		this.closed = !0, this.eventSource?.close(), this.eventSource = null, this.streamRetryTimer &&= (clearTimeout(this.streamRetryTimer), null), this.pollTimer &&= (clearInterval(this.pollTimer), null), await this.events.close();
+	}
+	static forTesting(t) {
+		let n = Object.entries(t).map(([e, t]) => ({
+			key: e,
+			version: 1,
+			type: typeof t == "boolean" ? "Boolean" : typeof t == "number" ? "Number" : typeof t == "string" ? "String" : "Json",
+			enabled: !0,
+			variations: [{
+				key: "default",
+				value: t
+			}],
+			rules: [],
+			fallthrough: {
+				type: "Fixed",
+				variation: "default"
+			},
+			offVariation: "default"
+		})), r = new e({
+			sdkKey: "test-key",
+			baseUrl: "http://localhost"
+		}, {
+			md5: () => new Uint8Array(16),
+			createEventSource: () => ({
+				addEventListener: () => {},
+				close: () => {},
+				readyState: 2
+			}),
+			fetch: async () => new Response()
+		});
+		return r.store.init(n, [], 1), r.initialized = !0, r;
+	}
+	evaluateFlag(e, t, n) {
+		return this.variationDetail(e, t, n).value;
+	}
+	async initialize() {
+		let e, t = new Promise((t, n) => {
+			e = setTimeout(() => n(/* @__PURE__ */ Error("Initialization timed out")), this.config.initTimeout);
+		}), n = (async () => {
+			await this.fetchFlags(), this.initialized = !0, this.events.start(), this.startDataSource();
+		})();
+		try {
+			await Promise.race([n, t]);
+		} finally {
+			clearTimeout(e);
+		}
+	}
+	async fetchFlags() {
+		let e = await this.platform.fetch(`${this.config.baseUrl}/v1/sdk/flags`, { headers: this.headers() });
+		if (!e.ok) throw Error(`Failed to fetch flags: ${e.status}`);
+		let t = await e.json();
+		this.store.init(t.flags, t.segments, t.version);
+	}
+	startDataSource() {
+		this.closed || (this.config.streaming ? this.startStreaming() : this.startPolling());
+	}
+	startStreaming() {
+		if (this.closed) return;
+		let e = this.platform.sseSupportsHeaders ? `${this.config.baseUrl}/v1/sdk/stream` : `${this.config.baseUrl}/v1/sdk/stream?authorization=${encodeURIComponent(this.config.sdkKey)}`;
+		this.eventSource = this.platform.createEventSource(e, this.headers());
+		for (let e of ["flag.created", "flag.updated"]) this.eventSource.addEventListener(e, (e) => {
+			try {
+				let t = JSON.parse(e.data);
+				t.key && this.fetchSingleFlag(t.key);
+			} catch {}
+		});
+		this.eventSource.addEventListener("flag.deleted", (e) => {
+			try {
+				let t = JSON.parse(e.data);
+				t.key && this.store.delete(t.key);
+			} catch {}
+		}), this.eventSource.addEventListener("segment.updated", () => {
+			this.fetchFlags().catch(() => {});
+		}), this.eventSource.addEventListener("open", () => {
+			this.streamRetryCount = 0;
+		}), this.eventSource.addEventListener("error", () => {
+			if (this.eventSource?.close(), this.eventSource = null, this.closed) return;
+			if (this.streamRetryCount >= this.config.maxStreamRetries) {
+				console.warn(`[featureflip] SSE connection failed after ${this.config.maxStreamRetries} retries, falling back to polling`), this.startPolling();
+				return;
+			}
+			let e = Math.min(1e3 * 2 ** this.streamRetryCount, 3e4);
+			this.streamRetryCount++, this.streamRetryTimer = setTimeout(() => {
+				this.streamRetryTimer = null, this.startStreaming();
+			}, e);
+		});
+	}
+	startPolling() {
+		this.pollTimer = setInterval(() => {
+			this.fetchFlags().catch(() => {});
+		}, this.config.pollInterval);
+	}
+	async fetchSingleFlag(e) {
+		try {
+			let t = await this.platform.fetch(`${this.config.baseUrl}/v1/sdk/flags/${encodeURIComponent(e)}`, { headers: this.headers() });
+			if (t.ok) {
+				let e = await t.json();
+				this.store.upsert(e);
+			}
+		} catch {}
+	}
+	recordEvaluation(e, t, n) {
+		let r = t.user_id == null ? void 0 : String(t.user_id);
+		this.events.enqueue({
+			type: "Evaluation",
+			flagKey: e,
+			userId: r,
+			variation: n,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
+	headers() {
+		return {
+			Authorization: this.config.sdkKey,
+			"Content-Type": "application/json",
+			...this.platform.extraHeaders
+		};
+	}
+};
+//#endregion
+export { p as t };

package/dist/node.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./client-Bf3tS17L.cjs`);let t=require(`crypto`);var n=(0,require(`module`).createRequire)({}.url);function r(){return{md5(e){return(0,t.createHash)(`md5`).update(e,`utf8`).digest()},createEventSource(e,t){let{EventSource:r}=n(`eventsource`),i=new r(e,{fetch:(e,n)=>globalThis.fetch(e,{...n,headers:{...n?.headers,...t}})});return{addEventListener:(e,t)=>{i.addEventListener(e,t)},close:()=>i.close(),get readyState(){return i.readyState}}},async fetch(e,t){return globalThis.fetch(e,t)},extraHeaders:{"User-Agent":`featureflip-js/0.1.0`},sseSupportsHeaders:!0}}exports.FeatureflipClient=e.t,exports.createNodePlatform=r;

package/dist/node.d.ts

@@ -0,0 +1,117 @@
+export declare function createNodePlatform(): Platform;
+
+export declare type EvaluationContext = Record<string, unknown>;
+
+export declare interface EvaluationDetail<T = unknown> {
+    value: T;
+    variationKey?: string;
+    reason: EvaluationReason;
+    ruleId?: string;
+}
+
+export declare type EvaluationReason = 'RuleMatch' | 'Fallthrough' | 'FlagDisabled' | 'FlagNotFound' | 'Error';
+
+declare interface EventSourceLike {
+    addEventListener(type: string, listener: (event: {
+        data: string;
+    }) => void): void;
+    close(): void;
+    readonly readyState: number;
+}
+
+export declare class FeatureflipClient {
+    private readonly config;
+    private readonly store;
+    private readonly events;
+    private readonly platform;
+    private initialized;
+    private initPromise;
+    private eventSource;
+    private pollTimer;
+    private closed;
+    private streamRetryCount;
+    private streamRetryTimer;
+    constructor(config: FeatureflipConfig, platform: Platform);
+    /** Whether the client has successfully loaded initial flag data. */
+    get isInitialized(): boolean;
+    /**
+     * Wait for the client to finish initialization.
+     * Rejects after initTimeout if initial flag fetch fails.
+     */
+    waitForInitialization(): Promise<void>;
+    /**
+     * Evaluate a boolean flag.
+     * Returns defaultValue if flag not found or evaluation fails.
+     */
+    boolVariation(key: string, context: EvaluationContext, defaultValue: boolean): boolean;
+    /**
+     * Evaluate a string flag.
+     */
+    stringVariation(key: string, context: EvaluationContext, defaultValue: string): string;
+    /**
+     * Evaluate a number flag.
+     */
+    numberVariation(key: string, context: EvaluationContext, defaultValue: number): number;
+    /**
+     * Evaluate a JSON flag.
+     */
+    jsonVariation<T>(key: string, context: EvaluationContext, defaultValue: T): T;
+    /**
+     * Evaluate a flag and return the full detail including reason.
+     */
+    variationDetail<T>(key: string, context: EvaluationContext, defaultValue: T): EvaluationDetail<T>;
+    /**
+     * Track a custom event.
+     */
+    track(eventKey: string, context: EvaluationContext, metadata?: Record<string, unknown>): void;
+    /**
+     * Send an identify event for the given context.
+     */
+    identify(context: EvaluationContext): void;
+    /**
+     * Flush any pending events immediately.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the client, flushing pending events and stopping all connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Create a test client with hardcoded flag values. No network calls.
+     */
+    static forTesting(flags: Record<string, unknown>): FeatureflipClient;
+    private evaluateFlag;
+    private initialize;
+    private fetchFlags;
+    private startDataSource;
+    private startStreaming;
+    private startPolling;
+    private fetchSingleFlag;
+    private recordEvaluation;
+    private headers;
+}
+
+export declare interface FeatureflipConfig {
+    sdkKey: string;
+    baseUrl: string;
+    streaming?: boolean;
+    pollInterval?: number;
+    flushInterval?: number;
+    flushBatchSize?: number;
+    initTimeout?: number;
+    maxStreamRetries?: number;
+}
+
+export declare type FlagType = 'Boolean' | 'String' | 'Number' | 'Json';
+
+export declare interface Platform {
+    md5(input: string): Uint8Array;
+    createEventSource(url: string, headers: Record<string, string>): EventSourceLike;
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** Extra headers the platform can inject (e.g. User-Agent on Node). */
+    readonly extraHeaders?: Record<string, string>;
+    /** Whether the platform's EventSource implementation supports custom headers. */
+    readonly sseSupportsHeaders?: boolean;
+}
+
+export { }

package/dist/node.mjs

@@ -0,0 +1,37 @@
+import { t as e } from "./client-ChXPtrh5.js";
+import { createHash as t } from "crypto";
+import { createRequire as n } from "module";
+//#region src/platform/node.ts
+var r = n(import.meta.url);
+function i() {
+	return {
+		md5(e) {
+			return t("md5").update(e, "utf8").digest();
+		},
+		createEventSource(e, t) {
+			let { EventSource: n } = r("eventsource"), i = new n(e, { fetch: (e, n) => globalThis.fetch(e, {
+				...n,
+				headers: {
+					...n?.headers,
+					...t
+				}
+			}) });
+			return {
+				addEventListener: (e, t) => {
+					i.addEventListener(e, t);
+				},
+				close: () => i.close(),
+				get readyState() {
+					return i.readyState;
+				}
+			};
+		},
+		async fetch(e, t) {
+			return globalThis.fetch(e, t);
+		},
+		extraHeaders: { "User-Agent": "featureflip-js/0.1.0" },
+		sseSupportsHeaders: !0
+	};
+}
+//#endregion
+export { e as FeatureflipClient, i as createNodePlatform };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@featureflip/js",
+  "version": "1.0.0",
+  "description": "JavaScript/TypeScript SDK for FeatureFlip",
+  "license": "Apache-2.0",
+  "homepage": "https://featureflip.io/docs",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/node.d.ts",
+      "node": {
+        "import": "./dist/node.mjs",
+        "require": "./dist/node.cjs"
+      },
+      "browser": {
+        "import": "./dist/browser.mjs",
+        "require": "./dist/browser.cjs"
+      },
+      "default": "./dist/browser.mjs"
+    }
+  },
+  "types": "./dist/node.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "eventsource": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^4.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}