@bernierllc/email-sendgrid-plugin 1.0.1

package/dist/plugin/sendgrid-plugin.js

@@ -0,0 +1,204 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SendGridTemplatePlugin = void 0;
+const sendgrid_client_1 = require("../api/sendgrid-client");
+const rate_limiter_1 = require("../api/rate-limiter");
+const ownership_validator_1 = require("../safety/ownership-validator");
+const prefix_enforcer_1 = require("../safety/prefix-enforcer");
+const template_converter_1 = require("../converters/template-converter");
+const sender_converter_1 = require("../converters/sender-converter");
+const template_manager_1 = require("./template-manager");
+const sender_manager_1 = require("./sender-manager");
+const sync_manager_1 = require("./sync-manager");
+class SendGridTemplatePlugin {
+    constructor(config) {
+        this.name = 'sendgrid-templates';
+        this.version = '1.0.0';
+        this.providerId = 'sendgrid';
+        this.initialized = false;
+        this.config = config;
+    }
+    async initialize(__pluginConfig) {
+        if (this.initialized) {
+            return;
+        }
+        // Initialize rate limiter if configured
+        if (this.config.rateLimits) {
+            this.rateLimiter = new rate_limiter_1.SimpleRateLimiter({
+                maxRequestsPerSecond: this.config.rateLimits.apiCallsPerSecond,
+                maxRequestsPerMinute: this.config.rateLimits.templatesPerMinute
+            });
+        }
+        // Initialize SendGrid client
+        this.client = new sendgrid_client_1.SendGridClient({
+            apiKey: this.config.apiKey,
+            rateLimiter: this.rateLimiter,
+            logger: this.logger
+        });
+        // Initialize safety components
+        this.ownershipValidator = new ownership_validator_1.OwnershipValidator(this.config.safetyMode, this.logger);
+        this.prefixEnforcer = new prefix_enforcer_1.PrefixEnforcer(this.config.templatePrefix);
+        // Initialize converters
+        this.templateConverter = new template_converter_1.TemplateConverter(this.prefixEnforcer);
+        this.senderConverter = new sender_converter_1.SenderConverter();
+        // Initialize managers
+        this.templateManager = new template_manager_1.TemplateManager(this.client, this.ownershipValidator, this.prefixEnforcer, this.templateConverter, this.logger);
+        this.senderManager = new sender_manager_1.SenderManager(this.client, this.senderConverter, this.logger);
+        this.syncManager = new sync_manager_1.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() {
+        if (!this.initialized) {
+            return;
+        }
+        this.ownershipValidator.clearRegistrations();
+        this.senderManager.clearCache();
+        this.initialized = false;
+        this.logger?.info('SendGrid plugin destroyed');
+    }
+    // Template operations
+    async createTemplate(template) {
+        this.ensureInitialized();
+        return this.templateManager.createTemplate(template);
+    }
+    async updateTemplate(providerTemplateId, template) {
+        this.ensureInitialized();
+        return this.templateManager.updateTemplate(providerTemplateId, template);
+    }
+    async deleteTemplate(providerTemplateId) {
+        this.ensureInitialized();
+        return this.templateManager.deleteTemplate(providerTemplateId);
+    }
+    async getTemplate(providerTemplateId) {
+        this.ensureInitialized();
+        return this.templateManager.getTemplate(providerTemplateId);
+    }
+    async listTemplates() {
+        this.ensureInitialized();
+        return this.templateManager.listTemplates();
+    }
+    // Synchronization
+    async syncToProvider(template) {
+        this.ensureInitialized();
+        return this.syncManager.syncToProvider(template);
+    }
+    async syncFromProvider(providerTemplateId) {
+        this.ensureInitialized();
+        return this.syncManager.syncFromProvider(providerTemplateId);
+    }
+    // SendGrid-specific features
+    async getVerifiedSenders() {
+        this.ensureInitialized();
+        return this.senderManager.getVerifiedSenders();
+    }
+    async validateSender(email) {
+        this.ensureInitialized();
+        return this.senderManager.validateSender(email);
+    }
+    async selectBestSender(email) {
+        this.ensureInitialized();
+        return this.senderManager.selectBestSender(email);
+    }
+    async createTemplateVersion(templateId, version) {
+        this.ensureInitialized();
+        return this.templateManager.createTemplateVersion(templateId, version);
+    }
+    async activateTemplateVersion(templateId, versionId) {
+        this.ensureInitialized();
+        return this.templateManager.activateTemplateVersion(templateId, versionId);
+    }
+    async getTemplateAnalytics(__templateId, __dateRange) {
+        this.ensureInitialized();
+        // TODO: Implement analytics fetching from SendGrid
+        throw new Error('Template analytics not yet implemented');
+    }
+    async batchSyncTemplates(templates) {
+        this.ensureInitialized();
+        return this.syncManager.batchSync(templates);
+    }
+    // Capabilities
+    getCapabilities() {
+        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) {
+        return this.getCapabilities().some(cap => cap.feature === feature);
+    }
+    getFeatureConfig(feature) {
+        const capability = this.getCapabilities().find(cap => cap.feature === feature);
+        return capability?.config || null;
+    }
+    validateRoute(__route) {
+        // Placeholder validation
+        return {
+            isValid: true,
+            errors: []
+        };
+    }
+    // Private methods
+    async loadExistingTemplates() {
+        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}`);
+        }
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('SendGrid plugin not initialized. Call initialize() first.');
+        }
+    }
+}
+exports.SendGridTemplatePlugin = SendGridTemplatePlugin;

package/dist/plugin/sync-manager.d.ts

@@ -0,0 +1,19 @@
+import { TemplateManager } from './template-manager';
+import { TemplateConverter } from '../converters/template-converter';
+import { SendGridClient } from '../api/sendgrid-client';
+import { Template, SyncResult } from '../types/plugin-types';
+export declare class SyncManager {
+    private readonly templateManager;
+    private readonly converter;
+    private readonly client;
+    private readonly logger?;
+    constructor(templateManager: TemplateManager, converter: TemplateConverter, client: SendGridClient, logger?: {
+        info: (message: string) => void;
+        error: (message: string) => void;
+    } | undefined);
+    syncToProvider(template: Template): Promise<SyncResult>;
+    syncFromProvider(providerTemplateId: string): Promise<Template>;
+    batchSync(templates: Template[]): Promise<SyncResult[]>;
+    private generateLocalId;
+    private sleep;
+}

package/dist/plugin/sync-manager.js

@@ -0,0 +1,94 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncManager = void 0;
+class SyncManager {
+    constructor(templateManager, converter, client, logger) {
+        this.templateManager = templateManager;
+        this.converter = converter;
+        this.client = client;
+        this.logger = logger;
+    }
+    async syncToProvider(template) {
+        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) {
+        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(response);
+        const localId = this.generateLocalId();
+        return this.converter.convertToLocalTemplate(templateData, localId);
+    }
+    async batchSync(templates) {
+        this.logger?.info(`Starting batch sync of ${templates.length} templates`);
+        const results = [];
+        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;
+    }
+    generateLocalId() {
+        return `local_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+exports.SyncManager = SyncManager;

package/dist/plugin/template-manager.d.ts

@@ -0,0 +1,25 @@
+import { SendGridClient } from '../api/sendgrid-client';
+import { OwnershipValidator } from '../safety/ownership-validator';
+import { PrefixEnforcer } from '../safety/prefix-enforcer';
+import { TemplateConverter } from '../converters/template-converter';
+import { Template, ProviderTemplate, TemplateVersion } from '../types/plugin-types';
+export declare class TemplateManager {
+    private readonly client;
+    private readonly ownershipValidator;
+    private readonly prefixEnforcer;
+    private readonly converter;
+    private readonly logger?;
+    constructor(client: SendGridClient, ownershipValidator: OwnershipValidator, prefixEnforcer: PrefixEnforcer, converter: TemplateConverter, logger?: {
+        info: (message: string) => void;
+        error: (message: string) => void;
+    } | undefined);
+    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[]>;
+    createTemplateVersion(templateId: string, version: TemplateVersion): Promise<string>;
+    activateTemplateVersion(templateId: string, versionId: string): Promise<void>;
+    private hasConflicts;
+    private detectConflicts;
+}

package/dist/plugin/template-manager.js

@@ -0,0 +1,152 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateManager = void 0;
+const errors_1 = require("../api/errors");
+class TemplateManager {
+    constructor(client, ownershipValidator, prefixEnforcer, converter, logger) {
+        this.client = client;
+        this.ownershipValidator = ownershipValidator;
+        this.prefixEnforcer = prefixEnforcer;
+        this.converter = converter;
+        this.logger = logger;
+    }
+    async createTemplate(template) {
+        // Apply template naming convention
+        const templateName = this.prefixEnforcer.applyPrefix(template.name);
+        // Create base template in SendGrid
+        const createRequest = {
+            name: templateName,
+            generation: 'dynamic'
+        };
+        const response = await this.client.request('/templates', {
+            method: 'POST',
+            body: JSON.stringify(createRequest)
+        });
+        if (!this.client.isSuccessResponse(response)) {
+            throw new errors_1.SendGridApiError(`Failed to create template: ${response.statusCode}`, response.statusCode, response.body);
+        }
+        const templateData = this.client.parseResponseBody(response);
+        const templateId = templateData.id;
+        // Register as app-managed
+        this.ownershipValidator.registerTemplate(templateId);
+        // Create initial version with content
+        await this.createTemplateVersion(templateId, {
+            name: 'v1.0.0',
+            subject: template.subject,
+            htmlContent: template.htmlContent,
+            textContent: template.textContent,
+            active: true
+        });
+        // Log operation
+        this.logger?.info(`Created SendGrid template: ${templateName} (ID: ${templateId})`);
+        return templateId;
+    }
+    async updateTemplate(providerTemplateId, template) {
+        // Validate template ownership
+        this.ownershipValidator.validateOwnership(providerTemplateId);
+        // Get current template state
+        const currentTemplate = await this.getTemplate(providerTemplateId);
+        // Check for conflicts
+        if (this.hasConflicts(currentTemplate, template)) {
+            throw new errors_1.TemplateConflictError(providerTemplateId, this.detectConflicts(currentTemplate, template));
+        }
+        // Create new version with updated content
+        await this.createTemplateVersion(providerTemplateId, {
+            name: `v${template.version}`,
+            subject: template.subject,
+            htmlContent: template.htmlContent,
+            textContent: template.textContent,
+            active: template.isActive
+        });
+        this.logger?.info(`Updated SendGrid template: ${providerTemplateId}`);
+    }
+    async deleteTemplate(providerTemplateId) {
+        this.ownershipValidator.validateOwnership(providerTemplateId);
+        const response = await this.client.request(`/templates/${providerTemplateId}`, {
+            method: 'DELETE'
+        });
+        if (!this.client.isSuccessResponse(response)) {
+            throw new errors_1.SendGridApiError(`Failed to delete template: ${response.statusCode}`, response.statusCode, response.body);
+        }
+        this.ownershipValidator.unregisterTemplate(providerTemplateId);
+        this.logger?.info(`Deleted SendGrid template: ${providerTemplateId}`);
+    }
+    async getTemplate(providerTemplateId) {
+        this.ownershipValidator.validateOwnership(providerTemplateId);
+        const response = await this.client.request(`/templates/${providerTemplateId}`, {
+            method: 'GET'
+        });
+        if (response.statusCode === 404) {
+            throw new errors_1.TemplateNotFoundError(providerTemplateId);
+        }
+        if (!this.client.isSuccessResponse(response)) {
+            throw new errors_1.SendGridApiError(`Failed to get template: ${response.statusCode}`, response.statusCode, response.body);
+        }
+        const templateData = this.client.parseResponseBody(response);
+        return this.converter.convertToProviderTemplate(templateData);
+    }
+    async listTemplates() {
+        const response = await this.client.request('/templates?generations=dynamic', {
+            method: 'GET'
+        });
+        if (!this.client.isSuccessResponse(response)) {
+            throw new errors_1.SendGridApiError(`Failed to list templates: ${response.statusCode}`, response.statusCode, response.body);
+        }
+        const data = this.client.parseResponseBody(response);
+        // Filter to only app-managed templates
+        const appTemplates = data.result.filter(template => this.prefixEnforcer.hasPrefix(template.name));
+        // Register all app templates
+        appTemplates.forEach(template => {
+            this.ownershipValidator.registerTemplate(template.id);
+        });
+        return appTemplates.map(template => this.converter.convertToProviderTemplate(template));
+    }
+    async createTemplateVersion(templateId, version) {
+        const versionRequest = {
+            template_id: templateId,
+            name: version.name,
+            subject: version.subject,
+            html_content: version.htmlContent,
+            plain_content: version.textContent || '',
+            active: version.active ? 1 : 0
+        };
+        const response = await this.client.request(`/templates/${templateId}/versions`, {
+            method: 'POST',
+            body: JSON.stringify(versionRequest)
+        });
+        if (!this.client.isSuccessResponse(response)) {
+            throw new errors_1.SendGridApiError(`Failed to create template version: ${response.statusCode}`, response.statusCode, response.body);
+        }
+        const versionData = this.client.parseResponseBody(response);
+        return versionData.id;
+    }
+    async activateTemplateVersion(templateId, versionId) {
+        const response = await this.client.request(`/templates/${templateId}/versions/${versionId}/activate`, { method: 'POST' });
+        if (!this.client.isSuccessResponse(response)) {
+            throw new errors_1.SendGridApiError(`Failed to activate template version: ${response.statusCode}`, response.statusCode, response.body);
+        }
+        this.logger?.info(`Activated template version: ${templateId}/${versionId}`);
+    }
+    hasConflicts(current, updated) {
+        // Simple conflict detection - can be enhanced
+        return current.updatedAt > updated.updatedAt;
+    }
+    detectConflicts(current, updated) {
+        const conflicts = [];
+        if (current.subject !== updated.subject) {
+            conflicts.push('subject modified');
+        }
+        if (current.htmlContent !== updated.htmlContent) {
+            conflicts.push('HTML content modified');
+        }
+        return conflicts;
+    }
+}
+exports.TemplateManager = TemplateManager;

package/dist/safety/ownership-validator.d.ts

@@ -0,0 +1,15 @@
+export type SafetyMode = 'strict' | 'permissive';
+export declare class OwnershipValidator {
+    private appTemplateIds;
+    private readonly safetyMode;
+    private readonly logger?;
+    constructor(safetyMode: SafetyMode, logger?: {
+        debug: (message: string) => void;
+    });
+    registerTemplate(templateId: string): void;
+    unregisterTemplate(templateId: string): void;
+    validateOwnership(templateId: string): void;
+    isOwnedTemplate(templateId: string): boolean;
+    getOwnedTemplates(): string[];
+    clearRegistrations(): void;
+}

package/dist/safety/ownership-validator.js

@@ -0,0 +1,42 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OwnershipValidator = void 0;
+const errors_1 = require("../api/errors");
+class OwnershipValidator {
+    constructor(safetyMode, logger) {
+        this.appTemplateIds = new Set();
+        this.safetyMode = safetyMode;
+        this.logger = logger;
+    }
+    registerTemplate(templateId) {
+        this.appTemplateIds.add(templateId);
+        this.logger?.debug(`Registered app template: ${templateId}`);
+    }
+    unregisterTemplate(templateId) {
+        this.appTemplateIds.delete(templateId);
+        this.logger?.debug(`Unregistered app template: ${templateId}`);
+    }
+    validateOwnership(templateId) {
+        if (this.safetyMode === 'strict' && !this.appTemplateIds.has(templateId)) {
+            throw new errors_1.UnauthorizedTemplateAccessError(`Template ${templateId} is not managed by this application`);
+        }
+    }
+    isOwnedTemplate(templateId) {
+        return this.appTemplateIds.has(templateId);
+    }
+    getOwnedTemplates() {
+        return Array.from(this.appTemplateIds);
+    }
+    clearRegistrations() {
+        this.appTemplateIds.clear();
+        this.logger?.debug('Cleared all template registrations');
+    }
+}
+exports.OwnershipValidator = OwnershipValidator;

package/dist/safety/prefix-enforcer.d.ts

@@ -0,0 +1,8 @@
+export declare class PrefixEnforcer {
+    private readonly prefix;
+    constructor(prefix: string);
+    applyPrefix(name: string): string;
+    stripPrefix(name: string): string;
+    hasPrefix(name: string): boolean;
+    getPrefix(): string;
+}

package/dist/safety/prefix-enforcer.js

@@ -0,0 +1,34 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrefixEnforcer = void 0;
+class PrefixEnforcer {
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
+    applyPrefix(name) {
+        if (name.startsWith(this.prefix)) {
+            return name;
+        }
+        return `${this.prefix}${name}`;
+    }
+    stripPrefix(name) {
+        if (name.startsWith(this.prefix)) {
+            return name.substring(this.prefix.length);
+        }
+        return name;
+    }
+    hasPrefix(name) {
+        return name.startsWith(this.prefix);
+    }
+    getPrefix() {
+        return this.prefix;
+    }
+}
+exports.PrefixEnforcer = PrefixEnforcer;

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

@@ -0,0 +1,24 @@
+export interface SendGridPluginConfig {
+    apiKey: string;
+    templatePrefix: string;
+    sharedAccount?: boolean;
+    safetyMode: 'strict' | 'permissive';
+    rateLimits?: {
+        templatesPerMinute: number;
+        apiCallsPerSecond: number;
+    };
+    webhookConfig?: {
+        secret: string;
+        eventTypes: string[];
+    };
+}
+export interface ApiRequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    headers?: Record<string, string>;
+    body?: string;
+}
+export interface ApiResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+}

package/dist/types/config-types.js

@@ -0,0 +1,9 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });