@fhiron/sdk 0.1.0

package/src/_linter/terminology.js

@@ -0,0 +1,265 @@
+// Fhiron linter — catálogos terminológicos chilenos esenciales.
+//
+// Para `fhiron_search_terminology`: cuando el agente IA dice "necesito el
+// código DEIS de Las Condes" o "el TFC de paracetamol", llama esta tool en
+// vez de alucinar un código.
+//
+// Sistemas soportados:
+//   - "deis-comuna"       → Codificación DEIS de comunas (decreto 817/MINSAL)
+//   - "deis-establecimiento" → Establecimientos de salud DEIS (sin URI canónica oficial)
+//   - "tfc"                → Tabla de Fármacos (códigos ATC — http://www.whocc.no/atc)
+//   - "cie10"              → CIE-10 chileno
+//   - "identificadores"    → CSTipoIdentificador (RUN, pasaporte, etc.)
+//
+// Búsqueda: normalización lower + sin tildes + match parcial. Devuelve hasta
+// `limit` resultados (default 10). Si query es vacío, devuelve los primeros.
+
+"use strict";
+
+const { CS } = require("./catalog.js");
+
+// ── Comunas DEIS (decreto 817 — subset representativo) ───────────────────────
+
+const COMUNAS = [
+  { code: "13101", name: "Santiago",          region: "Metropolitana de Santiago" },
+  { code: "13114", name: "Las Condes",        region: "Metropolitana de Santiago" },
+  { code: "13123", name: "Providencia",       region: "Metropolitana de Santiago" },
+  { code: "13125", name: "Ñuñoa",             region: "Metropolitana de Santiago" },
+  { code: "13110", name: "La Florida",        region: "Metropolitana de Santiago" },
+  { code: "13119", name: "Maipú",             region: "Metropolitana de Santiago" },
+  { code: "13130", name: "Puente Alto",       region: "Metropolitana de Santiago" },
+  { code: "13127", name: "Peñalolén",         region: "Metropolitana de Santiago" },
+  { code: "13104", name: "Conchalí",          region: "Metropolitana de Santiago" },
+  { code: "13132", name: "Quilicura",         region: "Metropolitana de Santiago" },
+  { code: "13301", name: "Colina",            region: "Metropolitana de Santiago" },
+  { code: "01101", name: "Iquique",           region: "Tarapacá" },
+  { code: "02101", name: "Antofagasta",       region: "Antofagasta" },
+  { code: "03101", name: "Copiapó",           region: "Atacama" },
+  { code: "04101", name: "La Serena",         region: "Coquimbo" },
+  { code: "04102", name: "Coquimbo",          region: "Coquimbo" },
+  { code: "05101", name: "Valparaíso",        region: "Valparaíso" },
+  { code: "05109", name: "Viña del Mar",      region: "Valparaíso" },
+  { code: "05804", name: "Quilpué",           region: "Valparaíso" },
+  { code: "06101", name: "Rancagua",          region: "O'Higgins" },
+  { code: "07101", name: "Talca",             region: "Maule" },
+  { code: "08101", name: "Concepción",        region: "Biobío" },
+  { code: "08102", name: "Talcahuano",        region: "Biobío" },
+  { code: "09101", name: "Temuco",            region: "Araucanía" },
+  { code: "10101", name: "Puerto Montt",      region: "Los Lagos" },
+  { code: "11101", name: "Coyhaique",         region: "Aysén" },
+  { code: "12101", name: "Punta Arenas",      region: "Magallanes" },
+  { code: "14101", name: "Valdivia",          region: "Los Ríos" },
+  { code: "15101", name: "Arica",             region: "Arica y Parinacota" },
+  { code: "16101", name: "Chillán",           region: "Ñuble" },
+];
+
+// ── Establecimientos DEIS (subset top hospitales) ────────────────────────────
+
+const ESTABLECIMIENTOS = [
+  { code: "100311", name: "Hospital Clínico Universidad de Chile",                  region: "Metropolitana de Santiago" },
+  { code: "100312", name: "Hospital del Salvador",                                  region: "Metropolitana de Santiago" },
+  { code: "102100", name: "Hospital San Juan de Dios",                              region: "Metropolitana de Santiago" },
+  { code: "103100", name: "Hospital Sótero del Río",                                region: "Metropolitana de Santiago" },
+  { code: "104100", name: "Hospital Barros Luco Trudeau",                           region: "Metropolitana de Santiago" },
+  { code: "104201", name: "Hospital Exequiel González Cortés",                      region: "Metropolitana de Santiago" },
+  { code: "105100", name: "Hospital Padre Hurtado",                                 region: "Metropolitana de Santiago" },
+  { code: "106101", name: "Hospital San José",                                      region: "Metropolitana de Santiago" },
+  { code: "108101", name: "Hospital de Urgencia Asistencia Pública (Posta Central)", region: "Metropolitana de Santiago" },
+  { code: "111301", name: "Hospital Dr. Luis Calvo Mackenna",                       region: "Metropolitana de Santiago" },
+  { code: "112101", name: "Hospital Dr. Roberto del Río",                           region: "Metropolitana de Santiago" },
+  { code: "201100", name: "Hospital Regional de Iquique Dr. Ernesto Torres Galdames", region: "Tarapacá" },
+  { code: "301100", name: "Hospital Dr. Leonardo Guzmán de Antofagasta",            region: "Antofagasta" },
+  { code: "401100", name: "Hospital San Juan de Dios de La Serena",                 region: "Coquimbo" },
+  { code: "501100", name: "Hospital Carlos van Buren",                              region: "Valparaíso" },
+  { code: "501101", name: "Hospital Dr. Gustavo Fricke",                            region: "Valparaíso" },
+  { code: "601100", name: "Hospital Regional Libertador Bernardo O'Higgins",        region: "O'Higgins" },
+  { code: "701100", name: "Hospital Regional de Talca",                             region: "Maule" },
+  { code: "801100", name: "Hospital Clínico Regional Dr. Guillermo Grant Benavente", region: "Biobío" },
+  { code: "901100", name: "Hospital Hernán Henríquez Aravena de Temuco",            region: "Araucanía" },
+  { code: "1001100", name: "Hospital Base Dr. Eduardo Schütz Schroeder",            region: "Los Lagos" },
+];
+
+// ── TFC (Tabla de Fármacos Catalogados — subset esencial) ────────────────────
+
+const TFC = [
+  { code: "C09AA02", name: "Enalapril 10 mg comprimido",          atc: "C09AA02", indication: "Hipertensión" },
+  { code: "C09AA05", name: "Ramipril 5 mg cápsula",                atc: "C09AA05", indication: "Hipertensión" },
+  { code: "C07AB07", name: "Bisoprolol 5 mg comprimido",           atc: "C07AB07", indication: "Cardiovascular" },
+  { code: "C03CA01", name: "Furosemida 40 mg comprimido",          atc: "C03CA01", indication: "Diurético" },
+  { code: "A10BA02", name: "Metformina 850 mg comprimido",         atc: "A10BA02", indication: "Diabetes" },
+  { code: "A10AB04", name: "Insulina lispro 100 UI/mL",            atc: "A10AB04", indication: "Diabetes" },
+  { code: "C10AA01", name: "Simvastatina 20 mg comprimido",        atc: "C10AA01", indication: "Dislipidemia" },
+  { code: "C10AA05", name: "Atorvastatina 20 mg comprimido",       atc: "C10AA05", indication: "Dislipidemia" },
+  { code: "N02BE01", name: "Paracetamol 500 mg comprimido",        atc: "N02BE01", indication: "Analgésico" },
+  { code: "M01AE01", name: "Ibuprofeno 400 mg comprimido",         atc: "M01AE01", indication: "AINE" },
+  { code: "N02AA01", name: "Morfina 10 mg/mL ampolla",             atc: "N02AA01", indication: "Analgésico opioide" },
+  { code: "J01CA04", name: "Amoxicilina 500 mg cápsula",           atc: "J01CA04", indication: "Antibiótico" },
+  { code: "J01CR02", name: "Amoxicilina/Ác. clavulánico 875/125",  atc: "J01CR02", indication: "Antibiótico" },
+  { code: "J01FA10", name: "Azitromicina 500 mg comprimido",       atc: "J01FA10", indication: "Antibiótico" },
+  { code: "R03AC02", name: "Salbutamol 100 mcg inhalador",         atc: "R03AC02", indication: "Asma/EPOC" },
+  { code: "R03BA01", name: "Beclometasona 250 mcg inhalador",      atc: "R03BA01", indication: "Asma" },
+  { code: "N05BA01", name: "Diazepam 10 mg comprimido",            atc: "N05BA01", indication: "Ansiolítico" },
+  { code: "N06AB03", name: "Fluoxetina 20 mg cápsula",             atc: "N06AB03", indication: "Antidepresivo" },
+  { code: "B01AA03", name: "Warfarina 5 mg comprimido",            atc: "B01AA03", indication: "Anticoagulante" },
+  { code: "B01AC06", name: "Ácido acetilsalicílico 100 mg",        atc: "B01AC06", indication: "Antiagregante" },
+];
+
+// ── CIE-10 (subset diagnósticos comunes en Chile) ────────────────────────────
+
+const CIE10 = [
+  { code: "I10",   name: "Hipertensión esencial (primaria)" },
+  { code: "I11.9", name: "Cardiopatía hipertensiva sin insuficiencia cardiaca" },
+  { code: "I20.9", name: "Angina de pecho, no especificada" },
+  { code: "I21.9", name: "Infarto agudo de miocardio, no especificado" },
+  { code: "I50.9", name: "Insuficiencia cardiaca, no especificada" },
+  { code: "I63.9", name: "Infarto cerebral, no especificado" },
+  { code: "E10.9", name: "Diabetes mellitus tipo 1 sin complicaciones" },
+  { code: "E11.9", name: "Diabetes mellitus tipo 2 sin complicaciones" },
+  { code: "E78.5", name: "Hiperlipidemia, no especificada" },
+  { code: "E66.9", name: "Obesidad, no especificada" },
+  { code: "J18.9", name: "Neumonía, no especificada" },
+  { code: "J44.9", name: "EPOC, no especificada" },
+  { code: "J45.9", name: "Asma, no especificada" },
+  { code: "J06.9", name: "Infección aguda de las vías respiratorias superiores" },
+  { code: "K29.7", name: "Gastritis, no especificada" },
+  { code: "K35.8", name: "Apendicitis aguda no especificada" },
+  { code: "K80.2", name: "Cálculo de la vesícula biliar sin colecistitis" },
+  { code: "N39.0", name: "Infección de vías urinarias, sitio no especificado" },
+  { code: "N18.9", name: "Enfermedad renal crónica, no especificada" },
+  { code: "F32.9", name: "Episodio depresivo, no especificado" },
+  { code: "F41.9", name: "Trastorno de ansiedad, no especificado" },
+  { code: "M54.5", name: "Lumbago" },
+  { code: "M17.9", name: "Gonartrosis, no especificada" },
+  { code: "C50.9", name: "Tumor maligno de mama, no especificado" },
+  { code: "C61",   name: "Tumor maligno de la próstata" },
+  { code: "Z00.0", name: "Examen médico general" },
+  { code: "Z34.9", name: "Supervisión de embarazo normal, no especificado" },
+  { code: "O80",   name: "Parto único espontáneo" },
+];
+
+// ── Identificadores chilenos (CSTipoIdentificador) ───────────────────────────
+
+const IDENTIFICADORES = [
+  { code: "01", name: "RUN — Rol Único Nacional",        system: CS("CSTipoIdentificador") },
+  { code: "02", name: "Pasaporte (extranjero)",           system: CS("CSTipoIdentificador") },
+  { code: "03", name: "DNI (extranjero)",                 system: CS("CSTipoIdentificador") },
+  { code: "04", name: "Identificador provisorio MINSAL",  system: CS("CSTipoIdentificador") },
+];
+
+// ── Tabla de sistemas disponibles ────────────────────────────────────────────
+
+const SYSTEMS = {
+  "deis-comuna": {
+    label: "Comunas DEIS (decreto 817 / MINSAL)",
+    canonical: CS("CodigoComunaDEIS"),
+    rows: COMUNAS,
+  },
+  "deis-establecimiento": {
+    label: "Establecimientos de salud DEIS",
+    // MINSAL aún no publica URI canónica oficial para establecimientos.
+    canonical: null,
+    rows: ESTABLECIMIENTOS,
+  },
+  "deis": {
+    // alias agregado: combina comunas + establecimientos
+    label: "DEIS (comunas + establecimientos)",
+    canonical: null,
+    rows: [
+      ...COMUNAS.map((r) => ({ ...r, kind: "comuna" })),
+      ...ESTABLECIMIENTOS.map((r) => ({ ...r, kind: "establecimiento" })),
+    ],
+  },
+  "tfc": {
+    label: "Tabla de Fármacos (códigos ATC)",
+    canonical: "http://www.whocc.no/atc",
+    rows: TFC,
+  },
+  "cie10": {
+    label: "CIE-10 (Clasificación Internacional de Enfermedades)",
+    canonical: "http://hl7.org/fhir/sid/icd-10",
+    rows: CIE10,
+  },
+  "identificadores": {
+    label: "Identificadores chilenos (CSTipoIdentificador)",
+    canonical: CS("CSTipoIdentificador"),
+    rows: IDENTIFICADORES,
+  },
+};
+
+// ── Búsqueda ─────────────────────────────────────────────────────────────────
+
+function normalize(s) {
+  return String(s ?? "")
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, ""); // strip diacritics
+}
+
+/**
+ * Busca en un sistema terminológico.
+ *
+ * @param {string} system — uno de SYSTEMS
+ * @param {string} query — texto libre. Si vacío, devuelve los primeros `limit`.
+ * @param {{limit?:number}} [opts]
+ * @returns {{ system:string, label:string, canonical:string, total:number, results:Array<object> }}
+ */
+function search(system, query, opts) {
+  const limit = (opts && opts.limit) || 10;
+  const sys = SYSTEMS[system];
+  if (!sys) {
+    return {
+      system,
+      label: null,
+      canonical: null,
+      total: 0,
+      results: [],
+      error: `Sistema desconocido. Disponibles: ${Object.keys(SYSTEMS).join(", ")}.`,
+    };
+  }
+
+  const q = normalize(query || "").trim();
+  let matches;
+  if (!q) {
+    matches = sys.rows.slice(0, limit);
+  } else {
+    matches = sys.rows.filter((row) => {
+      const haystack = normalize([row.code, row.name, row.region, row.indication, row.atc].filter(Boolean).join(" "));
+      return haystack.includes(q);
+    }).slice(0, limit);
+  }
+
+  return {
+    system,
+    label: sys.label,
+    canonical: sys.canonical,
+    total: matches.length,
+    results: matches.map((r) => ({
+      ...r,
+      system: sys.canonical,
+    })),
+  };
+}
+
+/**
+ * Lista los sistemas terminológicos disponibles para `fhiron_search_terminology`.
+ * @returns {Array<{system:string, label:string, canonical:string, count:number}>}
+ */
+function listSystems() {
+  return Object.entries(SYSTEMS).map(([key, sys]) => ({
+    system: key,
+    label: sys.label,
+    canonical: sys.canonical,
+    count: sys.rows.length,
+  }));
+}
+
+module.exports = {
+  search,
+  listSystems,
+  SYSTEMS,
+  COMUNAS,
+  ESTABLECIMIENTOS,
+  TFC,
+  CIE10,
+  IDENTIFICADORES,
+};

