Atozas Push Notification System

A production-ready, cross-platform push notification system using only Socket.IO and Web Push Notifications. No Firebase, OneSignal, or third-party services required.

🎯 Features

• Cross-Platform Support: Web (Chrome, Edge, Firefox) ↔ Android (Browser/PWA)
• Smart Routing: Automatically uses Socket.IO for online users, Web Push for offline
• Real-Time Delivery: Millisecond-level latency when both parties are online
• Background Delivery: Works when tabs are closed or apps are backgrounded
• Unified API: Single interface regardless of platform or delivery method
• Presence Tracking: Know when users are online/offline
• Production Ready: Built for high-traffic systems (taxi, tracking, admin alerts)

📦 Installation

npm install @geethajyothi/atozas-pushnotification

🚀 Quick Start

1. Generate VAPID Keys

npm run generate-vapid

This creates vapid-keys.json with your public and private keys.

2. Server Setup

import { PushNotificationServer } from '@geethajyothi/atozas-pushnotification';

const server = new PushNotificationServer({
  port: 3000,
  vapidPublicKey: 'your-public-key',
  vapidPrivateKey: 'your-private-key',
  vapidEmail: 'mailto:[email protected]'
});

server.start();

3. Client Setup (Web)

Option A: Standalone Example (No Build Required)

Use examples/client-example-standalone.html - it includes the client code inline and works immediately.

Option B: Compiled Client

npm run build

Then in your HTML:

<script src="https://cdn.socket.io/4.7.2/socket.io.min.js"></script>
<script type="module">
  import { PushNotificationClient } from './node_modules/@geethajyothi/atozas-pushnotification/dist/client/browser.js';

  const client = new PushNotificationClient({
    serverUrl: 'http://localhost:3000',
    userId: 'user-123',
    authToken: 'your-auth-token',
    vapidPublicKey: 'your-vapid-public-key',
    onNotification: (payload) => {
      console.log('Notification:', payload);
    }
  });

  await client.initialize();
</script>

4. Send Notification

// From server
await server.sendNotification({
  userId: 'user-123',
  title: 'New Message',
  body: 'You have a new message',
  data: { type: 'message', id: 'msg-456' }
});

📚 Documentation

• QUICKSTART.md - 5-minute getting started guide
• DOCUMENTATION.md - Complete API reference
• ARCHITECTURE.md - Deep dive into system design
• examples/ - Working code examples

🔐 Security

• User authentication required before message delivery
• VAPID key-based Web Push authentication
• Socket.IO connection authentication
• Protection against replay and duplicate notifications

🌍 Browser Support

• Chrome/Chromium (Desktop & Android)
• Edge (Desktop & Android)
• Firefox (Desktop & Android)
• Safari (limited Web Push support)

📄 License

MIT

🆘 Troubleshooting

Module Import Errors

If you see errors like "Expected a JavaScript-or-Wasm module script", you're trying to import TypeScript files directly. Use one of these solutions:

1. Use the standalone example: examples/client-example-standalone.html
2. Compile first: Run npm run build then import from dist/client/browser.js
3. Use a bundler: Webpack, Vite, or similar to handle TypeScript

Service Worker Not Found

Make sure client/sw.js is copied to your public directory and accessible at /sw.js.

Push Notifications Not Working

• Ensure HTTPS is enabled (required for Web Push, except localhost)
• Check browser notification permissions
• Verify VAPID keys are correct
• Check server logs for errors

See DOCUMENTATION.md for more troubleshooting tips.