+-------------+        +-----------------+        +-------------+        +-----------+
|   Client    | -----> |  Fastify API    | -----> |  Sinch API  | -----> | Recipient |
| (e.g., App, |        | (/send-mms)     |        | (SMS /batches)|       | (Mobile)  |
|  Frontend)  |        +-----------------+        +-------------+        +-----------+
|             |          |    |    ^                                        ^
|             |          |    v    |                                        |
|             |          |  Node.js                                         | (MMS)
|             |          | (axios)                                          |
|             |          +-----------------+                                 |
|             |                                                              |
|             | <------------------------------------------------------------+
|             |                  (Optional: Delivery Status via Webhook -> DB -> API)
+-------------+

mkdir sinch-mms-fastify
cd sinch-mms-fastify

npm init -y

npm install fastify axios dotenv @fastify/rate-limit

npm install --save-dev pino-pretty tap

mkdir src
mkdir src/routes
mkdir src/services
touch src/app.js
touch src/server.js
touch src/routes/mms.js
touch src/services/sinchService.js
touch .env
touch .env.example
touch .gitignore

sinch-mms-fastify/
├── node_modules/
├── src/
│   ├── app.js             # Fastify app configuration
│   ├── server.js          # Server startup logic
│   ├── routes/
│   │   └── mms.js         # MMS sending route handler
│   └── services/
│       └── sinchService.js # Logic for interacting with Sinch API
├── .env                 # Local environment variables (DO NOT COMMIT)
├── .env.example         # Example environment variables (Commit this)
├── .gitignore           # Files/folders ignored by Git
├── package.json
└── package-lock.json

# Node dependencies
node_modules/

# Environment variables
.env*
!.env.example

# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*

# Build output
dist/
build/

# OS generated files
.DS_Store
Thumbs.db

# Sinch API Credentials (Find in Sinch Dashboard -> SMS -> APIs -> Your API -> REST Configuration)
SINCH_SERVICE_PLAN_ID=YOUR_SERVICE_PLAN_ID
SINCH_API_TOKEN=YOUR_API_TOKEN

# Sinch Number associated with the Service Plan ID (E.164 format, e.g., +12025550181)
SINCH_FROM_NUMBER=YOUR_SINCH_NUMBER

# Sinch API Region Base URL (e.g., us, eu, ca, au, br, jp) - determines the base URL
# Examples: https://us.sms.api.sinch.com, https://eu.sms.api.sinch.com
# Defaulting to US here. Change if needed.
SINCH_REGION=us

# Server Configuration
PORT=3000
HOST=0.0.0.0 # Listen on all available network interfaces
LOG_LEVEL=info # Pino log levels: 'fatal', 'error', 'warn', 'info', 'debug', 'trace' or 'silent'

# --- COPY from .env.example and fill with REAL values ---
SINCH_SERVICE_PLAN_ID=your_actual_service_plan_id_here
SINCH_API_TOKEN=your_actual_api_token_here
SINCH_FROM_NUMBER=+1xxxxxxxxxx # Your actual Sinch number
SINCH_REGION=us # Or your region
PORT=3000
HOST=0.0.0.0
LOG_LEVEL=info
# --- END COPY ---

{
  // ... other package.json content ...
  ""main"": ""src/server.js"", // Specify entry point
  ""scripts"": {
    ""start"": ""node src/server.js"",
    ""dev"": ""node src/server.js | pino-pretty"", // Pipe output to pino-pretty for dev
    ""test"": ""tap src/**/*.test.js"" // Configure test script later
  },
  // ... other package.json content ...
}

import axios from 'axios';
import dotenv from 'dotenv';

// Load environment variables early
dotenv.config();

const {
  SINCH_SERVICE_PLAN_ID,
  SINCH_API_TOKEN,
  SINCH_FROM_NUMBER,
  SINCH_REGION = 'us', // Default to 'us' if not set
} = process.env;

// Validate essential configuration
if (!SINCH_SERVICE_PLAN_ID || !SINCH_API_TOKEN || !SINCH_FROM_NUMBER) {
  // Using console.error here as the main app logger might not be initialized yet
  console.error('Error: Missing required Sinch environment variables (SERVICE_PLAN_ID, API_TOKEN, FROM_NUMBER).');
  process.exit(1); // Exit if critical config is missing
}