package/src/errors.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * Jerarquía de errores del SDK. Todos extienden FhironError, así que un
+ * `catch (err) { if (err instanceof FhironError) ... }` captura cualquier
+ * fallo del SDK. Las subclases permiten distinguir el caso sin parsear
+ * mensajes (recomendado para reintentos/UX).
+ */
+class FhironError extends Error {
+  constructor(message, details) {
+    super(message);
+    this.name = 'FhironError';
+    if (details) Object.assign(this, details);
+  }
+}
+
+/** HTTP 401/403 — API key ausente, inválida o sin permisos. */
+class FhironAuthError extends FhironError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = 'FhironAuthError';
+  }
+}
+
+/** HTTP 429 — cuota mensual agotada. `upgradeUrl` apunta al upgrade. */
+class FhironQuotaError extends FhironError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = 'FhironQuotaError';
+  }
+}
+
+/** HTTP 400/415 — el recurso o la petición tienen un problema de forma. */
+class FhironRequestError extends FhironError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = 'FhironRequestError';
+  }
+}
+
+/** HTTP 5xx — el servidor o el motor de validación fallaron. Reintentable. */
+class FhironServerError extends FhironError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = 'FhironServerError';
+  }
+}
+
+/** Timeout de la petición (supera `timeout` ms). Reintentable. */
+class FhironTimeoutError extends FhironError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = 'FhironTimeoutError';
+  }
+}
+
+/** Fallo de red (DNS, conexión rechazada, offline). Reintentable. */
+class FhironNetworkError extends FhironError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = 'FhironNetworkError';
+  }
+}
+
+module.exports = {
+  FhironError,
+  FhironAuthError,
+  FhironQuotaError,
+  FhironRequestError,
+  FhironServerError,
+  FhironTimeoutError,
+  FhironNetworkError,
+};

