@bernierllc/email 1.0.0

package/packages/core/src/providers/sendgrid.ts

@@ -0,0 +1,368 @@
+/*
+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.
+*/
+
+/**
+ * SendGrid email provider implementation
+ */
+
+import { EmailProvider, EmailMessage, SendResult, DeliveryStatus, WebhookEvent } from './base';
+
+export interface SendGridConfig {
+  apiKey: string;
+  fromEmail: string;
+  fromName?: string;
+  webhookUrl?: string;
+  webhookSecret?: string;
+  sandbox?: boolean;
+}
+
+export class SendGridProvider extends EmailProvider {
+  private apiKey: string;
+  private fromEmail: string;
+  private fromName?: string;
+  private webhookUrl?: string;
+  private webhookSecret?: string;
+  private sandbox: boolean;
+
+  constructor(config: SendGridConfig) {
+    super(config);
+    
+    if (!config.apiKey) {
+      throw new Error('SendGrid API key is required');
+    }
+    
+    this.apiKey = config.apiKey;
+    this.fromEmail = config.fromEmail;
+    this.fromName = config.fromName;
+    this.webhookUrl = config.webhookUrl;
+    this.webhookSecret = config.webhookSecret;
+    this.sandbox = config.sandbox || false;
+  }
+
+  async sendEmail(email: EmailMessage): Promise<SendResult> {
+    try {
+      const payload = {
+        personalizations: [{
+          to: [{
+            email: email.toEmail,
+            name: email.toName
+          }],
+          subject: email.subject,
+          custom_args: email.metadata || {}
+        }],
+        from: {
+          email: email.fromEmail || this.fromEmail,
+          name: email.fromName || this.fromName
+        },
+        content: this.buildContent(email),
+        headers: email.headers || {},
+        mail_settings: {
+          sandbox_mode: {
+            enable: this.sandbox
+          }
+        }
+      };
+
+      // Add reply-to if specified
+      if (email.replyTo) {
+        (payload as any).reply_to = { email: email.replyTo };
+      }
+
+      // Convert attachments to SendGrid format
+      if (email.attachments && email.attachments.length > 0) {
+        (payload as any).attachments = email.attachments.map((att: any) => ({
+          filename: att.filename,
+          content: att.content,
+          type: att.contentType,
+          disposition: 'attachment'
+        }));
+      }
+
+      const response = await this.makeRequest('/mail/send', 'POST', payload);
+      
+      // SendGrid returns 202 for successful sends
+      if (response.status === 202) {
+        return {
+          success: true,
+          messageId: response.headers?.['x-message-id'] || `sg-${Date.now()}`,
+          providerResponse: response.data,
+          metadata: {
+            provider: 'sendgrid',
+            statusCode: response.status
+          }
+        };
+      }
+
+      return {
+        success: false,
+        errorMessage: `SendGrid API returned status ${response.status}`,
+        metadata: {
+          provider: 'sendgrid',
+          statusCode: response.status,
+          response: response.data
+        }
+      };
+
+    } catch (error) {
+      return {
+        success: false,
+        errorMessage: error instanceof Error ? error.message : 'Unknown error',
+        metadata: {
+          provider: 'sendgrid'
+        }
+      };
+    }
+  }
+
+  async sendBatch(emails: EmailMessage[]): Promise<SendResult[]> {
+    // SendGrid doesn't have a true batch API, so we send individually
+    // but we can optimize by sending them concurrently
+    const promises = emails.map(email => this.sendEmail(email));
+    return Promise.all(promises);
+  }
+
+  async getDeliveryStatus(messageId: string): Promise<DeliveryStatus | null> {
+    try {
+      // Use SendGrid's Event API
+      const response = await this.makeRequest(`/messages/${messageId}`, 'GET');
+      
+      if (response.status === 200 && response.data) {
+        return {
+          messageId,
+          status: this.mapSendGridStatus(response.data.status),
+          deliveredAt: response.data.delivered_at ? new Date(response.data.delivered_at) : undefined,
+          openedAt: response.data.opened_at ? new Date(response.data.opened_at) : undefined,
+          clickedAt: response.data.clicked_at ? new Date(response.data.clicked_at) : undefined,
+          metadata: response.data
+        };
+      }
+
+      return null;
+    } catch (error) {
+      console.error('Failed to get delivery status:', error);
+      return null;
+    }
+  }
+
+  async processWebhook(payload: any, signature: string): Promise<WebhookEvent[]> {
+    // Verify webhook signature if configured
+    if (this.webhookSecret && !this.verifyWebhookSignature(payload, signature)) {
+      throw new Error('Invalid webhook signature');
+    }
+
+    const events: WebhookEvent[] = [];
+
+    // SendGrid sends events as an array
+    if (Array.isArray(payload)) {
+      for (const eventData of payload) {
+        events.push({
+          messageId: eventData.sg_message_id,
+          eventType: this.mapSendGridEvent(eventData.event),
+          timestamp: new Date(eventData.timestamp * 1000),
+          email: eventData.email,
+          reason: eventData.reason,
+          response: eventData.response,
+          metadata: eventData
+        });
+      }
+    }
+
+    return events;
+  }
+
+  async createTemplate(templateData: {
+    name: string;
+    subject: string;
+    htmlContent: string;
+    textContent?: string;
+  }): Promise<string> {
+    try {
+      // Create the template
+      const templatePayload = {
+        name: templateData.name,
+        generation: 'dynamic'
+      };
+
+      const templateResponse = await this.makeRequest('/templates', 'POST', templatePayload);
+      
+      if (templateResponse.status !== 201) {
+        throw new Error(`Failed to create template: ${templateResponse.status}`);
+      }
+
+      const templateId = templateResponse.data.id;
+
+      // Create a version for the template
+      const versionPayload = {
+        template_id: templateId,
+        subject: templateData.subject,
+        html_content: templateData.htmlContent,
+        plain_content: templateData.textContent || '',
+        active: 1
+      };
+
+      const versionResponse = await this.makeRequest(
+        `/templates/${templateId}/versions`,
+        'POST',
+        versionPayload
+      );
+
+      if (versionResponse.status !== 201) {
+        throw new Error(`Failed to create template version: ${versionResponse.status}`);
+      }
+
+      return templateId;
+    } catch (error) {
+      throw new Error(`Template creation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  async sendTemplateEmail(
+    templateId: string,
+    toEmail: string,
+    templateData: Record<string, any>,
+    toName?: string
+  ): Promise<SendResult> {
+    try {
+      const payload = {
+        personalizations: [{
+          to: [{
+            email: toEmail,
+            name: toName
+          }],
+          dynamic_template_data: templateData
+        }],
+        from: {
+          email: this.fromEmail,
+          name: this.fromName
+        },
+        template_id: templateId,
+        mail_settings: {
+          sandbox_mode: {
+            enable: this.sandbox
+          }
+        }
+      };
+
+      const response = await this.makeRequest('/mail/send', 'POST', payload);
+      
+      if (response.status === 202) {
+        return {
+          success: true,
+          messageId: response.headers?.['x-message-id'] || `sg-tpl-${Date.now()}`,
+          providerResponse: response.data,
+          metadata: {
+            provider: 'sendgrid',
+            templateId,
+            statusCode: response.status
+          }
+        };
+      }
+
+      return {
+        success: false,
+        errorMessage: `SendGrid API returned status ${response.status}`,
+        metadata: {
+          provider: 'sendgrid',
+          templateId,
+          statusCode: response.status
+        }
+      };
+
+    } catch (error) {
+      return {
+        success: false,
+        errorMessage: error instanceof Error ? error.message : 'Unknown error',
+        metadata: {
+          provider: 'sendgrid',
+          templateId
+        }
+      };
+    }
+  }
+
+  private buildContent(email: EmailMessage): Array<{ type: string; value: string }> {
+    const content: Array<{ type: string; value: string }> = [];
+    
+    if (email.textContent) {
+      content.push({
+        type: 'text/plain',
+        value: email.textContent
+      });
+    }
+    
+    if (email.htmlContent) {
+      content.push({
+        type: 'text/html',
+        value: email.htmlContent
+      });
+    }
+    
+    return content;
+  }
+
+  private async makeRequest(endpoint: string, method: string, requestData?: any): Promise<any> {
+    const url = `https://api.sendgrid.com/v3${endpoint}`;
+    
+    const response = await fetch(url, {
+      method,
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: requestData ? JSON.stringify(requestData) : undefined
+    });
+
+    const responseText = await response.text();
+    let data;
+    try {
+      data = JSON.parse(responseText);
+    } catch {
+      data = responseText;
+    }
+
+    return {
+      status: response.status,
+      headers: {},
+      data: data
+    };
+  }
+
+  private mapSendGridStatus(status: string): 'delivered' | 'bounced' | 'failed' | 'pending' | 'sent' | 'opened' | 'clicked' | 'spam' | 'unsubscribed' {
+    const statusMap: Record<string, 'delivered' | 'bounced' | 'failed' | 'pending' | 'sent' | 'opened' | 'clicked' | 'spam' | 'unsubscribed'> = {
+      'delivered': 'delivered',
+      'processed': 'sent',
+      'bounce': 'bounced',
+      'dropped': 'failed',
+      'deferred': 'pending',
+      'blocked': 'failed'
+    };
+    
+    return statusMap[status] || 'failed';
+  }
+
+  private mapSendGridEvent(event: string): string {
+    const eventMap: Record<string, string> = {
+      'delivered': 'delivered',
+      'processed': 'sent',
+      'open': 'opened',
+      'click': 'clicked',
+      'bounce': 'bounced',
+      'dropped': 'failed',
+      'spam_report': 'spam',
+      'unsubscribe': 'unsubscribed'
+    };
+    
+    return eventMap[event] || event;
+  }
+
+  private verifyWebhookSignature(payload: any, signature: string): boolean {
+    // Implement SendGrid webhook signature verification
+    // This is a simplified version - you'd need to implement the actual verification
+    return true;
+  }
+} 

package/packages/core/src/types/provider.ts

@@ -0,0 +1,91 @@
+/*
+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.
+*/
+
+/**
+ * Email provider type definitions
+ */
+
+export interface EmailMessage {
+  toEmail: string;
+  toName?: string;
+  fromEmail?: string;
+  fromName?: string;
+  subject: string;
+  htmlContent?: string;
+  textContent?: string;
+  replyTo?: string;
+  headers?: Record<string, string>;
+  attachments?: EmailAttachment[];
+  metadata?: Record<string, any>;
+}
+
+export interface EmailAttachment {
+  filename: string;
+  content: string; // Base64 encoded
+  contentType?: string;
+  disposition?: 'attachment' | 'inline';
+}
+
+export interface SendResult {
+  success: boolean;
+  messageId?: string;
+  errorMessage?: string;
+  providerResponse?: any;
+  metadata?: Record<string, any>;
+}
+
+export interface DeliveryStatus {
+  messageId: string;
+  status: 'delivered' | 'bounced' | 'failed' | 'pending' | 'sent' | 'opened' | 'clicked' | 'spam' | 'unsubscribed';
+  deliveredAt?: Date;
+  openedAt?: Date;
+  clickedAt?: Date;
+  bouncedAt?: Date;
+  reason?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface WebhookEvent {
+  messageId: string;
+  eventType: string;
+  timestamp: Date;
+  email: string;
+  reason?: string;
+  response?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface ProviderConfig {
+  provider: 'sendgrid' | 'ses' | 'mailgun' | 'postmark' | 'smtp';
+  apiKey?: string;
+  region?: string;
+  endpoint?: string;
+  fromEmail: string;
+  fromName?: string;
+  replyTo?: string;
+  webhookUrl?: string;
+  webhookSecret?: string;
+  sandbox?: boolean;
+}
+
+export interface BatchEmailOptions {
+  templateId?: string;
+  variables?: Record<string, any>;
+  scheduledFor?: Date;
+  metadata?: Record<string, any>;
+}
+
+export interface EmailProviderCapabilities {
+  supportsBatch: boolean;
+  supportsTemplates: boolean;
+  supportsWebhooks: boolean;
+  supportsAttachments: boolean;
+  supportsDeliveryTracking: boolean;
+  maxBatchSize: number;
+  maxAttachmentSize: number;
+} 

package/packages/core/src/types/scheduled.ts

@@ -0,0 +1,78 @@
+/*
+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.
+*/
+
+/**
+ * Scheduled email type definitions
+ */
+
+export type TriggerType = 'immediate' | 'relative' | 'absolute';
+export type EmailStatus = 'pending' | 'sent' | 'failed' | 'cancelled' | 'paused';
+
+export interface ScheduledEmail {
+  id?: string;
+  templateId: string;
+  recipientEmail: string;
+  recipientName?: string;
+  scheduledFor: Date;
+  triggerType: TriggerType;
+  triggerOffset?: number; // days before/after reference date
+  referenceDate?: Date;
+  variables: Record<string, any>;
+  status: EmailStatus;
+  sentAt?: Date;
+  errorMessage?: string;
+  retryCount: number;
+  maxRetries: number;
+  metadata: Record<string, any>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export interface SchedulingFilters {
+  templateId?: string;
+  recipientEmail?: string;
+  status?: EmailStatus;
+  scheduledAfter?: Date;
+  scheduledBefore?: Date;
+  createdAfter?: Date;
+  createdBefore?: Date;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ProcessingResult {
+  processedCount: number;
+  successCount: number;
+  failedCount: number;
+  errors: Array<{
+    emailId: string;
+    error: string;
+  }>;
+  processingTimeSeconds: number;
+}
+
+export interface EmailBatch {
+  templateId: string;
+  recipients: Array<{
+    email: string;
+    name?: string;
+    variables: Record<string, any>;
+  }>;
+  scheduledFor?: Date;
+  triggerType?: TriggerType;
+  triggerOffset?: number;
+  referenceDate?: Date;
+  metadata?: Record<string, any>;
+}
+
+export interface SchedulingConfig {
+  batchSize: number;
+  retryDelays: number[]; // minutes
+  maxConcurrency: number;
+  processingInterval: number; // minutes
+} 

package/packages/core/src/types/template.ts

@@ -0,0 +1,97 @@
+/*
+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.
+*/
+
+/**
+ * Email template type definitions
+ */
+
+export type TemplateVariableType = 'text' | 'number' | 'date' | 'boolean' | 'url' | 'email';
+
+export interface TemplateVariable {
+  name: string;
+  type: TemplateVariableType;
+  description?: string;
+  defaultValue?: any;
+  required: boolean;
+  validation?: {
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+  };
+}
+
+export interface EmailTemplate {
+  id?: string;
+  name: string;
+  subject: string;
+  htmlBody: string;
+  textBody: string;
+  variables: TemplateVariable[];
+  categoryId?: string;
+  tags: string[];
+  isActive: boolean;
+  version: number;
+  createdAt?: Date;
+  updatedAt?: Date;
+  createdBy?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface TemplateCategory {
+  id: string;
+  name: string;
+  description?: string;
+  color?: string;
+  isActive: boolean;
+}
+
+export interface RenderedTemplate {
+  subject: string;
+  htmlContent: string;
+  textContent: string;
+  variables: Record<string, any>;
+  templateId: string;
+}
+
+export interface TemplateFilters {
+  categoryId?: string;
+  tags?: string[];
+  isActive?: boolean;
+  search?: string;
+  createdBy?: string;
+  createdAfter?: Date;
+  createdBefore?: Date;
+}
+
+export interface ValidationResult {
+  isValid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationWarning[];
+}
+
+export interface ValidationError {
+  field: string;
+  message: string;
+  code: string;
+  value?: any;
+}
+
+export interface ValidationWarning {
+  field: string;
+  message: string;
+  code: string;
+  value?: any;
+}
+
+export interface TemplatePreview {
+  template: EmailTemplate;
+  variables: Record<string, any>;
+  rendered: RenderedTemplate;
+} 

package/packages/core/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}