create-easy-stack 1.0.3

package/bin/create.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import prompts from 'prompts';
+import { loadInfra, loadTemplates } from '../lib/registry.mjs';
+import {
+  addInfraToProject,
+  createProject,
+  initGit,
+  installDependencies,
+  isValidProjectName,
+} from '../lib/scaffold.mjs';
+
+const c = {
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+};
+
+const HELP = `
+${c.bold('create-my-stack')} — personal project generator
+
+${c.bold('Usage')}
+  create-my-stack [name] [options]      create a project
+  create-my-stack add <infra...>        add infra to the project in --dir (default: .)
+  create-my-stack list                  show templates and infra
+
+${c.bold('Options')}
+  -t, --template <id>     template id (see "list")
+  -i, --infra <a,b,c>     infra modules, comma separated (backend templates)
+      --no-infra          skip the infra question
+      --pm <pnpm|npm|yarn|bun>   package manager (default: the one that launched the CLI, else pnpm)
+      --install / --no-install   run the install step
+      --git / --no-git           run "git init"
+  -d, --dir <path>        target directory for "add"
+  -y, --yes               accept defaults, never prompt
+  -h, --help
+`;
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    template: { type: 'string', short: 't' },
+    infra: { type: 'string', short: 'i' },
+    'no-infra': { type: 'boolean' },
+    pm: { type: 'string' },
+    install: { type: 'boolean' },
+    'no-install': { type: 'boolean' },
+    git: { type: 'boolean' },
+    'no-git': { type: 'boolean' },
+    dir: { type: 'string', short: 'd' },
+    yes: { type: 'boolean', short: 'y' },
+    help: { type: 'boolean', short: 'h' },
+  },
+});
+
+const interactive = !values.yes && process.stdin.isTTY && process.stdout.isTTY;
+const onCancel = () => {
+  console.log(c.yellow('\nCancelled.'));
+  process.exit(1);
+};
+const log = (message) => console.log(c.dim(message));
+
+function detectPackageManager() {
+  const agent = process.env.npm_config_user_agent ?? '';
+  const match = /^(pnpm|yarn|bun|npm)\//.exec(agent);
+  return match ? match[1] : 'pnpm';
+}
+
+function printList() {
+  const templates = loadTemplates();
+  const infra = loadInfra();
+  console.log(`\n${c.bold('Templates')}`);
+  for (const t of templates) {
+    console.log(`  ${c.cyan(t.id.padEnd(18))} ${t.label} ${c.dim(`— ${t.description}`)}`);
+  }
+  console.log(`\n${c.bold('Infra')} ${c.dim('(backend templates)')}`);
+  for (const i of infra) {
+    const requires = i.requires?.length ? c.dim(` (needs ${i.requires.join(', ')})`) : '';
+    console.log(`  ${c.cyan(i.id.padEnd(18))} ${i.label}${requires}`);
+  }
+  console.log();
+}
+
+async function runAdd() {
+  const projectDir = path.resolve(values.dir ?? '.');
+  const requested = positionals.slice(1);
+  if (requested.length === 0) {
+    console.error(c.red('Usage: create-my-stack add <infra...>'));
+    process.exit(1);
+  }
+  const result = addInfraToProject({
+    projectDir,
+    infra: requested,
+    availableInfra: loadInfra(),
+    log,
+  });
+  for (const { id, because } of result.autoAdded) {
+    console.log(c.yellow(`  ${id} was added too because ${because} needs it`));
+  }
+  console.log(
+    c.green(`\nAdded: ${result.added.map((i) => i.id).join(', ') || 'nothing new'}`),
+  );
+  console.log(c.dim('Run the install step again, then review .env.example / docker-compose.yml.\n'));
+}
+
+async function runCreate() {
+  const templates = loadTemplates();
+  const availableInfra = loadInfra();
+
+  // 1. Project name
+  let name = positionals[0];
+  if (!name && interactive) {
+    ({ name } = await prompts(
+      {
+        type: 'text',
+        name: 'name',
+        message: 'Project name',
+        initial: 'my-app',
+        validate: (v) => isValidProjectName(v) || 'Use lowercase letters, digits, - . _ ~',
+      },
+      { onCancel },
+    ));
+  }
+  name ??= 'my-app';
+  if (!isValidProjectName(path.basename(name))) {
+    console.error(c.red(`Invalid project name "${name}"`));
+    process.exit(1);
+  }
+  const projectDir = path.resolve(name);
+  if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {
+    console.error(c.red(`Directory ${projectDir} already exists and is not empty.`));
+    process.exit(1);
+  }
+
+  // 2. Template
+  let templateId = values.template;
+  if (!templateId && interactive) {
+    ({ templateId } = await prompts(
+      {
+        type: 'select',
+        name: 'templateId',
+        message: 'Template',
+        choices: templates.map((t) => ({
+          title: `${t.label}`,
+          description: t.description,
+          value: t.id,
+        })),
+      },
+      { onCancel },
+    ));
+  }
+  const template = templates.find((t) => t.id === templateId);
+  if (!template) {
+    console.error(c.red(`Pick a template with --template. Available: ${templates.map((t) => t.id).join(', ')}`));
+    process.exit(1);
+  }
+
+  // 3. Infra (backend templates only)
+  let infra = [];
+  if (template.supportsInfra) {
+    const choices = availableInfra.filter(
+      (i) => !i.templates || i.templates.includes(template.id),
+    );
+    if (values.infra) {
+      infra = values.infra.split(',').map((s) => s.trim()).filter(Boolean);
+    } else if (!values['no-infra'] && interactive) {
+      ({ infra } = await prompts(
+        {
+          type: 'multiselect',
+          name: 'infra',
+          message: 'Infra to include',
+          hint: '- space to select, enter to confirm',
+          instructions: false,
+          choices: choices.map((i) => ({
+            title: i.label,
+            value: i.id,
+            selected: i.default === true,
+          })),
+        },
+        { onCancel },
+      ));
+    } else if (!values['no-infra']) {
+      infra = choices.filter((i) => i.default).map((i) => i.id);
+    }
+  }
+
+  // 4. Install / git
+  const packageManager = values.pm ?? detectPackageManager();
+  const ask = async (flagOn, flagOff, message, initial) => {
+    if (values[flagOn]) return true;
+    if (values[flagOff]) return false;
+    if (!interactive) return initial;
+    const { answer } = await prompts(
+      { type: 'confirm', name: 'answer', message, initial },
+      { onCancel },
+    );
+    return answer;
+  };
+  const doGit = await ask('git', 'no-git', 'Initialise a git repository?', true);
+  const doInstall = await ask('install', 'no-install', `Install dependencies with ${packageManager}?`, false);
+
+  // 5. Go
+  console.log(`\n${c.bold(`Creating ${name}`)} ${c.dim(`from ${template.id}`)}`);
+  const result = createProject({ template, infra, projectDir, availableInfra, log });
+  for (const { id, because } of result.autoAdded) {
+    console.log(c.yellow(`  ${id} was added too because ${because} needs it`));
+  }
+  if (doGit) initGit(projectDir);
+  if (doInstall) {
+    console.log(c.dim(`\n${packageManager} install ...`));
+    if (!installDependencies(projectDir, packageManager)) {
+      console.log(c.yellow('Install failed — run it yourself after fixing the error above.'));
+    }
+  }
+
+  const rel = path.relative(process.cwd(), projectDir) || '.';
+  const run = (script) => (packageManager === 'npm' ? `npm run ${script}` : `${packageManager} ${script}`);
+  console.log(`\n${c.green('Done!')} Next steps:\n`);
+  console.log(`  cd ${rel}`);
+  if (!doInstall) console.log(`  ${packageManager} install`);
+  if (result.infra.some((i) => i.docker)) console.log('  docker compose up -d');
+  for (const step of template.nextSteps ?? []) console.log(`  ${run(step)}`);
+  console.log(`\n${c.dim('Generators: ')}${run('gen')} ${c.dim('(plop) — see README.md in the project.')}\n`);
+}
+
+try {
+  if (values.help) {
+    console.log(HELP);
+  } else if (positionals[0] === 'list') {
+    printList();
+  } else if (positionals[0] === 'add') {
+    await runAdd();
+  } else {
+    await runCreate();
+  }
+} catch (error) {
+  console.error(c.red(`\n${error.message}`));
+  process.exit(1);
+}

