@objectstack/plugin-email 9.8.0 → 9.9.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/plugin-email@9.8.0 build /home/runner/work/framework/framework/packages/plugins/plugin-email
+> @objectstack/plugin-email@9.9.0 build /home/runner/work/framework/framework/packages/plugins/plugin-email
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     34.07 KB
-ESM dist/index.mjs.map 72.66 KB
-ESM ⚡️ Build success in 89ms
-CJS dist/index.js     35.81 KB
-CJS dist/index.js.map 74.00 KB
-CJS ⚡️ Build success in 94ms
+ESM dist/index.mjs     40.23 KB
+ESM dist/index.mjs.map 86.52 KB
+ESM ⚡️ Build success in 137ms
+CJS dist/index.js     41.99 KB
+CJS dist/index.js.map 87.87 KB
+CJS ⚡️ Build success in 147ms
 DTS Build start
-DTS ⚡️ Build success in 18829ms
-DTS dist/index.d.mts 10.14 KB
-DTS dist/index.d.ts  10.14 KB
+DTS ⚡️ Build success in 18230ms
+DTS dist/index.d.mts 10.30 KB
+DTS dist/index.d.ts  10.30 KB

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @objectstack/plugin-email
 
+## 9.9.0
+
+### Minor Changes
+
+- 575448d: feat(formula,email): render `datetime` in a reference timezone (ADR-0053 Phase 2)
+
+  `datetime` template holes now render in a reference timezone's wall-clock when one is supplied, at the presentation boundary — storage stays UTC.
+
+  - **Formula template engine** — the `datetime` formatter takes the reference timezone from `EvalContext.timezone` (threaded in #1980) and passes it to `Intl.DateTimeFormat`. `{{ ts | datetime }}` renders in that zone; `{{ ts | datetime:iso }}` stays UTC (machine-readable). Calendar-day `date` rendering is intentionally **unchanged** (tz-naive — a `Field.date` has no zone). New exported `formatValue(name, value, arg, { locale, timeZone })` makes the whitelisted formatters reusable outside the full CEL template engine.
+  - **Email pipeline** — `plugin-email`'s renderer previously bypassed the formatter pipeline (`String()` only), so a datetime went out as raw ISO. Email holes now accept the shared formula formatters — `{{ order.total | currency }}`, `{{ ts | datetime }}` — reusing `formatValue` (single source of truth), while keeping the engine's HTML-escaping and `{{{ }}}` raw-output semantics. `SendTemplateInput.timezone` (mirroring the existing `locale`) flows into rendering so an email's datetime shows the recipient's wall-clock.
+
+### Patch Changes
+
+- Updated dependencies [84249a4]
+- Updated dependencies [11af299]
+- Updated dependencies [d5774b5]
+- Updated dependencies [134043a]
+- Updated dependencies [90108e0]
+- Updated dependencies [9afeb2d]
+- Updated dependencies [6bec07e]
+- Updated dependencies [601cc11]
+- Updated dependencies [d99a75a]
+- Updated dependencies [575448d]
+  - @objectstack/spec@9.9.0
+  - @objectstack/core@9.9.0
+  - @objectstack/formula@9.9.0
+  - @objectstack/platform-objects@9.9.0
+
 ## 9.8.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -149,12 +149,17 @@ interface EmailServiceOptions {
     defaultTemplateContext?: Record<string, unknown>;
 }
 
+/** Locale + reference timezone for hole formatters (ADR-0053 Phase 2). */
+interface RenderOptions {
+    locale?: string;
+    timeZone?: string;
+}
 /**
  * Render `template` with values from `data`. Missing placeholders
  * render as empty strings (no throw); call `requireVars()` first if
  * you need strict validation.
  */
