feat(email): implement email module and controller for sending emails (#2255)

- Added EmailModule and EmailController to handle email sending functionality.
- Introduced SendEmailDto for structured email data input.
- Updated app.module.ts to include EmailModule.
- Enhanced service-token.config.ts to allow 'email:send' permission.
- Refactored existing invitation and member management logic to utilize the new email sending capabilities.
- Implemented tests for the new email functionality.

Co-authored-by: Tofik Hasanov <annexcies@gmail.com>
Co-authored-by: Tofik Hasanov <72318342+tofikwest@users.noreply.github.com>

Author: github-actions[bot]

apps/api/src/app.module.ts

@@ -40,6 +40,7 @@ import { FrameworksModule } from './frameworks/frameworks.module';
 import { AuditModule } from './audit/audit.module';
 import { ControlsModule } from './controls/controls.module';
 import { RolesModule } from './roles/roles.module';
+import { EmailModule } from './email/email.module';
 import { SecretsModule } from './secrets/secrets.module';
 import { SecurityPenetrationTestsModule } from './security-penetration-tests/security-penetration-tests.module';
 import { StripeModule } from './stripe/stripe.module';
@@ -95,6 +96,7 @@ import { StripeModule } from './stripe/stripe.module';
     RolesModule,
     AuditModule,
     ControlsModule,
+    EmailModule,
     SecretsModule,
     SecurityPenetrationTestsModule,
     StripeModule,

apps/api/src/auth/service-token.config.ts

@@ -22,6 +22,7 @@ export const SERVICE_DEFINITIONS: Record<string, ServiceDefinition> = {
       'integration:update',
       'cloud-security:update',
       'vendor:update',
+      'email:send',
     ],
   },
   portal: {

apps/api/src/email/dto/send-email.dto.ts

@@ -0,0 +1,66 @@
+import {
+  IsString,
+  IsOptional,
+  IsArray,
+  IsBoolean,
+  ValidateNested,
+} from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+class EmailAttachmentDto {
+  @ApiProperty()
+  @IsString()
+  filename: string;
+
+  @ApiProperty()
+  @IsString()
+  content: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  contentType?: string;
+}
+
+export class SendEmailDto {
+  @ApiProperty({ description: 'Recipient email address' })
+  @IsString()
+  to: string;
+
+  @ApiProperty({ description: 'Email subject line' })
+  @IsString()
+  subject: string;
+
+  @ApiProperty({ description: 'Pre-rendered HTML content' })
+  @IsString()
+  html: string;
+
+  @ApiPropertyOptional({ description: 'Explicit FROM address override' })
+  @IsOptional()
+  @IsString()
+  from?: string;
+
+  @ApiPropertyOptional({
+    description: 'Use system sender address (RESEND_FROM_SYSTEM)',
+  })
+  @IsOptional()
+  @IsBoolean()
+  system?: boolean;
+
+  @ApiPropertyOptional({ description: 'CC recipients' })
+  @IsOptional()
+  cc?: string | string[];
+
+  @ApiPropertyOptional({ description: 'Schedule email for later delivery' })
+  @IsOptional()
+  @IsString()
+  scheduledAt?: string;
+
+  @ApiPropertyOptional({ description: 'File attachments' })
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => EmailAttachmentDto)
+  attachments?: EmailAttachmentDto[];
+}

apps/api/src/email/email.controller.ts

@@ -0,0 +1,44 @@
+import { Body, Controller, HttpCode, Post, UseGuards } from '@nestjs/common';
+import {
+  ApiOperation,
+  ApiResponse,
+  ApiSecurity,
+  ApiTags,
+} from '@nestjs/swagger';
+import { tasks } from '@trigger.dev/sdk';
+import { HybridAuthGuard } from '../auth/hybrid-auth.guard';
+import { PermissionGuard } from '../auth/permission.guard';
+import { RequirePermission } from '../auth/require-permission.decorator';
+import { SendEmailDto } from './dto/send-email.dto';
+import type { sendEmailTask } from '../trigger/email/send-email';
+
+@ApiTags('Internal - Email')
+@Controller({ path: 'internal/email', version: '1' })
+@UseGuards(HybridAuthGuard, PermissionGuard)
+@ApiSecurity('apikey')
+export class EmailController {
+  @Post('send')
+  @HttpCode(200)
+  @RequirePermission('email', 'send')
+  @ApiOperation({
+    summary: 'Send an email via the centralized Trigger task (internal)',
+  })
+  @ApiResponse({ status: 200, description: 'Email task triggered' })
+  async sendEmail(@Body() dto: SendEmailDto) {
+    const fromAddress = dto.system
+      ? (process.env.RESEND_FROM_SYSTEM ?? process.env.RESEND_FROM_DEFAULT)
+      : (dto.from ?? process.env.RESEND_FROM_DEFAULT);
+
+    const handle = await tasks.trigger<typeof sendEmailTask>('send-email', {
+      to: dto.to,
+      subject: dto.subject,
+      html: dto.html,
+      from: fromAddress,
+      cc: dto.cc,
+      scheduledAt: dto.scheduledAt,
+      attachments: dto.attachments,
+    });
+
+    return { success: true, taskId: handle.id };
+  }
+}

