sequenceDiagram
    participant Client
    participant NestJS API
    participant AWS SNS
    participant SMS Recipient
    participant Status SNS Topic
    participant (Optional) Database

    Client->>+NestJS API: POST /sms/send (phone, message)
    NestJS API->>+AWS SNS: PublishCommand(PhoneNumber, Message)
    AWS SNS-->>-NestJS API: { MessageId: '...' }
    NestJS API-->>Client: { success: true, messageId: '...' }
    Note over NestJS API, (Optional) Database: Record message details (messageId, status='SUBMITTED')
    AWS SNS->>+SMS Recipient: Deliver SMS
    SMS Recipient-->>-AWS SNS: Delivery Acknowledgment/Failure
    AWS SNS->>+Status SNS Topic: Publish Delivery Status Notification
    Status SNS Topic->>+NestJS API: POST /sms/status/callback (SNS Notification)
    NestJS API->>NestJS API: Verify SNS Message Signature
    NestJS API->>NestJS API: Parse Status (DELIVERED/FAILED)
    Note over NestJS API, (Optional) Database: Update message status (messageId, newStatus)
    NestJS API-->>-Status SNS Topic: HTTP 200 OK

nest new nestjs-sns-callbacks
cd nestjs-sns-callbacks

# Using npm
npm install @aws-sdk/client-sns @nestjs/config class-validator class-transformer sns-validator
npm install --save-dev @types/sns-validator

# Or using yarn
yarn add @aws-sdk/client-sns @nestjs/config class-validator class-transformer sns-validator
yarn add --dev @types/sns-validator

# .env

# AWS Credentials & Region (Ensure these have necessary SNS permissions)
AWS_REGION=us-east-1 # Change to your desired AWS region
# AWS_ACCESS_KEY_ID=YOUR_AWS_ACCESS_KEY_ID       # See note below
# AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY # See note below

# ARN of the SNS Topic that will receive delivery status updates from SNS SMS
# We will create this topic in Step 4.
DELIVERY_STATUS_TOPIC_ARN=arn:aws:sns:us-east-1:123456789012:sms-delivery-status-topic

# (Optional) Database URL if you plan to persist status
# DATABASE_URL=postgresql://user:password@host:port/database

# The base URL where your NestJS app is publicly accessible (for SNS subscription)
# Use your Ngrok URL during development, or your production domain later.
APP_BASE_URL=https://your-public-domain-or-ngrok-url.com

# (Optional) Port for the application
# 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 { SmsModule } from './sms/sms.module'; // We will create this next

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // Make ConfigModule available globally
      envFilePath: '.env', // Load the .env file
    }),
    SmsModule, // Import the SMS module
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

src/
├── app.controller.ts
├── app.module.ts
├── app.service.ts
├── main.ts
├── sms/
│   ├── dto/
│   │   └── send-sms.dto.ts       # DTO for sending SMS requests
│   ├── entities/               # (Optional) For database entities
│   │   └── sms-message.entity.ts
│   ├── interfaces/
│   │   └── sns-notification.interface.ts # Type definition for SNS notifications
│   ├── sms.controller.ts       # Handles incoming API requests (send & callback)
│   ├── sms.module.ts           # SMS module definition
│   └── sms.service.ts          # Contains business logic (sending SMS, processing callbacks)
└── config/                     # (Optional) Configuration setup if needed beyond basic .env

// src/sms/sms.module.ts
import { Module, Provider } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { SNSClient } from '@aws-sdk/client-sns';
import { SmsController } from './sms.controller';
import { SmsService } from './sms.service';

// Define a provider token for dependency injection
export const AWS_SNS_CLIENT = Symbol('AWS_SNS_CLIENT');

