@xenterprises/fastify-xhubspot

Fastify plugin for HubSpot CRM integration — contacts, companies, deals, engagements, and custom objects — for third-party portals and SaaS backends that manage CRM data from their own API. It wraps the official @hubspot/api-client with input validation, consistent error propagation, and optional debug request logging.

Install

npm install @xenterprises/fastify-xhubspot fastify@5

Minimal example

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

const fastify = Fastify();

await fastify.register(xHubspot, {
  apiKey: process.env.HUBSPOT_ACCESS_TOKEN, // consumer owns env access
});

const contact = await fastify.xHubspot.contacts.create({
  email: "[email protected]",
  firstname: "John",
  lastname: "Doe",
});

await fastify.xHubspot.engagement.createNote(contact.id, "Initial onboarding call completed");

Options

| Name | Type | Default | Required | Description | |------|------|---------|----------|-------------| | apiKey | string | — | Yes* | HubSpot Private App access token (pat-na1-...) | | logRequests | boolean | false | No | Log each HubSpot API call at debug level | | client | Client | — | No | Pre-built @hubspot/api-client Client instance (advanced/testing). When provided, apiKey is not required and no client is constructed |

* Required unless client is provided. The plugin never reads process.env; pass configuration in explicitly.

Decorators

fastify.xHubspot

Single namespace exposing:

| Member | Type | Description | |--------|------|-------------| | client | Client | The raw @hubspot/api-client Client instance for direct API access | | contacts | ContactsService | Contact operations | | companies | CompaniesService | Company operations | | deals | DealsService | Deal operations | | engagement | EngagementsService | Notes, tasks, calls, emails | | customObjects | CustomObjectsService | Custom object operations |

fastify.xHubspot.contacts

| Method | Arguments | Returns | Description | |--------|-----------|---------|-------------| | create(data) | CrmProperties | CrmObject | Create a contact | | getById(id, props?) | string, string[] | CrmObject | Get contact by ID | | getByEmail(email, props?) | string, string[] | CrmObject & { email } | Get contact by email | | update(id, props) | string, CrmProperties | CrmObject | Update contact | | delete(id) | string | true | Archive contact | | list(opts?) | { limit?, after?, sort? } | { contacts, paging } | List contacts with pagination | | search(prop, value) | string, string | CrmObject[] | Search by property value | | batchCreate(contacts) | CrmProperties[] | CrmObject[] | Create up to 100 contacts | | batchUpdate(contacts) | { id, properties }[] | CrmObject[] | Update up to 100 contacts | | getAssociations(id, type) | string, string | Association[] | Get associated objects | | associate(id, objectId, type) | string, string, string | true | Create association |

fastify.xHubspot.companies

| Method | Arguments | Returns | Description | |--------|-----------|---------|-------------| | create(data) | CrmProperties | CrmObject | Create a company | | getById(id, props?) | string, string[] | CrmObject | Get company by ID | | getByDomain(domain, props?) | string, string[] | CrmObject | Find company by domain | | update(id, props) | string, CrmProperties | CrmObject | Update company | | delete(id) | string | true | Archive company | | list(opts?) | { limit?, after? } | { companies, paging } | List companies | | search(prop, value) | string, string | CrmObject[] | Search by property | | batchCreate(companies) | CrmProperties[] | CrmObject[] | Create up to 100 | | batchUpdate(companies) | { id, properties }[] | CrmObject[] | Update up to 100 | | getAssociations(id, type) | string, string | Association[] | Get associations |

fastify.xHubspot.deals

| Method | Arguments | Returns | Description | |--------|-----------|---------|-------------| | create(data) | CrmProperties | CrmObject | Create a deal | | getById(id, props?) | string, string[] | CrmObject | Get deal by ID | | update(id, props) | string, CrmProperties | CrmObject | Update deal | | delete(id) | string | true | Archive deal | | list(opts?) | { limit?, after? } | { deals, paging } | List deals | | search(prop, value) | string, string | CrmObject[] | Search by property | | batchCreate(deals) | CrmProperties[] | CrmObject[] | Create up to 100 | | getAssociations(id, type) | string, string | Association[] | Get associations |

fastify.xHubspot.engagement

| Method | Arguments | Returns | Description | |--------|-----------|---------|-------------| | createNote(contactId, body, ownerId?) | string, string, string? | EngagementResult | Create a note | | createTask(contactId, taskData) | string, TaskData | EngagementResult | Create a task | | createCall(contactId, callData) | string, CallData | EngagementResult | Log a call | | createEmail(contactId, emailData) | string, EmailData | EngagementResult | Log an email | | getEngagements(contactId) | string | { engagements, total } | All engagements for contact | | getNotes(contactId, limit?) | string, number? | CrmObject[] | List notes | | getTasks(contactId, limit?) | string, number? | CrmObject[] | List tasks | | getCalls(contactId, limit?) | string, number? | CrmObject[] | List calls | | getEmails(contactId, limit?) | string, number? | CrmObject[] | List emails |

fastify.xHubspot.customObjects

| Method | Arguments | Returns | Description | |--------|-----------|---------|-------------| | create(type, data) | string, CrmProperties | CrmObject | Create custom object | | getById(type, id, props?) | string, string, string[] | CrmObject | Get by ID | | update(type, id, props) | string, string, CrmProperties | CrmObject | Update | | delete(type, id) | string, string | true | Archive | | list(type, opts?) | string, { limit?, after? } | { objects, paging } | List | | search(type, prop, value) | string, string, string | CrmObject[] | Search | | batchCreate(type, objects) | string, CrmProperties[] | CrmObject[] | Batch create | | associate(type, id, toType, toId, assocTypeId?) | string, string, string, string, number? | true | Create association | | getAssociations(type, id, assocType) | string, string, string | Association[] | Get associations |

Routes

None. The plugin adds no routes.

Error behavior

• Registration fails fast on missing/invalid options. Messages name the plugin, the option, and an example:
  • xhubspot: missing required option `apiKey` (string), e.g. `app.register(xHubspot, { apiKey: 'pat-na1-...' })`
  • xhubspot: option `logRequests` must be a boolean, e.g. ...
• Method argument validation throws Errors with an [xHubspot] prefix (e.g. [xHubspot] contacts.getById requires a contactId) before any API call is made.
• HubSpot API errors are re-thrown unchanged after being logged at error level via fastify.log (message only — no tokens or raw SDK error dumps). companies.getByDomain() throws an error with .status = 404 when no company matches.

Requirements

• Node.js >= 20
• Fastify ^5.0.0 (peer dependency)

License

Proprietary — All Rights Reserved X Enterprises. See LICENSE.