@bernierllc/email-sendgrid-plugin 1.3.0 → 1.4.0

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,20 +1,10 @@
 {
   "name": "@bernierllc/email-sendgrid-plugin",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "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",
   "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
-    "test": "jest",
-    "test:run": "jest --watchAll=false",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "lint": "eslint src --ext .ts",
-    "prepublishOnly": "npm run clean && npm run build"
-  },
   "keywords": [
     "sendgrid",
     "email",
@@ -26,10 +16,10 @@
   "author": "Bernier LLC",
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@bernierllc/logger": "1.3.0",
-    "@bernierllc/rate-limiter": "0.2.0",
-    "@bernierllc/retry-policy": "0.3.0",
-    "@sendgrid/mail": "^8.1.3"
+    "@sendgrid/mail": "^8.1.3",
+    "@bernierllc/rate-limiter": "0.2.2",
+    "@bernierllc/logger": "1.3.1",
+    "@bernierllc/retry-policy": "0.3.1"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",
@@ -45,5 +35,13 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "af7e74b3715d56d3a193e1bb6743b337c2b0df6d"
-}
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "test:run": "jest --watchAll=false",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts"
+  }
+}

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>;
+}