cds-error-outbox 1.0.0

package/README.md

@@ -0,0 +1,283 @@
+# cds-error-outbox
+
+A production-ready, reusable **SAP CAP** (Node.js) plugin that automatically captures service errors, deduplicates them, and sends batched HTML email notifications — with **zero production dependencies**.
+
+---
+
+## Features
+
+- Hooks into **all CAP services** via `srv.on('error')` — zero manual wiring required
+- Stores errors in a CDS-managed `error.outbox.Errors` DB entity (auto-deployed)
+- **Deduplicates** by `SHA-256(message + service + action)` — increments count instead of creating duplicate rows
+- Sends **batched HTML email reports** on a configurable interval
+- Pluggable email providers: **O365 (Microsoft Graph API)**, **SMTP (nodemailer)**, **Mock (dev/test)**
+- Fully configurable via `cds.env.requires.errorOutbox`
+- **Non-blocking** — error capture is fire-and-forget; the request pipeline is never delayed
+- Never crashes the application — all internal failures are logged and swallowed
+
+---
+
+## Installation
+
+```bash
+npm install cds-error-outbox
+```
+
+Because `package.json` declares `"cds": { "plugin": true }`, CAP automatically loads `index.js` at startup.
+
+> **Important:** Due to how CAP resolves symlinked local packages, you must explicitly require the plugin in your project's `srv/server.js` (or root `server.js`):
+>
+> ```js
+> require('cds-error-outbox');  // ← add as the very first line
+> // ... rest of your server.js
+> ```
+
+---
+
+## Configuration
+
+Add the following to your project's `package.json` under `cds.requires`, or to `.cdsrc.json`:
+
+```json
+{
+  "cds": {
+    "requires": {
+      "errorOutbox": {
+        "enabled": true,
+        "interval": 300000,
+        "batchSize": 50,
+        "dedup": {
+          "enabled": true,
+          "windowMinutes": 10
+        },
+        "mail": {
+          "provider": "o365",
+          "tenantId": "<YOUR_TENANT_ID>",
+          "clientId": "<YOUR_CLIENT_ID>",
+          "clientSecret": "<YOUR_CLIENT_SECRET>",
+          "from": "errors@yourcompany.com",
+          "to": "devops@yourcompany.com"
+        }
+      }
+    }
+  }
+}
+```
+
+### Configuration reference
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Enable/disable the entire plugin |
+| `interval` | number (ms) | `300000` | Batch email job frequency |
+| `batchSize` | number | `50` | Max errors per email batch |
+| `dedup.enabled` | boolean | `true` | Enable hash-based deduplication |
+| `dedup.windowMinutes` | number | `10` | Rolling dedup window in minutes |
+| `mail.provider` | string | `'mock'` | `'o365'` \| `'smtp'` \| `'mock'` |
+| `mail.from` | string | `''` | Sender address |
+| `mail.to` | string | `''` | Recipient(s), comma-separated |
+| `mail.tenantId` | string | `''` | Azure AD tenant ID (O365 only) |
+| `mail.clientId` | string | `''` | Azure AD app client ID (O365 only) |
+| `mail.clientSecret` | string | `''` | Azure AD app client secret (O365 only) |
+| `mail.smtp.host` | string | `''` | SMTP host (SMTP only) |
+| `mail.smtp.port` | number | `587` | SMTP port (SMTP only) |
+| `mail.smtp.secure` | boolean | `false` | Use TLS (SMTP only) |
+| `mail.smtp.auth.user` | string | `''` | SMTP username (SMTP only) |
+| `mail.smtp.auth.pass` | string | `''` | SMTP password (SMTP only) |
+
+---
+
+## Email Providers
+
+### `mock` _(default — development/testing)_
+
+Logs the email subject and metadata to the console. No external calls. Use this during local development.
+
+### `o365` — Microsoft Graph API
+
+Uses the [Microsoft Graph `sendMail` API](https://learn.microsoft.com/en-us/graph/api/user-sendmail) with an OAuth 2.0 **client credentials** flow. No user login is required. Zero additional npm dependencies.
+
+#### O365 Setup
+
+1. Go to [Azure Portal → App Registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps) and click **New registration**
+2. Note the **Application (client) ID** and **Directory (tenant) ID**
+3. Go to **Certificates & Secrets** → **New client secret** — note the secret **Value** (shown once)
+4. Go to **API Permissions** → **Add a permission** → **Microsoft Graph** → **Application permissions**
+   - Add: `Mail.Send`
+5. Click **Grant admin consent** for your organisation
+6. The `mail.from` address must be a **licensed Exchange Online mailbox** that the app registration has permission to send from
+7. Configure `cds.requires.errorOutbox.mail`:
+
+```json
+{
+  "provider": "o365",
+  "tenantId": "<Directory (tenant) ID>",
+  "clientId": "<Application (client) ID>",
+  "clientSecret": "<Client Secret value>",
+  "from": "errors@yourcompany.com",
+  "to": "devops@yourcompany.com"
+}
+```
+
+> **Security:** Never commit `clientSecret` to source control.
+>
+> The O365 provider reads credentials from **env variables as a fallback** — values in `package.json` take priority, but any missing field is automatically picked up from the environment:
+>
+> ```bash
+> export CDS_REQUIRES_ERROROUTBOX_MAIL_TENANTID="xxxx"
+> export CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTID="xxxx"
+> export CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTSECRET="xxxx"
+> export CDS_REQUIRES_ERROROUTBOX_MAIL_FROM="errors@company.com"
+> export CDS_REQUIRES_ERROROUTBOX_MAIL_TO="devops@company.com"
+> ```
+>
+> On BTP / Cloud Foundry use `cf set-env <app> CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTSECRET "<value>"` instead of putting the secret in `manifest.yml`.
+
+### `smtp`
+
+Requires `nodemailer` (optional peer dependency):
+
+```bash
+npm install nodemailer
+```
+
+```json
+{
+  "provider": "smtp",
+  "from": "errors@yourcompany.com",
+  "to": "devops@yourcompany.com",
+  "smtp": {
+    "host": "smtp.yourcompany.com",
+    "port": 587,
+    "secure": false,
+    "auth": { "user": "smtp-user", "pass": "smtp-password" }
+  }
+}
+```
+
+---
+
+## How it works
+
+```
+CAP service throws an error
+         │
+         ▼
+  srv.on('error') — fire-and-forget via setImmediate (non-blocking)
+         │
+         ▼
+  SHA-256( message | service | action )
+         │
+    ┌────┴────┐
+    │         │
+duplicate?   new?
+    │         │
+    ▼         ▼
+ UPDATE     INSERT
+ count+1    count=1
+ lastSeen   firstSeen/lastSeen
+         │
+         ▼
+  setInterval every `interval` ms
+         │
+         ▼
+  SELECT sent=false LIMIT batchSize   (oldest first)
+         │
+         ▼
+  Format HTML (grouped by service)
+         │
+         ▼
+  provider.send(...)
+         │
+         ▼ (only on success)
+  UPDATE sent=true WHERE ID IN [...]
+```
+
+---
+
+## DB Entity
+
+The plugin automatically adds the following entity to your project's database schema:
+
+```cds
+namespace error.outbox;
+
+entity Errors {
+  key ID        : UUID;
+      hash      : String(64);
+      service   : String;
+      action    : String;
+      message   : LargeString;
+      stack     : LargeString;
+      count     : Integer;
+      firstSeen : Timestamp;
+      lastSeen  : Timestamp;
+      sent      : Boolean default false;
+}
+```
+
+After installing the plugin, register the model in your project's `db/` folder. Create a file `db/error-outbox.cds`:
+
+```cds
+using from '../plugins/cds-error-outbox/db/model';
+```
+
+Then run deploy:
+
+```bash
+cds deploy --to sqlite   # local development
+cds build                # production (BTP, HANA)
+```
+
+---
+
+## Environment variables
+
+CAP maps nested config paths to environment variables. You can override any value at runtime without changing `package.json`:
+
+```bash
+CDS_REQUIRES_ERROROUTBOX_ENABLED=true
+CDS_REQUIRES_ERROROUTBOX_INTERVAL=60000
+CDS_REQUIRES_ERROROUTBOX_MAIL_PROVIDER=o365
+CDS_REQUIRES_ERROROUTBOX_MAIL_TENANTID=...
+CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTID=...
+CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTSECRET=...
+CDS_REQUIRES_ERROROUTBOX_MAIL_FROM=errors@yourcompany.com
+CDS_REQUIRES_ERROROUTBOX_MAIL_TO=devops@yourcompany.com
+```
+
+---
+
+## Project structure
+
+```
+cds-error-outbox/
+├── package.json          ← CAP plugin declaration (cds.plugin: true)
+├── index.js              ← Entry point — calls bootstrap.initialize()
+│
+├── config/
+│   └── defaults.js       ← Default config values
+│
+├── lib/
+│   ├── bootstrap.js      ← Init orchestration (cds lifecycle hooks)
+│   ├── config.js         ← Deep merge + config loader (singleton)
+│   ├── interceptor.js    ← srv.on('error') hook (fire-and-forget)
+│   ├── dedup.js          ← SHA-256 hash + DB upsert logic
+│   ├── scheduler.js      ← Interval batch job
+│   └── formatter.js      ← HTML email builder
+│
+├── providers/
+│   ├── index.js          ← Provider factory
+│   ├── o365.js           ← Microsoft Graph API (zero extra deps)
+│   ├── smtp.js           ← nodemailer wrapper (optional peer dep)
+│   └── mock.js           ← Console logger (dev/test)
+│
+└── db/
+    └── model.cds         ← error.outbox.Errors entity
+```
+
+---
+
+## License
+
+MIT

package/config/defaults.js

@@ -0,0 +1,46 @@
+'use strict';
+
+module.exports = {
+  enabled: true,
+
+  /** How often (ms) the batch job runs to send unsent errors. */
+  interval: 300000,
+
+  /** Maximum number of unsent errors to include per email batch. */
+  batchSize: 50,
+
+  dedup: {
+    /** Whether to deduplicate errors by hash within the rolling window. */
+    enabled: true,
+
+    /** Only deduplicate within this time window (minutes). */
+    windowMinutes: 10
+  },
+
+  mail: {
+    /** Email provider: 'o365' | 'smtp' | 'mock' */
+    provider: 'mock',
+
+    /** Sender address (required for o365 and smtp). */
+    from: '',
+
+    /** Recipient address(es) — comma-separated for multiple (required for o365 and smtp). */
+    to: '',
+
+    /** === O365 / Microsoft Graph API options === */
+    tenantId: '',
+    clientId: '',
+    clientSecret: '',
+
+    /** === SMTP options (used only when provider = 'smtp') === */
+    smtp: {
+      host: '',
+      port: 587,
+      secure: false,
+      auth: {
+        user: '',
+        pass: ''
+      }
+    }
+  }
+};

package/db/model.cds

@@ -0,0 +1,18 @@
+namespace error.outbox;
+
+entity Errors {
+  key ID        : UUID;
+
+      hash      : String(64);
+      service   : String;
+      action    : String;
+
+      message   : LargeString;
+      stack     : LargeString;
+
+      count     : Integer;
+      firstSeen : Timestamp;
+      lastSeen  : Timestamp;
+
+      sent      : Boolean default false;
+}

package/index.cds

@@ -0,0 +1 @@
+using from './db/model';

package/index.js

@@ -0,0 +1,14 @@
+'use strict';
+
+/**
+ * cds-error-outbox — CAP plugin entry point.
+ *
+ * CAP automatically requires this file when the package is installed,
+ * because package.json declares `"cds": { "plugin": true }`.
+ *
+ * The bootstrap.initialize() call registers CAP lifecycle listeners
+ * (cds.on('serving') and cds.on('served')) so no blocking work happens here.
+ */
+const { initialize } = require('./lib/bootstrap');
+
+initialize();

package/lib/bootstrap.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const cds = require('@sap/cds');
+const { loadConfig } = require('./config');
+const { attach }     = require('./interceptor');
+const { start }      = require('./scheduler');
+const { getProvider } = require('../providers');
+
+/**
+ * Initialize the cds-error-outbox plugin.
+ *
+ * Called once at plugin load time (from index.js).
+ * Uses CAP lifecycle events to ensure initialization order:
+ *
+ *   cds.on('serving') → attach error interceptor to each served service
+ *   cds.on('served')  → start scheduler (DB is fully connected at this point)
+ */
+function initialize() {
+  // ── Load and validate config ─────────────────────────────────────────────
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    console.error('[cds-error-outbox] Failed to load config — plugin disabled:', err.message);
+    return;
+  }
+
+  if (!config.enabled) {
+    console.info('[cds-error-outbox] Plugin is disabled (config.enabled = false).');
+    return;
+  }
+
+  // ── Resolve email provider ───────────────────────────────────────────────
+  let provider;
+  try {
+    provider = getProvider(config);
+  } catch (err) {
+    console.error('[cds-error-outbox] Failed to load email provider — plugin disabled:', err.message);
+    return;
+  }
+
+  // ── Attach interceptor to every served service ───────────────────────────
+  cds.on('serving', (srv) => {
+    try {
+      attach(srv, config);
+    } catch (err) {
+      console.error(
+        `[cds-error-outbox] Failed to attach interceptor to service "${srv.name}":`,
+        err.message
+      );
+    }
+  });
+
+  // ── Start scheduler after all services + DB are ready ───────────────────
+  // cds.on('served') fires once after ALL services have been bootstrapped
+  // and cds.db is guaranteed to be available.
+  cds.on('served', () => {
+    try {
+      start(config, provider);
+    } catch (err) {
+      console.error('[cds-error-outbox] Failed to start scheduler:', err.message);
+    }
+  });
+
+  console.info(
+    `[cds-error-outbox] Plugin initialized — ` +
+    `provider: ${config.mail.provider}, interval: ${config.interval}ms`
+  );
+}
+
+module.exports = { initialize };

