Production-Ready SMS Scheduling with NestJS and Vonage

graph LR
    Client[Client Application] -- HTTP POST /schedule --> API{NestJS API Endpoint};
    API -- Validates & Creates Job --> DB[(PostgreSQL Database)];
    Scheduler(NestJS Scheduler @Cron) -- Checks for Due Jobs --> DB;
    Scheduler -- Finds Due Job --> Sender[Vonage Service];
    Sender -- Sends SMS via API --> Vonage[Vonage Messages API];
    Vonage -- Delivers SMS --> UserDevice[User's Phone];
    API -- Logs Events --> Logger{Logging System};
    Sender -- Logs Events/Errors --> Logger;
    Scheduler -- Logs Events/Errors --> Logger;

    subgraph NestJS Application
        API
        Scheduler
        Sender
        DBInteraction[Database Service/Repository]
    end

    API -- Uses --> DBInteraction;
    Scheduler -- Uses --> DBInteraction;
    Scheduler -- Triggers --> Sender;
    DBInteraction -- Interacts --> DB;

npm install -g @nestjs/cli

nest new vonage-sms-scheduler
cd vonage-sms-scheduler

# Core NestJS modules + Vonage SDK
npm install @nestjs/config @nestjs/schedule @nestjs/typeorm typeorm pg @vonage/server-sdk class-validator class-transformer

# Development dependencies (TypeORM migrations require these)
npm install --save-dev ts-node tsconfig-paths

# .env

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=your_db_user
DB_PASSWORD=your_db_password
DB_DATABASE=vonage_scheduler

# Vonage API Credentials
VONAGE_API_KEY=YOUR_VONAGE_API_KEY
VONAGE_API_SECRET=YOUR_VONAGE_API_SECRET
VONAGE_APPLICATION_ID=YOUR_VONAGE_APPLICATION_ID
VONAGE_PRIVATE_KEY_PATH=./private.key # Path relative to project root
VONAGE_FROM_NUMBER=YOUR_VONAGE_PHONE_NUMBER # Number purchased from Vonage

# Application Settings
PORT=3000
TZ=UTC # Explicitly set timezone for scheduling consistency

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { ScheduleModule } from '@nestjs/schedule';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AppController } from './app.controller';
import { AppService } from './app.service';
// We will create these modules later
// import { SchedulingModule } from './scheduling/scheduling.module';
// import { VonageModule } from './vonage/vonage.module';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // Make ConfigService available globally
      envFilePath: '.env',
    }),
    ScheduleModule.forRoot(), // Initialize the scheduler
    // TypeOrmModule setup will be added in the database section
    // SchedulingModule, // Will be added later
    // VonageModule,     // Will be added later
  ],
  controllers: [AppController], // Default controller, can be removed if not needed
  providers: [AppService], // Default service, can be removed if not needed
})
export class AppModule {}

// src/scheduling/entities/scheduled-message.entity.ts
import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
  Index,
} from 'typeorm';

export enum MessageStatus {
  PENDING = 'PENDING',
  SENT = 'SENT',
  FAILED = 'FAILED',
  PROCESSING = 'PROCESSING', // Optional: To prevent multiple workers picking the same job
}

@Entity('scheduled_messages')
export class ScheduledMessage {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  recipient: string; // E.164 format recommended (e.g., +15551234567)

  @Column('text')
  message: string;

  @Column({ type: 'timestamp with time zone' })
  @Index() // Index for efficient querying
  sendAt: Date;

  @Column({
    type: 'enum',
    enum: MessageStatus,
    default: MessageStatus.PENDING,
  })
  @Index() // Index for efficient querying
  status: MessageStatus;

  @Column({ nullable: true })
  vonageMessageId?: string; // Store Vonage ID upon successful sending

  @Column('text', { nullable: true })
  failureReason?: string; // Store error message if sending fails

  @CreateDateColumn({ type: 'timestamp with time zone' })
  createdAt: Date;

  @UpdateDateColumn({ type: 'timestamp with time zone' })
  updatedAt: Date;
}

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { ScheduleModule } from '@nestjs/schedule';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { ScheduledMessage } from './scheduling/entities/scheduled-message.entity';
// import { SchedulingModule } from './scheduling/scheduling.module';
// import { VonageModule } from './vonage/vonage.module';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    ScheduleModule.forRoot(),
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        type: 'postgres',
        host: configService.get<string>('DB_HOST'),
        port: configService.get<number>('DB_PORT'),
        username: configService.get<string>('DB_USERNAME'),
        password: configService.get<string>('DB_PASSWORD'),
        database: configService.get<string>('DB_DATABASE'),
        entities: [ScheduledMessage], // Add other entities here if needed
        synchronize: false, // IMPORTANT: Set to false in production, use migrations instead
        autoLoadEntities: true, // Automatically loads entities registered via forFeature()
        logging: process.env.NODE_ENV === 'development', // Log SQL in development
        extra: {
          ssl:
            process.env.NODE_ENV === 'production'
              ? {
                  rejectUnauthorized: false, // WARNING: Highly insecure for production! Requires proper certificate validation. See docs.
                }
              : false,
        },
      }),
      inject: [ConfigService],
    }),
    // SchedulingModule, // Will be added later
    // VonageModule,     // Will be added later
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

