fastify-xhubspot

Full HubSpot CRM integration for Fastify v5. Decorates five service objects (contacts, companies, deals, engagement, customObjects) plus the raw HubSpot SDK client for advanced use.

Installation

npm install @xenterprises/fastify-xhubspot @hubspot/api-client

Quick Start

import Fastify from "fastify";
import xHubspot from "@xenterprises/fastify-xhubspot";

const fastify = Fastify();

await fastify.register(xHubspot, {
  apiKey: process.env.HUBSPOT_API_KEY,
});

fastify.post("/contacts", async (request) => {
  const contact = await fastify.contacts.create({
    email: request.body.email,
    firstname: request.body.firstName,
    lastname: request.body.lastName,
  });
  return contact;
});

await fastify.listen({ port: 3000 });

Options

Decorators

Contacts

• contacts.create — Create a new contact
• contacts.getById / contacts.getByEmail — Fetch a contact by ID or email
• contacts.update — Update contact properties
• contacts.delete — Archive a contact
• contacts.list — Page through all contacts
• contacts.search — Filter contacts by a property value
• contacts.batchCreate / contacts.batchUpdate — Bulk create or update contacts
• contacts.getAssociations / contacts.associate — Read and create contact associations

Companies

• companies.create — Create a new company
• companies.getById / companies.getByDomain — Fetch a company by ID or domain
• companies.update — Update company properties
• companies.delete — Archive a company
• companies.list — Page through all companies
• companies.search — Filter companies by a property value
• companies.batchCreate / companies.batchUpdate — Bulk create or update companies
• companies.getAssociations — Read company associations

Deals

• deals.create — Create a new deal
• deals.getById — Fetch a deal by ID
• deals.update — Update deal properties
• deals.delete — Archive a deal
• deals.list — Page through all deals
• deals.search — Filter deals by a property value
• deals.batchCreate / deals.getAssociations — Bulk create deals and read associations

Engagement

• engagement.createNote — Log a note against a contact
• engagement.createTask — Create a task linked to a contact
• engagement.createCall — Log a call against a contact
• engagement.createEmail — Log an email against a contact
• engagement.getEngagements — List all engagement IDs and types for a contact
• engagement.getNotes — List note engagements for a contact
• engagement.getTasks — List task engagements for a contact
• engagement.getCalls — List call engagements for a contact
• engagement.getEmails — List email engagements for a contact

Custom Objects

• customObjects.create — Create a custom object record
• customObjects.getById — Fetch a custom object by ID
• customObjects.update — Update custom object properties
• customObjects.delete — Archive a custom object record
• customObjects.list — Page through custom object records
• customObjects.search — Filter custom objects by a property value
• customObjects.batchCreate — Bulk create custom object records
• customObjects.associate / customObjects.getAssociations — Create and read custom object associations

Error Reference

All methods throw the original HubSpot API error on failure (the error is logged via fastify.log.error first). Input validation errors throw synchronously before any API call.

Environment Variables

How It Works

At registration the plugin creates a single @hubspot/api-client instance using the provided accessToken, decorates it on fastify.hubspot, then decorates each of the five service objects. Each service wraps the relevant HubSpot v3 CRM API calls with input validation, debug logging (when logRequests: true), and error forwarding. The raw fastify.hubspot client is available for any HubSpot API surface not covered by the service objects.

AI Context

package: "@xenterprises/fastify-xhubspot"
type: fastify-plugin
use-when: HubSpot CRM integration — contacts, companies, deals, engagements, and custom objects
decorators: fastify.hubspot (raw SDK), fastify.contacts, fastify.companies, fastify.deals, fastify.engagement, fastify.customObjects
env: HUBSPOT_API_KEY (Private App access token)
peer-deps: "@hubspot/api-client"
services: contacts, companies, deals, engagement, customObjects — each with create/get/update/delete/list/search/batch/associations