Connect

ixiclinic Connect (@ixiclinic/connect, en bridge/) es el agente local de hardware. Se instala en una máquina dentro de la red (LAN) de la sucursal y es la única pieza que alcanza el hardware del laboratorio (impresoras de red en el puerto 9100, impresoras USB del SO, cajón de dinero). Se conecta saliente al cloud por Socket.IO (atraviesa NAT, sin abrir puertos) y ejecuta los trabajos de impresión que el API le enruta.

Nota: Connect no forma parte del workspace de pnpm. El workspace solo incluye apps/* y packages/* (pnpm-workspace.yaml); bridge/ es un proyecto hermano en la raíz con su propio bun.lock. Por eso no se levanta con pnpm dev ni con Turbo.

Ver también la guía completa de Impresión y Bridge.

Por qué existe

El cloud no alcanza la LAN del cliente: una impresora térmica en el mostrador no es accesible desde api.ixiclinic.com. Connect cierra esa brecha conectándose hacia afuera y haciendo de puente entre el cloud y el hardware físico.

Arquitectura (bridge/src/)

Enrolamiento por token

1. En el admin: Hardware → Nuevo agente y se copia su token.
2. El agente se autentica enviando ese token en el header x-bridge-token en cada llamada HTTP (BridgeApi); el socket lo pasa en auth: { token }.
3. El token puede venir por env (IXICLINIC_BRIDGE_TOKEN), por flag (--token) o guardarse en la config local (~/.ixiclinic-bridge/config.json) para los próximos arranques.

Endpoints del bridge (todos autenticados por el token): POST /api/bridge/register, POST /api/bridge/heartbeat, POST /api/bridge/printers, GET /api/bridge/jobs, POST /api/bridge/jobs/{id}/result, GET /api/bridge/latest.

Flujo de trabajos: poll + push

El diseño separa la fuente de verdad de la señal:

• El poll GET /api/bridge/jobs es la fuente de verdad. El agente consulta cada IXICLINIC_POLL_MS (default 15 s); aunque el socket se caiga, el poll recupera los trabajos.
• El push por socket (evento job:new) es solo un "despertador": al recibirlo, el agente dispara un poll inmediato en lugar de esperar el intervalo. printers:rescan fuerza un re-descubrimiento.
• El servidor maneja los reintentos: un trabajo fallido vuelve a pending y reaparece en el siguiente poll. El agente reporta el estado con POST /api/bridge/jobs/{id}/result (printing / done / failed).

Variables de entorno

Desarrollo

En dev el agente corre con tsx (no con Bun):

cd bridge
bun install
IXICLINIC_API_URL=https://api.ixiclinic.com IXICLINIC_BRIDGE_TOKEN=<token> bun run dev
# bun run dev === "tsx watch src/index.ts"; también vale Node ≥ 18

Probar la impresión desde el admin o por API:

POST /api/printing/jobs
{ "role": "test", "documentType": "test" }

Instalación en producción

Tras crear el agente en el admin y copiar su token, en la máquina con la impresora se ejecuta una vez el instalador (bridge/install/install.sh en macOS/Linux, bridge/install/install.ps1 en Windows). El instalador descarga el binario del último Release, lo registra como servicio (systemd / launchd / tarea de Windows) y lo arranca. El agente avisa en sus logs cuando hay una versión nueva (GET /api/bridge/latest).

Empaquetado y release

Bun se usa para compilar el agente a un binario único (no como runtime de dev):

bun build src/index.ts --compile --outfile dist/ixiclinic-connect

El workflow .github/workflows/connect-release.yml (disparado por un tag connect-v* o manual) hace que Bun cross-compile desde un solo runner los binarios para Linux, Windows y macOS (Apple Silicon + Intel) y los adjunta a un GitHub Release.

Pendiente

• Firma de binarios (notarization de Apple / Authenticode).
• Self-update del binario en ejecución (hoy avisa para reinstalar).
• Descubrimiento por mDNS/Bonjour y estado por SNMP (papel, online).
• Conector de instrumentos de laboratorio (serial/TCP → resultados).