RedwoodJS Bulk SMS Messaging with Vonage: Build Scalable Broadcasting System

# Replace 'redwood-bulk-sms' with your desired project name
yarn create redwood-app redwood-bulk-sms --typescript
cd redwood-bulk-sms

yarn workspace api add @vonage/server-sdk

yarn workspace api list --pattern @vonage/server-sdk

# .env
# From Vonage Dashboard -> API Settings
VONAGE_API_KEY=YOUR_API_KEY_HERE
VONAGE_API_SECRET=YOUR_API_SECRET_HERE

# From Vonage Dashboard -> Applications
VONAGE_APPLICATION_ID=YOUR_APPLICATION_ID_HERE

# Path to downloaded private key file
VONAGE_PRIVATE_KEY_PATH=./private.key

# Your Vonage number in E.164 format (e.g., +14155550100)
VONAGE_FROM_NUMBER=YOUR_VONAGE_NUMBER_HERE

# Secrets
.env
private.key
*.key

// api/db/schema.prisma

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

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

// Add models below

# .env
DATABASE_URL="file:./dev.db"  # SQLite for development
# For PostgreSQL: DATABASE_URL="postgresql://user:password@host:port/database?schema=public"

yarn rw g service sms

// api/src/services/sms/sms.ts
import { Vonage } from '@vonage/server-sdk'
import { Messages } from '@vonage/messages' // Import the Messages class type if needed
import type { SendBulkSmsInput } from 'types/graphql' // We'll create this type later

import { logger } from 'src/lib/logger'
import { db } from 'src/lib/db' // Import the db client

// --- Vonage Client Initialization ---
// Retrieve credentials securely from environment variables
const vonageApiKey = process.env.VONAGE_API_KEY
const vonageApiSecret = process.env.VONAGE_API_SECRET
const vonageAppId = process.env.VONAGE_APPLICATION_ID
const vonagePrivateKeyPath = process.env.VONAGE_PRIVATE_KEY_PATH
const vonageFromNumber = process.env.VONAGE_FROM_NUMBER

// Basic validation to ensure environment variables are set
if (
  !vonageApiKey ||
  !vonageApiSecret ||
  !vonageAppId ||
  !vonagePrivateKeyPath ||
  !vonageFromNumber
) {
  throw new Error(
    'Missing Vonage credentials in environment variables. Check .env file.'
  )
}

// Initialize Vonage client.
// While Messages API primarily uses Application ID + Private Key for authentication,
// the SDK might use API Key/Secret for other functionalities or fallbacks.
const vonage = new Vonage({
  apiKey: vonageApiKey,
  apiSecret: vonageApiSecret,
  applicationId: vonageAppId,
  privateKey: vonagePrivateKeyPath,
})

// Create a specific client instance for the Messages API
const vonageMessages = new Messages(vonage.options) // Use the same options

// --- Helper Function for Single SMS ---
// Encapsulates sending a single message and basic error handling
async function sendSingleSms(
  to: string,
  text: string
): Promise<{ success: boolean; messageId?: string; error?: string }> {
  const commonLogData = { recipient: to, messageText: text }
  try {
    // Input validation (basic example)
    if (!to || !text) {
      return { success: false, error: 'Recipient number and text are required.' }
    }

    // Validate E.164 format (basic check)
    const e164Regex = /^\+[1-9]\d{1,14}$/
    if (!e164Regex.test(to)) {
      logger.error(`Invalid phone number format: ${to}`)
      return { success: false, error: `Invalid phone number format: ${to}. Use E.164 (e.g., +14155550100)` }
    }

    // Validate message length (160 chars for GSM-7, 70 for Unicode)
    if (text.length > 1600) {
      return { success: false, error: 'Message exceeds maximum length of 1600 characters.' }
    }

    logger.debug(`Attempting to send SMS to: ${to}`)

    const resp = await vonageMessages.send({
      message_type: 'text',
      channel: 'sms',
      to: to,
      from: vonageFromNumber, // Use the configured Vonage number
      text: text,
    })

    logger.info(`SMS sent to ${to}, message_uuid: ${resp.message_uuid}`)
    await logSmsAttempt({
      ...commonLogData,
      status: 'SUCCESS',
      vonageMessageId: resp.message_uuid,
    })
    return { success: true, messageId: resp.message_uuid }
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown Vonage API error'
    logger.error(`Failed to send SMS to ${to}: ${errorMessage}`, error)
    // More specific error handling based on Vonage error codes could be added here
    await logSmsAttempt({
      ...commonLogData,
      status: 'FAILED',
      errorMessage: errorMessage,
    })
    return { success: false, error: errorMessage }
  }
}

