vintasend 0.4.0 → 0.4.7

package/dist/examples/vintasend-medplum-example/lib/notification-service.test.ts

@@ -0,0 +1,293 @@
+// @ts-nocheck - MockClient type compatibility with MedplumClient
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { MockClient } from '@medplum/mock';
+import type { Binary, Media } from '@medplum/fhirtypes';
+import { convertMediaToAttachment } from './notification-service';
+
+describe('convertMediaToAttachment', () => {
+  let medplum: MockClient;
+
+  beforeEach(() => {
+    medplum = new MockClient();
+  });
+
+  it('should convert Media resource to VintaSend attachment format', async () => {
+    // Create a binary resource with base64 data
+    const binaryContent = Buffer.from('test file content');
+    const binary = await medplum.createResource<Binary>({
+      resourceType: 'Binary',
+      contentType: 'application/pdf',
+      data: binaryContent.toString('base64'),
+    });
+
+    // Create a media resource
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      content: {
+        contentType: 'application/pdf',
+        url: `Binary/${binary.id}`,
+        title: 'test-document.pdf',
+      },
+    });
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result).toBeDefined();
+    expect(result).not.toBeNull();
+    expect(result?.filename).toBe('test-document.pdf');
+    expect(result?.contentType).toBe('application/pdf');
+    expect(result?.file).toBeInstanceOf(Buffer);
+    expect(result?.file.toString()).toBe('test file content');
+  });
+
+  it('should handle different file types correctly', async () => {
+    const testCases = [
+      {
+        contentType: 'image/jpeg',
+        filename: 'photo.jpg',
+        content: 'jpeg image data',
+      },
+      {
+        contentType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        filename: 'document.docx',
+        content: 'word document data',
+      },
+      {
+        contentType: 'text/plain',
+        filename: 'notes.txt',
+        content: 'plain text content',
+      },
+    ];
+
+    for (const testCase of testCases) {
+      const binary = await medplum.createResource<Binary>({
+        resourceType: 'Binary',
+        contentType: testCase.contentType,
+        data: Buffer.from(testCase.content).toString('base64'),
+      });
+
+      const media = await medplum.createResource<Media>({
+        resourceType: 'Media',
+        status: 'completed',
+        content: {
+          contentType: testCase.contentType,
+          url: `Binary/${binary.id}`,
+          title: testCase.filename,
+        },
+      });
+
+      const result = await convertMediaToAttachment(medplum, media);
+
+      expect(result?.filename).toBe(testCase.filename);
+      expect(result?.contentType).toBe(testCase.contentType);
+      expect(result?.file.toString()).toBe(testCase.content);
+    }
+  });
+
+  it('should use default filename when Media has no title', async () => {
+    const binary = await medplum.createResource<Binary>({
+      resourceType: 'Binary',
+      contentType: 'application/pdf',
+      data: Buffer.from('content').toString('base64'),
+    });
+
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      content: {
+        contentType: 'application/pdf',
+        url: `Binary/${binary.id}`,
+        // No title provided
+      },
+    });
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result?.filename).toBe('attachment');
+  });
+
+  it('should use default contentType when Media has no contentType', async () => {
+    const binary = await medplum.createResource<Binary>({
+      resourceType: 'Binary',
+      contentType: 'application/octet-stream',
+      data: Buffer.from('content').toString('base64'),
+    });
+
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      content: {
+        url: `Binary/${binary.id}`,
+        title: 'file.bin',
+        // No contentType provided
+      },
+    });
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result?.contentType).toBe('application/octet-stream');
+  });
+
+  it('should return null when Binary resource cannot be fetched', async () => {
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      content: {
+        contentType: 'application/pdf',
+        url: 'Binary/nonexistent-binary-id',
+        title: 'test.pdf',
+      },
+    });
+
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result).toBeNull();
+    expect(consoleErrorSpy).toHaveBeenCalled();
+
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('should return null when Media has no content URL', async () => {
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      // No content object
+    });
+
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result).toBeNull();
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '[getBinaryFromMedia] Media resource has no content URL'
+    );
+
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('should return null when Binary has no data field', async () => {
+    const binary = await medplum.createResource<Binary>({
+      resourceType: 'Binary',
+      contentType: 'application/pdf',
+      // No data field
+    });
+
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      content: {
+        contentType: 'application/pdf',
+        url: `Binary/${binary.id}`,
+        title: 'test.pdf',
+      },
+    });
+
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result).toBeNull();
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '[convertMediaToAttachment] Binary resource has no data:',
+      binary.id
+    );
+
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('should handle base64 decoding correctly', async () => {
+    const originalContent = 'Hello, World! This is a test file with special characters: @#$%^&*()';
+    const binary = await medplum.createResource<Binary>({
+      resourceType: 'Binary',
+      contentType: 'text/plain',
+      data: Buffer.from(originalContent).toString('base64'),
+    });
+
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      content: {
+        contentType: 'text/plain',
+        url: `Binary/${binary.id}`,
+        title: 'test.txt',
+      },
+    });
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result?.file.toString()).toBe(originalContent);
+  });
+
+  it('should handle large files', async () => {
+    // Create a 1MB file
+    const largeContent = Buffer.alloc(1024 * 1024, 'a');
+    const binary = await medplum.createResource<Binary>({
+      resourceType: 'Binary',
+      contentType: 'application/octet-stream',
+      data: largeContent.toString('base64'),
+    });
+
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      content: {
+        contentType: 'application/octet-stream',
+        url: `Binary/${binary.id}`,
+        title: 'large-file.bin',
+      },
+    });
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result).toBeDefined();
+    expect(result?.file.length).toBe(1024 * 1024);
+  });
+
+  it('should handle binary content with special characters in filename', async () => {
+    const binary = await medplum.createResource<Binary>({
+      resourceType: 'Binary',
+      contentType: 'application/pdf',
+      data: Buffer.from('content').toString('base64'),
+    });
+
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      content: {
+        contentType: 'application/pdf',
+        url: `Binary/${binary.id}`,
+        title: 'test document (v2) [final].pdf',
+      },
+    });
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result?.filename).toBe('test document (v2) [final].pdf');
+  });
+
+  it('should handle conversion errors gracefully', async () => {
+    // Create media with invalid Binary URL format
+    const media = await medplum.createResource<Media>({
+      resourceType: 'Media',
+      status: 'completed',
+      content: {
+        contentType: 'application/pdf',
+        url: 'InvalidFormat/NoSlash',
+        title: 'test.pdf',
+      },
+    });
+
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const result = await convertMediaToAttachment(medplum, media);
+
+    expect(result).toBeNull();
+    expect(consoleErrorSpy).toHaveBeenCalled();
+
+    consoleErrorSpy.mockRestore();
+  });
+});

