create-easy-stack 1.0.3

package/infra/email/files/src/core/infrastructure/email/email.job.spec.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { EmailDispatcher, EmailJobHandler, SEND_EMAIL } from './email.job.js';
+import { JobPayloadCipher } from '../messaging/jobs/job-payload-cipher.js';
+import type { IEmailSender } from './email-sender.port.js';
+import type { IJobQueue } from '../messaging/jobs/job-queue.port.js';
+
+const MESSAGE = {
+  to: 'jane.doe@example.com',
+  subject: 'Your code',
+  text: 'Code: 482915',
+  html: '<p>482915</p>',
+};
+
+describe('send-email job', () => {
+  let cipher: JobPayloadCipher;
+  let jobs: {
+    enqueue: ReturnType<typeof vi.fn>;
+    register: ReturnType<typeof vi.fn>;
+  };
+  let sender: { send: ReturnType<typeof vi.fn> };
+
+  beforeEach(() => {
+    cipher = new JobPayloadCipher('s'.repeat(32), 'jobs-email-v1');
+    jobs = { enqueue: vi.fn().mockResolvedValue(undefined), register: vi.fn() };
+    sender = { send: vi.fn().mockResolvedValue(undefined) };
+  });
+
+  it('retries after 10 s, 30 s and 90 s and runs five at a time', () => {
+    expect(SEND_EMAIL.name).toBe('send-email');
+    expect(SEND_EMAIL.retryDelaysMs).toEqual([10_000, 30_000, 90_000]);
+    expect(SEND_EMAIL.concurrency).toBe(5);
+  });
+
+  describe('EmailDispatcher', () => {
+    it('puts the email on the queue as one encrypted payload and nothing else (AC-5)', async () => {
+      const dispatcher = new EmailDispatcher(
+        jobs as unknown as IJobQueue,
+        cipher,
+      );
+
+      await dispatcher.dispatch(MESSAGE);
+
+      expect(jobs.enqueue).toHaveBeenCalledOnce();
+      const [job, data] = jobs.enqueue.mock.calls[0];
+      expect(job).toBe(SEND_EMAIL);
+      expect(Object.keys(data)).toEqual(['payload']);
+      const json = JSON.stringify(data);
+      expect(json).not.toContain('jane.doe');
+      expect(json).not.toContain('482915');
+      expect(cipher.decrypt(data.payload)).toEqual(MESSAGE);
+    });
+
+    it('lets the failure through when the queue cannot take the job', async () => {
+      jobs.enqueue.mockRejectedValue(new Error('queue down'));
+      const dispatcher = new EmailDispatcher(
+        jobs as unknown as IJobQueue,
+        cipher,
+      );
+
+      await expect(dispatcher.dispatch(MESSAGE)).rejects.toThrow('queue down');
+    });
+  });
+
+  describe('EmailJobHandler', () => {
+    const build = () =>
+      new EmailJobHandler(
+        jobs as unknown as IJobQueue,
+        sender as unknown as IEmailSender,
+        cipher,
+      );
+
+    it('registers itself for the send-email job when the module starts', () => {
+      build().onModuleInit();
+
+      expect(jobs.register).toHaveBeenCalledWith(
+        SEND_EMAIL,
+        expect.any(Function),
+      );
+    });
+
+    it('decrypts the payload and sends exactly that message (AC-2)', async () => {
+      await build().handle({ payload: cipher.encrypt(MESSAGE) });
+
+      expect(sender.send).toHaveBeenCalledWith(MESSAGE);
+    });
+
+    it('rethrows a failure from the provider so the job is retried (AC-3)', async () => {
+      sender.send.mockRejectedValue(new Error('provider down'));
+
+      await expect(
+        build().handle({ payload: cipher.encrypt(MESSAGE) }),
+      ).rejects.toThrow('provider down');
+    });
+
+    it('fails, rather than sending something, on a payload it cannot decrypt', async () => {
+      await expect(build().handle({ payload: 'garbage' })).rejects.toThrow();
+
+      expect(sender.send).not.toHaveBeenCalled();
+    });
+  });
+});