// --- Database Logging Helper ---
async function logSmsAttempt(data: {
  recipient: string
  messageText: string
  status: 'SUCCESS' | 'FAILED'
  vonageMessageId?: string
  errorMessage?: string
}) {
  try {
    await db.smsLog.create({ data })
  } catch (dbError) {
    const errorMessage = dbError instanceof Error ? dbError.message : 'Unknown database error'
    logger.error(
      `Failed to log SMS attempt for ${data.recipient} to database: ${errorMessage}`,
      dbError
    )
    // DB logging failure is non-critical for message delivery
    // Monitor these errors via centralized logging
  }
}

// --- Bulk SMS Sending Logic ---
export const sendBulkSms = async ({ input }: { input: SendBulkSmsInput }) => {
  const { recipients, message } = input
  const results: Array<{
    to: string
    success: boolean
    messageId?: string
    error?: string
  }> = []

  logger.info(
    `Starting bulk SMS job for ${recipients.length} recipients.`
  )

  // IMPORTANT: Rate Limiting
  // Vonage rate limits vary by number type (1 SMS/sec for long codes, higher for toll-free)
  //
  // For production, use one of these approaches:
  // 1. Throttling: Use p-throttle library to limit concurrent requests
  // 2. Queue System: BullMQ, AWS SQS, or similar (recommended for reliability)
  //
  // This implementation uses Promise.allSettled without throttling
  // Add rate limiting before production deployment

  const sendPromises = recipients.map((recipient) =>
    sendSingleSms(recipient, message) // logSmsAttempt is called inside sendSingleSms
      .then((result) => ({ to: recipient, ...result })) // Add recipient number to result
      .catch((err) => { // Catch unexpected errors from sendSingleSms itself (e.g., validation error)
        const errorMessage = err instanceof Error ? err.message : 'Unknown error'
        return {
          to: recipient,
          success: false,
          error: `Unexpected error during sendSingleSms execution: ${errorMessage}`,
        }
      })
  )

  const settledResults = await Promise.allSettled(sendPromises)

  settledResults.forEach((result, index) => {
    const recipient = recipients[index] // Maintain order
    if (result.status === 'fulfilled') {
      // The result.value contains { to, success, messageId?, error? } from sendSingleSms
      results.push(result.value)
      // Logging is handled within sendSingleSms now
    } else {
      // This catches errors *before* or *outside* sendSingleSms's try/catch,
      // or if the promise wrapping sendSingleSms itself was rejected unexpectedly.
      const reasonMessage = result.reason instanceof Error ? result.reason.message : String(result.reason)
      const errorMsg = `Promise rejected for recipient ${recipient}: ${reasonMessage}`
      logger.error(errorMsg)
      results.push({
        to: recipient,
        success: false,
        error: errorMsg,
      })
      // Log this critical/unexpected failure if needed, although sendSingleSms handles most API/logic errors.
      logSmsAttempt({ recipient, messageText: message, status: 'FAILED', errorMessage: errorMsg });
    }
  })

  const successfulSends = results.filter((r) => r.success).length
  const failedSends = results.length - successfulSends

  logger.info(
    `Bulk SMS job completed. Success: ${successfulSends}, Failed: ${failedSends}`
  )

  // Return a summary and detailed results
  return {
    totalRecipients: recipients.length,
    successfulSends,
    failedSends,
    results, // Array of individual results
  }
}

// Add other SMS-related service functions if needed (e.g., getMessageStatus)

yarn rw g sdl sms --no-crud

# api/src/graphql/sms.sdl.ts
export const schema = gql`
  # Input type for the bulk SMS mutation
  input SendBulkSmsInput {
    recipients: [String!]! # Array of phone numbers, expected in E.164 format
    message: String!       # The text message content
  }

  # Represents the result of a single SMS send attempt within the bulk job
  type SmsSendResult {
    to: String!
    success: Boolean!
    messageId: String # Vonage message UUID if successful
    error: String     # Error message if failed
  }

  # Represents the overall summary of the bulk SMS job
  type BulkSmsSummary {
    totalRecipients: Int!
    successfulSends: Int!
    failedSends: Int!
    results: [SmsSendResult!]! # Detailed results for each recipient
  }

  type Mutation {
    # Mutation to send bulk SMS messages
    # Protected by @requireAuth to ensure only logged-in users can trigger it
    sendBulkSms(input: SendBulkSmsInput!): BulkSmsSummary! @requireAuth
  }
`

