@agenticmail/api 0.9.2 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/api",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "REST API server for AgenticMail — email and SMS endpoints for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/public/index.html

@@ -39,6 +39,7 @@
       <button id="search-clear" class="search-clear-btn" title="Clear (Esc)" data-icon="close"></button>
     </div>
     <div class="topbar-right">
+      <button class="icon-btn" id="sound-toggle-btn" title="Notification sound"></button>
       <button class="icon-btn" id="refresh-btn" title="Refresh (r)" data-icon="refresh"></button>
       <button id="profile-btn" class="profile-trigger" title="Account">
         <span id="profile-avatar"></span>

package/public/js/app.js

@@ -15,6 +15,7 @@ import { openMessage } from './message-view.js';
 import { populateComposeFrom, openCompose, openDraft, closeCompose, discardCompose, sendCompose } from './compose.js';
 import { subscribeToAllAgents, maybeRequestNotificationPermission } from './sse.js';
 import { icon } from './icons.js';
+import { isSoundEnabled, setSoundEnabled, playNotificationSound } from './sound.js';
 
 // Hydrate every `data-icon="name"` placeholder in the static HTML
 // with the corresponding inline SVG. Done once on load so we don't
@@ -188,6 +189,27 @@ document.getElementById('sidebar-backdrop').addEventListener('click', () => {
   document.getElementById('main')?.classList.remove('sidebar-open');
 });
 
