@fhirfly-io/shl 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+SMART Health Links SDK for Node.js — build IPS FHIR Bundles from clinical codes, encrypt, and share via SHL/QR code.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
@@ -20,98 +20,140 @@ PHI never leaves your server. Only terminology codes are sent to FHIRfly for enr
 npm install @fhirfly-io/shl
 ```
 
+For FHIRfly API enrichment (recommended):
+
+```bash
+npm install @fhirfly-io/shl @fhirfly-io/terminology
+```
+
 ## Quick Start
 
 ```typescript
-import { IPS, SHL } from '@fhirfly-io/shl';
-import { Fhirfly } from '@fhirfly-io/terminology';
+import { IPS, SHL } from "@fhirfly-io/shl";
+import Fhirfly from "@fhirfly-io/terminology";
 
-const fhirfly = new Fhirfly({ apiKey: process.env.FHIRFLY_API_KEY });
+const client = 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' },
+// Build the IPS Bundle
+const bundle = new IPS.Bundle({
+  patient: { name: "Maria Garcia", birthDate: "1985-03-15", gender: "female" },
 });
 
-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' });
+bundle.addMedication({ byNDC: "00071015523", fhirfly: client.ndc });
+bundle.addCondition({ byICD10: "E11.9", fhirfly: client.icd10 });
+bundle.addAllergy({ bySNOMED: "387207008" });
+bundle.addImmunization({ byCVX: "208", fhirfly: client.cvx });
+bundle.addResult({ byLOINC: "2339-0", fhirfly: client.loinc, value: 95, unit: "mg/dL" });
+bundle.addDocument({ content: pdfBuffer, contentType: "application/pdf", title: "Visit Summary" });
 
-// Build with configurable output profile
-const bundle = await ips.build({ profile: 'ips' });  // or 'r4' for generic FHIR
+const fhirBundle = await bundle.build();
 
-// Validate — mandatory before packaging
-const validation = await bundle.validate();
+// Create the SHL (zero-infra with FhirflyStorage)
+const storage = new SHL.FhirflyStorage({ apiKey: process.env.FHIRFLY_API_KEY });
 
-// 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',
+const result = await SHL.create({
+  bundle: fhirBundle,
+  storage,
+  passcode: "1234",
+  label: "Maria's Health Summary",
 });
 
-console.log(shl.url);       // shlink:/eyJ1cmwiOiJodHRwczovL...
-console.log(shl.qrCode);    // Base64 PNG
-console.log(shl.passcode);  // Communicate out-of-band to patient
+console.log(result.url);      // shlink:/eyJ1cmwiOiJodHRwczovL...
+console.log(result.qrCode);   // data:image/png;base64,...
+console.log(result.passcode); // "1234"
 ```
 
-## Design Principles
+## Storage Adapters
 
-- **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
+```typescript
+// FHIRfly hosted (zero infrastructure, recommended)
+new SHL.FhirflyStorage({ apiKey: "..." });
 
-## Output Profiles
+// AWS S3
+new SHL.S3Storage({ bucket: "my-bucket", region: "us-east-1", baseUrl: "https://shl.example.com" });
 
-| 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 |
+// Azure Blob Storage
+new SHL.AzureStorage({ container: "shl-data", connectionString: "...", baseUrl: "https://shl.example.com" });
+
+// Google Cloud Storage
+new SHL.GCSStorage({ bucket: "my-bucket", baseUrl: "https://shl.example.com" });
+
+// Local filesystem (development)
+new SHL.LocalStorage({ directory: "./shl-data", baseUrl: "http://localhost:3456/shl" });
+```
 
 ## 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 codes (enriched via FHIRfly API)
+bundle.addMedication({ byNDC: "00071015523", fhirfly: client.ndc });
+bundle.addMedication({ byRxNorm: "161", fhirfly: client.rxnorm });
+bundle.addCondition({ byICD10: "E11.9", fhirfly: client.icd10 });
+bundle.addResult({ byLOINC: "2339-0", fhirfly: client.loinc, value: 95, unit: "mg/dL" });
+bundle.addImmunization({ byCVX: "208", fhirfly: client.cvx });
 
 // From SNOMED (no API call needed)
-ips.addMedication({ bySNOMED: '376988009' });
+bundle.addMedication({ bySNOMED: "376988009" });
+bundle.addAllergy({ bySNOMED: "387207008" });
 
 // From existing FHIR R4 resources
-ips.addMedication({ fromResource: existingMedicationStatement });
+bundle.addMedication({ fromResource: existingMedicationStatement });
+bundle.addCondition({ fromResource: existingCondition });
+
+// Manual coding (no API dependency)
+bundle.addMedication({ code: "376988009", system: "http://snomed.info/sct", display: "Levothyroxine" });
 ```
 
