@bernierllc/email-sendgrid-plugin 1.0.1

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

@@ -0,0 +1,79 @@
+export interface PluginConfig {
+    [key: string]: unknown;
+}
+export interface ProviderCapability {
+    feature: string;
+    description: string;
+    methods: string[];
+    config: Record<string, unknown>;
+}
+export interface Template {
+    id: string;
+    name: string;
+    description?: string;
+    subject: string;
+    htmlContent: string;
+    textContent?: string;
+    category: string;
+    tags: string[];
+    version: string;
+    isActive: boolean;
+    context?: string;
+    variables?: Record<string, unknown>;
+    requiredVariables: string[];
+    providerTemplateIds?: Record<string, string>;
+    lastSyncedAt?: Record<string, Date>;
+    syncStatus?: Record<string, string>;
+    createdAt: Date;
+    updatedAt: Date;
+    createdBy: string;
+    lastModifiedBy: string;
+}
+export interface ProviderTemplate {
+    id: string;
+    name: string;
+    description?: string;
+    subject: string;
+    htmlContent: string;
+    textContent?: string;
+    version: string;
+    active: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface TemplateVersion {
+    name: string;
+    subject: string;
+    htmlContent: string;
+    textContent?: string;
+    active: boolean;
+}
+export interface SyncResult {
+    success: boolean;
+    action: 'created' | 'updated' | 'deleted' | 'failed';
+    providerTemplateId?: string;
+    localTemplateId?: string;
+    error?: string;
+    metadata: Record<string, unknown>;
+}
+export interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+}
+export interface RouteConflict {
+    templateId: string;
+    conflicts: string[];
+}
+export interface DateRange {
+    start: Date;
+    end: Date;
+}
+export interface TemplateAnalytics {
+    templateId: string;
+    opens: number;
+    clicks: number;
+    bounces: number;
+    deliveries: number;
+    dateRange: DateRange;
+}
+export type FeatureConfig = Record<string, unknown>;

package/dist/types/plugin-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 });

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

@@ -0,0 +1,56 @@
+export interface VerifiedSender {
+    id: string;
+    email: string;
+    name: string;
+    isVerified: boolean;
+    domain: string;
+    verificationStatus: 'pending' | 'verified' | 'failed';
+    createdAt: Date;
+    lastVerifiedAt?: Date;
+}
+export interface SenderValidationResult {
+    isValid: boolean;
+    verifiedSender?: VerifiedSender;
+    domain: string;
+    domainMatches: VerifiedSender[];
+    errors: string[];
+    suggestions: string[];
+}
+export interface SendGridTemplateData {
+    id: string;
+    name: string;
+    generation: 'legacy' | 'dynamic';
+    updated_at: string;
+    versions?: SendGridTemplateVersion[];
+}
+export interface SendGridTemplateVersion {
+    id: string;
+    template_id: string;
+    active: number;
+    name: string;
+    html_content: string;
+    plain_content?: string;
+    subject: string;
+    updated_at: string;
+    editor: string;
+}
+export interface SendGridVerifiedSenderData {
+    id: number;
+    nickname: string;
+    from_email: string;
+    from_name: string;
+    reply_to: string;
+    reply_to_name: string;
+    address: string;
+    address2: string;
+    city: string;
+    state: string;
+    zip: string;
+    country: string;
+    verified: boolean;
+    locked: boolean;
+}
+export interface SendGridApiError extends Error {
+    statusCode?: number;
+    response?: unknown;
+}

package/dist/types/sendgrid-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 });

package/jest.config.js

