fastify-x-twilio

Fastify plugin combining Twilio and SendGrid communications. Registers a single fastify.xTwilio decorator namespace holding up to four services: sms (SMS/MMS), conversations (Twilio Conversations), rcs (RCS rich messaging, optional), and email (SendGrid transactional email).

Installation

npm install @xenterprises/fastify-xtwilio fastify@5

Quick Start

Register with only the services you need. A service whose option object is omitted is skipped silently — no active: false boilerplate required.

import Fastify from "fastify";
import xTwilio from "@xenterprises/fastify-xtwilio";

const fastify = Fastify();

await fastify.register(xTwilio, {
  twilio: {
    accountSid: process.env.TWILIO_ACCOUNT_SID, // consumer owns env access
    authToken: process.env.TWILIO_AUTH_TOKEN,
    phoneNumber: process.env.TWILIO_PHONE_NUMBER,
  },
});

// Send an SMS
await fastify.xTwilio.sms.send("+15551234567", "Hello from Fastify!");

The plugin never reads process.env itself — all configuration arrives via register options. To add SendGrid email, include the sendgrid object:

await fastify.register(xTwilio, {
  twilio: {
    accountSid: process.env.TWILIO_ACCOUNT_SID,
    authToken: process.env.TWILIO_AUTH_TOKEN,
    phoneNumber: process.env.TWILIO_PHONE_NUMBER,
  },
  sendgrid: {
    apiKey: process.env.SENDGRID_API_KEY,
    fromEmail: process.env.SENDGRID_FROM_EMAIL,
  },
});

await fastify.xTwilio.email.send("user@example.com", "Welcome!", "<h1>Welcome!</h1>");

A service object that is present but missing its credentials is a hard registration error (active defaults to true — explicit active: true without credentials still throws). You can also disable a service explicitly with active: false; omitting the object entirely has the same effect.

Options

All options are optional at the top level: omit twilio or sendgrid entirely to skip that service group. Once a service object is present, its credential options are required unless active: false.

twilio options

*Either phoneNumber or messagingServiceSid is required for SMS.

sendgrid options

Decorators

Single namespace fastify.xTwilio holding the four services. A service is absent (undefined) when its option object is omitted or disabled via active: false; rcs is additionally absent unless twilio.messagingServiceSid is provided.

Methods

SMS

• sms.send / sms.sendMMS / sms.sendBulk / sms.schedule / sms.cancelScheduled / sms.get / sms.getStatus / sms.list / sms.delete / sms.getMedia / sms.validatePhoneNumber — all SMS/MMS operations

Conversations

• conversations.create / conversations.get / conversations.update / conversations.list / conversations.delete / conversations.addParticipant / conversations.listParticipants / conversations.removeParticipant / conversations.sendMessage / conversations.sendMediaMessage / conversations.getMessages / conversations.getMessage / conversations.deleteMessage / conversations.getWebhooks / conversations.createWebhook — full conversation lifecycle

RCS

• rcs.send / rcs.sendMedia / rcs.sendTemplate / rcs.sendRichCard / rcs.sendCarousel / rcs.sendQuickReplies / rcs.getStatus / rcs.listTemplates / rcs.getTemplate / rcs.deleteTemplate — rich RCS messaging

Email

• email.send / email.sendTemplate / email.sendWithAttachments / email.sendBulk / email.sendPersonalizedBulk — send transactional emails
• email.validate / email.addContact / email.searchContact / email.deleteContact / email.createList / email.getLists / email.deleteList — SendGrid contact and list management

Error Reference

Registration fails fast on missing or invalid options. Registration errors use the xtwilio: prefix and each message ends with a full usage example (e.g. \app.register(xTwilio, { ... })``, elided below).

At runtime, every public method validates its arguments before calling external APIs; argument errors are prefixed with the service and method (e.g. [xTwilio] sms.send: to (string) is required.). External API failures are logged via fastify.log.error and re-thrown as [xTwilio] Failed to <operation>: <original message>. Two methods intentionally do not throw on API failure and instead return a result object: sms.validatePhoneNumber returns { valid: false, ... } and email.validate returns { valid: false, verdict: "Unknown", error }.

Environment Variables

The plugin never reads process.env itself. The consumer sets these variables (by convention) and passes the values into app.register(xTwilio, { ... }). They are inputs to the consumer's configuration, not to the plugin — a variable is only needed when you register the service it feeds.

How It Works

On registration the plugin validates the top-level option types, decorates the instance with an empty xTwilio namespace, and calls four setup* functions. A setup* function returns immediately when its option object is omitted or active: false; otherwise it validates credentials, initializes its own Twilio or SendGrid client, and attaches its API to fastify.xTwilio. The rcs service additionally skips registration when messagingServiceSid is not provided. All Twilio/SendGrid API errors are caught, logged via fastify.log.error (message only — no request config or credentials), and re-thrown with the [xTwilio] prefix and the original error message attached.

AI Context

package: "@xenterprises/fastify-xtwilio"
type: fastify-plugin
use-when: SMS/MMS, Twilio Conversations, RCS rich messaging, and SendGrid transactional email in one plugin
decorators: fastify.xTwilio (namespace holding sms, conversations, rcs — only if messagingServiceSid provided — and email; omitted services are absent)
env: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER, TWILIO_MESSAGING_SERVICE_SID, SENDGRID_API_KEY, SENDGRID_FROM_EMAIL (consumer sets and passes into register options; plugin never reads process.env)
services: sms (11 methods), conversations (15 methods), rcs (10 methods), email (12 methods)