mutation SendBulk {
  sendBulkSms(input: {
    recipients: ["+14155550101", "+14155550102"] # Use valid E.164 test numbers
    message: "Hello from RedwoodJS Bulk Sender!"
  }) {
    totalRecipients
    successfulSends
    failedSends
    results {
      to
      success
      messageId
      error
    }
  }
}

{
  "data": {
    "sendBulkSms": {
      "totalRecipients": 2,
      "successfulSends": 2,
      "failedSends": 0,
      "results": [
        {
          "to": "+14155550101",
          "success": true,
          "messageId": "uuid-123",
          "error": null
        },
        {
          "to": "+14155550102",
          "success": true,
          "messageId": "uuid-456",
          "error": null
        }
      ]
    }
  }
}

// api/src/lib/logger.ts
export const logger = createLogger({
  options: {
    level: process.env.LOG_LEVEL || 'info', // 'debug' for development
    redact: ['recipient', 'messageText'], // Redact PII in production
  },
})

// Helper function to determine if error is retryable
function isRetryable(error: any): boolean {
  // Check for temporary errors (rate limits, network issues, server errors)
  if (error.status) {
    return error.status === 429 || (error.status >= 500 && error.status < 600)
  }
  // Check for network errors
  if (error.code) {
    return ['ETIMEDOUT'_ 'ECONNRESET'_ 'ENOTFOUND'].includes(error.code)
  }
  return false
}

// Enhanced sendSingleSms with retry logic
async function sendSingleSmsWithRetry(
  to: string_
  text: string_
  maxAttempts: number = 3
): Promise<{ success: boolean; messageId?: string; error?: string }> {
  let lastError: any

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const result = await sendSingleSms(to_ text)
      if (result.success) {
        return result
      }
      lastError = new Error(result.error)
    } catch (error) {
      lastError = error

      if (!isRetryable(error) || attempt === maxAttempts) {
        break
      }

      // Exponential backoff: 1s_ 2s_ 4s
      const delayMs = 1000 * Math.pow(2_ attempt - 1)
      logger.warn(`Attempt ${attempt} failed for ${to}. Retrying in ${delayMs}ms...`)
      await new Promise(resolve => setTimeout(resolve, delayMs))
    }
  }

  const errorMessage = lastError instanceof Error ? lastError.message : 'Unknown error'
  logger.error(`All ${maxAttempts} attempts failed for ${to}: ${errorMessage}`)
  return { success: false, error: errorMessage }
}

yarn workspace api add bullmq ioredis

// api/src/lib/queue.ts
import { Queue, Worker } from 'bullmq'
import Redis from 'ioredis'

const connection = new Redis(process.env.REDIS_URL)

export const smsQueue = new Queue('sms', { connection })

// Worker to process SMS jobs
const worker = new Worker('sms', async (job) => {
  const { to, message } = job.data
  return await sendSingleSms(to, message)
}, {
  connection,
  concurrency: 5, // Process 5 messages concurrently
  limiter: {
    max: 1, // 1 message per second (adjust based on your Vonage limits)
    duration: 1000,
  },
})

// api/db/schema.prisma

// ... (datasource and generator)

model SmsLog {
  id              String   @id @default(cuid())
  recipient       String   // The phone number the message was sent to (E.164)
  messageText     String   // The content of the message
  status          String   // e.g., 'SUCCESS', 'FAILED'
  vonageMessageId String?  @unique // The message_uuid from Vonage on success
  errorMessage    String?  // Error details on failure
  sentAt          DateTime @default(now()) // When the send attempt was initiated
  updatedAt       DateTime @updatedAt

  @@index([recipient])
  @@index([status])
  @@index([sentAt])
}

yarn rw prisma migrate dev --name add_sms_log

// Get recent failures
const recentFailures = await db.smsLog.findMany({
  where: {
    status: 'FAILED',
    sentAt: { gte: new Date(Date.now() - 24 * 60 * 60 * 1000) } // Last 24 hours
  },
  orderBy: { sentAt: 'desc' },
  take: 100
})

// Count messages by status
const stats = await db.smsLog.groupBy({
  by: ['status'],
  _count: true
})

// api/src/services/sms/sms.ts
import { requireAuth } from 'src/lib/auth'