apps/api/src/email/email.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { AuthModule } from '../auth/auth.module';
+import { EmailController } from './email.controller';
+
+@Module({
+  imports: [AuthModule],
+  controllers: [EmailController],
+})
+export class EmailModule {}

apps/app/src/app/(app)/[orgId]/people/all/actions/addEmployeeWithoutInvite.ts

@@ -1,152 +1,31 @@
 'use server';
 
-import { createTrainingVideoEntries } from '@/lib/db/employee';
-import { auth } from '@/utils/auth';
-import { sendInviteMemberEmail } from '@comp/email';
 import type { Role } from '@db';
-import { db } from '@db';
-import { headers } from 'next/headers';
+import { inviteSingleMemberViaApi } from '@/lib/people-api';
 
 export const addEmployeeWithoutInvite = async ({
   email,
-  organizationId,
+  organizationId: _organizationId,
   roles,
 }: {
   email: string;
   organizationId: string;
   roles: Role[];
 }) => {
   try {
-    const session = await auth.api.getSession({ headers: await headers() });
-    if (!session?.session) {
-      throw new Error('Authentication required.');
-    }
-    const currentUserId = session.session.userId;
-    const currentUserMember = await db.member.findFirst({
-      where: {
-        organizationId: organizationId,
-        userId: currentUserId,
-        deactivated: false,
-      },
+    const result = await inviteSingleMemberViaApi({
+      email: email.toLowerCase(),
+      roles,
     });
 
-    if (!currentUserMember) {
-      throw new Error("You don't have permission to add members.");
-    }
-
-    const isAdmin =
-      currentUserMember.role.includes('admin') || currentUserMember.role.includes('owner');
-    const isAuditor = currentUserMember.role.includes('auditor');
-
-    if (!isAdmin && !isAuditor) {
-      throw new Error("You don't have permission to add members.");
-    }
-
-    if (isAuditor && !isAdmin) {
-      const onlyAuditorRole = roles.length === 1 && roles[0] === 'auditor';
-      if (!onlyAuditorRole) {
-        throw new Error("Auditors can only add users with the 'auditor' role.");
-      }
-    }
-
-    // Get organization name
-    const organization = await db.organization.findUnique({
-      where: { id: organizationId },
-      select: { name: true },
-    });
-
-    if (!organization) {
-      throw new Error('Organization not found.');
-    }
-
-    let userId = '';
-    const existingUser = await db.user.findFirst({
-      where: {
-        email: {
-          equals: email,
-          mode: 'insensitive',
-        },
-      },
-    });
-
-    if (!existingUser) {
-      const newUser = await db.user.create({
-        data: {
-          emailVerified: false,
-          email,
-          name: email.split('@')[0],
-        },
-      });
-
-      userId = newUser.id;
-    }
-
-    const finalUserId = existingUser?.id ?? userId;
-
-    // Check if there's an existing member (including deactivated ones) for this user and organization
-    const existingMember = await db.member.findFirst({
-      where: {
-        userId: finalUserId,
-        organizationId,
-      },
-    });
-
-    let member;
-    if (existingMember) {
-      // If member exists but is deactivated, reactivate it and update roles
-      if (existingMember.deactivated) {
-        const roleString = roles.sort().join(',');
-        member = await db.member.update({
-          where: { id: existingMember.id },
-          data: {
-            deactivated: false,
-            role: roleString,
-          },
-        });
-      } else {
-        // Member already exists and is active, return existing member
-        member = existingMember;
-      }
-    } else {
-      // No existing member, create a new one
-      member = await auth.api.addMember({
-        headers: await headers(),
-        body: {
-          userId: finalUserId,
-          organizationId,
-          role: roles.join(','),
-        },
-      });
-    }
-
-    // Create training video completion entries for the new member (only if member was just created/reactivated)
-    if (member?.id && !existingMember) {
-      await createTrainingVideoEntries(member.id);
-    }
-
-    // Generate invite link
-    const inviteLink = `${process.env.NEXT_PUBLIC_PORTAL_URL}/${organizationId}`;
-
-    // Send the invitation email (non-fatal: member is already created)
-    let emailSent = true;
-    let emailError: string | undefined;
-    try {
-      await sendInviteMemberEmail({
-        inviteeEmail: email.toLowerCase(),
-        inviteLink,
-        organizationName: organization.name,
-      });
-    } catch (emailErr) {
-      emailSent = false;
-      emailError = emailErr instanceof Error ? emailErr.message : 'Failed to send invite email';
-      console.error('Invite email failed after member was added:', { email, organizationId, error: emailErr });
-    }
-
     return {
-      success: true,
-      data: member,
-      emailSent,
-      ...(emailError && { emailError }),
+      success: result.success,
+      data: undefined,
+      emailSent: result.emailSent ?? result.success,
+      ...(result.error && {
+        error: result.error,
+        emailError: result.error,
+      }),
     };
   } catch (error) {
     console.error('Error adding employee:', error);