@agentcrafta/chat-next 0.0.2 → 0.0.3

package/README.md

@@ -0,0 +1,322 @@
+# Agente Conversacional Embebido
+
+## Descripción del Componente
+
+El **Agente Conversacional Embebido** es un componente React que integra Microsoft Bot Framework Web Chat en una interfaz moderna y personalizable. Proporciona una experiencia de chat completa con soporte para reinicio de conversación, personalización de estilos dinámicos basados en variables CSS, y gestión automática del estado de conexión.
+
+Este componente utiliza el Web Chat de Bot Framework para comunicarse con Power Virtual Agents (PVA) u otros bots compatibles, ofreciendo una interfaz de usuario intuitiva y responsive.
+
+## Índice
+
+- [Instalación y Configuración](#instalación-y-configuración)
+- [Variables de Entorno](#variables-de-entorno)
+- [Uso del Componente](#uso-del-componente)
+- [Server Actions](#server-actions)
+- [Hook useChat](#hook-usechat)
+- [Configuración de StyleOptions](#configuración-de-styleoptions)
+- [Tipos y Interfaces](#tipos-y-interfaces)
+
+## Instalación y Configuración
+
+### Variables de Entorno
+
+Configure las siguientes variables en su archivo `.env.local` para desarrollo local:
+
+```env
+# URL del endpoint para obtener tokens del agente conversacional
+TOKEN_AGENTE_URL=https://your-bot-endpoint.com/powervirtualagents/botsbyschema/...
+```
+
+Para PRODUCCIÓN, asegúrese de establecer estas variables en su entorno de despliegue.
+
+**Importante**: La variable `TOKEN_AGENTE_URL` debe apuntar al endpoint completo de Power Virtual Agents que incluye el esquema del bot y la API version.
+
+## Uso del Componente
+
+### Características
+
+- **Chat flotante**: Aparece como un botón flotante en la esquina inferior derecha
+- **Interfaz responsive**: Se adapta a diferentes tamaños de pantalla
+- **Reinicio de conversación**: Botón para reiniciar la conversación completa
+- **Personalización de estilos**: Utiliza variables CSS para temas dinámicos
+- **Gestión de errores**: Manejo robusto de errores tanto en cliente como en servidor
+
+### Props del Componente
+
+| Prop           | Tipo           | Default     | Descripción                                                     |
+| -------------- | -------------- | ----------- | --------------------------------------------------------------- |
+| `botName`      | `string`       | `"Agent"`   | Nombre que se mostrará en la cabecera del chat                  |
+| `logoUrl`      | `string`       | `undefined` | URL del logo que se mostrará junto al nombre del bot (opcional) |
+| `show`         | `boolean`      | `true`      | Indica si el chat debe mostrarse o no (por defecto es true)     |
+| `styleOptions` | `StyleOptions` | `undefined` | Opciones de estilo personalizadas para el chat (opcional)       |
+
+### Importación y Uso
+
+#### Básico
+
+```tsx
+import { Chat } from "../chat";
+
+export default function HomePage() {
+  return (
+    <div>
+      <h1>Mi Aplicación</h1>
+      <Chat botName="Asistente Virtual" />
+    </div>
+  );
+}
+```
+
+#### Avanzado con Personalización de Estilos
+
+```tsx
+import { Chat } from "../chat";
+
+export default function HomePage() {
+  return (
+    <div>
+      <h1>Mi Aplicación</h1>
+      <Chat
+        botName="Asistente Virtual"
+        logoUrl="logo.svg"
+        styleOptions={{
+          accent: getCssVariableAsHex("var(--primary)"),
+          backgroundColor: getCssVariableAsHex("var(--background)"),
+          //Respuestas del Bot
+          botAvatarBackgroundColor: getCssVariableAsHex("var(--background)"),
+          bubbleBackground: getCssVariableAsHex("var(--muted)"),
+          bubbleBorderRadius: 10,
+          //Mensajes del usuario
+          bubbleFromUserBackground: getCssVariableAsHex("var(--secondary)"),
+          bubbleFromUserBorderRadius: 10,
+          bubbleFromUserTextColor: getCssVariableAsHex("var(--background)"),
+          userAvatarBackgroundColor: getCssVariableAsHex("var(--primary)"),
+          //Caja de escritura
+          sendBoxHeight: 50,
+          sendBoxPlaceholderColor: getCssVariableAsHex("var(--muted)"),
+          sendBoxBackground: getCssVariableAsHex("var(--background)"),
+          sendBoxBorderTop: `solid 1px ${getCssVariableAsHex("var(--border)")}`,
+          sendBoxButtonColor: getCssVariableAsHex("var(--primary)"),
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## Server Actions
+
+### `getRegionalSettings()`
+
+**Propósito**: Obtiene la configuración regional del bot, incluyendo las URLs de los canales disponibles.
+
+```typescript
+const data = await getRegionalSettings();
+console.log(data.channelUrlsById.directline); // URL de DirectLine
+```
+
+**Retorna**: Configuración regional con URLs de canales disponibles.
+
+### `getConversationToken()`
+
+**Propósito**: Obtiene el token de autenticación necesario para establecer la conexión con DirectLine.
+
+```typescript
+const token = await getConversationToken();
+```
+
+**Retorna**: Token de conversación válido para DirectLine.
+
+### `getChatStoreConfig()`
+
+**Propósito**: Obtiene la configuración del store de Web Chat, incluyendo eventos iniciales y filtros.
+
+```typescript
+const config = await getChatStoreConfig();
+// config.eventConfig.startConversation - Evento para iniciar conversación
+// config.filterConfig - Configuración de filtros
+```
+
+**Retorna**: Configuración del store con estado inicial y eventos.
+
+### `logChatError(input)`
+
+**Propósito**: Registra errores del chat en el servidor para monitoreo y debugging.
+
+```typescript
+await logChatError({
+  errorType: "connection_failed",
+  errorMessage: "No se pudo conectar al bot",
+  actionType: "initialize_chat",
+  userId: "optional-user-id",
+});
+```
+
+**Parámetros**:
+
+- `errorType`: Tipo de error (string)
+- `errorMessage`: Mensaje descriptivo del error
+- `actionType`: Acción que causó el error (opcional)
+- `userId`: ID del usuario (opcional)
+
+## Hook useChat
+
+### Funciones y Estado
+
+#### Estado del Chat
+
+### Props del Hook
+
+| Prop           | Tipo           | Default     | Descripción                                               |
+| -------------- | -------------- | ----------- | --------------------------------------------------------- |
+| `styleOptions` | `StyleOptions` | `undefined` | Opciones de estilo personalizadas para el chat (opcional) |
+
+```typescript
+const {
+  isVisible, // boolean - Chat visible/oculto
+  isRestarting, // boolean - Estado de reinicio
+  chatKey, // number - Key para forzar re-render
+  webChatRef, // RefObject - Referencia al DOM del chat
+  styleOptions, // StyleOptions - Configuración de estilos
+  // ... funciones
+} = useChat();
+```
+
+#### Funciones Principales
+
+##### `handleChangeVisibility(visible: boolean)`
+
+Controla la visibilidad del chat.
+
+```typescript
+handleChangeVisibility(true); // Mostrar chat
+handleChangeVisibility(false); // Ocultar chat
+```
+
+##### `initializeChat()`
+
+Inicializa el chat embebido obteniendo tokens y configuración.
+
+- Obtiene configuración regional
+- Solicita token de conversación
+- Crea la instancia de DirectLine
+- Renderiza Web Chat con estilos personalizados
+
+##### `restartConversation()`
+
+Reinicia completamente la conversación utilizando el patrón React key.
+
+- Limpia referencias actuales
+- Regenera el chatKey para forzar remount
+- Reinicializa la conexión
+
+##### `cleanup()`
+
+Limpia la instancia del chat de forma segura.
+
+## Configuración de StyleOptions
+
+### Opciones de Color y Tema
+
+```typescript
+interface StyleOptions {
+  // Colores principales
+  accent: string; // Color principal (#0078D4)
+  backgroundColor: string; // Fondo del chat (#e8e9eb)
+
+  // Configuración de burbujas del bot
+  bubbleBackground: string; // Fondo de mensajes del bot
+  bubbleBorderRadius: number; // Radio de borde de burbujas
+  bubbleTextColor: string; // Color del texto del bot
+
+  // Configuración de burbujas del usuario
+  bubbleFromUserBackground: string; // Fondo de mensajes del usuario
+  bubbleFromUserBorderRadius: number; // Radio de borde del usuario
+  bubbleFromUserTextColor: string; // Color del texto del usuario
+
+  // Configuración de avatares
+  botAvatarImage: string; // URL del avatar del bot
+  botAvatarInitials: string; // Iniciales del bot
+  userAvatarImage: string; // URL del avatar del usuario
+  userAvatarInitials: string; // Iniciales del usuario
+  userAvatarBackgroundColor: string; // Color de fondo del avatar
+
+  // Caja de entrada
+  sendBoxBackground: string; // Fondo de la caja de texto
+  sendBoxBorderTop: string; // Borde superior de la caja
+  sendBoxButtonColor: string; // Color del botón de enviar
+  sendBoxHeight: number; // Altura de la caja (50px)
+
+  // Animaciones
+  typingAnimationBackgroundImage: string; // GIF de animación de escritura
+  typingAnimationDuration: number; // Duración de la animación (ms)
+  typingAnimationHeight: number; // Altura de la animación
+  typingAnimationWidth: number; // Ancho de la animación
+}
+```
+
+### Categorías de Configuración
+
+#### **Diseño y Layout**
+
+- `avatarSize`: Tamaño de avatares (31px)
+- `bubbleMessageMaxWidth`: Ancho máximo de burbujas (480px)
+- `paddingRegular`: Padding estándar (10px)
+
+#### **Tipografía**
+
+- `primaryFont`: Fuente principal del chat
+- `monospaceFont`: Fuente para código (Consolas)
+- `fontSizeSmall`: Tamaño de fuente pequeña (70%)
+
+#### **Interactividad**
+
+- `suggestedActionBackgroundColor`: Color de acciones sugeridas
+- `suggestedActionLayout`: Layout de acciones ('flow', 'stacked', 'carousel')
+- `hideUploadButton`: Ocultar botón de subir archivos
+
+#### **Animaciones y Feedback**
+
+- `spinnerAnimationHeight/Width`: Dimensiones del spinner (16px)
+- `autoScrollSnapOnPage`: Auto-scroll en nuevos mensajes
+
+## Tipos e Interfaces
+
+### `StyleOptions`
+
+Interface completa para la configuración de estilos del Web Chat.
+
+### `WebChatAction`
+
+Define las acciones disponibles para el store de Web Chat:
+
+- `DIRECT_LINE/CONNECT_FULFILLED`: Conexión establecida
+- `DIRECT_LINE/POST_ACTIVITY`: Enviar actividad/mensaje
+- `DIRECT_LINE/INCOMING_ACTIVITY`: Recibir actividad/mensaje
+
+### `WebChatStore`
+
+Interface para el store personalizado con middleware para manejo de eventos y filtros.
+
+### `WebChatLib`
+
+Interface para la biblioteca global de Web Chat con métodos de creación y renderizado.
+
+---
+
+## Notas de Implementación
+
+1. **Seguridad**: El componente incluye validación de tokens y manejo de errores robusto
+2. **Performance**: Utiliza el patrón React key para reinicializaciones eficientes
+3. **Accesibilidad**: Incluye labels ARIA y soporte para navegación por teclado
+4. **Responsive**: Diseño adaptable para diferentes dispositivos
+5. **Temas**: Integración completa con el sistema de temas de la aplicación
+
+## Troubleshooting
+
+### Problemas Comunes
+
+1. **Chat no se inicializa**: Verificar `TOKEN_AGENTE_URL` en `.env`
+2. **Estilos no se aplican**: Verificar variables CSS disponibles
+3. **Errores de conexión**: Revisar configuración de CORS y headers de seguridad
+4. **Imágenes no cargan**: Verificar rutas en carpeta `public/`

package/dist/chat-server-DoG_Rvk7.d.ts

@@ -0,0 +1,20 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { StyleOptions } from '@agentcrafta/core';
+
+type ChatProps = {
+    show?: boolean;
+    botName?: string;
+    logoUrl?: string;
+    styleOptions?: Partial<StyleOptions>;
+};
+/**
+ * @description Componente de servidor para el chat. Este componente se encarga de manejar la lógica del servidor y la comunicación con el cliente.
+ * @param botName Nombre del bot a mostrar en el encabezado del chat
+ * @param logoUrl URL del logo a mostrar junto al nombre del bot (opcional)
+ * @param show Indica si el chat debe mostrarse o no (por defecto es true)
+ * @param styleOptions: StyleOptions Opciones de estilo personalizadas para el chat (opcional)
+ * @returns
+ */
+declare function ChatServer(props: ChatProps): react_jsx_runtime.JSX.Element;
+
+export { ChatServer as C };