@objectstack/plugin-email 4.0.1

package/src/email-service.test.ts

@@ -0,0 +1,142 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  EmailService,
+  LogTransport,
+  formatAddress,
+  normalizeMessage,
+  type EmailPersistence,
+} from './email-service.js';
+
+describe('formatAddress', () => {
+  it('passes through bare addresses', () => {
+    expect(formatAddress('alice@example.com')).toBe('alice@example.com');
+  });
+  it('quotes display names with reserved chars', () => {
+    expect(formatAddress({ name: 'Alice, CEO', address: 'a@b.com' })).toBe('"Alice, CEO" <a@b.com>');
+  });
+  it('does not quote simple display names', () => {
+    expect(formatAddress({ name: 'Alice', address: 'a@b.com' })).toBe('Alice <a@b.com>');
+  });
+  it('rejects malformed addresses', () => {
+    expect(() => formatAddress('not-an-email')).toThrow(/Invalid email address/);
+    expect(() => formatAddress({ address: '' })).toThrow(/Invalid email address/);
+  });
+});
+
+describe('normalizeMessage', () => {
+  it('requires subject', () => {
+    expect(() => normalizeMessage({ to: 'a@b.com', text: 'hi', subject: '' } as any, 'no@reply.com'))
+      .toThrow(/subject is required/);
+  });
+  it('requires text or html', () => {
+    expect(() => normalizeMessage({ to: 'a@b.com', subject: 'Hi' } as any, 'no@reply.com'))
+      .toThrow(/text or html/);
+  });
+  it('requires at least one recipient', () => {
+    expect(() => normalizeMessage({ to: [] as any, subject: 'Hi', text: 'x' }, 'no@reply.com'))
+      .toThrow(/recipient/);
+  });
+  it('requires from when no defaultFrom', () => {
+    expect(() => normalizeMessage({ to: 'a@b.com', subject: 'Hi', text: 'x' }))
+      .toThrow(/from address required/);
+  });
+  it('canonicalizes recipients and applies defaultFrom', () => {
+    const msg = normalizeMessage(
+      { to: ['a@b.com', { name: 'B', address: 'b@c.com' }], subject: 'Hi', text: 'x' },
+      { name: 'No Reply', address: 'no@reply.com' },
+    );
+    expect(msg.to).toEqual(['a@b.com', 'B <b@c.com>']);
+    expect(msg.from).toBe('No Reply <no@reply.com>');
+  });
+});
+
+describe('LogTransport', () => {
+  it('returns a synthetic Message-ID and logs', async () => {
+    const logger = { info: vi.fn() };
+    const t = new LogTransport(logger);
+    const res = await t.send({ to: ['a@b.com'], from: 'x@y.com', subject: 'Hi', text: 'hello' });
+    expect(res.messageId).toMatch(/^<dev-/);
+    expect(logger.info).toHaveBeenCalledWith('[LogTransport] would send email', expect.objectContaining({
+      subject: 'Hi', to: ['a@b.com'],
+    }));
+  });
+});
+
+describe('EmailService', () => {
+  function makePersistence() {
+    const rows = new Map<string, Record<string, any>>();
+    const p: EmailPersistence = {
+      async insert(row) { rows.set(row.id, { ...row }); return { id: row.id }; },
+      async update(id, patch) {
+        const cur = rows.get(id);
+        if (cur) rows.set(id, { ...cur, ...patch });
+      },
+    };
+    return { p, rows };
+  }
+
+  it('sends successfully, persists queued+sent rows', async () => {
+    const transport = { send: vi.fn(async () => ({ messageId: '<m1@x>' })) };
+    const { p, rows } = makePersistence();
+    const svc = new EmailService({ transport, defaultFrom: 'no@reply.com', persistence: p });
+    const res = await svc.send({ to: 'a@b.com', subject: 'Hi', text: 'hello', relatedObject: 'lead', relatedId: 'L1' });
+    expect(res.status).toBe('sent');
+    expect(res.messageId).toBe('<m1@x>');
+    expect(transport.send).toHaveBeenCalledTimes(1);
+    const row = rows.get(res.id);
+    expect(row).toMatchObject({
+      status: 'sent',
+      message_id: '<m1@x>',
+      from_address: 'no@reply.com',
+      to_addresses: 'a@b.com',
+      related_object: 'lead',
+      related_id: 'L1',
+      attempt_count: 1,
+    });
+    expect(typeof row?.sent_at).toBe('string');
+  });
+
+  it('marks failed when transport throws past retry budget', async () => {
+    const transport = { send: vi.fn(async () => { throw new Error('smtp 421'); }) };
+    const { p, rows } = makePersistence();
+    const svc = new EmailService({ transport, defaultFrom: 'no@reply.com', persistence: p, retries: 1 });
+    const res = await svc.send({ to: 'a@b.com', subject: 'Hi', text: 'x' });
+    expect(transport.send).toHaveBeenCalledTimes(2); // 1 + 1 retry
+    expect(res.status).toBe('failed');
+    expect(res.error).toMatch(/smtp 421/);
+    expect(rows.get(res.id)).toMatchObject({ status: 'failed', attempt_count: 2 });
+  });
+
+  it('works without persistence', async () => {
+    const transport = { send: vi.fn(async () => ({ messageId: '<m@x>' })) };
+    const svc = new EmailService({ transport, defaultFrom: 'no@reply.com' });
+    const res = await svc.send({ to: 'a@b.com', subject: 'Hi', text: 'x' });
+    expect(res.status).toBe('sent');
+    expect(res.id).toMatch(/[0-9a-f-]{30,}/);
+  });
+
+  it('propagates validation errors instead of marking failed', async () => {
+    const transport = { send: vi.fn(async () => ({ messageId: '<m@x>' })) };
+    const svc = new EmailService({ transport, defaultFrom: 'no@reply.com' });
+    await expect(svc.send({ to: 'a@b.com', subject: '', text: 'x' })).rejects.toThrow(/subject is required/);
+    expect(transport.send).not.toHaveBeenCalled();
+  });
+
+  it('tolerates persistence failures and still delivers', async () => {
+    const transport = { send: vi.fn(async () => ({ messageId: '<m@x>' })) };
+    const persistence: EmailPersistence = {
+      insert: vi.fn(async () => { throw new Error('db down'); }),
+      update: vi.fn(async () => { throw new Error('db down'); }),
+    };
+    const warn = vi.fn();
+    const svc = new EmailService({
+      transport, defaultFrom: 'no@reply.com', persistence,
+      logger: { info: vi.fn(), warn },
+    });
+    const res = await svc.send({ to: 'a@b.com', subject: 'Hi', text: 'x' });
+    expect(res.status).toBe('sent');
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('persist failed'), expect.any(Object));
+  });
+});

