+-----------------+      +---------------------+      +----------------+      +-----------------+
|   API Client    |----->|  Node.js/Express  |----->|  Prisma Client |----->|    Database     |
| (e.g., Postman) |      |      API Layer      |      |  (Data Access) |      | (e.g., SQLite)  |
+-----------------+      +----------+----------+      +----------------+      +-----------------+
                             |
                             | (Vonage SDK)
                             v
                       +-----------------+
                       | Vonage Messages |
                       |       API       |
                       +-----------------+
                             |
                             v
                       +-----------------+
                       | SMS Recipient   |
                       +-----------------+

mkdir vonage-sms-campaigner
cd vonage-sms-campaigner

npm init -y

npm install express @vonage/server-sdk @prisma/client dotenv
npm install prisma --save-dev

npx prisma init --datasource-provider sqlite

vonage-sms-campaigner/
├── prisma/
│   ├── schema.prisma
│   └── dev.db        # (Will be created by Prisma)
├── src/
│   ├── controllers/
│   │   └── campaignController.js
│   ├── services/
│   │   ├── vonageService.js
│   │   └── campaignService.js
│   ├── middleware/    # (Add this for Step 7)
│   │   └── rateLimiter.js
│   ├── routes/
│   │   └── campaignRoutes.js
│   └── server.js
├── .env              # For environment variables (DO NOT COMMIT)
├── .gitignore
└── package.json

# Dependencies
node_modules/

# Prisma
prisma/dev.db
prisma/dev.db-journal

# Environment Variables
.env*

# Build Outputs (if applicable)
dist/
build/

# OS files
.DS_Store
Thumbs.db

# Vonage Private Key
private.key
*.key

// src/server.js
require('dotenv').config(); // Load .env variables first
const express = require('express');
const campaignRoutes = require('./routes/campaignRoutes');

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware
app.use(express.json()); // Parse JSON request bodies
app.use(express.urlencoded({ extended: true })); // Parse URL-encoded bodies

// Basic Root Route
app.get('/', (req, res) => {
  res.send('Vonage SMS Campaigner API is running!');
});

// API Routes
app.use('/api/campaigns', campaignRoutes);

// Simple Error Handling Middleware (Will be enhanced in Step 5)
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send({ error: 'Something went wrong!' });
});


app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

# .env
# Database Configuration (Prisma default)
DATABASE_URL="file:./prisma/dev.db"

# Server Port
PORT=3000

# Vonage Credentials (Add these later in Step 4)
VONAGE_APPLICATION_ID=YOUR_VONAGE_APP_ID_FROM_DASHBOARD # Replace with actual ID
VONAGE_PRIVATE_KEY_PATH=./private.key                   # Path relative to project root where you save the key
VONAGE_NUMBER=YOUR_VONAGE_VIRTUAL_NUMBER_E164           # Replace with actual Vonage number (e.g., +12015550123)

// src/services/vonageService.js
const { Vonage } = require('@vonage/server-sdk');
const path = require('path');
const fs = require('fs'); // Needed to check if key file exists

// Resolve path from the current working directory where Node is started
const privateKeyPath = process.env.VONAGE_PRIVATE_KEY_PATH
    ? path.resolve(process.cwd(), process.env.VONAGE_PRIVATE_KEY_PATH)
    : null;

if (!privateKeyPath || !fs.existsSync(privateKeyPath)) {
    console.error(`Error: Vonage private key file not found at path specified by VONAGE_PRIVATE_KEY_PATH: ${process.env.VONAGE_PRIVATE_KEY_PATH}`);
    // Optionally exit or handle appropriately
    // process.exit(1);
}

const vonage = new Vonage({
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: privateKeyPath, // Use the resolved absolute path
});

const fromNumber = process.env.VONAGE_NUMBER;

/**
 * Sends a single SMS message using the Vonage Messages API.
 * @param {string} to - The recipient's phone number (E.164 format recommended).
 * @param {string} text - The message content.
 * @returns {Promise<object&gt;} - Promise resolving with the Vonage API response.
 * @throws {Error} - Throws an error if sending fails.
 */
async function sendSms(to, text) {
  if (!to || !text) {
    throw new Error('Recipient phone number and message text are required.');
  }
  if (!process.env.VONAGE_APPLICATION_ID || !privateKeyPath || !fromNumber) {
      throw new Error('Vonage credentials (Application ID, Private Key Path, Number) are missing or invalid in .env');
  }

  console.log(`Attempting to send SMS from ${fromNumber} to ${to}`);

  try {
    // Use standard double quotes for JSON string values
    const resp = await vonage.messages.send({
      message_type: ""text"",
      text: text,
      to: to,
      from: fromNumber,
      channel: ""sms""
    });
    console.log(`Message sent successfully to ${to}: ${resp.message_uuid}`);
    return resp; // Contains message_uuid
  } catch (err) {
    // Log more detailed Vonage error if available
    const errorMessage = err.response?.data?.title || err.response?.data?.detail || err.message || 'Unknown Vonage error';
    const errorStatus = err.response?.status || 'N/A';
    console.error(`Error sending SMS to ${to}: Status ${errorStatus} - ${errorMessage}`);
    // Rethrow a more informative error
    throw new Error(`Failed to send SMS to ${to}. Vonage API Error: ${errorMessage} (Status: ${errorStatus})`);
  }
}

