Developer guide: Building a Node.js SMS scheduling and reminder service with Vonage

+---------+       +-----------------+       +-----------------+       +--------+       +------+
|  User   | ----> |   Express API   | ----> | Reminder Logic  | ----> | Vonage | ----> | SMS  |
| (Admin) |       | (POST /schedule)|       | (setTimeout/DB) |       |  API   |       | User |
+---------+       +-----------------+       +-----------------+       +--------+       +------+
     |                     ^                                              |
     | GET /reminders/:id  |                                              |
     | DELETE /reminders/:id|                                              |
     +---------------------+----------------------------------------------+

// src/vonageClient.js
const { Vonage } = require('@vonage/server-sdk');
const { Auth } = require('@vonage/auth');
const fs = require('fs'); // Needed to check private key path
require('dotenv').config(); // Load environment variables

// --- Input Validation ---
// Basic check to ensure required environment variables are set
const requiredEnvVars = [
    'VONAGE_API_KEY',
    'VONAGE_API_SECRET',
    'VONAGE_APPLICATION_ID',
    'VONAGE_PRIVATE_KEY_PATH',
    'VONAGE_NUMBER'
];

let hasError = false;
for (const envVar of requiredEnvVars) {
    if (!process.env[envVar]) {
        console.error(`Error: Missing required environment variable ${envVar}. Please check your .env file.`);
        hasError = true;
    }
}

// Check if private key file exists
if (process.env.VONAGE_PRIVATE_KEY_PATH && !fs.existsSync(process.env.VONAGE_PRIVATE_KEY_PATH)) {
    console.error(`Error: Private key file not found at path: ${process.env.VONAGE_PRIVATE_KEY_PATH}`);
    hasError = true;
}

if (hasError) {
    process.exit(1); // Exit if critical config is missing or invalid
}


// --- Vonage Authentication ---
// Use Application ID and Private Key for authentication with Messages API
// The Vonage SDK requires API Key/Secret for basic instantiation, even if subsequent calls
// like Messages API primarily use Application ID/Private Key for JWT generation.
const credentials = new Auth({
    apiKey: process.env.VONAGE_API_KEY,
    apiSecret: process.env.VONAGE_API_SECRET,
    applicationId: process.env.VONAGE_APPLICATION_ID,
    privateKey: process.env.VONAGE_PRIVATE_KEY_PATH,
});

// --- Vonage Client Initialization ---
const vonage = new Vonage(credentials);

// --- SMS Sending Function ---
/**
 * Sends an SMS message using the Vonage Messages API.
 * @param {string} to - The recipient phone number (E.164 format).
 * @param {string} text - The message content.
 * @returns {Promise<string&gt;} - Resolves with the message UUID on success.
 * @throws {Error} - Rejects with an error if sending fails.
 */
async function sendSms(to, text) {
    const fromNumber = process.env.VONAGE_NUMBER;
    console.log(`Attempting to send SMS from ${fromNumber} to ${to}`);

    try {
        const resp = await vonage.messages.send({
            message_type: ""text"",
            text: text,
            to: to,
            from: fromNumber,
            channel: ""sms""
        });
        console.log(`SMS sent successfully to ${to}. Message UUID: ${resp.message_uuid}`);
        return resp.message_uuid;
    } catch (err) {
        console.error(`Error sending SMS to ${to}:`, err.response ? err.response.data : err.message);
        // Rethrow a more specific error or handle as needed
        throw new Error(`Failed to send SMS via Vonage: ${err.message}`);
    }
}

module.exports = {
    sendSms,
    vonage // Exporting vonage instance might be useful for other API calls
};

// src/scheduler.js
const { sendSms } = require('./vonageClient');
const { v4: uuidv4 } = require('uuid'); // Use uuid for unique IDs

// --- In-Memory Storage for Pending Reminders ---
// WARNING: This is NOT persistent. If the server restarts, pending reminders are lost.
// A database (see Section 5) is strongly recommended for reliability.
const pendingReminders = new Map(); // Map<reminderId_ { timeoutId: NodeJS.Timeout_ recipient: string_ message: string_ sendAt: Date_ status: string }&gt;

/**
 * Schedules an SMS reminder using in-memory storage.
 * @param {string} recipient - Recipient phone number (E.164 format).
 * @param {string} message - Message content.
 * @param {Date} sendAtDate - The Date object representing when to send the message.
 * @returns {string} The unique ID of the scheduled reminder.
 * @throws {Error} If scheduling fails (e.g., time is in the past).
 */