@@ -0,0 +1,25 @@
+/*
+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 = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/index.ts'
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 60,
+      functions: 75,
+      lines: 65,
+      statements: 65
+    }
+  }
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bernierllc/email-sendgrid-plugin",
+  "version": "1.0.1",
+  "description": "SendGrid-specific template management, sender verification, and advanced features plugin for email template service",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "sendgrid",
+    "email",
+    "template",
+    "plugin",
+    "sender-verification",
+    "template-management"
+  ],
+  "author": "Bernier LLC",
+  "license": "SEE LICENSE IN LICENSE",
+  "dependencies": {
+    "@sendgrid/mail": "^8.1.3",
+    "@bernierllc/logger": "^1.0.1",
+    "@bernierllc/retry-policy": "^0.1.3",
+    "@bernierllc/rate-limiter": "^0.1.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.30",
+    "@typescript-eslint/eslint-plugin": "^7.3.1",
+    "@typescript-eslint/parser": "^7.3.1",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.2"
+  }
+}

package/src/api/errors.ts

@@ -0,0 +1,49 @@
+/*
+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.
+*/
+
+export class SendGridApiError extends Error {
+  constructor(
+    message: string,
+    public statusCode?: number,
+    public response?: unknown
+  ) {
+    super(message);
+    this.name = 'SendGridApiError';
+  }
+}
+
+export class TemplateNotFoundError extends Error {
+  constructor(public templateId: string) {
+    super(`Template not found: ${templateId}`);
+    this.name = 'TemplateNotFoundError';
+  }
+}
+
+export class UnauthorizedTemplateAccessError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UnauthorizedTemplateAccessError';
+  }
+}
+
+export class TemplateConflictError extends Error {
+  constructor(
+    public templateId: string,
+    public conflicts: string[]
+  ) {
+    super(`Template conflicts detected: ${conflicts.join(', ')}`);
+    this.name = 'TemplateConflictError';
+  }
+}
+
+export class RateLimitError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RateLimitError';
+  }
+}

package/src/api/rate-limiter.ts