package/infra/email/files/src/core/config/email.env.ts

@@ -0,0 +1,73 @@
+const JOB_PAYLOAD_SECRET_MIN_LENGTH = 32;
+// `log` only prints messages, so it is for development; `smtp` works everywhere.
+const EMAIL_PROVIDERS = ['log', 'smtp'];
+const DEV_ONLY_EMAIL_PROVIDERS = ['log'];
+
+const present = (config: Record<string, unknown>, name: string) =>
+  typeof config[name] === 'string' && (config[name] as string).trim() !== '';
+
+export function validateEmailEnv(
+  config: Record<string, unknown>,
+  errors: string[],
+): void {
+  const secret = config.JOB_PAYLOAD_SECRET;
+  if (typeof secret !== 'string' || secret.length < JOB_PAYLOAD_SECRET_MIN_LENGTH) {
+    errors.push(
+      `JOB_PAYLOAD_SECRET must be set to a string of at least ${JOB_PAYLOAD_SECRET_MIN_LENGTH} characters`,
+    );
+  }
+
+  const provider = (config.EMAIL_PROVIDER ?? 'log') as string;
+  if (!EMAIL_PROVIDERS.includes(provider)) {
+    errors.push(
+      `EMAIL_PROVIDER must be one of: ${EMAIL_PROVIDERS.join(', ')} (got "${provider}")`,
+    );
+    return;
+  }
+  if (
+    config.NODE_ENV === 'production' &&
+    DEV_ONLY_EMAIL_PROVIDERS.includes(provider)
+  ) {
+    // The log adapter prints one-time codes; it must never run in production
+    errors.push(
+      `EMAIL_PROVIDER=${provider} only prints emails and is not allowed in production; configure a real provider`,
+    );
+  }
+  if (provider === 'smtp') validateSmtp(config, errors);
+}
+
+/** What `EMAIL_PROVIDER=smtp` needs: where to connect, who to send as, and (optionally) a login. */
+function validateSmtp(config: Record<string, unknown>, errors: string[]): void {
+  if (!present(config, 'SMTP_HOST')) {
+    errors.push('SMTP_HOST must be set when EMAIL_PROVIDER=smtp');
+  }
+
+  if (config.SMTP_PORT !== undefined) {
+    const port = Number(config.SMTP_PORT);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+      errors.push('SMTP_PORT must be a valid integer between 1 and 65535');
+    }
+  }
+
+  if (
+    config.SMTP_SECURE !== undefined &&
+    config.SMTP_SECURE !== 'true' &&
+    config.SMTP_SECURE !== 'false'
+  ) {
+    errors.push('SMTP_SECURE must be "true" or "false"');
+  }
+
+  // A login is a pair: a user without a password (or the reverse) can never work
+  if (present(config, 'SMTP_USER') !== present(config, 'SMTP_PASS')) {
+    errors.push('SMTP_USER and SMTP_PASS must be set together');
+  }
+
+  if (
+    !present(config, 'EMAIL_FROM') ||
+    !(config.EMAIL_FROM as string).includes('@')
+  ) {
+    errors.push(
+      'EMAIL_FROM must be set to a sender address when EMAIL_PROVIDER=smtp, e.g. "App <no-reply@example.com>"',
+    );
+  }
+}