package/src/email-service.ts

@@ -0,0 +1,366 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  IEmailService,
+  IEmailTransport,
+  SendEmailInput,
+  SendEmailResult,
+  SendTemplateInput,
+  NormalizedEmailMessage,
+  EmailAddress,
+  EmailDeliveryStatus,
+  TransportSendResult,
+} from '@objectstack/spec/contracts';
+import { renderTemplate, requireVars, htmlToText } from './template-engine.js';
+
+/**
+ * Internal persistence shim — typed loosely so the service can run
+ * without an ObjectQL engine wired (e.g. unit tests, serverless).
+ */
+export interface EmailPersistence {
+  insert(row: Record<string, any>): Promise<{ id: string } | string>;
+  update?(id: string, patch: Record<string, any>): Promise<void>;
+}
+
+/**
+ * Naive RFC-5322 validator — good enough to catch obvious typos.
+ * Defers full validation to the transport / receiving MTA.
+ */
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Format an EmailAddress (string or {name,address}) into the canonical
+ * `"Display" <addr>` form. Throws if address is malformed.
+ */
+export function formatAddress(addr: EmailAddress): string {
+  const obj = typeof addr === 'string' ? { address: addr } : addr;
+  const address = String(obj.address ?? '').trim();
+  if (!EMAIL_REGEX.test(address)) {
+    throw new Error(`Invalid email address: ${address || '(empty)'}`);
+  }
+  const name = obj.name?.trim();
+  if (!name) return address;
+  // Quote display name if it contains characters that need quoting
+  const needsQuote = /[",()<>@:;.\\\[\]]/.test(name);
+  const quoted = needsQuote ? `"${name.replace(/"/g, '\\"')}"` : name;
+  return `${quoted} <${address}>`;
+}
+
+function listToArray(v: EmailAddress | EmailAddress[] | undefined): string[] | undefined {
+  if (v === undefined) return undefined;
+  const arr = Array.isArray(v) ? v : [v];
+  return arr.map(formatAddress);
+}
+
+/**
+ * Validate input + apply default-from + canonicalize recipients.
+ * Throws Error('VALIDATION_FAILED: <reason>') for malformed payloads.
+ */
+export function normalizeMessage(
+  input: SendEmailInput,
+  defaultFrom?: EmailAddress,
+): NormalizedEmailMessage {
+  if (!input || typeof input !== 'object') {
+    throw new Error('VALIDATION_FAILED: input must be an object');
+  }
+  const subject = String(input.subject ?? '').trim();
+  if (!subject) throw new Error('VALIDATION_FAILED: subject is required');
+  if (!input.text && !input.html) {
+    throw new Error('VALIDATION_FAILED: at least one of text or html is required');
+  }
+  const toArr = listToArray(input.to);
+  if (!toArr || toArr.length === 0) {
+    throw new Error('VALIDATION_FAILED: at least one recipient (to) is required');
+  }
+  const fromCandidate = input.from ?? defaultFrom;
+  if (!fromCandidate) {
+    throw new Error('VALIDATION_FAILED: from address required (set options.defaultFrom or pass input.from)');
+  }
+  const from = formatAddress(fromCandidate);
+
+  const msg: NormalizedEmailMessage = {
+    to: toArr,
+    from,
+    subject,
+    ...(input.text !== undefined ? { text: input.text } : {}),
+    ...(input.html !== undefined ? { html: input.html } : {}),
+  };
+  const cc = listToArray(input.cc);
+  if (cc && cc.length > 0) msg.cc = cc;
+  const bcc = listToArray(input.bcc);
+  if (bcc && bcc.length > 0) msg.bcc = bcc;
+  if (input.replyTo) msg.replyTo = formatAddress(input.replyTo);
+  if (input.attachments && input.attachments.length > 0) msg.attachments = input.attachments;
+  if (input.headers && Object.keys(input.headers).length > 0) msg.headers = input.headers;
+  return msg;
+}
+
+/**
+ * Development transport — never actually sends. Logs to the provided
+ * logger and returns a synthetic Message-ID. Useful for local dev,
+ * tests, and "dry run" environments.
+ */
+export class LogTransport implements IEmailTransport {
+  private counter = 0;
+  constructor(private readonly logger?: { info: (msg: string, meta?: any) => void }) {}
+  async send(message: NormalizedEmailMessage): Promise<TransportSendResult> {
+    const messageId = `<dev-${Date.now()}-${++this.counter}@objectstack.local>`;
+    this.logger?.info('[LogTransport] would send email', {
+      messageId,
+      to: message.to,
+      from: message.from,
+      subject: message.subject,
+      hasText: !!message.text,
+      hasHtml: !!message.html,
+      attachments: message.attachments?.length ?? 0,
+    });
+    return { messageId, response: 'logged' };
+  }
+}
+
+/**
+ * Generate a UUID-like id without pulling crypto in test contexts.
+ * Uses crypto.randomUUID when available, falls back to a v4-shaped
+ * random string. NOT cryptographically secure when the fallback is
+ * used; the only consumer is local row identifiers, never tokens.
+ */
+function newId(): string {
+  try {
+    const g = (globalThis as any).crypto;
+    if (g?.randomUUID) return g.randomUUID();
+  } catch { /* fall through */ }
+  const hex = (n: number) => Math.floor(Math.random() * 16 ** n).toString(16).padStart(n, '0');
+  return `${hex(8)}-${hex(4)}-4${hex(3)}-a${hex(3)}-${hex(12)}`;
+}
+
+/**
+ * Loader for sys_email_template rows. Injected by EmailServicePlugin
+ * on `kernel:ready`. Returns the best-matching row for `(name, locale)`
+ * or `null` when none exists / inactive.
+ */
+export interface TemplateLoader {
+  load(name: string, locale: string | undefined): Promise<EmailTemplateRow | null>;
+}
+
+/**
+ * Row shape returned by the loader — mirrors sys_email_template
+ * columns relevant to rendering.
+ */
+export interface EmailTemplateRow {
+  name: string;
+  locale: string;
+  subject: string;
+  body_html: string;
+  body_text?: string | null;
+  from_name?: string | null;
+  from_address?: string | null;
+  reply_to?: string | null;
+  active?: boolean;
+  variables_json?: string | null;
+}
+
+export interface EmailServiceOptions {
+  transport: IEmailTransport;
+  defaultFrom?: EmailAddress;
+  /** Persist each attempt to sys_email. Omit to disable persistence. */
+  persistence?: EmailPersistence;
+  /** Resolve named templates for sendTemplate(). Omit to disable templates. */
+  templateLoader?: TemplateLoader;
+  /** Retry attempts on transport throw. Default 0 (no retry). */
+  retries?: number;
+  /** Logger for diagnostic output. */
+  logger?: { info: (msg: string, meta?: any) => void; warn: (msg: string, meta?: any) => void; error?: (msg: string, meta?: any) => void };
+  /** Default render context merged into every sendTemplate call (e.g. `{ appName }`). */
+  defaultTemplateContext?: Record<string, unknown>;
+}
+
+/**
+ * Concrete IEmailService implementation.
+ *
+ * Flow:
+ *   1. Validate + normalize input (throws on bad input).
+ *   2. Persist queued row to sys_email (best-effort; failures logged).
+ *   3. Call transport.send(); on success, update row to sent +
+ *      timestamp + messageId. On failure, mark failed + error.
+ *   4. Return SendEmailResult with the persisted row id (or a fresh
+ *      id when persistence is disabled).
+ */
+export class EmailService implements IEmailService {
+  constructor(public options: EmailServiceOptions) {
+    if (!options.transport) throw new Error('EmailService: transport is required');
+  }
+
+  /** Wire (or replace) the template loader after construction. */
+  setTemplateLoader(loader: TemplateLoader): void {
+    this.options.templateLoader = loader;
+  }
+
+  /** Wire (or replace) persistence after construction. */
+  setPersistence(persistence: EmailPersistence | undefined): void {
+    this.options.persistence = persistence;
+  }
+
+  /**
+   * Hot-swap the underlying transport. Used by EmailServicePlugin when
+   * the `mail` settings namespace changes (e.g. SMTP host updated in
+   * the admin UI) so subsequent `send()` calls go through the new
+   * transport without restarting the process.
+   */
+  setTransport(transport: IEmailTransport): void {
+    this.options.transport = transport;
+  }
+
+  /** Replace the default `from` address used when callers omit `input.from`. */
+  setDefaultFrom(from: EmailAddress | undefined): void {
+    this.options.defaultFrom = from;
+  }
+
+  async send(input: SendEmailInput): Promise<SendEmailResult> {
+    let normalized: NormalizedEmailMessage;
+    try {
+      normalized = normalizeMessage(input, this.options.defaultFrom);
+    } catch (err: any) {
+      // Validation failures must surface to the caller.
+      throw err;
+    }
+
+    const id = newId();
+    const baseRow: Record<string, any> = {
+      id,
+      from_address: normalized.from,
+      to_addresses: normalized.to.join(', '),
+      ...(normalized.cc?.length ? { cc_addresses: normalized.cc.join(', ') } : {}),
+      ...(normalized.bcc?.length ? { bcc_addresses: normalized.bcc.join(', ') } : {}),
+      ...(normalized.replyTo ? { reply_to: normalized.replyTo } : {}),
+      subject: normalized.subject,
+      ...(normalized.text !== undefined ? { body_text: normalized.text } : {}),
+      ...(normalized.html !== undefined ? { body_html: normalized.html } : {}),
+      ...(input.relatedObject ? { related_object: input.relatedObject } : {}),
+      ...(input.relatedId ? { related_id: input.relatedId } : {}),
+      ...(input.sentBy ? { sent_by: input.sentBy } : {}),
+      status: 'queued',
+      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 });
+      }
+    }
+    const rowId = persistedId ?? id;
+
+    const maxAttempts = (this.options.retries ?? 0) + 1;
+    let lastError: any;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const result = await this.options.transport.send(normalized);
+        const messageId = result.messageId;
+        const status: EmailDeliveryStatus = 'sent';
+        await this.updateRow(rowId, {
+          status,
+          message_id: messageId,
+          sent_at: new Date().toISOString(),
+          attempt_count: attempt,
+        });
+        return { id: rowId, status, messageId };
+      } catch (err: any) {
+        lastError = err;
+        if (attempt < maxAttempts) {
+          // simple exponential backoff
+          await new Promise(r => setTimeout(r, Math.min(2000, 100 * 2 ** (attempt - 1))));
+        }
+      }
+    }
+    const errMessage = String(lastError?.message ?? lastError ?? 'send failed').slice(0, 1000);
+    await this.updateRow(rowId, {
+      status: 'failed',
+      error: errMessage,
+      attempt_count: maxAttempts,
+    });
+    return { id: rowId, status: 'failed', error: errMessage };
+  }
+
+  private async updateRow(id: string, patch: Record<string, any>): Promise<void> {
+    if (!this.options.persistence?.update) return;
+    try {
+      await this.options.persistence.update(id, patch);
+    } catch (err: any) {
+      this.options.logger?.warn('EmailService: sys_email update failed (non-fatal)', { id, error: err?.message });
+    }
+  }
+
+  /**
+   * Render a named template from sys_email_template and deliver via
+   * send(). Looks up `(name, locale)` then falls back to `(name, 'en-US')`.
+   */
+  async sendTemplate(input: SendTemplateInput): Promise<SendEmailResult> {
+    if (!input?.template) {
+      throw new Error('VALIDATION_FAILED: template name is required');
+    }
+    const loader = this.options.templateLoader;
+    if (!loader) {
+      throw new Error('TEMPLATE_NOT_FOUND: no templateLoader configured on EmailService');
+    }
+    const preferred = input.locale && String(input.locale).trim();
+    let row = await loader.load(input.template, preferred || undefined);
+    if (!row && preferred && preferred !== 'en-US') {
+      row = await loader.load(input.template, 'en-US');
+    }
+    if (!row) {
+      throw new Error(`TEMPLATE_NOT_FOUND: ${input.template} (locale=${preferred || 'en-US'})`);
+    }
+    if (row.active === false) {
+      throw new Error(`TEMPLATE_INACTIVE: ${input.template}`);
+    }
+
+    // Validate required variables (declared in variables_json).
+    const data: Record<string, any> = {
+      ...(this.options.defaultTemplateContext || {}),
+      ...(input.data || {}),
+    };
+    if (row.variables_json) {
+      try {
+        const decl: Array<{ name: string; required?: boolean }> = JSON.parse(String(row.variables_json));
+        const required = decl.filter((v) => v?.required).map((v) => v.name);
+        if (required.length) requireVars(data, required);
+      } catch (err: any) {
+        if (String(err?.message).startsWith('MISSING_VARIABLES')) throw err;
+        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 from: EmailAddress | undefined = input.from
+      ?? (row.from_address
+        ? { address: row.from_address, ...(row.from_name ? { name: row.from_name } : {}) }
+        : undefined);
+
+    const sendInput: SendEmailInput = {
+      to: input.to,
+      subject,
+      html,
+      text,
+      ...(from ? { from } : {}),
+      ...(input.cc ? { cc: input.cc } : {}),
+      ...(input.bcc ? { bcc: input.bcc } : {}),
+      ...(input.replyTo ?? row.reply_to
+        ? { replyTo: input.replyTo ?? (row.reply_to as string) }
+        : {}),
+      ...(input.attachments ? { attachments: input.attachments } : {}),
+      ...(input.headers ? { headers: input.headers } : {}),
+      ...(input.relatedObject ? { relatedObject: input.relatedObject } : {}),
+      ...(input.relatedId ? { relatedId: input.relatedId } : {}),
+      ...(input.sentBy ? { sentBy: input.sentBy } : {}),
+    };
+    return this.send(sendInput);
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/plugin-email
+ *
+ * Outbound email delivery for ObjectStack. Registers an `IEmailService`
+ * implementation backed by a pluggable `IEmailTransport` (SMTP via
+ * nodemailer, SendGrid, Resend, SES, …) and persists each attempt to
+ * the `sys_email` system object for audit / activity-stream display.
+ */
+
+export { EmailServicePlugin } from './email-plugin.js';
+export type { EmailServicePluginOptions } from './email-plugin.js';
+export { LogTransport, normalizeMessage, formatAddress } from './email-service.js';
+export type { EmailServiceOptions, TemplateLoader, EmailTemplateRow, EmailPersistence } from './email-service.js';
+export { renderTemplate, requireVars, htmlToText } from './template-engine.js';
+export {
+  ResendTransport,
+  PostmarkTransport,
+  makeTransport,
+  type ResendTransportOptions,
+  type PostmarkTransportOptions,
+  type MakeTransportOptions,
+} from './transports/index.js';
+export {
+  AUTH_PASSWORD_RESET_TEMPLATE,
+  AUTH_VERIFY_EMAIL_TEMPLATE,
+  AUTH_MAGIC_LINK_TEMPLATE,
+  AUTH_INVITATION_TEMPLATE,
+  AUTH_TWO_FACTOR_OTP_TEMPLATE,
+  BUILTIN_AUTH_TEMPLATES,
+} from './templates/auth-templates.js';