const snsClientProvider: Provider = {
  provide: AWS_SNS_CLIENT,
  useFactory: (configService: ConfigService): SNSClient => {
    const region = configService.get<string&gt;('AWS_REGION');
    // AWS SDK v3 automatically uses credentials from environment variables
    // (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), AWS profiles, or IAM roles.
    // Ensure they are set correctly in your environment or IAM configuration.
    return new SNSClient({ region });
  },
  inject: [ConfigService], // Inject ConfigService to read region from .env
};

@Module({
  imports: [ConfigModule], // Ensure ConfigModule is available
  controllers: [SmsController],
  providers: [snsClientProvider, SmsService],
  exports: [SmsService], // Export if needed by other modules
})
export class SmsModule {}

// src/sms/sms.service.ts
import { Injectable, Inject, Logger, BadRequestException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import {
  SNSClient,
  PublishCommand,
  PublishCommandInput,
  PublishCommandOutput,
  SetSMSAttributesCommand, // Import for setting attributes later
  SetSMSAttributesCommandInput,
} from '@aws-sdk/client-sns';
import { AWS_SNS_CLIENT } from './sms.module'; // Import the provider token

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

  constructor(
    @Inject(AWS_SNS_CLIENT) private readonly snsClient: SNSClient,
    private readonly configService: ConfigService,
  ) {}

  /**
   * Sends an SMS message using AWS SNS.
   * @param phoneNumber - The recipient's phone number in E.164 format (e.g., +12223334444).
   * @param message - The text message content.
   * @returns The MessageId from SNS upon successful request initiation.
   * @throws BadRequestException if phone number format is invalid.
   * @throws Error if sending fails for other reasons.
   */
  async sendSms(phoneNumber: string, message: string): Promise<string&gt; {
    // Basic validation (more robust validation in DTO/Controller layer)
    if (!phoneNumber || !message) {
      // This check is somewhat redundant if using DTOs, but good defense.
      throw new BadRequestException('Phone number and message are required.');
    }

    // Validate E.164 format. Sending to invalid numbers fails and incurs cost.
    if (!/^\+[1-9]\d{1,14}$/.test(phoneNumber)) {
       // Throw an error instead of just logging. Consider making this configurable if non-E.164 support is needed (though not recommended).
       throw new BadRequestException(`Invalid phone number format: ${phoneNumber}. Must use E.164 format (e.g., +12223334444).`);
    }

    const params: PublishCommandInput = {
      PhoneNumber: phoneNumber,
      Message: message,
      // Optional: Add MessageAttributes for SenderID, MaxPrice, SMSType etc.
      // See AWS SNS documentation for available attributes.
      // MessageAttributes: {
      //   'AWS.SNS.SMS.SenderID': {
      //     DataType: 'String',
      //     StringValue: 'MySenderID' // Requires pre-registration in some countries
      //   },
      //   'AWS.SNS.SMS.SMSType': {
      //     DataType: 'String',
      //     StringValue: 'Transactional' // Or 'Promotional' - affects delivery path/cost
      //   }
      // }
    };

    try {
      this.logger.log(`Attempting to send SMS to ${phoneNumber}`);
      const command = new PublishCommand(params);
      const result: PublishCommandOutput = await this.snsClient.send(command);

      if (!result.MessageId) {
          throw new Error('SNS did not return a MessageId.');
      }

      this.logger.log(`SMS initiated successfully to ${phoneNumber}. MessageId: ${result.MessageId}`);
      // Optional: Persist message details with MessageId and initial status ('SUBMITTED') here (See Section 6)
      // await this.persistInitialMessageRecord(result.MessageId, phoneNumber, message);

      return result.MessageId;
    } catch (error) {
      this.logger.error(`Failed to send SMS to ${phoneNumber}: ${error.message}`, error.stack);
      // Consider more specific error handling based on AWS SDK error types
      if (error instanceof BadRequestException) throw error; // Re-throw validation errors
      throw new Error(`Failed to send SMS via SNS: ${error.message}`);
    }
  }

  /**
   * Placeholder method for processing incoming delivery status notifications.
   * This will be refined significantly when the database layer is added (Section 6)
   * to handle the specific payload structure and update records.
   * @param payload - The raw parsed JSON payload from the SNS notification's 'Message' field.
   */
  async processDeliveryStatus(payload: any): Promise<void&gt; {
     this.logger.log(`Received raw delivery status payload: ${JSON.stringify(payload)}`);
     // Initial Placeholder Logic: Just log the received payload.
     // Detailed processing (extracting messageId, status, destination, updating DB)
     // will be implemented in Section 6 when the SmsMessage entity is available.
     // Example extraction (adapt based on actual payload structure):
     // const messageId = payload.messageId || payload.notification?.messageId;
     // const status = payload.status;
     // const destination = payload.delivery?.destination;
     // this.logger.log(`Processing status update for MessageId ${messageId}: ${status}`);
     // await this.updatePersistedStatus(messageId, status, payload); // Call DB update logic
  }

   /**
    * Configures AWS SNS account-level SMS attributes to enable delivery status notifications.
    * Sends status updates to the SNS topic specified by DELIVERY_STATUS_TOPIC_ARN.
    * Requires sns:SetSMSAttributes IAM permission. Run once during setup or via a dedicated command.
    */
   async configureSmsDeliveryStatusAttributes(): Promise<void&gt; {
    const deliveryStatusTopicArn = this.configService.get<string&gt;('DELIVERY_STATUS_TOPIC_ARN');

    if (!deliveryStatusTopicArn) {
        this.logger.error('DELIVERY_STATUS_TOPIC_ARN is not configured in .env. Cannot set SMS attributes.');
        return;
    }

    // **IMPORTANT CLARIFICATION ON 'RoleArn' PARAMETERS:**
    // AWS uses confusing parameter names here (`SuccessfulFeedbackRoleArn`, `FailureFeedbackRoleArn`).
    // When sending delivery status notifications *to an SNS Topic* (as we are doing),
    // you provide the **ARN of the target SNS Topic** as the value for these parameters.
    // You do NOT need to create or provide a separate IAM Role ARN here for SNS-to-Topic delivery.
    // SNS uses its service principal permissions (which you grant on the Topic's policy) to publish.
    // An IAM Role ARN *is* required if you were logging statuses directly to CloudWatch Logs instead of an SNS Topic.
    const params: SetSMSAttributesCommandInput = {
        attributes: {
            // Send 100% of successful delivery statuses to the specified SNS topic
            'DeliveryStatusSuccessSamplingRate': '100', // Percentage as a string ""0""-""100""
            // ARN of the SNS topic to notify for successful deliveries
            'SuccessfulFeedbackRoleArn': deliveryStatusTopicArn, // Use Topic ARN here
            // 'SuccessfulFeedbackSampleRate': '100', // Seems redundant with DeliveryStatusSuccessSamplingRate, but some docs show it. Included for safety.

            // ARN of the SNS topic to notify for failed deliveries
            'FailureFeedbackRoleArn': deliveryStatusTopicArn, // Use Topic ARN here

            // Optional: Default Sender ID (must be registered if used)
            // 'DefaultSenderID': 'MySenderID',

            // Optional: Default SMS Type ('Transactional' for higher reliability, 'Promotional' for lower cost)
            'DefaultSMSType': 'Transactional',

            // Optional: Monthly spend limit in USD (as a string)
            // 'MonthlySpendLimit': '1',
        },
    };

    try {
        this.logger.log(`Attempting to set SMS delivery status attributes to publish to Topic: ${deliveryStatusTopicArn}`);
        const command = new SetSMSAttributesCommand(params);
        await this.snsClient.send(command);
        this.logger.log(`Successfully set SMS delivery status attributes.`);
    } catch (error) {
        this.logger.error(`Failed to set SMS attributes: ${error.message}`, error.stack);
        // This might fail due to permissions (ensure IAM user/role has sns:SetSMSAttributes)
        // or invalid ARN / parameters.
        throw new Error(`Failed to configure SNS SMS attributes: ${error.message}`);
    }
  }
}

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

