@fhiron/sdk 0.1.0 → 0.1.1

package/README.md

@@ -112,7 +112,7 @@ try {
 |----------------------|--------|
 | `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. |
+| `FhironRequestError` | HTTP 400 / 415: petición malformada (JSON inválido, Content-Type incorrecto). Un recurso inválido NO lanza: devuelve un resultado con `ok:false` y los errores en `result.errors`. |
 | `FhironServerError`  | HTTP 5xx: servidor o motor. Reintentable. |
 | `FhironTimeoutError` | Supera `timeout`. Reintentable. |
 | `FhironNetworkError` | Fallo de red / offline. Reintentable. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fhiron/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Fhiron SDK — embebe validación FHIR® contra CL Core v1.9.4 en tu app. Mismo motor que @fhiron/mcp-connector y @fhiron/cli. Cliente tipado, errores en español, zero dependencies. Node 18+, ESM y CommonJS.",
   "type": "commonjs",
   "main": "src/index.js",

package/src/_linter/catalog.js

@@ -486,7 +486,7 @@ const CATALOG = {
   },
   "cl-cov-04": {
     why: "Coverage en Chile debe identificar al titular de la cobertura. Para Fonasa es el RUN del cotizante, para ISAPRE el número de contrato. Sin `subscriberId` el dispensador no puede liquidar.",
-    suggestion: "`subscriberId: \"15420097-3\"` (RUN del cotizante en Fonasa) o número de contrato ISAPRE.",
+    suggestion: "`subscriberId: \"15420097-5\"` (RUN del cotizante en Fonasa) o número de contrato ISAPRE.",
     docsUrl: DOCS("cl-cov-04"),
   },
   "cl-imm-05": {
@@ -585,12 +585,12 @@ const CATALOG = {
     docsUrl: DOCS("mcp-quota-01"),
   },
   "mcp-net-01": {
-    why: "No se pudo establecer conexión con Fhiron Bridge — red caída, firewall, DNS o el servicio está reiniciando.",
+    why: "No se pudo establecer conexión con Fhiron Inspect: red caída, firewall, DNS o el servicio está reiniciando.",
     suggestion: "Revisa tu conexión, el firewall corporativo y el estado del servicio en https://status.fhiron.cl.",
     docsUrl: DOCS("mcp-net-01"),
   },
   "mcp-server-01": {
-    why: "El servidor respondió 500 — bug en Fhiron Bridge, no en tu recurso.",
+    why: "El servidor respondió 500: bug en Fhiron Inspect, no en tu recurso.",
     suggestion: "Reintenta en unos segundos. Si persiste, reporta el caso en https://github.com/Fhironstack/skills/issues incluyendo el recurso (sin datos sensibles).",
     docsUrl: DOCS("mcp-server-01"),
   },

package/src/_linter/i18n.js

@@ -26,8 +26,8 @@ const DICT = {
 
   // ── serverInfo description ────────────────────────────────────────────────
   "server.description": {
-    es: "Fhiron Bridge — validación FHIR contra CL Core v1.9.4 con errores en español, ejemplos válidos y catálogos terminológicos chilenos (DEIS, TFC, CIE-10).",
-    en: "Fhiron Bridge — FHIR validation against CL Core v1.9.4 with educational issue feedback, valid resource examples, and Chilean terminology catalogs (DEIS, TFC, ICD-10). Server messages are localized; rule explanations remain in Spanish (CL Core is a Chilean implementation guide).",
+    es: "Fhiron Inspect — validación FHIR contra CL Core v1.9.4 con errores en español, ejemplos válidos y catálogos terminológicos chilenos (DEIS, TFC, CIE-10).",
+    en: "Fhiron Inspect — FHIR validation against CL Core v1.9.4 with educational issue feedback, valid resource examples, and Chilean terminology catalogs (DEIS, TFC, ICD-10). Server messages are localized; rule explanations remain in Spanish (CL Core is a Chilean implementation guide).",
   },
 
   // ── Tool descriptions ─────────────────────────────────────────────────────
@@ -68,7 +68,7 @@ const DICT = {
     en: "[FIX] Apply a mechanical quickFix to a FHIR resource using RFC 6901 jsonPointer. QuickFixes come from the `issues[]` array of fhiron_validate or fhiron_lint. Returns the patched resource as JSON. Idempotent: applying the same fix twice yields the same result. Call this tool immediately after validating if the issue has `quickFix` — the AI can auto-correct without asking the user.",
   },
   "tool.get_example.desc": {
-    es: "[SCAFFOLD] Devuelve un recurso FHIR válido CL Core v1.9.4 listo para editar (Patient, Practitioner, Observation, Medication, MedicationRequest, Encounter, Condition, AllergyIntolerance, Procedure, Coverage, Organization, Immunization, DiagnosticReport, Bundle). Útil cuando la IA necesita scaffolding sin alucinar codes, systems o el formato del RUN. Llamá esta tool antes de armar un recurso desde cero.",
+    es: "[SCAFFOLD] Devuelve un recurso FHIR válido CL Core v1.9.4 listo para editar (Patient, Practitioner, Observation, Medication, MedicationRequest, Encounter, Condition, AllergyIntolerance, Procedure, Coverage, Organization, Immunization, DiagnosticReport, Bundle). Útil cuando la IA necesita scaffolding sin alucinar codes, systems o el formato del RUN. Llama esta tool antes de armar un recurso desde cero.",
     en: "[SCAFFOLD] Return a valid CL Core v1.9.4 FHIR resource ready to edit (Patient, Practitioner, Observation, Medication, MedicationRequest, Encounter, Condition, AllergyIntolerance, Procedure, Coverage, Organization, Immunization, DiagnosticReport, Bundle). Useful when the AI needs scaffolding without hallucinating codes, systems or RUN format. Call this tool before building a resource from scratch.",
   },
   "tool.search_terminology.desc": {
@@ -76,7 +76,7 @@ const DICT = {
     en: "[TERMINOLOGY] Search Chilean terminology catalogs: DEIS communes (system 'deis-comuna'), DEIS facilities ('deis-establecimiento'), ATC/TFC medications ('tfc'), ICD-10 diagnoses ('cie10'), CSTipoIdentificador ('identificadores'). Call this tool BEFORE inventing a code — the AI should look up, not guess.",
   },
   "tool.explain_code.desc": {
-    es: "[EXPLAIN] Devuelve la explicación pedagógica completa de un código de error (cl-run-01, cl-patient-04, hapi-error, mcp-quota-01, etc.): qué falla, por qué, qué perfil CL Core lo indica, link de docs, fix sugerido y ejemplo correcto. Llamá esta tool cuando el usuario pregunta '¿qué significa este error?' o '¿por qué falla?'.",
+    es: "[EXPLAIN] Devuelve la explicación pedagógica completa de un código de error (cl-run-01, cl-patient-04, hapi-error, mcp-quota-01, etc.): qué falla, por qué, qué perfil CL Core lo indica, link de docs, fix sugerido y ejemplo correcto. Llama esta tool cuando el usuario pregunta '¿qué significa este error?' o '¿por qué falla?'.",
     en: "[EXPLAIN] Return the full educational explanation of an error code (cl-run-01, cl-patient-04, hapi-error, mcp-quota-01, etc.): what fails, why, which CL Core profile flags it, docs link, suggested fix and valid example. Call this tool when the user asks 'what does this error mean?' or 'why is it failing?'.",
   },
 
@@ -137,12 +137,12 @@ const DICT = {
   },
   "err.resource_type.short": { es: "Falta resourceType.", en: "Missing resourceType." },
   "err.timeout": {
-    es: "Fhiron Bridge tardó más de 10s en responder. Reintenta en un momento.",
-    en: "Fhiron Bridge took longer than 10s to respond. Please retry in a moment.",
+    es: "Fhiron Inspect tardó más de 10s en responder. Reintenta en un momento.",
+    en: "Fhiron Inspect took longer than 10s to respond. Please retry in a moment.",
   },
   "err.network": {
-    es: (v) => `No se pudo conectar a Fhiron Bridge (${v.endpoint}). Revisa tu conexión o el estado del servicio en status.fhiron.cl.`,
-    en: (v) => `Could not connect to Fhiron Bridge (${v.endpoint}). Check your connection or service status at status.fhiron.cl.`,
+    es: (v) => `No se pudo conectar a Fhiron Inspect (${v.endpoint}). Revisa tu conexión o el estado del servicio en status.fhiron.cl.`,
+    en: (v) => `Could not connect to Fhiron Inspect (${v.endpoint}). Check your connection or service status at status.fhiron.cl.`,
   },
   "err.auth": {
     es: (v) => `API key rechazada (HTTP ${v.status}). Verifica el valor en https://fhiron.cl/dashboard/connect-ai.`,
@@ -154,16 +154,16 @@ const DICT = {
     en: (v) => `${v.detail} Upgrade your plan at https://fhiron.cl/precios.`,
   },
   "err.server_500": {
-    es: "Fhiron Bridge tuvo un error interno. Intenta de nuevo en unos segundos.",
-    en: "Fhiron Bridge had an internal error. Please retry in a few seconds.",
+    es: "Fhiron Inspect tuvo un error interno. Intenta de nuevo en unos segundos.",
+    en: "Fhiron Inspect had an internal error. Please retry in a few seconds.",
   },
   "err.server_5xx": {
     es: (v) => `Servicio temporalmente no disponible (HTTP ${v.status}). Reintenta en 1-2 minutos o revisa status.fhiron.cl.`,
     en: (v) => `Service temporarily unavailable (HTTP ${v.status}). Retry in 1-2 minutes or check status.fhiron.cl.`,
   },
   "err.server_other": {
-    es: (v) => `Fhiron Bridge respondió ${v.status}: ${v.detail}`,
-    en: (v) => `Fhiron Bridge responded ${v.status}: ${v.detail}`,
+    es: (v) => `Fhiron Inspect respondió ${v.status}: ${v.detail}`,
+    en: (v) => `Fhiron Inspect responded ${v.status}: ${v.detail}`,
   },
   "err.unknown_tool": {
     es: (v) => `Herramienta desconocida: ${v.name}. Disponibles: ${v.list}.`,
@@ -235,8 +235,8 @@ const DICT = {
   // ── Logging notifications (M8) ────────────────────────────────────────────
   "log.lint.start":  { es: (v) => `Linter local sobre ${v.resourceType}…`,                en: (v) => `Local linter on ${v.resourceType}…` },
   "log.lint.done":   { es: (v) => `Linter local: ${v.errors} error(es), ${v.warnings} advertencia(s).`, en: (v) => `Local linter: ${v.errors} error(s), ${v.warnings} warning(s).` },
-  "log.bridge.call": { es: (v) => `Llamando a HAPI Bridge (${v.endpoint})…`,              en: (v) => `Calling HAPI Bridge (${v.endpoint})…` },
-  "log.bridge.done": { es: (v) => `Bridge respondió en ${v.ms}ms (status ${v.status}).`,  en: (v) => `Bridge responded in ${v.ms}ms (status ${v.status}).` },
+  "log.bridge.call": { es: (v) => `Llamando a HAPI Inspect (${v.endpoint})…`,              en: (v) => `Calling HAPI Inspect (${v.endpoint})…` },
+  "log.bridge.done": { es: (v) => `Inspect respondió en ${v.ms}ms (status ${v.status}).`,  en: (v) => `Inspect responded in ${v.ms}ms (status ${v.status}).` },
 
   // ── RUN — errores de validación (módulo 11) ───────────────────────────────
   "run.err.no_dash": {
@@ -358,8 +358,8 @@ const DICT = {
     en: (v) => `Method '${v.method}' requires completing the initialize handshake + notifications/initialized first (MCP spec).`,
   },
   "bridge.fallback.server_error": {
-    es: "Fhiron Bridge respondió con un error inesperado. Intenta de nuevo en unos segundos.",
-    en: "Fhiron Bridge responded with an unexpected error. Please retry in a few seconds.",
+    es: "Fhiron Inspect respondió con un error inesperado. Intenta de nuevo en unos segundos.",
+    en: "Fhiron Inspect responded with an unexpected error. Please retry in a few seconds.",
   },
   "explain.fallback.no_context": {
     es: "No hay explicación adicional disponible para este código.",

package/src/_linter/rules.d.ts

@@ -103,3 +103,15 @@ export declare function listCodes(): string[];
  * Si el código no está en el catálogo, devuelve el issue intacto.
  */
 export declare function enrichIssue(issue: LintIssue): LintIssue;
+
+/**
+ * Recursos FHIR de ejemplo válidos contra CL Core, indexados por resourceType.
+ * Usados por el demo público, el MCP (`fhiron_get_example`) y los docs.
+ */
+export declare const EXAMPLES: Record<string, Record<string, unknown>>;
+
+/** Devuelve un recurso de ejemplo válido para el resourceType dado, o null. */
+export declare function getExample(resourceType: string): Record<string, unknown> | null;
+
+/** Lista los resourceType para los que hay ejemplo disponible. */
+export declare function listExamples(): string[];

package/src/_linter/terminology.js

@@ -151,7 +151,7 @@ const IDENTIFICADORES = [
 const SYSTEMS = {
   "deis-comuna": {
     label: "Comunas DEIS (decreto 817 / MINSAL)",
-    canonical: CS("CodigoComunaDEIS"),
+    canonical: CS("CSCodComunasCL"),
     rows: COMUNAS,
   },
   "deis-establecimiento": {

package/src/http.js

@@ -76,7 +76,11 @@ async function postJson(url, opts) {
     }
   }
 
-  if (res.ok) return payload;
+  // HTTP 422 NO es un error de petición: es el resultado de validación cuando
+  // el recurso es inválido. El endpoint /api/validate responde `valid ? 200 : 422`
+  // con el mismo body (ValidateResponse: { valid, errors, warnings, issues, ... }).
+  // Igual que @fhiron/mcp-connector, tratamos 422 como respuesta normalizable.
+  if (res.ok || res.status === 422) return payload;
 
   throwForStatus(res.status, payload);
 }
@@ -109,7 +113,8 @@ function throwForStatus(status, payload) {
       { ...details, upgradeUrl: (payload && payload.upgrade_url) || 'https://fhiron.cl/precios' },
     );
   }
-  if (status === 400 || status === 415 || status === 422) {
+  // 422 ya no llega aquí (se trata como resultado de validación en postJson).
+  if (status === 400 || status === 415) {
     throw new FhironRequestError(
       serverMsg || `La petición no es válida (HTTP ${status}).`,
       details,

package/src/index.d.ts

@@ -108,7 +108,7 @@ export declare class FhironAuthError extends FhironError {}
 export declare class FhironQuotaError extends FhironError {
   upgradeUrl?: string;
 }
-/** HTTP 400/415/422. */
+/** HTTP 400/415: problema de forma de la petición (el 422 es resultado de validación, no error). */
 export declare class FhironRequestError extends FhironError {}
 /** HTTP 5xx (reintentable). */
 export declare class FhironServerError extends FhironError {}