JavaScript

Esta guía muestra cómo integrar SofIA SDK en aplicaciones que utilizan JavaScript nativo sin frameworks adicionales.

Configuración inicial

1. Instalación

npm install @omniloy/sofia-sdk

2. Importación del componente

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>SofIA SDK - Vanilla JS</title>
    
    <!-- Importar el componente -->
    <script type="module">
        import '@omniloy/sofia-sdk';
    </script>
</head>
<body>
    <!-- El componente estará disponible aquí -->
</body>
</html>

Implementación básica

Estructura HTML

<div id="sofia-container">
    <!-- language="es" es el valor por defecto (español) -->
    <sofia-sdk
        id="sofia"
        apikey="your-api-key"
        userid="user_12345"
        patientid="patient_67890"
        templateid="clinical-notes-v1"
        language="es"
        isopen="false"
        template='{
            "$schema": "http://json-schema.org/draft-07/schema#",
            "title": "clinical_notes",
            "type": "object",
            "required": ["diagnosis"],
            "properties": {
                "diagnosis": {"type": "string", "description": "Diagnóstico principal"}
            }
        }'
    ></sofia-sdk>
    
    <button id="toggle-sofia">Abrir/Cerrar SofIA</button>
</div>

Configuración JavaScript

// Esperar a que el componente esté definido
customElements.whenDefined('sofia-sdk').then(() => {
    const sofiaComponent = document.getElementById('sofia');
    const toggleButton = document.getElementById('toggle-sofia');
    
    // Configurar callback para recibir reportes
    sofiaComponent.handleReport = (report) => {
        console.log('Reporte clínico recibido:', report);
        
        // Procesar el reporte según sus necesidades
        displayReport(report);
        sendToEHR(report);
    };
    
    // Configurar callback para cambios de visibilidad
    sofiaComponent.setIsOpen = (isOpen) => {
        console.log('Estado del componente:', isOpen ? 'Abierto' : 'Cerrado');
        sofiaComponent.isopen = isOpen;
        toggleButton.textContent = isOpen ? 'Cerrar SofIA' : 'Abrir SofIA';
    };
    
    // Manejar click del botón
    toggleButton.addEventListener('click', () => {
        const currentState = sofiaComponent.getAttribute('isopen') === 'true';
        sofiaComponent.setAttribute('isopen', String(!currentState));
    });
});

// Función para mostrar el reporte en la interfaz
function displayReport(report) {
    const reportContainer = document.getElementById('report-display');
    if (reportContainer) {
        const heading = document.createElement('h3');
        heading.textContent = 'Reporte Clínico';
        const pre = document.createElement('pre');
        pre.textContent = JSON.stringify(report, null, 2);
        reportContainer.replaceChildren(heading, pre);
    }
}

// Función para enviar al sistema EHR/HIS
function sendToEHR(report) {
    // Implementar integración con su sistema
    fetch('/api/clinical-reports', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(report)
    }).then(response => {
        console.log('Reporte enviado al EHR:', response.status);
    }).catch(error => {
        console.error('Error enviando reporte:', error);
    });
}

Obtener el último reporte

Use el callback set-get-last-report para acceder al último reporte generado para la sesión actual de paciente/usuario. El SDK proporciona una función que retorna una Promise que resuelve al reporte almacenado (o undefined si no existe).

sofiaComponent.setGetLastReport = (getLastReportFn) => {
    // Guardar la función para uso posterior
    window.getLastSofiaReport = getLastReportFn;
};

// Después, obtener el último reporte
async function fetchLastReport() {
    const report = await window.getLastSofiaReport();
    if (report) {
        console.log('Último reporte:', report);
    }
}

Añada debug="true" al elemento <sofia-sdk> para habilitar logging detallado en consola. Esto es útil durante el desarrollo para rastrear eventos del ciclo de vida del SDK, estado de conexión y validación de configuración.

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

Gestión de estados

Control de visibilidad

const sofiaComponent = document.querySelector('sofia-sdk');

// Abrir programáticamente
function openSofia() {
    sofiaComponent.isopen = true;
}