export class SendSmsDto {
  @IsNotEmpty()
  @IsPhoneNumber(null, { message: 'Phone number must be a valid E.164 format phone number (e.g., +12223334444).' }) // null region uses default validation
  phoneNumber: string;

  @IsNotEmpty()
  @IsString()
  @MaxLength(1600) // SNS SMS message length limits (check current AWS docs for specifics, including character encoding impact)
  message: string;
}

// src/sms/interfaces/sns-notification.interface.ts

// Represents the overall structure of the POST request body from SNS
export interface SnsNotificationRequest {
  Type: 'SubscriptionConfirmation' | 'Notification' | 'UnsubscribeConfirmation';
  MessageId: string; // Message ID of the notification itself
  Token?: string; // Only for SubscriptionConfirmation & UnsubscribeConfirmation
  TopicArn: string;
  Subject?: string;
  Message: string; // This is a JSON string that needs parsing for 'Notification' type
  Timestamp: string; // ISO 8601 timestamp
  SignatureVersion: string;
  Signature: string;
  SigningCertURL: string;
  SubscribeURL?: string; // Only for SubscriptionConfirmation
  UnsubscribeURL?: string; // Only for UnsubscribeConfirmation
}

// Represents the structure of the 'Message' field after JSON parsing for a delivery status notification
// Note: The exact location of the original messageId can vary slightly.
export interface SnsDeliveryStatusMessage {
  notification?: { // Optional outer layer sometimes present
    messageId: string; // UUID generated by SNS when sending the original SMS
    timestamp: string; // ISO 8601 timestamp
  };
  delivery: {
    phoneCarrier: string; // e.g., Verizon Wireless, AT&T, etc.
    mnc: number; // Mobile Network Code
    destination: string; // The recipient phone number (E.164 format)
    priceInUSD: number; // Cost of the message segment
    smsType: 'Promotional' | 'Transactional';
    mcc: number; // Mobile Country Code
    providerResponse: string; // Information from the downstream provider (can be vague or detailed)
    dwellTimeMs: number; // Time spent in the downstream provider network
    dwellTimeMsUntilDeviceAck?: number; // Time until device acknowledgment (if available)
  };
  status: 'SUCCESS' | 'FAILURE' | string; // The delivery status. 'SUCCESS' corresponds to delivered to handset. Other strings possible for failures.
  // The original messageId is often outside the 'delivery' object in direct SNS status messages,
  // but sometimes nested under 'notification'. Code must check both.
  messageId?: string; // UUID generated by SNS when sending the original SMS (sometimes here)
}

