@fhiron/sdk

Embebe validación FHIR® contra CL Core v1.9.4 dentro de tu aplicación. Mismo motor que @fhiron/cli y @fhiron/mcp-connector: misma API, misma cuota, mismo CL Core.

• Cliente tipado (TypeScript de primera clase, .d.ts incluidos)
• Errores en español, con referencia al perfil que falla
• Zero dependencies, Node 18+, ESM y CommonJS
• lint() estructural offline (sin red, sin cuota) + validate() remoto

Tres canales, misma plataforma: conversa con tu agente vía MCP, automatiza en terminal y CI con la CLI, embebe la validación en tu producto con el SDK.

Instalación

npm install @fhiron/sdk

Necesitas una API key de tu tenant. Genérala en fhiron.cl/dashboard.

Uso

import { Fhiron } from '@fhiron/sdk';

const fhiron = new Fhiron({ apiKey: process.env.FHIRON_API_KEY });

const patient = {
  resourceType: 'Patient',
  identifier: [{ system: 'http://www.registrocivil.cl/run', value: '12345678-9' }],
  name: [{ family: 'Pérez', given: ['Ana'] }],
  gender: 'female',
};

const result = await fhiron.validate(patient);

if (!result.ok) {
  for (const issue of result.errors) {
    console.log(`${issue.path}: ${issue.message}`);
  }
}

CommonJS:

const { Fhiron } = require('@fhiron/sdk');

API

new Fhiron(options?)

| Opción | Tipo | Default | Descripción | |-----------------|----------|--------------------------------------------|-------------| | apiKey | string | process.env.FHIRON_API_KEY | API key del tenant. | | baseUrl | string | https://fhiron.cl (o FHIRON_API_URL) | Base de la API. | | timeout | number | 10000 | Timeout por petición (ms). | | clCoreVersion | string | resuelto por el tenant | Fija la versión de CL Core, ej. "1.9.4". | | language | string | "es" | Idioma de los mensajes ("es" | "en"). |

await fhiron.validate(resource, opts?)

Valida un recurso FHIR (o un Bundle) contra CL Core en el motor remoto. Descuenta 1 de la cuota mensual. Devuelve un ValidateResult:

interface ValidateResult {
  valid: boolean;            // el motor no encontró errores
  ok: boolean;               // valid && !engineDegraded: úsalo para gate
  engineDegraded: boolean;   // el motor no pudo validar (NO se descontó cuota)
  resourceType: string | null;
  profile: string | null;
  issues: Issue[];           // todos los hallazgos, en español
  errors: Issue[];           // atajo: severity === 'error'
  warnings: Issue[];
  information: Issue[];
  messages: { errors: string[]; warnings: string[] };
  raw: Record<string, unknown>;  // respuesta cruda del endpoint
}

opts: { profile?, clCoreVersion?, timeout? }. profile acepta "[email protected]" o "1.9.4".

fhiron.lint(resource)

Lint estructural offline (sin red, sin cuota). Devuelve Issue[]. Útil para feedback inmediato en un editor o un formulario antes de gastar una validación remota.

await fhiron.check(resource, opts?)

Conveniencia: corre lint() local y validate() remoto, y adjunta localIssues al resultado.

Manejo de errores

validate() lanza errores tipados ante fallos HTTP o de red. Todos extienden FhironError:

import { FhironQuotaError, FhironAuthError, FhironError } from '@fhiron/sdk';

try {
  await fhiron.validate(resource);
} catch (err) {
  if (err instanceof FhironQuotaError) {
    console.log('Cuota agotada. Upgrade en', err.upgradeUrl);
  } else if (err instanceof FhironAuthError) {
    console.log('Revisa tu API key.');
  } else if (err instanceof FhironError) {
    console.log('Fallo de Fhiron:', err.message);
  }
}

| Clase | Cuándo | |----------------------|--------| | FhironAuthError | HTTP 401 / 403: key ausente, inválida o sin permisos. | | FhironQuotaError | HTTP 429: cuota agotada (.upgradeUrl). | | FhironRequestError | HTTP 400 / 415 / 422: problema de forma del recurso. | | FhironServerError | HTTP 5xx: servidor o motor. Reintentable. | | FhironTimeoutError | Supera timeout. Reintentable. | | FhironNetworkError | Fallo de red / offline. Reintentable. |

Notas

• La validación remota cumple la misma política de cuota que el resto de Fhiron: se descuenta por recurso validado contra el endpoint canónico.
• lint() es estructural y local; no reemplaza a validate(), que corre el motor HAPI + perfiles CL Core.
• Cuando engineDegraded es true, el motor remoto no pudo procesar el recurso (problema sistémico del servidor) y no se descontó cuota.

Licencia

MIT