@bernierllc/email 1.0.0 → 1.1.0

package/packages/core/specification.md

@@ -1,416 +0,0 @@
-# @email-template-manager/core - Core Library Specification
-
-## Overview
-
-The core library provides the foundational functionality for email template management, scheduling, and delivery. This package is framework-agnostic and can be used in any JavaScript/TypeScript environment.
-
-## Core Data Models
-
-### EmailTemplate
-
-```typescript
-interface EmailTemplate {
-  id: string;
-  name: string;
-  subject: string;
-  htmlBody: string;
-  textBody: string;
-  variables: TemplateVariable[];
-  categoryId?: string;
-  tags: string[];
-  isActive: boolean;
-  version: number;
-  createdAt: Date;
-  updatedAt: Date;
-  createdBy: string;
-}
-
-interface TemplateVariable {
-  name: string;
-  type: "text" | "number" | "date" | "boolean" | "url";
-  description?: string;
-  defaultValue?: any;
-  required: boolean;
-}
-```
-
-### ScheduledEmail
-
-```typescript
-interface ScheduledEmail {
-  id: string;
-  templateId: string;
-  recipientEmail: string;
-  recipientName?: string;
-  scheduledFor: Date;
-  triggerType: "immediate" | "relative" | "absolute";
-  triggerOffset?: number; // days before/after reference date
-  referenceDate?: Date;
-  variables: Record<string, any>;
-  status: "pending" | "sent" | "failed" | "cancelled" | "paused";
-  sentAt?: Date;
-  errorMessage?: string;
-  retryCount: number;
-  maxRetries: number;
-  metadata: Record<string, any>;
-}
-```
-
-### MagicLink
-
-```typescript
-interface MagicLink {
-  id: string;
-  token: string;
-  email: string;
-  type: string;
-  payload: Record<string, any>;
-  expiresAt: Date;
-  usedAt?: Date;
-  isUsed: boolean;
-  metadata: Record<string, any>;
-}
-```
-
-### EmailProvider Configuration
-
-```typescript
-interface EmailProviderConfig {
-  provider: "sendgrid" | "ses" | "mailgun" | "postmark" | "smtp";
-  apiKey?: string;
-  region?: string;
-  endpoint?: string;
-  fromEmail: string;
-  fromName: string;
-  replyTo?: string;
-  webhookUrl?: string;
-  webhookSecret?: string;
-}
-```
-
-## Core Classes
-
-### EmailTemplateManager
-
-```typescript
-class EmailTemplateManager {
-  constructor(config: EmailManagerConfig);
-
-  // Template CRUD operations
-  async createTemplate(
-    template: Partial<EmailTemplate>
-  ): Promise<EmailTemplate>;
-  async getTemplate(id: string): Promise<EmailTemplate | null>;
-  async updateTemplate(
-    id: string,
-    updates: Partial<EmailTemplate>
-  ): Promise<EmailTemplate>;
-  async deleteTemplate(id: string): Promise<boolean>;
-  async listTemplates(filters?: TemplateFilters): Promise<EmailTemplate[]>;
-
-  // Template rendering
-  async renderTemplate(
-    templateId: string,
-    variables: Record<string, any>
-  ): Promise<RenderedTemplate>;
-  async previewTemplate(
-    template: EmailTemplate,
-    variables: Record<string, any>
-  ): Promise<RenderedTemplate>;
-
-  // Variable validation
-  validateTemplateVariables(
-    template: EmailTemplate,
-    variables: Record<string, any>
-  ): ValidationResult;
-}
-```
-
-### EmailScheduler
-
-```typescript
-class EmailScheduler {
-  constructor(
-    templateManager: EmailTemplateManager,
-    emailProvider: EmailProvider
-  );
-
-  // Scheduling operations
-  async scheduleEmail(email: Partial<ScheduledEmail>): Promise<ScheduledEmail>;
-  async scheduleBatch(
-    emails: Partial<ScheduledEmail>[]
-  ): Promise<ScheduledEmail[]>;
-  async cancelScheduledEmail(id: string): Promise<boolean>;
-  async pauseScheduledEmail(id: string): Promise<boolean>;
-  async resumeScheduledEmail(id: string): Promise<boolean>;
-
-  // Processing
-  async processPendingEmails(): Promise<ProcessingResult>;
-  async retryFailedEmails(): Promise<ProcessingResult>;
-
-  // Status tracking
-  async getScheduledEmail(id: string): Promise<ScheduledEmail | null>;
-  async listScheduledEmails(
-    filters?: SchedulingFilters
-  ): Promise<ScheduledEmail[]>;
-}
-```
-
-### MagicLinkManager
-
-```typescript
-class MagicLinkManager {
-  constructor(config: MagicLinkConfig);
-
-  // Magic link operations
-  async generateMagicLink(
-    email: string,
-    type: string,
-    payload: Record<string, any>,
-    expiresIn?: number
-  ): Promise<MagicLink>;
-  async validateMagicLink(token: string): Promise<MagicLink | null>;
-  async useMagicLink(token: string): Promise<MagicLink>;
-  async revokeMagicLink(token: string): Promise<boolean>;
-
-  // Cleanup
-  async cleanupExpiredLinks(): Promise<number>;
-}
-```
-
-### EmailProvider (Abstract Base)
-
-```typescript
-abstract class EmailProvider {
-  constructor(config: EmailProviderConfig);
-
-  abstract async sendEmail(email: EmailMessage): Promise<SendResult>;
-  abstract async sendBatch(emails: EmailMessage[]): Promise<SendResult[]>;
-  abstract async getDeliveryStatus(messageId: string): Promise<DeliveryStatus>;
-  abstract async processWebhook(
-    payload: any,
-    signature: string
-  ): Promise<WebhookEvent[]>;
-}
-```
-
-## Utility Functions
-
-### Template Rendering
-
-```typescript
-// Liquid template engine integration
-function renderLiquidTemplate(
-  template: string,
-  variables: Record<string, any>
-): string;
-
-// HTML sanitization
-function sanitizeHtml(html: string): string;
-
-// Text extraction from HTML
-function extractTextFromHtml(html: string): string;
-```
-
-### Validation
-
-```typescript
-function validateEmailAddress(email: string): boolean;
-function validateTemplateVariables(
-  template: EmailTemplate,
-  variables: Record<string, any>
-): ValidationResult;
-function validateCronExpression(expression: string): boolean;
-```
-
-### Encryption/Security
-
-```typescript
-function generateSecureToken(length?: number): string;
-function hashToken(token: string): string;
-function verifyTokenHash(token: string, hash: string): boolean;
-function encryptPayload(payload: Record<string, any>, key: string): string;
-function decryptPayload(encrypted: string, key: string): Record<string, any>;
-```
-
-## Configuration
-
-### EmailManagerConfig
-
-```typescript
-interface EmailManagerConfig {
-  // Database connection
-  database: {
-    type: "postgresql" | "mysql" | "sqlite" | "mongodb";
-    connectionString: string;
-    ssl?: boolean;
-    pool?: {
-      min: number;
-      max: number;
-      idleTimeoutMillis: number;
-    };
-  };
-
-  // Email provider
-  emailProvider: EmailProviderConfig;
-
-  // Template settings
-  templates: {
-    defaultFromEmail: string;
-    defaultFromName: string;
-    liquidEngine: {
-      strictVariables: boolean;
-      customFilters?: Record<string, Function>;
-    };
-  };
-
-  // Scheduling
-  scheduling: {
-    defaultMaxRetries: number;
-    retryDelayMinutes: number[];
-    batchSize: number;
-    processingIntervalMinutes: number;
-  };
-
-  // Security
-  security: {
-    encryptionKey: string;
-    tokenLength: number;
-    defaultExpiryHours: number;
-  };
-
-  // Logging
-  logging: {
-    level: "debug" | "info" | "warn" | "error";
-    includePayload: boolean;
-  };
-}
-```
-
-## Event System
-
-### EmailEvents
-
-```typescript
-interface EmailTemplateEvent {
-  type: "template.created" | "template.updated" | "template.deleted";
-  templateId: string;
-  timestamp: Date;
-  metadata: Record<string, any>;
-}
-
-interface EmailSchedulingEvent {
-  type: "email.scheduled" | "email.sent" | "email.failed" | "email.cancelled";
-  scheduledEmailId: string;
-  timestamp: Date;
-  metadata: Record<string, any>;
-}
-
-interface MagicLinkEvent {
-  type: "link.generated" | "link.used" | "link.expired" | "link.revoked";
-  linkId: string;
-  timestamp: Date;
-  metadata: Record<string, any>;
-}
-```
-
-### Event Emitter
-
-```typescript
-class EmailEventEmitter extends EventEmitter {
-  onTemplateEvent(handler: (event: EmailTemplateEvent) => void): void;
-  onSchedulingEvent(handler: (event: EmailSchedulingEvent) => void): void;
-  onMagicLinkEvent(handler: (event: MagicLinkEvent) => void): void;
-}
-```
-
-## Error Handling
-
-### Custom Errors
-
-```typescript
-class EmailTemplateError extends Error {
-  code: string;
-  templateId?: string;
-}
-
-class EmailSchedulingError extends Error {
-  code: string;
-  scheduledEmailId?: string;
-}
-
-class MagicLinkError extends Error {
-  code: string;
-  token?: string;
-}
-
-class EmailProviderError extends Error {
-  code: string;
-  provider: string;
-  originalError?: Error;
-}
-```
-
-## Testing Utilities
-
-### Mock Providers
-
-```typescript
-class MockEmailProvider extends EmailProvider {
-  // Implementation for testing
-}
-
-class InMemoryStorage implements StorageAdapter {
-  // Implementation for testing
-}
-```
-
-### Test Helpers
-
-```typescript
-function createTestTemplate(overrides?: Partial<EmailTemplate>): EmailTemplate;
-function createTestScheduledEmail(
-  overrides?: Partial<ScheduledEmail>
-): ScheduledEmail;
-function createTestMagicLink(overrides?: Partial<MagicLink>): MagicLink;
-```
-
-## Export Structure
-
-```typescript
-// Main classes
-export { EmailTemplateManager, EmailScheduler, MagicLinkManager };
-
-// Email providers
-export {
-  EmailProvider,
-  SendGridProvider,
-  SESProvider,
-  MailgunProvider,
-  PostmarkProvider,
-  SMTPProvider,
-};
-
-// Data models
-export type { EmailTemplate, ScheduledEmail, MagicLink, EmailProviderConfig };
-
-// Utilities
-export { renderLiquidTemplate, validateEmailAddress, generateSecureToken };
-
-// Events
-export { EmailEventEmitter };
-export type { EmailTemplateEvent, EmailSchedulingEvent, MagicLinkEvent };
-
-// Errors
-export {
-  EmailTemplateError,
-  EmailSchedulingError,
-  MagicLinkError,
-  EmailProviderError,
-};
-
-// Testing
-export { MockEmailProvider, InMemoryStorage, createTestTemplate };
-```
-
-This core library provides all the essential functionality needed for email template management while remaining framework-agnostic and easily extensible.

