@bernierllc/email-sendgrid-plugin 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.4.0](https://github.com/bernierllc/tools/compare/@bernierllc/email-sendgrid-plugin@1.3.0...@bernierllc/email-sendgrid-plugin@1.4.0) (2026-03-03)
+
+
+### Bug Fixes
+
+* **email-sendgrid-plugin:** use workspace:* for internal dependencies ([5846df1](https://github.com/bernierllc/tools/commit/5846df165069987cac4f61dc44c2e09e403e8b66))
+
+
+### Features
+
+* **email:** add multi-provider capability matrix with smart routing ([#29](https://github.com/bernierllc/tools/issues/29)) ([b9c38c0](https://github.com/bernierllc/tools/commit/b9c38c0a93985dc1675681657cc2ec3a209a9435))
+
+
+
+
+
 # 1.3.0 (2025-12-25)
 
 

package/__tests__/converters/attachment-header-mapping.test.ts

@@ -0,0 +1,337 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { SenderConverter } from '../../src/converters/sender-converter';
+import { EmailAttachment } from '../../src/types/sendgrid-types';
+
+describe('SenderConverter - Attachment & Header Mapping', () => {
+  let converter: SenderConverter;
+
+  beforeEach(() => {
+    converter = new SenderConverter();
+  });
+
+  // ── convertAttachment ─────────────────────────────────────────────
+
+  describe('convertAttachment', () => {
+    it('should convert a basic attachment with only required fields', () => {
+      const attachment: EmailAttachment = {
+        filename: 'report.pdf',
+        content: 'dGVzdCBjb250ZW50', // base64 for "test content"
+      };
+
+      const result = converter.convertAttachment(attachment);
+
+      expect(result).toEqual({
+        content: 'dGVzdCBjb250ZW50',
+        filename: 'report.pdf',
+      });
+      expect(result.type).toBeUndefined();
+      expect(result.disposition).toBeUndefined();
+    });
+
+    it('should map contentType to SendGrid type field', () => {
+      const attachment: EmailAttachment = {
+        filename: 'report.pdf',
+        content: 'dGVzdCBjb250ZW50',
+        contentType: 'application/pdf',
+      };
+
+      const result = converter.convertAttachment(attachment);
+
+      expect(result.type).toBe('application/pdf');
+    });
+
+    it('should map disposition field', () => {
+      const attachment: EmailAttachment = {
+        filename: 'logo.png',
+        content: 'aW1hZ2VkYXRh',
+        contentType: 'image/png',
+        disposition: 'inline',
+      };
+
+      const result = converter.convertAttachment(attachment);
+
+      expect(result.disposition).toBe('inline');
+    });
+
+    it('should handle calendar attachment (text/calendar)', () => {
+      const icsContent = Buffer.from(
+        'BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VEVENT\nSUMMARY:Meeting\nEND:VEVENT\nEND:VCALENDAR'
+      ).toString('base64');
+
+      const attachment: EmailAttachment = {
+        filename: 'invite.ics',
+        content: icsContent,
+        contentType: 'text/calendar',
+        disposition: 'attachment',
+      };
+
+      const result = converter.convertAttachment(attachment);
+
+      expect(result).toEqual({
+        content: icsContent,
+        filename: 'invite.ics',
+        type: 'text/calendar',
+        disposition: 'attachment',
+      });
+    });
+
+    it('should preserve base64 content exactly as provided', () => {
+      const longContent = Buffer.from('A'.repeat(1000)).toString('base64');
+      const attachment: EmailAttachment = {
+        filename: 'large.bin',
+        content: longContent,
+      };
+
+      const result = converter.convertAttachment(attachment);
+
+      expect(result.content).toBe(longContent);
+    });
+  });
+
+  // ── convertAttachments ────────────────────────────────────────────
+
+  describe('convertAttachments', () => {
+    it('should return undefined for undefined input', () => {
+      expect(converter.convertAttachments(undefined)).toBeUndefined();
+    });
+
+    it('should return undefined for empty array', () => {
+      expect(converter.convertAttachments([])).toBeUndefined();
+    });
+
+    it('should convert a single attachment', () => {
+      const attachments: EmailAttachment[] = [
+        { filename: 'file.txt', content: 'YWJj', contentType: 'text/plain' },
+      ];
+
+      const result = converter.convertAttachments(attachments);
+
+      expect(result).toHaveLength(1);
+      expect(result![0]).toEqual({
+        content: 'YWJj',
+        filename: 'file.txt',
+        type: 'text/plain',
+      });
+    });
+
+    it('should convert multiple attachments preserving order', () => {
+      const attachments: EmailAttachment[] = [
+        { filename: 'first.pdf', content: 'YWJJ', contentType: 'application/pdf' },
+        { filename: 'second.png', content: 'aW1n', contentType: 'image/png', disposition: 'inline' },
+        { filename: 'third.ics', content: 'Y2Fs', contentType: 'text/calendar' },
+      ];
+
+      const result = converter.convertAttachments(attachments);
+
+      expect(result).toHaveLength(3);
+      expect(result![0].filename).toBe('first.pdf');
+      expect(result![1].filename).toBe('second.png');
+      expect(result![1].disposition).toBe('inline');
+      expect(result![2].filename).toBe('third.ics');
+      expect(result![2].type).toBe('text/calendar');
+    });
+
+    it('should handle mix of fully-specified and minimal attachments', () => {
+      const attachments: EmailAttachment[] = [
+        {
+          filename: 'full.pdf',
+          content: 'YWJJ',
+          contentType: 'application/pdf',
+          disposition: 'attachment',
+        },
+        { filename: 'minimal.bin', content: 'YWJJ' },
+      ];
+
+      const result = converter.convertAttachments(attachments);
+
+      expect(result).toHaveLength(2);
+      expect(result![0].type).toBe('application/pdf');
+      expect(result![0].disposition).toBe('attachment');
+      expect(result![1].type).toBeUndefined();
+      expect(result![1].disposition).toBeUndefined();
+    });
+  });
+
+  // ── convertHeaders ────────────────────────────────────────────────
+
+  describe('convertHeaders', () => {
+    it('should return undefined for undefined input', () => {
+      expect(converter.convertHeaders(undefined)).toBeUndefined();
+    });
+
+    it('should return undefined for empty object', () => {
+      expect(converter.convertHeaders({})).toBeUndefined();
+    });
+
+    it('should pass through custom headers', () => {
+      const headers = {
+        'X-Custom-Header': 'custom-value',
+        'X-Campaign-Id': 'camp-123',
+      };
+
+      const result = converter.convertHeaders(headers);
+
+      expect(result).toEqual({
+        'X-Custom-Header': 'custom-value',
+        'X-Campaign-Id': 'camp-123',
+      });
+    });
+
+    it('should filter out reserved SendGrid headers (case-insensitive)', () => {
+      const headers = {
+        'X-Custom': 'keep-me',
+        'X-SG-ID': 'should-be-removed',
+        'x-sg-eid': 'should-be-removed',
+        'Content-Type': 'should-be-removed',
+        'DKIM-Signature': 'should-be-removed',
+        'To': 'should-be-removed',
+        'From': 'should-be-removed',
+        'Subject': 'should-be-removed',
+        'Reply-To': 'should-be-removed',
+        'CC': 'should-be-removed',
+        'BCC': 'should-be-removed',
+        'Received': 'should-be-removed',
+        'Content-Transfer-Encoding': 'should-be-removed',
+      };
+
+      const result = converter.convertHeaders(headers);
+
+      expect(result).toEqual({
+        'X-Custom': 'keep-me',
+      });
+    });
+
+    it('should return undefined if all headers are reserved', () => {
+      const headers = {
+        'Content-Type': 'text/html',
+        'From': 'test@example.com',
+      };
+
+      expect(converter.convertHeaders(headers)).toBeUndefined();
+    });
+
+    it('should preserve header value strings exactly', () => {
+      const headers = {
+        'X-Mailer': 'BernierLLC Email Service v2.0',
+        'X-Priority': '1',
+        'List-Unsubscribe': '<mailto:unsub@example.com>, <https://example.com/unsub>',
+      };
+
+      const result = converter.convertHeaders(headers);
+
+      expect(result).toEqual(headers);
+    });
+  });
+
+  // ── buildMailPayload ──────────────────────────────────────────────
+
+  describe('buildMailPayload', () => {
+    it('should return empty object when no attachments or headers', () => {
+      const payload = converter.buildMailPayload({});
+
+      expect(payload).toEqual({});
+      expect(payload.attachments).toBeUndefined();
+      expect(payload.headers).toBeUndefined();
+    });
+
+    it('should include only attachments when no headers', () => {
+      const payload = converter.buildMailPayload({
+        attachments: [
+          { filename: 'test.pdf', content: 'YWJJ', contentType: 'application/pdf' },
+        ],
+      });
+
+      expect(payload.attachments).toHaveLength(1);
+      expect(payload.attachments![0].filename).toBe('test.pdf');
+      expect(payload.headers).toBeUndefined();
+    });
+
+    it('should include only headers when no attachments', () => {
+      const payload = converter.buildMailPayload({
+        headers: { 'X-Custom': 'value' },
+      });
+
+      expect(payload.headers).toEqual({ 'X-Custom': 'value' });
+      expect(payload.attachments).toBeUndefined();
+    });
+
+    it('should include both attachments and headers', () => {
+      const payload = converter.buildMailPayload({
+        attachments: [
+          { filename: 'report.pdf', content: 'YWJJ', contentType: 'application/pdf' },
+          { filename: 'invite.ics', content: 'Y2Fs', contentType: 'text/calendar' },
+        ],
+        headers: {
+          'X-Campaign': 'launch-2025',
+          'X-Priority': '1',
+        },
+      });
+
+      expect(payload.attachments).toHaveLength(2);
+      expect(payload.headers).toEqual({
+        'X-Campaign': 'launch-2025',
+        'X-Priority': '1',
+      });
+    });
+
+    it('should omit attachments field when array is empty', () => {
+      const payload = converter.buildMailPayload({
+        attachments: [],
+        headers: { 'X-Test': 'yes' },
+      });
+
+      expect(payload.attachments).toBeUndefined();
+      expect(payload.headers).toEqual({ 'X-Test': 'yes' });
+    });
+
+    it('should omit headers field when all are reserved', () => {
+      const payload = converter.buildMailPayload({
+        attachments: [{ filename: 'a.txt', content: 'YQ==' }],
+        headers: { 'Content-Type': 'text/plain' },
+      });
+
+      expect(payload.attachments).toHaveLength(1);
+      expect(payload.headers).toBeUndefined();
+    });
+
+    it('should handle calendar invite with custom headers (real-world scenario)', () => {
+      const icsContent = Buffer.from(
+        'BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//BernierLLC//EN\nBEGIN:VEVENT\nDTSTART:20250301T100000Z\nDTEND:20250301T110000Z\nSUMMARY:Project Kickoff\nEND:VEVENT\nEND:VCALENDAR'
+      ).toString('base64');
+
+      const payload = converter.buildMailPayload({
+        attachments: [
+          {
+            filename: 'invite.ics',
+            content: icsContent,
+            contentType: 'text/calendar',
+            disposition: 'attachment',
+          },
+        ],
+        headers: {
+          'X-Campaign-Id': 'kickoff-2025',
+          'X-Mailer': 'BernierLLC Email Service',
+        },
+      });
+
+      expect(payload.attachments).toHaveLength(1);
+      expect(payload.attachments![0]).toEqual({
+        content: icsContent,
+        filename: 'invite.ics',
+        type: 'text/calendar',
+        disposition: 'attachment',
+      });
+      expect(payload.headers).toEqual({
+        'X-Campaign-Id': 'kickoff-2025',
+        'X-Mailer': 'BernierLLC Email Service',
+      });
+    });
+  });
+});