package/infra/email/files/src/core/infrastructure/email/email-dispatcher.port.ts

@@ -0,0 +1,13 @@
+import type { EmailMessage } from './email-sender.port.js';
+
+/**
+ * Hands an email over for delivery. Unlike `IEmailSender.send`, it returns once the message
+ * is accepted, not once it is delivered: the actual sending happens in the background, with
+ * retries. Rejects only when the message could not be accepted (the queue is unavailable).
+ */
+export interface IEmailDispatcher {
+  dispatch(message: EmailMessage): Promise<void>;
+}
+
+/** DI token for the active IEmailDispatcher. */
+export const EMAIL_DISPATCHER = 'IEmailDispatcher';

package/infra/email/files/src/core/infrastructure/email/email-layout.spec.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+import { renderEmail } from './email-layout.js';
+
+const CONTENT = {
+  appName: 'Ecom',
+  heading: 'Xác thực địa chỉ email của bạn',
+  paragraphs: ['Dùng mã dưới đây để hoàn tất đăng ký.'],
+  highlight: '482915',
+  afterParagraphs: ['Mã có hiệu lực trong 10 phút.'],
+  reason: 'Bạn nhận email này vì đã đăng ký tại Ecom.',
+};
+
+describe('renderEmail', () => {
+  it('puts the shop name, heading, paragraphs, highlighted value and footer in both versions', () => {
+    const { html, text } = renderEmail(CONTENT);
+
+    for (const part of [
+      'Ecom',
+      CONTENT.heading,
+      CONTENT.paragraphs[0],
+      '482915',
+      CONTENT.afterParagraphs[0],
+      CONTENT.reason,
+    ]) {
+      expect(html).toContain(part);
+      expect(text).toContain(part);
+    }
+  });
+
+  it('produces a complete HTML document a mail client can render', () => {
+    const { html } = renderEmail(CONTENT);
+
+    expect(html.startsWith('<!doctype html>')).toBe(true);
+    expect(html).toContain('<html lang="vi">');
+    expect(html).toContain('charset="utf-8"');
+    expect(html).toContain('name="viewport"');
+    expect(html).toContain('</html>');
+  });
+
+  it('escapes everything it was given, so markup in a value cannot change the page', () => {
+    const { html, text } = renderEmail({
+      ...CONTENT,
+      appName: '<b>Shop & Co</b>',
+      paragraphs: ['<script>alert("x")</script>'],
+      highlight: '<img src=x>',
+      reason: "it's <i>fine</i>",
+    });
+
+    expect(html).not.toContain('<script>');
+    expect(html).not.toContain('<img src=x>');
+    expect(html).not.toContain('<b>Shop');
+    expect(html).toContain('&lt;b&gt;Shop &amp; Co&lt;/b&gt;');
+    expect(html).toContain('&lt;script&gt;alert(&quot;x&quot;)&lt;/script&gt;');
+    expect(html).toContain('it&#39;s &lt;i&gt;fine&lt;/i&gt;');
+    // the plain-text version has no markup to escape, so it keeps the raw text
+    expect(text).toContain('<b>Shop & Co</b>');
+  });
+
+  it('works without a highlighted value or trailing paragraphs', () => {
+    const { html, text } = renderEmail({
+      appName: 'Ecom',
+      heading: 'Hello',
+      paragraphs: ['Just a note.'],
+      reason: 'Because.',
+    });
+
+    expect(html).toContain('Just a note.');
+    expect(html).not.toContain('letter-spacing');
+    expect(text).toBe(
+      ['Ecom', '', 'Hello', '', 'Just a note.', '', '--', 'Because.'].join(
+        '\n',
+      ),
+    );
+  });
+
+  it('writes the plain-text version readable on its own, with the footer set apart', () => {
+    const { text } = renderEmail(CONTENT);
+
+    expect(text.startsWith('Ecom\n\n' + CONTENT.heading)).toBe(true);
+    expect(text).toContain('    482915');
+    expect(text.endsWith(`--\n${CONTENT.reason}`)).toBe(true);
+  });
+});

