ocular-widget-sdk/README.md

Ocular's widget SDK

# Ocular Widget SDK

Un SDK para integrar fácilmente el widget de Ocular Solution en aplicaciones web. Proporciona una interfaz moderna con soporte para promesas y eventos para una experiencia de integración fluida.

## Instalación

```bash
npm install ocular-widget-sdk
```

## Compatibilidad

✅ **JavaScript puro** - Sin configuración adicional  
✅ **TypeScript** - Tipos incluidos automáticamente  
✅ **Vue 3** - Soporte completo para Composition API y Options API  
✅ **React** - Compatible con todas las versiones  
✅ **Angular** - Tipos TypeScript integrados  
✅ **Vite, Webpack, Rollup** - Soporte para bundlers modernos  
✅ **Node.js** - Detección automática del entorno  

### Uso en JavaScript (Vanilla/Sin TypeScript)

```javascript
// ES Modules
import { initOcularWidget, ocularWidgetInstance } from 'ocular-widget-sdk';

// CommonJS
const { initOcularWidget, ocularWidgetInstance } = require('ocular-widget-sdk');

// Funciona igual, sin tipos pero con toda la funcionalidad
await initOcularWidget({ code: 'tu-codigo' });
ocularWidgetInstance.show();
```

### Uso en TypeScript

```typescript
import { 
  initOcularWidget, 
  ocularWidgetInstance, 
  type InitOptions 
} from 'ocular-widget-sdk';

// Con tipos automáticos e IntelliSense completo
const options: InitOptions = { code: 'tu-codigo' };
await initOcularWidget(options);

const customer = {
  id: '123',
  name: 'Juan Pérez',
  email: 'juan@email.com'
};

ocularWidgetInstance.setCustomer(customer);
```

## Uso Básico

```javascript
import { initOcularWidget, ocularWidgetInstance } from 'ocular-widget-sdk';

// IMPORTANTE: initOcularWidget debe ejecutarse UNA SOLA VEZ al cargar la app
// Generalmente en el archivo principal (main.js, index.js, App.js)
try {
  await initOcularWidget({ code: 'tu-codigo-widget' });
  console.log('Widget inicializado correctamente');

  // Mostrar el botón flotante del widget
  await ocularWidgetInstance.show();
} catch (error) {
  console.error('Error inicializando widget:', error);
}

// Después de la inicialización, puedes usar ocularWidgetInstance
// en cualquier componente sin volver a inicializar
```

## API Reference

### `initOcularWidget(options)`

Inicializa y carga el widget de Ocular Solution en la página.

**Parámetros:**
- `options.code` (string, requerido): El código único del widget proporcionado por Ocular Solution

**Retorna:** `Promise<string>`
- Se resuelve cuando el script del widget se ha cargado exitosamente
- Se rechaza si hay un error durante la carga

**Ejemplo:**
```javascript
try {
  const result = await initOcularWidget({ code: 'mi-codigo-widget' });
  console.log(result); // "Script cargado exitosamente"
} catch (error) {
  console.error('Error:', error.message);
}
```

**Casos especiales:**
- Si ya se inicializó anteriormente, retorna `"Ya inicializado"`
- Si el script ya existe en el DOM, retorna `"Script ya existe"`
- Si no se proporciona código, rechaza con error

### `ocularWidgetInstance`

Instancia principal del widget que proporciona métodos para controlar y escuchar eventos.

#### Métodos

##### `show(opened = false)`

Muestra el widget en la página.

**⚠️ IMPORTANTE**: Este método debe ejecutarse después de que se emita el evento `is-ready`.

**Parámetros:**
- `opened` (boolean, opcional):
  - `false` (por defecto): Muestra solo el botón flotante del widget
  - `true`: Abre completamente el widget mostrando su contenido

**Retorna:** `Promise<string>` - `"success"` cuando se completa

**Ejemplos:**
```javascript
// Esperar a que el widget esté listo
ocularWidgetInstance.on('is-ready', async () => {
  // Mostrar solo el botón flotante (icono circular)
  await ocularWidgetInstance.show();
  
  // Abrir el widget completamente
  await ocularWidgetInstance.show(true);
});
```

##### `hide()`

Oculta el widget de la página.

**⚠️ IMPORTANTE**: Este método debe ejecutarse después de que se emita el evento `is-ready`.

**Retorna:** `Promise<string>` - `"success"` cuando se completa

**Ejemplo:**
```javascript
ocularWidgetInstance.on('is-ready', async () => {
  await ocularWidgetInstance.hide();
});
```

##### `toggle()`

Alterna la visibilidad del widget (muestra si está oculto, oculta si está visible).

**⚠️ IMPORTANTE**: Este método debe ejecutarse después de que se emita el evento `is-ready`.

**Retorna:** `Promise<string>` - `"success"` cuando se completa

**Ejemplo:**
```javascript
ocularWidgetInstance.on('is-ready', async () => {
  await ocularWidgetInstance.toggle();
});
```

