Standards alignment: Document .js tools deviation, fix port 3030, enhance tool documentation

2026-01-14 12:47:22 +00:00
parent 2c384eb734
commit 534016e9d5
6 changed files with 226 additions and 4 deletions
@@ -0,0 +1,157 @@
+# 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.