package/infra/email/files/src/core/infrastructure/email/email-layout.ts

@@ -0,0 +1,88 @@
+export interface EmailLayoutContent {
+  /** The shop's name, shown at the top and used in the footer. */
+  appName: string;
+  heading: string;
+  /** Paragraphs before the highlighted value. */
+  paragraphs: string[];
+  /** A value the reader has to copy (e.g. a one-time code), shown large on its own line. */
+  highlight?: string;
+  /** Paragraphs after the highlighted value. */
+  afterParagraphs?: string[];
+  /** Why the reader got this email, shown in the footer. */
+  reason: string;
+}
+
+export interface RenderedEmail {
+  html: string;
+  text: string;
+}
+
+const escapeHtml = (value: string): string =>
+  value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+
+const FONT = 'Arial, Helvetica, sans-serif';
+
+/**
+ * The one look every email shares: the shop's name on top, the content, and a footer
+ * saying why it was sent. Each kind of email only supplies its words; the HTML (inline
+ * styles and tables, because mail clients ignore most of modern CSS) and the plain-text
+ * twin both come from here, so they can't drift apart. All text is escaped, so a value
+ * with markup in it can't change the page.
+ */
+export function renderEmail(content: EmailLayoutContent): RenderedEmail {
+  const { appName, heading, paragraphs, highlight, afterParagraphs, reason } =
+    content;
+  const after = afterParagraphs ?? [];
+
+  const paragraph = (value: string) =>
+    `<p style="margin:0 0 16px;font-size:15px;line-height:1.6;color:#374151;">${escapeHtml(value)}</p>`;
+
+  const highlightBlock = highlight
+    ? `<div style="margin:8px 0 24px;padding:16px;background:#f3f4f6;border-radius:6px;text-align:center;font-size:32px;font-weight:bold;letter-spacing:8px;color:#111827;">${escapeHtml(highlight)}</div>`
+    : '';
+
+  const html = `<!doctype html>
+<html lang="vi">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(heading)}</title>
+</head>
+<body style="margin:0;padding:0;background:#f4f5f7;">
+<table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="background:#f4f5f7;padding:24px 0;">
+<tr><td align="center">
+<table role="presentation" width="480" cellspacing="0" cellpadding="0" style="width:100%;max-width:480px;background:#ffffff;border-radius:8px;">
+<tr><td style="padding:32px;font-family:${FONT};">
+<div style="margin:0 0 24px;font-size:18px;font-weight:bold;color:#111827;">${escapeHtml(appName)}</div>
+<h1 style="margin:0 0 16px;font-size:20px;line-height:1.3;color:#111827;">${escapeHtml(heading)}</h1>
+${paragraphs.map(paragraph).join('\n')}
+${highlightBlock}
+${after.map(paragraph).join('\n')}
+<hr style="margin:24px 0 16px;border:0;border-top:1px solid #e5e7eb;">
+<p style="margin:0;font-size:12px;line-height:1.5;color:#6b7280;">${escapeHtml(reason)}</p>
+</td></tr>
+</table>
+</td></tr>
+</table>
+</body>
+</html>`;
+
+  const text = [
+    appName,
+    '',
+    heading,
+    '',
+    ...paragraphs.flatMap((value) => [value, '']),
+    ...(highlight ? [`    ${highlight}`, ''] : []),
+    ...after.flatMap((value) => [value, '']),
+    '--',
+    reason,
+  ].join('\n');
+
+  return { html, text };
+}

