@fhirfly-io/shl 0.3.2 → 0.5.0

package/README.md

@@ -90,6 +90,7 @@ const result = await SHL.create({
   storage,
   passcode: "1234",
   label: "Maria's Health Summary",
+  expiresAt: "travel", // 90 days — or use "point-of-care" (15min), "appointment" (24h), "permanent"
 });
 
 console.log(result.url);      // shlink:/eyJ1cmwiOiJodHRwczovL...
@@ -97,6 +98,35 @@ console.log(result.qrCode);   // data:image/png;base64,...
 console.log(result.passcode); // "1234"
 ```
 
+### Expiration Presets
+
+Instead of calculating `Date` objects, use named presets:
+
+```typescript
+await SHL.create({ bundle, storage, expiresAt: "point-of-care" }); // 15 minutes
+await SHL.create({ bundle, storage, expiresAt: "appointment" });    // 24 hours
+await SHL.create({ bundle, storage, expiresAt: "travel" });         // 90 days
+await SHL.create({ bundle, storage, expiresAt: "permanent" });      // no expiration
+await SHL.create({ bundle, storage, expiresAt: new Date(...) });    // raw Date still works
+```
+
+### PSHD Compliance
+
+For CMS-aligned patient-to-provider sharing at the point of care:
+
+```typescript
+const fhirBundle = await bundle.build({ profile: "pshd" }); // strips meta.profile, uses collection bundle
+
+const result = await SHL.create({
+  bundle: fhirBundle,
+  storage,
+  compliance: "pshd",
+  expiresAt: "point-of-care",
+});
+```
+
+See the [PSHD Guide](https://fhirfly.io/docs/shl/pshd) for full details.
+
 ## Storage Adapters
 
 ```typescript
@@ -171,6 +201,29 @@ app.listen(3000);
 
 Also available for Fastify (`@fhirfly-io/shl/fastify`) and Lambda (`@fhirfly-io/shl/lambda`).
 
+### Audit Logging
+
+Use `AuditableStorage` to capture access events at the storage level — plug in any logging backend:
+
+```typescript
+import { AuditableStorage, SHLServerStorage, AccessEvent } from "@fhirfly-io/shl/server";
+
+class MyAuditStorage extends ServerLocalStorage implements AuditableStorage {
+  async onAccess(shlId: string, event: AccessEvent): Promise<void> {
+    await db.auditLog.insert({
+      shlId,
+      recipient: event.recipient,
+      ip: event.ip,
+      timestamp: event.timestamp,
+    });
+  }
+}
+
+app.use("/shl", expressMiddleware({ storage: new MyAuditStorage({ ... }) }));
+```
+
+The server handler detects `AuditableStorage` at runtime via `isAuditableStorage()` — existing storage implementations work unchanged.
+
 ## Live Exercise
 
 Run the comprehensive integration test against the live API to exercise every SDK path:

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

@@ -180,7 +180,11 @@ var CODE_SYSTEMS = {
   CVX: "http://hl7.org/fhir/sid/cvx",
   ICD10CM: "http://hl7.org/fhir/sid/icd-10-cm",
   CONDITION_CLINICAL: "http://terminology.hl7.org/CodeSystem/condition-clinical",
-  ALLERGY_CLINICAL: "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical"
+  ALLERGY_CLINICAL: "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
+  /** CMS Patient-Shared Health Document category code system */
+  CMS_PATIENT_SHARED_CATEGORY: "https://cms.gov/fhir/CodeSystem/patient-shared-category",
+  /** V3 ActCode security label for patient-asserted data */
+  SECURITY_PATAST: "PATAST"
 };
 
 // src/ips/medication.ts
@@ -1106,8 +1110,9 @@ function resolveDocuments(documents, patientRef, profile, generateUuid2) {
       contentType,
       data: base64Content
     };
-    const typeCode = doc.typeCode ?? "34133-9";
-    const typeDisplay = doc.typeDisplay ?? "Summarization of episode note";
+    const isPshd = profile === "pshd";
+    const typeCode = isPshd ? "60591-5" : doc.typeCode ?? "34133-9";
+    const typeDisplay = isPshd ? "Patient summary Document" : doc.typeDisplay ?? "Summarization of episode note";
     const docRefResource = {
       resourceType: "DocumentReference",
       id: docRefId,
@@ -1133,7 +1138,29 @@ function resolveDocuments(documents, patientRef, profile, generateUuid2) {
         }
       ]
     };
