@coframe/sdk 1.1.30 → 1.1.32

package/README.md

@@ -161,6 +161,8 @@ setUserToken('customer-123')
 
 await featureFlags.init({
   projectId: 'your-project-id',
+  // Optional: replaces the complete default ingest base, including /ingest/v2.
+  ingestUrl: 'https://events.example.com/coframe',
   selector: {
     names: ['checkout-redesign'],
     groups: ['homepage_campaigns'],
@@ -192,6 +194,24 @@ context. It can fall back to that persistent cache if Edge is temporarily
 unavailable. Call `reloadFeatureFlags()` to request fresh evaluations
 explicitly.
 
+Every single-flag getter automatically records a `feature_flag_called` event
+after a result has loaded. This applies to boolean, multivariate, and Remote
+Config flags. The event includes the key, evaluated value, payload, version,
+reason, and evaluation request metadata. The project, key, and version identify
+the corresponding flag definition without changing the Edge response. Every
+getter or hook access records its own event, including repeated reads of the
+same result. To read without recording an event, pass `{ sendEvent: false }`:
+
+```ts
+const variant = getFeatureFlag('checkout-layout', { sendEvent: false })
+```
+
+Tracking uses an independent Feature Flags queue and does not initialize the
+main SDK. It follows the shared consent state: while consent is explicitly
+disabled, events remain in memory and are sent after consent is enabled. The
+optional Feature Flags `ingestUrl` has the same base-replacement behavior as
+the main SDK; the client appends `/batched_events/<projectId>/`.
+
 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:
@@ -247,15 +267,20 @@ function CheckoutLayout() {
 
 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:
+browser bundle or a `NEXT_PUBLIC_*` environment variable. `evaluateFlags()`
+records every flag returned by its selector, while each single-key helper
+records only that key. Repeated evaluations record new events even when the
+result is unchanged. Both paths enqueue tracking without delaying their result
+and accept `sendEvent: false` to evaluate without recording an event.
+Single-key helpers send a key-filtered request and fail 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,
+  flushFeatureFlagEvents,
   getFeatureFlag,
   getRemoteConfig,
   isFeatureEnabled,
@@ -272,8 +297,19 @@ const options = {
 const checkoutFlags = await evaluateFlags({
   ...options,
   selector: { groups: ['cart_checkout'] },
+  ingestUrl: 'https://events.example.com/coframe',
 })
 
+// evaluateFlags tracks every returned flag without another Edge request.
+// Single-key helpers track their requested key automatically.
+const checkoutVariant = await getFeatureFlag('checkout-layout', {
+  ...options,
+  ingestUrl: 'https://events.example.com/coframe',
+})
+
+// Useful before a short-lived process exits. Tracking failures are swallowed.
+await flushFeatureFlagEvents()
+
 const enabled = await isFeatureEnabled('checkout-redesign', {
   ...options,
   defaultValue: false,
@@ -420,6 +456,7 @@ Modern resolution modes handle package subpath exports more reliably.
 - `evaluateFlags(options)`
 - `getFeatureFlag(key, options)` / `isFeatureEnabled(key, options)`
 - `getFeatureFlagPayload(key, options)` / `getRemoteConfig(key, options)`
+- `flushFeatureFlagEvents()`
 
 Returns a payload that may include:
 

package/dist/pkg/cf.cjs.js

@@ -991,7 +991,13 @@ function isDebugToolsSessionEnabled(allowed) {
         clearDebugToolsSession();
         return false;
     }
-    const enabledByUrl = resolveDebugToolsEntry().kind !== 'none';
+    const entry = resolveDebugToolsEntry();
+    const enabledByUrl = entry.kind !== 'none';
+    const annotationUrlEntry = entry.kind === 'tool' && entry.toolId === 'annotations';
+    if (annotationUrlEntry) {
+        clearDebugToolsSession();
+        return true;
+    }
     if (enabledByUrl) {
         enableDebugToolsSession();
         return true;
@@ -999,6 +1005,8 @@ function isDebugToolsSessionEnabled(allowed) {
     try {
         const enabled = window.sessionStorage.getItem(COFRAME_DEBUG_TOOLS_SESSION_STORAGE_KEY) ===
             ENABLED_VALUE;
+        if (!enabled)
+            clearDebugToolsSession();
         return enabled;
     }
     catch (_a) {

package/dist/pkg/cf.esm.mjs

@@ -989,7 +989,13 @@ function isDebugToolsSessionEnabled(allowed) {
         clearDebugToolsSession();
         return false;
     }
-    const enabledByUrl = resolveDebugToolsEntry().kind !== 'none';
+    const entry = resolveDebugToolsEntry();
+    const enabledByUrl = entry.kind !== 'none';
+    const annotationUrlEntry = entry.kind === 'tool' && entry.toolId === 'annotations';
+    if (annotationUrlEntry) {
+        clearDebugToolsSession();
+        return true;
+    }
     if (enabledByUrl) {
         enableDebugToolsSession();
         return true;
@@ -997,6 +1003,8 @@ function isDebugToolsSessionEnabled(allowed) {
     try {
         const enabled = window.sessionStorage.getItem(COFRAME_DEBUG_TOOLS_SESSION_STORAGE_KEY) ===
             ENABLED_VALUE;
+        if (!enabled)
+            clearDebugToolsSession();
         return enabled;
     }
     catch (_a) {

package/dist/pkg/feature-flags.cjs.js

@@ -98,6 +98,206 @@ const setUserTokenCookie = (uuid, logger) => {
     setCookie(USER_TOKEN_COOKIE_KEY, uuid);
 };
 
+const FEATURE_FLAG_EVENT_TYPE = 'feature_flag_called';
+const FEATURE_FLAG_BATCH_BYTES = 48 * 1024;
+function resolveFeatureFlagIngestBase(customUrl) {
+    const normalized = customUrl === null || customUrl === void 0 ? void 0 : customUrl.trim().replace(/\/+$/, '');
+    return normalized || "https://ingest.app.coframe.com/ingest/v2";
+}
+function featureFlagEventsEndpoint(ingestBase, projectId) {
+    return `${ingestBase}/batched_events/${projectId}/`;
+}
+function featureFlagValue(result) {
+    var _a;
+    return (_a = result.variant) !== null && _a !== void 0 ? _a : result.enabled;
+}
+function snapshotPayload(payload) {
+    return payload === null
+        ? null
+        : JSON.parse(JSON.stringify(payload));
+}
+function newEventId() {
+    const cryptoObject = globalThis.crypto;
+    if ((cryptoObject === null || cryptoObject === void 0 ? void 0 : cryptoObject.randomUUID) || (cryptoObject === null || cryptoObject === void 0 ? void 0 : cryptoObject.getRandomValues)) {
+        return generateUUID();
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (char) => {
+        const random = Math.floor(Math.random() * 16);
+        return (char === 'x' ? random : (random & 0x3) | 0x8).toString(16);
+    });
+}
+function createFeatureFlagTrackingEvent(access) {
+    var _a;
+    const { result, response } = access;
+    const errors = [];
+    if (response.errorsWhileComputingFlags) {
+        errors.push('errors_while_computing_flags');
+    }
+    if (!result)
+        errors.push('flag_missing');
+    return {
+        event_id: newEventId(),
+        project_id: access.projectId,
+        session_id: access.sessionId,
+        type: FEATURE_FLAG_EVENT_TYPE,
+        time: new Date().toISOString(),
+        url: access.url,
+        user_token: access.userToken,
+        content: {
+            metadata: {
+                key: access.key,
+                ...(result
+                    ? {
+                        value: featureFlagValue(result),
+                        payload: snapshotPayload('payload' in result ? ((_a = result.payload) !== null && _a !== void 0 ? _a : null) : null),
+                        version: result.metadata.version,
+                        reason: result.reason,
+                    }
+                    : {}),
+                request_id: response.requestId,
+                snapshot_version: response.snapshotVersion,
+                ...(errors.length > 0 ? { error: errors.join(',') } : {}),
+            },
+        },
+    };
+}
+function jsonBytes(value) {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+function chunkFeatureFlagEvents(events) {
+    const chunks = [];
+    let current = [];
+    for (const event of events) {
+        if (current.length > 0 &&
+            jsonBytes([...current, event]) > FEATURE_FLAG_BATCH_BYTES) {
+            chunks.push(current);
+            current = [];
+        }
+        current.push(event);
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+
+const FLUSH_INTERVAL_MS = 3000;
+const BATCH_SIZE = 32;
+const MAX_QUEUE_SIZE = 1000;
+let config$1;
+let ingestBase = '';
+let sessionId = '';
+let consentAllowed = true;
+let queue = [];
+let flushTimer;
+let warnedQueueFull = false;
+let warnedTransport = false;
+function installLifecycle() {
+    if (typeof window === 'undefined')
+        return;
+    flushTimer = window.setInterval(flushFeatureFlagBrowserEvents, FLUSH_INTERVAL_MS);
+    window.addEventListener('pagehide', flushFeatureFlagBrowserEvents);
+    if (typeof document !== 'undefined') {
+        document.addEventListener('visibilitychange', flushWhenHidden);
+    }
+}
+function removeLifecycle() {
+    if (typeof window === 'undefined')
+        return;
+    if (flushTimer !== undefined)
+        window.clearInterval(flushTimer);
+    flushTimer = undefined;
+    window.removeEventListener('pagehide', flushFeatureFlagBrowserEvents);
+    if (typeof document !== 'undefined') {
+        document.removeEventListener('visibilitychange', flushWhenHidden);
+    }
+}
+function flushWhenHidden() {
+    if (typeof document !== 'undefined' &&
+        document.visibilityState === 'hidden') {
+        flushFeatureFlagBrowserEvents();
+    }
+}
+function configureFeatureFlagBrowserTracking(nextConfig) {
+    removeLifecycle();
+    const nextIngestBase = resolveFeatureFlagIngestBase(nextConfig.ingestUrl);
+    const sameTarget = (config$1 === null || config$1 === void 0 ? void 0 : config$1.projectId) === nextConfig.projectId && ingestBase === nextIngestBase;
+    if (!sameTarget) {
+        flushFeatureFlagBrowserEvents();
+        queue = [];
+    }
+    config$1 = nextConfig;
+    ingestBase = nextIngestBase;
+    consentAllowed = nextConfig.consentAllowed;
+    warnedQueueFull = false;
+    warnedTransport = false;
+    sessionId || (sessionId = generateUUID());
+    installLifecycle();
+}
+function updateFeatureFlagTrackingUserToken(nextUserToken) {
+    if (config$1)
+        config$1.userToken = nextUserToken;
+}
+function setFeatureFlagTrackingConsent(enabled) {
+    consentAllowed = enabled;
+    if (enabled) {
+        flushFeatureFlagBrowserEvents();
+    }
+}
+function trackFeatureFlagBrowserAccess(key, result, response) {
+    if (!config$1)
+        return;
+    const access = {
+        projectId: config$1.projectId,
+        sessionId,
+        userToken: config$1.userToken,
+        url: typeof window === 'undefined' ? '' : window.location.href,
+        key,
+        result,
+        response,
+    };
+    queue.push(createFeatureFlagTrackingEvent(access));
+    if (queue.length > MAX_QUEUE_SIZE) {
+        queue.shift();
+        if (!warnedQueueFull) {
+            warnedQueueFull = true;
+            console.warn('[Coframe] Feature Flag tracking queue is full');
+        }
+    }
+    if (consentAllowed && queue.length >= BATCH_SIZE) {
+        flushFeatureFlagBrowserEvents();
+    }
+}
+function flushFeatureFlagBrowserEvents() {
+    if (!config$1 || !consentAllowed || queue.length === 0)
+        return;
+    const events = queue;
+    queue = [];
+    const endpoint = featureFlagEventsEndpoint(ingestBase, config$1.projectId);
+    if (typeof navigator === 'undefined' || !navigator.sendBeacon) {
+        if (!warnedTransport) {
+            warnedTransport = true;
+            console.warn('[Coframe] Feature Flag tracking requires navigator.sendBeacon');
+        }
+        return;
+    }
+    try {
+        for (const chunk of chunkFeatureFlagEvents(events)) {
+            const blob = new Blob([JSON.stringify(chunk)], { type: 'text/plain' });
+            if (!navigator.sendBeacon(endpoint, blob))
+                warnTransport();
+        }
+    }
+    catch (_a) {
+        warnTransport();
+    }
+}
+function warnTransport() {
+    if (warnedTransport)
+        return;
+    warnedTransport = true;
+    console.warn('[Coframe] Failed to send Feature Flag tracking beacon');
+}
+
 const DEFAULT_TIMEOUT_MS = 3000;
 const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
 const CACHE_PREFIX = 'coframe.featureFlags.';
@@ -241,7 +441,7 @@ async function fetchFeatureFlags(context) {
         window.clearTimeout(timeout);
     }
 }
-async function initializeFeatureFlags(nextConfig, nextProjectId, nextUserToken, nextUserContext) {
+async function initializeFeatureFlags(nextConfig, nextProjectId, nextUserToken, nextUserContext, trackingConsentAllowed = true) {
     var _a;
     if (!nextConfig)
         return;
@@ -249,6 +449,12 @@ async function initializeFeatureFlags(nextConfig, nextProjectId, nextUserToken,
     projectId = nextProjectId;
     userToken = nextUserToken;
     userContext = nextUserContext;
+    configureFeatureFlagBrowserTracking({
+        projectId: nextProjectId,
+        userToken: nextUserToken,
+        ingestUrl: nextConfig.ingestUrl,
+        consentAllowed: trackingConsentAllowed,
+    });
     requestGeneration += 1;
     inFlight = undefined;
     inFlightContextKey = undefined;
@@ -336,6 +542,7 @@ function updateFeatureFlagUserToken(nextUserToken) {
     if (nextUserToken === userToken)
         return;
     userToken = nextUserToken;
+    updateFeatureFlagTrackingUserToken(nextUserToken);
     requestGeneration += 1;
     inFlight = undefined;
     inFlightContextKey = undefined;
@@ -362,23 +569,43 @@ function onFeatureFlags(callback) {
             listeners.splice(index, 1);
     };
 }
-function getFeatureFlagResult(key) {
+function peekFeatureFlagResult(key) {
     return response === null || response === void 0 ? void 0 : response.flags[key];
 }
-function getFeatureFlag(key) {
+let warnedTrackingFailure = false;
+function trackFeatureFlagAccess(key) {
+    if (!response)
+        return;
+    try {
+        trackFeatureFlagBrowserAccess(key, response.flags[key], response);
+    }
+    catch (_a) {
+        if (!warnedTrackingFailure) {
+            warnedTrackingFailure = true;
+            console.warn('[Coframe] Feature Flag tracking failed');
+        }
+    }
+}
+function getFeatureFlagResult(key, options = {}) {
+    const result = peekFeatureFlagResult(key);
+    if (options.sendEvent !== false)
+        trackFeatureFlagAccess(key);
+    return result;
+}
+function getFeatureFlag(key, options) {
     var _a;
-    const result = getFeatureFlagResult(key);
+    const result = getFeatureFlagResult(key, options);
     if (!result)
         return undefined;
     return (_a = result.variant) !== null && _a !== void 0 ? _a : result.enabled;
 }
 function isFeatureEnabled(key, options) {
     var _a, _b;
-    return (_b = (_a = getFeatureFlagResult(key)) === null || _a === void 0 ? void 0 : _a.enabled) !== null && _b !== void 0 ? _b : options === null || options === void 0 ? void 0 : options.defaultValue;
+    return (_b = (_a = getFeatureFlagResult(key, options)) === null || _a === void 0 ? void 0 : _a.enabled) !== null && _b !== void 0 ? _b : options === null || options === void 0 ? void 0 : options.defaultValue;
 }
-function getFeatureFlagPayload(key) {
+function getFeatureFlagPayload(key, options) {
     var _a;
-    const result = getFeatureFlagResult(key);
+    const result = getFeatureFlagResult(key, options);
     if (!result)
         return undefined;
     return 'payload' in result ? ((_a = result.payload) !== null && _a !== void 0 ? _a : null) : null;
@@ -511,6 +738,7 @@ function persistIdentity() {
 }
 function applyConsent(enabled) {
     setCookiesEnabled(enabled);
+    setFeatureFlagTrackingConsent(enabled);
     if (enabled)
         persistIdentity();
 }
@@ -552,6 +780,7 @@ function installConsentSync() {
     subscribeToCmd((cmd) => typeof cmd.cookiesEnabled === 'boolean', (cmd) => applyConsent(!!cmd.cookiesEnabled));
 }
 function initFeatureFlags(options) {
+    var _a, _b;
     const queuedConsent = getQueuedConsent();
     installConsentSync();
     const queuedUserToken = options.userToken ? undefined : getQueuedUserToken();
@@ -573,8 +802,9 @@ function initFeatureFlags(options) {
     if (options.reloadOnSpaNavigation !== false) {
         installSpaNavigationReload();
     }
-    const { selector, requestTimeoutMs, cacheTtlMs } = options;
-    return initializeFeatureFlags({ selector, requestTimeoutMs, cacheTtlMs }, options.projectId, currentUserToken, options.userContext);
+    const { selector, requestTimeoutMs, cacheTtlMs, ingestUrl } = options;
+    const trackingConsentAllowed = (_b = (_a = options.consent) !== null && _a !== void 0 ? _a : queuedConsent) !== null && _b !== void 0 ? _b : true;
+    return initializeFeatureFlags({ selector, requestTimeoutMs, cacheTtlMs, ingestUrl }, options.projectId, currentUserToken, options.userContext, trackingConsentAllowed);
 }
 function setUserToken(userToken) {
     currentUserToken = requireIdentity(userToken);