npm package: @nobufintech/chat-widget
Description: Nobu Chat Widget
Author: Nobu Fintech
Latest version: 0.1.33

# @nobu/chat-widget

Widget de chat universal que funciona en cualquier sitio web o framework. Compatible con React, Vue, Angular, WordPress, Shopify y sitios estáticos.

## 🚀 Características

- ✅ **Universal**: Funciona en cualquier framework o sitio web
- ✅ **Múltiples formatos**: Script embebible, componente React, Web Component
- ✅ **TypeScript**: Tipos incluidos para mejor developer experience
- ✅ **Ligero**: Diferentes builds optimizados para cada caso de uso
- ✅ **Personalizable**: Temas, posición y configuración flexible

## 📦 Instalación y Uso

### 🎯 Caso 1: Script Embebible (Sitios web estáticos)

**Ideal para**: HTML, WordPress, Shopify, Wix, Squarespace, landing pages

**Build necesario**:
```bash
npm run build:embed
# Genera: dist/embed.iife.js (~150kb)
```

**Uso por el cliente**:
```html
<!-- Agrega esto antes del cierre de </body> -->
<script 
  src="https://unpkg.com/@nobu/chat-widget/dist/embed.iife.js"
  data-api-key="tu_token_aqui"
  data-theme="light"
></script>
```

**Características**:
- ✅ **1 línea de código** - Instalación instantánea
- ✅ **Autosuficiente** - Incluye React y todas las dependencias
- ✅ **Sin configuración** - Funciona inmediatamente
- ✅ **Universal** - Compatible con cualquier sitio web

**Ejemplos específicos**:

*WordPress*:
```php
// functions.php
function add_nobu_chat() {
    ?>
    <script 
      src="https://unpkg.com/@nobu/chat-widget/dist/embed.iife.js"
      data-api-key="tu_token_aqui"
    ></script>
    <?php
}
add_action('wp_footer', 'add_nobu_chat');
```

*Shopify*:
```html
<!-- En theme.liquid antes de </body> -->
<script 
  src="https://unpkg.com/@nobu/chat-widget/dist/embed.iife.js"
  data-api-key="tu_token_aqui"
></script>
```

*HTML estático*:
```html
<!DOCTYPE html>
<html>
<head>
  <title>Mi sitio web</title>
</head>
<body>
  <h1>Bienvenido</h1>
  
  <!-- Chat widget -->
  <script 
    src="https://unpkg.com/@nobu/chat-widget/dist/embed.iife.js"
    data-api-key="tu_token_aqui"
  ></script>
</body>
</html>
```

### 🎯 Caso 2: Componente React (Aplicaciones React)

**Ideal para**: React, Next.js, Gatsby, Create React App, Vite + React

**Build necesario**:
```bash
npm run build
# Genera: 
# - dist/react.es.js (~15kb)
# - dist/react.umd.js (~15kb)
# - dist/index.d.ts (tipos TypeScript)
```

**Instalación por el cliente**:
```bash
npm install @nobu/chat-widget
```

**Uso por el cliente**:
```jsx
import ChatWidget from '@nobu/chat-widget';

function App() {
  return (
    <div>
      <h1>Mi aplicación</h1>
      <ChatWidget 
        apiKey="tu_token_aqui"
        theme="light"
        position="bottom-right"
      />
    </div>
  );
}
```

**Con TypeScript**:
```tsx
import ChatWidget, { ChatConfig } from '@nobu/chat-widget';

const config: ChatConfig = {
  apiKey: "tu_token_aqui",
  theme: 'light',
  position: 'bottom-right'
};

function App() {
  return <ChatWidget {...config} />;
}
```

**Características**:
- ✅ **Optimizado** - React no duplicado (peerDependency)
- ✅ **Tree shaking** - Solo importa lo necesario
- ✅ **TypeScript** - Tipos completos incluidos
- ✅ **SSR compatible** - Funciona con Next.js, Gatsby

**Ejemplos específicos**:

