@kameleoon/javascript-sdk-core/dist/types.d.ts

Kameleoon JS SDK Core

import { ClientConfigurationDataType, JSONType, RuleType } from './clientConfiguration/types';
import { IExternalEventSource } from './eventSource';
import { IExternalRequester, IUrlProvider, RequestType } from './requester';
import { IExternalStorage } from './storage';
import { IExternalPRNG, VisitorDataFiltersType } from './utilities';
import { IVisitorCodeManager } from './visitorCodeManager';
import { IExternalLogger } from './logging';
import { FeatureFlagType as ConfigFeatureFlagType } from './clientConfiguration/types';
import { Environment, ExternalPackageInfoType } from './sdkInfoTypes';
import { CustomData, DataManager } from './kameleoonData';
/**
 * @param {number} updateInterval - update interval in _minutes_ for sdk configuration, minimum value is 1 minute
 * @defaultvalue 60
 *
 * @param {Environment | string | undefined} environment - feature flag environment.
 * @defaultvalue Environment.Production
 *
 * @param {number | undefined} targetingDataCleanupInterval - interval in _minutes_ for cleaning up targeting data, minimum value is 1 minute
 * Note: if not specified, default value will be used
 * @defaultvalue
 * - JavaScript SDK: `undefined` (no cleanup)
 * - React/React Native SDK: `undefined` (no cleanup)
 * - NodeJS SDK: `30`
 *
 * @param {string | undefined} cookieDomain - domain which cookie which Kameleoon visitor code belongs to
 * @param {string | undefined} networkDomain - custom domain to be used in place of all requests URL, domain format is `example.com`, if the format is incorrect, default Kameleoon domain will be used
 * @param {number | undefined} requestTimeout - timeout in _milliseconds_ for requests
 * @defaultvalue `10_000` (10 seconds)
 * @param {number | undefined} trackingInterval - interval in _milliseconds_ for performing background tracking requests, must be a value between `100` to `1_000` milliseconds
 * @defaultvalue `1_000` (1 second)
 * @param {string | undefined} defaultDataFile - json string containing default configuration data, used to initialize the SDK when no data is available in the storage or when the data is not up-to-date
 * @defaultvalue `undefined` (no default data file)
 * */
export type SDKConfigurationType = {
    updateInterval?: number;
    environment?: Environment | string;
    targetingDataCleanupInterval?: number;
    requestTimeout?: number;
    networkDomain?: string;
    cookieDomain?: string;
    trackingInterval?: number;
    defaultDataFile?: string;
};
/**
 * @param {string} urlProvider - main source for all URLs used in the SDK
 * */
export type DependenciesType = {
    urlProvider?: IUrlProvider;
};
/**
 * @param {string} siteCode - client's siteCode defined on Kameleoon platform
 * @param {Partial<SDKConfigurationType>} configuration - client's configuration
 * @param {InternalSDKConfigurationType} internalConfiguration - internal configuration for sdk core to be initialized with certain parameters to certain type of JavaScript SDK
 * @param {DependenciesType | undefined} dependencies - internal dependencies meant primarily for testing purposes
 * @param {boolean | undefined} stubMode - When set to true, the client will operate in stub mode and perform no operations. In this mode, all method calls become no-ops, ensuring that no external actions or side effects occur.
 * */
export type SDKCoreParameters = {
    siteCode: string;
    internalConfiguration: InternalSDKConfigurationType;
    configuration?: Partial<SDKConfigurationType>;
    dependencies?: DependenciesType;
    stubMode?: boolean;
};
/**
 * @param {ExternalPackageInfoType} packageInfo - external package info, used to get package version and name
 * @param {IExternalPRNG | undefined} prng - external PRNG implementation
 * */
export type InternalsType = {
    packageInfo: ExternalPackageInfoType;
    prng?: IExternalPRNG;
};
/**
 * @param {IExternalStorage | undefined} externalStorage - external file system storage implemented outside client initialization
 * @param {IExternalEventSourceConstructor | undefined} externalEventSource - constructor for building external event source implementation
 * @param {ExternalPackageInfoType} externalPackageInfo - external package info, used to get package version and name
 * @param {IExternalRequester} externalRequester - external requester , used to track or get data
 * @param {IVisitorCodeManager} externalVisitorCodeManager - external visitor code manager, used to get or generate visitor code
 * @param {IExternalLogger | undefined} logger - external logger implementation
 * */