+// Sound toggle. Stateful icon button — bell (on) / bell-slash (off).
+// Clicking flips the preference (persisted to localStorage by the
+// sound module), updates the icon, and plays a single test chime
+// on transitions to ON so the user hears what they just enabled.
+function renderSoundToggle() {
+  const btn = document.getElementById('sound-toggle-btn');
+  if (!btn) return;
+  const on = isSoundEnabled();
+  btn.innerHTML = icon(on ? 'soundOn' : 'soundOff', { size: 18 });
+  btn.title = on ? 'Notification sound: on (click to mute)' : 'Notification sound: off (click to enable)';
+  btn.classList.toggle('sound-on', on);
+  btn.classList.toggle('sound-off', !on);
+}
+document.getElementById('sound-toggle-btn')?.addEventListener('click', () => {
+  const next = !isSoundEnabled();
+  setSoundEnabled(next);
+  renderSoundToggle();
+  if (next) playNotificationSound();   // sample the chime on enable
+});
+renderSoundToggle();
+
 document.getElementById('refresh-btn').addEventListener('click', async () => {
   if (state.selectedAgent) {
     await loadList(state.selectedAgent, state.selectedFolder);

package/public/js/icons.js

@@ -47,6 +47,13 @@ const PATHS = {
   // ─── Status / dots ──────────────────────────────────────────────
   dot:     'M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8z',
   check:   'M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41L9 16.17z',
+  // Material-style notifications bell — used for the sound-on
+  // state. Off uses the same path with a diagonal slash overlay
+  // applied via CSS (.icon-svg.off → ::after rule in styles.css).
+  soundOn:  'M12 22a2 2 0 0 0 2-2h-4a2 2 0 0 0 2 2zm6-6V11c0-3.07-1.64-5.64-4.5-6.32V4a1.5 1.5 0 0 0-3 0v.68C7.63 5.36 6 7.92 6 11v5l-2 2v1h16v-1l-2-2z',
+  // Bell with a slash through it (off state). Single-path so the
+  // icon hot-swaps cleanly without dependency on overlay rules.
+  soundOff: 'M16.27 19.27 18 21l-1.27 1.27-1.45-1.45A1.98 1.98 0 0 1 14 22h-4a2 2 0 0 1-2-2h4a2 2 0 0 0 .27-.27L3 9.46 4.27 8.19 16.27 19.27zM18 16v-5a6 6 0 0 0-4.5-5.81V5a1.5 1.5 0 0 0-3 0v.19a6 6 0 0 0-2.16.91L18 16z',
 };
 
 export function icon(name, opts = {}) {

package/public/js/list-view.js

@@ -214,6 +214,48 @@ async function loadDraftsList(agent) {
   }
 }
 
+/**
+ * Refresh the currently-rendered list without rebuilding the
+ * toolbar. Used by the SSE new-mail handler so a new email
+ * silently slides into the list — no flicker, no "Loading…",
+ * no bulk-action selection wiped, no scroll jump.
+ *
+ * Drafts have their own loader; everything else uses the
+ * generic digest path. Falls through to a noop on errors
+ * (the SSE notification already pinged the user, so a silent
+ * refresh failure is acceptable — the next user-driven
+ * refresh / folder switch will repair).
+ */
+export async function silentRefresh(agent, folder) {
+  if (!agent) return;
+  try {
+    if (folder === 'drafts') {
+      const data = await apiGet('/drafts', { agentKey: agent.apiKey });
+      const rows = Array.isArray(data?.drafts) ? data.drafts : [];
+      state.messages = rows.map(r => ({
+        uid: r.id,
+        __draftId: r.id,
+        subject: r.subject || '(no subject)',
+        from: [{ name: agent.name, address: agent.email }],
+        date: r.updated_at ? `${r.updated_at}Z`.replace('ZZ', 'Z') : null,
+        preview: (r.text_body || '').slice(0, 240),
+        flags: [],
+        __recipient: r.to_addr || '(no recipient)',
+      }));
+      renderList();
+      return;
+    }
+    await ensureFolderCache(agent);
+    const isStarred = folder === 'starred';
+    const imap = isStarred ? 'INBOX' : (state.folderNames?.[folder]);
+    if (!imap) return;
+    const url = `/mail/digest?folder=${encodeURIComponent(imap)}&limit=50&offset=0&previewLength=240`;
+    const data = await apiGet(url, { agentKey: agent.apiKey });
+    state.messages = data.messages ?? [];
+    renderList();
+  } catch { /* silent — next user action will repair */ }
+}
+
 export function renderList() {
   const root = document.getElementById('list-rows');
   if (!root) return;

package/public/js/sound.js

@@ -0,0 +1,61 @@
+// Notification sound — soft 2-note chime synthesised via Web Audio
+// API (no external asset shipped, zero network cost). User
+// preference (on/off) lives in localStorage.
+//
+// Why Web Audio and not an <audio src="...">: the asset would have
+// to be bundled (cache invalidation, MIME types, paths under
+// `/branding/`, etc.), and we'd still need code to gate playback
+// on a user-toggle. Synthesizing a chime is one short function
+// with no asset surface and lets us tweak the timbre by editing
+// numbers.
+
+const STORAGE_KEY = 'agenticmail.notif.soundEnabled';
+
+/** True if the user has the chime turned on. Defaults to true. */
+export function isSoundEnabled() {
+  // null = never set → default ON. 'false' string = explicitly off.
+  return localStorage.getItem(STORAGE_KEY) !== 'false';
+}
+
+/** Persist the user's choice. */
+export function setSoundEnabled(enabled) {
+  try { localStorage.setItem(STORAGE_KEY, enabled ? 'true' : 'false'); } catch { /* private mode */ }
+}
+
+/**
+ * Play the new-mail chime. Two short sine pulses an octave apart
+ * (E5 → A5), 220 ms total, gain envelope quick attack + 60 ms
+ * decay so it reads as a soft "ding" rather than a buzz. Bails
+ * silently when sound is disabled or the browser blocks audio
+ * (e.g. tab hasn't received a user gesture yet — first arrival
+ * after a page load with no interaction may be muted by the
+ * autoplay policy; subsequent arrivals work).
+ */
+export function playNotificationSound() {
+  if (!isSoundEnabled()) return;
+  try {
+    const Ctor = window.AudioContext || window.webkitAudioContext;
+    if (!Ctor) return;
+    const ctx = new Ctor();
+    const now = ctx.currentTime;
+    const playTone = (freq, startOffset, duration = 0.08) => {
+      const osc = ctx.createOscillator();
+      const gain = ctx.createGain();
+      osc.type = 'sine';
+      osc.frequency.value = freq;
+      const start = now + startOffset;
+      // Quick attack + exponential decay = "chime" not "beep".
+      gain.gain.setValueAtTime(0.0001, start);
+      gain.gain.exponentialRampToValueAtTime(0.18, start + 0.01);
+      gain.gain.exponentialRampToValueAtTime(0.0001, start + duration);
+      osc.connect(gain).connect(ctx.destination);
+      osc.start(start);
+      osc.stop(start + duration);
+    };
+    playTone(659.25, 0);     // E5
+    playTone(880.00, 0.12);  // A5 — major sixth above
+    // Close the context shortly after the tones end so we don't
+    // leak audio contexts. Some browsers cap at ~6 concurrent.
+    setTimeout(() => { try { ctx.close(); } catch {} }, 600);
+  } catch { /* audio blocked; user-toggle is still respected */ }
+}

package/public/js/sse.js

@@ -1,13 +1,16 @@
 // Real-time mail delivery via Server-Sent Events. Every agent gets
 // its own subscription; the dispatcher pushes a `new` event per
 // arrived message. We fan that out to:
-//   1. List view — reload if it's the active inbox (instant ping)
+//   1. List view — silent in-place refresh (no flicker, no scroll
+//      jump, no bulk-selection wipe) if it's the active inbox
 //   2. Profile dropdown — bump the per-agent unread counter
 //   3. Browser notification — system ping when the tab is in the background
+//   4. Soft chime (toggleable) when sound is enabled
 import { state, API_URL } from './state.js';
 import { toast } from './utils.js';
 import { renderProfile } from './profile.js';
-import { loadList } from './list-view.js';
+import { silentRefresh } from './list-view.js';
+import { playNotificationSound } from './sound.js';
 
 export function subscribeToAllAgents() {
   // Tear down previous controllers (called on agent-list refresh).
@@ -49,11 +52,23 @@ async function handleSseEvent(agent, event) {
 
   const isOpen = state.selectedAgent?.id === agent.id;
   if (isOpen) {
-    await loadList(agent, state.selectedFolder);
+    // Silent in-place refresh — re-fetches the list digest and
+    // re-renders ONLY the rows div. Toolbar (select-all, refresh,
+    // bulk-actions) is untouched; existing row checkboxes survive;
+    // scroll position is preserved by the browser since we replace
+    // only the inner content. No "Loading…" flicker.
+    await silentRefresh(agent, state.selectedFolder);
     state.unread[agent.id] = 0;   // user is looking — clear badge
     renderProfile();
   }
 
+  // Soft chime — respects the user's sound toggle. Plays for every
+  // arrival regardless of whether the tab is focused, because that
+  // is the whole point of the chime (a foregrounded tab still
+  // benefits from the audible ping when the user's attention is
+  // elsewhere on screen).
+  playNotificationSound();
+
   fireBrowserNotification(agent, event, isOpen);
 
   if (!isOpen) {

package/public/styles.css

@@ -159,6 +159,10 @@ a { color: var(--accent-strong); }
   color: var(--ink-soft); font-size: 18px;
 }
 .icon-btn:hover { background: var(--bg-hover); }
+/* Sound-toggle state colours. On = brand pink (alive); off = muted
+   so the button reads as "currently silent". */
+#sound-toggle-btn.sound-on { color: var(--pink); }
+#sound-toggle-btn.sound-off { color: var(--muted); }
 
 /* ─── Profile (top right) ─────────────────────────────────────────── */
 .profile-trigger {