Developer Guide: Building SMS Marketing Campaigns with Fastify and Plivo

This guide provides a step-by-step walkthrough for building a production-ready SMS marketing campaign application using the Fastify framework for Node.js and Plivo's messaging platform APIs. We will cover everything from initial project setup to deployment and monitoring.

By the end of this tutorial, you will have a functional backend service capable of managing subscriber lists, creating SMS marketing campaigns, and sending bulk messages via Plivo, incorporating best practices for security, error handling, and scalability.

Project Overview and Goals

What We're Building:

We are creating a backend API service using Fastify. This service will manage:

1. Subscribers: Storing phone numbers and consent status for receiving marketing messages.
2. Campaigns: Defining marketing messages and targeting specific subscriber groups (though for simplicity, we'll initially target all opted-in subscribers).
3. Sending: Triggering the dispatch of campaign messages to opted-in subscribers via the Plivo SMS API.

Problem Solved:

This application provides the core infrastructure needed for businesses to leverage SMS marketing effectively. It centralizes subscriber management, ensures consent is handled, and integrates with a reliable communication platform (Plivo) for message delivery.

Technologies Used:

• Node.js: The JavaScript runtime environment.
• Fastify: A high-performance, low-overhead Node.js web framework. Chosen for its speed, extensibility, and developer-friendly features (like built-in validation and logging).
• Plivo: A cloud communications platform providing SMS API capabilities. Chosen for its reliable delivery, developer tools, and scalability.
• PostgreSQL: A robust open-source relational database.
• Prisma: A modern ORM for Node.js and TypeScript, simplifying database interactions.
• Docker: For containerizing the application for consistent deployment.
• Fly.io: (Example deployment platform) A platform for deploying full-stack apps and databases.
• GitHub Actions: For continuous integration and deployment (CI/CD).

System Architecture:

+-------------+       +-----------------+       +-------------+
|   Client    | ----> |  Fastify API    | ----> |  Plivo API  |
| (e.g., Web) |       | (This Project)  |       |  (for SMS)  |
+-------------+       +--------+--------+       +-------------+
                              |
                              |
                              v
                      +---------------+
                      |  PostgreSQL   |
                      |  (Database)   |
                      +---------------+

Prerequisites:

• Node.js (LTS version recommended) and npm/yarn installed.
• Access to a PostgreSQL database instance, including connection details (URL string with username, password, host, port, database name) for configuration.
• A Plivo account with Auth ID, Auth Token, and a Plivo phone number capable of sending SMS.
• Docker installed locally (for containerization and deployment).
• Fly.io CLI installed (optional, for deployment).
• Basic familiarity with Node.js, REST APIs, and SQL.

Final Outcome:

A containerized Fastify application exposing RESTful API endpoints for managing subscribers and campaigns, capable of sending SMS messages via Plivo. The application will include logging, basic error handling, security measures, and deployment configurations.

1. Setting up the Project

Let's initialize our Fastify project and set up the basic structure.

1. Create Project Directory:

   bash

   mkdir fastify-plivo-sms
   cd fastify-plivo-sms
   

2. Initialize Node.js Project:

   bash

   npm init -y
   

3. Install Core Dependencies:

   bash

   npm install fastify fastify-env fastify-sensible fastify-cors pino-pretty @prisma/client plivo async-retry libphonenumber-js fastify-rate-limit @fastify/helmet @fastify/sentry @sentry/node @sentry/tracing
   # For potential async/job queue implementation (optional but recommended for production bulk sending):
   # npm install bullmq ioredis
   
   • fastify: The core framework.
   • fastify-env: For managing environment variables.
   • fastify-sensible: Adds useful decorators like httpErrors.
   • fastify-cors: Enables Cross-Origin Resource Sharing.
   • pino-pretty: Developer-friendly logger formatting (for development).
   • @prisma/client: Prisma's database client.
   • plivo: The official Plivo Node.js SDK.
   • async-retry: For adding retry logic to Plivo calls.
   • libphonenumber-js: For robust phone number validation/formatting.
   • fastify-rate-limit: For API rate limiting.
   • @fastify/helmet: For security headers.
   • @fastify/sentry, @sentry/node, @sentry/tracing: For error tracking with Sentry.
   • bullmq, ioredis: (Optional) Recommended for production-grade background job processing.

4. Install Development Dependencies:

   bash

   npm install --save-dev prisma nodemon tap
   
   • prisma: The Prisma CLI for migrations and generation.
   • nodemon: Automatically restarts the server during development.
   • tap: Fastify's recommended testing framework.

5. Configure package.json Scripts: Update the scripts section in your package.json:

   json

   // package.json
   "scripts": {
     "test": "tap 'test/**/*.test.js'",
     "start": "node src/server.js",
     "dev": "nodemon --watch src --exec 'node --inspect=127.0.0.1:9229' src/server.js | pino-pretty",
     "db:seed": "node scripts/seed.js",
     "prisma:migrate": "npx prisma migrate dev",
     "prisma:generate": "npx prisma generate",
     "prisma:deploy": "npx prisma migrate deploy"
   },
   
   • test: Runs tests using tap.
   • start: Runs the application in production mode.
   • dev: Runs the application in development mode with nodemon for auto-reloads, pino-pretty for readable logs, and the Node inspector attached to 127.0.0.1 (localhost only) for security.
   • db:seed: Runs the database seeding script.
   • prisma:*: Helper scripts for Prisma operations.

6. Initialize Prisma:

   bash

   npx prisma init --datasource-provider postgresql
   

   This creates a prisma directory with a schema.prisma file and a .env file for your database connection string.

7. Configure Environment Variables (.env): Update the generated .env file. Add placeholders for Plivo credentials and other settings.

   bash

   # .env
   
   # Database Connection (Prisma uses this)
   # Example: postgresql://user:password@host:port/database?schema=public
   DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/sms_marketing?schema=public"
   
   # Application Settings
   HOST=0.0.0.0
   PORT=3000
   LOG_LEVEL=info # Use 'debug' for more verbose logging
   NODE_ENV=development # Set to 'production' in deployed environments
   
   # Plivo Credentials
   PLIVO_AUTH_ID="YOUR_PLIVO_AUTH_ID"
   PLIVO_AUTH_TOKEN="YOUR_PLIVO_AUTH_TOKEN" # Also used for webhook signature validation
   PLIVO_SENDER_NUMBER="YOUR_PLIVO_PHONE_NUMBER" # Must be SMS-enabled
   
   # Sentry DSN (Optional - for error tracking)
   SENTRY_DSN=""
   
   # Add any other environment variables as needed
   
   • Important: Replace placeholders with your actual database URL and Plivo credentials. Never commit your .env file with real secrets to version control. Add .env to your .gitignore file.

8. Project Structure: Create the following directory structure:

   fastify-plivo-sms/
   ├── prisma/
   │   └── schema.prisma
   ├── src/
   │   ├── plugins/
   │   ├── routes/
   │   ├── services/
   │   ├── app.js        # Main Fastify application setup
   │   └── server.js     # Entry point to start the server
   ├── test/
   ├── scripts/
   │   └── seed.js       # Database seeding script
   ├── .github/
   │   └── workflows/
   │       └── deploy.yml # Example CI/CD workflow
   ├── .env
   ├── .gitignore
   ├── Dockerfile
   ├── fly.toml          # Example deployment config
   └── package.json
   

9. Basic Fastify App Setup (src/app.js):

   javascript

   // src/app.js
   'use strict'
   
   const path = require('path')
   const Fastify = require('fastify')
   const sensible = require('fastify-sensible')
   const env = require('fastify-env')
   const cors = require('fastify-cors')
   const autoload = require('fastify-autoload')
   const helmet = require('@fastify/helmet')
   const rateLimit = require('fastify-rate-limit')
   const Sentry = require('@sentry/node')
   
   // Define environment variable schema
   const schema = {
     type: 'object',
     required: [ 'PORT', 'HOST', 'DATABASE_URL', 'PLIVO_AUTH_ID', 'PLIVO_AUTH_TOKEN', 'PLIVO_SENDER_NUMBER' ],
     properties: {
       PORT: { type: 'string', default: 3000 },
       HOST: { type: 'string', default: '0.0.0.0' },
       DATABASE_URL: { type: 'string' },
       LOG_LEVEL: { type: 'string', default: 'info'},
       NODE_ENV: { type: 'string', default: 'development' },
       PLIVO_AUTH_ID: { type: 'string' },
       PLIVO_AUTH_TOKEN: { type: 'string' },
       PLIVO_SENDER_NUMBER: { type: 'string' },
       SENTRY_DSN: { type: 'string', default: '' } // Optional
     },
   }
   
   const envOptions = {
     confKey: 'config', // Access variables via `fastify.config`
     schema: schema,
     dotenv: true // Load .env file
   }
   
   async function build (opts = {}) {
     const fastify = Fastify({
       logger: {
         level: process.env.LOG_LEVEL || 'info', // Default log level
         // Use pino-pretty in dev, JSON in production
         ...(process.env.NODE_ENV !== 'production' && {
             transport: {
                 target: 'pino-pretty',
                 options: {
                     translateTime: 'HH:MM:ss Z',
                     ignore: 'pid,hostname',
                 },
             },
         }),
       },
       ...opts
     })
   
     // Register essential plugins FIRST
     await fastify.register(env, envOptions)
   
      // Initialize Sentry (early, using env vars from fastify.config)
      if (fastify.config.SENTRY_DSN) {
        fastify.register(require('@fastify/sentry'), {
          dsn: fastify.config.SENTRY_DSN,
          environment: fastify.config.NODE_ENV || 'development',
          // Add other Sentry config as needed (release, tracesSampleRate)
        });
        fastify.log.info('Sentry plugin registered.');
      } else {
        fastify.log.warn('SENTRY_DSN not found, Sentry integration disabled.');
      }
   
     await fastify.register(sensible) // Adds useful utilities like fastify.httpErrors
     await fastify.register(cors, {
       origin: '*', // Configure allowed origins appropriately for production
       methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']
     })
     await fastify.register(helmet, {
         // Disable CSP if not needed or configured separately via reverse proxy
         contentSecurityPolicy: false
     });
     await fastify.register(rateLimit, {
         max: 100, // Max requests per windowMs per key
         timeWindow: '1 minute',
         errorResponseBuilder: (req, context) => ({
             code: 429, error: 'Too Many Requests',
             message: `Rate limit exceeded. Retry after ${context.after}`
         })
         // Consider using Redis for distributed rate limiting:
         // redis: new require('ioredis')(process.env.REDIS_URL)
     });
   
     // Autoload plugins (like database, plivo client)
     await fastify.register(autoload, {
       dir: path.join(__dirname, 'plugins'),
       options: { ...opts, config: fastify.config } // Pass config to plugins
     })
   
     // Autoload routes (including webhooks)
     await fastify.register(autoload, {
       dir: path.join(__dirname, 'routes'),
       options: { prefix: '/api/v1' } // Prefix API routes
     })
     // Load health check route without prefix
     await fastify.register(require('./routes/health'))
     // Load webhook route without prefix for easier configuration in Plivo
     await fastify.register(require('./routes/webhooks'), { prefix: '/webhooks' })
   
   
     fastify.log.info('Application plugins and routes loaded.')
   
     return fastify
   }
   
   module.exports = { build }
   
   • Why fastify-env? It validates required environment variables on startup, preventing runtime errors due to missing configuration.
   • Why fastify-sensible? Provides standard HTTP error objects (fastify.httpErrors.notFound()) and other utilities.
   • Why fastify-autoload? Simplifies loading plugins and routes from separate directories, keeping app.js clean.
   • Security Plugins: helmet and rateLimit added early.
   • Error Tracking: Sentry initialized early.
   • Route Loading: API routes prefixed, health and webhook routes loaded separately without prefix.

10. Server Entry Point (src/server.js):

    javascript

    // src/server.js
    'use strict'
    
    // If using Sentry, require it early for tracing instrumentation
    if (process.env.SENTRY_DSN) {
      require('@sentry/node');
    }
    
    const { build } = require('./app')
    
    async function start () {
      let fastify
      try {
        fastify = await build()
    
        await fastify.ready() // Ensure all plugins are loaded
    
        const host = fastify.config.HOST
        const port = fastify.config.PORT
    
        await fastify.listen({ port: port, host: host }) // Use object syntax for listen
    
      } catch (err) {
        console.error('Error starting server:', err)
        if (fastify) {
          fastify.log.error(err)
        } else {
            // If Fastify didn't even initialize, log directly
            console.error(err);
        }
        process.exit(1)
      }
    }
    
    start()
    

11. Add .gitignore: Create a .gitignore file in the root directory:

    # .gitignore
    node_modules/
    .env
    dist/
    coverage/
    npm-debug.log*
    yarn-debug.log*
    yarn-error.log*
    *.local
    
    # Prisma generated client (usually in node_modules, but good to ignore explicitly if output changes)
    # node_modules/@prisma/client/
    
    # Prisma migration SQL files (usually not committed, schema is the source of truth)
    # If you *do* want to commit SQL for review, remove or adjust this line.
    prisma/migrations/**/*.sql
    !prisma/migrations/migration_lock.toml
    
    # Fly.io state (if applicable)
    .fly/
    
    • Note on prisma/migrations/*.sql: This line prevents generated SQL migration files from being committed. This is standard practice as the schema.prisma file is the source of truth, and migrations are generated from it. If your team workflow requires committing the SQL files for review, you can remove this line.

You now have a basic Fastify project structure ready for adding features. Run npm run dev to start the development server. You should see log output indicating the server is listening.

2. Implementing Core Functionality

We'll start by defining our database schema and creating services for managing subscribers and campaigns.

1. Define Database Schema (prisma/schema.prisma):

   sql

   // prisma/schema.prisma
   generator client {
     provider = ""prisma-client-js""
   }
   
   datasource db {
     provider = ""postgresql""
     url      = env(""DATABASE_URL"")
   }
   
   model Subscriber {
     id          String   @id @default(cuid()) // Unique ID
     phoneNumber String   @unique             // Subscriber's phone number (E.164 format recommended)
     isOptedIn   Boolean  @default(true)      // Consent status for marketing
     createdAt   DateTime @default(now())
     updatedAt   DateTime @updatedAt
   
     @@index([isOptedIn]) // Index for filtering opted-in subscribers
   }
   
   model Campaign {
     id           String    @id @default(cuid())
     name         String    // Internal name for the campaign
     messageBody  String    // The SMS message content
     sentAt       DateTime? // Timestamp when the campaign was sent
     createdAt    DateTime  @default(now())
     updatedAt    DateTime  @updatedAt
   }
   
   • Why CUID? Provides unique, sortable identifiers.
   • Why @unique on phoneNumber? Prevents duplicate subscriber entries.
   • Why isOptedIn? Crucial for tracking consent, a legal requirement (e.g., TCPA, GDPR).
   • Why @@index([isOptedIn])? Added an index to potentially speed up queries filtering by opt-in status, which is common.

2. Apply Database Migrations: Create the initial migration and apply it to your database.

   bash

   # Create the migration files based on schema changes
   npm run prisma:migrate -- --name init
   
   # Generate the Prisma client types
   npm run prisma:generate
   

   Prisma will create the Subscriber and Campaign tables in your PostgreSQL database.

3. Create Prisma Plugin (src/plugins/prisma.js): This plugin initializes the Prisma client and makes it available throughout the Fastify application.

   javascript

   // src/plugins/prisma.js
   'use strict'
   
   const fp = require('fastify-plugin')
   const { PrismaClient } = require('@prisma/client')
   
   async function prismaPlugin (fastify, options) {
     const prisma = new PrismaClient({
       log: fastify.config.LOG_LEVEL === 'debug' ? ['query', 'info', 'warn', 'error'] : ['warn', 'error'],
     })
   
     try {
       await prisma.$connect()
       fastify.log.info('Prisma client connected successfully.')
     } catch (err) {
       fastify.log.error('Prisma client connection error:', err)
       throw new Error('Failed to connect to database') // Prevent server start if DB fails
     }
   
     // Make Prisma Client available through decorator
     fastify.decorate('prisma', prisma)
   
     // Graceful shutdown
     fastify.addHook('onClose', async (instance) => {
       instance.log.info('Disconnecting Prisma client...')
       await instance.prisma.$disconnect()
       instance.log.info('Prisma client disconnected.')
     })
   }
   
   module.exports = fp(prismaPlugin)
   
   • Why fastify-plugin? Ensures the plugin is loaded correctly and decorators (fastify.prisma) are available globally.
   • Why onClose hook? Ensures the database connection is closed cleanly when the server shuts down.

4. Create Subscriber Service (src/services/subscriberService.js): This service encapsulates the logic for interacting with the Subscriber model, now using libphonenumber-js.

   javascript

   // src/services/subscriberService.js
   'use strict'
   const { parsePhoneNumberFromString } = require('libphonenumber-js');
   
   class SubscriberService {
     constructor (prisma) {
       this.prisma = prisma
     }
   
     _validateAndFormatNumber(phoneNumber) {
         if (typeof phoneNumber !== 'string') {
             throw new Error('Phone number must be a string.');
         }
         const parsed = parsePhoneNumberFromString(phoneNumber);
         if (!parsed || !parsed.isValid()) {
           throw new Error('Invalid phone number format.');
         }
         // Store consistently in E.164 format
         return parsed.format('E.164');
     }
   
     async createSubscriber (inputPhoneNumber) {
       const formattedNumber = this._validateAndFormatNumber(inputPhoneNumber);
   
       return this.prisma.subscriber.create({
         data: {
           phoneNumber: formattedNumber,
           isOptedIn: true, // Default to opted-in on creation, confirm consent via other means
         },
       })
     }
   
     async getSubscriberById (id) {
       return this.prisma.subscriber.findUnique({ where: { id } })
     }
   
     async getSubscriberByPhoneNumber (inputPhoneNumber) {
       // Validate format before querying
       const formattedNumber = this._validateAndFormatNumber(inputPhoneNumber);
       return this.prisma.subscriber.findUnique({ where: { phoneNumber: formattedNumber } })
     }
   
     async getAllSubscribers (filterOptedIn = null) {
        const whereClause = {};
        if (filterOptedIn !== null) {
          whereClause.isOptedIn = Boolean(filterOptedIn);
        }
        return this.prisma.subscriber.findMany({
            where: whereClause,
            orderBy: { createdAt: 'desc' } // Optional: order by creation date
        });
     }
   
     async updateOptInStatus (id, isOptedIn) {
       return this.prisma.subscriber.update({
         where: { id },
         data: { isOptedIn: Boolean(isOptedIn) },
       })
     }
   
      async updateOptInStatusByPhoneNumber (inputPhoneNumber, isOptedIn) {
        const formattedNumber = this._validateAndFormatNumber(inputPhoneNumber);
   
        // Use updateMany to avoid fetching first (more efficient if number is guaranteed unique)
        // Or stick to findUnique + update if you need the subscriber object returned potentially.
        const result = await this.prisma.subscriber.updateMany({
          where: { phoneNumber: formattedNumber },
          data: { isOptedIn: Boolean(isOptedIn) },
        });
   
        if (result.count === 0) {
            throw new Error('Subscriber not found.');
        }
        // Note: updateMany doesn't return the record, just the count.
        // If you need the updated record, you'd need to query again or use findUnique + update.
        return { phoneNumber: formattedNumber, isOptedIn: Boolean(isOptedIn), updatedCount: result.count };
      }
   
     async deleteSubscriber (id) {
       return this.prisma.subscriber.delete({ where: { id } })
     }
   }
   
   module.exports = SubscriberService
   
   • Validation: Uses libphonenumber-js for robust validation and formatting to E.164 standard.

5. Create Campaign Service (src/services/campaignService.js): (No changes from original, logic remains the same)

   javascript

   // src/services/campaignService.js
   'use strict'
   
   class CampaignService {
     constructor (prisma) {
       this.prisma = prisma
     }
   
     async createCampaign (name, messageBody) {
       if (!name || !messageBody) {
         throw new Error('Campaign name and message body are required.')
       }
       return this.prisma.campaign.create({
         data: {
           name,
           messageBody,
         },
       })
     }
   
     async getCampaignById (id) {
       return this.prisma.campaign.findUnique({ where: { id } })
     }
   
     async getAllCampaigns () {
       return this.prisma.campaign.findMany({ orderBy: { createdAt: 'desc' }})
     }
   
     async markCampaignAsSent (id) {
       return this.prisma.campaign.update({
         where: { id },
         data: { sentAt: new Date() },
       })
     }
   
      async deleteCampaign (id) {
        // Consider implications: Should deleting prevent sending history?
        // Maybe add a 'deletedAt' field instead (soft delete).
        return this.prisma.campaign.delete({ where: { id } });
      }
   }
   
   module.exports = CampaignService
   

These services provide a clean abstraction layer over the database operations. We'll use them in our API routes next.

3. Building a Complete API Layer

Now, let's expose our services through Fastify routes with proper request validation.

1. Subscriber Routes (src/routes/subscribers.js):

   javascript

   // src/routes/subscribers.js
   'use strict'
   
   const SubscriberService = require('../services/subscriberService')
   
   // Validation Schemas
   const createSubscriberSchema = {
     body: {
       type: 'object',
       required: ['phoneNumber'],
       properties: {
         // Use a broader string type here; service layer handles validation/formatting
         phoneNumber: { type: 'string', description: 'Phone number, preferably in E.164 format (e.g., +15551234567)' },
       },
     },
     response: {
       201: { $ref: 'subscriber#' } // Reference shared schema
     }
   }
   
   const updateOptInSchema = {
      params: {
        type: 'object',
        required: ['id'],
        properties: { id: { type: 'string', format: 'cuid' } } // Add format hint if using CUIDs
      },
     body: {
       type: 'object',
       required: ['isOptedIn'],
       properties: {
         isOptedIn: { type: 'boolean' },
       },
     },
      response: {
        200: { $ref: 'subscriber#' }
      }
   }
   
    const subscriberParamsSchema = {
      params: {
        type: 'object',
        required: ['id'],
        properties: { id: { type: 'string', format: 'cuid' } }
      }
    }
   
   const listSubscribersSchema = {
      querystring: {
        type: 'object',
        properties: {
          optedIn: { type: 'boolean' }
        }
      },
      response: {
        200: {
          type: 'array',
          items: { $ref: 'subscriber#' }
        }
      }
    }
   
   
   module.exports = async function (fastify, opts) {
     // Instantiate service with Prisma client from fastify instance
     const subscriberService = new SubscriberService(fastify.prisma)
   
     // Shared Schema for Subscriber response
     fastify.addSchema({
        $id: 'subscriber',
        type: 'object',
        properties: {
          id: { type: 'string', format: 'cuid' },
          phoneNumber: { type: 'string', format: 'e164' }, // Indicate E.164 format
          isOptedIn: { type: 'boolean' },
          createdAt: { type: 'string', format: 'date-time' },
          updatedAt: { type: 'string', format: 'date-time' }
        }
     })
   
     // --- Routes ---
   
     // POST /api/v1/subscribers - Create a new subscriber
     fastify.post('/', { schema: createSubscriberSchema }, async (request, reply) => {
       try {
         const { phoneNumber } = request.body
         // Service layer now handles validation and checks for duplicates based on formatted number
         const subscriber = await subscriberService.createSubscriber(phoneNumber)
         return reply.code(201).send(subscriber)
       } catch (err) {
         request.log.error({ err }, 'Failed to create subscriber')
         if (err.message.includes('Invalid phone number')) {
             return reply.badRequest(err.message);
         }
         // Handle Prisma unique constraint error (P2002)
         if (err.code === 'P2002' && err.meta?.target?.includes('phoneNumber')) {
            // Extract the formatted number from the error if possible, or use input
            // This requires knowing the exact error structure or re-validating
            return reply.conflict(`Subscriber with phone number already exists.`);
         }
         throw fastify.httpErrors.internalServerError('Could not create subscriber.')
       }
     })
   
     // GET /api/v1/subscribers - List subscribers (optionally filter by optedIn status)
      fastify.get('/', { schema: listSubscribersSchema }, async (request, reply) => {
        try {
          const { optedIn } = request.query; // optedIn will be true, false, or undefined
          const filter = optedIn === undefined ? null : optedIn;
          const subscribers = await subscriberService.getAllSubscribers(filter);
          return subscribers;
        } catch (err) {
          request.log.error({ err }, 'Failed to retrieve subscribers');
          throw fastify.httpErrors.internalServerError('Could not retrieve subscribers.');
        }
      });
   
   
     // GET /api/v1/subscribers/:id - Get a specific subscriber
     fastify.get('/:id', { schema: { params: subscriberParamsSchema.params, response: { 200: { $ref: 'subscriber#'}} }}, async (request, reply) => {
        try {
          const { id } = request.params;
          const subscriber = await subscriberService.getSubscriberById(id);
          if (!subscriber) {
            throw fastify.httpErrors.notFound('Subscriber not found.');
          }
          return subscriber;
        } catch (err) {
            if (err.statusCode === 404) throw err; // Re-throw not found errors
            request.log.error({ err, subscriberId: request.params.id }, 'Failed to retrieve subscriber');
            throw fastify.httpErrors.internalServerError('Could not retrieve subscriber.');
        }
      });
   
   
     // PUT /api/v1/subscribers/:id/optin - Update opt-in status
     fastify.put('/:id/optin', { schema: updateOptInSchema }, async (request, reply) => {
       try {
         const { id } = request.params
         const { isOptedIn } = request.body
         const subscriber = await subscriberService.updateOptInStatus(id, isOptedIn)
         return subscriber
       } catch (err) {
          request.log.error({ err, subscriberId: request.params.id }, 'Failed to update subscriber opt-in status');
          if (err.code === 'P2025') { // Prisma record not found error
              throw fastify.httpErrors.notFound('Subscriber not found.');
          }
          throw fastify.httpErrors.internalServerError('Could not update subscriber.');
       }
     })
   
     // DELETE /api/v1/subscribers/:id - Delete a subscriber
     fastify.delete('/:id', { schema: { params: subscriberParamsSchema.params, response: { 204: {} } }}, async (request, reply) => {
        try {
          const { id } = request.params;
          await subscriberService.deleteSubscriber(id);
          return reply.code(204).send(); // No Content
        } catch (err) {
          request.log.error({ err, subscriberId: request.params.id }, 'Failed to delete subscriber');
           if (err.code === 'P2025') { // Prisma record not found error
               throw fastify.httpErrors.notFound('Subscriber not found.');
           }
          throw fastify.httpErrors.internalServerError('Could not delete subscriber.');
        }
      });
   
   }
   
   • Schema Validation: Updated schema to accept a broader string for phoneNumber at the API layer, relying on the service layer for E.164 validation and formatting. Added format hints for CUID and E.164.
   • Error Handling: Adjusted error handling for unique constraints, acknowledging that the service layer handles validation.

2. Campaign Routes (src/routes/campaigns.js): (Schema and basic CRUD routes remain similar, focus on the /send endpoint)

   javascript

   // src/routes/campaigns.js
   'use strict'
   
   const CampaignService = require('../services/campaignService')
   const SubscriberService = require('../services/subscriberService');
   const PlivoService = require('../services/plivoService');
   
   
   // Validation Schemas
   const createCampaignSchema = {
     body: {
       type: 'object',
       required: ['name', 'messageBody'],
       properties: {
         name: { type: 'string', minLength: 1 },
         messageBody: { type: 'string', minLength: 1, maxLength: 1600 }, // Consider SMS limits
       },
     },
     response: {
       201: { $ref: 'campaign#' }
     }
   }
   
   const campaignParamsSchema = {
      params: {
        type: 'object',
        required: ['id'],
        properties: { id: { type: 'string', format: 'cuid' } }
      }
    }
   
   const listCampaignsSchema = {
      response: {
        200: {
          type: 'array',
          items: { $ref: 'campaign#' }
        }
      }
    }
   
    // Updated response for /send to reflect async nature (even if underlying code is sync for demo)
    const sendCampaignSchema = {
      params: campaignParamsSchema.params,
      response: {
        202: { // Use 202 Accepted for async operations
          type: 'object',
          properties: {
            message: { type: 'string' },
            campaignId: { type: 'string' },
            status: { type: 'string', enum: ['queued', 'processing_sync'] }, // Indicate sync processing for this demo version
            estimated_subscribers: { type: 'integer' }
          }
        }
      }
    }
   
   module.exports = async function (fastify, opts) {
     const campaignService = new CampaignService(fastify.prisma)
     const subscriberService = new SubscriberService(fastify.prisma);
      // Pass Plivo client, sender number, and logger to PlivoService