refactor: Create Interfaces for eCommerce (#964)

alexs-mparticle · alexs-mparticle · commit c9a27237ea78 · 2025-01-27T10:22:47.000-05:00
diff --git a/src/ecommerce.interfaces.ts b/src/ecommerce.interfaces.ts
@@ -0,0 +1,201 @@
+import {
+    ProductAction,
+    Product,
+    Promotion,
+    CommerceEvent,
+} from '@mparticle/event-models';
+import {
+    SDKEventAttrs,
+    SDKEventOptions,
+    TransactionAttributes,
+} from '@mparticle/web-sdk';
+import { valueof } from './utils';
+import {
+    ProductActionType,
+    PromotionActionType,
+    CommerceEventType,
+    EventType,
+} from './types';
+import {
+    SDKEvent,
+    SDKEventCustomFlags,
+    SDKImpression,
+    SDKProduct,
+    SDKProductImpression,
+    SDKPromotion,
+} from './sdkRuntimeModels';
+
+interface IECommerceShared {
+    createProduct(
+        name: string,
+        sku: string | number,
+        price: string | number,
+        quantity?: string | number,
+        variant?: string,
+        category?: string,
+        brand?: string,
+        position?: number,
+        couponCode?: string,
+        attributes?: SDKEventAttrs
+    ): SDKProduct | null;
+    createImpression(name: string, product: Product): SDKImpression | null;
+    createPromotion(
+        id: string | number,
+        creative?: string,
+        name?: string,
+        position?: number
+    ): SDKPromotion | null;
+    createTransactionAttributes(
+        id: string | number,
+        affiliation?: string,
+        couponCode?: string,
+        revenue?: string | number,
+        shipping?: string | number,
+        tax?: number
+    ): TransactionAttributes | null;
+    expandCommerceEvent(event: CommerceEvent): SDKEvent[] | null;
+}
+
+export interface SDKCart {
+    add(product: SDKProduct | SDKProduct[], logEvent?: boolean): void;
+    remove(product: SDKProduct | SDKProduct[], logEvent?: boolean): void;
+    clear(): void;
+}
+
+// Used for the public `eCommerce` namespace
+export interface SDKECommerceAPI extends IECommerceShared {
+    logCheckout(
+        step: number,
+        option?: string,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags
+    ): void;
+    logImpression(
+        impression: SDKProductImpression,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags,
+        eventOptions?: SDKEventOptions
+    ): void;
+    logProductAction(
+        productActionType: valueof<typeof ProductActionType>,
+        product: SDKProduct | SDKProduct[],
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags,
+        transactionAttributes?: TransactionAttributes,
+        eventOptions?: SDKEventOptions
+    ): void;
+    logPromotion(
+        type: valueof<typeof PromotionActionType>,
+        promotion: SDKPromotion,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags,
+        eventOptions?: SDKEventOptions
+    ): void;
+    setCurrencyCode(code: string): void;
+
+    /*
+     * @deprecated
+     */
+    Cart: SDKCart;
+
+    /*
+     * @deprecated
+     */
+    logPurchase(
+        transactionAttributes: TransactionAttributes,
+        product: SDKProduct | SDKProduct[],
+        clearCart?: boolean,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags
+    ): void;
+
+    /*
+     * @deprecated
+     */
+    logRefund(
+        transactionAttributes: TransactionAttributes,
+        product: SDKProduct | SDKProduct[],
+        clearCart?: boolean,
+        attrs?: SDKEventAttrs,
+        customFlags?: SDKEventCustomFlags
+    ): void;
+}
+
+interface ExtractedActionAttributes {
+    Affiliation?: string;
+    'Coupon Code'?: string;
+    'Total Amount'?: number;
+    'Shipping Amount'?: number;
+    'Tax Amount'?: number;
+    'Checkout Option'?: string;
+    'Checkout Step'?: number;
+    'Transaction ID'?: string;
+}
+interface ExtractedProductAttributes {
+    'Coupon Code'?: string;
+    Brand?: string;
+    Category?: string;
+    Name?: string;
+    Id?: string;
+    'Item Price'?: number;
+    Quantity?: number;
+    Position?: number;
+    Variant?: string;
+    'Total Product Amount': number;
+}
+interface ExtractedPromotionAttributes {
+    Id?: string;
+    Creative?: string;
+    Name?: string;
+    Position?: number;
+}
+interface ExtractedTransactionId {
+    'Transaction ID'?: string;
+}
+
+// Used for the private `_Ecommerce` namespace
+export interface IECommerce extends IECommerceShared {
+    buildProductList(event: SDKEvent, product: Product | Product[]): Product[];
+    convertProductActionToEventType(
+        productActionType: valueof<typeof ProductActionType>
+    ): // https://go.mparticle.com/work/SQDSDKS-4801
+    typeof CommerceEventType | typeof EventType | null;
+    convertPromotionActionToEventType(
+        promotionActionType: valueof<typeof PromotionActionType>
+    ): typeof CommerceEventType | null;
+    convertTransactionAttributesToProductAction(
+        transactionAttributes: TransactionAttributes,
+        productAction: ProductAction
+    ): void;
+    createCommerceEventObject(
+        customFlags: SDKEventCustomFlags,
+        options?: SDKEventOptions
+    ): SDKEvent | null;
+    expandProductAction(commerceEvent: CommerceEvent): SDKEvent[];
+    expandProductImpression(commerceEvent: CommerceEvent): SDKEvent[];
+    expandPromotionAction(commerceEvent: CommerceEvent): SDKEvent[];
+    extractActionAttributes(
+        attributes: ExtractedActionAttributes,
+        productAction: ProductAction
+    ): void;
+    extractProductAttributes(
+        attributes: ExtractedProductAttributes,
+        product: Product
+    ): void;
+    extractPromotionAttributes(
+        attributes: ExtractedPromotionAttributes,
+        promotion: Promotion
+    ): void;
+    extractTransactionId(
+        attributes: ExtractedTransactionId,
+        productAction: ProductAction
+    ): void;
+    generateExpandedEcommerceName(eventName: string, plusOne: boolean): string;
+    getProductActionEventName(
+        productActionType: valueof<typeof ProductActionType>
+    ): string;
+    getPromotionActionEventName(
+        promotionActionType: valueof<typeof PromotionActionType>
+    ): string;
+    sanitizeAmount(amount: string | number, category: string): number;
+}
diff --git a/src/ecommerce.js b/src/ecommerce.js
@@ -5,6 +5,8 @@ var Messages = Constants.Messages;
 
 export default function Ecommerce(mpInstance) {
     var self = this;
+
+    // https://go.mparticle.com/work/SQDSDKS-4801
     this.convertTransactionAttributesToProductAction = function(
         transactionAttributes,
         productAction
@@ -103,8 +105,11 @@ export default function Ecommerce(mpInstance) {
                 return Types.CommerceEventType.ProductRemoveFromCart;
             case Types.ProductActionType.RemoveFromWishlist:
                 return Types.CommerceEventType.ProductRemoveFromWishlist;
+
+            // https://go.mparticle.com/work/SQDSDKS-4801
             case Types.ProductActionType.Unknown:
                 return Types.EventType.Unknown;
+
             case Types.ProductActionType.ViewDetail:
                 return Types.CommerceEventType.ProductViewDetail;
             default:
@@ -139,6 +144,7 @@ export default function Ecommerce(mpInstance) {
         );
     };
 
+    // https://go.mparticle.com/work/SQDSDKS-4801
     this.extractProductAttributes = function(attributes, product) {
         if (product.CouponCode) {
             attributes['Coupon Code'] = product.CouponCode;
@@ -170,12 +176,14 @@ export default function Ecommerce(mpInstance) {
         attributes['Total Product Amount'] = product.TotalAmount || 0;
     };
 
+    // https://go.mparticle.com/work/SQDSDKS-4801
     this.extractTransactionId = function(attributes, productAction) {
         if (productAction.TransactionId) {
             attributes['Transaction Id'] = productAction.TransactionId;
         }
     };
 
+    // https://go.mparticle.com/work/SQDSDKS-4801
     this.extractActionAttributes = function(attributes, productAction) {
         self.extractTransactionId(attributes, productAction);
 
@@ -208,6 +216,7 @@ export default function Ecommerce(mpInstance) {
         }
     };
 
+    // https://go.mparticle.com/work/SQDSDKS-4801
     this.extractPromotionAttributes = function(attributes, promotion) {
         if (promotion.Id) {
             attributes['Id'] = promotion.Id;
diff --git a/src/identity-user-interfaces.ts b/src/identity-user-interfaces.ts
@@ -1,29 +1,29 @@
 import { AllUserAttributes, MPID, Product, User } from '@mparticle/web-sdk';
 import { SDKIdentityTypeEnum } from './identity.interfaces';
 import { MessageType } from './types';
-import { BaseEvent } from './sdkRuntimeModels';
+import { BaseEvent, SDKProduct } from './sdkRuntimeModels';
 import Constants from './constants';
 const { HTTPCodes } = Constants;
 
 // Cart is Deprecated and private to mParticle user in @mparticle/web-sdk
 // but we need to expose it here for type safety in some of our tests
-interface Cart {
+interface ICart {
     /**
      * @deprecated Cart persistence in mParticle has been deprecated. Please use mParticle.eCommerce.logProductAction(mParticle.ProductActionType.AddToCart, [products])
      */
-    add: (product: Product, logEventBoolean?: boolean) => void;
+    add: (product: SDKProduct, logEventBoolean?: boolean) => void;
     /**
      * @deprecated Cart persistence in mParticle has been deprecated. Please use mParticle.eCommerce.logProductAction(mParticle.ProductActionType.RemoveFromCart, [products])
      */
-    remove: (product: Product, logEventBoolean?: boolean) => void;
+    remove: (product: SDKProduct, logEventBoolean?: boolean) => void;
     /**
      * @deprecated Cart persistence in mParticle has been deprecated.
      */
     clear: () => void;
     /**
      * @deprecated Cart Products have been deprecated
      */
-    getCartProducts: () => Product[];
+    getCartProducts: () => SDKProduct[];
 }
 
 // https://go.mparticle.com/work/SQDSDKS-5033
@@ -36,7 +36,7 @@ export interface IMParticleUser extends User {
     /*
      * @deprecated
      */
-    getCart(): Cart;
+    getCart(): ICart;
 }
 
 export interface ISDKUserIdentity {
diff --git a/src/sdkRuntimeModels.ts b/src/sdkRuntimeModels.ts
@@ -40,6 +40,7 @@ import IntegrationCapture from './integrationCapture';
 import { INativeSdkHelpers } from './nativeSdkHelpers.interfaces';
 import { ICookieSyncManager, IPixelConfiguration } from './cookieSyncManager';
 import { IEvents } from './events.interfaces';
+import { IECommerce, SDKECommerceAPI } from './ecommerce.interfaces';
 
 // TODO: Resolve this with version in @mparticle/web-sdk
 export type SDKEventCustomFlags = Dictionary<any>;
@@ -107,6 +108,11 @@ export interface SDKPromotion {
     Position?: string;
 }
 
+export interface SDKImpression {
+    Name: string;
+    Product: SDKProduct;
+}
+
 export interface SDKProductImpression {
     ProductImpressionList?: string;
     ProductList?: SDKProduct[];
@@ -150,7 +156,9 @@ export interface SDKProduct {
     Position?: number;
     CouponCode?: string;
     TotalAmount?: number;
-    Attributes?: { [key: string]: string };
+
+    // https://go.mparticle.com/work/SQDSDKS-4801
+    Attributes?: Record<string, unknown> | null;
 }
 
 export interface MParticleWebSDK {
@@ -170,6 +178,7 @@ export interface MParticleWebSDK {
     _Forwarders: any;
     _Helpers: SDKHelpersApi;
     _Events: IEvents;
+    _Ecommerce: IECommerce;
     config: SDKInitConfig;
     _ServerModel: IServerModel;
     _SessionManager: ISessionManager;
@@ -208,7 +217,7 @@ export interface MParticleWebSDK {
         eventOptions?: SDKEventOptions
     ): void;
     logBaseEvent(event: BaseEvent, eventOptions?: SDKEventOptions): void;
-    eCommerce: any;
+    eCommerce: SDKECommerceAPI;
     logLevel: string;
     ProductActionType: SDKProductActionType;
     generateHash(value: string): string;
diff --git a/src/sdkToEventsApiConverter.ts b/src/sdkToEventsApiConverter.ts
@@ -373,7 +373,7 @@ export function convertProducts(
             price: sdkProduct.Price,
             quantity: sdkProduct.Quantity,
             coupon_code: sdkProduct.CouponCode,
-            custom_attributes: sdkProduct.Attributes,
+            custom_attributes: sdkProduct.Attributes as Record<string, string>,
         };
         products.push(product);
     }
diff --git a/src/serverModel.ts b/src/serverModel.ts
@@ -110,7 +110,7 @@ export interface IProductV2DTO {
     ps: number;
     cc: string | number;
     tpa: number;
-    attrs: Record<string, string> | null;
+    attrs: Record<string, unknown> | undefined;
 }
 
 export interface IPromotionV2DTO {
diff --git a/test/src/tests-batchUploader_3.ts b/test/src/tests-batchUploader_3.ts
@@ -1,19 +1,13 @@
 import sinon from 'sinon';
 import { urls, apiKey, MPConfig, testMPID } from './config/constants';
 import {
-    BaseEvent,
     MParticleWebSDK,
-    SDKEvent,
-    SDKProductActionType,
 } from '../../src/sdkRuntimeModels';
-import { Batch, CustomEventData } from '@mparticle/event-models';
 import Utils from './config/utils';
-import { BatchUploader } from '../../src/batchUploader';
 import { expect } from 'chai';
 import _BatchValidator from '../../src/mockBatchCreator';
-import Logger from '../../src/logger.js';
-import { event0, event1, event2, event3 } from '../fixtures/events';
 import fetchMock from 'fetch-mock/esm/client';
+import { ProductActionType } from '../../src/types';
 const { fetchMockSuccess, waitForCondition, hasIdentifyReturned  } = Utils;
 
 declare global {
@@ -137,7 +131,7 @@ describe('batch uploader', () => {
             window.mParticle.logEvent('Test Event');
 
             var product1 = window.mParticle.eCommerce.createProduct('iphone', 'iphoneSKU', 999);
-            window.mParticle.eCommerce.logProductAction(SDKProductActionType.AddToCart, product1);
+            window.mParticle.eCommerce.logProductAction(ProductActionType.AddToCart, product1);
 
             const lastCall = fetchMock.lastCall();
             const endpoint = lastCall[0];
diff --git a/test/src/tests-batchUploader_4.ts b/test/src/tests-batchUploader_4.ts
diff --git a/test/src/tests-identities-attributes.ts b/test/src/tests-identities-attributes.ts
diff --git a/test/src/tests-identity.ts b/test/src/tests-identity.ts

Original file line number	Diff line number	Diff line change
`@@ -373,7 +373,7 @@ export function convertProducts(`
`373`	`373`	`price: sdkProduct.Price,`
`374`	`374`	`quantity: sdkProduct.Quantity,`
`375`	`375`	`coupon_code: sdkProduct.CouponCode,`
`376`		`- custom_attributes: sdkProduct.Attributes,`
	`376`	`+ custom_attributes: sdkProduct.Attributes as Record<string, string>,`
`377`	`377`	`};`
`378`	`378`	`products.push(product);`
`379`	`379`	`}`
Original file line number	Diff line number	Diff line change
`@@ -110,7 +110,7 @@ export interface IProductV2DTO {`
`110`	`110`	`ps: number;`
`111`	`111`	`cc: string \| number;`
`112`	`112`	`tpa: number;`
`113`		`- attrs: Record<string, string> \| null;`
	`113`	`+ attrs: Record<string, unknown> \| undefined;`
`114`	`114`	`}`
`115`	`115`
`116`	`116`	`export interface IPromotionV2DTO {`