Nuvix Messaging Library v2

A comprehensive messaging library for Email, SMS, and Push notifications with support for multiple service providers.

v2 highlights: Bun-only runtime · ESM-only · zero runtime dependencies (JWT via native WebCrypto, phone parsing via built-in calling-code table) · typed MessagingError · consistent per-recipient delivery results · FCM OAuth token caching · HTTPS-only transport with header-injection protection · fully mocked test suite (no real credentials needed).

Features

Email Adapters

• Mailgun - Email delivery service
• SendGrid - Email delivery platform
• SMTP - Generic SMTP support (optional nodemailer peer dependency)

SMS Adapters

• Twilio - SMS and communication APIs
• Vonage (formerly Nexmo) - Global communications platform
• Msg91 - SMS and communication platform
• Telesign - Customer verification platform
• TextMagic - SMS marketing platform

Push Notification Adapters

• FCM (Firebase Cloud Messaging) - Google's messaging solution
• APNS (Apple Push Notification Service) - Apple's push notification service

Requirements

• Bun >= 1.1
• Node.js is not supported in v2.

Installation

bun add @nuvix/messaging

Usage Examples

Email

import { Mailgun } from "@nuvix/messaging";
import { Email } from "@nuvix/messaging";

const adapter = new Mailgun("api-key", "domain.com");
const email = new Email({
  to: ["[email protected]"],
  subject: "Hello World",
  content: "This is a test email",
  fromName: "Your App",
  fromEmail: "[email protected]",
});

const result = await adapter.send(email);
console.log(`Delivered to ${result.deliveredTo} recipients`);

SMS

import { Twilio } from "@nuvix/messaging";
import { SMS } from "@nuvix/messaging";

const adapter = new Twilio("account-sid", "auth-token", "+1234567890");
const sms = new SMS({
  to: ["+1987654321"],
  content: "Hello from your app!",
});

const result = await adapter.send(sms);

Push Notifications

import { FCM } from "@nuvix/messaging";
import { Push } from "@nuvix/messaging";

const adapter = new FCM("service-account-json");
const push = new Push({
  to: ["device-token"],
  title: "New Message",
  body: "You have a new notification",
  data: { type: "message", id: "123" },
});

const result = await adapter.send(push);

Typed errors

import { MessagingError, MessagingErrorCode } from "@nuvix/messaging";

try {
  await adapter.send(sms);
} catch (error) {
  if (error instanceof MessagingError) {
    switch (error.code) {
      case MessagingErrorCode.BATCH_LIMIT_EXCEEDED:
        // split the batch and retry
        break;
      case MessagingErrorCode.NO_RECIPIENTS:
        // fix the message
        break;
    }
  }
}

Testing

The default test suite is fully mocked — no provider credentials required:

bun install
bun test            # run all tests
bun test --coverage # with coverage
bun test --watch    # watch mode

Optional live integration tests hit real provider APIs. They are excluded by default; enable them with credentials from .env:

cp .env.example .env   # fill in credentials
bun run test:live      # RUN_LIVE_TESTS=true bun test tests/live

Development

Project Structure

src/
├── adapter.ts              # Base adapter class (HTTP engine, retries, validation)
├── response.ts             # Delivery result accumulator
├── types.ts                # Type definitions
├── errors.ts               # MessagingError + error codes
├── adapter/                # Adapter implementations
│   ├── Email.ts            # Email base class
│   ├── SMS.ts              # SMS base class
│   ├── Push.ts             # Push base class
│   ├── Email/              # Mailgun, Sendgrid, SMTP
│   ├── SMS/                # Twilio, Vonage, Msg91, Telesign, TextMagic
│   └── Push/               # FCM, APNS
├── messages/               # Message classes (Email, SMS, Push, Attachment)
└── helpers/
    └── jwt.ts              # Native WebCrypto JWT signing (RS256 / ES256)

tests/
├── helpers/mock-fetch.ts   # fetch mocking utilities
├── adapters/               # Adapter tests (mocked HTTP)
├── live/                   # Optional live integration tests
├── adapter.test.ts         # Base engine tests (retry, security, validation)
├── jwt.test.ts             # WebCrypto JWT signing tests
├── messages.test.ts        # Message class tests
└── response.test.ts        # Response tests

Building

bun run build        # bun build (ESM, target=bun) + tsc declarations
bun run typecheck    # tsc --noEmit

Linting

bun run lint
bun run lint:fix

Security

• All outbound requests are restricted to https://
• Header values are sanitized against CRLF injection
• Provider errors are surfaced per recipient without leaking credentials
• SMTP's insecure TLS-bypass option (rejectUnauthorized: false) was removed in v2

Migrating from v1

See MIGRATION.md.

License

This project is licensed under the MIT License.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests (mocked — no real credentials in CI)
4. Ensure bun test, bun run lint, and bun run build pass
5. Submit a pull request

Service Provider Documentation

• Mailgun API
• SendGrid API
• Twilio SMS API
• Vonage SMS API
• Firebase Cloud Messaging
• Apple Push Notification Service