module.exports = { sendSms };

// src/services/campaignService.js
const { PrismaClient } = require('@prisma/client');
const { sendSms } = require('./vonageService');

const prisma = new PrismaClient();

/**
 * Sends an SMS campaign to a list of recipients.
 * @param {string[]} recipientNumbers - Array of phone numbers (E.164 format recommended).
 * @param {string} message - The message text to send.
 * @returns {Promise<object&gt;} - Promise resolving with results (successes, failures).
 */
async function sendCampaign(recipientNumbers, message) {
  if (!Array.isArray(recipientNumbers) || recipientNumbers.length === 0) {
    throw new Error('Recipient numbers must be a non-empty array.');
  }
  if (!message) {
    throw new Error('Message text cannot be empty.');
  }

  const results = {
    successes: [],
    failures: [],
  };

  // Sequentially send messages to avoid overwhelming the API rate limits initially
  // For higher volume, consider batching or parallel requests with delays & proper rate limiting
  for (const number of recipientNumbers) {
    try {
      // Basic E.164 format check (can be improved with regex)
      if (!/^\+[1-9]\d{1,14}$/.test(number)) {
          throw new Error(`Invalid phone number format: ${number}. Must be E.164 (e.g., +14155552671).`);
      }
      const response = await sendSms(number, message);
      results.successes.push({ number: number, message_uuid: response.message_uuid });
      // Optional: Add a small delay between sends if hitting rate limits
      // await new Promise(resolve =&gt; setTimeout(resolve, 200)); // 200ms delay
    } catch (error) {
      console.error(`Failed processing number ${number}: ${error.message}`);
      results.failures.push({ number: number, error: error.message });
    }
  }

  console.log(`Campaign finished. Success: ${results.successes.length}, Failures: ${results.failures.length}`);
  return results;
}

// --- Example of fetching recipients from DB (Requires Schema Update - See Step 6) ---
/**
 * Sends an SMS campaign to recipients belonging to a specific group.
 * @param {number} recipientGroupId - The ID of the RecipientGroup.
 * @param {string} message - The message text to send.
 * @returns {Promise<object&gt;} - Promise resolving with results (successes, failures).
 */
async function sendCampaignToGroup(recipientGroupId, message) {
    const groupWithRecipients = await prisma.recipientGroup.findUnique({
        where: { id: recipientGroupId },
        include: {
            recipients: { // Only include recipients who haven't opted out
                where: { isOptedOut: { not: true } } // Requires 'isOptedOut' field in schema (Step 8)
            }
        },
    });

    if (!groupWithRecipients) {
        throw new Error(`Recipient group with ID ${recipientGroupId} not found.`);
    }

    const recipientNumbers = groupWithRecipients.recipients.map(r =&gt; r.phoneNumber);

    if (recipientNumbers.length === 0) {
        console.warn(`Recipient group ${recipientGroupId} has no active recipients.`);
        return { successes: [], failures: [] };
    }

    return sendCampaign(recipientNumbers, message);
}


module.exports = { sendCampaign, sendCampaignToGroup }; // Export both functions

// src/controllers/campaignController.js
const { sendCampaign, sendCampaignToGroup } = require('../services/campaignService');

/**
 * POST /api/campaigns/send
 * Sends a campaign to a provided list of numbers.
 * Request body example: { "recipientNumbers": ["+15551234567", "+447700900123"], "message": "Hello!" }
 */
async function handleSendCampaign(req, res, next) {
  const { recipientNumbers, message } = req.body;

  // Basic Validation
  if (!Array.isArray(recipientNumbers) || recipientNumbers.length === 0 || typeof message !== 'string' || message.trim() === '') {
    return res.status(400).json({
      error: 'Invalid input. Requires "recipientNumbers" (non-empty array of strings) and "message" (non-empty string).',
    });
  }

  // Further validation (e.g., check number format within the service or here)

  try {
    const results = await sendCampaign(recipientNumbers, message);
    res.status(200).json({
      message: 'Campaign processing completed.', // Changed from "initiated" as it's sequential for now
      results: results,
    });
  } catch (error) {
    console.error('Error in handleSendCampaign:', error);
    // Pass to the centralized error handler
    next(error);
  }
}

/**
 * POST /api/campaigns/send-group
 * Sends a campaign to recipients of a specific group ID.
 * Request body example: { "recipientGroupId": 1, "message": "Group message!" }
 */
