@kameleoon/javascript-sdk-core 0.0.3 → 1.0.0

package/dist/kameleoonClient.d.ts

@@ -1,102 +1,191 @@
-import Configuration from './configurations/configuration';
-import TargetingData from './targeting/targetingData';
-import Experiment from './configurations/experiment';
-import FeatureFlag from './configurations/featureFlag';
-import ExperimentConfigurationNotFound from './exceptions/experimentConfigurationNotFound';
-import FeatureConfigurationNotFound from './exceptions/featureConfigurationNotFound';
-import NotActivated from './exceptions/notActivated';
-import NotTargeted from './exceptions/notTargeted';
-import VariationConfigurationNotFound from './exceptions/variationConfigurationNotFound';
-import CredentialsNotFound from './exceptions/credentialsNotFound';
-import { CallbackInterface, DataInterface, SDKConfiguration } from './interfaces/interfaces';
-declare class KameleoonClient {
-    static readonly VISITOR_CODE_MAX_LENGTH = 255;
-    configurations?: Configuration;
-    ready: boolean;
-    readyCallbacks: CallbackInterface[];
-    minutesBetweenConfigurationUpdate: number;
-    siteCode: string;
-    targetingData: {
-        [visitorCode: string]: TargetingData[];
-    };
-    targetingDataNumberEntriesAuthorized: number;
-    unsentData: {
-        [visitorCode: string]: DataInterface[];
-    };
-    visitorDataMaximumSize: number;
-    environment: string | null;
-    private realTimeConfigurationService;
-    private handlerUpdateConfiguration;
-    private variationStorage;
-    constructor(siteCode: string, configuration?: SDKConfiguration);
-    private updateCampaignConfiguration;
-    runWhenReady: (successCallback: () => void, errorCallback: () => void, timeout: number) => void;
-    clearCallbacks: (success: boolean, errorCallback?: (() => void) | undefined) => void;
-    trackConversion: (visitorCode: string, goalId: number, revenue?: number | undefined) => void;
-    flush: (visitorCode?: string | undefined) => void;
+import { JSONType } from './campaignConfiguration';
+import { KameleoonDataType } from './kameleoonData';
+import { TrackConversionParamsType, ExperimentType, FeatureFlagType, GetFeatureFlagVariableParamsType, FeatureVariableResultType, SDKCoreParameters } from './types';
+/**
+ * @interface an interface of KameleoonClient instance
+ * */
+export interface IKameleoonClient {
+    /**
+     * @method initialize - an asynchronous method for KameleoonClient initialization by fetching Kameleoon SDK related data from server or by retrieving data from local source if data is up-to-date or update interval has not been reached
+     * @returns {Promise<boolean>} Promise resolved into boolean field indicating success or fail
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.StorageWrite` Couldn't update storage data
+     * - `KameleoonException.ClientConfiguration` Couldn't retrieve client configuration from Kameleoon Api
+     * */
+    initialize: () => Promise<boolean>;
+    /**
+     * @method addData - method for adding targeting data to the storage so that other methods could decide whether the current visitor is targeted or not. Note: userAgent data will not be stored in storage like other data, and it will be sent with every tracking request for bot filtration.
+     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
+     * @param {KameleoonDataType[]} kameleoonData - number of instances of any type of `KameleoonData`, can be added solely in array or as a sequential arguments
+     * @returns {void}
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.VisitorCodeMaxLength` The visitor code length was exceeded
+     * - `KameleoonException.StorageWrite` Couldn't update storage data
+     * - `KameleoonException.Initialization` Couldn't update storage data
+     * */
+    addData: (visitorCode: string, ...data: KameleoonDataType[]) => void;
+    /**
+     * @method triggerExperiment - triggers experiment by assigning the variation to the user with `visitorCode`, if the variation is already assigned just returns it's id. Note: returned id `0` indicates default variation.  At the same time executes `flushData` without sending extra request.
+     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
+     * @param {number} experimentId - id of experiment running for the current visitor
+     * @returns {number} associated variationId which is successfully searched/assigned
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.ExperimentConfigurationNotFound` No configuration found for provided `experimentId`
+     * - `KameleoonException.VisitorCodeMaxLength` The visitor code length was exceeded
+     * - `KameleoonException.StorageRead` Couldn't find associated experiment by provided `experimentId` and `visitorCode` inside the storage
+     * - `KameleoonException.NotTargeted` Current visitor is not targeted
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * */
     triggerExperiment: (visitorCode: string, experimentId: number) => number;
-    activateFeature: (visitorCode: string, featureIdOrName: number | string) => boolean;
-    generateRandomString: () => string;
-    obtainAsyncVisitorCode: (domain: string, defaultVisitorCode?: string | undefined) => Promise<string>;
-    obtainVisitorCode: (domain: string, defaultVisitorCode?: string | undefined) => string;
-    obtainHashDouble: (containerId: number, visitorCode: string, xpConf: Experiment | FeatureFlag) => number;
-    private getCommonSSXParameters;
-    private getDataTrackingURL;
-    private getAPIDataRequestURL;
-    private getEventsRequestURL;
-    getExperimentRegisterURL: (visitorCode: string, experimentId: number, variationId?: number | undefined, noneVariation?: boolean | undefined) => string;
-    getUnsentUsers: () => string[];
-    getUnsentData: (visitorCode: string) => DataInterface[];
-    getTargetingData: (visitorCode: string) => TargetingData[];
-    emptyUnsentData: (visitorCode: string) => void;
-    emptyTargetingData: () => void;
-    addData: (visitorCode: string, ...data: DataInterface[]) => Promise<void>;
-    checkTargeting: (visitorCode: string, campaignId: number, isFF: boolean) => boolean | null;
-    private getConditionData;
-    obtainVariationAssociatedData: (variationId: number) => Record<string | number | symbol, string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | (string | number | boolean | {
-        [x: string]: string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | (string | number | boolean | any | any)[])[])[])[])[])[])[])[])[])[])[];
-    } | any)[])[])[])[])[])[])[])[])[])[])[]>;
-    obtainFeatureVariable: (featureIdOrName: number | string, variable: string) => any;
-    retrieveDataFromRemoteSource: (key: string) => Promise<any>;
-    private _parseJsonValue;
-    private saveConfiguration;
-    private validateVisitorCode;
-    private checkSiteEnabled;
-    private checkFeatureKeyOrId;
-    private getAndClearUnsentData;
-    onUpdateConfiguration: (handler: () => void) => void;
-    private manageConfiguraitonUpdate;
-    private fireUpdateConfigurationHandler;
+    /**
+     * @method trackConversion - creates and adds `Conversion` data to the visitor with specified parameters and executes `flushData`. Note: it's a helper method for the quick and convenient conversion tracking, however creating and adding `Conversion` manually allows more flexible `Conversion` with `negative` parameter
+     * @param {TrackConversionParamsType} conversionParameters - `visitorCode`, `goalId` and `revenue` parameters for data tracking
+     * @returns {void}
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.VisitorCodeMaxLength` The visitor code length was exceeded
+     * - `KameleoonException.StorageWrite` Couldn't update storage data
+     * */
+    trackConversion: ({ visitorCode, goalId, revenue, }: TrackConversionParamsType) => void;
+    /**
+     * @method flushData - takes visitor associated kameleoon data and sends the data tracking request with collected data
+     * sent data is removed from `KameleoonClient` instance but not from the storage for correct targeting checks
+     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
+     * @returns {void}
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * */
+    flushData: (visitorCode: string) => void;
+    /**
+     * @method getExperiments - returns a list of experiments stored in the client configuration
+     * @returns {ExperimentType[]} a list of all experiments items with `id` and `name` fields
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * */
+    getExperiments: () => ExperimentType[];
+    /**
+     * @method getVisitorExperiments - returns a list of experiments that the visitor with `visitorCode` is targeted by and that are *active* for the visitor (visitor will have one of the variations allocated if the experiment will be triggered).
+     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
+     * @param {boolean | undefined} isAllocated - boolean value indicating that only experiments *allocated* for visitor will be returned. Default value is `true`
+     * @returns {ExperimentType[]} a list of all experiments items with `id` and `name` fields
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * */
+    getVisitorExperiments: (visitorCode: string, isAllocated?: boolean) => ExperimentType[];
+    /**
+     * @method getFeatureFlags - returns a list of feature flags stored in the client configuration
+     * @returns {FeatureFlagType[]} a list of all feature flags items with `id` and `key` fields
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * */
+    getFeatureFlags: () => FeatureFlagType[];
+    /**
+     * @method getVisitorFeatureFlags - returns a list of feature flags that the visitor with `visitorCode` that is targeted by and that are *active* for the visitor (visitor will have one of the variations allocated).
+     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
+     * @returns {FeatureFlagType[]} a list of all feature flags items with `id` and `key` fields
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * - `KameleoonException.NotTargeted` - Current visitor is not targeted
+     * */
+    getVisitorFeatureFlags: (visitorCode: string) => FeatureFlagType[];
+    /**
+     * @method isFeatureFlagActive - returns a boolean indicating whether the visitor with `visitorCode` has `featureKey` active for him, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request if the feature rollout rule was of type of `Experimentation`
+     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
+     * @param {string} featureKey - a unique key for feature flag
+     * @returns {boolean} a boolean indicator of whether the feature flag with `featureKey` is active for visitor with `visitorCode`
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * - `KameleoonException.FeatureFlagConfigurationNotFound` - No feature flag was found for provided `visitorCode` and `featureKey`
+     * - `KameleoonException.DataInconsistency` - Allocated variation was found but there is no feature flag with according `featureKey`.
+     * - `KameleoonException.NotTargeted` - Current visitor is not targeted
+     * */
+    isFeatureFlagActive: (visitorCode: string, featureKey: string) => boolean;
+    /**
+     * @method getFeatureFlagVariationKey - returns variation key for the visitor under `visitorCode` in the found feature flag, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request if the feature rollout rule was of type of `Experimentation`
+     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
+     * @param {string} featureKey - a unique key for feature flag
+     * @returns {string} a string containing variable key for the allocated feature flag variation for the provided visitor
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * - `KameleoonException.FeatureFlagConfigurationNotFound` - No feature flag was found for provided `visitorCode` and `featureKey`
+     * - `KameleoonException.NotTargeted` - Current visitor is not targeted
+     * */
+    getFeatureFlagVariationKey: (visitorCode: string, featureKey: string) => string;
+    /**
+     * @method getFeatureFlagVariable - returns a variable for the visitor under `visitorCode` in the found feature flag, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request if the feature rollout rule was of type of `Experimentation`
+     * @param {GetFeatureFlagVariableParamsType} parameters - an object with parameters of a type `GetFeatureFlagVariableParamsType`, see the type for details.
+     * @returns {FeatureVariableResultType} a variable object containing `type` and `value` fields, `type` can be checked against `FeatureVariableType` enum, if the `type` is `FeatureVariableType.BOOLEAN` then the `value` type will be `boolean` and so on.
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * - `KameleoonException.FeatureFlagConfigurationNotFound` - No feature flag was found for provided `visitorCode` and `featureKey`
+     * - `KameleoonException.NotTargeted` - Current visitor is not targeted
+     * - `KameleoonException.JSONParse` - Couldn't pass JSON value
+     * - `KameleoonException.NumberParse` - Couldn't pass Number value
+     * */
+    getFeatureFlagVariable: ({ visitorCode, featureKey, variableKey, }: GetFeatureFlagVariableParamsType) => FeatureVariableResultType;
+    /**
+     * @method getRemoteData - returns a data which is stored for specified siteCode on a remote Kameleoon server.
+     * @param {string} key - unique key that the data you try to get is associated with.
+     * @returns {JSONType} - promise with retrieving data for specific key.
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.RemoteData` - Couldn't retrieve data from Kameleoon server
+     * */
+    getRemoteData: (key: string) => Promise<JSONType>;
+    /**
+     * @method onConfigurationUpdate - fires a callback on client configuration update. Note: this method only works for server sent events of real time update.
+     * @param {() => void} callback - callback function with no parameters that will be called upon configuration update
+     * @returns {void}
+     * @throws `KameleoonError` with one of the following `type` s:
+     *
+     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
+     * */
+    onConfigurationUpdate: (callback: () => void) => void;
+}
+/**
+ * @class
+ * KameleoonClient - a class for creating kameleoon client instance
+ * for communicating with Kameleoon JavaScript SDK Core, when new instance is created
+ * */
+export declare class KameleoonClient implements IKameleoonClient {
+    private internalConfiguration;
+    private variationConfiguration?;
+    private campaignConfiguration?;
+    private settings;
+    private requester;
+    /**
+     * @param {SDKCoreParameters} sdkCoreParameters - parameters for initializing sdk core
+     */
+    constructor({ siteCode, configuration, internalConfiguration, }: SDKCoreParameters);
+    initialize(): Promise<boolean>;
+    addData(visitorCode: string, ...data: KameleoonDataType[]): void;
+    triggerExperiment(visitorCode: string, experimentId: number): number;
+    trackConversion({ visitorCode, goalId, revenue, }: TrackConversionParamsType): void;
+    flushData(visitorCode: string): void;
+    getExperiments(): ExperimentType[];
+    getVisitorExperiments(visitorCode: string, isActive?: boolean): ExperimentType[];
+    getFeatureFlags(): FeatureFlagType[];
+    getVisitorFeatureFlags(visitorCode: string): FeatureFlagType[];
+    getFeatureFlagVariationKey(visitorCode: string, featureKey: string): string;
+    getFeatureFlagVariable({ visitorCode, featureKey, variableKey, }: GetFeatureFlagVariableParamsType): FeatureVariableResultType;
+    isFeatureFlagActive(visitorCode: string, featureKey: string): boolean;
+    getRemoteData(key: string): Promise<JSONType>;
+    onConfigurationUpdate(callback: () => void): void;
+    private _getFeatureFlagVariation;
 }
-declare const KameleoonException: {
-    ExperimentConfigurationNotFound: typeof ExperimentConfigurationNotFound;
-    FeatureConfigurationNotFound: typeof FeatureConfigurationNotFound;
-    VariationConfigurationNotFound: typeof VariationConfigurationNotFound;
-    NotTargeted: typeof NotTargeted;
-    NotActivated: typeof NotActivated;
-    CredentialsNotFound: typeof CredentialsNotFound;
-};
-export { KameleoonClient };
-export { KameleoonException };