package/infra/email/files/src/core/infrastructure/email/email.job.ts

@@ -0,0 +1,64 @@
+import { Inject, Injectable, OnModuleInit } from '@nestjs/common';
+import {
+  defineJob,
+  JOB_QUEUE,
+  type IJobQueue,
+} from '../messaging/jobs/job-queue.port.js';
+import {
+  EMAIL_SENDER,
+  type EmailMessage,
+  type IEmailSender,
+} from './email-sender.port.js';
+import type { IEmailDispatcher } from './email-dispatcher.port.js';
+import { JobPayloadCipher } from '../messaging/jobs/job-payload-cipher.js';
+
+/** DI token for the cipher that protects email payloads in the queue. */
+export const EMAIL_PAYLOAD_CIPHER = 'EMAIL_PAYLOAD_CIPHER';
+
+/** What travels through the queue: the whole email, encrypted. */
+export interface SendEmailJobData {
+  payload: string;
+}
+
+/**
+ * Sending an email in the background. Retries after 10 s, 30 s and 90 s; after that the
+ * job is set aside in the dead-letter queue. Up to 5 emails are sent at the same time.
+ */
+export const SEND_EMAIL = defineJob<SendEmailJobData>({
+  name: 'send-email',
+  retryDelaysMs: [10_000, 30_000, 90_000],
+  concurrency: 5,
+});
+
+/** Accepts emails by putting them on the job queue. */
+@Injectable()
+export class EmailDispatcher implements IEmailDispatcher {
+  constructor(
+    @Inject(JOB_QUEUE) private readonly jobs: IJobQueue,
+    @Inject(EMAIL_PAYLOAD_CIPHER) private readonly cipher: JobPayloadCipher,
+  ) {}
+
+  dispatch(message: EmailMessage): Promise<void> {
+    return this.jobs.enqueue(SEND_EMAIL, {
+      payload: this.cipher.encrypt(message),
+    });
+  }
+}
+
+/** Runs the `send-email` jobs: decrypt, then send. A failure is rethrown so the job is retried. */
+@Injectable()
+export class EmailJobHandler implements OnModuleInit {
+  constructor(
+    @Inject(JOB_QUEUE) private readonly jobs: IJobQueue,
+    @Inject(EMAIL_SENDER) private readonly sender: IEmailSender,
+    @Inject(EMAIL_PAYLOAD_CIPHER) private readonly cipher: JobPayloadCipher,
+  ) {}
+
+  onModuleInit(): void {
+    this.jobs.register(SEND_EMAIL, (data) => this.handle(data));
+  }
+
+  async handle(data: SendEmailJobData): Promise<void> {
+    await this.sender.send(this.cipher.decrypt(data.payload));
+  }
+}