async function handleSendCampaignToGroup(req, res, next) {
    const { recipientGroupId, message } = req.body;

    // Basic Validation
    const groupId = parseInt(recipientGroupId, 10);
    if (isNaN(groupId) || typeof message !== 'string' || message.trim() === '') {
        return res.status(400).json({
            error: 'Invalid input. Requires "recipientGroupId" (number) and "message" (non-empty string).',
        });
    }

    try {
        const results = await sendCampaignToGroup(groupId, message);
        res.status(200).json({
            message: `Campaign processing completed for group ${groupId}.`, // Changed from "initiated"
            results: results,
        });
    } catch (error) {
        console.error('Error in handleSendCampaignToGroup:', error);
        // Handle specific errors like "group not found" differently if needed
        if (error.message.includes('not found')) {
             return res.status(404).json({ error: error.message });
        }
        // Pass other errors to the centralized handler
        next(error);
    }
}


module.exports = { handleSendCampaign, handleSendCampaignToGroup };

// src/routes/campaignRoutes.js
const express = require('express');
const { handleSendCampaign, handleSendCampaignToGroup } = require('../controllers/campaignController');
// Rate limiting middleware will be introduced and implemented in Step 7
const rateLimiter = require('../middleware/rateLimiter');

const router = express.Router();

// WARNING: These endpoints are currently PUBLIC. Add authentication middleware for production.
// Apply rate limiting (introduced in Step 7) to campaign sending endpoints
router.post('/send', rateLimiter, handleSendCampaign);
router.post('/send-group', rateLimiter, handleSendCampaignToGroup);

// Optional: Endpoint to check basic Vonage configuration status
router.get('/status', (req, res) => {
    // Basic check: Ensure Vonage credentials seem present in environment
    if (process.env.VONAGE_APPLICATION_ID && process.env.VONAGE_PRIVATE_KEY_PATH && process.env.VONAGE_NUMBER) {
        // Further check could involve ensuring the private key file exists
        res.status(200).json({ status: 'Vonage credentials seem loaded from environment variables.'});
    } else {
        res.status(500).json({ status: 'Error: One or more required Vonage credentials missing in environment variables.' });
    }
});


module.exports = router;

# .env (Update these lines with your actual values)
# ... other variables ...

VONAGE_APPLICATION_ID=PASTE_YOUR_APPLICATION_ID_HERE # Replace with the ID from Vonage Dashboard
VONAGE_PRIVATE_KEY_PATH=./private.key                # Ensure this path is correct relative to project root
VONAGE_NUMBER=PASTE_YOUR_VONAGE_NUMBER_HERE          # Replace with your linked Vonage number in E.164 format (e.g., +14155552671)

// src/server.js (Replace the simple error handler with this)

// Remove or comment out the previous simple error handler:
// app.use((err, req, res, next) => {
//   console.error(err.stack);
//   res.status(500).send({ error: 'Something went wrong!' });
// });

// More structured error handler (Place this AFTER your routes)
app.use((err, req, res, next) => {
  // Log the error internally (replace console.error with a proper logger like Winston/Pino in production)
  console.error(`[ERROR] ${req.method} ${req.path} - ${err.message}`);
  // Log stack trace only in development or if needed for detailed debugging
  if (process.env.NODE_ENV !== 'production') {
      console.error(err.stack);
  }

  // Determine status code - check for custom status or default to 500
  // Use err.status for compatibility with some error libraries, fallback to statusCode
  const statusCode = err.status || err.statusCode || 500;

  // Send structured error response to client - avoid leaking sensitive details
  res.status(statusCode).json({
    status: 'error',
    // Only include specific error message in non-production environments for debugging
    // In production, use a generic message unless it's a specific client error (4xx) you want to expose
    message: (statusCode < 500 || process.env.NODE_ENV !== 'production') ? err.message : 'An internal server error occurred.'_
  });
});

// prisma/schema.prisma

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

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

model Recipient {
  id             Int      @id @default(autoincrement())
  phoneNumber    String   @unique // E.164 format REQUIRED
  firstName      String?
  lastName       String?
  isOptedOut     Boolean  @default(false) // For handling STOP replies
  createdAt      DateTime @default(now())
  updatedAt      DateTime @updatedAt

  // Relation to RecipientGroup (a recipient can belong to one group)
  recipientGroup   RecipientGroup? @relation(fields: [recipientGroupId], references: [id])
  recipientGroupId Int?

  @@index([recipientGroupId]) // Index for faster group lookups
}

model RecipientGroup {
  id        Int      @id @default(autoincrement())
  name      String   @unique // e.g., ""Newsletter Subscribers"", ""VIP Customers""
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  // Relation to multiple recipients
  recipients Recipient[]
}

# Create the migration files based on schema changes
# Prisma will prompt you for a name, e.g., add_recipient_models_and_optout
npx prisma migrate dev

# This command will also apply the migration to your dev database (dev.db)