// src/sms/sms.controller.ts
import {
  Controller,
  Post,
  Body,
  HttpCode,
  HttpStatus,
  UsePipes,
  ValidationPipe,
  Headers,
  Logger,
  RawBodyRequest, // Import this
  Req, // Import this
  Inject, // Import Inject if not already present
} from '@nestjs/common';
import { Request } from 'express'; // Import this
import { SmsService } from './sms.service';
import { SendSmsDto } from './dto/send-sms.dto';
import { ConfigService } from '@nestjs/config';
import MessageValidator = require('sns-validator'); // Use require syntax for CommonJS module
import { SnsNotificationRequest, SnsDeliveryStatusMessage } from './interfaces/sns-notification.interface';

@Controller('sms')
export class SmsController {
  private readonly logger = new Logger(SmsController.name);
  private readonly validator = new MessageValidator();
  private readonly deliveryStatusTopicArn: string;

  constructor(
    private readonly smsService: SmsService,
    private readonly configService: ConfigService,
  ) {
    this.deliveryStatusTopicArn = this.configService.get<string&gt;('DELIVERY_STATUS_TOPIC_ARN');
    if (!this.deliveryStatusTopicArn) {
      this.logger.warn('DELIVERY_STATUS_TOPIC_ARN is not set in environment variables. Callback Topic ARN validation cannot be performed.');
    }
  }

