@bernierllc/email-sendgrid-plugin 1.1.2 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,49 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# 1.3.0 (2025-12-25)
+
+
+### Bug Fixes
+
+* **ci:** add lerna version step before publish ([3d20300](https://github.com/bernierllc/tools/commit/3d203002143bf353fffafe4f8a78a99009567347))
+* **ci:** correct jest testEnvironment paths for CI ([c47144c](https://github.com/bernierllc/tools/commit/c47144c3d78aec2be1e1454066c235c2227823fd))
+* **ci:** fix release workflow + convert internal deps to workspace:* ([01c078b](https://github.com/bernierllc/tools/commit/01c078b49d6025f7eef750f79207a1c71c8d85dc))
+* **jest:** resolve Node.js v25+ localStorage SecurityError ([8ffc512](https://github.com/bernierllc/tools/commit/8ffc512805519bc5ba523bdbcd1c457e84998c9e))
+* update neverhub-adapter deps to workspace:* and publish 0.1.2 ([f0e3d04](https://github.com/bernierllc/tools/commit/f0e3d04d8d4f094e3bb899ddf81e93243d16e2c2))
+
+
+### Features
+
+* **email-sendgrid-plugin:** Implement SendGrid template management and sender verification plugin ([5368de9](https://github.com/bernierllc/tools/commit/5368de95d03888e5561fa0d01281f603b3f4a6f1))
+* **email:** deprecate email-sendgrid-plugin and document consolidation status ([724e37c](https://github.com/bernierllc/tools/commit/724e37ca80dac6ddea112fdc1129fb78018c1c82))
+
+
+
+
+
+# 1.2.0 (2025-12-25)
+
+
+### Bug Fixes
+
+* **ci:** correct jest testEnvironment paths for CI ([c47144c](https://github.com/bernierllc/tools/commit/c47144c3d78aec2be1e1454066c235c2227823fd))
+* **ci:** fix release workflow + convert internal deps to workspace:* ([01c078b](https://github.com/bernierllc/tools/commit/01c078b49d6025f7eef750f79207a1c71c8d85dc))
+* **jest:** resolve Node.js v25+ localStorage SecurityError ([8ffc512](https://github.com/bernierllc/tools/commit/8ffc512805519bc5ba523bdbcd1c457e84998c9e))
+* update neverhub-adapter deps to workspace:* and publish 0.1.2 ([f0e3d04](https://github.com/bernierllc/tools/commit/f0e3d04d8d4f094e3bb899ddf81e93243d16e2c2))
+
+
+### Features
+
+* **email-sendgrid-plugin:** Implement SendGrid template management and sender verification plugin ([5368de9](https://github.com/bernierllc/tools/commit/5368de95d03888e5561fa0d01281f603b3f4a6f1))
+* **email:** deprecate email-sendgrid-plugin and document consolidation status ([724e37c](https://github.com/bernierllc/tools/commit/724e37ca80dac6ddea112fdc1129fb78018c1c82))
+
+
+
+
+
 # @bernierllc/email-sendgrid-plugin
 
 ## 1.1.2

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',
+      });
+    });
+  });
+});

package/dist/converters/sender-converter.d.ts

@@ -1,6 +1,30 @@
-import { VerifiedSender, SendGridVerifiedSenderData } from '../types/sendgrid-types';
+import { VerifiedSender, SendGridVerifiedSenderData, EmailAttachment, SendGridAttachment, SendGridMailPayload } from '../types/sendgrid-types';
 export declare class SenderConverter {
     convertToVerifiedSender(sendgridData: SendGridVerifiedSenderData): VerifiedSender;
+    /**
+     * Convert a single EmailAttachment to SendGrid's attachment format.
+     */
+    convertAttachment(attachment: EmailAttachment): SendGridAttachment;
+    /**
+     * Convert an array of EmailAttachment objects to SendGrid format.
+     * Returns undefined if the array is empty or undefined (so the field
+     * can be omitted from the payload).
+     */
+    convertAttachments(attachments?: EmailAttachment[]): SendGridAttachment[] | undefined;
+    /**
+     * Convert custom headers to the format expected by SendGrid's v3 mail send API.
+     * Filters out reserved SendGrid headers that must not be overridden.
+     * Returns undefined if no valid headers remain.
+     */
+    convertHeaders(headers?: Record<string, string>): Record<string, string> | undefined;
+    /**
+     * Build the attachment and header portion of a SendGrid mail payload
+     * from canonical email data.
+     */
+    buildMailPayload(options: {
+        attachments?: EmailAttachment[];
+        headers?: Record<string, string>;
+    }): SendGridMailPayload;
     extractDomain(email: string): string;
     isDomainMatch(domain1: string, domain2: string): boolean;
 }

package/dist/converters/sender-converter.js

@@ -22,6 +22,80 @@ class SenderConverter {
             lastVerifiedAt: sendgridData.verified ? new Date() : undefined
         };
     }
+    /**
+     * Convert a single EmailAttachment to SendGrid's attachment format.
+     */
+    convertAttachment(attachment) {
+        const sgAttachment = {
+            content: attachment.content,
+            filename: attachment.filename,
+        };
+        if (attachment.contentType) {
+            sgAttachment.type = attachment.contentType;
+        }
+        if (attachment.disposition) {
+            sgAttachment.disposition = attachment.disposition;
+        }
+        return sgAttachment;
+    }
+    /**
+     * Convert an array of EmailAttachment objects to SendGrid format.
+     * Returns undefined if the array is empty or undefined (so the field
+     * can be omitted from the payload).
+     */
+    convertAttachments(attachments) {
+        if (!attachments || attachments.length === 0) {
+            return undefined;
+        }
+        return attachments.map(a => this.convertAttachment(a));
+    }
+    /**
+     * Convert custom headers to the format expected by SendGrid's v3 mail send API.
+     * Filters out reserved SendGrid headers that must not be overridden.
+     * Returns undefined if no valid headers remain.
+     */
+    convertHeaders(headers) {
+        if (!headers || Object.keys(headers).length === 0) {
+            return undefined;
+        }
+        const RESERVED_HEADERS = new Set([
+            'x-sg-id',
+            'x-sg-eid',
+            'received',
+            'dkim-signature',
+            'content-type',
+            'content-transfer-encoding',
+            'to',
+            'from',
+            'subject',
+            'reply-to',
+            'cc',
+            'bcc',
+        ]);
+        const filtered = {};
+        for (const [key, value] of Object.entries(headers)) {
+            if (!RESERVED_HEADERS.has(key.toLowerCase())) {
+                filtered[key] = value;
+            }
+        }
+        return Object.keys(filtered).length > 0 ? filtered : undefined;
+    }
+    /**
+     * Build the attachment and header portion of a SendGrid mail payload
+     * from canonical email data.
+     */
+    buildMailPayload(options) {
+        const payload = {};
+        const attachments = this.convertAttachments(options.attachments);
+        if (attachments) {
+            payload.attachments = attachments;
+        }
+        const headers = this.convertHeaders(options.headers);
+        if (headers) {
+            payload.headers = headers;
+        }
+        return payload;
+    }
     extractDomain(email) {
         return email.split('@')[1]?.toLowerCase() || '';
     }

package/dist/index.d.ts

@@ -11,4 +11,4 @@ export { SenderConverter } from './converters/sender-converter';
 export { SendGridApiError, TemplateNotFoundError, UnauthorizedTemplateAccessError, TemplateConflictError, RateLimitError } from './api/errors';
 export type { SendGridPluginConfig, ApiRequestOptions, ApiResponse } from './types/config-types';
 export type { PluginConfig, ProviderCapability, Template, ProviderTemplate, TemplateVersion, SyncResult, ValidationResult, DateRange, TemplateAnalytics, FeatureConfig } from './types/plugin-types';
-export type { VerifiedSender, SenderValidationResult, SendGridTemplateData, SendGridTemplateVersion, SendGridVerifiedSenderData } from './types/sendgrid-types';
+export type { VerifiedSender, SenderValidationResult, SendGridTemplateData, SendGridTemplateVersion, SendGridVerifiedSenderData, EmailAttachment, SendGridAttachment, SendGridMailPayload } from './types/sendgrid-types';

package/dist/types/sendgrid-types.d.ts

@@ -54,3 +54,29 @@ export interface SendGridApiError extends Error {
     statusCode?: number;
     response?: unknown;
 }
+/**
+ * Email attachment in the canonical format (matches @bernierllc/email-sender EmailAttachment).
+ */
+export interface EmailAttachment {
+    filename: string;
+    content: string;
+    contentType?: string;
+    disposition?: 'attachment' | 'inline';
+}
+/**
+ * SendGrid's attachment format for the v3 mail send API.
+ */
+export interface SendGridAttachment {
+    content: string;
+    filename: string;
+    type?: string;
+    disposition?: string;
+}
+/**
+ * SendGrid mail personalization/message payload fields related to
+ * attachments and custom headers.
+ */
+export interface SendGridMailPayload {
+    attachments?: SendGridAttachment[];
+    headers?: Record<string, string>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bernierllc/email-sendgrid-plugin",
-  "version": "1.1.2",
+  "version": "1.3.1",
   "deprecated": "This package is deprecated. SendGrid functionality has been merged into @bernierllc/email-sender@3.0.0+. See https://github.com/BernierLLC/tools/blob/main/packages/core/email-sender/MIGRATION.md for migration guide.",
   "description": "SendGrid-specific template management, sender verification, and advanced features plugin for email template service",
   "main": "dist/index.js",
@@ -17,9 +17,9 @@
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
     "@sendgrid/mail": "^8.1.3",
-    "@bernierllc/logger": "1.1.0",
-    "@bernierllc/retry-policy": "0.1.6",
-    "@bernierllc/rate-limiter": "0.1.7"
+    "@bernierllc/logger": "1.3.0",
+    "@bernierllc/rate-limiter": "0.2.1",
+    "@bernierllc/retry-policy": "0.3.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",

package/src/converters/sender-converter.ts

@@ -6,7 +6,13 @@ The client may use and modify this code *only within the scope of the project it
 Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
 */
 
-import { VerifiedSender, SendGridVerifiedSenderData } from '../types/sendgrid-types';
+import {
+  VerifiedSender,
+  SendGridVerifiedSenderData,
+  EmailAttachment,
+  SendGridAttachment,
+  SendGridMailPayload
+} from '../types/sendgrid-types';
 
 export class SenderConverter {
   convertToVerifiedSender(sendgridData: SendGridVerifiedSenderData): VerifiedSender {
@@ -24,6 +30,97 @@ export class SenderConverter {
     };
   }
 
+  /**
+   * Convert a single EmailAttachment to SendGrid's attachment format.
+   */
+  convertAttachment(attachment: EmailAttachment): SendGridAttachment {
+    const sgAttachment: SendGridAttachment = {
+      content: attachment.content,
+      filename: attachment.filename,
+    };
+
+    if (attachment.contentType) {
+      sgAttachment.type = attachment.contentType;
+    }
+
+    if (attachment.disposition) {
+      sgAttachment.disposition = attachment.disposition;
+    }
+
+    return sgAttachment;
+  }
+
+  /**
+   * Convert an array of EmailAttachment objects to SendGrid format.
+   * Returns undefined if the array is empty or undefined (so the field
+   * can be omitted from the payload).
+   */
+  convertAttachments(attachments?: EmailAttachment[]): SendGridAttachment[] | undefined {
+    if (!attachments || attachments.length === 0) {
+      return undefined;
+    }
+
+    return attachments.map(a => this.convertAttachment(a));
+  }
+
+  /**
+   * Convert custom headers to the format expected by SendGrid's v3 mail send API.
+   * Filters out reserved SendGrid headers that must not be overridden.
+   * Returns undefined if no valid headers remain.
+   */
+  convertHeaders(headers?: Record<string, string>): Record<string, string> | undefined {
+    if (!headers || Object.keys(headers).length === 0) {
+      return undefined;
+    }
+
+    const RESERVED_HEADERS = new Set([
+      'x-sg-id',
+      'x-sg-eid',
+      'received',
+      'dkim-signature',
+      'content-type',
+      'content-transfer-encoding',
+      'to',
+      'from',
+      'subject',
+      'reply-to',
+      'cc',
+      'bcc',
+    ]);
+
+    const filtered: Record<string, string> = {};
+    for (const [key, value] of Object.entries(headers)) {
+      if (!RESERVED_HEADERS.has(key.toLowerCase())) {
+        filtered[key] = value;
+      }
+    }
+
+    return Object.keys(filtered).length > 0 ? filtered : undefined;
+  }
+
+  /**
+   * Build the attachment and header portion of a SendGrid mail payload
+   * from canonical email data.
+   */
+  buildMailPayload(options: {
+    attachments?: EmailAttachment[];
+    headers?: Record<string, string>;
+  }): SendGridMailPayload {
+    const payload: SendGridMailPayload = {};
+
+    const attachments = this.convertAttachments(options.attachments);
+    if (attachments) {
+      payload.attachments = attachments;
+    }
+
+    const headers = this.convertHeaders(options.headers);
+    if (headers) {
+      payload.headers = headers;
+    }
+
+    return payload;
+  }
+
   extractDomain(email: string): string {
     return email.split('@')[1]?.toLowerCase() || '';
   }

package/src/index.ts

@@ -54,5 +54,8 @@ export type {
   SenderValidationResult,
   SendGridTemplateData,
   SendGridTemplateVersion,
-  SendGridVerifiedSenderData
+  SendGridVerifiedSenderData,
+  EmailAttachment,
+  SendGridAttachment,
+  SendGridMailPayload
 } from './types/sendgrid-types';

package/src/types/sendgrid-types.ts

@@ -67,3 +67,32 @@ export interface SendGridApiError extends Error {
   statusCode?: number;
   response?: unknown;
 }
+
+/**
+ * Email attachment in the canonical format (matches @bernierllc/email-sender EmailAttachment).
+ */
+export interface EmailAttachment {
+  filename: string;
+  content: string; // Base64 encoded
+  contentType?: string;
+  disposition?: 'attachment' | 'inline';
+}
+
+/**
+ * SendGrid's attachment format for the v3 mail send API.
+ */
+export interface SendGridAttachment {
+  content: string;
+  filename: string;
+  type?: string;
+  disposition?: string;
+}
+
+/**
+ * SendGrid mail personalization/message payload fields related to
+ * attachments and custom headers.
+ */
+export interface SendGridMailPayload {
+  attachments?: SendGridAttachment[];
+  headers?: Record<string, string>;
+}