# Using Yarn
yarn create redwood-app ./sinch-redwood-callbacks

# Or using npm
npx create-redwood-app ./sinch-redwood-callbacks

cd sinch-redwood-callbacks

touch .env

# .env

# --- Database ---
# Replace with your actual database connection string
# Example for PostgreSQL: DATABASE_URL="postgresql://user:password@host:port/database?schema=public"
# Example for SQLite (default): DATABASE_URL="file:./dev.db"
DATABASE_URL="file:./dev.db"

# --- Sinch API Credentials ---
# Found on your Sinch Customer Dashboard under your API/Service Plan
SINCH_SERVICE_PLAN_ID="YOUR_SERVICE_PLAN_ID"
SINCH_API_TOKEN="YOUR_API_TOKEN"

# --- Sinch Webhook Security ---
# A secret string you create. Must match the secret configured in the Sinch Dashboard for the callback URL.
# Generate a strong random string (e.g., using `openssl rand -hex 32`, a password manager, or other secure generator)
SINCH_WEBHOOK_SECRET="YOUR_STRONG_RANDOM_SECRET_STRING"

# --- RedwoodJS Logger ---
# Optional: Set log level (trace, debug, info, warn, error, fatal)
LOG_LEVEL="info"

yarn rw prisma migrate dev --name initial_setup

yarn rw g function sinchCallbacks --ts

// api/src/functions/sinchCallbacks.ts
import type { APIGatewayEvent, Context } from 'aws-lambda'
import { logger } from 'src/lib/logger'

/**
 * The handler function is your code that processes http request events.
 * You already have access to the logger and use it to log any errors.
 *
 * @typedef { import('aws-lambda').APIGatewayEvent } APIGatewayEvent
 * @typedef { import('aws-lambda').Context } Context
 * @param { APIGatewayEvent } event - an object which contains information from the invoker.
 * @param { Context } context - contains information about the invocation,
 * function, and execution environment.
 */
export const handler = async (event: APIGatewayEvent, context: Context) => {
  logger.info('Incoming request to sinchCallbacks function')

  // Basic validation: Ensure it's a POST request
  if (event.httpMethod !== 'POST') {
    logger.warn('Received non-POST request')
    return {
      statusCode: 405, // Method Not Allowed
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ error: 'Method Not Allowed' }),
    }
  }

  // TODO: Add HMAC Signature Validation
  // TODO: Parse Request Body
  // TODO: Process Callback Data (using a Service)
  // TODO: Return appropriate response to Sinch

  return {
    statusCode: 200, // Placeholder: Acknowledge receipt
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: 'Callback received' }),
  }
}

{
  "type": "recipient_delivery_report_sms",
  "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
  "recipient": "+15551231234",
  "code": 401,
  "status": "Dispatched",
  "at": "2022-08-30T08:16:08.930Z",
  "operator_status_at": "2022-08-30T08:16:08.900Z",
  "client_reference": "your_optional_reference_123"
}

# NOTE: Replace YOUR_ENDPOINT_URL with your actual ngrok or deployed URL
# NOTE: This example does *not* include the HMAC signature yet.
curl -X POST \
  YOUR_ENDPOINT_URL/api/sinchCallbacks \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "recipient_delivery_report_sms",
    "batch_id": "TEST_BATCH_ID_123",
    "recipient": "+15559998888",
    "code": 0,
    "status": "Delivered",
    "at": "2025-04-20T10:00:00.000Z"
  }'

# Replace placeholders with your actual values
SINCH_SERVICE_PLAN_ID=""YOUR_SERVICE_PLAN_ID""
SINCH_API_TOKEN=""YOUR_API_TOKEN""
YOUR_SINCH_NUMBER_OR_ALPHANUMERIC=""YOUR_SENDER_ID""

curl -X POST \
  ""https://us.sms.api.sinch.com/xms/v1/${SINCH_SERVICE_PLAN_ID}/batches"" \
  -H ""Authorization: Bearer ${SINCH_API_TOKEN}"" \
  -H 'Content-Type: application/json' \
  -d '{
    ""from"": ""'""${YOUR_SINCH_NUMBER_OR_ALPHANUMERIC}""'"",
    ""to"": [ ""+15551234567"" ],
    ""body"": ""Hello from RedwoodJS!"",
    ""delivery_report"": ""per_recipient"",
    ""client_reference"": ""optional_your_ref_123""
  }'