function scheduleReminder(recipient, message, sendAtDate) {
    const now = new Date();
    const delay = sendAtDate.getTime() - now.getTime();

    if (delay &lt;= 0) {
        throw new Error("Scheduled time must be in the future.");
    }

    // Limit delay to avoid issues with extremely long timeouts (optional)
    // const maxDelay = 2147483647; // Max 32-bit integer (~24.8 days)
    // if (delay &gt; maxDelay) {
    //     throw new Error(`Scheduling delay too long (max ~24.8 days). Consider using a persistent job queue for longer schedules.`);
    // }

    const reminderId = uuidv4(); // Generate a unique ID

    console.log(`Scheduling reminder ${reminderId} for ${recipient} at ${sendAtDate.toISOString()} (in ${delay}ms)`);

    const timeoutId = setTimeout(async () =&gt; {
        console.log(`Executing reminder ${reminderId} for ${recipient}`);
        const reminder = pendingReminders.get(reminderId); // Get latest state

        if (!reminder || reminder.status !== 'pending') {
            console.warn(`Reminder ${reminderId} execution skipped: No longer pending (status: ${reminder?.status})`);
            pendingReminders.delete(reminderId); // Clean up if somehow still present
            return;
        }

        try {
            const messageUuid = await sendSms(recipient, message);
            console.log(`Reminder ${reminderId} sent successfully. Vonage Message ID: ${messageUuid}`);
            // Update status in memory
            pendingReminders.set(reminderId, { ...reminder, status: 'sent', vonageMessageId: messageUuid });
            // Optionally update status in DB here if using persistence
        } catch (error) {
            console.error(`Failed to send reminder ${reminderId}:`, error);
            // Update status in memory
            pendingReminders.set(reminderId, { ...reminder, status: 'failed' });
            // Optionally update status in DB here (e.g., 'failed')
        } finally {
            // Remove from active map *after* processing (sent or failed) for status query purposes
            // Or keep it with final status, depending on requirements for getReminderStatus
            // For this simple version, let's keep the final status available for a while.
            // A cleanup mechanism might be needed for long-running servers.
            console.log(`Reminder ${reminderId} processed. Final status: ${pendingReminders.get(reminderId)?.status}`);
        }
    }, delay);

    // Store reminder details and the timeout handle
    pendingReminders.set(reminderId, {
        timeoutId,
        recipient,
        message,
        sendAt: sendAtDate,
        status: 'pending' // Initial status
    });

    return reminderId;
}

/**
 * Cancels a pending reminder (in-memory version).
 * @param {string} reminderId - The ID of the reminder to cancel.
 * @returns {boolean} True if cancelled successfully, false otherwise (e.g., not found or already processed).
 */
function cancelReminder(reminderId) {
    const reminder = pendingReminders.get(reminderId);
    if (reminder && reminder.status === 'pending') {
        clearTimeout(reminder.timeoutId); // Clear the scheduled timeout
        // Update status in memory
        pendingReminders.set(reminderId, { ...reminder, status: 'cancelled' });
        console.log(`Cancelled reminder ${reminderId}`);
        // Optionally update status in DB here
        return true;
    }
    console.log(`Reminder ${reminderId} not found or cannot be cancelled (status: ${reminder?.status}).`);
    return false;
}

/**
 * Gets the details of a reminder (pending, sent, failed, cancelled) from memory.
 * @param {string} reminderId - The ID of the reminder.
 * @returns {object | undefined} Reminder details (excluding timeoutId) or undefined if not found.
 */
function getReminderStatus(reminderId) {
    const reminder = pendingReminders.get(reminderId);
    if(reminder) {
        // Return a copy without the internal timeoutId
        const { timeoutId, ...details } = reminder;
        return details;
    }
    return undefined;
}


module.exports = {
    scheduleReminder,
    cancelReminder,
    getReminderStatus,
};

// src/routes/reminderRoutes.js
const express = require('express');
const { scheduleReminder, cancelReminder, getReminderStatus } = require('../scheduler');
// Optional: Input validation library
// const { body, param, validationResult } = require('express-validator');

const router = express.Router();

// --- Middleware for Basic Input Validation (Example) ---
// For production applications, using a dedicated validation library like express-validator
// is highly recommended for more robust and maintainable validation.
// This example shows basic manual validation.
const validateScheduleRequest = (req, res, next) => {
    const { recipient, message, sendAt } = req.body;
    if (!recipient || !message || !sendAt) {
        return res.status(400).json({ error: 'Missing required fields: recipient, message, sendAt' });
    }
    // Basic phone number format check (E.164 recommended)
    if (!/^\+?[1-9]\d{1,14}$/.test(recipient)) {
         return res.status(400).json({ error: 'Invalid recipient phone number format (should be E.164, e.g., +14155550100)' });
    }
    // Check if sendAt is a valid date string parseable by new Date()
    const sendAtDate = new Date(sendAt);
    if (isNaN(sendAtDate.getTime())) {
        // More specific check for ISO 8601 format might be desired
        return res.status(400).json({ error: 'Invalid sendAt format. Use a valid date string (ISO 8601 recommended, e.g., 2025-12-31T23:59:59.000Z)' });
    }
    // Attach parsed date to request object for handler use
    req.sendAtDate = sendAtDate;
    next();
};

