Developer Guide: Implementing RedwoodJS AWS SNS Delivery Status Callbacks Using Node.js

graph LR
    A[RedwoodJS App UI/Service] -- 1. Send SMS Request --> B(RedwoodJS SMS Service);
    B -- 2. Publish SMS via SDK --> C(AWS SNS);
    C -- 3. Delivers SMS --> D(End User Device);
    C -- 4. Sends Status Update (HTTPS POST) --> E(RedwoodJS Callback Function /snsCallback);
    E -- 5. Verify SNS Signature --> E;
    E -- 6. Parse Status & Update DB --> F(Database);

    subgraph AWS Cloud
        C
    end

    subgraph RedwoodJS API
        B
        E
        F
    end

    subgraph User Interaction
        A
        D
    end

yarn create redwood-app ./redwood-sns-callbacks
cd redwood-sns-callbacks

yarn workspace api add @aws-sdk/client-sns aws-sns-message-validator

# .env
AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
AWS_SECRET_ACCESS_KEY="YOUR_SECRET_ACCESS_KEY"
AWS_REGION="us-east-1" # Or your preferred region
SNS_DELIVERY_STATUS_TOPIC_ARN="arn:aws:sns:us-east-1:123456789012:sms-delivery-status-topic" # Replace with your ACTUAL topic ARN

// api/db/schema.prisma

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

generator client {
  provider      = ""prisma-client-js""
  binaryTargets = ""native""
}

// Add this model
model SmsMessage {
  id            String   @id @default(cuid()) // Using CUID for IDs
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt

  toPhoneNumber String
  messageBody   String
  awsMessageId  String?  @unique // The MessageId returned by SNS publish
  deliveryStatus String? // e.g., 'PENDING', 'DELIVERED', 'FAILED'
  statusPayload Json?    // Store the raw status payload from SNS
  sentSuccessfully Boolean @default(false) // Track if the initial publish call succeeded
}

yarn rw prisma migrate dev --name add_sms_message

yarn rw g service sms

// api/src/services/sms/sms.ts
import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';
import type { PublishCommandInput } from '@aws-sdk/client-sns';
import { db } from 'src/lib/db'; // Import Redwood's Prisma client
import { logger } from 'src/lib/logger'; // Import Redwood's logger

const region = process.env.AWS_REGION;
const snsClient = new SNSClient({ region });

interface SendSmsInput {
  toPhoneNumber: string; // E.164 format (e.g., +15551234567)
  messageBody: string;
}

export const sendSms = async ({ toPhoneNumber, messageBody }: SendSmsInput) => {
  logger.info(
    `Attempting to send SMS to ${toPhoneNumber} via AWS SNS`
  );

  // 1. Create initial record in the database
  let smsRecord;
  try {
    smsRecord = await db.smsMessage.create({
      data: {
        toPhoneNumber,
        messageBody,
        deliveryStatus: 'PENDING', // Initial status
      },
    });
    logger.debug({ custom: { smsRecordId: smsRecord.id } }, 'SMS record created');
  } catch (dbError) {
    logger.error({ custom: { dbError } }, 'Failed to create SMS record in DB');
    // Depending on requirements, you might want to throw or return an error here
    // to prevent attempting the SNS publish if DB write fails.
    throw new Error('Database error creating SMS record.');
  }

  // 2. Prepare the SNS Publish command
  const params: PublishCommandInput = {
    Message: messageBody,
    PhoneNumber: toPhoneNumber,
    MessageAttributes: {
      // Optional: You can set a default Sender ID here if configured in SNS
      // 'AWS.SNS.SMS.SenderID': {
      //   DataType: 'String',
      //   StringValue: 'MySenderID'
      // },
      'AWS.SNS.SMS.SMSType': {
        DataType: 'String',
        StringValue: 'Transactional', // Or 'Promotional'
      },
    },
  };

  // 3. Send the message via SNS
  try {
    const command = new PublishCommand(params);
    const data = await snsClient.send(command);

    logger.info(
      { custom: { awsMessageId: data.MessageId, smsRecordId: smsRecord.id } },
      'SMS successfully published to SNS'
    );

    // 4. Update the DB record with the AWS Message ID and success status
    const updatedRecord = await db.smsMessage.update({
      where: { id: smsRecord.id },
      data: {
        awsMessageId: data.MessageId,
        sentSuccessfully: true, // Mark the publish call as successful
      },
    });

    return {
      success: true,
      message: 'SMS submitted to SNS successfully.',
      databaseId: updatedRecord.id,
      awsMessageId: data.MessageId,
    };
  } catch (error) {
    logger.error(
      { custom: { error, smsRecordId: smsRecord.id } },
      'Failed to publish SMS via SNS'
    );
    // Optionally update the DB record to reflect the publish failure
    await db.smsMessage.update({
      where: { id: smsRecord.id },
      data: {
        deliveryStatus: 'PUBLISH_FAILED',
        sentSuccessfully: false,
      },
    }).catch(updateError => {
      logger.error({ custom: { updateError, smsRecordId: smsRecord.id }}, 'Failed to update SMS record after SNS publish failure');
    });

    return {
      success: false,
      message: 'Failed to submit SMS to SNS.',
      error: error.message,
      databaseId: smsRecord.id,
    };
  }
};

