158 lines
4.1 KiB
Markdown
158 lines
4.1 KiB
Markdown
# 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.
|