// Cerrar programáticamente  
function closeSofia() {
    sofiaComponent.isopen = false;
}

// Alternar estado
function toggleSofia() {
    const isCurrentlyOpen = sofiaComponent.getAttribute('isopen') === 'true';
    sofiaComponent.setAttribute('isopen', String(!isCurrentlyOpen));
}

Actualización de datos del paciente

// Actualizar información del paciente
function updatePatientData(newPatientId, patientInfo) {
    sofiaComponent.patientid = newPatientId;
    sofiaComponent.patientdata = JSON.stringify(patientInfo);
}

// Ejemplo de uso
updatePatientData('patient_98765', {
    fullName: 'María García',
    birthDate: '1979-03-15',
    extraData: {
        medical_practice: 'Medicina Interna',
        allergies: ['Penicilina'],
        chronic_conditions: ['Diabetes tipo 2', 'Hipertensión']
    }
});

Consulta Datos del paciente para la referencia completa de la estructura de datos.

Manejo de errores

El SDK registra todos los errores en la consola del navegador con el prefijo [Sofia SDK]. Habilita debug="true" para ver la salida detallada de errores. Maneja los errores en tus callbacks con try/catch estándar:

sofiaComponent.handleReport = (report) => {
    try {
        // Procesar el reporte
        sendToEHR(report);
    } catch (error) {
        console.error('Error procesando reporte:', error);
        // Mostrar UI de fallback al usuario
    }
};

Para la lista completa de mensajes de error y sus pasos de resolución, consulta la Referencia de errores.

Ejemplo completo

Para ver una implementación completa y funcional, consulte nuestro ejemplo en GitHub: Ver ejemplo completo de Vanilla TypeScript → El ejemplo incluye:

Configuración completa del proyecto
Manejo avanzado de estados
Integración con APIs mockadas
Gestión de errores robusta
Estilado CSS personalizado

Ciclo de vida del componente

Añadir el componente

Espera a que el custom element esté definido antes de configurar los callbacks:

customElements.whenDefined('sofia-sdk').then(() => {
  const sofia = document.querySelector('sofia-sdk');
  sofia.handleReport = handleReport;
});

Eliminar el componente (limpieza en SPAs)

Si tu aplicación añade y elimina SofIA dinámicamente (por ejemplo, enrutamiento del lado del cliente), elimina el elemento del DOM al navegar fuera:

function destroySofia() {
  const sofia = document.querySelector('sofia-sdk');
  if (sofia) {
    sofia.remove();
  }
}

El SDK limpia los recursos internos (conexiones WebSocket, streams de audio) automáticamente cuando el elemento se desconecta del DOM.

Instalación y Configuración

Integración por Framework

Funcionalidades

Soporte

Configuración inicial

1. Instalación

2. Importación del componente

Implementación básica

Estructura HTML

Configuración JavaScript

Obtener el último reporte

Gestión de estados

Control de visibilidad

Actualización de datos del paciente

Manejo de errores

Ejemplo completo

Ciclo de vida del componente

Añadir el componente

Eliminar el componente (limpieza en SPAs)

Consideraciones adicionales

Rendimiento

Seguridad

Próximos pasos

​Configuración inicial

​1. Instalación

​2. Importación del componente

​Implementación básica

​Estructura HTML

​Configuración JavaScript

​Obtener el último reporte

​Gestión de estados

​Control de visibilidad

​Actualización de datos del paciente

​Manejo de errores

​Ejemplo completo

​Ciclo de vida del componente

​Añadir el componente

​Eliminar el componente (limpieza en SPAs)

​Consideraciones adicionales

​Rendimiento

​Seguridad

​Próximos pasos

Configuración inicial

1. Instalación

2. Importación del componente

Implementación básica

Estructura HTML

Configuración JavaScript

Obtener el último reporte

Gestión de estados

Control de visibilidad

Actualización de datos del paciente

Manejo de errores

Ejemplo completo

Ciclo de vida del componente

Añadir el componente

Eliminar el componente (limpieza en SPAs)

Consideraciones adicionales

Rendimiento

Seguridad

Próximos pasos