// Optional: Add SDL for GraphQL API if needed
// api/src/graphql/sms.sdl.ts
export const schema = gql`
  type SmsSendResponse {
    success: Boolean!
    message: String!
    databaseId: String
    awsMessageId: String
    error: String
  }

  type Mutation {
    sendSms(toPhoneNumber: String!, messageBody: String!): SmsSendResponse! @requireAuth
  }
`;

// Optional: Add service resolvers if using GraphQL
// api/src/services/sms/sms.ts (add this to the existing file)
/*
export const Mutation = {
  sendSms: (_parent, { toPhoneNumber, messageBody }: SendSmsInput, _context) => {
    // Add authorization/validation checks here if needed
    return sendSms({ toPhoneNumber, messageBody });
  },
};
*/

yarn rw g function snsCallback

// api/src/functions/snsCallback.ts
import type { APIGatewayEvent, Context } from 'aws-lambda';
import { MessageValidator } from 'aws-sns-message-validator';
import { db } from 'src/lib/db';
import { logger } from 'src/lib/logger';

// Instantiate the validator
const validator = new MessageValidator();

// Define expected structure of the SNS message body (adjust based on actual payloads)
interface SnsNotificationPayload {
  Type: 'SubscriptionConfirmation' | 'Notification' | 'UnsubscribeConfirmation';
  MessageId: string;
  Token?: string; // Only for SubscriptionConfirmation
  TopicArn: string;
  Subject?: string;
  Message: string; // This will be a JSON string for delivery status
  SubscribeURL?: string; // Only for SubscriptionConfirmation
  Timestamp: string;
  SignatureVersion: string;
  Signature: string;
  SigningCertURL: string;
}

interface DeliveryStatusMessage {
  notification: {
    messageId: string; // Corresponds to the original SNS publish MessageId
    timestamp: string;
  };
  delivery: {
    phoneCarrier: string;
    mnc: number;
    destination: string; // The recipient phone number
    priceInUSD: number;
    smsType: string;
    mcc: number;
    providerResponse: string; // Provider-specific info, can be useful for debugging
    dwellTimeMs: number;
    dwellTimeMsUntilDeviceAck?: number; // May be present for successful deliveries
  };
  status: 'SUCCESS' | 'FAILURE'; // The actual delivery status
}

