refactor: Create Interfaces for Events

src/events.interfaces.ts

@@ -0,0 +1,83 @@
+import {
+    Callback,
+    SDKEventAttrs,
+    SDKEventOptions,
+    TransactionAttributes,
+} from '@mparticle/web-sdk';
+import {
+    BaseEvent,
+    SDKEvent,
+    SDKEventCustomFlags,
+    SDKProduct,
+    SDKProductImpression,
+    SDKPromotion,
+} from './sdkRuntimeModels';
+import { valueof } from './utils';
+import { EventType, ProductActionType, PromotionActionType } from './types';
+
+// Supports wrapping event handlers functions that will ideally return a specific type
+type EventHandlerFunction<T> = (element: HTMLLinkElement | HTMLFormElement) => T;
+
+export interface IEvents {
+    addEventHandler(
+        domEvent: string,
+        selector: string | Node,
+        eventName: EventHandlerFunction<string> | string,
+        data: EventHandlerFunction<SDKEventAttrs> | SDKEventAttrs,
+        eventType: valueof<typeof EventType>
+    ): void;
+    logAST(): void;
+    logCheckoutEvent(
+        step: number,
+
+        // User options specified during the checkout process
+        // e.g., FedEx, DHL, UPS for delivery options;
+        // Visa, MasterCard, AmEx for payment options.
+        option?: string,
+
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags
+    ): void;
+    logCommerceEvent(
+        commerceEvent: SDKEvent,
+        attrs?: SDKEventAttrs,
+        options?: SDKEventOptions
+    ): void;
+    logEvent(event: BaseEvent, eventOptions?: SDKEventOptions): void;
+    logImpressionEvent(
+        impression: SDKProductImpression,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags,
+        eventOptions?: SDKEventOptions
+    );
+    logOptOut(): void;
+    logProductActionEvent(
+        productActionType: valueof<typeof ProductActionType>,
+        product: SDKProduct,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags,
+        transactionAttributes?: TransactionAttributes,
+        eventOptions?: SDKEventOptions
+    ): void;
+    logPromotionEvent(
+        promotionType: valueof<typeof PromotionActionType>,
+        promotion: SDKPromotion,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags,
+        eventOptions?: SDKEventOptions
+    ): void;
+    logPurchaseEvent(
+        transactionAttributes: TransactionAttributes,
+        product: SDKProduct,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags
+    ): void;
+    logRefundEvent(
+        transactionAttributes: TransactionAttributes,
+        product: SDKProduct,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags
+    ): void;
+    startTracking(callback: Callback): void;
+    stopTracking(): void;
+}

src/events.js

@@ -438,10 +438,13 @@ export default function Events(mpInstance) {
                 element = elements[i];
 
                 if (element.addEventListener) {
+                    // Modern browsers
                     element.addEventListener(domEvent, handler, false);
                 } else if (element.attachEvent) {
+                    // IE < 9
                     element.attachEvent('on' + domEvent, handler);
                 } else {
+                    // All other browsers
                     element['on' + domEvent] = handler;
                 }
             }

src/mp-instance.js

@@ -824,7 +824,7 @@ export default function mParticleInstance(instanceName) {
          * @for mParticle.eCommerce
          * @method logCheckout
          * @param {Number} step checkout step number
-         * @param {String} option
+         * @param {String} checkout option string
          * @param {Object} attrs
          * @param {Object} [customFlags] Custom flags for the event
          * @deprecated

src/sdkRuntimeModels.ts

@@ -4,6 +4,8 @@ import {
     MPConfiguration,
     MPID,
     IdentityApiData,
+    SDKEventOptions,
+    SDKEventAttrs,
 } from '@mparticle/web-sdk';
 import { IStore } from './store';
 import Validators from './validators';
@@ -37,6 +39,7 @@ import {
 import IntegrationCapture from './integrationCapture';
 import { INativeSdkHelpers } from './nativeSdkHelpers.interfaces';
 import { ICookieSyncManager, IPixelConfiguration } from './cookieSyncManager';
+import { IEvents } from './events.interfaces';
 
 // TODO: Resolve this with version in @mparticle/web-sdk
 export type SDKEventCustomFlags = Dictionary<any>;
@@ -150,11 +153,6 @@ export interface SDKProduct {
     Attributes?: { [key: string]: string };
 }
 
-// Temporary Interfaces for Events Module
-interface IEvents {
-    logEvent?(event: BaseEvent): void;
-}
-
 export interface MParticleWebSDK {
     addForwarder(mockForwarder: MPForwarder): void;
     _IntegrationCapture: IntegrationCapture;
@@ -204,11 +202,12 @@ export interface MParticleWebSDK {
     startNewSession(): void;
     logEvent(
         eventName: string,
-        eventType?: number,
-        attrs?: { [key: string]: string },
-        customFlags?: SDKEventCustomFlags
+        eventType?: valueof<typeof EventType>,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags,
+        eventOptions?: SDKEventOptions
     ): void;
-    logBaseEvent(event: any): void;
+    logBaseEvent(event: BaseEvent, eventOptions?: SDKEventOptions): void;
     eCommerce: any;
     logLevel: string;
     ProductActionType: SDKProductActionType;
@@ -293,6 +292,7 @@ export interface SDKHelpersApi {
         timeoutStart: number,
         now: number
     ): boolean;
+    isEventType?(type: valueof<typeof EventType>): boolean;
     isObject?(item: any);
     invokeCallback?(
         callback: IdentityCallback,