@fhiron/sdk 0.1.0

package/src/index.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const { postJson } = require('./http.js');
+const errors = require('./errors.js');
+const linter = require('./_linter/rules.js');
+const pkg = require('../package.json');
+
+const DEFAULT_BASE_URL = 'https://fhiron.cl';
+const DEFAULT_TIMEOUT = 10_000;
+const DEFAULT_LANGUAGE = 'es';
+
+/**
+ * Cliente del SDK de Fhiron. Embebe la validación FHIR contra CL Core en tu
+ * aplicación: misma API, misma cuota y mismo motor que @fhiron/cli y
+ * @fhiron/mcp-connector.
+ *
+ * @example
+ *   const { Fhiron } = require('@fhiron/sdk');
+ *   const fhiron = new Fhiron({ apiKey: process.env.FHIRON_API_KEY });
+ *   const result = await fhiron.validate(patient);
+ *   if (!result.ok) result.errors.forEach(e => console.log(e.path, e.message));
+ */
+class Fhiron {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.apiKey]        default: process.env.FHIRON_API_KEY
+   * @param {string} [options.baseUrl]       default: https://fhiron.cl (o FHIRON_API_URL)
+   * @param {number} [options.timeout]       ms, default 10000
+   * @param {string} [options.clCoreVersion] ej. "1.9.4" — fija la versión de CL Core
+   * @param {string} [options.language]      "es" | "en", default "es"
+   */
+  constructor(options = {}) {
+    this.apiKey = options.apiKey || process.env.FHIRON_API_KEY || null;
+    this.baseUrl = stripTrailingSlash(
+      options.baseUrl || process.env.FHIRON_API_URL || DEFAULT_BASE_URL,
+    );
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    this.clCoreVersion = normalizeVersion(options.clCoreVersion) || null;
+    this.language = options.language || DEFAULT_LANGUAGE;
+  }
+
+  /**
+   * Valida un recurso FHIR contra CL Core en el motor remoto (HAPI + perfiles).
+   * Descuenta 1 de la cuota mensual del tenant. Funciona también con Bundles
+   * (basta con que el recurso tenga `resourceType: "Bundle"`).
+   *
+   * @param {object} resource  recurso FHIR con `resourceType` en la raíz
+   * @param {object} [opts]
+   * @param {string} [opts.profile]        "hl7.fhir.cl.clcore@1.9.4" o "1.9.4"
+   * @param {string} [opts.clCoreVersion]  override puntual de la versión
+   * @param {number} [opts.timeout]
+   * @param {AbortSignal} [opts.signal]    (reservado; el timeout interno aplica)
+   * @returns {Promise<ValidateResult>}
+   */
+  async validate(resource, opts = {}) {
+    if (!this.apiKey) {
+      throw new errors.FhironAuthError(
+        'Falta la API key. Pásala a new Fhiron({ apiKey }) o exporta FHIRON_API_KEY.',
+      );
+    }
+    assertResource(resource);
+
+    const version =
+      normalizeVersion(opts.clCoreVersion) ||
+      versionFromProfile(opts.profile) ||
+      this.clCoreVersion;
+
+    const raw = await postJson(`${this.baseUrl}/api/validate`, {
+      apiKey: this.apiKey,
+      body: resource,
+      timeout: opts.timeout || this.timeout,
+      userAgent: `${pkg.name}/${pkg.version}`,
+      headers: {
+        'Accept-Language': this.language,
+        ...(version ? { 'X-Fhiron-CL-Core-Version': version } : {}),
+      },
+    });
+
+    return normalizeResult(raw);
+  }
+
+  /**
+   * Lint estructural OFFLINE (no toca la red, no descuenta cuota). Usa el
+   * mismo linter embebido que el MCP y la CLI. Útil para feedback inmediato
+   * antes de gastar una validación remota.
+   *
+   * @param {object} resource
+   * @returns {Issue[]}
+   */
+  lint(resource) {
+    assertResource(resource, { allowMissingType: true });
+    const issues = linter.lintResource(resource) || [];
+    return issues.map(normalizeIssue);
+  }
+
+  /**
+   * Conveniencia: lint local + validación remota en un solo llamado.
+   * Devuelve el resultado remoto con los issues locales adjuntos en
+   * `localIssues` (no se duplican con los del servidor, que ya los incluye).
+   * @param {object} resource
+   * @param {object} [opts]
+   * @returns {Promise<ValidateResult & { localIssues: Issue[] }>}
+   */
+  async check(resource, opts = {}) {
+    const localIssues = this.lint(resource);
+    const result = await this.validate(resource, opts);
+    return { ...result, localIssues };
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+function assertResource(resource, { allowMissingType = false } = {}) {
+  if (!resource || typeof resource !== 'object' || Array.isArray(resource)) {
+    throw new errors.FhironRequestError(
+      'El recurso debe ser un objeto FHIR (no string, array ni null).',
+    );
+  }
+  if (!allowMissingType && typeof resource.resourceType !== 'string') {
+    throw new errors.FhironRequestError(
+      'El recurso no tiene `resourceType` en la raíz. Todo recurso FHIR debe declararlo (ej. "Patient").',
+    );
+  }
+}
+
+function normalizeResult(raw) {
+  const data = raw && typeof raw === 'object' ? raw : {};
+  const issues = Array.isArray(data.issues) ? data.issues.map(normalizeIssue) : [];
+  const engineDegraded = data.engineDegraded === true;
+  const errorIssues = issues.filter((i) => i.severity === 'error');
+  // `valid` se deriva de los issues (locales + servidor), NO del flag crudo del
+  // API: ese flag solo cuenta errores de HAPI e ignora los del linter local,
+  // así que podía venir `valid:true` con un error en `issues`. Derivarlo aquí
+  // garantiza que valid/ok/errors sean siempre coherentes entre sí. El flag
+  // crudo del servidor sigue disponible en `raw.valid`.
+  const valid = errorIssues.length === 0;
+  return {
+    valid,
+    ok: valid && !engineDegraded,
+    engineDegraded,
+    resourceType: data.resourceType || null,
+    profile: data.profile || null,
+    issues,
+    errors: errorIssues,
+    warnings: issues.filter((i) => i.severity === 'warning'),
+    information: issues.filter((i) => i.severity === 'information' || i.severity === 'info'),
+    messages: {
+      errors: Array.isArray(data.errors) ? data.errors : [],
+      warnings: Array.isArray(data.warnings) ? data.warnings : [],
+    },
+    raw: data,
+  };
+}
+
+function normalizeIssue(i) {
+  if (!i || typeof i !== 'object') {
+    return { severity: 'error', code: 'unknown', path: '', message: String(i) };
+  }
+  return {
+    severity: i.severity || i.level || 'warning',
+    code: i.code || i.rule || 'unknown',
+    path: i.path || i.location || '',
+    message: i.message || i.text || '',
+    why: i.why,
+    profileUrl: i.profileUrl || i.profile,
+    docsUrl: i.docsUrl,
+    suggestion: i.suggestion || (i.quickFix && i.quickFix.title) || undefined,
+    quickFix: i.quickFix,
+  };
+}
+
+function versionFromProfile(profile) {
+  if (!profile || typeof profile !== 'string') return null;
+  const at = profile.lastIndexOf('@');
+  const candidate = at !== -1 ? profile.slice(at + 1) : profile;
+  return /^\d+\.\d+\.\d+$/.test(candidate) ? candidate : null;
+}
+
+function normalizeVersion(v) {
+  if (!v || typeof v !== 'string') return null;
+  return /^\d+\.\d+\.\d+$/.test(v) ? v : null;
+}
+
+function stripTrailingSlash(url) {
+  return typeof url === 'string' ? url.replace(/\/+$/, '') : url;
+}
+
+module.exports = {
+  Fhiron,
+  // Cliente por defecto opcional: usa FHIRON_API_KEY de la env.
+  ...errors,
+  versionFromProfile,
+  VERSION: pkg.version,
+};

package/src/index.mjs

@@ -0,0 +1,16 @@
+// ESM wrapper sobre el módulo CommonJS. Permite `import { Fhiron } from '@fhiron/sdk'`
+// en proyectos ESM/TypeScript sin duplicar la lógica.
+import mod from './index.js';
+
+export const Fhiron = mod.Fhiron;
+export const FhironError = mod.FhironError;
+export const FhironAuthError = mod.FhironAuthError;
+export const FhironQuotaError = mod.FhironQuotaError;
+export const FhironRequestError = mod.FhironRequestError;
+export const FhironServerError = mod.FhironServerError;
+export const FhironTimeoutError = mod.FhironTimeoutError;
+export const FhironNetworkError = mod.FhironNetworkError;
+export const versionFromProfile = mod.versionFromProfile;
+export const VERSION = mod.VERSION;
+
+export default mod;