@@ -0,0 +1,79 @@
+/*
+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 { RateLimitError } from './errors';
+
+export interface RateLimiterConfig {
+  maxRequestsPerSecond: number;
+  maxRequestsPerMinute: number;
+}
+
+export class SimpleRateLimiter {
+  private requestTimestamps: number[] = [];
+  private readonly maxRequestsPerSecond: number;
+  private readonly maxRequestsPerMinute: number;
+
+  constructor(config: RateLimiterConfig) {
+    this.maxRequestsPerSecond = config.maxRequestsPerSecond;
+    this.maxRequestsPerMinute = config.maxRequestsPerMinute;
+  }
+
+  async acquire(): Promise<void> {
+    const now = Date.now();
+
+    // Clean up old timestamps
+    this.requestTimestamps = this.requestTimestamps.filter(
+      timestamp => now - timestamp < 60000 // Keep last minute
+    );
+
+    // Check per-second limit
+    const lastSecond = this.requestTimestamps.filter(
+      timestamp => now - timestamp < 1000
+    );
+
+    if (lastSecond.length >= this.maxRequestsPerSecond) {
+      const waitTime = 1000 - (now - lastSecond[0]);
+      await this.sleep(waitTime);
+      return this.acquire();
+    }
+
+    // Check per-minute limit
+    if (this.requestTimestamps.length >= this.maxRequestsPerMinute) {
+      const waitTime = 60000 - (now - this.requestTimestamps[0]);
+      if (waitTime > 5000) {
+        throw new RateLimitError(`Rate limit exceeded, would need to wait ${Math.ceil(waitTime / 1000)}s`);
+      }
+      await this.sleep(waitTime);
+      return this.acquire();
+    }
+
+    // Add timestamp and proceed
+    this.requestTimestamps.push(now);
+  }
+
+  release(): void {
+    // No-op for simple implementation
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, Math.max(0, ms)));
+  }
+
+  getRemainingCapacity(): { perSecond: number; perMinute: number } {
+    const now = Date.now();
+    const lastSecond = this.requestTimestamps.filter(
+      timestamp => now - timestamp < 1000
+    ).length;
+    const lastMinute = this.requestTimestamps.length;
+
+    return {
+      perSecond: Math.max(0, this.maxRequestsPerSecond - lastSecond),
+      perMinute: Math.max(0, this.maxRequestsPerMinute - lastMinute)
+    };
+  }
+}

package/src/api/sendgrid-client.ts

@@ -0,0 +1,86 @@
+/*
+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 { ApiRequestOptions, ApiResponse } from '../types/config-types';
+import { SendGridApiError } from './errors';
+import { SimpleRateLimiter } from './rate-limiter';
+
+export interface SendGridClientConfig {
+  apiKey: string;
+  rateLimiter?: SimpleRateLimiter;
+  logger?: {
+    debug: (message: string) => void;
+    error: (message: string) => void;
+    info: (message: string) => void;
+  };
+}
+
+export class SendGridClient {
+  private readonly apiKey: string;
+  private readonly rateLimiter?: SimpleRateLimiter;
+  private readonly logger?: SendGridClientConfig['logger'];
+  private readonly baseUrl = 'https://api.sendgrid.com/v3';
+
+  constructor(config: SendGridClientConfig) {
+    this.apiKey = config.apiKey;
+    this.rateLimiter = config.rateLimiter;
+    this.logger = config.logger;
+  }
+
+  async request(endpoint: string, options: ApiRequestOptions): Promise<ApiResponse> {
+    // Apply rate limiting if configured
+    if (this.rateLimiter) {
+      await this.rateLimiter.acquire();
+    }
+
+    try {
+      const url = `${this.baseUrl}${endpoint}`;
+
+      const response = await fetch(url, {
+        method: options.method,
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+          ...options.headers
+        },
+        body: options.body
+      });
+
+      const body = await response.text();
+
+      // Log all API calls for audit trail
+      this.logger?.debug(`SendGrid API ${options.method} ${endpoint}: ${response.status}`);
+
+      return {
+        statusCode: response.status,
+        headers: Object.fromEntries(response.headers.entries()),
+        body
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      this.logger?.error(`SendGrid API error: ${errorMessage}`);
+      throw new SendGridApiError(`API request failed: ${errorMessage}`, undefined, error);
+    } finally {
+      if (this.rateLimiter) {
+        this.rateLimiter.release();
+      }
+    }
+  }
+
+  isSuccessResponse(response: ApiResponse): boolean {
+    return response.statusCode >= 200 && response.statusCode < 300;
+  }
+
+  parseResponseBody<T>(response: ApiResponse): T {
+    try {
+      return JSON.parse(response.body) as T;
+    } catch (error) {
+      throw new SendGridApiError('Failed to parse response body', response.statusCode, response.body);
+    }
+  }
+}

package/src/converters/sender-converter.ts

@@ -0,0 +1,41 @@
+/*
+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 { VerifiedSender, SendGridVerifiedSenderData } from '../types/sendgrid-types';
+
+export class SenderConverter {
+  convertToVerifiedSender(sendgridData: SendGridVerifiedSenderData): VerifiedSender {
+    const domain = this.extractDomain(sendgridData.from_email);
+
+    return {
+      id: sendgridData.id.toString(),
+      email: sendgridData.from_email,
+      name: sendgridData.from_name || sendgridData.nickname,
+      isVerified: sendgridData.verified,
+      domain,
+      verificationStatus: sendgridData.verified ? 'verified' : 'pending',
+      createdAt: new Date(), // SendGrid doesn't provide creation date
+      lastVerifiedAt: sendgridData.verified ? new Date() : undefined
+    };
+  }
+
+  extractDomain(email: string): string {
+    return email.split('@')[1]?.toLowerCase() || '';
+  }
+
+  isDomainMatch(domain1: string, domain2: string): boolean {
+    // Exact match
+    if (domain1 === domain2) return true;
+
+    // Subdomain match (e.g., app.example.com matches example.com)
+    if (domain1.endsWith(`.${domain2}`)) return true;
+    if (domain2.endsWith(`.${domain1}`)) return true;
+
+    return false;
+  }
+}

package/src/converters/template-converter.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.
+*/
+
+import {
+  SendGridTemplateData,
+  SendGridTemplateVersion
+} from '../types/sendgrid-types';
+import { ProviderTemplate, Template } from '../types/plugin-types';
+import { PrefixEnforcer } from '../safety/prefix-enforcer';
+
+export class TemplateConverter {
+  private readonly prefixEnforcer: PrefixEnforcer;
+
+  constructor(prefixEnforcer: PrefixEnforcer) {
+    this.prefixEnforcer = prefixEnforcer;
+  }
+
+  convertToProviderTemplate(
+    sendgridData: SendGridTemplateData,
+    activeVersion?: SendGridTemplateVersion
+  ): ProviderTemplate {
+    // Find active version if not provided
+    const version = activeVersion || this.findActiveVersion(sendgridData.versions || []);
+
+    return {
+      id: sendgridData.id,
+      name: this.prefixEnforcer.stripPrefix(sendgridData.name),
+      subject: version?.subject || '',
+      htmlContent: version?.html_content || '',
+      textContent: version?.plain_content,
+      version: version?.name || '1.0.0',
+      active: version?.active === 1,
+      createdAt: new Date(sendgridData.updated_at),
+      updatedAt: new Date(sendgridData.updated_at)
+    };
+  }
+
+  convertToLocalTemplate(
+    sendgridData: SendGridTemplateData,
+    localId: string,
+    activeVersion?: SendGridTemplateVersion
+  ): Template {
+    const providerTemplate = this.convertToProviderTemplate(sendgridData, activeVersion);
+
+    return {
+      id: localId,
+      name: providerTemplate.name,
+      subject: providerTemplate.subject,
+      htmlContent: providerTemplate.htmlContent,
+      textContent: providerTemplate.textContent,
+      category: 'synced',
+      tags: ['sendgrid', 'synced'],
+      version: providerTemplate.version,
+      isActive: providerTemplate.active,
+      requiredVariables: [],
+      providerTemplateIds: {
+        sendgrid: sendgridData.id
+      },
+      lastSyncedAt: {
+        sendgrid: new Date()
+      },
+      syncStatus: {
+        sendgrid: 'success'
+      },
+      createdAt: providerTemplate.createdAt,
+      updatedAt: providerTemplate.updatedAt,
+      createdBy: 'sendgrid-sync',
+      lastModifiedBy: 'sendgrid-sync'
+    };
+  }
+
+  extractVariables(content: string): string[] {
+    // Extract Handlebars-style variables: {{variableName}}
+    const regex = /\{\{([^}]+)\}\}/g;
+    const matches = content.matchAll(regex);
+    const variables = new Set<string>();
+
+    for (const match of matches) {
+      const variable = match[1].trim();
+      // Filter out Handlebars helpers
+      if (!variable.startsWith('#') && !variable.startsWith('/')) {
+        variables.add(variable);
+      }
+    }
+
+    return Array.from(variables);
+  }
+
+  private findActiveVersion(versions: SendGridTemplateVersion[]): SendGridTemplateVersion | undefined {
+    return versions.find(v => v.active === 1) || versions[0];
+  }
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+/*
+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.
+*/
+
+// Main plugin class
+export { SendGridTemplatePlugin, TemplateProviderPlugin } from './plugin/sendgrid-plugin';
+
+// Plugin components
+export { TemplateManager } from './plugin/template-manager';
+export { SenderManager } from './plugin/sender-manager';
+export { SyncManager } from './plugin/sync-manager';
+
+// API components
+export { SendGridClient } from './api/sendgrid-client';
+export { SimpleRateLimiter } from './api/rate-limiter';
+
+// Safety components
+export { OwnershipValidator, SafetyMode } from './safety/ownership-validator';
+export { PrefixEnforcer } from './safety/prefix-enforcer';
+
+// Converters
+export { TemplateConverter } from './converters/template-converter';
+export { SenderConverter } from './converters/sender-converter';
+
+// Errors
+export {
+  SendGridApiError,
+  TemplateNotFoundError,
+  UnauthorizedTemplateAccessError,
+  TemplateConflictError,
+  RateLimitError
+} from './api/errors';
+
+// Types
+export type { SendGridPluginConfig, ApiRequestOptions, ApiResponse } from './types/config-types';
+export type {
+  PluginConfig,
+  ProviderCapability,
+  Template,
+  ProviderTemplate,
+  TemplateVersion,
+  SyncResult,
+  ValidationResult,
+  DateRange,
+  TemplateAnalytics,
+  FeatureConfig
+} from './types/plugin-types';
+export type {
+  VerifiedSender,
+  SenderValidationResult,
+  SendGridTemplateData,
+  SendGridTemplateVersion,
+  SendGridVerifiedSenderData
+} from './types/sendgrid-types';