@featureflip/browser 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# @featureflip/browser-sdk
+
+Framework-agnostic browser SDK for evaluating Featureflip feature flags.
+
+## Installation
+
+```bash
+npm install @featureflip/browser-sdk
+```
+
+## Quick Start
+
+```ts
+import { FeatureflipClient } from '@featureflip/browser-sdk';
+
+const client = new FeatureflipClient({
+  clientKey: 'your-client-sdk-key',
+});
+
+await client.initialize();
+
+const showBanner = client.boolVariation('show-banner', false);
+```
+
+## API Reference
+
+### Constructor
+
+```ts
+new FeatureflipClient(config: FeatureflipClientConfig)
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `clientKey` | `string` | **(required)** | Client SDK key from your project settings |
+| `baseUrl` | `string` | `https://eval.featureflip.io` | Evaluation API base URL |
+| `context` | `Record<string, unknown>` | `{}` | Initial evaluation context (user attributes) |
+| `streaming` | `boolean` | `true` | Enable SSE streaming for real-time updates |
+| `initTimeout` | `number` | `10000` | Timeout in ms for the initial evaluate request |
+
+### Methods
+
+#### `initialize(): Promise<void>`
+
+Fetches all flag values from the server. Must be called before reading variations. Opens an SSE streaming connection if `streaming` is enabled.
+
+#### `boolVariation(key: string, defaultValue: boolean): boolean`
+
+Returns a boolean flag value, or `defaultValue` if the flag is missing or not a boolean.
+
+#### `stringVariation(key: string, defaultValue: string): string`
+
+Returns a string flag value, or `defaultValue` if the flag is missing or not a string.
+
+#### `numberVariation(key: string, defaultValue: number): number`
+
+Returns a number flag value, or `defaultValue` if the flag is missing or not a number.
+
+#### `jsonVariation<T>(key: string, defaultValue: T): T`
+
+Returns a flag value cast to `T`, or `defaultValue` if the flag is missing.
+
+#### `identify(context: Record<string, unknown>): Promise<void>`
+
+Re-evaluates all flags with a new context (e.g., after login). Emits `change` events for any flags whose values changed.
+
+```ts
+await client.identify({ user_id: '123', plan: 'pro' });
+```
+
+#### `on(event: EventType, handler: EventHandler): void`
+
+Subscribe to events.
+
+- `'ready'` -- fired after `initialize()` completes
+- `'change'` -- fired when flag values change (receives a `FlagChanges` object)
+- `'error'` -- fired on streaming or network errors
+
+```ts
+client.on('change', (changes) => {
+  console.log('Flags changed:', changes);
+});
+```
+
+#### `off(event: EventType, handler: EventHandler): void`
+
+Unsubscribe from events.
+
+#### `close(): void`
+
+Closes the SSE streaming connection and cleans up resources.
+
+### Testing
+
+Use `FeatureflipClient.forTesting()` to create a client with predetermined flag values -- no network calls.
+
+```ts
+const client = FeatureflipClient.forTesting({
+  'show-banner': true,
+  'button-color': 'blue',
+});
+
+client.boolVariation('show-banner', false); // true
+client.stringVariation('button-color', 'red'); // 'blue'
+```

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=class{handlers=new Map;on(e,t){this.handlers.has(e)||this.handlers.set(e,new Set),this.handlers.get(e).add(t)}off(e,t){this.handlers.get(e)?.delete(t)}emit(e,...t){this.handlers.get(e)?.forEach(e=>{try{e(...t)}catch{}})}};async function t(e,t,n,r){let i=await fetch(`${e}/v1/client/evaluate`,{method:`POST`,headers:{"Content-Type":`application/json`,Authorization:t},body:JSON.stringify({context:n}),signal:r});if(!i.ok)throw Error(`Evaluate request failed with status ${i.status}`);return i.json()}async function n(e,t,n,r){let i={"Content-Type":`application/json`,Authorization:t};r&&(i[`X-Connection-Id`]=r);let a=await fetch(`${e}/v1/client/identify`,{method:`POST`,headers:i,body:JSON.stringify({context:n})});if(!a.ok)throw Error(`Identify request failed with status ${a.status}`);return a.json()}var r=3e4,i=1e3,a=class{eventSource=null;options;backoffMs=i;reconnectTimer=null;closed=!1;_connectionId=null;get connectionId(){return this._connectionId}constructor(e){this.options=e,this.connect()}connect(){if(this.closed)return;this._connectionId=null;let{baseUrl:e,clientKey:t,context:n}=this.options,r=new TextEncoder().encode(JSON.stringify(n)),a=``;for(let e=0;e<r.length;e++)a+=String.fromCharCode(r[e]);let o=btoa(a),s=`${e}/v1/client/stream?authorization=${encodeURIComponent(t)}&context=${encodeURIComponent(o)}`;this.eventSource=new EventSource(s),this.eventSource.addEventListener(`flags-updated`,e=>{try{let t=JSON.parse(e.data);this.backoffMs=i,this.options.onChange(t.flags??t)}catch{}}),this.eventSource.addEventListener(`connection-ready`,e=>{try{let t=JSON.parse(e.data);t.connectionId&&(this._connectionId=t.connectionId)}catch{}}),this.eventSource.onerror=()=>{this.eventSource?.close(),this.eventSource=null,this.closed||(this.options.onError?.(Error(`SSE connection error`)),this.scheduleReconnect())}}scheduleReconnect(){this.closed||this.reconnectTimer!==null||(this.reconnectTimer=setTimeout(()=>{this.reconnectTimer=null,this.connect()},this.backoffMs),this.backoffMs=Math.min(this.backoffMs*2,r))}close(){this.closed=!0,this.eventSource?.close(),this.eventSource=null,this.reconnectTimer!==null&&(clearTimeout(this.reconnectTimer),this.reconnectTimer=null)}},o=class r{config;flags=new Map;emitter=new e;stream=null;initialized=!1;initPromise=null;closed=!1;constructor(e){if(!e.clientKey)throw Error(`clientKey is required`);this.config={clientKey:e.clientKey,baseUrl:e.baseUrl??`https://eval.featureflip.io`,context:e.context??{},streaming:e.streaming??!0,initTimeout:e.initTimeout??1e4}}initialize(){return this.initialized?Promise.resolve():(this.initPromise||=this.doInitialize(),this.initPromise)}async doInitialize(){let e=new AbortController,n=setTimeout(()=>e.abort(),this.config.initTimeout),r;try{r=await t(this.config.baseUrl,this.config.clientKey,this.config.context,e.signal)}finally{clearTimeout(n)}this.closed||(this.setFlags(r.flags),this.initialized=!0,this.config.streaming&&(this.stream=this.createStream()),this.emitter.emit(`ready`))}boolVariation(e,t){let n=this.flags.get(e);return n===void 0?t:typeof n.value==`boolean`?n.value:t}stringVariation(e,t){let n=this.flags.get(e);return n===void 0?t:typeof n.value==`string`?n.value:t}numberVariation(e,t){let n=this.flags.get(e);return n===void 0?t:typeof n.value==`number`?n.value:t}jsonVariation(e,t){let n=this.flags.get(e);return n===void 0?t:n.value}async identify(e){let t=this.config.context;this.config.context=e,this.stream&&=(this.stream.close(),null);let r;try{r=await n(this.config.baseUrl,this.config.clientKey,e)}catch(e){throw this.config.context=t,this.emitter.emit(`error`,e instanceof Error?e:Error(String(e))),this.config.streaming&&(this.stream=this.createStream()),e}let i=this.computeChanges(r.flags);this.setFlags(r.flags),Object.keys(i).length>0&&this.emitter.emit(`change`,i),this.config.streaming&&(this.stream=this.createStream())}on(e,t){this.emitter.on(e,t)}off(e,t){this.emitter.off(e,t)}close(){this.closed=!0,this.stream?.close(),this.stream=null}static forTesting(t){let n=Object.create(r.prototype);n.config={clientKey:`test-key`,baseUrl:`http://localhost`,context:{},streaming:!1,initTimeout:1e4},n.flags=new Map,n.emitter=new e,n.stream=null,n.initialized=!0,n.closed=!1;for(let[e,r]of Object.entries(t))n.flags.set(e,{value:r,variation:`test`,reason:`test`});return n}createStream(){return new a({baseUrl:this.config.baseUrl,clientKey:this.config.clientKey,context:this.config.context,onChange:e=>this.handleFlagUpdate(e),onError:e=>this.emitter.emit(`error`,e)})}setFlags(e){this.flags.clear();for(let[t,n]of Object.entries(e))this.flags.set(t,n)}computeChanges(e){let t={};for(let[n,r]of Object.entries(e)){let e=this.flags.get(n)?.value;e!==r.value&&(t[n]={oldValue:e,newValue:r.value})}for(let[n]of this.flags)n in e||(t[n]={oldValue:this.flags.get(n).value,newValue:void 0});return t}handleFlagUpdate(e){let t={};for(let[n,r]of Object.entries(e))if(r.reason===`FLAG_REMOVED`&&r.value===null){let e=this.flags.get(n);e!==void 0&&(t[n]={oldValue:e.value,newValue:void 0},this.flags.delete(n))}else{let e=this.flags.get(n);(e===void 0||e.value!==r.value)&&(t[n]={oldValue:e?.value,newValue:r.value}),this.flags.set(n,r)}Object.keys(t).length>0&&this.emitter.emit(`change`,t)}};exports.FeatureflipClient=o;

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+export declare type EventHandler = (...args: unknown[]) => void;
+
+export declare type EventType = 'ready' | 'change' | 'error';
+
+export declare class FeatureflipClient {
+    private config;
+    private flags;
+    private emitter;
+    private stream;
+    private initialized;
+    private initPromise;
+    private closed;
+    constructor(config: FeatureflipClientConfig);
+    initialize(): Promise<void>;
+    private doInitialize;
+    boolVariation(key: string, defaultValue: boolean): boolean;
+    stringVariation(key: string, defaultValue: string): string;
+    numberVariation(key: string, defaultValue: number): number;
+    jsonVariation<T>(key: string, defaultValue: T): T;
+    identify(context: Record<string, unknown>): Promise<void>;
+    on(event: EventType, handler: EventHandler): void;
+    off(event: EventType, handler: EventHandler): void;
+    close(): void;
+    static forTesting(flags: Record<string, unknown>): FeatureflipClient;
+    private createStream;
+    private setFlags;
+    private computeChanges;
+    private handleFlagUpdate;
+}
+
+export declare interface FeatureflipClientConfig {
+    clientKey: string;
+    baseUrl?: string;
+    context?: Record<string, unknown>;
+    streaming?: boolean;
+    initTimeout?: number;
+}
+
+export declare interface FlagChanges {
+    [flagKey: string]: {
+        oldValue: unknown;
+        newValue: unknown;
+    };
+}
+
+export declare interface FlagValue {
+    value: unknown;
+    variation: string;
+    reason: string;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,220 @@
+//#region src/events.ts
+var e = class {
+	handlers = /* @__PURE__ */ new Map();
+	on(e, t) {
+		this.handlers.has(e) || this.handlers.set(e, /* @__PURE__ */ new Set()), this.handlers.get(e).add(t);
+	}
+	off(e, t) {
+		this.handlers.get(e)?.delete(t);
+	}
+	emit(e, ...t) {
+		this.handlers.get(e)?.forEach((e) => {
+			try {
+				e(...t);
+			} catch {}
+		});
+	}
+};
+//#endregion
+//#region src/http.ts
+async function t(e, t, n, r) {
+	let i = await fetch(`${e}/v1/client/evaluate`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: t
+		},
+		body: JSON.stringify({ context: n }),
+		signal: r
+	});
+	if (!i.ok) throw Error(`Evaluate request failed with status ${i.status}`);
+	return i.json();
+}
+async function n(e, t, n, r) {
+	let i = {
+		"Content-Type": "application/json",
+		Authorization: t
+	};
+	r && (i["X-Connection-Id"] = r);
+	let a = await fetch(`${e}/v1/client/identify`, {
+		method: "POST",
+		headers: i,
+		body: JSON.stringify({ context: n })
+	});
+	if (!a.ok) throw Error(`Identify request failed with status ${a.status}`);
+	return a.json();
+}
+//#endregion
+//#region src/streaming.ts
+var r = 3e4, i = 1e3, a = class {
+	eventSource = null;
+	options;
+	backoffMs = i;
+	reconnectTimer = null;
+	closed = !1;
+	_connectionId = null;
+	get connectionId() {
+		return this._connectionId;
+	}
+	constructor(e) {
+		this.options = e, this.connect();
+	}
+	connect() {
+		if (this.closed) return;
+		this._connectionId = null;
+		let { baseUrl: e, clientKey: t, context: n } = this.options, r = new TextEncoder().encode(JSON.stringify(n)), a = "";
+		for (let e = 0; e < r.length; e++) a += String.fromCharCode(r[e]);
+		let o = btoa(a), s = `${e}/v1/client/stream?authorization=${encodeURIComponent(t)}&context=${encodeURIComponent(o)}`;
+		this.eventSource = new EventSource(s), this.eventSource.addEventListener("flags-updated", (e) => {
+			try {
+				let t = JSON.parse(e.data);
+				this.backoffMs = i, this.options.onChange(t.flags ?? t);
+			} catch {}
+		}), this.eventSource.addEventListener("connection-ready", (e) => {
+			try {
+				let t = JSON.parse(e.data);
+				t.connectionId && (this._connectionId = t.connectionId);
+			} catch {}
+		}), this.eventSource.onerror = () => {
+			this.eventSource?.close(), this.eventSource = null, this.closed || (this.options.onError?.(/* @__PURE__ */ Error("SSE connection error")), this.scheduleReconnect());
+		};
+	}
+	scheduleReconnect() {
+		this.closed || this.reconnectTimer !== null || (this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = null, this.connect();
+		}, this.backoffMs), this.backoffMs = Math.min(this.backoffMs * 2, r));
+	}
+	close() {
+		this.closed = !0, this.eventSource?.close(), this.eventSource = null, this.reconnectTimer !== null && (clearTimeout(this.reconnectTimer), this.reconnectTimer = null);
+	}
+}, o = class r {
+	config;
+	flags = /* @__PURE__ */ new Map();
+	emitter = new e();
+	stream = null;
+	initialized = !1;
+	initPromise = null;
+	closed = !1;
+	constructor(e) {
+		if (!e.clientKey) throw Error("clientKey is required");
+		this.config = {
+			clientKey: e.clientKey,
+			baseUrl: e.baseUrl ?? "https://eval.featureflip.io",
+			context: e.context ?? {},
+			streaming: e.streaming ?? !0,
+			initTimeout: e.initTimeout ?? 1e4
+		};
+	}
+	initialize() {
+		return this.initialized ? Promise.resolve() : (this.initPromise ||= this.doInitialize(), this.initPromise);
+	}
+	async doInitialize() {
+		let e = new AbortController(), n = setTimeout(() => e.abort(), this.config.initTimeout), r;
+		try {
+			r = await t(this.config.baseUrl, this.config.clientKey, this.config.context, e.signal);
+		} finally {
+			clearTimeout(n);
+		}
+		this.closed || (this.setFlags(r.flags), this.initialized = !0, this.config.streaming && (this.stream = this.createStream()), this.emitter.emit("ready"));
+	}
+	boolVariation(e, t) {
+		let n = this.flags.get(e);
+		return n === void 0 ? t : typeof n.value == "boolean" ? n.value : t;
+	}
+	stringVariation(e, t) {
+		let n = this.flags.get(e);
+		return n === void 0 ? t : typeof n.value == "string" ? n.value : t;
+	}
+	numberVariation(e, t) {
+		let n = this.flags.get(e);
+		return n === void 0 ? t : typeof n.value == "number" ? n.value : t;
+	}
+	jsonVariation(e, t) {
+		let n = this.flags.get(e);
+		return n === void 0 ? t : n.value;
+	}
+	async identify(e) {
+		let t = this.config.context;
+		this.config.context = e, this.stream &&= (this.stream.close(), null);
+		let r;
+		try {
+			r = await n(this.config.baseUrl, this.config.clientKey, e);
+		} catch (e) {
+			throw this.config.context = t, this.emitter.emit("error", e instanceof Error ? e : Error(String(e))), this.config.streaming && (this.stream = this.createStream()), e;
+		}
+		let i = this.computeChanges(r.flags);
+		this.setFlags(r.flags), Object.keys(i).length > 0 && this.emitter.emit("change", i), this.config.streaming && (this.stream = this.createStream());
+	}
+	on(e, t) {
+		this.emitter.on(e, t);
+	}
+	off(e, t) {
+		this.emitter.off(e, t);
+	}
+	close() {
+		this.closed = !0, this.stream?.close(), this.stream = null;
+	}
+	static forTesting(t) {
+		let n = Object.create(r.prototype);
+		n.config = {
+			clientKey: "test-key",
+			baseUrl: "http://localhost",
+			context: {},
+			streaming: !1,
+			initTimeout: 1e4
+		}, n.flags = /* @__PURE__ */ new Map(), n.emitter = new e(), n.stream = null, n.initialized = !0, n.closed = !1;
+		for (let [e, r] of Object.entries(t)) n.flags.set(e, {
+			value: r,
+			variation: "test",
+			reason: "test"
+		});
+		return n;
+	}
+	createStream() {
+		return new a({
+			baseUrl: this.config.baseUrl,
+			clientKey: this.config.clientKey,
+			context: this.config.context,
+			onChange: (e) => this.handleFlagUpdate(e),
+			onError: (e) => this.emitter.emit("error", e)
+		});
+	}
+	setFlags(e) {
+		this.flags.clear();
+		for (let [t, n] of Object.entries(e)) this.flags.set(t, n);
+	}
+	computeChanges(e) {
+		let t = {};
+		for (let [n, r] of Object.entries(e)) {
+			let e = this.flags.get(n)?.value;
+			e !== r.value && (t[n] = {
+				oldValue: e,
+				newValue: r.value
+			});
+		}
+		for (let [n] of this.flags) n in e || (t[n] = {
+			oldValue: this.flags.get(n).value,
+			newValue: void 0
+		});
+		return t;
+	}
+	handleFlagUpdate(e) {
+		let t = {};
+		for (let [n, r] of Object.entries(e)) if (r.reason === "FLAG_REMOVED" && r.value === null) {
+			let e = this.flags.get(n);
+			e !== void 0 && (t[n] = {
+				oldValue: e.value,
+				newValue: void 0
+			}, this.flags.delete(n));
+		} else {
+			let e = this.flags.get(n);
+			(e === void 0 || e.value !== r.value) && (t[n] = {
+				oldValue: e?.value,
+				newValue: r.value
+			}), this.flags.set(n, r);
+		}
+		Object.keys(t).length > 0 && this.emitter.emit("change", t);
+	}
+};
+//#endregion
+export { o as FeatureflipClient };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@featureflip/browser",
+  "version": "1.0.0",
+  "description": "Browser SDK for Featureflip - framework-agnostic feature flag client",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://featureflip.io/docs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "jsdom": "^29.0.1",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^4.1.2"
+  }
+}