@coframe/sdk 1.1.23 → 1.1.25

package/README.md

@@ -136,6 +136,148 @@ const projectData = serverData?.project
 
 Pass `projectData` into `<CoframeProvider>` to avoid the extra client-side project fetch and personalize on first paint.
 
+## Feature flags and remote config
+
+Browser Feature Flags use the existing public `projectId` and receive only
+flags marked **Public**. `selector` is optional; use `names` for
+individual flag keys and `groups` to evaluate every flag assigned to a page or
+business area.
+
+```ts
+import { setUserToken } from '@coframe/sdk'
+import {
+  featureFlags,
+  getFeatureFlag,
+  getFeatureFlagPayload,
+  isFeatureEnabled,
+  onFeatureFlags,
+} from '@coframe/sdk/feature-flags'
+
+setUserToken('customer-123')
+
+await featureFlags.init({
+  projectId: 'your-project-id',
+  selector: {
+    names: ['checkout-redesign'],
+    groups: ['homepage_campaigns'],
+  },
+})
+
+onFeatureFlags(() => {
+  if (isFeatureEnabled('checkout-redesign')) {
+    showNewCheckout()
+  }
+
+  const content = getFeatureFlagPayload('homepage-content')
+  const checkoutVariant = getFeatureFlag('checkout-layout')
+})
+```
+
+Feature Flags are a separate browser entry point and do not increase or initialize
+the main SDK bundle. When both clients are used, Feature Flags reuse the latest
+`setUserToken()` command from Coframe's shared command queue and follow later
+identity changes automatically.
+
+Loading does not delay Coframe page modification. Synchronous getters return
+`undefined` until a cached or fresh evaluation is available. The browser client
+always keeps the latest successful response in memory. Before consent, no
+Feature Flag result or evaluation context is persisted. After consent, the
+client also caches the response in `localStorage` for five minutes and keys it
+with an opaque SHA-256 fingerprint derived from the user token and evaluation
+context. It can fall back to that persistent cache if Edge is temporarily
+unavailable. Call `reloadFeatureFlags()` to request fresh evaluations
+explicitly.
+
+Payloads support any JSON value up to 32 KB. A payload is returned only when its
+flag is enabled. Remote Config uses the same transport and payload API and
+returns the same payload to all users while active:
+
+```ts
+import { getRemoteConfig } from '@coframe/sdk/feature-flags'
+
+const navigation = getRemoteConfig('navigation-config')
+```
+
+Multivariate flags return a stable variant key from `getFeatureFlag()`. Their
+weights divide users into deterministic buckets, and each variant can carry an
+independent optional payload. `isFeatureEnabled()` remains a boolean
+convenience and returns `true` whenever a variant is assigned:
+
+```ts
+import {
+  getFeatureFlag,
+  getFeatureFlagPayload,
+  isFeatureEnabled,
+} from '@coframe/sdk/feature-flags'
+
+const variant = getFeatureFlag('checkout-layout')
+const config = getFeatureFlagPayload('checkout-layout')
+const enabled = isFeatureEnabled('checkout-layout')
+```
+
+React apps can read evaluated values from the existing provider:
+
+```tsx
+import {
+  useFeatureFlag,
+  useFeatureFlagEnabled,
+  useFeatureFlagPayload,
+  useFeatureFlagVariantKey,
+} from '@coframe/sdk/react'
+
+function Checkout() {
+  const enabled = useFeatureFlag('checkout-redesign')
+  const payload = useFeatureFlagPayload('checkout-redesign')
+
+  if (enabled === undefined) return <CheckoutSkeleton />
+  return enabled ? <NewCheckout config={payload} /> : <OldCheckout />
+}
+
+function CheckoutLayout() {
+  const variant = useFeatureFlagVariantKey('checkout-layout')
+  const enabled = useFeatureFlagEnabled('checkout-layout')
+  const payload = useFeatureFlagPayload('checkout-layout')
+  return <Checkout variant={variant} enabled={enabled} config={payload} />
+}
+```
+
+For server and edge runtimes, use a secret Feature Flags Server API key. It is
+project-scoped, can read **Private** flags, and must never be included in a
+browser bundle or a `NEXT_PUBLIC_*` environment variable. Each single-key
+helper sends a key-filtered request and fails closed unless a `defaultValue` is
+supplied. Browser and server helpers both call `/api/v1/flags`; server helpers
+include the API key as a Bearer credential so the response may include both
+**Public** and **Private** flags:
+
+```ts
+import {
+  evaluateFlags,
+  getFeatureFlag,
+  getRemoteConfig,
+  isFeatureEnabled,
+} from '@coframe/sdk/server'
+
+const options = {
+  projectId: 'your-project-id',
+  apiKey: process.env.COFRAME_FEATURE_FLAGS_SERVER_KEY!,
+  userToken: user.id,
+  currentUrl: request.url,
+  userContext: { plan: user.plan },
+}
+
+const checkoutFlags = await evaluateFlags({
+  ...options,
+  selector: { groups: ['cart_checkout'] },
+})
+
+const enabled = await isFeatureEnabled('checkout-redesign', {
+  ...options,
+  defaultValue: false,
+})
+const variant = await getFeatureFlag('checkout-layout', options)
+const content = await getRemoteConfig('homepage-content', options)
+```
+
 ## Common React usage
 
 ### Read variants in components