-## Storage Adapters
+## CLI
+
+```bash
+npx @fhirfly-io/shl validate bundle.json   # Validate a FHIR Bundle
+npx @fhirfly-io/shl create bundle.json     # Create an SHL from a bundle
+npx @fhirfly-io/shl decode shlink:/eyJ...  # Decode an SHL URL
+npx @fhirfly-io/shl serve                  # Start a local SHL server
+npx @fhirfly-io/shl demo                   # Full round-trip demo
+```
+
+## Server Middleware
+
+Host your own SHL endpoints:
 
 ```typescript
-// AWS S3 (pre-signed URLs)
-new SHL.S3Storage({ bucket: 'my-bucket', region: 'us-east-1' });
+import express from "express";
+import { createShlMiddleware } from "@fhirfly-io/shl/express";
+import { ServerLocalStorage } from "@fhirfly-io/shl/server";
 
-// Azure Blob Storage (SAS tokens)
-new SHL.AzureStorage({ container: 'my-container', connectionString: '...' });
+const storage = new ServerLocalStorage({
+  directory: "./shl-data",
+  baseUrl: "http://localhost:3000/shl",
+});
 
-// Google Cloud Storage
-new SHL.GCSStorage({ bucket: 'my-bucket' });
+const app = express();
+app.use("/shl", createShlMiddleware({ storage }));
+app.listen(3000);
+```
+
+Also available for Fastify (`@fhirfly-io/shl/fastify`) and Lambda (`@fhirfly-io/shl/lambda`).
+
+## Live Exercise
 
-// Local filesystem (development/testing only)
-new SHL.LocalStorage({ directory: './shl-data' });
+Run the comprehensive integration test against the live API to exercise every SDK path:
+
+```bash
+npx tsx examples/live-exercise/index.ts --api-key <your-key> --verbose
 ```
 
+Covers bundle building, FhirflyStorage, LocalStorage + Express, SHL consumption, access control, and edge cases. See [`examples/live-exercise/README.md`](examples/live-exercise/README.md) for details.
+
 ## Related
 
