@wildo-ai/saas-backend-lib 1.0.1

package/src/notifications/email/services/email.backend.service.ts

@@ -0,0 +1,429 @@
+/**
+ * Email Backend Service
+ *
+ * Main service for sending emails. Orchestrates:
+ * - File-based template resolution via EmailTemplateRegistryBackendService
+ * - Context building
+ * - React Email rendering (subject fn + body fn → HTML/text)
+ * - Provider resolution and HTTP execution
+ */
+
+import { injectable, inject } from 'inversify';
+import { render } from '@react-email/render';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import type { CapabilityBindingsBackendService } from '~wildo-backend-lib/external-providers/services/feature-bindings.backend.service';
+import type { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import type { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';
+import type { EmailContextProviderRegistryBackendService } from './email-context-provider-registry.backend.service';
+import type { EmailTemplateRegistryBackendService } from './email-template-registry.backend.service';
+import { buildEmailBrandTokensFromConfig, type EmailBrandTokens } from '~wildo-backend-lib/notifications/email/utils/color-conversion.utils';
+import {
+  EmailTemplateContext,
+  EmailTemplateType_ToEngineCapability,
+  EmailTemplateType,
+  EngineCapability,
+  ErrorType,
+  isWildoBackendError,
+  WildoHeaderKeys,
+} from '@wildo-ai/saas-models';
+import { EmailFeature } from '@wildo-ai/external-connectors';
+import type {
+  StandardEmail_SendRequest,
+  StandardEmail_SendResponse,
+} from '@wildo-ai/external-connectors-models';
+import { ExternalProvider_ExchangeProtocol_Kind } from '@wildo-ai/external-connectors-models';
+import { AvailableLanguage } from '@wildo-ai/presets-components-models';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UTILITIES
+// ─────────────────────────────────────────────────────────────────────────────
+
+function validateEmailAddresses(emails: string[]): string[] {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emails.filter(email => !emailRegex.test(email.trim()));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface EmailSendRequest {
+  /** Template reference (e.g., "system.welcome_email") */
+  templateRef: string;
+  /** Locale for template selection */
+  locale: AvailableLanguage;
+  /** Email type for provider routing */
+  type: EmailTemplateType;
+  /** Primary recipient email(s) */
+  to: string | string[];
+  /** CC recipients (optional) */
+  cc?: string[];
+  /** BCC recipients (optional) */
+  bcc?: string[];
+  /** Reply-to address (optional) */
+  replyTo?: string;
+  /** From address (optional - uses provider default if not specified) */
+  from?: string;
+  /** Context for template rendering */
+  context: EmailTemplateContext;
+  /** File IDs for attachments (optional) */
+  attachmentFileIds?: string[];
+  /** Organization ID for org-scoped templates (optional) */
+  organizationId?: string;
+}
+
+export interface EmailSendResult {
+  success: boolean;
+  messageId?: string;
+  providerId?: string;
+  error?: string;
+  templateRef: string;
+  recipientCount: number;
+}
+
+interface EmailProviderConfig {
+  providerId: string;
+  apiKey: string;
+  fromAddress?: string;
+  fromName?: string;
+}
+
+interface EmailAddress {
+  email: string;
+  name?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SERVICE
+// ─────────────────────────────────────────────────────────────────────────────
+
+@injectable()
+export class EmailBackendService {
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.EmailTemplateRegistry) private readonly templateRegistry: EmailTemplateRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.EmailContextProviderRegistry) private readonly contextProviderRegistry: EmailContextProviderRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.CapabilityBindingsService) private readonly capabilityBindings: CapabilityBindingsBackendService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly configService: AppConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService) private readonly externalProvidersRegistry: ExternalProvidersRegistryBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('EmailBackendService');
+    this.logger.setDebugTypeLogging('EmailBackendService', false);
+  }
+
+  /**
+   * Send an email using a file-based template definition.
+   */
+  async send(request: EmailSendRequest): Promise<EmailSendResult> {
+    const startTime = Date.now();
+    this.logger.info('Sending email', {
+      templateRef: request.templateRef,
+      locale: request.locale,
+      recipientCount: Array.isArray(request.to) ? request.to.length : 1,
+    });
+
+    try {
+      // 0. Validate email addresses
+      const recipients = Array.isArray(request.to) ? request.to : [request.to];
+      const allEmails = [
+        ...recipients,
+        ...(request.cc || []),
+        ...(request.bcc || []),
+        ...(request.replyTo ? [request.replyTo] : []),
+      ];
+
+      const invalidEmails = validateEmailAddresses(allEmails);
+      if (invalidEmails.length > 0) {
+        throw this.errorBuilder.buildError(
+          ErrorType.VALIDATION,
+          undefined,
+          {
+            context: {
+              message: `Invalid email address format: ${invalidEmails.join(', ')}`,
+              invalidEmails,
+            },
+          },
+        );
+      }
+
+      // 1. Resolve template + labels from file-based registry
+      const defaultLocale = this.getDefaultLocale();
+      const resolved = this.templateRegistry.resolve(request.templateRef, request.locale, defaultLocale);
+
+      // 2. Get design tokens
+      const brandTokens = this.getDesignTokens();
+
+      // 3. Build additional context from providers
+      const additionalContext = await this.contextProviderRegistry.buildAdditionalContext(
+        {
+          templateRef: request.templateRef,
+          locale: request.locale,
+          baseContext: request.context,
+        },
+        this.createProviderUtils(),
+      );
+
+      // 4. Build full context
+      const fullContext: EmailTemplateContext = {
+        currentObject: request.context.currentObject,
+        objectContext: request.context.objectContext,
+        userContext: request.context.userContext,
+        additionalContext: {
+          ...(request.context.additionalContext as Record<string, unknown> || {}),
+          ...additionalContext,
+        },
+      };
+
+      // 5. Render subject and body from definition functions
+      const templateProps = { context: fullContext, brand: brandTokens, labels: resolved.labels };
+      const subject = resolved.definition.subject(templateProps);
+      const bodyElement = resolved.definition.body(templateProps);
+
+      const bodyHtml = await render(bodyElement, { pretty: true });
+      const bodyText = await render(bodyElement, { plainText: true });
+
+      // 6. Resolve provider
+      const emailType = resolved.definition.type ?? request.type;
+      const engineCapability = EmailTemplateType_ToEngineCapability[emailType];
+      const providerConfig = this.resolveEmailProvider(engineCapability);
+
+      // 7. Build email request
+      const emailRequest = this.buildEmailRequest(request, { subject, bodyHtml, bodyText }, providerConfig, recipients);
+
+      // 8. Execute send via provider
+      const response = await this.executeProviderRequest(providerConfig, emailRequest);
+
+      const durationMs = Date.now() - startTime;
+      this.logger.info('Email sent successfully', {
+        templateRef: request.templateRef,
+        messageId: response.messageId,
+        providerId: providerConfig.providerId,
+        durationMs,
+      });
+
+      return {
+        success: true,
+        messageId: response.messageId,
+        providerId: providerConfig.providerId,
+        templateRef: request.templateRef,
+        recipientCount: recipients.length,
+      };
+    } catch (err) {
+      const error = err as Error;
+      const durationMs = Date.now() - startTime;
+
+      this.logger.error('Email send failed', {
+        templateRef: request.templateRef,
+        errorMessage: error.message,
+        durationMs,
+      });
+
+      if (isWildoBackendError(err) && (err.type === ErrorType.CONFIGURATION || err.type === ErrorType.VALIDATION)) {
+        throw err;
+      }
+
+      return {
+        success: false,
+        error: error.message,
+        templateRef: request.templateRef,
+        recipientCount: Array.isArray(request.to) ? request.to.length : 1,
+      };
+    }
+  }
+
+  /**
+   * Send email to multiple recipients individually (different context per recipient).
+   */
+  async sendToMultiple(requests: EmailSendRequest[]): Promise<EmailSendResult[]> {
+    const results: EmailSendResult[] = [];
+    for (const request of requests) {
+      const result = await this.send(request);
+      results.push(result);
+    }
+    return results;
+  }
+
+  private getDefaultLocale(): string {
+    try {
+      const appConfig = this.configService.config as Record<string, unknown>;
+      return (appConfig?.defaultLanguage as string) || 'en';
+    } catch {
+      return 'en';
+    }
+  }
+
+  private getDesignTokens(): EmailBrandTokens {
+    try {
+      return buildEmailBrandTokensFromConfig(this.configService.config.email?.brandTokens);
+    } catch (err) {
+      this.logger.warn('Failed to extract design tokens, using defaults', {
+        errorMessage: (err as Error).message,
+      });
+      return buildEmailBrandTokensFromConfig(undefined);
+    }
+  }
+
+  private resolveEmailProvider(capability: EngineCapability): EmailProviderConfig {
+    const providerId = this.capabilityBindings.getPrimaryProviderForCapability(capability);
+
+    if (!providerId) {
+      throw this.errorBuilder.buildError(
+        ErrorType.CONFIGURATION,
+        undefined,
+        { context: { message: `No email provider configured for capability: ${capability}`, capability } },
+      );
+    }
+
+    const apiKey = this.externalProvidersRegistry.getProviderApiKey(
+      providerId,
+      ExternalProvider_ExchangeProtocol_Kind.EMAIL_PROVIDER,
+    );
+    if (!apiKey) {
+      throw this.errorBuilder.buildError(
+        ErrorType.CONFIGURATION,
+        undefined,
+        { context: { message: `No env-provided API key configured for provider: ${providerId}`, providerId, capability } },
+      );
+    }
+
+    const appConfig = this.configService.config as Record<string, unknown>;
+    const providersConfig = appConfig?.externalProvidersConfigurations as Record<string, {
+      fromAddress?: string;
+      fromName?: string;
+    }> | undefined;
+    const providerConfig = providersConfig?.[providerId];
+
+    return {
+      providerId,
+      apiKey,
+      fromAddress: providerConfig?.fromAddress,
+      fromName: providerConfig?.fromName,
+    };
+  }
+
+  private buildEmailRequest(
+    request: EmailSendRequest,
+    rendered: { subject: string; bodyHtml: string; bodyText: string },
+    providerConfig: EmailProviderConfig,
+    recipients: string[],
+  ): StandardEmail_SendRequest {
+    const toAddresses: EmailAddress[] = recipients.map(email => ({ email }));
+
+    const from: EmailAddress = {
+      email: request.from || providerConfig.fromAddress || 'noreply@example.com',
+      name: providerConfig.fromName,
+    };
+
+    return {
+      from,
+      to: toAddresses,
+      cc: request.cc?.map(email => ({ email })),
+      bcc: request.bcc?.map(email => ({ email })),
+      replyTo: request.replyTo ? { email: request.replyTo } : undefined,
+      subject: rendered.subject,
+      html: rendered.bodyHtml,
+      text: rendered.bodyText,
+    } as StandardEmail_SendRequest;
+  }
+
+  private async executeProviderRequest(
+    providerConfig: EmailProviderConfig,
+    request: StandardEmail_SendRequest,
+  ): Promise<StandardEmail_SendResponse> {
+    const transformResult = EmailFeature.transformSendEmail(
+      providerConfig.providerId,
+      request,
+    );
+
+    if (!transformResult.success) {
+      throw this.errorBuilder.buildError(
+        ErrorType.EXTERNAL_SERVICE,
+        undefined,
+        { context: { message: `Failed to transform email request for provider: ${providerConfig.providerId}`, providerId: providerConfig.providerId } },
+      );
+    }
+
+    const { payload, endpoint } = transformResult.data;
+
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        [WildoHeaderKeys.CONTENT_TYPE]: 'application/json',
+        [WildoHeaderKeys.AUTHORIZATION]: `Bearer ${providerConfig.apiKey}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw this.errorBuilder.buildError(
+        ErrorType.EXTERNAL_SERVICE,
+        undefined,
+        {
+          context: {
+            message: `Email provider returned error: ${response.status}`,
+            providerId: providerConfig.providerId,
+            status: response.status,
+            body: errorBody.substring(0, 500),
+          },
+        },
+      );
+    }
+
+    const responseData = await response.json();
+
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key.toLowerCase()] = value;
+    });
+
+    const parseResult = EmailFeature.parseSendEmailResponse(
+      providerConfig.providerId,
+      responseData,
+      request,
+      responseHeaders,
+    );
+
+    if (!parseResult.success) {
+      const errorMessage = 'error' in parseResult ? String((parseResult as { error: unknown }).error) : 'Unknown error';
+      throw this.errorBuilder.buildError(
+        ErrorType.EXTERNAL_SERVICE,
+        undefined,
+        { context: { message: `Failed to parse email response: ${errorMessage}`, providerId: providerConfig.providerId } },
+      );
+    }
+
+    return parseResult.data;
+  }
+
+  private createProviderUtils() {
+    return {
+      getRepository: <T>(resourceType: string): T => {
+        throw new Error(`getRepository('${resourceType}') is not available in the email context provider. Inject repository data via additionalContext instead.`);
+      },
+      logger: {
+        debug: (message: string, meta?: Record<string, unknown>) =>
+          this.logger.debug(message, meta),
+        info: (message: string, meta?: Record<string, unknown>) =>
+          this.logger.info(message, meta),
+        warn: (message: string, meta?: Record<string, unknown>) =>
+          this.logger.warn(message, meta),
+        error: (message: string, meta?: Record<string, unknown>) =>
+          this.logger.error(message, meta),
+      },
+      errorBuilder: {
+        buildError: (type: string, message: string, details?: Record<string, unknown>) => {
+          const err = new Error(message);
+          (err as Error & { type: string; details: unknown }).type = type;
+          (err as Error & { type: string; details: unknown }).details = details;
+          return err;
+        },
+      },
+    };
+  }
+}

package/src/notifications/email/utils/color-conversion.utils.ts

@@ -0,0 +1,142 @@
+/**
+ * Color Conversion Utilities
+ * 
+ * Utilities for converting colors between formats for email compatibility.
+ * Email clients don't support OKLCH, so we need to convert to Hex.
+ */
+
+import { oklch, formatHex, Oklch } from 'culori';
+
+/**
+ * Convert an OKLCH color string to Hex
+ * 
+ * @param oklchColor - OKLCH color string (e.g., "oklch(0.7 0.15 180)")
+ * @returns Hex color string (e.g., "#4fa3a3")
+ */
+export function oklchToHex(oklchColor: string): string {
+  try {
+    // Parse the OKLCH color
+    const parsed = oklch(oklchColor);
+    
+    if (!parsed) {
+      // If parsing fails, try to extract values manually
+      const match = oklchColor.match(/oklch\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*\)/i);
+      if (match) {
+        const color: Oklch = {
+          mode: 'oklch',
+          l: parseFloat(match[1]),
+          c: parseFloat(match[2]),
+          h: parseFloat(match[3]),
+        };
+        return formatHex(color) || '#000000';
+      }
+      return '#000000';
+    }
+    
+    // Convert to Hex
+    const hex = formatHex(parsed);
+    return hex || '#000000';
+  } catch {
+    // Silently return fallback - color conversion failures are non-critical
+    // Caller can log if needed, but we return a safe default
+    return '#000000';
+  }
+}
+
+/**
+ * Check if a color string is in OKLCH format
+ */
+export function isOklchColor(color: string): boolean {
+  return color.toLowerCase().startsWith('oklch(');
+}
+
+/**
+ * Convert any color to hex format
+ * Handles OKLCH, rgb, hsl, and passes through hex
+ */
+export function toHexColor(color: string): string {
+  if (!color) return '#000000';
+  
+  // Already hex
+  if (color.startsWith('#')) {
+    return color;
+  }
+  
+  // OKLCH
+  if (isOklchColor(color)) {
+    return oklchToHex(color);
+  }
+  
+  // Try culori for other formats
+  try {
+    const hex = formatHex(color);
+    return hex || '#000000';
+  } catch {
+    return '#000000';
+  }
+}
+
+/**
+ * Email Brand Tokens structure (hex colors)
+ */
+export interface EmailBrandTokens {
+  primaryColor: string;
+  primaryForeground: string;
+  secondaryColor: string;
+  backgroundColor: string;
+  foregroundColor: string;
+  mutedColor: string;
+  mutedForeground: string;
+  borderColor: string;
+  successColor: string;
+  warningColor: string;
+  destructiveColor: string;
+  borderRadius: string;
+  fontFamily: string;
+  headingFontFamily?: string;
+}
+
+/**
+ * Default email design tokens (fallback values)
+ */
+export const DEFAULT_EMAIL_DESIGN_TOKENS: EmailBrandTokens = {
+  primaryColor: '#0066cc',
+  primaryForeground: '#ffffff',
+  secondaryColor: '#6c757d',
+  backgroundColor: '#ffffff',
+  foregroundColor: '#1a1a1a',
+  mutedColor: '#f5f5f5',
+  mutedForeground: '#6c757d',
+  borderColor: '#e5e5e5',
+  successColor: '#22c55e',
+  warningColor: '#f59e0b',
+  destructiveColor: '#ef4444',
+  borderRadius: '0.5rem',
+  fontFamily: 'Arial, Helvetica, sans-serif',
+  headingFontFamily: 'Arial, Helvetica, sans-serif',
+};
+
+/**
+ * Build full `EmailBrandTokens` from the simplified `email.brandTokens` config.
+ * Merges provided values with `DEFAULT_EMAIL_DESIGN_TOKENS`.
+ */
+export function buildEmailBrandTokensFromConfig(
+  brandTokens?: {
+    primaryColor?: string;
+    secondaryColor?: string;
+    fontFamily?: string;
+    logoUrl?: string;
+  },
+): EmailBrandTokens {
+  if (!brandTokens) return { ...DEFAULT_EMAIL_DESIGN_TOKENS };
+
+  return {
+    ...DEFAULT_EMAIL_DESIGN_TOKENS,
+    ...(brandTokens.primaryColor && { primaryColor: toHexColor(brandTokens.primaryColor) }),
+    ...(brandTokens.secondaryColor && { secondaryColor: toHexColor(brandTokens.secondaryColor) }),
+    ...(brandTokens.fontFamily && {
+      fontFamily: brandTokens.fontFamily,
+      headingFontFamily: brandTokens.fontFamily,
+    }),
+  };
+}

package/src/notifications/email/utils/interpolate-email-label.utils.ts

@@ -0,0 +1,16 @@
+/**
+ * Replace `{placeholder}` tokens in email label strings.
+ *
+ * Translators can reorder clauses and words; placeholders stay semantic
+ * (`{appName}`, `{firstName}`, …) so each locale controls word order.
+ */
+export function interpolateEmailLabel(
+  template: string,
+  params: Record<string, string | number | undefined | null>,
+): string {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) => {
+    const v = params[key];
+    if (v === undefined || v === null) return match;
+    return String(v);
+  });
+}