export type ExternalsType = {
    externalStorage: IExternalStorage;
    externalEventSource: IExternalEventSource;
    externalVisitorCodeManager: IVisitorCodeManager;
    externalPackageInfo: ExternalPackageInfoType;
    externalRequester: IExternalRequester;
    externalPRNG: IExternalPRNG;
    externalLogger?: IExternalLogger;
};
/**
 * @param {boolean} useAbortController - a flag to enable or disable usage of `AbortController` for requests allowing for `requestTimeout` to be respected
 * */
export type InternalSettingsType = {
    useAbortController: boolean;
};
/**
 * @param {ExternalsType} externals - external dependencies for the SDK
 * @param {InternalSettingsType} settings - internal settings for the SDK
 * */
export type InternalSDKConfigurationType = {
    externals: ExternalsType & InternalDependencies;
    settings: InternalSettingsType;
};
export type InternalDependencies = {
    customDataManager?: DataManager;
};
/**
 * @readonly
 * @enum {string} an Enum containing all possible variants of feature variable types
 * */
export declare enum VariableType {
    BOOLEAN = "BOOLEAN",
    NUMBER = "NUMBER",
    STRING = "STRING",
    JSON = "JSON",
    JS = "JS",
    CSS = "CSS"
}
/**
 * @readonly
 * @enum {string} an Enum containing all possible variants for data status
 * */
export declare enum TrackingStatus {
    Sent = "sent",
    Unsent = "unsent",
    Pending = "pending"
}
export type BooleanVariableType = {
    key: string;
    type: VariableType.BOOLEAN;
    value: boolean;
};
export type NumberVariableType = {
    key: string;
    type: VariableType.NUMBER;
    value: number;
};
export type StringVariableType = {
    key: string;
    type: VariableType.STRING;
    value: string;
};
export type JSONVariableType = {
    key: string;
    type: VariableType.JSON;
    value: JSONType;
};
export type JSVariableType = {
    key: string;
    type: VariableType.JS;
    value: string;
};
export type CSSVariableType = {
    key: string;
    type: VariableType.CSS;
    value: string;
};
/**
 * @type `FeatureVariableResultType` - tuple of possible feature variable result types, each possible variation is an object containing `key`, `type` and `value` fields, `type` can be checked against `VariableType` enum, if the `type` is `VariableType.BOOLEAN` then the `value` type will be `boolean` and so on.
 * */
export type FeatureVariableResultType = BooleanVariableType | NumberVariableType | JSVariableType | CSSVariableType | StringVariableType | JSONVariableType;
/**
 * @type `FeatureFlagVariableType` - tuple of possible feature variable result types, each possible variation is an object containing `type` and `value` fields, `type` can be checked against `VariableType` enum, if the `type` is `VariableType.BOOLEAN` then the `value` type will be `boolean` and so on.
 * */
export type FeatureFlagVariableType = Omit<FeatureVariableResultType, 'key'>;
/**
 * @readonly
 * @enum {number} a helper Enum for getting milliseconds for a second/minute/hour/day/week/month.
 * Month is considered as an average of 30 days
 * */
export declare enum Milliseconds {
    Second = 1000,
    Minute = 60000,
    Hour = 3600000,
    Day = 86400000,
    Week = 604800000,
    Month = 2592000000
}
/**
 * @param {string} visitorCode - unique visitor identifier, shouldn't exceed 255 characters
 * @param {number} goalId - an id of a goal to track
 * @param {number | undefined} revenue - an optional parameter for revenue, default value is `0`
 * @param {boolean | undefined} negative Defines if the revenue is positive or negative, default value is `false`.
 * @param {CustomData[] | undefined} metadata Metadata of the conversion, default value is `undefined`.
 * */
