@bernierllc/email-sendgrid-plugin 1.0.1

package/src/plugin/template-manager.ts

@@ -0,0 +1,240 @@
+/*
+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, TemplateNotFoundError, TemplateConflictError } from '../api/errors';
+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';
+import {
+  SendGridTemplateData,
+  SendGridTemplateVersion
+} from '../types/sendgrid-types';
+
+export class TemplateManager {
+  constructor(
+    private readonly client: SendGridClient,
+    private readonly ownershipValidator: OwnershipValidator,
+    private readonly prefixEnforcer: PrefixEnforcer,
+    private readonly converter: TemplateConverter,
+    private readonly logger?: {
+      info: (message: string) => void;
+      error: (message: string) => void;
+    }
+  ) {}
+
+  async createTemplate(template: Template): Promise<string> {
+    // 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 SendGridApiError(
+        `Failed to create template: ${response.statusCode}`,
+        response.statusCode,
+        response.body
+      );
+    }
+
+    const templateData = this.client.parseResponseBody<SendGridTemplateData>(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: string, template: Template): Promise<void> {
+    // 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 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: string): Promise<void> {
+    this.ownershipValidator.validateOwnership(providerTemplateId);
+
+    const response = await this.client.request(`/templates/${providerTemplateId}`, {
+      method: 'DELETE'
+    });
+
+    if (!this.client.isSuccessResponse(response)) {
+      throw new 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: string): Promise<ProviderTemplate> {
+    this.ownershipValidator.validateOwnership(providerTemplateId);
+
+    const response = await this.client.request(`/templates/${providerTemplateId}`, {
+      method: 'GET'
+    });
+
+    if (response.statusCode === 404) {
+      throw new TemplateNotFoundError(providerTemplateId);
+    }
+
+    if (!this.client.isSuccessResponse(response)) {
+      throw new SendGridApiError(
+        `Failed to get template: ${response.statusCode}`,
+        response.statusCode,
+        response.body
+      );
+    }
+
+    const templateData = this.client.parseResponseBody<SendGridTemplateData>(response);
+    return this.converter.convertToProviderTemplate(templateData);
+  }
+
+  async listTemplates(): Promise<ProviderTemplate[]> {
+    const response = await this.client.request('/templates?generations=dynamic', {
+      method: 'GET'
+    });
+
+    if (!this.client.isSuccessResponse(response)) {
+      throw new SendGridApiError(
+        `Failed to list templates: ${response.statusCode}`,
+        response.statusCode,
+        response.body
+      );
+    }
+
+    const data = this.client.parseResponseBody<{ result: SendGridTemplateData[] }>(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: string,
+    version: TemplateVersion
+  ): Promise<string> {
+    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 SendGridApiError(
+        `Failed to create template version: ${response.statusCode}`,
+        response.statusCode,
+        response.body
+      );
+    }
+
+    const versionData = this.client.parseResponseBody<SendGridTemplateVersion>(response);
+    return versionData.id;
+  }
+
+  async activateTemplateVersion(templateId: string, versionId: string): Promise<void> {
+    const response = await this.client.request(
+      `/templates/${templateId}/versions/${versionId}/activate`,
+      { method: 'POST' }
+    );
+
+    if (!this.client.isSuccessResponse(response)) {
+      throw new SendGridApiError(
+        `Failed to activate template version: ${response.statusCode}`,
+        response.statusCode,
+        response.body
+      );
+    }
+
+    this.logger?.info(`Activated template version: ${templateId}/${versionId}`);
+  }
+
+  private hasConflicts(current: ProviderTemplate, updated: Template): boolean {
+    // Simple conflict detection - can be enhanced
+    return current.updatedAt > updated.updatedAt;
+  }
+
+  private detectConflicts(current: ProviderTemplate, updated: Template): string[] {
+    const conflicts: string[] = [];
+
+    if (current.subject !== updated.subject) {
+      conflicts.push('subject modified');
+    }
+
+    if (current.htmlContent !== updated.htmlContent) {
+      conflicts.push('HTML content modified');
+    }
+
+    return conflicts;
+  }
+}

package/src/safety/ownership-validator.ts

@@ -0,0 +1,55 @@
+/*
+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 { UnauthorizedTemplateAccessError } from '../api/errors';
+
+export type SafetyMode = 'strict' | 'permissive';
+
+export class OwnershipValidator {
+  private appTemplateIds: Set<string> = new Set();
+  private readonly safetyMode: SafetyMode;
+  private readonly logger?: {
+    debug: (message: string) => void;
+  };
+
+  constructor(safetyMode: SafetyMode, logger?: { debug: (message: string) => void }) {
+    this.safetyMode = safetyMode;
+    this.logger = logger;
+  }
+
+  registerTemplate(templateId: string): void {
+    this.appTemplateIds.add(templateId);
+    this.logger?.debug(`Registered app template: ${templateId}`);
+  }
+
+  unregisterTemplate(templateId: string): void {
+    this.appTemplateIds.delete(templateId);
+    this.logger?.debug(`Unregistered app template: ${templateId}`);
+  }
+
+  validateOwnership(templateId: string): void {
+    if (this.safetyMode === 'strict' && !this.appTemplateIds.has(templateId)) {
+      throw new UnauthorizedTemplateAccessError(
+        `Template ${templateId} is not managed by this application`
+      );
+    }
+  }
+
+  isOwnedTemplate(templateId: string): boolean {
+    return this.appTemplateIds.has(templateId);
+  }
+
+  getOwnedTemplates(): string[] {
+    return Array.from(this.appTemplateIds);
+  }
+
+  clearRegistrations(): void {
+    this.appTemplateIds.clear();
+    this.logger?.debug('Cleared all template registrations');
+  }
+}

package/src/safety/prefix-enforcer.ts

@@ -0,0 +1,37 @@
+/*
+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 PrefixEnforcer {
+  private readonly prefix: string;
+
+  constructor(prefix: string) {
+    this.prefix = prefix;
+  }
+
+  applyPrefix(name: string): string {
+    if (name.startsWith(this.prefix)) {
+      return name;
+    }
+    return `${this.prefix}${name}`;
+  }
+
+  stripPrefix(name: string): string {
+    if (name.startsWith(this.prefix)) {
+      return name.substring(this.prefix.length);
+    }
+    return name;
+  }
+
+  hasPrefix(name: string): boolean {
+    return name.startsWith(this.prefix);
+  }
+
+  getPrefix(): string {
+    return this.prefix;
+  }
+}

package/src/types/config-types.ts

@@ -0,0 +1,34 @@
+/*
+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 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/src/types/plugin-types.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.
+*/
+
+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/src/types/sendgrid-types.ts

@@ -0,0 +1,69 @@
+/*
+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 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/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}