New fsApi / version 2 support

src/observer.ts

@@ -5,7 +5,9 @@ import DataHandler from './handler';
 import {
   Logger, LogAppender, LogMessageType, LogMessage, LogLevel,
 } from './utils/logger';
-import { FunctionOperator } from './operators';
+import {
+  FunctionOperator, SetIdentityOperator, SetPagePropertiesOperator, SetUserPropertiesOperator, TrackEventOperator,
+} from './operators';
 import DataLayerTarget from './target';
 import MonitorFactory from './monitor-factory';
 import { errorType, Telemetry, telemetryType } from './utils/telemetry';
@@ -60,14 +62,23 @@ export interface DataLayerRule {
   debug?: boolean;
   source: string;
   operators?: OperatorOptions[];
-  destination: string | Function;
+  destination?: string | Function;
   readOnLoad?: boolean;
   url?: string;
   id?: string;
   description?: string;
   monitor?: boolean;
   waitUntil?: number | Function;
   maxRetry?: number;
+  version?: number;
+  fsApi?: FS_API_CONSTANTS;
+}
+
+export enum FS_API_CONSTANTS {
+  SET_IDENTITY = 'setIdentity',
+  TRACK_EVENT = 'trackEvent',
+  SET_USER_PROPERTIES = 'setUserProperties',
+  SET_PAGE_PROPERTIES = 'setPageProperties'
 }
 
 /**
@@ -190,8 +201,13 @@ export class DataLayerObserver {
    * adding the operator, the DataHandler will be removed to prevent unexpected data processing.
    * @param handler to add operators to
    * @param options for operators used to configure each Operator
+   * @param destination The javascript function to execute (must be one of destination or fsApi)
+   * @param fsApi The special FullStory constant to be executed (must be one of destination or fsApi)
+   * @param version The version of DLO you are using.  As of version 2, beforeDestination will not be used.
    */