export type TrackConversionParamsType = {
    visitorCode: string;
    goalId: number;
    revenue?: number;
    negative?: boolean;
    metadata?: CustomData[];
};
/**
 * @param {string} visitorCode - unique visitor identifier, shouldn't exceed 255 characters
 * @param {boolean | undefined} shouldAddData - optional parameter for adding retrieved data to the storage like `addData` method does, default value is `true`
 * @param {VisitorDataFiltersType | undefined} filters - optional parameter for specifying the filters for which data should be retrieved from what visit, by default only current and latest previous visits' `customData` is retrieved
 * */
export type RemoteVisitorDataParamsType = {
    visitorCode: string;
    shouldAddData?: boolean;
    filters?: VisitorDataFiltersType;
};
/**
 * @param {string | undefined} visitorCode - unique visitor identification string, can't exceed 255 characters length
 * @param {boolean | undefined} instant - Optional flag indicating whether the data should be sent instantly.
 * */
export type FlushParamsType = {
    visitorCode?: string;
    instant?: boolean;
};
/**
 * @param {string} visitorCode - unique visitor identifier, shouldn't exceed 255 characters
 * @param {string} featureKey - key of the feature flag to look for, can be found on Kameleoon Platform
 * @param {boolean | undefined} track - a flag to enable or disable tracking request
 * @defaultvalue `true`
 * */
export type IsFeatureFlagActiveParamsType = {
    visitorCode: string;
    featureKey: string;
    track?: boolean;
};
export type GetFeatureVariablesParamsType = {
    visitorCode: string;
    featureKey: string;
    variationKey: string;
};
export type FeatureFlagType = {
    id: number;
    key: string;
};
/**
 * @deprecated Use `Variable` instead.
 *
 * @type `KameleoonVariableType` - tuple of possible feature variable result types, each possible variation is an object containing `key`, `type` and `value` fields, `type` can be checked against `VariableType` enum, if the `type` is `VariableType.BOOLEAN` then the `value` type will be `boolean` and so on.
 * */
export type KameleoonVariableType = FeatureVariableResultType;
/**
 * @type `Variable` - tuple of possible feature variable result types, each possible variation is an object containing `key`, `type` and `value` fields, `type` can be checked against `VariableType` enum, if the `type` is `VariableType.BOOLEAN` then the `value` type will be `boolean` and so on.
 * */
export type Variable = FeatureVariableResultType;
/**
 * @type `KameleoonVariationType` - object containing information about the variation and its variables
 * @param {string} name - name of the variation
 * @param {string} key - key of the variation
 * @param {number | null} id - id of the variation or `null` if the visitor hit default variation
 * @param {number | null} experimentId - id of the experiment or `null` if the visitor hit default variation
 * @param {Variable[]} variables - array of variables for the variation
 * */
export type KameleoonVariationType = {
    name?: string;
    key: string;
    id: number | null;
    experimentId: number | null;
    variables: Variable[];
};
/**
 * @deprecated Use `Variation` instead.
 *
 * @type `VariationType` - an object containing information about the variation and its variables
 * @param {string} name - name of the variation
 * @param {string} key - key of the variation
 * @param {number | null} id - id of the variation or `null` if the visitor hit default variation
 * @param {number | null} experimentId - id of the experiment or `null` if the visitor hit default variation
 * @param {Map<string, Variable>} variables - map of variables for the variation, where key is the variable key and value is the variable object
 * */
export type VariationType = Omit<KameleoonVariationType, 'variables'> & {
    variables: Map<string, Variable>;
};
/**
 * @type `Variation` - an object containing information about the variation and its variables
 * @param {string} name - name of the variation
 * @param {string} key - key of the variation
 * @param {number | null} id - id of the variation or `null` if the visitor hit default variation
 * @param {number | null} experimentId - id of the experiment or `null` if the visitor hit default variation
 * @param {Map<string, Variable>} variables - map of variables for the variation, where key is the variable key and value is the variable object
 * */
export type Variation = VariationType;
/**
 * @param {string} visitorCode - unique visitor identifier, shouldn't exceed 255 characters
 * @param {string} featureKey - key of the feature flag to look for, can be found on Kameleoon Platform
 * @param {string} variableKey - key of the variable to be found for a feature flag with provided `featureKey`, can be found on Kameleoon Platform
 * */