package/infra/email/files/src/core/infrastructure/email/email.module.spec.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, afterEach, beforeEach } from 'vitest';
+import { Test } from '@nestjs/testing';
+import { EmailModule } from './email.module.js';
+import { EMAIL_SENDER } from './email-sender.port.js';
+import { EMAIL_DISPATCHER } from './email-dispatcher.port.js';
+import { EmailDispatcher } from './email.job.js';
+import { LogEmailSender } from './log-email-sender.js';
+import { JobQueueModule } from '../messaging/jobs/job-queue.module.js';
+
+describe('EmailModule', () => {
+  const original = { ...process.env };
+  beforeEach(() => {
+    process.env.JOB_QUEUE = 'inline';
+    process.env.JOB_PAYLOAD_SECRET = 's'.repeat(32);
+  });
+  afterEach(() => {
+    process.env = { ...original };
+  });
+
+  it('provides the adapter chosen by EMAIL_PROVIDER under the IEmailSender token', async () => {
+    process.env.EMAIL_PROVIDER = 'log';
+
+    const moduleRef = await Test.createTestingModule({
+      imports: [JobQueueModule, EmailModule],
+    }).compile();
+
+    expect(moduleRef.get(EMAIL_SENDER)).toBeInstanceOf(LogEmailSender);
+  });
+
+  it('provides the dispatcher that other features use to send email', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [JobQueueModule, EmailModule],
+    }).compile();
+
+    expect(moduleRef.get(EMAIL_DISPATCHER)).toBeInstanceOf(EmailDispatcher);
+  });
+
+  it('sends a dispatched email through the sender, via the queue (inline: right away) (AC-9)', async () => {
+    process.env.EMAIL_PROVIDER = 'log';
+    const sent: unknown[] = [];
+    const moduleRef = await Test.createTestingModule({
+      imports: [JobQueueModule, EmailModule],
+    })
+      .overrideProvider(EMAIL_SENDER)
+      .useValue({ send: async (message: unknown) => void sent.push(message) })
+      .compile();
+    await moduleRef.init();
+
+    await moduleRef.get(EMAIL_DISPATCHER).dispatch({
+      to: 'a@example.com',
+      subject: 'Hi',
+      text: 'Hello',
+    });
+
+    expect(sent).toEqual([
+      { to: 'a@example.com', subject: 'Hi', text: 'Hello' },
+    ]);
+    await moduleRef.close();
+  });
+});

package/infra/email/files/src/core/infrastructure/email/email.module.ts

@@ -0,0 +1,34 @@
+import { Global, Module } from '@nestjs/common';
+import { EMAIL_SENDER } from './email-sender.port.js';
+import { EMAIL_DISPATCHER } from './email-dispatcher.port.js';
+import { createEmailSender } from './email-sender.factory.js';
+import { JobPayloadCipher } from '../messaging/jobs/job-payload-cipher.js';
+import {
+  EMAIL_PAYLOAD_CIPHER,
+  EmailDispatcher,
+  EmailJobHandler,
+} from './email.job.js';
+
+// Global: any feature (registration now, password reset and order mails later) can
+// inject the dispatcher without importing a feature module.
+@Global()
+@Module({
+  providers: [
+    {
+      provide: EMAIL_SENDER,
+      useFactory: () => createEmailSender(process.env),
+    },
+    {
+      provide: EMAIL_PAYLOAD_CIPHER,
+      useFactory: () =>
+        new JobPayloadCipher(
+          process.env.JOB_PAYLOAD_SECRET as string,
+          'jobs-email-v1',
+        ),
+    },
+    { provide: EMAIL_DISPATCHER, useClass: EmailDispatcher },
+    EmailJobHandler,
+  ],
+  exports: [EMAIL_SENDER, EMAIL_DISPATCHER],
+})
+export class EmailModule {}

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

@@ -0,0 +1,34 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { Logger } from '@nestjs/common';
+import { LogEmailSender } from './log-email-sender.js';
+
+describe('LogEmailSender', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('prints the whole message (including the one-time code) instead of sending it', async () => {
+    const log = vi.spyOn(Logger.prototype, 'log').mockImplementation(() => {});
+
+    await new LogEmailSender().send({
+      to: 'a@example.com',
+      subject: 'Your code',
+      text: 'Code: 123456',
+    });
+
+    const printed = String(log.mock.calls[0][0]);
+    expect(printed).toContain('a@example.com');
+    expect(printed).toContain('Your code');
+    expect(printed).toContain('123456');
+  });
+
+  it('resolves, so a caller can treat it like any other sender', async () => {
+    vi.spyOn(Logger.prototype, 'log').mockImplementation(() => {});
+
+    await expect(
+      new LogEmailSender().send({
+        to: 'a@example.com',
+        subject: 's',
+        text: 't',
+      }),
+    ).resolves.toBeUndefined();
+  });
+});

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