package/lib/config.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const cds = require('@sap/cds');
+const defaults = require('../config/defaults');
+
+let _config = null;
+
+/**
+ * Recursively deep-merge source into target.
+ * Arrays in source replace arrays in target (no merge).
+ *
+ * @param {Object} target
+ * @param {Object} source
+ * @returns {Object}
+ */
+function deepMerge(target, source) {
+  if (!source || typeof source !== 'object') return target;
+
+  const result = Object.assign({}, target);
+
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key];
+    const tgtVal = result[key];
+
+    if (
+      srcVal !== null &&
+      typeof srcVal === 'object' &&
+      !Array.isArray(srcVal) &&
+      tgtVal !== null &&
+      typeof tgtVal === 'object' &&
+      !Array.isArray(tgtVal)
+    ) {
+      result[key] = deepMerge(tgtVal, srcVal);
+    } else if (srcVal !== undefined) {
+      result[key] = srcVal;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load and cache the merged config (defaults + cds.env.requires.errorOutbox).
+ * @returns {Object}
+ */
+function loadConfig() {
+  if (_config) return _config;
+
+  const userConfig =
+    (cds.env &&
+      cds.env.requires &&
+      cds.env.requires.errorOutbox) ||
+    {};
+
+  _config = deepMerge(defaults, userConfig);
+  return _config;
+}
+
+/**
+ * Reset the cached config singleton.
+ * Useful in tests to reload config between test cases.
+ */
+function resetConfig() {
+  _config = null;
+}
+
+module.exports = { loadConfig, resetConfig, deepMerge };

package/lib/dedup.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const ENTITY = 'error.outbox.Errors';
+
+// Truncation limits to prevent oversized DB entries
+const MAX_MESSAGE_LEN = 5000;
+const MAX_STACK_LEN = 10000;
+
+/**
+ * Creates a deterministic SHA-256 hash from the error's message, service, and action.
+ * Used as the dedup key.
+ *
+ * @param {string} message
+ * @param {string} service
+ * @param {string} action
+ * @returns {string} 64-character hex string
+ */
+function createHash(message, service, action) {
+  return crypto
+    .createHash('sha256')
+    .update(`${message}|${service}|${action}`)
+    .digest('hex');
+}
+
+/**
+ * Find an existing unsent error record matching the given hash within the dedup window.
+ *
+ * @param {object} db  - connected cds.db instance
+ * @param {string} hash
+ * @param {number} windowMinutes
+ * @returns {Promise<object|null>}
+ */
+async function findExistingError(db, hash, windowMinutes) {
+  const cutoff = new Date(Date.now() - windowMinutes * 60 * 1000).toISOString();
+
+  const results = await db.run(
+    SELECT.from(ENTITY)
+      .where({ hash })
+      .and('lastSeen >', cutoff)
+      .and({ sent: false })
+      .limit(1)
+  );
+
+  return results && results.length > 0 ? results[0] : null;
+}
+
+/**
+ * Insert a new error row or increment the count on an existing one.
+ * Deduplication is based on the hash + dedup window + sent=false.
+ *
+ * @param {object} db      - connected cds.db instance
+ * @param {object} errorData - { message, stack, service, action }
+ * @param {object} config  - merged plugin config
+ */
+async function upsertError(db, errorData, config) {
+  const { message, stack, service, action } = errorData;
+
+  const hash = createHash(message, service, action);
+  const now = new Date().toISOString();
+
+  const existing = config.dedup.enabled
+    ? await findExistingError(db, hash, config.dedup.windowMinutes)
+    : null;
+
+  if (existing) {
+    await db.run(
+      UPDATE(ENTITY)
+        .set({ count: existing.count + 1, lastSeen: now })
+        .where({ ID: existing.ID })
+    );
+  } else {
+    await db.run(
+      INSERT.into(ENTITY).entries({
+        ID: crypto.randomUUID(),
+        hash,
+        service: String(service || 'unknown'),
+        action: String(action || 'unknown'),
+        message: message ? String(message).substring(0, MAX_MESSAGE_LEN) : '',
+        stack: stack ? String(stack).substring(0, MAX_STACK_LEN) : '',
+        count: 1,
+        firstSeen: now,
+        lastSeen: now,
+        sent: false
+      })
+    );
+  }
+}
+
+module.exports = { createHash, findExistingError, upsertError };

package/lib/formatter.js

@@ -0,0 +1,214 @@
+'use strict';
+
+/**
+ * Escape special HTML characters to prevent injection in the email body.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Build an HTML email body from an array of error records, grouped by service.
+ *
+ * @param {object[]} errors - array of error.outbox.Errors records
+ * @returns {{ subject: string, html: string }}
+ */
+function formatHtmlEmail(errors) {
+  const timestamp = new Date().toISOString();
+  const total = errors.reduce((sum, e) => sum + (e.count || 1), 0);
+
+  // Group records by service name
+  const groups = {};
+  for (const err of errors) {
+    const key = err.service || 'unknown';
+    if (!groups[key]) groups[key] = [];
+    groups[key].push(err);
+  }
+
+  const subject = `[CAP Error Outbox] ${total} occurrence(s) in ${errors.length} error(s) — ${timestamp}`;
+
+  const fmt = (ts) => ts ? String(ts).replace('T', ' ').replace(/\.\d{3}Z$/, ' UTC') : '-';
+
+  // ── Outlook-safe HTML email ──────────────────────────────────────────────
+  // Rules applied:
+  //  1. Every colored cell has BOTH bgcolor="" attribute AND style="background:"
+  //  2. Text colors use style="color:" on the immediate element (not parent)
+  //  3. No border-radius, no box-shadow, no gradients, no flexbox
+  //  4. display:block only via <p> tags, never on <span>
+  //  5. Table widths via width="" attribute, not just CSS
+  //  6. valign/align attributes used alongside CSS vertical-align/text-align
+
+  let html = `<!DOCTYPE html>
+<html lang="en" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <meta name="color-scheme" content="light only">
+  <meta name="supported-color-schemes" content="light only">
+  <!--[if mso]><noscript><xml><o:OfficeDocumentSettings><o:AllowPNG/><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml></noscript><![endif]-->
+  <style>
+    body, table, td, p, a { -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; }
+    table, td { mso-table-lspace:0pt; mso-table-rspace:0pt; border-collapse:collapse; }
+    img { border:0; outline:none; text-decoration:none; }
+    /* Prevent Outlook dark mode */
+    [data-ogsc] body, [data-ogsb] body { background:#f4f4f4 !important; color:#222222 !important; }
+  </style>
+</head>
+<body style="margin:0;padding:0;background-color:#f4f4f4;" bgcolor="#f4f4f4">
+
+<table width="100%" cellpadding="0" cellspacing="0" border="0" bgcolor="#f4f4f4" style="background-color:#f4f4f4;">
+  <tr>
+    <td align="center" style="padding:20px 10px;">
+
+      <!-- WRAPPER -->
+      <table width="700" cellpadding="0" cellspacing="0" border="0" style="width:700px;background-color:#ffffff;" bgcolor="#ffffff">
+
+        <!-- HEADER -->
+        <tr>
+          <td bgcolor="#b03a2e" style="background-color:#b03a2e;padding:24px 28px 20px;" align="left">
+            <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:20px;font-weight:bold;color:#ffffff;line-height:1.2;">CAP Error Outbox Report</p>
+            <p style="margin:6px 0 0;font-family:Arial,Helvetica,sans-serif;font-size:11px;color:#f4c7c3;line-height:1;">Generated: ${escapeHtml(timestamp)}</p>
+          </td>
+        </tr>
+
+        <!-- STATS -->
+        <tr>
+          <td bgcolor="#ffffff" style="background-color:#ffffff;padding:0;border-bottom:2px solid #e8e8e8;">
+            <table width="100%" cellpadding="0" cellspacing="0" border="0">
+              <tr>
+                <td width="33%" align="center" bgcolor="#ffffff" style="background-color:#ffffff;padding:16px 10px;border-right:1px solid #e8e8e8;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:26px;font-weight:bold;color:#b03a2e;line-height:1;">${errors.length}</p>
+                  <p style="margin:4px 0 0;font-family:Arial,Helvetica,sans-serif;font-size:10px;color:#888888;text-transform:uppercase;letter-spacing:0.5px;line-height:1;">Distinct Errors</p>
+                </td>
+                <td width="34%" align="center" bgcolor="#ffffff" style="background-color:#ffffff;padding:16px 10px;border-right:1px solid #e8e8e8;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:26px;font-weight:bold;color:#b03a2e;line-height:1;">${total}</p>
+                  <p style="margin:4px 0 0;font-family:Arial,Helvetica,sans-serif;font-size:10px;color:#888888;text-transform:uppercase;letter-spacing:0.5px;line-height:1;">Total Occurrences</p>
+                </td>
+                <td width="33%" align="center" bgcolor="#ffffff" style="background-color:#ffffff;padding:16px 10px;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:26px;font-weight:bold;color:#b03a2e;line-height:1;">${Object.keys(groups).length}</p>
+                  <p style="margin:4px 0 0;font-family:Arial,Helvetica,sans-serif;font-size:10px;color:#888888;text-transform:uppercase;letter-spacing:0.5px;line-height:1;">Services Affected</p>
+                </td>
+              </tr>
+            </table>
+          </td>
+        </tr>\n`;
+
+  for (const [service, serviceErrors] of Object.entries(groups)) {
+    html += `
+        <!-- SERVICE: ${escapeHtml(service)} -->
+        <tr>
+          <td bgcolor="#ffffff" style="background-color:#ffffff;padding:20px 28px 4px;">
+
+            <!-- Service label -->
+            <table width="100%" cellpadding="0" cellspacing="0" border="0" style="margin-bottom:10px;">
+              <tr>
+                <td bgcolor="#f8f8f8" style="background-color:#f8f8f8;border-left:3px solid #b03a2e;padding:7px 12px;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:11px;font-weight:bold;color:#333333;text-transform:uppercase;letter-spacing:0.7px;">${escapeHtml(service)}</p>
+                </td>
+              </tr>
+            </table>
+
+            <!-- Error table -->
+            <table width="100%" cellpadding="0" cellspacing="0" border="0" style="border:1px solid #e8e8e8;margin-bottom:16px;">
+              <!-- Table header -->
+              <tr>
+                <td width="24" align="center" bgcolor="#2c3e50" style="background-color:#2c3e50;padding:8px 6px;border-right:1px solid #3d5166;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:10px;font-weight:bold;color:#ffffff;text-transform:uppercase;">#</p>
+                </td>
+                <td width="110" bgcolor="#2c3e50" style="background-color:#2c3e50;padding:8px 10px;border-right:1px solid #3d5166;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:10px;font-weight:bold;color:#ffffff;text-transform:uppercase;letter-spacing:0.4px;">Action</p>
+                </td>
+                <td bgcolor="#2c3e50" style="background-color:#2c3e50;padding:8px 10px;border-right:1px solid #3d5166;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:10px;font-weight:bold;color:#ffffff;text-transform:uppercase;letter-spacing:0.4px;">Message</p>
+                </td>
+                <td width="44" align="center" bgcolor="#2c3e50" style="background-color:#2c3e50;padding:8px 6px;border-right:1px solid #3d5166;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:10px;font-weight:bold;color:#ffffff;text-transform:uppercase;">Cnt</p>
+                </td>
+                <td width="118" bgcolor="#2c3e50" style="background-color:#2c3e50;padding:8px 10px;border-right:1px solid #3d5166;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:10px;font-weight:bold;color:#ffffff;text-transform:uppercase;letter-spacing:0.4px;">First Seen</p>
+                </td>
+                <td width="118" bgcolor="#2c3e50" style="background-color:#2c3e50;padding:8px 10px;">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:10px;font-weight:bold;color:#ffffff;text-transform:uppercase;letter-spacing:0.4px;">Last Seen</p>
+                </td>
+              </tr>\n`;
+
+    serviceErrors.forEach((err, idx) => {
+      const count  = err.count || 1;
+      const rowBg  = idx % 2 === 1 ? '#f9f9f9' : '#ffffff';
+      const bdrClr = '#e8e8e8';
+
+      html += `              <!-- Row ${idx + 1} -->
+              <tr>
+                <td align="center" valign="top" bgcolor="${rowBg}" style="background-color:${rowBg};padding:9px 6px;border-top:1px solid ${bdrClr};border-right:1px solid ${bdrClr};">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:11px;color:#aaaaaa;">${idx + 1}</p>
+                </td>
+                <td valign="top" bgcolor="${rowBg}" style="background-color:${rowBg};padding:9px 10px;border-top:1px solid ${bdrClr};border-right:1px solid ${bdrClr};">
+                  <p style="margin:0;font-family:Consolas,'Courier New',monospace;font-size:11px;color:#2c6fad;background-color:#eef4fb;padding:1px 5px;display:inline-block;">${escapeHtml(err.action || 'unknown')}</p>
+                </td>
+                <td valign="top" bgcolor="${rowBg}" style="background-color:${rowBg};padding:9px 10px;border-top:1px solid ${bdrClr};border-right:1px solid ${bdrClr};">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:12px;font-weight:bold;color:#b03a2e;">${escapeHtml(err.message || '-')}</p>
+                </td>
+                <td align="center" valign="top" bgcolor="${rowBg}" style="background-color:${rowBg};padding:9px 6px;border-top:1px solid ${bdrClr};border-right:1px solid ${bdrClr};">
+                  <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:12px;font-weight:bold;color:#ffffff;background-color:${count >= 10 ? '#922b21' : '#c0392b'};padding:1px 7px;text-align:center;">${count}</p>
+                </td>
+                <td valign="top" bgcolor="${rowBg}" style="background-color:${rowBg};padding:9px 10px;border-top:1px solid ${bdrClr};border-right:1px solid ${bdrClr};">
+                  <p style="margin:0;font-family:Consolas,'Courier New',monospace;font-size:10px;color:#888888;white-space:nowrap;">${escapeHtml(fmt(err.firstSeen))}</p>
+                </td>
+                <td valign="top" bgcolor="${rowBg}" style="background-color:${rowBg};padding:9px 10px;border-top:1px solid ${bdrClr};">
+                  <p style="margin:0;font-family:Consolas,'Courier New',monospace;font-size:10px;color:#888888;white-space:nowrap;">${escapeHtml(fmt(err.lastSeen))}</p>
+                </td>
+              </tr>\n`;
+
+      // Stack trace as a separate full-width row
+      if (err.stack) {
+        const stackExcerpt = err.stack.split('\n').slice(0, 5).join('\n');
+        html += `              <tr>
+                <td valign="top" bgcolor="#fafafa" style="background-color:#fafafa;padding:0 0 0 24px;border-top:none;" colspan="6">
+                  <table width="100%" cellpadding="0" cellspacing="0" border="0">
+                    <tr>
+                      <td bgcolor="#f2f2f2" style="background-color:#f2f2f2;padding:7px 10px;border-top:1px dashed #dddddd;border-left:3px solid #dddddd;">
+                        <p style="margin:0;font-family:Consolas,'Courier New',monospace;font-size:10px;color:#666666;white-space:pre-wrap;line-height:1.5;">${escapeHtml(stackExcerpt)}</p>
+                      </td>
+                    </tr>
+                  </table>
+                </td>
+              </tr>\n`;
+      }
+    });
+
+    html += `            </table>
+
+          </td>
+        </tr>\n`;
+  }
+
+  html += `
+        <!-- FOOTER -->
+        <tr>
+          <td bgcolor="#f4f4f4" style="background-color:#f4f4f4;padding:14px 28px;border-top:1px solid #e8e8e8;" align="center">
+            <p style="margin:0;font-family:Arial,Helvetica,sans-serif;font-size:10px;color:#aaaaaa;">Sent by <strong>cds-error-outbox</strong> &mdash; these errors are marked as sent and will not be repeated until new occurrences are captured.</p>
+          </td>
+        </tr>
+
+      </table>
+      <!-- /WRAPPER -->
+
+    </td>
+  </tr>
+</table>
+
+</body>
+</html>`;
+
+  return { subject, html };
+}
+
+module.exports = { formatHtmlEmail, escapeHtml };

package/lib/interceptor.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const cds = require('@sap/cds');
+const { upsertError } = require('./dedup');
+
+/**
+ * Attach a fire-and-forget error interceptor to the given CDS service.
+ * The handler never blocks or delays the request pipeline — errors are
+ * persisted to the DB asynchronously via setImmediate.
+ *
+ * @param {object} srv    - CDS service instance
+ * @param {object} config - merged plugin config
+ */
+function attach(srv, config) {
+  srv.on('error', (err, req) => {
+    // setImmediate defers DB work to after the current event loop tick,
+    // ensuring the error response is sent to the client without any delay.
+    setImmediate(async () => {
+      try {
+        const message = (err && err.message) ? String(err.message) : String(err);
+        const stack   = (err && err.stack)   ? String(err.stack)   : '';
+        const service = srv.name || 'unknown';
+        const action  =
+          (req && req.event)  ? req.event  :
+          (req && req.path)   ? req.path   :
+          (req && req.method) ? req.method :
+          'unknown';
+
+        // cds.tx() opens a brand-new root-level transaction that is completely
+        // independent of the failed request's already-rolled-back transaction.
+        // Without this, CAP's AsyncLocalStorage would propagate the dead
+        // transaction context into our INSERT/UPDATE, causing the
+        // "Transaction is rolled back" error.
+        await cds.tx(async (tx) => {
+          await upsertError(tx, { message, stack, service, action }, config);
+        });
+      } catch (internalError) {
+        // Never re-throw — log internally to avoid crashing the app.
+        console.error(
+          `[cds-error-outbox] Failed to persist error from service "${srv.name}":`,
+          internalError.message
+        );
+      }
+    });
+  });
+}
+
+module.exports = { attach };

package/lib/scheduler.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const cds = require('@sap/cds');
+const { formatHtmlEmail } = require('./formatter');
+
+const ENTITY = 'error.outbox.Errors';
+
+let _handle = null;
+
+/**
+ * Start the interval-based batch scheduler.
+ *
+ * @param {object} config   - merged plugin config
+ * @param {object} provider - email provider instance ({ send: Function })
+ * @returns {NodeJS.Timeout} interval handle (can be passed to stop())
+ */
+function start(config, provider) {
+  if (_handle) {
+    clearInterval(_handle);
+    _handle = null;
+  }
+
+  _handle = setInterval(() => {
+    runBatch(config, provider).catch((err) => {
+      // runBatch already guards internally; this is a last-resort safety net.
+      console.error('[cds-error-outbox] Unhandled error in runBatch:', err.message);
+    });
+  }, config.interval);
+
+  // Allow Node.js process to exit gracefully even if the interval is active.
+  if (typeof _handle.unref === 'function') _handle.unref();
+
+  console.info(
+    `[cds-error-outbox] Scheduler started — ` +
+    `interval: ${config.interval}ms, batchSize: ${config.batchSize}`
+  );
+
+  return _handle;
+}
+
+/**
+ * Stop the scheduler. Safe to call even if not started.
+ */
+function stop() {
+  if (_handle) {
+    clearInterval(_handle);
+    _handle = null;
+    console.info('[cds-error-outbox] Scheduler stopped.');
+  }
+}
+
+/**
+ * Core batch routine:
+ *   1. Fetch unsent errors from DB (up to batchSize, oldest first).
+ *   2. Format them into an HTML email.
+ *   3. Send via the configured email provider.
+ *   4. Mark successfully sent records as sent=true.
+ *
+ * Each step is independently guarded so a failure in one step does not
+ * prevent the scheduler from running again on the next interval.
+ *
+ * @param {object} config
+ * @param {object} provider
+ */
+async function runBatch(config, provider) {
+  // ── 1. Obtain DB connection ──────────────────────────────────────────────
+  let db;
+  try {
+    db = await cds.connect.to('db');
+  } catch (err) {
+    console.error('[cds-error-outbox] Cannot connect to DB — skipping batch:', err.message);
+    return;
+  }
+
+  // ── 2. Fetch unsent errors ───────────────────────────────────────────────
+  let errors;
+  try {
+    errors = await db.run(
+      SELECT.from(ENTITY)
+        .where({ sent: false })
+        .orderBy('lastSeen asc')
+        .limit(config.batchSize)
+    );
+  } catch (err) {
+    console.error('[cds-error-outbox] Failed to query unsent errors:', err.message);
+    return;
+  }
+
+  if (!errors || errors.length === 0) return;
+
+  // ── 3. Format email ──────────────────────────────────────────────────────
+  let subject, html;
+  try {
+    ({ subject, html } = formatHtmlEmail(errors));
+  } catch (err) {
+    console.error('[cds-error-outbox] Failed to format email body:', err.message);
+    return;
+  }
+
+  // ── 4. Send email ────────────────────────────────────────────────────────
+  try {
+    await provider.send(config.mail, subject, html);
+  } catch (err) {
+    // Do NOT mark as sent — will be retried on the next interval.
+    console.error(
+      `[cds-error-outbox] Email delivery failed (will retry on next interval): ${err.message}`
+    );
+    return;
+  }
+
+  // ── 5. Mark as sent (only after confirmed delivery) ──────────────────────
+  const ids = errors.map((e) => e.ID);
+  try {
+    await db.run(
+      UPDATE(ENTITY)
+        .set({ sent: true })
+        .where({ ID: { in: ids } })
+    );
+    console.info(`[cds-error-outbox] Batch complete — marked ${ids.length} error(s) as sent.`);
+  } catch (err) {
+    console.error('[cds-error-outbox] Failed to mark errors as sent:', err.message);
+  }
+}
+
+module.exports = { start, stop, runBatch };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "cds-error-outbox",
+  "version": "1.0.0",
+  "description": "A reusable CAP plugin that captures service errors, deduplicates them, and sends batched email notifications.",
+  "main": "index.js",
+  "cds": {
+    "plugin": true,
+    "requires": {
+      "cds-error-outbox": {
+        "model": "cds-error-outbox"
+      }
+    }
+  },
+  "keywords": [
+    "sap-cap",
+    "cds",
+    "plugin",
+    "error",
+    "outbox",
+    "email"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@sap/cds": ">=7"
+  },
+  "peerDependenciesMeta": {
+    "nodemailer": {
+      "optional": true
+    }
+  }
+}