-declare function renderTemplate(template: string, data: Record<string, any>): string;
+declare function renderTemplate(template: string, data: Record<string, any>, opts?: RenderOptions): string;
 /**
  * Throw `Error('MISSING_VARIABLES: a, b')` when required vars are
  * absent from `data`. Used by `IEmailService.sendTemplate()` to

package/dist/index.d.ts

@@ -149,12 +149,17 @@ interface EmailServiceOptions {
     defaultTemplateContext?: Record<string, unknown>;
 }
 
+/** Locale + reference timezone for hole formatters (ADR-0053 Phase 2). */
+interface RenderOptions {
+    locale?: string;
+    timeZone?: string;
+}
 /**
  * Render `template` with values from `data`. Missing placeholders
  * render as empty strings (no throw); call `requireVars()` first if
  * you need strict validation.
  */
-declare function renderTemplate(template: string, data: Record<string, any>): string;
+declare function renderTemplate(template: string, data: Record<string, any>, opts?: RenderOptions): string;
 /**
  * Throw `Error('MISSING_VARIABLES: a, b')` when required vars are
  * absent from `data`. Used by `IEmailService.sendTemplate()` to

package/dist/index.js

@@ -43,7 +43,22 @@ module.exports = __toCommonJS(index_exports);
 var import_audit = require("@objectstack/platform-objects/audit");
 
 // src/template-engine.ts
-var PLACEHOLDER = /(\{\{\{?)\s*([\w.]+)\s*(\}?\}\})/g;
+var import_formula = require("@objectstack/formula");
+var PLACEHOLDER = /(\{\{\{?)([^{}]*)(\}\}\}?)/g;
+var PATH_RE = /^[\w.]+$/;
+var FILTER_RE = /^(\w+)(?::\s*'?([^']*?)'?)?$/;
+function parseHole(inner) {
+  const pipe = inner.indexOf("|");
+  if (pipe === -1) {
+    const path2 = inner.trim();
+    return PATH_RE.test(path2) ? { path: path2 } : 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, path) {
   if (!path) return void 0;
   const parts = path.split(".");
@@ -57,15 +72,29 @@ function lookup(data, path) {
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
-function renderTemplate(template, data) {
+function renderTemplate(template, data, opts = {}) {
   if (!template) return "";
-  return template.replace(PLACEHOLDER, (_match, open, path, close) => {
-    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, open, inner, close) => {
+      const parsed = parseHole(inner);
+      if (!parsed) return match;
+      const isUnescaped = open === "{{{" && close === "}}}";
+      const raw = lookup(data, parsed.path);
+      let str;
+      if (parsed.formatter) {
+        const formatted = (0, import_formula.formatValue)(parsed.formatter, raw, parsed.arg, {
+          locale: opts.locale,
+          timeZone: opts.timeZone
+        });
+        str = formatted !== void 0 ? formatted : raw == null ? "" : typeof raw === "string" ? raw : String(raw);
+      } else {
+        if (raw == null) return "";
+        str = typeof raw === "string" ? raw : String(raw);
+      }
+      return isUnescaped ? str : escapeHtml(str);
+    }
+  );
 }
 function requireVars(data, required) {
   const missing = required.filter((name) => lookup(data, name) == null);
@@ -154,6 +183,36 @@ function normalizeMessage(input, defaultFrom) {
   if (input.headers && Object.keys(input.headers).length > 0) msg.headers = input.headers;
   return msg;
 }
+function splitAddresses(v) {
+  if (v == null) return [];
+  return String(v).split(",").map((s) => s.trim()).filter(Boolean);
+}
+function rowToNormalized(row) {
+  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 = {
+    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;
+}
 var LogTransport = class {
   constructor(logger) {
     this.logger = logger;
@@ -185,8 +244,20 @@ function newId() {
 var EmailService = class {
   constructor(options) {
     this.options = options;
+    /**
+     * 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.
+     */
+    this.managedRowIds = /* @__PURE__ */ new Set();
     if (!options.transport) throw new Error("EmailService: transport is required");
   }
