Prism-Notes-Main/tools/user-alert/README.md

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:

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

Usage

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

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

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.

await alertSystem.watchForSharedNotes();

stop()

Unsubscribes from collection changes and stops monitoring.

alertSystem.stop();

playNotificationSound()

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

await alertSystem.playNotificationSound();

Integration

This tool is integrated into Prism Notes via index.html. Include it in your 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.