// api/src/functions/sinchCallbacks.ts
import type { APIGatewayEvent, Context } from 'aws-lambda'
import { logger } from 'src/lib/logger'
// Import validation function (we'll create this in the Security section)
import { validateSinchSignature } from 'src/lib/sinchSecurity'
// Import the service function (we'll create this in the Data Layer section)
import { recordSmsStatusUpdate } from 'src/services/smsStatus/smsStatus'

// Define an interface for the expected callback payload
interface SinchRecipientDeliveryReport {
  type: 'recipient_delivery_report_sms' | 'recipient_delivery_report_mms' // Focus on SMS
  batch_id: string
  recipient: string
  code: number
  status: string
  at: string // ISO 8601 timestamp string
  operator_status_at?: string
  client_reference?: string
  // Add other potential fields if needed
}

export const handler = async (event: APIGatewayEvent, context: Context) => {
  // Use a unique request ID for logging correlation if available
  const requestId = context.awsRequestId || `local-${Date.now()}`
  const handlerLogger = logger.child({ requestId })
  handlerLogger.info('Incoming request to sinchCallbacks function')

  // 1. Basic Method Validation
  if (event.httpMethod !== 'POST') {
    handlerLogger.warn('Received non-POST request')
    return { statusCode: 405, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ error: 'Method Not Allowed' }) }
  }

  // 2. HMAC Signature Validation (Covered in Security Section)
  try {
    // Pass the raw body string. Ensure your deployment environment provides it.
    // RedwoodJS typically makes the raw body available in event.body when Content-Type is application/json.
    const rawBody = event.body
    if (rawBody === null || rawBody === undefined) {
        handlerLogger.error('Raw request body is missing or null.')
        // Return 400 as the request is fundamentally malformed for signature validation
        return { statusCode: 400, body: JSON.stringify({ error: 'Bad Request: Missing body' }) }
    }

    const webhookSecret = process.env.SINCH_WEBHOOK_SECRET
    if (!webhookSecret) {
      handlerLogger.error('SINCH_WEBHOOK_SECRET environment variable is not set.')
      // Return 500 as this is a server configuration issue
      return { statusCode: 500, body: JSON.stringify({ error: 'Internal Server Error: Webhook secret not configured' }) }
    }

    const isValid = validateSinchSignature(
      event.headers,
      rawBody,
      webhookSecret
    )
    if (!isValid) {
      handlerLogger.error('Invalid Sinch signature')
      return { statusCode: 401, body: JSON.stringify({ error: 'Unauthorized' }) }
    }
    handlerLogger.info('Sinch signature validated successfully')
  } catch (error) {
    handlerLogger.error({ error }, 'Error during signature validation')
    // Treat unexpected validation errors as potential bad requests or internal issues
    return { statusCode: 400, body: JSON.stringify({ error: 'Signature validation failed' }) }
  }

  // 3. Parse Request Body
  let payload: SinchRecipientDeliveryReport
  try {
    // The body should already be validated for existence in the signature check
    payload = JSON.parse(event.body!) // Use non-null assertion after check
    handlerLogger.info({ payloadType: payload.type }, 'Parsed request body')

    // Basic payload type check
    if (payload.type !== 'recipient_delivery_report_sms') {
       handlerLogger.warn({ type: payload.type }, 'Received non-SMS recipient report type, ignoring.')
       // Still return 200 OK to acknowledge receipt and prevent Sinch retries
       return { statusCode: 200, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: 'Callback type ignored' }) }
    }

  } catch (error) {
    handlerLogger.error({ error, bodySnippet: event.body?.substring(0, 100) }, 'Failed to parse request body') // Avoid logging full body potentially containing PII
    return { statusCode: 400, body: JSON.stringify({ error: 'Bad Request: Malformed JSON' }) }
  }

  // 4. Process Callback Data (Using Service)
  try {
    // Call the service function (defined later)
    await recordSmsStatusUpdate({
      batchId: payload.batch_id,
      recipient: payload.recipient,
      statusCode: payload.code,
      status: payload.status,
      statusTimestamp: new Date(payload.at), // Convert ISO string to Date object
      clientReference: payload.client_reference,
      rawPayload: event.body!, // Store raw payload for debugging
    })

    handlerLogger.info({ batchId: payload.batch_id, recipient: payload.recipient, status: payload.status }, 'Successfully processed Sinch callback')

    // 5. Return Success Response to Sinch
    // IMPORTANT: Always return 2xx to Sinch upon successful receipt,
    // even if your internal processing encounters a recoverable issue.
    // This prevents Sinch from retrying unnecessarily.
    return {
      statusCode: 200,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: 'Callback processed successfully' }),
    }

  } catch (error) {
    handlerLogger.error({ error, batchId: payload.batch_id, recipient: payload.recipient }, 'Error processing Sinch callback in service')
    // Even on internal error, acknowledge receipt to Sinch
    // Log the error thoroughly for internal investigation.
    return {
      statusCode: 200, // Acknowledge receipt to prevent Sinch retries
      // Alternatively, consider 500 if the error is critical and *not* related
      // to the specific callback data itself (e.g., database down).
      // However, 200 is generally safer for webhook stability.
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: 'Callback received but internal processing failed' }),
    }
  }
}

