@skillswaveca/nova-shared-libraries 4.24.0 → 4.26.0

package/packages/drivers/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-drivers",
   "description": "Some helper drivers for AWS services",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "4.24.0",
+  "version": "4.26.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",
@@ -16,17 +16,20 @@
   "devDependencies": {
     "chai": "^5.1.0",
     "eslint": "^9.0.0",
-    "mocha": "^10.4.0"
+    "mocha": "^10.4.0",
+    "sinon": "^21.0.0",
+    "sinon-chai": "^4.0.0"
   },
   "dependencies": {
-    "simple-oauth2": "^5.0.0",
     "@aws-sdk/client-dynamodb": "^3.572.0",
     "@aws-sdk/client-secrets-manager": "^3.572.0",
     "@aws-sdk/client-sqs": "^3.572.0",
     "@aws-sdk/lib-dynamodb": "^3.572.0",
+    "@hubspot/api-client": "^13.0.0",
     "aws-xray-sdk-core": "^3.6.0",
     "lodash.chunk": "^4.2.0",
     "node-fetch": "^3.1.0",
-    "pino": "^9.0.0"
+    "pino": "^9.0.0",
+    "simple-oauth2": "^5.0.0"
   }
 }

package/packages/drivers/src/hubspot.js

@@ -3,6 +3,7 @@ import { Client } from '@hubspot/api-client';
 import log from '../../nova-utils/src/logger.js';
 import { NovaDriver } from './nova-driver.js';
 import { secretsManager } from './aws/secrets-manager.js';
+import { validateEvent, getEventDefinition, getEventMetadata } from '../../nova-utils/src/event-definitions.js';
 
 const HUBSPOT_USER_ATTRIBUTE_MAPPINGS = {
   firstName: 'firstname',
@@ -22,6 +23,7 @@ export class HubSpotDriver extends NovaDriver {
      * @property {Object} hubSpot
      * @property {string} hubSpot.secretName
      * @property {string} hubSpot.secretKeyId
+     * @property {string} hubSpot.accountId
      * @property {string} region
      * @property {string} rootEnvironmentAwsAccountId
      * @property {boolean} enabled
@@ -31,6 +33,7 @@ export class HubSpotDriver extends NovaDriver {
         this._client = null;
         this.secretName = config.hubSpot.secretName;
         this.secretKeyId = config.hubSpot.secretKeyId;
+        this.accountId = config.hubSpot.accountId;
     }
 
     /**
@@ -177,4 +180,47 @@ export class HubSpotDriver extends NovaDriver {
 
         await this._callHubSpot('crm.contacts.basicApi.archive', user.hubSpotContactId);
     }
+
+    /**
+     * Sends a custom event to HubSpot using the event definitions.
+     * This method validates the event data against the predefined schema before sending.
+     * 
+     * @param {string} eventName - The name of the event to send
+     * @param {object} eventData - The event data to send
+     * @returns {Promise<object>} The response from HubSpot API
+     * @throws {Error} If validation fails or HubSpot API returns an error
+     */
+    async sendEvent(eventName, eventData) {
+        try {
+            // Validate the event exists and get its definition
+            const eventDefinition = getEventDefinition(eventName);
+            if (!eventDefinition) {
+                log.error({ eventName }, 'Event definition not found');
+                return;
+            }
+
+            const validatedData = await validateEvent(eventName, eventData);
+
+            const eventMetadata = await getEventMetadata(eventName, validatedData);
+
+            const response = await this._callHubSpot('events.send.basicApi.send', {
+                eventName: `pe${this.accountId}_${eventName}`,
+                properties: validatedData,
+                occurredAt: new Date(),
+                ...eventMetadata,
+            });
+
+            log.debug({ eventName, response }, 'Event sent to HubSpot successfully');
+            return response;
+        } catch (error) {
+            log.error({ 
+                eventName, 
+                eventData, 
+                error: error.message,
+                stack: error.stack 
+            }, 'Unexpected error while sending event');
+            
+            throw error;
+        }
+    }
 }

package/packages/nova-middleware/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-middleware",
   "description": "A collection of middleware used by nova projects",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "4.24.0",
+  "version": "4.26.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",

package/packages/nova-model/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-model",
   "description": "Nova model stuff",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "4.24.0",
+  "version": "4.26.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",

package/packages/nova-router/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-router",
   "description": "An extended Koa router that enables better validation",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "4.24.0",
+  "version": "4.26.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",

package/packages/nova-utils/index.js

@@ -1,4 +1,5 @@
 export * from './src/tenant-utils.js';
 export * from './src/logger.js';
 export * from './src/general.js';
+export * from './src/event-definitions.js';
 export * from './src/config.js';

package/packages/nova-utils/package-lock.json

@@ -0,0 +1,54 @@
+{
+  "name": "@skillswaveca/nova-utils",
+  "version": "4.25.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@skillswaveca/nova-utils",
+      "version": "4.25.0",
+      "license": "UNLICENSED",
+      "dependencies": {
+        "yup": "^1.4.0"
+      },
+      "devDependencies": {}
+    },
+    "node_modules/property-expr": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/property-expr/-/property-expr-2.0.6.tgz",
+      "integrity": "sha512-SVtmxhRE/CGkn3eZY1T6pC8Nln6Fr/lu1mKSgRud0eC73whjGfoAogbn78LkD8aFL0zz3bAFerKSnOl7NlErBA=="
+    },
+    "node_modules/tiny-case": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/tiny-case/-/tiny-case-1.0.3.tgz",
+      "integrity": "sha512-Eet/eeMhkO6TX8mnUteS9zgPbUMQa4I6Kkp5ORiBD5476/m+PIRiumP5tmh5ioJpH7k51Kehawy2UDfsnxxY8Q=="
+    },
+    "node_modules/toposort": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/toposort/-/toposort-2.0.2.tgz",
+      "integrity": "sha512-0a5EOkAUp8D4moMi2W8ZF8jcga7BgZd91O/yabJCFY8az+XSzeGyTKs0Aoo897iV1Nj6guFq8orWDS96z91oGg=="
+    },
+    "node_modules/type-fest": {
+      "version": "2.19.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-2.19.0.tgz",
+      "integrity": "sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==",
+      "engines": {
+        "node": ">=12.20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/yup": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/yup/-/yup-1.6.1.tgz",
+      "integrity": "sha512-JED8pB50qbA4FOkDol0bYF/p60qSEDQqBD0/qeIrUCG1KbPBIQ776fCUNb9ldbPcSTxA69g/47XTo4TqWiuXOA==",
+      "dependencies": {
+        "property-expr": "^2.0.5",
+        "tiny-case": "^1.0.3",
+        "toposort": "^2.0.2",
+        "type-fest": "^2.19.0"
+      }
+    }
+  }
+}

