# User Alert System

A standalone utility for monitoring shared notes and alerting the current user when notes are shared with them. Provides real-time notifications with desktop alerts and audio feedback.

## Features

- 🔔 Real-time desktop notifications when notes are shared
- 🔊 Audio alert system with fallback bell tones
- 📍 Prevents duplicate alerts for the same note
- 🎯 PocketBase integration for realtime subscriptions
- 🛡️ Graceful error handling for permission denials
- ♿ Respects browser notification permissions

## Installation

Copy the `user-alert` folder to your project:

```bash
cp -r user-alert /path/to/project/tools/
```

## Usage

After the tool is loaded, instantiate with your PocketBase instance:

```javascript
import { UserAlertSystem } from 'tools/user-alert/index.js';

// Create alert system
const alertSystem = new UserAlertSystem(
  pocketbaseInstance,
  userEmail,      // Current user's email
  userName        // Current user's display name
);

// Start monitoring for shared notes
await alertSystem.watchForSharedNotes();

// Stop monitoring when needed
alertSystem.stop();
```

## API

### Constructor

```javascript
new UserAlertSystem(pocketbaseInstance, userEmail, userName)
```

| Parameter | Type | Description |
| --- | --- | --- |
| `pocketbaseInstance` | PocketBase | Initialized PocketBase client |
| `userEmail` | string | Current user's email address |
| `userName` | string | Current user's display name |

### Methods

#### `watchForSharedNotes()`

Starts monitoring the notes collection for changes. Sets up realtime subscription that watches for notes where `sharedWith` includes the current user's email.

```javascript
await alertSystem.watchForSharedNotes();
```

#### `stop()`

Unsubscribes from collection changes and stops monitoring.

```javascript
alertSystem.stop();
```

#### `playNotificationSound()`

Plays a double-bell audio alert. Called automatically on alert, but can be triggered manually.

```javascript
await alertSystem.playNotificationSound();
```

## Integration

This tool is integrated into Prism Notes via `index.html`. Include it in your HTML:

```html
<script type="module">
  import { UserAlertSystem } from 'tools/user-alert/index.js';
  
  // Initialize after PocketBase and user auth is ready
  const alertSystem = new UserAlertSystem(pb, userEmail, userName);
  await alertSystem.watchForSharedNotes();
</script>
```

## PocketBase Collection Requirements

Your notes collection must have:
- `sharedWith` field (array of email addresses)
- `title`, `content` fields for display

Example schema:
```
notes {
  id: string (primary)
  title: string
  content: string
  createdBy: string
  sharedWith: array (of email strings)
  createdAt: date
}
```

## Browser Compatibility

Requires:
- Web Audio API for notification sounds
- Notifications API for desktop alerts
- ES6 modules for import/export
- PocketBase realtime subscriptions

Tested on:
- Chrome 90+
- Edge 90+
- Firefox 88+

## Permissions

The system requires user permission for:
- **Notifications**: Desktop notification display
- **Audio**: Playing notification sounds (may be blocked by autoplay policy until user gesture)

Users will be prompted by the browser to grant these permissions.

## Dependencies

- `pocketbase` (passed in constructor) — Realtime subscription system
- Browser APIs: Notifications API, Web Audio API, DOM

## Notes

- Notifications are persistent once dismissed; consider adding notification center
- Audio alerts may fail silently if browser blocks autoplay; notifications still work
- Prevent duplicate alerts by tracking `alertedNotes` Set internally
- Performance: Realtime subscription uses websocket; consider unsubscribing when user leaves page

## Troubleshooting

### "Permission denied" error
User denied notification permission. System will continue working but won't show desktop alerts.

### No audio on notification
Browser autoplay policy may block audio until user gesture. Desktop notification still appears.

### Alerts duplicating
Check that PocketBase realtime updates aren't sending multiple change events. Duplicate tracking should prevent this, but verify collection triggers.