š Unified notification system delivering real-time alerts across email, SMS, push, and in-app channels. Built for scalability with Redis queues and multi-tenant support
npm install @plyaz/notificationsUnified, multi-channel notification system for email, SMS, and push notifications with multi-provider support, template engine, webhook tracking, and production-ready compliance features.
``bash`
pnpm add @plyaz/notifications
Requirements:
- Node.js >= 22.4.0
- pnpm >= 8.0.0
`typescript
import { NotificationService, SendGridAdapter } from '@plyaz/notifications';
const service = new NotificationService({
providers: {
email: [new SendGridAdapter({
apiKey: process.env.SENDGRID_API_KEY!,
fromEmail: 'noreply@example.com',
fromName: 'My App'
})],
sms: [],
push: []
}
});
// Send email with template
const result = await service.sendEmail({
recipientId: 'user-123',
to: 'user@example.com',
templateId: 'welcome',
templateData: { userName: 'John' },
locale: 'en'
});
if (result.success) {
console.log('Email sent:', result.data.providerMessageId);
}
`
`typescript
import {
NotificationService,
SendGridAdapter,
InfobipEmailAdapter,
createProductionLogger
} from '@plyaz/notifications';
const logger = createProductionLogger({ service: 'notifications' });
const service = new NotificationService({
providers: {
email: [
new SendGridAdapter({ apiKey: '...', priority: 1 }, logger), // Primary
new InfobipEmailAdapter({ apiKey: '...', priority: 2 }, logger) // Fallback
],
sms: [],
push: []
},
logger
});
`
Create template at templates/en/email/welcome.md:
`markdown
---
subject: Welcome {{userName}}!
channel: email
category: transactional
layout: branded
---
Thanks for signing up. Get started by clicking below:
`typescript
import {
SendGridAdapter,
SendGridWebhookAdapter
} from '@plyaz/notifications';
const service = new NotificationService({
providers: {
email: [new SendGridAdapter({
apiKey: process.env.SENDGRID_API_KEY!,
fromEmail: 'noreply@example.com',
webhooks: [
new SendGridWebhookAdapter({
verificationKey: process.env.SENDGRID_WEBHOOK_KEY!,
onDelivered: (event) => {
console.log('Email delivered:', event.messageId);
},
onBounced: (event) => {
console.log('Email bounced:', event.reason);
}
})
]
})],
sms: [],
push: []
}
});
`
| Feature | Email | SMS | Push |
|---------|-------|-----|------|
| Providers | SendGrid, Infobip, Mock | Mock | Mock |
| Templates | ā
Full | ā
Full | ā
Full |
| Attachments | ā
Yes | ā No | ā No |
| Webhooks | ā
Yes | ā³ Pending | ā³ Pending |
| Bulk Sending | ā
Yes | ā³ Pending | ā³ Pending |
| Unsubscribe | ā
Yes | ā³ Pending | ā³ Pending |
`bashDevelopment
pnpm dev # Watch mode development
pnpm build # Build for production
pnpm clean # Clean dist directory
Package Dependencies
Per Plyaz monorepo architecture:
$3
- @plyaz/types/notifications - Type definitions
- @plyaz/logger - Structured logging with PII redaction
- @plyaz/api - Global API configuration
- @plyaz/errors - Error handling with correlation IDs$3
- @sendgrid/mail - SendGrid API client
- handlebars - Template engine
- marked - Markdown to HTML
- juice - CSS inlining for emails
- gray-matter - YAML frontmatter parsing
- zod - Schema validationDocumentation
- Usage Guide - Complete usage documentation with examples
- API Reference - Detailed API reference
- Implementation Status - Feature completion details
- Examples - 13 production-ready examples
Architecture
`
NotificationService
āāā ProviderRegistry (adapter selection & routing)
āāā TemplateEngine (Markdown + Handlebars)
āāā EventManager (lifecycle events)
āāā QueueProcessor (async processing)
āāā WebhookManager (delivery tracking)
āāā Email Adapters (SendGrid, Infobip, Mock)
āāā SMS Adapters (Mock)
āāā Push Adapters (Mock)
`Error Handling
Uses Result type pattern - no exceptions!
`typescript
const result = await service.sendEmail({ / ... / });if (result.success) {
console.log('Sent:', result.data.providerMessageId);
console.log('Retry attempts:', result.data.retryAttempts);
} else {
console.error('Failed:', result.error.message);
console.error('Error code:', result.error.code);
}
`Event System
`typescript
const service = new NotificationService({
providers: { / ... / }, // Lifecycle events
events: {
onSent: (event) => console.log('Sent:', event.notificationId),
onFailed: (event) => console.error('Failed:', event.error),
onDelivered: (event) => console.log('Delivered:', event.notificationId)
},
// Debug events
debugEvents: {
onFallbackTriggered: (event) => {
console.warn('Fallback:', event.metadata?.nextProvider);
}
},
// Error handlers
errorHandlers: {
onProviderError: async (error) => {
await errorTracking.report(error);
}
}
});
`Contributing
When adding new features:
1. Add types to
@plyaz/types/notifications
2. Implement feature with full TypeScript support
3. Add comprehensive tests (90% coverage minimum)
4. Update documentation (USAGE.md, API-REFERENCES.md)
5. Add example in examples/` directoryISC Ā© Plyaz