export type GetFeatureFlagVariableParamsType = {
    visitorCode: string;
    featureKey: string;
    variableKey: string;
};
/**
 * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
 * @param {number} customDataIndex - index of the custom data in the warehouse audience
 * @param {string | undefined} warehouseKey - unique key to identify the warehouse data (usually internal user ID)
 * If not specified, the `visitorCode` will be used as a `warehouseKey`
 * */
export type GetVisitorWarehouseAudienceParamsType = {
    visitorCode: string;
    customDataIndex: number;
    warehouseKey?: string;
};
/**
 * @param {string} visitorCode - unique visitor identifier, shouldn't exceed 255 characters
 * @param {string} featureKey - key of the feature flag to look for, can be found on Kameleoon Platform
 * @param {boolean | undefined} track - a flag to enable or disable tracking request
 * @defaultvalue `true`
 * */
export type GetVariationParamsType = {
    visitorCode: string;
    featureKey: string;
    track?: boolean;
};
/**
 * @param {string} visitorCode - unique visitor identifier, shouldn't exceed 255 characters
 * @param {boolean | undefined} onlyActive - an indicator to get only active variations
 * @defaultvalue `false`
 * @param {boolean | undefined} track - a flag to enable or disable tracking request
 * @defaultvalue `true`
 * */
export type GetVariationsParamsType = {
    visitorCode: string;
    onlyActive?: boolean;
    track?: boolean;
};
export type WarehouseAudienceType = {
    warehouseAudiences: Record<string, unknown>;
};
export type TrackingCacheItemType = {
    [experimentId: number]: {
        variationId: number;
        expirationTime: number;
        hasJsCssVariables: boolean;
    };
};
export type SetDataCallbackParametersType = {
    visitorCode: string;
    maxAge: number;
    path: string;
    key: string;
};
export type GetFeatureVariationParametersType = {
    visitorCode: string;
    featureKey: string;
    track: boolean;
};
export type EvaluatedExperimentType = {
    experimentId: number | null;
    variationId: number | null;
    variationKey: string;
    ruleType: RuleType | null;
    isSimulated: boolean;
};
export type EvaluateParametersType = {
    visitorCode: string;
    featureFlag: ConfigFeatureFlagType;
    track: boolean;
    save: boolean;
};
/**
 * @param {string} visitorCode - unique visitor identifier, shouldn't exceed 255 characters
 * @param {boolean} consent - a value representing the legal consent status. - 'true' indicates the
 *        visitor has given legal consent. - 'false' indicates the visitor has withdrawn or not
 *        provided legal consent.
 * @param {(visitorCode: string) => void} setData - a callback to set a visitor code in cookie
 * */
export type SetUserConsentParametersType = {
    visitorCode: string;
    consent: boolean;
    setData: ({ visitorCode, maxAge, path, }: SetDataCallbackParametersType) => void;
};
/**
 * @type `SimulateRequestDataType` a type of data provided to `simulateSuccessRequest` method depending on `RequestType`
 * */
export type SimulateRequestDataType = {
    [RequestType.Configuration]: ClientConfigurationDataType;
    [RequestType.RemoteData]: JSONType;
    [RequestType.Tracking]: null;
};
/**
 * @param {string} visitorCode - The unique visitor code identifying the visitor.
 * @param {number} experimentId - The identifier of the experiment you want to set/reset the forced variation for.
 * @param {string | null} variationKey - The identifier of the variation you want the experiment to be evaluated to.
 *        Set to `null` to reset the forced variation.
 * @param {boolean} [forceTargeting=true] - If `true`, the visitor will be targeted to the experiment
 *        regardless of its conditions. Otherwise, the normal targeting logic will be preserved.
 *        Optional (defaults to `true`).
 */
export type SetForcedVariationParametersType = {
    visitorCode: string;
    experimentId: number;
    variationKey: string | null;
    forceTargeting?: boolean;
};
export type DataFile = {
    featureFlags: Map<string, FeatureFlag>;
};
export type FeatureFlag = {
    variations: Map<string, Variation>;
    environmentEnabled: boolean;
    rules: Rule[];
    defaultVariationKey: string;
};
export type Rule = {
    variations: Map<string, Variation>;
};