@fhirfly-io/shl 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FHIRfly.io LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @fhirfly-io/shl
+
+SMART Health Links SDK for Node.js — build FHIR Bundles from clinical codes, enrich with terminology, encrypt, and share via SHL/QR code.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## What It Does
+
+Takes raw clinical data (NDC codes, ICD-10 codes, RxNorm, LOINC, CVX) and produces a shareable SMART Health Link:
+
+```
+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.
+
+## Installation
+
+```bash
+npm install @fhirfly-io/shl
+```
+
+## Quick Start
+
+```typescript
+import { IPS, SHL } from '@fhirfly-io/shl';
+import { Fhirfly } from '@fhirfly-io/terminology';
+
+const fhirfly = new Fhirfly({ apiKey: process.env.FHIRFLY_API_KEY });
+
+// Build incrementally — each method is independently testable
+const ips = new IPS.Bundle({
+  patient: { name: 'Oliver Brown', dob: '1990-03-15', gender: 'male' },
+});
+
+ips.addMedication({ byNDC: '0069-3150-83', fhirfly });
+ips.addCondition({ byICD10: 'E11.9', fhirfly });
+ips.addImmunization({ byCVX: '207', fhirfly });
+ips.addResult({ byLOINC: '2339-0', value: 95, unit: 'mg/dL' });
+ips.addDocument({ pdf: pdfBuffer, title: 'Visit Summary' });
+
+// Build with configurable output profile
+const bundle = await ips.build({ profile: 'ips' });  // or 'r4' for generic FHIR
+
+// Validate — mandatory before packaging
+const validation = await bundle.validate();
+
+// Package as SHL
+const shl = await SHL.create(bundle, {
+  storage: new SHL.S3Storage({ bucket: 'my-hipaa-bucket', region: 'us-east-1' }),
+  expiration: '30d',
+  passcode: { generate: true },
+  label: 'Medical Summary for Oliver Brown',
+});
+
+console.log(shl.url);       // shlink:/eyJ1cmwiOiJodHRwczovL...
+console.log(shl.qrCode);    // Base64 PNG
+console.log(shl.passcode);  // Communicate out-of-band to patient
+```
+
+## Design Principles
+
+- **Composable methods** — small, testable `add*` methods that build up a Bundle incrementally
+- **Configurable output** — `build({ profile: "ips" })` for IPS document Bundles, `build({ profile: "r4" })` for generic FHIR collections
+- **Bring Your Own Storage** — developer controls where encrypted PHI lives (S3, Azure, GCS, local)
+- **Bring Your Own PDF** — SDK wraps pre-rendered PDFs as FHIR DocumentReference; you control rendering
+- **Validation as a gate** — `SHL.create()` refuses to package invalid Bundles
+- **Create-only for v1** — SHL creation; receiving/decoding is out of scope
+
+## Output Profiles
+
+| Profile | Bundle.type | Composition | Use Case |
+|---------|-------------|-------------|----------|
+| `"ips"` | `document` | Yes (with IPS sections) | Kill the Clipboard, patient portals |
+| `"r4"` | `collection` | No | Apps needing FHIR Bundles without IPS compliance |
+
+## Input Formats
+
+Each `add*` method supports multiple input formats:
+
+```typescript
+// From raw codes (enriched via FHIRfly API)
+ips.addMedication({ byNDC: '0069-3150-83', fhirfly });
+ips.addMedication({ byRxNorm: '161', fhirfly });
+
+// From SNOMED (no API call needed)
+ips.addMedication({ bySNOMED: '376988009' });
+
+// From existing FHIR R4 resources
+ips.addMedication({ fromResource: existingMedicationStatement });
+```
+
+## Storage Adapters
+
+```typescript
+// AWS S3 (pre-signed URLs)
+new SHL.S3Storage({ bucket: 'my-bucket', region: 'us-east-1' });
+
+// Azure Blob Storage (SAS tokens)
+new SHL.AzureStorage({ container: 'my-container', connectionString: '...' });
+
+// Google Cloud Storage
+new SHL.GCSStorage({ bucket: 'my-bucket' });
+
+// Local filesystem (development/testing only)
+new SHL.LocalStorage({ directory: './shl-data' });
+```
+
+## Related
+
+- [@fhirfly-io/terminology](https://www.npmjs.com/package/@fhirfly-io/terminology) — FHIRfly terminology API SDK (required for code enrichment)
+- [SMART Health Links Spec](https://docs.smarthealthit.org/smart-health-links/spec/)
+- [IPS Implementation Guide](https://build.fhir.org/ig/HL7/fhir-ips/)
+- [FHIRfly Documentation](https://fhirfly.io/docs)
+
+## License
+
+MIT

package/dist/chunk-7WIM2QP5.js

@@ -0,0 +1,133 @@
+// src/server/handler.ts
+function createHandler(config) {
+  const { storage, onAccess } = config;
+  return async (req) => {
+    const path = req.path.replace(/^\/+/, "");
+    const segments = path.split("/").filter(Boolean);
+    if (segments.length === 1 && req.method === "POST") {
+      return handleManifest(segments[0], req, storage, onAccess);
+    }
+    if (segments.length === 2 && segments[1] === "content" && req.method === "GET") {
+      return handleContent(segments[0], storage);
+    }
+    if (segments.length === 3 && segments[1] === "attachment" && req.method === "GET") {
+      const index = segments[2];
+      return handleAttachment(segments[0], index, storage);
+    }
+    if (segments.length === 1 && req.method !== "POST") {
+      return jsonResponse(405, { error: "Method not allowed. Use POST for manifest requests." });
+    }
+    if (segments.length === 2 && segments[1] === "content" && req.method !== "GET") {
+      return jsonResponse(405, { error: "Method not allowed. Use GET for content requests." });
+    }
+    if (segments.length === 3 && segments[1] === "attachment" && req.method !== "GET") {
+      return jsonResponse(405, { error: "Method not allowed. Use GET for attachment requests." });
+    }
+    return jsonResponse(404, { error: "Not found" });
+  };
+}
+async function handleManifest(shlId, req, storage, onAccess) {
+  const manifestRaw = await storage.read(`${shlId}/manifest.json`);
+  if (manifestRaw === null) {
+    return jsonResponse(404, { error: "SHL not found" });
+  }
+  let updatedMetadata = null;
+  let accessDeniedReason = null;
+  const reqBody = req.body && typeof req.body === "object" ? req.body : {};
+  const providedPasscode = typeof reqBody["passcode"] === "string" ? reqBody["passcode"] : void 0;
+  updatedMetadata = await storage.updateMetadata(shlId, (metadata) => {
+    if (metadata.expiresAt) {
+      const expiresAt = new Date(metadata.expiresAt);
+      if (expiresAt.getTime() <= Date.now()) {
+        accessDeniedReason = "expired";
+        return null;
+      }
+    }
+    const currentCount = metadata.accessCount ?? 0;
+    if (metadata.maxAccesses !== void 0 && currentCount >= metadata.maxAccesses) {
+      accessDeniedReason = "exhausted";
+      return null;
+    }
+    if (metadata.passcode) {
+      if (!providedPasscode || providedPasscode !== metadata.passcode) {
+        accessDeniedReason = "passcode";
+        return null;
+      }
+    }
+    return {
+      ...metadata,
+      accessCount: currentCount + 1
+    };
+  });
+  if (accessDeniedReason === "expired") {
+    return jsonResponse(410, { error: "SHL has expired" });
+  }
+  if (accessDeniedReason === "exhausted") {
+    return jsonResponse(410, { error: "SHL access limit reached" });
+  }
+  if (accessDeniedReason === "passcode") {
+    return jsonResponse(401, { error: "Invalid passcode" });
+  }
+  if (updatedMetadata === null) {
+    return jsonResponse(404, { error: "SHL not found" });
+  }
+  if (onAccess) {
+    const event = {
+      shlId,
+      accessCount: updatedMetadata.accessCount ?? 1,
+      timestamp: /* @__PURE__ */ new Date()
+    };
+    Promise.resolve(onAccess(event)).catch(() => {
+    });
+  }
+  const manifestStr = typeof manifestRaw === "string" ? manifestRaw : new TextDecoder().decode(manifestRaw);
+  const manifest = JSON.parse(manifestStr);
+  return jsonResponse(200, manifest);
+}
+async function handleContent(shlId, storage) {
+  const content = await storage.read(`${shlId}/content.jwe`);
+  if (content === null) {
+    return jsonResponse(404, { error: "Content not found" });
+  }
+  const body = typeof content === "string" ? content : new TextDecoder().decode(content);
+  return {
+    status: 200,
+    headers: {
+      "content-type": "application/jose",
+      "cache-control": "no-store"
+    },
+    body
+  };
+}
+async function handleAttachment(shlId, index, storage) {
+  if (!/^\d+$/.test(index)) {
+    return jsonResponse(400, { error: "Invalid attachment index" });
+  }
+  const content = await storage.read(`${shlId}/attachment-${index}.jwe`);
+  if (content === null) {
+    return jsonResponse(404, { error: "Attachment not found" });
+  }
+  const body = typeof content === "string" ? content : new TextDecoder().decode(content);
+  return {
+    status: 200,
+    headers: {
+      "content-type": "application/jose",
+      "cache-control": "no-store"
+    },
+    body
+  };
+}
+function jsonResponse(status, body) {
+  return {
+    status,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store"
+    },
+    body: JSON.stringify(body)
+  };
+}
+
+export { createHandler };
+//# sourceMappingURL=chunk-7WIM2QP5.js.map
+//# sourceMappingURL=chunk-7WIM2QP5.js.map

package/dist/chunk-7WIM2QP5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/handler.ts"],"names":[],"mappings":"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","file":"chunk-7WIM2QP5.js","sourcesContent":["// Copyright 2026 FHIRfly.io LLC. All rights reserved.\n// Licensed under the MIT License. See LICENSE file in the project root.\nimport type {\n  HandlerRequest,\n  HandlerResponse,\n  SHLHandlerConfig,\n} from \"./types.js\";\nimport type { SHLMetadata, Manifest } from \"../shl/types.js\";\n\n/**\n * Create a framework-agnostic SHL request handler.\n *\n * Returns an async function that processes incoming requests and returns\n * responses. This handler implements two routes:\n *\n * - `POST /{shlId}` — Manifest endpoint (validates passcode, checks access limits)\n * - `GET /{shlId}/content` — Content endpoint (serves encrypted JWE)\n *\n * Framework adapters (Express, Fastify, Lambda) translate their native\n * request/response types to/from `HandlerRequest`/`HandlerResponse`.\n *\n * @example\n * ```ts\n * const handle = createHandler({ storage });\n * const response = await handle({\n *   method: \"POST\",\n *   path: \"/abc123\",\n *   body: { passcode: \"1234\" },\n *   headers: { \"content-type\": \"application/json\" },\n * });\n * ```\n */\nexport function createHandler(\n  config: SHLHandlerConfig,\n): (req: HandlerRequest) => Promise<HandlerResponse> {\n  const { storage, onAccess } = config;\n\n  return async (req: HandlerRequest): Promise<HandlerResponse> => {\n    // Normalize path: strip leading slash, split into segments\n    const path = req.path.replace(/^\\/+/, \"\");\n    const segments = path.split(\"/\").filter(Boolean);\n\n    // Route: POST /{shlId} → manifest\n    if (segments.length === 1 && req.method === \"POST\") {\n      return handleManifest(segments[0]!, req, storage, onAccess);\n    }\n\n    // Route: GET /{shlId}/content → serve encrypted content\n    if (segments.length === 2 && segments[1] === \"content\" && req.method === \"GET\") {\n      return handleContent(segments[0]!, storage);\n    }\n\n    // Route: GET /{shlId}/attachment/{index} → serve encrypted attachment\n    if (segments.length === 3 && segments[1] === \"attachment\" && req.method === \"GET\") {\n      const index = segments[2]!;\n      return handleAttachment(segments[0]!, index, storage);\n    }\n\n    // Method not allowed for known paths\n    if (segments.length === 1 && req.method !== \"POST\") {\n      return jsonResponse(405, { error: \"Method not allowed. Use POST for manifest requests.\" });\n    }\n    if (segments.length === 2 && segments[1] === \"content\" && req.method !== \"GET\") {\n      return jsonResponse(405, { error: \"Method not allowed. Use GET for content requests.\" });\n    }\n    if (segments.length === 3 && segments[1] === \"attachment\" && req.method !== \"GET\") {\n      return jsonResponse(405, { error: \"Method not allowed. Use GET for attachment requests.\" });\n    }\n\n    return jsonResponse(404, { error: \"Not found\" });\n  };\n}\n\nasync function handleManifest(\n  shlId: string,\n  req: HandlerRequest,\n  storage: SHLHandlerConfig[\"storage\"],\n  onAccess?: SHLHandlerConfig[\"onAccess\"],\n): Promise<HandlerResponse> {\n  // Read manifest to verify the SHL exists\n  const manifestRaw = await storage.read(`${shlId}/manifest.json`);\n  if (manifestRaw === null) {\n    return jsonResponse(404, { error: \"SHL not found\" });\n  }\n\n  // Atomically check access control + increment counter\n  let updatedMetadata: SHLMetadata | null = null;\n  let accessDeniedReason: \"expired\" | \"exhausted\" | \"passcode\" | null = null;\n  const reqBody = (req.body && typeof req.body === \"object\" ? req.body : {}) as Record<string, unknown>;\n  const providedPasscode = typeof reqBody[\"passcode\"] === \"string\" ? reqBody[\"passcode\"] : undefined;\n\n  updatedMetadata = await storage.updateMetadata(shlId, (metadata) => {\n    // Check expiration\n    if (metadata.expiresAt) {\n      const expiresAt = new Date(metadata.expiresAt);\n      if (expiresAt.getTime() <= Date.now()) {\n        accessDeniedReason = \"expired\";\n        return null;\n      }\n    }\n\n    // Check access count\n    const currentCount = metadata.accessCount ?? 0;\n    if (metadata.maxAccesses !== undefined && currentCount >= metadata.maxAccesses) {\n      accessDeniedReason = \"exhausted\";\n      return null;\n    }\n\n    // Check passcode\n    if (metadata.passcode) {\n      if (!providedPasscode || providedPasscode !== metadata.passcode) {\n        accessDeniedReason = \"passcode\";\n        return null;\n      }\n    }\n\n    // Access granted — increment count\n    return {\n      ...metadata,\n      accessCount: currentCount + 1,\n    };\n  });\n\n  // Handle access control failures\n  if (accessDeniedReason === \"expired\") {\n    return jsonResponse(410, { error: \"SHL has expired\" });\n  }\n  if (accessDeniedReason === \"exhausted\") {\n    return jsonResponse(410, { error: \"SHL access limit reached\" });\n  }\n  if (accessDeniedReason === \"passcode\") {\n    return jsonResponse(401, { error: \"Invalid passcode\" });\n  }\n\n  // If updateMetadata returned null but no denied reason, metadata file is missing\n  if (updatedMetadata === null) {\n    return jsonResponse(404, { error: \"SHL not found\" });\n  }\n\n  // Fire access event (non-blocking)\n  if (onAccess) {\n    const event = {\n      shlId,\n      accessCount: updatedMetadata.accessCount ?? 1,\n      timestamp: new Date(),\n    };\n    // Fire and forget — don't let callback errors break the response\n    Promise.resolve(onAccess(event)).catch(() => {});\n  }\n\n  // Return manifest\n  const manifestStr = typeof manifestRaw === \"string\"\n    ? manifestRaw\n    : new TextDecoder().decode(manifestRaw);\n  const manifest = JSON.parse(manifestStr) as Manifest;\n\n  return jsonResponse(200, manifest);\n}\n\nasync function handleContent(\n  shlId: string,\n  storage: SHLHandlerConfig[\"storage\"],\n): Promise<HandlerResponse> {\n  const content = await storage.read(`${shlId}/content.jwe`);\n  if (content === null) {\n    return jsonResponse(404, { error: \"Content not found\" });\n  }\n\n  const body = typeof content === \"string\"\n    ? content\n    : new TextDecoder().decode(content);\n\n  return {\n    status: 200,\n    headers: {\n      \"content-type\": \"application/jose\",\n      \"cache-control\": \"no-store\",\n    },\n    body,\n  };\n}\n\nasync function handleAttachment(\n  shlId: string,\n  index: string,\n  storage: SHLHandlerConfig[\"storage\"],\n): Promise<HandlerResponse> {\n  if (!/^\\d+$/.test(index)) {\n    return jsonResponse(400, { error: \"Invalid attachment index\" });\n  }\n  const content = await storage.read(`${shlId}/attachment-${index}.jwe`);\n  if (content === null) {\n    return jsonResponse(404, { error: \"Attachment not found\" });\n  }\n  const body = typeof content === \"string\"\n    ? content\n    : new TextDecoder().decode(content);\n  return {\n    status: 200,\n    headers: {\n      \"content-type\": \"application/jose\",\n      \"cache-control\": \"no-store\",\n    },\n    body,\n  };\n}\n\nfunction jsonResponse(status: number, body: unknown): HandlerResponse {\n  return {\n    status,\n    headers: {\n      \"content-type\": \"application/json\",\n      \"cache-control\": \"no-store\",\n    },\n    body: JSON.stringify(body),\n  };\n}\n"]}