*Next.js*:
```jsx
// pages/_app.js
import ChatWidget from '@nobu/chat-widget';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <ChatWidget apiKey="tu_token_aqui" />
    </>
  );
}
```

*Vite + React*:
```jsx
// src/App.jsx
import ChatWidget from '@nobu/chat-widget';

function App() {
  return (
    <div className="App">
      <ChatWidget apiKey={import.meta.env.VITE_CHAT_TOKEN} />
    </div>
  );
}
```

### 🎯 Caso 3: Web Component (Otros frameworks)

**Ideal para**: Vue.js, Angular, Svelte, Lit, microfrontends

**Build necesario**:
```bash
npm run build
# Genera:
# - dist/wc.es.js (~50kb)
# - dist/wc.umd.js (~50kb)
```

**Uso directo por el cliente**:
```html
<script type="module">
  import { defineNobuChat } from '@nobu/chat-widget/dist/wc.es.js';
  defineNobuChat();
</script>

<nobu-chat 
  api-key="tu_token_aqui"
  theme="light"
></nobu-chat>
```

**Características**:
- ✅ **Framework agnostic** - Funciona con cualquier framework
- ✅ **Shadow DOM** - CSS encapsulado, sin conflictos
- ✅ **Estándar web** - Soportado nativamente por navegadores

**Ejemplos específicos**:

*Vue.js*:
```vue
<template>
  <div>
    <h1>Mi App Vue</h1>
    <nobu-chat 
      :api-key="chatToken"
      theme="light"
    ></nobu-chat>
  </div>
</template>

<script>
import { defineNobuChat } from '@nobu/chat-widget/dist/wc.es.js';

export default {
  data() {
    return {
      chatToken: 'tu_token_aqui'
    }
  },
  mounted() {
    defineNobuChat();
  }
}
</script>
```

*Angular*:
```typescript
// app.component.ts
import { Component, OnInit, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { defineNobuChat } from '@nobu/chat-widget/dist/wc.es.js';

@Component({
  selector: 'app-root',
  template: `
    <h1>Mi App Angular</h1>
    <nobu-chat 
      api-key="tu_token_aqui"
      theme="light">
    </nobu-chat>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppComponent implements OnInit {
  ngOnInit() {
    defineNobuChat();
  }
}
```

*Svelte*:
```svelte
<script>
  import { onMount } from 'svelte';
  import { defineNobuChat } from '@nobu/chat-widget/dist/wc.es.js';
  
  onMount(() => {
    defineNobuChat();
  });
</script>

<h1>Mi App Svelte</h1>
<nobu-chat 
  api-key="tu_token_aqui"
  theme="light">
</nobu-chat>
```

### 🎯 Caso 4: Script Embebible Programático (SPAs dinámicas)

**Ideal para**: SPAs que necesitan cargar el widget dinámicamente

**Build necesario**:
```bash
npm run build:embed
# Genera: dist/embed.iife.js
```

**Uso por el cliente**:
```javascript
// Cargar dinámicamente
function loadChatWidget(apiKey) {
  const script = document.createElement('script');
  script.src = 'https://unpkg.com/@nobu/chat-widget/dist/embed.iife.js';
  script.dataset.apiKey = apiKey;
  script.dataset.theme = 'light';
  document.head.appendChild(script);
}

// Usar cuando sea necesario
loadChatWidget('tu_token_aqui');
```

**Ejemplos específicos**:

*Vue.js con carga dinámica*:
```vue
<script>
export default {
  mounted() {
    this.loadChatWidget();
  },
  methods: {
    loadChatWidget() {
      const script = document.createElement('script');
      script.src = 'https://unpkg.com/@nobu/chat-widget/dist/embed.iife.js';
      script.dataset.apiKey = this.apiKey;
      document.head.appendChild(script);
    }
  }
}
</script>
```

*Angular con carga dinámica*:
```typescript
// chat.service.ts
import { Injectable } from '@angular/core';