// api/db/schema.prisma

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

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

// Model representing an SMS message sent via Sinch
model Message {
  id            String   @id @default(cuid()) // Unique message ID in your system
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt

  to            String   // Recipient phone number. IMPORTANT: Store consistently, E.164 format recommended to match Sinch callbacks.
  body          String?  // Optional: Store message body
  sentAt        DateTime @default(now()) // Timestamp when the send request was made
  sinchBatchId  String   // The Batch ID returned by Sinch upon sending
  clientReference String?  // Optional: The client reference you sent to Sinch

  // Tracking the latest known status directly on the message can be useful
  latestStatus        String?
  latestStatusCode    Int?
  latestStatusTimestamp DateTime?

  // Relation to status updates
  statusUpdates SmsStatusUpdate[]

  @@index([sinchBatchId])
  @@index([clientReference])
  @@index([to]) // Index recipient if you query by it often
}

// Model representing a delivery status update received from Sinch
model SmsStatusUpdate {
  id            String   @id @default(cuid())
  createdAt     DateTime @default(now())

  messageId     String   // Foreign key linking to the Message
  // The onDelete: Cascade means if a Message is deleted, all its related SmsStatusUpdates are also deleted.
  // Consider alternatives like SetNull (if messageId is optional) or handling deletions
  // at the application level if you need to preserve status history after deleting a message.
  message       Message  @relation(fields: [messageId], references: [id], onDelete: Cascade)

  sinchBatchId  String   // Batch ID from the callback (redundant but useful for querying)
  recipient     String   // Recipient phone number from the callback
  status        String   // e.g., ""Dispatched"", ""Delivered"", ""Failed""
  statusCode    Int      // e.g., 401, 0, 402 (Sinch status codes)
  statusTimestamp DateTime // The 'at' timestamp from the callback

  clientReference String? // Client reference from the callback

  rawPayload    String   // Store the full JSON payload for auditing/debugging

  @@index([messageId])
  @@index([sinchBatchId, recipient]) // Efficiently find updates for a specific message in a batch
  @@index([statusTimestamp])
}

yarn rw prisma migrate dev --name add_message_and_status_tables

yarn rw g service smsStatus --ts

// api/src/services/smsStatus/smsStatus.ts
import type { Prisma } from '@prisma/client'
import { db } from 'src/lib/db'
import { logger } from 'src/lib/logger'

interface RecordSmsStatusInput {
  batchId: string
  recipient: string
  statusCode: number
  status: string
  statusTimestamp: Date
  clientReference?: string
  rawPayload: string
}

