graph LR
    subgraph Your Application
        Client[Client/Trigger] -- Send Request --> A[NestJS API: /send]
        A -- Save Initial Status (Pending) --> DB[(Database)]
        A -- messagebird.messages.create (with reportUrl & reference) --> MB_API[MessageBird API]
        WB[NestJS API: /status-webhook] -- Update Status --> DB
    end
    subgraph MessageBird Platform
        MB_API -- Sends SMS --> Carrier[Carrier Network] --> UserDevice[User Device]
        MB_API -- Status Update (POST Request) --> WB
    end

    style DB fill:#f9f,stroke:#333,stroke-width:2px

nest new messagebird-status-app --strict --package-manager npm
cd messagebird-status-app

# MessageBird SDK and configuration management
npm install messagebird @nestjs/config dotenv

# (Optional) Database integration (using PostgreSQL and TypeORM)
npm install @nestjs/typeorm typeorm pg

# (Optional) UUID for generating unique references
npm install uuid
npm install -D @types/uuid

# (Optional) Input validation
npm install class-validator class-transformer

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config'; // Import ConfigService
import { TypeOrmModule } from '@nestjs/typeorm'; // Uncomment if using DB
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MessagingModule } from './messaging/messaging.module';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // Make ConfigService available globally
      envFilePath: '.env',
    }),
    MessagingModule,
    // Uncomment the following TypeOrmModule section if using a database
    /*
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        type: 'postgres',
        host: configService.get<string&gt;('DB_HOST'),
        port: configService.get<number&gt;('DB_PORT'),
        username: configService.get<string&gt;('DB_USERNAME'),
        password: configService.get<string&gt;('DB_PASSWORD'),
        database: configService.get<string&gt;('DB_DATABASE'),
        // Use autoLoadEntities for simplicity, or configure paths manually.
        // If configuring manually, ensure the path points to compiled .js files in production (e.g., 'dist/**/*.entity.js').
        autoLoadEntities: true,
        // synchronize: true MUST NOT be used in production.
        // It can lead to data loss. Use migrations instead for schema changes.
        // Recommended ONLY for early development or local testing.
        synchronize: configService.get<string&gt;('NODE_ENV') !== 'production', // Example: Enable only if not in production
      }),
      inject: [ConfigService],
    }),
    */
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

nest g module messaging
nest g service messaging # We will add tests later
nest g controller messaging --no-spec