export const sendBulkSms = async ({ input }: { input: SendBulkSmsInput }) => {
  // Restrict to admin users only
  requireAuth({ roles: ['admin'] })

  // ... rest of implementation
}

// Add to sendBulkSms function
export const sendBulkSms = async ({ input }: { input: SendBulkSmsInput }) => {
  const { recipients, message } = input

  // Validate recipient count
  if (recipients.length === 0) {
    throw new Error('Recipient list cannot be empty')
  }
  if (recipients.length > 1000) {
    throw new Error('Maximum 1000 recipients per batch')
  }

  // Validate message content
  if (!message || message.trim().length === 0) {
    throw new Error('Message content is required')
  }
  if (message.length > 1600) {
    throw new Error('Message exceeds maximum length of 1600 characters')
  }

  // Validate phone numbers
  const e164Regex = /^\+[1-9]\d{1,14}$/
  const invalidNumbers = recipients.filter(num => !e164Regex.test(num))
  if (invalidNumbers.length > 0) {
    throw new Error(`Invalid phone numbers: ${invalidNumbers.join(', ')}`)
  }

  // ... rest of implementation
}

yarn workspace api add graphql-rate-limit-directive

// api/src/directives/rateLimit/rateLimit.ts
import { createRateLimitDirective } from 'graphql-rate-limit-directive'

export const rateLimitDirective = createRateLimitDirective({
  identifyContext: (ctx) => ctx.currentUser?.id || ctx.event.headers['x-forwarded-for']
})

# api/src/graphql/sms.sdl.ts
type Mutation {
  sendBulkSms(input: SendBulkSmsInput!): BulkSmsSummary!
    @requireAuth
    @rateLimit(limit: 10, duration: 3600) # 10 requests per hour
}

# .gitignore
.env
.env.*
private.key
*.key
*.pem

// Add consent tracking to schema
model Consent {
  id          String   @id @default(cuid())
  phoneNumber String   @unique
  opted_in     Boolean  @default(false)
  optInDate   DateTime?
  optOutDate  DateTime?
  source      String   // How consent was obtained
  ipAddress   String?  // IP address when consent was given
}

// api/src/lib/phoneUtils.ts
export function normalizePhoneNumber(phone: string, defaultRegion: string = 'US'): string {
  // Remove all non-digit characters except leading +
  let cleaned = phone.replace(/[^\d+]/g, '')

  // Add + if missing
  if (!cleaned.startsWith('+')) {
    cleaned = '+' + cleaned
  }

  return cleaned
}

export function validateE164(phone: string): boolean {
  const e164Regex = /^\+[1-9]\d{1,14}$/
  return e164Regex.test(phone)
}