-  private addOperators(handler: DataHandler, options: OperatorOptions[], destination: string | Function) {
+  private addOperators(handler: DataHandler, options: OperatorOptions[],
+    destination: string | Function | undefined = undefined, fsApi: FS_API_CONSTANTS | undefined = undefined,
+    version: number = 1) {
     const { beforeDestination, previewDestination = 'console.log', previewMode } = this.config;
 
     try {
@@ -200,16 +216,36 @@ export class DataLayerObserver {
         handler.push(this.getOperator(optionSet));
       });
 
-      // optionally perform a final transformation
+      // optionally perform a final transformation if version is 1
       // useful if every rule needs the same operator run before the destination
-      if (beforeDestination) {
+      if (beforeDestination && (version === 1)) {
         const beforeOptions = Array.isArray(beforeDestination) ? beforeDestination : [beforeDestination];
         beforeOptions.forEach((operator) => handler.push(this.getOperator(operator)));
       }
 
-      // end with destination
-      const func = previewMode ? previewDestination : destination;
-      handler.push(new FunctionOperator({ name: 'function', func }));
+      if (fsApi) {
+        switch (fsApi) {
+          case FS_API_CONSTANTS.SET_IDENTITY:
+            handler.push(new SetIdentityOperator({ name: FS_API_CONSTANTS.SET_IDENTITY }));
+            break;
+          case FS_API_CONSTANTS.SET_PAGE_PROPERTIES:
+            handler.push(new SetPagePropertiesOperator({ name: FS_API_CONSTANTS.SET_PAGE_PROPERTIES }));
+            break;
+          case FS_API_CONSTANTS.SET_USER_PROPERTIES:
+            handler.push(new SetUserPropertiesOperator({ name: FS_API_CONSTANTS.SET_USER_PROPERTIES }));
+            break;
+          case FS_API_CONSTANTS.TRACK_EVENT:
+            handler.push(new TrackEventOperator({ name: FS_API_CONSTANTS.TRACK_EVENT }));
+            break;
+          default:
+            Logger.getInstance().error(`Unexpected coding error: Unknown fsApi value ${fsApi}`);
+        }
+      } else if (destination) {
+        const func = previewMode ? previewDestination : destination;
+        handler.push(new FunctionOperator({ name: 'function', func }));
+      } else {
+        Logger.getInstance().error('Unexpected coding error: Missing fsApi or destination');
+      }
     } catch (err) {
       this.removeHandler(handler);
       Logger.getInstance().error(LogMessageType.OperatorError, { operator: JSON.stringify(options) });
@@ -263,22 +299,26 @@ export class DataLayerObserver {
    * @param source from the rule monitoring the data layer
    * @param target from the data layer
    * @param options list of OperatorOptions to transform data before a destination
-   * @param destination function using selector syntax or native function
    * @param read when true reads data layer target and emit the initial value
    * @param monitor when true property changes or function calls re-run the operators
    * @param debug when true the rule prints debug for each Operator transformation
    * @param debounce number of milliseconds to debounce property assignments before handling the event
+   * @param version version of this rule, defaults to 1
+   * @param destination function using selector syntax or native function
+   * @param fsApi special Fullstory API Constant
    * @throws error if an error occurs during handler creation
    */
   registerTarget(
     source: string,
     target: DataLayerTarget,
     options: OperatorOptions[],
-    destination: string | Function,
+    destination: string | Function | undefined = undefined,
+    fsApi: FS_API_CONSTANTS | undefined = undefined,
     read = false,
     monitor = true,
     debug = false,
     debounce = DataHandler.DefaultDebounceTime,
+    version:number = 1,
   ): DataHandler {
     let workingTarget = target;
     const targetValue = workingTarget.value;
@@ -289,8 +329,8 @@ export class DataLayerObserver {
      */
     if (monitor && Array.isArray(targetValue)) {
       if (targetValue.push && targetValue.unshift) {
-        this.registerTarget(source, DataLayerTarget.find(`${target.path}.unshift`), options, destination, false, true,
-          debug, debounce);
+        this.registerTarget(source, DataLayerTarget.find(`${target.path}.unshift`), options, destination, fsApi,
+          false, true, debug, debounce, version);
         workingTarget = DataLayerTarget.find(`${target.path}.push`);
       } else {
         Logger.getInstance().warn(LogMessageType.MonitorCreateError, {
@@ -303,7 +343,7 @@ export class DataLayerObserver {
     }
 
     const handler = this.addHandler(source, workingTarget, !!debug, debounce);
-    this.addOperators(handler, options, destination);
+    this.addOperators(handler, options, destination, fsApi, version);
 
     if (read) {
       // For read-on-load for targeted arrays we do a sort of manual fan-out of the items
@@ -408,6 +448,8 @@ export class DataLayerObserver {
       source,
       operators = [],
       destination,
+      fsApi,
+      version,
       readOnLoad: ruleReadOnLoad,
       url,
       monitor = true,
@@ -417,13 +459,37 @@ export class DataLayerObserver {
     // rule properties override global ones
     const readOnLoad = ruleReadOnLoad === undefined ? globalReadOnLoad : ruleReadOnLoad;
 
-    if (!source || !destination) {
+    if (!source) {
       Logger.getInstance().error(LogMessageType.RuleInvalid,
-        { rule: id, source, reason: `Missing ${source ? 'destination' : 'source'}` });
+        { rule: id, source, reason: 'Missing source' });
       Telemetry.error(errorType.invalidRuleError);
       return;
     }
 
+    // sanity check destination and fsApi parameters
+    if (!destination && !fsApi) {
+      Logger.getInstance().error(LogMessageType.OperatorError, {
+        reason: LogMessage.MissingDestination,
+      });
+      Telemetry.error(errorType.operatorError);
+      return;
+    }
+
+    if (destination && fsApi) {
+      Logger.getInstance().error(LogMessageType.OperatorError, {
+        reason: LogMessage.DuplicateDestination,
+      });
+      Telemetry.error(errorType.operatorError);
+      return;
+    }
+
+    if (fsApi && !Object.values(FS_API_CONSTANTS).includes(fsApi as FS_API_CONSTANTS)) {
+      const reason = Logger.format(LogMessage.UnsupportedFsApi, fsApi);
+      Logger.getInstance().error(LogMessageType.OperatorError, { reason });
+      Telemetry.error(errorType.operatorError);
+      return;
+    }
+
     // check the rule is valid for the url
     if (!this.isUrlValid(url)) {
       return;
@@ -432,7 +498,8 @@ export class DataLayerObserver {
     try {
       const register = () => {
         const target = DataLayerTarget.find(source);
-        this.registerTarget(source, target, operators, destination, readOnLoad, monitor, debug, debounce);
+        this.registerTarget(source, target, operators, destination, fsApi, readOnLoad, monitor, debug,
+          debounce, version);
       };
       const timeout = () => Logger.getInstance().warn(LogMessageType.RuleRegistrationError, {
         rule: id, source, reason: 'Max Retries Attempted',

src/operators/fsApi/fsApi.ts

@@ -0,0 +1,42 @@
+import { Operator, OperatorOptions, OperatorValidator } from '../../operator';
+import { getGlobal } from '../../utils/object';
+
+export interface FSApiOperatorOptions extends OperatorOptions {
+
+}
+
+export default abstract class FSApiOperator implements Operator {
+  static specification = {};
+
+  constructor(public options:FSApiOperatorOptions) {
+    // sets this.options
+  }
+
+  handleData(data: any[]): any[] | null {
+    const thisArg: object = getGlobal();
+    // @ts-ignore
+    const fsFunction:any = thisArg[thisArg._fs_namespace]; // eslint-disable-line
+    if (typeof fsFunction !== 'function') {
+      throw new Error('_fs_namespace is not a function');
+    }
+    // subclasses will determine how to prepare the data
+    const realData = this.prepareData(data);
+    if (realData === null) {
+      return null;
+    }
+    // make sure to push dlo as last parameter
+    realData.push('dlo');
+    const returnValue = fsFunction.apply(thisArg, realData);
+    if (returnValue === undefined || returnValue === null) {
+      return null;
+    }
+    return [returnValue];
+  }
+
+  validate() {
+    const validator = new OperatorValidator(this.options);
+    validator.validate(FSApiOperator.specification);
+  }
+
+  abstract prepareData(inputData:any[]): any[] | null;
+}

src/operators/fsApi/setIdentity.ts

@@ -0,0 +1,21 @@
+import FSApiOperator from './fsApi';
+
+// eslint-disable-next-line import/prefer-default-export
+export class SetIdentityOperator extends FSApiOperator {
+  // eslint-disable-next-line class-methods-use-this
+  prepareData(inputData:any[]): any[] | null {
+    if (inputData === null || inputData.length < 1) {
+      throw new Error('Input data is empty');
+    }
+    const realData:any[] = [
+      'setIdentity',
+      { uid: inputData[0] },
+    ];
+    // setIdentity calls can have optional properties
+    if (inputData.length > 1) {
+      // eslint-disable-next-line prefer-destructuring
+      realData[1].properties = inputData[1];
+    }
+    return realData;
+  }
+}

src/operators/fsApi/setPageProperties.ts

@@ -0,0 +1,18 @@
+import FSApiOperator from './fsApi';
+
+// eslint-disable-next-line import/prefer-default-export
+export class SetPagePropertiesOperator extends FSApiOperator {
+  // eslint-disable-next-line class-methods-use-this
+  prepareData(inputData:any[]): any[] | null {
+    if (inputData === null || inputData.length < 1) {
+      throw new Error('Input data is empty');
+    }
+    return [
+      'setProperties',
+      {
+        type: 'page',
+        properties: inputData[0],
+      },
+    ];
+  }
+}

src/operators/fsApi/setUserProperties.ts

@@ -0,0 +1,18 @@
+import FSApiOperator from './fsApi';
+
+// eslint-disable-next-line import/prefer-default-export
+export class SetUserPropertiesOperator extends FSApiOperator {
+  // eslint-disable-next-line class-methods-use-this
+  prepareData(inputData:any[]): any[] | null {
+    if (inputData === null || inputData.length < 1) {
+      throw new Error('Input data is empty');
+    }
+    return [
+      'setProperties',
+      {
+        type: 'user',
+        properties: inputData[0],
+      },
+    ];
+  }
+}

src/operators/fsApi/trackEvent.ts

@@ -0,0 +1,20 @@
+import FSApiOperator from './fsApi';
+
+// eslint-disable-next-line import/prefer-default-export
+export class TrackEventOperator extends FSApiOperator {
+  // eslint-disable-next-line class-methods-use-this
+  prepareData(inputData:any[]): any[] | null {
+    if (inputData === null || inputData.length < 1) {
+      throw new Error('Input data is empty');
+    } else if (inputData.length < 2) {
+      throw new Error('Input data expected to have two parameters');
+    }
+    return [
+      'trackEvent',
+      {
+        name: inputData[0],
+        properties: inputData[1],
+      },
+    ];
+  }
+}

src/operators/index.ts

@@ -7,3 +7,7 @@ export * from './suffix';
 export * from './rename';
 export * from './query';
 export * from './parse';
+export * from './fsApi/setIdentity';
+export * from './fsApi/setPageProperties';
+export * from './fsApi/setUserProperties';
+export * from './fsApi/trackEvent';

src/utils/logger.ts

@@ -34,6 +34,8 @@ export enum LogMessageType {
 export enum LogMessage {
   DataLayerMissing = 'Data layer not found',
   DuplicateValue = 'Value $0 already used',
+  DuplicateDestination = 'Only one of destination or fsApi can be defined',
+  MissingDestination = 'destination or fsApi must be defined',
   ShimFail = 'Shim not allowed because object is $0',
   SelectorInvalidIndex = 'Selector index $0 is not a number in $1',
   SelectorIncorrectTokenCount = 'Selector has incorrect number ($0) of tokens in $1',
@@ -45,6 +47,7 @@ export enum LogMessage {
   TargetPropertyMissing = 'Target property is missing',
   TargetPathMissing = 'Target path is missing',
   UnknownValue = 'Unknown value $0',
+  UnsupportedFsApi = 'Unsupported fsApi $0',
   UnsupportedType = 'Unsupported type $0',
 }
 

test/mocks/fullstoryV2.ts

@@ -0,0 +1,13 @@
+let callQueues: any[] = [];
+
+export function fullstoryMock(...args:any[]) {
+  callQueues.push(args);
+}
+
+export function clearCallQueues() {
+  callQueues = [];
+}
+
+export function getCallQueues() : any {
+  return callQueues;
+}