npm package: @geethajyothi/atozas-pushnotification
Description: Production-ready cross-platform push notification system using Socket.IO and Web Push Notifications
Latest version: 1.0.0

# 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

```bash
npm install @geethajyothi/atozas-pushnotification
```

## 🚀 Quick Start

### 1. Generate VAPID Keys

```bash
npm run generate-vapid
```

This creates `vapid-keys.json` with your public and private keys.

### 2. Server Setup

```typescript
import { PushNotificationServer } from '@geethajyothi/atozas-pushnotification';

const server = new PushNotificationServer({
  port: 3000,
  vapidPublicKey: 'your-public-key',
  vapidPrivateKey: 'your-private-key',
  vapidEmail: 'mailto:your-email@example.com'
});

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**

```bash
npm run build
```

Then in your HTML:

```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

```typescript
// 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](./QUICKSTART.md)** - 5-minute getting started guide
- **[DOCUMENTATION.md](./DOCUMENTATION.md)** - Complete API reference
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Deep dive into system design
- **[examples/](./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](./DOCUMENTATION.md) for more troubleshooting tips.