// --- API Endpoints ---

// POST /api/reminders - Schedule a new reminder
router.post('/', validateScheduleRequest, (req, res, next) => {
    const { recipient, message } = req.body;
    const { sendAtDate } = req; // Get parsed date from validation middleware

    try {
        const reminderId = scheduleReminder(recipient, message, sendAtDate);
        res.status(202).json({
            message: ""Reminder scheduled successfully."",
            reminderId: reminderId,
            details: {
                recipient: recipient,
                message: message,
                sendAt: sendAtDate.toISOString() // Return consistent ISO string format
            }
        });
    } catch (error) {
        // Handle specific scheduling errors like ""time in the past""
        if (error.message.includes(""future"")) {
            return res.status(400).json({ error: error.message });
        }
        // Pass other errors (e.g., from uuid, setTimeout setup) to the central error handler
        next(error);
    }
});

// GET /api/reminders/:id - Get status of a specific reminder
router.get('/:id', async (req, res, next) => { // Mark as async if DB check is added
    const { id } = req.params;
    try {
        const reminder = getReminderStatus(id); // Check in-memory store first

        if (reminder) {
            res.status(200).json(reminder);
        } else {
            // Optional: If using DB persistence, check the database here
            // const dbReminder = await findReminderInDb(id); // Assuming findReminderInDb exists
            // if (dbReminder) {
            //     // Map DB fields to the expected response structure if needed
            //     return res.status(200).json(dbReminder);
            // }
            res.status(404).json({ error: `Reminder with ID ${id} not found.` });
        }
    } catch (error) {
        next(error); // Pass DB errors etc. to central handler
    }
});

// DELETE /api/reminders/:id - Cancel a pending reminder
router.delete('/:id', (req, res, next) => {
    const { id } = req.params;
    try {
        const cancelled = cancelReminder(id);
        if (cancelled) {
            res.status(200).json({ message: `Reminder ${id} cancelled successfully.` });
        } else {
            // Could be not found, or already sent/failed/cancelled
            // Check current status to provide a more specific message if needed
            const currentStatus = getReminderStatus(id)?.status;
            if (currentStatus) {
                 res.status(400).json({ error: `Reminder ${id} cannot be cancelled (current status: ${currentStatus}).` });
            } else {
                 res.status(404).json({ error: `Reminder with ID ${id} not found.` });
            }
            // Or simply keep the 404 for ""not found or cannot be cancelled now""
            // res.status(404).json({ error: `Reminder with ID ${id} not found or cannot be cancelled.` });
        }
    } catch (error) {
        next(error); // Pass errors to central handler
    }
});

module.exports = router;

// server.js
require('dotenv').config(); // Ensure env vars are loaded first
const express = require('express');
const reminderRoutes = require('./src/routes/reminderRoutes');
// Optional: Database initialization and rescheduling logic
// const { initializeDatabase, getPendingRemindersFromDb } = require('./src/database');
// const { loadReminderIntoMemory } = require('./src/scheduler'); // Need this if rescheduling from DB

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 Logging Middleware ---
app.use((req, res, next) => {
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
    next();
});

// --- Optional Simple API Key Auth Middleware ---
// Uncomment and configure INTERNAL_API_KEY in .env to use
/*
const API_KEY = process.env.INTERNAL_API_KEY;
function authenticateKey(req, res, next) {
    const providedKey = req.headers['x-api-key'];
    if (!API_KEY) {
        console.warn(""Warning: INTERNAL_API_KEY not set, skipping API authentication."");
        return next(); // Skip auth if no key configured (for dev/testing)
    }
    if (providedKey && providedKey === API_KEY) {
        next(); // Key is valid
    } else {
        res.status(401).json({ error: 'Unauthorized: Invalid or missing API Key in X-API-Key header' });
    }
}
// Apply authentication to reminder routes
app.use('/api/reminders', authenticateKey, reminderRoutes);
*/

// --- Routes ---
// Apply reminder routes (without auth middleware if commented out above)
app.use('/api/reminders', reminderRoutes);

app.get('/', (req, res) => {
    res.send('SMS Reminder Service is running!');
});


// --- 404 Handler ---
// Handles requests that don't match any routes defined above
app.use((req, res, next) => {
    res.status(404).json({ error: 'Not Found' });
});

