@xenterprises/fastify-xhubspot 1.0.0

package/index.d.ts

@@ -0,0 +1,829 @@
+// Type definitions for @xenterprises/fastify-xhubspot
+// Project: xHubspot
+// Definitions by: Tim Mushen
+
+import { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+
+/**
+ * ============================================================================
+ * MAIN PLUGIN INTERFACE
+ * ============================================================================
+ */
+
+export interface XHubspotOptions {
+  /**
+   * HubSpot Private App Access Token
+   * Required. Get from: https://app.hubspotbeta.com/l/private-apps
+   * Must have scopes: crm.objects.contacts.read, .write, etc.
+   */
+  apiKey: string;
+
+  /**
+   * Enable detailed request/response logging
+   * Default: false
+   */
+  logRequests?: boolean;
+
+  /**
+   * Log sensitive data (email addresses, phone numbers, etc.)
+   * Default: false
+   * WARNING: Only enable in development
+   */
+  logSensitiveData?: boolean;
+
+  /**
+   * HubSpot API base URL (for custom implementations)
+   * Default: https://api.hubapi.com
+   */
+  baseUrl?: string;
+
+  /**
+   * Request timeout in milliseconds
+   * Default: 30000
+   */
+  requestTimeout?: number;
+
+  /**
+   * Maximum number of retries for failed requests
+   * Default: 3
+   */
+  maxRetries?: number;
+
+  /**
+   * Delay between retries in milliseconds
+   * Default: 1000
+   */
+  retryDelay?: number;
+
+  /**
+   * Rate limit (requests per second)
+   * Default: 10 (free tier)
+   */
+  rateLimit?: number;
+}
+
+/**
+ * ============================================================================
+ * CONTACT SERVICE TYPES
+ * ============================================================================
+ */
+
+export interface ContactProperty {
+  [key: string]: string | number | boolean | null;
+}
+
+export interface Contact {
+  id: string;
+  properties: ContactProperty;
+  associations?: AssociationResponse[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface ContactInput {
+  email?: string;
+  firstname?: string;
+  lastname?: string;
+  phone?: string;
+  hs_lead_status?: string;
+  lifecyclestage?: string;
+  [key: string]: any;
+}
+
+export interface ContactListOptions {
+  limit?: number;
+  after?: string;
+  properties?: string[];
+  searchFilter?: string;
+}
+
+export interface ContactListResponse {
+  results: Contact[];
+  paging?: {
+    next?: {
+      after: string;
+      link: string;
+    };
+  };
+}
+
+export interface ContactBatchInput {
+  id?: string;
+  properties: ContactProperty;
+}
+
+export interface ContactBatchResponse {
+  results: Contact[];
+  errors?: BatchError[];
+}
+
+export interface ContactSearchOptions {
+  property: string;
+  value: string;
+  limit?: number;
+  after?: string;
+  properties?: string[];
+}
+
+export interface ContactsService {
+  /**
+   * Create a new contact in HubSpot
+   * @param contactData - Contact information to create
+   * @returns Created contact with ID and properties
+   * @throws HubSpot API errors
+   */
+  create(contactData: ContactInput): Promise<Contact>;
+
+  /**
+   * Retrieve contact by HubSpot contact ID
+   * @param contactId - HubSpot contact ID
+   * @param properties - Optional array of properties to retrieve
+   * @returns Contact with specified properties
+   * @throws Error if contact not found
+   */
+  getById(contactId: string, properties?: string[]): Promise<Contact>;
+
+  /**
+   * Retrieve contact by email address
+   * Uses email as idempotency key - perfect for third-party portals
+   * @param email - Contact email address
+   * @param properties - Optional array of properties to retrieve
+   * @returns Contact object with email included
+   * @throws Error if contact not found
+   */
+  getByEmail(
+    email: string,
+    properties?: string[]
+  ): Promise<Contact & { email: string }>;
+
+  /**
+   * Update contact properties
+   * @param contactId - HubSpot contact ID
+   * @param properties - Properties to update
+   * @returns Updated contact object
+   * @throws Error if update fails
+   */
+  update(contactId: string, properties: ContactProperty): Promise<Contact>;
+
+  /**
+   * Delete/archive a contact
+   * @param contactId - HubSpot contact ID
+   * @returns Success confirmation
+   * @throws Error if deletion fails
+   */
+  delete(contactId: string): Promise<{ success: boolean }>;
+
+  /**
+   * List all contacts with pagination
+   * @param options - Pagination and filtering options
+   * @returns Paginated contact list
+   */
+  list(options?: ContactListOptions): Promise<ContactListResponse>;
+
+  /**
+   * Search contacts by property value
+   * @param property - Property name to search
+   * @param value - Property value to match
+   * @param options - Optional pagination options
+   * @returns Matching contacts
+   */
+  search(
+    property: string,
+    value: string,
+    options?: ContactListOptions
+  ): Promise<Contact[]>;
+
+  /**
+   * Create multiple contacts in one API call (batch operation)
+   * Maximum 100 contacts per call
+   * @param contacts - Array of contact data (max 100)
+   * @returns Created contacts with IDs
+   * @throws Error if batch exceeds 100 or API fails
+   */
+  batchCreate(contacts: ContactInput[]): Promise<ContactBatchResponse>;
+
+  /**
+   * Update multiple contacts in one API call (batch operation)
+   * Maximum 100 contacts per call
+   * @param contacts - Array of contact updates with IDs (max 100)
+   * @returns Updated contacts
+   * @throws Error if batch exceeds 100 or API fails
+   */
+  batchUpdate(contacts: ContactBatchInput[]): Promise<ContactBatchResponse>;
+
+  /**
+   * Get associated objects (companies, deals, etc.)
+   * @param contactId - HubSpot contact ID
+   * @param associationType - Type of association (companies, deals, etc.)
+   * @returns Array of associated object IDs
+   */
+  getAssociations(
+    contactId: string,
+    associationType: "companies" | "deals" | string
+  ): Promise<Association[]>;
+
+  /**
+   * Associate contact with another object (company, deal, etc.)
+   * @param contactId - HubSpot contact ID
+   * @param objectId - ID of object to associate
+   * @param associationType - Type of association
+   * @returns Success confirmation with association ID
+   */
+  associate(
+    contactId: string,
+    objectId: string,
+    associationType: string
+  ): Promise<{ success: boolean; associationId: string }>;
+}
+
+/**
+ * ============================================================================
+ * COMPANY SERVICE TYPES
+ * ============================================================================
+ */
+
+export interface CompanyProperty {
+  [key: string]: string | number | boolean | null;
+}
+
+export interface Company {
+  id: string;
+  properties: CompanyProperty;
+  associations?: AssociationResponse[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface CompanyInput {
+  name: string;
+  domain?: string;
+  industry?: string;
+  hs_lead_status?: string;
+  lifecyclestage?: string;
+  numberofemployees?: number;
+  [key: string]: any;
+}
+
+export interface CompanyListOptions {
+  limit?: number;
+  after?: string;
+  properties?: string[];
+}
+
+export interface CompanyListResponse {
+  results: Company[];
+  paging?: {
+    next?: {
+      after: string;
+      link: string;
+    };
+  };
+}
+
+export interface CompaniesService {
+  /**
+   * Create a new company in HubSpot
+   * @param companyData - Company information to create
+   * @returns Created company with ID and properties
+   */
+  create(companyData: CompanyInput): Promise<Company>;
+
+  /**
+   * Retrieve company by HubSpot company ID
+   * @param companyId - HubSpot company ID
+   * @param properties - Optional array of properties to retrieve
+   * @returns Company object
+   */
+  getById(companyId: string, properties?: string[]): Promise<Company>;
+
+  /**
+   * Retrieve company by domain name
+   * @param domain - Company domain (e.g., "example.com")
+   * @param properties - Optional array of properties to retrieve
+   * @returns Company object
+   */
+  getByDomain(domain: string, properties?: string[]): Promise<Company>;
+
+  /**
+   * Update company properties
+   * @param companyId - HubSpot company ID
+   * @param properties - Properties to update
+   * @returns Updated company object
+   */
+  update(companyId: string, properties: CompanyProperty): Promise<Company>;
+
+  /**
+   * Delete/archive a company
+   * @param companyId - HubSpot company ID
+   * @returns Success confirmation
+   */
+  delete(companyId: string): Promise<{ success: boolean }>;
+
+  /**
+   * List all companies with pagination
+   * @param options - Pagination and filtering options
+   * @returns Paginated company list
+   */
+  list(options?: CompanyListOptions): Promise<CompanyListResponse>;
+
+  /**
+   * Search companies by property value
+   * @param property - Property name to search
+   * @param value - Property value to match
+   * @returns Matching companies
+   */
+  search(property: string, value: string): Promise<Company[]>;
+
+  /**
+   * Create multiple companies in one API call
+   * @param companies - Array of company data (max 100)
+   * @returns Created companies with IDs
+   */
+  batchCreate(companies: CompanyInput[]): Promise<ContactBatchResponse>;
+
+  /**
+   * Get associated contacts for a company
+   * @param companyId - HubSpot company ID
+   * @returns Array of associated contact IDs
+   */
+  getAssociations(companyId: string): Promise<Association[]>;
+}
+
+/**
+ * ============================================================================
+ * DEAL SERVICE TYPES
+ * ============================================================================
+ */
+
+export interface DealProperty {
+  [key: string]: string | number | boolean | null;
+}
+
+export interface Deal {
+  id: string;
+  properties: DealProperty;
+  associations?: AssociationResponse[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface DealInput {
+  dealname: string;
+  dealstage: string;
+  amount?: number;
+  closedate?: string;
+  [key: string]: any;
+}
+
+export interface DealListOptions {
+  limit?: number;
+  after?: string;
+  properties?: string[];
+  pipelineId?: string;
+}
+
+export interface DealListResponse {
+  results: Deal[];
+  paging?: {
+    next?: {
+      after: string;
+      link: string;
+    };
+  };
+}
+
+export interface DealsService {
+  /**
+   * Create a new deal in HubSpot
+   * @param dealData - Deal information to create
+   * @returns Created deal with ID and properties
+   */
+  create(dealData: DealInput): Promise<Deal>;
+
+  /**
+   * Retrieve deal by HubSpot deal ID
+   * @param dealId - HubSpot deal ID
+   * @param properties - Optional array of properties to retrieve
+   * @returns Deal object
+   */
+  getById(dealId: string, properties?: string[]): Promise<Deal>;
+
+  /**
+   * Update deal properties
+   * @param dealId - HubSpot deal ID
+   * @param properties - Properties to update
+   * @returns Updated deal object
+   */
+  update(dealId: string, properties: DealProperty): Promise<Deal>;
+
+  /**
+   * Delete/archive a deal
+   * @param dealId - HubSpot deal ID
+   * @returns Success confirmation
+   */
+  delete(dealId: string): Promise<{ success: boolean }>;
+
+  /**
+   * List all deals with pagination
+   * @param options - Pagination and filtering options
+   * @returns Paginated deal list
+   */
+  list(options?: DealListOptions): Promise<DealListResponse>;
+
+  /**
+   * Get associated contacts for a deal
+   * @param dealId - HubSpot deal ID
+   * @returns Array of associated contact IDs
+   */
+  getAssociations(dealId: string): Promise<Association[]>;
+}
+
+/**
+ * ============================================================================
+ * ENGAGEMENT SERVICE TYPES
+ * ============================================================================
+ */
+
+export interface EngagementBase {
+  id?: string;
+  type: "NOTE" | "TASK" | "CALL" | "EMAIL";
+  timestamp?: number;
+  ownerId?: string;
+}
+
+export interface NoteInput extends EngagementBase {
+  type: "NOTE";
+  body: string;
+  contactId: string;
+  ownerId?: string;
+}
+
+export interface TaskInput extends EngagementBase {
+  type: "TASK";
+  title: string;
+  body?: string;
+  contactId: string;
+  ownerId?: string;
+  taskStatus?: "NOT_STARTED" | "IN_PROGRESS" | "COMPLETED" | "DEFERRED";
+  priority?: "LOW" | "MEDIUM" | "HIGH";
+  dueDate?: string;
+}
+
+export interface CallInput extends EngagementBase {
+  type: "CALL";
+  contactId: string;
+  callDuration?: number;
+  callResult?: "COMPLETED" | "BUSY" | "NO_ANSWER" | "LEFT_MESSAGE";
+  body?: string;
+  ownerId?: string;
+}
+
+export interface EmailInput extends EngagementBase {
+  type: "EMAIL";
+  contactId: string;
+  subject?: string;
+  body: string;
+  from?: string;
+  to?: string;
+  messageId?: string;
+}
+
+export interface Engagement {
+  id: string;
+  type: string;
+  timestamp: number;
+  contactId: string;
+  ownerId?: string;
+  body?: string;
+  title?: string;
+  [key: string]: any;
+}
+
+export interface EngagementListOptions {
+  contactId: string;
+  limit?: number;
+  offset?: number;
+  type?: "NOTE" | "TASK" | "CALL" | "EMAIL";
+}
+
+export interface EngagementsService {
+  /**
+   * Create an engagement note on a contact
+   * Primary use case for third-party portal interaction tracking
+   * @param contactId - HubSpot contact ID
+   * @param body - Note content/text
+   * @param ownerId - Optional owner ID (defaults to API user)
+   * @returns Created note with ID and timestamp
+   */
+  createNote(
+    contactId: string,
+    body: string,
+    ownerId?: string
+  ): Promise<Engagement>;
+
+  /**
+   * Create an engagement task on a contact
+   * @param contactId - HubSpot contact ID
+   * @param title - Task title
+   * @param options - Optional task details (body, priority, dueDate, etc.)
+   * @returns Created task with ID
+   */
+  createTask(
+    contactId: string,
+    title: string,
+    options?: Partial<TaskInput>
+  ): Promise<Engagement>;
+
+  /**
+   * Create a call engagement on a contact
+   * @param contactId - HubSpot contact ID
+   * @param callResult - Call outcome (COMPLETED, BUSY, NO_ANSWER, LEFT_MESSAGE)
+   * @param options - Optional call details (duration, body, etc.)
+   * @returns Created call engagement
+   */
+  createCall(
+    contactId: string,
+    callResult: string,
+    options?: Partial<CallInput>
+  ): Promise<Engagement>;
+
+  /**
+   * Create an email engagement on a contact
+   * @param contactId - HubSpot contact ID
+   * @param subject - Email subject
+   * @param body - Email body content
+   * @param options - Optional email details (from, to, messageId, etc.)
+   * @returns Created email engagement
+   */
+  createEmail(
+    contactId: string,
+    subject: string,
+    body: string,
+    options?: Partial<EmailInput>
+  ): Promise<Engagement>;
+
+  /**
+   * Retrieve engagements for a contact
+   * @param options - Contact ID and optional filtering
+   * @returns Array of engagement records
+   */
+  getEngagements(options: EngagementListOptions): Promise<Engagement[]>;
+
+  /**
+   * List all notes for a contact
+   * @param contactId - HubSpot contact ID
+   * @param limit - Optional limit (default: 20)
+   * @returns Array of note engagements
+   */
+  getNotes(contactId: string, limit?: number): Promise<Engagement[]>;
+
+  /**
+   * List all tasks for a contact
+   * @param contactId - HubSpot contact ID
+   * @param limit - Optional limit (default: 20)
+   * @returns Array of task engagements
+   */
+  getTasks(contactId: string, limit?: number): Promise<Engagement[]>;
+}
+
+/**
+ * ============================================================================
+ * CUSTOM OBJECTS SERVICE TYPES
+ * ============================================================================
+ */
+
+export interface CustomObjectProperty {
+  [key: string]: string | number | boolean | null;
+}
+
+export interface CustomObject {
+  id: string;
+  objectType: string;
+  properties: CustomObjectProperty;
+  associations?: AssociationResponse[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface CustomObjectInput {
+  objectType: string;
+  properties: CustomObjectProperty;
+}
+
+export interface CustomObjectListOptions {
+  objectType: string;
+  limit?: number;
+  after?: string;
+  properties?: string[];
+}
+
+export interface CustomObjectsService {
+  /**
+   * Create a custom object
+   * @param objectType - Type of custom object
+   * @param properties - Object properties
+   * @returns Created custom object with ID
+   */
+  create(
+    objectType: string,
+    properties: CustomObjectProperty
+  ): Promise<CustomObject>;
+
+  /**
+   * Retrieve custom object by ID
+   * @param objectType - Type of custom object
+   * @param objectId - Custom object ID
+   * @param properties - Optional array of properties to retrieve
+   * @returns Custom object
+   */
+  getById(
+    objectType: string,
+    objectId: string,
+    properties?: string[]
+  ): Promise<CustomObject>;
+
+  /**
+   * Update custom object properties
+   * @param objectType - Type of custom object
+   * @param objectId - Custom object ID
+   * @param properties - Properties to update
+   * @returns Updated custom object
+   */
+  update(
+    objectType: string,
+    objectId: string,
+    properties: CustomObjectProperty
+  ): Promise<CustomObject>;
+
+  /**
+   * Delete custom object
+   * @param objectType - Type of custom object
+   * @param objectId - Custom object ID
+   * @returns Success confirmation
+   */
+  delete(objectType: string, objectId: string): Promise<{ success: boolean }>;
+
+  /**
+   * List custom objects
+   * @param options - Pagination and filtering options
+   * @returns Paginated custom object list
+   */
+  list(options: CustomObjectListOptions): Promise<CustomObjectListResponse>;
+
+  /**
+   * Get associated objects
+   * @param objectType - Type of custom object
+   * @param objectId - Custom object ID
+   * @returns Array of associations
+   */
+  getAssociations(
+    objectType: string,
+    objectId: string
+  ): Promise<Association[]>;
+}
+
+export interface CustomObjectListResponse {
+  results: CustomObject[];
+  paging?: {
+    next?: {
+      after: string;
+      link: string;
+    };
+  };
+}
+
+/**
+ * ============================================================================
+ * ASSOCIATION TYPES
+ * ============================================================================
+ */
+
+export interface Association {
+  id: string;
+  type: string;
+}
+
+export interface AssociationResponse {
+  id: string;
+  type: string;
+  label?: string;
+}
+
+/**
+ * ============================================================================
+ * ERROR TYPES
+ * ============================================================================
+ */
+
+export interface BatchError {
+  status: number;
+  message: string;
+  correlationId?: string;
+}
+
+export interface HubSpotError extends Error {
+  status?: number;
+  message: string;
+  correlationId?: string;
+}
+
+/**
+ * ============================================================================
+ * FASTIFY MODULE AUGMENTATION
+ * ============================================================================
+ */
+
+declare module "fastify" {
+  interface FastifyInstance {
+    /**
+     * HubSpot API client instance
+     * Available when xHubspot plugin is registered
+     */
+    hubspot: any;
+
+    /**
+     * Contacts service - manage HubSpot contacts
+     * Methods: create, getById, getByEmail, update, delete, list, search,
+     *          batchCreate, batchUpdate, getAssociations, associate
+     */
+    contacts: ContactsService;
+
+    /**
+     * Companies service - manage HubSpot companies
+     * Methods: create, getById, getByDomain, update, delete, list, search,
+     *          batchCreate, getAssociations
+     */
+    companies: CompaniesService;
+
+    /**
+     * Deals service - manage HubSpot deals
+     * Methods: create, getById, update, delete, list, getAssociations
+     */
+    deals: DealsService;
+
+    /**
+     * Engagements service - create and retrieve contact engagements
+     * Methods: createNote, createTask, createCall, createEmail, getEngagements,
+     *          getNotes, getTasks
+     */
+    engagement: EngagementsService;
+
+    /**
+     * Custom objects service - manage HubSpot custom objects
+     * Methods: create, getById, update, delete, list, getAssociations
+     */
+    customObjects: CustomObjectsService;
+  }
+}
+
+/**
+ * ============================================================================
+ * PLUGIN EXPORT
+ * ============================================================================
+ */
+
+/**
+ * xHubspot - Fastify plugin for HubSpot CRM integration
+ *
+ * @param fastify - Fastify instance
+ * @param options - Plugin configuration (API key required)
+ *
+ * @example
+ * import Fastify from 'fastify';
+ * import xHubspot from '@xenterprises/fastify-xhubspot';
+ *
+ * const fastify = Fastify();
+ *
+ * await fastify.register(xHubspot, {
+ *   apiKey: process.env.HUBSPOT_ACCESS_TOKEN,
+ *   logRequests: false,
+ *   logSensitiveData: false,
+ * });
+ *
+ * // Now available:
+ * // fastify.contacts - Contact management
+ * // fastify.companies - Company management
+ * // fastify.deals - Deal management
+ * // fastify.engagement - Engagement tracking (notes, tasks, calls, emails)
+ * // fastify.customObjects - Custom object management
+ *
+ * // Create a contact
+ * const contact = await fastify.contacts.create({
+ *   email: 'john@example.com',
+ *   firstname: 'John',
+ *   lastname: 'Doe',
+ * });
+ *
+ * // Create an engagement note on contact
+ * const note = await fastify.engagement.createNote(
+ *   contact.id,
+ *   'Important follow-up needed next week'
+ * );
+ */
+declare function xHubspot(
+  fastify: FastifyInstance,
+  options: XHubspotOptions
+): Promise<void>;
+
+export default xHubspot;
+export { xHubspot };