@fhirfly-io/shl 0.1.0

package/dist/storage-iI_tyHcX.d.ts

@@ -0,0 +1,82 @@
+import { b as SHLStorage } from './types-yk0mDByJ.js';
+
+/**
+ * Configuration for local filesystem SHL storage.
+ */
+interface LocalStorageConfig {
+    /** Directory path for storing SHL files */
+    directory: string;
+    /** Base URL for serving the files (trailing slashes are stripped) */
+    baseUrl: string;
+}
+/**
+ * Local filesystem storage for SMART Health Links.
+ * Useful for development and testing.
+ *
+ * Files are written to `{directory}/{key}`. The user's server
+ * maps `{baseUrl}/{shlId}` to reads from this directory.
+ *
+ * @example
+ * ```ts
+ * const storage = new SHL.LocalStorage({
+ *   directory: "./shl-data",
+ *   baseUrl: "http://localhost:3000/shl",
+ * });
+ * ```
+ */
+declare class LocalStorage implements SHLStorage {
+    private readonly _config;
+    constructor(config: LocalStorageConfig);
+    /** Returns the storage configuration. */
+    get config(): LocalStorageConfig;
+    /** Base URL with trailing slashes stripped. */
+    get baseUrl(): string;
+    store(key: string, content: string | Uint8Array): Promise<void>;
+    delete(prefix: string): Promise<void>;
+}
+/**
+ * Configuration for S3-based SHL storage.
+ */
+interface S3StorageConfig {
+    /** S3 bucket name */
+    bucket: string;
+    /** AWS region */
+    region: string;
+    /** Optional key prefix */
+    prefix?: string;
+    /** Base URL for serving the files */
+    baseUrl: string;
+}
+/**
+ * S3-backed storage for SMART Health Links.
+ *
+ * Requires `@aws-sdk/client-s3` as a peer dependency — install it separately:
+ * ```
+ * npm install @aws-sdk/client-s3
+ * ```
+ *
+ * @example
+ * ```ts
+ * const storage = new SHL.S3Storage({
+ *   bucket: "my-shl-bucket",
+ *   region: "us-east-1",
+ *   baseUrl: "https://shl.example.com",
+ * });
+ * ```
+ */
+declare class S3Storage implements SHLStorage {
+    private readonly _config;
+    private _client?;
+    constructor(config: S3StorageConfig);
+    /** Returns the storage configuration. */
+    get config(): S3StorageConfig;
+    /** Base URL with trailing slashes stripped. */
+    get baseUrl(): string;
+    store(key: string, content: string | Uint8Array): Promise<void>;
+    delete(prefix: string): Promise<void>;
+    private _getClient;
+    private _s3Key;
+    private _contentType;
+}
+
+export { LocalStorage as L, S3Storage as S, type LocalStorageConfig as a, type S3StorageConfig as b };

package/dist/types--f4ITgu9.d.cts

@@ -0,0 +1,73 @@
+import { b as SHLStorage, e as SHLMetadata } from './types-yk0mDByJ.cjs';
+
+/**
+ * Framework-agnostic incoming request.
+ */
+interface HandlerRequest {
+    /** HTTP method (uppercase) */
+    method: string;
+    /** Path relative to mount point, e.g., "/{shlId}" or "/{shlId}/content" */
+    path: string;
+    /** Parsed JSON body (for POST requests) */
+    body?: unknown;
+    /** Request headers (lowercase keys) */
+    headers: Record<string, string | undefined>;
+}
+/**
+ * Framework-agnostic outgoing response.
+ */
+interface HandlerResponse {
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Response body (string for JSON, Uint8Array for binary) */
+    body: string | Uint8Array;
+}
+/**
+ * Extended storage interface for server-side operations.
+ *
+ * Adds `read` and `updateMetadata` to the base `SHLStorage` interface.
+ * Server storage needs to read files and atomically update metadata
+ * (e.g., increment access counts).
+ */
+interface SHLServerStorage extends SHLStorage {
+    /** Read a file by key. Returns null if not found. */
+    read(key: string): Promise<string | Uint8Array | null>;
+    /**
+     * Atomically read-modify-write metadata for an SHL.
+     *
+     * The `updater` function receives the current metadata and returns
+     * the updated metadata (or `null` to signal no update should occur).
+     *
+     * @param shlId - The SHL identifier
+     * @param updater - Function that transforms metadata
+     * @returns The updated metadata, or null if the SHL was not found or updater returned null
+     */
+    updateMetadata(shlId: string, updater: (current: SHLMetadata) => SHLMetadata | null): Promise<SHLMetadata | null>;
+}
+/**
+ * Configuration for the SHL server handler.
+ */
+interface SHLHandlerConfig {
+    /** Server storage backend (must implement SHLServerStorage) */
+    storage: SHLServerStorage;
+    /**
+     * Optional callback invoked on each successful manifest access.
+     * Useful for logging, analytics, or custom access control.
+     */
+    onAccess?: (event: AccessEvent) => void | Promise<void>;
+}
+/**
+ * Event emitted on each successful manifest access.
+ */
+interface AccessEvent {
+    /** The SHL identifier */
+    shlId: string;
+    /** Current access count (after increment) */
+    accessCount: number;
+    /** Timestamp of the access */
+    timestamp: Date;
+}
+
+export type { AccessEvent as A, HandlerRequest as H, SHLHandlerConfig as S, HandlerResponse as a, SHLServerStorage as b };