package/src/http.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const {
+  FhironAuthError,
+  FhironQuotaError,
+  FhironRequestError,
+  FhironServerError,
+  FhironTimeoutError,
+  FhironNetworkError,
+} = require('./errors.js');
+
+/**
+ * POST JSON a la API de Fhiron y mapea los errores HTTP a la jerarquía
+ * tipada del SDK. Devuelve el body parseado (objeto) en caso 2xx.
+ *
+ * Zero-dep: usa el `fetch` global (Node 18+). El timeout se implementa con
+ * AbortController para no colgar el proceso del cliente.
+ *
+ * @param {string} url
+ * @param {object} opts
+ * @param {string} opts.apiKey
+ * @param {unknown} opts.body            recurso FHIR crudo (se serializa)
+ * @param {Record<string,string>} [opts.headers]
+ * @param {number} [opts.timeout]
+ * @param {string} [opts.userAgent]
+ * @returns {Promise<any>}
+ */
+async function postJson(url, opts) {
+  const {
+    apiKey,
+    body,
+    headers = {},
+    timeout = 10_000,
+    userAgent = 'fhiron-sdk',
+  } = opts;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        'User-Agent': userAgent,
+        ...(apiKey ? { 'X-API-Key': apiKey } : {}),
+        ...headers,
+      },
+      body: typeof body === 'string' ? body : JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    if (err && (err.name === 'AbortError' || err.name === 'TimeoutError')) {
+      throw new FhironTimeoutError(`La petición superó el timeout de ${timeout}ms.`, {
+        url,
+        timeout,
+      });
+    }
+    throw new FhironNetworkError(
+      `No se pudo conectar al servidor de Fhiron (${url}): ${err && err.message ? err.message : err}.`,
+      { url, cause: err },
+    );
+  }
+  clearTimeout(timer);
+
+  const text = await res.text();
+  let payload = null;
+  if (text) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = text;
+    }
+  }
+
+  if (res.ok) return payload;
+
+  throwForStatus(res.status, payload);
+}
+
+function throwForStatus(status, payload) {
+  const serverMsg =
+    payload && typeof payload === 'object' && (payload.error || payload.message)
+      ? payload.error || payload.message
+      : typeof payload === 'string' && payload
+        ? payload
+        : null;
+
+  const details = { status, body: payload };
+
+  if (status === 401) {
+    throw new FhironAuthError(
+      serverMsg || 'Falta la API key o es inválida. Genera una en https://fhiron.cl/dashboard.',
+      details,
+    );
+  }
+  if (status === 403) {
+    throw new FhironAuthError(
+      serverMsg || 'La API key no tiene permisos para esta operación.',
+      details,
+    );
+  }
+  if (status === 429) {
+    throw new FhironQuotaError(
+      serverMsg || 'Cuota de validaciones agotada para tu plan.',
+      { ...details, upgradeUrl: (payload && payload.upgrade_url) || 'https://fhiron.cl/precios' },
+    );
+  }
+  if (status === 400 || status === 415 || status === 422) {
+    throw new FhironRequestError(
+      serverMsg || `La petición no es válida (HTTP ${status}).`,
+      details,
+    );
+  }
+  if (status >= 500) {
+    throw new FhironServerError(
+      serverMsg || `Error del servidor de Fhiron (HTTP ${status}). Reintenta en unos segundos.`,
+      details,
+    );
+  }
+  throw new FhironRequestError(serverMsg || `HTTP ${status}.`, details);
+}
+
+module.exports = { postJson, throwForStatus };

