@coframe/sdk 1.1.24 → 1.1.26

package/README.md

@@ -51,6 +51,7 @@ await init({
     projectId: 'your-project-id',
     projectUrl: 'https://cdn.example.com/coframe/project.json',
     ingestUrl: 'https://www.example.com/ingest/v2',
+    replayScriptUrl: 'https://www.example.com/replay/latest.js',
     enableDebug: false,
   },
 })
@@ -65,11 +66,14 @@ 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.
 
+`replayScriptUrl` replaces the session replay recorder script URL. A proxy must
+forward it to `<edge>/replay/latest.js` unchanged.
+
 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`.
+Configure all three overrides when the browser must avoid the SDK-compiled
+Coframe project, ingest and replay script endpoints entirely. Debug tools
+remain controlled by `enableDebug`.
 
 ### URL controls
 

package/dist/pkg/cf.cjs.js

@@ -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) {
@@ -3231,6 +3231,20 @@ function observeUrlChanges(baseUrlMatch, onUrlChange) {
     patchHistoryMethod('replaceState');
 }
 
+const callbacks = [];
+function onEventsFlushed(callback) {
+    callbacks.push(callback);
+}
+function notifyEventsFlushed() {
+    const pendingCallbacks = callbacks.splice(0);
+    for (const callback of pendingCallbacks) {
+        try {
+            callback();
+        }
+        catch (_a) { }
+    }
+}
+
 function startSession(Coframe, cookiesEnabled, executionStartTime, personalizationHeaders, sessionContext, pageUrl = getCurrentPageUrl()) {
     const sessionPayload = [
         Coframe,
@@ -3505,6 +3519,7 @@ function setupListeners(Coframe, executionStartTime) {
             personalizationHeaders: Coframe.personalizationHeaders,
         });
         flushQueuedEvents(Coframe.projectId);
+        notifyEventsFlushed();
     }, 1);
     window.addEventListener('beforeunload', () => handleEventFlush('before_unload'));
     window.addEventListener('pagehide', () => handleEventFlush('page_hide'));
@@ -3778,7 +3793,131 @@ async function modifyPage(Coframe, configResult, projectResult, analytics) {
     setupFlushInterval(Coframe);
 }
 
+let startRequested = false;
+let replayScriptUrl;
+const COMPILED_REPLAY_SCRIPT_URL = `${"https://edge.cofra.me"}/replay/latest.js`;
+function configureReplayScriptUrl(url) {
+    replayScriptUrl = (url === null || url === void 0 ? void 0 : url.trim()) || undefined;
+}
+function createMonitoringPayload(coframe, monitoringType, metadata) {
+    return {
+        event_id: generateUUID(),
+        monitoring_type: monitoringType,
+        local_time: new Date().toISOString(),
+        project_id: coframe.projectId,
+        session_id: coframe.sessionId,
+        url: location.href,
+        org_id: coframe.orgId,
+        metadata,
+    };
+}
+function reportStartFailure(coframe, reason) {
+    try {
+        queueMonitoringEvent(coframe, createMonitoringPayload(coframe, 'replay_start_failed', { reason }));
+    }
+    catch (_a) { }
+}
+function createStartContext(coframe, settings, forceSample) {
+    return {
+        projectId: coframe.projectId,
+        ingestUrl: resolveIngestUrl("https://ingest.app.coframe.com/ingest/v2"),
+        settings,
+        forceSample,
+        getPageViewId: () => coframe.sessionId,
+        getUserToken: () => coframe.userToken,
+        getVariantIds: () => { var _a; return ((_a = coframe.experimentInfo) !== null && _a !== void 0 ? _a : []).map((experiment) => experiment.variant_id); },
+        canSend: shouldSendEvents,
+        onEventsFlushed: (callback) => {
+            if (queuedEvents.length === 0 && queuedSessions.length === 0) {
+                callback();
+            }
+            else {
+                onEventsFlushed(callback);
+            }
+        },
+        report: (type, metadata) => queueMonitoringEvent(coframe, createMonitoringPayload(coframe, type, metadata)),
+    };
+}
+function startReplayIfEnabled(coframe, project, nonce) {
+    var _a;
+    try {
+        const settings = (_a = project.settings) === null || _a === void 0 ? void 0 : _a.session_replay;
+        if ((settings === null || settings === void 0 ? void 0 : settings.enabled) !== true ||
+            typeof CompressionStream !== 'function' ||
+            !shouldSendEvents() ||
+            startRequested) {
+            return;
+        }
+        let forceSample = false;
+        try {
+            forceSample = localStorage.getItem('coframe.enableRecording') === 'true';
+        }
+        catch (_b) { }
+        const script = document.createElement('script');
+        script.id = 'coframe-replay-script';
+        script.async = true;
+        script.src = replayScriptUrl !== null && replayScriptUrl !== void 0 ? replayScriptUrl : COMPILED_REPLAY_SCRIPT_URL;
+        if (nonce)
+            script.nonce = nonce;
+        script.onload = () => {
+            try {
+                const replay = window.CoframeReplay;
+                if ((replay === null || replay === void 0 ? void 0 : replay.protocolVersion) === 1) {
+                    replay.start(createStartContext(coframe, settings, forceSample));
+                }
+                else {
+                    reportStartFailure(coframe, 'incompatible_protocol');
+                }
+            }
+            catch (error) {
+                reportStartFailure(coframe, error instanceof Error ? error.message : String(error));
+            }
+        };
+        script.onerror = () => {
+            reportStartFailure(coframe, 'script_load_failed');
+        };
+        startRequested = true;
+        document.head.appendChild(script);
+    }
+    catch (error) {
+        reportStartFailure(coframe, error instanceof Error ? error.message : String(error));
+    }
+}
+
 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;
@@ -3812,6 +3951,7 @@ async function resolveConfig(Coframe, revealPage) {
     const executionStartTime = new Date();
     Coframe.batchSize = config.batchSize || 32;
     configureIngestUrl(config.ingestUrl);
+    configureReplayScriptUrl(config.replayScriptUrl);
     const gracefulExit = (msg) => {
         console.warn(`[Coframe] ${msg}`);
         revealPage();
@@ -3832,6 +3972,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 +3990,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',
@@ -4106,6 +4262,12 @@ async function init(options) {
         return;
     const analytics = setupTracking(Coframe, projectResult, configResult.previewVariantId, configResult.executionStartTime, configResult.config.nonce, configResult.config.waitForCookiesEnabled, identity.onConsentChange);
     await modifyPage(Coframe, configResult, projectResult, analytics);
+    try {
+        startReplayIfEnabled(Coframe, projectResult.project, configResult.config.nonce);
+    }
+    catch (error) {
+        console.warn('[Coframe] Failed to start session replay', error);
+    }
 }
 Coframe.debug = {
     getSelector,

package/dist/pkg/cf.esm.mjs

@@ -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) {
@@ -3229,6 +3229,20 @@ function observeUrlChanges(baseUrlMatch, onUrlChange) {
     patchHistoryMethod('replaceState');
 }
 
+const callbacks = [];
+function onEventsFlushed(callback) {
+    callbacks.push(callback);
+}
+function notifyEventsFlushed() {
+    const pendingCallbacks = callbacks.splice(0);
+    for (const callback of pendingCallbacks) {
+        try {
+            callback();
+        }
+        catch (_a) { }
+    }
+}
+
 function startSession(Coframe, cookiesEnabled, executionStartTime, personalizationHeaders, sessionContext, pageUrl = getCurrentPageUrl()) {
     const sessionPayload = [
         Coframe,
@@ -3503,6 +3517,7 @@ function setupListeners(Coframe, executionStartTime) {
             personalizationHeaders: Coframe.personalizationHeaders,
         });
         flushQueuedEvents(Coframe.projectId);
+        notifyEventsFlushed();
     }, 1);
     window.addEventListener('beforeunload', () => handleEventFlush('before_unload'));
     window.addEventListener('pagehide', () => handleEventFlush('page_hide'));
@@ -3776,7 +3791,131 @@ async function modifyPage(Coframe, configResult, projectResult, analytics) {
     setupFlushInterval(Coframe);
 }
 
+let startRequested = false;
+let replayScriptUrl;
+const COMPILED_REPLAY_SCRIPT_URL = `${"https://edge.cofra.me"}/replay/latest.js`;
+function configureReplayScriptUrl(url) {
+    replayScriptUrl = (url === null || url === void 0 ? void 0 : url.trim()) || undefined;
+}
+function createMonitoringPayload(coframe, monitoringType, metadata) {
+    return {
+        event_id: generateUUID(),
+        monitoring_type: monitoringType,
+        local_time: new Date().toISOString(),
+        project_id: coframe.projectId,
+        session_id: coframe.sessionId,
+        url: location.href,
+        org_id: coframe.orgId,
+        metadata,
+    };
+}
+function reportStartFailure(coframe, reason) {
+    try {
+        queueMonitoringEvent(coframe, createMonitoringPayload(coframe, 'replay_start_failed', { reason }));
+    }
+    catch (_a) { }
+}
+function createStartContext(coframe, settings, forceSample) {
+    return {
+        projectId: coframe.projectId,
+        ingestUrl: resolveIngestUrl("https://ingest.app.coframe.com/ingest/v2"),
+        settings,
+        forceSample,
+        getPageViewId: () => coframe.sessionId,
+        getUserToken: () => coframe.userToken,
+        getVariantIds: () => { var _a; return ((_a = coframe.experimentInfo) !== null && _a !== void 0 ? _a : []).map((experiment) => experiment.variant_id); },
+        canSend: shouldSendEvents,
+        onEventsFlushed: (callback) => {
+            if (queuedEvents.length === 0 && queuedSessions.length === 0) {
+                callback();
+            }
+            else {
+                onEventsFlushed(callback);
+            }
+        },
+        report: (type, metadata) => queueMonitoringEvent(coframe, createMonitoringPayload(coframe, type, metadata)),
+    };
+}
+function startReplayIfEnabled(coframe, project, nonce) {
+    var _a;
+    try {
+        const settings = (_a = project.settings) === null || _a === void 0 ? void 0 : _a.session_replay;
+        if ((settings === null || settings === void 0 ? void 0 : settings.enabled) !== true ||
+            typeof CompressionStream !== 'function' ||
+            !shouldSendEvents() ||
+            startRequested) {
+            return;
+        }
+        let forceSample = false;
+        try {
+            forceSample = localStorage.getItem('coframe.enableRecording') === 'true';
+        }
+        catch (_b) { }
+        const script = document.createElement('script');
+        script.id = 'coframe-replay-script';
+        script.async = true;
+        script.src = replayScriptUrl !== null && replayScriptUrl !== void 0 ? replayScriptUrl : COMPILED_REPLAY_SCRIPT_URL;
+        if (nonce)
+            script.nonce = nonce;
+        script.onload = () => {
+            try {
+                const replay = window.CoframeReplay;
+                if ((replay === null || replay === void 0 ? void 0 : replay.protocolVersion) === 1) {
+                    replay.start(createStartContext(coframe, settings, forceSample));
+                }
+                else {
+                    reportStartFailure(coframe, 'incompatible_protocol');
+                }
+            }
+            catch (error) {
+                reportStartFailure(coframe, error instanceof Error ? error.message : String(error));
+            }
+        };
+        script.onerror = () => {
+            reportStartFailure(coframe, 'script_load_failed');
+        };
+        startRequested = true;
+        document.head.appendChild(script);
+    }
+    catch (error) {
+        reportStartFailure(coframe, error instanceof Error ? error.message : String(error));
+    }
+}
+
 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;
@@ -3810,6 +3949,7 @@ async function resolveConfig(Coframe, revealPage) {
     const executionStartTime = new Date();
     Coframe.batchSize = config.batchSize || 32;
     configureIngestUrl(config.ingestUrl);
+    configureReplayScriptUrl(config.replayScriptUrl);
     const gracefulExit = (msg) => {
         console.warn(`[Coframe] ${msg}`);
         revealPage();
@@ -3830,6 +3970,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 +3988,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',
@@ -4104,6 +4260,12 @@ async function init(options) {
         return;
     const analytics = setupTracking(Coframe, projectResult, configResult.previewVariantId, configResult.executionStartTime, configResult.config.nonce, configResult.config.waitForCookiesEnabled, identity.onConsentChange);
     await modifyPage(Coframe, configResult, projectResult, analytics);
+    try {
+        startReplayIfEnabled(Coframe, projectResult.project, configResult.config.nonce);
+    }
+    catch (error) {
+        console.warn('[Coframe] Failed to start session replay', error);
+    }
 }
 Coframe.debug = {
     getSelector,

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

@@ -74,6 +74,15 @@ type ModalTrigger = 'exit' | 'scroll' | 'enter' | 'timer';
 interface AnalyticsCallback {
     callback: string;
 }
+interface SessionReplaySettings {
+    enabled: boolean;
+    sample_rate: number;
+    mask_text_selector: string;
+    block_selector: string;
+    url_deny_patterns: string[];
+    max_session_minutes: number;
+    max_session_bytes: number;
+}
 interface TreatmentData {
     impressionId: string;
     userToken: string;
@@ -141,6 +150,7 @@ interface ProjectSettings {
     bot_cloaking_enabled?: boolean;
     bot_score_threshold?: number;
     analytics_callback?: AnalyticsCallback;
+    session_replay?: SessionReplaySettings | null;
 }
 interface Project {
     org_id: string;
@@ -252,6 +262,7 @@ type CoframeConfig = {
     currentUrl?: string;
     projectUrl?: string;
     ingestUrl?: string;
+    replayScriptUrl?: string;
     referrer?: string;
     userContext?: Record<string, unknown>;
     nonce?: string;

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

@@ -93,6 +93,15 @@ type ModalTrigger = 'exit' | 'scroll' | 'enter' | 'timer';
 interface AnalyticsCallback {
     callback: string;
 }
+interface SessionReplaySettings {
+    enabled: boolean;
+    sample_rate: number;
+    mask_text_selector: string;
+    block_selector: string;
+    url_deny_patterns: string[];
+    max_session_minutes: number;
+    max_session_bytes: number;
+}
 interface TreatmentData {
     impressionId: string;
     userToken: string;
@@ -160,6 +169,7 @@ interface ProjectSettings {
     bot_cloaking_enabled?: boolean;
     bot_score_threshold?: number;
     analytics_callback?: AnalyticsCallback;
+    session_replay?: SessionReplaySettings | null;
 }
 interface Project {
     org_id: string;
@@ -271,6 +281,7 @@ type CoframeConfig = {
     currentUrl?: string;
     projectUrl?: string;
     ingestUrl?: string;
+    replayScriptUrl?: string;
     referrer?: string;
     userContext?: Record<string, unknown>;
     nonce?: string;

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

@@ -74,6 +74,15 @@ type ModalTrigger = 'exit' | 'scroll' | 'enter' | 'timer';
 interface AnalyticsCallback {
     callback: string;
 }
+interface SessionReplaySettings {
+    enabled: boolean;
+    sample_rate: number;
+    mask_text_selector: string;
+    block_selector: string;
+    url_deny_patterns: string[];
+    max_session_minutes: number;
+    max_session_bytes: number;
+}
 interface Audience {
     selector: ActivationCondition;
 }
@@ -107,6 +116,7 @@ interface ProjectSettings {
     bot_cloaking_enabled?: boolean;
     bot_score_threshold?: number;
     analytics_callback?: AnalyticsCallback;
+    session_replay?: SessionReplaySettings | null;
 }
 interface Project {
     org_id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coframe/sdk",
-  "version": "1.1.24",
+  "version": "1.1.26",
   "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",
@@ -98,6 +98,8 @@
     }
   },
   "dependencies": {
+    "@rrweb/record": "2.1.0",
+    "fflate": "0.8.3",
     "typescript": "^6.0.2"
   },
   "devDependencies": {
@@ -136,4 +138,4 @@
     "ua-parser-js": "^2.0.10"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
-}
+}