Build SMS Marketing Campaigns with MessageBird, Node.js, and Fastify

+---------+      +--------------+      +---------------+      +--------------+      +------------+
|  User   |----->| Mobile Device|----->| MessageBird   |----->| Fastify App  |<-----| Admin User |
| (SMS)   |      | (SMS: JOIN/  |      | (Virtual Num) |      | (Webhook)    |      | (API Call)|
+---------+      |  STOP)       |      +-------+-------+      +-------+------+      +-----+------+
                 +--------------+              |                      |                  |
                                               | SMS Sent             | Send Campaign    |
                                               v                      v                  |
                                         +-----+------+         +-----+------+           |
                                         | Fastify App|-------->| MessageBird|-----------+
                                         | (Send Reply|         | (Send SMS) |
                                         |  /Campaign)|         +------------+
                                         +-----+------+
                                               |
                                               v
                                         +-----+------+
                                         | Database   |
                                         | (SQLite)   |
                                         +------------+

mkdir fastify-messagebird-sms
cd fastify-messagebird-sms
npm init -y

// package.json
{
  "name": "fastify-messagebird-sms",
  "version": "1.0.0",
  "description": "",
  "main": "app.js",
  "type": "module", // <-- Add this line
  "scripts": {
    "start": "node app.js"_
    "dev": "node --watch app.js"_ // Requires Node.js 18.11+ (Node.js 20+ recommended)
    "test": "echo \"Error: no test specified\" && exit 1"
  }_
  "keywords": []_
  "author": ""_
  "license": "ISC"
}

npm install fastify messagebird dotenv better-sqlite3 @fastify/rate-limit @fastify/auth

mkdir routes plugins db utils
touch app.js .env .gitignore db/schema.sql db/database.js routes/webhook.js routes/campaign.js plugins/messagebird.js plugins/db.js plugins/auth.js plugins/verify-messagebird.js utils/phoneUtils.js

# .gitignore
node_modules
.env
*.sqlite
*.sqlite-journal
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# .env

# MessageBird Credentials
MESSAGEBIRD_API_KEY=YOUR_MESSAGEBIRD_LIVE_API_KEY
MESSAGEBIRD_WEBHOOK_SIGNING_KEY=YOUR_MESSAGEBIRD_WEBHOOK_SIGNING_KEY
MESSAGEBIRD_ORIGINATOR=YOUR_MESSAGEBIRD_VIRTUAL_NUMBER_OR_ALPHANUMERIC

# Application Security
API_SECRET_KEY=GENERATE_A_STRONG_RANDOM_SECRET_KEY_HERE

# Database
DATABASE_PATH=./db/subscriptions.sqlite

# Server Configuration (Optional – Fastify defaults work well)
# HOST=0.0.0.0
# PORT=3000

// plugins/messagebird.js
import fp from 'fastify-plugin';
import { messagebird } from 'messagebird';

async function messagebirdPlugin(fastify, options) {
  const { apiKey } = options;
  if (!apiKey) {
    throw new Error('MessageBird API Key is required');
  }

  const mbClient = messagebird(apiKey);

  // Decorate fastify instance with the client
  fastify.decorate('messagebird', mbClient);
  fastify.log.info('MessageBird client initialized');
}

export default fp(messagebirdPlugin, {
  name: 'messagebird',
  dependencies: [], // No dependencies for this plugin itself
});

-- db/schema.sql

CREATE TABLE IF NOT EXISTS subscriptions (
    phone_number TEXT PRIMARY KEY NOT NULL, -- E.164 format recommended
    subscribed INTEGER DEFAULT 0, -- 1 for true, 0 for false
    subscribed_at DATETIME,
    unsubscribed_at DATETIME
);

-- Optional: Add an index for faster lookups if the table grows large
-- CREATE INDEX IF NOT EXISTS idx_subscribed ON subscriptions (subscribed);

// db/database.js
import Database from 'better-sqlite3';
import fs from 'fs';
import path from 'path';

// Helper function to ensure the directory exists
function ensureDirectoryExistence(filePath) {
  const dirname = path.dirname(filePath);
  if (fs.existsSync(dirname)) {
    return true;
  }
  ensureDirectoryExistence(dirname);
  fs.mkdirSync(dirname);
}

