+-------------+        +---------------------+      +-----------------+      +----------------+
|   Client    | -----> | NestJS API Gateway  | ---> | MessagingService| ---> | Twilio Notify  |
| (e.g., Web, |        | (Controller/Auth)   |      | (Core Logic)    |      | API            |
|   Mobile)   |        +---------------------+      +-----------------+      +----------------+
+-------------+               |                                |
                              | (Optional)                     | (Optional)
                              v                                v
                       +-------------+                  +-----------------+
                       |  Database   |                  |   Logging Svc   |
                       | (Recipients,|                  | (e.g., Datadog, |
                       |   Logs)     |                  |   Sentry)       |
                       +-------------+                  +-----------------+

npm install -g @nestjs/cli

nest new nestjs-twilio-bulk-sms
cd nestjs-twilio-bulk-sms

npm install twilio @nestjs/config class-validator class-transformer
# or
yarn add twilio @nestjs/config class-validator class-transformer

# .env

# Twilio Credentials
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_NOTIFY_SERVICE_SID=ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Optional: If using a specific Messaging Service for Notify
# TWILIO_MESSAGING_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Application Settings
PORT=3000

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { AppController } from './app.controller';
import { AppService } from './app.service';
// Import your messaging module later
// import { MessagingModule } from './messaging/messaging.module';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // Make ConfigModule available globally
      envFilePath: '.env', // Specify the env file path
    }),
    // MessagingModule, // Uncomment once created
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe, HttpException, HttpStatus } from '@nestjs/common'; // Import HttpException, HttpStatus
import { ConfigService } from '@nestjs/config'; // Import ConfigService

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Enable CORS if needed (adjust origins for production)
  app.enableCors();

  // Use global validation pipe
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true, // Strip properties not defined in DTO
      transform: true, // Automatically transform payloads to DTO instances
      forbidNonWhitelisted: true, // Throw error if extra properties are sent
    }),
  );

  // Get port from ConfigService
  const configService = app.get(ConfigService);
  const port = configService.get<number&gt;('PORT') || 3000;

  await app.listen(port);
  console.log(`Application is running on: ${await app.getUrl()}`);
}
bootstrap();

nest generate module messaging
nest generate service messaging --no-spec # --no-spec skips test file for brevity
nest generate controller messaging --no-spec

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MessagingModule } from './messaging/messaging.module'; // Import

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    MessagingModule, // Add MessagingModule here
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

// src/messaging/messaging.service.ts
import { Injectable, Logger, InternalServerErrorException, BadRequestException, HttpException, HttpStatus } from '@nestjs/common'; // Added HttpException, HttpStatus
import { ConfigService } from '@nestjs/config';
import Twilio from 'twilio'; // Use default import

@Injectable()
export class MessagingService {
  private readonly logger = new Logger(MessagingService.name);
  private twilioClient: Twilio.Twilio; // Use the correct type
  private notifyServiceSid: string;

  constructor(private configService: ConfigService) {
    const accountSid = this.configService.get<string&gt;('TWILIO_ACCOUNT_SID');
    const authToken = this.configService.get<string&gt;('TWILIO_AUTH_TOKEN');
    this.notifyServiceSid = this.configService.get<string&gt;('TWILIO_NOTIFY_SERVICE_SID');

    if (!accountSid || !authToken || !this.notifyServiceSid) {
      this.logger.error('Twilio credentials or Notify Service SID missing in environment variables.');
      throw new InternalServerErrorException('Twilio configuration is incomplete.');
    }

    this.twilioClient = Twilio(accountSid, authToken); // Initialize Twilio client
    this.logger.log('Twilio client initialized.');
  }

  /**
   * Sends the same SMS message to multiple recipients using Twilio Notify.
   * @param recipients - An array of phone numbers in E.164 format (e.g., '+15551234567').
   * @param messageBody - The text content of the SMS.
   * @returns The SID of the Notification resource created.
   * @throws BadRequestException if the recipients array is empty.
   * @throws InternalServerErrorException if the message sending fails for other reasons.
   * @throws HttpException for specific errors like rate limiting.
   */
  async sendBulkSms(recipients: string[], messageBody: string): Promise<string&gt; {
    if (!recipients || recipients.length === 0) {
      this.logger.warn('Attempted to send bulk SMS with no recipients.');
      throw new BadRequestException('No recipients provided.'); // Throw standard exception
    }

    // Format recipients for Twilio Notify bindings
    // See: https://www.twilio.com/docs/notify/api/notification-resource#create-a-notification-resource
    const bindings = recipients.map(number =&gt; {
      return JSON.stringify({ binding_type: 'sms', address: number });
    });

    this.logger.log(`Sending bulk SMS via Notify to ${recipients.length} recipients.`);

    try {
      const notification = await this.twilioClient.notify
        .services(this.notifyServiceSid)
        .notifications.create({
          toBinding: bindings,
          body: messageBody,
        });

      this.logger.log(`Successfully created Notification resource: ${notification.sid}`);
      return notification.sid;
    } catch (error: any) { // Type assertion for error object
      this.logger.error(`Failed to send bulk SMS via Twilio Notify: ${error.message}`, error.stack);

      // Improved error handling based on Twilio error codes/status
      if (error.code === 20003) { // Example: Auth error
          throw new InternalServerErrorException('Twilio authentication failed. Check credentials.');
      } else if (error.status === 429) { // Example: Rate limited by Twilio
          this.logger.warn('Twilio rate limit hit. Consider implementing retry logic or queuing.');
          throw new HttpException('Rate limit exceeded', HttpStatus.TOO_MANY_REQUESTS);
      } else if (error.code === 21211 || error.code === 21604) { // Example: Invalid phone number or parameter
          throw new BadRequestException(`Invalid parameter provided to Twilio: ${error.message}`);
      }
      // Default generic error
      throw new InternalServerErrorException(`Failed to send bulk SMS. Error: ${error.message}`);
    }
  }