export const recordSmsStatusUpdate = async ({
  batchId,
  recipient,
  statusCode,
  status,
  statusTimestamp,
  clientReference,
  rawPayload,
}: RecordSmsStatusInput): Promise<void&gt; =&gt; {
  const serviceLogger = logger.child({
    batchId,
    recipient,
    status,
    functionName: 'recordSmsStatusUpdate',
  })
  serviceLogger.info('Attempting to record SMS status update')

  // 1. Find the original message
  // We need a reliable way to link the callback to the message *you* sent.
  // Using batchId AND recipient is usually the most robust way.
  // CRITICAL: This assumes your application stores the recipient phone number
  // in the `Message.to` field in the *exact same format* (E.164 recommended)
  // as Sinch provides it in the callback's `recipient` field.
  // Mismatched formats (e.g., ""+1"" vs ""1"", presence of spaces/dashes) will prevent finding the message.
  // Alternatively, if you reliably send a unique `clientReference` per message, you could use that.
  const message = await db.message.findFirst({
    where: {
      sinchBatchId: batchId,
      to: recipient, // Ensure 'to' is stored consistently (e.g., E.164 format)
      // OR potentially use clientReference if it's guaranteed unique per message
      // clientReference: clientReference
    },
    select: { id: true, latestStatusTimestamp: true }, // Select only necessary fields
  })

  if (!message) {
    // Could not find the original message this status update belongs to.
    // This might happen if:
    // - The message wasn't stored correctly when sent.
    // - There's a significant delay and the message was archived/deleted.
    // - The recipient format stored in `Message.to` doesn't match the callback `recipient`.
    // Decide how to handle this: Log an error? Create an orphaned status record?
    serviceLogger.error(
      { clientReference }, // Log client reference if available, might help debugging
      'Could not find original message for this status update. Check recipient format consistency (E.164 recommended) and if the message was stored.'
    )
    // Option: Throw an error (will be caught by handler, logged, but Sinch gets 200 OK)
    throw new Error(
      `Original message not found for batchId: ${batchId}, recipient: ${recipient}. Verify recipient format.`
    )
    // Option: Log and exit gracefully (Sinch gets 200 OK)
    // return;
  }

  serviceLogger.info({ messageId: message.id }, 'Found corresponding message')

  // 2. Create the SmsStatusUpdate record
  try {
    const createData: Prisma.SmsStatusUpdateCreateInput = {
      message: { connect: { id: message.id } },
      sinchBatchId: batchId,
      recipient: recipient,
      status: status,
      statusCode: statusCode,
      statusTimestamp: statusTimestamp,
      clientReference: clientReference,
      rawPayload: rawPayload,
    }

    // Idempotency Check (Optional but Recommended):
    // Avoid creating duplicate status updates if Sinch retries.
    // Check if an update with the same core details already exists.
    // Note: Checking timestamp equality can be fragile due to potential clock skew or minor variations.
    // Relying on messageId + recipient + status + statusCode is generally more robust for DLRs.
    const existingUpdate = await db.smsStatusUpdate.findFirst({
      where: {
        messageId: message.id,
        recipient: recipient, // Match the specific recipient
        status: status,       // Match the specific status event
        statusCode: statusCode, // Match the specific status code
        // statusTimestamp: statusTimestamp // Avoid matching exact timestamp unless necessary and reliable
      },
      select: { id: true }
    });

    if (existingUpdate) {
       serviceLogger.warn({ existingUpdateId: existingUpdate.id }, 'Duplicate status update received (same message, recipient, status, code). Ignoring.');
       return; // Successfully handled the duplicate, exit.
    }

    // Create the actual record
    const newStatusUpdate = await db.smsStatusUpdate.create({ data: createData })
    serviceLogger.info(
      { statusUpdateId: newStatusUpdate.id },
      'Created new SmsStatusUpdate record'
    )

    // 3. (Optional) Update the latest status on the parent Message record
    // Only update if this status is newer than the existing latest status
    if (
      !message.latestStatusTimestamp ||
      statusTimestamp &gt; message.latestStatusTimestamp
    ) {
      await db.message.update({
        where: { id: message.id },
        data: {
          latestStatus: status,
          latestStatusCode: statusCode,
          latestStatusTimestamp: statusTimestamp,
        },
      })
      serviceLogger.info(
        { messageId: message.id },
        'Updated latest status on Message record'
      )
    } else {
      serviceLogger.info(
         { messageId: message.id, newStatusTimestamp: statusTimestamp, latestStatusTimestamp: message.latestStatusTimestamp },
         'Received older or same-timestamp status update, not updating latest status on Message record'
       )
    }

  } catch (error) {
    serviceLogger.error({ error }, 'Database error while recording status update')
    // Re-throw the error to be caught by the handler function
    throw error
  }
}

// You might add other service functions here later, e.g.,
// - getMessageStatusHistory(messageId: string)
// - findMessagesByStatus(status: string)

// api/src/lib/sinchSecurity.ts
import crypto from 'crypto'
import { logger } from 'src/lib/logger'
import type { APIGatewayProxyEventHeaders } from 'aws-lambda'

/**
 * Finds a header value case-insensitively.
 * @param headers - The headers object.
 * @param headerName - The name of the header to find (case-insensitive).
 * @returns The header value or undefined if not found.
 */
