@botuyo/chat-widget-standalone 1.0.0 → 1.0.2

package/README.md

@@ -1,208 +1,169 @@
-# BotUyo Chat Widget - Standalone/CDN Version
-
-Widget de chat embebible enterprise-ready que puede ser usado en cualquier sitio web sin necesidad de React, Next.js u otros frameworks. También disponible como componente React con Provider y hooks.
-
-## 🎉 Última Actualización (25 Enero 2026)
-
-**Stack Modernizado + Optimización en Progreso**
-
-### ✅ Completado
-- 🚀 **React 19.2.3** - Última versión estable con concurrent features
-- ⚡ **Vite 7.3.1** - Build tool más rápido y optimizado
-- 📏 **ESLint 9.39.2** - Migrado a flat config (eslint.config.js)
-- 🟢 **Node.js 22.22.0** - LTS actual
-- 🔧 **TypeScript ESLint 8.53.1** - Mejores reglas de linting
-
-### ✅ Code Splitting Completado (26 Ene 2026)
-- ✅ **Code Splitting Implementado**: 7 chunks separados
-- ✅ **33% Reducción**: Carga inicial de 306KB → 208KB gzip
-- ✅ **ES Module Format**: Lazy loading real con chunks
-- ✅ **React.lazy() + Suspense**: ChatWidget bajo demanda
-- 📦 **Bundle**: 683KB inicial + 324KB lazy (total 1,007KB)
-
-### 🔄 En Optimización (Semana 4)
-- ⏳ **Lazy Loading Adicional**: Gallery y AudioPlayer
-- 📋 **CSS Optimization**: cssnano compression
-- 📋 **Preload Hints**: Recursos críticos
-
-### 📊 Estado del Proyecto
-- ✅ **Build**: Exitoso (Vite 7.3.1)
-- ✅ **Tests**: 616/626 pasando (98.4%)
-- 📦 **Bundle**: 1,021 kB JS (306 kB gzip), 45 kB CSS (8.7 kB gzip)
-- ⏳ **Optimización**: Code splitting en implementación
-- ✅ **Lint**: 0 errores, 9 warnings informativos
-- ✅ **TypeScript**: Tipos generados correctamente
-
-### 🔧 Cambios Técnicos Recientes
-- Creado `vite.config.mjs` (JavaScript puro, evita transpilación)
-- Migrado a `eslint.config.js` (flat config ESLint 9)
-- Agregado `.nvmrc` para fijar Node 22
-- Actualizado `tsconfig.json` con `esModuleInterop`
-- Test fixes para React 19 concurrent rendering
-- Instalado `rollup-plugin-visualizer` para análisis de bundle
-
-📖 **[Ver roadmap completo en MEJORAS_PROPUESTAS.md](./MEJORAS_PROPUESTAS.md)**  
-🎯 **[Ver plan de optimización en OPTIMIZATION_PLAN.md](./OPTIMIZATION_PLAN.md)**  
-📊 **[Ver estado actual en STATUS.md](./STATUS.md)**
+# BotUyo Chat Widget
 
----
-
-## 🎨 Theme Builder (Herramienta de Configuración)
-
-**[Abre el Theme Builder](./theme-builder.html)** - Herramienta visual para crear y personalizar temas en tiempo real.
+Widget de chat AI embebible enterprise-ready. Disponible via **NPM** y **CDN** para cualquier sitio web.
 
