feat: onboard topsort destination

src/v0/destinations/topsort/config.js

@@ -0,0 +1,30 @@
+const { getMappingConfig } = require('../../util');
+
+const BASE_URL = 'https://api.topsort.com/v2/events';
+
+const ConfigCategories = {
+  TRACK: {
+    type: 'track',
+    name: 'TopsortTrackConfig',
+  },
+  PLACEMENT: { name: 'TopsortPlacementConfig' },
+  ITEM: { name: 'TopsortItemConfig' },
+};
+
+const ECOMM_EVENTS_WITH_PRODUCT_ARRAY = [
+  'Product Clicked',
+  'Product added',
+  'Product Viewed',
+  'Product Removed',
+  'Checkout Started',
+  'Payment Info Entered',
+];
+
+const mappingConfig = getMappingConfig(ConfigCategories, __dirname);
+
+module.exports = {
+  mappingConfig,
+  ConfigCategories,
+  BASE_URL,
+  ECOMM_EVENTS_WITH_PRODUCT_ARRAY,
+};

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

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

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

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

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

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

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

@@ -0,0 +1,30 @@
+[
+  {
+    "destKey": "occurredAt",
+    "sourceKeys": ["originalTimestamp", "timestamp"],
+    "metadata": {
+      "type": "timestamp"
+    },
+    "required": true
+  },
+  {
+    "destKey": "anonymousId",
+    "sourceKeys": "opaqueUserId",
+    "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/transform.js

@@ -0,0 +1,132 @@
+const {
+  InstrumentationError,
+  ConfigurationError,
+  getHashFromArrayWithDuplicate,
+} = require('@rudderstack/integrations-lib');
+const { ConfigCategory, mappingConfig, ECOMM_EVENTS_WITH_PRODUCT_ARRAY } = require('./config');
+const { constructPayload, simpleProcessRouterDest } = require('../../util');
+const {
+  constructItemPayloads,
+  createEventData,
+  isProductArrayValid,
+  getMappedEventName,
+  addFinalPayload,
+} = require('./utils');
+
+// Function to process events with a product array
+const processProductArray = (
+  products,
+  basePayload,
+  placementPayload,
+  topsortEvent,
+  apiKey,
+  finalPayloads,
+) => {
+  const itemPayloads = constructItemPayloads(products, mappingConfig[ConfigCategory.ITEM.name]);
+  itemPayloads.forEach((itemPayload) => {
+    const eventData = createEventData(basePayload, placementPayload, itemPayload, topsortEvent);
+    addFinalPayload(eventData, apiKey, finalPayloads);
+  });
+};
+
+// Function to process events with a single product or no product data
+const processSingleProduct = (
+  basePayload,
+  placementPayload,
+  message,
+  topsortEvent,
+  apiKey,
+  finalPayloads,
+  messageId,
+) => {
+  const itemPayload = constructPayload(message, mappingConfig[ConfigCategory.ITEM.name]);
+  const eventData = createEventData(basePayload, placementPayload, itemPayload, topsortEvent);
+
+  // Ensure messageId is used instead of generating a UUID for single product events
+  eventData.data.id = messageId;
+
+  // Add final payload with appropriate ID and other headers
+  addFinalPayload(eventData, apiKey, finalPayloads);
+};
+
+const responseBuilder = (message, { Config }) => {
+  const { apiKey, topsortEvents } = Config;
+  const { event, properties } = message;
+
+  // Parse Topsort event mappings
+  const parsedTopsortEventMappings = getHashFromArrayWithDuplicate(topsortEvents);
+  const mappedEventName = getMappedEventName(parsedTopsortEventMappings, event);
+
+  if (!mappedEventName) {
+    throw new InstrumentationError("Event not mapped in 'topsortEvents'. Dropping the event.");
+  }
+
+  const topsortEvent = mappedEventName;
+
+  // Construct base and placement payloads
+  const basePayload = constructPayload(message, mappingConfig[ConfigCategory.TRACK.name]);
+  const placementPayload = constructPayload(message, mappingConfig[ConfigCategory.PLACEMENT.name]);
+
+  // Check if the event involves a product array (using ECOMM_EVENTS_WITH_PRODUCT_ARRAY)
+  const isProductArrayAvailable =
+    ECOMM_EVENTS_WITH_PRODUCT_ARRAY.includes(event) && isProductArrayValid(event, properties);
+
+  const finalPayloads = [];
+
+  // Handle events based on the presence of a product array
+  if (isProductArrayAvailable) {
+    processProductArray(
+      properties.products,
+      basePayload,
+      placementPayload,
+      topsortEvent,
+      apiKey,
+      finalPayloads,
+    );
+  } else {
+    processSingleProduct(
+      basePayload,
+      placementPayload,
+      message,
+      topsortEvent,
+      apiKey,
+      finalPayloads,
+    );
+  }
+
+  return finalPayloads;
+};
+
+const processEvent = (message, destination) => {
+  // Check for missing API Key or missing Advertiser ID
+  if (!destination.Config.apiKey) {
+    throw new ConfigurationError('API Key is missing. Aborting message.', 400);
+  }
+  if (!message.type) {
+    throw new InstrumentationError('Message Type is missing. Aborting message.', 400);
+  }
+
+  const messageType = message.type.toLowerCase();
+
+  let response;
+  // Handle 'track' event type
+  if (messageType === 'track') {
+    response = responseBuilder(message, destination); // Call responseBuilder to handle the event
+  } else {
+    throw new InstrumentationError('Only "track" events are supported. Dropping event.', 400);
+  }
+
+  return response;
+};
+
+// Process function that is called per event
+const process = (event) => processEvent(event.message, event.destination);
+
+// Router destination handler to process a batch of events
+const processRouterDest = async (inputs, reqMetadata) => {
+  // Process all events through the simpleProcessRouterDest utility
+  const respList = await simpleProcessRouterDest(inputs, process, reqMetadata);
+  return respList;
+};
+
+module.exports = { process, processRouterDest };

src/v0/destinations/topsort/utils.js

@@ -0,0 +1,61 @@
+const { generateUUID } = require('@rudderstack/integrations-lib');
+const { constructPayload } = require('../../util');
+const { BASE_URL } = require('./config');
+
+// Function to check if a product array is valid
+const isProductArrayValid = (event, properties) =>
+  Array.isArray(properties?.products) && properties?.products.length > 0;
+
+// Function to construct item payloads for each product
+const constructItemPayloads = (products, mappingConfig) =>
+  products.map((product) => constructPayload(product, mappingConfig));
+
+// Function to create a single event data structure
+const createEventData = (basePayload, placementPayload, itemPayload, event) => ({
+  data: {
+    ...basePayload,
+    placement: {
+      ...placementPayload,
+      ...itemPayload,
+    },
+    id: generateUUID(),
+  },
+  event,
+});
+
+// Function to add the structured event data to the final payloads array
+const addFinalPayload = (eventData, apiKey, finalPayloads) => {
+  finalPayloads.push({
+    ...eventData,
+    endpoint: BASE_URL, // Set the destination API URL
+    headers: {
+      'Content-Type': 'application/json',
+      api_key: apiKey, // Add the API key here for authentication
+    },
+  });
+};
+
+// Function to retrieve mapped event name from Topsort event mappings.
+const getMappedEventName = (parsedTopsortEventMappings, event) => {
+  const mappedEventNames = parsedTopsortEventMappings[event];
+
+  // Check if mapping exists
+  if (!mappedEventNames) {
+    throw new Error(`Event '${event}' not found in Topsort event mappings`);
+  }
+
+  // If there are multiple mappings, pick the first one or apply your logic
+  if (Array.isArray(mappedEventNames)) {
+    return mappedEventNames[0]; // Return the first mapping
+  }
+
+  return mappedEventNames; // Return the single mapping if not an array
+};
+
+module.exports = {
+  isProductArrayValid,
+  constructItemPayloads,
+  createEventData,
+  addFinalPayload,
+  getMappedEventName,
+};

src/v0/util/index.js

@@ -970,6 +970,7 @@
     strictMultiMap,
     validateTimestamp,
     allowedKeyCheck,
+    toArray,
   } = metadata;
 
   // if value is null and defaultValue is supplied - use that
@@ -1037,6 +1038,13 @@
     }
   }
 
+  if (toArray) {
+    if (Array.isArray(formattedVal)) {
+      return formattedVal;
+    }
+    return [formattedVal];
+  }
+
   return formattedVal;
 };
 

test/integrations/destinations/topsort/processor/data.ts

@@ -0,0 +1,3 @@
+import { trackTestdata } from './trackTestData';
+
+export const data = [...trackTestdata];