@coframe/sdk 1.1.22 → 1.1.24

package/README.md

@@ -65,6 +65,12 @@ only has to forward `<ingestUrl>/*` to `https://ingest.app.coframe.com/ingest/v2
 with the path unchanged. Both overrides are optional and retain the compiled
 Coframe endpoints when omitted.
 
+Configuring either `projectUrl` or `ingestUrl` makes CMAB experiments use
+deterministic local assignment without calling the Edge assignment API.
+Configure both overrides when the browser must avoid the SDK-compiled Coframe
+project and ingest endpoints entirely. Debug tools remain controlled by
+`enableDebug`.
+
 ### URL controls
 
 The npm entry uses the same browser URL controls as the script-tag and Edge
@@ -130,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
@@ -253,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:
 
@@ -269,3 +429,6 @@ Returns a payload that may include:
 - `useCoframeTreatments()`
 - `useCoframeTreatment(experimentId)`
 - `useCoframeVariant(experimentId)`
+- `useFeatureFlag(key)` / `useFeatureFlagVariantKey(key)`
+- `useFeatureFlagEnabled(key)`
+- `useFeatureFlagResult(key)` / `useFeatureFlagPayload(key)`