fraim-framework 2.0.34 → 2.0.36

package/registry/scripts/generate-engagement-emails.ts

@@ -0,0 +1,830 @@
+#!/usr/bin/env tsx
+
+/**
+ * Engagement Email Functions for AI Agents
+ * 
+ * Helper functions for AI agents to use in customer engagement workflows.
+ * Provides deterministic functions for issue retrieval, database lookup, and email sending.
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { MongoClient } from 'mongodb';
+import { join } from 'path';
+
+// Self-contained utility functions (no FRAIM internal imports)
+function determineDatabaseName(): string {
+  const env = process.env.NODE_ENV || process.env.ENVIRONMENT;
+  // If explicitly set to ppe/staging, use that; otherwise default to prod
+  if (env === 'ppe' || env === 'staging') {
+    return 'fraim_ppe';
+  }
+  // Default to production
+  return process.env.MONGO_DB_NAME || 'fraim_prod';
+}
+
+function determineSchema(branchName: string): string {
+  if (branchName.includes('ppe') || branchName.includes('staging')) return 'ppe';
+  return 'prod';
+}
+
+function getCurrentGitBranch(): string {
+  try {
+    return execSync('git branch --show-current', { encoding: 'utf8' }).trim();
+  } catch (error) {
+    return 'master';
+  }
+}
+
+interface FraimConfig {
+  persona: { name: string; displayNamePattern: string; emailSignature: string };
+  git: { repoOwner: string; repoName: string };
+  database: { identityCollection: string; executiveCollection: string };
+  marketing: { websiteUrl?: string; chatUrl?: string };
+}
+
+function loadClientConfig(): FraimConfig {
+  const configPath = join(process.cwd(), '.fraim', 'config.json');
+  if (!existsSync(configPath)) {
+    throw new Error('.fraim/config.json not found. Run fraim init first.');
+  }
+  return JSON.parse(readFileSync(configPath, 'utf-8'));
+}
+
+function getEnvOr(keys: string[], fallback: string): string {
+  for (const key of keys) {
+    const value = process.env[key];
+    if (value && value.length) return value;
+  }
+  return fallback;
+}
+
+// Load configuration
+const config = loadClientConfig();
+const personaName = config.persona.name;
+const personaDisplayNameDefault = config.persona.displayNamePattern.replace('{executiveName}', 'Your');
+
+const fraimConfig = {
+  repoOwner: config.git.repoOwner || 'mathursrus',
+  repoName: config.git.repoName || 'fraim-repo',
+  projectName: 'FRAIM',
+  personaName,
+  personaPronouns: getEnvOr(['FRAIM_PERSONA_PRONOUNS'], 'they/them'),
+  personaDisplayName: getEnvOr(['FRAIM_PERSONA_DISPLAY_NAME'], personaDisplayNameDefault),
+  personaDisplayNamePattern: config.persona.displayNamePattern,
+  personaThankYouSignature: config.persona.emailSignature,
+  defaultEmail: getEnvOr(['FRAIM_DEFAULT_EMAIL'], 'agent@example.com'),
+  prodDefaultEmail: getEnvOr(['PROD_FRAIM_DEFAULT_EMAIL'], 'agent@example.com'),
+  defaultAccessToken: getEnvOr(['FRAIM_DEFAULT_ACCESS_TOKEN'], ''),
+  defaultRefreshToken: getEnvOr(['FRAIM_DEFAULT_REFRESH_TOKEN'], ''),
+  prodAccessToken: getEnvOr(['PROD_FRAIM_DEFAULT_ACCESS_TOKEN'], ''),
+  prodRefreshToken: getEnvOr(['PROD_FRAIM_DEFAULT_REFRESH_TOKEN'], ''),
+  defaultOAuthClientId: getEnvOr(['FRAIM_DEFAULT_OAUTH_CLIENT_ID'], ''),
+  defaultOAuthClientSecret: getEnvOr(['FRAIM_DEFAULT_OAUTH_CLIENT_SECRET'], ''),
+  prodOAuthClientId: getEnvOr(['PROD_FRAIM_DEFAULT_OAUTH_CLIENT_ID'], ''),
+  prodOAuthClientSecret: getEnvOr(['PROD_FRAIM_DEFAULT_OAUTH_CLIENT_SECRET'], ''),
+  identityCollection: config.database?.identityCollection || 'Identity',
+  executiveCollection: config.database?.executiveCollection || 'Executive',
+  newsletterTitle: 'Weekly Update',
+  newsletterCtaText: 'Learn More',
+  newsletterUrl: getEnvOr(['FRAIM_NEWSLETTER_URL'], ''),
+  issueRepoUrl: `https://github.com/${config.git.repoOwner}/${config.git.repoName}.git`,
+  identityTokensCollection: 'Tokens',
+  webAppUrl: config.marketing?.websiteUrl || getEnvOr(['FRAIM_WEB_APP_URL'], 'http://localhost:3000'),
+  chatUrl: config.marketing?.chatUrl || getEnvOr(['FRAIM_CHAT_URL'], ''),
+};
+
+function formatExecutiveDisplayName(executiveName: string): string {
+  return config.persona.displayNamePattern.replace('{executiveName}', executiveName);
+}
+
+function formatPersonaSignature(): string {
+  return `With gratitude,\n${fraimConfig.personaThankYouSignature}\n${personaName} - Your AI Executive Assistant\n\n`;
+}
+
+// Get template path (relative to script location)
+function getTemplatePath(): string {
+  // Script is at <this-path>
+  // Template is at templates/customer-development/thank-you-email-template.html (Retrieve via get_fraim_file)
+  // Or generic path? Let's keep existing path logic but relative to process.cwd() as before
+  return join(process.cwd(), 'registry', 'templates', 'customer-development', 'thank-you-email-template.html');
+}
+
+interface ResolvedIssue {
+  number: number;
+  title: string;
+  body: string;
+  closed_at: string;
+  user: {
+    login: string;
+  };
+  labels: Array<{
+    name: string;
+  }>;
+}
+
+interface Executive {
+  id?: string;        // Executive ID (used in the identity collection)
+  _id?: string | any; // MongoDB ObjectId (may be present but we use 'id')
+  email: string;
+  name: string;
+  personaAccessToken?: string;
+  personaRefreshToken?: string;
+}
+
+/**
+ * Get the latest date from existing thank-you candidates files
+ * Returns the most recent date when thank-you emails were sent, or null if no files exist
+ */
+export function getLatestThankYouDate(): string | null {
+  const notesDir = 'docs/customer-development/thank-you-notes';
+  if (!existsSync(notesDir)) {
+    return null;
+  }
+
+  const files = readdirSync(notesDir).filter(f => f.startsWith('thank-you-candidates-') && f.endsWith('.json'));
+  if (files.length === 0) {
+    return null;
+  }
+
+  // Extract dates from filenames (e.g., thank-you-candidates-2025-10-29.json)
+  const dates: string[] = [];
+  for (const file of files) {
+    const dateMatch = file.match(/thank-you-candidates-(\d{4}-\d{2}-\d{2})\.json/);
+    if (dateMatch) {
+      const filePath = join(notesDir, file);
+      try {
+        const content = readFileSync(filePath, 'utf-8');
+        const json = JSON.parse(content);
+
+        // Check if any candidates have status "sent"
+        const hasSentEmails = json.candidates?.some((c: any) => c.status === 'sent');
+        if (hasSentEmails) {
+          dates.push(dateMatch[1]);
+        }
+      } catch (error) {
+        // Skip invalid JSON files
+        console.warn(`⚠️  Could not parse ${file}:`, error);
+      }
+    }
+  }
+
+  if (dates.length === 0) {
+    return null;
+  }
+
+  // Return the most recent date
+  dates.sort();
+  const latestDate = dates[dates.length - 1];
+  console.log(`📅 Latest thank-you date found: ${latestDate}`);
+  return latestDate;
+}
+
+/**
+ * Get resolved issues since a specified date (or latest thank-you date if not provided)
+ * AI agents call this to retrieve issues that were resolved
+ * @param date Optional date string (YYYY-MM-DD). If not provided, uses latest thank-you date. If no thank-you files exist, uses last 14 days.
+ */
+export async function getResolvedIssues(date?: string): Promise<ResolvedIssue[]> {
+  if (!date) {
+    // Try to get the latest thank-you date
+    const latestThankYouDate = getLatestThankYouDate();
+    if (latestThankYouDate) {
+      date = latestThankYouDate;
+      console.log(`📋 Using latest thank-you date as starting point: ${date}`);
+    } else {
+      // Fallback to last 14 days if no thank-you files exist
+      const fallbackDate = new Date(Date.now() - 14 * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+      date = fallbackDate;
+      console.log(`📋 No previous thank-you files found, using last 14 days: ${date}`);
+    }
+  }
+
+  // Use ">YYYY-MM-DD" format to get issues updated AFTER the date (not on the date)
+  // GitHub CLI requires quotes around the comparison operator
+  const command = `gh search issues --repo=${fraimConfig.repoOwner}/${fraimConfig.repoName} --state=closed --updated=">${date}" --label=user-reported --json number,title,body,labels,closedAt,author`;
+  const output = execSync(command, { encoding: 'utf-8' });
+  return JSON.parse(output);
+}
+
+function getProductionDatabase() {
+  const mongoUrl = process.env.PROD_MONGO_DATABASE_URL || process.env.MONGO_DATABASE_URL;
+  if (!mongoUrl) {
+    throw new Error('PROD_MONGO_DATABASE_URL or MONGO_DATABASE_URL environment variable is required');
+  }
+  return new MongoClient(mongoUrl);
+}
+
+/**
+ * Get database name, defaulting to production
+ */
+function getDatabaseName(): string {
+  const env = process.env.NODE_ENV || process.env.ENVIRONMENT;
+  // If explicitly set to ppe/staging, use that; otherwise default to prod
+  if (env === 'ppe' || env === 'staging') {
+    return determineDatabaseName();
+  }
+  // Default to production
+  return process.env.MONGO_DB_NAME || 'fraim_prod';
+}
+
+/**
+ * Get collection name with schema prefix (defaults to prod schema)
+ */
+function getCollectionName(baseName: string): string {
+  const env = process.env.NODE_ENV || process.env.ENVIRONMENT;
+  // If explicitly set to ppe/staging, use that schema; otherwise default to prod
+  if (env === 'ppe' || env === 'staging') {
+    const schema = determineSchema(getCurrentGitBranch());
+    return `${schema}_${baseName}`;
+  }
+  // Default to prod schema
+  return `prod_${baseName}`;
+}
+
+/**
+ * Find executive by email in database (defaults to production)
+ * AI agents call this to get executive info for database lookups
+ */
+export async function findExecutiveByEmail(email: string): Promise<Executive | null> {
+  const client = getProductionDatabase();
+  try {
+    await client.connect();
+    const dbName = getDatabaseName();
+    const db = client.db(dbName);
+    const executive = await db.collection(getCollectionName('Executive')).findOne({ email: email.toLowerCase() });
+    return executive as unknown as Executive;
+  } finally {
+    await client.close();
+  }
+}
+
+/**
+ * Get the persona email for an executive from the identity collection
+ * AI agents call this to get tokens or contact info for the executive's assistant
+ */
+export async function getPersonaEmailForExecutive(executiveId: string): Promise<string> {
+  const { MongoClient } = await import('mongodb');
+  const mongoUrl = process.env.PROD_MONGO_DATABASE_URL || process.env.MONGO_DATABASE_URL;
+  if (!mongoUrl) {
+    console.warn(`⚠️  PROD_MONGO_DATABASE_URL not set, using default ${fraimConfig.personaName} email`);
+    return fraimConfig.defaultEmail;
+  }
+
+  const client = new MongoClient(mongoUrl);
+  try {
+    await client.connect();
+    const dbName = getDatabaseName();
+    const db = client.db(dbName);
+    const collectionName = getCollectionName(fraimConfig.identityCollection);
+
+    // Query the identity collection (defaults to prod)
+    let identity = await db.collection(collectionName).findOne({
+      executive_id: executiveId,
+      status: 'active'
+    });
+
+    if (!identity) {
+      identity = await db.collection(collectionName).findOne({
+        executive_id: executiveId
+      });
+    }
+
+    if (identity && identity.email) {
+      return identity.email;
+    }
+
+    return fraimConfig.defaultEmail;
+  } catch (error) {
+    console.warn(`⚠️  Could not get ${fraimConfig.personaName} email for executive ${executiveId}:`, error);
+    return fraimConfig.defaultEmail;
+  } finally {
+    await client.close();
+  }
+}
+
+interface Improvement {
+  title: string;
+  description: string;
+  verification?: string;
+}
+
+interface Candidate {
+  customer: { name: string; email: string };
+  executive: { name: string; id?: string };
+  status: 'pending' | 'sent' | 'failed';
+  from: { displayName: string; email: string };
+  to: string;
+  subject: string;
+  // Structured format (preferred)
+  greeting?: string;
+  opening?: string;
+  improvements?: Improvement[];
+  closing?: string;
+  // Legacy format (fallback for backward compatibility)
+  body?: string;
+}
+
+interface CandidatesFile {
+  metadata: {
+    generatedOn: string;
+    issuesResolvedSince: string;
+    totalCustomers: number;
+    totalIssues: number;
+  };
+  candidates: Candidate[];
+}
+/**
+ * Send emails from candidates file (JSON format)
+ * AI agents call this after user review to send all emails
+ * @param candidatesFilePath Path to the JSON candidates file
+ * @param executiveId Optional executive ID to filter emails to specific executive only
+ */
+export async function sendCustomerMail(candidatesFilePath: string, executiveId?: string): Promise<void> {
+  if (!existsSync(candidatesFilePath)) {
+    throw new Error(`Candidates file not found: ${candidatesFilePath}`);
+  }
+
+  console.log(`📧 Sending emails from candidates file: ${candidatesFilePath}`);
+  if (executiveId) {
+    console.log(`🎯 Filtering to executive ID: ${executiveId}`);
+  }
+
+  const content = readFileSync(candidatesFilePath, 'utf-8');
+  const candidatesFile: CandidatesFile = JSON.parse(content);
+
+  console.log(`📊 Found ${candidatesFile.candidates.length} candidates (${candidatesFile.metadata.totalCustomers} customers)`);
+
+  // Filter candidates if executiveId is provided
+  let candidatesToSend = candidatesFile.candidates;
+  if (executiveId) {
+    candidatesToSend = candidatesFile.candidates.filter(candidate =>
+      candidate.executive.id === executiveId
+    );
+    console.log(`🔍 Filtered to ${candidatesToSend.length} candidate(s) for executive ${executiveId}`);
+
+    if (candidatesToSend.length === 0) {
+      console.log(`⚠️  No candidates found for executive ID: ${executiveId}`);
+      return;
+    }
+  }
+
+  // Update file with results as we send
+  const updatedCandidates = [...candidatesFile.candidates];
+
+  for (let i = 0; i < updatedCandidates.length; i++) {
+    const candidate = updatedCandidates[i];
+
+    // Skip if filtering by executive ID and this candidate doesn't match
+    if (executiveId && candidate.executive.id !== executiveId) {
+      continue;
+    }
+
+    if (candidate.status !== 'pending') {
+      console.log(`⏭️  Skipping ${candidate.customer.email} (status: ${candidate.status})`);
+      continue;
+    }
+
+    try {
+      console.log(`📧 Sending email to ${candidate.customer.email}...`);
+
+      // Get executive from database if we have their email
+      const executive = await findExecutiveByEmail(candidate.customer.email);
+
+      // Get persona tokens from identity collection if the executive is known
+      let personaTokens: { access_token?: string; refresh_token?: string } | null = null;
+      if (candidate.executive.id) {
+        try {
+          const client = getProductionDatabase();
+          try {
+            await client.connect();
+            const dbName = getDatabaseName();
+            const db = client.db(dbName);
+            const collectionName = getCollectionName(fraimConfig.identityCollection);
+
+            const identity = await db.collection(collectionName).findOne({
+              executive_id: candidate.executive.id,
+              status: 'active'
+            }) || await db.collection(collectionName).findOne({
+              executive_id: candidate.executive.id
+            });
+
+            if (identity && identity.access_token && identity.refresh_token) {
+              personaTokens = {
+                access_token: identity.access_token,
+                refresh_token: identity.refresh_token
+              };
+              console.log(`Found ${fraimConfig.personaName} tokens in ${dbName} database for ${candidate.from.email}`);
+            } else {
+              console.warn(`No ${fraimConfig.personaName} tokens found in ${dbName} database for executive ${candidate.executive.id}`);
+            }
+          } finally {
+            await client.close();
+          }
+        } catch (error) {
+          console.warn(`Could not get ${fraimConfig.personaName} tokens from database for executive ${candidate.executive.id}:`, error);
+        }
+      }
+      // Generate plain text body for fallback (from structured format if available)
+      const plainTextBody = generatePlainTextBody(candidate);
+
+      await sendSingleEmail({
+        to: candidate.to,
+        subject: candidate.subject,
+        body: plainTextBody,
+        fromEmail: candidate.from.email,
+        fromDisplayName: candidate.from.displayName,
+        candidate // Pass full candidate for HTML generation
+      }, executive, personaTokens);
+
+      console.log(`✅ Email sent to ${candidate.customer.email}`);
+      updatedCandidates[i].status = 'sent';
+
+      // Update file after each successful send
+      const updatedFile: CandidatesFile = {
+        ...candidatesFile,
+        candidates: updatedCandidates
+      };
+      writeFileSync(candidatesFilePath, JSON.stringify(updatedFile, null, 2));
+
+    } catch (error) {
+      console.error(`❌ Failed to send email to ${candidate.customer.email}:`, error);
+      updatedCandidates[i].status = 'failed';
+
+      // Update file with failure status
+      const updatedFile: CandidatesFile = {
+        ...candidatesFile,
+        candidates: updatedCandidates
+      };
+      writeFileSync(candidatesFilePath, JSON.stringify(updatedFile, null, 2));
+    }
+  }
+
+  console.log(`\n✅ Email sending complete. Status updated in ${candidatesFilePath}`);
+
+  // Exit cleanly to prevent hanging
+  process.exit(0);
+}
+
+interface SendEmailParams {
+  to: string;
+  subject: string;
+  body: string;
+  fromEmail: string;
+  fromDisplayName: string;
+  candidate?: Candidate; // Optional: for structured HTML generation
+}
+
+async function sendSingleEmail(
+  params: SendEmailParams,
+  executive?: Executive | null,
+  personaTokens?: { access_token?: string; refresh_token?: string } | null
+): Promise<void> {
+  const { to, subject, body, fromEmail, fromDisplayName } = params;
+
+  // Get Persona's tokens - prioritize identity tokens, then executive tokens, then default
+  let accessToken: string;
+  let refreshToken: string;
+
+  if (personaTokens?.access_token && personaTokens?.refresh_token) {
+    // Use persona identity tokens (preferred - ensures correct From address)
+    console.log(`🔑 Using ${fraimConfig.personaName} identity tokens for ${fromEmail}`);
+    accessToken = personaTokens.access_token;
+    refreshToken = personaTokens.refresh_token;
+  } else if (executive?.personaAccessToken && executive?.personaRefreshToken) {
+    // Fallback to executive-specific tokens
+    console.log(`🔑 Using executive persona tokens as fallback`);
+    accessToken = executive.personaAccessToken;
+    refreshToken = executive.personaRefreshToken;
+  } else {
+    // Use default persona tokens as last resort
+    console.log(`🔑 Using default ${fraimConfig.personaName} tokens as fallback`);
+    accessToken = fraimConfig.defaultAccessToken;
+    refreshToken = fraimConfig.defaultRefreshToken;
+
+    if (!accessToken || !refreshToken) {
+      throw new Error(`${fraimConfig.personaName} Gmail tokens not found. Need either identity tokens, executive tokens, or default tokens in environment variables.`);
+    }
+  }
+
+  // Verify the From email matches the authenticated account (Gmail requirement)
+  // For plus addressing, the base email should match
+  const fromBaseEmail = fromEmail.includes('+')
+    ? fromEmail.split('+')[0] + '@' + fromEmail.split('@')[1]
+    : fromEmail;
+
+  console.log(`📧 Sending from: "${fromDisplayName}" <${fromEmail}>`);
+
+  // Generate HTML email from template (use structured format if available)
+  const greeting = params.candidate?.greeting || 'Hi there,';
+  const htmlBody = generateHtmlEmail({
+    displayName: extractFirstName(greeting) || extractFirstName(body) || extractFirstName(fromDisplayName) || 'there',
+    greeting: greeting,
+    opening: params.candidate?.opening
+      ? convertTextToHtml(params.candidate.opening)
+      : convertBodyToHtml(body), // Fallback to legacy body
+    improvements: params.candidate?.improvements || [],
+    closing: params.candidate?.closing || '',
+    executiveName: extractExecutiveName(fromDisplayName),
+    fromEmail
+  });
+
+  // Create multipart email message (plain text + HTML)
+  const boundary = `boundary_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  const emailMessage = [
+    `To: ${to}`,
+    `From: ${fromDisplayName} <${fromEmail}>`,
+    `Subject: ${subject}`,
+    `Content-Type: multipart/alternative; boundary="${boundary}"`,
+    `MIME-Version: 1.0`,
+    ``,
+    `--${boundary}`,
+    `Content-Type: text/plain; charset=utf-8`,
+    `Content-Transfer-Encoding: 7bit`,
+    ``,
+    body,
+    ``,
+    `--${boundary}`,
+    `Content-Type: text/html; charset=utf-8`,
+    `Content-Transfer-Encoding: 7bit`,
+    ``,
+    htmlBody,
+    ``,
+    `--${boundary}--`
+  ].join('\r\n');
+
+  // Send email using Gmail API
+  const url = 'https://gmail.googleapis.com/gmail/v1/users/me/messages/send';
+  const requestBody = {
+    raw: Buffer.from(emailMessage).toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '')
+  };
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(requestBody)
+  });
+
+  if (!response.ok) {
+    if (response.status === 401) {
+      console.log('🔄 Access token expired, refreshing...');
+
+      // Refresh the access token
+      const clientId = fraimConfig.defaultOAuthClientId || process.env.FRAIM_DEFAULT_OAUTH_CLIENT_ID || process.env.PERSONA_DEFAULT_OAUTH_CLIENT_ID;
+      const clientSecret = fraimConfig.defaultOAuthClientSecret || process.env.FRAIM_DEFAULT_OAUTH_CLIENT_SECRET || process.env.PERSONA_DEFAULT_OAUTH_CLIENT_SECRET;
+
+      if (!clientId || !clientSecret) {
+        throw new Error('FRAIM_DEFAULT_OAUTH_CLIENT_ID and FRAIM_DEFAULT_OAUTH_CLIENT_SECRET environment variables are required for token refresh');
+      }
+
+      console.log('🔄 Refreshing token...');
+
+      const refreshResponse = await fetch('https://oauth2.googleapis.com/token', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: new URLSearchParams({
+          client_id: clientId,
+          client_secret: clientSecret,
+          refresh_token: refreshToken,
+          grant_type: 'refresh_token'
+        })
+      });
+
+      if (!refreshResponse.ok) {
+        const errorText = await refreshResponse.text();
+        console.error('❌ Token refresh failed:', refreshResponse.status, errorText);
+        throw new Error(`Failed to refresh access token: ${refreshResponse.status} - ${errorText}`);
+      }
+
+      const tokenData = await refreshResponse.json() as any;
+      const newAccessToken = tokenData.access_token;
+
+      console.log('✅ Token refreshed, retrying email send...');
+
+      // Retry with new token
+      const retryResponse = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${newAccessToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(requestBody)
+      });
+
+      if (!retryResponse.ok) {
+        const errorText = await retryResponse.text();
+        throw new Error(`Gmail API error after refresh: ${retryResponse.status} - ${errorText}`);
+      }
+
+      const result = await retryResponse.json() as any;
+      console.log(`✅ Email sent successfully to ${to}`);
+      console.log(`📧 Email ID: ${result.id}`);
+      return;
+    }
+    const errorText = await response.text();
+    throw new Error(`Gmail API error: ${response.status} - ${errorText}`);
+  }
+
+  const result = await response.json() as any;
+  console.log(`✅ Email sent successfully to ${to}`);
+  console.log(`📧 Email ID: ${result.id}`);
+}
+/**
+ * Generate HTML email from template
+ */
+function generateHtmlEmail(params: {
+  displayName: string;
+  greeting: string;
+  opening: string;
+  improvements: Improvement[];
+  closing: string;
+  executiveName: string;
+  fromEmail: string;
+}): string {
+  const templatePath = getTemplatePath();
+  let template = readFileSync(templatePath, 'utf-8');
+
+  // Replace simple template variables
+  template = template.replace(/\{\{displayName\}\}/g, escapeHtml(params.displayName));
+  template = template.replace(/\{\{executiveName\}\}/g, escapeHtml(params.executiveName));
+  template = template.replace(/\{\{personaName\}\}/g, escapeHtml(fraimConfig.personaName));
+  template = template.replace(/\{\{chatUrl\}\}/g, escapeHtml(fraimConfig.chatUrl || '#'));
+  template = template.replace(/\{\{webAppUrl\}\}/g, escapeHtml(fraimConfig.webAppUrl || '#'));
+  template = template.replace(/\{\{fromEmail\}\}/g, escapeHtml(params.fromEmail));
+  template = template.replace(/\{\{greeting\}\}/g, escapeHtml(params.greeting));
+  template = template.replace(/\{\{opening\}\}/g, params.opening);
+
+  // Generate improvements list HTML
+  const hasImprovements = params.improvements && params.improvements.length > 0;
+  if (hasImprovements) {
+    const improvementsHtml = params.improvements.map((improvement, index) => {
+      let html = `<div style="margin-bottom: ${index < params.improvements.length - 1 ? '20px' : '0'}; padding-bottom: ${index < params.improvements.length - 1 ? '20px' : '0'}; border-bottom: ${index < params.improvements.length - 1 ? '1px solid #e9ecef' : 'none'};">`;
+      html += `<div style="font-size: 16px; font-weight: 600; color: #333333; margin-bottom: 8px;">${escapeHtml(improvement.title)}</div>`;
+      html += `<div style="font-size: 15px; color: #555555; line-height: 1.7; margin-bottom: ${improvement.verification ? '10px' : '0'};">${convertTextToHtml(improvement.description)}</div>`;
+      if (improvement.verification) {
+        html += `<div style="font-size: 14px; color: #667eea; font-style: italic; padding-top: 8px; border-top: 1px solid #e9ecef; margin-top: 8px;">💡 <strong>How to verify:</strong> ${convertTextToHtml(improvement.verification)}</div>`;
+      }
+      html += `</div>`;
+      return html;
+    }).join('');
+
+    const improvementsSection = `
+                    <tr>
+                        <td style="padding: 0 30px 20px 30px;">
+                            <div style="background-color: #f8f9fa; border-left: 4px solid #667eea; border-radius: 6px; padding: 20px; margin: 20px 0;">
+                                <div style="font-size: 18px; font-weight: 600; color: #333333; margin-bottom: 16px;">
+                                    ✨ What's Fixed
+                                </div>
+                                ${improvementsHtml}
+                            </div>
+                        </td>
+                    </tr>`;
+    template = template.replace(/\{\{#if hasImprovements\}\}[\s\S]*?\{\{\/if\}\}/, improvementsSection);
+  } else {
+    // Remove conditional block if no improvements
+    template = template.replace(/\{\{#if hasImprovements\}\}[\s\S]*?\{\{\/if\}\}/, '');
+  }
+
+  // Replace closing paragraph
+  if (params.closing) {
+    template = template.replace(/\{\{#if closing\}\}[\s\S]*?\{\{\/if\}\}/, `
+                    <tr>
+                        <td style="padding: 0 30px 20px 30px;">
+                            <div style="font-size: 16px; color: #555555; line-height: 1.8;">
+                                ${convertTextToHtml(params.closing)}
+                            </div>
+                        </td>
+                    </tr>`);
+  } else {
+    template = template.replace(/\{\{#if closing\}\}[\s\S]*?\{\{\/if\}\}/, '');
+  }
+
+  return template;
+}
+
+/**
+ * Generate plain text body from candidate (supports both structured and legacy formats)
+ */
+function generatePlainTextBody(candidate: Candidate): string {
+  // If structured format exists, use it
+  if (candidate.greeting && candidate.opening) {
+    let body = `${candidate.greeting}\n\n${candidate.opening}\n\n`;
+
+    if (candidate.improvements && candidate.improvements.length > 0) {
+      body += `**What was improved:**\n\n`;
+      candidate.improvements.forEach((improvement, index) => {
+        body += `${index + 1}. ${improvement.title}: ${improvement.description}`;
+        if (improvement.verification) {
+          body += `\n   **How to verify:** ${improvement.verification}`;
+        }
+        body += `\n\n`;
+      });
+    }
+
+    if (candidate.closing) {
+      body += `${candidate.closing}\n\n`;
+    }
+
+    body += formatPersonaSignature();
+
+    return body;
+  }
+
+  // Fallback to legacy body format
+  return candidate.body || '';
+}
+
+/**
+ * Extract first name from text
+ */
+function extractFirstName(text: string): string | null {
+  // Try to find "Hi [Name]" pattern
+  const hiMatch = text.match(/\b[Hh]i\s+([A-Z][a-z]+)/);
+  if (hiMatch) {
+    return hiMatch[1];
+  }
+
+  // Try to find comma after greeting
+  const commaMatch = text.match(/^[Hh]i\s+([^,]+),/);
+  if (commaMatch) {
+    return commaMatch[1].trim().split(' ')[0];
+  }
+
+  return null;
+}
+
+/**
+ * Extract executive name from display name
+ */
+function extractExecutiveName(displayName: string): string {
+  // "{Persona} - [Name]'s AI Executive Assistant"
+  // We need to match based on the configured pattern
+  const pattern = fraimConfig.personaDisplayNamePattern.replace('{executiveName}', '(.+?)');
+
+  try {
+    // If pattern contains regex characters, they need expanding or escaping?
+    // This is simple pattern matching.
+    // Example: "Persona - {executiveName}'s AI Executive Assistant"
+    // Regex: /Persona - (.+?)'s AI Executive Assistant/
+    // We escape special chars except the group we added
+    const escapedPattern = pattern
+      .replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // Escape regex chars
+      .replace('\\(\\.+\\?\\)', '(.+?)'); // Restore capture group
+
+    const match = displayName.match(new RegExp(escapedPattern));
+    return match ? match[1] : 'Your';
+  } catch (e) {
+    return 'Your';
+  }
+}
+
+/**
+ * Convert plain text to HTML (for legacy body format)
+ */
+function convertBodyToHtml(body: string): string {
+  return convertTextToHtml(body);
+}
+
+/**
+ * Convert text to HTML (preserves markdown-style formatting)
+ */
+function convertTextToHtml(text: string): string {
+  if (!text) return '';
+
+  let html = text;
+
+  // Convert markdown-style bold **text** to <strong>text</strong>
+  html = html.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+
+  // Convert line breaks to paragraphs
+  html = html.replace(/\n\n+/g, '</p><p style="margin: 12px 0;">');
+  html = html.replace(/\n/g, '<br>');
+
+  // Wrap in paragraph tags
+  html = `<p style="margin: 0 0 12px 0;">${html}</p>`;
+
+  // Clean up empty paragraphs
+  html = html.replace(/<p[^>]*><\/p>/g, '');
+
+  return html;
+}
+
+/**
+ * Escape HTML special characters
+ */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}