// ormconfig.ts (or ormconfig.js) in the project root
import { DataSource } from 'typeorm';
import { config } from 'dotenv';

config(); // Load .env variables

export default new DataSource({
  type: 'postgres',
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT || '5432', 10),
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_DATABASE,
  entities: ['dist/**/*.entity{.ts,.js}'], // Point to compiled entities
  migrations: ['dist/migrations/*{.ts,.js}'], // Point to compiled migrations
  migrationsTableName: 'typeorm_migrations',
  synchronize: false, // Ensure synchronize is false
  logging: true,
  extra: {
    ssl:
      process.env.NODE_ENV === 'production'
        ? {
            rejectUnauthorized: false, // WARNING: Insecure for production! Use proper certificate validation.
          }
        : false,
  },
});

// package.json
{
  // ... other package.json content
  ""scripts"": {
    // ... other scripts
    ""build"": ""nest build"",
    ""start:dev"": ""nest start --watch"",
    ""start:prod"": ""node dist/main"",
    ""lint"": ""eslint \""{src,apps,libs,test}/**/*.ts\"" --fix"",
    ""test"": ""jest"",
    ""test:watch"": ""jest --watch"",
    ""test:cov"": ""jest --coverage"",
    ""test:debug"": ""node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand"",
    ""test:e2e"": ""jest --config ./test/jest-e2e.json"",
    ""typeorm"": ""ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js --dataSource ormconfig.ts"",
    ""migration:generate"": ""npm run typeorm migration:generate ./src/migrations/%npm_config_name%"",
    ""migration:run"": ""npm run typeorm migration:run"",
    ""migration:revert"": ""npm run typeorm migration:revert""
  },
  // ... dependencies, devDependencies etc.
}

nest g module vonage
nest g service vonage --no-spec # --no-spec skips test file generation for brevity

// src/vonage/vonage.service.ts
import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { Vonage } from '@vonage/server-sdk';
import { MessageSendRequest } from '@vonage/messages/dist/interfaces/MessageSendRequest';
import * as fs from 'fs';
import * as path from 'path';

@Injectable()
export class VonageService implements OnModuleInit {
  private readonly logger = new Logger(VonageService.name);
  private vonage: Vonage;
  private vonageFromNumber: string;

  constructor(private configService: ConfigService) {}

  onModuleInit() {
    const apiKey = this.configService.get<string>('VONAGE_API_KEY');
    const apiSecret = this.configService.get<string>('VONAGE_API_SECRET');
    const applicationId = this.configService.get<string>(
      'VONAGE_APPLICATION_ID',
    );
    const privateKeyPath = this.configService.get<string>(
      'VONAGE_PRIVATE_KEY_PATH',
    );
    this.vonageFromNumber = this.configService.get<string>(
      'VONAGE_FROM_NUMBER',
    );

    if (
      !apiKey ||
      !apiSecret ||
      !applicationId ||
      !privateKeyPath ||
      !this.vonageFromNumber
    ) {
      this.logger.error('Missing Vonage credentials in environment variables.');
      throw new Error('Missing Vonage credentials.');
    }

    const absolutePrivateKeyPath = path.resolve(process.cwd(), privateKeyPath);

    if (!fs.existsSync(absolutePrivateKeyPath)) {
      this.logger.error(`Private key file not found at: ${absolutePrivateKeyPath}`);
      throw new Error(`Private key file not found at: ${absolutePrivateKeyPath}`);
    }

    try {
        const privateKey = fs.readFileSync(absolutePrivateKeyPath);
        this.vonage = new Vonage({
          apiKey,
          apiSecret,
          applicationId,
          privateKey,
        });
        this.logger.log('Vonage SDK initialized successfully.');
    } catch (error) {
        this.logger.error(`Failed to read private key or initialize Vonage SDK: ${error.message}`, error.stack);
        throw new Error('Failed to initialize Vonage SDK.');
    }
  }