  // --- Add other messaging methods here (e.g., sendSingleSms) if needed ---
}

// src/messaging/dto/send-bulk-sms.dto.ts
import { IsArray, IsString, IsNotEmpty, ArrayNotEmpty, IsPhoneNumber } from 'class-validator';
// Remove swagger imports if not used, or keep if using Swagger
// import { ApiProperty } from '@nestjs/swagger';

export class SendBulkSmsDto {
  @IsArray()
  @ArrayNotEmpty()
  @IsPhoneNumber(null, { each: true, message: 'Each recipient must be a valid phone number in E.164 format (e.g., +15551234567)' })
  // @ApiProperty({
  //   description: 'An array of recipient phone numbers in E.164 format.',
  //   example: ['+15551234567', '+447700900123'],
  //   type: [String],
  // })
  recipients: string[];

  @IsString()
  @IsNotEmpty()
  // @ApiProperty({
  //   description: 'The text content of the SMS message.',
  //   example: 'Hello from our NestJS app!',
  // })
  message: string;
}

// src/messaging/messaging.controller.ts
import { Controller, Post, Body, UsePipes, ValidationPipe, Logger, HttpCode, HttpStatus } from '@nestjs/common';
import { MessagingService } from './messaging.service';
import { SendBulkSmsDto } from './dto/send-bulk-sms.dto';
// Remove swagger imports if not used, or keep if using Swagger
// import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';

// @ApiTags('Messaging') // Group endpoints in Swagger UI
@Controller('messaging')
export class MessagingController {
  private readonly logger = new Logger(MessagingController.name);

  constructor(private readonly messagingService: MessagingService) {}

