@bernierllc/email-sendgrid-plugin 1.0.1

package/__tests__/plugin/sendgrid-plugin.test.ts

@@ -0,0 +1,195 @@
+/*
+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 { SendGridTemplatePlugin } from '../../src/plugin/sendgrid-plugin';
+import { SendGridPluginConfig } from '../../src/types/config-types';
+
+describe('SendGridTemplatePlugin', () => {
+  let plugin: SendGridTemplatePlugin;
+  let config: SendGridPluginConfig;
+
+  beforeEach(() => {
+    config = {
+      apiKey: 'test-api-key',
+      templatePrefix: 'Test - ',
+      safetyMode: 'strict' as const,
+      rateLimits: {
+        templatesPerMinute: 60,
+        apiCallsPerSecond: 10
+      }
+    };
+
+    plugin = new SendGridTemplatePlugin(config);
+  });
+
+  describe('constructor', () => {
+    it('should create plugin with configuration', () => {
+      expect(plugin).toBeDefined();
+      expect(plugin.name).toBe('sendgrid-templates');
+      expect(plugin.version).toBe('1.0.0');
+      expect(plugin.providerId).toBe('sendgrid');
+    });
+  });
+
+  describe('initialize', () => {
+    it('should initialize plugin successfully', async () => {
+      await expect(plugin.initialize({})).resolves.toBeUndefined();
+    });
+
+    it('should be idempotent', async () => {
+      await plugin.initialize({});
+      await expect(plugin.initialize({})).resolves.toBeUndefined();
+    });
+  });
+
+  describe('destroy', () => {
+    it('should destroy plugin successfully', async () => {
+      await plugin.initialize({});
+      await expect(plugin.destroy()).resolves.toBeUndefined();
+    });
+
+    it('should handle destroy without initialization', async () => {
+      await expect(plugin.destroy()).resolves.toBeUndefined();
+    });
+  });
+
+  describe('getCapabilities', () => {
+    it('should return all supported capabilities', () => {
+      const capabilities = plugin.getCapabilities();
+
+      expect(capabilities).toHaveLength(4);
+      expect(capabilities.map(c => c.feature)).toEqual([
+        'template-management',
+        'sender-verification',
+        'template-analytics',
+        'batch-operations'
+      ]);
+    });
+
+    it('should include correct methods for each capability', () => {
+      const capabilities = plugin.getCapabilities();
+
+      const templateManagement = capabilities.find(c => c.feature === 'template-management');
+      expect(templateManagement?.methods).toContain('createTemplate');
+      expect(templateManagement?.methods).toContain('updateTemplate');
+      expect(templateManagement?.methods).toContain('deleteTemplate');
+
+      const senderVerification = capabilities.find(c => c.feature === 'sender-verification');
+      expect(senderVerification?.methods).toContain('getVerifiedSenders');
+      expect(senderVerification?.methods).toContain('validateSender');
+    });
+
+    it('should include configuration for each capability', () => {
+      const capabilities = plugin.getCapabilities();
+
+      capabilities.forEach(capability => {
+        expect(capability.config).toBeDefined();
+        expect(typeof capability.config).toBe('object');
+      });
+    });
+  });
+
+  describe('supportsFeature', () => {
+    it('should return true for supported features', () => {
+      expect(plugin.supportsFeature('template-management')).toBe(true);
+      expect(plugin.supportsFeature('sender-verification')).toBe(true);
+      expect(plugin.supportsFeature('template-analytics')).toBe(true);
+      expect(plugin.supportsFeature('batch-operations')).toBe(true);
+    });
+
+    it('should return false for unsupported features', () => {
+      expect(plugin.supportsFeature('unknown-feature')).toBe(false);
+      expect(plugin.supportsFeature('custom-domains')).toBe(false);
+    });
+  });
+
+  describe('getFeatureConfig', () => {
+    it('should return config for supported features', () => {
+      const config = plugin.getFeatureConfig('template-management');
+
+      expect(config).toBeDefined();
+      expect(config?.supportsVersioning).toBe(true);
+      expect(config?.supportsActivation).toBe(true);
+    });
+
+    it('should return null for unsupported features', () => {
+      const config = plugin.getFeatureConfig('unknown-feature');
+
+      expect(config).toBeNull();
+    });
+  });
+
+  describe('validateRoute', () => {
+    it('should validate route successfully', () => {
+      const result = plugin.validateRoute({});
+
+      expect(result.isValid).toBe(true);
+      expect(result.errors).toEqual([]);
+    });
+  });
+
+  describe('template operations', () => {
+    it('should throw error when not initialized', async () => {
+      await expect(plugin.createTemplate({} as any)).rejects.toThrow('not initialized');
+      await expect(plugin.getTemplate('123')).rejects.toThrow('not initialized');
+      await expect(plugin.listTemplates()).rejects.toThrow('not initialized');
+    });
+  });
+
+  describe('sender operations', () => {
+    it('should throw error when not initialized', async () => {
+      await expect(plugin.getVerifiedSenders()).rejects.toThrow('not initialized');
+      await expect(plugin.validateSender('test@example.com')).rejects.toThrow('not initialized');
+      await expect(plugin.selectBestSender('test@example.com')).rejects.toThrow('not initialized');
+    });
+  });
+
+  describe('sync operations', () => {
+    it('should throw error when not initialized', async () => {
+      await expect(plugin.syncToProvider({} as any)).rejects.toThrow('not initialized');
+      await expect(plugin.syncFromProvider('123')).rejects.toThrow('not initialized');
+      await expect(plugin.batchSyncTemplates([])).rejects.toThrow('not initialized');
+    });
+  });
+
+  describe('configuration variations', () => {
+    it('should work with permissive safety mode', async () => {
+      const permissiveConfig: SendGridPluginConfig = {
+        ...config,
+        safetyMode: 'permissive'
+      };
+
+      const permissivePlugin = new SendGridTemplatePlugin(permissiveConfig);
+      await expect(permissivePlugin.initialize({})).resolves.toBeUndefined();
+    });
+
+    it('should work without rate limits', async () => {
+      const noLimitsConfig: SendGridPluginConfig = {
+        apiKey: 'test-key',
+        templatePrefix: 'Test - ',
+        safetyMode: 'strict'
+      };
+
+      const noLimitsPlugin = new SendGridTemplatePlugin(noLimitsConfig);
+      await expect(noLimitsPlugin.initialize({})).resolves.toBeUndefined();
+    });
+
+    it('should work with webhook config', async () => {
+      const webhookConfig: SendGridPluginConfig = {
+        ...config,
+        webhookConfig: {
+          secret: 'webhook-secret',
+          eventTypes: ['delivered', 'bounced', 'opened']
+        }
+      };
+
+      const webhookPlugin = new SendGridTemplatePlugin(webhookConfig);
+      await expect(webhookPlugin.initialize({})).resolves.toBeUndefined();
+    });
+  });
+});

package/__tests__/plugin/template-manager.test.ts

@@ -0,0 +1,110 @@
+/*
+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 '../../src/plugin/template-manager';
+import { SendGridClient } from '../../src/api/sendgrid-client';
+import { OwnershipValidator } from '../../src/safety/ownership-validator';
+import { PrefixEnforcer } from '../../src/safety/prefix-enforcer';
+import { TemplateConverter } from '../../src/converters/template-converter';
+import { Template } from '../../src/types/plugin-types';
+
+describe('TemplateManager', () => {
+  let manager: TemplateManager;
+  let mockClient: jest.Mocked<SendGridClient>;
+  let ownershipValidator: OwnershipValidator;
+  let prefixEnforcer: PrefixEnforcer;
+  let converter: TemplateConverter;
+
+  beforeEach(() => {
+    mockClient = {
+      request: jest.fn(),
+      isSuccessResponse: jest.fn(),
+      parseResponseBody: jest.fn()
+    } as any;
+
+    ownershipValidator = new OwnershipValidator('strict');
+    prefixEnforcer = new PrefixEnforcer('Test - ');
+    converter = new TemplateConverter(prefixEnforcer);
+
+    manager = new TemplateManager(
+      mockClient,
+      ownershipValidator,
+      prefixEnforcer,
+      converter
+    );
+  });
+
+  describe('createTemplate', () => {
+    it('should create template successfully', async () => {
+      const template: Template = {
+        id: 'local-123',
+        name: 'Welcome',
+        subject: 'Welcome!',
+        htmlContent: '<html>Test</html>',
+        category: 'transactional',
+        tags: [],
+        version: '1.0.0',
+        isActive: true,
+        requiredVariables: [],
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        createdBy: 'test',
+        lastModifiedBy: 'test'
+      };
+
+      mockClient.request.mockResolvedValueOnce({
+        statusCode: 201,
+        headers: {},
+        body: JSON.stringify({ id: 'sendgrid-123', name: 'Test - Welcome', generation: 'dynamic', updated_at: new Date().toISOString() })
+      });
+
+      mockClient.isSuccessResponse.mockReturnValue(true);
+      mockClient.parseResponseBody.mockReturnValueOnce({ id: 'sendgrid-123', name: 'Test - Welcome', generation: 'dynamic', updated_at: new Date().toISOString() });
+
+      mockClient.request.mockResolvedValueOnce({
+        statusCode: 201,
+        headers: {},
+        body: JSON.stringify({ id: 'version-123' })
+      });
+
+      mockClient.isSuccessResponse.mockReturnValue(true);
+      mockClient.parseResponseBody.mockReturnValueOnce({ id: 'version-123' });
+
+      const result = await manager.createTemplate(template);
+
+      expect(result).toBe('sendgrid-123');
+      expect(mockClient.request).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('listTemplates', () => {
+    it('should list and register templates', async () => {
+      mockClient.request.mockResolvedValueOnce({
+        statusCode: 200,
+        headers: {},
+        body: JSON.stringify({
+          result: [
+            { id: 'template-1', name: 'Test - Template 1', generation: 'dynamic', updated_at: new Date().toISOString(), versions: [] }
+          ]
+        })
+      });
+
+      mockClient.isSuccessResponse.mockReturnValue(true);
+      mockClient.parseResponseBody.mockReturnValueOnce({
+        result: [
+          { id: 'template-1', name: 'Test - Template 1', generation: 'dynamic', updated_at: new Date().toISOString(), versions: [] }
+        ]
+      });
+
+      const result = await manager.listTemplates();
+
+      expect(result).toHaveLength(1);
+      expect(ownershipValidator.isOwnedTemplate('template-1')).toBe(true);
+    });
+  });
+});

package/__tests__/safety/ownership-validator.test.ts

@@ -0,0 +1,130 @@
+/*
+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 { OwnershipValidator } from '../../src/safety/ownership-validator';
+import { UnauthorizedTemplateAccessError } from '../../src/api/errors';
+
+describe('OwnershipValidator', () => {
+  describe('constructor', () => {
+    it('should create validator with specified safety mode', () => {
+      const validator = new OwnershipValidator('strict');
+      expect(validator).toBeDefined();
+    });
+  });
+
+  describe('registerTemplate', () => {
+    it('should register template successfully', () => {
+      const validator = new OwnershipValidator('strict');
+
+      validator.registerTemplate('template-123');
+
+      expect(validator.isOwnedTemplate('template-123')).toBe(true);
+    });
+
+    it('should not add duplicate registrations', () => {
+      const validator = new OwnershipValidator('strict');
+
+      validator.registerTemplate('template-123');
+      validator.registerTemplate('template-123');
+
+      expect(validator.getOwnedTemplates()).toEqual(['template-123']);
+    });
+  });
+
+  describe('unregisterTemplate', () => {
+    it('should unregister template successfully', () => {
+      const validator = new OwnershipValidator('strict');
+
+      validator.registerTemplate('template-123');
+      expect(validator.isOwnedTemplate('template-123')).toBe(true);
+
+      validator.unregisterTemplate('template-123');
+      expect(validator.isOwnedTemplate('template-123')).toBe(false);
+    });
+
+    it('should handle unregistering non-existent template', () => {
+      const validator = new OwnershipValidator('strict');
+
+      expect(() => validator.unregisterTemplate('non-existent')).not.toThrow();
+    });
+  });
+
+  describe('validateOwnership', () => {
+    it('should pass validation for owned template in strict mode', () => {
+      const validator = new OwnershipValidator('strict');
+      validator.registerTemplate('template-123');
+
+      expect(() => validator.validateOwnership('template-123')).not.toThrow();
+    });
+
+    it('should throw error for unowned template in strict mode', () => {
+      const validator = new OwnershipValidator('strict');
+
+      expect(() => validator.validateOwnership('template-123')).toThrow(UnauthorizedTemplateAccessError);
+    });
+
+    it('should pass validation for any template in permissive mode', () => {
+      const validator = new OwnershipValidator('permissive');
+
+      expect(() => validator.validateOwnership('template-123')).not.toThrow();
+      expect(() => validator.validateOwnership('unregistered')).not.toThrow();
+    });
+  });
+
+  describe('isOwnedTemplate', () => {
+    it('should return true for registered templates', () => {
+      const validator = new OwnershipValidator('strict');
+      validator.registerTemplate('template-123');
+
+      expect(validator.isOwnedTemplate('template-123')).toBe(true);
+    });
+
+    it('should return false for unregistered templates', () => {
+      const validator = new OwnershipValidator('strict');
+
+      expect(validator.isOwnedTemplate('template-123')).toBe(false);
+    });
+  });
+
+  describe('getOwnedTemplates', () => {
+    it('should return all registered templates', () => {
+      const validator = new OwnershipValidator('strict');
+
+      validator.registerTemplate('template-1');
+      validator.registerTemplate('template-2');
+      validator.registerTemplate('template-3');
+
+      const owned = validator.getOwnedTemplates();
+      expect(owned).toHaveLength(3);
+      expect(owned).toContain('template-1');
+      expect(owned).toContain('template-2');
+      expect(owned).toContain('template-3');
+    });
+
+    it('should return empty array when no templates registered', () => {
+      const validator = new OwnershipValidator('strict');
+
+      expect(validator.getOwnedTemplates()).toEqual([]);
+    });
+  });
+
+  describe('clearRegistrations', () => {
+    it('should clear all registered templates', () => {
+      const validator = new OwnershipValidator('strict');
+
+      validator.registerTemplate('template-1');
+      validator.registerTemplate('template-2');
+
+      expect(validator.getOwnedTemplates()).toHaveLength(2);
+
+      validator.clearRegistrations();
+
+      expect(validator.getOwnedTemplates()).toEqual([]);
+    });
+  });
+});

package/__tests__/safety/prefix-enforcer.test.ts

@@ -0,0 +1,136 @@
+/*
+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 { PrefixEnforcer } from '../../src/safety/prefix-enforcer';
+
+describe('PrefixEnforcer', () => {
+  describe('constructor', () => {
+    it('should create enforcer with specified prefix', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+      expect(enforcer.getPrefix()).toBe('MyApp - ');
+    });
+  });
+
+  describe('applyPrefix', () => {
+    it('should add prefix to name without prefix', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      const result = enforcer.applyPrefix('Welcome Email');
+
+      expect(result).toBe('MyApp - Welcome Email');
+    });
+
+    it('should not add prefix if already present', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      const result = enforcer.applyPrefix('MyApp - Welcome Email');
+
+      expect(result).toBe('MyApp - Welcome Email');
+    });
+
+    it('should handle empty string', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      const result = enforcer.applyPrefix('');
+
+      expect(result).toBe('MyApp - ');
+    });
+
+    it('should work with different prefix formats', () => {
+      const enforcer = new PrefixEnforcer('[PROD]');
+
+      expect(enforcer.applyPrefix('template')).toBe('[PROD]template');
+      expect(enforcer.applyPrefix('[PROD]template')).toBe('[PROD]template');
+    });
+  });
+
+  describe('stripPrefix', () => {
+    it('should remove prefix from name', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      const result = enforcer.stripPrefix('MyApp - Welcome Email');
+
+      expect(result).toBe('Welcome Email');
+    });
+
+    it('should return name unchanged if no prefix', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      const result = enforcer.stripPrefix('Welcome Email');
+
+      expect(result).toBe('Welcome Email');
+    });
+
+    it('should handle empty string', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      const result = enforcer.stripPrefix('');
+
+      expect(result).toBe('');
+    });
+
+    it('should only strip the prefix once', () => {
+      const enforcer = new PrefixEnforcer('App - ');
+
+      const result = enforcer.stripPrefix('App - App - Template');
+
+      expect(result).toBe('App - Template');
+    });
+  });
+
+  describe('hasPrefix', () => {
+    it('should return true for names with prefix', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      expect(enforcer.hasPrefix('MyApp - Welcome')).toBe(true);
+    });
+
+    it('should return false for names without prefix', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      expect(enforcer.hasPrefix('Welcome')).toBe(false);
+    });
+
+    it('should return false for empty string', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      expect(enforcer.hasPrefix('')).toBe(false);
+    });
+
+    it('should be case-sensitive', () => {
+      const enforcer = new PrefixEnforcer('MyApp - ');
+
+      expect(enforcer.hasPrefix('myapp - Welcome')).toBe(false);
+    });
+  });
+
+  describe('getPrefix', () => {
+    it('should return the configured prefix', () => {
+      const enforcer = new PrefixEnforcer('Test - ');
+
+      expect(enforcer.getPrefix()).toBe('Test - ');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle prefix-only names', () => {
+      const enforcer = new PrefixEnforcer('Prefix');
+
+      expect(enforcer.applyPrefix('Prefix')).toBe('Prefix');
+      expect(enforcer.stripPrefix('Prefix')).toBe('');
+      expect(enforcer.hasPrefix('Prefix')).toBe(true);
+    });
+
+    it('should handle special characters in prefix', () => {
+      const enforcer = new PrefixEnforcer('[App-v1.0]_');
+
+      expect(enforcer.applyPrefix('template')).toBe('[App-v1.0]_template');
+      expect(enforcer.stripPrefix('[App-v1.0]_template')).toBe('template');
+    });
+  });
+});

package/dist/api/errors.d.ts

@@ -0,0 +1,20 @@
+export declare class SendGridApiError extends Error {
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+export declare class TemplateNotFoundError extends Error {
+    templateId: string;
+    constructor(templateId: string);
+}
+export declare class UnauthorizedTemplateAccessError extends Error {
+    constructor(message: string);
+}
+export declare class TemplateConflictError extends Error {
+    templateId: string;
+    conflicts: string[];
+    constructor(templateId: string, conflicts: string[]);
+}
+export declare class RateLimitError extends Error {
+    constructor(message: string);
+}

package/dist/api/errors.js

@@ -0,0 +1,50 @@
+"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.RateLimitError = exports.TemplateConflictError = exports.UnauthorizedTemplateAccessError = exports.TemplateNotFoundError = exports.SendGridApiError = void 0;
+class SendGridApiError extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.statusCode = statusCode;
+        this.response = response;
+        this.name = 'SendGridApiError';
+    }
+}
+exports.SendGridApiError = SendGridApiError;
+class TemplateNotFoundError extends Error {
+    constructor(templateId) {
+        super(`Template not found: ${templateId}`);
+        this.templateId = templateId;
+        this.name = 'TemplateNotFoundError';
+    }
+}
+exports.TemplateNotFoundError = TemplateNotFoundError;
+class UnauthorizedTemplateAccessError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnauthorizedTemplateAccessError';
+    }
+}
+exports.UnauthorizedTemplateAccessError = UnauthorizedTemplateAccessError;
+class TemplateConflictError extends Error {
+    constructor(templateId, conflicts) {
+        super(`Template conflicts detected: ${conflicts.join(', ')}`);
+        this.templateId = templateId;
+        this.conflicts = conflicts;
+        this.name = 'TemplateConflictError';
+    }
+}
+exports.TemplateConflictError = TemplateConflictError;
+class RateLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RateLimitError';
+    }
+}
+exports.RateLimitError = RateLimitError;

package/dist/api/rate-limiter.d.ts

@@ -0,0 +1,17 @@
+export interface RateLimiterConfig {
+    maxRequestsPerSecond: number;
+    maxRequestsPerMinute: number;
+}
+export declare class SimpleRateLimiter {
+    private requestTimestamps;
+    private readonly maxRequestsPerSecond;
+    private readonly maxRequestsPerMinute;
+    constructor(config: RateLimiterConfig);
+    acquire(): Promise<void>;
+    release(): void;
+    private sleep;
+    getRemainingCapacity(): {
+        perSecond: number;
+        perMinute: number;
+    };
+}