@objectstack/plugin-email 9.8.0 → 9.9.0

package/src/email-service.ts

@@ -95,6 +95,48 @@ export function normalizeMessage(
   return msg;
 }
 
+/** Split a persisted comma-separated address column back into a list. */
+function splitAddresses(v: unknown): string[] {
+  if (v == null) return [];
+  return String(v)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Reconstruct a NormalizedEmailMessage from a persisted `sys_email` row
+ * (the outbox-drain path). Addresses are already canonicalized at insert
+ * time, so this re-splits the stored columns rather than re-validating.
+ * Throws when the row lacks the minimum fields needed to send.
+ */
+export function rowToNormalized(row: Record<string, any>): NormalizedEmailMessage {
+  const to = splitAddresses(row.to_addresses);
+  if (to.length === 0) throw new Error('VALIDATION_FAILED: row has no to_addresses');
+  const from = String(row.from_address ?? '').trim();
+  if (!from) throw new Error('VALIDATION_FAILED: row has no from_address');
+  const subject = String(row.subject ?? '').trim();
+  if (!subject) throw new Error('VALIDATION_FAILED: row has no subject');
+  const text = row.body_text;
+  const html = row.body_html;
+  if ((text == null || text === '') && (html == null || html === '')) {
+    throw new Error('VALIDATION_FAILED: row has neither body_text nor body_html');
+  }
+  const msg: NormalizedEmailMessage = {
+    to,
+    from,
+    subject,
+    ...(text != null && text !== '' ? { text: String(text) } : {}),
+    ...(html != null && html !== '' ? { html: String(html) } : {}),
+  };
+  const cc = splitAddresses(row.cc_addresses);
+  if (cc.length > 0) msg.cc = cc;
+  const bcc = splitAddresses(row.bcc_addresses);
+  if (bcc.length > 0) msg.bcc = bcc;
+  if (row.reply_to) msg.replyTo = String(row.reply_to);
+  return msg;
+}
+
 /**
  * Development transport — never actually sends. Logs to the provided
  * logger and returns a synthetic Message-ID. Useful for local dev,
@@ -186,10 +228,24 @@ export interface EmailServiceOptions {
  *      id when persistence is disabled).
  */
 export class EmailService implements IEmailService {
+  /**
+   * Row ids the service is itself delivering (via `send()`). The
+   * EmailServicePlugin's sys_email afterInsert drain hook consults this
+   * set and skips these rows, so a service-originated `queued` insert is
+   * delivered exactly once (by `send()`) — never double-sent by the hook.
+   * App-originated raw inserts are absent here, so the hook handles them.
+   */
+  private readonly managedRowIds = new Set<string>();
+
   constructor(public options: EmailServiceOptions) {
     if (!options.transport) throw new Error('EmailService: transport is required');
   }
 
+  /** True when this row id is currently being delivered by `send()`. */
+  isServiceManaged(id: string): boolean {
+    return this.managedRowIds.has(id);
+  }
+
   /** Wire (or replace) the template loader after construction. */
   setTemplateLoader(loader: TemplateLoader): void {
     this.options.templateLoader = loader;
@@ -242,17 +298,37 @@ export class EmailService implements IEmailService {
       attempt_count: 0,
     };
 
-    let persistedId: string | undefined;
-    if (this.options.persistence) {
-      try {
-        const res = await this.options.persistence.insert(baseRow);
-        persistedId = typeof res === 'string' ? res : res?.id ?? id;
-      } catch (err: any) {
-        this.options.logger?.warn('EmailService: sys_email persist failed (non-fatal)', { error: err?.message });
+    // Reserve the row id BEFORE persistence.insert so the drain hook
+    // (which fires synchronously inside that insert) sees it as managed
+    // and skips it — `send()` owns this row's delivery.
+    this.managedRowIds.add(id);
+    try {
+      let persistedId: string | undefined;
+      if (this.options.persistence) {
+        try {
+          const res = await this.options.persistence.insert(baseRow);
+          persistedId = typeof res === 'string' ? res : res?.id ?? id;
+          if (persistedId !== id) this.managedRowIds.add(persistedId);
+        } catch (err: any) {
+          this.options.logger?.warn('EmailService: sys_email persist failed (non-fatal)', { error: err?.message });
+        }
       }
+      const rowId = persistedId ?? id;
+      return await this.deliverNormalized(rowId, normalized);
+    } finally {
+      this.managedRowIds.delete(id);
     }
-    const rowId = persistedId ?? id;
+  }
 
+  /**
+   * Deliver a normalized message through the transport (with retry) and
+   * finalize the persisted `sys_email` row (`sent` + message_id + sent_at,
+   * or `failed` + error). Shared by `send()` and `deliverPersistedRow()`.
+   */
+  private async deliverNormalized(
+    rowId: string,
+    normalized: NormalizedEmailMessage,
+  ): Promise<SendEmailResult> {
     const maxAttempts = (this.options.retries ?? 0) + 1;
     let lastError: any;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -284,6 +360,29 @@ export class EmailService implements IEmailService {
     return { id: rowId, status: 'failed', error: errMessage };
   }
 
+  /**
+   * Deliver an ALREADY-PERSISTED `sys_email` row (the outbox-drain path).
+   *
+   * An app (e.g. a sandboxed action that can only `api.write`, never reach
+   * the email service) inserts a `sys_email` row as `status:'queued'`; the
+   * plugin's afterInsert hook calls this to actually transmit it. Unlike
+   * `send()`, this does NOT insert a new row — it reconstructs the message
+   * from the row columns and finalizes that same row in place.
+   */
+  async deliverPersistedRow(row: Record<string, any>): Promise<SendEmailResult> {
+    const rowId = String(row?.id ?? '');
+    if (!rowId) throw new Error('deliverPersistedRow: row.id is required');
+    let normalized: NormalizedEmailMessage;
+    try {
+      normalized = rowToNormalized(row);
+    } catch (err: any) {
+      const errMessage = String(err?.message ?? err ?? 'invalid row').slice(0, 1000);
+      await this.updateRow(rowId, { status: 'failed', error: errMessage, attempt_count: 0 });
+      return { id: rowId, status: 'failed', error: errMessage };
+    }
+    return this.deliverNormalized(rowId, normalized);
+  }
+
   private async updateRow(id: string, patch: Record<string, any>): Promise<void> {
     if (!this.options.persistence?.update) return;
     try {
@@ -333,10 +432,16 @@ export class EmailService implements IEmailService {
       }
     }
 
-    const subject = renderTemplate(row.subject, data);
-    const html = renderTemplate(row.body_html, data);
+    // Render holes with the recipient's locale + reference timezone so
+    // `{{ ts | datetime }}` shows the right wall-clock (ADR-0053 Phase 2).
+    const renderOpts = {
+      ...(input.locale ? { locale: input.locale } : {}),
+      ...(input.timezone ? { timeZone: input.timezone } : {}),
+    };
+    const subject = renderTemplate(row.subject, data, renderOpts);
+    const html = renderTemplate(row.body_html, data, renderOpts);
     const text = row.body_text
-      ? renderTemplate(row.body_text, data)
+      ? renderTemplate(row.body_text, data, renderOpts)
       : htmlToText(html);
 
     const from: EmailAddress | undefined = input.from

package/src/send-template.test.ts

@@ -60,6 +60,34 @@ describe('EmailService.sendTemplate', () => {
     expect(msg.text).toContain('reset: https://x.com/r/abc');
   });
 
+  it('renders a datetime hole in the input reference timezone (ADR-0053 Phase 2)', async () => {
+    const transport = new CaptureTransport();
+    const tpl: EmailTemplateRow = {
+      name: 'order.shipped',
+      locale: 'en-US',
+      subject: 'Shipped',
+      body_html: '<p>Ships {{ shipAt | datetime }}</p>',
+      body_text: 'Ships {{ shipAt | datetime }}',
+      active: true,
+    };
+    const svc = new EmailService({
+      transport,
+      defaultFrom: { address: 'no-reply@x.com' },
+      templateLoader: makeLoader([tpl]),
+    });
+
+    // 2026-06-02T01:30Z → 2026-06-01 in America/New_York.
+    await svc.sendTemplate({
+      template: 'order.shipped',
+      to: 'a@x.com',
+      data: { shipAt: '2026-06-02T01:30:00Z' },
+      timezone: 'America/New_York',
+    });
+
+    expect(transport.sent[0].html).toContain('6/1/26'); // shifted to NY day
+    expect(transport.sent[0].html).not.toContain('2026-06-02T01:30'); // not raw ISO
+  });
+
   it('throws TEMPLATE_NOT_FOUND when loader returns null', async () => {
     const svc = new EmailService({
       transport: new CaptureTransport(),

package/src/template-engine.test.ts

@@ -37,6 +37,49 @@ describe('template-engine', () => {
     it('escapes all standard HTML entities', () => {
       expect(renderTemplate('{{s}}', { s: `&<>"'` })).toBe('&amp;&lt;&gt;&quot;&#39;');
     });
+
+    // ADR-0053 Phase 2: formatter holes reuse the shared formula whitelist.
+    describe('formatter holes', () => {
+      it('applies currency / number formatters', () => {
+        expect(renderTemplate('{{ amt | currency }}', { amt: 1234.5 })).toBe('$1,234.50');
+        expect(renderTemplate('{{ n | number:2 }}', { n: 1000 })).toBe('1,000.00');
+      });
+
+      it('renders datetime in the supplied reference timezone', () => {
+        // 2026-06-02T01:30Z → 2026-06-01 in America/New_York.
+        const data = { ts: '2026-06-02T01:30:00Z' };
+        const ny = renderTemplate('{{ ts | datetime }}', data, { timeZone: 'America/New_York' });
+        expect(ny).toContain('6/1/26');
+        const utc = renderTemplate('{{ ts | datetime }}', data, { timeZone: 'UTC' });
+        expect(utc).toContain('6/2/26');
+      });
+
+      it('still HTML-escapes formatted output unless triple-braced', () => {
+        // A formatter can yield characters needing escaping; default escapes.
+        expect(renderTemplate('{{ s | upper }}', { s: 'a&b' })).toBe('A&amp;B');
+        expect(renderTemplate('{{{ s | upper }}}', { s: 'a&b' })).toBe('A&B');
+      });
+
+      it('falls back to the raw value for an unknown formatter (no throw)', () => {
+        expect(renderTemplate('{{ x | bogus }}', { x: 'hi' })).toBe('hi');
+      });
+
+      it('renders a missing formatted value as empty (never "undefined")', () => {
+        expect(renderTemplate('{{ missing | datetime }}', {})).toBe('');
+      });
+
+      // Regression: the placeholder matcher must stay linear. CodeQL flagged a
+      // polynomial-ReDoS on inputs like `{{{{.` + many tabs; the brace-free
+      // `[^{}]*` capture removes the backtracking. Pathological input resolves
+      // fast and is left verbatim (not a valid path[+formatter] hole).
+      it('handles pathological brace/whitespace input without backtracking', () => {
+        const evil = '{{{{.' + '\t'.repeat(50_000);
+        const start = Date.now();
+        const out = renderTemplate(evil + '}}', {});
+        expect(Date.now() - start).toBeLessThan(1000);
+        expect(typeof out).toBe('string');
+      });
+    });
   });
 
   describe('requireVars', () => {

package/src/template-engine.ts

@@ -9,6 +9,13 @@
  * (e.g. when injecting pre-rendered HTML fragments such as URLs in
  * `<a href="">`).
  *
+ * A hole may carry an optional formatter from the shared formula
+ * whitelist — `{{ order.total | currency:EUR }}`, `{{ ts | datetime }}` —
+ * reusing `@objectstack/formula`'s `formatValue` so dates, money, and
+ * (ADR-0053 Phase 2) reference-timezone `datetime` render identically to
+ * in-app templates. An unknown formatter falls back to the raw string,
+ * keeping the lenient "never throw on render" contract.
+ *
  * Deliberately tiny (no loops / conditionals / partials) — the design
  * stance is that email templates SHOULD be data-only renderings; any
  * branching belongs in the caller. If we ever need more, swap for
@@ -16,7 +23,46 @@
  * runtime; we resist that until a real use case demands it.
  */
 
-const PLACEHOLDER = /(\{\{\{?)\s*([\w.]+)\s*(\}?\}\})/g;
+import { formatValue } from '@objectstack/formula';
+
+// Match a hole: open braces, a BRACE-FREE inner body, close braces. Capturing
+// the inner with `[^{}]*` (a single star over a negated class — no nested
+// quantifier, no overlapping `\s*` groups) keeps the matcher strictly linear:
+// it can never backtrack into a polynomial-ReDoS shape. The inner body is then
+// parsed with plain string ops (`parseHole`) instead of a complex pattern.
+// 1=open(`{{`|`{{{`)  2=inner  3=close(`}}`|`}}}`).
+const PLACEHOLDER = /(\{\{\{?)([^{}]*)(\}\}\}?)/g;
+
+/** Locale + reference timezone for hole formatters (ADR-0053 Phase 2). */
+export interface RenderOptions {
+  locale?: string;
+  timeZone?: string;
+}
+
+// A hole body is a dotted path with an optional `| formatter[:arg]`. Validated
+// against small, already-extracted strings (bounded input → no ReDoS).
+const PATH_RE = /^[\w.]+$/;
+const FILTER_RE = /^(\w+)(?::\s*'?([^']*?)'?)?$/;
+
+interface ParsedHole {
+  path: string;
+  formatter?: string;
+  arg?: string;
+}
+
+/** Parse a hole's inner body into a path + optional formatter. Null if malformed. */
+function parseHole(inner: string): ParsedHole | null {
+  const pipe = inner.indexOf('|');
+  if (pipe === -1) {
+    const path = inner.trim();
+    return PATH_RE.test(path) ? { path } : null;
+  }
+  const path = inner.slice(0, pipe).trim();
+  if (!PATH_RE.test(path)) return null;
+  const m = FILTER_RE.exec(inner.slice(pipe + 1).trim());
+  if (!m) return null;
+  return { path, formatter: m[1], arg: m[2] };
+}
 
 function lookup(data: Record<string, any>, path: string): unknown {
   if (!path) return undefined;
@@ -43,15 +89,37 @@ function escapeHtml(s: string): string {
  * render as empty strings (no throw); call `requireVars()` first if
  * you need strict validation.
  */
-export function renderTemplate(template: string, data: Record<string, any>): string {
+export function renderTemplate(
+  template: string,
+  data: Record<string, any>,
+  opts: RenderOptions = {},
+): string {
   if (!template) return '';
-  return template.replace(PLACEHOLDER, (_match, open: string, path: string, close: string) => {
-    const isUnescaped = open === '{{{' && close === '}}}';
-    const raw = lookup(data, path);
-    if (raw == null) return '';
-    const str = typeof raw === 'string' ? raw : String(raw);
-    return isUnescaped ? str : escapeHtml(str);
-  });
+  return template.replace(
+    PLACEHOLDER,
+    (match: string, open: string, inner: string, close: string) => {
+      const parsed = parseHole(inner);
+      if (!parsed) return match; // not a path[+formatter] hole — leave verbatim
+      const isUnescaped = open === '{{{' && close === '}}}';
+      const raw = lookup(data, parsed.path);
+      let str: string;
+      if (parsed.formatter) {
+        // Formatted holes render '' for a missing value (the formula formatters
+        // treat null as empty), so they never emit "undefined".
+        const formatted = formatValue(parsed.formatter, raw, parsed.arg, {
+          locale: opts.locale,
+          timeZone: opts.timeZone,
+        });
+        str = formatted !== undefined
+          ? formatted
+          : raw == null ? '' : (typeof raw === 'string' ? raw : String(raw)); // unknown formatter → raw
+      } else {
+        if (raw == null) return '';
+        str = typeof raw === 'string' ? raw : String(raw);
+      }
+      return isUnescaped ? str : escapeHtml(str);
+    },
+  );
 }
 
 /**