@spotify-confidence/openfeature-server-provider-local 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.8.1](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.8.0...openfeature-provider-js-v0.8.1) (2026-02-10)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * rust-guest bumped from 0.1.14 to 0.1.15
+
+## [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)
 
 

package/README.md

@@ -8,6 +8,7 @@ OpenFeature provider for the Spotify Confidence resolver (local mode, powered by
 - 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
 
@@ -194,6 +195,20 @@ const provider = createConfidenceServerProvider({
 });
 ```
 
+### `./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:

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,194 @@
+"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;
+		}
+		for (const child of this.childLoggers.values()) child.configure(debug);
+	}
+	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 };

package/dist/index.fetch.d.ts

@@ -1,5 +1,5 @@
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
-import { EvaluationContext, JsonValue, Provider, ProviderMetadata, ProviderStatus, ResolutionDetails } from "@openfeature/server-sdk";
+import { EvaluationContext, JsonValue, Provider, ProviderMetadata, ProviderStatus } from "@openfeature/server-sdk";
 
 //#region src/proto/confidence/flags/types/v1/types.d.ts
 /** Schema for the value of a flag. */
@@ -173,6 +173,27 @@ interface ResolveFlagsResponse {
   /** Unique identifier for this particular resolve request. */
   resolveId: string;
 }
+interface ApplyFlagsRequest {
+  /** The flags to apply and information about when they were applied. */
+  flags: AppliedFlag[];
+  /** Credentials for the client. */
+  clientSecret: string;
+  /** An opaque token that was returned from `ResolveFlags`; it must be set. */
+  resolveToken: Uint8Array;
+  /**
+  * The client time when the this request was sent, used for correcting
+  * clock skew from the client.
+  */
+  sendTime?: Date | undefined;
+  /** Information about the SDK used to initiate the request. */
+  sdk?: Sdk | undefined;
+}
+interface AppliedFlag {
+  /** The id of the flag that should be applied, has the format `flags/*`. */
+  flag: string;
+  /** The client time when the flag was applied. */
+  applyTime?: Date | undefined;
+}
 interface ResolvedFlag {
   /** The id of the flag that as resolved. */
   flag: string;
@@ -189,9 +210,13 @@ interface ResolvedFlag {
   flagSchema?: FlagSchema_StructFlagSchema | undefined;
   /** The reason to why the flag could be resolved or not. */
   reason: ResolveReason;
+  /** Determines whether the flag should be applied in the clients */
+  shouldApply: boolean;
 }
 declare const ResolveFlagsRequest: MessageFns$3<ResolveFlagsRequest>;
 declare const ResolveFlagsResponse: MessageFns$3<ResolveFlagsResponse>;
+declare const ApplyFlagsRequest: MessageFns$3<ApplyFlagsRequest>;
+declare const AppliedFlag: MessageFns$3<AppliedFlag>;
 declare const ResolvedFlag: MessageFns$3<ResolvedFlag>;
 type Builtin$3 = Date | Function | Uint8Array | string | number | boolean | undefined;
 type DeepPartial$3<T> = T extends Builtin$3 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$3<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$3<U>> : T extends {} ? { [K in keyof T]?: DeepPartial$3<T[K]> } : Partial<T>;
@@ -322,6 +347,7 @@ interface LocalResolver {
   setResolverState(request: SetResolverStateRequest): void;
   flushLogs(): Uint8Array;
   flushAssigned(): Uint8Array;
+  applyFlags(request: ApplyFlagsRequest): void;
 }
 //#endregion
 //#region src/materialization.d.ts
@@ -398,7 +424,40 @@ interface MaterializationStore {
   writeMaterializations?(writeOps: MaterializationStore.WriteOp[]): Promise<void>;
 }
 //#endregion
+//#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;
+};
+type FlagValue = 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/ConfidenceServerProviderLocal.d.ts
+type FlagBundle$1 = FlagBundle;
 interface ProviderOptions {
   flagClientSecret: string;
   initializeTimeout?: number;
@@ -430,19 +489,15 @@ declare class ConfidenceServerProviderLocal implements Provider {
   constructor(resolverOrPromise: LocalResolver | Promise<LocalResolver>, options: ProviderOptions);
   initialize(context?: EvaluationContext): Promise<void>;
   onClose(): Promise<void>;
-  evaluate<T>(flagKey: string, defaultValue: T, context: EvaluationContext): Promise<ResolutionDetails<T>>;
+  resolve(context: EvaluationContext, flagNames: string[], apply?: boolean): Promise<FlagBundle$1>;
+  evaluate<T extends JsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext): Promise<ResolutionDetails<T>>;
   private resolveWithSticky;
-  /**
-  * Extract and validate the value from a resolved flag.
-  */
-  private extractValue;
   updateState(signal?: AbortSignal): Promise<void>;
   flush(signal?: AbortSignal): Promise<void>;
   private flushAssigned;
   private sendFlagLogs;
   private readMaterializations;
   private writeMaterializations;
-  private static convertReason;
   private static convertEvaluationContext;
   /** Resolves with an evaluation of a Boolean flag */
   resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: EvaluationContext): Promise<ResolutionDetails<boolean>>;
@@ -452,6 +507,13 @@ declare class ConfidenceServerProviderLocal implements Provider {
   resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext): Promise<ResolutionDetails<T>>;
   /** Resolves with an evaluation of a String flag */
   resolveStringEvaluation(flagKey: string, defaultValue: string, context: EvaluationContext): Promise<ResolutionDetails<string>>;
+  /**
+  * Applies a previously resolved flag, logging that it was used/exposed.
+  * Call this when a flag value is actually rendered or used in the client.
+  * @param resolveToken - Base64-encoded resolve token from the flag bundle
+  * @param flagName - Name of the flag to apply
+  */
+  applyFlag(resolveToken: string, flagName: string): void;
 }
 //#endregion
 //#region src/index.fetch.d.ts