package/src/index.d.ts

@@ -0,0 +1,125 @@
+// Type declarations para @fhiron/sdk. El runtime es JS puro (CommonJS + ESM
+// wrapper); estos tipos dan autocompletado y chequeo estricto en proyectos
+// TypeScript que consumen el SDK.
+
+export type Severity = 'error' | 'warning' | 'information' | 'info';
+
+export interface QuickFix {
+  title: string;
+  jsonPointer: string;
+  replacement: unknown;
+}
+
+/** Un hallazgo de validación, ya en español y con referencia al perfil. */
+export interface Issue {
+  /** Identificador estable del hallazgo, ej. "cl-run-01". */
+  code: string;
+  severity: Severity;
+  /** Ruta FHIR con punto (Patient.identifier[0].value). "" para la raíz. */
+  path: string;
+  /** Mensaje en español, con referencia al perfil cuando aplica. */
+  message: string;
+  /** Por qué es un problema (contexto pedagógico), cuando está disponible. */
+  why?: string;
+  /** URL canónica del StructureDefinition / CodeSystem que falla. */
+  profileUrl?: string;
+  /** URL de documentación humana (docs.fhiron.cl/errores/{code}). */
+  docsUrl?: string;
+  /** Sugerencia textual de corrección. */
+  suggestion?: string;
+  /** Corrección automática estructurada, cuando existe. */
+  quickFix?: QuickFix;
+}
+
+export interface ValidateResult {
+  /** true si el motor remoto no encontró errores (y no quedó degradado). */
+  valid: boolean;
+  /** Atajo: `valid && !engineDegraded`. Úsalo para decidir si dejar pasar. */
+  ok: boolean;
+  /** El motor remoto no pudo validar (problema sistémico). NO se descontó cuota. */
+  engineDegraded: boolean;
+  resourceType: string | null;
+  /** Perfil CL Core detectado por el motor, si lo reporta. */
+  profile: string | null;
+  /** Todos los hallazgos (locales + del servidor), normalizados. */
+  issues: Issue[];
+  /** Atajo: issues con severidad error. */
+  errors: Issue[];
+  /** Atajo: issues con severidad warning. */
+  warnings: Issue[];
+  /** Atajo: issues informativos. */
+  information: Issue[];
+  /** Mensajes crudos del servidor (string[]), por si los necesitas tal cual. */
+  messages: { errors: string[]; warnings: string[] };
+  /** Respuesta cruda del endpoint, sin normalizar. */
+  raw: Record<string, unknown>;
+}
+
+export interface FhironOptions {
+  /** API key del tenant. Default: process.env.FHIRON_API_KEY. */
+  apiKey?: string;
+  /** Base URL de la API. Default: https://fhiron.cl (o FHIRON_API_URL). */
+  baseUrl?: string;
+  /** Timeout por petición en ms. Default: 10000. */
+  timeout?: number;
+  /** Versión de CL Core a forzar, ej. "1.9.4". */
+  clCoreVersion?: string;
+  /** Idioma de los mensajes: "es" (default) | "en". */
+  language?: string;
+}
+
+export interface ValidateOptions {
+  /** "hl7.fhir.cl.clcore@1.9.4" o "1.9.4". Se traduce a la versión de CL Core. */
+  profile?: string;
+  /** Override puntual de la versión de CL Core. */
+  clCoreVersion?: string;
+  /** Timeout puntual en ms. */
+  timeout?: number;
+  /** Reservado para cancelación externa. */
+  signal?: AbortSignal;
+}
+
+export declare class Fhiron {
+  apiKey: string | null;
+  baseUrl: string;
+  timeout: number;
+  clCoreVersion: string | null;
+  language: string;
+  constructor(options?: FhironOptions);
+  /** Valida un recurso (o Bundle) contra CL Core en el motor remoto. */
+  validate(resource: object, opts?: ValidateOptions): Promise<ValidateResult>;
+  /** Lint estructural offline (sin red, sin cuota). */
+  lint(resource: object): Issue[];
+  /** Lint local + validación remota; adjunta `localIssues`. */
+  check(
+    resource: object,
+    opts?: ValidateOptions,
+  ): Promise<ValidateResult & { localIssues: Issue[] }>;
+}
+
+// ── Errores ──────────────────────────────────────────────────────────────
+export declare class FhironError extends Error {
+  status?: number;
+  body?: unknown;
+}
+/** HTTP 401/403. */
+export declare class FhironAuthError extends FhironError {}
+/** HTTP 429. */
+export declare class FhironQuotaError extends FhironError {
+  upgradeUrl?: string;
+}
+/** HTTP 400/415/422. */
+export declare class FhironRequestError extends FhironError {}
+/** HTTP 5xx (reintentable). */
+export declare class FhironServerError extends FhironError {}
+/** Timeout (reintentable). */
+export declare class FhironTimeoutError extends FhironError {
+  timeout?: number;
+}
+/** Fallo de red (reintentable). */
+export declare class FhironNetworkError extends FhironError {}
+
+/** "hl7.fhir.cl.clcore@1.9.4" → "1.9.4"; otros → null. */
+export declare function versionFromProfile(profile: string): string | null;
+
+export declare const VERSION: string;