package/dist/types-DKtPO4DP.d.ts

@@ -0,0 +1,73 @@
+import { b as SHLStorage, e as SHLMetadata } from './types-yk0mDByJ.js';
+
+/**
+ * Framework-agnostic incoming request.
+ */
+interface HandlerRequest {
+    /** HTTP method (uppercase) */
+    method: string;
+    /** Path relative to mount point, e.g., "/{shlId}" or "/{shlId}/content" */
+    path: string;
+    /** Parsed JSON body (for POST requests) */
+    body?: unknown;
+    /** Request headers (lowercase keys) */
+    headers: Record<string, string | undefined>;
+}
+/**
+ * Framework-agnostic outgoing response.
+ */
+interface HandlerResponse {
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Response body (string for JSON, Uint8Array for binary) */
+    body: string | Uint8Array;
+}
+/**
+ * Extended storage interface for server-side operations.
+ *
+ * Adds `read` and `updateMetadata` to the base `SHLStorage` interface.
+ * Server storage needs to read files and atomically update metadata
+ * (e.g., increment access counts).
+ */
+interface SHLServerStorage extends SHLStorage {
+    /** Read a file by key. Returns null if not found. */
+    read(key: string): Promise<string | Uint8Array | null>;
+    /**
+     * Atomically read-modify-write metadata for an SHL.
+     *
+     * The `updater` function receives the current metadata and returns
+     * the updated metadata (or `null` to signal no update should occur).
+     *
+     * @param shlId - The SHL identifier
+     * @param updater - Function that transforms metadata
+     * @returns The updated metadata, or null if the SHL was not found or updater returned null
+     */
+    updateMetadata(shlId: string, updater: (current: SHLMetadata) => SHLMetadata | null): Promise<SHLMetadata | null>;
+}
+/**
+ * Configuration for the SHL server handler.
+ */
+interface SHLHandlerConfig {
+    /** Server storage backend (must implement SHLServerStorage) */
+    storage: SHLServerStorage;
+    /**
+     * Optional callback invoked on each successful manifest access.
+     * Useful for logging, analytics, or custom access control.
+     */
+    onAccess?: (event: AccessEvent) => void | Promise<void>;
+}
+/**
+ * Event emitted on each successful manifest access.
+ */
+interface AccessEvent {
+    /** The SHL identifier */
+    shlId: string;
+    /** Current access count (after increment) */
+    accessCount: number;
+    /** Timestamp of the access */
+    timestamp: Date;
+}
+
+export type { AccessEvent as A, HandlerRequest as H, SHLHandlerConfig as S, HandlerResponse as a, SHLServerStorage as b };

package/dist/types-yk0mDByJ.d.cts