// --- Database Initialization ---
let db;

export function initDb(dbPath) {
  ensureDirectoryExistence(dbPath); // Make sure the db directory exists
  db = new Database(dbPath); // { verbose: console.log } // Enable verbose logging for debugging SQL
  db.pragma('journal_mode = WAL'); // Recommended for better concurrency

  // Read and execute schema file
  try {
    const schema = fs.readFileSync(path.join(path.dirname(dbPath), 'schema.sql'), 'utf8');
    db.exec(schema);
    console.log('Database schema loaded successfully.');
  } catch (err) {
    console.error('Error loading database schema:', err);
    throw err; // Rethrow to prevent application start if schema fails
  }
}

// --- Data Access Functions ---

// Add or update a subscriber, setting their status to subscribed (1)
export function addSubscriber(phoneNumber) {
  const stmt = db.prepare(`
    INSERT INTO subscriptions (phone_number, subscribed, subscribed_at, unsubscribed_at)
    VALUES (?, 1, datetime('now'), NULL)
    ON CONFLICT(phone_number) DO UPDATE SET
      subscribed = 1,
      subscribed_at = datetime('now'),
      unsubscribed_at = NULL;
  `);
  return stmt.run(phoneNumber);
}

// Mark a subscriber as unsubscribed (0)
export function removeSubscriber(phoneNumber) {
  const stmt = db.prepare(`
    UPDATE subscriptions
    SET subscribed = 0, unsubscribed_at = datetime('now')
    WHERE phone_number = ?;
  `);
  return stmt.run(phoneNumber);
}

// Check if a phone number is currently subscribed
export function isSubscribed(phoneNumber) {
  const stmt = db.prepare('SELECT subscribed FROM subscriptions WHERE phone_number = ?');
  const result = stmt.get(phoneNumber);
  return result?.subscribed === 1;
}

// Get all currently subscribed phone numbers
export function getAllSubscribers() {
  const stmt = db.prepare('SELECT phone_number FROM subscriptions WHERE subscribed = 1');
  return stmt.all().map(row => row.phone_number);
}

// Close the database connection (important for graceful shutdown)
export function closeDb() {
  if (db) {
    db.close();
    console.log('Database connection closed.');
  }
}

// plugins/db.js
import fp from 'fastify-plugin';
import { initDb, closeDb, addSubscriber, removeSubscriber, isSubscribed, getAllSubscribers } from '../db/database.js';

async function dbPlugin(fastify, options) {
  const { dbPath } = options;
  if (!dbPath) {
    throw new Error('Database path (dbPath) is required');
  }

  try {
    initDb(dbPath);
    fastify.log.info(`Database initialized at ${dbPath}`);

    // Decorate fastify with DB utility functions
    fastify.decorate('db', {
      addSubscriber,
      removeSubscriber,
      isSubscribed,
      getAllSubscribers,
    });

    // Add hook to close DB connection on server shutdown
    fastify.addHook('onClose', (instance, done) => {
      closeDb();
      done();
    });

  } catch (err) {
    fastify.log.error('Failed to initialize database:', err);
    // Propagate the error to prevent the server from starting incorrectly
    throw err;
  }
}

export default fp(dbPlugin, {
  name: 'db',
  dependencies: [], // No dependencies for this plugin itself
});

// routes/webhook.js
import { normalizePhoneNumber, isValidE164 } from '../utils/phoneUtils.js'; // We'll create this util soon

const webhookSchema = {
  // Basic validation: ensure required fields from MessageBird exist
  // For production, use a more robust JSON Schema validator
  body: {
    type: 'object',
    required: ['originator', 'payload'],
    properties: {
      originator: { type: 'string' }, // Sender's phone number
      payload: { type: 'string' },    // SMS message content
      // Add other fields you might need from the webhook payload
    },
  },
};

