@mantiq/heartbeat 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantiq/heartbeat",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "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()],
     ]
 

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/CachePage.ts

@@ -29,7 +29,6 @@ export async function renderCachePage(store: HeartbeatStore, basePath: string):
   })
 
   const content = `
-    <h1 class="page-title">Cache</h1>
     <div class="stats">
       ${stat('Hit Rate', hitRate, `${hits} hits / ${misses} misses`)}
       ${stat('Hits', hits.toString())}

package/src/dashboard/pages/EventsPage.ts

@@ -16,7 +16,6 @@ export async function renderEventsPage(store: HeartbeatStore, basePath: string):
   })
 
   const content = `
-    <h1 class="page-title">Events</h1>
     <div class="card">
       ${table(['Event', 'Listeners', 'Time'], rows)}
     </div>

package/src/dashboard/pages/ExceptionsPage.ts

@@ -30,7 +30,6 @@ export async function renderExceptionsPage(store: HeartbeatStore, basePath: stri
   })
 
   const content = `
-    <h1 class="page-title">Exceptions</h1>
     <div class="stats">
       ${stat('Total', entries.length.toString())}
       ${stat('Groups', groups.length.toString(), 'Unique')}

package/src/dashboard/pages/JobsPage.ts

@@ -29,7 +29,6 @@ export async function renderJobsPage(store: HeartbeatStore, basePath: string): P
   })
 
   const content = `
-    <h1 class="page-title">Jobs</h1>
     <div class="stats">
       ${stat('Processed', processed.toString(), 'Completed')}
       ${stat('Failed', failed.toString())}

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/pages/OverviewPage.ts

@@ -50,7 +50,6 @@ export async function renderOverviewPage(store: HeartbeatStore, metrics: Metrics
   ], labels)
 
   const content = `
-    <h1 class="page-title">Overview</h1>
     <div class="stats">
       ${stat('Requests', requestCount.toLocaleString(), 'Total recorded')}
       ${stat('P95 Latency', formatDuration(p95), 'Response time')}

package/src/dashboard/pages/PerformancePage.ts

@@ -16,7 +16,6 @@ export function renderPerformancePage(metrics: MetricsCollector, basePath: strin
   const errorRate = totalRequests > 0 ? ((totalErrors / totalRequests) * 100).toFixed(1) + '%' : '0%'
 
   const content = `
-    <h1 class="page-title">Performance</h1>
 
     <div class="card mb">
       <div class="card-title">Latency</div>

package/src/dashboard/pages/QueriesPage.ts

@@ -30,7 +30,6 @@ export async function renderQueriesPage(store: HeartbeatStore, basePath: string)
   })
 
   const content = `
-    <h1 class="page-title">Queries</h1>
     <div class="stats">
       ${stat('Total', entries.length.toString())}
       ${stat('Slow', slowCount.toString(), '> threshold')}

package/src/dashboard/pages/RequestDetailPage.ts

@@ -51,24 +51,24 @@ export async function renderRequestDetailPage(store: HeartbeatStore, uuid: strin
   const mdEscaped = md.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$/g, '\\$')
 
   const content = `
-    <div style="display:flex;align-items:center;gap:12px;margin-bottom:14px">
-      <a href="${basePath}/requests" style="color:var(--fg-3);text-decoration:none;font-size:13px">&larr; Requests</a>
-      <div style="margin-left:auto">
+    <div style="display:flex;align-items:center;gap:12px;margin-bottom:16px">
+      <a href="${basePath}/requests" style="color:var(--fg-3);text-decoration:none;font-size:13px;display:flex;align-items:center;gap:4px">&larr; <span>Requests</span></a>
+      <div style="margin-left:auto;display:flex;align-items:center;gap:8px">
         <button class="copy-btn" onclick="copyMd()" title="Copy full request as Markdown">${COPY_ICON}<span>Copy as Markdown</span></button>
       </div>
     </div>
 
-    <div class="copy-bar">
-      <code>${entry.uuid}</code>
-      <button class="copy-btn" onclick="copyText('${entry.uuid}', this)" title="Copy ID">${COPY_ICON}</button>
-    </div>
-
-    <div class="copy-bar">
-      <code style="color:var(--fg-1);font-size:13px;font-weight:500">${escapeHtml(requestLine)}</code>
-      ${statusBadge(c.status)}
-      ${durationBadge(c.duration)}
-      <span class="sm dim" style="flex-shrink:0">${timeStr}</span>
-      <button class="copy-btn" onclick="copyText('${escapeHtml(requestLine)}', this)" title="Copy request">${COPY_ICON}</button>
+    <div class="card mb" style="padding:16px 18px">
+      <div style="display:flex;align-items:center;gap:10px;flex-wrap:wrap">
+        <code style="color:var(--fg-1);font-size:14px;font-weight:600;letter-spacing:-.01em">${escapeHtml(requestLine)}</code>
+        ${statusBadge(c.status)}
+        ${durationBadge(c.duration)}
+        <span class="sm dim" style="flex-shrink:0">${timeStr}</span>
+        <button class="copy-btn" onclick="copyText('${escapeHtml(requestLine)}', this)" title="Copy request" style="margin-left:auto">${COPY_ICON}</button>
+      </div>
+      <div style="margin-top:8px">
+        <code class="sm dim" style="font-size:11px">${entry.uuid}</code>
+      </div>
     </div>
 
     <div class="stats">

package/src/dashboard/pages/RequestsPage.ts

@@ -20,7 +20,6 @@ export async function renderRequestsPage(store: HeartbeatStore, basePath: string
   })
 
   const content = `
-    <h1 class="page-title">Requests</h1>
     <div class="card">
       ${table(['Method', 'Path', 'Status', 'Duration', 'IP', 'Time'], rows)}
     </div>

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 },
   ]
 
@@ -51,6 +52,7 @@ export function renderLayout(options: {
   </aside>
   <main>
     <div class="topbar">
+      <h1 class="page-title">${title}</h1>
       <button class="theme-btn" onclick="toggleTheme()" title="Toggle theme">${ICONS.moon}</button>
     </div>
     ${content}
@@ -84,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>`,
 }
 
@@ -156,8 +159,8 @@ body{
 
 /* Main */
 main{margin-left:200px;flex:1;padding:24px 28px;max-width:1200px;position:relative}
-.topbar{display:flex;justify-content:flex-end;margin-bottom:8px}
-.page-title{font-size:18px;font-weight:600;letter-spacing:-.02em;margin-bottom:20px;color:var(--fg-0)}
+.topbar{display:flex;align-items:center;justify-content:space-between;margin-bottom:20px}
+.page-title{font-size:18px;font-weight:600;letter-spacing:-.02em;color:var(--fg-0);margin:0}
 
 /* Cards */
 .card{

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)
+  }
+}