  async sendSms(to: string, text: string): Promise<{ success: boolean; messageId?: string; error?: string }> {
    if (!this.vonage) {
        const errorMessage = 'Vonage SDK not initialized. Cannot send SMS.';
        this.logger.error(errorMessage);
        return { success: false, error: errorMessage };
    }

    const messageRequest: MessageSendRequest = {
      message_type: 'text',
      channel: 'sms',
      to: to,
      from: this.vonageFromNumber,
      text: text,
    };

    try {
      this.logger.log(`Attempting to send SMS to ${to}`);
      const response = await this.vonage.messages.send(messageRequest);
      this.logger.log(`SMS sent successfully to ${to}. Message UUID: ${response.message_uuid}`);
      return { success: true, messageId: response.message_uuid };
    } catch (error) {
      const errorMessage = `Failed to send SMS to ${to}: ${error?.response?.data?.title || error.message}`;
      this.logger.error(errorMessage, error.stack);
      // Consider logging more details from error?.response?.data if available
      // console.error('Vonage Error Details:', error?.response?.data);
      return { success: false, error: errorMessage };
    }
  }
}

// src/vonage/vonage.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config'; // Import ConfigModule if not global
import { VonageService } from './vonage.service';

@Module({
  imports: [ConfigModule], // Ensure ConfigService is available
  providers: [VonageService],
  exports: [VonageService], // Export service for other modules to use
})
export class VonageModule {}

// src/app.module.ts
// ... other imports
import { VonageModule } from './vonage/vonage.module'; // Import VonageModule

@Module({
  imports: [
    // ... other modules (ConfigModule, ScheduleModule, TypeOrmModule)
    VonageModule, // Add VonageModule here
    // SchedulingModule, // Will be added later
  ],
  // ... controllers, providers
})
export class AppModule {}

nest g module scheduling
nest g service scheduling --no-spec
nest g controller scheduling --no-spec

// src/scheduling/dto/schedule-sms.dto.ts
import {
  IsNotEmpty,
  IsString,
  IsPhoneNumber, // From class-validator, validates E.164 format
  IsDate,
  MinDate,
  MaxLength,
} from 'class-validator';
import { Type } from 'class-transformer'; // Required for date transformation

export class ScheduleSmsDto {
  @IsNotEmpty()
  @IsPhoneNumber(null) // null region code allows global E.164 format
  recipient: string;

  @IsNotEmpty()
  @IsString()
  @MaxLength(1600) // Vonage SMS limit (though concatenation might apply)
  message: string;

  @IsNotEmpty()
  @Type(() => Date) // Transform incoming string/number to Date object
  @IsDate()
  @MinDate(new Date(), { message: 'sendAt must be a future date' })
  sendAt: Date;
}

// src/scheduling/scheduling.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository, LessThanOrEqual, IsNull } from 'typeorm';
import { Cron, CronExpression } from '@nestjs/schedule'; // Use Cron decorators
import {
  ScheduledMessage,
  MessageStatus,
} from './entities/scheduled-message.entity';
import { ScheduleSmsDto } from './dto/schedule-sms.dto';
import { VonageService } from '../vonage/vonage.service';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class SchedulingService {
  private readonly logger = new Logger(SchedulingService.name);

  constructor(
    @InjectRepository(ScheduledMessage)
    private messageRepository: Repository<ScheduledMessage>,
    private vonageService: VonageService,
    private configService: ConfigService, // Optional: For advanced config
  ) {}

  async scheduleSms(dto: ScheduleSmsDto): Promise<ScheduledMessage> {
    const newMessage = this.messageRepository.create({
      ...dto,
      status: MessageStatus.PENDING,
      sendAt: dto.sendAt, // Ensure date object is used
    });

    await this.messageRepository.save(newMessage);
    this.logger.log(`Scheduled SMS ID: ${newMessage.id} for ${dto.recipient} at ${dto.sendAt}`);
    return newMessage;
  }

  // Cron job to run every minute (adjust as needed)
  @Cron(CronExpression.EVERY_MINUTE)
  async handleCron() {
    this.logger.log('Running scheduled message check...');
    await this.processDueMessages();
  }

  async processDueMessages(): Promise<void> {
    const now = new Date();
    // Find messages that are due (sendAt <= now) and still pending
    const dueMessages = await this.messageRepository.find({
      where: {
        status: MessageStatus.PENDING,
        sendAt: LessThanOrEqual(now),
      },
      take: 100, // Process in batches to avoid overwhelming resources
      order: {
        sendAt: 'ASC', // Process older messages first
      },
    });

    if (dueMessages.length === 0) {
      this.logger.log('No due messages found.');
      return;
    }

    this.logger.log(`Found ${dueMessages.length} due messages to process.`);

    for (const message of dueMessages) {
      // Optional: Implement locking mechanism to prevent race conditions
      // when running multiple instances (horizontal scaling).
      // Example: Update status to PROCESSING before sending.
      /*
      const updated = await this.messageRepository.update(
          { id: message.id, status: MessageStatus.PENDING }, // Only update if still PENDING
          { status: MessageStatus.PROCESSING }
      );
      if (updated.affected === 0) {
          // If affected is 0, another instance likely processed it between the find and update calls.
          this.logger.log(`Message ID ${message.id} skipped (likely processed by another instance).`);
          continue; // Skip this message
      }
      */

      this.logger.log(`Processing message ID: ${message.id} to ${message.recipient}`);
      try {
        const result = await this.vonageService.sendSms(
          message.recipient,
          message.message,
        );

        if (result.success) {
          message.status = MessageStatus.SENT;
          message.vonageMessageId = result.messageId;
          message.failureReason = null;
          this.logger.log(`Message ID: ${message.id} sent successfully. Vonage ID: ${result.messageId}`);
        } else {
          message.status = MessageStatus.FAILED;
          message.failureReason = result.error || 'Unknown Vonage error';
          this.logger.error(`Failed to send message ID: ${message.id}. Reason: ${message.failureReason}`);
          // Implement retry logic here if desired (e.g., increment retry count, schedule for later)
        }
      } catch (error) {
        message.status = MessageStatus.FAILED;
        message.failureReason = error.message || 'Internal processing error';
        this.logger.error(`Error processing message ID: ${message.id}: ${error.message}`, error.stack);
      } finally {
        // Ensure status is updated regardless of Vonage call outcome
        // If using the PROCESSING status, ensure you save here.
        // If not using PROCESSING, the status is already set in the try/catch blocks.
        await this.messageRepository.save(message);
      }
    }
    this.logger.log('Finished processing batch of due messages.');
  }

  async getMessageStatus(id: string): Promise<ScheduledMessage | null> {
      return this.messageRepository.findOneBy({ id });
  }
}