package/dist/examples/vintasend-medplum-example/lib/notification-service.ts

@@ -0,0 +1,284 @@
+import { MedplumClient } from '@medplum/core';
+import type { BotEvent } from '@medplum/core';
+import type { ContextGenerator } from 'vintasend';
+import { VintaSendFactory } from 'vintasend';
+import { MedplumSingleton } from './medplum-singleton';
+import { formatPatientNameWithPreferredName } from './patients';
+import * as compiledTemplates from '../compiled-notification-templates.json';
+import {
+  MedplumNotificationBackend,
+  MedplumAttachmentManager,
+  PugInlineEmailTemplateRendererFactory,
+  MedplumLogger,
+} from 'vintasend-medplum';
+import { SendgridNotificationAdapterFactory } from 'vintasend-sendgrid';
+import type { Media } from '@medplum/fhirtypes';
+import { getBinaryFromMedia } from './file-upload';
+
+async function getUserById(medplum: MedplumClient, referenceString: string) {
+  if (!referenceString) {
+    // eslint-disable-next-line no-console
+    console.error('[getUserById] referenceString is null/undefined/empty!');
+    throw new Error('The "id" parameter cannot be null, undefined, or an empty string.');
+  }
+
+  const [resourceType, id] = referenceString.split('/');
+
+  if (!id) {
+    // eslint-disable-next-line no-console
+    console.error('[getUserById] ID extracted from referenceString is empty!');
+    throw new Error('The "id" parameter cannot be null, undefined, or an empty string.');
+  }
+
+  return medplum.readResource(resourceType as 'Patient' | 'Practitioner', id);
+}
+
+/**
+ * Converts a Media resource to VintaSend attachment format.
+ * 
+ * Fetches the Binary resource referenced by the Media and extracts the file data,
+ * then returns it in the format expected by VintaSend for email attachments.
+ * 
+ * @param medplum - The Medplum client instance
+ * @param media - The Media resource containing the file metadata
+ * @returns A NotificationAttachmentUpload object with file, filename, and contentType
+ * 
+ * @example
+ * const attachment = await convertMediaToAttachment(medplum, media);
+ * // { file: Buffer, filename: 'document.pdf', contentType: 'application/pdf' }
+ */
+export async function convertMediaToAttachment(
+  medplum: MedplumClient,
+  media: Media
+): Promise<{
+  file: Buffer;
+  filename: string;
+  contentType: string;
+} | null> {
+  try {
+    // Fetch Binary resource from media.content.url
+    const binary = await getBinaryFromMedia(medplum, media);
+    
+    if (!binary) {
+      console.error('[convertMediaToAttachment] Failed to fetch Binary resource for Media:', media.id);
+      return null;
+    }
+
+    // Extract file data - Binary.data is base64-encoded
+    let file: Buffer;
+    if (binary.data) {
+      // If data is embedded in the Binary resource as base64
+      file = Buffer.from(binary.data, 'base64');
+    } else {
+      // If Binary is stored externally, we need to fetch it via URL
+      // This is handled by getBinaryFromMedia
+      console.error('[convertMediaToAttachment] Binary resource has no data:', binary.id);
+      return null;
+    }
+
+    // Return in VintaSend NotificationAttachmentUpload format
+    return {
+      file,
+      filename: media.content?.title || 'attachment',
+      contentType: media.content?.contentType || 'application/octet-stream',
+    };
+  } catch (error) {
+    console.error('[convertMediaToAttachment] Error converting Media to attachment:', error);
+    return null;
+  }
+}
+
+class TaskAssignmentContextGenerator implements ContextGenerator {
+  async generate({
+    userId,
+    taskTitle,
+    taskDescription,
+    taskIsUrgent,
+    taskLink,
+    requesterName,
+    attachmentCount,
+  }: {
+    userId: string;
+    taskTitle: string;
+    taskDescription: string;
+    taskIsUrgent: boolean;
+    taskLink: string;
+    requesterName: string;
+    attachmentCount?: number;
+  }): Promise<{
+    firstName: string;
+    taskTitle: string;
+    taskDescription: string;
+    taskIsUrgent: boolean;
+    taskLink: string;
+    requesterName: string;
+    attachmentCount: number;
+  }> {
+    const medplum = MedplumSingleton.getInstance();
+    const user = await getUserById(medplum, userId);
+    const firstName = formatPatientNameWithPreferredName(user.name?.[0]) ?? 'Practitioner';
+
+    return {
+      firstName,
+      taskTitle,
+      taskDescription,
+      taskIsUrgent,
+      taskLink,
+      requesterName,
+      attachmentCount: attachmentCount || 0,
+    };
+  }
+}
+
+class TaskDueSoonContextGenerator implements ContextGenerator {
+  async generate({
+    userId,
+    taskTitle,
+    taskDescription,
+    taskIsUrgent,
+    taskLink,
+    dueDate,
+  }: {
+    userId: string;
+    taskTitle: string;
+    taskDescription: string;
+    taskIsUrgent: boolean;
+    taskLink: string;
+    dueDate: string;
+  }): Promise<{
+    firstName: string;
+    taskTitle: string;
+    taskDescription: string;
+    taskIsUrgent: boolean;
+    taskLink: string;
+    dueDate: string;
+  }> {
+    const medplum = MedplumSingleton.getInstance();
+    const user = await getUserById(medplum, userId);
+    const firstName = formatPatientNameWithPreferredName(user.name?.[0]) ?? 'Practitioner';
+
+    return {
+      firstName,
+      taskTitle,
+      taskDescription,
+      taskIsUrgent,
+      taskLink,
+      dueDate,
+    };
+  }
+}
+
+class InboxMessageContextGenerator implements ContextGenerator {
+  async generate({
+    userId,
+    sender,
+    messageContent,
+    messageTopic,
+  }: {
+    userId: string;
+    sender: string;
+    messageContent: string;
+    messageTopic: string;
+  }): Promise<{
+    firstName: string;
+    senderName: string;
+    senderFirstName: string;
+    messageContent: string;
+    messageTopic: string;
+  }> {
+    const medplum = MedplumSingleton.getInstance();
+    const user = await getUserById(medplum, userId);
+    const firstName = formatPatientNameWithPreferredName(user.name?.[0]) ?? 'Practitioner';
+
+    // Extract sender name from reference
+    let senderName = 'Unknown';
+    let senderFirstName = 'Unknown';
+    try {
+      const [senderResourceType, senderId] = sender.split('/');
+      if (senderId) {
+        const senderResource = await medplum.readResource(senderResourceType as 'Patient' | 'Practitioner', senderId);
+        senderName = formatPatientNameWithPreferredName(senderResource.name?.[0]) ?? 'Unknown';
+        senderFirstName = senderResource.name?.[0]?.given?.[0] || 'Unknown';
+      }
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error('[InboxMessageContextGenerator] Error fetching sender:', error);
+    }
+
+    return {
+      firstName,
+      senderName,
+      senderFirstName,
+      messageContent,
+      messageTopic,
+    };
+  }
+}
+
+// context map for generating the context of each notification
+export const contextGeneratorsMap = {
+  taskAssignment: new TaskAssignmentContextGenerator(),
+  taskDueSoon: new TaskDueSoonContextGenerator(),
+  inboxMessage: new InboxMessageContextGenerator(),
+} as const;
+
+export type NotificationTypeConfig = {
+  ContextMap: typeof contextGeneratorsMap;
+  NotificationIdType: string;
+  UserIdType: string;
+};
+
+export type SendGridConfig = {
+  SENDGRID_API_KEY: string;
+  SENDGRID_FROM_EMAIL: string;
+  SENDGRID_FROM_NAME: string;
+};
+
+/**
+ * Helper function to build SendGridConfig from bot event secrets
+ * Reduces duplication across bot handlers
+ * Throws if required secrets (API key or from email) are missing
+ */
+export function buildSendGridConfig(event: BotEvent): SendGridConfig {
+  const apiKey = event.secrets.SENDGRID_API_KEY?.valueString;
+  const fromEmail = event.secrets.SENDGRID_FROM_EMAIL?.valueString;
+  const fromName = event.secrets.SENDGRID_FROM_NAME?.valueString || 'Medplum Notifications';
+
+  if (!apiKey) {
+    // eslint-disable-next-line no-console
+    console.error('[buildSendGridConfig] SENDGRID_API_KEY secret is missing or empty');
+    throw new Error('SENDGRID_API_KEY must be configured in bot secrets');
+  }
+
+  if (!fromEmail) {
+    // eslint-disable-next-line no-console
+    console.error('[buildSendGridConfig] SENDGRID_FROM_EMAIL secret is missing or empty');
+    throw new Error('SENDGRID_FROM_EMAIL must be configured in bot secrets');
+  }
+
+  return {
+    SENDGRID_API_KEY: apiKey,
+    SENDGRID_FROM_EMAIL: fromEmail,
+    SENDGRID_FROM_NAME: fromName,
+  };
+}
+
+export function getNotificationService(medplum: MedplumClient, sendgridConfig: SendGridConfig) {
+  const backend = new MedplumNotificationBackend<NotificationTypeConfig>(medplum);
+  const templateRenderer = new PugInlineEmailTemplateRendererFactory<NotificationTypeConfig>().create(
+    compiledTemplates
+  );
+  const adapter = new SendgridNotificationAdapterFactory<NotificationTypeConfig>().create(templateRenderer, false, {
+    apiKey: sendgridConfig.SENDGRID_API_KEY || '',
+    fromEmail: sendgridConfig.SENDGRID_FROM_EMAIL || '',
+    fromName: sendgridConfig.SENDGRID_FROM_NAME,
+  });
+  return new VintaSendFactory<NotificationTypeConfig>().create(
+    [adapter],
+    backend,
+    new MedplumLogger(),
+    contextGeneratorsMap,
+    undefined,
+    new MedplumAttachmentManager(medplum)
+  );
+}