-    if (profile === "ips") {
+    if (isPshd) {
+      docRefResource.category = [
+        {
+          coding: [
+            {
+              system: CODE_SYSTEMS.CMS_PATIENT_SHARED_CATEGORY,
+              code: "patient-shared",
+              display: "Patient Shared"
+            }
+          ]
+        }
+      ];
+      docRefResource.author = [{ reference: patientRef }];
+      docRefResource.meta = {
+        security: [
+          {
+            system: "http://terminology.hl7.org/CodeSystem/v3-ActCode",
+            code: CODE_SYSTEMS.SECURITY_PATAST,
+            display: "patient asserted"
+          }
+        ]
+      };
+    } else if (profile === "ips") {
       docRefResource.meta = {
         profile: ["http://hl7.org/fhir/uv/ips/StructureDefinition/DocumentReference-uv-ips"]
       };
@@ -1332,11 +1359,9 @@ var Bundle = class {
   async build(options) {
     const profile = options?.profile ?? "ips";
     const bundleId = options?.bundleId ?? generateUuid();
-    const compositionId = generateUuid();
     const patientId = generateUuid();
-    const compositionDate = options?.compositionDate ?? (/* @__PURE__ */ new Date()).toISOString();
+    const timestamp = options?.compositionDate ?? (/* @__PURE__ */ new Date()).toISOString();
     const patientFullUrl = `urn:uuid:${patientId}`;
-    const compositionFullUrl = `urn:uuid:${compositionId}`;
     const patientResource = normalizePatient(this._patient, patientId, profile);
     const [medResult, condResult, allergyResult, immResult, resultResult] = await Promise.all([
       resolveMedications(this._medications, patientFullUrl, profile, generateUuid),
@@ -1353,6 +1378,22 @@ var Bundle = class {
       ...immResult.warnings,
       ...resultResult.warnings
     ];
+    if (profile === "pshd") {
+      return this.buildPshdBundle(
+        bundleId,
+        timestamp,
+        patientFullUrl,
+        patientResource,
+        medResult.entries,
+        condResult.entries,
+        allergyResult.entries,
+        immResult.entries,
+        resultResult.entries,
+        docResult.entries
+      );
+    }
+    const compositionId = generateUuid();
+    const compositionFullUrl = `urn:uuid:${compositionId}`;
     const medRefs = medResult.entries.map((e) => ({ reference: e.fullUrl }));
     const condRefs = condResult.entries.map((e) => ({ reference: e.fullUrl }));
     const allergyRefs = allergyResult.entries.map((e) => ({ reference: e.fullUrl }));
@@ -1361,7 +1402,7 @@ var Bundle = class {
     const composition = this.buildComposition(
       compositionId,
       patientFullUrl,
-      compositionDate,
+      timestamp,
       profile,
       medRefs,
       allergyRefs,
@@ -1387,7 +1428,7 @@ var Bundle = class {
         value: `urn:uuid:${bundleId}`
       },
       type: "document",
-      timestamp: compositionDate,
+      timestamp,
       entry: entries
     };
     return bundle;
@@ -1407,6 +1448,37 @@ var Bundle = class {
         path: "Patient.birthDate"
       });
     }
+    if (profile === "pshd") {
+      if (this._documents.length === 0) {
+        issues.push({
+          severity: "error",
+          message: "PSHD requires at least one DocumentReference (1..1)",
+          path: "Bundle.entry:DocumentReference"
+        });
+      } else {
+        const hasPdf = this._documents.some(
+          (d) => (d.contentType ?? "application/pdf") === "application/pdf"
+        );
+        if (!hasPdf) {
+          issues.push({
+            severity: "error",
+            message: "PSHD requires at least one PDF document (contentType application/pdf)",
+            path: "DocumentReference.content.attachment.contentType"
+          });
+        }
+      }
+      if (!this._patient.gender) {
+        issues.push({
+          severity: "warning",
+          message: "Patient.gender recommended for PSHD demographic matching",
+          path: "Patient.gender"
+        });
+      }
+      return {
+        valid: issues.filter((i) => i.severity === "error").length === 0,
+        issues
+      };
+    }
     if (profile === "ips") {
       if (!this.hasValidName()) {
         issues.push({
@@ -1482,6 +1554,37 @@ var Bundle = class {
     const s = this._patient;
     return !!(s.given || s.family || s.name);
   }
+  buildPshdBundle(bundleId, timestamp, patientFullUrl, patientResource, medEntries, condEntries, allergyEntries, immEntries, resultEntries, docEntries) {
+    const entries = [
+      { fullUrl: patientFullUrl, resource: patientResource },
+      ...medEntries,
+      ...condEntries,
+      ...allergyEntries,
+      ...immEntries,
+      ...resultEntries,
+      ...docEntries
+    ];
+    for (const entry of entries) {
+      const meta = entry.resource.meta;
+      if (meta?.profile) {
+        delete meta.profile;
+        if (Object.keys(meta).length === 0) {
+          delete entry.resource.meta;
+        }
+      }
+    }
+    return {
+      resourceType: "Bundle",
+      id: bundleId,
+      identifier: {
+        system: "urn:ietf:rfc:3986",
+        value: `urn:uuid:${bundleId}`
+      },
+      type: "collection",
+      timestamp,
+      entry: entries
+    };
+  }
   buildComposition(id, patientRef, date, profile, medRefs, allergyRefs, condRefs, immRefs, resultRefs) {
     const composition = {
       resourceType: "Composition",
@@ -1610,6 +1713,7 @@ function generateUuid() {
 var shl_exports = {};
 chunkQ7SFCCGT_cjs.__export(shl_exports, {
   AzureStorage: () => chunkUDS6UJAL_cjs.AzureStorage,
+  EXPIRATION_PRESETS: () => EXPIRATION_PRESETS,
   FhirflyStorage: () => chunkUDS6UJAL_cjs.FhirflyStorage,
   GCSStorage: () => chunkUDS6UJAL_cjs.GCSStorage,
   LocalStorage: () => chunkUDS6UJAL_cjs.LocalStorage,
@@ -1621,6 +1725,18 @@ chunkQ7SFCCGT_cjs.__export(shl_exports, {
   getEntryContent: () => getEntryContent,
   revoke: () => revoke
 });
+
+// src/shl/types.ts
+var EXPIRATION_PRESETS = {
+  "point-of-care": 15 * 60 * 1e3,
+  // 15 minutes
+  "appointment": 24 * 60 * 60 * 1e3,
+  // 24 hours
+  "travel": 90 * 24 * 60 * 60 * 1e3,
+  // 90 days
+  "permanent": 0
+  // no expiration
+};
 function base64url(data) {
   return data.toString("base64url");
 }
@@ -1708,13 +1824,43 @@ async function generateQRCode(url) {
   });
 }
 async function create(options) {
-  const { bundle, passcode, expiresAt, maxAccesses, label, storage, debug } = options;
+  const { bundle, passcode, maxAccesses, label, storage, debug } = options;
+  let expiresAt;
+  if (typeof options.expiresAt === "string") {
+    const preset = options.expiresAt;
+    const durationMs = EXPIRATION_PRESETS[preset];
+    if (durationMs === void 0) {
+      throw new chunkUDS6UJAL_cjs.ValidationError(`Unknown expiration preset: "${preset}"`);
+    }
+    expiresAt = durationMs > 0 ? new Date(Date.now() + durationMs) : void 0;
+  } else {
+    expiresAt = options.expiresAt;
+  }
   if (!bundle || typeof bundle !== "object") {
     throw new chunkUDS6UJAL_cjs.ValidationError("bundle is required and must be an object");
   }
   if (!storage?.baseUrl) {
     throw new chunkUDS6UJAL_cjs.ValidationError("storage with baseUrl is required");
   }
+  let mode = options.mode ?? "manifest";
+  if (options.compliance === "pshd") {
+    mode = "direct";
+    if (passcode) {
+      throw new chunkUDS6UJAL_cjs.ValidationError(
+        "PSHD compliance forbids passcode (flag U is incompatible with flag P)"
+      );
+    }
+    if (!expiresAt && options.expiresAt !== "permanent") {
+      throw new chunkUDS6UJAL_cjs.ValidationError(
+        "PSHD compliance requires expiresAt (short-lived links for point-of-care)"
+      );
+    }
+  }
+  if (mode === "direct" && passcode) {
+    throw new chunkUDS6UJAL_cjs.ValidationError(
+      "Direct mode (flag U) is incompatible with passcode (flag P)"
+    );
+  }
   const key = generateKey();
   const shlId = generateShlId();
   let jwe;
@@ -1774,31 +1920,34 @@ async function create(options) {
       );
     }
   }
-  const manifest = {
-    files: [
-      {
-        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));
-  } catch (err) {
-    throw new chunkUDS6UJAL_cjs.StorageError(
-      `Failed to store manifest: ${err instanceof Error ? err.message : String(err)}`,
-      "store"
-    );
+  if (mode === "manifest") {
+    const manifest = {
+      files: [
+        {
+          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));
+    } catch (err) {
+      throw new chunkUDS6UJAL_cjs.StorageError(
+        `Failed to store manifest: ${err instanceof Error ? err.message : String(err)}`,
+        "store"
+      );
+    }
   }
   const metadata = {
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
+  if (mode === "direct") metadata.mode = "direct";
   if (passcode) {
     metadata.passcode = crypto$1.createHash("sha256").update(passcode).digest("hex");
   }
@@ -1812,7 +1961,7 @@ async function create(options) {
       "store"
     );
   }
-  const flags = buildFlags(passcode);
+  const flags = buildFlags(mode, passcode);
   const shlPayload = {
     url: `${baseUrl}/${shlId}`,
     key: base64url(key),
@@ -1839,8 +1988,8 @@ async function create(options) {
   if (debug) result.debugBundlePath = `${shlId}/bundle.json`;
   return result;
 }
-function buildFlags(passcode) {
-  const flags = ["L"];
+function buildFlags(mode, passcode) {
+  const flags = [mode === "direct" ? "U" : "L"];
   if (passcode) flags.push("P");
   return flags.sort().join("");
 }
@@ -1948,5 +2097,5 @@ async function revoke(shlId, storage) {
 
 exports.ips_exports = ips_exports;
 exports.shl_exports = shl_exports;
-//# sourceMappingURL=chunk-63Q54EKN.cjs.map
-//# sourceMappingURL=chunk-63Q54EKN.cjs.map
+//# sourceMappingURL=chunk-CN44QKWJ.cjs.map
+//# sourceMappingURL=chunk-CN44QKWJ.cjs.map