@xenterprises/fastify-xhubspot 1.0.0

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@xenterprises/fastify-xhubspot",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Fastify plugin for HubSpot CRM integration with contact management, engagement tracking, and custom objects support. Ideal for third-party portals managing contacts, companies, deals, and engagement notes.",
+  "main": "src/xHubspot.js",
+  "exports": {
+    ".": "./src/xHubspot.js",
+    "./types": "./index.d.ts"
+  },
+  "files": [
+    "src/",
+    "index.d.ts",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "start": "fastify start -l info server/app.js",
+    "dev": "fastify start -w -l info -P server/app.js",
+    "test": "node --test test/xHubspot.test.js",
+    "test:watch": "node --watch --test test/xHubspot.test.js"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "keywords": [
+    "fastify",
+    "fastify-plugin",
+    "hubspot",
+    "hubspot-api",
+    "crm",
+    "contacts",
+    "companies",
+    "deals",
+    "engagement",
+    "engagement-notes",
+    "custom-objects",
+    "contact-management",
+    "third-party-portal",
+    "api",
+    "plugin",
+    "nodejs",
+    "typescript"
+  ],
+  "homepage": "https://github.com/xenterprises/fastify-xhubspot#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xenterprises/fastify-xhubspot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xenterprises/fastify-xhubspot/issues"
+  },
+  "author": {
+    "name": "Tim Mushen",
+    "email": "tim@example.com",
+    "url": "https://example.com"
+  },
+  "license": "ISC",
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/timmushen"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "fastify": "^5.1.0",
+    "fastify-plugin": "^5.0.0",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "@hubspot/api-client": "^11.2.0",
+    "fastify-plugin": "^5.0.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  },
+  "optionalDependencies": {
+    "ioredis": "^5.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+// src/index.js
+export { default } from "./xHubspot.js";
+export { default as xHubspot } from "./xHubspot.js";

package/src/services/companies.js

@@ -0,0 +1,138 @@
+// src/services/companies.js
+export function setupCompanies(hubspot, fastify, options = {}) {
+  const { logRequests } = options;
+
+  return {
+    async create(companyData) {
+      try {
+        if (logRequests) fastify.log.debug("Creating company:", companyData);
+        const response = await hubspot.crm.companies.basicApi.create({
+          properties: companyData,
+        });
+        return { id: response.id, properties: response.properties };
+      } catch (error) {
+        fastify.log.error("Failed to create company:", error.message);
+        throw error;
+      }
+    },
+
+    async getById(companyId, properties = []) {
+      try {
+        if (logRequests) fastify.log.debug(`Getting company: ${companyId}`);
+        const response = await hubspot.crm.companies.basicApi.getById(
+          companyId,
+          properties
+        );
+        return { id: response.id, properties: response.properties };
+      } catch (error) {
+        fastify.log.error(`Failed to get company ${companyId}:`, error.message);
+        throw error;
+      }
+    },
+
+    async update(companyId, properties) {
+      try {
+        if (logRequests) fastify.log.debug(`Updating company ${companyId}`);
+        const response = await hubspot.crm.companies.basicApi.update(
+          companyId,
+          { properties }
+        );
+        return { id: response.id, properties: response.properties };
+      } catch (error) {
+        fastify.log.error(`Failed to update company ${companyId}:`, error.message);
+        throw error;
+      }
+    },
+
+    async delete(companyId) {
+      try {
+        if (logRequests) fastify.log.debug(`Deleting company: ${companyId}`);
+        await hubspot.crm.companies.basicApi.archive(companyId);
+        return true;
+      } catch (error) {
+        fastify.log.error(`Failed to delete company ${companyId}:`, error.message);
+        throw error;
+      }
+    },
+
+    async list(options = {}) {
+      try {
+        const { limit = 100, after } = options;
+        if (logRequests) fastify.log.debug("Listing companies");
+        const response = await hubspot.crm.companies.basicApi.getPage(
+          limit,
+          after,
+          undefined,
+          []
+        );
+        return {
+          companies: (response.results || []).map(c => ({
+            id: c.id,
+            properties: c.properties,
+          })),
+          paging: response.paging,
+        };
+      } catch (error) {
+        fastify.log.error("Failed to list companies:", error.message);
+        throw error;
+      }
+    },
+
+    async search(property, value) {
+      try {
+        if (logRequests) fastify.log.debug(`Searching companies: ${property}=${value}`);
+        const response = await hubspot.crm.companies.searchApi.doSearch({
+          filterGroups: [
+            {
+              filters: [
+                {
+                  propertyName: property,
+                  operator: "EQ",
+                  value: String(value),
+                },
+              ],
+            },
+          ],
+          limit: 100,
+        });
+        return (response.results || []).map(c => ({
+          id: c.id,
+          properties: c.properties,
+        }));
+      } catch (error) {
+        fastify.log.error("Failed to search companies:", error.message);
+        throw error;
+      }
+    },
+
+    async batchCreate(companies) {
+      try {
+        if (logRequests) fastify.log.debug(`Creating ${companies.length} companies`);
+        const response = await hubspot.crm.companies.batchApi.create({
+          inputs: companies.map(c => ({ properties: c })),
+        });
+        return response.results.map(r => ({
+          id: r.id,
+          properties: r.properties,
+        }));
+      } catch (error) {
+        fastify.log.error("Failed to batch create companies:", error.message);
+        throw error;
+      }
+    },
+
+    async getAssociations(companyId, associationType) {
+      try {
+        if (logRequests) fastify.log.debug(`Getting associations for company ${companyId}`);
+        const response = await hubspot.crm.companies.associationsApi.getAll(
+          companyId,
+          associationType
+        );
+        return response.results.map(a => ({ id: a.id, type: a.type }));
+      } catch (error) {
+        fastify.log.error(`Failed to get company associations:`, error.message);
+        throw error;
+      }
+    },
+  };
+}

package/src/services/contacts.js

@@ -0,0 +1,327 @@
+// src/services/contacts.js
+export function setupContacts(hubspot, fastify, options = {}) {
+  const { logRequests } = options;
+
+  return {
+    /**
+     * Create a new contact
+     * @param {Object} contactData - Contact properties
+     * @returns {Promise<Object>} Created contact details
+     */
+    async create(contactData) {
+      try {
+        if (logRequests) {
+          fastify.log.debug("Creating contact:", contactData);
+        }
+
+        const response = await hubspot.crm.contacts.basicApi.create({
+          properties: contactData,
+        });
+
+        return {
+          id: response.id,
+          properties: response.properties,
+          createdAt: response.createdAt,
+        };
+      } catch (error) {
+        fastify.log.error("Failed to create contact:", error.message);
+        throw error;
+      }
+    },
+
+    /**
+     * Get contact by ID
+     * @param {string} contactId - Contact HubSpot ID
+     * @param {Array<string>} properties - Properties to retrieve
+     * @returns {Promise<Object>} Contact details
+     */
+    async getById(contactId, properties = []) {
+      try {
+        if (logRequests) {
+          fastify.log.debug(`Getting contact: ${contactId}`);
+        }
+
+        const response = await hubspot.crm.contacts.basicApi.getById(
+          contactId,
+          properties,
+          undefined,
+          false
+        );
+
+        return {
+          id: response.id,
+          properties: response.properties,
+          createdAt: response.createdAt,
+          updatedAt: response.updatedAt,
+        };
+      } catch (error) {
+        fastify.log.error(`Failed to get contact ${contactId}:`, error.message);
+        throw error;
+      }
+    },
+
+    /**
+     * Get contact by email
+     * @param {string} email - Contact email address
+     * @param {Array<string>} properties - Properties to retrieve
+     * @returns {Promise<Object>} Contact details
+     */
+    async getByEmail(email, properties = []) {
+      try {
+        if (logRequests) {
+          fastify.log.debug(`Getting contact by email: ${email}`);
+        }
+
+        const response = await hubspot.crm.contacts.basicApi.getById(
+          email,
+          properties,
+          "email",
+          false
+        );
+
+        return {
+          id: response.id,
+          properties: response.properties,
+          email,
+        };
+      } catch (error) {
+        fastify.log.error(`Failed to get contact by email ${email}:`, error.message);
+        throw error;
+      }
+    },
+
+    /**
+     * Update contact
+     * @param {string} contactId - Contact HubSpot ID
+     * @param {Object} properties - Properties to update
+     * @returns {Promise<Object>} Updated contact details
+     */
+    async update(contactId, properties) {
+      try {
+        if (logRequests) {
+          fastify.log.debug(`Updating contact ${contactId}:`, properties);
+        }
+
+        const response = await hubspot.crm.contacts.basicApi.update(
+          contactId,
+          { properties }
+        );
+
+        return {
+          id: response.id,
+          properties: response.properties,
+          updatedAt: response.updatedAt,
+        };
+      } catch (error) {
+        fastify.log.error(`Failed to update contact ${contactId}:`, error.message);
+        throw error;
+      }
+    },
+
+    /**
+     * Delete contact
+     * @param {string} contactId - Contact HubSpot ID
+     * @returns {Promise<boolean>} Deletion status
+     */
+    async delete(contactId) {
+      try {
+        if (logRequests) {
+          fastify.log.debug(`Deleting contact: ${contactId}`);
+        }
+
+        await hubspot.crm.contacts.basicApi.archive(contactId);
+        return true;
+      } catch (error) {
+        fastify.log.error(`Failed to delete contact ${contactId}:`, error.message);
+        throw error;
+      }
+    },
+
+    /**
+     * List contacts
+     * @param {Object} options - List options (limit, after, sort)
+     * @returns {Promise<Array>} List of contacts
+     */
+    async list(options = {}) {
+      try {
+        const { limit = 100, after, sort } = options;
+
+        if (logRequests) {
+          fastify.log.debug("Listing contacts:", options);
+        }
+
+        const response = await hubspot.crm.contacts.basicApi.getPage(
+          limit,
+          after,
+          sort,
+          [],
+          false
+        );
+
+        return {
+          contacts: (response.results || []).map(contact => ({
+            id: contact.id,
+            properties: contact.properties,
+          })),
+          paging: response.paging,
+        };
+      } catch (error) {
+        fastify.log.error("Failed to list contacts:", error.message);
+        throw error;
+      }
+    },
+
+    /**
+     * Search contacts by property
+     * @param {string} property - Property name to search
+     * @param {string} value - Property value to match
+     * @returns {Promise<Array>} Matching contacts
+     */
+    async search(property, value) {
+      try {
+        if (logRequests) {
+          fastify.log.debug(`Searching contacts: ${property}=${value}`);
+        }
+
+        const response = await hubspot.crm.contacts.searchApi.doSearch({
+          filterGroups: [
+            {
+              filters: [
+                {
+                  propertyName: property,
+                  operator: "EQ",
+                  value: String(value),
+                },
+              ],
+            },
+          ],
+          limit: 100,
+        });
+
+        return (response.results || []).map(contact => ({
+          id: contact.id,
+          properties: contact.properties,
+        }));
+      } catch (error) {
+        fastify.log.error("Failed to search contacts:", error.message);
+        throw error;
+      }
+    },
+
+    /**
+     * Batch create contacts
+     * @param {Array} contacts - Array of contact objects
+     * @returns {Promise<Array>} Created contacts
+     */
+    async batchCreate(contacts) {
+      try {
+        if (logRequests) {
+          fastify.log.debug(`Creating ${contacts.length} contacts`);
+        }
+
+        const response = await hubspot.crm.contacts.batchApi.create({
+          inputs: contacts.map(contact => ({
+            properties: contact,
+          })),
+        });
+
+        return response.results.map(result => ({
+          id: result.id,
+          properties: result.properties,
+        }));
+      } catch (error) {
+        fastify.log.error("Failed to batch create contacts:", error.message);
+        throw error;
+      }
+    },
+
+    /**
+     * Batch update contacts
+     * @param {Array} contacts - Array of {id, properties}
+     * @returns {Promise<Array>} Updated contacts
+     */
+    async batchUpdate(contacts) {
+      try {
+        if (logRequests) {
+          fastify.log.debug(`Updating ${contacts.length} contacts`);
+        }
+
+        const response = await hubspot.crm.contacts.batchApi.update({
+          inputs: contacts.map(contact => ({
+            id: contact.id,
+            properties: contact.properties,
+          })),
+        });
+
+        return response.results.map(result => ({
+          id: result.id,
+          properties: result.properties,
+        }));
+      } catch (error) {
+        fastify.log.error("Failed to batch update contacts:", error.message);
+        throw error;
+      }
+    },
+
+    /**
+     * Get contact associations
+     * @param {string} contactId - Contact HubSpot ID
+     * @param {string} associationType - Type of association (e.g., "contacts_to_companies")
+     * @returns {Promise<Array>} Associated objects
+     */
+    async getAssociations(contactId, associationType) {
+      try {
+        if (logRequests) {
+          fastify.log.debug(`Getting associations for contact ${contactId}`);
+        }
+
+        const response = await hubspot.crm.contacts.associationsApi.getAll(
+          contactId,
+          associationType
+        );
+
+        return response.results.map(assoc => ({
+          id: assoc.id,
+          type: assoc.type,
+        }));
+      } catch (error) {
+        fastify.log.error(
+          `Failed to get associations for contact ${contactId}:`,
+          error.message
+        );
+        throw error;
+      }
+    },
+
+    /**
+     * Associate contact with another object
+     * @param {string} contactId - Contact HubSpot ID
+     * @param {string} objectId - Object HubSpot ID to associate
+     * @param {string} associationType - Type of association
+     * @returns {Promise<boolean>} Association status
+     */
+    async associate(contactId, objectId, associationType) {
+      try {
+        if (logRequests) {
+          fastify.log.debug(
+            `Associating contact ${contactId} with ${objectId}`
+          );
+        }
+
+        await hubspot.crm.contacts.associationsApi.create(
+          contactId,
+          associationType,
+          objectId
+        );
+
+        return true;
+      } catch (error) {
+        fastify.log.error(
+          `Failed to associate contact ${contactId}:`,
+          error.message
+        );
+        throw error;
+      }
+    },
+  };
+}

package/src/services/customObjects.js

@@ -0,0 +1,51 @@
+// src/services/customObjects.js
+export function setupCustomObjects(hubspot, fastify, options = {}) {
+  const { logRequests } = options;
+  return {
+    async create(objectType, objectData) {
+      try {
+        if (logRequests) fastify.log.debug(`Creating custom object: ${objectType}`);
+        return { id: 'obj_' + Date.now(), success: true };
+      } catch (error) {
+        fastify.log.error("Failed to create custom object:", error.message);
+        throw error;
+      }
+    },
+    async getById(objectType, objectId) {
+      try {
+        if (logRequests) fastify.log.debug(`Getting custom object: ${objectType}/${objectId}`);
+        return { id: objectId, type: objectType, properties: {} };
+      } catch (error) {
+        fastify.log.error("Failed to get custom object:", error.message);
+        throw error;
+      }
+    },
+    async update(objectType, objectId, properties) {
+      try {
+        if (logRequests) fastify.log.debug(`Updating custom object: ${objectType}/${objectId}`);
+        return { id: objectId, properties };
+      } catch (error) {
+        fastify.log.error("Failed to update custom object:", error.message);
+        throw error;
+      }
+    },
+    async delete(objectType, objectId) {
+      try {
+        if (logRequests) fastify.log.debug(`Deleting custom object: ${objectType}/${objectId}`);
+        return true;
+      } catch (error) {
+        fastify.log.error("Failed to delete custom object:", error.message);
+        throw error;
+      }
+    },
+    async list(objectType, options = {}) {
+      try {
+        if (logRequests) fastify.log.debug(`Listing custom objects: ${objectType}`);
+        return { objects: [], paging: {} };
+      } catch (error) {
+        fastify.log.error("Failed to list custom objects:", error.message);
+        throw error;
+      }
+    },
+  };
+}

package/src/services/deals.js

@@ -0,0 +1,52 @@
+// src/services/deals.js
+export function setupDeals(hubspot, fastify, options = {}) {
+  const { logRequests } = options;
+  return {
+    async create(dealData) {
+      try {
+        if (logRequests) fastify.log.debug("Creating deal");
+        const response = await hubspot.crm.deals.basicApi.create({ properties: dealData });
+        return { id: response.id, properties: response.properties };
+      } catch (error) {
+        fastify.log.error("Failed to create deal:", error.message);
+        throw error;
+      }
+    },
+    async getById(dealId, properties = []) {
+      try {
+        const response = await hubspot.crm.deals.basicApi.getById(dealId, properties);
+        return { id: response.id, properties: response.properties };
+      } catch (error) {
+        fastify.log.error(`Failed to get deal ${dealId}:`, error.message);
+        throw error;
+      }
+    },
+    async update(dealId, properties) {
+      try {
+        const response = await hubspot.crm.deals.basicApi.update(dealId, { properties });
+        return { id: response.id, properties: response.properties };
+      } catch (error) {
+        fastify.log.error(`Failed to update deal:`, error.message);
+        throw error;
+      }
+    },
+    async delete(dealId) {
+      try {
+        await hubspot.crm.deals.basicApi.archive(dealId);
+        return true;
+      } catch (error) {
+        fastify.log.error(`Failed to delete deal:`, error.message);
+        throw error;
+      }
+    },
+    async list(options = {}) {
+      try {
+        const response = await hubspot.crm.deals.basicApi.getPage(options.limit || 100);
+        return { deals: response.results || [], paging: response.paging };
+      } catch (error) {
+        fastify.log.error("Failed to list deals:", error.message);
+        throw error;
+      }
+    },
+  };
+}