// src/messaging/messaging.service.ts
import { Injectable, Logger, InternalServerErrorException, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import * as MessageBird from 'messagebird'; // Use namespace import
import { v4 as uuidv4 } from 'uuid';
// Optional DB integration imports
// import { InjectRepository } from '@nestjs/typeorm';
// import { Repository } from 'typeorm';
// import { Message } from './entities/message.entity'; // Corrected import path

@Injectable()
export class MessagingService implements OnModuleInit {
  private readonly logger = new Logger(MessagingService.name);
  private messagebird: MessageBird.MessageBird; // Use MessageBird type
  private originator: string;
  private callbackUrl: string;

  constructor(
      private configService: ConfigService,
      // Uncomment if using DB
      // @InjectRepository(Message)
      // private messageRepository: Repository<Message&gt;,
    ) {}

  onModuleInit() {
    const apiKey = this.configService.get<string&gt;('MESSAGEBIRD_API_KEY');
    this.originator = this.configService.get<string&gt;('MESSAGEBIRD_ORIGINATOR');
    const baseUrl = this.configService.get<string&gt;('CALLBACK_BASE_URL');

    if (!apiKey || !this.originator || !baseUrl) {
      this.logger.error('MessageBird API Key, Originator, or Callback Base URL not configured.');
      throw new InternalServerErrorException('Messaging service configuration is incomplete.');
    }

    // Initialize MessageBird SDK
    this.messagebird = MessageBird(apiKey);
    this.callbackUrl = `${baseUrl}/messaging/status`; // Construct the full callback URL
    this.logger.log('MessageBird SDK initialized.');
    this.logger.log(`Using Originator: ${this.originator}`);
    this.logger.log(`Expecting status callbacks at: ${this.callbackUrl}`);
  }

  /**
   * Sends an SMS message via MessageBird and requests status reports.
   * @param to Recipient phone number (E.164 format expected)
   * @param body Message content
   * @returns The unique reference ID generated for this message
   */
  async sendMessage(to: string, body: string): Promise<string&gt; {
    // Generate a unique reference for this message - CRUCIAL for tracking
    const reference = uuidv4();
    this.logger.log(`Attempting to send SMS to ${to} with reference: ${reference}`);

    // --- Optional: Persist initial message details (status: 'pending') ---
    // const newMessage = this.messageRepository.create({ reference, recipient: to, body, status: 'pending' });
    // try {
    //   await this.messageRepository.save(newMessage);
    //   this.logger.log(`Saved initial message record with reference ${reference}`);
    // } catch (dbErr) {
    //   this.logger.error(`Database error saving initial message: ${dbErr.message}`, dbErr.stack);
    //   // Decide how to handle - maybe don't send if DB fails? Or send and log?
    // }
    // --- End Optional DB Interaction ---

    const params: MessageBird.messages.MessageCreateParameters = {
      originator: this.originator,
      recipients: [to],
      body: body,
      reference: reference, // Include the reference in the request
      reportUrl: this.callbackUrl, // Tell MessageBird where to POST status updates
    };

    return new Promise((resolve, reject) =&gt; {
      this.messagebird.messages.create(params, async (err, response) =&gt; { // Note: async callback for optional DB update
        if (err) {
          this.logger.error(`Failed to send SMS via MessageBird: ${err.message}`, err.stack);
          // --- Optional: Update status to 'failed_to_send' on API error ---
          // try {
          //    await this.messageRepository.update({ reference }, { status: 'failed_to_send' });
          // } catch (dbUpdateErr) { this.logger.error(`Failed to update status to failed_to_send for ${reference}: ${dbUpdateErr.message}`); }
          // --- End Optional Update ---
          reject(new InternalServerErrorException(`MessageBird API error: ${err.message}`));
        } else {
          const messageBirdId = response?.id;
          if (response?.recipients?.items?.length &gt; 0) {
             this.logger.log(`Message accepted by MessageBird for recipient ${to}. Message ID: ${messageBirdId}, Reference: ${reference}`);
             // --- Optional: Update status to 'accepted' on successful API call ---
             // try {
             //    await this.messageRepository.update({ reference }, { status: 'accepted', messageBirdId: messageBirdId });
             //    this.logger.log(`Message ${reference} accepted. DB status updated.`);
             // } catch (dbUpdateErr) { this.logger.error(`Failed to update status to accepted for ${reference}: ${dbUpdateErr.message}`); }
             // --- End Optional Update ---
          } else {
             this.logger.warn(`MessageBird response did not contain expected recipient details for ${to}, Reference: ${reference}. Response: ${JSON.stringify(response)}`);
             // Consider how to handle this - maybe update DB status differently?
          }
          resolve(reference); // Return the reference ID on successful API call
        }
      });
    });
  }

  /**
   * Processes incoming delivery status updates from MessageBird.
   * @param statusData The webhook payload from MessageBird
   */
  async processStatusUpdate(statusData: any): Promise<void&gt; { // Make async for potential DB ops
    const reference = statusData.reference;
    const status = statusData.status;
    const statusDatetime = statusData.statusDatetime;
    let recipient = statusData.recipient; // Can be number or string, sometimes without '+'
    const messageId = statusData.id; // MessageBird's internal ID

    if (!reference) {
      this.logger.warn('Received status update without a reference ID. Cannot correlate.', statusData);
      return;
    }

    this.logger.log(`Received status update for reference ${reference}: Status=${status}, Recipient=${recipient}, Time=${statusDatetime}, MsgID=${messageId}`);

    // --- Database Update Logic ---
    // Here, you would typically find the message record in your database
    // using the 'reference' and update its status and statusUpdatedAt fields.

    // **Normalization Note:** If storing or looking up by recipient, ensure consistent formatting.
    // MessageBird might send `recipient` without a leading '+'. Consider normalizing
    // to E.164 format (e.g., using a library like 'libphonenumber-js') before DB operations.
    // Example (pseudo-code): const normalizedRecipient = normalizeToE164(recipient);

    // Example DB update (uncomment and adapt if using TypeORM):
    /*
    try {
      const message = await this.messageRepository.findOne({ where: { reference } });
      if (message) {
        message.status = status;
        message.statusUpdatedAt = new Date(statusDatetime); // Ensure correct parsing/type
        message.messageBirdId = messageId ?? message.messageBirdId; // Update MB ID if present
        message.lastRawStatus = statusData; // Optional: Store raw payload for debugging
        // Potentially update the recipient field if needed after normalization
        await this.messageRepository.save(message);
        this.logger.log(`Updated status for reference ${reference} in DB.`);
      } else {
        this.logger.warn(`Could not find message with reference ${reference} in DB to update status.`);
      }
    } catch (dbErr) {
      this.logger.error(`Database error updating status for reference ${reference}: ${dbErr.message}`, dbErr.stack);
      // IMPORTANT: Still return OK to MessageBird below, but log the DB error for investigation.
      // Consider pushing to a dead-letter queue for retry if DB update fails.
    }
    */
    // --- End Database Update Logic ---
  }
}

// src/messaging/messaging.controller.ts
import { Controller, Post, Body, HttpCode, HttpStatus, Logger, ValidationPipe, UsePipes } from '@nestjs/common';
import { MessagingService } from './messaging.service';
import { SendMessageDto } from './dto/send-message.dto'; // We'll create this DTO next

@Controller('messaging')
export class MessagingController {
  private readonly logger = new Logger(MessagingController.name);

  constructor(private readonly messagingService: MessagingService) {}

  /**
   * Endpoint to send an SMS message.
   */
  @Post('send')
  @HttpCode(HttpStatus.ACCEPTED) // 202 Accepted is suitable as delivery is async
  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
  async sendMessage(@Body() sendMessageDto: SendMessageDto): Promise<{ message: string; reference: string }> {
    this.logger.log(`Received request to send SMS to ${sendMessageDto.to}`);
    const reference = await this.messagingService.sendMessage(
      sendMessageDto.to,
      sendMessageDto.body,
    );
    return {
      message: 'SMS send request accepted by MessageBird.',
      reference: reference, // Return the unique reference
    };
  }

  /**
   * Webhook endpoint to receive delivery status updates from MessageBird.
   * MessageBird expects a 2xx response quickly. Offload heavy processing if needed.
   */
  @Post('status')
  @HttpCode(HttpStatus.OK) // Respond with 200 OK immediately to acknowledge receipt
  async handleStatusWebhook(@Body() statusData: any): Promise<void&gt; {
    // Log the raw incoming data for debugging (optional)
    // this.logger.debug('Received MessageBird status webhook:', JSON.stringify(statusData, null, 2));

    // No validation DTO here initially, as MessageBird's payload is fixed,
    // but you could add one for stricter typing or basic checks if desired.

    // Asynchronously process the update. Don't await if processing might be slow.
    // Await is safe here ONLY if processStatusUpdate is guaranteed to be fast (e.g., only logging).
    // For DB operations, consider running without await and handling errors internally,
    // or push to a queue.
    await this.messagingService.processStatusUpdate(statusData);

    // IMPORTANT: Respond quickly! This endpoint must return 200 OK fast.
    // If processStatusUpdate involves slow operations (DB writes, external calls),
    // do NOT await it here. Instead, trigger it asynchronously:
    // this.messagingService.processStatusUpdate(statusData).catch(err =&gt; {
    //   this.logger.error('Error processing status update asynchronously:', err);
    // });
    // OR push statusData to a message queue (e.g., BullMQ, RabbitMQ) for background processing.
  }
}

// src/messaging/dto/send-message.dto.ts
import { IsNotEmpty, IsString, IsPhoneNumber } from 'class-validator';

export class SendMessageDto {
  @IsNotEmpty()
  @IsPhoneNumber(null) // Use 'null' for generic E.164 format validation (e.g., +1xxxxxxxxxx)
  @IsString()
  readonly to: string;

  @IsNotEmpty()
  @IsString()
  readonly body: string;
}

erDiagram
    MESSAGE {
        string id PK ""UUID, generated by DB or code""
        string reference UK ""UUID, generated by code, used for correlation""
        string messageBirdId NULL ""MessageBird's internal message ID""
        string recipient ""E.164 phone number""
        string body ""Message content""
        string status ""pending, accepted, sent, delivered, failed, expired, etc.""
        datetime createdAt ""Timestamp when record created""
        datetime statusUpdatedAt NULL ""Timestamp of last status update from MB""
        jsonb lastRawStatus NULL ""Store the last raw JSON payload from webhook""
        datetime updatedAt ""Timestamp record last updated""
    }

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

@Entity('messages') // Ensure table name matches your DB
export class Message {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  // Critical index for finding the message based on the webhook reference
  @Index({ unique: true })
  @Column({ type: 'uuid' })
  reference: string;

  // Indexing MessageBird's ID can be useful for reconciliation
  @Index()
  @Column({ nullable: true })
  messageBirdId: string;

  @Column()
  recipient: string; // Store normalized E.164 format if possible

  @Column({ type: 'text' })
  body: string;

  // Index status for efficient querying (e.g., find all 'failed' messages)
  @Index()
  @Column({ default: 'pending' })
  status: string; // e.g., pending, accepted, buffered, sent, delivered, expired, delivery_failed

  @CreateDateColumn()
  createdAt: Date;

  // Use timestamptz for PostgreSQL to store timezone info (recommended)
  @Column({ type: 'timestamptz', nullable: true })
  statusUpdatedAt: Date;

  // Store the last raw status payload (JSONB is efficient in PostgreSQL)
  @Column({ type: 'jsonb', nullable: true })
  lastRawStatus: any;

  @UpdateDateColumn() // Automatically updated by TypeORM on save/update
  updatedAt: Date;
}

# Add scripts to package.json (adjust path if needed)
# ""typeorm"": ""ts-node ./node_modules/typeorm/cli.js"",
# ""migration:generate"": ""npm run typeorm -- migration:generate --dataSource ./src/data-source.ts -n"",
# ""migration:run"": ""npm run typeorm -- migration:run --dataSource ./src/data-source.ts""

# Create a TypeORM DataSource file (e.g., src/data-source.ts) if you don't have one

npm run migration:generate -- InitialMessageSchema
# Review the generated migration file in the migrations folder
npm run migration:run