@nuvix/messaging

Nuvix Messaging Library

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

Features

Email Adapters

• Mailgun - Email delivery service
• SendGrid - Email delivery platform
• SMTP - Generic SMTP support

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

Installation

bun install

Testing

This library includes comprehensive tests for all adapters using real API credentials. Tests are designed to work with actual services to ensure reliability.

Test Configuration

1. Copy the example environment file:

   cp .env.example .env

2. Configure your credentials in .env:

   # Example for Mailgun
   MAILGUN_API_KEY=key-1234567890abcdef
   MAILGUN_DOMAIN=mg.yourdomain.com
   MAILGUN_IS_EU=false
   
   # Example for Twilio
   TWILIO_ACCOUNT_SID=AC1234567890abcdef
   TWILIO_AUTH_TOKEN=your_auth_token
   TWILIO_FROM=[phone]
   
   # Add other service credentials as needed

3. Alternatively, configure credentials in test.config.ts:

   export const testConfig: TestConfig = {
     mailgun: {
       apiKey: "your-actual-api-key",
       domain: "your-domain.com",
       isEU: false,
       testEmail: "[e-mail]",
     },
     // ... other configurations
   };

Running Tests

# Run all tests
bun test

# Run tests with coverage
bun test --coverage

# Run tests in watch mode
bun test --watch

# Run specific test files
bun test tests/adapters/email.test.ts
bun test tests/adapters/sms.test.ts
bun test tests/adapters/push.test.ts

Test Behavior

• Configured Services: Tests will run with real API calls for services with valid credentials
• Unconfigured Services: Tests will be automatically skipped with helpful messages
• Real API Calls: Tests use actual service APIs to ensure reliability
• Test Messages: All test messages are clearly marked and include unique identifiers

Example Test Output

🧪 Starting Nuvix Messaging Adapter Tests
📊 Test Configuration Summary:
✅ Configured services: mailgun, twilio, fcm
⚠️  Unconfigured services (will be skipped): sendgrid, vonage, msg91, telesign, textmagic, apns
💡 To test these services, configure credentials in test.config.ts or environment variables

✅ Mailgun text email sent successfully
✅ Twilio SMS sent successfully
✅ FCM push notification sent successfully
⏭️  Skipping SendGrid tests: credentials not configured

Usage Examples

Email

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

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

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

SMS

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

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

const result = await adapter.send(sms);

Push Notifications

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

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);

Development

Project Structure

src/
├── adapter.ts              # Base adapter class
├── response.ts             # Response handling
├── types.ts                # Type definitions
├── adapter/                # Adapter implementations
│   ├── Email.ts            # Email base class
│   ├── SMS.ts              # SMS base class
│   ├── Push.ts             # Push base class
│   ├── Email/              # Email adapters
│   ├── SMS/                # SMS adapters
│   └── Push/               # Push adapters
├── messages/               # Message classes
│   ├── Email.ts
│   ├── SMS.ts
│   └── Push.ts
└── helpers/                # Utility functions

tests/
├── setup.ts                # Test configuration
├── utils.ts                # Test utilities
└── adapters/               # Adapter tests
    ├── email.test.ts
    ├── sms.test.ts
    ├── push.test.ts
    └── messages.test.ts

Building

bun run build

Linting

bun run lint
bun run lint:fix

License

This project is licensed under the MIT License.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for any new functionality
4. Ensure all tests pass with real credentials
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