@plyaz/notifications

Unified, multi-channel notification system for email, SMS, and push notifications with multi-provider support, template engine, webhook tracking, and production-ready compliance features.

Installation

``bash
pnpm add @plyaz/notifications
`

Requirements:
- Node.js >= 22.4.0
- pnpm >= 8.0.0

Quick Start

$3

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

$3

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

$3

Create template at templates/en/email/welcome.md:

`markdown
---
subject: Welcome {{userName}}!
channel: email
category: transactional
layout: branded
---

Welcome to our platform, {{userName}}!

Thanks for signing up. Get started by clicking below:

Get Started
`

$3

`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: []
}
});
`

Features

$3

- ✅ Email - SendGrid, Infobip adapters (100% complete)
- ⏳ SMS - Mock adapter complete, providers pending
- ⏳ Push - Mock adapter complete, providers pending

$3

- Markdown + Handlebars templates
- Multi-language support (i18n)
- 4 layout variants (branded, minimal, transactional, none)
- Automatic CSS inlining for emails
- YAML frontmatter configuration

$3

- Multi-provider setup with automatic failover
- Priority-based routing (1 = highest)
- Circuit breaker pattern
- Health monitoring
- Retry logic with exponential backoff

$3

- RFC 8058 one-click unsubscribe
- User preference management
- Token generation (AES-256-GCM, JWT, HMAC-SHA256)
- PII redaction and hashing
- Webhook signature verification

$3

- SendGrid webhook support (ECDSA/HMAC verification)
- Infobip delivery & tracking webhooks
- Event normalization
- Idempotency handling
- Multiple webhook handlers

$3

- Bulk sending optimization (adapter-level bulk APIs)
- Attachment support (buffer, URL, file path)
- SMS character validation (GSM-7, UCS-2)
- URL shortening (3 adapter types)
- Inline CSS for email compatibility
- Event system (lifecycle, debug, error events)

Channel Support Matrix

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

Development Commands

`bash


Development

pnpm dev # Watch mode development
pnpm build # Build for production
pnpm clean # Clean dist directory

Testing

pnpm test # Run tests once
pnpm test:watch # Run tests in watch mode
pnpm test:coverage # Run tests with coverage
pnpm test:ui # Open Vitest UI

Code Quality

pnpm lint # Run ESLint
pnpm lint:fix # Auto-fix linting issues
pnpm format # Format code with Prettier
pnpm type:check # TypeScript type checking

Examples

pnpm example:order-email # Full feature showcase
pnpm example:attachments # Attachments guide
pnpm example:unsubscribe # Unsubscribe system
pnpm example:preferences # User preferences
pnpm example:webhook-complete # Production webhooks
pnpm test:sms-validation # SMS validation
pnpm test:url-shortening # URL shortening
`

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 validation

Documentation

- 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/` directory
6. Update IMPLEMENTATION_STATUS.md

License

ISC © Plyaz