@spotify-confidence/openfeature-server-provider-local 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.8.0](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.7.0...openfeature-provider-js-v0.8.0) (2026-01-27)
+
+
+### Features
+
+* **js:** add React support with useFlag and useFlagDetails hooks ([#246](https://github.com/spotify/confidence-resolver/issues/246)) ([d579a4c](https://github.com/spotify/confidence-resolver/commit/d579a4c8fe493ee3a92539203f21d1c03758c58e))
+* **wasm:** add wasm API to apply previously resolved flags ([#235](https://github.com/spotify/confidence-resolver/issues/235)) ([79048f6](https://github.com/spotify/confidence-resolver/commit/79048f63a8c771eb98ecf478cab0b654aa745374))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * rust-guest bumped from 0.1.13 to 0.1.14
+
+## [0.7.0](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.6.0...openfeature-provider-js-v0.7.0) (2026-01-22)
+
+
+### Features
+
+* inlined WASM for improved portability ([#243](https://github.com/spotify/confidence-resolver/issues/243)) ([8d86283](https://github.com/spotify/confidence-resolver/commit/8d862837244ffd9099bfeb56b42e203212e73a96))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * rust-guest bumped from 0.1.12 to 0.1.13
+
 ## [0.6.0](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.5.1...openfeature-provider-js-v0.6.0) (2026-01-15)
 
 

package/README.md

@@ -3,12 +3,15 @@
 OpenFeature provider for the Spotify Confidence resolver (local mode, powered by WebAssembly). It periodically fetches resolver state, evaluates flags locally, and flushes evaluation logs to the Confidence backend.
 
 ## Features
+
 - Local flag evaluation via WASM (no per-eval network calls)
 - Automatic state refresh and batched flag log flushing
 - Pluggable `fetch` with retries, timeouts and routing
 - Optional logging using `debug`
+- **[React integration](./README-REACT.md)** for Next.js with Server Components
 
 ## Requirements
+
 - Node.js 18+ (built-in `fetch`) or provide a compatible `fetch`
 - WebAssembly support (Node 18+/modern browsers)
 
@@ -24,6 +27,7 @@ yarn add debug
 ```
 
 Notes:
+
 - `debug` is an optional peer. Install it if you want logs. Without it, logging is a no-op.
 - Types and bundling are ESM-first; Node is supported, and a browser build is provided for modern bundlers.
 
@@ -34,6 +38,7 @@ Notes:
 You'll need a **client secret** from Confidence to use this provider.
 
 **📖 See the [Integration Guide: Getting Your Credentials](../INTEGRATION_GUIDE.md#getting-your-credentials)** for step-by-step instructions on:
+
 - How to navigate the Confidence dashboard
 - Creating a Backend integration
 - Creating a test flag for verification
@@ -104,6 +109,7 @@ const context = {
 The provider uses a **default value fallback** pattern - when evaluation fails, it returns your specified default value instead of throwing an error.
 
 **📖 See the [Integration Guide: Error Handling](../INTEGRATION_GUIDE.md#error-handling)** for:
+
 - Common failure scenarios
 - Error codes and meanings
 - Production best practices
@@ -119,8 +125,8 @@ const enabled = await client.getBooleanValue('my-flag.enabled', false, context);
 // For detailed error information, use getBooleanDetails()
 const details = await client.getBooleanDetails('my-flag.enabled', false, context);
 if (details.errorCode) {
-    console.error('Flag evaluation error:', details.errorMessage);
-    console.log('Reason:', details.reason);
+  console.error('Flag evaluation error:', details.errorMessage);
+  console.log('Reason:', details.reason);
 }
 ```
 
@@ -135,11 +141,85 @@ if (details.errorCode) {
 - `fetch` (optional): Custom `fetch` implementation. Required for Node < 18; for Node 18+ you can omit.
 
 The provider periodically:
+
 - Refreshes resolver state (configurable via `stateUpdateInterval`, default every 30s)
 - Flushes flag evaluation logs to the backend (configurable via `flushInterval`, default every 10s)
 
 ---
 
+## Exports and WASM Loading
+
+The package provides multiple exports for different environments:
+
+### Default export (recommended)
+
+```ts
+import { createConfidenceServerProvider } from '@spotify-confidence/openfeature-server-provider-local';
+```
+
+The WASM is **inlined as a data URL** — this is the most portable option and should work across virtually all environments. The tradeoff is a larger bundle (~700kB), but this isn't a problem for the intended server-side usage.
+
+No configuration needed.
+
+### `./node` — Traditional Node.js
+
+```ts
+import { createConfidenceServerProvider } from '@spotify-confidence/openfeature-server-provider-local/node';
+```
+
+Uses `fs.readFile()` to load WASM from the installed package. Works well in a regular Node.js environment with node_modules.
+
+You can customize the WASM path if needed:
+
+```ts
+const provider = createConfidenceServerProvider({
+  flagClientSecret: '...',
+  wasmPath: '/custom/path/to/confidence_resolver.wasm',
+});
+```
+
+### `./fetch` — Modern and standards compliant environments
+
+```ts
+import { createConfidenceServerProvider } from '@spotify-confidence/openfeature-server-provider-local/fetch';
+```
+
+Uses `fetch()` with `import.meta.url` to load WASM. Works in Deno, Bun, and browsers with bundlers that properly handle asset URLs (Vite, Rollup, etc.).
+
+You can customize the WASM URL if needed:
+
+```ts
+const provider = createConfidenceServerProvider({
+  flagClientSecret: '...',
+  wasmUrl: '/assets/confidence_resolver.wasm',
+});
+```
+
+### `./react-server` and `./react-client` — React/Next.js Integration
+
+```ts
+// Server Component
+import { ConfidenceProvider, getFlag, getFlagDetails } from '@spotify-confidence/openfeature-server-provider-local/react-server';
+
+// Client Component
+import { useFlag, useFlagDetails } from '@spotify-confidence/openfeature-server-provider-local/react-client';
+```
+
+React hooks and components for Next.js App Router with Server Components. Flags are resolved on the server and provided to client components via React Context.
+
+**See [README-REACT.md](./README-REACT.md) for full documentation.**
+
+### A note on browser usage
+
+While browsers are mentioned in this doc, this package is intended for server-side use only. Two concerns for browser usage:
+
+- Size: The WASM+JS is currently ~270kb gzipped, too large for typical client bundles.
+- Security: In a browser, all flag rules and variants are exposed to users.
+
+That said, the package does work in browsers, and there may be specialized use cases where these tradeoffs are acceptable.
+
+---
+
 ## Materialization Stores
 
 Materialization stores provide persistent storage for sticky variant assignments and custom targeting segments. This enables two key use cases:
@@ -164,11 +244,13 @@ const provider = createConfidenceServerProvider({
 ```
 
 **When to use**:
+
 - You need sticky assignments or materialized segments but don't want to manage storage infrastructure
 - Quick prototyping or getting started
 - Lower-volume applications where network latency is acceptable
 
 **Trade-offs**:
+
 - Additional network calls during flag resolution (adds latency)
 - Lower performance compared to local storage implementations (Redis, DynamoDB, etc.)
 
@@ -200,6 +282,7 @@ For read-only stores (e.g., pre-populated materialized segments without sticky a
 ### When to Use Materialization Stores
 
 Consider implementing a materialization store if:
+
 - You need to support sticky variant assignments for experiments
 - You use materialized segments for custom targeting
 - You want to minimize network latency during flag resolution
@@ -214,10 +297,12 @@ If you don't use sticky assignments or materialized segments, the default behavi
 Logging uses the `debug` library if present; otherwise, all log calls are no-ops.
 
 Namespaces:
+
 - Core: `cnfd:*`
 - Fetch/middleware: `cnfd:fetch:*` (e.g. retries, auth renewals, request summaries)
 
 Log levels are hierarchical:
+
 - `cnfd:debug` enables debug, info, warn, and error
 - `cnfd:info` enables info, warn, and error
 - `cnfd:warn` enables warn and error
@@ -226,6 +311,7 @@ Log levels are hierarchical:
 Enable logs:
 
 - Node:
+
 ```bash
 DEBUG=cnfd:* node app.js
 # or narrower
@@ -233,6 +319,7 @@ DEBUG=cnfd:info,cnfd:fetch:* node app.js
 ```
 
 - Browser (in DevTools console):
+
 ```js
 localStorage.debug = 'cnfd:*';
 ```
@@ -245,19 +332,6 @@ yarn add debug
 
 ---
 
-## WebAssembly asset notes
-
-- Node: the WASM (`confidence_resolver.wasm`) is resolved from the installed package automatically; no extra config needed.
-- Browser: the ESM build resolves the WASM via `new URL('confidence_resolver.wasm', import.meta.url)` so modern bundlers (Vite/Rollup/Webpack 5 asset modules) will include it. If your bundler does not, configure it to treat the `.wasm` file as a static asset.
-
----
-
-## Using in browsers
-
-The package exports a browser ESM build that compiles the WASM via streaming and uses the global `fetch`. Integrate it with your OpenFeature SDK variant for the web similarly to Node, then register the provider before evaluation. Credentials must be available to the runtime (e.g. through your app’s configuration layer).
-
----
-
 ## Testing
 
 - You can inject a custom `fetch` via the `fetch` option to stub network behavior in tests.

package/dist/client.d.ts

@@ -0,0 +1,129 @@
+import { EvaluationDetails, FlagValue } from "@openfeature/core";
+
+//#region src/types.d.ts
+type ResolutionReason = "ERROR" | "FLAG_ARCHIVED" | "MATCH" | "NO_SEGMENT_MATCH" | "TARGETING_KEY_ERROR" | "NO_TREATMENT_MATCH" | "UNSPECIFIED";
+declare enum ErrorCode {
+  PROVIDER_NOT_READY = "PROVIDER_NOT_READY",
+  PROVIDER_FATAL = "PROVIDER_FATAL",
+  FLAG_NOT_FOUND = "FLAG_NOT_FOUND",
+  TYPE_MISMATCH = "TYPE_MISMATCH",
+  GENERAL = "GENERAL",
+}
+interface ResolutionDetails<T> {
+  reason: ResolutionReason;
+  value: T;
+  variant?: string;
+  errorCode?: ErrorCode;
+  errorMessage?: string;
+  shouldApply: boolean;
+}
+type FlagPrimitive = null | boolean | string | number;
+type FlagObject = {
+  [key: string]: FlagValue$1;
+};
+type FlagValue$1 = FlagPrimitive | FlagObject;
+//#endregion
+//#region src/flag-bundle.d.ts
+interface FlagBundle {
+  flags: Record<string, ResolutionDetails<FlagObject | null> | undefined>;
+  resolveId: string;
+  resolveToken: string;
+  errorCode?: ErrorCode;
+  errorMessage?: string;
+}
+//#endregion
+//#region src/react/client.d.ts
+type FlagBundle$1 = FlagBundle;
+type ApplyFn = (flagName: string) => Promise<void>;
+/** @internal */
+interface ConfidenceClientProviderProps {
+  bundle: FlagBundle$1;
+  apply: ApplyFn;
+  children: React.ReactNode;
+}
+/** @internal */
+declare function ConfidenceClientProvider({
+  bundle,
+  apply,
+  children
+}: ConfidenceClientProviderProps): React.ReactElement;
+interface UseFlagOptions {
+  /** Set to false for manual exposure control. Default is true (auto-expose on mount). */
+  expose?: boolean;
+}
+/**
+* Details returned by useFlagDetails hook.
+* Always includes an expose function for manual exposure logging.
+*/
+interface ClientEvaluationDetails<T extends FlagValue> extends EvaluationDetails<T> {
+  /** Function to manually log exposure. No-op if already auto-exposed or if called multiple times. */
+  expose: () => void;
+}
+/**
+* React hook for accessing Confidence feature flag values.
+*
+* Automatically logs exposure when the component mounts.
+* Supports dot notation to access nested properties within a flag value.
+*
+* @param flagKey - The flag key, optionally with dot notation for nested access (e.g., 'my-flag.config.enabled')
+* @param defaultValue - Default value if flag or nested property is not found
+* @returns The flag value (or nested property value)
+*
+* @example Basic usage
+* ```tsx
+* const enabled = useFlag('my-feature', false);
+* ```
+*
+* @example Dot notation for nested properties
+* ```tsx
+* // Flag value: { config: { maxItems: 10, enabled: true } }
+* const maxItems = useFlag('my-feature.config.maxItems', 5);
+* const enabled = useFlag('my-feature.config.enabled', false);
+* ```
+*
+* @see useFlagDetails for manual exposure control
+*/
+declare function useFlag<T extends FlagValue>(flagKey: string, defaultValue: T): T;
+/**
+* React hook for accessing Confidence feature flag values with full details.
+*
+* Returns the flag value along with variant, reason, and error information.
+* By default, automatically logs exposure when the component mounts.
+* Use `{ expose: false }` for manual exposure control.
+*
+* Supports dot notation to access nested properties within a flag value.
+*
+* @param flagKey - The flag key, optionally with dot notation for nested access (e.g., 'my-flag.config.enabled')
+* @param defaultValue - Default value if flag or nested property is not found
+* @param options - Use `{ expose: false }` for manual exposure control
+* @returns EvaluationDetails with value, flagKey, flagMetadata, variant, reason, errorCode, errorMessage, and expose function.
+*
+* @example Auto exposure with full details
+* ```tsx
+* const { value, variant, reason } = useFlagDetails('my-feature', false);
+* console.log(`Got ${value} from variant ${variant}, reason: ${reason}`);
+* ```
+*
+* @example Manual exposure
+* ```tsx
+* const { value: enabled, expose } = useFlagDetails('my-feature', false, { expose: false });
+*
+* const handleClick = () => {
+*   if (enabled) {
+*     expose(); // Log exposure only when user interacts
+*     doSomething();
+*   }
+* };
+* ```
+*
+* @example Error handling
+* ```tsx
+* const { value, errorCode } = useFlagDetails('my-feature', false);
+* if (errorCode === 'FLAG_NOT_FOUND') {
+*   console.warn('Flag not configured');
+* }
+* ```
+*/
+declare function useFlagDetails<T extends FlagValue>(flagKey: string, defaultValue: T, options?: UseFlagOptions): ClientEvaluationDetails<T>;
+//#endregion
+export { ClientEvaluationDetails, ConfidenceClientProvider, ConfidenceClientProviderProps, useFlag, useFlagDetails };

package/dist/client.js

@@ -0,0 +1,193 @@
+"use client";
+import { createContext, useCallback, useContext, useEffect, useRef } from "react";
+import "@bufbuild/protobuf/wire";
+import { jsx } from "react/jsx-runtime";
+const NOOP_LOG_FN = Object.assign(() => {}, { enabled: false });
+const debugBackend = loadDebug();
+const logger = new class LoggerImpl {
+	childLoggers = /* @__PURE__ */ new Map();
+	debug = NOOP_LOG_FN;
+	info = NOOP_LOG_FN;
+	warn = NOOP_LOG_FN;
+	error = NOOP_LOG_FN;
+	constructor(name) {
+		this.name = name;
+		this.configure();
+	}
+	async configure(backend = debugBackend) {
+		const debug = await backend;
+		if (!debug) return;
+		const debugFn = this.debug = (debug(this.name + ":debug"));
+		const infoFn = this.info = (debug(this.name + ":info"));
+		const warnFn = this.warn = (debug(this.name + ":warn"));
+		const errorFn = this.error = (debug(this.name + ":error"));
+		switch (true) {
+			case debugFn.enabled: infoFn.enabled = true;
+			case infoFn.enabled: warnFn.enabled = true;
+			case warnFn.enabled: errorFn.enabled = true;
+		}
+	}
+	getLogger(name) {
+		let child = (this.childLoggers.get(name));
+		if (!child) {
+			child = new LoggerImpl(this.name + ":" + name);
+			this.childLoggers.set(name, child);
+		}
+		return child;
+	}
+}("cnfd");
+logger.getLogger.bind(logger);
+async function loadDebug() {
+	try {
+		const { default: debug } = await import("debug");
+		if (typeof debug !== "function") return null;
+		return debug;
+	} catch (e) {
+		return null;
+	}
+}
+function devWarn(message) {
+	if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") console.warn(message);
+}
+function hasKey(obj, key) {
+	return key in obj;
+}
+let ErrorCode = /* @__PURE__ */ function(ErrorCode$1) {
+	ErrorCode$1["PROVIDER_NOT_READY"] = "PROVIDER_NOT_READY";
+	ErrorCode$1["PROVIDER_FATAL"] = "PROVIDER_FATAL";
+	ErrorCode$1["FLAG_NOT_FOUND"] = "FLAG_NOT_FOUND";
+	ErrorCode$1["TYPE_MISMATCH"] = "TYPE_MISMATCH";
+	ErrorCode$1["GENERAL"] = "GENERAL";
+	return ErrorCode$1;
+}({});
+function error(errorCode, errorMessage) {
+	return {
+		flags: {},
+		resolveId: "",
+		resolveToken: "",
+		errorCode,
+		errorMessage
+	};
+}
+function resolve(bundle, flagKey, defaultValue, logger$1) {
+	const [flagName, ...path] = flagKey.split(".");
+	const flag = bundle?.flags[flagName];
+	if (bundle?.errorCode) {
+		logger$1?.warn(`Flag evaluation for "%s" failed. %s %s`, flagKey, bundle.errorCode, bundle?.errorMessage);
+		return {
+			reason: "ERROR",
+			errorCode: bundle.errorCode,
+			errorMessage: bundle.errorMessage,
+			value: defaultValue,
+			shouldApply: false
+		};
+	}
+	if (!flag) {
+		logger$1?.warn(`Flag evaluation for '${flagKey}' failed: flag not found`);
+		return {
+			reason: "ERROR",
+			errorCode: ErrorCode.FLAG_NOT_FOUND,
+			value: defaultValue,
+			shouldApply: false
+		};
+	}
+	let value = flag.value;
+	for (let i = 0; i < path.length; i++) {
+		if (value === null || typeof value !== "object" || Array.isArray(value)) return {
+			reason: "ERROR",
+			value: defaultValue,
+			errorCode: ErrorCode.TYPE_MISMATCH,
+			errorMessage: `resolved value is not an object at ${[flagName, ...path.slice(0, i)].join(".")}`,
+			shouldApply: false
+		};
+		value = value[path[i]];
+	}
+	try {
+		const validated = evaluateAssignment(value, defaultValue, [flagName, ...path]);
+		return {
+			...flag,
+			value: validated
+		};
+	} catch (e) {
+		return {
+			reason: "ERROR",
+			value: defaultValue,
+			errorCode: ErrorCode.TYPE_MISMATCH,
+			errorMessage: String(e),
+			shouldApply: false
+		};
+	}
+}
+function evaluateAssignment(resolvedValue, defaultValue, path) {
+	const resolvedType = typeof resolvedValue;
+	const defaultType = typeof defaultValue;
+	if (Array.isArray(defaultValue)) throw `arrays are not supported as flag values at ${path.join(".")}`;
+	if (defaultValue === null) return resolvedValue;
+	if (resolvedValue === null) return defaultValue;
+	if (resolvedType !== defaultType) throw `resolved value (${resolvedType}) isn't assignable to default type (${defaultType}) at ${path.join(".")}`;
+	if (typeof resolvedValue === "object") {
+		const result = { ...resolvedValue };
+		for (const [key, value] of Object.entries(defaultValue)) {
+			if (!hasKey(resolvedValue, key)) throw `resolved value is missing field "${key}" at ${path.join(".")}`;
+			result[key] = evaluateAssignment(resolvedValue[key], value, [...path, key]);
+		}
+		return result;
+	}
+	return resolvedValue;
+}
+const ConfidenceContext = createContext(null);
+const warnedFlags = /* @__PURE__ */ new Set();
+function ConfidenceClientProvider({ bundle, apply, children }) {
+	const appliedFlags = useRef(/* @__PURE__ */ new Set());
+	const filteredApply = useCallback((flagName) => {
+		if (appliedFlags.current.has(flagName)) return Promise.resolve();
+		appliedFlags.current.add(flagName);
+		return apply(flagName);
+	}, [apply]);
+	return /* @__PURE__ */ jsx(ConfidenceContext.Provider, {
+		value: {
+			bundle,
+			apply: filteredApply
+		},
+		children
+	});
+}
+function useFlag(flagKey, defaultValue) {
+	return useFlagDetails(flagKey, defaultValue).value;
+}
+function useFlagDetails(flagKey, defaultValue, options) {
+	const ctx = useContext(ConfidenceContext);
+	if (!ctx && !warnedFlags.has(flagKey)) {
+		warnedFlags.add(flagKey);
+		devWarn(`[Confidence] useFlagDetails("${flagKey}") called without a parent ConfidenceProvider. Returning default value.`);
+	}
+	const bundle = ctx?.bundle ?? error(ErrorCode.GENERAL, "useFlagDetails called without a parent ConfidenceProvider");
+	const [baseFlagName] = flagKey.split(".", 1);
+	const resolution = resolve(bundle, flagKey, defaultValue);
+	const autoExpose = options?.expose !== false;
+	const doExpose = useCallback(() => {
+		if (resolution.shouldApply) ctx?.apply(baseFlagName);
+	}, [
+		ctx,
+		baseFlagName,
+		resolution.shouldApply
+	]);
+	useEffect(() => {
+		if (autoExpose) doExpose();
+	}, [autoExpose, doExpose]);
+	const expose = useCallback(() => {
+		if (autoExpose) devWarn(`[Confidence] expose() called on "${flagKey}" but auto-exposure is enabled. Call is ignored.`);
+		else doExpose();
+	}, [
+		autoExpose,
+		doExpose,
+		flagKey
+	]);
+	return {
+		flagKey,
+		flagMetadata: {},
+		...resolution,
+		expose
+	};
+}
+export { ConfidenceClientProvider, useFlag, useFlagDetails };