@lobehub/lobehub 2.0.0-next.124 → 2.0.0-next.125

package/src/server/services/email/README.md

@@ -0,0 +1,241 @@
+# Email Service
+
+A flexible email service implementation supporting multiple email providers.
+
+## Architecture
+
+Based on the search service pattern, this service provides a unified interface for sending emails across different providers.
+
+```plaintext
+EmailService
+  └── EmailServiceImpl (interface)
+      └── NodemailerImpl (SMTP provider)
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { EmailService } from '@/server/services/email';
+
+const emailService = new EmailService();
+
+// Send a simple text email
+await emailService.sendMail({
+  from: 'noreply@example.com',
+  to: 'user@example.com',
+  subject: 'Welcome to LobeChat',
+  text: 'Thanks for signing up!',
+  html: '<p>Thanks for signing up!</p>',
+});
+```
+
+### With Multiple Recipients
+
+```typescript
+await emailService.sendMail({
+  from: 'team@example.com',
+  to: ['user1@example.com', 'user2@example.com'],
+  subject: 'Team Update',
+  text: 'Check out our latest updates',
+});
+```
+
+### With Attachments
+
+```typescript
+await emailService.sendMail({
+  from: 'support@example.com',
+  to: 'user@example.com',
+  subject: 'Your Invoice',
+  text: 'Please find your invoice attached.',
+  attachments: [
+    {
+      filename: 'invoice.pdf',
+      path: '/path/to/invoice.pdf',
+    },
+  ],
+});
+```
+
+### With Reply-To Address
+
+```typescript
+await emailService.sendMail({
+  from: 'noreply@example.com',
+  replyTo: 'support@example.com',
+  to: 'user@example.com',
+  subject: 'Contact Us',
+  text: 'Reply to this email for support.',
+});
+```
+
+## Configuration
+
+### Environment Variables
+
+Configure SMTP settings using environment variables:
+
+```bash
+# SMTP Server Configuration
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_SECURE=false # true for port 465, false for other ports
+SMTP_USER=your-username
+SMTP_PASS=your-password
+```
+
+### Using Well-Known Services
+
+You can also use well-known email services (Gmail, SendGrid, etc.):
+
+```typescript
+import { EmailImplType, EmailService } from '@/server/services/email';
+import { NodemailerImpl } from '@/server/services/email/impls/nodemailer';
+
+const emailService = new EmailService(EmailImplType.Nodemailer);
+// Configure in constructor with service name
+```
+
+### Testing with Ethereal
+
+For development and testing, use [Ethereal Email](https://ethereal.email/):
+
+```typescript
+// The preview URL will be logged automatically in development
+const result = await emailService.sendMail({...});
+console.log('Preview URL:', result.previewUrl);
+```
+
+## Verify Connection
+
+Before sending emails, verify your SMTP configuration:
+
+```typescript
+import { EmailService } from '@/server/services/email';
+
+const emailService = new EmailService();
+
+try {
+  await emailService.verify();
+  console.log('SMTP connection verified ✓');
+} catch (error) {
+  console.error('SMTP verification failed:', error);
+}
+```
+
+## Integration with Better-Auth
+
+Example integration for email verification:
+
+```typescript
+import { betterAuth } from 'better-auth';
+
+import { EmailService } from '@/server/services/email';
+
+export const auth = betterAuth({
+  emailAndPassword: {
+    enabled: true,
+    sendResetPasswordEmail: async ({ user, url }) => {
+      const emailService = new EmailService();
+
+      await emailService.sendMail({
+        from: 'noreply@lobechat.com',
+        to: user.email,
+        subject: 'Reset Your Password',
+        text: `Click here to reset your password: ${url}`,
+        html: `
+          <h1>Reset Your Password</h1>
+          <p>Click the link below to reset your password:</p>
+          <a href="${url}">Reset Password</a>
+        `,
+      });
+    },
+  },
+  emailVerification: {
+    enabled: true,
+    sendVerificationEmail: async ({ user, url }) => {
+      const emailService = new EmailService();
+
+      await emailService.sendMail({
+        from: 'noreply@lobechat.com',
+        to: user.email,
+        subject: 'Verify Your Email',
+        text: `Click here to verify your email: ${url}`,
+        html: `
+          <h1>Verify Your Email</h1>
+          <p>Click the link below to verify your email address:</p>
+          <a href="${url}">Verify Email</a>
+        `,
+      });
+    },
+  },
+});
+```
+
+## Adding New Providers
+
+To add a new email provider (e.g., Resend, SendGrid):
+
+1. Create provider implementation in `impls/[provider-name]/index.ts`:
+
+```typescript
+import { EmailPayload, EmailResponse, EmailServiceImpl } from '../type';
+
+export class ResendImpl implements EmailServiceImpl {
+  async sendMail(payload: EmailPayload): Promise<EmailResponse> {
+    // Implement using Resend API
+  }
+}
+```
+
+2. Add to the enum in `impls/index.ts`:
+
+```typescript
+export enum EmailImplType {
+  Nodemailer = 'nodemailer',
+  Resend = 'resend', // Add new provider
+}
+```
+
+3. Update factory function in `impls/index.ts`:
+
+```typescript
+export const createEmailServiceImpl = (type: EmailImplType) => {
+  switch (type) {
+    case EmailImplType.Nodemailer:
+      return new NodemailerImpl();
+    case EmailImplType.Resend:
+      return new ResendImpl();
+    default:
+      return new NodemailerImpl();
+  }
+};
+```
+
+## Error Handling
+
+The service throws `TRPCError` for various failure scenarios:
+
+```typescript
+try {
+  await emailService.sendMail({...});
+} catch (error) {
+  if (error.code === 'SERVICE_UNAVAILABLE') {
+    // Handle SMTP connection issues
+  } else if (error.code === 'PRECONDITION_FAILED') {
+    // Handle configuration errors
+  }
+}
+```
+
+## Debugging
+
+Enable debug logging:
+
+```bash
+DEBUG=lobe-email:* node your-app.js
+```
+
+This will log detailed information about email sending operations.

package/src/server/services/email/impls/index.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { EmailImplType, createEmailServiceImpl } from './index';
+
+vi.mock('./nodemailer', () => ({
+  NodemailerImpl: vi.fn().mockImplementation(() => ({
+    sendMail: vi.fn().mockResolvedValue({ messageId: 'test-id' }),
+    verify: vi.fn().mockResolvedValue(true),
+  })),
+}));
+
+describe('createEmailServiceImpl', () => {
+  it('should create NodemailerImpl by default', () => {
+    const impl = createEmailServiceImpl();
+
+    expect(impl).toBeDefined();
+    expect(impl.sendMail).toBeDefined();
+  });
+
+  it('should create NodemailerImpl when explicitly specified', () => {
+    const impl = createEmailServiceImpl(EmailImplType.Nodemailer);
+
+    expect(impl).toBeDefined();
+    expect(impl.sendMail).toBeDefined();
+  });
+
+  it('should fall back to NodemailerImpl for unknown type', () => {
+    const impl = createEmailServiceImpl('unknown' as EmailImplType);
+
+    expect(impl).toBeDefined();
+    expect(impl.sendMail).toBeDefined();
+  });
+});
+
+describe('EmailImplType enum', () => {
+  it('should have Nodemailer as a valid type', () => {
+    expect(EmailImplType.Nodemailer).toBe('nodemailer');
+  });
+});

package/src/server/services/email/impls/index.ts

@@ -0,0 +1,32 @@
+import { NodemailerImpl } from './nodemailer';
+import { EmailServiceImpl } from './type';
+
+/**
+ * Available email service implementations
+ */
+export enum EmailImplType {
+  Nodemailer = 'nodemailer',
+  // Future providers can be added here:
+  // Resend = 'resend',
+  // SendGrid = 'sendgrid',
+}
+
+/**
+ * Create an email service implementation instance
+ */
+export const createEmailServiceImpl = (
+  type: EmailImplType = EmailImplType.Nodemailer,
+): EmailServiceImpl => {
+  switch (type) {
+    case EmailImplType.Nodemailer: {
+      return new NodemailerImpl();
+    }
+
+    default: {
+      return new NodemailerImpl();
+    }
+  }
+};
+
+export type { EmailServiceImpl } from './type';
+export type { EmailPayload, EmailResponse } from './type';

package/src/server/services/email/impls/nodemailer/index.ts

@@ -0,0 +1,108 @@
+import { TRPCError } from '@trpc/server';
+import debug from 'debug';
+import nodemailer from 'nodemailer';
+import type { Transporter } from 'nodemailer';
+
+import { emailEnv } from '@/envs/email';
+
+import { EmailPayload, EmailResponse, EmailServiceImpl } from '../type';
+import { NodemailerConfig } from './type';
+
+const log = debug('lobe-email:Nodemailer');
+
+/**
+ * Nodemailer implementation of the email service
+ */
+export class NodemailerImpl implements EmailServiceImpl {
+  private transporter: Transporter;
+
+  constructor() {
+    log('Initializing Nodemailer from environment variables');
+
+    if (!emailEnv.SMTP_USER || !emailEnv.SMTP_PASS) {
+      throw new Error(
+        'SMTP_USER and SMTP_PASS environment variables are required to use email service. Please configure SMTP settings in your .env file.',
+      );
+    }
+
+    const transportConfig: NodemailerConfig = {
+      auth: {
+        pass: emailEnv.SMTP_PASS,
+        user: emailEnv.SMTP_USER,
+      },
+      host: emailEnv.SMTP_HOST ?? 'localhost',
+      port: emailEnv.SMTP_PORT ?? 587,
+      secure: emailEnv.SMTP_SECURE ?? false,
+    };
+
+    try {
+      this.transporter = nodemailer.createTransport(transportConfig);
+      log('Nodemailer transporter created successfully');
+    } catch (error) {
+      log.extend('error')('Failed to create Nodemailer transporter: %o', error);
+      throw new TRPCError({
+        cause: error,
+        code: 'INTERNAL_SERVER_ERROR',
+        message: 'Failed to initialize Nodemailer transport',
+      });
+    }
+  }
+
+  async sendMail(payload: EmailPayload): Promise<EmailResponse> {
+    // Use SMTP_USER as default sender if not provided
+    const from = payload.from ?? emailEnv.SMTP_USER!;
+
+    log('Sending email with payload: %o', {
+      from,
+      subject: payload.subject,
+      to: payload.to,
+    });
+
+    try {
+      const info = await this.transporter.sendMail({
+        attachments: payload.attachments,
+        from,
+        html: payload.html,
+        replyTo: payload.replyTo,
+        subject: payload.subject,
+        text: payload.text,
+        to: payload.to,
+      });
+
+      log('Email sent successfully with message ID: %s', info.messageId);
+
+      const previewUrl = nodemailer.getTestMessageUrl(info);
+
+      return {
+        messageId: info.messageId,
+        previewUrl: previewUrl || undefined,
+      };
+    } catch (error) {
+      log.extend('error')('Failed to send email: %o', error);
+      throw new TRPCError({
+        cause: error,
+        code: 'SERVICE_UNAVAILABLE',
+        message: `Failed to send email: ${(error as Error).message}`,
+      });
+    }
+  }
+
+  /**
+   * Verify the SMTP connection configuration
+   */
+  async verify(): Promise<boolean> {
+    try {
+      log('Verifying SMTP connection...');
+      await this.transporter.verify();
+      log('SMTP connection verified successfully');
+      return true;
+    } catch (error) {
+      log.extend('error')('SMTP verification failed: %o', error);
+      throw new TRPCError({
+        cause: error,
+        code: 'SERVICE_UNAVAILABLE',
+        message: 'Failed to verify SMTP connection',
+      });
+    }
+  }
+}

package/src/server/services/email/impls/nodemailer/type.ts

@@ -0,0 +1,31 @@
+/**
+ * Nodemailer SMTP transport configuration
+ */
+export interface NodemailerConfig {
+  /**
+   * Authentication credentials
+   */
+  auth?: {
+    pass: string;
+    user: string;
+  };
+  /**
+   * SMTP server hostname
+   */
+  host?: string;
+  /**
+   * SMTP server port
+   * @default 587
+   */
+  port?: number;
+  /**
+   * Use TLS connection
+   * @default false
+   */
+  secure?: boolean;
+  /**
+   * Well-known service name (e.g., 'Gmail', 'SendGrid')
+   * When set, overrides host, port, and secure
+   */
+  service?: string;
+}

package/src/server/services/email/impls/type.ts

@@ -0,0 +1,61 @@
+/**
+ * Email message payload
+ */
+export interface EmailPayload {
+  /**
+   * Email attachments
+   */
+  attachments?: Array<{
+    content?: Buffer | string;
+    filename?: string;
+    path?: string;
+  }>;
+  /**
+   * Sender address (defaults to SMTP_USER if not provided)
+   */
+  from?: string;
+  /**
+   * HTML body of the email
+   */
+  html?: string;
+  /**
+   * Reply-To address
+   */
+  replyTo?: string;
+  /**
+   * Subject line
+   */
+  subject: string;
+  /**
+   * Plain text body of the email
+   */
+  text?: string;
+  /**
+   * Recipient address(es)
+   */
+  to: string | string[];
+}
+
+/**
+ * Email send response
+ */
+export interface EmailResponse {
+  /**
+   * Message ID assigned by the email service
+   */
+  messageId: string;
+  /**
+   * Preview URL for test emails (e.g., Ethereal)
+   */
+  previewUrl?: string;
+}
+
+/**
+ * Email service implementation interface
+ */
+export interface EmailServiceImpl {
+  /**
+   * Send an email
+   */
+  sendMail(payload: EmailPayload): Promise<EmailResponse>;
+}

package/src/server/services/email/index.test.ts

@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { EmailImplType, createEmailServiceImpl } from './impls';
+import { EmailService } from './index';
+
+// Mock dependencies
+vi.mock('./impls');
+
+describe('EmailService', () => {
+  let emailService: EmailService;
+  let mockEmailImpl: ReturnType<typeof createMockEmailImpl>;
+
+  function createMockEmailImpl() {
+    return {
+      sendMail: vi.fn(),
+      verify: vi.fn(),
+    };
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockEmailImpl = createMockEmailImpl();
+    vi.mocked(createEmailServiceImpl).mockReturnValue(mockEmailImpl as any);
+    emailService = new EmailService();
+  });
+
+  describe('constructor', () => {
+    it('should create instance with default email implementation', () => {
+      expect(createEmailServiceImpl).toHaveBeenCalledWith(undefined);
+    });
+
+    it('should create instance with specified implementation type', () => {
+      emailService = new EmailService(EmailImplType.Nodemailer);
+      expect(createEmailServiceImpl).toHaveBeenCalledWith(EmailImplType.Nodemailer);
+    });
+  });
+
+  describe('sendMail', () => {
+    it('should call emailImpl.sendMail with correct payload', async () => {
+      const mockResponse = {
+        messageId: 'test-message-id',
+        previewUrl: 'https://ethereal.email/message/xxx',
+      };
+      mockEmailImpl.sendMail.mockResolvedValue(mockResponse);
+
+      const payload = {
+        from: 'sender@example.com',
+        html: '<p>Hello world</p>',
+        subject: 'Test Email',
+        text: 'Hello world',
+        to: 'recipient@example.com',
+      };
+
+      const result = await emailService.sendMail(payload);
+
+      expect(mockEmailImpl.sendMail).toHaveBeenCalledWith(payload);
+      expect(result).toBe(mockResponse);
+    });
+
+    it('should support multiple recipients', async () => {
+      const mockResponse = {
+        messageId: 'test-message-id',
+      };
+      mockEmailImpl.sendMail.mockResolvedValue(mockResponse);
+
+      const payload = {
+        from: 'sender@example.com',
+        subject: 'Test Email',
+        text: 'Hello world',
+        to: ['recipient1@example.com', 'recipient2@example.com'],
+      };
+
+      await emailService.sendMail(payload);
+
+      expect(mockEmailImpl.sendMail).toHaveBeenCalledWith(payload);
+    });
+
+    it('should support attachments', async () => {
+      const mockResponse = {
+        messageId: 'test-message-id',
+      };
+      mockEmailImpl.sendMail.mockResolvedValue(mockResponse);
+
+      const payload = {
+        attachments: [
+          {
+            content: Buffer.from('test content'),
+            filename: 'test.txt',
+          },
+        ],
+        from: 'sender@example.com',
+        subject: 'Test Email',
+        text: 'Hello world',
+        to: 'recipient@example.com',
+      };
+
+      await emailService.sendMail(payload);
+
+      expect(mockEmailImpl.sendMail).toHaveBeenCalledWith(payload);
+    });
+
+    it('should support reply-to address', async () => {
+      const mockResponse = {
+        messageId: 'test-message-id',
+      };
+      mockEmailImpl.sendMail.mockResolvedValue(mockResponse);
+
+      const payload = {
+        from: 'noreply@example.com',
+        replyTo: 'support@example.com',
+        subject: 'Test Email',
+        text: 'Hello world',
+        to: 'recipient@example.com',
+      };
+
+      await emailService.sendMail(payload);
+
+      expect(mockEmailImpl.sendMail).toHaveBeenCalledWith(payload);
+    });
+  });
+
+  describe('verify', () => {
+    it('should call emailImpl.verify if available', async () => {
+      mockEmailImpl.verify.mockResolvedValue(true);
+
+      const result = await emailService.verify();
+
+      expect(mockEmailImpl.verify).toHaveBeenCalled();
+      expect(result).toBe(true);
+    });
+
+    it('should return true if verify method is not available', async () => {
+      const mockImplWithoutVerify = {
+        sendMail: vi.fn(),
+      };
+      vi.mocked(createEmailServiceImpl).mockReturnValue(mockImplWithoutVerify as any);
+      emailService = new EmailService();
+
+      const result = await emailService.verify();
+
+      expect(result).toBe(true);
+    });
+  });
+});

package/src/server/services/email/index.ts

@@ -0,0 +1,40 @@
+
+import { EmailImplType, EmailPayload, EmailResponse, createEmailServiceImpl } from './impls';
+import type { EmailServiceImpl } from './impls';
+
+/**
+ * Email service class
+ * Provides email sending functionality with multiple provider support
+ */
+export class EmailService {
+  private emailImpl: EmailServiceImpl;
+
+  constructor(implType?: EmailImplType) {
+    this.emailImpl = createEmailServiceImpl(implType);
+  }
+
+  /**
+   * Send an email
+   */
+  async sendMail(payload: EmailPayload): Promise<EmailResponse> {
+    return this.emailImpl.sendMail(payload);
+  }
+
+  /**
+   * Verify the email service configuration
+   * Note: Only available for Nodemailer implementation
+   */
+  async verify(): Promise<boolean> {
+    // Check if the implementation has a verify method
+    if ('verify' in this.emailImpl && typeof this.emailImpl.verify === 'function') {
+      return this.emailImpl.verify();
+    }
+
+    // For implementations without verify, assume it's valid
+    return true;
+  }
+}
+
+// Export types
+export type { EmailPayload, EmailResponse } from './impls';
+export { EmailImplType } from './impls';