export const handler = async (event: APIGatewayEvent, _context: Context) => {
  logger.debug({ custom: event.headers }, 'Received request on /snsCallback');

  if (!event.body) {
    logger.error('Request body is missing');
    return { statusCode: 400, body: 'Bad Request: Missing body' };
  }

  let snsPayload: SnsNotificationPayload;
  try {
    // AWS often sends the payload with escaped quotes, requires careful parsing
    snsPayload = JSON.parse(event.body);
    logger.debug({ custom: snsPayload }, 'Parsed SNS Payload');
  } catch (error) {
    logger.error({ custom: { body: event.body, error } }, 'Failed to parse request body as JSON');
    return { statusCode: 400, body: 'Bad Request: Invalid JSON' };
  }

  // 1. Validate the incoming message signature (CRITICAL for security)
  try {
    await new Promise<void>((resolve, reject) => {
      validator.validate(snsPayload, (err, message) => {
        if (err) {
          logger.error({ custom: { error: err, snsPayload } }, 'SNS Message validation failed');
          return reject(err);
        }
        logger.info({ custom: { messageId: message.MessageId } }, 'SNS Message signature validated successfully');
        resolve();
      });
    });
  } catch (validationError) {
    return { statusCode: 403, body: 'Forbidden: Invalid SNS message signature' };
  }

  // 2. Handle Subscription Confirmation
  if (snsPayload.Type === 'SubscriptionConfirmation') {
    logger.info(
      { custom: { subscribeUrl: snsPayload.SubscribeURL } },
      'Received SNS Subscription Confirmation'
    );
    try {
      // IMPORTANT: You MUST visit the SubscribeURL to confirm the subscription.
      // In a real app, you might make an HTTP GET request here programmatically.
      // For initial setup, you can copy/paste the URL from the logs into your browser.
      const response = await fetch(snsPayload.SubscribeURL);
      if (!response.ok) {
         throw new Error(`Failed to confirm subscription: ${response.statusText}`);
      }
      logger.info('Successfully confirmed SNS subscription via SubscribeURL');
      return { statusCode: 200, body: 'Subscription confirmed' };
    } catch (error) {
      logger.error({ custom: { error } }, 'Failed to automatically confirm SNS subscription');
      // Return 200 anyway so SNS doesn't retry indefinitely, but log the error.
      // Manual confirmation via console/logs might be needed.
      return { statusCode: 200, body: 'Subscription confirmation received, but auto-confirm failed. Check logs.' };
    }
  }

  // 3. Handle Delivery Status Notification
  if (snsPayload.Type === 'Notification') {
    logger.info({ custom: { messageId: snsPayload.MessageId } }, 'Received SNS Notification');

    let deliveryStatus: DeliveryStatusMessage;
    try {
      deliveryStatus = JSON.parse(snsPayload.Message);
      logger.debug({ custom: deliveryStatus }, 'Parsed Delivery Status Message');
    } catch (error) {
      logger.error(
        { custom: { message: snsPayload.Message, error } },
        'Failed to parse SNS Message content as JSON (delivery status)'
      );
      return { statusCode: 400, body: 'Bad Request: Invalid Message JSON' };
    }

    const awsMessageId = deliveryStatus.notification.messageId;
    const status = deliveryStatus.status === 'SUCCESS' ? 'DELIVERED' : 'FAILED';

    // 4. Update the corresponding database record
    try {
      const updatedRecord = await db.smsMessage.update({
        where: { awsMessageId: awsMessageId },
        data: {
          deliveryStatus: status,
          statusPayload: deliveryStatus as any, // Store the full payload as JSON
          updatedAt: new Date(), // Explicitly set update time
        },
      });
      logger.info(
        { custom: { awsMessageId, newStatus: status, dbId: updatedRecord.id } },
        'Successfully updated SMS message status in database'
      );
      return { statusCode: 200, body: 'Notification processed successfully' };
    } catch (error) {
      // Handle case where messageId might not be found (e.g., race condition, data issue)
      if (error.code === 'P2025') { // Prisma code for record not found
         logger.warn({ custom: { awsMessageId } }, 'Could not find matching SMS record for update. Maybe already processed or invalid ID.');
         // Return 200 so SNS doesn't retry, as we can't fix this by retrying.
         return { statusCode: 200, body: 'Notification acknowledged, but no matching record found.' };
      }
      logger.error(
        { custom: { awsMessageId, error } },
        'Failed to update SMS message status in database'
      );
      // Return 500 to potentially trigger SNS retries if it was a transient DB error
      return { statusCode: 500, body: 'Internal Server Error: Database update failed' };
    }
  }

  // Handle other types like UnsubscribeConfirmation if necessary
  logger.warn({ custom: { type: snsPayload.Type } }, 'Received unhandled SNS message type');
  return { statusCode: 200, body: 'Unhandled message type received' };
};