+  /** True when this row id is currently being delivered by `send()`. */
+  isServiceManaged(id) {
+    return this.managedRowIds.has(id);
+  }
   /** Wire (or replace) the template loader after construction. */
   setTemplateLoader(loader) {
     this.options.templateLoader = loader;
@@ -232,16 +303,30 @@ var EmailService = class {
       status: "queued",
       attempt_count: 0
     };
-    let persistedId;
-    if (this.options.persistence) {
-      try {
-        const res = await this.options.persistence.insert(baseRow);
-        persistedId = typeof res === "string" ? res : res?.id ?? id;
-      } catch (err) {
-        this.options.logger?.warn("EmailService: sys_email persist failed (non-fatal)", { error: err?.message });
+    this.managedRowIds.add(id);
+    try {
+      let persistedId;
+      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) {
+          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()`.
+   */
+  async deliverNormalized(rowId, normalized) {
     const maxAttempts = (this.options.retries ?? 0) + 1;
     let lastError;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -271,6 +356,28 @@ var EmailService = class {
     });
     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) {
+    const rowId = String(row?.id ?? "");
+    if (!rowId) throw new Error("deliverPersistedRow: row.id is required");
+    let normalized;
+    try {
+      normalized = rowToNormalized(row);
+    } catch (err) {
+      const errMessage = String(err?.message ?? err ?? "invalid row").slice(0, 1e3);
+      await this.updateRow(rowId, { status: "failed", error: errMessage, attempt_count: 0 });
+      return { id: rowId, status: "failed", error: errMessage };
+    }
+    return this.deliverNormalized(rowId, normalized);
+  }
   async updateRow(id, patch) {
     if (!this.options.persistence?.update) return;
     try {
@@ -316,9 +423,13 @@ var EmailService = class {
         this.options.logger?.warn("EmailService: variables_json parse failed (ignored)", { template: input.template });
       }
     }
-    const subject = renderTemplate(row.subject, data);
-    const html = renderTemplate(row.body_html, data);
-    const text = row.body_text ? renderTemplate(row.body_text, data) : htmlToText(html);
+    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, renderOpts) : htmlToText(html);
     const from = input.from ?? (row.from_address ? { address: row.from_address, ...row.from_name ? { name: row.from_name } : {} } : void 0);
     const sendInput = {
       to: input.to,
@@ -792,6 +903,47 @@ var EmailServicePlugin = class {
       if (persistence) this.service.setPersistence(persistence);
       this.service.setTemplateLoader(templateLoader);
       ctx.logger.info("EmailServicePlugin: sys_email persistence + template loader enabled");
+      if (persistence && typeof engine.registerHook === "function") {
+        const svc = this.service;
+        const DRAIN_PKG = "com.objectstack.service.email.drain";
+        if (typeof engine.unregisterHooksByPackage === "function") {
+          engine.unregisterHooksByPackage(DRAIN_PKG);
+        }
+        engine.registerHook(
+          "afterInsert",
+          async (hookCtx) => {
+            try {
+              if (hookCtx?.object !== "sys_email") return;
+              const row = hookCtx?.result;
+              if (!row || typeof row !== "object") return;
+              if (row.status !== "queued" || row.message_id) return;
+              const rowId = row.id != null ? String(row.id) : "";
+              if (!rowId || svc.isServiceManaged(rowId)) return;
+              setTimeout(() => {
+                void (async () => {
+                  try {
+                    const rows = await engine.find("sys_email", {
+                      where: { id: rowId },
+                      limit: 1,
+                      context: SYSTEM_CTX
+                    });
+                    const fresh = Array.isArray(rows) ? rows[0] : rows?.data?.[0];
+                    const target = fresh ?? row;
+                    if (target.status !== "queued" || target.message_id) return;
+                    await svc.deliverPersistedRow(target);
+                  } catch (err) {
+                    ctx.logger.warn(`EmailServicePlugin: outbox drain failed for ${rowId}: ${err?.message ?? err}`);
+                  }
+                })();
+              }, 0);
+            } catch (err) {
+              ctx.logger.warn(`EmailServicePlugin: outbox drain hook error: ${err?.message ?? err}`);
+            }
+          },
+          { packageId: DRAIN_PKG }
+        );
+        ctx.logger.info("EmailServicePlugin: sys_email outbox drain hook installed");
+      }
       try {
         const queue = ctx.getService("queue");
         if (queue && typeof queue.subscribe === "function" && this.service) {