@wildo-ai/saas-backend-lib 1.0.1

package/src/notifications/email/services/email-template-generation.backend.service.ts

@@ -0,0 +1,811 @@
+/**
+ * Email Template Generation Backend Service
+ *
+ * Responsible for LLM-based email template generation.
+ * Uses the flows-actors agent pattern for LLM invocation.
+ */
+
+import { injectable, inject } from 'inversify';
+import { z } from 'zod';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { AgentsBackendService } from '~wildo-backend-lib/flows-actors/services/agents.backend.service';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { EmailTemplateValidatorBackendService } from './email-template-validator.backend.service';
+import { EmailTemplateCompilerBackendService } from './email-template-compiler.backend.service';
+import { buildEmailBrandTokensFromConfig, DEFAULT_EMAIL_DESIGN_TOKENS, type EmailBrandTokens } from '~wildo-backend-lib/notifications/email/utils/color-conversion.utils';
+import { serializeZodSchemaToTypeScript } from '~wildo-backend-lib/notifications/email/utils/zod-to-typescript.utils';
+import { EMAIL_TEMPLATE_ALLOWED_IMPORTS } from './email-template-validator.backend.service';
+
+// Import engine types
+import {
+  CoreResourceType,
+  ErrorType,
+  ErrorCustomMessageReference,
+  FlowsActors_Agent_Invocation,
+  CoreUserNotificationChannel,
+  EmailTemplateSchema,
+  EmailTemplate,
+  EmailTemplateStatus,
+  EmailTemplateGenerationSource,
+  EmailTemplateType,
+  EmailTemplateFrequency,
+  EmailTemplateScope,
+  SystemEmailTemplateRef,
+  SystemEmailTemplateRegistry,
+} from '@wildo-ai/saas-models';
+import { AvailableLanguage } from '@wildo-ai/presets-components-models';
+import {
+  LLMProvider_GenerateTextInputSchema,
+  LLMProvider_GenerateTextOutputSchema,
+  LLMProvider_OperationContext_BaseSchema,
+  LLMProvider_FinishReason,
+} from '@wildo-ai/external-connectors-models';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Type Definitions
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface EmailTemplateGenerationOptions {
+  /** Force regenerate even if template exists */
+  forceRegenerate?: boolean;
+  /** Specific template refs to generate (empty = all) */
+  templateRefs?: string[];
+  /** Specific locales to generate (empty = all configured) */
+  locales?: AvailableLanguage[];
+}
+
+export interface EmailTemplateGenerationResultDetail {
+  templateRef: string;
+  locale: AvailableLanguage;
+  success: boolean;
+  templateId?: string;
+  errors?: string[];
+  durationMs?: number;
+}
+
+export interface EmailTemplateGenerationResult {
+  generated: number;
+  failed: number;
+  details: EmailTemplateGenerationResultDetail[];
+  startedAt: Date;
+  completedAt: Date;
+}
+
+export interface EmailTemplateGenerationContext {
+  appName: string;
+  appDescription?: string;
+  logoUrl?: string;
+  designTokens: EmailBrandTokens;
+  availableComponents: PredefinedEmailComponent[];
+  allowedImports: string[];
+  /** Resource schemas for context typing, keyed by resource type */
+  resourceSchemas: Map<string, string>;
+}
+
+export interface PredefinedEmailComponent {
+  name: string;
+  importPath: string;
+  description: string;
+  props: Array<{
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+  }>;
+  example: string;
+}
+
+interface GeneratedTemplateOutput {
+  tsxSource: string;
+  subjectTemplate: string;
+  designRationale?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Predefined Email Components (LLM Context)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const PREDEFINED_EMAIL_COMPONENTS: PredefinedEmailComponent[] = [
+  {
+    name: 'EmailLayout',
+    importPath: '@wildo-ai/email-components',
+    description: 'Main email layout wrapper with header/footer support',
+    props: [
+      { name: 'children', type: 'React.ReactNode', required: true, description: 'Email body content' },
+      { name: 'brand', type: 'EmailBrandTokens', required: true, description: 'Brand design tokens' },
+      { name: 'header', type: 'React.ReactNode', required: false, description: 'Custom header' },
+      { name: 'footer', type: 'React.ReactNode', required: false, description: 'Custom footer' },
+    ],
+    example: '<EmailLayout brand={__brand}>{/* content */}</EmailLayout>',
+  },
+  {
+    name: 'PrimaryButton',
+    importPath: '@wildo-ai/email-components',
+    description: 'Primary call-to-action button with brand colors',
+    props: [
+      { name: 'href', type: 'string', required: true, description: 'Button link URL' },
+      { name: 'children', type: 'React.ReactNode', required: true, description: 'Button text' },
+      { name: 'brand', type: 'EmailBrandTokens', required: true, description: 'Brand design tokens' },
+    ],
+    example: '<PrimaryButton href={loginUrl} brand={__brand}>Get Started</PrimaryButton>',
+  },
+  {
+    name: 'SecondaryButton',
+    importPath: '@wildo-ai/email-components',
+    description: 'Secondary action button with muted styling',
+    props: [
+      { name: 'href', type: 'string', required: true },
+      { name: 'children', type: 'React.ReactNode', required: true },
+      { name: 'brand', type: 'EmailBrandTokens', required: true },
+    ],
+    example: '<SecondaryButton href={learnMoreUrl} brand={__brand}>Learn More</SecondaryButton>',
+  },
+  {
+    name: 'Card',
+    importPath: '@wildo-ai/email-components',
+    description: 'Content card with border and background',
+    props: [
+      { name: 'children', type: 'React.ReactNode', required: true },
+      { name: 'brand', type: 'EmailBrandTokens', required: true },
+    ],
+    example: '<Card brand={__brand}><Text>Card content</Text></Card>',
+  },
+  {
+    name: 'Divider',
+    importPath: '@wildo-ai/email-components',
+    description: 'Horizontal divider with brand border color',
+    props: [
+      { name: 'brand', type: 'EmailBrandTokens', required: true },
+    ],
+    example: '<Divider brand={__brand} />',
+  },
+  {
+    name: 'AlertBox',
+    importPath: '@wildo-ai/email-components',
+    description: 'Alert/notification box with status colors (success, warning, error, info)',
+    props: [
+      { name: 'variant', type: '"success" | "warning" | "error" | "info"', required: true },
+      { name: 'children', type: 'React.ReactNode', required: true },
+      { name: 'brand', type: 'EmailBrandTokens', required: true },
+    ],
+    example: '<AlertBox variant="success" brand={__brand}>Payment successful!</AlertBox>',
+  },
+];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Service Implementation
+// ═══════════════════════════════════════════════════════════════════════════
+
+@injectable()
+export class EmailTemplateGenerationBackendService {
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.AgentsBackendService) private readonly agentsService: AgentsBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) private readonly resourcesRegistry: ResourcesRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly configService: AppConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService) private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.EmailTemplateValidator) private readonly validator: EmailTemplateValidatorBackendService,
+    @inject(SAAS_SERVICE_TYPES.EmailTemplateCompiler) private readonly compiler: EmailTemplateCompilerBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('EmailTemplateGenerationBackendService');
+    this.logger.setDebugTypeLogging('EmailTemplateGenerationBackendService', true);
+  }
+
+  // ─── Repository Access ──────────────────────────────────────
+
+  /**
+   * Get EmailTemplate repository from RepositoriesRegistryHandler
+   */
+  private getEmailTemplateRepository() {
+    return this.repositoriesRegistry.getRepository(CoreResourceType.EMAIL_TEMPLATES);
+  }
+
+  // ─── Main Generation Flow ───────────────────────────────────
+
+  /**
+   * Generate missing email templates for all configured locales
+   *
+   * @param options - Generation options
+   * @returns Generation result with details for each template
+   */
+  public async generateMissingTemplates(
+    options: EmailTemplateGenerationOptions = {}
+  ): Promise<EmailTemplateGenerationResult> {
+    const startedAt = new Date();
+
+    this.logDebug('Starting email template generation', { options });
+
+    // 1. Get configured locales
+    const configuredLocales = this.getConfiguredLocales();
+    const targetLocales = options.locales ?? configuredLocales;
+
+    // 2. Collect all required template refs
+    const allRequiredTemplateRefs = this.collectRequiredTemplateRefs();
+    const targetRefs = options.templateRefs?.length
+      ? allRequiredTemplateRefs.filter(ref => options.templateRefs!.includes(ref))
+      : allRequiredTemplateRefs;
+
+    this.logDebug('Collected required template refs', {
+      count: targetRefs.length,
+      locales: targetLocales,
+    });
+
+    // 3. Check existing templates in DB
+    const repository = this.getEmailTemplateRepository();
+    const existingTemplates = await this.findExistingTemplates(
+      repository as any,
+      targetRefs,
+      targetLocales
+    );
+
+    // 4. Compute delta (what needs to be generated)
+    const toGenerate: Array<{ templateRef: string; locale: AvailableLanguage }> = [];
+
+    for (const ref of targetRefs) {
+      for (const locale of targetLocales) {
+        const exists = existingTemplates.some(t =>
+          t.templateRef === ref &&
+          t.locale === locale &&
+          t.status === EmailTemplateStatus.PUBLISHED
+        );
+
+        if (!exists || options.forceRegenerate) {
+          toGenerate.push({ templateRef: ref, locale });
+        }
+      }
+    }
+
+    this.logDebug('Templates to generate', { count: toGenerate.length });
+
+    if (toGenerate.length === 0) {
+      return {
+        generated: 0,
+        failed: 0,
+        details: [],
+        startedAt,
+        completedAt: new Date(),
+      };
+    }
+
+    // 5. Build generation context
+    const generationContext = this.buildGenerationContext();
+
+    // 6. Generate templates
+    const results: EmailTemplateGenerationResultDetail[] = [];
+
+    for (const { templateRef, locale } of toGenerate) {
+      const result = await this.generateSingleTemplate(
+        templateRef,
+        locale,
+        generationContext,
+        repository as any
+      );
+      results.push(result);
+    }
+
+    const completedAt = new Date();
+    const generated = results.filter(r => r.success).length;
+    const failed = results.filter(r => !r.success).length;
+
+    this.logDebug('Email template generation completed', {
+      generated,
+      failed,
+      durationMs: completedAt.getTime() - startedAt.getTime(),
+    });
+
+    return {
+      generated,
+      failed,
+      details: results,
+      startedAt,
+      completedAt,
+    };
+  }
+
+  /**
+   * Generate a single template with retry policy
+   */
+  private async generateSingleTemplate(
+    templateRef: string,
+    locale: AvailableLanguage,
+    context: EmailTemplateGenerationContext,
+    repository: any
+  ): Promise<EmailTemplateGenerationResultDetail> {
+    const startTime = Date.now();
+    const maxRetries = 5;
+    const errors: string[] = [];
+
+    this.logDebug('Generating template', { templateRef, locale });
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        // Build prompt with accumulated feedback
+        const prompt = this.buildGenerationPrompt(templateRef, locale, context, errors);
+
+        // Call LLM agent
+        const generated = await this.callGenerationAgent(prompt);
+
+        // Validate TSX
+        const validation = await this.validator.validate(generated.tsxSource);
+
+        if (!validation.valid) {
+          errors.push(`Attempt ${attempt}: Validation failed - ${validation.errors.join(', ')}`);
+          continue;
+        }
+
+        // Compile TSX → JS
+        const compiled = await this.compiler.compile(generated.tsxSource);
+
+        if (!compiled.success) {
+          errors.push(`Attempt ${attempt}: Compilation failed - ${compiled.errors.join(', ')}`);
+          continue;
+        }
+
+        // Store in DB - include applicationId for proper scoping
+        const appConfig = this.configService.config as Record<string, unknown>;
+        const applicationId = this.configService.applicationId || (appConfig._id as string);
+
+        const templateData = {
+          templateRef,
+          locale,
+          applicationId, // Required for APPLICATION-scoped resource
+          tsxSource: generated.tsxSource,
+          compiledModule: compiled.compiledCode,
+          subjectTemplate: generated.subjectTemplate,
+          ...this.getTemplateMetadata(templateRef),
+          status: EmailTemplateStatus.DRAFT,
+          generationSource: EmailTemplateGenerationSource.AGENT,
+          version: 1,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        };
+
+        const savedTemplate = await repository.create(templateData);
+
+        return {
+          templateRef,
+          locale,
+          success: true,
+          templateId: savedTemplate._id,
+          durationMs: Date.now() - startTime,
+        };
+
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        errors.push(`Attempt ${attempt}: ${errorMessage}`);
+        this.logDebug('Generation attempt failed', {
+          templateRef,
+          locale,
+          attempt,
+          error: errorMessage
+        });
+      }
+    }
+
+    // All retries failed
+    this.logger.error('Email template generation failed after all retries', {
+      templateRef,
+      locale,
+      errors,
+    });
+
+    return {
+      templateRef,
+      locale,
+      success: false,
+      errors,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  // ─── Generation Context Building ────────────────────────────
+
+  private buildGenerationContext(): EmailTemplateGenerationContext {
+    const config = this.configService.config;
+
+    const designTokens = buildEmailBrandTokensFromConfig(config.email?.brandTokens);
+
+    const appIdentity = config.appIdentity;
+
+    // Collect resource schemas for context typing
+    const resourceSchemas = this.collectResourceSchemas();
+
+    return {
+      appName: appIdentity?.displayName || appIdentity?.appName || 'Application',
+      appDescription: appIdentity?.description,
+      logoUrl: appIdentity?.logoUrl,
+      designTokens,
+      availableComponents: PREDEFINED_EMAIL_COMPONENTS,
+      allowedImports: EMAIL_TEMPLATE_ALLOWED_IMPORTS,
+      resourceSchemas,
+    };
+  }
+
+  /**
+   * Collect resource schemas and serialize them to TypeScript for LLM context
+   */
+  private collectResourceSchemas(): Map<string, string> {
+    const schemas = new Map<string, string>();
+
+    try {
+      const resourcesRegistry = this.resourcesRegistry.getResourcesRegistry();
+      const resourceConfigs = resourcesRegistry.resourceConfigurations;
+
+      for (const [resourceType, config] of Object.entries(resourceConfigs)) {
+        const mainSchema = (config as any).mainSchema;
+        if (mainSchema) {
+          try {
+            const serialized = serializeZodSchemaToTypeScript(mainSchema, resourceType);
+            schemas.set(resourceType, serialized);
+          } catch (schemaError) {
+            this.logDebug('Failed to serialize schema for resource', {
+              resourceType,
+              error: schemaError instanceof Error ? schemaError.message : String(schemaError),
+            });
+          }
+        }
+      }
+    } catch (error) {
+      this.logDebug('Failed to collect resource schemas', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    return schemas;
+  }
+
+  // ─── LLM Agent Invocation ───────────────────────────────────
+
+  /**
+   * Call the email template generation agent
+   */
+  private async callGenerationAgent(userPrompt: string): Promise<GeneratedTemplateOutput> {
+    // Combine system prompt with user prompt
+    const systemPrompt = this.getSystemPrompt();
+    const fullPrompt = `${systemPrompt}\n\n---\n\nTASK:\n${userPrompt}`;
+
+    // Build agent invocation - use simplified typing to avoid strict context requirements
+    const appConfig = this.configService.config as Record<string, unknown>;
+    const invocation = {
+      agentRef: 'email-template.generation.agent',
+      initiator: {
+        applicationId: (appConfig._id as string) || 'system',
+      },
+      invocationContext: [],
+      input: {
+        prompt: fullPrompt,
+      },
+      output: {
+        text: '',
+      },
+      executionContext: {
+        callTimestamp: new Date().toISOString(),
+        finishReason: LLMProvider_FinishReason.STOP,
+        usage: {},
+        outputTracking: {},
+      },
+      artifactBindings: [],
+    } satisfies FlowsActors_Agent_Invocation<
+      typeof LLMProvider_GenerateTextInputSchema,
+      typeof LLMProvider_GenerateTextOutputSchema,
+      typeof LLMProvider_OperationContext_BaseSchema
+    >;
+
+    // Invoke agent
+    const result = await this.agentsService.invokeAgent(invocation);
+
+    // Extract generated content
+    const output = result.output as { text: string };
+    const generatedText = output?.text;
+
+    if (!generatedText || typeof generatedText !== 'string') {
+      throw this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        undefined,
+        { context: { message: 'Email template generation returned empty output' } }
+      );
+    }
+
+    // Parse the JSON response
+    try {
+      // Try to extract JSON from the response (may be wrapped in markdown code blocks)
+      let jsonText = generatedText;
+      const jsonMatch = generatedText.match(/```(?:json)?\s*([\s\S]*?)```/);
+      if (jsonMatch) {
+        jsonText = jsonMatch[1].trim();
+      }
+
+      const parsed = JSON.parse(jsonText) as GeneratedTemplateOutput;
+
+      if (!parsed.tsxSource || !parsed.subjectTemplate) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+          context: { message: 'Missing required fields: tsxSource and subjectTemplate' },
+        });
+      }
+
+      return parsed;
+    } catch (parseError) {
+      // If not valid JSON, the model might have returned raw TSX
+      // Try to extract TSX and use a default subject
+      const tsxMatch = generatedText.match(/```(?:tsx|typescript)?\s*([\s\S]*?)```/);
+      if (tsxMatch) {
+        return {
+          tsxSource: tsxMatch[1].trim(),
+          subjectTemplate: '{{appName}} - Notification',
+        };
+      }
+
+      throw this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        undefined,
+        { context: { message: 'Failed to parse generated template output', parseError: String(parseError) } }
+      );
+    }
+  }
+
+  private getSystemPrompt(): string {
+    return `You are an expert email template developer using React Email (TSX).
+
+You create professional, responsive email templates that:
+1. Work across all major email clients (Gmail, Outlook, Apple Mail)
+2. Follow the brand guidelines provided via design tokens
+3. Use ONLY the allowed React Email components and custom components
+4. Include proper fallbacks for email client compatibility
+
+CRITICAL RULES:
+- ONLY import from: 'react', '@react-email/components', '@wildo-ai/email-components'
+- NO external API calls, NO fetch, NO async operations in the template
+- Use the provided EmailLayout component for consistent headers/footers
+- All colors must be HEX format (provided in design tokens)
+- Use inline styles only (email clients don't support external CSS)
+- The template receives a 'context' prop with: currentObject, objectContext, userContext, additionalContext
+- Design tokens are available via '__brand' global variable
+
+OUTPUT FORMAT:
+Return a JSON object with these fields:
+{
+  "tsxSource": "// The complete TSX template code starting with imports",
+  "subjectTemplate": "Subject line with {{placeholder}} syntax for variable interpolation",
+  "designRationale": "Brief explanation of design choices"
+}
+
+TEMPLATE STRUCTURE:
+import React from 'react';
+import { Text, Container, Section } from '@react-email/components';
+import { EmailLayout, PrimaryButton, Card } from '@wildo-ai/email-components';
+
+interface EmailProps {
+  context: {
+    currentObject: any;
+    objectContext: { primaryScopeContext: { appName: string; organizationName?: string } };
+    userContext: { email: string; name?: string; firstName?: string };
+    additionalContext?: Record<string, unknown>;
+  };
+}
+
+export default function EmailTemplate({ context }: EmailProps) {
+  const { currentObject, objectContext, userContext } = context;
+  // Access __brand for design tokens
+
+  return (
+    <EmailLayout brand={__brand}>
+      {/* Your email content */}
+    </EmailLayout>
+  );
+}`;
+  }
+
+  // ─── Template Ref Collection ────────────────────────────────
+
+  /**
+   * Collect all required email template refs from:
+   * 1. System templates (SystemEmailTemplateRegistry)
+   * 2. Resource operation notifications (where channel = EMAIL)
+   */
+  private collectRequiredTemplateRefs(): string[] {
+    const refs: string[] = [];
+
+    // 1. System templates from registry
+    refs.push(...Object.values(SystemEmailTemplateRef));
+
+    // 2. Resource-related templates from resources registry
+    try {
+      const resourcesRegistry = this.resourcesRegistry.getResourcesRegistry();
+      const resourceConfigs = resourcesRegistry.resourceConfigurations;
+
+      for (const [_resourceType, config] of Object.entries(resourceConfigs)) {
+        // Access operationsConfiguration which contains the operation definitions
+        const opsConfig = (config as any).operationsConfiguration || {};
+
+        for (const [_opKey, opConfig] of Object.entries(opsConfig)) {
+          // Each operation config has variants array
+          const variants = (opConfig as any).variants || [];
+
+          for (const variant of variants) {
+            const userNotifications = variant.userNotifications || [];
+
+            for (const notification of userNotifications) {
+              if (notification.channel === CoreUserNotificationChannel.EMAIL) {
+                // notification.identifier already includes customNotificationRef if present
+                const templateRef = `email.${notification.identifier}`;
+                refs.push(templateRef);
+              }
+            }
+          }
+        }
+      }
+    } catch (error) {
+      this.logDebug('Could not collect resource notification refs', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+
+    return [...new Set(refs)]; // Deduplicate
+  }
+
+  // ─── Configured Locales ────────────────────────────────────
+
+  private getConfiguredLocales(): AvailableLanguage[] {
+    const appConfig = this.configService.config;
+    const languageConfig = appConfig.appPreferences?.languages;
+
+    if (!languageConfig?.enabledLanguages?.length) {
+      return [languageConfig?.defaultLanguage ?? AvailableLanguage.EN];
+    }
+
+    return languageConfig.enabledLanguages;
+  }
+
+  // ─── Find Existing Templates ────────────────────────────────
+
+  private async findExistingTemplates(
+    repository: any,
+    templateRefs: string[],
+    locales: AvailableLanguage[]
+  ): Promise<EmailTemplate[]> {
+    try {
+      const results = await repository.find({
+        templateRef: { $in: templateRefs },
+        locale: { $in: locales },
+      });
+
+      return results as EmailTemplate[];
+    } catch (error) {
+      this.logDebug('Error finding existing templates', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return [];
+    }
+  }
+
+  // ─── Template Metadata ─────────────────────────────────────
+
+  private getTemplateMetadata(templateRef: string): {
+    type: EmailTemplateType;
+    frequency: EmailTemplateFrequency;
+    scope: EmailTemplateScope;
+    description?: string;
+  } {
+    // Check if it's a system template
+    const systemTemplate = SystemEmailTemplateRegistry[templateRef as SystemEmailTemplateRef];
+
+    if (systemTemplate) {
+      return {
+        type: systemTemplate.type,
+        frequency: systemTemplate.frequency,
+        scope: systemTemplate.scope,
+        description: systemTemplate.description,
+      };
+    }
+
+    // Default for resource-based templates
+    return {
+      type: EmailTemplateType.TRANSACTIONAL,
+      frequency: EmailTemplateFrequency.RECURRENT,
+      scope: EmailTemplateScope.APPLICATION,
+    };
+  }
+
+  // ─── Prompt Building ───────────────────────────────────────
+
+  private buildGenerationPrompt(
+    templateRef: string,
+    locale: AvailableLanguage,
+    context: EmailTemplateGenerationContext,
+    previousErrors: string[]
+  ): string {
+    const parts: string[] = [];
+
+    // Template identification
+    parts.push(`Generate an email template for: ${templateRef}`);
+    parts.push(`Target locale: ${locale}`);
+
+    // App context
+    parts.push(`\nAPP CONTEXT:`);
+    parts.push(`- App Name: ${context.appName}`);
+    if (context.appDescription) {
+      parts.push(`- Description: ${context.appDescription}`);
+    }
+
+    // Design tokens
+    parts.push(`\nDESIGN TOKENS (use via __brand global):`);
+    parts.push(JSON.stringify(context.designTokens, null, 2));
+
+    // Available components
+    parts.push(`\nAVAILABLE COMPONENTS:`);
+    for (const comp of context.availableComponents) {
+      parts.push(`- ${comp.name}: ${comp.description}`);
+      parts.push(`  Example: ${comp.example}`);
+    }
+
+    // Template-specific context
+    const metadata = this.getTemplateMetadata(templateRef);
+    parts.push(`\nTEMPLATE REQUIREMENTS:`);
+    parts.push(`- Type: ${metadata.type}`);
+    parts.push(`- Frequency: ${metadata.frequency}`);
+    parts.push(`- Scope: ${metadata.scope}`);
+    if (metadata.description) {
+      parts.push(`- Purpose: ${metadata.description}`);
+    }
+
+    // Add resource schema context for resource-based templates
+    const resourceType = this.extractResourceTypeFromTemplateRef(templateRef);
+    if (resourceType && context.resourceSchemas.has(resourceType)) {
+      parts.push(`\nRESOURCE CONTEXT (context.currentObject type):`);
+      parts.push(`The template will receive a \`currentObject\` of type \`${resourceType}\`:`);
+      parts.push('```typescript');
+      parts.push(context.resourceSchemas.get(resourceType)!);
+      parts.push('```');
+      parts.push(`Use these fields when accessing \`context.currentObject\` properties.`);
+    }
+
+    // Previous errors for retry feedback
+    if (previousErrors.length > 0) {
+      parts.push(`\nPREVIOUS ATTEMPTS FAILED:`);
+      for (const error of previousErrors) {
+        parts.push(`- ${error}`);
+      }
+      parts.push(`\nFix these issues in your response.`);
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Extract resource type from template ref for resource-based templates.
+   * Template refs follow the pattern: email.{resourceType}.{operation}.{variant}
+   * or system templates like: email.system.welcome
+   */
+  private extractResourceTypeFromTemplateRef(templateRef: string): string | null {
+    // Skip system templates
+    if (templateRef.startsWith('email.system.') || templateRef.startsWith('system.')) {
+      return null;
+    }
+
+    // Pattern: email.{RESOURCE_TYPE}.{operation}
+    const parts = templateRef.split('.');
+    if (parts.length >= 2) {
+      // Try to match against known resource types
+      const possibleResourceType = parts[1].toUpperCase();
+      try {
+        const resourcesRegistry = this.resourcesRegistry.getResourcesRegistry();
+        if (resourcesRegistry.resourceConfigurations[possibleResourceType]) {
+          return possibleResourceType;
+        }
+      } catch {
+        // Ignore - not a known resource type
+      }
+    }
+
+    return null;
+  }
+}