@@ -0,0 +1,17 @@
+import { Logger } from '@nestjs/common';
+import type { EmailMessage, IEmailSender } from './email-sender.port.js';
+
+/**
+ * Development adapter: prints the email instead of sending it, so the developer
+ * can read the one-time code from the server log. It deliberately logs the body,
+ * which is why `validateEnv` refuses it in production.
+ */
+export class LogEmailSender implements IEmailSender {
+  private readonly logger = new Logger(LogEmailSender.name);
+
+  async send(message: EmailMessage): Promise<void> {
+    this.logger.log(
+      `\n--- email (not sent: EMAIL_PROVIDER=log) ---\nTo: ${message.to}\nSubject: ${message.subject}\n\n${message.text}\n--------------------------------------------`,
+    );
+  }
+}

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

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from 'vitest';
+import nodemailer from 'nodemailer';
+import { SmtpEmailSender } from './smtp-email-sender.js';
+
+const OPTIONS = {
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  from: 'Ecom <no-reply@example.com>',
+};
+
+// nodemailer's JSON transport builds the real message but "sends" it into a string, so
+// the test sees exactly what would have gone out, without opening a connection.
+const capturing = () => {
+  const transporter = nodemailer.createTransport({ jsonTransport: true });
+  const sendMail = vi.spyOn(transporter, 'sendMail');
+  const lastMessage = async () => {
+    const info = await sendMail.mock.results[0].value;
+    return JSON.parse(info.message);
+  };
+  return { transporter, sendMail, lastMessage };
+};
+
+describe('SmtpEmailSender', () => {
+  it('sends from the configured address to the recipient with subject, text and HTML', async () => {
+    const { transporter, lastMessage } = capturing();
+
+    await new SmtpEmailSender(OPTIONS, transporter).send({
+      to: 'a@example.com',
+      subject: 'Hello',
+      text: 'plain body',
+      html: '<p>html body</p>',
+    });
+
+    const sent = await lastMessage();
+    expect(sent.from.address).toBe('no-reply@example.com');
+    expect(sent.from.name).toBe('Ecom');
+    expect(sent.to[0].address).toBe('a@example.com');
+    expect(sent.subject).toBe('Hello');
+    expect(sent.text).toBe('plain body');
+    expect(sent.html).toBe('<p>html body</p>');
+  });
+
+  it('sends a text-only message when there is no HTML', async () => {
+    const { transporter, lastMessage } = capturing();
+
+    await new SmtpEmailSender(OPTIONS, transporter).send({
+      to: 'a@example.com',
+      subject: 'Hello',
+      text: 'plain body',
+    });
+
+    const sent = await lastMessage();
+    expect(sent.text).toBe('plain body');
+    expect(sent.html).toBeUndefined();
+  });
+
+  it('rejects when the server refuses, so the caller can decide what that means', async () => {
+    const { transporter, sendMail } = capturing();
+    sendMail.mockRejectedValue(new Error('550 mailbox unavailable'));
+
+    await expect(
+      new SmtpEmailSender(OPTIONS, transporter).send({
+        to: 'a@example.com',
+        subject: 'Hello',
+        text: 'plain body',
+      }),
+    ).rejects.toThrow('550 mailbox unavailable');
+  });
+
+  it('can be built from options alone, without opening a connection', () => {
+    expect(
+      () => new SmtpEmailSender({ ...OPTIONS, user: 'apikey', pass: 'secret' }),
+    ).not.toThrow();
+  });
+
+  describe('transport security', () => {
+    const transportOptionsFor = (options: object) => {
+      const create = vi.spyOn(nodemailer, 'createTransport');
+      new SmtpEmailSender({ ...OPTIONS, ...options });
+      const passed = create.mock.calls[0][0] as { requireTLS?: boolean };
+      create.mockRestore();
+      return passed;
+    };
+
+    it('refuses to continue unencrypted when credentials go over a plain port', () => {
+      expect(transportOptionsFor({ user: 'u', pass: 'p' }).requireTLS).toBe(
+        true,
+      );
+    });
+
+    it('does not insist on TLS for an implicit-TLS port or a local relay without credentials', () => {
+      expect(
+        transportOptionsFor({ secure: true, user: 'u', pass: 'p' }).requireTLS,
+      ).toBe(false);
+      expect(transportOptionsFor({}).requireTLS).toBe(false);
+    });
+  });
+});

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