@@ -259,9 +401,21 @@ Modern resolution modes handle package subpath exports more reliably.
 - `onTreatmentApplied(...)`
 - `onLog(...)`
 
+### `@coframe/sdk/feature-flags`
+
+- `featureFlags.init(options)`
+- `featureFlags.setUserToken(userToken)` / `featureFlags.reset()`
+- `featureFlags.getUserToken()`
+- `getFeatureFlag(key)` / `isFeatureEnabled(key)`
+- `getFeatureFlagPayload(key)` / `getRemoteConfig(key)`
+- `onFeatureFlags(callback)` / `reloadFeatureFlags()`
+
 ### `@coframe/sdk/server`
 
 - `getProjectData(options)`
+- `evaluateFlags(options)`
+- `getFeatureFlag(key, options)` / `isFeatureEnabled(key, options)`
+- `getFeatureFlagPayload(key, options)` / `getRemoteConfig(key, options)`
 
 Returns a payload that may include:
 
@@ -275,3 +429,6 @@ Returns a payload that may include:
 - `useCoframeTreatments()`
 - `useCoframeTreatment(experimentId)`
 - `useCoframeVariant(experimentId)`
+- `useFeatureFlag(key)` / `useFeatureFlagVariantKey(key)`
+- `useFeatureFlagEnabled(key)`
+- `useFeatureFlagResult(key)` / `useFeatureFlagPayload(key)`

package/dist/pkg/cf.cjs.js

@@ -2277,7 +2277,7 @@ function isElementVisible(el) {
     return rect.top >= 0 && rect.bottom <= window.innerHeight;
 }
 const VALUE_UNKNOWN_YET = 'n/a';