package/packages/core/src/adapters/supabase.ts

@@ -1,291 +0,0 @@
-/*
-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.
-*/
-
-/**
- * Supabase adapter for EmailTemplateManager
- */
-
-import { createClient, SupabaseClient } from '@supabase/supabase-js';
-import { EmailTemplate, TemplateFilters } from '../types/template';
-
-export interface SupabaseConfig {
-  url: string;
-  key: string;
-  templatesTable?: string;
-  logsTable?: string;
-}
-
-export class SupabaseEmailAdapter {
-  private supabase: SupabaseClient;
-  private templatesTable: string;
-  private logsTable: string;
-
-  constructor(config: SupabaseConfig) {
-    this.supabase = createClient(config.url, config.key);
-    this.templatesTable = config.templatesTable || 'email_templates';
-    this.logsTable = config.logsTable || 'email_delivery_logs';
-  }
-
-  /**
-   * Save template to Supabase
-   */
-  async saveTemplate(template: EmailTemplate): Promise<EmailTemplate> {
-    const { data, error } = await this.supabase
-      .from(this.templatesTable)
-      .upsert([
-        {
-          id: template.id,
-          name: template.name,
-          subject: template.subject,
-          html_body: template.htmlBody,
-          text_body: template.textBody,
-          variables: template.variables,
-          category_id: template.categoryId,
-          tags: template.tags,
-          is_active: template.isActive,
-          version: template.version,
-          created_at: template.createdAt?.toISOString(),
-          updated_at: template.updatedAt?.toISOString(),
-          created_by: template.createdBy,
-          metadata: template.metadata,
-        },
-      ])
-      .select()
-      .single();
-
-    if (error) {
-      throw new Error(`Failed to save template: ${error.message}`);
-    }
-
-    return this.mapFromDatabase(data);
-  }
-
-  /**
-   * Load template by ID
-   */
-  async loadTemplate(id: string): Promise<EmailTemplate | null> {
-    const { data, error } = await this.supabase
-      .from(this.templatesTable)
-      .select('*')
-      .eq('id', id)
-      .single();
-
-    if (error) {
-      if (error.code === 'PGRST116') {
-        return null; // Not found
-      }
-      throw new Error(`Failed to load template: ${error.message}`);
-    }
-
-    return this.mapFromDatabase(data);
-  }
-
-  /**
-   * Load template by name
-   */
-  async loadTemplateByName(name: string): Promise<EmailTemplate | null> {
-    const { data, error } = await this.supabase
-      .from(this.templatesTable)
-      .select('*')
-      .eq('name', name)
-      .eq('is_active', true)
-      .single();
-
-    if (error) {
-      if (error.code === 'PGRST116') {
-        return null; // Not found
-      }
-      throw new Error(`Failed to load template by name: ${error.message}`);
-    }
-
-    return this.mapFromDatabase(data);
-  }
-
-  /**
-   * Load templates with filters
-   */
-  async loadTemplates(filters?: TemplateFilters): Promise<EmailTemplate[]> {
-    let query = this.supabase.from(this.templatesTable).select('*');
-
-    if (filters) {
-      if (filters.categoryId) {
-        query = query.eq('category_id', filters.categoryId);
-      }
-
-      if (filters.isActive !== undefined) {
-        query = query.eq('is_active', filters.isActive);
-      }
-
-      if (filters.createdBy) {
-        query = query.eq('created_by', filters.createdBy);
-      }
-
-      if (filters.createdAfter) {
-        query = query.gte('created_at', filters.createdAfter.toISOString());
-      }
-
-      if (filters.createdBefore) {
-        query = query.lte('created_at', filters.createdBefore.toISOString());
-      }
-
-      if (filters.search) {
-        query = query.or(
-          `name.ilike.%${filters.search}%,subject.ilike.%${filters.search}%`
-        );
-      }
-
-      if (filters.tags && filters.tags.length > 0) {
-        query = query.overlaps('tags', filters.tags);
-      }
-    }
-
-    const { data, error } = await query.order('created_at', { ascending: false });
-
-    if (error) {
-      throw new Error(`Failed to load templates: ${error.message}`);
-    }
-
-    return data?.map(item => this.mapFromDatabase(item)) || [];
-  }
-
-  /**
-   * Delete template
-   */
-  async deleteTemplate(id: string): Promise<boolean> {
-    const { error } = await this.supabase
-      .from(this.templatesTable)
-      .delete()
-      .eq('id', id);
-
-    if (error) {
-      throw new Error(`Failed to delete template: ${error.message}`);
-    }
-
-    return true;
-  }
-
-  /**
-   * Log email delivery
-   */
-  async logEmailDelivery(log: {
-    templateName: string;
-    recipientEmail: string;
-    messageId?: string;
-    success: boolean;
-    error?: string;
-    metadata?: any;
-  }): Promise<void> {
-    const { error } = await this.supabase
-      .from(this.logsTable)
-      .insert([
-        {
-          template_name: log.templateName,
-          recipient_email: log.recipientEmail,
-          message_id: log.messageId,
-          success: log.success,
-          error_message: log.error,
-          sent_at: new Date().toISOString(),
-          metadata: log.metadata,
-        },
-      ]);
-
-    if (error) {
-      console.error('Failed to log email delivery:', error);
-      // Don't throw error for logging failures
-    }
-  }
-
-  /**
-   * Update email delivery status from webhook
-   */
-  async updateDeliveryStatus(
-    messageId: string,
-    status: string,
-    deliveredAt?: Date,
-    webhookData?: any
-  ): Promise<void> {
-    const { error } = await this.supabase
-      .from(this.logsTable)
-      .update({
-        delivery_status: status,
-        delivered_at: deliveredAt?.toISOString(),
-        webhook_data: webhookData,
-      })
-      .eq('message_id', messageId);
-
-    if (error) {
-      console.error('Failed to update delivery status:', error);
-      // Don't throw error for logging failures
-    }
-  }
-
-  /**
-   * Get email delivery logs
-   */
-  async getDeliveryLogs(filters?: {
-    templateName?: string;
-    recipientEmail?: string;
-    success?: boolean;
-    limit?: number;
-    offset?: number;
-  }): Promise<any[]> {
-    let query = this.supabase.from(this.logsTable).select('*');
-
-    if (filters) {
-      if (filters.templateName) {
-        query = query.eq('template_name', filters.templateName);
-      }
-
-      if (filters.recipientEmail) {
-        query = query.eq('recipient_email', filters.recipientEmail);
-      }
-
-      if (filters.success !== undefined) {
-        query = query.eq('success', filters.success);
-      }
-
-      if (filters.limit) {
-        query = query.limit(filters.limit);
-      }
-
-      if (filters.offset) {
-        query = query.range(filters.offset, filters.offset + (filters.limit || 50) - 1);
-      }
-    }
-
-    const { data, error } = await query.order('sent_at', { ascending: false });
-
-    if (error) {
-      throw new Error(`Failed to get delivery logs: ${error.message}`);
-    }
-
-    return data || [];
-  }
-
-  /**
-   * Map database row to EmailTemplate
-   */
-  private mapFromDatabase(data: any): EmailTemplate {
-    return {
-      id: data.id,
-      name: data.name,
-      subject: data.subject,
-      htmlBody: data.html_body,
-      textBody: data.text_body,
-      variables: data.variables || [],
-      categoryId: data.category_id,
-      tags: data.tags || [],
-      isActive: data.is_active,
-      version: data.version,
-      createdAt: data.created_at ? new Date(data.created_at) : undefined,
-      updatedAt: data.updated_at ? new Date(data.updated_at) : undefined,
-      createdBy: data.created_by,
-      metadata: data.metadata,
-    };
-  }
-}