package/dist/chunk-CNVYKA4D.cjs

@@ -0,0 +1,135 @@
+'use strict';
+
+// src/server/handler.ts
+function createHandler(config) {
+  const { storage, onAccess } = config;
+  return async (req) => {
+    const path = req.path.replace(/^\/+/, "");
+    const segments = path.split("/").filter(Boolean);
+    if (segments.length === 1 && req.method === "POST") {
+      return handleManifest(segments[0], req, storage, onAccess);
+    }
+    if (segments.length === 2 && segments[1] === "content" && req.method === "GET") {
+      return handleContent(segments[0], storage);
+    }
+    if (segments.length === 3 && segments[1] === "attachment" && req.method === "GET") {
+      const index = segments[2];
+      return handleAttachment(segments[0], index, storage);
+    }
+    if (segments.length === 1 && req.method !== "POST") {
+      return jsonResponse(405, { error: "Method not allowed. Use POST for manifest requests." });
+    }
+    if (segments.length === 2 && segments[1] === "content" && req.method !== "GET") {
+      return jsonResponse(405, { error: "Method not allowed. Use GET for content requests." });
+    }
+    if (segments.length === 3 && segments[1] === "attachment" && req.method !== "GET") {
+      return jsonResponse(405, { error: "Method not allowed. Use GET for attachment requests." });
+    }
+    return jsonResponse(404, { error: "Not found" });
+  };
+}
+async function handleManifest(shlId, req, storage, onAccess) {
+  const manifestRaw = await storage.read(`${shlId}/manifest.json`);
+  if (manifestRaw === null) {
+    return jsonResponse(404, { error: "SHL not found" });
+  }
+  let updatedMetadata = null;
+  let accessDeniedReason = null;
+  const reqBody = req.body && typeof req.body === "object" ? req.body : {};
+  const providedPasscode = typeof reqBody["passcode"] === "string" ? reqBody["passcode"] : void 0;
+  updatedMetadata = await storage.updateMetadata(shlId, (metadata) => {
+    if (metadata.expiresAt) {
+      const expiresAt = new Date(metadata.expiresAt);
+      if (expiresAt.getTime() <= Date.now()) {
+        accessDeniedReason = "expired";
+        return null;
+      }
+    }
+    const currentCount = metadata.accessCount ?? 0;
+    if (metadata.maxAccesses !== void 0 && currentCount >= metadata.maxAccesses) {
+      accessDeniedReason = "exhausted";
+      return null;
+    }
+    if (metadata.passcode) {
+      if (!providedPasscode || providedPasscode !== metadata.passcode) {
+        accessDeniedReason = "passcode";
+        return null;
+      }
+    }
+    return {
+      ...metadata,
+      accessCount: currentCount + 1
+    };
+  });
+  if (accessDeniedReason === "expired") {
+    return jsonResponse(410, { error: "SHL has expired" });
+  }
+  if (accessDeniedReason === "exhausted") {
+    return jsonResponse(410, { error: "SHL access limit reached" });
+  }
+  if (accessDeniedReason === "passcode") {
+    return jsonResponse(401, { error: "Invalid passcode" });
+  }
+  if (updatedMetadata === null) {
+    return jsonResponse(404, { error: "SHL not found" });
+  }
+  if (onAccess) {
+    const event = {
+      shlId,
+      accessCount: updatedMetadata.accessCount ?? 1,
+      timestamp: /* @__PURE__ */ new Date()
+    };
+    Promise.resolve(onAccess(event)).catch(() => {
+    });
+  }
+  const manifestStr = typeof manifestRaw === "string" ? manifestRaw : new TextDecoder().decode(manifestRaw);
+  const manifest = JSON.parse(manifestStr);
+  return jsonResponse(200, manifest);
+}
+async function handleContent(shlId, storage) {
+  const content = await storage.read(`${shlId}/content.jwe`);
+  if (content === null) {
+    return jsonResponse(404, { error: "Content not found" });
+  }
+  const body = typeof content === "string" ? content : new TextDecoder().decode(content);
+  return {
+    status: 200,
+    headers: {
+      "content-type": "application/jose",
+      "cache-control": "no-store"
+    },
+    body
+  };
+}
+async function handleAttachment(shlId, index, storage) {
+  if (!/^\d+$/.test(index)) {
+    return jsonResponse(400, { error: "Invalid attachment index" });
+  }
+  const content = await storage.read(`${shlId}/attachment-${index}.jwe`);
+  if (content === null) {
+    return jsonResponse(404, { error: "Attachment not found" });
+  }
+  const body = typeof content === "string" ? content : new TextDecoder().decode(content);
+  return {
+    status: 200,
+    headers: {
+      "content-type": "application/jose",
+      "cache-control": "no-store"
+    },
+    body
+  };
+}
+function jsonResponse(status, body) {
+  return {
+    status,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store"
+    },
+    body: JSON.stringify(body)
+  };
+}
+
+exports.createHandler = createHandler;
+//# sourceMappingURL=chunk-CNVYKA4D.cjs.map
+//# sourceMappingURL=chunk-CNVYKA4D.cjs.map