package/dist/examples/vintasend-medplum-example/lib/patients.ts

@@ -0,0 +1,20 @@
+import { formatHumanName } from '@medplum/core';
+import { HumanName } from '@medplum/fhirtypes';
+import { PREFERRED_NAME_EXTENSION_URL } from './extensions';
+
+export function getPatientPreferredName(patientName: HumanName | undefined): string | undefined {
+  if (!patientName) return;
+  const preferredName = patientName?.extension?.find(
+    (extension) => extension.url === PREFERRED_NAME_EXTENSION_URL
+  )?.valueString;
+  return preferredName;
+}
+
+export function formatPatientNameWithPreferredName(patientName: HumanName | undefined) {
+  const preferredName = getPatientPreferredName(patientName);
+  if (!preferredName) return formatHumanName(patientName);
+  const given = patientName?.given?.join(' ');
+  const familyName = patientName?.family;
+
+  return `${given} (${preferredName}) ${familyName}`;
+}

package/dist/examples/vintasend-medplum-example/notification-templates/emails/task-assignment/body.html.pug

@@ -0,0 +1,37 @@
+doctype html
+html
+  head
+    meta(charset='utf-8')
+    style.
+      body {
+        white-space: pre-line;
+      }
+  body
+    h1 Task Assigned
+
+    p Hello #{firstName},
+
+    p You have been assigned a new task by #{requesterName}.
+
+    p
+      strong Task:
+      |  #{taskTitle}
+    if taskDescription
+      p
+        strong Description:
+        |  #{taskDescription}
+    
+    if attachmentCount > 0
+      p
+        strong Attachments:
+        |  #{attachmentCount} file(s) attached
+      p Files are attached to this email for your reference.
+    
+    if taskIsUrgent
+      p
+        strong URGENT
+
+    p
+      a(href=taskLink) View Task
+
+    p Please review the task details and take appropriate action.