##### `setCustomer(customer)`

Establece la información del cliente en el widget.

**⚠️ IMPORTANTE**: Este método debe ejecutarse después de que se emita el evento `is-ready`.

**Parámetros:**
- `customer` (object): Objeto con la información del cliente

**Retorna:** `Promise<string>` - `"success"` cuando se completa

**Ejemplo:**
```javascript
ocularWidgetInstance.on('is-ready', async () => {
  await ocularWidgetInstance.setCustomer({
    id: '12345',
    name: 'Juan Pérez',
    email: 'juan@ejemplo.com',
    phone: '+1234567890'
  });
});
```

##### `setLocale(locale)`

Establece el idioma/localización del widget.

**⚠️ IMPORTANTE**: Este método debe ejecutarse después de que se emita el evento `is-ready`.

**Parámetros:**
- `locale` (string): Código de idioma (ej: 'es', 'en', 'fr')

**Retorna:** `Promise<string>` - `"success"` cuando se completa

**Ejemplo:**
```javascript
ocularWidgetInstance.on('is-ready', async () => {
  await ocularWidgetInstance.setLocale('es');
});
```

#### Eventos

##### `on(event, callback)`

Registra un listener para eventos del widget.

**Parámetros:**
- `event` (string): Nombre del evento a escuchar
- `callback` (function): Función que se ejecuta cuando ocurre el evento

**Ejemplo:**
```javascript
ocularWidgetInstance.on('is-ready', (eventData) => {
  console.log('Widget listo:', eventData);
});
```

##### `off(event)`

Remueve todos los listeners de un evento específico.

**Parámetros:**
- `event` (string): Nombre del evento

**Ejemplo:**
```javascript
ocularWidgetInstance.off('is-ready');
```

## Arquitectura de Uso

### Patrón Recomendado

El SDK está diseñado con un patrón **"Initialize Once, Use Everywhere"** (Inicializar una vez, usar en todas partes):

1. **Inicialización (Una sola vez)**:
   - Ejecuta `initOcularWidget()` en el archivo principal de tu aplicación
   - Esto carga el script del widget y lo prepara para uso global

2. **Uso en componentes**:
   - Importa solo `ocularWidgetInstance` en cualquier componente
   - **IMPORTANTE**: Espera a que se emita el evento `is-ready` antes de usar métodos como `show()`, `hide()`, `toggle()`, etc.
   - La instancia está disponible globalmente

### Ejemplo Básico

```javascript
// main.js (Inicialización única)
import { initOcularWidget, ocularWidgetInstance } from 'ocular-widget-sdk';

// Inicializar el widget una sola vez
await initOcularWidget({ code: 'tu-codigo-widget' });

// Esperar a que el widget esté listo
ocularWidgetInstance.on('is-ready', () => {
  console.log('✅ Widget listo para usar');
  // Ahora puedes usar todos los métodos
  ocularWidgetInstance.show();
});

// ===============================================
// cualquier-otro-archivo.js (Uso en componentes)
// ===============================================
import { ocularWidgetInstance } from 'ocular-widget-sdk';

// Asegurarse de que el widget esté listo antes de usar métodos
function useWidget() {
  ocularWidgetInstance.on('is-ready', () => {
    // Métodos disponibles después del evento is-ready
    ocularWidgetInstance.show(true); // Abrir widget
    ocularWidgetInstance.setCustomer({ name: 'Juan', email: 'juan@email.com' });
  });
}
```

## Eventos Disponibles

El widget emite varios eventos durante su ciclo de vida que puedes escuchar:

### Eventos del Sistema

| Evento | Descripción |
|--------|-------------|
| `ready` | El widget se ha inicializado y está listo para usar |
| `script-ready` | El script del widget se ha cargado correctamente |
| `widget-event` | Evento genérico que se dispara para todos los eventos del widget |

### Eventos del Widget

| Evento | Descripción |
|--------|-------------|
| `is-ready` | El widget se creó correctamente y está montado |
| `minimized` | El widget se minimizó |
| `hidden` | El widget se ocultó |
| `opened` | El widget se abrió |
| `button-displayed` | El botón del widget se mostró |
| `closed` | El widget se cerró |
| `call-started` | El widget inició una llamada |
| `call-ended` | El widget finalizó una llamada |
| `scheduled-success` | El widget agendó una cita exitosamente |

## Ejemplo Completo