// api/src/services/sms/sms.test.ts
import { mock } from 'jest-mock-extended';
import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';
import { sendSms } from './sms';
import { db } from 'src/lib/db'; // Import db for potential mocking/spying if needed

// Mock the AWS SDK v3 client
jest.mock('@aws-sdk/client-sns', () => {
  const originalModule = jest.requireActual('@aws-sdk/client-sns');
  return {
    ...originalModule,
    SNSClient: jest.fn(() => ({ // Mock the constructor
      send: jest.fn(), // Mock the send method
    })),
    PublishCommand: jest.fn((input) => ({ // Mock the command constructor
      input, // Store input for inspection if needed
    })),
  };
});

// Mock the db client (optional, depending on test granularity)
// jest.mock('src/lib/db', () => ({
//   db: {
//     smsMessage: {
//       create: jest.fn(),
//       update: jest.fn(),
//     },
//   },
// }))

describe('sms service', () => {
  const mockSnsClient = new SNSClient({}); // Instance of the mocked client
  const mockSend = mockSnsClient.send as jest.Mock; // Get the mocked send method

  beforeEach(() => {
    jest.clearAllMocks(); // Clear mocks between tests

    // Mock successful DB operations if db is mocked
    // (db.smsMessage.create as jest.Mock).mockResolvedValue({ id: 'sms-cuid-123' });
    // (db.smsMessage.update as jest.Mock).mockResolvedValue({ id: 'sms-cuid-123', awsMessageId: 'mock-aws-id-xyz' });
  });

  it('sendSms successfully publishes to SNS and updates DB', async () => {
    const toPhoneNumber = '+15550001111';
    const messageBody = 'Test message';
    const mockAwsMessageId = 'mock-aws-id-xyz';

    // Mock successful SNS response
    mockSend.mockResolvedValueOnce({ MessageId: mockAwsMessageId });

    // Mock DB interactions (if not using real test DB)
    const mockDbCreate = jest.spyOn(db.smsMessage, 'create').mockResolvedValueOnce({
      id: 'sms-cuid-123', createdAt: new Date(), updatedAt: new Date(),
      toPhoneNumber, messageBody, awsMessageId: null, deliveryStatus: 'PENDING',
      statusPayload: null, sentSuccessfully: false
    });
    const mockDbUpdate = jest.spyOn(db.smsMessage, 'update').mockResolvedValueOnce({
      id: 'sms-cuid-123', createdAt: new Date(), updatedAt: new Date(),
      toPhoneNumber, messageBody, awsMessageId: mockAwsMessageId, deliveryStatus: 'PENDING',
      statusPayload: null, sentSuccessfully: true
    });


    const result = await sendSms({ toPhoneNumber, messageBody });

    expect(result.success).toBe(true);
    expect(result.awsMessageId).toBe(mockAwsMessageId);
    expect(result.databaseId).toBe('sms-cuid-123'); // Comes from the DB mock
    expect(mockSend).toHaveBeenCalledTimes(1);
    // Optionally inspect the input passed to PublishCommand
    // expect(PublishCommand).toHaveBeenCalledWith({ Message: messageBody, PhoneNumber: toPhoneNumber, ... });
    expect(mockDbCreate).toHaveBeenCalledWith({ data: { toPhoneNumber, messageBody, deliveryStatus: 'PENDING' } });
    expect(mockDbUpdate).toHaveBeenCalledWith({ where: { id: 'sms-cuid-123' }, data: { awsMessageId: mockAwsMessageId, sentSuccessfully: true } });
  });

  it('sendSms handles SNS publish failure', async () => {
     const toPhoneNumber = '+15552223333';
     const messageBody = 'Failure test';
     const errorMessage = 'SNS publish failed miserably';

     // Mock failed SNS response
     mockSend.mockRejectedValueOnce(new Error(errorMessage));

     // Mock DB interactions
     const mockDbCreate = jest.spyOn(db.smsMessage, 'create').mockResolvedValueOnce({
       id: 'sms-fail-456', createdAt: new Date(), updatedAt: new Date(),
       toPhoneNumber, messageBody, awsMessageId: null, deliveryStatus: 'PENDING',
       statusPayload: null, sentSuccessfully: false
     });
     // Mock the update that happens on failure
     const mockDbUpdateOnFail = jest.spyOn(db.smsMessage, 'update').mockResolvedValueOnce({
       id: 'sms-fail-456', createdAt: new Date(), updatedAt: new Date(),
       toPhoneNumber, messageBody, awsMessageId: null, deliveryStatus: 'PUBLISH_FAILED',
       statusPayload: null, sentSuccessfully: false
     });


     const result = await sendSms({ toPhoneNumber, messageBody });

     expect(result.success).toBe(false);
     expect(result.error).toBe(errorMessage);
     expect(result.databaseId).toBe('sms-fail-456');
     expect(mockSend).toHaveBeenCalledTimes(1);
     expect(mockDbCreate).toHaveBeenCalledTimes(1);
     expect(mockDbUpdateOnFail).toHaveBeenCalledWith({
        where: { id: 'sms-fail-456' },
        data: { deliveryStatus: 'PUBLISH_FAILED', sentSuccessfully: false }
     });
  });

  // Add more tests: DB create failure, etc.
});

