Build SMS Marketing Campaigns with RedwoodJS and Infobip API

yarn create redwood-app ./redwood-infobip-sms --typescript

cd redwood-infobip-sms

yarn rw prisma migrate dev
# You will be prompted to name the migration, e.g., ""initial setup""

yarn workspace api add axios

yarn rw g service campaign --crud

// api/src/services/campaigns/campaigns.ts
import axios from 'axios'
import type { Prisma } from '@prisma/client' // Will be used later
import { db } from 'src/lib/db' // Will be used later
import { logger } from 'src/lib/logger'

interface SendSmsPayload {
  to: string[] // Array of recipient phone numbers in E.164 format
  text: string
  from?: string // Optional sender ID, defaults to env var
}

// Note: This function will be renamed to `sendSms` to match the GraphQL mutation later
export const sendSmsViaInfobip = async ({ to, text, from }: SendSmsPayload) => {
  const apiKey = process.env.INFOBIP_API_KEY
  const baseUrl = process.env.INFOBIP_BASE_URL
  // Use the provided 'from', fallback to env var, then a default
  const senderId = from || process.env.INFOBIP_SENDER_ID || 'InfoSMS'

  if (!apiKey || !baseUrl) {
    logger.error('Infobip API Key or Base URL missing in environment variables.')
    throw new Error('Infobip configuration is incomplete.')
  }

  // Basic validation
  if (!to || to.length === 0 || !text) {
    logger.error('Missing required parameters: to (list of numbers) and text.')
    throw new Error('Recipient numbers and message text are required.')
  }
  // Add more validation here (e.g., phone number format, text length) if needed

  const infobipUrl = `${baseUrl}/sms/3/messages` // Updated to current SMS API v3 endpoint

  // Structure the payload according to Infobip API V3 documentation
  // Ref: https://www.infobip.com/docs/sms/sms-over-api
  const payload = {
    messages: to.map((recipient) => ({
      destinations: [{ to: recipient }],
      from: senderId,
      text: text,
    })),
  }

  try {
    logger.info(`Sending SMS via Infobip to ${to.length} recipients.`)
    logger.debug({ payload: { messages: payload.messages.map(m => ({...m, text: '[REDACTED]'})) } }, 'Infobip Request Payload (Text Redacted):') // Avoid logging full text

    const response = await axios.post(infobipUrl, payload, {
      headers: {
        Authorization: `App ${apiKey}`, // Use 'App' prefix for API Key method
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
      timeout: 10000, // 10 second timeout
    })

    logger.info(
      { bulkId: response.data.bulkId, status: response.status },
      'Infobip SMS submitted successfully.'
    )

    // Return relevant info, like the bulk ID for tracking
    return {
      success: true,
      bulkId: response.data.bulkId,
      messages: response.data.messages, // Contains status for each message
    }
  } catch (error) {
    logger.error({ error }, 'Failed to send SMS via Infobip.')

    if (axios.isAxiosError(error)) {
      logger.error(
        {
          status: error.response?.status,
          data: error.response?.data,
          // headers: error.response?.headers, // Avoid logging potentially sensitive headers
        },
        'Infobip API Error Details'
      )
      // Provide a more user-friendly error message if possible
      const errorMessage = error.response?.data?.requestError?.serviceException?.text || error.message;
      throw new Error(`Infobip API request failed: ${errorMessage}`)
    } else {
      throw new Error(`An unexpected error occurred: ${error.message}`)
    }
  }
}

// --- Placeholder for Campaign CRUD functions (to be added in Section 6) ---
// export const campaigns = () => { ... }
// export const campaign = ({ id }: Prisma.CampaignWhereUniqueInput) => { ... }
// export const createCampaign = ({ input }: { input: Prisma.CampaignCreateInput }) => { ... }
// export const updateCampaign = ({ id, input }: { id: number; input: Prisma.CampaignUpdateInput }) => { ... }
// export const deleteCampaign = ({ id }: Prisma.CampaignWhereUniqueInput) => { ... }
// --- Placeholder for triggerCampaignSend function (to be added in Section 6) ---
// export const triggerCampaignSend = async ({ input }: { input: TriggerCampaignSendInput }) => { ... }

# api/src/graphql/campaigns.sdl.ts
export const schema = gql`
  # Type returned after attempting to send SMS
  type SendSmsResponse {
    success: Boolean!
    bulkId: String # Infobip's ID for the batch submission
    message: String # Optional message for non-bulk results
    # Optional: Add individual message statuses if needed
    # messages: [InfobipMessageStatus]
  }

  # Input for the sendSms mutation
  input SendSmsInput {
    to: [String!]! # Array of phone numbers (E.164 format required)
    text: String!
    from: String # Optional: Override default sender ID
  }

  # Define Mutations (actions that change data or trigger processes)
  type Mutation {
    """"""
    Triggers sending an SMS message to multiple recipients via Infobip.
    Requires authentication. Use for ad-hoc sends not tied to a stored campaign.
    """"""
    sendSms(input: SendSmsInput!): SendSmsResponse! @requireAuth
  }

  # --- Placeholder Types/Queries/Mutations for Campaigns (added in Section 6) ---
  # type Campaign { ... }
  # type Recipient { ... }
  # type Query { ... }
  # input CreateCampaignInput { ... }
  # input UpdateCampaignInput { ... }
  # input TriggerCampaignSendInput { ... }
  # type Mutation {
  #   createCampaign(...)
  #   updateCampaign(...)
  #   deleteCampaign(...)
  #   triggerCampaignSend(...)
  # }
  # --- End Placeholders ---
`

// api/src/services/campaigns/campaigns.ts
// ... imports ...

interface SendSmsInput { // Renamed from SendSmsPayload to match SDL
  to: string[]
  text: string
  from?: string
}

// Renamed function to match SDL mutation name 'sendSms'
// The input argument is automatically destructured by Redwood { input }
export const sendSms = async ({ input }: { input: SendSmsInput }) => {
  const { to, text, from } = input // Destructure from the input object

  const apiKey = process.env.INFOBIP_API_KEY
  const baseUrl = process.env.INFOBIP_BASE_URL
  const senderId = from || process.env.INFOBIP_SENDER_ID || 'InfoSMS'

  // ... (rest of the validation and payload logic remains the same) ...

  const infobipUrl = `${baseUrl}/sms/3/messages` // Updated to current SMS API v3 endpoint
  const payload = {
    messages: to.map((recipient) => ({
      destinations: [{ to: recipient }],
      from: senderId,
      text: text,
    })),
  }

  try {
    logger.info(`Sending SMS via Infobip to ${to.length} recipients.`)
    logger.debug({ payload: { messages: payload.messages.map(m => ({...m, text: '[REDACTED]'})) } }, 'Infobip Request Payload (Text Redacted):')

    const response = await axios.post(infobipUrl, payload, {
      headers: {
        Authorization: `App ${apiKey}`,
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
      timeout: 10000,
    })

    logger.info(
      { bulkId: response.data.bulkId, status: response.status },
      'Infobip SMS submitted successfully.'
    )

    // Ensure the return matches SendSmsResponse type in SDL
     return {
      success: true,
      bulkId: response.data.bulkId,
      // messages: response.data.messages, // Optional detailed statuses
      message: `SMS submitted successfully to ${to.length} numbers.` // Add optional message
    }
  } catch (error) {
     logger.error({ error }, 'Failed to send SMS via Infobip.')

     if (axios.isAxiosError(error)) {
       logger.error(
         {
           status: error.response?.status,
           data: error.response?.data,
         },
         'Infobip API Error Details'
       )
       const errorMessage = error.response?.data?.requestError?.serviceException?.text || error.message;
       throw new Error(`Infobip API request failed: ${errorMessage}`)
     } else {
       throw new Error(`An unexpected error occurred: ${error.message}`)
     }
     // Re-throw the error after logging so GraphQL reports it
     // throw error; // Original code had this commented out, but re-throwing is usually correct for GraphQL
  }
}
// ... rest of the file ...

mutation SendTestSms {
  # Note: This will fail if @requireAuth is active and you haven't set up auth
  sendSms(
    input: {
      # Replace with actual E.164 numbers you can test with
      to: [""+15551234567"", ""+15559876543""]
      text: ""Hello from RedwoodJS and Infobip!""
      # from: ""OptionalSender"" # Optionally override sender from .env
    }
  ) {
    success
    bulkId
    message
  }
}

// api/src/services/campaigns/campaigns.ts
import axios from 'axios'
// ... other imports ...
import { logger } from 'src/lib/logger'

// Helper function for async delay
const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

// ... interface SendSmsInput ...

export const sendSms = async ({ input }: { input: SendSmsInput }) => {
  const { to, text, from } = input
  const apiKey = process.env.INFOBIP_API_KEY
  const baseUrl = process.env.INFOBIP_BASE_URL
  const senderId = from || process.env.INFOBIP_SENDER_ID || 'InfoSMS'

  // ... validation ...
  if (!apiKey || !baseUrl) {
    logger.error('Infobip API Key or Base URL missing in environment variables.')
    throw new Error('Infobip configuration is incomplete.')
  }
  if (!to || to.length === 0 || !text) {
    logger.error('Missing required parameters: to (list of numbers) and text.')
    throw new Error('Recipient numbers and message text are required.')
  }

  const infobipUrl = `${baseUrl}/sms/3/messages` // Updated to current SMS API v3 endpoint
  const payload = {
    messages: to.map((recipient) => ({
      destinations: [{ to: recipient }],
      from: senderId,
      text: text,
    })),
  }

  const MAX_RETRIES = 3;
  let attempt = 0;

  while (attempt < MAX_RETRIES) {
      attempt++;
      try {
          logger.info(`Sending SMS via Infobip (Attempt ${attempt}/${MAX_RETRIES}) to ${to.length} recipients.`);
          // logger.debug({ payload }, 'Infobip Request Payload:'); // Be cautious logging payload

          const response = await axios.post(infobipUrl, payload, {
             headers: {
                Authorization: `App ${apiKey}`,
                'Content-Type': 'application/json',
                Accept: 'application/json',
             },
             timeout: 15000 // Slightly longer timeout for retries
          });

          logger.info(
            { bulkId: response.data.bulkId, status: response.status, attempt },
            'Infobip SMS submitted successfully.'
          );
          return {
             success: true,
             bulkId: response.data.bulkId,
             message: `SMS submitted successfully on attempt ${attempt}.`,
            // messages: response.data.messages,
          };

      } catch (error) {
          logger.warn({ error: error.message, attempt, maxRetries: MAX_RETRIES }, `Attempt ${attempt} failed for Infobip SMS.`);

          let shouldRetry = false;
          // Exponential backoff: 1s, 2s, 4s... + some jitter
          let waitMs = 1000 * Math.pow(2, attempt - 1) + Math.random() * 500;

          if (axios.isAxiosError(error)) {
              const status = error.response?.status;
              // Retry on network errors or specific server errors (e.g., 5xx)
              if (!status || (status >= 500 && status <= 599)) {
                  shouldRetry = true;
                  logger.warn(`Network or server error (${status || 'N/A'}), scheduling retry.`);
              } else {
                   // Log details for non-retryable client errors (4xx) or others
                   logger.error({ status: error.response?.status, data: error.response?.data }, 'Non-retryable Infobip API Error Details');
              }
          } else {
              // Non-axios error (e.g., code error before request)
              logger.error({ error }, 'Non-Axios error during Infobip request attempt.');
              // Generally don't retry these unless specifically handled
          }

          if (shouldRetry && attempt < MAX_RETRIES) {
              logger.info(`Waiting ${Math.round(waitMs)}ms before next retry.`);
              await delay(waitMs);
              // Continue to next iteration of the loop
          } else {
              // Last attempt failed or non-retryable error occurred
               logger.error({ error: error.message, attempt }, 'Failed to send SMS via Infobip after all retries or due to non-retryable error.');
               // Construct a meaningful error to throw
               let finalError;
               if (axios.isAxiosError(error)) {
                 const errorMessage = error.response?.data?.requestError?.serviceException?.text || error.message;
                 finalError = new Error(`Infobip API request failed after ${attempt} attempts: ${errorMessage}`);
               } else {
                 finalError = new Error(`An unexpected error occurred after ${attempt} attempts: ${error.message}`);
               }
               throw finalError; // Throw the aggregated/final error
          }
      }
  }
  // This line should technically be unreachable if the logic above is correct,
  // as the loop either returns successfully or throws an error.
  // Included primarily for type safety / exhaustive checks in some setups.
  // throw new Error('SMS sending failed unexpectedly after retry loop.');
}
// ... rest of file ...

// api/db/schema.prisma

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

generator client {
  provider      = ""prisma-client-js""
  binaryTargets = ""native"" // Or specific targets like ""debian-openssl-1.1.x"" for deployment
}

model Recipient {
  id          Int      @id @default(autoincrement())
  phoneNumber String   @unique // E.164 format REQUIRED
  firstName   String?
  lastName    String?
  isOptedOut  Boolean  @default(false) // Added for opt-out tracking
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt

  // Many-to-Many relationship with Campaign
  campaigns   Campaign[] @relation(""CampaignRecipients"")

  @@index([isOptedOut]) // Index for filtering active recipients
}

model Campaign {
  id            Int      @id @default(autoincrement())
  name          String   @unique
  message       String
  senderId      String?  // Campaign-specific sender override
  // Suggested statuses: DRAFT, SCHEDULED, SENDING, SENT, FAILED, COMPLETE_NO_RECIPIENTS
  status        String   @default(""DRAFT"")
  scheduledAt   DateTime?
  sentAt        DateTime? // Timestamp when sending was initiated/completed
  infobipBulkId String?  // Store Infobip's bulk ID for tracking
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt

  // Many-to-Many relationship with Recipient
  recipients    Recipient[] @relation(""CampaignRecipients"")

  @@index([status])
  @@index([scheduledAt])
}

// Prisma implicitly handles the join table (_CampaignRecipients)
// based on the @relation definition above.

yarn rw prisma migrate dev
# Provide migration name, e.g., ""add campaign recipient models optout""

// api/src/services/campaigns/campaigns.ts
import axios from 'axios'
import type { Prisma, Campaign, Recipient } from '@prisma/client' // Import types
import { db } from 'src/lib/db'
import { logger } from 'src/lib/logger'
import { requireAuth } from 'src/lib/auth' // Assuming auth is set up

// --- Helper: delay function (from Section 5) ---
const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

// --- Interface: SendSmsInput (from Section 3) ---
interface SendSmsInput { to: string[]; text: string; from?: string; }

// --- Service Function: sendSms (with retries, from Section 5) ---
export const sendSms = async ({ input }: { input: SendSmsInput }) => {
    // ... existing sendSms logic with retries ...
    const { to, text, from } = input
    const apiKey = process.env.INFOBIP_API_KEY
    const baseUrl = process.env.INFOBIP_BASE_URL
    const senderId = from || process.env.INFOBIP_SENDER_ID || 'InfoSMS'

    if (!apiKey || !baseUrl) {
      logger.error('Infobip API Key or Base URL missing in environment variables.')
      throw new Error('Infobip configuration is incomplete.')
    }
    if (!to || to.length === 0 || !text) {
      logger.error('Missing required parameters: to (list of numbers) and text.')
      throw new Error('Recipient numbers and message text are required.')
    }

    const infobipUrl = `${baseUrl}/sms/3/messages` // Updated to current SMS API v3 endpoint
    const payload = {
      messages: to.map((recipient) => ({
        destinations: [{ to: recipient }],
        from: senderId,
        text: text,
      })),
    }

    const MAX_RETRIES = 3;
    let attempt = 0;

    while (attempt < MAX_RETRIES) {
        attempt++;
        try {
            logger.info(`Sending SMS via Infobip (Attempt ${attempt}/${MAX_RETRIES}) to ${to.length} recipients.`);

            const response = await axios.post(infobipUrl, payload, {
               headers: {
                  Authorization: `App ${apiKey}`,
                  'Content-Type': 'application/json',
                  Accept: 'application/json',
               },
               timeout: 15000
            });

            logger.info(
              { bulkId: response.data.bulkId, status: response.status, attempt },
              'Infobip SMS submitted successfully.'
            );
            return {
               success: true,
               bulkId: response.data.bulkId,
               message: `SMS submitted successfully on attempt ${attempt}.`,
            };

        } catch (error) {
            logger.warn({ error: error.message, attempt, maxRetries: MAX_RETRIES }, `Attempt ${attempt} failed for Infobip SMS.`);

            let shouldRetry = false;
            let waitMs = 1000 * Math.pow(2, attempt - 1) + Math.random() * 500;

            if (axios.isAxiosError(error)) {
                const status = error.response?.status;
                if (!status || (status >= 500 && status <= 599)) {
                    shouldRetry = true;
                    logger.warn(`Network or server error (${status || 'N/A'}), scheduling retry.`);
                } else {
                     logger.error({ status: error.response?.status, data: error.response?.data }, 'Non-retryable Infobip API Error Details');
                }
            } else {
                logger.error({ error }, 'Non-Axios error during Infobip request attempt.');
            }

            if (shouldRetry && attempt < MAX_RETRIES) {
                logger.info(`Waiting ${Math.round(waitMs)}ms before next retry.`);
                await delay(waitMs);
            } else {
                 logger.error({ error: error.message, attempt }, 'Failed to send SMS via Infobip after all retries or due to non-retryable error.');
                 let finalError;
                 if (axios.isAxiosError(error)) {
                   const errorMessage = error.response?.data?.requestError?.serviceException?.text || error.message;
                   finalError = new Error(`Infobip API request failed after ${attempt} attempts: ${errorMessage}`);
                 } else {
                   finalError = new Error(`An unexpected error occurred after ${attempt} attempts: ${error.message}`);
                 }
                 throw finalError;
            }
        }
    }
    // Should be unreachable
    throw new Error('SMS sending failed unexpectedly after retry loop.');
}


// --- Campaign CRUD Functions ---

/** Returns a list of campaigns (consider pagination for production). */
export const campaigns = () => {
  requireAuth({ roles: ['admin', 'marketer'] }) // Example role check
  return db.campaign.findMany({ orderBy: { createdAt: 'desc' } })
}

/** Returns a single campaign by ID, including its recipients. */
export const campaign = ({ id }: Prisma.CampaignWhereUniqueInput) => {
  requireAuth()
  return db.campaign.findUnique({
    where: { id },
    include: {
      recipients: { // Optionally filter/paginate recipients here too
         orderBy: { createdAt: 'asc' }
      }
    },
  })
}

// Use Prisma generated types for better safety
interface CreateCampaignServiceInput {
  input: Omit<Prisma.CampaignCreateInput, 'recipients'> & { // Base Campaign data
    recipientIds?: number[] // Accept array of Recipient IDs
  }
}

/** Creates a new campaign. Optionally connects recipients by ID. */
export const createCampaign = async ({ input }: CreateCampaignServiceInput) => {
  requireAuth({ roles: ['admin', 'marketer'] })
  const { recipientIds, ...campaignData } = input

  return db.campaign.create({
    data: {
      ...campaignData, // Spread basic fields like name, message, status
      status: campaignData.status || 'DRAFT', // Ensure default status
      // Connect recipients if IDs are provided
      recipients: recipientIds && recipientIds.length > 0
        ? { connect: recipientIds.map((id) => ({ id })) }
        : undefined,
    },
  })
}

interface UpdateCampaignServiceInput {
   id: number;
   input: Omit<Prisma.CampaignUpdateInput, 'recipients'> & {
     recipientIds?: number[] // Allow updating connected recipients
   }
}

/** Updates an existing campaign. Allows replacing the recipient list. */
export const updateCampaign = ({ id, input }: UpdateCampaignServiceInput) => {
   requireAuth({ roles: ['admin', 'marketer'] })
   const { recipientIds, ...campaignData } = input

   return db.campaign.update({
     where: { id },
     data: {
       ...campaignData,
       // Use 'set' to replace the entire list of connected recipients
       // Use connect/disconnect for adding/removing specific ones if needed
       recipients: recipientIds
        ? { set: recipientIds.map((id) => ({ id })) }
        : undefined, // If recipientIds is omitted, don't change recipients
     },
   })
}

/** Deletes a campaign by its ID. */
export const deleteCampaign = ({ id }: Prisma.CampaignWhereUniqueInput) => {
   requireAuth({ roles: ['admin'] }) // Stricter role for deletion
   // Add checks: prevent deletion of 'SENDING' or recently 'SENT' campaigns?
   return db.campaign.delete({
     where: { id },
   })
}


// --- Trigger Campaign Sending Logic ---

interface TriggerCampaignSendInput {
  campaignId: number
}

/** Fetches campaign details and sends SMS to its ACTIVE recipients. */
export const triggerCampaignSend = async ({ input }: { input: TriggerCampaignSendInput }) => {
    requireAuth({ roles: ['admin', 'marketer'] })
    const { campaignId } = input;

    logger.info({ campaignId }, ""Attempting to trigger campaign send."");

    // Fetch campaign WITH recipients
    const camp = await db.campaign.findUnique({
        where: { id: campaignId },
        include: { recipients: true } // Include related recipients
    });

    if (!camp) {
        logger.error({ campaignId }, ""Campaign not found for triggering send."");
        throw new Error(`Campaign with ID ${campaignId} not found.`);
    }

    // Filter out opted-out recipients
    const activeRecipients = camp.recipients.filter(r => !r.isOptedOut);

    if (activeRecipients.length === 0) {
        logger.warn({ campaignId }, ""Campaign has no active (opted-in) recipients. Nothing to send."");
        // Update status to reflect this outcome
        await db.campaign.update({
            where: { id: campaignId },
            data: { status: 'COMPLETE_NO_RECIPIENTS', sentAt: new Date() } // Mark as completed
        });
        return { success: true, message: ""Campaign has no active recipients."" };
    }

    // Prevent re-sending or sending while already in progress
    if (camp.status === 'SENDING' || camp.status === 'SENT') {
         logger.warn({ campaignId, status: camp.status }, ""Campaign is already sending or has been sent. Send trigger ignored."");
         // Return success:false or throw an error depending on desired behavior
         return { success: false, message: `Campaign status is already ${camp.status}. Send trigger ignored.` };
    }

    // Update campaign status to SENDING before initiating send
    await db.campaign.update({
        where: { id: campaignId },
        data: { status: 'SENDING', sentAt: new Date() } // Mark start time
    });

    let sendResult;
    try {
        const recipientNumbers = activeRecipients.map(r => r.phoneNumber);
        const sender = camp.senderId; // Use campaign-specific sender if set

        // Call the core SMS sending function (which includes retries)
        sendResult = await sendSms({
            input: {
                to: recipientNumbers,
                text: camp.message,
                from: sender // Pass campaign sender override if available
            }
        });

        // Update campaign status to SENT (or potentially FAILED_PARTIAL if needed)
        await db.campaign.update({
            where: { id: campaignId },
            data: {
                status: 'SENT', // Mark as sent after successful submission to Infobip
                infobipBulkId: sendResult.bulkId // Store the bulk ID
            }
        });

        logger.info({ campaignId, bulkId: sendResult.bulkId, recipientCount: recipientNumbers.length }, ""Campaign SMS successfully submitted to Infobip."");
        return { success: true, bulkId: sendResult.bulkId, message: `Campaign ${campaignId} sent to ${recipientNumbers.length} recipients.` };

    } catch (error) {
        logger.error({ campaignId, error: error.message }, ""Failed to send campaign SMS via Infobip."");
        // Update campaign status to FAILED
        await db.campaign.update({
            where: { id: campaignId },
            data: { status: 'FAILED' } // Mark as failed
        });
        // Re-throw the error so the GraphQL mutation reports failure
        throw new Error(`Failed to send campaign ${campaignId}: ${error.message}`);
    }
}

---

## 7. SMS Marketing Compliance (TCPA & FCC Regulations)

**CRITICAL: Legal requirements for SMS marketing in the United States.**

### TCPA Requirements (United States)

The Telephone Consumer Protection Act (TCPA) governs commercial SMS messaging. **Non-compliance can result in penalties of $500 per violation, or $1,500 per willful violation, with no cap on total damages.**

#### Prior Express Written Consent (Required)

Before sending any marketing SMS messages, you **must** obtain prior express written consent from recipients. This means:

*   **Clear Authorization**: Consumers must explicitly agree to receive SMS messages
*   **Written Record**: Maintain documentation of consent (date, time, method, exact language used)
*   **Scope Disclosure**: Clearly state what types of messages they'll receive and frequency

**Example Consent Language:**

```text
By providing your phone number and checking this box, you agree to receive 
marketing text messages from [Business Name] at the number provided, including 
messages sent by autodialer. Consent is not a condition of purchase. Message 
and data rates may apply. Message frequency varies. Reply HELP for help or 
STOP to cancel.

model Recipient {
  id           Int      @id @default(autoincrement())
  phoneNumber  String   @unique
  firstName    String?
  lastName     String?
  isOptedOut   Boolean  @default(false)
  consentDate  DateTime? // When consent was obtained
  consentMethod String?  // How consent was obtained (e.g., "web_form", "checkout")
  optOutDate   DateTime? // When user opted out
  optOutMethod String?   // How user opted out (e.g., "SMS_STOP", "web_preferences")
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt
  campaigns    Campaign[] @relation("CampaignRecipients")
  @@index([isOptedOut])
}

// Add this check before sending in triggerCampaignSend function
const now = new Date();
const hour = now.getHours(); // 0-23 in server's local time
// NOTE: For production, use recipient's timezone via a timezone library
if (hour < 8 || hour >= 21) {
    logger.warn({ campaignId, hour }, "Campaign send attempted outside allowed hours (8 AM - 9 PM).");
    throw new Error("SMS messages cannot be sent before 8:00 AM or after 9:00 PM per TCPA regulations.");
}

// Example: api/src/functions/smsWebhook/smsWebhook.ts
export const handler = async (event) => {
  const body = JSON.parse(event.body);
  const incomingText = body.message?.text?.toLowerCase().trim();
  const senderNumber = body.message?.from;

  const optOutKeywords = ['stop', 'unsubscribe', 'cancel', 'end', 'quit', 'remove'];
  const isOptOut = optOutKeywords.some(keyword => 
    incomingText?.includes(keyword)
  );

  if (isOptOut && senderNumber) {
    // Update recipient in database
    await db.recipient.updateMany({
      where: { phoneNumber: senderNumber },
      data: { 
        isOptedOut: true,
        optOutDate: new Date(),
        optOutMethod: 'SMS_KEYWORD'
      }
    });

    logger.info({ senderNumber, keyword: incomingText }, 'Recipient opted out via SMS');
    
    // Send confirmation (ONE time only per FCC rules)
    // Implementation here...
  }

  return { statusCode: 200 };
};

// api/src/services/campaigns/campaigns.test.ts
import { sendSms, triggerCampaignSend } from './campaigns';

scenario('sends SMS successfully', async (scenario) => {
  // Mock axios or Infobip responses
  const result = await sendSms({
    input: {
      to: ['+15551234567'],
      text: 'Test message',
      from: 'TestSender'
    }
  });

  expect(result.success).toBe(true);
  expect(result.bulkId).toBeDefined();
});

scenario('respects opt-out status', async (scenario) => {
  const campaign = scenario.campaign.withOptedOutRecipient;
  const result = await triggerCampaignSend({ 
    input: { campaignId: campaign.id } 
  });
  
  // Should not send to opted-out recipients
  expect(result.message).toContain('no active recipients');
});

// Use RedwoodJS testing utilities
import { mockGraphQLQuery, mockCurrentUser } from '@redwoodjs/testing/api';

test('sendSms mutation works', async () => {
  mockCurrentUser({ id: 1, roles: ['admin'] });
  
  const result = await mockGraphQLQuery(SEND_SMS_MUTATION, {
    variables: {
      input: {
        to: ['+15551234567'],
        text: 'Test'
      }
    }
  });

  expect(result.data.sendSms.success).toBe(true);
});

yarn rw prisma migrate deploy