fastify-xrcs

Fastify plugin for building and sending RCS rich cards and carousels via the Twilio Content API. Decorates the server with fastify.xrcs providing fluent builders for cards, carousels, and content templates, plus API methods to create, send, list, and delete templates. Works in builder-only mode (no Twilio credentials) or API mode (with credentials).

Installation

npm install @xenterprises/fastify-xrcs fastify@5

Quick Start

import Fastify from "fastify";
import xRCS from "@xenterprises/fastify-xrcs";

const fastify = Fastify();

await fastify.register(xRCS, {
  accountSid: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
  messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
});

fastify.post("/notify/:phone", async (request) => {
  const card = fastify.xrcs.card()
    .title("Order Confirmed")
    .body("Your order #1234 is on its way!")
    .urlButton("Track Order", "https://example.com/track/1234")
    .build();

  return fastify.xrcs.sendCard(`+1${request.params.phone}`, card);
});

await fastify.listen({ port: 3000 });

Options

accountSid and authToken must always be provided together. When both are omitted the plugin registers in builder-only mode — builders and validators work but API calls throw. Passing an empty or whitespace-only string for either option is now rejected at registration (see Error Reference); to use builder-only mode, omit both options entirely.

Methods

API methods (require Twilio credentials)

• createTemplate(builder, register?) — Build a payload and optionally register it with the Twilio Content API.
• sendMessage(to, contentSid, vars?) — Send a message using an existing Content API template SID.
• sendCard(to, card, friendlyName?) — Create a card template and send it in one step.
• sendCarousel(to, carousel, friendlyName?) — Create a carousel template and send it in one step.
• getTemplate(contentSid) — Fetch a content template by SID.
• listTemplates(limit?) — List all content templates.
• deleteTemplate(contentSid) — Delete a content template.
• getMessageStatus(messageSid) — Fetch delivery status for a sent message.

Builders (no credentials required)

• card() — Fluent CardBuilder for RCS rich cards with title, body, media, and buttons.
• carousel() — Fluent CarouselBuilder for multi-card carousels.
• template(name?) — Fluent ContentTemplateBuilder for Twilio Content API payloads.

Validators

• validate.card(card) — Validate a card object without throwing.
• validate.carousel(carousel) — Validate a carousel object without throwing.

Constants

Also exported as named exports: CONTENT_TYPES, ACTION_TYPES, MEDIA_HEIGHT, CardBuilder, CarouselBuilder, ContentTemplateBuilder, and buildRcsApi(twilioClient, messagingServiceSid) (the API factory, exported so tests can inject a fake client). The package's default export is the Fastify plugin.

Error Reference

Registration fails fast with suite-standard messages that name the plugin, the option, and a usage example:

Runtime and builder errors keep the [xRCS] prefix:

Twilio API errors are wrapped in a new Error carrying only the original err.message — raw SDK error objects (which may contain request details) are never rethrown or logged.

Environment Variables

The plugin never reads process.env. The consumer sets these variables and passes the values into app.register(xRCS, { ... }) — this table documents that consumer convention, not plugin inputs:

How It Works

On registration the plugin validates options — failing fast on non-boolean active, non-string or empty credentials, or a half-provided credential pair — and initializes one Twilio client (reused for all calls; never per-request) when accountSid and authToken are present. fastify.xrcs is decorated with builder factories, constants, validation helpers, and API functions. Builder methods return this for chaining; .build() produces a plain object. API methods call the Twilio Content API to create/list/delete templates and the Messages API to send. sendCard and sendCarousel are convenience wrappers that call createTemplate then sendMessage in sequence.

AI Context

package: "@xenterprises/fastify-xrcs"
type: fastify-plugin
use-when: RCS rich cards and carousels via Twilio Content API — fluent builder pattern with optional builder-only mode (no credentials)
decorator: fastify.xrcs (card, carousel, template builders; createTemplate, sendMessage, sendCard, sendCarousel, getTemplate, listTemplates, deleteTemplate, getMessageStatus, validate)
env: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_MESSAGING_SERVICE_SID — consumer convention; the app reads these and passes values into register options (the plugin never reads process.env)
builder-only: omit accountSid/authToken to use builders/validators without API calls; empty-string credentials throw at registration