@objectstack/plugin-email 4.0.1

package/src/send-template.test.ts

@@ -0,0 +1,273 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EmailService, type TemplateLoader, type EmailTemplateRow } from './email-service.js';
+import type { IEmailTransport, NormalizedEmailMessage, TransportSendResult } from '@objectstack/spec/contracts';
+
+class CaptureTransport implements IEmailTransport {
+  public sent: NormalizedEmailMessage[] = [];
+  async send(message: NormalizedEmailMessage): Promise<TransportSendResult> {
+    this.sent.push(message);
+    return { messageId: `msg-${this.sent.length}` };
+  }
+}
+
+function makeLoader(rows: EmailTemplateRow[]): TemplateLoader {
+  return {
+    async load(name, locale) {
+      const exact = rows.find((r) => r.name === name && r.locale === locale);
+      if (exact) return exact;
+      const fb = rows.find((r) => r.name === name && r.locale === 'en-US');
+      return fb || null;
+    },
+  };
+}
+
+describe('EmailService.sendTemplate', () => {
+  const sampleTemplate: EmailTemplateRow = {
+    name: 'auth.password_reset',
+    locale: 'en-US',
+    subject: 'Reset {{user.name}}',
+    body_html: '<p>Hi {{user.name}}, <a href="{{{resetUrl}}}">reset</a></p>',
+    body_text: 'Hi {{user.name}}, reset: {{resetUrl}}',
+    active: true,
+    variables_json: JSON.stringify([
+      { name: 'user.name', required: true },
+      { name: 'resetUrl', required: true },
+    ]),
+  };
+
+  it('renders template + delivers via transport', async () => {
+    const transport = new CaptureTransport();
+    const svc = new EmailService({
+      transport,
+      defaultFrom: { address: 'no-reply@x.com' },
+      templateLoader: makeLoader([sampleTemplate]),
+    });
+
+    const res = await svc.sendTemplate({
+      template: 'auth.password_reset',
+      to: 'alice@x.com',
+      data: { user: { name: 'Alice' }, resetUrl: 'https://x.com/r/abc' },
+    });
+
+    expect(res.status).toBe('sent');
+    expect(transport.sent).toHaveLength(1);
+    const msg = transport.sent[0];
+    expect(msg.subject).toBe('Reset Alice');
+    expect(msg.html).toContain('Hi Alice');
+    expect(msg.html).toContain('href="https://x.com/r/abc"');
+    expect(msg.text).toContain('reset: https://x.com/r/abc');
+  });
+
+  it('throws TEMPLATE_NOT_FOUND when loader returns null', async () => {
+    const svc = new EmailService({
+      transport: new CaptureTransport(),
+      defaultFrom: { address: 'no-reply@x.com' },
+      templateLoader: makeLoader([]),
+    });
+    await expect(svc.sendTemplate({
+      template: 'auth.unknown',
+      to: 'a@x.com',
+      data: {},
+    })).rejects.toThrow(/TEMPLATE_NOT_FOUND/);
+  });
+
+  it('throws TEMPLATE_INACTIVE for active=false rows', async () => {
+    const svc = new EmailService({
+      transport: new CaptureTransport(),
+      defaultFrom: { address: 'no-reply@x.com' },
+      templateLoader: makeLoader([{ ...sampleTemplate, active: false }]),
+    });
+    await expect(svc.sendTemplate({
+      template: 'auth.password_reset',
+      to: 'a@x.com',
+      data: { user: { name: 'A' }, resetUrl: 'https://x' },
+    })).rejects.toThrow(/TEMPLATE_INACTIVE/);
+  });
+
+  it('throws MISSING_VARIABLES when required vars absent', async () => {
+    const svc = new EmailService({
+      transport: new CaptureTransport(),
+      defaultFrom: { address: 'no-reply@x.com' },
+      templateLoader: makeLoader([sampleTemplate]),
+    });
+    await expect(svc.sendTemplate({
+      template: 'auth.password_reset',
+      to: 'a@x.com',
+      data: { user: { name: 'A' } }, // missing resetUrl
+    })).rejects.toThrow(/MISSING_VARIABLES: resetUrl/);
+  });
+
+  it('falls back to en-US when requested locale missing', async () => {
+    const transport = new CaptureTransport();
+    const svc = new EmailService({
+      transport,
+      defaultFrom: { address: 'no-reply@x.com' },
+      templateLoader: makeLoader([sampleTemplate]),
+    });
+    await svc.sendTemplate({
+      template: 'auth.password_reset',
+      to: 'a@x.com',
+      locale: 'zh-CN',
+      data: { user: { name: 'A' }, resetUrl: 'https://x' },
+    });
+    expect(transport.sent[0].subject).toBe('Reset A'); // en-US row used
+  });
+
+  it('uses template fromOverride when supplied', async () => {
+    const transport = new CaptureTransport();
+    const svc = new EmailService({
+      transport,
+      defaultFrom: { address: 'no-reply@x.com' },
+      templateLoader: makeLoader([{
+        ...sampleTemplate,
+        from_address: 'security@x.com',
+        from_name: 'Security Team',
+      }]),
+    });
+    await svc.sendTemplate({
+      template: 'auth.password_reset',
+      to: 'a@x.com',
+      data: { user: { name: 'A' }, resetUrl: 'https://x' },
+    });
+    expect(transport.sent[0].from).toBe('Security Team <security@x.com>');
+  });
+
+  it('merges defaultTemplateContext into data', async () => {
+    const transport = new CaptureTransport();
+    const svc = new EmailService({
+      transport,
+      defaultFrom: { address: 'no-reply@x.com' },
+      templateLoader: makeLoader([{
+        ...sampleTemplate,
+        subject: '{{appName}}: reset',
+        body_html: '<p>{{appName}}</p>',
+        variables_json: '[]',
+      }]),
+      defaultTemplateContext: { appName: 'Acme' },
+    });
+    await svc.sendTemplate({
+      template: 'auth.password_reset',
+      to: 'a@x.com',
+      data: {},
+    });
+    expect(transport.sent[0].subject).toBe('Acme: reset');
+    expect(transport.sent[0].html).toContain('Acme');
+  });
+
+  it('throws if no templateLoader configured', async () => {
+    const svc = new EmailService({
+      transport: new CaptureTransport(),
+      defaultFrom: { address: 'no-reply@x.com' },
+    });
+    await expect(svc.sendTemplate({
+      template: 'x',
+      to: 'a@x.com',
+      data: {},
+    })).rejects.toThrow(/templateLoader/);
+  });
+
+  it('auto-derives plain text from HTML when body_text omitted', async () => {
+    const transport = new CaptureTransport();
+    const svc = new EmailService({
+      transport,
+      defaultFrom: { address: 'no-reply@x.com' },
+      templateLoader: makeLoader([{
+        ...sampleTemplate,
+        body_text: null,
+      }]),
+    });
+    await svc.sendTemplate({
+      template: 'auth.password_reset',
+      to: 'a@x.com',
+      data: { user: { name: 'A' }, resetUrl: 'https://x' },
+    });
+    expect(transport.sent[0].text).toContain('Hi A');
+    expect(transport.sent[0].text).not.toContain('<a href');
+  });
+});
+
+describe('ResendTransport', () => {
+  let originalFetch: typeof globalThis.fetch;
+  beforeEach(() => { originalFetch = globalThis.fetch; });
+  afterEach(() => { globalThis.fetch = originalFetch; });
+
+  it('POSTs JSON with bearer auth and returns messageId', async () => {
+    const fetchSpy = vi.fn(async () => new Response(JSON.stringify({ id: 'res-123' }), {
+      status: 200, headers: { 'Content-Type': 'application/json' },
+    }));
+    globalThis.fetch = fetchSpy as any;
+    const { ResendTransport } = await import('./transports/resend.js');
+    const t = new ResendTransport('sk_test_key');
+    const res = await t.send({
+      to: ['a@x.com'],
+      from: 'no-reply@x.com',
+      subject: 'Hi',
+      text: 'body',
+    });
+    expect(res.messageId).toBe('res-123');
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    const [url, init] = fetchSpy.mock.calls[0] as any;
+    expect(url).toBe('https://api.resend.com/emails');
+    expect(init.headers.Authorization).toBe('Bearer sk_test_key');
+    const body = JSON.parse(init.body);
+    expect(body).toMatchObject({ to: ['a@x.com'], from: 'no-reply@x.com', subject: 'Hi', text: 'body' });
+  });
+
+  it('throws on non-2xx', async () => {
+    globalThis.fetch = (async () => new Response('bad key', { status: 401 })) as any;
+    const { ResendTransport } = await import('./transports/resend.js');
+    const t = new ResendTransport('bad');
+    await expect(t.send({ to: ['a@x.com'], from: 'b@x.com', subject: 's', text: 'x' }))
+      .rejects.toThrow(/Resend 401/);
+  });
+
+  it('throws when constructor called with empty apiKey', async () => {
+    const { ResendTransport } = await import('./transports/resend.js');
+    expect(() => new ResendTransport('')).toThrow(/apiKey is required/);
+  });
+});
+
+describe('PostmarkTransport', () => {
+  let originalFetch: typeof globalThis.fetch;
+  beforeEach(() => { originalFetch = globalThis.fetch; });
+  afterEach(() => { globalThis.fetch = originalFetch; });
+
+  it('POSTs Postmark-shaped JSON and returns MessageID', async () => {
+    const fetchSpy = vi.fn(async () => new Response(JSON.stringify({ MessageID: 'pm-9' }), {
+      status: 200, headers: { 'Content-Type': 'application/json' },
+    }));
+    globalThis.fetch = fetchSpy as any;
+    const { PostmarkTransport } = await import('./transports/postmark.js');
+    const t = new PostmarkTransport({ apiKey: 'tok', messageStream: 'broadcast' });
+    const res = await t.send({
+      to: ['a@x.com', 'b@x.com'],
+      from: 'no-reply@x.com',
+      subject: 'Hi',
+      html: '<p>x</p>',
+    });
+    expect(res.messageId).toBe('pm-9');
+    const [url, init] = fetchSpy.mock.calls[0] as any;
+    expect(url).toBe('https://api.postmarkapp.com/email');
+    expect(init.headers['X-Postmark-Server-Token']).toBe('tok');
+    const body = JSON.parse(init.body);
+    expect(body.To).toBe('a@x.com, b@x.com');
+    expect(body.MessageStream).toBe('broadcast');
+    expect(body.HtmlBody).toBe('<p>x</p>');
+  });
+});
+
+describe('makeTransport factory', () => {
+  it('builds LogTransport for log provider', async () => {
+    const { makeTransport } = await import('./transports/index.js');
+    const { LogTransport } = await import('./email-service.js');
+    expect(makeTransport({ provider: 'log' })).toBeInstanceOf(LogTransport);
+  });
+
+  it('rejects resend/postmark without apiKey', async () => {
+    const { makeTransport } = await import('./transports/index.js');
+    expect(() => makeTransport({ provider: 'resend' })).toThrow(/apiKey/);
+    expect(() => makeTransport({ provider: 'postmark' })).toThrow(/apiKey/);
+  });
+});