@@ -0,0 +1,63 @@
+import nodemailer from 'nodemailer';
+import type { Transporter } from 'nodemailer';
+import type { EmailMessage, IEmailSender } from './email-sender.port.js';
+
+export interface SmtpOptions {
+  host: string;
+  port: number;
+  /** TLS from the first byte (port 465). With `false` the connection is upgraded with STARTTLS when the server offers it (port 587). */
+  secure: boolean;
+  /** Both or neither: some relays accept mail from a trusted network without logging in. */
+  user?: string;
+  pass?: string;
+  /** The From header, e.g. `Ecom <no-reply@example.com>`. */
+  from: string;
+}
+
+// A provider that hangs must not hang the request that is waiting on it
+const CONNECTION_TIMEOUT_MS = 10_000;
+const GREETING_TIMEOUT_MS = 10_000;
+const SOCKET_TIMEOUT_MS = 20_000;
+
+/**
+ * Sends email through any SMTP server (a hosted provider, Gmail's SMTP, a local relay...).
+ * The message goes out as multipart text + HTML.
+ */
+export class SmtpEmailSender implements IEmailSender {
+  private readonly transporter: Transporter;
+
+  constructor(
+    private readonly options: SmtpOptions,
+    // Injectable so tests can capture the message instead of opening a connection
+    transporter?: Transporter,
+  ) {
+    this.transporter =
+      transporter ??
+      nodemailer.createTransport({
+        host: options.host,
+        port: options.port,
+        secure: options.secure,
+        // With credentials on a plain port, refuse to continue unencrypted if the server (or someone
+        // in between) drops STARTTLS, rather than send the password and codes in clear text.
+        // A local relay without credentials (e.g. a dev mail catcher) keeps working without TLS.
+        requireTLS: !options.secure && options.user !== undefined,
+        auth:
+          options.user !== undefined
+            ? { user: options.user, pass: options.pass }
+            : undefined,
+        connectionTimeout: CONNECTION_TIMEOUT_MS,
+        greetingTimeout: GREETING_TIMEOUT_MS,
+        socketTimeout: SOCKET_TIMEOUT_MS,
+      });
+  }
+
+  async send(message: EmailMessage): Promise<void> {
+    await this.transporter.sendMail({
+      from: this.options.from,
+      to: message.to,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+    });
+  }
+}

package/infra/email/infra.json

