vintasend 0.4.3 → 0.4.7

package/README.md

@@ -345,6 +345,7 @@ VintaSend has many backend, adapter, and template renderer implementations. If y
 ##### Adapters
 
 * **[vintasend-nodemailer](https://github.com/vintasoftware/vintasend-nodemailer/)**: Uses nodemailer to send transactional emails to users.
+* **[vintasend-sendgrid](https://github.com/vintasoftware/vintasend-ts-sendgrid/)**: Uses SendGrid's API to send transactional emails with attachment support.
 * **[vintasend-medplum](https://github.com/vintasoftware/vintasend-medplum/)**: Uses Medplum's email API to send notifications in healthcare applications.
 
 ##### Attachment Managers

package/dist/examples/vintasend-medplum-example/.env.example

@@ -0,0 +1,11 @@
+# Medplum Configuration
+MEDPLUM_BASE_URL=https://api.medplum.com
+MEDPLUM_CLIENT_ID=your-client-id-here
+MEDPLUM_CLIENT_SECRET=your-client-secret-here
+
+# Application Configuration
+APP_BASE_URL=https://your-app-url.com
+
+SENDGRID_API_KEY=
+SENDGRID_FROM_EMAIL=vintasend-medplum@vinta.com.br
+SENDGRID_FROM_NAME=VintaSend Medplum Example

package/dist/examples/vintasend-medplum-example/IMPLEMENTATION_PLAN_FILE_ATTACHMENTS.md

@@ -0,0 +1,597 @@
+# Implementation Plan: Task File Attachments with Email Notifications
+
+## Overview
+This plan outlines the implementation of file upload functionality for tasks, with automatic inclusion of those files as email attachments in task assignment notifications. This builds on the existing VintaSend notification system and leverages VintaSend's attachment management capabilities.
+
+---
+
+## Phase 1: Foundation - Medplum File Storage Setup
+
+### Objectives
+- Understand FHIR Binary and Media resources
+- Set up file upload utilities
+- Create helper functions for file management
+
+### Tasks
+
+#### 1.1: Create File Upload Utilities
+**File**: `lib/file-upload.ts`
+
+**Implementation**:
+```typescript
+import { MedplumClient } from '@medplum/core';
+import { Binary, Media, Reference, Task } from '@medplum/fhirtypes';
+
+export interface FileUploadResult {
+  binary: Binary;
+  media: Media;
+}
+
+export async function uploadFileToMedplum(
+  medplum: MedplumClient,
+  file: File | Buffer,
+  filename: string,
+  contentType: string
+): Promise<FileUploadResult> {
+  // Create Binary resource for file storage
+  // Create Media resource as metadata wrapper
+  // Return both references
+}
+
+export async function attachFileToTask(
+  medplum: MedplumClient,
+  task: Task,
+  mediaReference: Reference<Media>
+): Promise<Task> {
+  // Add media reference to task.input array
+  // Update and return task
+}
+
+export async function getTaskAttachments(
+  medplum: MedplumClient,
+  task: Task
+): Promise<Media[]> {
+  // Retrieve all Media resources referenced in task.input
+  // Return array of Media resources
+}
+```
+
+**Documentation in Tutorial**:
+- Add new section: "Advanced: File Attachments for Task Notifications"
+- Subsection: "Step 1: Understanding FHIR File Storage"
+- Explain Binary vs Media resources
+- Document helper functions
+
+#### 1.2: Update Constants
+**File**: `lib/constants.ts`
+
+**Implementation**:
+```typescript
+export const TASK_ATTACHMENT_INPUT_TYPE = {
+  system: 'http://your-app-url.com/task-input-types',
+  code: 'attachment',
+  display: 'File Attachment'
+};
+
+export const MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024; // 10MB
+export const ALLOWED_FILE_TYPES = [
+  'application/pdf',
+  'image/jpeg',
+  'image/png',
+  'application/msword',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+];
+```
+
+**Documentation in Tutorial**:
+- Subsection: "Step 2: Configure File Upload Constraints"
+- Document allowed file types
+- Explain size limits and FHIR standards
+
+---
+
+## Phase 2: Frontend - File Upload UI Component
+
+### Objectives
+- Create React component for file uploads
+- Integrate with task creation/editing forms
+- Handle file validation and preview
+
+### Tasks
+
+#### 2.1: Create File Upload Component
+**File**: `src/components/tasks/TaskFileUpload.tsx`
+
+**Implementation**:
+```typescript
+import { useState, useCallback } from 'react';
+import { useMedplum } from '@medplum/react';
+import { Button, FileInput, Group, Text } from '@mantine/core';
+import { uploadFileToMedplum } from '../../../lib/file-upload';
+
+interface TaskFileUploadProps {
+  onFileUploaded: (mediaId: string) => void;
+}
+
+export function TaskFileUpload({ onFileUploaded }: TaskFileUploadProps) {
+  const medplum = useMedplum();
+  const [uploading, setUploading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleFileChange = useCallback(async (file: File) => {
+    // Validate file type and size
+    // Upload to Medplum
+    // Call onFileUploaded with Media ID
+  }, [medplum, onFileUploaded]);
+
+  return (
+    <div>
+      {/* FileInput with validation */}
+      {/* Upload progress indicator */}
+      {/* Error display */}
+    </div>
+  );
+}
+```
+
+#### 2.2: Create Attachment List Component
+**File**: `src/components/tasks/TaskAttachmentList.tsx`
+
+**Implementation**:
+```typescript
+import { Media } from '@medplum/fhirtypes';
+import { Badge, Group, ActionIcon } from '@mantine/core';
+import { IconDownload, IconX } from '@tabler/icons-react';
+
+interface TaskAttachmentListProps {
+  attachments: Media[];
+  onRemove?: (mediaId: string) => void;
+  readOnly?: boolean;
+}
+
+export function TaskAttachmentList({ 
+  attachments, 
+  onRemove, 
+  readOnly = false 
+}: TaskAttachmentListProps) {
+  // Display list of attachments with download/remove options
+}
+```
+
+#### 2.3: Integrate with Task Form
+**File**: `src/components/tasks/TaskFormWithAttachments.tsx`
+
+**Implementation**:
+- Extend existing task form component
+- Add file upload section
+- Handle attachment state management
+- Submit attachments with task creation/update
+
+**Documentation in Tutorial**:
+- Subsection: "Step 3: Build File Upload UI"
+- Show component implementation
+- Explain integration with task forms
+- Include screenshots/examples
+
+---
+
+## Phase 3: Backend - Email Attachment Integration
+
+### Objectives
+- Retrieve task attachments when sending notifications
+- Convert Media/Binary resources to VintaSend attachments
+- Update email templates to mention attachments
+
+### Tasks
+
+#### 3.1: Update Notification Service with Attachment Mapping
+**File**: `lib/notification-service.ts`
+
+**Implementation**:
+```typescript
+import { Media } from '@medplum/fhirtypes';
+
+async function convertMediaToAttachment(
+  medplum: MedplumClient,
+  media: Media
+): Promise<{
+  filename: string;
+  content: Buffer;
+  contentType: string;
+}> {
+  // Fetch Binary resource from media.content.url
+  // Extract file data
+  // Return in VintaSend attachment format
+}
+
+// Update TaskAssignmentContextGenerator if needed
+```
+
+#### 3.2: Update Task Assignment Email Service
+**File**: `bots/services/emails/send-task-assignment-email.ts`
+
+**Implementation**:
+```typescript
+import { getTaskAttachments } from '../../../lib/file-upload';
+
+export async function sendTaskAssignmentEmail(
+  medplum: MedplumClient,
+  task: Task,
+  taskLinkBaseUrl: string,
+  sendgridConfig: SendGridConfig
+) {
+  // ... existing code ...
+
+  // NEW: Retrieve task attachments
+  const taskAttachments = await getTaskAttachments(medplum, task);
+  
+  // NEW: Convert to VintaSend attachment format
+  const attachments = await Promise.all(
+    taskAttachments.map(media => convertMediaToAttachment(medplum, media))
+  );
+
+  await vintasend.createNotification({
+    userId: referenceString,
+    notificationTypeId: 'taskAssignment',
+    // ... existing params ...
+    attachments, // NEW: Add attachments
+    extraParams: {
+      attachmentCount: attachments.length // For template
+    },
+  });
+}
+```
+
+#### 3.3: Update Email Templates
+**File**: `notification-templates/emails/task-assignment/body.html.pug`
+
+**Implementation**:
+```pug
+doctype html
+html
+  head
+    meta(charset='utf-8')
+    style.
+      body { white-space: pre-line; }
+  body
+    h1 You've been assigned a task
+    
+    p Hello #{firstName},
+    
+    p You have been assigned a new task:
+    
+    p
+      strong Task:
+      |  #{taskTitle}
+    if taskDescription
+      p
+        strong Description:
+        |  #{taskDescription}
+    
+    // NEW: Show attachment info
+    if attachmentCount > 0
+      p
+        strong Attachments:
+        |  #{attachmentCount} file(s) attached
+      p Files are attached to this email for your reference.
+    
+    p
+      a(href=taskLink) View Task Details
+    
+    if taskIsUrgent
+      p
+        strong URGENT - This task requires immediate attention
+    
+    if requesterName
+      p
+        em Task created by: #{requesterName}
+```
+
+**Documentation in Tutorial**:
+- Subsection: "Step 4: Add Attachment Support to Notifications"
+- Explain attachment retrieval
+- Show VintaSend attachment API usage
+- Document template updates
+
+---
+
+## Phase 4: Testing & Validation
+
+### Objectives
+- Test file upload flow end-to-end
+- Validate email attachments
+- Test error scenarios
+
+### Tasks
+
+#### 4.1: Create Test Utilities
+**File**: `lib/file-upload.test.ts`
+
+**Implementation**:
+```typescript
+import { describe, it, expect } from 'vitest';
+import { uploadFileToMedplum, attachFileToTask } from './file-upload';
+
+describe('File Upload Utilities', () => {
+  it('should upload file and create Binary/Media resources', async () => {
+    // Test implementation
+  });
+
+  it('should attach media to task', async () => {
+    // Test implementation
+  });
+
+  it('should reject files over size limit', async () => {
+    // Test implementation
+  });
+
+  it('should reject invalid file types', async () => {
+    // Test implementation
+  });
+});
+```
+
+#### 4.2: Update Bot Tests
+**File**: `bots/services/emails/send-task-assignment-email.test.ts`
+
+**Implementation**:
+- Add test cases for tasks with attachments
+- Mock Media and Binary resources
+- Verify attachment conversion logic
+
+---
+
+## Phase 5: Tutorial Documentation
+
+### Objectives
+- Write comprehensive tutorial section
+- Add code examples
+- Include troubleshooting guide
+
+### Tasks
+
+#### 5.1: Tutorial Structure
+Add to `TUTORIAL_EMAIL_NOTIFICATIONS.md`:
+
+```markdown
+## Advanced: File Attachments for Task Notifications
+
+One of VintaSend's powerful features is built-in attachment management. 
+Files are stored efficiently in Medplum as FHIR Binary resources with 
+automatic deduplication, and can be easily attached to email notifications.
+
+In this section, we'll implement:
+- ✅ File upload UI for tasks
+- ✅ FHIR-compliant file storage (Binary/Media resources)
+- ✅ Automatic email attachment inclusion
+- ✅ File deduplication via checksums
+- ✅ Support for multiple file types
+
+### Why Use VintaSend for Attachments?
+
+**📎 Automatic Deduplication**
+- Files with identical content stored once via checksum
+- Multiple notifications can reference the same file
+- Reduces storage costs
+
+**🔒 FHIR-Native Storage**
+- Files stored as Binary resources
+- Metadata stored as Media resources
+- Full FHIR compliance and access control
+
+**📧 Email Provider Agnostic**
+- Works with SendGrid, AWS SES, or any adapter
+- Attachment handling abstracted from email provider
+- Easy to switch providers without code changes
+
+### Prerequisites
+
+- Completed the basic task assignment tutorial
+- VintaSend and VintaSend-Medplum installed
+- Understanding of FHIR Binary and Media resources
+
+### Step 1: Understanding FHIR File Storage
+[Documentation of Binary/Media resources]
+
+### Step 2: Configure File Upload Constraints
+[Constants and validation rules]
+
+### Step 3: Build File Upload UI
+[React components implementation]
+
+### Step 4: Add Attachment Support to Notifications
+[Backend integration]
+
+### Step 5: Testing File Attachments
+[Test cases and validation]
+
+### Step 6: Advanced Features
+[Preview, deduplication, security]
+
+### How It Works: The Full Flow
+[End-to-end explanation]
+
+### Benefits of This Approach
+✅ **FHIR-Compliant**: All files stored as proper FHIR resources
+✅ **Efficient**: Automatic deduplication saves storage
+✅ **Type-Safe**: TypeScript ensures correct file handling
+✅ **Flexible**: Support multiple file types and sizes
+✅ **Auditable**: Complete file access history via FHIR
+✅ **Provider-Agnostic**: Works with any email service
+```
+
+#### 6.2: Add Troubleshooting Section
+```markdown
+### Troubleshooting File Attachments
+
+**Files not uploading?**
+- Check file size against MAX_ATTACHMENT_SIZE
+- Verify file type is in ALLOWED_FILE_TYPES
+- Ensure user has permission to create Binary resources
+
+**Attachments not appearing in emails?**
+- Verify Media resources are properly linked to task
+- Check that Binary content is accessible
+- Review SendGrid attachment size limits (max 30MB total)
+
+**Deduplication not working?**
+- Ensure MedplumAttachmentManager is configured
+- Verify checksums are being calculated correctly
+- Check Binary resource metadata
+
+**Performance issues?**
+- Consider image optimization before upload
+- Implement lazy loading for attachment lists
+- Use pagination for tasks with many attachments
+```
+
+---
+
+## Timeline Estimation
+
+| Phase | Estimated Time | Priority |
+|-------|---------------|----------|
+| Phase 1: Foundation | 4-6 hours | High |
+| Phase 2: Frontend UI | 6-8 hours | High |
+| Phase 3: Email Integration | 4-6 hours | High |
+| Phase 4: Testing | 4-6 hours | Medium |
+| Phase 5: Documentation | 3-4 hours | High |
+| **Total** | **27-38 hours** | - |
+
+---
+
+## Dependencies & Requirements
+
+### NPM Packages
+- Existing: `vintasend`, `vintasend-medplum`, `vintasend-sendgrid`
+- No new packages required (all functionality built-in)
+
+### Environment Variables
+```bash
+# Existing variables
+SENDGRID_API_KEY=your-key
+SENDGRID_FROM_EMAIL=noreply@example.com
+APP_BASE_URL=https://your-app.com
+
+# Optional: Add file upload limits
+MAX_FILE_SIZE_MB=10
+```
+
+### Medplum Configuration
+- Ensure Binary resource creation permissions
+- Verify Media resource read/write access
+- Configure storage backend if needed (S3, Azure, etc.)
+
+---
+
+## Success Criteria
+
+### Must Have (MVP)
+- ✅ Users can upload files when creating tasks
+- ✅ Files stored as FHIR Binary/Media resources
+- ✅ Email notifications include uploaded files as attachments
+- ✅ Basic file type validation (PDF, images, docs)
+- ✅ File size limit enforcement
+
+### Should Have
+- ✅ File preview for images
+- ✅ Multiple file upload support
+- ✅ Attachment list display in task UI
+- ✅ Remove attachment functionality
+- ✅ Comprehensive error handling
+
+### Nice to Have
+- ✅ Drag-and-drop file upload
+- ✅ PDF preview in browser
+- ✅ File compression before upload
+- ✅ Bulk attachment download
+- ✅ Attachment access audit trail
+
+---
+
+## Risk Assessment & Mitigation
+
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| SendGrid attachment size limit | High | Medium | Validate total size before sending; link large files instead |
+| File storage costs | Medium | High | Implement deduplication; add cleanup policies |
+| Security vulnerabilities | High | Low | Validate file types; scan for malware; enforce access control |
+| Performance degradation | Medium | Medium | Lazy loading; pagination; optimize file sizes |
+| Browser compatibility | Low | Low | Test across browsers; use standard File API |
+
+---
+
+## Future Enhancements
+
+### V2 Features
+1. **Virus scanning integration** - Scan uploaded files for malware
+2. **Image optimization** - Automatically compress/resize images
+3. **Attachment versioning** - Track file changes over time
+4. **Bulk operations** - Upload/download multiple files at once
+5. **Advanced preview** - Preview more file types (Word, Excel, etc.)
+
+### V3 Features
+1. **Cloud storage integration** - Direct upload to S3/Azure/GCS
+2. **OCR for documents** - Extract text from scanned files
+3. **E-signature support** - Sign documents within the app
+4. **Attachment templates** - Pre-populate common file types
+5. **Collaborative editing** - Real-time document collaboration
+
+---
+
+## Rollback Plan
+
+If issues arise during implementation:
+
+1. **Phase 1-2 Issues**: Revert UI changes, keep backend utilities
+2. **Phase 3 Issues**: Disable attachment feature in email service
+3. **Production Issues**: 
+   - Feature flag to disable file uploads
+   - Graceful degradation (email without attachments)
+   - Roll back bot to previous version
+
+**Rollback Commands**:
+```bash
+# Revert bot deployment
+npm run bots:deploy -- --version previous
+
+# Disable file upload UI
+# Set feature flag: ENABLE_TASK_ATTACHMENTS=false
+```
+
+---
+
+## Monitoring & Metrics
+
+### Key Metrics to Track
+- File upload success/failure rate
+- Average file size
+- Email with attachments delivery rate
+- Storage usage over time
+- Attachment download frequency
+
+### Logging Points
+```typescript
+// Log file uploads
+console.log('[FileUpload] File uploaded', { 
+  filename, 
+  size, 
+  contentType, 
+  userId 
+});
+
+// Log email attachments
+console.log('[EmailAttachment] Sending email with attachments', {
+  taskId,
+  attachmentCount,
+  totalSize
+});
+```
+
+---
+
+## Conclusion
+
+This implementation plan provides a comprehensive roadmap for adding file attachment functionality to task assignments with email notification integration. By leveraging VintaSend's built-in attachment management and FHIR's Binary/Media resources, we can build a robust, scalable, and compliant solution.
+
+The phased approach allows for incremental development and testing, with clear documentation at each step to help future developers understand and maintain the system.