-- [@fhirfly-io/terminology](https://www.npmjs.com/package/@fhirfly-io/terminology) — FHIRfly terminology API SDK (required for code enrichment)
+- [@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/)
-- [FHIRfly Documentation](https://fhirfly.io/docs)
+- [FHIRfly SHL Docs](https://fhirfly.io/docs/shl/overview)
+- [SHL Viewer](https://fhirfly.io/shl/viewer)
 
 ## License
 

package/dist/chunk-5I5H3SLO.cjs

@@ -0,0 +1,286 @@
+'use strict';
+
+var chunkUDS6UJAL_cjs = require('./chunk-UDS6UJAL.cjs');
+var fs = require('fs');
+var path = require('path');
+
+var ServerLocalStorage = class extends chunkUDS6UJAL_cjs.LocalStorage {
+  constructor(config) {
+    super(config);
+  }
+  async read(key) {
+    const filePath = path.join(this.config.directory, key);
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    try {
+      return fs.readFileSync(filePath, "utf8");
+    } catch {
+      return null;
+    }
+  }
+  async updateMetadata(shlId, updater) {
+    const key = `${shlId}/metadata.json`;
+    const raw = await this.read(key);
+    if (raw === null) return null;
+    const current = JSON.parse(raw);
+    const updated = updater(current);
+    if (updated === null) return null;
+    await this.store(key, JSON.stringify(updated));
+    return updated;
+  }
+};
+var _s3Module;
+async function getS3Module() {
+  if (_s3Module) return _s3Module;
+  try {
+    _s3Module = await import('@aws-sdk/client-s3');
+    return _s3Module;
+  } catch {
+    throw new chunkUDS6UJAL_cjs.StorageError(
+      "@aws-sdk/client-s3 is required for ServerS3Storage. Install it: npm install @aws-sdk/client-s3",
+      "import"
+    );
+  }
+}
+var ServerS3Storage = class {
+  _config;
+  _client;
+  constructor(config) {
+    this._config = config;
+  }
+  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 chunkUDS6UJAL_cjs.StorageError) throw err;
+      throw new chunkUDS6UJAL_cjs.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 deleteCommand = new s3.DeleteObjectsCommand({
+          Bucket: this._config.bucket,
+          Delete: {
+            Objects: objects.map((obj) => ({ Key: obj.Key })),
+            Quiet: true
+          }
+        });
+        await client.send(deleteCommand);
+        continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+      } while (continuationToken);
+    } catch (err) {
+      if (err instanceof chunkUDS6UJAL_cjs.StorageError) throw err;
+      throw new chunkUDS6UJAL_cjs.StorageError(
+        `Failed to delete ${prefix}: ${err instanceof Error ? err.message : String(err)}`,
+        "delete"
+      );
+    }
+  }
+  async read(key) {
+    try {
+      const s3 = await getS3Module();
+      const client = this._getClient(s3);
+      const command = new s3.GetObjectCommand({
+        Bucket: this._config.bucket,
+        Key: this._s3Key(key)
+      });
+      const response = await client.send(command);
+      if (!response.Body) return null;
+      return response.Body.transformToString();
+    } catch (err) {
+      const code = err.name;
+      if (code === "NoSuchKey") return null;
+      if (err instanceof chunkUDS6UJAL_cjs.StorageError) throw err;
+      throw new chunkUDS6UJAL_cjs.StorageError(
+        `Failed to read ${key}: ${err instanceof Error ? err.message : String(err)}`,
+        "read"
+      );
+    }
+  }
+  async updateMetadata(shlId, updater) {
+    const key = `${shlId}/metadata.json`;
+    const raw = await this.read(key);
+    if (raw === null) return null;
+    const current = JSON.parse(raw);
+    const updated = updater(current);
+    if (updated === null) return null;
+    await this.store(key, JSON.stringify(updated));
+    return updated;
+  }
+  _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";
+  }
+};
+var _azureModule;
+async function getAzureModule() {
+  if (_azureModule) return _azureModule;
+  try {
+    _azureModule = await import('@azure/storage-blob');
+    return _azureModule;
+  } catch {
+    throw new chunkUDS6UJAL_cjs.StorageError(
+      "@azure/storage-blob is required for ServerAzureStorage. Install it: npm install @azure/storage-blob",
+      "import"
+    );
+  }
+}
+var ServerAzureStorage = class extends chunkUDS6UJAL_cjs.AzureStorage {
+  _serverContainerClient;
+  constructor(config) {
+    super(config);
+  }
+  async read(key) {
+    try {
+      const container = await this._getServerContainer();
+      const blobName = this._serverBlobName(key);
+      const client = container.getBlockBlobClient(blobName);
+      const response = await client.download();
+      if (!response.readableStreamBody) return null;
+      return await streamToString(response.readableStreamBody);
+    } catch (err) {
+      const code = err.statusCode;
+      if (code === 404) return null;
+      if (err instanceof chunkUDS6UJAL_cjs.StorageError) throw err;
+      throw new chunkUDS6UJAL_cjs.StorageError(
+        `Failed to read ${key}: ${err instanceof Error ? err.message : String(err)}`,
+        "read"
+      );
+    }
+  }
+  async updateMetadata(shlId, updater) {
+    const key = `${shlId}/metadata.json`;
+    const raw = await this.read(key);
+    if (raw === null) return null;
+    const current = JSON.parse(raw);
+    const updated = updater(current);
+    if (updated === null) return null;
+    await this.store(key, JSON.stringify(updated));
+    return updated;
+  }
+  async _getServerContainer() {
+    if (!this._serverContainerClient) {
+      const azure = await getAzureModule();
+      const serviceClient = azure.BlobServiceClient.fromConnectionString(this.config.connectionString);
+      this._serverContainerClient = serviceClient.getContainerClient(this.config.container);
+    }
+    return this._serverContainerClient;
+  }
+  _serverBlobName(key) {
+    const prefix = this.config.prefix?.replace(/\/+$/, "");
+    return prefix ? `${prefix}/${key}` : key;
+  }
+};
+var _gcsModule;
+async function getGCSModule() {
+  if (_gcsModule) return _gcsModule;
+  try {
+    _gcsModule = await import('@google-cloud/storage');
+    return _gcsModule;
+  } catch {
+    throw new chunkUDS6UJAL_cjs.StorageError(
+      "@google-cloud/storage is required for ServerGCSStorage. Install it: npm install @google-cloud/storage",
+      "import"
+    );
+  }
+}
+var ServerGCSStorage = class extends chunkUDS6UJAL_cjs.GCSStorage {
+  _serverBucket;
+  constructor(config) {
+    super(config);
+  }
+  async read(key) {
+    try {
+      const bucket = await this._getServerBucket();
+      const fileName = this._serverFileName(key);
+      const file = bucket.file(fileName);
+      const [content] = await file.download();
+      return content.toString("utf8");
+    } catch (err) {
+      const code = err.code;
+      if (code === 404) return null;
+      if (err instanceof chunkUDS6UJAL_cjs.StorageError) throw err;
+      throw new chunkUDS6UJAL_cjs.StorageError(
+        `Failed to read ${key}: ${err instanceof Error ? err.message : String(err)}`,
+        "read"
+      );
+    }
+  }
+  async updateMetadata(shlId, updater) {
+    const key = `${shlId}/metadata.json`;
+    const raw = await this.read(key);
+    if (raw === null) return null;
+    const current = JSON.parse(raw);
+    const updated = updater(current);
+    if (updated === null) return null;
+    await this.store(key, JSON.stringify(updated));
+    return updated;
+  }
+  async _getServerBucket() {
+    if (!this._serverBucket) {
+      const gcs = await getGCSModule();
+      const storage = new gcs.Storage();
+      this._serverBucket = storage.bucket(this.config.bucket);
+    }
+    return this._serverBucket;
+  }
+  _serverFileName(key) {
+    const prefix = this.config.prefix?.replace(/\/+$/, "");
+    return prefix ? `${prefix}/${key}` : key;
+  }
+};
+async function streamToString(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+exports.ServerAzureStorage = ServerAzureStorage;
+exports.ServerGCSStorage = ServerGCSStorage;
+exports.ServerLocalStorage = ServerLocalStorage;
+exports.ServerS3Storage = ServerS3Storage;
+//# sourceMappingURL=chunk-5I5H3SLO.cjs.map
+//# sourceMappingURL=chunk-5I5H3SLO.cjs.map

package/dist/chunk-5I5H3SLO.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/storage.ts"],"names":["LocalStorage","join","existsSync","readFileSync","StorageError","AzureStorage","GCSStorage"],"mappings":"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","file":"chunk-5I5H3SLO.cjs","sourcesContent":["// Copyright 2026 FHIRfly.io LLC. All rights reserved.\n// Licensed under the MIT License. See LICENSE file in the project root.\nimport { readFileSync, existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { LocalStorage, AzureStorage, GCSStorage } from \"../shl/storage.js\";\nimport type { LocalStorageConfig, S3StorageConfig, AzureStorageConfig, GCSStorageConfig } from \"../shl/storage.js\";\nimport type { SHLServerStorage } from \"./types.js\";\nimport type { SHLMetadata } from \"../shl/types.js\";\nimport { StorageError } from \"../errors.js\";\n\n/**\n * Local filesystem server storage for SMART Health Links.\n *\n * Extends the base `LocalStorage` (write-only) with `read` and\n * `updateMetadata` methods needed for serving SHLs.\n *\n * @example\n * ```ts\n * import { ServerLocalStorage } from \"@fhirfly-io/shl/server\";\n *\n * const storage = new ServerLocalStorage({\n *   directory: \"./shl-data\",\n *   baseUrl: \"https://shl.example.com\",\n * });\n * ```\n */\nexport class ServerLocalStorage extends LocalStorage implements SHLServerStorage {\n  constructor(config: LocalStorageConfig) {\n    super(config);\n  }\n\n  async read(key: string): Promise<string | Uint8Array | null> {\n    const filePath = join(this.config.directory, key);\n    if (!existsSync(filePath)) {\n      return null;\n    }\n    try {\n      // Read as UTF-8 for JSON/JWE files, binary for others\n      return readFileSync(filePath, \"utf8\");\n    } catch {\n      return null;\n    }\n  }\n\n  async updateMetadata(\n    shlId: string,\n    updater: (current: SHLMetadata) => SHLMetadata | null,\n  ): Promise<SHLMetadata | null> {\n    const key = `${shlId}/metadata.json`;\n    const raw = await this.read(key);\n    if (raw === null) return null;\n\n    const current = JSON.parse(raw as string) as SHLMetadata;\n    const updated = updater(current);\n    if (updated === null) return null;\n\n    await this.store(key, JSON.stringify(updated));\n    return updated;\n  }\n}\n\n// Minimal S3 interfaces (same pattern as shl/storage.ts)\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  GetObjectCommand: 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 ServerS3Storage. Install it: npm install @aws-sdk/client-s3\",\n      \"import\",\n    );\n  }\n}\n\n/**\n * S3-backed server storage for SMART Health Links.\n *\n * Implements the full `SHLServerStorage` interface with `read` and\n * `updateMetadata` on top of S3.\n *\n * Uses conditional PutObject for optimistic concurrency on metadata updates.\n *\n * @example\n * ```ts\n * import { ServerS3Storage } from \"@fhirfly-io/shl/server\";\n *\n * const storage = new ServerS3Storage({\n *   bucket: \"my-shl-bucket\",\n *   region: \"us-east-1\",\n *   baseUrl: \"https://shl.example.com\",\n * });\n * ```\n */\nexport class ServerS3Storage implements SHLServerStorage {\n  private readonly _config: S3StorageConfig;\n  private _client?: S3ClientInstance;\n\n  constructor(config: S3StorageConfig) {\n    this._config = config;\n  }\n\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 = 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      do {\n        const listInput: Record<string, unknown> = {\n          Bucket: this._config.bucket,\n          Prefix: s3Prefix,\n        };\n        if (continuationToken) listInput[\"ContinuationToken\"] = continuationToken;\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 deleteCommand = new s3.DeleteObjectsCommand({\n          Bucket: this._config.bucket,\n          Delete: {\n            Objects: objects.map((obj) => ({ Key: obj.Key })),\n            Quiet: true,\n          },\n        });\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  async read(key: string): Promise<string | Uint8Array | null> {\n    try {\n      const s3 = await getS3Module();\n      const client = this._getClient(s3);\n\n      const command = new s3.GetObjectCommand({\n        Bucket: this._config.bucket,\n        Key: this._s3Key(key),\n      });\n\n      const response = (await client.send(command)) as {\n        Body?: { transformToString(): Promise<string> };\n      };\n\n      if (!response.Body) return null;\n      return response.Body.transformToString();\n    } catch (err) {\n      // S3 returns NoSuchKey for missing objects\n      const code = (err as { name?: string }).name;\n      if (code === \"NoSuchKey\") return null;\n      if (err instanceof StorageError) throw err;\n      throw new StorageError(\n        `Failed to read ${key}: ${err instanceof Error ? err.message : String(err)}`,\n        \"read\",\n      );\n    }\n  }\n\n  async updateMetadata(\n    shlId: string,\n    updater: (current: SHLMetadata) => SHLMetadata | null,\n  ): Promise<SHLMetadata | null> {\n    const key = `${shlId}/metadata.json`;\n    const raw = await this.read(key);\n    if (raw === null) return null;\n\n    const current = JSON.parse(raw as string) as SHLMetadata;\n    const updated = updater(current);\n    if (updated === null) return null;\n\n    await this.store(key, JSON.stringify(updated));\n    return updated;\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\n// ---------------------------------------------------------------------------\n// Azure Blob Storage (Server)\n// ---------------------------------------------------------------------------\n\n// Minimal Azure interfaces for server-side operations\ninterface AzureBlobModule {\n  BlobServiceClient: {\n    fromConnectionString(connectionString: string): AzureBlobServiceClient;\n  };\n}\ninterface AzureBlobServiceClient {\n  getContainerClient(container: string): AzureContainerClient;\n}\ninterface AzureContainerClient {\n  getBlockBlobClient(blobName: string): AzureBlockBlobClient;\n  listBlobsFlat(options?: { prefix?: string }): AsyncIterable<{ name: string }>;\n}\ninterface AzureBlockBlobClient {\n  upload(content: Uint8Array | Buffer, contentLength: number, options?: Record<string, unknown>): Promise<unknown>;\n  deleteIfExists(): Promise<unknown>;\n  download(): Promise<{ readableStreamBody?: NodeJS.ReadableStream }>;\n}\n\nlet _azureModule: AzureBlobModule | undefined;\nasync function getAzureModule(): Promise<AzureBlobModule> {\n  if (_azureModule) return _azureModule;\n  try {\n    _azureModule = (await import(\"@azure/storage-blob\")) as unknown as AzureBlobModule;\n    return _azureModule;\n  } catch {\n    throw new StorageError(\n      \"@azure/storage-blob is required for ServerAzureStorage. Install it: npm install @azure/storage-blob\",\n      \"import\",\n    );\n  }\n}\n\n/**\n * Azure Blob Storage server storage for SMART Health Links.\n *\n * Extends the base `AzureStorage` with `read` and `updateMetadata`\n * methods needed for serving SHLs.\n *\n * @example\n * ```ts\n * import { ServerAzureStorage } from \"@fhirfly-io/shl/server\";\n *\n * const storage = new ServerAzureStorage({\n *   container: \"shl-data\",\n *   connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING!,\n *   baseUrl: \"https://shl.example.com\",\n * });\n * ```\n */\nexport class ServerAzureStorage extends AzureStorage implements SHLServerStorage {\n  private _serverContainerClient?: AzureContainerClient;\n\n  constructor(config: AzureStorageConfig) {\n    super(config);\n  }\n\n  async read(key: string): Promise<string | Uint8Array | null> {\n    try {\n      const container = await this._getServerContainer();\n      const blobName = this._serverBlobName(key);\n      const client = container.getBlockBlobClient(blobName);\n\n      const response = await client.download();\n      if (!response.readableStreamBody) return null;\n\n      return await streamToString(response.readableStreamBody);\n    } catch (err) {\n      const code = (err as { statusCode?: number }).statusCode;\n      if (code === 404) return null;\n      if (err instanceof StorageError) throw err;\n      throw new StorageError(\n        `Failed to read ${key}: ${err instanceof Error ? err.message : String(err)}`,\n        \"read\",\n      );\n    }\n  }\n\n  async updateMetadata(\n    shlId: string,\n    updater: (current: SHLMetadata) => SHLMetadata | null,\n  ): Promise<SHLMetadata | null> {\n    const key = `${shlId}/metadata.json`;\n    const raw = await this.read(key);\n    if (raw === null) return null;\n\n    const current = JSON.parse(raw as string) as SHLMetadata;\n    const updated = updater(current);\n    if (updated === null) return null;\n\n    await this.store(key, JSON.stringify(updated));\n    return updated;\n  }\n\n  private async _getServerContainer(): Promise<AzureContainerClient> {\n    if (!this._serverContainerClient) {\n      const azure = await getAzureModule();\n      const serviceClient = azure.BlobServiceClient.fromConnectionString(this.config.connectionString);\n      this._serverContainerClient = serviceClient.getContainerClient(this.config.container);\n    }\n    return this._serverContainerClient;\n  }\n\n  private _serverBlobName(key: string): string {\n    const prefix = this.config.prefix?.replace(/\\/+$/, \"\");\n    return prefix ? `${prefix}/${key}` : key;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Google Cloud Storage (Server)\n// ---------------------------------------------------------------------------\n\n// Minimal GCS interfaces for server-side operations\ninterface GCSModule {\n  Storage: new () => GCSStorageClient;\n}\ninterface GCSStorageClient {\n  bucket(name: string): GCSBucket;\n}\ninterface GCSBucket {\n  file(name: string): GCSFile;\n  getFiles(options?: { prefix?: string }): Promise<[GCSFile[]]>;\n}\ninterface GCSFile {\n  save(content: Buffer, options?: Record<string, unknown>): Promise<void>;\n  delete(options?: Record<string, unknown>): Promise<unknown>;\n  download(): Promise<[Buffer]>;\n  name: string;\n}\n\nlet _gcsModule: GCSModule | undefined;\nasync function getGCSModule(): Promise<GCSModule> {\n  if (_gcsModule) return _gcsModule;\n  try {\n    _gcsModule = (await import(\"@google-cloud/storage\")) as unknown as GCSModule;\n    return _gcsModule;\n  } catch {\n    throw new StorageError(\n      \"@google-cloud/storage is required for ServerGCSStorage. Install it: npm install @google-cloud/storage\",\n      \"import\",\n    );\n  }\n}\n\n/**\n * Google Cloud Storage server storage for SMART Health Links.\n *\n * Extends the base `GCSStorage` with `read` and `updateMetadata`\n * methods needed for serving SHLs.\n *\n * @example\n * ```ts\n * import { ServerGCSStorage } from \"@fhirfly-io/shl/server\";\n *\n * const storage = new ServerGCSStorage({\n *   bucket: \"my-shl-bucket\",\n *   baseUrl: \"https://shl.example.com\",\n * });\n * ```\n */\nexport class ServerGCSStorage extends GCSStorage implements SHLServerStorage {\n  private _serverBucket?: GCSBucket;\n\n  constructor(config: GCSStorageConfig) {\n    super(config);\n  }\n\n  async read(key: string): Promise<string | Uint8Array | null> {\n    try {\n      const bucket = await this._getServerBucket();\n      const fileName = this._serverFileName(key);\n      const file = bucket.file(fileName);\n\n      const [content] = await file.download();\n      return content.toString(\"utf8\");\n    } catch (err) {\n      const code = (err as { code?: number }).code;\n      if (code === 404) return null;\n      if (err instanceof StorageError) throw err;\n      throw new StorageError(\n        `Failed to read ${key}: ${err instanceof Error ? err.message : String(err)}`,\n        \"read\",\n      );\n    }\n  }\n\n  async updateMetadata(\n    shlId: string,\n    updater: (current: SHLMetadata) => SHLMetadata | null,\n  ): Promise<SHLMetadata | null> {\n    const key = `${shlId}/metadata.json`;\n    const raw = await this.read(key);\n    if (raw === null) return null;\n\n    const current = JSON.parse(raw as string) as SHLMetadata;\n    const updated = updater(current);\n    if (updated === null) return null;\n\n    await this.store(key, JSON.stringify(updated));\n    return updated;\n  }\n\n  private async _getServerBucket(): Promise<GCSBucket> {\n    if (!this._serverBucket) {\n      const gcs = await getGCSModule();\n      const storage = new gcs.Storage();\n      this._serverBucket = storage.bucket(this.config.bucket);\n    }\n    return this._serverBucket;\n  }\n\n  private _serverFileName(key: string): string {\n    const prefix = this.config.prefix?.replace(/\\/+$/, \"\");\n    return prefix ? `${prefix}/${key}` : key;\n  }\n}\n\n/** Helper: convert a Node.js ReadableStream to a string. */\nasync function streamToString(stream: NodeJS.ReadableStream): Promise<string> {\n  const chunks: Buffer[] = [];\n  for await (const chunk of stream) {\n    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string));\n  }\n  return Buffer.concat(chunks).toString(\"utf8\");\n}\n"]}