@splitsoftware/splitio-commons 1.2.1-rc.4 → 1.2.1-rc.5

package/src/sync/syncManagerOnline.ts

@@ -6,6 +6,7 @@ import { IPushManager } from './streaming/types';
 import { IPollingManager, IPollingManagerCS } from './polling/types';
 import { PUSH_SUBSYSTEM_UP, PUSH_SUBSYSTEM_DOWN } from './streaming/constants';
 import { SYNC_START_POLLING, SYNC_CONTINUE_POLLING, SYNC_STOP_POLLING } from '../logger/constants';
+import { isConsentGranted } from '../utils/consent';
 
 /**
  * Online SyncManager factory.
@@ -25,7 +26,7 @@ export function syncManagerOnlineFactory(
    */
   return function (params: ISyncManagerFactoryParams): ISyncManagerCS {
 
-    const { log, streamingEnabled } = params.settings;
+    const { settings, settings: { log, streamingEnabled } } = params;
 
     /** Polling Manager */
     const pollingManager = pollingManagerFactory && pollingManagerFactory(params);
@@ -39,7 +40,6 @@ export function syncManagerOnlineFactory(
     // It is not inyected as push and polling managers, because at the moment it is required
     const submitter = submitterManagerFactory(params);
 
-
     /** Sync Manager logic */
 
     function startPolling() {
@@ -69,12 +69,18 @@ export function syncManagerOnlineFactory(
     let startFirstTime = true; // flag to distinguish calling the `start` method for the first time, to support pausing and resuming the synchronization
 
     return {
+      // Exposed for fine-grained control of synchronization.
+      // E.g.: user consent, app state changes (Page hide, Foreground/Background, Online/Offline).
+      pollingManager,
       pushManager,
+      submitter,
 
       /**
        * Method used to start the syncManager for the first time, or resume it after being stopped.
        */
       start() {
+        running = true;
+
         // start syncing splits and segments
         if (pollingManager) {
           if (pushManager) {
@@ -90,21 +96,21 @@ export function syncManagerOnlineFactory(
         }
 
         // start periodic data recording (events, impressions, telemetry).
-        if (submitter) submitter.start();
-        running = true;
+        if (isConsentGranted(settings)) submitter.start();
       },
 
       /**
        * Method used to stop/pause the syncManager.
        */
       stop() {
+        running = false;
+
         // stop syncing
         if (pushManager) pushManager.stop();
         if (pollingManager && pollingManager.isRunning()) pollingManager.stop();
 
         // stop periodic data recording (events, impressions, telemetry).
-        if (submitter) submitter.stop();
-        running = false;
+        submitter.stop();
       },
 
       isRunning() {
@@ -112,7 +118,7 @@ export function syncManagerOnlineFactory(
       },
 
       flush() {
-        if (submitter) return submitter.execute();
+        if (isConsentGranted(settings)) return submitter.execute();
         else return Promise.resolve();
       },
 

package/src/sync/types.ts

@@ -3,6 +3,7 @@ import { IPlatform } from '../sdkFactory/types';
 import { ISplitApi } from '../services/types';
 import { IStorageSync } from '../storages/types';
 import { ISettings } from '../types';
+import { IPollingManager } from './polling/types';
 import { IPushManager } from './streaming/types';
 
 export interface ITask<Input extends any[] = []> {
@@ -43,7 +44,9 @@ export interface ITimeTracker {
 
 export interface ISyncManager extends ITask {
   flush(): Promise<any>,
-  pushManager?: IPushManager
+  pushManager?: IPushManager,
+  pollingManager?: IPollingManager,
+  submitter?: ISyncTask
 }
 
 export interface ISyncManagerCS extends ISyncManager {

package/src/types.ts

@@ -54,6 +54,11 @@ type EventConsts = {
  * @typedef {string} SDKMode
  */
 export type SDKMode = 'standalone' | 'consumer' | 'localhost' | 'consumer_partial';
+/**
+ * User consent status.
+ * @typedef {string} ConsentStatus
+ */
+export type ConsentStatus = 'GRANTED' | 'DECLINED' | 'UNKNOWN';
 /**
  * Settings interface. This is a representation of the settings the SDK expose, that's why
  * most of it's props are readonly. Only features should be rewritten when localhost mode is active.
@@ -111,6 +116,7 @@ export interface ISettings {
   },
   readonly log: ILogger
   readonly impressionListener?: unknown
+  readonly userConsent?: ConsentStatus
 }
 /**
  * Log levels.

package/src/utils/consent.ts

@@ -0,0 +1,8 @@
+import { ISettings } from '../types';
+import { CONSENT_GRANTED } from './constants';
+
+export function isConsentGranted(settings: ISettings) {
+  const userConsent = settings.userConsent;
+  // undefined userConsent is handled as granted (default)
+  return !userConsent || userConsent === CONSENT_GRANTED;
+}

package/src/utils/constants/index.ts

@@ -32,3 +32,8 @@ export const STORAGE_MEMORY: StorageType = 'MEMORY';
 export const STORAGE_LOCALSTORAGE: StorageType = 'LOCALSTORAGE';
 export const STORAGE_REDIS: StorageType = 'REDIS';
 export const STORAGE_PLUGGABLE: StorageType = 'PLUGGABLE';
+
+// User consent
+export const CONSENT_GRANTED = 'GRANTED'; // The user has granted consent for tracking events and impressions
+export const CONSENT_DECLINED = 'DECLINED'; // The user has declined consent for tracking events and impressions
+export const CONSENT_UNKNOWN = 'UNKNOWN'; // The user has neither granted nor declined consent for tracking events and impressions

package/src/utils/settingsValidation/consent.ts

@@ -0,0 +1,14 @@
+import { ERROR_INVALID_CONFIG_PARAM } from '../../logger/constants';
+import { ILogger } from '../../logger/types';
+import { CONSENT_DECLINED, CONSENT_GRANTED, CONSENT_UNKNOWN } from '../constants';
+
+const userConsentValues = [CONSENT_DECLINED, CONSENT_GRANTED, CONSENT_UNKNOWN];
+
+export function validateConsent({ userConsent, log }: { userConsent: any, log: ILogger }) {
+  if (typeof userConsent === 'string') userConsent = userConsent.toUpperCase();
+
+  if (userConsentValues.indexOf(userConsent) > -1) return userConsent;
+
+  log.error(ERROR_INVALID_CONFIG_PARAM, ['userConsent', userConsentValues, CONSENT_GRANTED]);
+  return CONSENT_GRANTED;
+}

package/src/utils/settingsValidation/impressionsMode.ts

@@ -1,14 +1,13 @@
-import { ERROR_INVALID_IMPRESSIONS_MODE } from '../../logger/constants';
+import { ERROR_INVALID_CONFIG_PARAM } from '../../logger/constants';
 import { ILogger } from '../../logger/types';
 import { SplitIO } from '../../types';
 import { DEBUG, OPTIMIZED } from '../constants';
 
-export function validImpressionsMode(log: ILogger, impressionsMode: string): SplitIO.ImpressionsMode {
-  impressionsMode = impressionsMode.toUpperCase();
-  if ([DEBUG, OPTIMIZED].indexOf(impressionsMode) === -1) {
-    log.error(ERROR_INVALID_IMPRESSIONS_MODE, [[DEBUG, OPTIMIZED], OPTIMIZED]);
-    impressionsMode = OPTIMIZED;
-  }
+export function validImpressionsMode(log: ILogger, impressionsMode: any): SplitIO.ImpressionsMode {
+  if (typeof impressionsMode === 'string') impressionsMode = impressionsMode.toUpperCase();
 
-  return impressionsMode as SplitIO.ImpressionsMode;
+  if ([DEBUG, OPTIMIZED].indexOf(impressionsMode) > -1) return impressionsMode;
+
+  log.error(ERROR_INVALID_CONFIG_PARAM, ['impressionsMode', [DEBUG, OPTIMIZED], OPTIMIZED]);
+  return OPTIMIZED;
 }

package/src/utils/settingsValidation/index.ts

@@ -97,7 +97,7 @@ function fromSecondsToMillis(n: number) {
  */
 export function settingsValidation(config: unknown, validationParams: ISettingsValidationParams) {
 
-  const { defaults, runtime, storage, integrations, logger, localhost } = validationParams;
+  const { defaults, runtime, storage, integrations, logger, localhost, consent } = validationParams;
 
   // creates a settings object merging base, defaults and config objects.
   const withDefaults = merge({}, base, defaults, config) as ISettings;
@@ -161,5 +161,9 @@ export function settingsValidation(config: unknown, validationParams: ISettingsV
   // ensure a valid impressionsMode
   withDefaults.sync.impressionsMode = validImpressionsMode(log, withDefaults.sync.impressionsMode);
 
+  // ensure a valid user consent value
+  // @ts-ignore, modify readonly prop
+  withDefaults.userConsent = consent(withDefaults);
+
   return withDefaults;
 }

package/src/utils/settingsValidation/types.ts

@@ -20,4 +20,6 @@ export interface ISettingsValidationParams {
   logger: (settings: ISettings) => ISettings['log'],
   /** Localhost mode validator (`settings.sync.localhostMode`) */
   localhost?: (settings: ISettings) => ISettings['sync']['localhostMode'],
+  /** User consent validator (`settings.userConsent`) */
+  consent: (settings: ISettings) => ISettings['userConsent'],
 }

package/types/logger/constants.d.ts

@@ -67,6 +67,7 @@ export declare const SYNC_CONTINUE_POLLING = 118;
 export declare const SYNC_STOP_POLLING = 119;
 export declare const EVENTS_TRACKER_SUCCESS = 120;
 export declare const IMPRESSIONS_TRACKER_SUCCESS = 121;
+export declare const USER_CONSENT_UPDATED = 122;
 export declare const ENGINE_VALUE_INVALID = 200;
 export declare const ENGINE_VALUE_NO_ATTRIBUTES = 201;
 export declare const CLIENT_NO_LISTENER = 202;
@@ -112,10 +113,11 @@ export declare const ERROR_INVALID_KEY_OBJECT = 317;
 export declare const ERROR_INVALID = 318;
 export declare const ERROR_EMPTY = 319;
 export declare const ERROR_EMPTY_ARRAY = 320;
-export declare const ERROR_INVALID_IMPRESSIONS_MODE = 321;
+export declare const ERROR_INVALID_CONFIG_PARAM = 321;
 export declare const ERROR_HTTP = 322;
 export declare const ERROR_LOCALHOST_MODULE_REQUIRED = 323;
 export declare const ERROR_STORAGE_INVALID = 324;
+export declare const ERROR_NOT_BOOLEAN = 325;
 export declare const LOG_PREFIX_SETTINGS = "settings";
 export declare const LOG_PREFIX_INSTANTIATION = "Factory instantiation";
 export declare const LOG_PREFIX_ENGINE = "engine";

package/types/sdkFactory/types.d.ts

@@ -39,4 +39,5 @@ export interface ISdkFactoryParams {
     impressionListener?: SplitIO.IImpressionListener;
     integrationsManagerFactory?: (params: IIntegrationFactoryParams) => IIntegrationManager | undefined;
     impressionsObserverFactory?: () => IImpressionObserver;
+    extraProps?: (settings: ISettings, syncManager?: ISyncManager) => object;
 }

package/types/sdkFactory/userConsentProps.d.ts

@@ -0,0 +1,6 @@
+import { ISyncManager } from '../sync/types';
+import { ISettings } from '../types';
+export declare function userConsentProps(settings: ISettings, syncManager?: ISyncManager): {
+    setUserConsent(consent: unknown): boolean;
+    getUserConsent(): import("../types").ConsentStatus | undefined;
+};

package/types/storages/KeyBuilderCS.d.ts

@@ -8,6 +8,8 @@ export declare class KeyBuilderCS extends KeyBuilder {
      */
     buildSegmentNameKey(segmentName: string): string;
     extractSegmentName(builtSegmentKeyName: string): string | undefined;
+    buildOldSegmentNameKey(segmentName: string): string;
+    extractOldSegmentKey(builtSegmentKeyName: string): string | undefined;
     buildLastUpdatedKey(): string;
     isSplitsCacheKey(key: string): boolean;
     buildSplitsFilterQueryKey(): string;

package/types/sync/types.d.ts

@@ -3,6 +3,7 @@ import { IPlatform } from '../sdkFactory/types';
 import { ISplitApi } from '../services/types';
 import { IStorageSync } from '../storages/types';
 import { ISettings } from '../types';
+import { IPollingManager } from './polling/types';
 import { IPushManager } from './streaming/types';
 export interface ITask<Input extends any[] = []> {
     /**
@@ -39,6 +40,8 @@ export interface ITimeTracker {
 export interface ISyncManager extends ITask {
     flush(): Promise<any>;
     pushManager?: IPushManager;
+    pollingManager?: IPollingManager;
+    submitter?: ISyncTask;
 }
 export interface ISyncManagerCS extends ISyncManager {
     shared(matchingKey: string, readinessManager: IReadinessManager, storage: IStorageSync): ISyncManager | undefined;

package/types/types.d.ts

@@ -48,6 +48,11 @@ declare type EventConsts = {
  * @typedef {string} SDKMode
  */
 export declare type SDKMode = 'standalone' | 'consumer' | 'localhost' | 'consumer_partial';
+/**
+ * User consent status.
+ * @typedef {string} ConsentStatus
+ */
+export declare type ConsentStatus = 'GRANTED' | 'DECLINED' | 'UNKNOWN';
 /**
  * Settings interface. This is a representation of the settings the SDK expose, that's why
  * most of it's props are readonly. Only features should be rewritten when localhost mode is active.
@@ -105,6 +110,7 @@ export interface ISettings {
     };
     readonly log: ILogger;
     readonly impressionListener?: unknown;
+    readonly userConsent?: ConsentStatus;
 }
 /**
  * Log levels.

package/types/utils/consent.d.ts

@@ -0,0 +1,2 @@
+import { ISettings } from '../types';
+export declare function isConsentGranted(settings: ISettings): boolean;

package/types/utils/constants/index.d.ts

@@ -20,3 +20,6 @@ export declare const STORAGE_MEMORY: StorageType;
 export declare const STORAGE_LOCALSTORAGE: StorageType;
 export declare const STORAGE_REDIS: StorageType;
 export declare const STORAGE_PLUGGABLE: StorageType;
+export declare const CONSENT_GRANTED = "GRANTED";
+export declare const CONSENT_DECLINED = "DECLINED";
+export declare const CONSENT_UNKNOWN = "UNKNOWN";

package/types/utils/settingsValidation/consent.d.ts

@@ -0,0 +1,5 @@
+import { ILogger } from '../../logger/types';
+export declare function validateConsent({ userConsent, log }: {
+    userConsent: any;
+    log: ILogger;
+}): any;

package/types/utils/settingsValidation/impressionsMode.d.ts

@@ -1,3 +1,3 @@
 import { ILogger } from '../../logger/types';
 import { SplitIO } from '../../types';
-export declare function validImpressionsMode(log: ILogger, impressionsMode: string): SplitIO.ImpressionsMode;
+export declare function validImpressionsMode(log: ILogger, impressionsMode: any): SplitIO.ImpressionsMode;

package/types/utils/settingsValidation/types.d.ts

@@ -23,4 +23,6 @@ export interface ISettingsValidationParams {
     logger: (settings: ISettings) => ISettings['log'];
     /** Localhost mode validator (`settings.sync.localhostMode`) */
     localhost?: (settings: ISettings) => ISettings['sync']['localhostMode'];
+    /** User consent validator (`settings.userConsent`) */
+    consent: (settings: ISettings) => ISettings['userConsent'];
 }

package/types/utils/settingsValidation/userConsent.d.ts

@@ -0,0 +1,5 @@
+import { ILogger } from '../../logger/types';
+export declare function validateUserConsent({ userConsent, log }: {
+    userConsent: any;
+    log: ILogger;
+}): any;