feat: onboard topsort destination (#3913)

* chore: topsort changes

* chore: boilerplates

* chore: topsort changes

* chore: function updates

* chore: product array changes

* chore: purchase event implementation

* chore: purchase function updated

* chore: build finalPayload

* chore: few updations

* chore: mockfn changes

* chore: restructured files
- moved impressions and clicks logic into its own file
- moved purchase related logic into its own file

* chore: update formatting

* chore: test cases added

* chore: destType updated

---------

Co-authored-by: Utsab Chowdhury <[email protected]>
Co-authored-by: Sai Sankeerth <[email protected]>

Author: 3 people

src/features.ts

@@ -93,6 +93,7 @@ const defaultFeaturesConfig: FeaturesConfig = {
     AMAZON_AUDIENCE: true,
     INTERCOM_V2: true,
     LINKEDIN_AUDIENCE: true,
+    TOPSORT: true,
   },
   regulations: [
     'BRAZE',

src/v0/destinations/topsort/config.js

@@ -0,0 +1,31 @@
+const { getMappingConfig } = require('../../util');
+
+const ENDPOINT = 'https://api.topsort.com/v2/events';
+
+const ConfigCategory = {
+  TRACK: {
+    type: 'track',
+    name: 'TopsortTrackConfig',
+  },
+  PLACEMENT: { name: 'TopsortPlacementConfig' },
+  ITEM: { name: 'TopsortItemConfig' },
+  PURCHASE_ITEM: { name: 'TopSortPurchaseProductConfig' },
+};
+
+const ECOMM_EVENTS_WITH_PRODUCT_ARRAY = [
+  'Cart Viewed',
+  'Checkout Started',
+  'Order Updated',
+  'Order Completed',
+  'Order Refunded',
+  'Order Cancelled',
+];
+
+const mappingConfig = getMappingConfig(ConfigCategory, __dirname);
+
+module.exports = {
+  mappingConfig,
+  ConfigCategory,
+  ENDPOINT,
+  ECOMM_EVENTS_WITH_PRODUCT_ARRAY,
+};

src/v0/destinations/topsort/data/TopSortPurchaseProductConfig.json

@@ -0,0 +1,24 @@
+[
+  {
+    "destKey": "productId",
+    "sourceKeys": ["product_id", "properties.product_id"]
+  },
+  {
+    "destKey": "unitPrice",
+    "sourceKeys": ["price", "properties.price"],
+    "metadata": {
+      "type": "toNumber"
+    }
+  },
+  {
+    "destKey": "quantity",
+    "sourceKeys": ["quantity", "properties.quantity"],
+    "metadata": {
+      "toInt": true
+    }
+  },
+  {
+    "destKey": "vendorId",
+    "sourceKeys": "properties.vendorId"
+  }
+]

src/v0/destinations/topsort/data/TopsortItemConfig.json

@@ -0,0 +1,15 @@
+[
+  {
+    "destKey": "position",
+    "sourceKeys": ["properties.position", "position"],
+    "metadata": {
+      "toInt": true
+    },
+    "required": false
+  },
+  {
+    "destKey": "productId",
+    "sourceKeys": ["properties.product_id", "product_id"],
+    "required": false
+  }
+]

src/v0/destinations/topsort/data/TopsortPlacementConfig.json

@@ -0,0 +1,36 @@
+[
+  {
+    "destKey": "path",
+    "sourceKeys": "context.page.path",
+    "required": false
+  },
+  {
+    "destKey": "searchQuery",
+    "sourceKeys": "properties.query",
+    "required": false
+  },
+  {
+    "destKey": "page",
+    "sourceKeys": "properties.pageNumber",
+    "metadata": {
+      "toInt": true
+    },
+    "required": false
+  },
+  {
+    "destKey": "pageSize",
+    "sourceKeys": "properties.pageSize",
+    "metadata": {
+      "toInt": true
+    },
+    "required": false
+  },
+  {
+    "destKey": "categoryIds",
+    "sourceKeys": "properties.category_id",
+    "required": false,
+    "metadata": {
+      "toArray": true
+    }
+  }
+]

src/v0/destinations/topsort/data/TopsortTrackConfig.json

@@ -0,0 +1,27 @@
+[
+  {
+    "destKey": "occurredAt",
+    "sourceKeys": ["timestamp", "originalTimestamp"],
+    "required": true
+  },
+  {
+    "destKey": "opaqueUserId",
+    "sourceKeys": "anonymousId",
+    "required": true
+  },
+  {
+    "destKey": "resolvedBidId",
+    "sourceKeys": "properties.resolvedBidId",
+    "required": false
+  },
+  {
+    "destKey": "entity",
+    "sourceKeys": "properties.entity",
+    "required": false
+  },
+  {
+    "destKey": "additionalAttribution",
+    "sourceKeys": "properties.additionalAttribution",
+    "required": false
+  }
+]

src/v0/destinations/topsort/impressions-and-clicks.js

@@ -0,0 +1,95 @@
+const { ConfigCategory, mappingConfig } = require('./config');
+const { getItemPayloads, addFinalPayload } = require('./utils');
+const { constructPayload, generateUUID } = require('../../util');
+
+const processImpressionsAndClicksUtility = {
+  // Create event data object
+  createEventData(basePayload, placementPayload, itemPayload, event) {
+    return {
+      topsortPayload: {
+        ...basePayload,
+        placement: {
+          ...placementPayload,
+          ...itemPayload,
+        },
+        id: generateUUID(),
+      },
+      event,
+    };
+  },
+
+  // Process events with a product array
+  processProductArray({
+    products,
+    basePayload,
+    placementPayload,
+    topsortEventName,
+    finalPayloads,
+  }) {
+    const itemPayloads = getItemPayloads(products, mappingConfig[ConfigCategory.ITEM.name]);
+    itemPayloads.forEach((itemPayload) => {
+      const eventData = this.createEventData(
+        basePayload,
+        placementPayload,
+        itemPayload,
+        topsortEventName,
+      );
+      addFinalPayload(eventData, finalPayloads);
+    });
+  },
+
+  // Process events with a single product
+  processSingleProduct({
+    basePayload,
+    placementPayload,
+    message,
+    topsortEventName,
+    finalPayloads,
+  }) {
+    const itemPayload = constructPayload(message, mappingConfig[ConfigCategory.ITEM.name]);
+    const eventData = this.createEventData(
+      basePayload,
+      placementPayload,
+      itemPayload,
+      topsortEventName,
+    );
+
+    // Ensure messageId is used instead of generating a UUID for single product events
+    eventData.topsortPayload.id = message.messageId;
+
+    // Add final payload with appropriate ID and other headers
+    addFinalPayload(eventData, finalPayloads);
+  },
+
+  processImpressionsAndClicks({
+    isProductArrayAvailable,
+    basePayload,
+    topsortEventName,
+    finalPayloads,
+    products,
+    message,
+    placementPayload,
+  }) {
+    if (isProductArrayAvailable) {
+      // If product array is available, process the event with multiple products
+      this.processProductArray({
+        basePayload,
+        topsortEventName,
+        finalPayloads,
+        products,
+        placementPayload,
+      });
+    } else {
+      // Otherwise, process the event with a single product
+      this.processSingleProduct({
+        basePayload,
+        topsortEventName,
+        finalPayloads,
+        message,
+        placementPayload,
+      });
+    }
+  },
+};
+
+module.exports = { processImpressionsAndClicksUtility };

src/v0/destinations/topsort/purchase.js

@@ -0,0 +1,56 @@
+const { ConfigCategory, mappingConfig } = require('./config');
+const { getItemPayloads, addFinalPayload } = require('./utils');
+const { constructPayload, generateUUID } = require('../../util');
+
+const processPurchaseEventUtility = {
+  // Create event data object for purchase events
+  createEventData(basePayload, items, event) {
+    return {
+      topsortPayload: {
+        ...basePayload,
+        items,
+        id: generateUUID(),
+      },
+      event,
+    };
+  },
+
+  // Function to process events with a product array for purchase events
+  processProductArray(args) {
+    const { products, basePayload, topsortEventName, finalPayloads } = args;
+    const itemPayloads = getItemPayloads(
+      products,
+      mappingConfig[ConfigCategory.PURCHASE_ITEM.name],
+    );
+    const eventData = this.createEventData(basePayload, itemPayloads, topsortEventName);
+    addFinalPayload(eventData, finalPayloads);
+  },
+
+  // Function to process events with a single product for purchase events
+  processSingleProduct(args) {
+    const { basePayload, message, topsortEventName, finalPayloads } = args;
+    const itemPayload = constructPayload(message, mappingConfig[ConfigCategory.PURCHASE_ITEM.name]);
+    const eventData = this.createEventData(basePayload, [itemPayload], topsortEventName);
+
+    // Ensure messageId is used instead of generating a UUID for single product events
+    eventData.topsortPayload.id = message.messageId;
+
+    // Add final payload with appropriate ID and other headers
+    addFinalPayload(eventData, finalPayloads);
+  },
+
+  // Function to process purchase events (either with a product array or single product)
+  processPurchaseEvent(args) {
+    if (args.isProductArrayAvailable) {
+      // Process the event with multiple products (product array)
+      this.processProductArray(args);
+    } else {
+      // Process the event with a single product
+      this.processSingleProduct(args);
+    }
+  },
+};
+
+module.exports = {
+  processPurchaseEventUtility,
+};