const findHeader = (headers: APIGatewayProxyEventHeaders, headerName: string): string | undefined => {
  const lowerCaseHeaderName = headerName.toLowerCase();
  const headerKey = Object.keys(headers).find(key => key.toLowerCase() === lowerCaseHeaderName);
  return headerKey ? headers[headerKey] : undefined;
}

/**
 * Validates the Sinch webhook signature using HMAC-SHA256.
 *
 * @param headers - The request headers object (from APIGatewayEvent). Case-insensitive lookup is performed.
 * @param rawBody - The raw, unparsed request body string. MUST be the exact bytes received.
 * @param secret - Your Sinch Webhook Secret from environment variables.
 * @returns `true` if the signature is valid, `false` otherwise.
 * @throws Error if required headers are missing or the secret is invalid.
 */
export const validateSinchSignature = (
  headers: APIGatewayProxyEventHeaders,
  rawBody: string,
  secret: string | undefined
): boolean => {
  const securityLogger = logger.child({ functionName: 'validateSinchSignature' })

  if (!secret) {
    securityLogger.error('Webhook secret is not provided or empty.')
    // Throwing an error here helps distinguish configuration issues from invalid signatures in the handler
    throw new Error('Webhook secret is missing or invalid.');
  }

  // 1. Extract Headers provided by Sinch
  const sinchTimestamp = findHeader(headers, 'x-sinch-timestamp')
  const sinchSignatureHeader = findHeader(headers, 'x-sinch-signature')

  if (!sinchTimestamp) {
    securityLogger.warn('Missing x-sinch-timestamp header')
    return false // Or throw new Error('Missing x-sinch-timestamp header');
  }

  if (!sinchSignatureHeader) {
    securityLogger.warn('Missing x-sinch-signature header')
    return false // Or throw new Error('Missing x-sinch-signature header');
  }

  // 2. Prepare the Signed Content String
  // Format: HTTP_Method + '\n' + Content-MD5 + '\n' + Content-Type + '\n' + Timestamp_Header + '\n' + Request_URI
  // For Sinch callbacks: Method=POST, MD5=hash of rawBody, ContentType=application/json, Timestamp=x-sinch-timestamp, URI=/api/sinchCallbacks (or the path part of your endpoint)
  // IMPORTANT: Sinch documentation might specify slightly different formats. Verify against current Sinch docs.
  // Assuming the standard format based on common webhook patterns and Sinch examples:
  // StringToSign = <Request Body&gt; + <Timestamp Header Value&gt;

  // Sinch typically signs the raw request body concatenated with the timestamp header value.
  const stringToSign = rawBody + sinchTimestamp;
  securityLogger.debug({ stringToSignLength: stringToSign.length }, 'Constructed string-to-sign')


  // 3. Decode the Secret (Sinch secrets are typically Base64 encoded)
  let decodedSecret: Buffer;
  try {
    decodedSecret = Buffer.from(secret, 'base64');
  } catch (e) {
    securityLogger.error({ error: e }, 'Failed to decode webhook secret from Base64. Ensure it is correctly encoded.');
    throw new Error('Invalid webhook secret encoding.');
  }


  // 4. Calculate the Expected Signature
  const hmac = crypto.createHmac('sha256', decodedSecret);
  const expectedSignature = hmac.update(stringToSign).digest('base64');
  securityLogger.debug('Calculated expected signature');


  // 5. Compare Signatures
  // Sinch signature header format is often `sv1=<signature&gt;` or just the signature.
  // Adjust parsing based on the actual header format received. Assuming it's just the Base64 signature.
  const providedSignature = sinchSignatureHeader; // Adjust if prefix like 'sv1=' is present

  // Use crypto.timingSafeEqual for security against timing attacks
  try {
    const providedSigBuffer = Buffer.from(providedSignature, 'base64');
    const expectedSigBuffer = Buffer.from(expectedSignature, 'base64');

    // Ensure buffers have the same length before comparing to prevent timingSafeEqual errors
    if (providedSigBuffer.length !== expectedSigBuffer.length) {
        securityLogger.warn('Signature length mismatch');
        return false;
    }

    const isValid = crypto.timingSafeEqual(providedSigBuffer, expectedSigBuffer);
    securityLogger.info(`Signature validation result: ${isValid}`);
    return isValid;

  } catch (error) {
    // Handle potential errors during buffer conversion (e.g., invalid Base64 in provided signature)
    securityLogger.error({ error }, 'Error during signature comparison (possibly invalid Base64 format in provided signature)');
    return false;
  }
}