@flagship.io/react-sdk 5.1.1 → 5.2.0

package/dist/edge/setupTests.js

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/jest-globals';

package/dist/edge/src/FSFlag.js

@@ -0,0 +1,59 @@
+import { Flagship, FSFlagMetadata, FSFlagStatus } from './deps.js';
+import { GET_FLAG_CAST_ERROR, noVisitorMessage } from './constants.js';
+import { hasSameType, logInfo, logWarn, sprintf } from './utils.js';
+export class FSFlag {
+    key;
+    flag;
+    constructor(key, state) {
+        const flagsData = state.flags;
+        if (!state.hasVisitorData) {
+            logWarn(Flagship.getConfig(), noVisitorMessage, 'GetFlag');
+        }
+        this.key = key;
+        this.flag = flagsData?.get(key);
+    }
+    getValue(defaultValue) {
+        if (!this.flag) {
+            return defaultValue;
+        }
+        if (this.flag.value === null || this.flag.value === undefined) {
+            return defaultValue;
+        }
+        if (defaultValue !== null && defaultValue !== undefined && !hasSameType(this.flag.value, defaultValue)) {
+            logInfo(Flagship.getConfig(), sprintf(GET_FLAG_CAST_ERROR, this.key), 'getValue');
+            return defaultValue;
+        }
+        return this.flag.value;
+    }
+    exists() {
+        if (!this.flag) {
+            return false;
+        }
+        return !!(this.flag.campaignId && this.flag.variationId && this.flag.variationGroupId);
+    }
+    async visitorExposed() {
+        // do nothing
+    }
+    get metadata() {
+        if (!this.flag) {
+            return FSFlagMetadata.Empty();
+        }
+        return new FSFlagMetadata({
+            campaignId: this.flag.campaignId,
+            campaignName: this.flag.campaignName,
+            variationGroupId: this.flag.variationGroupId,
+            variationGroupName: this.flag.variationGroupName,
+            variationId: this.flag.variationId,
+            variationName: this.flag.variationName,
+            isReference: !!this.flag.isReference,
+            campaignType: this.flag.campaignType,
+            slug: this.flag.slug
+        });
+    }
+    get status() {
+        if (!this.exists()) {
+            return FSFlagStatus.NOT_FOUND;
+        }
+        return FSFlagStatus.FETCHED;
+    }
+}

package/dist/edge/src/FlagshipContext.js

@@ -0,0 +1,8 @@
+'use client';
+import { createContext } from 'react';
+export const initStat = {
+    isInitializing: true
+};
+export const FlagshipContext = createContext({
+    state: { ...initStat }
+});

package/dist/edge/src/FlagshipHooks.js