```javascript
// ============================================
// 📁 main.js o App.js (Inicialización única)
// ============================================
import { initOcularWidget, ocularWidgetInstance } from 'ocular-widget-sdk';

// IMPORTANTE: Esto se ejecuta UNA SOLA VEZ al cargar la app
async function initializeApp() {
  try {
    await initOcularWidget({ code: 'tu-codigo-widget' });
    console.log('✅ Widget inicializado globalmente');

    // Configuración inicial opcional
    await ocularWidgetInstance.show(); // Mostrar botón flotante
  } catch (error) {
    console.error('❌ Error inicializando widget:', error);
  }
}

initializeApp();

// ============================================
// 📁 cualquier-componente.js (Uso en componentes)
// ============================================
import { ocularWidgetInstance } from 'ocular-widget-sdk';

class WidgetManager {
  constructor() {
    this.setupEventListeners();
  }

  setupEventListeners() {
    // Eventos del sistema
    ocularWidgetInstance.on('ready', () => {
      console.log('🚀 Widget system ready');
    });

    // Eventos del widget
    ocularWidgetInstance.on('is-ready', () => {
      console.log('✨ Widget mounted successfully');
    });

    ocularWidgetInstance.on('opened', () => {
      console.log('👁️ Widget opened by user');
    });

    ocularWidgetInstance.on('closed', () => {
      console.log('❌ Widget closed by user');
    });

    ocularWidgetInstance.on('call-started', (eventData) => {
      console.log('📞 Call started:', eventData);
    });

    ocularWidgetInstance.on('call-ended', (eventData) => {
      console.log('📴 Call ended:', eventData);
    });

    ocularWidgetInstance.on('scheduled-success', (eventData) => {
      console.log('📅 Appointment scheduled:', eventData);
    });

    // Evento genérico para debugging
    ocularWidgetInstance.on('widget-event', (eventData) => {
      console.log('📡 Widget event:', eventData);
    });
  }

  // Métodos que pueden ser llamados desde cualquier componente
  async openWidget() {
    try {
      await ocularWidgetInstance.show(true); // Abrir completamente
    } catch (error) {
      console.error('Error opening widget:', error);
    }
  }

  async setCustomerInfo(customerData) {
    try {
      await ocularWidgetInstance.setCustomer(customerData);
      console.log('👤 Customer info updated');
    } catch (error) {
      console.error('Error setting customer:', error);
    }
  }

  async toggleWidget() {
    try {
      await ocularWidgetInstance.toggle();
    } catch (error) {
      console.error('Error toggling widget:', error);
    }
  }

  async changeLanguage(locale) {
    try {
      await ocularWidgetInstance.setLocale(locale);
      console.log(`🌍 Language changed to: ${locale}`);
    } catch (error) {
      console.error('Error changing language:', error);
    }
  }
}

// Uso en componente
const manager = new WidgetManager();

// Ejemplo de uso en eventos del componente
document.getElementById('contact-btn').addEventListener('click', () => {
  manager.openWidget();
});

document.getElementById('customer-form').addEventListener('submit', (e) => {
  const customerData = {
    id: e.target.customerId.value,
    name: e.target.customerName.value,
    email: e.target.customerEmail.value
  };
  manager.setCustomerInfo(customerData);
});
```

## Compatibilidad

### Lenguajes y Frameworks
- ✅ **JavaScript (ES5+)** - Sin configuración adicional necesaria
- ✅ **TypeScript** - Declaraciones de tipos incluidas automáticamente  
- ✅ **Vue 3** - Composition API y Options API
- ✅ **React** - Todas las versiones (16.8+)
- ✅ **Angular** - Soporte completo con tipos
- ✅ **Svelte** - Compatible con todos los frameworks modernos
- ✅ **Vanilla JavaScript** - Uso directo sin frameworks

### Navegadores y Entornos
- **Navegadores:** Chrome, Firefox, Safari, Edge (versiones modernas)
- **Entornos:** Solo funciona en el cliente (navegador), no en servidor
- **Bundlers:** Vite, Webpack, Rollup, Parcel
- **Module Systems:** ES Modules, CommonJS

### Configuración Cero
- **JavaScript**: Funciona inmediatamente sin configuración
- **TypeScript**: Los tipos se detectan automáticamente  
- **Bundlers**: Compatible con tree-shaking y code splitting

## Notas Importantes

1. **Solo Cliente**: El SDK solo funciona en entornos de navegador, no en servidor
2. **Singleton**: El widget se inicializa una sola vez por página
3. **Inicialización única**: `initOcularWidget()` debe ejecutarse UNA SOLA VEZ al cargar la aplicación (generalmente en main.js, index.js o App.js). Después de eso, `ocularWidgetInstance` puede ser usado en cualquier componente
4. **Evento is-ready**: **CRÍTICO** - Los métodos `show()`, `hide()`, `toggle()`, `setCustomer()`, `setLocale()` solo funcionan después de que se emita el evento `is-ready`
5. **Async/Await**: Todos los métodos del widget son asíncronos
6. **Eventos**: Los eventos se disparan automáticamente según las interacciones del usuario
7. **Error Handling**: Siempre maneja los errores en las promesas
8. **Instancia global**: Una vez inicializado, `ocularWidgetInstance` está disponible globalmente para toda la aplicación

## Soporte

Para soporte técnico o reportar issues, contacta al equipo de Ocular Solution.