// src/scheduling/scheduling.controller.ts
import {
  Controller,
  Post,
  Body,
  UsePipes,
  ValidationPipe,
  HttpCode,
  HttpStatus,
  Logger,
  Get,
  Param,
  NotFoundException,
} from '@nestjs/common';
import { SchedulingService } from './scheduling.service';
import { ScheduleSmsDto } from './dto/schedule-sms.dto';
import { ScheduledMessage } from './entities/scheduled-message.entity';

@Controller('schedule') // Base path for endpoints in this controller
export class SchedulingController {
  private readonly logger = new Logger(SchedulingController.name);

  constructor(private readonly schedulingService: SchedulingService) {}

  @Post()
  @HttpCode(HttpStatus.ACCEPTED) // Use 202 Accepted as scheduling is asynchronous
  @UsePipes(new ValidationPipe({ transform: true, whitelist: true })) // Enable validation & transformation
  async scheduleSms(
    @Body() scheduleSmsDto: ScheduleSmsDto,
  ): Promise<{ message: string; id: string }> {
    this.logger.log(`Received request to schedule SMS for ${scheduleSmsDto.recipient}`);
    try {
        const scheduledMessage = await this.schedulingService.scheduleSms(
          scheduleSmsDto,
        );
        return {
          message: 'SMS scheduled successfully',
          id: scheduledMessage.id,
        };
    } catch (error) {
        this.logger.error(`Failed to schedule SMS: ${error.message}`, error.stack);
        // Consider re-throwing or returning a specific error response
        throw error; // Re-throw to let global exception filter handle it
    }
  }

  @Get(':id/status')
  async getStatus(@Param('id') id: string): Promise<ScheduledMessage> {
      this.logger.log(`Received request for status of message ID: ${id}`);
      const message = await this.schedulingService.getMessageStatus(id);
      if (!message) {
          throw new NotFoundException(`Scheduled message with ID ${id} not found.`);
      }
      return message;
  }
}

// src/scheduling/scheduling.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { SchedulingService } from './scheduling.service';
import { SchedulingController } from './scheduling.controller';
import { ScheduledMessage } from './entities/scheduled-message.entity';
import { VonageModule } from '../vonage/vonage.module'; // Import VonageModule
import { ConfigModule } from '@nestjs/config'; // Often needed here too

@Module({
  imports: [
    TypeOrmModule.forFeature([ScheduledMessage]), // Make repository available
    VonageModule, // Import to use VonageService
    ConfigModule, // Make ConfigService available
  ],
  controllers: [SchedulingController],
  providers: [SchedulingService],
})
export class SchedulingModule {}

// src/app.module.ts
// ... other imports
import { VonageModule } from './vonage/vonage.module';
import { SchedulingModule } from './scheduling/scheduling.module'; // Import SchedulingModule

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
    ScheduleModule.forRoot(),
    TypeOrmModule.forRootAsync({
      // ... TypeORM config
    }),
    VonageModule,
    SchedulingModule, // Add SchedulingModule here
  ],
  controllers: [AppController], // Keep or remove as needed
  providers: [AppService], // Keep or remove as needed
})
export class AppModule {}