@fhiron/sdk 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# @fhiron/sdk
+
+Embebe validación FHIR® contra **CL Core v1.9.4** dentro de tu aplicación. Mismo motor que [`@fhiron/cli`](https://www.npmjs.com/package/@fhiron/cli) y [`@fhiron/mcp-connector`](https://www.npmjs.com/package/@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
+
+```bash
+npm install @fhiron/sdk
+```
+
+Necesitas una API key de tu tenant. Genérala en [fhiron.cl/dashboard](https://fhiron.cl/dashboard).
+
+## Uso
+
+```ts
+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:
+
+```js
+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`:
+
+```ts
+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 `"hl7.fhir.cl.clcore@1.9.4"` 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`:
+
+```ts
+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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@fhiron/sdk",
+  "version": "0.1.0",
+  "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",
+  "module": "src/index.mjs",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs",
+      "require": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "keywords": [
+    "fhir",
+    "sdk",
+    "cl-core",
+    "chile",
+    "hl7",
+    "validation",
+    "validador",
+    "deis",
+    "minsal",
+    "tfc",
+    "typescript",
+    "spanish"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Fhironstack/skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Fhironstack/skills/issues"
+  },
+  "homepage": "https://fhiron.cl/sdk",
+  "scripts": {
+    "test": "node --test 'test/*.test.js'",
+    "sync-linter": "bash scripts/sync-linter.sh",
+    "typecheck": "tsc --noEmit --strict src/index.d.ts test/types.test-d.ts",
+    "prepublishOnly": "bash scripts/sync-linter.sh && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}