@vasugrover/bun-notifications

A modular, type-safe notification service for Bun applications, supporting Discord, Telegram, and Email (SMTP) channels, with Drizzle ORM database tracking and a flexible template system.

Overview

@vasugrover/bun-notifications provides a robust, extensible notification infrastructure for Bun-based backends. It enables seamless integration with multiple notification channels, ensures reliable delivery tracking via PostgreSQL, and offers a template-driven approach for dynamic message content.

Features

• Multi-Provider Support: Out-of-the-box integration with Discord (webhook), Telegram (Bot API), and Email (SMTP via nodemailer).
• Database-Backed Tracking: All notifications are tracked in PostgreSQL using Drizzle ORM, supporting auditability and status monitoring.
• Template System: Variable substitution for dynamic, context-aware messages.
• Extensible Architecture: Add new providers by implementing the NotificationProvider interface.
• Environment-Based Configuration: Providers auto-configure from environment variables for secure, flexible deployment.
• Bun-Native: Designed and tested exclusively for Bun environments.
• Type Safety: All APIs and types are strictly typed for reliability and maintainability.

Installation

Install via Bun:

bun add @vasugrover/bun-notifications

Usage

1. Initialize the Service

import { NotificationService } from '@vasugrover/bun-notifications';
import { db } from './db'; // Your Drizzle ORM instance

const env = process.env;
const logger = console; // Or your preferred logger

const service = new NotificationService(db, env, logger);
service.initializeDefaultProviders();

2. Sending Notifications

Send a notification to a specific provider:

await service.sendNotification('discord', 'System Alert', 'A new event occurred.', 'alert');

Send a broadcast to multiple providers:

await service.sendBroadcast(['discord', 'telegram'], 'Update', 'System maintenance at 2 AM.', 'info');

3. Using Templates

import { templates } from '@vasugrover/bun-notifications';

const rendered = templates.welcome.render({ name: 'Alice', message: 'Welcome to the platform!' });
await service.sendNotification('email', rendered.title, rendered.message, 'info', { email: 'alice@example.com' });

4. Custom Providers

Implement a custom provider by extending the NotificationProvider interface:

import { NotificationProvider, Notification } from '@vasugrover/bun-notifications';

class MyProvider implements NotificationProvider {
  async send(notification: Notification): Promise<boolean> {
    // Custom logic
    return true;
  }
}

service.registerProvider('my', new MyProvider());

Environment Variables

Set the following environment variables as needed for your providers:

• DISCORD_WEBHOOK_URL
• TELEGRAM_BOT_TOKEN
• TELEGRAM_CHAT_ID
• SMTP_HOST
• SMTP_PORT
• SMTP_USER
• SMTP_PASS
• SMTP_FROM

For email notifications, always provide metadata.email in the notification call.

Database Schema

The package uses a notifications table with the following fields:

• id, title, message, type, provider, status, sentAt, error, metadata, createdAt, updatedAt

Types:

• Notification (select)
• NewNotification (insert)

Template System

Templates support variable substitution using the {{var}} syntax. Predefined templates include:

• templates.welcome
• templates.alert
• templates.info

You can create custom templates by implementing the TemplateRenderer interface.

TypeScript Types

• NotificationStatus: 'pending' | 'sent' | 'failed'
• Notification: Full notification object
• NewNotification: For inserts
• NotificationProvider: { send(notification: Notification): Promise<boolean> }

Troubleshooting

• Ensure all required environment variables are set for each provider.
• Check the provider's send() return value and the database record if a notification is not sent.
• Verify template variable names and data if templates do not render as expected.
• Review type definitions in src/types.ts and src/schema.ts for type errors.

Contributing

Contributions are welcome. Please review the contribution guidelines before submitting changes. Ensure that:

1. All changes are backward compatible
2. TypeScript types are updated as needed
3. Documentation is kept current
4. All checks pass using Bun (bun run typecheck, bun run lint, bun run build)

License

This project is licensed under the MIT License. See the LICENSE file for details.

Repository

• GitHub: https://github.com/itsvasugrover/bun-notifications
• Issues: https://github.com/itsvasugrover/bun-notifications/issues

Support

For questions or support, please open an issue on the GitHub repository.