  /**
   * Endpoint to send an SMS message.
   */
  @Post('send')
  @HttpCode(HttpStatus.ACCEPTED) // Use 202 Accepted as sending is async
  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
  async sendSms(@Body() sendSmsDto: SendSmsDto): Promise&lt;{ messageId: string; status: string }&gt; {
    this.logger.log(`Received request to send SMS to ${sendSmsDto.phoneNumber}`);
    const messageId = await this.smsService.sendSms(sendSmsDto.phoneNumber, sendSmsDto.message);
    return { messageId, status: 'Message submission accepted by SNS.' };
  }

  /**
   * Callback endpoint to receive delivery status notifications from AWS SNS.
   * IMPORTANT: This endpoint MUST be publicly accessible via HTTPS.
   * Uses `RawBodyRequest` to get the raw body for signature verification.
   */
  @Post('status/callback')
  @HttpCode(HttpStatus.OK) // Respond OK quickly to SNS to acknowledge receipt
  async handleSnsCallback(@Req() req: RawBodyRequest<Request&gt;, @Headers('x-amz-sns-message-type') messageType: string): Promise<string&gt; {
    // **Crucial:** Get the raw body. Ensure `json` body parser in main.ts is configured with `rawBody: true`.
    const rawBody = req.rawBody?.toString('utf8'); // Get raw body as UTF-8 string

    if (!rawBody) {
       this.logger.error('Raw body is missing from the request. Ensure rawBody:true is set for NestFactory.create in main.ts.');
       // Do not acknowledge SNS without raw body for validation. Returning non-200 might cause retries.
       // Consider returning a specific error message, but avoid overly detailed internal errors.
       return 'Error: Internal configuration error (missing raw body).';
    }

    let parsedBody: SnsNotificationRequest;
    try {
        parsedBody = JSON.parse(rawBody);
    } catch (e) {
        this.logger.error(`Failed to parse incoming SNS raw body: ${e.message}`, rawBody);
        return 'Error: Invalid JSON format in request body.';
    }


    this.logger.log(`Received SNS callback of type: ${messageType || parsedBody.Type}`); // Use header first, fallback to body
    this.logger.debug(`Parsed SNS callback body: ${JSON.stringify(parsedBody)}`); // Log parsed body for debug

    // 1. Validate the Message Signature (Security Critical!)
    try {
      const valid = await new Promise<boolean&gt;((resolve, reject) =&gt; {
        // Pass the parsed body object to the validator
        this.validator.validate(parsedBody, (err) =&gt; {
          if (err) {
            // Log the detailed validation error internally
            this.logger.error('SNS Message Validation Error:', err);
            return reject(err); // Reject the promise on error
          }
          this.logger.log('SNS message signature validated successfully.');
          resolve(true); // Resolve promise indicating validation success
        });
      });

      if (!valid) {
         // This path should theoretically not be reached if validation fails because the promise rejects.
         throw new Error('SNS Message validation failed silently (unexpected state).');
      }

      // Optional but Recommended: Verify Topic ARN matches expectation
      if (this.deliveryStatusTopicArn && parsedBody.TopicArn !== this.deliveryStatusTopicArn) {
           this.logger.warn(`Received message from unexpected Topic ARN: ${parsedBody.TopicArn}. Expected: ${this.deliveryStatusTopicArn}. Processing anyway (configurable behavior).`);
           // Decide whether to reject or just log based on security posture.
           // For now, we log a warning and proceed. Could return an error:
           // return 'Error: Invalid Topic ARN';
      }

    } catch (error) {
      this.logger.error(`SNS Message Signature Validation Failed: ${error.message}`, error.stack);
      // Do NOT process the message if validation fails.
      // **Why return 200 OK here?** Returning a 4xx/5xx error might cause SNS to retry sending the *same invalid message* repeatedly.
      // By returning 200 OK but logging the error, we acknowledge receipt to prevent retries for permanently invalid messages (like bad signatures).
      // Legitimate transient issues (network, temporary app failure) *should* return non-200 to trigger SNS retries.
      return 'Error: Invalid SNS message signature.'; // Return a generic error externally.
    }

    // 2. Handle Different SNS Message Types
    switch (parsedBody.Type) {
      case 'SubscriptionConfirmation':
        this.logger.log(`Received SubscriptionConfirmation from SNS for Topic: ${parsedBody.TopicArn}.`);
        // **ACTION REQUIRED:** You MUST visit the SubscribeURL to activate the subscription.
        // This proves you control the endpoint. You can do this manually during setup,
        // or add code here to programmatically fetch the URL (requires an HTTP client like axios/fetch).
        // For security, ensure you validate the SubscribeURL domain before fetching.
        this.logger.warn(`**ACTION REQUIRED:** You MUST visit this URL to confirm the SNS subscription: ${parsedBody.SubscribeURL}`);
        return 'SubscriptionConfirmation received. Please visit the SubscribeURL logged by the server to confirm.';

      case 'Notification':
        this.logger.log(`Received Notification from SNS. SNS MessageId: ${parsedBody.MessageId}`);
        try {
          // The 'Message' field is a JSON string containing the actual delivery status
          const deliveryStatus: SnsDeliveryStatusMessage = JSON.parse(parsedBody.Message);
          this.logger.debug(`Parsed Notification Message content: ${JSON.stringify(deliveryStatus)}`);

          // Extract the key information
          // Note: The original MessageId might be in `deliveryStatus.messageId` or `deliveryStatus.notification.messageId`
          const originalMessageId = deliveryStatus.messageId || deliveryStatus.notification?.messageId;
          const status = deliveryStatus.status;
          const destination = deliveryStatus.delivery?.destination;

          if (!originalMessageId || !status) {
              this.logger.warn('Notification message content is incomplete (missing original messageId or status).', deliveryStatus);
              // Still return OK to avoid retries for potentially malformed (but validly signed) messages.
              return 'Warning: Incomplete notification data received.';
          }

          // Pass the relevant payload to the service for processing/persistence
          // This structure matches the expected input for the updated `processDeliveryStatus` in Section 6.
          await this.smsService.processDeliveryStatus({
            messageId: originalMessageId,
            status: status.toUpperCase(), // Normalize status (e.g., 'SUCCESS', 'FAILURE')
            destination: destination,
            providerResponse: deliveryStatus.delivery?.providerResponse,
            fullPayload: deliveryStatus, // Pass the full parsed message for detailed logging/storage
          });

          return 'Notification processed successfully.';

        } catch (parseError) {
          this.logger.error(`Error parsing SNS Notification 'Message' field: ${parseError.message}`, parseError.stack);
          return 'Error: Could not parse notification message content.';
        }

      case 'UnsubscribeConfirmation':
        this.logger.log(`Received UnsubscribeConfirmation for TopicArn: ${parsedBody.TopicArn}. MessageId: ${parsedBody.MessageId}`);
        // Handle cleanup if necessary (e.g., update internal state if tracking subscriptions)
        return 'UnsubscribeConfirmation received.';

      default:
        this.logger.warn(`Received unknown SNS message type: '${parsedBody.Type}'. Body: ${JSON.stringify(parsedBody)}`);
        return 'Unknown message type received.';
    }
  }
}

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    // Enable raw body parsing globally. This makes `req.rawBody` available in controllers.
    rawBody: true,
  });

  const configService = app.get(ConfigService);
  const port = configService.get<number&gt;('PORT') || 3000;
  const logger = new Logger('Bootstrap'); // Create a logger instance

  // Enable global validation pipes
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true, // Strip properties not defined in DTOs
    transform: true, // Automatically transform payloads to DTO instances
  }));

  await app.listen(port);
  logger.log(`Application listening on port ${port}`);
  logger.log(`Callback endpoint expected at: /sms/status/callback`);
}
bootstrap();