Overview y stack

Qué es

EMA FHIR SDK es la librería TypeScript que los productos del ecosistema EMA usan para hablar con Aidbox. No es un cliente HTTP genérico: encapsula las decisiones FHIR específicas de EMA (perfiles sin versión, tags de tenant, multi-país, validadores nacionales), y se asegura de que cada escritura llegue a Aidbox con su meta.profile y meta.tag correctos sin que los productos consumidores tengan que hacerlo a mano.

Estado del producto

Versión 0.6.0 — Wave 1 cerrada, post-refactor mayor (mayo 2026).

El refactor reemplazó el mirror estático de países por un ProfileResolver runtime que lee desde emashared.countries. Esto desacopla el SDK del release del IG: cuando Vault publica un nuevo país o cambia el canonical base, los productos no necesitan actualizar el SDK ni redeployar.

Consumidor activo: emaclinic. Pendientes de migración Wave 3: emalab, emavault, emawell.

Stack

Capa	Tecnología	Versión
Lenguaje	TypeScript (target ES2022)	5+
Empaquetador	tsup	^8.4
Tests	Vitest	^3.0
Tipos FHIR	`@types/fhir` (referencia para 35 resources handcrafted)	^0.0.41
Runtime deps	ninguna — fetch nativo	—
Peer deps	`@supabase/supabase-js` (para `ProfileResolver`)	≥ 2.49
Peer deps opcionales	`react` (sólo subpath `/sdc`)	≥ 18

ESM-only. Targets soportados: Cloudflare Workers, Deno, Bun y Node 18+.

Subpaths exportados

package.json define 6 entry points tree-shakeables:

Subpath	Para qué
`emafhir`	Core: `createClient`, `createEmaClient`, helpers, `ref`, `transaction`
`emafhir/auth`	Estrategias de auth: `clientCredentials`, `bearerAuth`
`emafhir/search`	`SearchBuilder` fluent API
`emafhir/types`	Tipos FHIR R4 (35 resources) + `ResourceTypeMap`
`emafhir/sdc`	Renderer headless de Questionnaires
`emafhir/validators`	`validateRun`, `validateCurp`, `validateRfc`, `validateDni`

Repo

github.com/emahealth/emafhir

Decisiones registradas

54 decisiones formales (F001-F054) en docs/decisions.md del repo. Las más críticas:

F050-F054 — refactor a ProfileResolver (supersede F044+F045 hardcoded countries).
ADR-0001 — meta-inject idempotente.
ADR-0002 — meta.profile sin versión (Aidbox FAR resuelve).