package/dist/chunk-CNVYKA4D.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/handler.ts"],"names":[],"mappings":"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","file":"chunk-CNVYKA4D.cjs","sourcesContent":["// Copyright 2026 FHIRfly.io LLC. All rights reserved.\n// Licensed under the MIT License. See LICENSE file in the project root.\nimport type {\n  HandlerRequest,\n  HandlerResponse,\n  SHLHandlerConfig,\n} from \"./types.js\";\nimport type { SHLMetadata, Manifest } from \"../shl/types.js\";\n\n/**\n * Create a framework-agnostic SHL request handler.\n *\n * Returns an async function that processes incoming requests and returns\n * responses. This handler implements two routes:\n *\n * - `POST /{shlId}` — Manifest endpoint (validates passcode, checks access limits)\n * - `GET /{shlId}/content` — Content endpoint (serves encrypted JWE)\n *\n * Framework adapters (Express, Fastify, Lambda) translate their native\n * request/response types to/from `HandlerRequest`/`HandlerResponse`.\n *\n * @example\n * ```ts\n * const handle = createHandler({ storage });\n * const response = await handle({\n *   method: \"POST\",\n *   path: \"/abc123\",\n *   body: { passcode: \"1234\" },\n *   headers: { \"content-type\": \"application/json\" },\n * });\n * ```\n */\nexport function createHandler(\n  config: SHLHandlerConfig,\n): (req: HandlerRequest) => Promise<HandlerResponse> {\n  const { storage, onAccess } = config;\n\n  return async (req: HandlerRequest): Promise<HandlerResponse> => {\n    // Normalize path: strip leading slash, split into segments\n    const path = req.path.replace(/^\\/+/, \"\");\n    const segments = path.split(\"/\").filter(Boolean);\n\n    // Route: POST /{shlId} → manifest\n    if (segments.length === 1 && req.method === \"POST\") {\n      return handleManifest(segments[0]!, req, storage, onAccess);\n    }\n\n    // Route: GET /{shlId}/content → serve encrypted content\n    if (segments.length === 2 && segments[1] === \"content\" && req.method === \"GET\") {\n      return handleContent(segments[0]!, storage);\n    }\n\n    // Route: GET /{shlId}/attachment/{index} → serve encrypted attachment\n    if (segments.length === 3 && segments[1] === \"attachment\" && req.method === \"GET\") {\n      const index = segments[2]!;\n      return handleAttachment(segments[0]!, index, storage);\n    }\n\n    // Method not allowed for known paths\n    if (segments.length === 1 && req.method !== \"POST\") {\n      return jsonResponse(405, { error: \"Method not allowed. Use POST for manifest requests.\" });\n    }\n    if (segments.length === 2 && segments[1] === \"content\" && req.method !== \"GET\") {\n      return jsonResponse(405, { error: \"Method not allowed. Use GET for content requests.\" });\n    }\n    if (segments.length === 3 && segments[1] === \"attachment\" && req.method !== \"GET\") {\n      return jsonResponse(405, { error: \"Method not allowed. Use GET for attachment requests.\" });\n    }\n\n    return jsonResponse(404, { error: \"Not found\" });\n  };\n}\n\nasync function handleManifest(\n  shlId: string,\n  req: HandlerRequest,\n  storage: SHLHandlerConfig[\"storage\"],\n  onAccess?: SHLHandlerConfig[\"onAccess\"],\n): Promise<HandlerResponse> {\n  // Read manifest to verify the SHL exists\n  const manifestRaw = await storage.read(`${shlId}/manifest.json`);\n  if (manifestRaw === null) {\n    return jsonResponse(404, { error: \"SHL not found\" });\n  }\n\n  // Atomically check access control + increment counter\n  let updatedMetadata: SHLMetadata | null = null;\n  let accessDeniedReason: \"expired\" | \"exhausted\" | \"passcode\" | null = null;\n  const reqBody = (req.body && typeof req.body === \"object\" ? req.body : {}) as Record<string, unknown>;\n  const providedPasscode = typeof reqBody[\"passcode\"] === \"string\" ? reqBody[\"passcode\"] : undefined;\n\n  updatedMetadata = await storage.updateMetadata(shlId, (metadata) => {\n    // Check expiration\n    if (metadata.expiresAt) {\n      const expiresAt = new Date(metadata.expiresAt);\n      if (expiresAt.getTime() <= Date.now()) {\n        accessDeniedReason = \"expired\";\n        return null;\n      }\n    }\n\n    // Check access count\n    const currentCount = metadata.accessCount ?? 0;\n    if (metadata.maxAccesses !== undefined && currentCount >= metadata.maxAccesses) {\n      accessDeniedReason = \"exhausted\";\n      return null;\n    }\n\n    // Check passcode\n    if (metadata.passcode) {\n      if (!providedPasscode || providedPasscode !== metadata.passcode) {\n        accessDeniedReason = \"passcode\";\n        return null;\n      }\n    }\n\n    // Access granted — increment count\n    return {\n      ...metadata,\n      accessCount: currentCount + 1,\n    };\n  });\n\n  // Handle access control failures\n  if (accessDeniedReason === \"expired\") {\n    return jsonResponse(410, { error: \"SHL has expired\" });\n  }\n  if (accessDeniedReason === \"exhausted\") {\n    return jsonResponse(410, { error: \"SHL access limit reached\" });\n  }\n  if (accessDeniedReason === \"passcode\") {\n    return jsonResponse(401, { error: \"Invalid passcode\" });\n  }\n\n  // If updateMetadata returned null but no denied reason, metadata file is missing\n  if (updatedMetadata === null) {\n    return jsonResponse(404, { error: \"SHL not found\" });\n  }\n\n  // Fire access event (non-blocking)\n  if (onAccess) {\n    const event = {\n      shlId,\n      accessCount: updatedMetadata.accessCount ?? 1,\n      timestamp: new Date(),\n    };\n    // Fire and forget — don't let callback errors break the response\n    Promise.resolve(onAccess(event)).catch(() => {});\n  }\n\n  // Return manifest\n  const manifestStr = typeof manifestRaw === \"string\"\n    ? manifestRaw\n    : new TextDecoder().decode(manifestRaw);\n  const manifest = JSON.parse(manifestStr) as Manifest;\n\n  return jsonResponse(200, manifest);\n}\n\nasync function handleContent(\n  shlId: string,\n  storage: SHLHandlerConfig[\"storage\"],\n): Promise<HandlerResponse> {\n  const content = await storage.read(`${shlId}/content.jwe`);\n  if (content === null) {\n    return jsonResponse(404, { error: \"Content not found\" });\n  }\n\n  const body = typeof content === \"string\"\n    ? content\n    : new TextDecoder().decode(content);\n\n  return {\n    status: 200,\n    headers: {\n      \"content-type\": \"application/jose\",\n      \"cache-control\": \"no-store\",\n    },\n    body,\n  };\n}\n\nasync function handleAttachment(\n  shlId: string,\n  index: string,\n  storage: SHLHandlerConfig[\"storage\"],\n): Promise<HandlerResponse> {\n  if (!/^\\d+$/.test(index)) {\n    return jsonResponse(400, { error: \"Invalid attachment index\" });\n  }\n  const content = await storage.read(`${shlId}/attachment-${index}.jwe`);\n  if (content === null) {\n    return jsonResponse(404, { error: \"Attachment not found\" });\n  }\n  const body = typeof content === \"string\"\n    ? content\n    : new TextDecoder().decode(content);\n  return {\n    status: 200,\n    headers: {\n      \"content-type\": \"application/jose\",\n      \"cache-control\": \"no-store\",\n    },\n    body,\n  };\n}\n\nfunction jsonResponse(status: number, body: unknown): HandlerResponse {\n  return {\n    status,\n    headers: {\n      \"content-type\": \"application/json\",\n      \"cache-control\": \"no-store\",\n    },\n    body: JSON.stringify(body),\n  };\n}\n"]}