package/src/template-engine.test.ts

@@ -0,0 +1,76 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { renderTemplate, requireVars, htmlToText } from './template-engine.js';
+
+describe('template-engine', () => {
+  describe('renderTemplate', () => {
+    it('substitutes dotted paths', () => {
+      expect(renderTemplate('Hi {{user.name}}', { user: { name: 'Alice' } }))
+        .toBe('Hi Alice');
+    });
+
+    it('escapes HTML by default', () => {
+      expect(renderTemplate('<p>{{x}}</p>', { x: '<script>alert(1)</script>' }))
+        .toBe('<p>&lt;script&gt;alert(1)&lt;/script&gt;</p>');
+    });
+
+    it('does not escape with triple braces', () => {
+      expect(renderTemplate('<a href="{{{url}}}">go</a>', { url: 'https://x.com/?a=1&b=2' }))
+        .toBe('<a href="https://x.com/?a=1&b=2">go</a>');
+    });
+
+    it('renders missing variables as empty strings', () => {
+      expect(renderTemplate('a={{a}} b={{b}}', { a: 'A' })).toBe('a=A b=');
+    });
+
+    it('handles deeply nested paths', () => {
+      expect(renderTemplate('{{a.b.c.d}}', { a: { b: { c: { d: 'deep' } } } }))
+        .toBe('deep');
+    });
+
+    it('stringifies non-string scalars', () => {
+      expect(renderTemplate('count={{n}}', { n: 42 })).toBe('count=42');
+      expect(renderTemplate('flag={{f}}', { f: true })).toBe('flag=true');
+    });
+
+    it('escapes all standard HTML entities', () => {
+      expect(renderTemplate('{{s}}', { s: `&<>"'` })).toBe('&amp;&lt;&gt;&quot;&#39;');
+    });
+  });
+
+  describe('requireVars', () => {
+    it('passes when all present', () => {
+      expect(() => requireVars({ a: 1, b: 'x' }, ['a', 'b'])).not.toThrow();
+    });
+
+    it('throws MISSING_VARIABLES listing the gaps', () => {
+      expect(() => requireVars({ a: 1 }, ['a', 'b', 'c']))
+        .toThrow('MISSING_VARIABLES: b, c');
+    });
+
+    it('supports dotted paths', () => {
+      expect(() => requireVars({ user: { name: 'a' } }, ['user.name'])).not.toThrow();
+      expect(() => requireVars({ user: {} }, ['user.name']))
+        .toThrow('MISSING_VARIABLES: user.name');
+    });
+  });
+
+  describe('htmlToText', () => {
+    it('strips tags and collapses whitespace', () => {
+      expect(htmlToText('<p>Hello <strong>world</strong></p>')).toBe('Hello world');
+    });
+
+    it('converts <br> to newlines', () => {
+      expect(htmlToText('a<br>b<br/>c')).toBe('a\nb\nc');
+    });
+
+    it('handles common entities', () => {
+      expect(htmlToText('<p>1 &lt; 2 &amp;&amp; 3 &gt; 2</p>')).toBe('1 < 2 && 3 > 2');
+    });
+
+    it('collapses 3+ newlines to 2', () => {
+      expect(htmlToText('<p>a</p><p>b</p>')).toBe('a\nb');
+    });
+  });
+});