package/packages/nova-utils/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-utils",
   "description": "A collection of random utils used in nova repos",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "4.24.0",
+  "version": "4.26.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",
@@ -14,5 +14,7 @@
   "author": "SkillsWave",
   "license": "UNLICENSED",
   "devDependencies": {},
-  "dependencies": {}
+  "dependencies": {
+    "yup": "^1.4.0"
+  }
 }

package/packages/nova-utils/src/event-definitions.js

@@ -0,0 +1,237 @@
+import * as yup from 'yup';
+
+/**
+ * HubSpot Event Definitions
+ *
+ * This module contains the schema definitions for custom events that can be sent to HubSpot.
+ * Each event definition includes:
+ * - name: The event name used in HubSpot
+ * - description: Human-readable description of the event
+ * - properties: Schema definition for event properties
+ * - validator: Yup validation schema for the event data
+ */
+
+const clientOnboardingCompletedEventDefinition = {
+  name: 'client_onboarding_completed',
+  description: 'Client has finished PLG onboarding and pressed "create workspace."',
+  properties: {
+    email: {
+      type: 'string',
+      required: true,
+      description: 'Email address of the user',
+    },
+    tenant_id: {
+      type: 'string',
+      required: true,
+      description: 'The ID of the tenant that was created',
+    },
+    tenant_name: {
+      type: 'string',
+      required: true,
+      description: 'The name of the tenant that was created',
+    },
+  },
+  validator: yup.object({
+    email: yup.string().email('Must be a valid email').required('Email is required'),
+  }),
+  getMetadata: eventData => {
+    return {
+      email: eventData.email,
+    };
+  },
+};
+
+const usersInvitedEventDefinition = {
+  name: 'users_invited',
+  description: 'PLG Admin has invited one or more users to their workspace.',
+  properties: {
+    email: {
+      type: 'string',
+      required: true,
+      description: 'Email address of the user',
+    },
+    tenant_id: {
+      type: 'string',
+      required: true,
+      description: 'The ID of the tenant that was created',
+    },
+    tenant_name: {
+      type: 'string',
+      required: true,
+      description: 'The name of the tenant that was created',
+    },
+  },
+  validator: yup.object({
+    email: yup.string().email('Must be a valid email').required('Email is required'),
+  }),
+  getMetadata: eventData => {
+    return {
+      email: eventData.email,
+    };
+  },
+};
+
+const creditCardEventDefinition = {
+  name: 'credit_card_added',
+  description: 'PLG Admin added a credit card in Stripe.',
+  properties: {
+    email: {
+      type: 'string',
+      required: true,
+      description: 'Email address of the user',
+    },
+    tenant_id: {
+      type: 'string',
+      required: true,
+      description: 'The ID of the tenant that was created',
+    },
+    tenant_name: {
+      type: 'string',
+      required: true,
+      description: 'The name of the tenant that was created',
+    },
+  },
+  validator: yup.object({
+    email: yup.string().email('Must be a valid email').required('Email is required'),
+  }),
+  getMetadata: eventData => {
+    return {
+      email: eventData.email,
+    };
+  },
+};
+
+const firstRequestSubmittedEventDefinition = {
+  name: 'first_request_submitted',
+  description: 'A user in the PLG workspace has submitted the first request.',
+  properties: {
+    email: {
+      type: 'string',
+      required: true,
+      description: 'Email address of the user',
+    },
+    tenant_id: {
+      type: 'string',
+      required: true,
+      description: 'The ID of the tenant that was created',
+    },
+    tenant_name: {
+      type: 'string',
+      required: true,
+      description: 'The name of the tenant that was created',
+    },
+  },
+  validator: yup.object({
+    email: yup.string().email('Must be a valid email').required('Email is required'),
+  }),
+  getMetadata: eventData => {
+    return {
+      email: eventData.email,
+    };
+  },
+};
+
+const transactionsThresholdMetEventDefinition = {
+  name: 'transactions_threshold_met',
+  description: 'The PLG tenant has completed a specified number of transactions.',
+  properties: {
+    email: {
+      type: 'string',
+      required: true,
+      description: 'Email address of the user',
+    },
+    tenant_id: {
+      type: 'string',
+      required: true,
+      description: 'The ID of the tenant that was created',
+    },
+    tenant_name: {
+      type: 'string',
+      required: true,
+      description: 'The name of the tenant that was created',
+    },
+  },
+  validator: yup.object({
+    email: yup.string().email('Must be a valid email').required('Email is required'),
+  }),
+  getMetadata: eventData => {
+    return {
+      email: eventData.email,
+    };
+  },
+};
+
+/**
+ * Map of all available event definitions
+ * Key: event name, Value: event definition object
+ */
+export const eventDefinitions = {
+  [clientOnboardingCompletedEventDefinition.name]: clientOnboardingCompletedEventDefinition,
+  [usersInvitedEventDefinition.name]: usersInvitedEventDefinition,
+  [creditCardEventDefinition.name]: creditCardEventDefinition,
+  [firstRequestSubmittedEventDefinition.name]: firstRequestSubmittedEventDefinition,
+  [transactionsThresholdMetEventDefinition.name]: transactionsThresholdMetEventDefinition,
+};
+/**
+ * Get event definition by name
+ * @param {string} eventName - The name of the event
+ * @returns {Object|null} The event definition or null if not found
+ */
+export const getEventDefinition = eventName => {
+  return eventDefinitions[eventName] || null;
+};
+
+/**
+ * Get all available event names
+ * @returns {string[]} Array of event names
+ */
+export const getEventNames = () => {
+  return Object.keys(eventDefinitions);
+};
+
+/**
+ * Validate event data against its schema
+ * @param {string} eventName - The name of the event
+ * @param {Object} eventData - The event data to validate
+ * @returns {Promise<Object>} The validated and transformed event data
+ * @throws {Error} If validation fails
+ */
+export const validateEvent = async(eventName, eventData) => {
+  const eventDef = getEventDefinition(eventName);
+
+  if (!eventDef) {
+    return;
+  }
+
+  const validatedData = await eventDef.validator.validate(eventData, {
+    abortEarly: false,
+    stripUnknown: true,
+  });
+
+  return validatedData;
+};
+
+/**
+ * Check if an event name is valid
+ * @param {string} eventName - The name of the event
+ * @returns {boolean} True if the event exists, false otherwise
+ */
+export const isValidEventName = eventName => {
+  return Object.hasOwn(eventDefinitions, eventName);
+};
+
+/**
+ * Gets any event metadata required to send the event to HubSpot.
+ * @param {string} eventName The name of the event
+ * @param {Object} eventData The custom data for the event
+ * @returns {Promise<Object>} The metadata for the event required to send it to HubSpot
+ */
+export const getEventMetadata = async(eventName, eventData) => {
+  const eventDef = getEventDefinition(eventName);
+
+  if (!eventDef || typeof eventDef.getMetadata !== 'function') {
+    return {};
+  }
+
+  return await eventDef.getMetadata(eventData);
+};