> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Guía de Migración

> Guía paso a paso para migrar de SofIA SDK v0.x a v1.0

Esta guía cubre cada cambio importante y deprecación entre SofIA SDK **v0.0.x** y **v1.0.0**, con ejemplos de código antes/después y un checklist para completar la migración.

Comienza actualizando a la última versión:

```bash theme={null}
npm install @omniloy/sofia-sdk@latest
```

Luego asegúrate de importar el SDK **una vez** en el archivo de entrada de tu aplicación — esta importación por efecto secundario es la que registra el custom element `<sofia-sdk>`. Sin ella, el componente nunca se monta:

```javascript theme={null}
// En tu archivo de entrada (main.js, index.js, app.js, ...)
import '@omniloy/sofia-sdk';
```

¿Usas React? Importa el componente y sus estilos desde el subpath `/react` en su lugar:

```tsx theme={null}
import { Omniscribe } from '@omniloy/sofia-sdk/react';
import '@omniloy/sofia-sdk/react/index.css';
```

<Tip>
  ¿No estás seguro de si el SDK se registró? Ejecuta `customElements.get('sofia-sdk')` en la consola del navegador — debería devolver la definición del componente, no `undefined`.
</Tip>

## Resumen de migración

| Área                   | Qué cambió                                                        | Impacto                                                                  |
| ---------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Prop de template       | `toolsargs` → `template`                                          | **Alto** — debe renombrarse                                              |
| Modo solo-chat         | `isonlychat` eliminado                                            | **Medio** — ahora es auto-detectado                                      |
| Control de generación  | `disablegenerate` eliminado                                       | **Medio** — omitir `template`/`templateid` en su lugar                   |
| Control de acciones    | `disableactions` eliminado                                        | **Bajo** — no montar el componente                                       |
| Personalización UI     | `sofiatitle` eliminado                                            | **Bajo** — el título siempre es "SofIA"                                  |
| Estado de carga        | `isscreenloading` eliminado                                       | **Bajo** — no disponible en Chat UI                                      |
| Transcriptor           | `transcriptorselectvalues` eliminado                              | **Bajo** — sin efecto                                                    |
| Renderizado de reporte | `renderReportContent` eliminado                                   | **Bajo** — no disponible en Chat UI                                      |
| Callback de llenado    | `handleFill` eliminado                                            | **Bajo** — no disponible en Chat UI                                      |
| URLs de conexión       | `wssurl` deprecada (v1.0.7); `baseurl` ahora (v1.0.8) condicional | **Medio** — elimina `wssurl`; quita `baseurl` si tu clave no lo requiere |

## Migración paso a paso

### 1. Renombrar `toolsargs` a `template`

La prop `toolsargs` ha sido renombrada a `template`. El contenido del JSON Schema es idéntico — solo cambia el nombre del atributo.

**Antes (v0.x):**

```html theme={null}
<sofia-sdk
  baseurl="https://api.example.com"
  apikey="tu-key"
  userid="doctor-1"
  patientid="paciente-1"
  toolsargs='{"$schema":"http://json-schema.org/draft-07/schema#","title":"notas","type":"object","properties":{"diagnostico":{"type":"string"}}}'
></sofia-sdk>
```

**Después (v1.0):**

```html theme={null}
<sofia-sdk
  baseurl="https://api.example.com"
  apikey="tu-key"
  userid="doctor-1"
  patientid="paciente-1"
  template='{"$schema":"http://json-schema.org/draft-07/schema#","title":"notas","type":"object","properties":{"diagnostico":{"type":"string"}}}'
  templateid="tu-template-id"
></sofia-sdk>
```

<Warning>
  En v1.0, `templateid` también es requerido para la generación de reportes. Sin ambos `template` y `templateid`, el SDK opera en modo solo-chat.
</Warning>

### 2. Eliminar `isonlychat`

El modo solo-chat ahora es automático. Si omites tanto `template` como `templateid`, el SDK opera en modo solo-chat sin mostrar el botón de generar.

**Antes (v0.x):**

```html theme={null}
<sofia-sdk
  isonlychat="true"
  baseurl="https://..."
  <!-- otras props -->
></sofia-sdk>
```

**Después (v1.0):**

```html theme={null}
<!-- Simplemente omitir template y templateid -->
<sofia-sdk
  baseurl="https://..."
  <!-- otras props -->
></sofia-sdk>
```

### 3. Eliminar `disablegenerate`

Para ocultar el botón de generar, omite `template` y `templateid` en lugar de configurar un flag.

**Antes (v0.x):**

```html theme={null}
<sofia-sdk
  disablegenerate="true"
  toolsargs='...'
  <!-- otras props -->
></sofia-sdk>
```

**Después (v1.0):**

```html theme={null}
<!-- Omitir template y templateid para deshabilitar la generación -->
<sofia-sdk
  baseurl="https://..."
  <!-- otras props, sin template/templateid -->
></sofia-sdk>
```

### 4. Eliminar `disableactions`

Si el componente no debe renderizarse, no lo montes en absoluto en lugar de pasar un flag de deshabilitación.

**Antes (v0.x):**

```html theme={null}
<sofia-sdk disableactions="true" ...></sofia-sdk>
```

**Después (v1.0):**

```javascript theme={null}
// Renderizar condicionalmente según la lógica de tu aplicación
if (deberíaMostrarSofia) {
  document.getElementById('container').innerHTML = '<sofia-sdk ...></sofia-sdk>';
}
```