package/dist/chunk-KI44MYPE.cjs

@@ -0,0 +1,170 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+// src/errors.ts
+var ShlError = class _ShlError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ShlError";
+    Object.setPrototypeOf(this, _ShlError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends ShlError {
+  issues;
+  constructor(message, issues = []) {
+    super(message);
+    this.name = "ValidationError";
+    this.issues = issues;
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var StorageError = class _StorageError extends ShlError {
+  operation;
+  constructor(message, operation) {
+    super(message);
+    this.name = "StorageError";
+    this.operation = operation;
+    Object.setPrototypeOf(this, _StorageError.prototype);
+  }
+};
+var EncryptionError = class _EncryptionError extends ShlError {
+  constructor(message) {
+    super(message);
+    this.name = "EncryptionError";
+    Object.setPrototypeOf(this, _EncryptionError.prototype);
+  }
+};
+var LocalStorage = class {
+  _config;
+  constructor(config) {
+    this._config = config;
+  }
+  /** Returns the storage configuration. */
+  get config() {
+    return this._config;
+  }
+  /** Base URL with trailing slashes stripped. */
+  get baseUrl() {
+    return this._config.baseUrl.replace(/\/+$/, "");
+  }
+  async store(key, content) {
+    const filePath = path.join(this._config.directory, key);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+  async delete(prefix) {
+    const dirPath = path.join(this._config.directory, prefix);
+    fs.rmSync(dirPath, { recursive: true, force: true });
+  }
+};
+var _s3Module;
+async function getS3Module() {
+  if (_s3Module) return _s3Module;
+  try {
+    _s3Module = await import('@aws-sdk/client-s3');
+    return _s3Module;
+  } catch {
+    throw new StorageError(
+      "@aws-sdk/client-s3 is required for S3Storage. Install it: npm install @aws-sdk/client-s3",
+      "import"
+    );
+  }
+}
+var S3Storage = class {
+  _config;
+  _client;
+  constructor(config) {
+    this._config = config;
+  }
+  /** Returns the storage configuration. */
+  get config() {
+    return this._config;
+  }
+  /** Base URL with trailing slashes stripped. */
+  get baseUrl() {
+    return this._config.baseUrl.replace(/\/+$/, "");
+  }
+  async store(key, content) {
+    try {
+      const s3 = await getS3Module();
+      const client = this._getClient(s3);
+      const body = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+      const command = new s3.PutObjectCommand({
+        Bucket: this._config.bucket,
+        Key: this._s3Key(key),
+        Body: body,
+        ContentType: this._contentType(key)
+      });
+      await client.send(command);
+    } catch (err) {
+      if (err instanceof StorageError) throw err;
+      throw new StorageError(
+        `Failed to store ${key}: ${err instanceof Error ? err.message : String(err)}`,
+        "store"
+      );
+    }
+  }
+  async delete(prefix) {
+    try {
+      const s3 = await getS3Module();
+      const client = this._getClient(s3);
+      const s3Prefix = this._s3Key(prefix);
+      let continuationToken;
+      do {
+        const listInput = {
+          Bucket: this._config.bucket,
+          Prefix: s3Prefix
+        };
+        if (continuationToken) {
+          listInput["ContinuationToken"] = continuationToken;
+        }
+        const listCommand = new s3.ListObjectsV2Command(listInput);
+        const response = await client.send(listCommand);
+        const objects = response.Contents;
+        if (!objects || objects.length === 0) break;
+        const deleteInput = {
+          Bucket: this._config.bucket,
+          Delete: {
+            Objects: objects.map((obj) => ({ Key: obj.Key })),
+            Quiet: true
+          }
+        };
+        const deleteCommand = new s3.DeleteObjectsCommand(deleteInput);
+        await client.send(deleteCommand);
+        continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+      } while (continuationToken);
+    } catch (err) {
+      if (err instanceof StorageError) throw err;
+      throw new StorageError(
+        `Failed to delete ${prefix}: ${err instanceof Error ? err.message : String(err)}`,
+        "delete"
+      );
+    }
+  }
+  _getClient(s3) {
+    if (!this._client) {
+      this._client = new s3.S3Client({ region: this._config.region });
+    }
+    return this._client;
+  }
+  _s3Key(key) {
+    const prefix = this._config.prefix?.replace(/\/+$/, "");
+    return prefix ? `${prefix}/${key}` : key;
+  }
+  _contentType(key) {
+    if (key.endsWith(".jwe")) return "application/jose";
+    if (key.endsWith(".json")) return "application/json";
+    return "application/octet-stream";
+  }
+};
+
+exports.EncryptionError = EncryptionError;
+exports.LocalStorage = LocalStorage;
+exports.S3Storage = S3Storage;
+exports.ShlError = ShlError;
+exports.StorageError = StorageError;
+exports.ValidationError = ValidationError;
+//# sourceMappingURL=chunk-KI44MYPE.cjs.map
+//# sourceMappingURL=chunk-KI44MYPE.cjs.map

package/dist/chunk-KI44MYPE.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/shl/storage.ts"],"names":["join","mkdirSync","dirname","writeFileSync","rmSync"],"mappings":"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","file":"chunk-KI44MYPE.cjs","sourcesContent":["// Copyright 2026 FHIRfly.io LLC. All rights reserved.\n// Licensed under the MIT License. See LICENSE file in the project root.\n/**\n * Base error class for all SHL SDK errors.\n */\nexport class ShlError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ShlError\";\n    Object.setPrototypeOf(this, ShlError.prototype);\n  }\n}\n\n/**\n * Error thrown when IPS bundle validation fails.\n */\nexport class ValidationError extends ShlError {\n  readonly issues: string[];\n\n  constructor(message: string, issues: string[] = []) {\n    super(message);\n    this.name = \"ValidationError\";\n    this.issues = issues;\n    Object.setPrototypeOf(this, ValidationError.prototype);\n  }\n}\n\n/**\n * Error thrown when a storage operation fails.\n */\nexport class StorageError extends ShlError {\n  readonly operation: string;\n\n  constructor(message: string, operation: string) {\n    super(message);\n    this.name = \"StorageError\";\n    this.operation = operation;\n    Object.setPrototypeOf(this, StorageError.prototype);\n  }\n}\n\n/**\n * Error thrown when encryption or decryption fails.\n */\nexport class EncryptionError extends ShlError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"EncryptionError\";\n    Object.setPrototypeOf(this, EncryptionError.prototype);\n  }\n}\n","// Copyright 2026 FHIRfly.io LLC. All rights reserved.\n// Licensed under the MIT License. See LICENSE file in the project root.\nimport { mkdirSync, writeFileSync, rmSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport type { SHLStorage } from \"./types.js\";\nimport { StorageError } from \"../errors.js\";\n\n/**\n * Configuration for local filesystem SHL storage.\n */\nexport interface LocalStorageConfig {\n  /** Directory path for storing SHL files */\n  directory: string;\n  /** Base URL for serving the files (trailing slashes are stripped) */\n  baseUrl: string;\n}\n\n/**\n * Local filesystem storage for SMART Health Links.\n * Useful for development and testing.\n *\n * Files are written to `{directory}/{key}`. The user's server\n * maps `{baseUrl}/{shlId}` to reads from this directory.\n *\n * @example\n * ```ts\n * const storage = new SHL.LocalStorage({\n *   directory: \"./shl-data\",\n *   baseUrl: \"http://localhost:3000/shl\",\n * });\n * ```\n */\nexport class LocalStorage implements SHLStorage {\n  private readonly _config: LocalStorageConfig;\n\n  constructor(config: LocalStorageConfig) {\n    this._config = config;\n  }\n\n  /** Returns the storage configuration. */\n  get config(): LocalStorageConfig {\n    return this._config;\n  }\n\n  /** Base URL with trailing slashes stripped. */\n  get baseUrl(): string {\n    return this._config.baseUrl.replace(/\\/+$/, \"\");\n  }\n\n  async store(key: string, content: string | Uint8Array): Promise<void> {\n    const filePath = join(this._config.directory, key);\n    mkdirSync(dirname(filePath), { recursive: true });\n    writeFileSync(filePath, content);\n  }\n\n  async delete(prefix: string): Promise<void> {\n    const dirPath = join(this._config.directory, prefix);\n    rmSync(dirPath, { recursive: true, force: true });\n  }\n}\n\n/**\n * Configuration for S3-based SHL storage.\n */\nexport interface S3StorageConfig {\n  /** S3 bucket name */\n  bucket: string;\n  /** AWS region */\n  region: string;\n  /** Optional key prefix */\n  prefix?: string;\n  /** Base URL for serving the files */\n  baseUrl: string;\n}\n\n// Minimal interfaces for @aws-sdk/client-s3 (peer dependency)\ninterface S3ClientInstance {\n  send(command: unknown): Promise<unknown>;\n}\ninterface S3Module {\n  S3Client: new (config: { region: string }) => S3ClientInstance;\n  PutObjectCommand: new (input: Record<string, unknown>) => unknown;\n  ListObjectsV2Command: new (input: Record<string, unknown>) => unknown;\n  DeleteObjectsCommand: new (input: Record<string, unknown>) => unknown;\n}\n\nlet _s3Module: S3Module | undefined;\nasync function getS3Module(): Promise<S3Module> {\n  if (_s3Module) return _s3Module;\n  try {\n    _s3Module = (await import(\"@aws-sdk/client-s3\")) as unknown as S3Module;\n    return _s3Module;\n  } catch {\n    throw new StorageError(\n      \"@aws-sdk/client-s3 is required for S3Storage. Install it: npm install @aws-sdk/client-s3\",\n      \"import\",\n    );\n  }\n}\n\n/**\n * S3-backed storage for SMART Health Links.\n *\n * Requires `@aws-sdk/client-s3` as a peer dependency — install it separately:\n * ```\n * npm install @aws-sdk/client-s3\n * ```\n *\n * @example\n * ```ts\n * const storage = new SHL.S3Storage({\n *   bucket: \"my-shl-bucket\",\n *   region: \"us-east-1\",\n *   baseUrl: \"https://shl.example.com\",\n * });\n * ```\n */\nexport class S3Storage implements SHLStorage {\n  private readonly _config: S3StorageConfig;\n  private _client?: S3ClientInstance;\n\n  constructor(config: S3StorageConfig) {\n    this._config = config;\n  }\n\n  /** Returns the storage configuration. */\n  get config(): S3StorageConfig {\n    return this._config;\n  }\n\n  /** Base URL with trailing slashes stripped. */\n  get baseUrl(): string {\n    return this._config.baseUrl.replace(/\\/+$/, \"\");\n  }\n\n  async store(key: string, content: string | Uint8Array): Promise<void> {\n    try {\n      const s3 = await getS3Module();\n      const client = this._getClient(s3);\n      const body =\n        typeof content === \"string\" ? Buffer.from(content, \"utf8\") : content;\n\n      const command = new s3.PutObjectCommand({\n        Bucket: this._config.bucket,\n        Key: this._s3Key(key),\n        Body: body,\n        ContentType: this._contentType(key),\n      });\n\n      await client.send(command);\n    } catch (err) {\n      if (err instanceof StorageError) throw err;\n      throw new StorageError(\n        `Failed to store ${key}: ${err instanceof Error ? err.message : String(err)}`,\n        \"store\",\n      );\n    }\n  }\n\n  async delete(prefix: string): Promise<void> {\n    try {\n      const s3 = await getS3Module();\n      const client = this._getClient(s3);\n      const s3Prefix = this._s3Key(prefix);\n\n      let continuationToken: string | undefined;\n\n      do {\n        const listInput: Record<string, unknown> = {\n          Bucket: this._config.bucket,\n          Prefix: s3Prefix,\n        };\n        if (continuationToken) {\n          listInput[\"ContinuationToken\"] = continuationToken;\n        }\n\n        const listCommand = new s3.ListObjectsV2Command(listInput);\n        const response = (await client.send(listCommand)) as {\n          Contents?: Array<{ Key?: string }>;\n          IsTruncated?: boolean;\n          NextContinuationToken?: string;\n        };\n\n        const objects = response.Contents;\n        if (!objects || objects.length === 0) break;\n\n        const deleteInput = {\n          Bucket: this._config.bucket,\n          Delete: {\n            Objects: objects.map((obj) => ({ Key: obj.Key })),\n            Quiet: true,\n          },\n        };\n\n        const deleteCommand = new s3.DeleteObjectsCommand(deleteInput);\n        await client.send(deleteCommand);\n\n        continuationToken = response.IsTruncated\n          ? response.NextContinuationToken\n          : undefined;\n      } while (continuationToken);\n    } catch (err) {\n      if (err instanceof StorageError) throw err;\n      throw new StorageError(\n        `Failed to delete ${prefix}: ${err instanceof Error ? err.message : String(err)}`,\n        \"delete\",\n      );\n    }\n  }\n\n  private _getClient(s3: S3Module): S3ClientInstance {\n    if (!this._client) {\n      this._client = new s3.S3Client({ region: this._config.region });\n    }\n    return this._client;\n  }\n\n  private _s3Key(key: string): string {\n    const prefix = this._config.prefix?.replace(/\\/+$/, \"\");\n    return prefix ? `${prefix}/${key}` : key;\n  }\n\n  private _contentType(key: string): string {\n    if (key.endsWith(\".jwe\")) return \"application/jose\";\n    if (key.endsWith(\".json\")) return \"application/json\";\n    return \"application/octet-stream\";\n  }\n}\n"]}