// api/src/lib/smsUtils.ts
export function calculateSegments(message: string): {
  segments: number
  encoding: 'GSM-7' | 'UCS-2'
  charsPerSegment: number
} {
  const gsmRegex = /^[@£$¥èéùìòÇØøÅåΔ_ΦΓΛΩΠΨΣΘΞÆæßÉ !"#¤%&'()*+,\-.\/0-9:;<=>?¡A-ZÄÖÑܧ¿a-zäöñüà\r\n]*$/

  const isGsm = gsmRegex.test(message)
  const encoding = isGsm ? 'GSM-7' : 'UCS-2'
  const charsPerSegment = isGsm ? (message.length > 160 ? 153 : 160) : (message.length > 70 ? 67 : 70)
  const segments = Math.ceil(message.length / charsPerSegment)

  return { segments, encoding, charsPerSegment }
}

// api/src/services/sms/sms.ts
async function shouldSendSms(phoneNumber: string): Promise<boolean&gt; {
  const consent = await db.consent.findUnique({
    where: { phoneNumber }
  })

  return consent?.opted_in === true && !consent.optOutDate
}

// Update sendBulkSms to check consent
export const sendBulkSms = async ({ input }: { input: SendBulkSmsInput }) =&gt; {
  const { recipients, message } = input

  // Filter out opted-out recipients
  const filteredRecipients = []
  for (const recipient of recipients) {
    if (await shouldSendSms(recipient)) {
      filteredRecipients.push(recipient)
    } else {
      logger.info(`Skipping opted-out recipient: ${recipient}`)
    }
  }

  // ... continue with filteredRecipients
}

// api/src/lib/timezoneUtils.ts
import { DateTime } from 'luxon'

export function isBusinessHours(timezone: string): boolean {
  const now = DateTime.now().setZone(timezone)
  const hour = now.hour

  // 9 AM to 8 PM local time
  return hour >= 9 && hour < 20
}

export function calculateDelay(timezone: string_ targetHour: number = 9): number {
  const now = DateTime.now().setZone(timezone)
  const target = now.set({ hour: targetHour_ minute: 0_ second: 0 })

  if (now > target) {
    // Schedule for tomorrow
    return target.plus({ days: 1 }).diff(now).milliseconds
  }

  return target.diff(now).milliseconds
}

// api/src/services/sms/sms.ts
import { smsQueue } from 'src/lib/queue'

export const sendBulkSms = async ({ input }: { input: SendBulkSmsInput }) => {
  const { recipients, message } = input

  // Enqueue jobs instead of sending directly
  const jobs = await Promise.all(
    recipients.map(recipient =>
      smsQueue.add('send-sms', {
        to: recipient,
        message,
        timestamp: Date.now()
      })
    )
  )

  return {
    totalRecipients: recipients.length,
    jobsCreated: jobs.length,
    message: 'SMS jobs queued successfully'
  }
}

async function logBulkSmsAttempts(attempts: Array<{
  recipient: string
  messageText: string
  status: 'SUCCESS' | 'FAILED'
  vonageMessageId?: string
  errorMessage?: string
}>) {
  try {
    await db.smsLog.createMany({
      data: attempts,
      skipDuplicates: true
    })
  } catch (error) {
    logger.error('Failed to batch log SMS attempts', error)
  }
}

yarn workspace api add p-limit

import pLimit from 'p-limit'

export const sendBulkSms = async ({ input }: { input: SendBulkSmsInput }) => {
  const { recipients, message } = input
  const limit = pLimit(5) // Max 5 concurrent requests

  const sendPromises = recipients.map(recipient =>
    limit(() => sendSingleSms(recipient, message))
  )

  const results = await Promise.allSettled(sendPromises)
  // ... process results
}

// api/src/lib/metrics.ts
import { performance } from 'perf_hooks'

export function trackDuration(label: string_ fn: () =&gt; Promise<any&gt;) {
  const start = performance.now()
  return fn().finally(() =&gt; {
    const duration = performance.now() - start
    logger.info(`${label} took ${duration.toFixed(2)}ms`)
  })
}

yarn workspace api add pino-pretty @logtail/pino

// api/src/lib/logger.ts
import { Logtail } from '@logtail/pino'
import { createLogger } from '@redwoodjs/api/logger'

const logtail = new Logtail(process.env.LOGTAIL_TOKEN)

export const logger = createLogger({
  options: {
    level: process.env.LOG_LEVEL || 'info',
    redact: ['recipient', 'messageText', 'vonageApiKey', 'vonageApiSecret']
  },
  destination: logtail
})

yarn workspace api add @sentry/node

// api/src/lib/sentry.ts
import * as Sentry from '@sentry/node'

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1
})

export { Sentry }

yarn workspace api add prom-client

// api/src/lib/metrics.ts
import { Counter, Histogram, Registry } from 'prom-client'

const register = new Registry()

export const smsCounter = new Counter({
  name: 'sms_sent_total',
  help: 'Total number of SMS messages sent',
  labelNames: ['status'],
  registers: [register]
})

export const smsDuration = new Histogram({
  name: 'sms_send_duration_seconds',
  help: 'SMS send duration in seconds',
  registers: [register]
})

// Expose metrics endpoint
export function getMetrics() {
  return register.metrics()
}

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

export const handler = async (event: APIGatewayEvent, context: Context) => {
  const checks = {
    database: false,
    timestamp: new Date().toISOString()
  }

  try {
    await db.$queryRaw`SELECT 1`
    checks.database = true
  } catch (error) {
    logger.error('Database health check failed', error)
  }

  const isHealthy = checks.database

  return {
    statusCode: isHealthy ? 200 : 503,
    body: JSON.stringify(checks)
  }
}

// api/src/lib/logger.ts
export const logger = createLogger({
  options: {
    level: 'debug', // Verbose output
    prettyPrint: true
  }
})

# Required environment variables for production
VONAGE_API_KEY=your_api_key
VONAGE_API_SECRET=your_api_secret
VONAGE_APPLICATION_ID=your_app_id
VONAGE_PRIVATE_KEY_PATH=/var/secrets/private.key
VONAGE_FROM_NUMBER=+14155550100
DATABASE_URL=postgresql://user:pass@host:5432/db
REDIS_URL=redis://host:6379
LOG_LEVEL=info
SENTRY_DSN=your_sentry_dsn
NODE_ENV=production

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'yarn'

      - name: Install Dependencies
        run: yarn install --frozen-lockfile

      - name: Lint Code
        run: yarn rw lint

      - name: Type Check
        run: yarn rw type-check

      - name: Run Tests
        run: yarn rw test api --no-watch
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/test

      - name: Build Application
        run: yarn rw build

      - name: Deploy to Production
        run: yarn rw deploy vercel --prod
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

