@bernierllc/email-sendgrid-plugin 1.0.1

package/src/plugin/sender-manager.ts

@@ -0,0 +1,166 @@
+/*
+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 { SendGridClient } from '../api/sendgrid-client';
+import { SendGridApiError } from '../api/errors';
+import { SenderConverter } from '../converters/sender-converter';
+import {
+  VerifiedSender,
+  SenderValidationResult,
+  SendGridVerifiedSenderData
+} from '../types/sendgrid-types';
+
+export class SenderManager {
+  private sendersCache?: VerifiedSender[];
+  private cacheTimestamp?: number;
+  private readonly cacheTTL = 300000; // 5 minutes
+
+  constructor(
+    private readonly client: SendGridClient,
+    private readonly converter: SenderConverter,
+    private readonly logger?: {
+      info: (message: string) => void;
+      debug: (message: string) => void;
+    }
+  ) {}
+
+  async getVerifiedSenders(useCache = true): Promise<VerifiedSender[]> {
+    // Return cached data if valid
+    if (
+      useCache &&
+      this.sendersCache &&
+      this.cacheTimestamp &&
+      Date.now() - this.cacheTimestamp < this.cacheTTL
+    ) {
+      this.logger?.debug('Returning cached verified senders');
+      return this.sendersCache;
+    }
+
+    const response = await this.client.request('/verified_senders', {
+      method: 'GET'
+    });
+
+    if (!this.client.isSuccessResponse(response)) {
+      throw new SendGridApiError(
+        'Failed to fetch verified senders',
+        response.statusCode,
+        response.body
+      );
+    }
+
+    const data = this.client.parseResponseBody<{ results: SendGridVerifiedSenderData[] }>(response);
+    const senders = data.results.map(sender => this.converter.convertToVerifiedSender(sender));
+
+    // Update cache
+    this.sendersCache = senders;
+    this.cacheTimestamp = Date.now();
+
+    this.logger?.info(`Fetched ${senders.length} verified senders from SendGrid`);
+
+    return senders;
+  }
+
+  async validateSender(email: string): Promise<SenderValidationResult> {
+    const verifiedSenders = await this.getVerifiedSenders();
+    const emailDomain = this.converter.extractDomain(email);
+
+    // Check for exact match
+    const exactMatch = verifiedSenders.find(
+      sender => sender.email.toLowerCase() === email.toLowerCase() && sender.isVerified
+    );
+
+    if (exactMatch) {
+      return {
+        isValid: true,
+        verifiedSender: exactMatch,
+        domain: emailDomain,
+        domainMatches: [exactMatch],
+        errors: [],
+        suggestions: []
+      };
+    }
+
+    // Check for domain matches
+    const domainMatches = verifiedSenders.filter(sender => {
+      const senderDomain = this.converter.extractDomain(sender.email);
+      return this.converter.isDomainMatch(emailDomain, senderDomain) && sender.isVerified;
+    });
+
+    if (domainMatches.length > 0) {
+      return {
+        isValid: true,
+        domain: emailDomain,
+        domainMatches,
+        errors: [],
+        suggestions: domainMatches.map(sender => sender.email)
+      };
+    }
+
+    // No matches found
+    return {
+      isValid: false,
+      domain: emailDomain,
+      domainMatches: [],
+      errors: [`No verified sender found for email ${email} or domain ${emailDomain}`],
+      suggestions: this.getSenderSuggestions(email, verifiedSenders)
+    };
+  }
+
+  async selectBestSender(fromEmail: string): Promise<VerifiedSender | null> {
+    const validation = await this.validateSender(fromEmail);
+
+    if (!validation.isValid || validation.domainMatches.length === 0) {
+      return null;
+    }
+
+    // Prefer exact match
+    if (validation.verifiedSender) {
+      return validation.verifiedSender;
+    }
+
+    // Fall back to best domain match
+    // Priority: most recently verified, then alphabetical
+    return validation.domainMatches.sort((a, b) => {
+      if (a.lastVerifiedAt && b.lastVerifiedAt) {
+        return b.lastVerifiedAt.getTime() - a.lastVerifiedAt.getTime();
+      }
+      if (a.lastVerifiedAt && !b.lastVerifiedAt) return -1;
+      if (!a.lastVerifiedAt && b.lastVerifiedAt) return 1;
+      return a.email.localeCompare(b.email);
+    })[0];
+  }
+
+  clearCache(): void {
+    this.sendersCache = undefined;
+    this.cacheTimestamp = undefined;
+    this.logger?.debug('Cleared verified senders cache');
+  }
+
+  private getSenderSuggestions(email: string, senders: VerifiedSender[]): string[] {
+    const emailDomain = this.converter.extractDomain(email);
+
+    // Find senders with similar domains
+    const suggestions: string[] = [];
+
+    for (const sender of senders) {
+      if (!sender.isVerified) continue;
+
+      const senderDomain = this.converter.extractDomain(sender.email);
+
+      // Check for partial domain matches
+      if (
+        emailDomain.includes(senderDomain) ||
+        senderDomain.includes(emailDomain)
+      ) {
+        suggestions.push(sender.email);
+      }
+    }
+
+    return suggestions.slice(0, 5); // Limit to 5 suggestions
+  }
+}

package/src/plugin/sendgrid-plugin.ts

@@ -0,0 +1,316 @@
+/*
+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 { SendGridPluginConfig } from '../types/config-types';
+import {
+  PluginConfig,
+  ProviderCapability,
+  Template,
+  ProviderTemplate,
+  TemplateVersion,
+  SyncResult,
+  ValidationResult,
+  DateRange,
+  TemplateAnalytics,
+  FeatureConfig
+} from '../types/plugin-types';
+import { VerifiedSender, SenderValidationResult } from '../types/sendgrid-types';
+import { SendGridClient } from '../api/sendgrid-client';
+import { SimpleRateLimiter } from '../api/rate-limiter';
+import { OwnershipValidator } from '../safety/ownership-validator';
+import { PrefixEnforcer } from '../safety/prefix-enforcer';
+import { TemplateConverter } from '../converters/template-converter';
+import { SenderConverter } from '../converters/sender-converter';
+import { TemplateManager } from './template-manager';
+import { SenderManager } from './sender-manager';
+import { SyncManager } from './sync-manager';
+
+export interface TemplateProviderPlugin {
+  readonly name: string;
+  readonly version: string;
+  readonly providerId: string;
+
+  initialize(config: PluginConfig): Promise<void>;
+  destroy(): Promise<void>;
+
+  // Template operations
+  createTemplate(template: Template): Promise<string>;
+  updateTemplate(providerTemplateId: string, template: Template): Promise<void>;
+  deleteTemplate(providerTemplateId: string): Promise<void>;
+  getTemplate(providerTemplateId: string): Promise<ProviderTemplate>;
+  listTemplates(): Promise<ProviderTemplate[]>;
+
+  // Synchronization
+  syncToProvider(template: Template): Promise<SyncResult>;
+  syncFromProvider(providerTemplateId: string): Promise<Template>;
+
+  // Capabilities
+  getCapabilities(): ProviderCapability[];
+  supportsFeature(feature: string): boolean;
+  getFeatureConfig(feature: string): FeatureConfig | null;
+}
+
+export class SendGridTemplatePlugin implements TemplateProviderPlugin {
+  readonly name = 'sendgrid-templates';
+  readonly version = '1.0.0';
+  readonly providerId = 'sendgrid';
+
+  private client!: SendGridClient;
+  private rateLimiter?: SimpleRateLimiter;
+  private ownershipValidator!: OwnershipValidator;
+  private prefixEnforcer!: PrefixEnforcer;
+  private templateConverter!: TemplateConverter;
+  private senderConverter!: SenderConverter;
+  private templateManager!: TemplateManager;
+  private senderManager!: SenderManager;
+  private syncManager!: SyncManager;
+
+  private readonly config: SendGridPluginConfig;
+  private readonly logger?: {
+    info: (message: string) => void;
+    debug: (message: string) => void;
+    error: (message: string) => void;
+  };
+
+  private initialized = false;
+
+  constructor(config: SendGridPluginConfig) {
+    this.config = config;
+  }
+
+  async initialize(__pluginConfig: PluginConfig): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    // Initialize rate limiter if configured
+    if (this.config.rateLimits) {
+      this.rateLimiter = new SimpleRateLimiter({
+        maxRequestsPerSecond: this.config.rateLimits.apiCallsPerSecond,
+        maxRequestsPerMinute: this.config.rateLimits.templatesPerMinute
+      });
+    }
+
+    // Initialize SendGrid client
+    this.client = new SendGridClient({
+      apiKey: this.config.apiKey,
+      rateLimiter: this.rateLimiter,
+      logger: this.logger
+    });
+
+    // Initialize safety components
+    this.ownershipValidator = new OwnershipValidator(
+      this.config.safetyMode,
+      this.logger
+    );
+    this.prefixEnforcer = new PrefixEnforcer(this.config.templatePrefix);
+
+    // Initialize converters
+    this.templateConverter = new TemplateConverter(this.prefixEnforcer);
+    this.senderConverter = new SenderConverter();
+
+    // Initialize managers
+    this.templateManager = new TemplateManager(
+      this.client,
+      this.ownershipValidator,
+      this.prefixEnforcer,
+      this.templateConverter,
+      this.logger
+    );
+
+    this.senderManager = new SenderManager(
+      this.client,
+      this.senderConverter,
+      this.logger
+    );
+
+    this.syncManager = new SyncManager(
+      this.templateManager,
+      this.templateConverter,
+      this.client,
+      this.logger
+    );
+
+    // Load existing templates
+    await this.loadExistingTemplates();
+
+    this.initialized = true;
+    this.logger?.info('SendGrid plugin initialized successfully');
+  }
+
+  async destroy(): Promise<void> {
+    if (!this.initialized) {
+      return;
+    }
+
+    this.ownershipValidator.clearRegistrations();
+    this.senderManager.clearCache();
+
+    this.initialized = false;
+    this.logger?.info('SendGrid plugin destroyed');
+  }
+
+  // Template operations
+  async createTemplate(template: Template): Promise<string> {
+    this.ensureInitialized();
+    return this.templateManager.createTemplate(template);
+  }
+
+  async updateTemplate(providerTemplateId: string, template: Template): Promise<void> {
+    this.ensureInitialized();
+    return this.templateManager.updateTemplate(providerTemplateId, template);
+  }
+
+  async deleteTemplate(providerTemplateId: string): Promise<void> {
+    this.ensureInitialized();
+    return this.templateManager.deleteTemplate(providerTemplateId);
+  }
+
+  async getTemplate(providerTemplateId: string): Promise<ProviderTemplate> {
+    this.ensureInitialized();
+    return this.templateManager.getTemplate(providerTemplateId);
+  }
+
+  async listTemplates(): Promise<ProviderTemplate[]> {
+    this.ensureInitialized();
+    return this.templateManager.listTemplates();
+  }
+
+  // Synchronization
+  async syncToProvider(template: Template): Promise<SyncResult> {
+    this.ensureInitialized();
+    return this.syncManager.syncToProvider(template);
+  }
+
+  async syncFromProvider(providerTemplateId: string): Promise<Template> {
+    this.ensureInitialized();
+    return this.syncManager.syncFromProvider(providerTemplateId);
+  }
+
+  // SendGrid-specific features
+  async getVerifiedSenders(): Promise<VerifiedSender[]> {
+    this.ensureInitialized();
+    return this.senderManager.getVerifiedSenders();
+  }
+
+  async validateSender(email: string): Promise<SenderValidationResult> {
+    this.ensureInitialized();
+    return this.senderManager.validateSender(email);
+  }
+
+  async selectBestSender(email: string): Promise<VerifiedSender | null> {
+    this.ensureInitialized();
+    return this.senderManager.selectBestSender(email);
+  }
+
+  async createTemplateVersion(
+    templateId: string,
+    version: TemplateVersion
+  ): Promise<string> {
+    this.ensureInitialized();
+    return this.templateManager.createTemplateVersion(templateId, version);
+  }
+
+  async activateTemplateVersion(templateId: string, versionId: string): Promise<void> {
+    this.ensureInitialized();
+    return this.templateManager.activateTemplateVersion(templateId, versionId);
+  }
+
+  async getTemplateAnalytics(
+    __templateId: string,
+    __dateRange: DateRange
+  ): Promise<TemplateAnalytics> {
+    this.ensureInitialized();
+    // TODO: Implement analytics fetching from SendGrid
+    throw new Error('Template analytics not yet implemented');
+  }
+
+  async batchSyncTemplates(templates: Template[]): Promise<SyncResult[]> {
+    this.ensureInitialized();
+    return this.syncManager.batchSync(templates);
+  }
+
+  // Capabilities
+  getCapabilities(): ProviderCapability[] {
+    return [
+      {
+        feature: 'template-management',
+        description: 'Full CRUD operations for SendGrid templates',
+        methods: ['createTemplate', 'updateTemplate', 'deleteTemplate', 'getTemplate', 'listTemplates'],
+        config: {
+          supportsVersioning: true,
+          supportsActivation: true,
+          maxNameLength: 100,
+          templatePrefix: this.config.templatePrefix
+        }
+      },
+      {
+        feature: 'sender-verification',
+        description: 'SendGrid verified sender management',
+        methods: ['getVerifiedSenders', 'validateSender', 'selectBestSender'],
+        config: {
+          supportsDomainMatching: true,
+          supportsAutoSelection: true
+        }
+      },
+      {
+        feature: 'template-analytics',
+        description: 'SendGrid template usage and performance analytics',
+        methods: ['getTemplateAnalytics'],
+        config: {
+          supportsRealTime: false,
+          historicalDataDays: 30,
+          metricsAvailable: ['opens', 'clicks', 'bounces', 'deliveries']
+        }
+      },
+      {
+        feature: 'batch-operations',
+        description: 'Efficient bulk template operations',
+        methods: ['batchSyncTemplates'],
+        config: {
+          maxBatchSize: 50,
+          supportsTransactions: false
+        }
+      }
+    ];
+  }
+
+  supportsFeature(feature: string): boolean {
+    return this.getCapabilities().some(cap => cap.feature === feature);
+  }
+
+  getFeatureConfig(feature: string): FeatureConfig | null {
+    const capability = this.getCapabilities().find(cap => cap.feature === feature);
+    return capability?.config || null;
+  }
+
+  validateRoute(__route: unknown): ValidationResult {
+    // Placeholder validation
+    return {
+      isValid: true,
+      errors: []
+    };
+  }
+
+  // Private methods
+  private async loadExistingTemplates(): Promise<void> {
+    try {
+      const templates = await this.templateManager.listTemplates();
+      this.logger?.info(`Loaded ${templates.length} existing SendGrid templates`);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.logger?.error(`Failed to load existing templates: ${errorMessage}`);
+    }
+  }
+
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new Error('SendGrid plugin not initialized. Call initialize() first.');
+    }
+  }
+}

package/src/plugin/sync-manager.ts

@@ -0,0 +1,115 @@
+/*
+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 { TemplateManager } from './template-manager';
+import { TemplateConverter } from '../converters/template-converter';
+import { SendGridClient } from '../api/sendgrid-client';
+import { Template, SyncResult } from '../types/plugin-types';
+import { SendGridTemplateData } from '../types/sendgrid-types';
+
+export class SyncManager {
+  constructor(
+    private readonly templateManager: TemplateManager,
+    private readonly converter: TemplateConverter,
+    private readonly client: SendGridClient,
+    private readonly logger?: {
+      info: (message: string) => void;
+      error: (message: string) => void;
+    }
+  ) {}
+
+  async syncToProvider(template: Template): Promise<SyncResult> {
+    try {
+      const existingProviderId = template.providerTemplateIds?.sendgrid;
+
+      if (existingProviderId) {
+        // Update existing template
+        await this.templateManager.updateTemplate(existingProviderId, template);
+
+        return {
+          success: true,
+          action: 'updated',
+          providerTemplateId: existingProviderId,
+          localTemplateId: template.id,
+          metadata: {
+            newVersion: template.version
+          }
+        };
+      } else {
+        // Create new template
+        const newProviderId = await this.templateManager.createTemplate(template);
+
+        return {
+          success: true,
+          action: 'created',
+          providerTemplateId: newProviderId,
+          localTemplateId: template.id,
+          metadata: {
+            version: template.version
+          }
+        };
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.logger?.error(`Template sync failed: ${errorMessage}`);
+
+      return {
+        success: false,
+        action: 'failed',
+        localTemplateId: template.id,
+        error: errorMessage,
+        metadata: {
+          errorType: error instanceof Error ? error.constructor.name : 'UnknownError',
+          timestamp: new Date()
+        }
+      };
+    }
+  }
+
+  async syncFromProvider(providerTemplateId: string): Promise<Template> {
+    const response = await this.client.request(`/templates/${providerTemplateId}`, {
+      method: 'GET'
+    });
+
+    if (!this.client.isSuccessResponse(response)) {
+      throw new Error(`Failed to fetch template from SendGrid: ${response.statusCode}`);
+    }
+
+    const templateData = this.client.parseResponseBody<SendGridTemplateData>(response);
+    const localId = this.generateLocalId();
+
+    return this.converter.convertToLocalTemplate(templateData, localId);
+  }
+
+  async batchSync(templates: Template[]): Promise<SyncResult[]> {
+    this.logger?.info(`Starting batch sync of ${templates.length} templates`);
+
+    const results: SyncResult[] = [];
+
+    for (const template of templates) {
+      const result = await this.syncToProvider(template);
+      results.push(result);
+
+      // Add delay to respect rate limits
+      await this.sleep(100);
+    }
+
+    const successful = results.filter(r => r.success).length;
+    this.logger?.info(`Batch sync completed: ${successful}/${templates.length} successful`);
+
+    return results;
+  }
+
+  private generateLocalId(): string {
+    return `local_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}