tracking-crm-core/README.md

Framework simplificado y robusto de tracking CRM - Sistema modular para tracking de visitantes, sesiones, eventos y captura de leads optimizado para navegadores

# tracking-crm-core

Framework modular de tracking y CRM para aplicaciones web. **Completamente agnóstico respecto al backend** - envía datos estructurados a cualquier endpoint que configures: tu propia API, N8N, Zapier, base de datos directa, o cualquier webhook.

## 🚀 Instalación

```bash
npm install tracking-crm-core
```

## 🎯 Filosofía del Framework

Este framework se enfoca en **capturar y estructurar datos de tracking correctamente**, dejando que **tú decidas dónde y cómo procesarlos**. No estás limitado a ninguna herramienta específica.

### ✅ Lo que hace el framework:
- Captura eventos de usuarios (clicks, formularios, navegación)
- Gestiona sesiones y tracking de comportamiento
- Estructura payloads de datos consistentes
- Envía datos a los endpoints que configures
- Proporciona APIs simples y tipadas

### 🎨 Lo que decides tú:
- Dónde enviar los datos (tu API, N8N, webhooks, etc.)
- Cómo procesar y almacenar la información
- Qué hacer con los datos (CRM, analytics, etc.)
- Integración con tu stack tecnológico

## 📦 Uso Básico

### Con tu propia API

```typescript
import { createTrackingFramework, PRESET_CONFIGS } from 'tracking-crm-core';

const tracker = createTrackingFramework({
  businessId: 'mi-empresa',
  environment: 'production',
  endpoints: {
    baseUrl: 'https://mi-api.com',
    sessionTracking: '/api/tracking/session',
    leadCapture: '/api/tracking/leads',
    immediateEvents: '/api/tracking/events'
  }
});

// El framework enviará datos estructurados a tus endpoints
tracker.trackPageView();
tracker.trackClick('boton-cta', { section: 'hero' });
tracker.trackFormSubmit('contacto', { source: 'landing' });
```

### Con N8N (si lo prefieres)

```typescript
import { PRESET_CONFIGS, createTrackingFramework } from '@tracking-crm/core';

const tracker = createTrackingFramework(
  PRESET_CONFIGS.localWithN8N('mi-negocio')
);
```

### Con webhooks externos

```typescript
import { PRESET_CONFIGS, createTrackingFramework } from '@tracking-crm/core';

const tracker = createTrackingFramework(
  PRESET_CONFIGS.webhook('mi-negocio', 'https://hooks.zapier.com/hooks/catch/...')
);
```

## 📋 Estructura de Datos

El framework envía payloads estructurados que puedes procesar como prefieras:

### Payload de Sesión
```json
{
  "businessId": "mi-empresa",
  "sessionId": "sess_123456789",
  "visitorId": "visitor_987654321",
  "events": [
    {
      "eventType": "page_view",
      "eventName": "page_view",
      "eventData": {
        "url": "https://mi-sitio.com/landing",
        "title": "Landing Page"
      },
      "createdAt": "2024-01-01T12:00:00Z",
      "pageUrl": "https://mi-sitio.com/landing"
    }
  ],
  "deviceInfo": {
    "deviceType": "desktop",
    "browser": "Chrome",
    "operatingSystem": "Windows"
  },
  "sessionDuration": 120,
  "scrollDepth": 75
}
```

### Payload de Lead
```json
{
  "businessId": "mi-empresa",
  "visitorId": "visitor_987654321",
  "leadData": {
    "name": "Juan Pérez",
    "email": "juan@ejemplo.com",
    "phone": "+1234567890"
  },
  "source": "landing_page",
  "utmParams": {
    "source": "google",
    "medium": "cpc",
    "campaign": "verano2024"
  },
  "createdAt": "2024-01-01T12:00:00Z"
}
```

## 🔧 Configuraciones Predefinidas