// Construct base URL based on region
const SINCH_BASE_URL = `https://${SINCH_REGION}.sms.api.sinch.com/xms/v1/${SINCH_SERVICE_PLAN_ID}`;

// Create an axios instance for Sinch API calls
const sinchApiClient = axios.create({
  baseURL: SINCH_BASE_URL,
  headers: {
    'Authorization': `Bearer ${SINCH_API_TOKEN}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  timeout: 15000, // 15 second timeout
});

/**
 * Sends an MMS message via the Sinch API.
 * Note: Uses console.log/error for simplicity in this standalone module.
 * A more sophisticated setup might involve injecting a logger instance.
 *
 * @param {string} to The recipient phone number in E.164 format (e.g., +1xxxxxxxxxx).
 * @param {string} mediaUrl The publicly accessible URL of the media file (JPEG, PNG, GIF supported).
 * @param {string} [text] Optional text message to accompany the media. Max 1600 chars.
 * @returns {Promise<object&gt;} The response data from the Sinch API on success.
 * @throws {Error} If the API call fails or returns an error status.
 */
async function sendMms(to, mediaUrl, text = '') {
  const endpoint = '/batches'; // Using the batches endpoint

  // Construct the payload for sending a single MMS message within a batch
  const payload = {
    to: [to], // Recipient needs to be in an array
    from: SINCH_FROM_NUMBER,
    body: {
      url: mediaUrl,
      // You can optionally add a message/caption to the media body itself
      // message: ""Media Caption Example"",
    },
    // Add the text part if provided
    ...(text && { parameters: { // Standard text goes in parameters for media messages
        // Note: The exact parameter key and carrier handling for text alongside MMS can vary.
        // 'text_message' is a plausible custom parameter.
        // Consult the latest Sinch API documentation for the /batches endpoint and test with target carriers
        // if precise text display behavior is critical.
        text_message: { default: text }
    }}),
    // Explicitly defining type might be needed for some scenarios, but often inferred
    // type: 'mt_media',
    // delivery_report: 'full' // Optional: Request detailed delivery reports (requires webhook setup)
  };

  try {
    console.info(`[Sinch Service] Attempting to send MMS to ${to}...`); // Basic logging
    const response = await sinchApiClient.post(endpoint, payload);

    // Sinch API usually returns 200 or 201 on success for batch sends
    if (response.status === 200 || response.status === 201) {
      console.info(`[Sinch Service] Sinch API Success Response Status: ${response.status}`);
      console.info('[Sinch Service] Sinch Response Data:', response.data); // Log successful response data
      // The response.data often contains a batch_id which can be used for tracking
      return response.data;
    } else {
      // This case might not be hit often if axios throws on non-2xx status, but good practice
      console.error(`[Sinch Service] Sinch API returned non-success status: ${response.status}`, response.data);
      throw new Error(`Sinch API Error: Status ${response.status}`);
    }
  } catch (error) {
    console.error('[Sinch Service] Error sending MMS via Sinch:', error.message);
    if (error.response) {
      // The request was made and the server responded with a status code
      // that falls out of the range of 2xx
      console.error('[Sinch Service] Sinch Error Response Data:', error.response.data);
      console.error('[Sinch Service] Sinch Error Response Status:', error.response.status);
      console.error('[Sinch Service] Sinch Error Response Headers:', error.response.headers);
      // Rethrow a more specific error including details from Sinch if available
      const sinchError = error.response.data?.request_error?.service_exception?.text
                       || error.response.data?.text
                       || `Sinch API request failed with status ${error.response.status}`;
      throw new Error(`Failed to send MMS: ${sinchError}`);
    } else if (error.request) {
      // The request was made but no response was received
      console.error('[Sinch Service] Sinch Error Request:', error.request);
      throw new Error('Failed to send MMS: No response received from Sinch API.');
    } else {
      // Something happened in setting up the request that triggered an Error
      console.error('[Sinch Service] Sinch Error Config:', error.config);
      throw new Error(`Failed to send MMS: Error setting up request - ${error.message}`);
    }
  }
}

export default { sendMms };

import sinchService from '../services/sinchService.js';

// Define the JSON schema for the request body for validation
const sendMmsBodySchema = {
  type: 'object',
  required: ['to', 'mediaUrl'],
  properties: {
    to: {
      type: 'string',
      description: 'Recipient phone number in E.164 format (e.g., +12025550181)',
      // Basic pattern for E.164 format (must start with +, followed by digits)
      pattern: '^\\+[1-9]\\d{1,14}$'
    },
    mediaUrl: {
      type: 'string',
      description: 'Publicly accessible URL of the media file (JPEG, PNG, GIF)',
      format: 'url' // Use Fastify's built-in format validation
    },
    text: {
      type: 'string',
      description: 'Optional text message to accompany the media (max 1600 chars)',
      maxLength: 1600,
      nullable: true // Allow null or missing
    }
  },
  additionalProperties: false // Disallow properties not defined in the schema
};

// Define the schema for the success response
const successResponseSchema = {
  type: 'object',
  properties: {
    message: { type: 'string' },
    batch_id: { type: 'string', description: 'Sinch batch ID for tracking' },
    // Include other relevant fields from Sinch response if needed
  }
};

// Define the schema for error responses
const errorResponseSchema = {
    type: 'object',
    properties: {
        statusCode: { type: 'integer' },
        error: { type: 'string' },
        message: { type: 'string' },
    }
};


/**
 * Fastify route handler plugin for sending MMS.
 * @param {import('fastify').FastifyInstance} fastify The Fastify instance.
 * @param {object} options Plugin options.
 */
async function mmsRoutes(fastify, options) {

  fastify.post('/send-mms', {
    schema: {
      description: 'Send an MMS message via Sinch',
      tags: ['MMS'], // Useful for OpenAPI documentation generation
      summary: 'Sends an MMS message',
      body: sendMmsBodySchema,
      response: {
        200: successResponseSchema, // Successful send
        // Sinch might return 201 Created for batches, map to 200 for consistency or keep 201
        // 201: successResponseSchema,
        // Add schemas for 4xx and 5xx errors for OpenAPI documentation
        400: errorResponseSchema, // Validation error
        500: errorResponseSchema  // Server/Sinch API error
      }
    }
  }, async (request, reply) => {
    // Access the logger instance decorated onto the request object
    const log = request.log;
    const { to, mediaUrl, text } = request.body;

    log.info(`Received request to send MMS to ${to}`);

    try {
      // Pass the logger instance to the service if it were refactored to accept it
      // const sinchResponse = await sinchService.sendMms(to, mediaUrl, text, log);
      const sinchResponse = await sinchService.sendMms(to, mediaUrl, text);

      // Sinch batch API usually returns 200 or 201 on success
      // Standardize API response to 200 OK for simplicity client-side.
      const replyPayload = {
          message: 'MMS sent successfully via Sinch.',
          // Pass relevant info back, like the batch_id for tracking
          batch_id: sinchResponse?.id || 'N/A',
      };

      reply.code(200).send(replyPayload);

    } catch (error) {
      log.error({ err: error }, `Error processing /send-mms request: ${error.message}`);

      // Determine appropriate status code based on error type
      // Check if it's likely a client-side issue passed up from the service
      if (error.message.includes('Failed to send MMS:') &&
          (error.message.includes('400') || // Rough check for Sinch 400 errors
           error.message.includes('Invalid') ||
           error.message.includes('format'))) {
         reply.code(400).send({
             statusCode: 400,
             error: 'Bad Request',
             // Provide a clearer message if possible, else the Sinch error
             message: error.message.replace('Failed to send MMS: ', '')
         });
      } else {
         // Assume internal server error or downstream Sinch API error (5xx, network, etc.)
         reply.code(500).send({
             statusCode: 500,
             error: 'Internal Server Error',
             // Avoid leaking potentially sensitive details from Sinch 5xx errors
             message: 'An unexpected error occurred while attempting to send the MMS.'
         });
      }
    }
  });
}

export default mmsRoutes;

import Fastify from 'fastify';
import dotenv from 'dotenv';
import rateLimit from '@fastify/rate-limit';
import mmsRoutes from './routes/mms.js';

// Load environment variables first
dotenv.config();

const {
  LOG_LEVEL = 'info', // Default to 'info' if not set
} = process.env;


/**
 * Builds and configures the Fastify application instance.
 * @param {object} opts - Options for Fastify constructor (e.g., for testing)
 * @returns {Promise<import('fastify').FastifyInstance&gt;} The configured Fastify app instance.
 */
async function buildApp(opts = {}) {

  // Initialize Fastify
  // Pass logger options based on environment (pretty print in dev/test)
  const app = Fastify({
    logger: {
      level: LOG_LEVEL,
      ...(process.env.NODE_ENV !== 'production' && { // Enable pretty printing only outside production
        transport: {
          target: 'pino-pretty',
          options: {
            translateTime: 'HH:MM:ss Z', // Human-readable time
            ignore: 'pid,hostname',     // Hide less relevant fields like process ID and hostname
          },
        }
      }),
    },
    ...opts, // Pass any additional options (e.g., from tests)
  });

  // --- Register Plugins ---

  // 1. Rate Limiting
  // Protects against brute-force attacks and abuse
  await app.register(rateLimit, {
    max: 100, // Max requests per window (adjust as needed)
    timeWindow: '1 minute', // Time window
    // Optional: Add Redis for distributed rate limiting across multiple instances
    // redis: new Redis({ host: '127.0.0.1', port: 6379 }),
    // Optional: Customize error response
    // errorResponseBuilder: function (req, context) {
    //   return {
    //     statusCode: 429,
    //     error: 'Too Many Requests',
    //     message: `Rate limit exceeded. You are allowed ${context.max} requests per ${context.after}. Please try again later.`,
    //   }
    // }
  });
  app.log.info('Rate limit plugin registered.');


  // Add other plugins here if needed (e.g., @fastify/cors, @fastify/swagger, @fastify/helmet)


  // --- Register Routes ---
  await app.register(mmsRoutes, { prefix: '/api/v1' }); // Prefix routes with /api/v1
  app.log.info('MMS routes registered under /api/v1.');


  // --- Add Hooks (optional) ---
  // Example: A global hook to log every request start/end
  // app.addHook('onRequest', async (request, reply) =&gt; {
  //   request.log.info({ req: { method: request.method, url: request.url, id: request.id } }, 'Incoming request');
  // });
  // app.addHook('onResponse', async (request, reply) =&gt; {
  //   request.log.info({ res: { statusCode: reply.statusCode }, reqId: request.id }, 'Request completed');
  // });


  // --- Graceful Shutdown ---
  // Handle SIGINT (Ctrl+C) and SIGTERM (used by Docker/Kubernetes)
  const shutdown = async (signal) =&gt; {
      app.log.warn(`Received ${signal}. Shutting down gracefully...`);
      try {
          await app.close();
          app.log.info('Server closed successfully.');
          process.exit(0);
      } catch (err) {
          app.log.error({ err }, 'Error during server shutdown.');
          process.exit(1);
      }
  };
  process.on('SIGINT', shutdown);
  process.on('SIGTERM', shutdown);

  app.log.info('Application setup complete.');
  return app;
}

export default buildApp;

import buildApp from './app.js';

const {
  PORT = 3000,  // Default to 3000 if not set
  HOST = '0.0.0.0' // Default to listen on all interfaces
} = process.env;

/**
 * Starts the Fastify server.
 */
async function startServer() {
  let app;
  try {
    app = await buildApp();

    // Start listening and log the address
    await app.listen({ port: PORT, host: HOST });
    // Note: Accessing app.server.address() might return null if listening on a pipe/socket
    // or if called before the 'listening' event. Fastify's internal log usually handles this.
    // For explicit logging, ensure it's done after await app.listen() resolves.
    const address = app.server.address();
    const addressString = typeof address === 'string' ? address : `${address?.address}:${address?.port}`;
    app.log.info(`Server listening on ${addressString}`);

  } catch (err) {
    // Log error using console.error before app.log might be available or if app init failed
    console.error('Error starting server:', err);
    // If app exists and has log, use it, otherwise stick to console
    if (app && app.log) {
        app.log.error({ err }, 'Server startup failed.');
    }
    process.exit(1);
  }
}

startServer();