@@ -0,0 +1,96 @@
+/**
+ * Options for creating a SMART Health Link.
+ */
+interface SHLOptions {
+    /** The FHIR Bundle to share (as a JSON object) */
+    bundle: Record<string, unknown>;
+    /** Additional files to include (e.g., PDF documents, SMART Health Cards) */
+    attachments?: SHLAttachment[];
+    /** Optional passcode to protect the link */
+    passcode?: string;
+    /** Expiration date for the link */
+    expiresAt?: Date;
+    /** Maximum number of times the link can be accessed */
+    maxAccesses?: number;
+    /** Label for the SHL (shown in viewer apps, max 80 chars) */
+    label?: string;
+    /** Storage backend to use */
+    storage: SHLStorage;
+    /** Save unencrypted bundle alongside encrypted JWE (development only — do not use in production) */
+    debug?: boolean;
+}
+/**
+ * An additional file to include in the SHL manifest.
+ */
+interface SHLAttachment {
+    /** MIME content type (e.g., "application/pdf") */
+    contentType: string;
+    /** File content — string for text, Uint8Array for binary */
+    content: string | Uint8Array;
+}
+/**
+ * Result of creating a SMART Health Link.
+ */
+interface SHLResult {
+    /** The full SHL URL (shlink:/ protocol) */
+    url: string;
+    /** QR code as a PNG data URI (data:image/png;base64,...) */
+    qrCode: string;
+    /** The passcode (if one was set) */
+    passcode?: string;
+    /** Unique identifier for the SHL */
+    id: string;
+    /** When the link expires */
+    expiresAt?: Date;
+    /** Path to the unencrypted bundle (only set when debug mode is enabled) */
+    debugBundlePath?: string;
+}
+/**
+ * SHL manifest file entry.
+ */
+interface ManifestEntry {
+    /** MIME type of the content (e.g., "application/fhir+json", "application/pdf") */
+    contentType: string;
+    /** URL to retrieve the content */
+    location?: string;
+    /** Embedded content (base64url-encoded if encrypted) */
+    embedded?: string;
+}
+/**
+ * SHL manifest file.
+ */
+interface Manifest {
+    /** Array of files available via this SHL */
+    files: ManifestEntry[];
+}
+/**
+ * Metadata stored alongside an SHL for access control.
+ */
+interface SHLMetadata {
+    /** Passcode required to access the link */
+    passcode?: string;
+    /** Maximum number of times the link can be accessed */
+    maxAccesses?: number;
+    /** Number of times the link has been accessed */
+    accessCount?: number;
+    /** ISO 8601 expiration date */
+    expiresAt?: string;
+    /** ISO 8601 creation date */
+    createdAt: string;
+}
+/**
+ * Interface for SHL storage backends.
+ *
+ * Storage backends write files to a location (filesystem, S3, etc.).
+ * The user configures their own server to serve these files via `baseUrl`.
+ */
+interface SHLStorage {
+    /** Base URL of the user's SHL server. Used to compute manifest and content URLs. */
+    readonly baseUrl: string;
+    /** Store content at the given key path. */
+    store(key: string, content: string | Uint8Array): Promise<void>;
+    /** Delete all files for an SHL by prefix. */
+    delete(prefix: string): Promise<void>;
+}
+
+export type { Manifest as M, SHLOptions as S, SHLResult as a, SHLStorage as b, ManifestEntry as c, SHLAttachment as d, SHLMetadata as e };

