@skillswaveca/nova-shared-libraries 4.23.0 → 4.25.0

package/docs-base/package-info.js

@@ -1,31 +1,31 @@
 export const packageInfo = [
   {
     "name": "@skillswaveca/nova-utils",
-    "version": "4.22.0",
+    "version": "4.24.0",
     "description": "A collection of random utils used in nova repos",
     "docsPath": "./nova-utils/index.html"
   },
   {
     "name": "@skillswaveca/nova-router",
-    "version": "4.22.0",
+    "version": "4.24.0",
     "description": "An extended Koa router that enables better validation",
     "docsPath": "./nova-router/index.html"
   },
   {
     "name": "@skillswaveca/nova-model",
-    "version": "4.22.0",
+    "version": "4.24.0",
     "description": "Nova model stuff",
     "docsPath": "./nova-model/index.html"
   },
   {
     "name": "@skillswaveca/nova-middleware",
-    "version": "4.22.0",
+    "version": "4.24.0",
     "description": "A collection of middleware used by nova projects",
     "docsPath": "./nova-middleware/index.html"
   },
   {
     "name": "@skillswaveca/nova-drivers",
-    "version": "4.22.0",
+    "version": "4.24.0",
     "description": "Some helper drivers for AWS services",
     "docsPath": "./drivers/index.html"
   }

package/index.js

@@ -1,6 +1,7 @@
 export * from './packages/nova-utils/src/tenant-utils.js';
 export * from './packages/nova-utils/src/logger.js';
 export * from './packages/nova-utils/src/general.js';
+export * from './packages/nova-utils/src/event-definitions.js';
 export * from './packages/nova-utils/src/config.js';
 export * from './packages/nova-router/src/nova-router.js';
 export * from './packages/nova-middleware/src/oauth-middleware.js';
@@ -9,6 +10,7 @@ export * from './packages/drivers/src/wave.js';
 export * from './packages/drivers/src/oauth.js';
 export * from './packages/drivers/src/nova-driver.js';
 export * from './packages/drivers/src/kraken-driver.js';
+export * from './packages/drivers/src/hubspot.js';
 export * from './packages/drivers/src/http.js';
 export * from './packages/drivers/src/config.js';
 export * from './packages/nova-model/src/stream/nova-stream-task-router.js';

package/package.json

@@ -3,7 +3,7 @@
   "name": "@skillswaveca/nova-shared-libraries",
   "description": "A monorepo of shared libraries for Nova projects.",
   "repository": "https://github.com/SkillsWave/nova-shared-libraries",
-  "version": "4.23.0",
+  "version": "4.25.0",
   "main": "index.js",
   "license": "MIT",
   "keywords": [],
@@ -14,6 +14,7 @@
     "@aws-sdk/client-sqs": "^3.682.0",
     "@aws-sdk/client-ssm": "^3.682.0",
     "@aws-sdk/lib-dynamodb": "^3.682.0",
+    "@hubspot/api-client": "^13.0.0",
     "@koa/router": "^13.1.0",
     "aws-xray-sdk-core": "^3.6.0",
     "jsonwebtoken": "^9.0.2",
@@ -24,7 +25,8 @@
     "pino": "^9.1.0",
     "simple-oauth2": "^5.0.0",
     "uuid": "^9.0.1",
-    "yn": "^5.0.0"
+    "yn": "^5.0.0",
+    "yup": "^1.4.0"
   },
   "devDependencies": {
     "@alpha-lambda/eslint-config": "^2.0.0",

package/packages/drivers/index.js

@@ -2,6 +2,7 @@ export * from './src/wave.js';
 export * from './src/oauth.js';
 export * from './src/nova-driver.js';
 export * from './src/kraken-driver.js';
+export * from './src/hubspot.js';
 export * from './src/http.js';
 export * from './src/config.js';
 export * from './src/aws/sqs.js';

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.23.0",
+  "version": "4.25.0",
   "main": "index.js",
   "scripts": {
     "pre-release": "pnpm run create-index",

package/packages/drivers/src/hubspot.js

@@ -0,0 +1,226 @@
+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',
+  lastName: 'lastname',
+  email: 'email',
+  guid: 'external_id',
+  tenantId: 'tenant_id',
+};
+
+/**
+ * HubSpotDriver class provides methods to interact with HubSpot's CRM API using the HubSpot API client.
+ */
+export class HubSpotDriver extends NovaDriver {
+
+    /**
+     * @param {Object} config
+     * @property {Object} hubSpot
+     * @property {string} hubSpot.secretName
+     * @property {string} hubSpot.secretKeyId
+     * @property {string} hubSpot.accountId
+     * @property {string} region
+     * @property {string} rootEnvironmentAwsAccountId
+     * @property {boolean} enabled
+     */
+    constructor(config) {
+        super(config);
+        this._client = null;
+        this.secretName = config.hubSpot.secretName;
+        this.secretKeyId = config.hubSpot.secretKeyId;
+        this.accountId = config.hubSpot.accountId;
+    }
+
+    /**
+     * Maps a skillswave user to a hubSpot user object.
+     * @param {Object} user
+     * @returns {Object} The mapped HubSpot user object.
+     * @private
+     */
+    _mapToHubSpotUser(user) {
+        const hubSpotUser = {};
+        for (const [key, value] of Object.entries(user)) {
+            if (HUBSPOT_USER_ATTRIBUTE_MAPPINGS[key]) {
+                hubSpotUser[HUBSPOT_USER_ATTRIBUTE_MAPPINGS[key]] = value;
+            }
+        }
+
+        return hubSpotUser;
+    }
+
+    /**
+     * This method retrieves the access token from AWS Secrets Manager and creates a new HubSpot client instance. It will return the existing client if it has already been created.
+     * @returns {Promise<Client>} The HubSpot client instance.
+     * @private
+     */
+    async _getClient() {
+        if (!this._client) {
+            const accessToken = await secretsManager.getSecret(this.secretName, this.secretKeyId, this.config.region, this.config.rootEnvironmentAwsAccountId);
+            const hubSpotClient = new Client({ accessToken });
+
+            this._client = hubSpotClient;
+        }
+
+        return this._client;
+    }
+
+    /**
+     * Calls a HubSpot API method based on the provided method path and arguments.
+     * @param {string|Array<string>} methodPath
+     * @param  {...any} args
+     * @returns {Promise<any>} Returns the raw result from the HubSpot client method.
+     */
+    async _callHubSpot(methodPath, ...args) {
+        if (!this.enabled) {
+            log.warn('HubSpot driver is disabled');
+            return;
+        }
+
+        let client = await this._getClient();
+        if (!client) {
+            log.error('Failed to create HubSpot client');
+            return;
+        }
+
+        const path = Array.isArray(methodPath) ? methodPath : methodPath.split('.');
+        let parent = null;
+        for (const key of path) {
+            if (typeof client[key] === 'undefined') {
+                log.error(`Invalid HubSpot client method path: ${methodPath}`);
+                return;
+            }
+            parent = client;
+            client = client[key];
+        }
+
+        if (typeof client !== 'function') {
+            log.error(`Target at path ${methodPath} is not a function`);
+            return;
+        }
+
+        try {
+            return await client.apply(parent, args.length === 1 ? [args[0]] : args);
+        } catch (e) {
+            log.error({ error: e.message }, `Error calling HubSpot method ${methodPath}`);
+            throw e;
+        }
+    }
+
+    /**
+     * Updates a HubSpot deal with the given properties.
+     * @param {string} dealId 
+     * @param {object} properties 
+     * @returns The updated deal object.
+     */
+    async updateDeal(dealId, properties) {
+        return await this._callHubSpot('crm.deals.basicApi.update', dealId, { properties });
+    }
+
+    /**
+     * Looks up a HubSpot contact ID for a given user. May return multiple IDs.
+     * @param {Object} user 
+     * @returns {Promise<string[]|null>} An array of HubSpot contact IDs or null if no contact is found.
+     */
+    async lookupUserContactId(user) {
+        if (!user.email) {
+            log.error('User email is required for lookup');
+            return;
+        }
+
+        try {
+            const response = await this._callHubSpot('crm.contacts.searchApi.doSearch', {
+                filterGroups: [{
+                    filters: [{
+                        propertyName: 'email',
+                        operator: 'EQ',
+                        value: user.email,
+                    }]
+                }]
+            });
+
+            return response.results.length > 0 ? response.results.map(result => result.id) : [];
+        } catch (error) {
+            log.error({ error }, `Error looking up user ${user.email} in HubSpot`);
+            throw error;
+        }
+    }
+
+    /**
+     * Creates or updates a HubSpot contact. If the provided user has a `hubSpotContactId`, it will update the existing contact; otherwise, it will create a new one.
+     * @param {object} user 
+     * @returns {object} The created/updated HubSpot user.
+     */
+    async upsertUser(user) {
+        const hubSpotUser = this._mapToHubSpotUser(user);
+        let response;
+        if (user.hubSpotContactId) {
+            response = await this._callHubSpot('crm.contacts.basicApi.update', user.hubSpotContactId, { properties: hubSpotUser });
+        } else {
+            response = await this._callHubSpot('crm.contacts.basicApi.create', { properties: hubSpotUser });
+        }
+
+        return { hubSpotContactId: response.id, ...user };
+    }
+
+    /**
+     * Deletes a HubSpot user.
+     * @param {object} user 
+     * @returns {Promise<void>}
+     */
+    async deleteUser(user) {
+        if (!user.hubSpotContactId) {
+            log.error(`User ${user.email} does not have a HubSpot contact ID, skipping deletion.`);
+            return;
+        }
+
+        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.23.0",
+  "version": "4.25.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.23.0",
+  "version": "4.25.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.23.0",
+  "version": "4.25.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.24.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@skillswaveca/nova-utils",
+      "version": "4.24.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.23.0",
+  "version": "4.25.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,104 @@
+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 testEventDefinition = {
+  name: 'hubspot_test_event',
+  description: 'Test event for HubSpot integration',
+  properties: {
+    email: {
+      type: 'string',
+      required: true,
+      description: 'Email address of the user',
+    },
+  },
+  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 = {
+  [testEventDefinition.name]: testEventDefinition,
+};
+
+/**
+ * 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 eventDefinitions.hasOwnProperty(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);
+};