package/dist/examples/vintasend-medplum-example/notification-templates/emails/task-assignment/subject.txt.pug

@@ -0,0 +1,4 @@
+if taskIsUrgent
+  | [URGENT] Task assigned to you: #{taskTitle}
+else
+  | Task assigned to you: #{taskTitle}

package/dist/examples/vintasend-medplum-example/notification-templates/emails/task-due-soon/body.html.pug

@@ -0,0 +1,34 @@
+doctype html
+html
+  head
+    meta(charset='utf-8')
+    style.
+      body {
+        white-space: pre-line;
+      }
+  body
+    h1 Task Due Reminder
+
+    p Hello #{firstName},
+
+    p This is a reminder that you have a task that is due in approximately 24 hours.
+
+    p
+      strong Task:
+      |  #{taskTitle}
+    if taskDescription
+      p
+        strong Description:
+        |  #{taskDescription}
+    p
+      strong Due Date:
+      |  #{dueDate}
+    if taskIsUrgent
+      p
+        strong URGENT
+
+    p
+      a(href=taskLink) View Task
+
+    p Please make sure to complete this task before the due date.
+

package/dist/examples/vintasend-medplum-example/notification-templates/emails/task-due-soon/subject.txt.pug

@@ -0,0 +1,4 @@
+if taskIsUrgent
+  | [URGENT] Task due soon: #{taskTitle}
+else
+  | Reminder: Task due soon - #{taskTitle}