```typescript
import { PRESET_CONFIGS } from '@tracking-crm/core';

// Para desarrollo con tu propia API
PRESET_CONFIGS.localDevelopment('mi-negocio')

// Para desarrollo con N8N
PRESET_CONFIGS.localWithN8N('mi-negocio')

// Para producción personalizada
PRESET_CONFIGS.custom('mi-negocio', 'https://mi-api.com')

// Para webhooks externos
PRESET_CONFIGS.webhook('mi-negocio', 'https://webhook-url.com')
```

## 🏗️ Ejemplos de Implementación Backend

### Con Express.js + Prisma

```javascript
// routes/tracking.js
app.post('/api/tracking/session', async (req, res) => {
  const { businessId, sessionId, visitorId, events } = req.body;
  
  // Guardar en tu base de datos
  await prisma.session.create({
    data: {
      sessionId,
      visitorId,
      businessId,
      events: {
        create: events.map(event => ({
          type: event.eventType,
          name: event.eventName,
          data: event.eventData,
          createdAt: event.createdAt
        }))
      }
    }
  });
  
  res.json({ success: true });
});
```

### Con Next.js API Routes

```typescript
// pages/api/tracking/leads.ts
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const leadData = req.body;
  
  // Procesar lead como prefieras
  await saveLead(leadData);
  await sendToEmailMarketing(leadData);
  await notifySlack(leadData);
  
  res.json({ success: true, leadId: 'lead_123' });
}
```

### Con Serverless Functions

```typescript
// netlify/functions/tracking.ts
export const handler = async (event, context) => {
  const data = JSON.parse(event.body);
  
  // Enviar a tu CRM, base de datos, etc.
  await processTrackingData(data);
  
  return {
    statusCode: 200,
    body: JSON.stringify({ success: true })
  };
};
```

## 🎨 Componentes React Incluidos

```typescript
import { ConsentBanner, LeadForm, TrackingDashboard } from '@tracking-crm/core';

function App() {
  return (
    <div>
      <ConsentBanner onAccept={() => tracker.trackEvent('consent', 'accepted')} />
      <LeadForm onSubmit={(data) => tracker.trackFormSubmit('lead-form', data)} />
      <TrackingDashboard /> {/* Para debug en desarrollo */}
    </div>
  );
}
```

## 🔍 API Completa

### `createTrackingFramework(config)`

Función principal que inicializa el framework.

**Retorna objeto con:**
- `trackEvent(type, name, data)` - Trackear evento personalizado
- `trackPageView(url?, title?)` - Trackear vista de página
- `trackClick(elementId, metadata?)` - Trackear click en elemento
- `trackFormSubmit(formId, formData?)` - Trackear envío de formulario
- `getStatus()` - Obtener estado del tracking
- `cleanup()` - Limpiar listeners y recursos

### Configuración

```typescript
interface TrackingConfig {
  businessId: string;
  environment?: 'development' | 'production' | 'staging';
  endpoints?: {
    baseUrl?: string;
    sessionTracking?: string;
    leadCapture?: string;
    immediateEvents?: string;
    heartbeat?: string;
    custom?: Record<string, string>;
  };
  timing?: {
    heartbeatInterval?: number;
    inactivityTimeout?: number;
    bufferFlushInterval?: number;
  };
  debug?: {
    enabled?: boolean;
    sessionDebug?: boolean;
    apiDebug?: boolean;
  };
}
```

## 🚀 Ventajas de este Enfoque

- **🔧 Flexibilidad Total**: Usa cualquier backend, no estás limitado
- **📊 Datos Estructurados**: Payloads consistentes y bien tipados
- **🎯 Enfoque Simple**: El framework hace tracking, tú decides qué hacer con los datos
- **🔄 Fácil Migración**: Cambia de backend sin cambiar el código frontend
- **📈 Escalable**: Desde prototipos hasta aplicaciones enterprise

## 📝 Licencia

MIT - Úsalo como quieras, donde quieras.

---

**¿Preguntas?** Este framework está diseñado para ser simple y flexible. Si necesitas ayuda integrándolo con tu stack específico, revisa los ejemplos o crea un issue.