export default async function webhookRoutes(fastify, options) {

  // This route requires the verifyMessageBird plugin (added later)
  const routeOptions = {
    schema: webhookSchema,
    // Apply the verification middleware specifically to this route using fastify-auth
    preHandler: fastify.auth([fastify.verifyMessageBird]),
  };

  fastify.post('/messagebird', routeOptions, async (request, reply) => {
    const { originator, payload } = request.body;
    const messageContent = payload.trim().toUpperCase(); // Normalize keyword check

    let replyMessage = '';

    // Attempt to normalize the phone number
    let normalizedNumber;
    try {
      // Ensure E.164 format for consistent storage and use
      normalizedNumber = normalizePhoneNumber(originator);
      if (!normalizedNumber || !isValidE164(normalizedNumber)) {
          fastify.log.warn(`Received webhook from invalid or non-normalizable originator format: ${originator}`);
          // Don't reply to potentially spoofed/malformed numbers. Acknowledge receipt.
          return reply.code(200).send({ message: 'Originator format invalid, processing skipped.' });
      }
    } catch (error) {
        fastify.log.error({ err: error, originator }, 'Error normalizing phone number');
        // Acknowledge receipt but indicate an error occurred.
        return reply.code(200).send({ message: 'Error processing originator number.' });
    }


    try {
      if (messageContent === 'JOIN') {
        fastify.db.addSubscriber(normalizedNumber);
        fastify.log.info(`Subscriber added: ${normalizedNumber}`);
        replyMessage = 'Thanks for subscribing! Reply STOP to unsubscribe.';
      } else if (messageContent === 'STOP') {
        fastify.db.removeSubscriber(normalizedNumber);
        fastify.log.info(`Subscriber removed: ${normalizedNumber}`);
        replyMessage = 'You have been unsubscribed.';
      } else {
        // Optional: Handle unrecognized messages
        fastify.log.info(`Received unrecognized message from ${normalizedNumber}: ${payload}`);
        // replyMessage = 'Sorry, I only understand JOIN or STOP.';
        // Decide if you want to reply to unrecognized messages. Often it's better not to.
        // If no replyMessage is set, we won't send an SMS back.
      }

      // Send confirmation SMS if needed
      if (replyMessage) {
        await fastify.messagebird.messages.create({
          originator: options.messagebirdOriginator, // Your MessageBird number/sender ID
          recipients: [normalizedNumber],
          body: replyMessage,
        });
        fastify.log.info(`Sent confirmation to ${normalizedNumber}: ${replyMessage}`);
      }

      // Always reply to MessageBird webhook with a 2xx status code quickly
      // to acknowledge receipt and prevent retries.
      reply.code(200).send({ message: 'Webhook processed successfully' });

    } catch (error) {
      fastify.log.error({ err: error, originator: normalizedNumber }, 'Error processing webhook');
      // Don't reveal internal errors in the response to MessageBird.
      // A 200 OK is still sent to MessageBird to prevent retries for potentially
      // non-recoverable application errors (like DB errors). Log the error for investigation.
      reply.code(200).send({ message: 'Internal processing error occurred.' });
    }
  });
}

// utils/phoneUtils.js

/**
 * Basic normalization: Attempts to convert a phone number string towards E.164 format.
 * Removes non-digit characters except a leading '+'.
 * 
 * **E.164 Standard:** ITU-T Recommendation E.164 defines the international public 
 * telecommunication numbering plan. E.164 numbers contain a maximum of 15 digits 
 * (after the '+' sign) and follow the format: +[country code][subscriber number].
 * 
 * WARNING: This normalization is extremely basic and likely insufficient for many
 * real-world scenarios. It makes naive assumptions and doesn't validate number
 * structure or country codes. **Strongly consider using a robust library like
 * `libphonenumber-js` for production environments** to handle diverse
 * international formats correctly. See: https://www.npmjs.com/package/libphonenumber-js
 *
 * @param {string | null | undefined} phoneNumber The phone number string to normalize.
 * @returns {string | null} The normalized number (e.g., '+14155552671') or null if input is invalid/empty or normalization fails basic checks.
 */
