@spotify-confidence/openfeature-server-provider-local 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.13.0](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.12.1...openfeature-provider-js-v0.13.0) (2026-05-05)
+
+
+### Features
+
+* **js:** Next.js Pages Router support ([#393](https://github.com/spotify/confidence-resolver/issues/393)) ([8efd0ae](https://github.com/spotify/confidence-resolver/commit/8efd0aee9581edaddd531bc15ba63e741e598eff))
+
 ## [0.12.1](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.12.0...openfeature-provider-js-v0.12.1) (2026-04-28)
 
 

package/dist/index.fetch.js

@@ -1418,7 +1418,7 @@ function isObject(value) {
 function isSet$3(value) {
 	return value !== null && value !== void 0;
 }
-const VERSION = "0.12.1";
+const VERSION = "0.13.0";
 const NOOP_LOG_FN = Object.assign(() => {}, { enabled: false });
 const debugBackend = loadDebug();
 const logger$2 = new class LoggerImpl {

package/dist/index.inlined.js

@@ -1418,7 +1418,7 @@ function isObject(value) {
 function isSet$3(value) {
 	return value !== null && value !== void 0;
 }
-const VERSION = "0.12.1";
+const VERSION = "0.13.0";
 const NOOP_LOG_FN = Object.assign(() => {}, { enabled: false });
 const debugBackend = loadDebug();
 const logger$2 = new class LoggerImpl {

package/dist/index.node.js

@@ -1421,7 +1421,7 @@ function isObject(value) {
 function isSet$3(value) {
 	return value !== null && value !== void 0;
 }
-const VERSION = "0.12.1";
+const VERSION = "0.13.0";
 const NOOP_LOG_FN = Object.assign(() => {}, { enabled: false });
 const debugBackend = loadDebug();
 const logger$2 = new class LoggerImpl {

package/dist/pages-router/api.d.ts

@@ -0,0 +1,20 @@
+import { NextApiHandler } from "next";
+
+//#region src/pages-router/api.d.ts
+interface ApplyHandlerOptions {
+  /** Use a non-default OpenFeature provider by name. */
+  providerName?: string;
+}
+/**
+* Builds the POST handler that the client `ConfidencePagesProvider` calls to
+* fire exposure events. Mount it at `/api/confidence/apply` (or pass a custom
+* `apiPath` to `ConfidencePagesProvider` if you mount it elsewhere).
+*
+* @example
+* // pages/api/confidence/apply.ts
+* import { applyHandler } from '@spotify-confidence/openfeature-server-provider-local/pages-router/api';
+* export default applyHandler();
+*/
+declare function applyHandler(opts?: ApplyHandlerOptions): NextApiHandler;
+//#endregion
+export { ApplyHandlerOptions, applyHandler };

package/dist/pages-router/api.js

@@ -0,0 +1,62 @@
+import { OpenFeature } from "@openfeature/server-sdk";
+import { createDecipheriv, createHash } from "node:crypto";
+const PROVIDER_NAME = "ConfidenceServerProviderLocal";
+function getConfidenceProvider(providerName) {
+	const provider = providerName ? OpenFeature.getProvider(providerName) : OpenFeature.getProvider();
+	if (provider?.metadata?.name !== PROVIDER_NAME) return null;
+	return provider;
+}
+const ALGO = "aes-256-gcm";
+const IV_LEN = 12;
+const TAG_LEN = 16;
+let cachedKey = null;
+function getKey() {
+	if (cachedKey) return cachedKey;
+	const raw = process.env.CONFIDENCE_TOKEN_KEY;
+	if (!raw) throw new Error("CONFIDENCE_TOKEN_KEY is not set. Generate one with: openssl rand -hex 32 — and set it in the server environment.");
+	cachedKey = createHash("sha256").update(raw).digest();
+	return cachedKey;
+}
+function openResolveToken(handle) {
+	const buf = Buffer.from(handle, "base64url");
+	if (buf.length < IV_LEN + TAG_LEN) throw new Error("Invalid Confidence handle");
+	const iv = buf.subarray(0, IV_LEN);
+	const tag = buf.subarray(IV_LEN, IV_LEN + TAG_LEN);
+	const ciphertext = buf.subarray(IV_LEN + TAG_LEN);
+	const decipher = createDecipheriv(ALGO, getKey(), iv);
+	decipher.setAuthTag(tag);
+	return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}
+function applyHandler(opts = {}) {
+	return async (req, res) => {
+		if (req.method !== "POST") {
+			res.setHeader("Allow", "POST");
+			res.status(405).end();
+			return;
+		}
+		const body = req.body;
+		if (!body || typeof body.resolveToken !== "string" || typeof body.flagName !== "string") {
+			res.status(400).end();
+			return;
+		}
+		const provider = getConfidenceProvider(opts.providerName);
+		if (!provider) {
+			res.status(503).end();
+			return;
+		}
+		let openedToken;
+		try {
+			openedToken = openResolveToken(body.resolveToken);
+		} catch {
+			res.status(400).end();
+			return;
+		}
+		if (!openedToken) {
+			res.status(204).end();
+			return;
+		}
+		provider.applyFlag(openedToken, body.flagName);
+		res.status(204).end();
+	};
+}
+export { applyHandler };

package/dist/pages-router/client.d.ts

@@ -0,0 +1,69 @@
+import { ReactNode } from "react";
+import "@openfeature/core";
+
+//#region src/types.d.ts
+type ResolutionReason = "ERROR" | "FLAG_ARCHIVED" | "MATCH" | "NO_SEGMENT_MATCH" | "TARGETING_KEY_ERROR" | "NO_TREATMENT_MATCH" | "MATERIALIZATION_NOT_SUPPORTED" | "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/pages-router/types.d.ts
+type FlagBundle$1 = FlagBundle;
+/**
+* Server-to-client transport payload returned from `withConfidence` and
+* consumed by `<ConfidencePagesProvider>`. Structurally a `FlagBundle` whose
+* `resolveToken` has been sealed (AES-GCM) — the apply API route is the only
+* thing that opens it.
+*/
+type ConfidencePageProps = FlagBundle$1;
+//#endregion
+//#region src/pages-router/client.d.ts
+interface Props {
+  /**
+  * The Confidence payload returned from `withConfidence` in
+  * `getServerSideProps`, normally pulled out of `pageProps` in `_app.tsx`.
+  * Pages that don't resolve flags pass `undefined` and any `useFlag` /
+  * `useFlagDetails` calls in their tree return defaults.
+  */
+  confidence?: ConfidencePageProps;
+  /** Override the apply API route. Must match where you mount `applyHandler`. */
+  apiPath?: string;
+  children: ReactNode;
+}
+/**
+* Place at the top of `_app.tsx`. Bridges the bundle resolved on the server
+* to the client `useFlag` / `useFlagDetails` hooks.
+*/
+declare function ConfidencePagesProvider({
+  confidence,
+  apiPath,
+  children
+}: Props): React.ReactElement;
+//#endregion
+export { type ConfidencePageProps, ConfidencePagesProvider };

package/dist/pages-router/client.js

@@ -0,0 +1,32 @@
+"use client";
+import { useCallback } from "react";
+import { ConfidenceClientProvider } from "@spotify-confidence/openfeature-server-provider-local/react-client";
+import { Fragment, jsx } from "react/jsx-runtime";
+const DEFAULT_APPLY_PATH = "/api/confidence/apply";
+function ConfidencePagesProvider({ confidence, apiPath = DEFAULT_APPLY_PATH, children }) {
+	const resolveToken = confidence?.resolveToken;
+	const apply = useCallback(async (flagName) => {
+		if (!resolveToken) return;
+		try {
+			const res = await fetch(apiPath, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					resolveToken,
+					flagName
+				}),
+				keepalive: true
+			});
+			if (!res.ok && process.env.NODE_ENV !== "production") console.warn(`[Confidence] apply failed: ${res.status} ${res.statusText}. Mount applyHandler at ${apiPath} and ensure a ConfidenceServerProviderLocal is registered.`);
+		} catch (err) {
+			if (process.env.NODE_ENV !== "production") console.warn("[Confidence] apply request failed:", err);
+		}
+	}, [resolveToken, apiPath]);
+	if (!confidence) return /* @__PURE__ */ jsx(Fragment, { children });
+	return /* @__PURE__ */ jsx(ConfidenceClientProvider, {
+		bundle: confidence,
+		apply,
+		children
+	});
+}
+export { ConfidencePagesProvider };

package/dist/pages-router/server.d.ts

@@ -0,0 +1,112 @@
+import { EvaluationContext } from "@openfeature/server-sdk";
+import { GetServerSideProps, GetServerSidePropsContext, Redirect } from "next";
+import "@openfeature/core";
+
+//#region src/types.d.ts
+type ResolutionReason = "ERROR" | "FLAG_ARCHIVED" | "MATCH" | "NO_SEGMENT_MATCH" | "TARGETING_KEY_ERROR" | "NO_TREATMENT_MATCH" | "MATERIALIZATION_NOT_SUPPORTED" | "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/pages-router/types.d.ts
+type FlagBundle$1 = FlagBundle;
+/**
+* Server-to-client transport payload returned from `withConfidence` and
+* consumed by `<ConfidencePagesProvider>`. Structurally a `FlagBundle` whose
+* `resolveToken` has been sealed (AES-GCM) — the apply API route is the only
+* thing that opens it.
+*/
+type ConfidencePageProps = FlagBundle$1;
+//#endregion
+//#region src/pages-router/server.d.ts
+interface WithConfidenceOptions {
+  /** Use a non-default OpenFeature provider by name. */
+  providerName?: string;
+}
+/**
+* Return type of the function passed to `withConfidence`. Augments the standard
+* `getServerSideProps` shape with a required `context` (the evaluation context
+* for flag resolution) and an optional `flags` allow-list.
+*/
+type WithConfidenceResult<P extends {
+  [key: string]: any;
+  confidence?: never;
+}> = {
+  props: P | Promise<P>;
+  /**
+  * Evaluation context for flag resolution. Omit to skip flag resolution
+  * entirely for this request — `pageProps.confidence` will be absent and
+  * any `useFlag` / `useFlagDetails` calls in the tree fall back to
+  * default values. Useful when flag access is conditional (e.g.
+  * unauthenticated requests).
+  */
+  context?: EvaluationContext;
+  /** Restrict resolution to a subset of flags. Defaults to all. */
+  flags?: string[];
+} | {
+  redirect: Redirect;
+} | {
+  notFound: true;
+};
+/**
+* Low-level: resolve flags into a `ConfidencePageProps` payload. Use this if
+* you want flag resolution outside the `withConfidence` flow (e.g. inside a
+* custom decorator). Most callers should just use `withConfidence`.
+*/
+declare function resolveConfidence(context: EvaluationContext, opts?: {
+  flags?: string[];
+  providerName?: string;
+}): Promise<ConfidencePageProps>;
+/**
+* `getServerSideProps` decorator. Pass a single function that does your data
+* fetching AND returns the evaluation context for flag resolution. The
+* decorator resolves the flag bundle, seals it, and merges it into
+* `pageProps.confidence`.
+*
+* Returning `{ redirect }` or `{ notFound }` short-circuits before flag
+* resolution, just like a normal `getServerSideProps`.
+*
+* @example
+* export const getServerSideProps = withConfidence(async ({ req }) => {
+*   const visitorId = req.cookies.uid ?? 'anon';
+*   const data = await fetchSomeData();
+*   return {
+*     props: { data },
+*     context: { visitor_id: visitorId },
+*   };
+* });
+*/
+declare function withConfidence<P extends {
+  [key: string]: any;
+  confidence?: never;
+} = {}>(gssp: (ctx: GetServerSidePropsContext) => Promise<WithConfidenceResult<P>>, opts?: WithConfidenceOptions): GetServerSideProps<P & {
+  confidence?: ConfidencePageProps;
+}>;
+//#endregion
+export { type ConfidencePageProps, WithConfidenceOptions, WithConfidenceResult, resolveConfidence, withConfidence };

package/dist/pages-router/server.js

@@ -0,0 +1,121 @@
+import "@bufbuild/protobuf/wire";
+import { OpenFeature } from "@openfeature/server-sdk";
+import { createCipheriv, createHash, randomBytes } from "node:crypto";
+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;
+	}
+}
+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
+	};
+}
+const PROVIDER_NAME = "ConfidenceServerProviderLocal";
+function getConfidenceProvider(providerName) {
+	const provider = providerName ? OpenFeature.getProvider(providerName) : OpenFeature.getProvider();
+	if (provider?.metadata?.name !== PROVIDER_NAME) return null;
+	return provider;
+}
+const ALGO = "aes-256-gcm";
+const IV_LEN = 12;
+let cachedKey = null;
+function getKey() {
+	if (cachedKey) return cachedKey;
+	const raw = process.env.CONFIDENCE_TOKEN_KEY;
+	if (!raw) throw new Error("CONFIDENCE_TOKEN_KEY is not set. Generate one with: openssl rand -hex 32 — and set it in the server environment.");
+	cachedKey = createHash("sha256").update(raw).digest();
+	return cachedKey;
+}
+function sealResolveToken(token) {
+	const iv = randomBytes(IV_LEN);
+	const cipher = createCipheriv(ALGO, getKey(), iv);
+	const ciphertext = Buffer.concat([cipher.update(token, "utf8"), cipher.final()]);
+	const tag = cipher.getAuthTag();
+	return Buffer.concat([
+		iv,
+		tag,
+		ciphertext
+	]).toString("base64url");
+}
+function providerMissingBundle(providerName) {
+	return error(ErrorCode.GENERAL, `OpenFeature provider${providerName ? ` "${providerName}"` : ""} is not a ConfidenceServerProviderLocal. Register one with OpenFeature.setProviderAndWait — typically in instrumentation.ts.`);
+}
+async function resolveConfidence(context, opts = {}) {
+	const provider = getConfidenceProvider(opts.providerName);
+	if (!provider) return providerMissingBundle(opts.providerName);
+	const bundle = await provider.resolve(context, opts.flags ?? []);
+	return {
+		...bundle,
+		resolveToken: sealResolveToken(bundle.resolveToken)
+	};
+}
+function withConfidence(gssp, opts = {}) {
+	return async (ctx) => {
+		const result = await gssp(ctx);
+		if (!("props" in result)) return result;
+		const innerProps = await Promise.resolve(result.props);
+		if (result.context === void 0) return { props: innerProps };
+		const confidence = await resolveConfidence(result.context, {
+			flags: result.flags,
+			providerName: opts.providerName
+		});
+		return { props: {
+			...innerProps,
+			confidence
+		} };
+	};
+}
+export { resolveConfidence, withConfidence };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spotify-confidence/openfeature-server-provider-local",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Spotify Confidence Open Feature provider",
   "type": "module",
   "files": [
@@ -32,6 +32,18 @@
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
     },
+    "./pages-router/server": {
+      "types": "./dist/pages-router/server.d.ts",
+      "default": "./dist/pages-router/server.js"
+    },
+    "./pages-router/client": {
+      "types": "./dist/pages-router/client.d.ts",
+      "default": "./dist/pages-router/client.js"
+    },
+    "./pages-router/api": {
+      "types": "./dist/pages-router/api.d.ts",
+      "default": "./dist/pages-router/api.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -60,6 +72,7 @@
     "debug": "^4.4.3",
     "dotenv": "^17.2.2",
     "happy-dom": "^20.3.4",
+    "next": "^16.0.0",
     "prettier": "^2.8.8",
     "react": "^19",
     "react-dom": "^19.2.3",
@@ -72,6 +85,7 @@
   "peerDependencies": {
     "@openfeature/core": "^1.0.0",
     "debug": "^4.4.3",
+    "next": ">=13.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -81,6 +95,9 @@
     "debug": {
       "optional": true
     },
+    "next": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }