@fhirfly-io/shl 0.2.0 → 0.3.1

package/README.md

@@ -14,13 +14,18 @@ Raw codes + patient info → Enriched FHIR Bundle → Encrypted SHL → QR code
 
 PHI never leaves your server. Only terminology codes are sent to FHIRfly for enrichment — no BAA required.
 
+## Prerequisites
+
+- **Node.js** 18 or later
+- **FHIRfly API key** — optional, for code enrichment (display names, SNOMED mappings). [Get a free key](https://fhirfly.io/register). Without it, use manual `code`/`system`/`display` input or `bySNOMED`/`fromResource` (no API call needed).
+
 ## Installation
 
 ```bash
 npm install @fhirfly-io/shl
 ```
 
-For FHIRfly API enrichment (recommended):
+For FHIRfly API enrichment (optional — adds display names and SNOMED cross-mappings):
 
 ```bash
 npm install @fhirfly-io/shl @fhirfly-io/terminology
@@ -28,17 +33,46 @@ npm install @fhirfly-io/shl @fhirfly-io/terminology
 
 ## Quick Start
 
+### Without FHIRfly API (no key needed)
+
+```typescript
+import { IPS, SHL } from "@fhirfly-io/shl";
+
+const bundle = new IPS.Bundle({
+  name: "Maria Garcia",
+  birthDate: "1985-03-15",
+  gender: "female",
+});
+
+// Manual coding — no API dependency
+bundle.addMedication({ code: "376988009", system: "http://snomed.info/sct", display: "Levothyroxine" });
+bundle.addCondition({ code: "44054006", system: "http://snomed.info/sct", display: "Type 2 diabetes" });
+bundle.addAllergy({ bySNOMED: "387207008" });
+
+const fhirBundle = await bundle.build();
+
+const storage = new SHL.LocalStorage({ directory: "./shl-data", baseUrl: "http://localhost:3456/shl" });
+const result = await SHL.create({ bundle: fhirBundle, storage, passcode: "1234" });
+
+console.log(result.url);    // shlink:/eyJ...
+console.log(result.qrCode); // data:image/png;base64,...
+```
+
+### With FHIRfly API (enriched)
+
 ```typescript
 import { IPS, SHL } from "@fhirfly-io/shl";
 import Fhirfly from "@fhirfly-io/terminology";
 
 const client = new Fhirfly({ apiKey: process.env.FHIRFLY_API_KEY });
 
-// Build the IPS Bundle
 const bundle = new IPS.Bundle({
-  patient: { name: "Maria Garcia", birthDate: "1985-03-15", gender: "female" },
+  name: "Maria Garcia",
+  birthDate: "1985-03-15",
+  gender: "female",
 });
 
+// Code-based input — FHIRfly enriches with display names, SNOMED mappings, etc.
 bundle.addMedication({ byNDC: "00071015523", fhirfly: client.ndc });
 bundle.addCondition({ byICD10: "E11.9", fhirfly: client.icd10 });
 bundle.addAllergy({ bySNOMED: "387207008" });
@@ -48,7 +82,7 @@ bundle.addDocument({ content: pdfBuffer, contentType: "application/pdf", title:
 
 const fhirBundle = await bundle.build();
 
-// Create the SHL (zero-infra with FhirflyStorage)
+// FhirflyStorage — zero infrastructure, included free in all plans
 const storage = new SHL.FhirflyStorage({ apiKey: process.env.FHIRFLY_API_KEY });
 
 const result = await SHL.create({
@@ -122,7 +156,7 @@ Host your own SHL endpoints:
 
 ```typescript
 import express from "express";
-import { createShlMiddleware } from "@fhirfly-io/shl/express";
+import { expressMiddleware } from "@fhirfly-io/shl/express";
 import { ServerLocalStorage } from "@fhirfly-io/shl/server";
 
 const storage = new ServerLocalStorage({
@@ -131,7 +165,7 @@ const storage = new ServerLocalStorage({
 });
 
 const app = express();
-app.use("/shl", createShlMiddleware({ storage }));
+app.use("/shl", expressMiddleware({ storage }));
 app.listen(3000);
 ```
 
@@ -149,6 +183,8 @@ Covers bundle building, FhirflyStorage, LocalStorage + Express, SHL consumption,
 
 ## Related
 
+- [EHR Integration Guide](https://fhirfly.io/docs/shl/ehr-integration) — Map HL7v2, CCDA, FHIR R4, and flat database records to IPS bundles
+- [Security & Compliance](https://fhirfly.io/docs/shl/security) — Zero-knowledge architecture, HIPAA, compliance checklist
 - [@fhirfly-io/terminology](https://www.npmjs.com/package/@fhirfly-io/terminology) — FHIRfly terminology API SDK
 - [SMART Health Links Spec](https://docs.smarthealthit.org/smart-health-links/spec/)
 - [IPS Implementation Guide](https://build.fhir.org/ig/HL7/fhir-ips/)

package/dist/{chunk-UFFYRACT.cjs → chunk-63Q54EKN.cjs}

@@ -2,7 +2,7 @@
 
 var chunkUDS6UJAL_cjs = require('./chunk-UDS6UJAL.cjs');
 var chunkQ7SFCCGT_cjs = require('./chunk-Q7SFCCGT.cjs');
-var crypto = require('crypto');
+var crypto$1 = require('crypto');
 var zlib = require('zlib');
 var QRCode = require('qrcode');
 
@@ -1603,11 +1603,7 @@ var Bundle = class {
   }
 };
 function generateUuid() {
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-    const r = Math.random() * 16 | 0;
-    const v = c === "x" ? r : r & 3 | 8;
-    return v.toString(16);
-  });
+  return crypto.randomUUID();
 }
 
 // src/shl/index.ts
@@ -1622,6 +1618,7 @@ chunkQ7SFCCGT_cjs.__export(shl_exports, {
   decode: () => decode,
   decrypt: () => decrypt,
   decryptContent: () => decryptContent2,
+  getEntryContent: () => getEntryContent,
   revoke: () => revoke
 });
 function base64url(data) {
@@ -1631,10 +1628,10 @@ function base64urlDecode(str) {
   return Buffer.from(str, "base64url");
 }
 function generateKey() {
-  return crypto.randomBytes(32);
+  return crypto$1.randomBytes(32);
 }
 function generateShlId() {
-  return base64url(crypto.randomBytes(32));
+  return base64url(crypto$1.randomBytes(32));
 }
 function encryptBundle(bundle, key) {
   const json = JSON.stringify(bundle);
@@ -1646,8 +1643,8 @@ function encryptBundle(bundle, key) {
     zip: "DEF"
   };
   const headerB64 = base64url(Buffer.from(JSON.stringify(header), "utf8"));
-  const iv = crypto.randomBytes(12);
-  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const iv = crypto$1.randomBytes(12);
+  const cipher = crypto$1.createCipheriv("aes-256-gcm", key, iv);
   cipher.setAAD(Buffer.from(headerB64, "ascii"));
   const ciphertext = Buffer.concat([cipher.update(compressed), cipher.final()]);
   const tag = cipher.getAuthTag();
@@ -1657,8 +1654,8 @@ function encryptContent(data, key, contentType) {
   const compressed = zlib.deflateRawSync(data);
   const header = { alg: "dir", enc: "A256GCM", cty: contentType, zip: "DEF" };
   const headerB64 = base64url(Buffer.from(JSON.stringify(header), "utf8"));
-  const iv = crypto.randomBytes(12);
-  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const iv = crypto$1.randomBytes(12);
+  const cipher = crypto$1.createCipheriv("aes-256-gcm", key, iv);
   cipher.setAAD(Buffer.from(headerB64, "ascii"));
   const ciphertext = Buffer.concat([cipher.update(compressed), cipher.final()]);
   const tag = cipher.getAuthTag();
@@ -1677,7 +1674,7 @@ function decryptContent(jwe, key) {
   const iv = base64urlDecode(ivB64);
   const ciphertext = base64urlDecode(ciphertextB64);
   const tag = base64urlDecode(tagB64);
-  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+  const decipher = crypto$1.createDecipheriv("aes-256-gcm", key, iv);
   decipher.setAAD(Buffer.from(headerB64, "ascii"));
   decipher.setAuthTag(tag);
   const compressed = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
@@ -1697,7 +1694,7 @@ function decryptBundle(jwe, key) {
   const iv = base64urlDecode(ivB64);
   const ciphertext = base64urlDecode(ciphertextB64);
   const tag = base64urlDecode(tagB64);
-  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+  const decipher = crypto$1.createDecipheriv("aes-256-gcm", key, iv);
   decipher.setAAD(Buffer.from(headerB64, "ascii"));
   decipher.setAuthTag(tag);
   const compressed = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
@@ -1710,8 +1707,6 @@ async function generateQRCode(url) {
     margin: 2
   });
 }
-
-// src/shl/create.ts
 async function create(options) {
   const { bundle, passcode, expiresAt, maxAccesses, label, storage, debug } = options;
   if (!bundle || typeof bundle !== "object") {
@@ -1740,6 +1735,11 @@ async function create(options) {
     );
   }
   if (debug) {
+    if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") {
+      throw new chunkUDS6UJAL_cjs.ValidationError(
+        "debug mode is not allowed when NODE_ENV=production \u2014 it stores unencrypted PHI"
+      );
+    }
     const debugPath = `${shlId}/bundle.json`;
     try {
       await storage.store(debugPath, JSON.stringify(bundle, null, 2));
@@ -1777,14 +1777,16 @@ async function create(options) {
   const manifest = {
     files: [
       {
-        contentType: "application/fhir+json",
+        contentType: "application/fhir+json;fhirVersion=4.0.1",
         location: `${baseUrl}/${shlId}/content`
       },
       ...attachments.map((att, i) => ({
         contentType: att.contentType,
         location: `${baseUrl}/${shlId}/attachment/${i}`
       }))
-    ]
+    ],
+    status: "finalized",
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
   };
   try {
     await storage.store(`${shlId}/manifest.json`, JSON.stringify(manifest));
@@ -1797,7 +1799,9 @@ async function create(options) {
   const metadata = {
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  if (passcode) metadata.passcode = passcode;
+  if (passcode) {
+    metadata.passcode = crypto$1.createHash("sha256").update(passcode).digest("hex");
+  }
   if (maxAccesses !== void 0) metadata.maxAccesses = maxAccesses;
   if (expiresAt) metadata.expiresAt = expiresAt.toISOString();
   try {
@@ -1918,6 +1922,21 @@ function decryptContent2(jwe, key) {
     );
   }
 }
+async function getEntryContent(entry) {
+  if (entry.embedded) {
+    return entry.embedded;
+  }
+  if (!entry.location) {
+    throw new chunkUDS6UJAL_cjs.ValidationError(
+      "Manifest entry has neither location nor embedded content"
+    );
+  }
+  const res = await globalThis.fetch(entry.location);
+  if (!res.ok) {
+    throw new chunkUDS6UJAL_cjs.EncryptionError(`Failed to fetch content: HTTP ${res.status}`);
+  }
+  return res.text();
+}
 
 // src/shl/revoke.ts
 async function revoke(shlId, storage) {
@@ -1929,5 +1948,5 @@ async function revoke(shlId, storage) {
 
 exports.ips_exports = ips_exports;
 exports.shl_exports = shl_exports;
-//# sourceMappingURL=chunk-UFFYRACT.cjs.map
-//# sourceMappingURL=chunk-UFFYRACT.cjs.map
+//# sourceMappingURL=chunk-63Q54EKN.cjs.map
+//# sourceMappingURL=chunk-63Q54EKN.cjs.map