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
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 |
| Toast | toast eliminado | Bajo — sin efecto |
Migración paso a paso
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"
wssurl="wss://ws.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>
<sofia-sdk
baseurl="https://api.example.com"
wssurl="wss://ws.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>
<!-- 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>
<!-- 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>
// 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 |
toast | 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);
};
});
useEffect(() => {
if (sofiaRef.current) {
sofiaRef.current.handleReport = handleReport;
sofiaRef.current.setIsOpen = setIsOpen;
}
}, [handleReport, setIsOpen]);
ngAfterViewInit() {
this.sofia.nativeElement.handleReport = this.handleReport.bind(this);
this.sofia.nativeElement.setIsOpen = this.setIsOpen.bind(this);
}
Checklist de migración
Usa este checklist para verificar que tu migración está completa:
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
Sin cambios
Estas props funcionan exactamente igual en v1.0:
baseurl, wssurl, apikey — props de conexión requeridasuserid, patientid — identificadores de sesión requeridospatientdata — contexto de paciente opcionallanguage — localización ("es" o "en")debug — habilita logging detalladoisopen — controla la visibilidad del widgethandleReport — callback de entrega de reportessetIsOpen — callback de estado de visibilidadsetGetLastReport — recuperación del último reporte