@@ -0,0 +1,58 @@
+{
+  "id": "email",
+  "label": "Email (SMTP / log adapter, sent through the job queue)",
+  "templates": ["nest-ddd"],
+  "requires": ["rabbitmq"],
+  "dependencies": {
+    "nodemailer": "^10.0.13"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^8.0.2"
+  },
+  "env": [
+    "# Email — 'log' only prints messages (dev); 'smtp' sends through any SMTP server",
+    "EMAIL_PROVIDER=log",
+    "SMTP_HOST=",
+    "SMTP_PORT=587",
+    "SMTP_USER=",
+    "SMTP_PASS=",
+    "EMAIL_FROM=\"{{PROJECT_NAME}} <no-reply@example.com>\"",
+    "# Encrypts job payloads (email addresses, one-time codes) in the queue. >= 32 chars",
+    "JOB_PAYLOAD_SECRET=change-me-to-a-random-string-of-32-chars-or-more"
+  ],
+  "inject": [
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:imports",
+      "lines": ["import { EmailModule } from './core/infrastructure/email/email.module.js';"]
+    },
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:modules",
+      "lines": ["EmailModule,"]
+    },
+    {
+      "file": "src/core/index.ts",
+      "marker": "// @infra:barrel",
+      "lines": [
+        "export * from './infrastructure/email/email-sender.port.js';",
+        "export * from './infrastructure/email/email-dispatcher.port.js';",
+        "export * from './infrastructure/email/email-layout.js';",
+        "export * from './infrastructure/email/email-sender.factory.js';",
+        "export * from './infrastructure/email/log-email-sender.js';",
+        "export * from './infrastructure/email/smtp-email-sender.js';",
+        "export * from './infrastructure/email/email.module.js';"
+      ]
+    },
+    {
+      "file": "src/core/config/env.validation.ts",
+      "marker": "// @infra:env-imports",
+      "lines": ["import { validateEmailEnv } from './email.env.js';"]
+    },
+    {
+      "file": "src/core/config/env.validation.ts",
+      "marker": "// @infra:env-checks",
+      "lines": ["validateEmailEnv(config, errors);"]
+    }
+  ]
+}

package/infra/prisma-postgres/docker.service.yml

@@ -0,0 +1,12 @@
+postgres:
+  image: postgres:15-alpine
+  container_name: {{PROJECT_NAME_SNAKE}}_postgres
+  environment:
+    POSTGRES_USER: root
+    POSTGRES_PASSWORD: rootpassword
+    POSTGRES_DB: {{PROJECT_NAME_SNAKE}}_db
+  ports:
+    - '5432:5432'
+  volumes:
+    - postgres_data:/var/lib/postgresql/data
+  restart: unless-stopped

package/infra/prisma-postgres/files/prisma/schema.prisma

@@ -0,0 +1,10 @@
+// Prisma schema. Models are added here; migrations live in prisma/migrations.
+// Always use `pnpm prisma:migrate` (never `prisma db push`) so every change leaves a migration file.
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+}

package/infra/prisma-postgres/files/prisma.config.mjs

@@ -0,0 +1,10 @@
+import 'dotenv/config';
+import { defineConfig } from 'prisma/config';
+
+export default defineConfig({
+  schema: 'prisma/schema.prisma',
+  migrations: { path: 'prisma/migrations' },
+  datasource: {
+    url: process.env.DATABASE_URL,
+  },
+});

package/infra/prisma-postgres/files/src/core/config/database.env.ts

@@ -0,0 +1,13 @@
+/** DATABASE_URL must be a postgres:// connection string. */
+export function validateDatabaseEnv(
+  config: Record<string, unknown>,
+  errors: string[],
+): void {
+  const databaseUrl = config.DATABASE_URL;
+  if (
+    typeof databaseUrl !== 'string' ||
+    !/^postgres(ql)?:\/\/.+/.test(databaseUrl)
+  ) {
+    errors.push('DATABASE_URL must be set to a postgres:// connection string');
+  }
+}

package/infra/prisma-postgres/files/src/core/infrastructure/database/database.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from '@nestjs/common';
+import { PrismaService } from './prisma.service.js';
+
+@Global()
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class DatabaseModule {}

package/infra/prisma-postgres/files/src/core/infrastructure/database/prisma.service.ts

@@ -0,0 +1,26 @@
+import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+
+import pg from 'pg';
+import { PrismaPg } from '@prisma/adapter-pg';
+
+@Injectable()
+export class PrismaService
+  extends PrismaClient
+  implements OnModuleInit, OnModuleDestroy
+{
+  constructor() {
+    const connectionString = process.env.DATABASE_URL;
+    const pool = new pg.Pool({ connectionString });
+    const adapter = new PrismaPg(pool);
+    super({ adapter });
+  }
+
+  async onModuleInit() {
+    await this.$connect();
+  }
+
+  async onModuleDestroy() {
+    await this.$disconnect();
+  }
+}