export function normalizePhoneNumber(phoneNumber) {
    if (!phoneNumber) return null;

    let normalized = String(phoneNumber).trim().replace(/[^\d+]/g, ''); // Remove invalid chars

    if (normalized.startsWith('+')) {
        // Keep the leading '+', remove any others that might have slipped through regex
        normalized = '+' + normalized.substring(1).replace(/\+/g, '');
    } else {
        // Very naive: assume '+' is missing if it doesn't start with it.
        // This is often WRONG for international numbers not already in E.164.
        // normalized = '+' + normalized; // Commented out due to high risk of incorrectness
        // For this basic example, we'll only accept numbers that *already* start with '+'
        // or are purely digits (which might be local format – still risky).
        // A better approach requires a library. If it doesn't start with +, return null for stricter E.164.
         return null; // Require numbers to include the '+' prefix from the source.
    }

    // Final basic check: Must start with '+' and contain only digits afterward.
    if (!/^\+\d+$/.test(normalized)) {
       console.warn(`Could not normalize "${phoneNumber}" to a basic E.164 format. Result: "${normalized}"`);
       // Return null if strict format is required downstream
       return null;
    }

    return normalized;
}

/**
 * Basic E.164 format check: Starts with '+' followed by 1 to 15 digits.
 * Validates against the ITU-T E.164 standard which specifies a maximum 
 * of 15 digits after the '+' sign.
 * Does NOT validate country code validity or exact length requirements per country.
 *
 * @param {string | null | undefined} phoneNumber The phone number string to check.
 * @returns {boolean} True if the format looks like a basic E.164 number, false otherwise.
 */
export function isValidE164(phoneNumber) {
    if (!phoneNumber) return false;
    // E.164 standard: maximum 15 digits after the '+' sign
    return /^\+\d{1,15}$/.test(phoneNumber);
}

// plugins/verify-messagebird.js
import fp from 'fastify-plugin';
import crypto from 'crypto';

async function verifyMessageBirdPlugin(fastify, options) {
  const { webhookSigningKey } = options;

  if (!webhookSigningKey) {
    throw new Error('MessageBird Webhook Signing Key is required for verification');
  }

  // Verification function to be used as a preHandler hook via fastify.auth
  async function verifyRequest(request, reply) {
    const signature = request.headers['messagebird-signature'];
    const timestamp = request.headers['messagebird-request-timestamp'];

    // MessageBird signs the *raw* request body.
    // Accessing request.rawBody requires a contentTypeParser that stores it,
    // like the one added in app.js. If rawBody is not available, verification will fail.
    const body = request.rawBody; // Relies on the custom JSON parser in app.js

    if (!signature || !timestamp || body === undefined || body === null) {
      fastify.log.warn('Webhook verification failed: Missing signature, timestamp, or raw body');
      // Use 400 Bad Request as the required elements for verification are missing
      reply.code(400).send({ error: 'Missing signature headers or body for verification' });
      return; // Stop processing
    }

    // 1. Prepare the signed payload string (timestamp + '.' + rawBody)
    const signedPayload = `${timestamp}.${body}`;

    // 2. Calculate the expected signature (HMAC-SHA256)
    let expectedSignature;
    try {
      expectedSignature = crypto
        .createHmac('sha256', webhookSigningKey)
        .update(signedPayload)
        .digest('hex');
    } catch (error) {
        fastify.log.error({ err: error }, 'Error calculating HMAC signature, check signing key.');
        reply.code(500).send({ error: 'Internal server error during signature calculation' });
        return;
    }


    // 3. Compare signatures using timing-safe comparison
    try {
      // Ensure both buffers have the same byte length for timingSafeEqual
      const sigBuffer = Buffer.from(signature, 'hex');
      const expectedSigBuffer = Buffer.from(expectedSignature, 'hex');

      if (sigBuffer.length !== expectedSigBuffer.length) {
          fastify.log.warn('Webhook verification failed: Signature length mismatch.');
          reply.code(403).send({ error: 'Invalid signature' });
          return;
      }

      const signaturesMatch = crypto.timingSafeEqual(sigBuffer, expectedSigBuffer);

      if (!signaturesMatch) {
        fastify.log.warn('Webhook verification failed: Invalid signature');
        reply.code(403).send({ error: 'Invalid signature' });
        return; // Stop processing
      }
    } catch (error) {
      // Handles cases like invalid hex strings in signature or comparison errors
      fastify.log.error({ err: error }, 'Error during signature comparison');
      // Indicate bad request data if comparison fails due to format issues
      reply.code(400).send({ error: 'Invalid signature format or comparison error' });
      return; // Stop processing
    }


    // Optional but Recommended: Check timestamp validity (e.g., within 5 minutes)
    const requestTimeMs = Date.parse(timestamp); // Parses ISO 8601 string
    if (isNaN(requestTimeMs)) {
        fastify.log.warn(`Webhook verification failed: Invalid timestamp format. Timestamp: ${timestamp}`);
        reply.code(400).send({ error: 'Invalid request timestamp format' });
        return;
    }
    const nowMs = Date.now();
    const fiveMinutesMs = 5 * 60 * 1000;
    if (Math.abs(nowMs - requestTimeMs) > fiveMinutesMs) {
        fastify.log.warn(`Webhook verification failed: Timestamp out of tolerance. Timestamp: ${timestamp}, Now: ${new Date(nowMs).toISOString()}`);
        reply.code(408).send({ error: 'Request timestamp out of tolerance (replay attack?)' });
        return; // Stop processing
    }


    fastify.log.info('MessageBird webhook signature verified successfully');
    // If verification passes, fastify-auth allows continuation to the route handler
  }

  // Decorate fastify with the verification function so it can be used in routes via fastify.auth
  // We rely on @fastify/auth being registered globally in app.js
  if (!fastify.auth) {
      // This check ensures @fastify/auth is available. It should be registered *before* this plugin.
      throw new Error('@fastify/auth plugin must be registered before verify-messagebird plugin');
  }
  fastify.decorate('verifyMessageBird', verifyRequest);
}

