hubspot-integration-lib

Librería Node.js para integraciones automatizadas entre HubSpot y APIs externas. Permite sincronizar datos bidireccionalmente, ejecutar reglas de negocio condicionales, y realizar polling automático.

🚀 Inicio Rápido

Instalación

npm install hubspot-integration-lib dotenv node-cron

Inicialización del Proyecto

Después de instalar, ejecuta el comando de inicialización para crear automáticamente la estructura estándar:

npx hubspot-integration-init

Este comando creará:

• ✅ integration.config.json - Configuración de la integración
• ✅ .env.example - Ejemplo de variables de entorno
• ✅ src/scheduler.js - Script para ejecutar con cron
• ✅ src/sync-entity.js - Script template para sincronizar entidades
• ✅ .gitignore - Configuración de Git
• ✅ Carpetas src/ y logs/

📚 Documentación

Toda la documentación está disponible en la carpeta docs/:

• Guía de Uso - Guía completa paso a paso para nuevos usuarios
• Documentación Técnica - Información técnica detallada de la librería
• Prompt para Proyectos - Template para generar proyectos de integración
• Guía de Publicación - Cómo publicar nuevas versiones en npm

✨ Características

• ✅ Sincronización bidireccional entre HubSpot y sistemas externos
• ✅ Motor de reglas de negocio configurable vía JSON
• ✅ Polling automático con soporte para cron jobs
• ✅ Múltiples tipos de autenticación (Bearer, API Key, Login, OAuth, Basic)
• ✅ Mapeo flexible de campos entre sistemas
• ✅ Detección automática de cambios antes de actualizar
• ✅ Soporte para objetos asociados (traer Contact asociado a Deal, etc.)
• ✅ Reintentos automáticos en llamadas HTTP
• ✅ Logging estructurado con Winston
• ✅ Soporte para cualquier objeto de HubSpot (deals, contacts, companies, products, objetos personalizados, etc.)

📖 Ejemplo Básico

require('dotenv').config();
const { runIntegration } = require('hubspot-integration-lib');

// Ejecutar integración
const result = await runIntegration();

if (result.success) {
    console.log('✅ Integración exitosa');
    console.log('Resumen:', result.summary);
}

🔧 Configuración

La configuración se realiza completamente vía integration.config.json:

{
  "integrationName": "mi_integracion",
  "direction": "bidirectional",
  "auth": {
    "hubspotToken": "HUBSPOT_API_KEY",
    "externalToken": "EXTERNAL_AUTH",
    "external": {
      "type": "login",
      "login": {
        "endpoint": "${EXTERNAL_BASE_URL}/api/auth/login",
        "usernameKey": "EXTERNAL_USERNAME",
        "passwordKey": "EXTERNAL_PASSWORD"
      }
    }
  },
  "mapping": {
    "deals": {
      "dealname": "nombre",
      "amount": "monto"
    }
  },
  "rules": []
}

📋 Requisitos

• Node.js >= 18.0.0
• Cuenta de HubSpot con API Key
• Acceso a la API externa que quieres integrar

📝 Licencia

MIT

👤 Autor

Vanessa Gustin [email protected]