@@ -0,0 +1,152 @@
+'use client';
+import { useCallback, useContext, useMemo } from 'react';
+import { Flagship, FSFlagCollection } from './deps.js';
+import { noVisitorMessage } from './constants.js';
+import { FlagshipContext } from './FlagshipContext.js';
+import { FSFlag } from './FSFlag.js';
+import { deepClone, hasContextChanged, logError, logWarn } from './utils.js';
+/**
+ * This hook returns a flag object by its key. If no flag match the given key an empty flag will be returned.
+ * @param key
+ * @param defaultValue
+ * @returns
+ */
+export const useFsFlag = (key) => {
+    const { state } = useContext(FlagshipContext);
+    const { visitor } = state;
+    if (!visitor) {
+        return new FSFlag(key, state);
+    }
+    return visitor.getFlag(key);
+};
+const handleContextChange = (param) => {
+    const { updateFunction, functionName, visitor, config } = param;
+    if (!visitor) {
+        logError(config, noVisitorMessage, functionName);
+        return;
+    }
+    const originalContextClone = deepClone(visitor.context);
+    updateFunction();
+    const updatedContext = visitor.context;
+    if (hasContextChanged(originalContextClone, updatedContext)) {
+        visitor.fetchFlags();
+    }
+};
+export const useFlagship = () => {
+    const { state } = useContext(FlagshipContext);
+    const { visitor, config } = state;
+    const fsUpdateContext = useCallback((context) => {
+        handleContextChange({
+            config,
+            visitor,
+            updateFunction: () => visitor?.updateContext(context),
+            functionName: 'updateContext'
+        });
+    }, [visitor]);
+    const fsClearContext = useCallback(() => {
+        handleContextChange({
+            config,
+            visitor,
+            updateFunction: () => visitor?.clearContext(),
+            functionName: 'cleanContext'
+        });
+    }, [visitor]);
+    const fsAuthenticate = useCallback((visitorId) => {
+        const functionName = 'authenticate';
+        if (!visitor) {
+            logError(config, noVisitorMessage, functionName);
+            return;
+        }
+        const originalVisitorId = visitor.visitorId;
+        visitor.authenticate(visitorId);
+        if (originalVisitorId !== visitorId) {
+            visitor.fetchFlags();
+        }
+    }, [visitor]);
+    const fsUnauthenticate = useCallback(() => {
+        const functionName = 'unauthenticate';
+        if (!visitor) {
+            logError(config, noVisitorMessage, functionName);
+            return;
+        }
+        const originalVisitorId = visitor.visitorId;
+        visitor.unauthenticate();
+        if (originalVisitorId !== visitor.visitorId) {
+            visitor.fetchFlags();
+        }
+    }, [visitor]);
+    const fsSendHit = useCallback((hit) => {
+        const functionName = 'sendHit';
+        if (!visitor) {
+            logError(config, noVisitorMessage, functionName);
+            return Promise.resolve();
+        }
+        if (Array.isArray(hit)) {
+            return visitor.sendHits(hit);
+        }
+        return visitor.sendHit(hit);
+    }, [visitor]);
+    const getFlag = useCallback((key) => {
+        if (!visitor) {
+            return new FSFlag(key, state);
+        }
+        return visitor.getFlag(key);
+    }, [visitor]);
+    const fetchFlags = useCallback(async () => {
+        if (!visitor) {
+            logWarn(config, noVisitorMessage, 'fetchFlags');
+            return Promise.resolve();
+        }
+        return visitor.fetchFlags();
+    }, [visitor]);
+    const setConsent = useCallback((hasConsented) => {
+        if (!visitor) {
+            logWarn(config, noVisitorMessage, 'setConsent');
+            return;
+        }
+        visitor.setConsent(hasConsented);
+    }, [visitor]);
+    const close = useCallback(() => {
+        return Flagship.close();
+    }, []);
+    const getFlags = useCallback(() => {
+        if (!visitor) {
+            const flags = new Map();
+            state.flags?.forEach((flag, key) => {
+                flags.set(key, new FSFlag(key, state));
+            });
+            return new FSFlagCollection({ flags });
+        }
+        return visitor.getFlags();
+    }, [visitor]);
+    const collectEAIEventsAsync = useCallback(async (...args) => {
+        if (!visitor) {
+            return;
+        }
+        return visitor.collectEAIEventsAsync(...args);
+    }, [visitor]);
+    return useMemo(() => ({
+        visitorId: visitor?.visitorId,
+        anonymousId: visitor?.anonymousId,
+        context: { ...visitor?.context },
+        hasConsented: visitor?.hasConsented,
+        sdkStatus: Flagship.getStatus(),
+        flagsStatus: visitor?.flagsStatus,
+        setConsent,
+        updateContext: fsUpdateContext,
+        clearContext: fsClearContext,
+        authenticate: fsAuthenticate,
+        unauthenticate: fsUnauthenticate,
+        sendHits: fsSendHit,
+        getFlag,
+        fetchFlags,
+        close,
+        getFlags,
+        collectEAIEventsAsync
+    }), [visitor, setConsent,
+        fsUpdateContext,
+        fsClearContext, fsAuthenticate, fsUnauthenticate,
+        fsSendHit, getFlag, fetchFlags, close,
+        getFlags,
+        collectEAIEventsAsync]);
+};

