@xenterprises/fastify-xhubspot 1.1.0 → 1.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xenterprises/fastify-xhubspot",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "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": {

package/CHANGELOG.md

@@ -1,295 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
-
-## [1.0.0] - 2025-12-29
-
-### ✨ Initial Release
-
-#### Added
-
-**Core Plugin Features:**
-- Complete Fastify v5 plugin with fastify-plugin integration
-- Lazy initialization of HubSpot client
-- API key validation on startup
-- Comprehensive error handling with correlation IDs
-- Request logging capability with sensitive data masking
-- Module decoration pattern for Fastify instance
-
-**Contact Management Service:**
-- `create(contactData)` - Create individual contacts
-- `getById(contactId, properties)` - Retrieve contact by HubSpot ID
-- `getByEmail(email, properties)` - Retrieve contact by email (idempotent key)
-- `update(contactId, properties)` - Update contact properties
-- `delete(contactId)` - Archive/delete contacts
-- `list(options)` - Paginated contact listing with filtering
-- `search(property, value, options)` - Search contacts by property
-- `batchCreate(contacts)` - Bulk create up to 100 contacts per call
-- `batchUpdate(contacts)` - Bulk update up to 100 contacts per call
-- `getAssociations(contactId, associationType)` - Retrieve associated objects
-- `associate(contactId, objectId, associationType)` - Create associations
-
-**Company Management Service:**
-- `create(companyData)` - Create companies
-- `getById(companyId, properties)` - Retrieve company by ID
-- `getByDomain(domain, properties)` - Retrieve company by domain
-- `update(companyId, properties)` - Update company properties
-- `delete(companyId)` - Archive/delete companies
-- `list(options)` - Paginated company listing
-- `search(property, value)` - Search companies by property
-- `batchCreate(companies)` - Bulk create up to 100 companies
-- `getAssociations(companyId)` - Retrieve associated contacts/deals
-
-**Deal Management Service:**
-- `create(dealData)` - Create deals in HubSpot sales pipeline
-- `getById(dealId, properties)` - Retrieve deal by ID
-- `update(dealId, properties)` - Update deal properties
-- `delete(dealId)` - Archive/delete deals
-- `list(options)` - Paginated deal listing with pipeline filtering
-- `getAssociations(dealId)` - Retrieve associated contacts/companies
-
-**Engagement/Activity Service:**
-- `createNote(contactId, body, ownerId)` - Create engagement notes
-- `createTask(contactId, title, options)` - Create tasks with priority and due dates
-- `createCall(contactId, callResult, options)` - Log call engagements
-- `createEmail(contactId, subject, body, options)` - Log email engagements
-- `getEngagements(options)` - Retrieve contact engagement history
-- `getNotes(contactId, limit)` - Retrieve notes for contact
-- `getTasks(contactId, limit)` - Retrieve tasks for contact
-
-**Custom Objects Service:**
-- `create(objectType, properties)` - Create custom objects
-- `getById(objectType, objectId, properties)` - Retrieve custom objects
-- `update(objectType, objectId, properties)` - Update custom objects
-- `delete(objectType, objectId)` - Delete custom objects
-- `list(options)` - List custom objects with pagination
-- `getAssociations(objectType, objectId)` - Retrieve custom object associations
-
-**Configuration & Environment:**
-- Comprehensive `.env.example` with 100+ configuration options
-- Environment variable support for:
-  - HubSpot API configuration
-  - Contact/company/deal/custom object properties
-  - Batch operation sizes
-  - Rate limiting
-  - Data validation rules
-  - Webhook configuration
-  - Logging levels
-  - Feature flags for selective enablement
-
-**Documentation:**
-- TypeScript definitions (index.d.ts) with full type safety
-- Comprehensive SECURITY.md with 10 security sections:
-  - API key management
-  - Authentication & authorization
-  - Data protection & privacy
-  - Webhook security
-  - Request validation & sanitization
-  - Error handling & logging
-  - Rate limiting & DOS protection
-  - Network security
-  - Third-party portal integration
-  - Compliance & regulations (GDPR, CCPA)
-- CHANGELOG.md tracking all versions
-- LICENSE (ISC)
-
-**Testing:**
-- Basic test structure in place
-- Plugin registration validation
-- Service availability checks
-
-**Docker Support:**
-- Dockerfile with multi-stage build
-- docker-compose.yml configuration
-- .dockerignore file
-
-### 📋 Known Limitations
-
-- Single browser instance for Puppeteer (in future xPDF integration)
-- No connection pooling for HubSpot API (uses single client)
-- Webhook processing is synchronous (async processing recommended for production)
-- No built-in caching (Redis integration recommended for high-volume reads)
-
-### 🔒 Security Features
-
-- API token validation on startup
-- HTTPS enforcement in production
-- Webhook signature validation support
-- Email and phone number validation
-- Blocked email domain configuration
-- Sensitive data logging control
-- Request logging with data masking
-- Rate limiting configuration
-- GDPR/CCPA compliance guidance
-
-### 🚀 Performance Considerations
-
-- Lazy client initialization (creates HubSpot client on first use)
-- Batch operations support (up to 100 items per call)
-- Configurable rate limiting (10-500 req/sec based on tier)
-- Retry logic with exponential backoff
-- Connection reuse for all operations
-
-### 📚 Dependencies
-
-#### Runtime
-- `fastify-plugin`: ^5.0.0
-- `@hubspot/api-client`: ^15.0.0 (or latest)
-
-#### Development
-- `fastify`: ^5.1.0
-- `node`: ^20.0.0
-
----
-
-## [Unreleased] - Future Enhancements
-
-### Planned for v1.1.0
-
-**Features:**
-- [ ] Contact deduplication API
-- [ ] Contact merge functionality
-- [ ] Advanced contact search with filters
-- [ ] Deal pipeline stages API
-- [ ] Deal stage automation
-- [ ] Engagement batch operations
-- [ ] Email template support
-- [ ] SMS integration (via Twilio bridge)
-- [ ] Workflow automation integration
-- [ ] Custom property definitions API
-
-**Performance:**
-- [ ] Connection pooling
-- [ ] Request caching layer
-- [ ] Batch operation queuing
-- [ ] Response compression
-
-**Developer Experience:**
-- [ ] GraphQL support
-- [ ] Webhook sandbox environment
-- [ ] Mock API for testing
-- [ ] CLI tools for bulk operations
-- [ ] Database schema sync utilities
-
-### Planned for v1.2.0
-
-**Features:**
-- [ ] List/segment management
-- [ ] Email campaign integration
-- [ ] Chatbot/conversation API
-- [ ] Landing page management
-- [ ] Form submission handling
-- [ ] Invoice generation
-- [ ] Advanced reporting
-- [ ] Custom field type support
-
-**Compliance:**
-- [ ] HIPAA compliance guidelines
-- [ ] SOC 2 compliance documentation
-- [ ] Data residency options
-- [ ] Encryption at rest
-
-**Infrastructure:**
-- [ ] Kubernetes manifests
-- [ ] Helm charts
-- [ ] Terraform modules
-- [ ] Load balancer configuration
-
-### Planned for v2.0.0 (Major Release)
-
-**Breaking Changes:**
-- Migration to ES modules only (drop CommonJS)
-- Required Node.js 22+
-- Fastify v6+ support
-
-**New Features:**
-- [ ] GraphQL API server
-- [ ] Real-time webhooks with WebSocket
-- [ ] AI-powered contact recommendations
-- [ ] Advanced analytics dashboard
-- [ ] Multi-tenant support
-- [ ] Custom database backends
-
-**Performance:**
-- [ ] Edge function support (Vercel, Cloudflare)
-- [ ] Serverless function optimization
-- [ ] Micro-service architecture support
-
----
-
-## Version History
-
-### v1.0.0 - 2025-12-29
-- ✅ Initial production release
-- ✅ All core features implemented
-- ✅ Full documentation and type definitions
-- ✅ Comprehensive security guidelines
-- ✅ Docker support
-
----
-
-## Migration Guides
-
-### Upgrading from Beta to v1.0.0
-
-No breaking changes - this is the first stable release.
-
-### Future v1.0.0 → v1.1.0 Upgrade
-
-Expected to be non-breaking. No API changes expected.
-
-### Future v1.x → v2.0.0 Upgrade
-
-Will include breaking changes:
-- CommonJS removed (ES modules only)
-- Node.js 22+ required
-- Fastify v6+ required
-- New API design for some services
-
----
-
-## Release Schedule
-
-- **v1.0.0**: 2025-12-29 (Initial release)
-- **v1.1.0**: Estimated Q1 2026
-- **v1.2.0**: Estimated Q2 2026
-- **v2.0.0**: Estimated Q4 2026 (major rewrite)
-
----
-
-## Support & Security Updates
-
-| Version | Release Date | End of Life | Security Updates |
-|---------|------------|----------|-----------------|
-| 1.0.x   | 2025-12-29 | 2027-12-29 | Until EOL       |
-| 1.1.x   | 2026-Q1    | 2027-Q1    | Until EOL       |
-| 2.0.x   | 2026-Q4    | 2028-Q4    | Until EOL       |
-
----
-
-## Contributing
-
-Please follow these guidelines when submitting changes:
-
-1. Reference an issue number in your PR
-2. Include a test for new features
-3. Update CHANGELOG.md in your PR
-4. Follow [Keep a Changelog](https://keepachangelog.com/) format
-5. Use semantic versioning for version bumps
-
----
-
-## Security Announcements
-
-None currently. All security issues should be reported privately to the maintainer.
-
----
-
-**Last Updated:** 2025-12-29
-**Maintainer:** Tim Mushen
-**License:** ISC

package/SECURITY.md

@@ -1,1078 +0,0 @@
-# Security Guidelines for xHubspot
-
-This document provides comprehensive security guidance for using the xHubspot Fastify plugin with HubSpot's CRM API. Follow these guidelines to protect your data and ensure secure integration.
-
-## Table of Contents
-
-1. [API Key Management](#api-key-management)
-2. [Authentication & Authorization](#authentication--authorization)
-3. [Data Protection & Privacy](#data-protection--privacy)
-4. [Webhook Security](#webhook-security)
-5. [Request Validation & Sanitization](#request-validation--sanitization)
-6. [Error Handling & Logging](#error-handling--logging)
-7. [Rate Limiting & DOS Protection](#rate-limiting--dos-protection)
-8. [Network Security](#network-security)
-9. [Third-Party Portal Integration](#third-party-portal-integration)
-10. [Compliance & Regulations](#compliance--regulations)
-
----
-
-## 1. API Key Management
-
-### 1.1 Token Generation & Storage
-
-**DO:**
-- Create Private App Access Tokens with minimal required scopes
-- Store tokens in environment variables (never hardcode)
-- Use `.env.local` for local development (never commit to version control)
-- Rotate tokens every 90 days minimum
-- Use different tokens for development, staging, and production
-
-**DON'T:**
-- Commit `.env` or token files to version control
-- Share tokens via email, Slack, or chat
-- Log tokens in application logs
-- Use the same token across multiple environments
-- Create tokens with all available scopes
-
-### 1.2 Required OAuth Scopes
-
-Only request scopes needed for your use case:
-
-```
-Minimum for contact management:
-- crm.objects.contacts.read
-- crm.objects.contacts.write
-
-Minimum for company/deal management:
-- crm.objects.companies.read
-- crm.objects.companies.write
-- crm.objects.deals.read
-- crm.objects.deals.write
-
-For custom objects:
-- crm.objects.custom.read
-- crm.objects.custom.write
-```
-
-Avoid requesting:
-- `crm.lists.read` / `crm.lists.write` - Only if absolutely necessary
-- `crm.quotes.*` - Unless specifically needed
-- `crm.pipelines.*` - Unless modifying pipelines
-- `actions:*` - Administrative scope
-
-### 1.3 Token Validation
-
-```javascript
-// BAD: Token validation only on startup
-async function xHubspot(fastify, options) {
-  const hubspot = new Client({ accessToken: options.apiKey });
-  // No token validation - fails silently
-}
-
-// GOOD: Comprehensive token validation
-async function xHubspot(fastify, options) {
-  const { apiKey, logRequests = false } = options;
-
-  if (!apiKey || apiKey.trim().length === 0) {
-    throw new Error("HubSpot API Key is required and cannot be empty");
-  }
-
-  if (!apiKey.startsWith("pat-")) {
-    fastify.log.warn("⚠️  Provided API key does not match HubSpot Private App pattern");
-  }
-
-  const hubspot = new Client({ accessToken: apiKey });
-
-  // Test token validity with a minimal read operation
-  try {
-    await hubspot.crm.contacts.basicApi.getPage({ limit: 1 });
-    fastify.log.info("✅ HubSpot API token validated successfully");
-  } catch (error) {
-    if (error.status === 401) {
-      throw new Error("HubSpot API token is invalid or expired");
-    }
-    throw error;
-  }
-}
-```
-
----
-
-## 2. Authentication & Authorization
-
-### 2.1 Access Control in Third-Party Portals
-
-When integrating xHubspot with third-party portals:
-
-```javascript
-// BAD: No authorization checks
-fastify.post("/api/contacts", async (request, reply) => {
-  const contact = await fastify.contacts.create(request.body);
-  return contact;
-});
-
-// GOOD: Verify user authorization
-fastify.post("/api/contacts", async (request, reply) => {
-  // 1. Verify user authentication
-  if (!request.user) {
-    return reply.status(401).send({ error: "Unauthorized" });
-  }
-
-  // 2. Verify user authorization for this operation
-  if (!request.user.permissions.includes("contacts:write")) {
-    return reply.status(403).send({ error: "Forbidden" });
-  }
-
-  // 3. Verify contact ownership/access
-  const contact = await fastify.contacts.create(request.body);
-  return contact;
-});
-```
-
-### 2.2 Role-Based Access Control (RBAC)
-
-Implement granular permission checks:
-
-```javascript
-const permissions = {
-  "contacts:read": ["getById", "getByEmail", "list", "search"],
-  "contacts:write": ["create", "update", "batchCreate", "batchUpdate"],
-  "contacts:delete": ["delete"],
-  "companies:read": ["getById", "list"],
-  "companies:write": ["create", "update"],
-  "engagement:write": ["createNote", "createTask", "createCall", "createEmail"],
-};
-
-// Verify permission before allowing operation
-async function checkPermission(user, service, method) {
-  const allowedServices = permissions[`${service}:write`] || [];
-  if (!allowedServices.includes(method)) {
-    throw new Error(`User lacks permission for ${service}.${method}`);
-  }
-}
-```
-
-### 2.3 Session Management
-
-```javascript
-// Use secure session configuration
-fastify.register(require("@fastify/session"), {
-  secret: process.env.SESSION_SECRET,
-  cookie: {
-    secure: process.env.NODE_ENV === "production", // HTTPS only in production
-    httpOnly: true, // Prevent JavaScript access
-    sameSite: "strict", // CSRF protection
-    maxAge: 3600000, // 1 hour
-  },
-});
-```
-
----
-
-## 3. Data Protection & Privacy
-
-### 3.1 Sensitive Data Handling
-
-**Sensitive fields in HubSpot:**
-- Email addresses
-- Phone numbers
-- Social security numbers
-- Payment card information
-- Home addresses
-
-```javascript
-// BAD: Logging sensitive data
-if (logRequests) {
-  console.log("Creating contact:", contactData);
-  // Outputs: { email: 'john@example.com', phone: '+1234567890' }
-}
-
-// GOOD: Mask sensitive data before logging
-function maskSensitiveData(data) {
-  const masked = { ...data };
-  if (masked.email) {
-    masked.email = masked.email.replace(/(.{2})(.*)(.{2})/, "$1****$3");
-  }
-  if (masked.phone) {
-    masked.phone = masked.phone.replace(/\d(?=\d{4})/g, "*");
-  }
-  return masked;
-}
-
-if (logRequests) {
-  console.log("Creating contact:", maskSensitiveData(contactData));
-  // Outputs: { email: 'jo****om', phone: '****7890' }
-}
-```
-
-### 3.2 Encryption in Transit
-
-```javascript
-// HTTPS is mandatory for all production requests
-const fastify = Fastify({
-  https: {
-    key: fs.readFileSync("./private-key.pem"),
-    cert: fs.readFileSync("./certificate.pem"),
-  },
-});
-
-// Verify TLS version 1.2 minimum
-// Node.js default is TLS 1.2+, but verify in headers
-fastify.register(require("@fastify/helmet"), {
-  contentSecurityPolicy: false,
-  strictTransportSecurity: {
-    maxAge: 31536000, // 1 year
-    includeSubDomains: true,
-    preload: true,
-  },
-});
-```
-
-### 3.3 Data Minimization
-
-Only retrieve properties you need:
-
-```javascript
-// BAD: Request all properties
-const contact = await fastify.contacts.getById(contactId);
-
-// GOOD: Request only necessary properties
-const contact = await fastify.contacts.getById(contactId, [
-  "firstname",
-  "lastname",
-  "email",
-  "phone",
-]);
-```
-
-### 3.4 GDPR & Privacy Compliance
-
-```javascript
-// Right to be forgotten - delete contact data
-async function deleteContact(contactId) {
-  // 1. Log the deletion request for audit trail
-  auditLog.record({
-    action: "DELETE_CONTACT",
-    contactId,
-    timestamp: new Date(),
-    reason: "GDPR Right to Deletion",
-  });
-
-  // 2. Delete from HubSpot
-  await fastify.contacts.delete(contactId);
-
-  // 3. Delete from local cache/database
-  await db.contacts.delete(contactId);
-
-  // 4. Verify deletion
-  try {
-    await fastify.contacts.getById(contactId);
-    throw new Error("Contact deletion failed - data still exists");
-  } catch (error) {
-    if (error.status === 404) {
-      // Expected - contact successfully deleted
-    }
-  }
-}
-
-// Right to access - provide contact data
-async function getContactData(contactId) {
-  const contact = await fastify.contacts.getById(contactId, null);
-  const engagements = await fastify.engagement.getEngagements({
-    contactId,
-  });
-  const associations = await fastify.contacts.getAssociations(contactId);
-
-  return {
-    personalData: contact,
-    engagementHistory: engagements,
-    associations,
-    exportedAt: new Date().toISOString(),
-  };
-}
-```
-
----
-
-## 4. Webhook Security
-
-### 4.1 Webhook Signature Validation
-
-HubSpot signs webhooks with an HMAC-SHA256 signature. Always validate:
-
-```javascript
-import crypto from "crypto";
-
-function validateWebhookSignature(request, secret) {
-  const signature = request.headers["x-hubspot-request-signature"];
-  const timestamp = request.headers["x-hubspot-request-timestamp"];
-
-  if (!signature || !timestamp) {
-    throw new Error("Missing webhook signature or timestamp");
-  }
-
-  // Prevent replay attacks - signature must be recent (within 5 minutes)
-  const webhookTime = parseInt(timestamp);
-  const currentTime = Math.floor(Date.now() / 1000);
-  if (Math.abs(webhookTime - currentTime) > 300) {
-    throw new Error("Webhook timestamp too old - possible replay attack");
-  }
-
-  // Reconstruct the signature
-  const stringToSign = `${timestamp}${JSON.stringify(request.body)}`;
-  const expectedSignature = crypto
-    .createHmac("sha256", secret)
-    .update(stringToSign)
-    .digest("hex");
-
-  // Constant-time comparison to prevent timing attacks
-  if (
-    !crypto.timingSafeEqual(
-      Buffer.from(signature),
-      Buffer.from(expectedSignature)
-    )
-  ) {
-    throw new Error("Invalid webhook signature");
-  }
-
-  return true;
-}
-
-// Usage in Fastify hook
-fastify.post("/webhooks/hubspot", async (request, reply) => {
-  try {
-    validateWebhookSignature(
-      request,
-      process.env.HUBSPOT_WEBHOOK_SECRET
-    );
-  } catch (error) {
-    fastify.log.error("Webhook validation failed:", error.message);
-    return reply.status(401).send({ error: "Unauthorized" });
-  }
-
-  // Process webhook...
-});
-```
-
-### 4.2 Webhook Event Filtering
-
-```javascript
-// Only subscribe to necessary events
-const ALLOWED_EVENTS = [
-  "contact.creation",
-  "contact.change",
-  "deal.creation",
-  "deal.change",
-];
-
-fastify.post("/webhooks/hubspot", async (request, reply) => {
-  const { eventType } = request.body;
-
-  // Reject unexpected events
-  if (!ALLOWED_EVENTS.includes(eventType)) {
-    fastify.log.warn(`Received unexpected event: ${eventType}`);
-    return reply.status(202).send({ received: true });
-  }
-
-  // Process whitelisted events
-  await handleWebhookEvent(request.body);
-  reply.status(200).send({ success: true });
-});
-```
-
-### 4.3 Webhook Processing Best Practices
-
-```javascript
-// BAD: Blocking webhook processing
-fastify.post("/webhooks/hubspot", async (request, reply) => {
-  const result = await processWebhook(request.body); // Takes 30 seconds
-  reply.status(200).send(result);
-});
-
-// GOOD: Async webhook processing with immediate response
-fastify.post("/webhooks/hubspot", async (request, reply) => {
-  // Immediately acknowledge webhook
-  reply.status(202).send({ accepted: true });
-
-  // Process asynchronously in background
-  processWebhookAsync(request.body)
-    .catch((error) => {
-      fastify.log.error("Webhook processing failed:", error);
-      // Log to error tracking service (Sentry, etc.)
-    });
-});
-
-async function processWebhookAsync(event) {
-  // Add to queue for processing
-  await webhookQueue.add(event);
-}
-```
-
----
-
-## 5. Request Validation & Sanitization
-
-### 5.1 Input Validation
-
-```javascript
-import { z } from "zod";
-
-const ContactSchema = z.object({
-  email: z.string().email().optional(),
-  firstname: z.string().max(50).optional(),
-  lastname: z.string().max(50).optional(),
-  phone: z.string().regex(/^\+?[0-9\s\-()]+$/).optional(),
-  hs_lead_status: z.enum(["NEW", "OPEN", "IN_PROGRESS", "OPEN_DEAL"]).optional(),
-});
-
-// Validate before creating contact
-fastify.post("/api/contacts", async (request, reply) => {
-  try {
-    const validatedData = ContactSchema.parse(request.body);
-    const contact = await fastify.contacts.create(validatedData);
-    return contact;
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      return reply.status(400).send({
-        error: "Validation failed",
-        details: error.errors,
-      });
-    }
-    throw error;
-  }
-});
-```
-
-### 5.2 Email Validation
-
-```javascript
-import { z } from "zod";
-
-const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-const BLOCKED_DOMAINS = [
-  "test.com",
-  "example.com",
-  "localhost",
-  "invalid.com",
-];
-
-function validateEmail(email) {
-  if (!EMAIL_REGEX.test(email)) {
-    throw new Error("Invalid email format");
-  }
-
-  const [, domain] = email.split("@");
-  if (BLOCKED_DOMAINS.includes(domain.toLowerCase())) {
-    throw new Error("Email domain is blocked");
-  }
-
-  return true;
-}
-
-// Usage
-fastify.post("/api/contacts", async (request, reply) => {
-  if (request.body.email) {
-    validateEmail(request.body.email);
-  }
-  const contact = await fastify.contacts.create(request.body);
-  return contact;
-});
-```
-
-### 5.3 Phone Number Validation
-
-```javascript
-import libphonenumber from "libphonenumber-js";
-
-function validatePhoneNumber(phone, defaultCountry = "US") {
-  try {
-    const number = libphonenumber(phone, defaultCountry);
-    if (!number || !number.isValid()) {
-      throw new Error("Invalid phone number");
-    }
-    return number.format("E.164"); // +1234567890
-  } catch (error) {
-    throw new Error("Phone number validation failed");
-  }
-}
-
-// Usage
-fastify.post("/api/contacts", async (request, reply) => {
-  if (request.body.phone) {
-    request.body.phone = validatePhoneNumber(request.body.phone);
-  }
-  const contact = await fastify.contacts.create(request.body);
-  return contact;
-});
-```
-
-### 5.4 SQL/NoSQL Injection Prevention
-
-Use the HubSpot client library properly - never build queries manually:
-
-```javascript
-// BAD: Manual query building (never do this)
-const query = `contacts with email = '${userInput}'`;
-
-// GOOD: Use library's built-in methods
-const contact = await fastify.contacts.getByEmail(userInput);
-
-// GOOD: Use proper filtering with the API
-const contacts = await fastify.contacts.search("email", userInput);
-```
-
----
-
-## 6. Error Handling & Logging
-
-### 6.1 Secure Error Messages
-
-```javascript
-// BAD: Exposing internal error details
-fastify.post("/api/contacts", async (request, reply) => {
-  try {
-    const contact = await fastify.contacts.create(request.body);
-    return contact;
-  } catch (error) {
-    return reply.status(500).send({
-      error: error.message, // Exposes HubSpot API details!
-      stack: error.stack,   // Exposes internal paths
-    });
-  }
-});
-
-// GOOD: Generic user-facing errors with detailed internal logging
-fastify.post("/api/contacts", async (request, reply) => {
-  try {
-    const contact = await fastify.contacts.create(request.body);
-    return contact;
-  } catch (error) {
-    // Log full details for debugging
-    fastify.log.error({
-      message: "Contact creation failed",
-      error: error.message,
-      stack: error.stack,
-      correlationId: error.correlationId,
-    });
-
-    // Return generic error to user
-    const status = error.status || 500;
-    return reply.status(status).send({
-      error: "An error occurred. Please contact support.",
-      correlationId: error.correlationId, // For support inquiries
-    });
-  }
-});
-```
-
-### 6.2 Structured Logging
-
-```javascript
-// Use structured logging for security events
-function logSecurityEvent(fastify, event, details) {
-  fastify.log.info({
-    type: "SECURITY_EVENT",
-    event,
-    timestamp: new Date().toISOString(),
-    ...details,
-  });
-}
-
-// Usage
-if (!request.user) {
-  logSecurityEvent(fastify, "UNAUTHORIZED_ACCESS", {
-    endpoint: request.url,
-    ip: request.ip,
-    headers: request.headers,
-  });
-  return reply.status(401).send({ error: "Unauthorized" });
-}
-
-if (!hasPermission) {
-  logSecurityEvent(fastify, "FORBIDDEN_ACCESS", {
-    userId: request.user.id,
-    endpoint: request.url,
-    requiredPermission,
-    userPermissions: request.user.permissions,
-  });
-  return reply.status(403).send({ error: "Forbidden" });
-}
-```
-
-### 6.3 Never Log Sensitive Data
-
-```javascript
-// Configuration for xHubspot
-const config = {
-  apiKey: process.env.HUBSPOT_ACCESS_TOKEN,
-  logRequests: process.env.HUBSPOT_LOG_REQUESTS === "true",
-  logSensitiveData: false, // ALWAYS false in production
-};
-
-// Sensitive fields to never log
-const SENSITIVE_FIELDS = [
-  "email",
-  "phone",
-  "ssn",
-  "creditcard",
-  "bankaccount",
-  "password",
-  "apiKey",
-  "accessToken",
-];
-
-function sanitizeForLogging(data) {
-  const sanitized = JSON.parse(JSON.stringify(data));
-
-  function mask(obj) {
-    if (typeof obj !== "object" || obj === null) return;
-    for (const key in obj) {
-      if (SENSITIVE_FIELDS.some((field) => key.toLowerCase().includes(field))) {
-        obj[key] = "***REDACTED***";
-      } else if (typeof obj[key] === "object") {
-        mask(obj[key]);
-      }
-    }
-  }
-
-  mask(sanitized);
-  return sanitized;
-}
-```
-
----
-
-## 7. Rate Limiting & DOS Protection
-
-### 7.1 HubSpot API Rate Limiting
-
-```javascript
-// Configure rate limiting based on your HubSpot tier
-const RATE_LIMITS = {
-  free: 10, // requests per second
-  professional: 100,
-  enterprise: 500,
-};
-
-// Use the configured rate limit
-const config = {
-  rateLimit: process.env.HUBSPOT_RATE_LIMIT || RATE_LIMITS.free,
-  maxRetries: parseInt(process.env.HUBSPOT_MAX_RETRIES || "3"),
-  retryDelay: parseInt(process.env.HUBSPOT_RETRY_DELAY || "1000"),
-};
-
-// Implement backoff strategy for rate limit errors
-async function withRetry(fn, maxRetries = 3) {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      if (error.status === 429) {
-        // Rate limited
-        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
-        fastify.log.warn(
-          `Rate limited. Retrying after ${delay}ms (attempt ${attempt}/${maxRetries})`
-        );
-        await new Promise((resolve) => setTimeout(resolve, delay));
-      } else {
-        throw error;
-      }
-    }
-  }
-}
-```
-
-### 7.2 Application-Level Rate Limiting
-
-```javascript
-import fastifyRateLimit from "@fastify/rate-limit";
-
-fastify.register(fastifyRateLimit, {
-  max: 100, // Max requests per window
-  timeWindow: "15 minutes",
-  cache: 10000, // Number of records to store
-  allowList: ["127.0.0.1"], // Whitelist IPs
-  redis: process.env.REDIS_URL, // Optional: use Redis for distributed rate limiting
-});
-```
-
-### 7.3 Batch Operation Limits
-
-```javascript
-// Enforce HubSpot's batch limits
-const BATCH_SIZE_LIMITS = {
-  contacts: 100,
-  companies: 100,
-  deals: 100,
-};
-
-fastify.post("/api/contacts/batch", async (request, reply) => {
-  const { contacts } = request.body;
-
-  if (!Array.isArray(contacts)) {
-    return reply.status(400).send({ error: "Expected array of contacts" });
-  }
-
-  if (contacts.length > BATCH_SIZE_LIMITS.contacts) {
-    return reply.status(400).send({
-      error: `Batch size exceeds maximum of ${BATCH_SIZE_LIMITS.contacts}`,
-    });
-  }
-
-  const result = await fastify.contacts.batchCreate(contacts);
-  return result;
-});
-```
-
----
-
-## 8. Network Security
-
-### 8.1 CORS Configuration
-
-```javascript
-import fastifyCors from "@fastify/cors";
-
-fastify.register(fastifyCors, {
-  origin: process.env.ALLOWED_ORIGINS?.split(",") || ["https://app.example.com"],
-  credentials: true,
-  methods: ["GET", "POST", "PUT", "DELETE"],
-  allowedHeaders: ["Content-Type", "Authorization"],
-});
-```
-
-### 8.2 HTTPS Enforcement
-
-```javascript
-fastify.register(require("@fastify/helmet"), {
-  strictTransportSecurity: {
-    maxAge: 31536000,
-    includeSubDomains: true,
-    preload: true,
-  },
-  frameguard: {
-    action: "deny", // Prevent clickjacking
-  },
-  noSniff: true,
-  xssFilter: true,
-});
-
-// Redirect HTTP to HTTPS in production
-if (process.env.NODE_ENV === "production") {
-  fastify.register(require("@fastify/https-redirect"));
-}
-```
-
-### 8.3 VPN/IP Whitelisting
-
-```javascript
-// Optional: Restrict API access to specific IPs
-const ALLOWED_IPS = (process.env.HUBSPOT_ALLOWED_IPS || "").split(",").filter(Boolean);
-
-fastify.addHook("preHandler", async (request, reply) => {
-  if (ALLOWED_IPS.length > 0) {
-    const clientIP = request.ip;
-    if (!ALLOWED_IPS.includes(clientIP)) {
-      fastify.log.warn(`Access denied from IP: ${clientIP}`);
-      return reply.status(403).send({ error: "Forbidden" });
-    }
-  }
-});
-```
-
----
-
-## 9. Third-Party Portal Integration
-
-### 9.1 Portal Authentication
-
-```javascript
-// Implement JWT-based authentication for portal
-import jwt from "@fastify/jwt";
-
-fastify.register(jwt, {
-  secret: process.env.JWT_SECRET,
-  sign: { expiresIn: "24h" },
-});
-
-// Login endpoint
-fastify.post("/auth/login", async (request, reply) => {
-  const { username, password } = request.body;
-
-  // Verify credentials (example with bcrypt)
-  const user = await verifyCredentials(username, password);
-
-  if (!user) {
-    return reply.status(401).send({ error: "Invalid credentials" });
-  }
-
-  const token = fastify.jwt.sign({
-    userId: user.id,
-    username: user.username,
-    permissions: user.permissions,
-  });
-
-  return { token };
-});
-
-// Protect routes with authentication
-fastify.post("/api/contacts", async (request, reply) => {
-  try {
-    await request.jwtVerify();
-  } catch (error) {
-    return reply.status(401).send({ error: "Unauthorized" });
-  }
-
-  const contact = await fastify.contacts.create(request.body);
-  return contact;
-});
-```
-
-### 9.2 Portal Data Isolation
-
-```javascript
-// Ensure portal users only access their own data
-async function getPortalUserContacts(userId) {
-  // Get contacts associated with this portal user
-  const contacts = await db.contacts.find({ portalUserId: userId });
-  return contacts;
-}
-
-// Verify access before returning data
-fastify.get("/api/contacts/:id", async (request, reply) => {
-  const { id } = request.params;
-  const { userId } = request.user;
-
-  const contact = await fastify.contacts.getById(id);
-
-  // Verify the user owns this contact
-  const ownership = await db.contacts.verify(id, userId);
-  if (!ownership) {
-    return reply.status(403).send({ error: "Forbidden" });
-  }
-
-  return contact;
-});
-```
-
-### 9.3 Audit Logging for Portal Actions
-
-```javascript
-// Log all portal actions for compliance
-async function logPortalAction(userId, action, resourceId, details) {
-  await db.auditLog.create({
-    userId,
-    action,
-    resourceId,
-    timestamp: new Date(),
-    ipAddress: details.ip,
-    userAgent: details.userAgent,
-    changes: details.changes,
-  });
-}
-
-fastify.post("/api/contacts", async (request, reply) => {
-  const contact = await fastify.contacts.create(request.body);
-
-  await logPortalAction(request.user.id, "CREATE_CONTACT", contact.id, {
-    ip: request.ip,
-    userAgent: request.headers["user-agent"],
-    changes: request.body,
-  });
-
-  return contact;
-});
-```
-
----
-
-## 10. Compliance & Regulations
-
-### 10.1 GDPR Compliance
-
-**Data Processing Agreement (DPA):**
-- Ensure you have a DPA with HubSpot
-- Document all data processing activities
-- Implement data retention policies
-
-**User Rights:**
-- **Right to Access:** Implement endpoint to export user data
-- **Right to Erasure:** Implement contact deletion with audit trail
-- **Right to Rectification:** Allow contact data updates
-- **Right to Data Portability:** Export contact data in standard format
-
-```javascript
-// Implement GDPR data export endpoint
-fastify.get("/api/user/data-export", async (request, reply) => {
-  const userId = request.user.id;
-
-  // Gather all user data
-  const contactData = await getContactData(userId);
-  const engagementData = await getEngagementData(userId);
-  const auditLog = await getAuditLog(userId);
-
-  // Return as JSON for portability
-  return {
-    exportDate: new Date().toISOString(),
-    dataSubject: userId,
-    contacts: contactData,
-    engagements: engagementData,
-    auditLog,
-  };
-});
-
-// Implement right to erasure
-fastify.delete("/api/user/data", async (request, reply) => {
-  const userId = request.user.id;
-
-  // Request confirmation
-  if (!request.body.confirmDeletion) {
-    return reply.status(400).send({
-      error: "Data deletion must be confirmed",
-    });
-  }
-
-  // Log deletion request
-  await logPortalAction(userId, "DATA_DELETION_REQUEST", userId, {
-    ip: request.ip,
-    reason: "GDPR Right to Erasure",
-  });
-
-  // Delete all associated data
-  const contacts = await getPortalUserContacts(userId);
-  for (const contact of contacts) {
-    await fastify.contacts.delete(contact.id);
-  }
-
-  await db.user.delete(userId);
-
-  return { success: true, message: "All data has been deleted" };
-});
-```
-
-### 10.2 CCPA Compliance (California)
-
-Similar to GDPR but with specific timeline requirements:
-- Must provide data access within 45 days
-- Must allow "Do Not Sell My Personal Information" opt-out
-- Must not discriminate against users exercising rights
-
-### 10.3 Data Retention Policies
-
-```javascript
-// Implement automatic data retention/deletion
-const DATA_RETENTION_DAYS = parseInt(process.env.DATA_RETENTION_DAYS || "365");
-
-async function purgeOldContacts() {
-  const cutoffDate = new Date();
-  cutoffDate.setDate(cutoffDate.getDate() - DATA_RETENTION_DAYS);
-
-  const oldContacts = await db.contacts.find({
-    lastInteraction: { $lt: cutoffDate },
-    markedForDeletion: true,
-  });
-
-  for (const contact of oldContacts) {
-    await fastify.contacts.delete(contact.hubspotId);
-    await db.contacts.delete(contact.id);
-  }
-}
-
-// Run daily via cron job
-schedule.scheduleJob("0 2 * * *", purgeOldContacts); // 2 AM daily
-```
-
-### 10.4 Compliance Monitoring
-
-```javascript
-// Monitor for compliance violations
-async function monitorCompliance() {
-  // Check for suspicious activity
-  const suspiciousActivity = await db.auditLog.find({
-    action: "DELETE_CONTACT",
-    timestamp: { $gte: new Date(Date.now() - 24 * 60 * 60 * 1000) },
-  });
-
-  if (suspiciousActivity.length > 100) {
-    // Alert security team
-    await sendSecurityAlert({
-      type: "HIGH_DELETION_VOLUME",
-      count: suspiciousActivity.length,
-      period: "24 hours",
-    });
-  }
-
-  // Check for compliance violations
-  const unencryptedTokens = await db.config.find({
-    field: "apiKey",
-    encrypted: false,
-  });
-
-  if (unencryptedTokens.length > 0) {
-    await sendSecurityAlert({
-      type: "UNENCRYPTED_SECRETS",
-      count: unencryptedTokens.length,
-    });
-  }
-}
-```
-
----
-
-## Security Checklist
-
-Before deploying to production:
-
-- [ ] API key stored in environment variable, not hardcoded
-- [ ] Token rotation scheduled (every 90 days)
-- [ ] HTTPS/TLS enabled for all connections
-- [ ] Webhook signature validation implemented
-- [ ] Input validation and sanitization for all endpoints
-- [ ] Error messages don't expose internal details
-- [ ] Sensitive data never logged
-- [ ] Authentication and authorization implemented
-- [ ] Rate limiting configured
-- [ ] CORS configured with specific allowed origins
-- [ ] CSRF protection enabled
-- [ ] Audit logging implemented
-- [ ] Database backups configured
-- [ ] Security headers (CSP, HSTS, etc.) configured
-- [ ] Third-party dependencies up to date
-- [ ] Security testing completed
-- [ ] Incident response plan documented
-- [ ] Compliance requirements identified and implemented
-- [ ] Data retention policy defined
-- [ ] Privacy policy updated and compliant
-
----
-
-## Incident Response
-
-If you suspect a security incident:
-
-1. **Immediately revoke the compromised API token** in HubSpot admin
-2. **Generate a new API token** with same scopes
-3. **Update environment variables** with new token
-4. **Review audit logs** for unauthorized access
-5. **Notify affected users** if personal data was exposed
-6. **File required notifications** with regulators (GDPR/CCPA)
-7. **Conduct root cause analysis** to prevent future incidents
-8. **Document incident** for compliance records
-
----
-
-## Additional Resources
-
-- [HubSpot API Security](https://developers.hubspot.com/docs/api/overview)
-- [OWASP Top 10](https://owasp.org/Top10/)
-- [GDPR Compliance Guide](https://gdpr-info.eu/)
-- [CCPA Compliance Guide](https://www.ccpa.ca.gov/)
-- [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)
-- [Fastify Security](https://www.fastify.io/docs/latest/Guides/Security/)
-
----
-
-**Last Updated:** 2025-12-29
-**Maintainer:** Tim Mushen
-**License:** ISC