package/src/template-engine.ts

@@ -0,0 +1,94 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Minimal mustache-style template renderer.
+ *
+ * Supports `{{path.to.value}}` placeholders resolved against a plain
+ * JS object via dotted-path lookup. Values are HTML-escaped by
+ * default; use `{{{path}}}` (triple braces) to opt out of escaping
+ * (e.g. when injecting pre-rendered HTML fragments such as URLs in
+ * `<a href="">`).
+ *
+ * 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
+ * Handlebars, but bringing it in costs ~50KB and pulls a parser at
+ * runtime; we resist that until a real use case demands it.
+ */
+
+const PLACEHOLDER = /(\{\{\{?)\s*([\w.]+)\s*(\}?\}\})/g;
+
+function lookup(data: Record<string, any>, path: string): unknown {
+  if (!path) return undefined;
+  const parts = path.split('.');
+  let cur: any = data;
+  for (const p of parts) {
+    if (cur == null) return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Render `template` with values from `data`. Missing placeholders
+ * render as empty strings (no throw); call `requireVars()` first if
+ * you need strict validation.
+ */
+export function renderTemplate(template: string, data: Record<string, any>): 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);
+  });
+}
+
+/**
+ * Throw `Error('MISSING_VARIABLES: a, b')` when required vars are
+ * absent from `data`. Used by `IEmailService.sendTemplate()` to
+ * fail fast rather than send a half-rendered email.
+ */
+export function requireVars(
+  data: Record<string, any>,
+  required: ReadonlyArray<string>,
+): void {
+  const missing = required.filter((name) => lookup(data, name) == null);
+  if (missing.length > 0) {
+    throw new Error(`MISSING_VARIABLES: ${missing.join(', ')}`);
+  }
+}
+
+/**
+ * Strip HTML tags + collapse whitespace to derive a plain-text body
+ * from an HTML template. Conservative: keeps line breaks at block
+ * boundaries (<br>, </p>, </div>) so the resulting text is at least
+ * paragraph-shaped.
+ */
+export function htmlToText(html: string): string {
+  if (!html) return '';
+  return html
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/(p|div|h[1-6]|li|tr)>/gi, '\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n[ \t]+/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}

package/src/templates/auth-templates.ts

@@ -0,0 +1,177 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { EmailTemplateDefinition as EmailTemplate } from '@objectstack/spec/system';
+
+/**
+ * Built-in auth email templates seeded into `sys_email_template` on
+ * EmailServicePlugin startup. Each template is `isSystem: true` so
+ * tenants may overlay subject/body but should not delete the row.
+ *
+ * Templates use `{{path.to.value}}` placeholders; `{{{...}}}` for
+ * unescaped URLs (see template-engine.ts).
+ *
+ * Authoring conventions:
+ * - Subject: plain, max ~80 chars, no markup.
+ * - HTML body: single column, ~600px max width, inline styles only
+ *   (most clients strip <head>).
+ * - Always include a plain-text fallback (good for spam scoring).
+ * - Provide an `{{appName}}` variable everywhere for brand override.
+ */
+
+const baseStyles = 'font-family:-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif;line-height:1.5;color:#1f2937';
+const buttonStyles = 'display:inline-block;padding:12px 24px;background:#2563eb;color:#ffffff;text-decoration:none;border-radius:6px;font-weight:600';
+const footerStyles = 'margin-top:32px;padding-top:16px;border-top:1px solid #e5e7eb;color:#6b7280;font-size:12px';
+
+function wrap(title: string, bodyHtml: string): string {
+  return `<!doctype html><html><body style="${baseStyles};margin:0;padding:24px;background:#f9fafb">
+<div style="max-width:560px;margin:0 auto;background:#ffffff;padding:32px;border-radius:8px;border:1px solid #e5e7eb">
+<h1 style="margin:0 0 16px 0;font-size:20px;font-weight:600">${title}</h1>
+${bodyHtml}
+<div style="${footerStyles}">
+You received this email because of activity on your {{appName}} account.<br>
+If this wasn't you, you can safely ignore this message.
+</div>
+</div></body></html>`;
+}
+
+export const AUTH_PASSWORD_RESET_TEMPLATE: EmailTemplate = {
+  name: 'auth.password_reset',
+  label: 'Password Reset',
+  category: 'auth',
+  locale: 'en-US',
+  subject: 'Reset your {{appName}} password',
+  bodyHtml: wrap('Reset your password', `
+<p>Hi {{user.name}},</p>
+<p>We received a request to reset the password for the account associated with <strong>{{user.email}}</strong>.</p>
+<p>Click the button below to choose a new password. This link expires in {{expiresInMinutes}} minutes.</p>
+<p style="margin:24px 0"><a href="{{{resetUrl}}}" style="${buttonStyles}">Reset password</a></p>
+<p style="font-size:13px;color:#6b7280">Or copy and paste this URL into your browser:<br><span style="word-break:break-all">{{resetUrl}}</span></p>
+<p>If you didn't request this, no action is needed — your password stays the same.</p>
+`),
+  bodyText: `Hi {{user.name}},
+
+We received a request to reset the password for {{user.email}}.
+
+Reset your password (link expires in {{expiresInMinutes}} minutes):
+{{resetUrl}}
+
+If you didn't request this, ignore this email.`,
+  variables: [
+    { name: 'user.name', type: 'string', required: false, description: 'Recipient display name' },
+    { name: 'user.email', type: 'string', required: true, description: 'Recipient email' },
+    { name: 'resetUrl', type: 'url', required: true, description: 'Password reset URL' },
+    { name: 'expiresInMinutes', type: 'number', required: false, description: 'Link TTL in minutes' },
+    { name: 'appName', type: 'string', required: false, description: 'Product/app name (brand override)' },
+  ],
+  active: true,
+  isSystem: true,
+  description: 'Sent when a user requests a password reset via better-auth.',
+};
+
+export const AUTH_VERIFY_EMAIL_TEMPLATE: EmailTemplate = {
+  name: 'auth.verify_email',
+  label: 'Verify Email Address',
+  category: 'auth',
+  locale: 'en-US',
+  subject: 'Verify your {{appName}} email address',
+  bodyHtml: wrap('Verify your email', `
+<p>Hi {{user.name}},</p>
+<p>Thanks for signing up for {{appName}}! Please confirm <strong>{{user.email}}</strong> belongs to you.</p>
+<p style="margin:24px 0"><a href="{{{verificationUrl}}}" style="${buttonStyles}">Verify email</a></p>
+<p style="font-size:13px;color:#6b7280">Or copy and paste this URL into your browser:<br><span style="word-break:break-all">{{verificationUrl}}</span></p>
+`),
+  bodyText: `Hi {{user.name}},
+
+Please verify your email ({{user.email}}) by opening this link:
+{{verificationUrl}}`,
+  variables: [
+    { name: 'user.name', type: 'string', required: false },
+    { name: 'user.email', type: 'string', required: true },
+    { name: 'verificationUrl', type: 'url', required: true },
+    { name: 'appName', type: 'string', required: false },
+  ],
+  active: true,
+  isSystem: true,
+  description: 'Sent when better-auth needs to verify a newly-registered email address.',
+};
+
+export const AUTH_MAGIC_LINK_TEMPLATE: EmailTemplate = {
+  name: 'auth.magic_link',
+  label: 'Magic Link Sign-In',
+  category: 'auth',
+  locale: 'en-US',
+  subject: 'Your {{appName}} sign-in link',
+  bodyHtml: wrap('Sign in to {{appName}}', `
+<p>Click the button below to sign in. This link expires in {{expiresInMinutes}} minutes and may only be used once.</p>
+<p style="margin:24px 0"><a href="{{{magicLinkUrl}}}" style="${buttonStyles}">Sign in</a></p>
+<p style="font-size:13px;color:#6b7280">Or paste:<br><span style="word-break:break-all">{{magicLinkUrl}}</span></p>
+`),
+  bodyText: `Sign in to {{appName}} (expires in {{expiresInMinutes}} min):
+{{magicLinkUrl}}`,
+  variables: [
+    { name: 'magicLinkUrl', type: 'url', required: true },
+    { name: 'expiresInMinutes', type: 'number', required: false },
+    { name: 'appName', type: 'string', required: false },
+  ],
+  active: true,
+  isSystem: true,
+  description: 'Passwordless sign-in link sent by the magic-link plugin.',
+};
+
+export const AUTH_INVITATION_TEMPLATE: EmailTemplate = {
+  name: 'auth.invitation',
+  label: 'Organization Invitation',
+  category: 'auth',
+  locale: 'en-US',
+  subject: '{{inviter.name}} invited you to {{organization.name}}',
+  bodyHtml: wrap('You have been invited', `
+<p><strong>{{inviter.name}}</strong> ({{inviter.email}}) has invited you to join <strong>{{organization.name}}</strong> on {{appName}} as <em>{{role}}</em>.</p>
+<p style="margin:24px 0"><a href="{{{acceptUrl}}}" style="${buttonStyles}">Accept invitation</a></p>
+<p style="font-size:13px;color:#6b7280">Or paste:<br><span style="word-break:break-all">{{acceptUrl}}</span></p>
+`),
+  bodyText: `{{inviter.name}} ({{inviter.email}}) invited you to join {{organization.name}} on {{appName}}.
+
+Accept: {{acceptUrl}}`,
+  variables: [
+    { name: 'inviter.name', type: 'string', required: false },
+    { name: 'inviter.email', type: 'string', required: false },
+    { name: 'organization.name', type: 'string', required: true },
+    { name: 'role', type: 'string', required: false },
+    { name: 'acceptUrl', type: 'url', required: true },
+    { name: 'appName', type: 'string', required: false },
+  ],
+  active: true,
+  isSystem: true,
+  description: 'Sent by better-auth organization plugin when a user is invited to an org.',
+};
+
+export const AUTH_TWO_FACTOR_OTP_TEMPLATE: EmailTemplate = {
+  name: 'auth.two_factor_otp',
+  label: 'Two-Factor Verification Code',
+  category: 'auth',
+  locale: 'en-US',
+  subject: 'Your {{appName}} verification code',
+  bodyHtml: wrap('Your verification code', `
+<p>Use this code to complete sign-in:</p>
+<p style="font-size:32px;font-weight:700;letter-spacing:6px;background:#f3f4f6;padding:16px;text-align:center;border-radius:6px;margin:24px 0">{{otp}}</p>
+<p style="color:#6b7280;font-size:13px">This code expires in {{expiresInMinutes}} minutes. If you didn't try to sign in, change your password — your account may be at risk.</p>
+`),
+  bodyText: `Your {{appName}} verification code: {{otp}}
+(expires in {{expiresInMinutes}} minutes)`,
+  variables: [
+    { name: 'otp', type: 'string', required: true },
+    { name: 'expiresInMinutes', type: 'number', required: false },
+    { name: 'appName', type: 'string', required: false },
+  ],
+  active: true,
+  isSystem: true,
+  description: 'Time-based OTP delivered for two-factor / email-OTP login.',
+};
+
+export const BUILTIN_AUTH_TEMPLATES: EmailTemplate[] = [
+  AUTH_PASSWORD_RESET_TEMPLATE,
+  AUTH_VERIFY_EMAIL_TEMPLATE,
+  AUTH_MAGIC_LINK_TEMPLATE,
+  AUTH_INVITATION_TEMPLATE,
+  AUTH_TWO_FACTOR_OTP_TEMPLATE,
+];

package/src/transports/index.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { IEmailTransport } from '@objectstack/spec/contracts';
+import { LogTransport } from '../email-service.js';
+import { ResendTransport } from './resend.js';
+import { PostmarkTransport } from './postmark.js';
+
+export { ResendTransport, type ResendTransportOptions } from './resend.js';
+export { PostmarkTransport, type PostmarkTransportOptions } from './postmark.js';
+
+export interface MakeTransportOptions {
+  provider: 'log' | 'resend' | 'postmark';
+  apiKey?: string;
+  options?: Record<string, unknown>;
+  logger?: { info: (msg: string, meta?: any) => void };
+}
+
+/**
+ * Build an IEmailTransport from a provider tag + opts. Used by
+ * EmailServicePlugin to materialise the transport selected by
+ * `EmailServiceConfig.provider`.
+ *
+ * Throws when a non-`log` provider is requested without an `apiKey`.
+ */
+export function makeTransport(opts: MakeTransportOptions): IEmailTransport {
+  const { provider, apiKey, options = {}, logger } = opts;
+  switch (provider) {
+    case 'log':
+      return new LogTransport(logger);
+    case 'resend':
+      if (!apiKey) throw new Error("makeTransport: provider='resend' requires apiKey (OS_EMAIL_API_KEY)");
+      return new ResendTransport({ apiKey, ...(options as any) });
+    case 'postmark':
+      if (!apiKey) throw new Error("makeTransport: provider='postmark' requires apiKey (OS_EMAIL_API_KEY)");
+      return new PostmarkTransport({ apiKey, ...(options as any) });
+    default:
+      throw new Error(`makeTransport: unknown provider '${provider}'`);
+  }
+}