package/dist/edge/src/FlagshipProvider.js

@@ -0,0 +1,159 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useState, useRef, useEffect } from "react";
+import { Flagship, DecisionMode, FSSdkStatus } from "./deps.js";
+import { FlagshipContext, initStat } from "./FlagshipContext.js";
+import { INTERNAL_EVENTS } from "./internalType.js";
+import { version as SDK_VERSION } from "./sdkVersion.js";
+import { useNonInitialEffect, logError, extractFlagsMap } from "./utils.js";
+export function FlagshipProvider({ children, envId, apiKey, decisionMode = DecisionMode.DECISION_API, visitorData, loadingComponent, onSdkStatusChanged, onBucketingUpdated, initialCampaigns, initialFlagsData, fetchFlagsOnBucketingUpdated, hitDeduplicationTime = 2, fetchNow = true, language = 1, sdkVersion = SDK_VERSION, onFlagsStatusChanged, shouldSaveInstance, ...props }) {
+    const flags = extractFlagsMap(initialFlagsData, initialCampaigns);
+    const [state, setState] = useState({
+        ...initStat,
+        flags,
+        hasVisitorData: !!visitorData,
+    });
+    const [lastModified, setLastModified] = useState();
+    const stateRef = useRef();
+    stateRef.current = state;
+    const visitorDataRef = useRef(visitorData);
+    // #region functions
+    const onBucketingLastModified = (lastUpdate) => {
+        if (onBucketingUpdated) {
+            onBucketingUpdated(lastUpdate);
+        }
+        setLastModified(lastUpdate);
+    };
+    const statusChanged = (status) => {
+        if (onSdkStatusChanged) {
+            onSdkStatusChanged(status);
+        }
+        switch (status) {
+            case FSSdkStatus.SDK_PANIC:
+            case FSSdkStatus.SDK_INITIALIZED:
+                createVisitor();
+                break;
+            case FSSdkStatus.SDK_NOT_INITIALIZED:
+                setState((prev) => ({
+                    ...prev,
+                    config: Flagship.getConfig(),
+                    isInitializing: false,
+                }));
+                break;
+        }
+    };
+    const initSdk = () => {
+        Flagship.start(envId, apiKey, {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            decisionMode: decisionMode,
+            fetchNow,
+            onSdkStatusChanged: statusChanged,
+            onBucketingUpdated: onBucketingLastModified,
+            hitDeduplicationTime,
+            language,
+            sdkVersion,
+            ...props,
+        });
+    };
+    function initializeState(param) {
+        setState((currentState) => ({
+            ...currentState,
+            visitor: param.fsVisitor,
+            config: Flagship.getConfig(),
+            isInitializing: false,
+            hasVisitorData: !!visitorData,
+        }));
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const onVisitorReady = (fsVisitor, error) => {
+        if (error) {
+            logError(Flagship.getConfig(), error.message || error, "onReady");
+        }
+        initializeState({ fsVisitor });
+    };
+    const createVisitor = () => {
+        if (!visitorDataRef.current) {
+            return;
+        }
+        const fsVisitor = Flagship.newVisitor({
+            visitorId: visitorDataRef.current.id,
+            context: visitorDataRef.current.context,
+            isAuthenticated: visitorDataRef.current.isAuthenticated,
+            hasConsented: visitorDataRef.current.hasConsented,
+            initialCampaigns,
+            initialFlagsData,
+            onFlagsStatusChanged,
+            shouldSaveInstance,
+        });
+        fsVisitor?.on("ready", (error) => {
+            onVisitorReady(fsVisitor, error);
+        });
+        if (!fetchNow) {
+            initializeState({ fsVisitor });
+        }
+    };
+    function updateVisitor() {
+        if (!visitorDataRef.current ||
+            Flagship.getStatus() !== FSSdkStatus.SDK_INITIALIZED) {
+            return;
+        }
+        if (!state.visitor ||
+            (state.visitor.visitorId !== visitorDataRef.current.id &&
+                (!visitorDataRef.current.isAuthenticated ||
+                    (visitorDataRef.current.isAuthenticated &&
+                        state.visitor.anonymousId)))) {
+            state.visitor?.cleanup();
+            createVisitor();
+            return;
+        }
+        if (visitorDataRef.current.hasConsented !== state.visitor.hasConsented) {
+            state.visitor.setConsent(visitorDataRef.current.hasConsented ?? true);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        state.visitor.updateContext(visitorDataRef.current.context);
+        if (!state.visitor.anonymousId && visitorDataRef.current.isAuthenticated) {
+            state.visitor.authenticate(visitorDataRef.current.id);
+        }
+        if (state.visitor.anonymousId && !visitorDataRef.current.isAuthenticated) {
+            state.visitor.unauthenticate();
+        }
+        state.visitor.fetchFlags();
+    }
+    // #endregion
+    useNonInitialEffect(() => {
+        if (fetchFlagsOnBucketingUpdated) {
+            state.visitor?.fetchFlags();
+        }
+    }, [lastModified]);
+    useNonInitialEffect(() => {
+        visitorDataRef.current = visitorData;
+        updateVisitor();
+    }, [JSON.stringify(visitorData)]);
+    useEffect(() => {
+        initSdk();
+    }, [envId, apiKey, decisionMode]);
+    const handleDisplay = () => {
+        const isFirstInit = !state.visitor;
+        if (state.isInitializing && loadingComponent && isFirstInit && fetchNow) {
+            return _jsx(_Fragment, { children: loadingComponent });
+        }
+        return _jsx(_Fragment, { children: children });
+    };
+    useEffect(() => {
+        window?.addEventListener?.(INTERNAL_EVENTS.FsTriggerRendering, onVariationsForced);
+        return () => window?.removeEventListener?.(INTERNAL_EVENTS.FsTriggerRendering, onVariationsForced);
+    }, [state.config?.isQAModeEnabled]);
+    const onVariationsForced = (e) => {
+        const { detail } = e;
+        if (detail.forcedReFetchFlags) {
+            stateRef.current?.visitor?.fetchFlags();
+        }
+        else {
+            setState((state) => ({
+                ...state,
+                toggleForcedVariations: !state.toggleForcedVariations,
+            }));
+        }
+    };
+    return (_jsx(FlagshipContext.Provider, { value: { state, setState }, children: handleDisplay() }));
+}

package/dist/edge/src/FlagshipProviderSSR.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flagship, DecisionMode, FSSdkStatus } from "./deps.js";
+import { FlagshipProvider } from "./FlagshipProvider.js";
+import { version as SDK_VERSION } from "./sdkVersion.js";
+async function initFlagship({ envId, apiKey, config, }) {
+    if (Flagship.getStatus() !== FSSdkStatus.SDK_NOT_INITIALIZED) {
+        return Flagship;
+    }
+    await Flagship.start(envId, apiKey, {
+        ...config,
+        fetchNow: false,
+        sdkVersion: SDK_VERSION,
+    });
+    return Flagship;
+}
+/**
+ * FlagshipProviderSSR is a server-side rendering component for Flagship.
+ * It initializes the Flagship SDK and provides the necessary context for rendering.
+ * This component is designed to be used in server-side environments where you need to fetch and provide
+ * Flagship data before rendering the React application.
+ * @returns
+ */
+export async function FlagshipProviderSSR({ children, envId, apiKey, decisionMode = DecisionMode.DECISION_API, visitorData, loadingComponent, onSdkStatusChanged, onBucketingUpdated, fetchFlagsOnBucketingUpdated, hitDeduplicationTime = 2, fetchNow = false, onFlagsStatusChanged, shouldSaveInstance, ...props }) {
+    const language = 1;
+    const fs = await initFlagship({
+        envId,
+        apiKey,
+        config: {
+            ...props,
+            decisionMode: decisionMode,
+            initialBucketing: props.initialBucketing,
+            hitDeduplicationTime,
+            language,
+        },
+    });
+    let initialFlagsData = props.initialFlagsData;
+    if (!props.initialFlagsData && !props.initialCampaigns) {
+        const visitor = fs.newVisitor({
+            visitorId: visitorData?.id,
+            context: visitorData?.context,
+            isAuthenticated: visitorData?.isAuthenticated,
+            hasConsented: visitorData?.hasConsented,
+            onFlagsStatusChanged,
+            shouldSaveInstance,
+        });
+        await visitor.fetchFlags();
+        initialFlagsData = visitor.getFlags().toJSON();
+    }
+    return (_jsx(FlagshipProvider, { envId: envId, apiKey: apiKey, decisionMode: decisionMode, visitorData: visitorData, loadingComponent: loadingComponent, onSdkStatusChanged: onSdkStatusChanged, onBucketingUpdated: onBucketingUpdated, initialFlagsData: initialFlagsData, fetchFlagsOnBucketingUpdated: fetchFlagsOnBucketingUpdated, hitDeduplicationTime: hitDeduplicationTime, fetchNow: fetchNow, language: language, sdkVersion: SDK_VERSION, onFlagsStatusChanged: onFlagsStatusChanged, shouldSaveInstance: shouldSaveInstance, ...props, children: children }));
+}

package/dist/edge/src/constants.js

@@ -0,0 +1,4 @@
+export const noVisitorMessage = 'flagship Visitor not initialized.';
+export const noVisitorDefault = 'fsVisitor not initialized, returns default value';
+export const GET_FLAG_CAST_ERROR = 'Flag for key {0} has a different type. Default value is returned.';
+export const GET_METADATA_CAST_ERROR = 'Flag for key {0} has a different type with defaultValue, an empty metadata object is returned';

package/dist/edge/src/deps.js

@@ -0,0 +1 @@
+export * from '@flagship.io/js-sdk/dist/edge.js';

package/dist/edge/src/index.js

@@ -0,0 +1,7 @@
+import { FlagshipProvider } from "./FlagshipProvider.js";
+export * from "./deps.js";
+export * from "./FlagshipHooks.js";
+export * from "./type.js";
+export { FlagshipProvider } from "./FlagshipProvider.js";
+export { FlagshipProviderSSR } from "./FlagshipProviderSSR.js";
+export default FlagshipProvider;

package/dist/edge/src/internalType.js

@@ -0,0 +1,4 @@
+export var INTERNAL_EVENTS;
+(function (INTERNAL_EVENTS) {
+    INTERNAL_EVENTS["FsTriggerRendering"] = "FS_TRIGGER_RENDERING";
+})(INTERNAL_EVENTS || (INTERNAL_EVENTS = {}));

package/dist/edge/src/sdkVersion.js

@@ -0,0 +1,2 @@
+// Generated by genversion.
+export const version = '5.2.0';

package/dist/edge/src/type.js

@@ -0,0 +1 @@
+export {};

package/dist/edge/src/utils.js

@@ -0,0 +1,154 @@
+'use client';
+import { useEffect, useRef } from 'react';
+import { Flagship, LogLevel } from './deps.js';
+export function logError(config, message, tag) {
+    if (!config || !config.logLevel || config.logLevel < LogLevel.ERROR) {
+        return;
+    }
+    if (typeof config.onLog === 'function') {
+        config.onLog(LogLevel.ERROR, tag, message);
+    }
+    if (config.logManager && typeof config.logManager.error === 'function') {
+        config.logManager.error(message, tag);
+    }
+}
+export function logInfo(config, message, tag) {
+    if (!config || !config.logLevel || config.logLevel < LogLevel.INFO) {
+        return;
+    }
+    if (typeof config.onLog === 'function') {
+        config.onLog(LogLevel.INFO, tag, message);
+    }
+    if (config.logManager && typeof config.logManager.info === 'function') {
+        config.logManager.info(message, tag);
+    }
+}
+export function logWarn(config, message, tag) {
+    if (!config || !config.logLevel || config.logLevel < LogLevel.WARNING) {
+        return;
+    }
+    if (typeof config.onLog === 'function') {
+        config.onLog(LogLevel.WARNING, tag, message);
+    }
+    if (config.logManager && typeof config.logManager.warning === 'function') {
+        config.logManager.warning(message, tag);
+    }
+}
+export const getFlagsFromCampaigns = (campaigns) => {
+    const flags = new Map();
+    if (!campaigns || !Array.isArray(campaigns)) {
+        return flags;
+    }
+    campaigns.forEach((campaign) => {
+        const object = campaign.variation.modifications.value;
+        for (const key in object) {
+            const value = object[key];
+            flags.set(key, {
+                key,
+                campaignId: campaign.id,
+                campaignName: campaign.name || '',
+                variationGroupId: campaign.variationGroupId,
+                variationGroupName: campaign.variationGroupName || '',
+                variationId: campaign.variation.id,
+                variationName: campaign.variation.name || '',
+                isReference: campaign.variation.reference,
+                slug: campaign.slug || '',
+                value
+            });
+        }
+    });
+    return flags;
+};
+export function uuidV4() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (char) {
+        const rand = (Math.random() * 16) | 0;
+        const value = char === 'x' ? rand : (rand & 0x3) | 0x8;
+        return value.toString(16);
+    });
+}
+export function useNonInitialEffect(effect, deps) {
+    const initialRender = useRef(true);
+    useEffect(() => {
+        if (initialRender.current) {
+            initialRender.current = false;
+            return;
+        }
+        if (typeof effect === 'function') {
+            return effect();
+        }
+    }, deps);
+}
+export function hasSameType(flagValue, defaultValue) {
+    if (typeof flagValue !== typeof defaultValue) {
+        return false;
+    }
+    if (typeof flagValue === 'object' && typeof defaultValue === 'object' &&
+        Array.isArray(flagValue) !== Array.isArray(defaultValue)) {
+        return false;
+    }
+    return true;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function sprintf(format, ...value) {
+    let formatted = format;
+    for (let i = 0; i < value.length; i++) {
+        const element = value[i];
+        formatted = formatted.replace(new RegExp(`\\{${i}\\}`, 'g'), element);
+    }
+    return formatted;
+}
+export function hexToValue(hex, config) {
+    if (typeof hex !== 'string') {
+        logError(config, `Invalid hex string: ${hex}`, 'hexToValue');
+        return null;
+    }
+    let jsonString = '';
+    for (let i = 0; i < hex.length; i += 2) {
+        const hexChar = hex.slice(i, i + 2);
+        const charCode = parseInt(hexChar, 16);
+        if (isNaN(charCode)) {
+            logError(config, `Invalid hex character: ${hexChar}`, 'hexToValue');
+            return null;
+        }
+        jsonString += String.fromCharCode(charCode);
+    }
+    try {
+        const value = JSON.parse(jsonString);
+        return value;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }
+    catch (error) {
+        logError(config, `Error while parsing JSON: ${error?.message}`, 'hexToValue');
+        return null;
+    }
+}
+export function extractFlagsMap(initialFlagsData, initialCampaigns) {
+    let flags = new Map();
+    if (Array.isArray(initialFlagsData)) {
+        initialFlagsData.forEach((flag) => {
+            flags.set(flag.key, {
+                key: flag.key,
+                campaignId: flag.campaignId,
+                campaignName: flag.campaignName,
+                variationGroupId: flag.variationGroupId,
+                variationGroupName: flag.variationGroupName,
+                variationId: flag.variationId,
+                variationName: flag.variationName,
+                isReference: flag.isReference,
+                campaignType: flag.campaignType,
+                slug: flag.slug,
+                value: hexToValue(flag.hex, Flagship.getConfig())?.v
+            });
+        });
+    }
+    else if (initialCampaigns) {
+        flags = getFlagsFromCampaigns(initialCampaigns);
+    }
+    return flags;
+}
+export function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+export function hasContextChanged(original, updated) {
+    return JSON.stringify(original) !== JSON.stringify(updated);
+}