  @Post('bulk-sms')
  @HttpCode(HttpStatus.ACCEPTED) // Use 202 Accepted as the process is async
  // @ApiOperation({ summary: 'Send a bulk SMS message via Twilio Notify' })
  // @ApiResponse({ status: HttpStatus.ACCEPTED, description: 'Request accepted, notification creation initiated.' })
  // @ApiResponse({ status: HttpStatus.BAD_REQUEST, description: 'Invalid input data (e.g., missing fields, invalid phone numbers, empty recipients array).' })
  // @ApiResponse({ status: HttpStatus.INTERNAL_SERVER_ERROR, description: 'Failed to initiate bulk SMS due to server or Twilio error.' })
  @UsePipes(new ValidationPipe({ transform: true, whitelist: true })) // Apply validation pipe specifically here too (or rely on global)
  async sendBulkSms(@Body() sendBulkSmsDto: SendBulkSmsDto): Promise<{ message: string; notificationSid?: string }> {
    this.logger.log(`Received request to send bulk SMS to ${sendBulkSmsDto.recipients.length} recipients.`);

    const { recipients, message } = sendBulkSmsDto;

    try {
      // Service now throws BadRequestException for empty recipients or invalid params,
      // and HttpException/InternalServerErrorException for other issues.
      // These will be handled by NestJS Exception Filters.
      const notificationSid = await this.messagingService.sendBulkSms(recipients, message);
      return {
        message: 'Bulk SMS request accepted by Twilio Notify.',
        notificationSid: notificationSid,
      };
    } catch (error) {
      // If it's not a validation error caught by the pipe, or a specific exception
      // thrown by the service, NestJS default exception filter will handle these.
      // We re-throw it to let the framework handle the HTTP response.
      this.logger.error(`Error processing bulk SMS request: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error.stack : undefined);
      throw error;
    }
  }
}

npm install @nestjs/swagger swagger-ui-express
# or
yarn add @nestjs/swagger swagger-ui-express

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe, HttpException, HttpStatus } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'; // Import Swagger

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableCors();
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      transform: true,
      forbidNonWhitelisted: true,
    }),
  );

  // Swagger Setup
  const config = new DocumentBuilder()
    .setTitle('Bulk SMS API')
    .setDescription('API for sending bulk SMS messages via Twilio Notify')
    .setVersion('1.0')
    .addTag('Messaging') // Match the tag used in the controller (if uncommented there)
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api-docs', app, document); // Serve docs at /api-docs

  const configService = app.get(ConfigService);
  const port = configService.get<number&gt;('PORT') || 3000;

  await app.listen(port);
  console.log(`Application is running on: ${await app.getUrl()}`);
  console.log(`Swagger Docs available at: ${await app.getUrl()}/api-docs`); // Log Swagger URL
}
bootstrap();

npm install prisma @prisma/client --save-dev
# or
yarn add prisma @prisma/client -D

npx prisma init --datasource-provider postgresql # or your chosen DB

// prisma/schema.prisma
generator client {
  provider = ""prisma-client-js""
}

datasource db {
  provider = ""postgresql""
  url      = env(""DATABASE_URL"")
}

model Recipient {
  id          String   @id @default(cuid())
  phoneNumber String   @unique // E.164 format
  firstName   String?
  lastName    String?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  // Add relationships to groups/lists if needed
  // Example: recipientListId String?
  // Example: recipientList RecipientList? @relation(fields: [recipientListId], references: [id])
}

// Example List Model
// model RecipientList {
//   id          String      @id @default(cuid())
//   name        String      @unique
//   description String?
//   recipients  Recipient[]
//   createdAt   DateTime    @default(now())
//   updatedAt   DateTime    @updatedAt
// }

model BulkMessageLog {
  id              String   @id @default(cuid())
  twilioNotifySid String   @unique // The SID from Twilio Notify
  messageBody     String
  status          String   @default(""initiated"") // e.g., initiated, completed, failed
  recipientCount  Int
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}

npx prisma migrate dev --name init-messaging-schema

npx prisma generate

nest generate service prisma --no-spec

// src/prisma/prisma.service.ts
import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    await this.$connect();
    this.logger.log('Prisma client connected.');
  }

  async onModuleDestroy() {
    await this.$disconnect();
    this.logger.log('Prisma client disconnected.');
  }

  // Add a logger for potential connection issues if needed
  private readonly logger = new Logger(PrismaService.name);
}

// Example modification in MessagingService
import { PrismaService } from '../prisma/prisma.service'; // Adjust path as needed

// ... inside MessagingService class
constructor(
  private configService: ConfigService,
  private prisma: PrismaService, // Inject PrismaService
) {
  // ... Twilio setup
}

// Example method using DB lookup (conceptual)
async sendBulkSmsToList(listId: string, messageBody: string): Promise<string&gt; {
  // 1. Fetch recipients from DB based on listId (example)
  const recipientsData = await this.prisma.recipient.findMany({
    // where: { recipientListId: listId }, // Example filter if using lists
    select: { phoneNumber: true }
  });
  const recipients = recipientsData.map(r =&gt; r.phoneNumber);

  if (recipients.length === 0) {
      throw new BadRequestException(`No recipients found for list ID: ${listId}`);
  }

  // 2. Call existing logic to send SMS
  const notificationSid = await this.sendBulkSms(recipients, messageBody);

  // 3. Log the attempt
  try {
      await this.prisma.bulkMessageLog.create({
          data: {
              twilioNotifySid: notificationSid,
              messageBody: messageBody,
              recipientCount: recipients.length,
              status: 'initiated', // Initial status
          },
      });
      this.logger.log(`Logged bulk message initiation for SID: ${notificationSid}`);
  } catch (dbError) {
      this.logger.error(`Failed to log bulk message initiation for SID ${notificationSid}: ${dbError instanceof Error ? dbError.message : String(dbError)}`, dbError instanceof Error ? dbError.stack : undefined);
      // Decide how to handle logging failure: maybe just log the error and continue,
      // or potentially throw an error if logging is critical.
  }

  return notificationSid;
}

// Conceptual retry logic using a hypothetical library or manual implementation
// Place this logic *around* the call to sendBulkSms in the controller, or use a queue.
// Avoid direct retry of `notifications.create` inside `MessagingService` due to idempotency issues.

// Example using a queue (conceptual - requires setting up BullMQ or similar)
// In MessagingController:
// constructor(
//   private readonly messagingService: MessagingService,
//   @InjectQueue('message-queue') private messageQueue: Queue, // Inject queue
// ) {}

// async sendBulkSms(@Body() sendBulkSmsDto: SendBulkSmsDto) {
//   this.logger.log(`Queueing request to send bulk SMS to ${sendBulkSmsDto.recipients.length} recipients.`);
//   await this.messageQueue.add('send-bulk-sms-job', {
//     recipients: sendBulkSmsDto.recipients,
//     message: sendBulkSmsDto.message,
//   }, {
//     attempts: 3, // Max attempts
//     backoff: { type: 'exponential', delay: 1000 }, // Exponential backoff
//   });
//   return { message: 'Bulk SMS request queued for processing.' };
//   // HttpStatus should likely remain 202 Accepted
// }

// Then create a Queue Processor that calls messagingService.sendBulkSms