package/infra/email/files/src/core/infrastructure/email/email-sender.factory.spec.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createEmailSender,
+  smtpOptionsFromEnv,
+} from './email-sender.factory.js';
+import { LogEmailSender } from './log-email-sender.js';
+import { SmtpEmailSender } from './smtp-email-sender.js';
+
+const SMTP_ENV = {
+  EMAIL_PROVIDER: 'smtp',
+  SMTP_HOST: 'smtp.example.com',
+  EMAIL_FROM: 'Ecom <no-reply@example.com>',
+};
+
+describe('createEmailSender', () => {
+  it('uses the log adapter for "log"', () => {
+    expect(createEmailSender({ EMAIL_PROVIDER: 'log' })).toBeInstanceOf(
+      LogEmailSender,
+    );
+  });
+
+  it('defaults to the log adapter when EMAIL_PROVIDER is not set', () => {
+    expect(createEmailSender({})).toBeInstanceOf(LogEmailSender);
+  });
+
+  it('uses the SMTP adapter for "smtp"', () => {
+    expect(createEmailSender(SMTP_ENV)).toBeInstanceOf(SmtpEmailSender);
+  });
+
+  it('fails loudly for a provider it does not know, instead of silently not sending', () => {
+    expect(() =>
+      createEmailSender({ EMAIL_PROVIDER: 'carrier-pigeon' }),
+    ).toThrow(/carrier-pigeon/);
+  });
+});
+
+describe('smtpOptionsFromEnv', () => {
+  it('defaults to port 587 with STARTTLS (not TLS from the first byte)', () => {
+    expect(smtpOptionsFromEnv(SMTP_ENV)).toEqual({
+      host: 'smtp.example.com',
+      port: 587,
+      secure: false,
+      user: undefined,
+      pass: undefined,
+      from: 'Ecom <no-reply@example.com>',
+    });
+  });
+
+  it('turns on TLS from the first byte for port 465', () => {
+    expect(smtpOptionsFromEnv({ ...SMTP_ENV, SMTP_PORT: '465' })).toMatchObject(
+      {
+        port: 465,
+        secure: true,
+      },
+    );
+  });
+
+  it('lets SMTP_SECURE override what the port suggests', () => {
+    expect(
+      smtpOptionsFromEnv({
+        ...SMTP_ENV,
+        SMTP_PORT: '465',
+        SMTP_SECURE: 'false',
+      }),
+    ).toMatchObject({ secure: false });
+    expect(
+      smtpOptionsFromEnv({
+        ...SMTP_ENV,
+        SMTP_PORT: '2465',
+        SMTP_SECURE: 'true',
+      }),
+    ).toMatchObject({ port: 2465, secure: true });
+  });
+
+  it('passes the login through, and treats empty values as no login', () => {
+    expect(
+      smtpOptionsFromEnv({
+        ...SMTP_ENV,
+        SMTP_USER: 'apikey',
+        SMTP_PASS: 'secret',
+      }),
+    ).toMatchObject({ user: 'apikey', pass: 'secret' });
+    expect(
+      smtpOptionsFromEnv({ ...SMTP_ENV, SMTP_USER: '', SMTP_PASS: '' }),
+    ).toMatchObject({ user: undefined, pass: undefined });
+  });
+});