package/providers/index.js

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+ * Email provider factory.
+ *
+ * Returns a provider object with a `send(mailConfig, subject, html)` function
+ * based on config.mail.provider. Falls back to 'mock' for unknown values.
+ *
+ * Supported providers:
+ *   'o365'  — Microsoft Graph API (client credentials, no extra deps)
+ *   'smtp'  — nodemailer (optional peer dep: npm install nodemailer)
+ *   'mock'  — console.log only, safe for development/testing
+ *
+ * @param {object} config - merged plugin config
+ * @returns {{ send: Function }}
+ */
+function getProvider(config) {
+  const providerName = (config.mail && config.mail.provider)
+    ? String(config.mail.provider).toLowerCase()
+    : 'mock';
+
+  switch (providerName) {
+    case 'o365':
+      return require('./o365');
+
+    case 'smtp':
+      return require('./smtp');
+
+    case 'mock':
+      return require('./mock');
+
+    default:
+      console.warn(
+        `[cds-error-outbox] Unknown email provider "${providerName}". Falling back to mock.`
+      );
+      return require('./mock');
+  }
+}
+
+module.exports = { getProvider };

package/providers/mock.js

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * Mock email provider — logs to console only.
+ * No external calls are made.
+ *
+ * Use this in development and test environments to verify the plugin
+ * is capturing and formatting errors without needing real mail credentials.
+ *
+ * @param {object} mailConfig
+ * @param {string} subject
+ * @param {string} html
+ */
+async function send(mailConfig, subject, html) {
+  console.log('[cds-error-outbox][mock] ──────────── Email (mock) ────────────');
+  console.log(`[cds-error-outbox][mock]  From   : ${mailConfig.from || '(not configured)'}`);
+  console.log(`[cds-error-outbox][mock]  To     : ${mailConfig.to   || '(not configured)'}`);
+  console.log(`[cds-error-outbox][mock]  Subject: ${subject}`);
+  console.log(`[cds-error-outbox][mock]  HTML   : ${html ? html.length : 0} chars`);
+  console.log('[cds-error-outbox][mock] ─────────────────────────────────────');
+}
+
+module.exports = { send };