// api/src/functions/snsCallback.test.ts
import { mockHttpEvent } from '@redwoodjs/testing/api';
import { handler } from './snsCallback';
import { MessageValidator } from 'aws-sns-message-validator';
import { db } from 'src/lib/db';
import { logger } from 'src/lib/logger'; // Import to potentially spy on logs

// Mock the validator
jest.mock('aws-sns-message-validator', () => ({
  MessageValidator: jest.fn().mockImplementation(() => ({
    validate: jest.fn((payload, callback) => {
      // Default mock: Successful validation
      // You can override this in specific tests if needed
      if (payload?.Signature === 'INVALID_SIGNATURE_FOR_TEST') {
        // Simulate validation failure
        callback(new Error('Invalid signature'));
      } else if (payload?.Type === 'SubscriptionConfirmation' && payload?.SubscribeURL) {
        // Simulate successful validation for subscription confirmation
        callback(null, payload);
      } else if (payload?.Type === 'Notification' && payload?.MessageId) {
        // Simulate successful validation for notification
        callback(null, payload);
      } else {
        // Default success case or handle other scenarios
        callback(null, payload);
      }
    }),
  })),
}));

// Mock the db client
jest.mock('src/lib/db', () => ({
  db: {
    smsMessage: {
      update: jest.fn(),
    },
  },
}));

// Mock fetch for subscription confirmation
global.fetch = jest.fn();

// Mock logger (optional, to suppress or check logs)
jest.mock('src/lib/logger', () => ({
  logger: {
    info: jest.fn(),
    error: jest.fn(),
    warn: jest.fn(),
    debug: jest.fn(),
  },
}));


