feat(automation): notify nodes reference email templates for localized delivery — resolve (name, recipient locale) at delivery time

.changeset/notify-node-email-template-locale-bridge.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-automation": minor
+"@objectstack/service-messaging": minor
+---
+
+feat(automation): flow `notify` nodes can reference an email template for localized delivery — `template` + `templateData` on `NotifyNodeConfig`, resolved by `(name, recipient locale)` at delivery time (#9205)
+
+Ruled 「立项，走 emailTemplates 路线」: instead of widening the `flows`
+translation surface (whose guidance excludes notification text, #7646), a
+`notify` node now bridges to the existing localized email-template subsystem.
+
+- **Spec** — `NotifyConfigSchema` gains `template` (a `sys_email_template`
+ name, read raw like `topic`/`channels`) and `templateData` (render context
+ for the template's `{{var}}` holes; values interpolate `{token}` templates
+ per run) as the localizable alternative to inline `title`/`message`. Inline
+ strings stay fully valid and byte-identical for existing flows — they are
+ the non-localizable path, and the describes now say so. A node carrying BOTH
+ paths, or `templateData` without `template`, or NEITHER path, is refused
+ loudly with the fix in the message (the `objectNavTargetExclusivity`
+ posture: unrepresentable over silent precedence).
+- **service-automation** — the notify executor forwards the template
+ reference and its interpolated render context in the emit payload (the
+ outbox snapshots it onto each delivery row), and no longer demands an
+ inline title when a template is referenced.
+- **service-messaging** — the email channel routes a template-carrying
+ delivery through `IEmailService.sendTemplate({ template, locale, data })`,
+ resolving the recipient locale per delivery: `payload.locale` if the
+ producer set one, else the deployment default
+ (`II18nService.getDefaultLocale()`, the #8195 ruled source), else
+ `sendTemplate`'s documented `en-US` ladder. Template-resolution failures
+ (`TEMPLATE_NOT_FOUND` / `TEMPLATE_INACTIVE` / `MISSING_VARIABLES`, and an
+ email service without `sendTemplate`) are graded `permanent` — dead
+ immediately with the code on the delivery row, instead of burning the retry
+ schedule on metadata that cannot fix itself.
+
+The inbox channel keeps its existing rendering (notification title/body,
+falling back to the topic on the template path): it has no locale-capable
+rendering seam to the email-template subsystem today, and that gap is
+documented in the PR rather than papered over with a duplicated resolver.

content/docs/references/automation/io-node-config.mdx

@@ -96,8 +96,10 @@ const result = HttpConfigSchema.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **recipients** | `string \| string[]` | ✅ | Recipient user id(s) / audience selector(s); `{token}` templates resolve per run |
-| **title** | `string` | ✅ | Notification title |
-| **message** | `string` | optional | Notification body |
+| **title** | `string` | optional | Notification title, sent to every recipient verbatim (not localizable — use `template` for per-locale content). Either this or `template` is required; the two are mutually exclusive. |
+| **message** | `string` | optional | Notification body, sent verbatim like `title` (not localizable). Only valid with inline `title`, never with `template`. |
+| **template** | `string` | optional | Email template name (`sys_email_template.name`, e.g. `crm.large_deal_won`) — the localizable content path: the delivery path resolves `(name, recipient locale)` at delivery time and renders subject/body per recipient. Mutually exclusive with inline `title`/`message`, which are the non-localizable path. Read raw — no `{token}` interpolation. |
+| **templateData** | `Record<string, any>` | optional | Render context for the referenced template's `{{var}}` placeholders; values interpolate `{token}` templates per run. Only valid together with `template`. |
 | **channels** | `string \| string[]` | optional | Channels to fan out to (default: inbox) |
 | **topic** | `string` | optional | Event topic (default: "notify") |
 | **severity** | `Enum<'info' \| 'warning' \| 'critical'>` | optional | Severity forwarded to the messaging service |

packages/services/service-automation/src/builtin/notify-node.test.ts

@@ -210,6 +210,48 @@ describe('notify (baseline node)', () => {
  expect(result.error).toContain('title');
  });
 
+ // ── #9205 — the localizable content path: template references ────────
+ it('emits the template reference + interpolated templateData instead of inline content', async () => {
+ engine.registerFlow('notify_flow', notifyFlow({
+ topic: 'deal.won',
+ recipients: ['user_1'],
+ channels: ['inbox', 'email'],
+ template: 'crm.large_deal_won',
+ templateData: { dealName: '{dealName}', dealUrl: '/opps/{dealId}' },
+ }));
+
+ const result = await engine.execute('notify_flow', {
+ params: { dealName: 'Acme', dealId: '42' },
+ } as any);
+
+ expect(result.success).toBe(true);
+ expect(messaging.emitted).toHaveLength(1);
+ const payload = messaging.emitted[0].payload;
+ // The reference rides RAW (a static metadata cross-reference); its
+ // render context is interpolated per run — that pair is what the
+ // email channel resolves per recipient locale at delivery time.
+ expect(payload.template).toBe('crm.large_deal_won');
+ expect(payload.templateData).toEqual({ dealName: 'Acme', dealUrl: '/opps/42' });
+ // No inline content keys on this path: a channel without template
+ // support falls back to the topic, the honest degraded rendering —
+ // not an empty string masquerading as content.
+ expect(payload).not.toHaveProperty('title');
+ expect(payload).not.toHaveProperty('body');
+ });
+
+ it('refuses a node carrying BOTH template and inline title (the contract superRefine, at the parse seam)', async () => {
+ engine.registerFlow('notify_flow', notifyFlow({
+ recipients: ['user_1'],
+ title: 'Deal won',
+ template: 'crm.large_deal_won',
+ }));
+ const result = await engine.execute('notify_flow');
+ expect(result.success).toBe(false);
+ expect(result.error).toContain('`template`');
+ expect(result.error).toContain('`title`');
+ expect(messaging.emitted).toHaveLength(0);
+ });
+
  it('fails the step when no recipient is given', async () => {
  engine.registerFlow('notify_flow', notifyFlow({ title: 'Hi' }));
  const result = await engine.execute('notify_flow');

packages/services/service-automation/src/builtin/notify-node.ts

@@ -168,8 +168,27 @@ export function registerNotifyNode(engine: AutomationEngine, ctx: PluginContext)
  recipients: {
  description: 'Recipient user id(s) / audience selector(s)',
  },
- title: { type: 'string', description: 'Notification title' },
- message: { type: 'string', description: 'Notification body' },
+ title: {
+ type: 'string',
+ description: 'Notification title, sent verbatim (not localizable — use template for per-locale content). Either this or template is required; mutually exclusive with template.',
+ },
+ message: {
+ type: 'string',
+ description: 'Notification body, sent verbatim (not localizable). Only valid with inline title, never with template.',
+ },
+ // ── Localizable content path (#9205) ─────────────────────
+ // Mirrors `NotifyConfigSchema.template`/`templateData`; the
+ // mutual exclusion with title/message lives in the Zod
+ // contract's superRefine (executed at parse time), matching
+ // how requiredness is owned there rather than by the form.
+ template: {
+ type: 'string',
+ description: 'Email template name (sys_email_template.name) — resolved by (name, recipient locale) at delivery time and rendered per recipient. Mutually exclusive with inline title/message.',
+ },
+ templateData: {
+ type: 'object',
+ description: 'Render context for the referenced template\'s {{var}} placeholders; values interpolate {token} templates per run. Only valid together with template.',
+ },
  channels: {
  type: 'array', items: { type: 'string' },
  description: 'Channels to fan out to (default: inbox)',
@@ -228,6 +247,14 @@ export function registerNotifyNode(engine: AutomationEngine, ctx: PluginContext)
  // useless `[object Object]` (#3450). Serialize it readably instead.
  const title = stringifyForTemplate(interpolate(cfg.title ?? '', variables, context));
  const body = stringifyForTemplate(interpolate(cfg.message ?? '', variables, context));
+ // #9205 — the localizable content path. `template` is read RAW (a
+ // static metadata cross-reference, like `topic`/`channels`);
+ // `templateData` VALUES interpolate per run, so flow state can feed
+ // the template's `{{var}}` holes at delivery time.
+ const template = toStr(cfg.template);
+ const templateData = cfg.templateData
+ ? (interpolate(cfg.templateData, variables, context) as Record<string, unknown>)
+ : undefined;
  const channels = toStringList(cfg.channels);
  const topic = cfg.topic ? String(cfg.topic) : undefined;
  const severity = cfg.severity ? String(cfg.severity) : undefined;
@@ -246,7 +273,11 @@ export function registerNotifyNode(engine: AutomationEngine, ctx: PluginContext)
  const source = resolveSource(cfg, variables, context);
  const actorId = toStr(interpolate(cfg.actorId, variables, context));
 
- if (!title) return { success: false, error: 'notify: title is required' };
+ // With a `template` reference the content lives in the template
+ // bundle, resolved per recipient locale at delivery — no inline
+ // title to demand (the Zod contract already refused a node carrying
+ // NEITHER, and one carrying BOTH).
+ if (!title && !template) return { success: false, error: 'notify: title is required' };
  if (recipients.length === 0) {
  // Name the templates that came up empty (framework#3582). The
  // dominant cause is a cross-object hop — `{record.owner.manager}`
@@ -269,7 +300,7 @@ export function registerNotifyNode(engine: AutomationEngine, ctx: PluginContext)
  const messaging = getMessaging();
  if (!messaging) {
  ctx.logger.warn(
- `[notify] no messaging service registered; notification "${title}" not delivered`,
+ `[notify] no messaging service registered; notification "${title || `template ${template}`}" not delivered`,
  );
  return {
  success: true,
@@ -289,7 +320,21 @@ export function registerNotifyNode(engine: AutomationEngine, ctx: PluginContext)
  const result = await messaging.emit({
  topic: topic ?? 'notify',
  audience: recipients,
- payload: { ...(payload ?? {}), title, body, url: actionUrl },
+ // Content rides in the payload per path (#9205): the inline
+ // strings, or the template reference + its render context —
+ // which the outbox snapshots onto each delivery row, so the
+ // per-recipient-locale resolution happens at delivery time
+ // in the channel (email-channel.ts reads payload.template).
+ // On the template path no inline title/body keys are set:
+ // channels without template support fall back to the topic,
+ // which is the honest degraded rendering, not ''.
+ payload: {
+ ...(payload ?? {}),
+ ...(template
+ ? { template, ...(templateData !== undefined ? { templateData } : {}) }
+ : { title, body }),
+ url: actionUrl,
+ },
  severity,
  source,
  actorId,