package/dist/types-yk0mDByJ.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Options for creating a SMART Health Link.
+ */
+interface SHLOptions {
+    /** The FHIR Bundle to share (as a JSON object) */
+    bundle: Record<string, unknown>;
+    /** Additional files to include (e.g., PDF documents, SMART Health Cards) */
+    attachments?: SHLAttachment[];
+    /** Optional passcode to protect the link */
+    passcode?: string;
+    /** Expiration date for the link */
+    expiresAt?: Date;
+    /** Maximum number of times the link can be accessed */
+    maxAccesses?: number;
+    /** Label for the SHL (shown in viewer apps, max 80 chars) */
+    label?: string;
+    /** Storage backend to use */
+    storage: SHLStorage;
+    /** Save unencrypted bundle alongside encrypted JWE (development only — do not use in production) */
+    debug?: boolean;
+}
+/**
+ * An additional file to include in the SHL manifest.
+ */
+interface SHLAttachment {
+    /** MIME content type (e.g., "application/pdf") */
+    contentType: string;
+    /** File content — string for text, Uint8Array for binary */
+    content: string | Uint8Array;
+}
+/**
+ * Result of creating a SMART Health Link.
+ */
+interface SHLResult {
+    /** The full SHL URL (shlink:/ protocol) */
+    url: string;
+    /** QR code as a PNG data URI (data:image/png;base64,...) */
+    qrCode: string;
+    /** The passcode (if one was set) */
+    passcode?: string;
+    /** Unique identifier for the SHL */
+    id: string;
+    /** When the link expires */
+    expiresAt?: Date;
+    /** Path to the unencrypted bundle (only set when debug mode is enabled) */
+    debugBundlePath?: string;
+}
+/**
+ * SHL manifest file entry.
+ */
+interface ManifestEntry {
+    /** MIME type of the content (e.g., "application/fhir+json", "application/pdf") */
+    contentType: string;
+    /** URL to retrieve the content */
+    location?: string;
+    /** Embedded content (base64url-encoded if encrypted) */
+    embedded?: string;
+}
+/**
+ * SHL manifest file.
+ */
+interface Manifest {
+    /** Array of files available via this SHL */
+    files: ManifestEntry[];
+}
+/**
+ * Metadata stored alongside an SHL for access control.
+ */
+interface SHLMetadata {
+    /** Passcode required to access the link */
+    passcode?: string;
+    /** Maximum number of times the link can be accessed */
+    maxAccesses?: number;
+    /** Number of times the link has been accessed */
+    accessCount?: number;
+    /** ISO 8601 expiration date */
+    expiresAt?: string;
+    /** ISO 8601 creation date */
+    createdAt: string;
+}
+/**
+ * Interface for SHL storage backends.
+ *
+ * Storage backends write files to a location (filesystem, S3, etc.).
+ * The user configures their own server to serve these files via `baseUrl`.
+ */
+interface SHLStorage {
+    /** Base URL of the user's SHL server. Used to compute manifest and content URLs. */
+    readonly baseUrl: string;
+    /** Store content at the given key path. */
+    store(key: string, content: string | Uint8Array): Promise<void>;
+    /** Delete all files for an SHL by prefix. */
+    delete(prefix: string): Promise<void>;
+}
+
+export type { Manifest as M, SHLOptions as S, SHLResult as a, SHLStorage as b, ManifestEntry as c, SHLAttachment as d, SHLMetadata as e };

package/package.json

@@ -0,0 +1,137 @@
+{
+  "name": "@fhirfly-io/shl",
+  "version": "0.1.0",
+  "description": "Official FHIRfly SDK for SMART Health Links - IPS bundle creation and SHL sharing",
+  "author": "FHIRfly.io LLC <admin@fhirfly.io>",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://fhirfly.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FHIRfly-io/fhirfly-shl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FHIRfly-io/fhirfly-shl/issues"
+  },
+  "keywords": [
+    "fhirfly",
+    "healthcare",
+    "smart-health-links",
+    "shl",
+    "ips",
+    "fhir",
+    "patient-summary",
+    "health-records",
+    "qr-code",
+    "clinical",
+    "middleware",
+    "express",
+    "fastify",
+    "lambda"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./server": {
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      },
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      }
+    },
+    "./express": {
+      "require": {
+        "types": "./dist/express.d.cts",
+        "default": "./dist/express.cjs"
+      },
+      "import": {
+        "types": "./dist/express.d.ts",
+        "default": "./dist/express.js"
+      }
+    },
+    "./fastify": {
+      "require": {
+        "types": "./dist/fastify.d.cts",
+        "default": "./dist/fastify.cjs"
+      },
+      "import": {
+        "types": "./dist/fastify.d.ts",
+        "default": "./dist/fastify.js"
+      }
+    },
+    "./lambda": {
+      "require": {
+        "types": "./dist/lambda.d.cts",
+        "default": "./dist/lambda.cjs"
+      },
+      "import": {
+        "types": "./dist/lambda.d.ts",
+        "default": "./dist/lambda.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "test:validate:setup": "bash tests/fhir-validate/setup-validator.sh",
+    "test:validate": "npm run test:validate:setup && vitest run tests/fhir-validate/",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "express": "^4.0.0 || ^5.0.0",
+    "fastify": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@fhirfly-io/terminology": "^0.5.0",
+    "@types/node": "^22.0.0",
+    "@types/qrcode": "^1.5.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.0.0"
+  }
+}