npm - tia-gpc-widget - Versions diffs - 1.0.0 - Mend

tia-gpc-widget 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,387 @@
+# TIA GPC Widget
+Librería React para integrar TIA GPC - Sistema de atención al cliente con IA.
+## 📦 Instalación
+```bash
+npm install @tia/gpc-widget
+```
+o con yarn:
+```bash
+yarn add @tia/gpc-widget
+```
+## 🚀 Uso Básico
+### React / Vite
+```jsx
+import { TiaGPCWidget } from '@tia/gpc-widget';
+import '@tia/gpc-widget/styles';
+function App() {
+  return (
+    <div>
+      <TiaGPCWidget token="tu-token-de-licencia" />
+    </div>
+  );
+}
+export default App;
+```
+### Next.js App Router
+```jsx
+// app/layout.js
+import { TiaGPCWidget } from '@tia/gpc-widget';
+import '@tia/gpc-widget/styles';
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <TiaGPCWidget token={process.env.NEXT_PUBLIC_TIA_GPC_TOKEN} />
+      </body>
+    </html>
+  );
+}
+```
+### Next.js Pages Router
+```jsx
+// pages/_app.js
+import { TiaGPCWidget } from '@tia/gpc-widget';
+import '@tia/gpc-widget/styles';
+function MyApp({ Component, pageProps }) {
+  return (
+    <>
+      <Component {...pageProps} />
+      <TiaGPCWidget token={process.env.NEXT_PUBLIC_TIA_GPC_TOKEN} />
+    </>
+  );
+}
+export default MyApp;
+```
+## ⚙️ Props
+### Requeridas
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `token` | `string` | Token de licencia de TIA GPC |
+### Opcionales
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `theme` | `"auto" \| "light" \| "dark"` | `"auto"` | Tema visual del widget |
+| `language` | `"auto" \| "es" \| "en" \| "fr"` | `"auto"` | Idioma de la interfaz |
+| `position` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | `"bottom-right"` | Posición del widget flotante |
+| `autoOpen` | `boolean` | `false` | Abrir automáticamente al cargar |
+| `showBranding` | `boolean` | `true` | Mostrar marca "Powered by TIA" |
+| `showMetadata` | `boolean` | `false` | Mostrar metadatos de tokens y tiempos de respuesta |
+| `mobileFullscreen` | `boolean` | `true` | Mostrar en pantalla completa en móviles |
+| `onReady` | `() => void` | - | Callback cuando el widget está listo |
+| `onError` | `(error: Error) => void` | - | Callback cuando hay un error |
+| `onClose` | `() => void` | - | Callback cuando se cierra el widget |
+## 📝 Ejemplos
+### Configuración Completa
+```jsx
+import { TiaGPCWidget } from '@tia/gpc-widget';
+import '@tia/gpc-widget/styles';
+function App() {
+  const handleReady = () => {
+    console.log('TIA GPC Widget ready!');
+  };
+  const handleError = (error) => {
+    console.error('TIA GPC Error:', error);
+  };
+  const handleClose = () => {
+    console.log('Widget closed');
+  };
+  return (
+    <TiaGPCWidget
+      token="tu-token-de-licencia"
+      theme="light"
+      language="en"
+      position="bottom-right"
+      autoOpen={false}
+      showBranding={true}
+      showMetadata={false}
+      mobileFullscreen={true}
+      onReady={handleReady}
+      onError={handleError}
+      onClose={handleClose}
+    />
+  );
+}
+```
+### Variables de Entorno (Recomendado)
+Crea un archivo `.env` o `.env.local`:
+```env
+# Para Vite/React
+VITE_TIA_GPC_TOKEN=tu-token-de-licencia
+# Para Next.js
+NEXT_PUBLIC_TIA_GPC_TOKEN=tu-token-de-licencia
+```
+Luego úsala:
+```jsx
+// Vite/React
+<TiaGPCWidget token={process.env.VITE_TIA_GPC_TOKEN} />
+// Next.js
+<TiaGPCWidget token={process.env.NEXT_PUBLIC_TIA_GPC_TOKEN} />
+```
+### Uso Condicional
+```jsx
+import { useState } from 'react';
+import { TiaGPCWidget } from '@tia/gpc-widget';
+import '@tia/gpc-widget/styles';
+function App() {
+  const [showChat, setShowChat] = useState(true);
+  return (
+    <div>
+      <button onClick={() => setShowChat(!showChat)}>
+        Toggle Chat
+      </button>
+      {showChat && <TiaGPCWidget token="tu-token" />}
+    </div>
+  );
+}
+```
+## 🌍 Idiomas Soportados
+- 🇪🇸 Español (`es`)
+- 🇬🇧 English (`en`)
+- 🇫🇷 Français (`fr`)
+El widget detecta automáticamente el idioma del navegador cuando `language="auto"`.
+## 🎨 Temas
+- **`auto`**: Detecta el tema del sistema operativo del usuario
+- **`light`**: Tema claro
+- **`dark`**: Tema oscuro
+## 🛡️ Seguridad (Turnstile)
+TIA GPC utiliza [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/) para protección anti-bot.
+✅ **Ya configurado** - La librería viene con Turnstile preconfigurado. No necesitas hacer nada adicional.
+## 📦 Dependencias
+### Peer Dependencies (debes instalarlas en tu proyecto)
+```bash
+npm install react react-dom
+```
+Versiones soportadas:
+- `react`: ^18.0.0
+- `react-dom`: ^18.0.0
+### Dependencies Incluidas
+El paquete incluye automáticamente:
+- `@marsidev/react-turnstile` - Integración de Cloudflare Turnstile
+- `axios` - Cliente HTTP
+- `i18next` - Internacionalización
+- `react-i18next` - i18n para React
+- `i18next-browser-languagedetector` - Detección automática de idioma
+- `lucide-react` - Iconos
+- `react-hot-toast` - Notificaciones toast
+## 🎯 Exports Disponibles
+```jsx
+// Componente principal
+import { TiaGPCWidget } from '@tia/gpc-widget';
+// Constantes útiles
+import { WIDGET_POSITIONS, THEMES, LANGUAGES } from '@tia/gpc-widget';
+// Servicio para uso avanzado (opcional)
+import { GPCService, getGPCService } from '@tia/gpc-widget';
+// Estilos
+import '@tia/gpc-widget/styles';
+```
+### Uso de Constantes
+```jsx
+import { TiaGPCWidget, WIDGET_POSITIONS, THEMES, LANGUAGES } from '@tia/gpc-widget';
+<TiaGPCWidget
+  token="tu-token"
+  position={WIDGET_POSITIONS.BOTTOM_LEFT}
+  theme={THEMES.DARK}
+  language={LANGUAGES.ENGLISH,}
+/>
+```
+## 🔧 Troubleshooting
+### El widget no se muestra
+1. Verifica que importaste los estilos:
+   ```jsx
+   import '@tia/gpc-widget/styles';
+   ```
+2. Asegúrate que React y ReactDOM estén instalados:
+   ```bash
+   npm install react react-dom
+   ```
+### Errores de Conexión
+Si ves errores de conexión al backend:
+- Verifica que tu `token` de licencia sea válido
+- Asegúrate de tener conexión a internet
+- Contacta a soporte si el problema persiste
+## 🏗️ Desarrollo Local
+### Clonar el repositorio
+```bash
+git clone https://gitlab.com/softia/tiagpc-frontend.git
+cd tiagpc-frontend
+```
+### Instalar dependencias
+```bash
+npm install
+```
+### Configurar variables de entorno
+Crea un archivo `.env` (valores de desarrollo):
+```env
+VITE_API_URL=http://localhost:8002
+VITE_TURNSTILE_SITE_KEY=0x4AAAAAAB9XB2TsB-P7vbJM
+VITE_ENV=development
+VITE_DEBUG=true
+```
+> **Nota:** En producción, la librería usa automáticamente los valores correctos de API y Turnstile configurados internamente.
+### Comandos disponibles
+```bash
+# Servidor de desarrollo
+npm run dev
+# Build de producción
+npm run build
+# Preview del build
+npm run preview
+# Linting
+npm run lint
+```
+### Build para publicación
+```bash
+# Crear build de producción
+npm run build
+# El build genera:
+# - dist/tia-gpc.es.js (ESM)
+# - dist/tia-gpc.cjs.js (CommonJS)
+# - dist/tia-gpc.css (Estilos)
+```
+## 📤 Publicación en NPM
+```bash
+# 1. Autenticarse en npm
+npm login
+# 2. Publicar (automáticamente ejecuta build)
+npm publish --access public
+# O para scoped packages
+npm publish --access public
+```
+El script `prepublishOnly` ejecuta automáticamente el build antes de publicar.
+## 🌐 Compatibilidad
+### Frameworks Soportados
+- ✅ React 18+
+- ✅ Next.js 13+ (App Router y Pages Router)
+- ✅ Vite
+- ✅ Create React App
+- ✅ Remix
+- ✅ Gatsby
+### Navegadores Soportados
+- ✅ Chrome/Edge (últimas 2 versiones)
+- ✅ Firefox (últimas 2 versiones)
+- ✅ Safari 14+
+- ✅ Mobile (iOS Safari, Chrome Mobile)
+## 📱 Características
+- 💬 Chat con IA contextualizada por documentos
+- 🛡️ Protección anti-bot con Cloudflare Turnstile
+- 🌍 Multiidioma (Español, Inglés, Francés) con detección automática
+- 📱 Totalmente responsive y optimizado para móviles
+- 🎨 Temas claro/oscuro con detección automática del sistema
+- ⚡ Tree-shaking y optimización de bundle
+- 🔒 Validación de sesiones con cacheo
+- ♿ Accesible (a11y)
+- 📊 Metadatos opcionales (tokens, tiempos de respuesta)
+## 📄 Licencia
+UNLICENSED - Uso restringido solo para clientes autorizados de TIA GPC.
+## 🆘 Soporte
+Para soporte técnico, contacta a:
+- 📧 Email: soporte@tiagpc.com
+- 🌐 Documentación: https://docs.tiagpc.com
+- 🔗 Repository: https://gitlab.com/softia/tiagpc-frontend
+---
+**TIA GPC** - Sistema de atención al cliente con IA para negocios