export default fp(verifyMessageBirdPlugin, {
  name: 'verify-messagebird',
  dependencies: ['@fastify/auth'], // Explicitly declare dependency on @fastify/auth
});

// plugins/auth.js
import fp from 'fastify-plugin';
import crypto from 'crypto'; // Need crypto for timingSafeEqual

async function authPlugin(fastify, options) {
  const { apiSecretKey } = options;

  if (!apiSecretKey) {
    throw new Error('API Secret Key is required for authentication');
  }

  // Authentication function to be used with fastify.auth
  async function verifyApiKey(request, reply) {
    const providedKey = request.headers['x-api-key'];

    if (!providedKey) {
      fastify.log.warn('API Key verification failed: Missing x-api-key header');
      reply.code(401).send({ error: 'Missing API Key' });
      return; // Stop processing
    }

    // Use timing-safe comparison to prevent timing attacks
    try {
      const keyBuffer = Buffer.from(providedKey);
      const secretBuffer = Buffer.from(apiSecretKey);

      // Important: timingSafeEqual requires buffers of the same length.
      if (keyBuffer.length !== secretBuffer.length) {
        fastify.log.warn('API Key verification failed: Key length mismatch');
        // Still perform a comparison to obscure length differences, but know it will fail.
        // Use a dummy buffer of the same length as the expected key for the comparison.
        // This prevents leaking length info via timing.
        crypto.timingSafeEqual(secretBuffer, secretBuffer); // Compare secret against itself
        reply.code(403).send({ error: 'Invalid API Key' });
        return; // Stop processing
      }

      const keysMatch = crypto.timingSafeEqual(keyBuffer, secretBuffer);

      if (!keysMatch) {
        fastify.log.warn('API Key verification failed: Invalid key');
        reply.code(403).send({ error: 'Invalid API Key' });
        return; // Stop processing
      }

      fastify.log.info('API Key verified successfully');
      // If verification passes, fastify-auth allows continuation

    } catch (error) {
      fastify.log.error({ err: error }, 'Error during API Key comparison');
      reply.code(500).send({ error: 'Internal server error during authentication' });
      return; // Stop processing
    }
  }

  // Decorate fastify with the verification function
  if (!fastify.auth) {
      throw new Error('@fastify/auth plugin must be registered before the auth plugin');
  }
  fastify.decorate('verifyApiKey', verifyApiKey);
}

export default fp(authPlugin, {
  name: 'apiKeyAuth',
  dependencies: ['@fastify/auth'], // Depends on @fastify/auth
});