@mantiq/heartbeat 0.1.5 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantiq/heartbeat",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Observability, APM & queue monitoring for MantiqJS",
   "type": "module",
   "license": "MIT",

package/src/HeartbeatServiceProvider.ts

@@ -18,6 +18,7 @@ import { JobWatcher } from './watchers/JobWatcher.ts'
 import { EventWatcher } from './watchers/EventWatcher.ts'
 import { ModelWatcher } from './watchers/ModelWatcher.ts'
 import { LogWatcher } from './watchers/LogWatcher.ts'
+import { MailWatcher } from './watchers/MailWatcher.ts'
 import { ScheduleWatcher } from './watchers/ScheduleWatcher.ts'
 import { CreateHeartbeatTables } from './migrations/CreateHeartbeatTables.ts'
 import { DashboardController } from './dashboard/DashboardController.ts'
@@ -187,6 +188,7 @@ export class HeartbeatServiceProvider extends ServiceProvider {
       ['event', new EventWatcher()],
       ['model', new ModelWatcher()],
       ['log', new LogWatcher()],
+      ['mail', new MailWatcher()],
       ['schedule', new ScheduleWatcher()],
     ]
 
@@ -194,8 +196,8 @@ export class HeartbeatServiceProvider extends ServiceProvider {
     const onAny = eventBus.onAny.bind(eventBus)
 
     for (const [key, watcher] of watcherMap) {
-      const watcherConfig = config.watchers[key]
-      if (!watcherConfig.enabled) continue
+      const watcherConfig = config.watchers[key as keyof typeof config.watchers]
+      if (!watcherConfig?.enabled) continue
 
       watcher.configure(watcherConfig as Record<string, any>)
       heartbeat.addWatcher(watcher)

package/src/contracts/Entry.ts

@@ -11,6 +11,7 @@ export type EntryType =
   | 'model'
   | 'log'
   | 'schedule'
+  | 'mail'
 
 /**
  * A raw pending entry before it's persisted — pushed by watchers into the buffer.
@@ -125,6 +126,20 @@ export interface ScheduleEntryContent {
   status: 'success' | 'error'
 }
 
+export interface MailEntryContent {
+  to: string[]
+  cc: string[]
+  bcc: string[]
+  subject: string
+  from: string
+  mailer: string
+  html: string | null
+  text: string | null
+  attachments: string[]
+  duration: number
+  queued: boolean
+}
+
 // ── Span types ──────────────────────────────────────────────────────────────
 
 export type SpanStatus = 'ok' | 'error'

package/src/contracts/HeartbeatConfig.ts

@@ -21,6 +21,7 @@ export interface HeartbeatConfig {
     model: { enabled: boolean }
     log: { enabled: boolean; level: string }
     schedule: { enabled: boolean }
+    mail: { enabled: boolean }
   }
   tracing: { enabled: boolean; propagate: boolean }
   sampling: { rate: number; always_sample_errors: boolean }
@@ -50,6 +51,7 @@ export const DEFAULT_CONFIG: HeartbeatConfig = {
     model:     { enabled: true },
     log:       { enabled: true, level: 'debug' },
     schedule:  { enabled: true },
+    mail:      { enabled: true },
   },
   tracing: { enabled: true, propagate: true },
   sampling: { rate: 1.0, always_sample_errors: true },

package/src/dashboard/DashboardController.ts

@@ -9,6 +9,8 @@ import { renderCachePage } from './pages/CachePage.ts'
 import { renderEventsPage } from './pages/EventsPage.ts'
 import { renderPerformancePage } from './pages/PerformancePage.ts'
 import { renderRequestDetailPage } from './pages/RequestDetailPage.ts'
+import { renderMailPage } from './pages/MailPage.ts'
+import { renderMailDetailPage } from './pages/MailDetailPage.ts'
 import type { EntryType } from '../contracts/Entry.ts'
 
 /**
@@ -69,6 +71,8 @@ export class DashboardController {
         return renderEventsPage(this.store, this.basePath)
       case 'performance':
         return renderPerformancePage(this.metrics, this.basePath)
+      case 'mail':
+        return renderMailPage(this.store, this.basePath)
     }
 
     // Parameterized routes
@@ -78,6 +82,12 @@ export class DashboardController {
       return html ?? this.render404()
     }
 
+    const mailDetail = sub.match(/^mail\/([a-f0-9-]+)$/)
+    if (mailDetail) {
+      const html = await renderMailDetailPage(this.store, mailDetail[1]!, this.basePath)
+      return html ?? this.render404()
+    }
+
     return this.render404()
   }
 

package/src/dashboard/pages/MailDetailPage.ts

@@ -0,0 +1,110 @@
+import { renderLayout } from '../shared/layout.ts'
+import { badge, durationBadge, escapeHtml } from '../shared/components.ts'
+import type { HeartbeatStore } from '../../storage/HeartbeatStore.ts'
+import type { MailEntryContent } from '../../contracts/Entry.ts'
+
+export async function renderMailDetailPage(store: HeartbeatStore, uuid: string, basePath: string): Promise<string | null> {
+  const entry = await store.getEntry(uuid)
+  if (!entry || entry.type !== 'mail') return null
+
+  const c = JSON.parse(entry.content) as MailEntryContent
+  const recorded = new Date(entry.created_at)
+  const timeStr = `${recorded.getFullYear()}-${String(recorded.getMonth() + 1).padStart(2, '0')}-${String(recorded.getDate()).padStart(2, '0')} ${String(recorded.getHours()).padStart(2, '0')}:${String(recorded.getMinutes()).padStart(2, '0')}:${String(recorded.getSeconds()).padStart(2, '0')}`
+
+  const attachmentsList = c.attachments.length > 0
+    ? c.attachments.map(a => `<span class="mono sm" style="padding:4px 8px;background:var(--bg-2);border-radius:4px;font-size:11px">${escapeHtml(a)}</span>`).join(' ')
+    : '<span class="dim sm">None</span>'
+
+  const content = `
+    <div style="display:flex;align-items:center;gap:12px;margin-bottom:16px">
+      <a href="${basePath}/mail" style="color:var(--fg-3);text-decoration:none;font-size:13px">&larr; Mail</a>
+    </div>
+
+    <div class="card mb" style="padding:16px 18px">
+      <div style="display:flex;align-items:center;gap:10px;flex-wrap:wrap">
+        <span style="color:var(--fg-0);font-size:15px;font-weight:600">${escapeHtml(c.subject || '(no subject)')}</span>
+        ${c.queued ? badge('queued', 'amber') : badge('sent', 'green')}
+        ${badge(c.mailer, 'mute')}
+        ${durationBadge(c.duration)}
+      </div>
+      <div class="sm dim" style="margin-top:6px">${timeStr}</div>
+    </div>
+
+    <div class="card mb">
+      <div class="card-title">Details</div>
+      <div class="meta-grid">
+        <div class="meta-item">
+          <div class="meta-label">From</div>
+          <div class="meta-value mono sm">${escapeHtml(c.from)}</div>
+        </div>
+        <div class="meta-item">
+          <div class="meta-label">To</div>
+          <div class="meta-value mono sm">${escapeHtml(c.to.join(', '))}</div>
+        </div>
+        ${c.cc.length > 0 ? `<div class="meta-item">
+          <div class="meta-label">CC</div>
+          <div class="meta-value mono sm">${escapeHtml(c.cc.join(', '))}</div>
+        </div>` : ''}
+        ${c.bcc.length > 0 ? `<div class="meta-item">
+          <div class="meta-label">BCC</div>
+          <div class="meta-value mono sm">${escapeHtml(c.bcc.join(', '))}</div>
+        </div>` : ''}
+        <div class="meta-item">
+          <div class="meta-label">Attachments</div>
+          <div class="meta-value">${attachmentsList}</div>
+        </div>
+      </div>
+    </div>
+
+    <div class="card">
+      <div class="tabs">
+        <input type="radio" name="mail-tab" id="tab-html" checked>
+        <label for="tab-html">HTML Preview</label>
+        <input type="radio" name="mail-tab" id="tab-source">
+        <label for="tab-source">Source</label>
+        <input type="radio" name="mail-tab" id="tab-text">
+        <label for="tab-text">Plain Text</label>
+      </div>
+
+      <div class="tab-panel" id="panel-html" style="padding:0">
+        ${c.html
+          ? `<iframe id="mail-preview" srcdoc="${escapeAttr(c.html)}" style="width:100%;border:none;min-height:500px;background:#fff;border-radius:0 0 8px 8px" onload="this.style.height=this.contentDocument.body.scrollHeight+'px'"></iframe>`
+          : `<div style="padding:40px;text-align:center;color:var(--fg-3)">No HTML content</div>`
+        }
+      </div>
+
+      <div class="tab-panel" id="panel-source" style="padding:14px 0 0">
+        <pre class="code-block" style="max-height:500px;overflow:auto">${escapeHtml(c.html ?? '(no HTML)')}</pre>
+      </div>
+
+      <div class="tab-panel" id="panel-text" style="padding:14px 18px">
+        <pre style="white-space:pre-wrap;font-family:var(--font-mono, monospace);font-size:13px;color:var(--fg-1);line-height:1.6">${escapeHtml(c.text ?? '(no plain text)')}</pre>
+      </div>
+    </div>
+
+    <script>
+    (function() {
+      var tabs = document.querySelectorAll('[name="mail-tab"]');
+      var panels = {
+        'tab-html': document.getElementById('panel-html'),
+        'tab-source': document.getElementById('panel-source'),
+        'tab-text': document.getElementById('panel-text'),
+      };
+      function show() {
+        for (var id in panels) { panels[id].style.display = 'none'; }
+        for (var t of tabs) {
+          if (t.checked) { panels[t.id].style.display = 'block'; }
+        }
+      }
+      for (var t of tabs) t.addEventListener('change', show);
+      show();
+    })();
+    </script>
+  `
+
+  return renderLayout({ title: 'Mail Detail', activePage: 'mail', basePath, content })
+}
+
+function escapeAttr(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}

package/src/dashboard/pages/MailPage.ts

@@ -0,0 +1,50 @@
+import { renderLayout } from '../shared/layout.ts'
+import { durationBadge, timeAgo, escapeHtml, badge } from '../shared/components.ts'
+import type { HeartbeatStore } from '../../storage/HeartbeatStore.ts'
+import type { MailEntryContent } from '../../contracts/Entry.ts'
+
+export async function renderMailPage(store: HeartbeatStore, basePath: string): Promise<string> {
+  const entries = await store.getEntries('mail', 50)
+
+  const rows = entries.map((e) => {
+    const c = JSON.parse(e.content) as MailEntryContent
+    const to = c.to.length > 2
+      ? `${escapeHtml(c.to.slice(0, 2).join(', '))} +${c.to.length - 2}`
+      : escapeHtml(c.to.join(', '))
+
+    return `<tr>
+      <td style="padding:10px 14px">
+        <a href="${basePath}/mail/${e.uuid}" style="color:var(--fg-0);text-decoration:none;font-weight:500">${escapeHtml(c.subject || '(no subject)')}</a>
+      </td>
+      <td class="mono sm" style="padding:10px 14px;color:var(--fg-2)">${to}</td>
+      <td style="padding:10px 14px">${badge(c.mailer, 'mute')}</td>
+      <td style="padding:10px 14px">${c.queued ? badge('queued', 'amber') : badge('sent', 'green')}</td>
+      <td style="padding:10px 14px">${durationBadge(c.duration)}</td>
+      <td class="sm dim" style="padding:10px 14px;text-align:right">${timeAgo(e.created_at)}</td>
+    </tr>`
+  }).join('')
+
+  const empty = entries.length === 0
+    ? `<tr><td colspan="6" style="padding:40px;text-align:center;color:var(--fg-3)">No mail entries recorded yet</td></tr>`
+    : ''
+
+  const content = `
+    <div class="card">
+      <table style="width:100%;border-collapse:collapse">
+        <thead>
+          <tr style="border-bottom:1px solid var(--border)">
+            <th class="th">Subject</th>
+            <th class="th">To</th>
+            <th class="th">Mailer</th>
+            <th class="th">Status</th>
+            <th class="th">Duration</th>
+            <th class="th" style="text-align:right">Time</th>
+          </tr>
+        </thead>
+        <tbody>${rows}${empty}</tbody>
+      </table>
+    </div>
+  `
+
+  return renderLayout({ title: 'Mail', activePage: 'mail', basePath, content })
+}

package/src/dashboard/shared/layout.ts

@@ -19,6 +19,7 @@ export function renderLayout(options: {
     { key: 'jobs', label: 'Jobs', icon: ICONS.layers },
     { key: 'cache', label: 'Cache', icon: ICONS.box },
     { key: 'events', label: 'Events', icon: ICONS.zap },
+    { key: 'mail', label: 'Mail', icon: ICONS.mail },
     { key: 'performance', label: 'Performance', icon: ICONS.activity },
   ]
 
@@ -85,6 +86,7 @@ const ICONS = {
   box: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"/><polyline points="3.27 6.96 12 12.01 20.73 6.96"/><line x1="12" y1="22.08" x2="12" y2="12"/></svg>`,
   zap: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="13 2 3 14 12 14 11 22 21 10 12 10 13 2"/></svg>`,
   activity: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="22 12 18 12 15 21 9 3 6 12 2 12"/></svg>`,
+  mail: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z"/><polyline points="22,6 12,13 2,6"/></svg>`,
   moon: `<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>`,
 }
 

package/src/index.ts

@@ -43,6 +43,7 @@ export { EventWatcher } from './watchers/EventWatcher.ts'
 export { ModelWatcher } from './watchers/ModelWatcher.ts'
 export { LogWatcher } from './watchers/LogWatcher.ts'
 export { ScheduleWatcher } from './watchers/ScheduleWatcher.ts'
+export { MailWatcher } from './watchers/MailWatcher.ts'
 
 // ── Tracing ─────────────────────────────────────────────────────────────────
 export { Tracer } from './tracing/Tracer.ts'

package/src/watchers/MailWatcher.ts

@@ -0,0 +1,52 @@
+import { Watcher } from '../contracts/Watcher.ts'
+import type { MailEntryContent } from '../contracts/Entry.ts'
+
+/**
+ * Records sent emails for the Heartbeat dashboard.
+ *
+ * Captures: recipients, subject, from, mailer driver, HTML body (for preview),
+ * attachments list, duration, and whether it was queued.
+ *
+ * Integration: HeartbeatServiceProvider wraps MailManager.send() to intercept
+ * outgoing messages and feed them to this watcher.
+ */
+export class MailWatcher extends Watcher {
+  override register(): void {
+    // Driven by HeartbeatServiceProvider wrapping mail transport
+  }
+
+  recordMail(data: {
+    to: string[]
+    cc?: string[]
+    bcc?: string[]
+    subject: string
+    from: string
+    mailer: string
+    html: string | null
+    text: string | null
+    attachments: string[]
+    duration: number
+    queued: boolean
+  }): void {
+    if (!this.isEnabled()) return
+
+    const content: MailEntryContent = {
+      to: data.to,
+      cc: data.cc ?? [],
+      bcc: data.bcc ?? [],
+      subject: data.subject,
+      from: data.from,
+      mailer: data.mailer,
+      html: data.html,
+      text: data.text,
+      attachments: data.attachments,
+      duration: data.duration,
+      queued: data.queued,
+    }
+
+    const tags = ['mail', data.mailer]
+    if (data.queued) tags.push('queued')
+
+    this.record('mail', content, tags)
+  }
+}