-Características:
-- 🎨 **5 Temas Predefinidos**: Default, Ocean, Sunset, Midnight, Nature
-- 🖌️ **Editor Visual**: Personaliza colores, espaciado, dimensiones
-- 👁️ **Preview en Vivo**: Ve los cambios en tiempo real
-- 📋 **Copiar Config**: Exporta la configuración lista para usar
-- 🎯 **Para Dashboard**: Herramienta oficial para generar configs de clientes
+[![npm version](https://badge.fury.io/js/%40botuyo%2Fchat-widget-standalone.svg)](https://www.npmjs.com/package/@botuyo/chat-widget-standalone)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-## 📚 Documentación
-- **[🎯 Roadmap y Mejoras](./MEJORAS_PROPUESTAS.md)** - Estado actual y próximos pasos
-- **[✅ Cobertura de Personalización](./CUSTOMIZATION_COVERAGE.md)** - ¡TODO lo que puedes personalizar!
-- **[🎯 Guía Rápida de Temas](./QUICK_THEME_SETUP.md)** - ¡Empieza aquí si el widget se ve transparente!
-- **[🎨 Guía Completa de Personalización](./THEME_GUIDE.md)** - Temas, colores y ejemplos avanzados
-- **[📖 Documentación CSS Variables](./CSS_CUSTOMIZATION.md)** - Detalles técnicos del sistema de diseño
+---
 
 ## 🚀 Instalación Rápida
 
 ### Opción 1: CDN (JavaScript Vanilla)
 
-Agrega este código antes del cierre del `</body>` en tu HTML:
+Agrega este código antes del cierre de `</body>`:
 
 ```html
 <!-- BotUyo Chat Widget -->
-<script src="https://cdn.botuyo.com/chat-widget.js"></script>
-<script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@botuyo/chat-widget-standalone@1.0.0/dist/botuyo-chat.js"></script>
+<script type="module">
   BotUyoChat.init({
     apiKey: 'tu-api-key-aqui',
     apiBaseUrl: 'https://api.botuyo.com',
     theme: {
-      primaryColor: 'hsl(160, 84%, 39%)',
+      primaryColor: '#10b981',
       botName: 'Asistente BotUyo',
-      position: 'bottom-right',
-      // ⚠️ IMPORTANTE: Variables CSS necesarias
-      cssVariables: {
-        background: '0 0% 100%',           // Fondo blanco
-        foreground: '240 10% 3.9%',        // Texto oscuro
-        primary: '160 84% 39%',            // Color principal
-        // ... Ver QUICK_THEME_SETUP.md para más opciones
-      }
+      position: 'bottom-right'
     }
   });
 </script>
 ```
 
+**CDN Alternativo (unpkg):**
+```html
+<script type="module" src="https://unpkg.com/@botuyo/chat-widget-standalone@1.0.0/dist/botuyo-chat.js"></script>
+```
+
 ### Opción 2: NPM Package (React/Next.js)
 
-**Instalación:**
 ```bash
 npm install @botuyo/chat-widget-standalone
 ```
 
-**Uso con Provider:**
-```tsx
-import { ChatWidgetProvider, useChatWidget } from '@botuyo/chat-widget-standalone';
-
-function App() {
-  return (
-    <ChatWidgetProvider
-      apiKey="tu-api-key-aqui"
-      apiBaseUrl="https://api.botuyo.com"
-      theme={{ 
-        primaryColor: 'hsl(160, 84%, 39%)',
-        // ⚠️ IMPORTANTE: Variables CSS necesarias
-        cssVariables: {
-          background: '0 0% 100%',
-          foreground: '240 10% 3.9%',
-          primary: '160 84% 39%',
-          // ... Ver QUICK_THEME_SETUP.md para configuración completa
-        }
-      }}
-    >
-      <YourApp />
-    </ChatWidgetProvider>
-  );
-}
-
-// En cualquier componente:
-function MyComponent() {
-  const chat = useChatWidget();
-  return <button onClick={chat.open}>Abrir Chat</button>;
-}
-```
-
 **Uso directo:**
 ```tsx
-import { ChatWidget } from '@botuyo/chat-widget-standalone';
-
-function App() {
-  return (
-    <ChatWidget
-      apiKey="tu-api-key-aqui"
-      apiBaseUrl="https://api.botuyo.com"
-      theme={{ 
-        primaryColor: 'hsl(160, 84%, 39%)',
-        cssVariables: {
-          background: '0 0% 100%',
-          foreground: '240 10% 3.9%',
-          primary: '160 84% 39%',
-        }
-      }}
-    />
-  );
-}
+import BotUyoChat from '@botuyo/chat-widget-standalone';
+
+// En tu componente o useEffect
+BotUyoChat.init({
+  apiKey: 'tu-api-key-aqui',
+  apiBaseUrl: 'https://api.botuyo.com',
+  theme: {
+    primaryColor: '#10b981',
+    botName: 'Asistente Virtual'
+  }
+});
 ```
 
-## ⚙️ Configuración
+---
 
-### Opciones Disponibles
+## ⚙️ Configuración Completa
 
 ```typescript
 interface StandaloneConfig {
-  // Requerido
+  // ═══════════════════════════════════════════
+  // REQUERIDO
+  // ═══════════════════════════════════════════
   apiKey: string;              // Tu API key de BotUyo
-  apiBaseUrl: string;          // URL del backend Socket.IO
+  apiBaseUrl: string;          // URL del backend (ej: https://api.botuyo.com)
 
-  // Tema (opcional)
+  // ═══════════════════════════════════════════
+  // TEMA (opcional)
+  // ═══════════════════════════════════════════
   theme?: {
-    primaryColor?: string;     // Color principal (default: '#10b981')
-    botName?: string;          // Nombre del bot (default: 'Asistente Virtual')
-    logoUrl?: string;          // URL del logo (default: '/avatar/mar_default.webp')
+    primaryColor?: string;         // Color principal (default: '#10b981')
+    botName?: string;              // Nombre del bot (default: 'Asistente Virtual')
+    logoUrl?: string;              // URL del avatar del bot
     position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-    welcomeMessage?: string;   // Mensaje de bienvenida
-    inputPlaceholder?: string; // Placeholder del input
-    borderRadius?: string;     // Border radius (default: '0.75rem')
-    launcherBorderRadius?: string; // Border radius del botón (default: '50%')
+    welcomeMessage?: string;       // Mensaje de bienvenida inicial
+    inputPlaceholder?: string;     // Placeholder del input (default: 'Escribe tu mensaje...')
+    borderRadius?: string;         // Border radius ventana (default: '0.75rem')
+    launcherBorderRadius?: string; // Border radius botón (default: '50%')
+    starterPrompt?: string;        // Prompt inicial sugerido
+    avatarScale?: number;          // Escala del avatar (default: 1)
+    
+    // Variables CSS para control total del tema
+    cssVariables?: {
+      background?: string;         // HSL sin paréntesis: '0 0% 100%'
+      foreground?: string;         // Color del texto
+      card?: string;               // Fondo de cards
+      cardForeground?: string;     // Texto en cards
+      primary?: string;            // Color primario
+      primaryForeground?: string;  // Texto sobre primario
+      muted?: string;              // Color muted
+      mutedForeground?: string;    // Texto muted
+      border?: string;             // Color de bordes
+      destructive?: string;        // Color de errores
+      radius?: string;             // Border radius global
+    };
+    
+    // Estilos de burbujas
+    bubbleStyles?: {
+      radius?: {
+        bubble?: string;
+        image?: string;
+        button?: string;
+        card?: string;
+      };
+      bot?: {
+        bg?: string;
+        text?: string;
+        border?: string;
+      };
+      user?: {
+        text?: string;
+      };
+      launcher?: {
+        bg?: string;
+        pulse?: boolean;
+      };
+    };
   };
 
-  // Contexto del usuario (opcional)
+  // ═══════════════════════════════════════════
+  // CONTEXTO DEL USUARIO (opcional)
+  // ═══════════════════════════════════════════
   userContext?: {
-    token?: string;            // Token de autenticación
-    metadata?: any;            // Metadata adicional
+    token?: string;            // Token de autenticación del usuario
+    metadata?: {               // Metadata adicional del usuario
+      userId?: string;
+      email?: string;
+      name?: string;
+      [key: string]: any;
+    };
   };
 
-  // Contexto de la página (opcional)
+  // ═══════════════════════════════════════════
+  // CONTEXTO DE LA PÁGINA (opcional)
+  // ═══════════════════════════════════════════
   pageContext?: {
-    url?: string;
-    title?: string;
-    path?: string;
-    referrer?: string;
+    page?: string;             // Identificador de la página
+    id?: string | number;      // ID del recurso actual
+    url?: string;              // URL actual
+    title?: string;            // Título de la página
+    path?: string;             // Path de la URL
+    referrer?: string;         // Página de origen
+    [key: string]: any;        // Metadata adicional
   };
 
+  // ═══════════════════════════════════════════
   // SEO (opcional)
+  // ═══════════════════════════════════════════
   includeSEOMetadata?: boolean; // Incluir metadata SEO (default: false)
 
-  // Callbacks (opcional)
-  onNavigate?: (url: string) => void;
-  onLogin?: (loginUrl: string) => void;
-  onEvent?: (eventName: string, data: any) => void;
-  onStateChange?: (isOpen: boolean) => void;
+  // ═══════════════════════════════════════════
+  // CALLBACKS (opcional)
+  // ═══════════════════════════════════════════
+  onNavigate?: (url: string) => void;        // Cuando el bot sugiere navegar
+  onLogin?: (userData: any) => void;         // Cuando el usuario se autentica
+  onEvent?: (eventName: string, data: any) => void; // Eventos personalizados
+  onStateChange?: (isOpen: boolean) => void; // Cuando el chat se abre/cierra
 }
 ```
 
-## 📚 Ejemplos de Uso
+---
+
+## 📚 Ejemplos
 
 ### Ejemplo Básico
 
@@ -213,13 +174,13 @@ interface StandaloneConfig {
   <title>Mi Sitio Web</title>
 </head>
 <body>
-  <h1>Bienvenido a mi sitio</h1>
+  <h1>Bienvenido</h1>
   
-  <script src="https://cdn.botuyo.com/chat-widget.js"></script>
-  <script>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@botuyo/chat-widget-standalone@1.0.0/dist/botuyo-chat.js"></script>
+  <script type="module">
     BotUyoChat.init({
       apiKey: 'demo-key-12345',
-      apiBaseUrl: 'http://localhost:4000'
+      apiBaseUrl: 'https://api.botuyo.com'
     });
   </script>
 </body>
@@ -229,33 +190,41 @@ interface StandaloneConfig {
 ### Ejemplo con Personalización Completa
 
 ```html
-<script>
+<script type="module">
   BotUyoChat.init({
     apiKey: 'mi-api-key',
     apiBaseUrl: 'https://api.botuyo.com',
     
     theme: {
-      primaryColor: '#ff6b6b',
-      botName: 'Asistente Virtual de Mi Empresa',
+      primaryColor: '#6366f1',
+      botName: 'Asistente de Mi Empresa',
       logoUrl: 'https://mi-sitio.com/logo.png',
       position: 'bottom-left',
-      welcomeMessage: '¡Hola! ¿Necesitas ayuda?',
+      welcomeMessage: '¡Hola! 👋 ¿En qué puedo ayudarte hoy?',
       inputPlaceholder: 'Pregúntame lo que quieras...',
+      cssVariables: {
+        background: '0 0% 100%',
+        foreground: '240 10% 3.9%',
+        primary: '239 84% 67%',
+        card: '0 0% 100%',
+        border: '240 6% 90%'
+      }
     },
 
     userContext: {
-      token: 'user-auth-token',
+      token: 'user-auth-token-jwt',
       metadata: {
         userId: '12345',
-        email: 'user@example.com'
+        email: 'usuario@ejemplo.com',
+        plan: 'premium'
       }
     },
 
     pageContext: {
+      page: 'producto',
+      id: 'SKU-12345',
       url: window.location.href,
-      title: document.title,
-      path: window.location.pathname,
-      referrer: document.referrer
+      title: document.title
     },
 
     onNavigate: (url) => {
@@ -264,175 +233,159 @@ interface StandaloneConfig {
     },
 
     onEvent: (eventName, data) => {
-      console.log('Evento recibido:', eventName, data);
+      console.log('Evento:', eventName, data);
       
-      // Manejo de eventos personalizados
-      if (eventName === 'reservation_created') {
-        alert('¡Reserva creada! ID: ' + data.reservationId);
+      if (eventName === 'lead_captured') {
+        // Enviar a tu CRM
+        sendToCRM(data);
       }
     },
 
     onStateChange: (isOpen) => {
-      console.log('Chat está', isOpen ? 'abierto' : 'cerrado');
+      console.log('Chat:', isOpen ? 'abierto' : 'cerrado');
+      // Analytics
+      gtag('event', isOpen ? 'chat_opened' : 'chat_closed');
     }
   });
 </script>
 ```
 
-### Ejemplo con Control Programático
+### Control Programático
 
-```html
-<script>
-  // Inicializar
-  const chat = BotUyoChat.init({
-    apiKey: 'demo-key',
-    apiBaseUrl: 'http://localhost:4000'
-  });
+```javascript
+// Inicializar
+BotUyoChat.init({
+  apiKey: 'mi-api-key',
+  apiBaseUrl: 'https://api.botuyo.com'
+});
 
-  // Abrir el chat programáticamente
-  document.getElementById('btnAbrir').addEventListener('click', () => {
-    BotUyoChat.open();
-  });
+// Abrir el chat
+document.getElementById('btn-ayuda').onclick = () => {
+  BotUyoChat.open();
+};
 
-  // Cerrar el chat programáticamente
-  document.getElementById('btnCerrar').addEventListener('click', () => {
-    BotUyoChat.close();
-  });
+// Cerrar el chat
+BotUyoChat.close();
 
-  // Enviar un mensaje programáticamente
-  document.getElementById('btnEnviar').addEventListener('click', () => {
-    BotUyoChat.sendMessage('Hola, necesito ayuda');
-  });
+// Enviar mensaje programáticamente
+BotUyoChat.sendMessage('Necesito ayuda con mi pedido #12345');
 
-  // Destruir el widget
-  document.getElementById('btnDestruir').addEventListener('click', () => {
-    BotUyoChat.destroy();
-  });
+// Actualizar configuración en tiempo real
+BotUyoChat.update({
+  theme: {
+    primaryColor: '#ef4444',
+    botName: 'Soporte Urgente'
+  }
+});
 
-  // Actualizar configuración
-  document.getElementById('btnActualizar').addEventListener('click', () => {
-    BotUyoChat.update({
-      theme: {
-        primaryColor: '#ff6b6b',
-        botName: 'Nuevo Nombre'
-      }
-    });
-  });
-</script>
+// Destruir el widget
+BotUyoChat.destroy();
 ```
 
-## 🛠️ API Pública
-
-### `BotUyoChat.init(config)`
-
-Inicializa el widget con la configuración proporcionada.
-
-**Retorna**: Instancia del widget para encadenamiento.
-
-### `BotUyoChat.open()`
-
-Abre la ventana del chat programáticamente.
-
-### `BotUyoChat.close()`
-
-Cierra la ventana del chat programáticamente.
-
-### `BotUyoChat.sendMessage(message)`
-
-Envía un mensaje al chat programáticamente.
-
-**Parámetros**:
-- `message` (string): El mensaje a enviar.
-
-### `BotUyoChat.update(config)`
-
-Actualiza la configuración del widget sin reiniciarlo.
+---
 
-**Parámetros**:
-- `config` (Partial<StandaloneConfig>): Configuración parcial a actualizar.
+## 🛠️ API Pública
 
-### `BotUyoChat.destroy()`
+| Método | Descripción |
+|--------|-------------|
+| `BotUyoChat.init(config)` | Inicializa el widget. Retorna la instancia. |
+| `BotUyoChat.open()` | Abre la ventana del chat |
+| `BotUyoChat.close()` | Cierra la ventana del chat |
+| `BotUyoChat.sendMessage(message)` | Envía un mensaje programáticamente |
+| `BotUyoChat.update(config)` | Actualiza la configuración sin reiniciar |
+| `BotUyoChat.destroy()` | Destruye el widget y limpia recursos |
 
-Destruye el widget y limpia todos los recursos.
+---
 
-## 🎨 Personalización de Estilos
+## 🎨 Temas Predefinidos
 
-El widget utiliza variables CSS que puedes sobrescribir:
+### Tema Claro (Default)
+```javascript
+cssVariables: {
+  background: '0 0% 100%',
+  foreground: '240 10% 3.9%',
+  primary: '160 84% 39%',
+  card: '0 0% 100%',
+  border: '240 6% 90%'
+}
+```
 
-```html
-<style>
-  /* Sobrescribir estilos del widget */
-  #botuyo-chat-widget-root {
-    /* Tus estilos personalizados */
-  }
+### Tema Oscuro
+```javascript
+cssVariables: {
+  background: '240 10% 3.9%',
+  foreground: '0 0% 98%',
+  primary: '160 84% 39%',
+  card: '240 4% 16%',
+  border: '240 4% 20%'
+}
+```
 
-  /* Variables CSS globales */
-  :root {
-    --paseo-chat-primary: #10b981;
-    --paseo-chat-background: #ffffff;
-    --paseo-chat-text: #1f2937;
-    --paseo-chat-border: #e5e7eb;
+### Tema Ocean
+```javascript
+theme: {
+  primaryColor: '#0ea5e9',
+  cssVariables: {
+    background: '200 50% 98%',
+    foreground: '200 50% 10%',
+    primary: '199 89% 48%'
   }
-</style>
+}
 ```
 
-## 🧪 Testing Local
+---
 
-Para probar el widget localmente:
+## 🌐 Compatibilidad
 
-1. Clona el repositorio
-2. Instala dependencias:
-   ```bash
-   c� Documentación
+| Navegador | Versión Mínima |
+|-----------|----------------|
+| Chrome | 90+ |
+| Firefox | 88+ |
+| Safari | 14+ |
+| Edge | 90+ |
+| iOS Safari | 14+ |
+| Chrome Mobile | 90+ |
 
-- **[Guía de Inicio Rápido](QUICK_START.md)** - Comienza en 5 minutos
-- **[Guía de Instalación Completa](INSTALLATION_GUIDE.md)** - Instrucciones detalladas para CDN y React
-- **[Checklist de Verificación](VERIFICATION_CHECKLIST.md)** - Verifica que todo funcione correctamente
-- **[Resumen de Implementación](INSTALLATION_SUMMARY.md)** - Resumen técnico completo
-- **[Ejemplos](examples/)** - Ejemplos funcionales (CDN, React, Next.js)
+---
 
-## �d standalone-widget
-   npm install
-   ```
+## 📦 Build Local
 
-3. Inicia el servidor de desarrollo:
-   ```bash
-   npm run dev
-   ```
+```bash
+# Clonar repositorio
+git clone https://github.com/botuyo/chat-widget.git
+cd chat-widget
 
-4. Abre `http://localhost:3001` en tu navegador
+# Instalar dependencias
+npm install
 
-## 📦 Build para Producción
+# Desarrollo
+npm run dev
 
-```bash
+# Build producción
 npm run build
-```
 
-Esto generará:
-- `dist/botuyo-chat.js` - Bundle minificado para CDN
-- `dist/botuyo-chat.css` - Estilos del widget
-- `dist/botuyo-chat.js.map` - Source map para debugging
+# Tests
+npm test
+```
 
-## 🌐 Compatibilidad
+**Archivos generados:**
+- `dist/botuyo-chat.js` - Bundle principal (~3KB, carga chunks lazy)
+- `dist/botuyo-chat.css` - Estilos (~25KB)
+- `dist/vendor-react-*.js` - React (~194KB, lazy)
+- `dist/chunk-chat-ui-*.js` - UI del chat (~89KB, lazy)
 
-- ✅ Chrome 90+
-- ✅ Firefox 88+
-- ✅ Safari 14+
-- ✅ Edge 90+
-- ✅ Mobile browsers (iOS Safari, Chrome Mobile)
+---
 
 ## 📄 Licencia
 
-MIT License - © 2025 BotUyo
+MIT License - © 2026 BotUyo
 
-## 🆘 Soporte
-
-- 📧 Email: soporte@botuyo.com
-- 💬 Chat: https://botuyo.com/soporte
-- 📖 Docs: https://docs.botuyo.com/chat-widget
+---
 
 ## 🔗 Links
 
-- [Documentación completa](https://docs.botuyo.com)
-- [Ejemplos en vivo](https://botuyo.com/widget-demo)
-- [Repositorio GitHub](https://github.com/botuyo/chat-widget)
+- **NPM**: [npmjs.com/package/@botuyo/chat-widget-standalone](https://www.npmjs.com/package/@botuyo/chat-widget-standalone)
+- **CDN jsDelivr**: `https://cdn.jsdelivr.net/npm/@botuyo/chat-widget-standalone@1.0.0/dist/botuyo-chat.js`
+- **CDN unpkg**: `https://unpkg.com/@botuyo/chat-widget-standalone@1.0.0/dist/botuyo-chat.js`
+- **Documentación**: [docs.botuyo.com](https://docs.botuyo.com)
+- **Soporte**: soporte@botuyo.com