-function checkActivationCondition(condition, personalizationHeaders, currentUrl, languages, browserPlatform, userToken, userVisitCount, runJsFunction, logger) {
+function checkActivationCondition(condition, personalizationHeaders, currentUrl, languages, browserPlatform, userToken, userVisitCount, runJsFunction, logger, options) {
     if (condition.and) {
         const results = condition.and.map((c) => checkActivationCondition(c, personalizationHeaders, currentUrl, languages, browserPlatform, userToken, userVisitCount, runJsFunction, logger));
         const hasUnknown = results.some((r) => r === VALUE_UNKNOWN_YET);
@@ -2835,7 +2835,7 @@ function keepRolledOutExperiments(frames) {
 function buildSessionContext(isInitialApply) {
     const context = {};
     const viewport = getScreenSize();
-    if (isReportedSize(viewport.width) && isReportedSize(viewport.height)) {
+    if (isReportedSize$1(viewport.width) && isReportedSize$1(viewport.height)) {
         context.viewport_width = viewport.width;
         context.viewport_height = viewport.height;
     }
@@ -2858,7 +2858,7 @@ function buildSessionContext(isInitialApply) {
     }
     return context;
 }
-function isReportedSize(size) {
+function isReportedSize$1(size) {
     return (typeof size === 'number' && size > 0 && size !== Number.POSITIVE_INFINITY);
 }
 function getNavigationType(isInitialApply) {
@@ -3779,6 +3779,39 @@ async function modifyPage(Coframe, configResult, projectResult, analytics) {
 }
 
 const TIMEOUT_MAX_MS = 5000;
+const MAX_NOT_RENDERED_REASON_CHARS = 200;
+function isReportedSize(size) {
+    return (typeof size === 'number' && size > 0 && size !== Number.POSITIVE_INFINITY);
+}
+function describeEnvironment(initTime) {
+    const metadata = {};
+    if (typeof window !== 'undefined') {
+        if (isReportedSize(window.innerWidth)) {
+            metadata.viewport_width = window.innerWidth;
+        }
+        if (isReportedSize(window.innerHeight)) {
+            metadata.viewport_height = window.innerHeight;
+        }
+        const screen = window.screen;
+        if (screen && isReportedSize(screen.width)) {
+            metadata.screen_width = screen.width;
+        }
+        if (screen && isReportedSize(screen.height)) {
+            metadata.screen_height = screen.height;
+        }
+        if (isReportedSize(window.devicePixelRatio)) {
+            metadata.device_pixel_ratio = window.devicePixelRatio;
+        }
+        if (typeof navigator.userAgent === 'string') {
+            metadata.user_agent = navigator.userAgent;
+        }
+        if (typeof document.readyState === 'string') {
+            metadata.document_ready_state = document.readyState;
+        }
+    }
+    metadata.ms_since_init = Math.max(0, Date.now() - initTime);
+    return metadata;
+}
 function getFeatureFlagValue(cmd) {
     if (cmd.featureFlagSet !== undefined)
         return cmd.featureFlagSet;
@@ -3832,6 +3865,15 @@ async function resolveConfig(Coframe, revealPage) {
             logger.warn('Failed to wait for variant rendered command', 'missing_variant_rendered');
         }
     };
+    const warnVariantNotRendered = (reason) => {
+        if (!applyVariantChangesStarted)
+            return;
+        const metadata = describeEnvironment(executionStartTime.getTime());
+        if (typeof reason === 'string') {
+            metadata.reason = reason.slice(0, MAX_NOT_RENDERED_REASON_CHARS);
+        }
+        logger.warn('Variant not rendered', 'variant_not_rendered', metadata);
+    };
     waitForCmd((cmd) => cmd.variantRendered === true || cmd.emit === 'variantRendered', Coframe, timeoutMs)
         .then((cmd) => {
         if (!cmd) {
@@ -3841,6 +3883,13 @@ async function resolveConfig(Coframe, revealPage) {
         .finally(() => {
         revealPage();
     });
+    const loggedReasons = [];
+    listenForCmd((cmd) => cmd.emit === 'variantNotRendered', (cmd) => {
+        if (loggedReasons.indexOf(cmd.reason) !== -1)
+            return;
+        loggedReasons.push(cmd.reason);
+        warnVariantNotRendered(cmd.reason);
+    });
     if (!projectId) {
         logger.error('No project ID', 'no_project_id', {
             description: 'No Coframe Page ID',

package/dist/pkg/cf.esm.mjs

@@ -2275,7 +2275,7 @@ function isElementVisible(el) {
     return rect.top >= 0 && rect.bottom <= window.innerHeight;
 }
 const VALUE_UNKNOWN_YET = 'n/a';
-function checkActivationCondition(condition, personalizationHeaders, currentUrl, languages, browserPlatform, userToken, userVisitCount, runJsFunction, logger) {
+function checkActivationCondition(condition, personalizationHeaders, currentUrl, languages, browserPlatform, userToken, userVisitCount, runJsFunction, logger, options) {
     if (condition.and) {
         const results = condition.and.map((c) => checkActivationCondition(c, personalizationHeaders, currentUrl, languages, browserPlatform, userToken, userVisitCount, runJsFunction, logger));
         const hasUnknown = results.some((r) => r === VALUE_UNKNOWN_YET);
@@ -2833,7 +2833,7 @@ function keepRolledOutExperiments(frames) {
 function buildSessionContext(isInitialApply) {
     const context = {};
     const viewport = getScreenSize();
-    if (isReportedSize(viewport.width) && isReportedSize(viewport.height)) {
+    if (isReportedSize$1(viewport.width) && isReportedSize$1(viewport.height)) {
         context.viewport_width = viewport.width;
         context.viewport_height = viewport.height;
     }
@@ -2856,7 +2856,7 @@ function buildSessionContext(isInitialApply) {
     }
     return context;
 }
-function isReportedSize(size) {
+function isReportedSize$1(size) {
     return (typeof size === 'number' && size > 0 && size !== Number.POSITIVE_INFINITY);
 }
 function getNavigationType(isInitialApply) {
@@ -3777,6 +3777,39 @@ async function modifyPage(Coframe, configResult, projectResult, analytics) {
 }
 
 const TIMEOUT_MAX_MS = 5000;
+const MAX_NOT_RENDERED_REASON_CHARS = 200;
+function isReportedSize(size) {
+    return (typeof size === 'number' && size > 0 && size !== Number.POSITIVE_INFINITY);
+}
+function describeEnvironment(initTime) {
+    const metadata = {};
+    if (typeof window !== 'undefined') {
+        if (isReportedSize(window.innerWidth)) {
+            metadata.viewport_width = window.innerWidth;
+        }
+        if (isReportedSize(window.innerHeight)) {
+            metadata.viewport_height = window.innerHeight;
+        }
+        const screen = window.screen;
+        if (screen && isReportedSize(screen.width)) {
+            metadata.screen_width = screen.width;
+        }
+        if (screen && isReportedSize(screen.height)) {
+            metadata.screen_height = screen.height;
+        }
+        if (isReportedSize(window.devicePixelRatio)) {
+            metadata.device_pixel_ratio = window.devicePixelRatio;
+        }
+        if (typeof navigator.userAgent === 'string') {
+            metadata.user_agent = navigator.userAgent;
+        }
+        if (typeof document.readyState === 'string') {
+            metadata.document_ready_state = document.readyState;
+        }
+    }
+    metadata.ms_since_init = Math.max(0, Date.now() - initTime);
+    return metadata;
+}
 function getFeatureFlagValue(cmd) {
     if (cmd.featureFlagSet !== undefined)
         return cmd.featureFlagSet;
@@ -3830,6 +3863,15 @@ async function resolveConfig(Coframe, revealPage) {
             logger.warn('Failed to wait for variant rendered command', 'missing_variant_rendered');
         }
     };
+    const warnVariantNotRendered = (reason) => {
+        if (!applyVariantChangesStarted)
+            return;
+        const metadata = describeEnvironment(executionStartTime.getTime());
+        if (typeof reason === 'string') {
+            metadata.reason = reason.slice(0, MAX_NOT_RENDERED_REASON_CHARS);
+        }
+        logger.warn('Variant not rendered', 'variant_not_rendered', metadata);
+    };
     waitForCmd((cmd) => cmd.variantRendered === true || cmd.emit === 'variantRendered', Coframe, timeoutMs)
         .then((cmd) => {
         if (!cmd) {
@@ -3839,6 +3881,13 @@ async function resolveConfig(Coframe, revealPage) {
         .finally(() => {
         revealPage();
     });
+    const loggedReasons = [];
+    listenForCmd((cmd) => cmd.emit === 'variantNotRendered', (cmd) => {
+        if (loggedReasons.indexOf(cmd.reason) !== -1)
+            return;
+        loggedReasons.push(cmd.reason);
+        warnVariantNotRendered(cmd.reason);
+    });
     if (!projectId) {
         logger.error('No project ID', 'no_project_id', {
             description: 'No Coframe Page ID',