package/infra/email/files/src/core/infrastructure/email/email-sender.factory.ts

@@ -0,0 +1,35 @@
+import type { IEmailSender } from './email-sender.port.js';
+import { LogEmailSender } from './log-email-sender.js';
+import { SmtpEmailSender, type SmtpOptions } from './smtp-email-sender.js';
+
+const DEFAULT_SMTP_PORT = 587;
+const IMPLICIT_TLS_PORT = 465;
+
+/** Reads the SMTP settings (already checked by `validateEnv`) from the environment. */
+export function smtpOptionsFromEnv(env: NodeJS.ProcessEnv): SmtpOptions {
+  const port = env.SMTP_PORT ? Number(env.SMTP_PORT) : DEFAULT_SMTP_PORT;
+  return {
+    host: env.SMTP_HOST as string,
+    port,
+    // Port 465 speaks TLS from the first byte; other ports start plain and upgrade
+    secure: env.SMTP_SECURE
+      ? env.SMTP_SECURE === 'true'
+      : port === IMPLICIT_TLS_PORT,
+    user: env.SMTP_USER || undefined,
+    pass: env.SMTP_PASS || undefined,
+    from: env.EMAIL_FROM as string,
+  };
+}
+
+/** Picks the adapter for `EMAIL_PROVIDER` (validated at boot by `validateEnv`). */
+export function createEmailSender(env: NodeJS.ProcessEnv): IEmailSender {
+  const provider = env.EMAIL_PROVIDER ?? 'log';
+  switch (provider) {
+    case 'log':
+      return new LogEmailSender();
+    case 'smtp':
+      return new SmtpEmailSender(smtpOptionsFromEnv(env));
+    default:
+      throw new Error(`Unknown EMAIL_PROVIDER "${provider}"`);
+  }
+}

package/infra/email/files/src/core/infrastructure/email/email-sender.port.ts

@@ -0,0 +1,19 @@
+export interface EmailMessage {
+  to: string;
+  subject: string;
+  /** Plain-text body. Always present: it is what text-only clients show and what spam filters like to see alongside the HTML. */
+  text: string;
+  /** HTML body. Sent together with `text` as a multipart message. */
+  html?: string;
+}
+
+/**
+ * Sends an email. One adapter per provider; the rest of the app only knows this port.
+ * `send` rejects when the provider fails, so callers decide whether that matters.
+ */
+export interface IEmailSender {
+  send(message: EmailMessage): Promise<void>;
+}
+
+/** DI token for the active IEmailSender. */
+export const EMAIL_SENDER = 'IEmailSender';