@Injectable()
export class ChatService {
  loadWidget(apiKey: string) {
    const script = document.createElement('script');
    script.src = 'https://unpkg.com/@nobu/chat-widget/dist/embed.iife.js';
    script.dataset.apiKey = apiKey;
    document.head.appendChild(script);
  }
}
```

## 📊 Resumen de Builds y Casos de Uso

| Caso de Uso | Build Necesario | Archivo Generado | Tamaño | Instalación Cliente |
|-------------|-----------------|------------------|--------|-------------------|
| **Sitios estáticos** | `npm run build:embed` | `embed.iife.js` | ~150kb | 1 línea HTML |
| **Apps React** | `npm run build` | `react.es.js` + `react.umd.js` | ~15kb | `npm install` |
| **Otros frameworks** | `npm run build` | `wc.es.js` + `wc.umd.js` | ~50kb | Import + custom element |
| **Carga dinámica** | `npm run build:embed` | `embed.iife.js` | ~150kb | JavaScript programático |

## 🛠️ Configuración

### Opciones disponibles

```typescript
interface ChatConfig {
  apiKey: string;           // Token de autenticación (obligatorio)
  apiUrl?: string;          // URL de tu API (opcional)
  theme?: 'light' | 'dark'; // Tema visual
  position?: 'bottom-right' | 'bottom-left'; // Posición en pantalla
}
```

### Formas de configurar

**Data attributes (script embebible)**:
```html
<script 
  src="..."
  data-api-key="tu_token"
  data-theme="light"
  data-position="bottom-right"
></script>
```

**Props (React)**:
```jsx
<ChatWidget 
  apiKey="tu_token"
  theme="light"
  position="bottom-right"
/>
```

**Attributes (Web Component)**:
```html
<nobu-chat 
  api-key="tu_token"
  theme="light"
  position="bottom-right">
</nobu-chat>
```

**Configuración global (script)**:
```html
<script>
  window.NobuChatConfig = {
    apiKey: 'tu_token',
    theme: 'light'
  };
</script>
<script src="https://unpkg.com/@nobu/chat-widget/dist/embed.iife.js"></script>
```

## 🎨 Personalización

### Temas
```css
/* Tema claro (default) */
:root {
  --chat-brand: #0ea5e9;
  --chat-bg: #ffffff;
  --chat-text: #111827;
}

/* Tema oscuro */
:root {
  --chat-brand: #3b82f6;
  --chat-bg: #1f2937;
  --chat-text: #f9fafb;
}
```

### CSS personalizado
```css
:root {
  --chat-brand: #your-color;     /* Color principal */
  --chat-bg: #ffffff;            /* Fondo del chat */
  --chat-text: #111827;          /* Color del texto */
  --chat-radius: 16px;           /* Radio de bordes */
}
```

## 🚀 CDN y Versionado

### CDN disponibles
```html
<!-- unpkg (recomendado) -->
<script src="https://unpkg.com/@nobu/chat-widget/dist/embed.iife.js"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@nobu/chat-widget/dist/embed.iife.js"></script>
```

### Versiones específicas
```html
<!-- Versión específica (recomendado para producción) -->
<script src="https://unpkg.com/@nobu/chat-widget@0.1.0/dist/embed.iife.js"></script>

<!-- Última versión -->
<script src="https://unpkg.com/@nobu/chat-widget@latest/dist/embed.iife.js"></script>
```

## 🔧 Comandos de Build (Para desarrolladores)

```bash
# Build completo (todos los formatos)
npm run build

# Solo script embebible
npm run build:embed

# Solo builds de librería
npm run build:lib

# Solo tipos TypeScript
npm run build:types

# Desarrollo
npm run dev
```

### Estructura generada

```
dist/
├── embed.iife.js     # Script embebible (autosuficiente)
├── react.es.js       # NPM - ES modules
├── react.umd.js      # NPM - UMD/CommonJS  
├── wc.es.js          # Web Component - ES modules
├── wc.umd.js         # Web Component - UMD
└── index.d.ts        # Tipos TypeScript
```

## 📄 Licencia

MIT License - ve [LICENSE](LICENSE) para más detalles.