@vocoweb/notify

Production-ready unified notification system for B2B SaaS.

Overview

@vocoweb/notify is the "Pulse" module that unifies Email, In-App, and Push notifications into a single API. Stop juggling SendGrid, Courier, and database notifications—just call notify.send().

Key Features:

• 📧 Multi-Channel - Email, in-app, and push notifications
• 🔔 Pre-built Inbox - Drop-in notification bell component
• 📬 Template System - Reusable notification templates
• ⚡ Real-Time - Supabase real-time for instant notifications
• 🎨 Customizable - Full control over templates and styling

Installation

npm install @vocoweb/notify

Quick Start

Server-Side

import { notify } from '@vocoweb/notify';

// Send multi-channel notification
export async function POST(request: Request) {
  await notify.send({
    userId: 'user_123',
    channel: ['email', 'in-app'],
    template: 'welcome-msg',
    data: {
      name: 'John Doe',
    },
  });
  
  return Response.json({ success: true });
}

// Send email only
await notify.sendEmail({
  to: '[email protected]',
  subject: 'Welcome to VocoWeb',
  template: 'welcome-email',
  data: { name: 'John' },
});

// Create in-app notification
await notify.sendInApp({
  userId: 'user_123',
  title: 'Project Deployed',
  message: 'Your project is live at example.com',
  link: '/projects/123',
});

Client-Side (React)

import { VocoNotificationBell } from '@vocoweb/notify/react';

// Add to navbar
export default function Navbar() {
  return (
    <nav>
      <VocoNotificationBell />
    </nav>
  );
}

API Reference

Server Methods

• send(options) - Universal send (multi-channel)
• sendEmail(options) - Send email notification
• sendInApp(options) - Create in-app notification
• markAsRead(notificationId) - Mark notification as read
• getNotifications(userId) - Get user notifications

React Components

• <VocoNotificationBell /> - Navbar notification bell with dropdown
• <VocoNotificationList /> - Notification list component

Templates

// Custom template
const templates = {
  'project-deployed': {
    email: {
      subject: 'Project Deployed',
      html: '<h1>Your project {{name}} is live!</h1>',
    },
    inApp: {
      title: 'Project Deployed',
      message: 'Your project {{name}} is live at {{url}}',
    },
  },
};

Environment Variables

# Supabase (Required)
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Email Provider (Optional)
SENDGRID_API_KEY=SG_...

Database Schema

CREATE TABLE notifications (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
  title TEXT NOT NULL,
  message TEXT NOT NULL,
  link TEXT,
  read BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

License

MIT © VocoWeb

Support

• Email: [email protected]
• Documentation: GitHub Wiki

Built with care by VocoWeb