### 5. Eliminar props deprecadas restantes

Elimina estas props por completo — no tienen efecto en v1.0:

| Prop                       | Razón                                              |
| -------------------------- | -------------------------------------------------- |
| `sofiatitle`               | El título siempre es "SofIA"                       |
| `isscreenloading`          | No disponible en UI basada en Chat                 |
| `transcriptorselectvalues` | Sin efecto                                         |
| `renderReportContent`      | Renderizado personalizado no disponible en Chat UI |
| `handleFill`               | No disponible en Chat UI                           |

### 6. Actualizar asignaciones de callbacks (específico por framework)

Los callbacks `handleReport`, `setIsOpen` y `setGetLastReport` permanecen sin cambios. Sin embargo, verifica que tus bindings son correctos:

**Vanilla JS:**

```javascript theme={null}
document.addEventListener('DOMContentLoaded', () => {
  const sofia = document.querySelector('sofia-sdk');
  sofia.handleReport = (report) => {
    console.log('Reporte:', report);
  };
});
```

**React:**

```jsx theme={null}
useEffect(() => {
  if (sofiaRef.current) {
    sofiaRef.current.handleReport = handleReport;
    sofiaRef.current.setIsOpen = setIsOpen;
  }
}, [handleReport, setIsOpen]);
```

**Angular:**

```typescript theme={null}
ngAfterViewInit() {
  this.sofia.nativeElement.handleReport = this.handleReport.bind(this);
  this.sofia.nativeElement.setIsOpen = this.setIsOpen.bind(this);
}
```

### 7. Eliminar `wssurl`  (v1.0.7+) y simplificar `baseurl` (v1.0.8+)

Desde v1.0.7, `wssurl` está deprecada y se ignora — la URL del WebSocket de transcripción la proporciona la API de settings. Elimínala. Para las claves más nuevas, el SDK (v1.0.8) resuelve el endpoint automáticamente, por lo que también puedes quitar `baseurl` (Omniloy te indica si tu clave lo necesita).

**Antes:**

```html theme={null}
<sofia-sdk
  baseurl="https://api.example.com"
  wssurl="wss://ws.example.com"
  apikey="tu-key"
  userid="doctor-1"
  patientid="paciente-1"
></sofia-sdk>
```

**Después (clave más nueva):**

```html theme={null}
<sofia-sdk
  apikey="tu-key"
  userid="doctor-1"
  patientid="paciente-1"
></sofia-sdk>
```

¿Tu clave todavía requiere `baseurl`? Mantenlo, pero elimina `wssurl` igualmente.

## Checklist de migración

Usa este checklist para verificar que tu migración está completa:

* [ ] Renombrados todos los atributos `toolsargs` a `template`
* [ ] Añadido `templateid` donde se use `template`
* [ ] Eliminado `isonlychat` — modo solo-chat es automático al omitir `template`/`templateid`
* [ ] Eliminado `disablegenerate` — omitir `template`/`templateid` en su lugar
* [ ] Eliminado `disableactions` — montar/desmontar condicionalmente el componente
* [ ] Eliminados `sofiatitle`, `isscreenloading`, `transcriptorselectvalues`
* [ ] Eliminados los callbacks `renderReportContent` y `handleFill`
* [ ] Eliminado `wssurl` — deprecada e ignorada desde v1.0.7
* [ ] Quitado `baseurl` si tu clave no lo requiere (desde v1.0.8); mantenido en caso contrario
* [ ] Verificado que el callback `handleReport` sigue funcionando correctamente
* [ ] Probado con `debug="true"` para confirmar que no hay warnings de deprecación en consola
* [ ] Validado en todos los navegadores objetivo

<Tip>
  Habilita `debug="true"` durante la migración. El SDK registra warnings de deprecación para cualquier prop de v0.x que siga en uso, con el prefijo `[Sofia SDK] DEPRECATED:`.
</Tip>

## Resumen de cambios importantes

### Props eliminadas en v1.0

Estas props fueron deprecadas en v0.0.10 y se eliminan en v1.0. Si aún se pasan, no tienen efecto funcional pero emiten warnings de deprecación cuando `debug="true"` está habilitado.

### Nuevos requisitos en v1.0

* **`templateid`** ahora es requerido junto con `template` para la generación de reportes
* El botón de generar solo aparece cuando **ambos** `template` y `templateid` están configurados
* `template` debe ser un JSON Schema Draft-07 válido con `$schema`, `type` y `properties`

### Props de conexión (cambiadas en v1.0.7)

* `apikey` — prop de conexión requerida (sin cambios)
* `wssurl` — **deprecada e ignorada** desde v1.0.7; la URL del transcriptor ahora la proporciona la API de settings — elimínala

### Props de conexión (cambiadas en v1.0.8)

* `baseurl` — ahora **condicional**: opcional para las claves más nuevas (endpoint auto-resuelto), sigue siendo requerida en caso contrario

### Sin cambios

Estas props funcionan exactamente igual en v1.0:

* `userid`, `patientid` — identificadores de sesión requeridos
* `patientdata` — contexto de paciente opcional
* `language` — localización (`"es"` o `"en"`)
* `debug` — habilita logging detallado
* `isopen` — controla la visibilidad del widget
* `handleReport` — callback de entrega de reportes
* `setIsOpen` — callback de estado de visibilidad
* `setGetLastReport` — recuperación del último reporte