package/providers/o365.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const https    = require('https');
+const qs       = require('querystring');
+
+/**
+ * Obtain an OAuth 2.0 access token using the client credentials grant.
+ * Endpoint: POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
+ *
+ * @param {object} mailConfig - { tenantId, clientId, clientSecret }
+ * @returns {Promise<string>} Bearer access token
+ */
+function getAccessToken(mailConfig) {
+  // Values from config take precedence; env variables are the fallback.
+  // Supported env variables:
+  //   CDS_REQUIRES_ERROROUTBOX_MAIL_TENANTID
+  //   CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTID
+  //   CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTSECRET
+  const tenantId     = mailConfig.tenantId     || process.env.CDS_REQUIRES_ERROROUTBOX_MAIL_TENANTID     || process.env.ERROR_OUTBOX_TENANT_ID;
+  const clientId     = mailConfig.clientId     || process.env.CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTID     || process.env.ERROR_OUTBOX_CLIENT_ID;
+  const clientSecret = mailConfig.clientSecret || process.env.CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTSECRET || process.env.ERROR_OUTBOX_CLIENT_SECRET;
+
+  if (!tenantId || !clientId || !clientSecret) {
+    return Promise.reject(
+      new Error(
+        '[cds-error-outbox][o365] tenantId, clientId, and clientSecret are required. ' +
+        'Set them in cds.requires.errorOutbox.mail or via env variables: ' +
+        'CDS_REQUIRES_ERROROUTBOX_MAIL_TENANTID, CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTID, CDS_REQUIRES_ERROROUTBOX_MAIL_CLIENTSECRET'
+      )
+    );
+  }
+
+  const body = qs.stringify({
+    grant_type:    'client_credentials',
+    client_id:     clientId,
+    client_secret: clientSecret,
+    scope:         'https://graph.microsoft.com/.default'
+  });
+
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'login.microsoftonline.com',
+      path:     `/${encodeURIComponent(tenantId)}/oauth2/v2.0/token`,
+      method:   'POST',
+      headers: {
+        'Content-Type':   'application/x-www-form-urlencoded',
+        'Content-Length': Buffer.byteLength(body)
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.access_token) {
+            resolve(parsed.access_token);
+          } else {
+            reject(
+              new Error(
+                `[cds-error-outbox][o365] Token request failed: ` +
+                (parsed.error_description || parsed.error || `HTTP ${res.statusCode}`)
+              )
+            );
+          }
+        } catch (e) {
+          reject(new Error(`[cds-error-outbox][o365] Failed to parse token response: ${e.message}`));
+        }
+      });
+    });
+
+    req.on('error', (err) =>
+      reject(new Error(`[cds-error-outbox][o365] Token HTTPS request error: ${err.message}`))
+    );
+
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Send an email via Microsoft Graph API (POST /users/{from}/sendMail).
+ *
+ * Required Azure AD app permission: Mail.Send (application, not delegated).
+ * The `from` address must be a licensed Exchange Online mailbox.
+ *
+ * @param {object} mailConfig - { tenantId, clientId, clientSecret, from, to }
+ * @param {string} subject
+ * @param {string} html
+ */
+async function send(mailConfig, subject, html) {
+  const from = mailConfig.from || process.env.CDS_REQUIRES_ERROROUTBOX_MAIL_FROM || process.env.ERROR_OUTBOX_FROM;
+  const to   = mailConfig.to   || process.env.CDS_REQUIRES_ERROROUTBOX_MAIL_TO   || process.env.ERROR_OUTBOX_TO;
+
+  if (!from || !to) {
+    throw new Error(
+      '[cds-error-outbox][o365] mail.from and mail.to are required. ' +
+      'Set them in cds.requires.errorOutbox.mail or via env variables: ' +
+      'CDS_REQUIRES_ERROROUTBOX_MAIL_FROM, CDS_REQUIRES_ERROROUTBOX_MAIL_TO'
+    );
+  }
+
+  const accessToken = await getAccessToken(mailConfig);
+
+  // Support comma-separated recipient list
+  const toRecipients = String(to)
+    .split(',')
+    .map((addr) => ({ emailAddress: { address: addr.trim() } }));
+
+  const payload = JSON.stringify({
+    message: {
+      subject,
+      body: {
+        contentType: 'HTML',
+        content: html
+      },
+      from: {
+        emailAddress: { address: from }
+      },
+      toRecipients
+    },
+    saveToSentItems: false
+  });
+
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'graph.microsoft.com',
+      path:     `/v1.0/users/${encodeURIComponent(from)}/sendMail`,
+      method:   'POST',
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'Content-Type':  'application/json',
+        'Content-Length': Buffer.byteLength(payload)
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        // Graph API returns 202 Accepted on success (no body)
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve();
+        } else {
+          reject(
+            new Error(
+              `[cds-error-outbox][o365] sendMail failed — HTTP ${res.statusCode}: ${data}`
+            )
+          );
+        }
+      });
+    });
+
+    req.on('error', (err) =>
+      reject(new Error(`[cds-error-outbox][o365] sendMail HTTPS request error: ${err.message}`))
+    );
+
+    req.write(payload);
+    req.end();
+  });
+}
+
+module.exports = { send, getAccessToken };