describe('snsCallback handler', () => {
  const mockDbUpdate = db.smsMessage.update as jest.Mock;
  const mockFetch = global.fetch as jest.Mock;
  const mockValidatorInstance = new MessageValidator({});
  const mockValidate = mockValidatorInstance.validate as jest.Mock;

  beforeEach(() => {
    jest.clearAllMocks();
    // Reset fetch mock to default successful response for subscription confirmation
    mockFetch.mockResolvedValue({ ok: true, statusText: 'OK' });
  });

  it('returns 400 if body is missing', async () => {
    const event = mockHttpEvent({}); // No body
    const response = await handler(event, null);
    expect(response.statusCode).toBe(400);
    expect(response.body).toContain('Missing body');
  });

  it('returns 400 if body is invalid JSON', async () => {
    const event = mockHttpEvent({ body: '{invalid json' });
    const response = await handler(event, null);
    expect(response.statusCode).toBe(400);
    expect(response.body).toContain('Invalid JSON');
  });

  it('returns 403 if SNS signature validation fails', async () => {
    const invalidPayload = {
      Type: 'Notification',
      MessageId: 'test-msg-id',
      TopicArn: 'arn:aws:sns:us-east-1:123456789012:test-topic',
      Message: '{}',
      Timestamp: new Date().toISOString(),
      SignatureVersion: '1',
      Signature: 'INVALID_SIGNATURE_FOR_TEST', // Trigger failure in mock
      SigningCertURL: 'https://example.com/cert.pem',
    };
    const event = mockHttpEvent({ body: JSON.stringify(invalidPayload) });

    const response = await handler(event, null);

    expect(mockValidate).toHaveBeenCalled();
    expect(response.statusCode).toBe(403);
    expect(response.body).toContain('Invalid SNS message signature');
  });

  it('handles SubscriptionConfirmation successfully', async () => {
    const subscribeUrl = 'https://example.com/subscribe?token=123';
    const subscriptionPayload = {
      Type: 'SubscriptionConfirmation',
      MessageId: 'sub-conf-id',
      Token: '123',
      TopicArn: 'arn:aws:sns:us-east-1:123456789012:test-topic',
      Message: 'You have chosen to subscribe to the topic...',
      SubscribeURL: subscribeUrl,
      Timestamp: new Date().toISOString(),
      SignatureVersion: '1',
      Signature: 'VALID_SIGNATURE',
      SigningCertURL: 'https://example.com/cert.pem',
    };
    const event = mockHttpEvent({ body: JSON.stringify(subscriptionPayload) });

    const response = await handler(event, null);

    expect(mockValidate).toHaveBeenCalledWith(subscriptionPayload, expect.any(Function));
    expect(mockFetch).toHaveBeenCalledWith(subscribeUrl);
    expect(response.statusCode).toBe(200);
    expect(response.body).toContain('Subscription confirmed');
    expect(logger.info).toHaveBeenCalledWith(expect.stringContaining('Successfully confirmed SNS subscription'));
  });

   it('handles SubscriptionConfirmation failure during fetch', async () => {
    const subscribeUrl = 'https://example.com/subscribe?token=456';
    const subscriptionPayload = { /* ... same structure as above ... */
      Type: 'SubscriptionConfirmation', MessageId: 'sub-conf-id-fail', Token: '456',
      TopicArn: 'arn:aws:sns:us-east-1:123456789012:test-topic', Message: 'Sub message',
      SubscribeURL: subscribeUrl, Timestamp: new Date().toISOString(), SignatureVersion: '1',
      Signature: 'VALID_SIGNATURE', SigningCertURL: 'https://example.com/cert.pem',
    };
    const event = mockHttpEvent({ body: JSON.stringify(subscriptionPayload) });

    // Mock fetch to fail
    mockFetch.mockResolvedValueOnce({ ok: false, statusText: 'Not Found' });

    const response = await handler(event, null);

    expect(mockValidate).toHaveBeenCalled();
    expect(mockFetch).toHaveBeenCalledWith(subscribeUrl);
    expect(response.statusCode).toBe(200); // Still 200 to avoid SNS retries
    expect(response.body).toContain('auto-confirm failed');
    expect(logger.error).toHaveBeenCalledWith(expect.objectContaining({ custom: { error: expect.any(Error) } }), expect.stringContaining('Failed to automatically confirm'));
  });


  it('handles Notification for SUCCESS status and updates DB', async () => {
    const awsMessageId = 'sns-publish-id-123';
    const deliveryStatusMessage: DeliveryStatusMessage = {
      notification: { messageId: awsMessageId, timestamp: new Date().toISOString() },
      delivery: { destination: '+15559998888', smsType: 'Transactional', /* other fields */ } as any,
      status: 'SUCCESS',
    };
    const notificationPayload = {
      Type: 'Notification',
      MessageId: 'sns-callback-id-abc',
      TopicArn: 'arn:aws:sns:us-east-1:123456789012:sms-delivery-status-topic',
      Message: JSON.stringify(deliveryStatusMessage),
      Timestamp: new Date().toISOString(),
      SignatureVersion: '1',
      Signature: 'VALID_SIGNATURE',
      SigningCertURL: 'https://example.com/cert.pem',
    };
    const event = mockHttpEvent({ body: JSON.stringify(notificationPayload) });

    // Mock successful DB update
    mockDbUpdate.mockResolvedValueOnce({ id: 'db-record-id-xyz', awsMessageId });

    const response = await handler(event, null);

    expect(mockValidate).toHaveBeenCalled();
    expect(mockDbUpdate).toHaveBeenCalledWith({
      where: { awsMessageId: awsMessageId },
      data: {
        deliveryStatus: 'DELIVERED',
        statusPayload: deliveryStatusMessage,
        updatedAt: expect.any(Date),
      },
    });
    expect(response.statusCode).toBe(200);
    expect(response.body).toContain('Notification processed successfully');
    expect(logger.info).toHaveBeenCalledWith(expect.objectContaining({ custom: { awsMessageId, newStatus: 'DELIVERED' } }), expect.stringContaining('Successfully updated SMS message status'));
  });

  it('handles Notification for FAILURE status and updates DB', async () => {
    const awsMessageId = 'sns-publish-id-456';
    const deliveryStatusMessage: DeliveryStatusMessage = {
      notification: { messageId: awsMessageId, timestamp: new Date().toISOString() },
      delivery: { destination: '+15557776666', smsType: 'Transactional', /* other fields */ } as any,
      status: 'FAILURE',
    };
    const notificationPayload = { /* ... same structure as success ... */
       Type: 'Notification', MessageId: 'sns-callback-id-def', TopicArn: '...',
       Message: JSON.stringify(deliveryStatusMessage), Timestamp: '...', SignatureVersion: '1',
       Signature: 'VALID_SIGNATURE', SigningCertURL: '...',
    };
    const event = mockHttpEvent({ body: JSON.stringify(notificationPayload) });

    mockDbUpdate.mockResolvedValueOnce({ id: 'db-record-id-abc', awsMessageId });

    const response = await handler(event, null);

    expect(mockValidate).toHaveBeenCalled();
    expect(mockDbUpdate).toHaveBeenCalledWith(expect.objectContaining({
      data: expect.objectContaining({ deliveryStatus: 'FAILED' })
    }));
    expect(response.statusCode).toBe(200);
    expect(response.body).toContain('Notification processed successfully');
     expect(logger.info).toHaveBeenCalledWith(expect.objectContaining({ custom: { awsMessageId, newStatus: 'FAILED' } }), expect.stringContaining('Successfully updated SMS message status'));
  });


  it('returns 400 if Notification Message is invalid JSON', async () => {
     const notificationPayload = {
      Type: 'Notification', MessageId: 'sns-callback-id-ghi', TopicArn: '...',
      Message: '{invalid json inside message', // Invalid JSON in Message
      Timestamp: '...', SignatureVersion: '1', Signature: 'VALID_SIGNATURE', SigningCertURL: '...',
    };
    const event = mockHttpEvent({ body: JSON.stringify(notificationPayload) });

    const response = await handler(event, null);

    expect(mockValidate).toHaveBeenCalled();
    expect(response.statusCode).toBe(400);
    expect(response.body).toContain('Invalid Message JSON');
    expect(logger.error).toHaveBeenCalledWith(expect.anything(), expect.stringContaining('Failed to parse SNS Message content'));
  });

  it('returns 200 if DB update fails with record not found (P2025)', async () => {
    const awsMessageId = 'sns-publish-id-789-notfound';
    const deliveryStatusMessage: DeliveryStatusMessage = { /* ... */ } as any;
     deliveryStatusMessage.notification = { messageId: awsMessageId, timestamp: '...' };
     deliveryStatusMessage.status = 'SUCCESS';
    const notificationPayload = { /* ... */ } as any;
    notificationPayload.Type = 'Notification';
    notificationPayload.Message = JSON.stringify(deliveryStatusMessage);
    notificationPayload.Signature = 'VALID_SIGNATURE'; // Ensure validation passes
    const event = mockHttpEvent({ body: JSON.stringify(notificationPayload) });

    // Mock DB update to throw Prisma "Record not found" error
    const notFoundError = new Error('Record to update not found.');
    notFoundError.code = 'P2025';
    mockDbUpdate.mockRejectedValueOnce(notFoundError);

    const response = await handler(event, null);

    expect(mockValidate).toHaveBeenCalled();
    expect(mockDbUpdate).toHaveBeenCalled();
    expect(response.statusCode).toBe(200); // Acknowledge to SNS, don't retry
    expect(response.body).toContain('no matching record found');
    expect(logger.warn).toHaveBeenCalledWith(expect.objectContaining({ custom: { awsMessageId } }), expect.stringContaining('Could not find matching SMS record'));
  });

  it('returns 500 if DB update fails with other error', async () => {
    const awsMessageId = 'sns-publish-id-101-dberror';
     const deliveryStatusMessage: DeliveryStatusMessage = { /* ... */ } as any;
     deliveryStatusMessage.notification = { messageId: awsMessageId, timestamp: '...' };
     deliveryStatusMessage.status = 'FAILURE';
    const notificationPayload = { /* ... */ } as any;
    notificationPayload.Type = 'Notification';
    notificationPayload.Message = JSON.stringify(deliveryStatusMessage);
    notificationPayload.Signature = 'VALID_SIGNATURE';
    const event = mockHttpEvent({ body: JSON.stringify(notificationPayload) });

    // Mock DB update to throw a generic error
    const dbError = new Error('Database connection lost');
    mockDbUpdate.mockRejectedValueOnce(dbError);

    const response = await handler(event, null);

    expect(mockValidate).toHaveBeenCalled();
    expect(mockDbUpdate).toHaveBeenCalled();
    expect(response.statusCode).toBe(500); // Signal potential retry to SNS
    expect(response.body).toContain('Database update failed');
    expect(logger.error).toHaveBeenCalledWith(expect.objectContaining({ custom: { awsMessageId, error: dbError } }), expect.stringContaining('Failed to update SMS message status'));
  });

  it('handles unhandled SNS message types gracefully', async () => {
     const unhandledPayload = {
      Type: 'UnsubscribeConfirmation', // Or any other type not explicitly handled
      MessageId: 'unsub-id', TopicArn: '...', Message: '...', Timestamp: '...',
      SignatureVersion: '1', Signature: 'VALID_SIGNATURE', SigningCertURL: '...',
    };
    const event = mockHttpEvent({ body: JSON.stringify(unhandledPayload) });

    const response = await handler(event, null);

    expect(mockValidate).toHaveBeenCalled();
    expect(response.statusCode).toBe(200);
    expect(response.body).toContain('Unhandled message type received');
    expect(logger.warn).toHaveBeenCalledWith(expect.objectContaining({ custom: { type: 'UnsubscribeConfirmation' } }), expect.stringContaining('Received unhandled SNS message type'));
  });

});