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:

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:

// 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:

import { Omniscribe } from '@omniloy/sofia-sdk/react';
import '@omniloy/sofia-sdk/react/index.css';

¿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.

​

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):

<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):

<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>

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.

​

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):

<sofia-sdk
  isonlychat="true"
  baseurl="https://..."
  <!-- otras props -->
></sofia-sdk>

Después (v1.0):

<!-- 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):

<sofia-sdk
  disablegenerate="true"
  toolsargs='...'
  <!-- otras props -->
></sofia-sdk>

Después (v1.0):

<!-- 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):

<sofia-sdk disableactions="true" ...></sofia-sdk>

Después (v1.0):

// 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:

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

React:

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

Angular:

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:

<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):

<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

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:.

​

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