package/providers/smtp.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * SMTP email provider using nodemailer.
+ *
+ * nodemailer is an optional peer dependency — install it separately:
+ *   npm install nodemailer
+ *
+ * Required config under mail.smtp:
+ *   host, port, secure, auth.user, auth.pass
+ *
+ * @param {object} mailConfig
+ * @param {string} subject
+ * @param {string} html
+ */
+async function send(mailConfig, subject, html) {
+  let nodemailer;
+  try {
+    nodemailer = require('nodemailer');
+  } catch (_) {
+    throw new Error(
+      '[cds-error-outbox][smtp] nodemailer is not installed. ' +
+      'Run: npm install nodemailer'
+    );
+  }
+
+  const { from, to, smtp } = mailConfig;
+
+  if (!from || !to) {
+    throw new Error(
+      '[cds-error-outbox][smtp] mail.from and mail.to must be configured.'
+    );
+  }
+
+  if (!smtp || !smtp.host) {
+    throw new Error(
+      '[cds-error-outbox][smtp] mail.smtp.host must be configured for the SMTP provider.'
+    );
+  }
+
+  const transportOptions = {
+    host:   smtp.host,
+    port:   smtp.port   !== undefined ? smtp.port   : 587,
+    secure: smtp.secure !== undefined ? smtp.secure : false
+  };
+
+  // Only set auth if credentials are provided (some internal SMTP relays don't require auth)
+  if (smtp.auth && smtp.auth.user) {
+    transportOptions.auth = {
+      user: smtp.auth.user,
+      pass: smtp.auth.pass
+    };
+  }
+
+  const transporter = nodemailer.createTransport(transportOptions);
+
+  // Normalise comma-separated recipients
+  const toAddresses = String(to)
+    .split(',')
+    .map((a) => a.trim())
+    .join(', ');
+
+  await transporter.sendMail({
+    from,
+    to: toAddresses,
+    subject,
+    html
+  });
+}
+
+module.exports = { send };