# In CI/CD pipeline
yarn rw prisma migrate deploy

# Tag releases
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3

# Rollback if needed
git checkout v1.2.2
yarn rw deploy vercel --prod

// api/src/services/sms/sms.test.ts
import { sendBulkSms } from './sms'
import { db } from 'src/lib/db'

// Mock dependencies
const mockSend = jest.fn()
jest.mock('@vonage/server-sdk', () => {
  const MockMessages = jest.fn().mockImplementation(() => ({
    send: mockSend
  }))
  const MockVonage = jest.fn().mockImplementation(() => ({
    options: {},
  }))
  return {
    Vonage: MockVonage,
    Messages: MockMessages,
    __esModule: true,
  }
})

jest.mock('src/lib/db', () => ({
  db: {
    smsLog: {
      create: jest.fn().mockResolvedValue({}),
    },
  },
}))

jest.mock('src/lib/logger')

const mockSmsLogCreate = db.smsLog.create as jest.Mock

describe('sms service', () => {
  beforeEach(() => {
    jest.clearAllMocks()
    mockSend.mockClear()
    mockSmsLogCreate.mockClear()
  })

  it('sendBulkSms handles success and failure correctly', async () => {
    // Arrange
    mockSend
      .mockResolvedValueOnce({ message_uuid: 'uuid-1' })
      .mockRejectedValueOnce(new Error('Vonage API Error'))

    const input = { recipients: ['+11112223333', '+14445556666'], message: 'Test' }

    // Act
    const result = await sendBulkSms({ input })

    // Assert
    expect(result.totalRecipients).toBe(2)
    expect(result.successfulSends).toBe(1)
    expect(result.failedSends).toBe(1)
    expect(result.results).toHaveLength(2)
    expect(result.results[0]).toMatchObject({
      to: '+11112223333',
      success: true,
      messageId: 'uuid-1'
    })
    expect(result.results[1]).toMatchObject({
      to: '+14445556666',
      success: false,
      error: expect.stringContaining('Vonage API Error')
    })

    // Verify mock calls
    expect(mockSend).toHaveBeenCalledTimes(2)
    expect(mockSmsLogCreate).toHaveBeenCalledTimes(2)
  })

  it('validates phone number format', async () => {
    const input = { recipients: ['1234567890'], message: 'Test' }
    const result = await sendBulkSms({ input })

    expect(result.failedSends).toBe(1)
    expect(result.results[0].error).toContain('Invalid phone number format')
  })

  it('handles empty recipient list', async () => {
    const input = { recipients: [], message: 'Test' }

    await expect(sendBulkSms({ input })).rejects.toThrow('Recipient list cannot be empty')
  })
})

// api/src/services/sms/sms.scenarios.ts
export const standard = defineScenario({
  smsLog: {
    one: {
      data: {
        recipient: '+14155550101',
        messageText: 'Test message',
        status: 'SUCCESS',
        vonageMessageId: 'test-uuid-1'
      }
    }
  }
})

// web/src/pages/BulkSmsPage/BulkSmsPage.test.tsx
import { render, screen, waitFor } from '@redwoodjs/testing/web'
import BulkSmsPage from './BulkSmsPage'

describe('BulkSmsPage', () => {
  it('renders successfully', () => {
    render(<BulkSmsPage /&gt;)
    expect(screen.getByText('Send Bulk SMS')).toBeInTheDocument()
  })

  it('sends bulk SMS successfully', async () =&gt; {
    const { getByLabelText, getByText } = render(<BulkSmsPage /&gt;)

    // Fill form
    const recipientsInput = getByLabelText('Recipients')
    const messageInput = getByLabelText('Message')

    fireEvent.change(recipientsInput, {
      target: { value: '+14155550101\n+14155550102' }
    })
    fireEvent.change(messageInput, {
      target: { value: 'Test message' }
    })

    // Submit
    fireEvent.click(getByText('Send'))

    // Verify
    await waitFor(() =&gt; {
      expect(screen.getByText('Messages sent successfully')).toBeInTheDocument()
    })
  })
})