@bernierllc/email-sendgrid-plugin 1.0.1

package/.eslintrc.js

@@ -0,0 +1,27 @@
+/*
+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.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+  ],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+  },
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-unused-vars': ['error', {
+      'argsIgnorePattern': '^_+',
+      'varsIgnorePattern': '^_+'
+    }],
+  },
+};

package/README.md

@@ -0,0 +1,432 @@
+# @bernierllc/email-sendgrid-plugin
+
+SendGrid-specific template management, sender verification, and advanced features plugin for email template services.
+
+## Installation
+
+```bash
+npm install @bernierllc/email-sendgrid-plugin
+```
+
+## Overview
+
+This package provides a comprehensive plugin for integrating SendGrid's template management and sender verification features into your email template service. It includes:
+
+- **Template CRUD Operations** - Create, read, update, and delete SendGrid templates
+- **Verified Sender Management** - Manage and validate SendGrid verified senders
+- **Template Synchronization** - Bi-directional sync between local and SendGrid templates
+- **Safety Features** - Shared account protection and template ownership validation
+- **Rate Limiting** - Built-in API rate limiting to respect SendGrid quotas
+- **Template Versioning** - Support for SendGrid template versions and activation
+
+## Key Features
+
+### Template Management
+- Full CRUD operations with SendGrid API
+- Template versioning and activation
+- Shared account safety (application-scoped operations)
+- Template prefix enforcement
+- Conflict detection and resolution
+
+### Verified Sender Integration
+- Sender verification status checking
+- Domain matching and validation
+- Automatic sender selection
+- Sender configuration management
+
+### Safety and Security
+- Application-scoped operations (never access non-app templates)
+- Template prefix enforcement
+- Shared account protection
+- Operation auditing and logging
+- Strict/permissive safety modes
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { SendGridTemplatePlugin } from '@bernierllc/email-sendgrid-plugin';
+
+const plugin = new SendGridTemplatePlugin({
+  apiKey: process.env.SENDGRID_API_KEY!,
+  templatePrefix: 'MyApp - ',
+  safetyMode: 'strict',
+  rateLimits: {
+    templatesPerMinute: 60,
+    apiCallsPerSecond: 10
+  }
+});
+
+// Initialize the plugin
+await plugin.initialize({});
+```
+
+### Creating Templates
+
+```typescript
+import { Template } from '@bernierllc/email-sendgrid-plugin';
+
+const template: Template = {
+  id: 'local-123',
+  name: 'Welcome Email',
+  subject: 'Welcome to {{appName}}',
+  htmlContent: '<html><body><h1>Welcome {{userName}}</h1></body></html>',
+  textContent: 'Welcome {{userName}}',
+  category: 'transactional',
+  tags: ['welcome', 'onboarding'],
+  version: '1.0.0',
+  isActive: true,
+  requiredVariables: ['appName', 'userName'],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  createdBy: 'system',
+  lastModifiedBy: 'system'
+};
+
+const sendgridTemplateId = await plugin.createTemplate(template);
+console.log(`Created SendGrid template: ${sendgridTemplateId}`);
+```
+
+### Managing Templates
+
+```typescript
+// Get template
+const template = await plugin.getTemplate('sendgrid-template-id');
+
+// List all templates
+const templates = await plugin.listTemplates();
+
+// Update template
+await plugin.updateTemplate('sendgrid-template-id', updatedTemplate);
+
+// Delete template
+await plugin.deleteTemplate('sendgrid-template-id');
+```
+
+### Sender Verification
+
+```typescript
+// Get all verified senders
+const senders = await plugin.getVerifiedSenders();
+
+// Validate sender email
+const validation = await plugin.validateSender('noreply@myapp.com');
+
+if (!validation.isValid) {
+  console.log('Sender validation failed:');
+  validation.errors.forEach(error => console.log(`- ${error}`));
+
+  console.log('Suggestions:');
+  validation.suggestions.forEach(suggestion => console.log(`- ${suggestion}`));
+}
+
+// Select best sender for outgoing email
+const bestSender = await plugin.selectBestSender('noreply@myapp.com');
+if (bestSender) {
+  console.log(`Using verified sender: ${bestSender.email}`);
+}
+```
+
+### Template Synchronization
+
+```typescript
+// Sync local template to SendGrid
+const syncResult = await plugin.syncToProvider(localTemplate);
+
+if (syncResult.success) {
+  console.log(`Synced template ${syncResult.action}: ${syncResult.providerTemplateId}`);
+} else {
+  console.error(`Sync failed: ${syncResult.error}`);
+}
+
+// Pull template from SendGrid
+const localTemplate = await plugin.syncFromProvider('sendgrid-template-id');
+
+// Batch synchronization
+const results = await plugin.batchSyncTemplates([template1, template2, template3]);
+const successful = results.filter(r => r.success).length;
+console.log(`Batch sync: ${successful}/${results.length} successful`);
+```
+
+### Template Versioning
+
+```typescript
+// Create new template version
+const versionId = await plugin.createTemplateVersion('sendgrid-template-id', {
+  name: 'v2.0.0',
+  subject: 'Updated Subject',
+  htmlContent: '<html><body>Updated content</body></html>',
+  textContent: 'Updated content',
+  active: false
+});
+
+// Activate template version
+await plugin.activateTemplateVersion('sendgrid-template-id', versionId);
+```
+
+## Configuration
+
+### SendGridPluginConfig
+
+```typescript
+interface SendGridPluginConfig {
+  // SendGrid API key (required)
+  apiKey: string;
+
+  // Template prefix for shared account safety (required)
+  templatePrefix: string;
+
+  // Safety mode: 'strict' or 'permissive' (required)
+  safetyMode: 'strict' | 'permissive';
+
+  // Whether using shared SendGrid account (optional)
+  sharedAccount?: boolean;
+
+  // API rate limits (optional)
+  rateLimits?: {
+    templatesPerMinute: number;
+    apiCallsPerSecond: number;
+  };
+
+  // Webhook configuration (optional)
+  webhookConfig?: {
+    secret: string;
+    eventTypes: string[];
+  };
+}
+```
+
+### Safety Modes
+
+**Strict Mode** (Recommended):
+- Only allows operations on templates registered with the application
+- Throws `UnauthorizedTemplateAccessError` for unregistered templates
+- Provides maximum safety in shared account environments
+
+**Permissive Mode**:
+- Allows operations on any template
+- Useful for administrative tools or migration scripts
+- Use with caution in shared account environments
+
+### Rate Limiting
+
+The plugin includes built-in rate limiting to respect SendGrid's API quotas:
+
+```typescript
+const plugin = new SendGridTemplatePlugin({
+  apiKey: process.env.SENDGRID_API_KEY!,
+  templatePrefix: 'MyApp - ',
+  safetyMode: 'strict',
+  rateLimits: {
+    templatesPerMinute: 60,   // Max 60 template operations per minute
+    apiCallsPerSecond: 10      // Max 10 API calls per second
+  }
+});
+```
+
+## Plugin Capabilities
+
+The plugin provides information about its capabilities:
+
+```typescript
+// Get all capabilities
+const capabilities = plugin.getCapabilities();
+
+// Check if feature is supported
+if (plugin.supportsFeature('sender-verification')) {
+  console.log('Sender verification is supported');
+}
+
+// Get feature configuration
+const config = plugin.getFeatureConfig('template-management');
+console.log(`Supports versioning: ${config.supportsVersioning}`);
+```
+
+### Available Capabilities
+
+- **template-management**: Full CRUD operations for SendGrid templates
+- **sender-verification**: SendGrid verified sender management
+- **template-analytics**: Template usage and performance analytics
+- **batch-operations**: Efficient bulk template operations
+
+## Error Handling
+
+The plugin provides specific error types for different failure scenarios:
+
+```typescript
+import {
+  SendGridApiError,
+  TemplateNotFoundError,
+  UnauthorizedTemplateAccessError,
+  TemplateConflictError,
+  RateLimitError
+} from '@bernierllc/email-sendgrid-plugin';
+
+try {
+  await plugin.getTemplate('template-id');
+} catch (error) {
+  if (error instanceof TemplateNotFoundError) {
+    console.log('Template does not exist');
+  } else if (error instanceof UnauthorizedTemplateAccessError) {
+    console.log('Template not owned by this application');
+  } else if (error instanceof SendGridApiError) {
+    console.log(`SendGrid API error: ${error.statusCode}`);
+  } else if (error instanceof RateLimitError) {
+    console.log('Rate limit exceeded');
+  }
+}
+```
+
+## Integration with Email Template Service
+
+This plugin is designed to work with `@bernierllc/email-template-service`:
+
+```typescript
+import { SendGridTemplatePlugin } from '@bernierllc/email-sendgrid-plugin';
+import { EmailTemplateService } from '@bernierllc/email-template-service';
+
+const sendGridPlugin = new SendGridTemplatePlugin({
+  apiKey: process.env.SENDGRID_API_KEY!,
+  templatePrefix: 'MyApp - ',
+  sharedAccount: true,
+  safetyMode: 'strict',
+  rateLimits: {
+    templatesPerMinute: 60,
+    apiCallsPerSecond: 10
+  }
+});
+
+const templateService = new EmailTemplateService({
+  providers: [sendGridPlugin],
+  syncConfig: {
+    enabled: true,
+    providers: {
+      sendgrid: {
+        enabled: true,
+        strategy: 'auto',
+        direction: 'bidirectional'
+      }
+    }
+  }
+});
+
+await templateService.initialize();
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Run tests in watch mode
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests once
+npm run test:run
+```
+
+## API Reference
+
+### SendGridTemplatePlugin
+
+#### Core Methods
+
+- `initialize(config: PluginConfig): Promise<void>` - Initialize the plugin
+- `destroy(): Promise<void>` - Cleanup and destroy the plugin
+
+#### Template Operations
+
+- `createTemplate(template: Template): Promise<string>` - Create a new template
+- `updateTemplate(id: string, template: Template): Promise<void>` - Update existing template
+- `deleteTemplate(id: string): Promise<void>` - Delete a template
+- `getTemplate(id: string): Promise<ProviderTemplate>` - Get template by ID
+- `listTemplates(): Promise<ProviderTemplate[]>` - List all templates
+
+#### Sender Operations
+
+- `getVerifiedSenders(): Promise<VerifiedSender[]>` - Get all verified senders
+- `validateSender(email: string): Promise<SenderValidationResult>` - Validate sender email
+- `selectBestSender(email: string): Promise<VerifiedSender | null>` - Auto-select best sender
+
+#### Synchronization
+
+- `syncToProvider(template: Template): Promise<SyncResult>` - Sync template to SendGrid
+- `syncFromProvider(id: string): Promise<Template>` - Pull template from SendGrid
+- `batchSyncTemplates(templates: Template[]): Promise<SyncResult[]>` - Batch sync
+
+#### Versioning
+
+- `createTemplateVersion(id: string, version: TemplateVersion): Promise<string>` - Create version
+- `activateTemplateVersion(id: string, versionId: string): Promise<void>` - Activate version
+
+#### Capabilities
+
+- `getCapabilities(): ProviderCapability[]` - Get all capabilities
+- `supportsFeature(feature: string): boolean` - Check feature support
+- `getFeatureConfig(feature: string): FeatureConfig | null` - Get feature config
+
+## Integration Status
+
+- **Logger**: Optional - All SendGrid operations and safety events
+- **Docs-Suite**: Ready - Complete API documentation
+- **NeverHub**: Optional - SendGrid API health monitoring and template sync events
+
+### NeverHub Integration
+
+This package supports optional NeverHub integration for enhanced observability and event-driven workflows:
+
+```typescript
+import { SendGridTemplatePlugin } from '@bernierllc/email-sendgrid-plugin';
+import { NeverHubAdapter } from '@bernierllc/neverhub-adapter';
+
+const plugin = new SendGridTemplatePlugin({
+  apiKey: process.env.SENDGRID_API_KEY!,
+  templatePrefix: 'MyApp - ',
+  safetyMode: 'strict'
+});
+
+// Auto-detect NeverHub availability
+const neverhub = await NeverHubAdapter.detectNeverHub()
+  ? new NeverHubAdapter()
+  : null;
+
+if (neverhub) {
+  // Register plugin capabilities
+  await neverhub.register({
+    type: 'email-plugin',
+    name: '@bernierllc/email-sendgrid-plugin',
+    capabilities: ['template-management', 'sender-verification']
+  });
+
+  // Subscribe to template events
+  await neverhub.subscribe('template.updated', async (event) => {
+    await plugin.syncFromProvider(event.templateId);
+  });
+}
+
+await plugin.initialize({});
+```
+
+The plugin works fully without NeverHub integration - all core functionality is available regardless of NeverHub presence.
+
+## Dependencies
+
+- `@sendgrid/mail` - Official SendGrid SDK
+- `@bernierllc/logger` - Operation logging (optional)
+- `@bernierllc/retry-policy` - API call retries
+- `@bernierllc/rate-limiter` - API rate limiting
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+
+## See Also
+
+- [@bernierllc/email-template-service](../email-template-service) - Email template service
+- [@bernierllc/email-sender](../email-sender) - Email sending abstraction
+- [@bernierllc/retry-policy](../retry-policy) - Retry policy utilities
+- [@bernierllc/rate-limiter](../rate-limiter) - Rate limiting utilities

package/__tests__/api/rate-limiter.test.ts

@@ -0,0 +1,125 @@
+/*
+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 { SimpleRateLimiter } from '../../src/api/rate-limiter';
+import { RateLimitError } from '../../src/api/errors';
+
+describe('SimpleRateLimiter', () => {
+  describe('constructor', () => {
+    it('should create rate limiter with specified limits', () => {
+      const limiter = new SimpleRateLimiter({
+        maxRequestsPerSecond: 10,
+        maxRequestsPerMinute: 100
+      });
+
+      expect(limiter).toBeDefined();
+      expect(limiter.getRemainingCapacity()).toEqual({
+        perSecond: 10,
+        perMinute: 100
+      });
+    });
+  });
+
+  describe('acquire', () => {
+    it('should allow requests within per-second limit', async () => {
+      const limiter = new SimpleRateLimiter({
+        maxRequestsPerSecond: 5,
+        maxRequestsPerMinute: 100
+      });
+
+      // Should allow 5 requests without delay
+      for (let i = 0; i < 5; i++) {
+        await expect(limiter.acquire()).resolves.toBeUndefined();
+      }
+    });
+
+    it('should enforce per-second rate limit', async () => {
+      const limiter = new SimpleRateLimiter({
+        maxRequestsPerSecond: 2,
+        maxRequestsPerMinute: 100
+      });
+
+      // Use up per-second quota
+      await limiter.acquire();
+      await limiter.acquire();
+
+      const start = Date.now();
+      await limiter.acquire(); // Should wait
+      const elapsed = Date.now() - start;
+
+      expect(elapsed).toBeGreaterThanOrEqual(900); // Allow some margin
+    });
+
+    it('should throw error if per-minute limit wait time exceeds threshold', async () => {
+      const limiter = new SimpleRateLimiter({
+        maxRequestsPerSecond: 100,
+        maxRequestsPerMinute: 2
+      });
+
+      // Use up per-minute quota
+      await limiter.acquire();
+      await limiter.acquire();
+
+      // Next request should throw since wait > 5s
+      await expect(limiter.acquire()).rejects.toThrow(RateLimitError);
+    });
+
+    it.skip('should clean up old timestamps (test too slow)', async () => {
+      // This test would take >60s to run, skipping for CI/CD speed
+      // Manual verification: timestamps older than 60s are filtered out
+    });
+  });
+
+  describe('getRemainingCapacity', () => {
+    it('should return correct remaining capacity', async () => {
+      const limiter = new SimpleRateLimiter({
+        maxRequestsPerSecond: 5,
+        maxRequestsPerMinute: 50
+      });
+
+      // Initial capacity
+      expect(limiter.getRemainingCapacity()).toEqual({
+        perSecond: 5,
+        perMinute: 50
+      });
+
+      // After 2 requests
+      await limiter.acquire();
+      await limiter.acquire();
+
+      expect(limiter.getRemainingCapacity()).toEqual({
+        perSecond: 3,
+        perMinute: 48
+      });
+    });
+
+    it('should never return negative capacity', async () => {
+      const limiter = new SimpleRateLimiter({
+        maxRequestsPerSecond: 1,
+        maxRequestsPerMinute: 10
+      });
+
+      await limiter.acquire();
+
+      const capacity = limiter.getRemainingCapacity();
+      expect(capacity.perSecond).toBeGreaterThanOrEqual(0);
+      expect(capacity.perMinute).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('release', () => {
+    it('should be a no-op', () => {
+      const limiter = new SimpleRateLimiter({
+        maxRequestsPerSecond: 10,
+        maxRequestsPerMinute: 100
+      });
+
+      expect(() => limiter.release()).not.toThrow();
+    });
+  });
+});