vintasend-medplum 0.4.0

package/README.md

@@ -0,0 +1,506 @@
+# VintaSend Medplum Implementation
+
+A complete VintaSend implementation using [Medplum](https://www.medplum.com/) as the backend, leveraging FHIR resources for notification management, file storage, and healthcare integration.
+
+## Overview
+
+This implementation uses FHIR (Fast Healthcare Interoperability Resources) standards to store and manage notifications, making it ideal for healthcare applications that need to integrate notifications with patient care workflows.
+
+### Key Components
+
+- **MedplumNotificationBackend**: Stores notifications as FHIR `Communication` resources
+- **MedplumNotificationAdapter**: Sends email notifications via Medplum's email API
+- **MedplumAttachmentManager**: Manages file attachments using FHIR `Binary` and `Media` resources
+- **MedplumLogger**: Simple console-based logger
+
+## How It Works
+
+### FHIR Resource Mapping
+
+The implementation maps VintaSend concepts to FHIR resources:
+
+#### Notifications → Communication Resources
+
+```typescript
+{
+  resourceType: "Communication",
+  status: "in-progress",           // PENDING_SEND
+  sent: "2024-01-15T10:00:00Z",   // sendAfter
+  topic: { text: "Welcome!" },     // title
+  recipient: [{ reference: "Patient/123" }],  // userId
+  payload: [{
+    contentString: "Hello {{name}}",  // bodyTemplate
+    extension: [{
+      url: "http://vintasend.com/fhir/StructureDefinition/email-notification-subject",
+      valueString: "Welcome {{name}}"  // subjectTemplate
+    }]
+  }],
+  note: [{ text: '{"userId": "123"}' }],  // contextParameters
+  meta: {
+    tag: [
+      { code: "notification" },
+      { code: "user-welcome" },      // contextName
+      { code: "EMAIL" }              // notificationType
+    ]
+  }
+}
+```
+
+#### File Attachments → Binary + Media Resources
+
+Files are stored using two FHIR resources:
+
+1. **Binary Resource**: Stores the actual file data (base64 encoded)
+2. **Media Resource**: Stores metadata and links to the Binary
+
+```typescript
+// Binary resource
+{
+  resourceType: "Binary",
+  contentType: "application/pdf",
+  data: "base64EncodedData..."
+}
+
+// Media resource
+{
+  resourceType: "Media",
+  status: "completed",
+  content: {
+    contentType: "application/pdf",
+    url: "Binary/binary-id",
+    size: 12345,
+    title: "invoice.pdf"
+  },
+  identifier: [{
+    system: "http://vintasend.com/fhir/attachment-checksum",
+    value: "sha256-checksum"
+  }]
+}
+```
+
+### Status Mapping
+
+| VintaSend Status | FHIR Communication Status |
+|-----------------|---------------------------|
+| PENDING_SEND    | in-progress               |
+| SENT            | completed                 |
+| FAILED          | stopped                   |
+
+## Installation
+
+```bash
+npm install vintasend-medplum @medplum/core
+```
+
+## Setup
+
+### Basic Configuration
+
+```typescript
+import { MedplumClient } from '@medplum/core';
+import { MedplumNotificationBackend } from 'vintasend-medplum';
+import { MedplumNotificationAdapter } from 'vintasend-medplum';
+import { MedplumAttachmentManager } from 'vintasend-medplum';
+import { MedplumLogger } from 'vintasend-medplum';
+import { PugTemplateRenderer } from 'vintasend-pug';
+import { NotificationService } from 'vintasend';
+
+// Initialize Medplum client
+const medplum = new MedplumClient({
+  baseUrl: 'https://api.medplum.com',
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+});
+
+// Create template renderer
+const templateRenderer = new PugTemplateRenderer({
+  templatesDir: './templates',
+});
+
+// Create notification adapter
+const adapter = new MedplumNotificationAdapter(medplum, templateRenderer);
+
+// Create backend
+const backend = new MedplumNotificationBackend(medplum, {
+  emailNotificationSubjectExtensionUrl: 'http://your-domain.com/fhir/StructureDefinition/email-notification-subject',
+});
+
+// Create attachment manager (optional)
+const attachmentManager = new MedplumAttachmentManager(medplum);
+
+// Create logger
+const logger = new MedplumLogger();
+
+// Initialize notification service
+const notificationService = new NotificationService(
+  backend,
+  [adapter],
+  logger,
+  attachmentManager,
+);
+```
+
+### With Custom Configuration
+
+```typescript
+// Custom extension URL for email subjects
+const backend = new MedplumNotificationBackend(medplum, {
+  emailNotificationSubjectExtensionUrl: 'http://example.com/fhir/email-subject',
+});
+```
+
+## Usage Examples
+
+### Sending a Simple Notification
+
+```typescript
+// Create a notification
+await notificationService.createNotification({
+  userId: 'Patient/123',
+  notificationType: 'EMAIL',
+  contextName: 'user-welcome',
+  contextParameters: {
+    firstName: 'John',
+    lastName: 'Doe',
+  },
+  title: 'Welcome to our platform!',
+  bodyTemplate: 'Hello {{firstName}} {{lastName}}!',
+  subjectTemplate: 'Welcome {{firstName}}!',
+  sendAfter: new Date(),
+});
+
+// Process pending notifications
+await notificationService.processPendingNotifications();
+```
+
+### Sending Notifications with Attachments
+
+```typescript
+import { readFile } from 'fs/promises';
+
+// Create notification with file attachments
+await notificationService.createNotification({
+  userId: 'Patient/123',
+  notificationType: 'EMAIL',
+  contextName: 'lab-results',
+  contextParameters: {
+    patientName: 'John Doe',
+  },
+  title: 'Your lab results are ready',
+  bodyTemplate: 'Dear {{patientName}}, your lab results are attached.',
+  subjectTemplate: 'Lab Results - {{patientName}}',
+  sendAfter: new Date(),
+  attachments: [
+    {
+      file: await readFile('./lab-results.pdf'),
+      filename: 'lab-results.pdf',
+      contentType: 'application/pdf',
+    },
+  ],
+});
+```
+
+### One-Off Notifications
+
+Send notifications to users without storing them in the system:
+
+```typescript
+await notificationService.createOneOffNotification({
+  emailOrPhone: 'patient@example.com',
+  firstName: 'Jane',
+  lastName: 'Smith',
+  notificationType: 'EMAIL',
+  contextName: 'appointment-reminder',
+  contextParameters: {
+    appointmentDate: '2024-02-01',
+    doctorName: 'Dr. Johnson',
+  },
+  title: 'Appointment Reminder',
+  bodyTemplate: 'Hi {{firstName}}, reminder for your appointment on {{appointmentDate}}.',
+  subjectTemplate: 'Appointment on {{appointmentDate}}',
+  sendAfter: new Date(),
+});
+```
+
+### Managing Attachments
+
+```typescript
+// Upload a file
+const fileRecord = await attachmentManager.uploadFile(
+  buffer,
+  'document.pdf',
+  'application/pdf',
+);
+
+// Retrieve file metadata
+const file = await attachmentManager.getFile(fileRecord.id);
+
+// Get file data
+const attachmentFile = attachmentManager.reconstructAttachmentFile(
+  file.storageMetadata,
+);
+const fileBuffer = await attachmentFile.read();
+
+// Generate temporary URL
+const url = await attachmentFile.url(3600); // 1 hour expiry
+
+// Delete file
+await attachmentManager.deleteFile(fileRecord.id);
+```
+
+### Querying Notifications
+
+```typescript
+// Get pending notifications
+const pending = await notificationService.getPendingNotifications(0, 10);
+
+// Get future notifications for a user
+const future = await notificationService.getFutureNotificationsFromUser(
+  'Patient/123',
+  0,
+  10,
+);
+
+// Get unread in-app notifications
+const unread = await notificationService.filterInAppUnreadNotifications(
+  'Patient/123',
+  0,
+  10,
+);
+
+// Mark as read
+await notificationService.markAsRead(notificationId);
+```
+
+### Canceling Notifications
+
+```typescript
+// Cancel a scheduled notification
+await notificationService.cancelNotification(notificationId);
+```
+
+## Healthcare Integration
+
+This implementation is designed for healthcare applications and integrates naturally with Medplum's FHIR-based infrastructure.
+
+### Linking Notifications to Patients
+
+```typescript
+// Create notification linked to a patient
+await notificationService.createNotification({
+  userId: 'Patient/123',  // FHIR Patient reference
+  notificationType: 'EMAIL',
+  contextName: 'medication-reminder',
+  contextParameters: {
+    medicationName: 'Aspirin',
+    dosage: '100mg',
+  },
+  // ...
+});
+```
+
+### Linking Notifications to Practitioners
+
+```typescript
+// Notify a healthcare provider
+await notificationService.createNotification({
+  userId: 'Practitioner/456',  // FHIR Practitioner reference
+  notificationType: 'EMAIL',
+  contextName: 'new-patient-alert',
+  // ...
+});
+```
+
+### Searching Notifications by Resource
+
+```typescript
+// Get all notifications for a patient
+const communications = await medplum.searchResources('Communication', {
+  _tag: 'notification',
+  recipient: 'Patient/123',
+});
+```
+
+## Features
+
+### ✅ Supported Features
+
+- Email notifications via Medplum's email API
+- File attachments using FHIR Binary and Media resources
+- One-off notifications (no user account required)
+- Scheduled notifications (send later)
+- Notification templates with context parameters
+- File deduplication via checksum
+- Attachment cleanup for orphaned files
+- FHIR-compliant data storage
+
+### ❌ Not Yet Supported
+
+- SMS notifications (Medplum limitation)
+- Push notifications (Medplum limitation)
+- In-app notification UI
+- Real-time notification delivery (requires polling or webhooks)
+
+## API Reference
+
+### MedplumNotificationBackend
+
+```typescript
+class MedplumNotificationBackend<Config extends BaseNotificationTypeConfig>
+```
+
+Main backend for storing notifications as FHIR Communication resources.
+
+**Constructor:**
+```typescript
+constructor(
+  medplum: MedplumClient,
+  options?: {
+    emailNotificationSubjectExtensionUrl?: string;
+  }
+)
+```
+
+**Key Methods:**
+- `persistNotification(notification)` - Create a new notification
+- `persistOneOffNotification(notification)` - Create a one-off notification
+- `getNotification(id)` - Retrieve a notification by ID
+- `getPendingNotifications(page, pageSize)` - Get notifications ready to send
+- `markAsSent(id)` - Mark notification as successfully sent
+- `markAsFailed(id)` - Mark notification as failed
+- `cancelNotification(id)` - Cancel a scheduled notification
+
+### MedplumNotificationAdapter
+
+```typescript
+class MedplumNotificationAdapter<
+  TemplateRenderer extends BaseEmailTemplateRenderer<Config>,
+  Config extends BaseNotificationTypeConfig
+>
+```
+
+Adapter for sending email notifications via Medplum.
+
+**Constructor:**
+```typescript
+constructor(
+  medplum: MedplumClient,
+  templateRenderer: TemplateRenderer
+)
+```
+
+**Properties:**
+- `supportsAttachments: boolean` - Returns `true`
+
+**Key Methods:**
+- `send(notification, context)` - Send an email notification with attachments
+
+### MedplumAttachmentManager
+
+```typescript
+class MedplumAttachmentManager extends BaseAttachmentManager
+```
+
+Manages file attachments using FHIR Binary and Media resources.
+
+**Constructor:**
+```typescript
+constructor(medplum: MedplumClient)
+```
+
+**Key Methods:**
+- `uploadFile(file, filename, contentType?)` - Upload a file to Medplum storage
+- `getFile(fileId)` - Retrieve file metadata by Media resource ID
+- `deleteFile(fileId)` - Delete file and its Binary resource
+- `reconstructAttachmentFile(storageMetadata)` - Create AttachmentFile from metadata
+
+### MedplumAttachmentFile
+
+```typescript
+class MedplumAttachmentFile implements AttachmentFile
+```
+
+Provides access to files stored in FHIR Binary resources.
+
+**Methods:**
+- `read()` - Read entire file into a Buffer
+- `stream()` - Get a ReadableStream for the file
+- `url(expiresIn?)` - Generate URL for file access
+- `delete()` - Delete the file from storage
+
+## Best Practices
+
+### 1. Use FHIR References Consistently
+
+Always use proper FHIR reference format for user IDs:
+
+```typescript
+// ✅ Good
+userId: 'Patient/123'
+userId: 'Practitioner/456'
+
+// ❌ Bad
+userId: '123'
+userId: 'user-456'
+```
+
+### 2. Configure Custom Extension URLs
+
+Use your own domain for extension URLs in production:
+
+```typescript
+const backend = new MedplumNotificationBackend(medplum, {
+  emailNotificationSubjectExtensionUrl: 'http://your-domain.com/fhir/email-subject',
+});
+```
+
+### 3. Handle Large Attachments Carefully
+
+For large files, consider:
+- Using file size limits
+- Implementing file compression
+- Using streaming for file operations
+
+```typescript
+// Check file size before upload
+const maxSize = 10 * 1024 * 1024; // 10MB
+if (buffer.length > maxSize) {
+  throw new Error('File too large');
+}
+```
+
+### 4. Clean Up Orphaned Files
+
+Regularly run cleanup to remove orphaned attachment files:
+
+```typescript
+// Get orphaned files
+const orphaned = await backend.getOrphanedAttachmentFiles();
+
+// Delete them
+for (const file of orphaned) {
+  await backend.deleteAttachmentFile(file.id);
+}
+```
+
+### 5. Use Pagination
+
+Always paginate when fetching large result sets:
+
+```typescript
+// ✅ Good
+const notifications = await notificationService.getPendingNotifications(0, 50);
+
+// ❌ Bad - could return thousands of records
+const notifications = await notificationService.getAllPendingNotifications();
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions:
+- VintaSend: [GitHub Issues](https://github.com/vintasoftware/vintasend-ts/issues)
+- Medplum: [Documentation](https://www.medplum.com/docs)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { MedplumAttachmentManager, MedplumAttachmentFile } from './medplum-attachment-manager';
+export { MedplumNotificationBackend, MedplumNotificationBackendFactory } from './medplum-backend';
+export { MedplumNotificationAdapter } from './medplum-adapter';

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MedplumNotificationAdapter = exports.MedplumNotificationBackendFactory = exports.MedplumNotificationBackend = exports.MedplumAttachmentFile = exports.MedplumAttachmentManager = void 0;
+var medplum_attachment_manager_1 = require("./medplum-attachment-manager");
+Object.defineProperty(exports, "MedplumAttachmentManager", { enumerable: true, get: function () { return medplum_attachment_manager_1.MedplumAttachmentManager; } });
+Object.defineProperty(exports, "MedplumAttachmentFile", { enumerable: true, get: function () { return medplum_attachment_manager_1.MedplumAttachmentFile; } });
+var medplum_backend_1 = require("./medplum-backend");
+Object.defineProperty(exports, "MedplumNotificationBackend", { enumerable: true, get: function () { return medplum_backend_1.MedplumNotificationBackend; } });
+Object.defineProperty(exports, "MedplumNotificationBackendFactory", { enumerable: true, get: function () { return medplum_backend_1.MedplumNotificationBackendFactory; } });
+var medplum_adapter_1 = require("./medplum-adapter");
+Object.defineProperty(exports, "MedplumNotificationAdapter", { enumerable: true, get: function () { return medplum_adapter_1.MedplumNotificationAdapter; } });

package/dist/medplum-adapter.d.ts

@@ -0,0 +1,19 @@
+import type { MedplumClient } from '@medplum/core';
+import type { BaseEmailTemplateRenderer } from 'vintasend/dist/services/notification-template-renderers/base-email-template-renderer';
+import { BaseNotificationAdapter } from 'vintasend/dist/services/notification-adapters/base-notification-adapter';
+import type { JsonObject } from 'vintasend/dist/types/json-values';
+import type { AnyDatabaseNotification } from 'vintasend/dist/types/notification';
+import type { BaseNotificationTypeConfig } from 'vintasend/dist/types/notification-type-config';
+import type { StoredAttachment } from 'vintasend/dist/types/attachment';
+export declare class MedplumNotificationAdapter<TemplateRenderer extends BaseEmailTemplateRenderer<Config>, Config extends BaseNotificationTypeConfig> extends BaseNotificationAdapter<TemplateRenderer, Config> {
+    private medplum;
+    key: string | null;
+    constructor(medplum: MedplumClient, templateRenderer: TemplateRenderer);
+    get supportsAttachments(): boolean;
+    send(notification: AnyDatabaseNotification<Config>, context: JsonObject): Promise<void>;
+    protected prepareAttachments(attachments: StoredAttachment[]): Promise<Array<{
+        filename: string;
+        content: string;
+        contentType: string;
+    }>>;
+}

package/dist/medplum-adapter.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MedplumNotificationAdapter = void 0;
+const base_notification_adapter_1 = require("vintasend/dist/services/notification-adapters/base-notification-adapter");
+class MedplumNotificationAdapter extends base_notification_adapter_1.BaseNotificationAdapter {
+    constructor(medplum, templateRenderer) {
+        const notificationType = 'EMAIL';
+        super(templateRenderer, notificationType, false);
+        this.medplum = medplum;
+        this.key = 'medplum-email';
+    }
+    get supportsAttachments() {
+        return true;
+    }
+    async send(notification, context) {
+        if (!this.backend) {
+            throw new Error('Backend not injected');
+        }
+        if (!notification.id) {
+            throw new Error('Notification ID is required');
+        }
+        // Use the helper method to get recipient email (handles both regular and one-off notifications)
+        const recipientEmail = await this.getRecipientEmail(notification);
+        const template = await this.templateRenderer.render(notification, context);
+        const emailOptions = {
+            to: recipientEmail,
+            subject: template.subject,
+            text: template.body,
+        };
+        // Add attachments if present
+        // Type assertion needed because npm version may not have attachments field yet
+        const notificationWithAttachments = notification;
+        if (notificationWithAttachments.attachments && notificationWithAttachments.attachments.length > 0) {
+            emailOptions.attachments = await this.prepareAttachments(notificationWithAttachments.attachments);
+        }
+        await this.medplum.sendEmail(emailOptions);
+    }
+    async prepareAttachments(attachments) {
+        return Promise.all(attachments.map(async (att) => {
+            const buffer = await att.file.read();
+            return {
+                filename: att.filename,
+                content: buffer.toString('base64'),
+                contentType: att.contentType,
+            };
+        }));
+    }
+}
+exports.MedplumNotificationAdapter = MedplumNotificationAdapter;

package/dist/medplum-attachment-manager.d.ts

@@ -0,0 +1,82 @@
+import { MedplumClient } from '@medplum/core';
+import { BaseAttachmentManager } from 'vintasend/dist/services/attachment-manager/base-attachment-manager';
+import type { AttachmentFileRecord, AttachmentFile, FileAttachment } from 'vintasend/dist/types/attachment';
+/**
+ * Medplum AttachmentManager implementation.
+ *
+ * This implementation uses FHIR resources for file storage:
+ * - Binary resources store the actual file data
+ * - Media resources store file metadata and link to Binary resources
+ *
+ * Files are uploaded to Medplum's storage and can be accessed via URLs.
+ */
+export declare class MedplumAttachmentManager extends BaseAttachmentManager {
+    private medplum;
+    constructor(medplum: MedplumClient);
+    /**
+     * Upload a file to Medplum storage using Binary and Media resources.
+     *
+     * @param file - The file data (Buffer, ReadableStream, or file path)
+     * @param filename - The filename to use for storage
+     * @param contentType - Optional MIME type (auto-detected if not provided)
+     * @returns AttachmentFileRecord with metadata about the uploaded file
+     */
+    uploadFile(file: FileAttachment, filename: string, contentType?: string): Promise<AttachmentFileRecord>;
+    /**
+     * Retrieve a file record by its Media resource ID.
+     *
+     * @param fileId - The Media resource ID
+     * @returns The file record or null if not found
+     */
+    getFile(fileId: string): Promise<AttachmentFileRecord | null>;
+    /**
+     * Delete a file from Medplum storage.
+     *
+     * Deletes both the Media resource (metadata) and Binary resource (file data).
+     *
+     * @param fileId - The Media resource ID
+     */
+    deleteFile(fileId: string): Promise<void>;
+    /**
+     * Reconstruct an AttachmentFile from storage metadata.
+     *
+     * @param storageMetadata - Metadata containing either 'url' (Binary URL) or 'binaryId'
+     * @returns AttachmentFile instance for accessing the file
+     */
+    reconstructAttachmentFile(storageMetadata: Record<string, unknown>): AttachmentFile;
+}
+/**
+ * Medplum AttachmentFile implementation.
+ *
+ * Provides access to files stored in Medplum Binary resources.
+ */
+export declare class MedplumAttachmentFile implements AttachmentFile {
+    private medplum;
+    private binaryId;
+    constructor(medplum: MedplumClient, binaryUrl: string);
+    /**
+     * Read the entire file into memory as a Buffer.
+     */
+    read(): Promise<Buffer>;
+    /**
+     * Get a readable stream for the file.
+     *
+     * Note: For Medplum, we read the entire file and convert to stream.
+     * For true streaming, you'd need to use Medplum's binary download API.
+     */
+    stream(): Promise<ReadableStream>;
+    /**
+     * Generate a URL for accessing the file.
+     *
+     * For Medplum, this returns the Binary resource URL.
+     * In production, you might want to generate a presigned URL.
+     *
+     * @param expiresIn - Seconds until the URL expires (not used for Medplum)
+     * @returns URL for file access
+     */
+    url(expiresIn?: number): Promise<string>;
+    /**
+     * Delete this file from storage.
+     */
+    delete(): Promise<void>;
+}