// --- Central Error Handler ---
// Must be defined last, after all routes and other middleware.
// Catches errors passed via next(error).
// eslint-disable-next-line no-unused-vars
app.use((err, req, res, next) => {
    console.error(""Unhandled Error:"", err.stack || err.message); // Log the full error stack

    // Respond with a generic 500 error in production
    // Avoid leaking detailed error information
    res.status(err.status || 500).json({ // Use error status if available, otherwise 500
        error: 'Internal Server Error',
        // message: process.env.NODE_ENV === 'development' ? err.message : undefined // Optionally show details in dev
    });
});

// --- Start Server ---
async function startServer() {
    try {
        // Optional: Initialize Database and Reschedule Tasks
        /*
        await initializeDatabase();
        console.log(""Database initialized successfully."");

        // Reschedule pending tasks from DB on startup
        console.log(""Checking for pending reminders in DB to reschedule..."");
        const pendingDbReminders = await getPendingRemindersFromDb(); // Fetch pending tasks
        let rescheduledCount = 0;
        for (const reminder of pendingDbReminders) {
            try {
                const sendAtDate = new Date(reminder.sendAt);
                if (sendAtDate > new Date()) { // Only reschedule if time is still in the future
                    console.log(`Rescheduling reminder from DB: ${reminder.id} for ${sendAtDate.toISOString()}`);
                    // --- Requires modification in scheduler.js ---
                    // Need a function like 'loadReminderIntoMemory' that creates the timeout
                    // based on DB data without re-inserting into DB, and populates an
                    // in-memory map of active timeouts (e.g., activeTimeouts<id_ timeoutId&gt;).
                    loadReminderIntoMemory(reminder.id, reminder.recipient, reminder.message, sendAtDate);
                    rescheduledCount++;
                } else {
                    console.warn(`Reminder ${reminder.id} from DB has past send time (${reminder.sendAt}), marking as missed.`);
                    // Optionally update DB status to 'missed' or 'failed_startup'
                    // await updateReminderStatusInDb(reminder.id, 'missed');
                }
            } catch (error) {
                console.error(`Failed to reschedule reminder ${reminder.id} from DB:`, error);
            }
        }
        console.log(`Rescheduled ${rescheduledCount} pending reminders from the database.`);
        */

        // Start listening for HTTP requests
        app.listen(PORT, () =&gt; {
            console.log(`Server listening on port ${PORT}`);
            console.log(`API endpoints available at http://localhost:${PORT}/api/reminders`);
            console.log(`Current server time: ${new Date().toISOString()} (Ensure server timezone is correct, preferably UTC)`);
        });

    } catch (error) {
        console.error(""Failed to start server:"", error);
        process.exit(1);
    }
}

startServer();

// src/database.js
const sqlite3 = require('sqlite3').verbose(); // Use verbose for detailed logs during dev
require('dotenv').config();

const dbPath = process.env.DATABASE_PATH || './data/reminders.db'; // Default path

// --- Database Connection ---
// Creates the directory and file if they don't exist
const dbDir = require('path').dirname(dbPath);
if (!require('fs').existsSync(dbDir)) {
    require('fs').mkdirSync(dbDir, { recursive: true });
}

const db = new sqlite3.Database(dbPath, (err) => {
    if (err) {
        console.error("Error connecting to SQLite database:", err.message);
        throw err; // Fail fast if DB connection fails
    }
    console.log(`Connected to SQLite database at ${dbPath}`);
});

// --- Database Initialization (Schema Setup) ---
/**
 * Creates the reminders table if it doesn't exist.
 * Should be called once on server startup.
 */
function initializeDatabase() {
    return new Promise((resolve, reject) => {
        const sql = `
            CREATE TABLE IF NOT EXISTS reminders (
                id TEXT PRIMARY KEY,            -- Unique reminder ID (UUID)
                recipient TEXT NOT NULL,        -- E.164 phone number
                message TEXT NOT NULL,
                sendAt TEXT NOT NULL,           -- ISO 8601 timestamp string (UTC recommended)
                status TEXT NOT NULL DEFAULT 'pending', -- 'pending', 'sent', 'failed', 'cancelled', 'missed'
                createdAt TEXT NOT NULL,        -- ISO 8601 timestamp string
                updatedAt TEXT NOT NULL,        -- ISO 8601 timestamp string
                vonageMessageId TEXT            -- Store Vonage message UUID after sending
            );
        `;
        db.run(sql, (err) => {
            if (err) {
                console.error("Error creating reminders table:", err.message);
                return reject(err);
            }
            console.log("Reminders table checked/created successfully.");
            resolve();
        });
    });
}

// --- Database Operations ---