@coframe/sdk 1.1.9 → 1.1.10

package/README.md

@@ -40,6 +40,21 @@ await init({
 
 `init()` accepts `config` and optional `projectData`, so npm consumers do not need to manually populate `window.CFQ` first.
 
+### URL controls
+
+The npm entry uses the same browser URL controls as the script-tag and Edge
+installations:
+
+- `cf_disable` skips initialization and reveals any antiflicker state.
+- `coframe_variant_id` previews one or more comma-separated variant IDs.
+- `keep_preview_for_session=true` keeps that preview active for the tab.
+- `coframe_should_send_events=true` allows events during preview for testing.
+
+For SSR, pass the complete request URL, including its query string, as
+`currentUrl`. This is required for query-sensitive targeting and allows
+`getProjectData()` to short-circuit before any request when `cf_disable` is
+present.
+
 ### React
 
 ```tsx
@@ -60,6 +75,8 @@ export default function App({ children }) {
 ```
 
 Mount the provider once at the root of your app. It initializes the SDK on mount and keeps treatment state available to child components.
+Keep it mounted across client-side route changes; runtime commands and the SDK's
+navigation observer handle subsequent page changes without remounting it.
 
 ### Server prefetch
 
@@ -148,6 +165,10 @@ import { CoframeProvider } from '@coframe/sdk/react'
 </CoframeProvider>
 ```
 
+If your privacy policy permits treatment analytics before cookie consent, use
+`onTreatmentAppliedBulkV2WithoutConsent` instead. It has the same callback
+arguments and does not fire again when consent is later granted.
+
 Outside React, you can also register callbacks from the main entry:
 
 ```ts
@@ -159,6 +180,7 @@ import { onLog, onTreatmentApplied } from '@coframe/sdk'
 - `getProjectData()` is intended for SSR and edge runtimes that can provide a full request URL and request headers.
 - In Pages Router or Remix, per-request server loaders are the most straightforward place to call it.
 - In App Router, keep the provider mounted in a persistent shell, but be careful about request URL handling in `layout.tsx` if you need query-sensitive SSR targeting.
+- The npm runtime reveals antiflicker styles but cannot insert them early enough to protect the initial paint. Render `antiflickerCSS` from `getProjectData()` in the server document head, or place equivalent static CSS and a timeout fallback there before application content.
 
 ## Package layout
 

package/dist/pkg/cf.cjs.js

@@ -1823,6 +1823,7 @@ const waitForBody = (timeout = 10000) => {
 function revealPage() {
     document.dispatchEvent(new CustomEvent('coframe:show', {}));
     document.documentElement.style.setProperty('--cf-show', '1');
+    document.documentElement.style.setProperty('--cf-visibility', 'visible');
 }
 async function replaceVariants(variants, orgId, logger, nonce) {
     const failedReplacements = [];
@@ -3646,6 +3647,12 @@ const Coframe = {
 };
 Coframe.logger = createLogger(() => Coframe);
 async function init(options) {
+    if (typeof window !== 'undefined' &&
+        /cf_disable/.test(window.location.search)) {
+        console.warn('[Coframe] Disabled via URL parameter');
+        revealPage();
+        return;
+    }
     if (options)
         injectOptions(options);
     const gracefulExit = (msg) => {

package/dist/pkg/cf.esm.mjs

@@ -1821,6 +1821,7 @@ const waitForBody = (timeout = 10000) => {
 function revealPage() {
     document.dispatchEvent(new CustomEvent('coframe:show', {}));
     document.documentElement.style.setProperty('--cf-show', '1');
+    document.documentElement.style.setProperty('--cf-visibility', 'visible');
 }
 async function replaceVariants(variants, orgId, logger, nonce) {
     const failedReplacements = [];
@@ -3644,6 +3645,12 @@ const Coframe = {
 };
 Coframe.logger = createLogger(() => Coframe);
 async function init(options) {
+    if (typeof window !== 'undefined' &&
+        /cf_disable/.test(window.location.search)) {
+        console.warn('[Coframe] Disabled via URL parameter');
+        revealPage();
+        return;
+    }
     if (options)
         injectOptions(options);
     const gracefulExit = (msg) => {

package/dist/pkg/react.cjs.js

@@ -5,10 +5,17 @@ var sdk = require('@coframe/sdk');
 var React = require('react');
 
 const CoframeContext = React.createContext({ treatments: null });
-function CoframeProvider({ projectConfig, projectData, onTreatmentApplied: onTreatmentAppliedProp, onTreatmentAppliedBulk: onTreatmentAppliedBulkProp, onTreatmentAppliedBulkV2, onLog: onLogProp, children, }) {
+function CoframeProvider({ projectConfig, projectData, onTreatmentApplied: onTreatmentAppliedProp, onTreatmentAppliedBulk: onTreatmentAppliedBulkProp, onTreatmentAppliedBulkV2, onTreatmentAppliedBulkV2WithoutConsent, onLog: onLogProp, children, }) {
     const [treatments, setTreatments] = React.useState(null);
     React.useEffect(() => {
         var _a, _b;
+        if (/cf_disable/.test(window.location.search)) {
+            sdk.init().catch((e) => {
+                console.error('[Coframe] Error disabling SDK', e);
+            });
+            setTreatments([]);
+            return;
+        }
         sdk.onTreatmentApplied({
             callback: onTreatmentAppliedProp,
             bulkCallback: (data) => {
@@ -16,6 +23,7 @@ function CoframeProvider({ projectConfig, projectData, onTreatmentApplied: onTre
                 onTreatmentAppliedBulkProp === null || onTreatmentAppliedBulkProp === void 0 ? void 0 : onTreatmentAppliedBulkProp(data);
             },
             bulkCallbackV2: onTreatmentAppliedBulkV2,
+            bulkCallbackV2WithoutConsent: onTreatmentAppliedBulkV2WithoutConsent,
         });
         if (onLogProp) {
             sdk.onLog(onLogProp);

package/dist/pkg/react.esm.mjs

@@ -1,13 +1,20 @@
 'use client';
-import { onTreatmentApplied, onLog, init } from '@coframe/sdk';
+import { init, onTreatmentApplied, onLog } from '@coframe/sdk';
 export { init, onLog, onTreatmentApplied, setConsent, setFeatureFlag, setPageHydrated, setUserToken, trackConversion } from '@coframe/sdk';
 import React, { createContext, useState, useEffect, useContext } from 'react';
 
 const CoframeContext = createContext({ treatments: null });
-function CoframeProvider({ projectConfig, projectData, onTreatmentApplied: onTreatmentAppliedProp, onTreatmentAppliedBulk: onTreatmentAppliedBulkProp, onTreatmentAppliedBulkV2, onLog: onLogProp, children, }) {
+function CoframeProvider({ projectConfig, projectData, onTreatmentApplied: onTreatmentAppliedProp, onTreatmentAppliedBulk: onTreatmentAppliedBulkProp, onTreatmentAppliedBulkV2, onTreatmentAppliedBulkV2WithoutConsent, onLog: onLogProp, children, }) {
     const [treatments, setTreatments] = useState(null);
     useEffect(() => {
         var _a, _b;
+        if (/cf_disable/.test(window.location.search)) {
+            init().catch((e) => {
+                console.error('[Coframe] Error disabling SDK', e);
+            });
+            setTreatments([]);
+            return;
+        }
         onTreatmentApplied({
             callback: onTreatmentAppliedProp,
             bulkCallback: (data) => {
@@ -15,6 +22,7 @@ function CoframeProvider({ projectConfig, projectData, onTreatmentApplied: onTre
                 onTreatmentAppliedBulkProp === null || onTreatmentAppliedBulkProp === void 0 ? void 0 : onTreatmentAppliedBulkProp(data);
             },
             bulkCallbackV2: onTreatmentAppliedBulkV2,
+            bulkCallbackV2WithoutConsent: onTreatmentAppliedBulkV2WithoutConsent,
         });
         if (onLogProp) {
             onLog(onLogProp);

package/dist/pkg/server.cjs.js

@@ -45,14 +45,14 @@ async function fetchProjectFromEdge(projectId, currentUrl, signal, userContext,
     }
 }
 
-async function fetchAntiflickerFromEdge(projectId, currentUrl, userContext, enableElementAntiFlicker, headers) {
+async function fetchAntiflickerFromEdge(projectId, currentUrl, userContext, antiflickerMode, headers) {
     try {
         const payload = { projectId, currentUrl };
         if (userContext) {
             payload.userContext = userContext;
         }
-        if (enableElementAntiFlicker) {
-            payload.enableElementAntiFlicker = enableElementAntiFlicker;
+        if (antiflickerMode) {
+            payload.antiflickerMode = antiflickerMode;
         }
         const config = encodeURIComponent(JSON.stringify(payload));
         const edgeUrl = new URL(`${"https://edge.cofra.me"}/cf.css`);
@@ -69,6 +69,13 @@ async function fetchAntiflickerFromEdge(projectId, currentUrl, userContext, enab
     }
 }
 async function getProjectData(options) {
+    try {
+        if (/cf_disable/.test(new URL(options.currentUrl).search)) {
+            return null;
+        }
+    }
+    catch (_a) {
+    }
     const includeProject = options.includeProject !== false;
     const includeCSS = options.includeCSS !== false;
     const [projectResult, antiflickerCSS] = await Promise.all([
@@ -76,7 +83,7 @@ async function getProjectData(options) {
             ? fetchProjectFromEdge(options.projectId, options.currentUrl, undefined, options.userContext, undefined, options.headers)
             : Promise.resolve(null),
         includeCSS
-            ? fetchAntiflickerFromEdge(options.projectId, options.currentUrl, options.userContext, options.enableElementAntiFlicker, options.headers)
+            ? fetchAntiflickerFromEdge(options.projectId, options.currentUrl, options.userContext, options.antiflickerMode, options.headers)
             : Promise.resolve(null),
     ]);
     const config = {};

package/dist/pkg/server.esm.mjs

@@ -43,14 +43,14 @@ async function fetchProjectFromEdge(projectId, currentUrl, signal, userContext,
     }
 }
 
-async function fetchAntiflickerFromEdge(projectId, currentUrl, userContext, enableElementAntiFlicker, headers) {
+async function fetchAntiflickerFromEdge(projectId, currentUrl, userContext, antiflickerMode, headers) {
     try {
         const payload = { projectId, currentUrl };
         if (userContext) {
             payload.userContext = userContext;
         }
-        if (enableElementAntiFlicker) {
-            payload.enableElementAntiFlicker = enableElementAntiFlicker;
+        if (antiflickerMode) {
+            payload.antiflickerMode = antiflickerMode;
         }
         const config = encodeURIComponent(JSON.stringify(payload));
         const edgeUrl = new URL(`${"https://edge.cofra.me"}/cf.css`);
@@ -67,6 +67,13 @@ async function fetchAntiflickerFromEdge(projectId, currentUrl, userContext, enab
     }
 }
 async function getProjectData(options) {
+    try {
+        if (/cf_disable/.test(new URL(options.currentUrl).search)) {
+            return null;
+        }
+    }
+    catch (_a) {
+    }
     const includeProject = options.includeProject !== false;
     const includeCSS = options.includeCSS !== false;
     const [projectResult, antiflickerCSS] = await Promise.all([
@@ -74,7 +81,7 @@ async function getProjectData(options) {
             ? fetchProjectFromEdge(options.projectId, options.currentUrl, undefined, options.userContext, undefined, options.headers)
             : Promise.resolve(null),
         includeCSS
-            ? fetchAntiflickerFromEdge(options.projectId, options.currentUrl, options.userContext, options.enableElementAntiFlicker, options.headers)
+            ? fetchAntiflickerFromEdge(options.projectId, options.currentUrl, options.userContext, options.antiflickerMode, options.headers)
             : Promise.resolve(null),
     ]);
     const config = {};

package/dist/pkg/types/index.d.ts

@@ -230,12 +230,13 @@ type ActivationCondition = {
     allocation?: ActivationConditionAllocation;
     js_function?: string;
 };
+type AntiflickerMode = 'body' | 'include' | 'exclude';
 type CoframeConfig = {
     projectId: string;
     previewVariantId?: string;
     trackingOnly?: boolean;
     enableAntiFlickering?: boolean;
-    enableElementAntiFlicker?: boolean;
+    antiflickerMode?: AntiflickerMode;
     waitForHydration?: boolean;
     waitForCookiesEnabled?: boolean;
     waitForFeatureFlag?: boolean;
@@ -295,6 +296,7 @@ interface TreatmentAppliedHandlers {
     callback?: (data: TreatmentData) => void;
     bulkCallback?: (data: TreatmentData[]) => void;
     bulkCallbackV2?: (data: TreatmentDataV2[], rawIds: ExperimentInfo[]) => void;
+    bulkCallbackV2WithoutConsent?: (data: TreatmentDataV2[], rawIds: ExperimentInfo[]) => void;
 }
 declare function setConsent(enabled: boolean): void;
 declare function setUserToken(token: string): void;

package/dist/pkg/types/react.d.ts

@@ -233,12 +233,13 @@ type ActivationCondition = {
     allocation?: ActivationConditionAllocation;
     js_function?: string;
 };
+type AntiflickerMode = 'body' | 'include' | 'exclude';
 type CoframeConfig = {
     projectId: string;
     previewVariantId?: string;
     trackingOnly?: boolean;
     enableAntiFlickering?: boolean;
-    enableElementAntiFlicker?: boolean;
+    antiflickerMode?: AntiflickerMode;
     waitForHydration?: boolean;
     waitForCookiesEnabled?: boolean;
     waitForFeatureFlag?: boolean;
@@ -290,13 +291,14 @@ interface CoframeProviderProps {
     onTreatmentApplied?: (data: TreatmentData) => void;
     onTreatmentAppliedBulk?: (data: TreatmentData[]) => void;
     onTreatmentAppliedBulkV2?: (data: TreatmentDataV2[], rawIds: ExperimentInfo[]) => void;
+    onTreatmentAppliedBulkV2WithoutConsent?: (data: TreatmentDataV2[], rawIds: ExperimentInfo[]) => void;
     onLog?: (payload: LogPayload) => void;
     children: ReactNode;
 }
 interface CoframeContextValue {
     treatments: TreatmentData[] | null;
 }
-declare function CoframeProvider({ projectConfig, projectData, onTreatmentApplied: onTreatmentAppliedProp, onTreatmentAppliedBulk: onTreatmentAppliedBulkProp, onTreatmentAppliedBulkV2, onLog: onLogProp, children, }: CoframeProviderProps): React.FunctionComponentElement<React.ProviderProps<CoframeContextValue>>;
+declare function CoframeProvider({ projectConfig, projectData, onTreatmentApplied: onTreatmentAppliedProp, onTreatmentAppliedBulk: onTreatmentAppliedBulkProp, onTreatmentAppliedBulkV2, onTreatmentAppliedBulkV2WithoutConsent, onLog: onLogProp, children, }: CoframeProviderProps): React.FunctionComponentElement<React.ProviderProps<CoframeContextValue>>;
 declare function useCoframeTreatments(): TreatmentData[] | null;
 declare function useCoframeTreatment(experimentId: string): TreatmentData | undefined;
 declare function useCoframeVariant(experimentId: string): string | undefined;

package/dist/pkg/types/server.d.ts

@@ -196,6 +196,7 @@ type ActivationCondition = {
     allocation?: ActivationConditionAllocation;
     js_function?: string;
 };
+type AntiflickerMode = 'body' | 'include' | 'exclude';
 type BotReason = 'none' | 'cf_bot_score' | 'cf_verified_bot' | 'force_bot_param';
 type PersonalizationHeaders = {
     'x-device-type': string;
@@ -215,7 +216,7 @@ interface GetProjectDataOptions {
     currentUrl: string;
     userContext?: Record<string, unknown>;
     headers: Headers | Record<string, string>;
-    enableElementAntiFlicker?: boolean;
+    antiflickerMode?: AntiflickerMode;
     includeProject?: boolean;
     includeCSS?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coframe/sdk",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "description": "Coframe optimizes your website using generative AI to deliver maximum impact to your audience and allow your site to improve itself as you sleep. Learn more at coframe.com.",
   "main": "dist/pkg/cf.cjs.js",
   "module": "dist/pkg/cf.esm.mjs",