@digia-engage/core 2.0.0-rc.1 → 2.0.0

package/src/Digia.ts

@@ -20,12 +20,17 @@ import { nativeDigiaModule } from './NativeDigiaEngage';
 import { digiaHealthReporter, HealthEventType } from './DigiaHealthReporter';
 import { digiaGuideController } from './DigiaGuideController';
 import { digiaActionHandler } from './actionHandler';
+import uuid from 'react-native-uuid';
+import { frequencyStore } from './frequencyStore';
+import { evaluate, hasPolicy, isSessionPolicy } from './frequencyEvaluator';
 import type {
     CampaignType,
     DigiaConfig,
     DigiaDelegate,
     DigiaExperienceEvent,
     DigiaPlugin,
+    FrequencyPolicy,
+    FrequencyState,
     GuideLifecycleEvent,
     InAppPayload,
 } from './types';
@@ -41,6 +46,7 @@ interface SdkCampaign {
     campaign_key: string;
     campaign_type: CampaignType;
     templateConfig?: Record<string, unknown>;
+    frequency?: FrequencyPolicy | null;
 }
 
 class DigiaClass implements DigiaDelegate {
@@ -53,6 +59,7 @@ class DigiaClass implements DigiaDelegate {
     private readonly _activePayloads = new Map<string, InAppPayload>();
     private _engageSubscription: { remove(): void } | null = null;
     private _projectId = '';
+    private _deviceId = '';
     private _apiBaseUrl = '';
     private _logLevel: DigiaConfig['logLevel'] = 'error';
     private _fontFamily: string | undefined;
@@ -89,6 +96,8 @@ class DigiaClass implements DigiaDelegate {
             throw e;
         }
 
+        this._deviceId = await this._loadOrCreateDeviceId();
+        await frequencyStore.checkProjectId(config.projectId);
         await this._refreshCampaignStore();
     }
 
@@ -170,7 +179,7 @@ class DigiaClass implements DigiaDelegate {
     // Mirrors DigiaCEPDelegate on Android.
     // Forwards to the native DigiaCEPDelegate via the bridge.
 
-    onCampaignTriggered(payload: InAppPayload): void {
+    async onCampaignTriggered(payload: InAppPayload): Promise<void> {
         if (!this._nativeBridgeWired) {
             digiaHealthReporter.report(HealthEventType.plugin_not_registered, { campaign_key: payload.id });
         }
@@ -180,6 +189,18 @@ class DigiaClass implements DigiaDelegate {
 
         if (campaignKey) {
             const campaign = this._campaignsByKey.get(campaignKey);
+
+            if (campaign && hasPolicy(campaign.frequency)) {
+                const policy = campaign.frequency!;
+                const isSession = isSessionPolicy(policy);
+                const state = await this._getFrequencyState(campaignKey, isSession);
+                const result = evaluate(policy, state, Date.now());
+                if (!result.allow) {
+                    this._log(`frequency_capped campaign_key=${campaignKey} reason=${result.reason}`);
+                    return;
+                }
+            }
+
             if (campaign?.campaign_type === 'inline' || campaign?.campaign_type === 'survey') {
                 this._log(`${campaign.campaign_type} campaign triggered campaign_key=${campaignKey}, forwarding to native`);
                 this._activePayloads.set(payload.id, payload);
@@ -270,16 +291,21 @@ class DigiaClass implements DigiaDelegate {
         const payload = this._activePayloads.get(data.campaignId);
         if (!payload) return;
 
+        const campaignKey = this._extractCampaignKey(payload);
+
         let event: DigiaExperienceEvent;
         switch (data.type) {
             case 'impressed':
                 event = { type: 'impressed' };
+                if (campaignKey) void this._bumpFrequencyImpression(campaignKey);
                 break;
             case 'clicked':
                 event = { type: 'clicked', elementId: data.elementId };
+                if (campaignKey) void this._applyStopOn(campaignKey, 'click');
                 break;
             case 'dismissed':
                 event = { type: 'dismissed' };
+                if (campaignKey) void this._applyStopOn(campaignKey, 'dismiss');
                 this._activePayloads.delete(data.campaignId);
                 break;
             default:
@@ -299,6 +325,16 @@ class DigiaClass implements DigiaDelegate {
         const properties = this._buildGuideProperties(event, campaignId, campaignKey);
         this._plugins.forEach((p) => p.track?.(eventName, properties));
 
+        if (event.type === 'viewed') {
+            void this._bumpFrequencyImpression(campaignKey);
+        }
+        if (event.type === 'clicked' || event.type === 'completed') {
+            void this._applyStopOn(campaignKey, 'click');
+        }
+        if (event.type === 'dismissed') {
+            void this._applyStopOn(campaignKey, 'dismiss');
+        }
+
         // Notify plugins of CEP lifecycle termination (template cleanup) on exit events.
         if (event.type === 'dismissed' || event.type === 'completed') {
             const storedPayload = this._activePayloads.get(payloadId);
@@ -403,6 +439,7 @@ class DigiaClass implements DigiaDelegate {
             headers: {
                 'Content-Type': 'application/json',
                 'x-digia-project-id': this._projectId,
+                'x-digia-device-id': this._deviceId,
             },
             body: JSON.stringify(body),
         });
@@ -489,10 +526,71 @@ class DigiaClass implements DigiaDelegate {
         return { ...raw, templateType: type, steps } as TemplateConfig;
     }
 
+    // ── Device ID ────────────────────────────────────────────────────────────
+
+    private async _loadOrCreateDeviceId(): Promise<string> {
+        const DEVICE_ID_KEY = 'digia:device_id';
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const AsyncStorage = require('@react-native-async-storage/async-storage').default;
+            const stored = await AsyncStorage.getItem(DEVICE_ID_KEY);
+            if (stored) return stored;
+            const id = uuid.v4() as string;
+            await AsyncStorage.setItem(DEVICE_ID_KEY, id);
+            return id;
+        } catch {
+            return uuid.v4() as string;
+        }
+    }
+
+    // ── Frequency capping ────────────────────────────────────────────────────
+
+    private async _getFrequencyState(campaignKey: string, isSession: boolean): Promise<FrequencyState | null> {
+        return frequencyStore.get(campaignKey, isSession);
+    }
+
+    async _bumpFrequencyImpression(campaignKey: string): Promise<void> {
+        const campaign = this._campaignsByKey.get(campaignKey);
+        if (!campaign || !hasPolicy(campaign.frequency)) return;
+        const isSession = isSessionPolicy(campaign.frequency!);
+        const now = Date.now();
+        const prev = await frequencyStore.get(campaignKey, isSession);
+        const next: FrequencyState = {
+            shown_count: (prev?.shown_count ?? 0) + 1,
+            first_shown_at: prev?.first_shown_at ?? now,
+            last_shown_at: now,
+            stopped_at: prev?.stopped_at ?? null,
+            stopped_reason: prev?.stopped_reason ?? null,
+        };
+        await frequencyStore.set(campaignKey, next, isSession);
+    }
+
+    async _applyStopOn(campaignKey: string, interactionType: 'click' | 'dismiss'): Promise<void> {
+        const campaign = this._campaignsByKey.get(campaignKey);
+        const stopOn = campaign?.frequency?.stop_on;
+        if (!stopOn) return;
+        const matches =
+            stopOn === 'any_action' ||
+            stopOn === interactionType;
+        if (!matches) return;
+        const isSession = isSessionPolicy(campaign!.frequency!);
+        const prev = await frequencyStore.get(campaignKey, isSession);
+        if (prev?.stopped_at) return;
+        const now = Date.now();
+        const next: FrequencyState = {
+            shown_count: prev?.shown_count ?? 0,
+            first_shown_at: prev?.first_shown_at ?? null,
+            last_shown_at: prev?.last_shown_at ?? null,
+            stopped_at: now,
+            stopped_reason: interactionType,
+        };
+        await frequencyStore.set(campaignKey, next, isSession);
+    }
+
     private _log(message: string): void {
         if (this._logLevel !== 'verbose') return;
         // eslint-disable-next-line no-console
-        console.log(`[Digia] ${message}`);
+        // console.log(`[Digia] ${message}`);
     }
 
 }

package/src/DigiaAnchorView.tsx

@@ -5,13 +5,18 @@
  * When a SHOW_TOOLTIP or SHOW_SPOTLIGHT campaign fires, the native SDK looks up this view
  * via AnchorRegistry and uses getLocationOnScreen() for accurate pixel-perfect coordinates.
  *
+ * Also reports layout into the JS digiaAnchorRegistry so JS-rendered guides (tooltip/spotlight)
+ * can position themselves relative to this anchor.
+ *
  * Usage:
  *   <DigiaAnchorView anchorKey="pdp_add_to_cart" style={{ alignSelf: 'flex-start' }}>
  *     <TouchableOpacity ...>Add to Cart</TouchableOpacity>
  *   </DigiaAnchorView>
  */
 
-import { requireNativeComponent, type ViewProps } from 'react-native';
+import React, { useCallback, useRef } from 'react';
+import { requireNativeComponent, View, type ViewProps, type LayoutChangeEvent } from 'react-native';
+import { digiaAnchorRegistry } from './digiaAnchorRegistry';
 
 interface DigiaAnchorViewProps extends ViewProps {
     anchorKey: string;
@@ -19,4 +24,27 @@ interface DigiaAnchorViewProps extends ViewProps {
     cornerRadius?: number;
 }
 
-export const DigiaAnchorView = requireNativeComponent<DigiaAnchorViewProps>('DigiaAnchorView');
+const NativeDigiaAnchorView = requireNativeComponent<DigiaAnchorViewProps>('DigiaAnchorView');
+
+export const DigiaAnchorView = ({ anchorKey, onLayout, ...rest }: DigiaAnchorViewProps) => {
+    const viewRef = useRef<View>(null);
+
+    const handleLayout = useCallback((e: LayoutChangeEvent) => {
+        onLayout?.(e);
+        // Use measure() for absolute screen coordinates (onLayout gives relative coords)
+        viewRef.current?.measure((_x, _y, width, height, pageX, pageY) => {
+            if (width > 0 && height > 0) {
+                digiaAnchorRegistry.setLayout(anchorKey, { pageX, pageY, width, height });
+            }
+        });
+    }, [anchorKey, onLayout]);
+
+    return (
+        <NativeDigiaAnchorView
+            ref={viewRef as any}
+            anchorKey={anchorKey}
+            onLayout={handleLayout}
+            {...rest}
+        />
+    );
+};

package/src/DigiaHealthReporter.ts

@@ -36,7 +36,7 @@ export class DigiaHealthReporter {
         //     },
         //     body: JSON.stringify({ event_type: eventType, detail }),
         // }).catch(() => { /* swallow */ });
-        if (__DEV__) console.log('[DigiaHealth]', eventType, detail);
+        // if (__DEV__) console.log('[DigiaHealth]', eventType, detail);
     }
 }
 

package/src/DigiaProvider.tsx

@@ -221,7 +221,9 @@ function TooltipOverlay({
     useEffect(() => {
         setLayout(null);
         setFloatPos(null);
+        // if (__DEV__) console.log(`[Digia] guide waiting for anchor key="${step.anchorKey}"`);
         return digiaAnchorRegistry.subscribe(step.anchorKey, (l) => {
+            // if (__DEV__) console.log(`[Digia] anchor resolved key="${step.anchorKey}"`, l);
             setLayout(l);
         });
     }, [step.anchorKey]);
@@ -478,7 +480,7 @@ function SpotlightCallout({
                 middleware: [offset(gap), flip(), shift({ padding: 16 })],
             },
         ).then(({ x, y, placement }) => {
-            console.log('[Digia:spotlight] floatPos=', { x, y }, 'resolved=', placement);
+            // console.log('[Digia:spotlight] floatPos=', { x, y }, 'resolved=', placement);
             setFloatPos({ x, y });
             setResolvedPlacement(placement as string);
         });

package/src/DigiaSlotView.tsx

@@ -36,11 +36,11 @@ export function DigiaSlotView({ placementKey, style }: DigiaSlotViewProps) {
     const [contentWidth, setContentWidth] = useState<number | null>(null);
 
     useEffect(() => {
-        console.log('[DigiaSlotView:debug] mounted placementKey=' + placementKey);
+        // console.log('[DigiaSlotView:debug] mounted placementKey=' + placementKey);
         const sub = DeviceEventEmitter.addListener(
             'digiaSlotWidth',
             (data: { slotKey: string; width: number | null }) => {
-                console.log('[DigiaSlotView:debug] digiaSlotWidth event received', JSON.stringify(data), 'myKey=' + placementKey, 'match=' + (data.slotKey === placementKey));
+                // console.log('[DigiaSlotView:debug] digiaSlotWidth event received', JSON.stringify(data), 'myKey=' + placementKey, 'match=' + (data.slotKey === placementKey));
                 if (data.slotKey === placementKey) {
                     setContentWidth(data.width && data.width > 0 ? data.width : null);
                 }
@@ -53,7 +53,7 @@ export function DigiaSlotView({ placementKey, style }: DigiaSlotViewProps) {
         (event: { nativeEvent: { height: number; width: number } }) => {
             const h = event.nativeEvent.height ?? 0;
             const w = event.nativeEvent.width ?? 0;
-            console.log('[DigiaSlotView:debug] onContentSizeChange placementKey=' + placementKey + ' h=' + h + ' w=' + w);
+            // console.log('[DigiaSlotView:debug] onContentSizeChange placementKey=' + placementKey + ' h=' + h + ' w=' + w);
             setContentHeight(Math.max(0, h));
             setContentWidth(w > 0 ? w : null);
         },

package/src/frequencyEvaluator.ts

@@ -0,0 +1,57 @@
+import type { FrequencyPolicy, FrequencyState, FrequencyEvalResult } from './types';
+
+const WINDOW_MS: Record<string, number> = {
+    day:   86_400_000,
+    week:  7 * 86_400_000,
+    month: 30 * 86_400_000,
+};
+
+export const isSessionPolicy = (policy: FrequencyPolicy): boolean =>
+    policy.max_per_window?.window === 'session';
+
+/**
+ * Pure eligibility function. No side effects.
+ *
+ * Semantics for max_per_window { count, window }:
+ *   - "count" shows are allowed, measured from first_shown_at.
+ *   - Once the window duration has elapsed since first_shown_at, permanently blocked (reason: 'window').
+ *   - Once shown_count >= count, permanently blocked (reason: 'max_total').
+ *   - 'session' window is checked by the caller via in-memory state — same logic applies.
+ */
+export const evaluate = (
+    policy: FrequencyPolicy,
+    state: FrequencyState | null,
+    now: number,
+): FrequencyEvalResult => {
+    if (!state) return { allow: true, reason: null };
+
+    if (state.stopped_at !== null) {
+        return { allow: false, reason: 'stopped' };
+    }
+
+    if (policy.max_total !== null && state.shown_count >= policy.max_total) {
+        return { allow: false, reason: 'max_total' };
+    }
+
+    if (policy.max_per_window !== null) {
+        const { count, window: win } = policy.max_per_window;
+        const windowMs = WINDOW_MS[win];
+
+        if (windowMs !== undefined && state.first_shown_at !== null) {
+            if (now - state.first_shown_at > windowMs) {
+                return { allow: false, reason: 'window' };
+            }
+        }
+
+        if (state.shown_count >= count) {
+            return { allow: false, reason: 'max_total' };
+        }
+    }
+
+    return { allow: true, reason: null };
+};
+
+export const hasPolicy = (policy: FrequencyPolicy | null | undefined): policy is FrequencyPolicy =>
+    policy !== null &&
+    policy !== undefined &&
+    (policy.max_total !== null || policy.max_per_window !== null || policy.stop_on !== null);

package/src/frequencyStore.ts

@@ -0,0 +1,79 @@
+import type { FrequencyState } from './types';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const STORE_META_KEY = 'digia:freq:__meta__';
+
+type AsyncStorageAdapter = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[]>;
+    multiRemove(keys: string[]): Promise<void>;
+};
+
+let _storage: AsyncStorageAdapter | null = null;
+
+const _loadStorage = (): AsyncStorageAdapter | null => {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require('@react-native-async-storage/async-storage');
+        return mod.default ?? mod;
+    } catch {
+        console.warn('[Digia] AsyncStorage unavailable — frequency state is in-memory only (resets on app restart)');
+        return null;
+    }
+};
+
+const getStorage = (): AsyncStorageAdapter | null => {
+    if (_storage === undefined) {
+        _storage = _loadStorage();
+    }
+    return _storage;
+};
+
+const _sessionStore = new Map<string, FrequencyState>();
+
+const storeKey = (campaignKey: string) => `digia:freq:${campaignKey}`;
+
+export const frequencyStore = {
+    async checkProjectId(projectId: string): Promise<void> {
+        const storage = getStorage();
+        if (!storage) return;
+        try {
+            const stored = await storage.getItem(STORE_META_KEY);
+            const meta = stored ? (JSON.parse(stored) as { projectId: string }) : null;
+            if (meta && meta.projectId !== projectId) {
+                const keys = await storage.getAllKeys();
+                const digiaKeys = keys.filter((k) => k.startsWith('digia:freq:'));
+                if (digiaKeys.length > 0) await storage.multiRemove([...digiaKeys]);
+            }
+            await storage.setItem(STORE_META_KEY, JSON.stringify({ projectId }));
+        } catch {
+            // non-fatal
+        }
+    },
+
+    async get(campaignKey: string, isSession: boolean): Promise<FrequencyState | null> {
+        if (isSession) return _sessionStore.get(campaignKey) ?? null;
+        const storage = getStorage();
+        if (!storage) return _sessionStore.get(campaignKey) ?? null;
+        try {
+            const raw = await storage.getItem(storeKey(campaignKey));
+            return raw ? (JSON.parse(raw) as FrequencyState) : null;
+        } catch {
+            return null;
+        }
+    },
+
+    async set(campaignKey: string, state: FrequencyState, isSession: boolean): Promise<void> {
+        _sessionStore.set(campaignKey, state);
+        if (isSession) return;
+        const storage = getStorage();
+        if (!storage) return;
+        try {
+            await storage.setItem(storeKey(campaignKey), JSON.stringify(state));
+        } catch {
+            // non-fatal: state already updated in-memory above
+        }
+    },
+};

package/src/types.ts

@@ -70,7 +70,7 @@ export type GuideLifecycleEvent =
  */
 export interface DigiaDelegate {
     /** Deliver a campaign payload into the Digia rendering engine. */
-    onCampaignTriggered(payload: InAppPayload): void;
+    onCampaignTriggered(payload: InAppPayload): void | Promise<void>;
     /** Invalidate / dismiss a campaign by its ID. */
     onCampaignInvalidated(campaignId: string): void;
 }
@@ -134,6 +134,35 @@ export type InAppBrowserAdapter = {
     open: (url: string) => Promise<void>;
 };
 
+// ─── Frequency capping ────────────────────────────────────────────────────────
+
+export interface FrequencyWindow {
+    count: number;
+    window: 'session' | 'day' | 'week' | 'month';
+}
+
+export interface FrequencyPolicy {
+    max_total: number | null;
+    max_per_window: FrequencyWindow | null;
+    stop_on: 'click' | 'dismiss' | 'any_action' | null;
+    min_gap_ms?: number | null; // reserved — not evaluated in v1
+}
+
+export interface FrequencyState {
+    shown_count: number;
+    first_shown_at: number | null;      // ms timestamp — set on first impression
+    last_shown_at: number | null;       // ms timestamp — reserved for min_gap_ms
+    stopped_at: number | null;
+    stopped_reason: string | null;
+}
+
+export type FrequencySkipReason = 'max_total' | 'window' | 'stopped';
+
+export interface FrequencyEvalResult {
+    allow: boolean;
+    reason: FrequencySkipReason | null;
+}
+
 // ─── SDK init config ──────────────────────────────────────────────────────────
 
 /**