@lenne.tech/nest-server 11.31.3 → 11.32.1

package/src/core/common/services/brevo.service.ts

@@ -1,27 +1,50 @@
-import { SendSmtpEmail, TransactionalEmailsApi, TransactionalEmailsApiApiKeys } from '@getbrevo/brevo';
-import { Injectable } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+
+import type { Brevo, BrevoClient } from '@getbrevo/brevo';
 
 import { ConfigService } from './config.service';
 
 /**
  * Brevo service to send transactional emails
+ *
+ * ## Return contract
+ *
+ * Both send methods resolve to one of four things, and callers on security-critical paths
+ * (verification, password reset, magic link) MUST distinguish them:
+ *
+ * | Value | Meaning |
+ * |-------|---------|
+ * | `false` | Rejected before sending — a required argument was missing |
+ * | `'TEST_USER!'` | Recipient matched `brevo.exclude`, nothing was sent (by design) |
+ * | `null` | The send FAILED. The error was logged, not thrown |
+ * | otherwise | The Brevo `SendTransacEmailResponse` (`{ messageId?, messageIds? }`) |
+ *
+ * A `null` is the one that bites: treating "did not throw" as "was delivered" silently drops mail.
+ * Set `brevo.throwOnError: true` if you would rather have the exception propagate.
  */
 @Injectable()
 export class BrevoService {
   brevoConfig: ConfigService['configFastButReadOnly']['brevo'];
-  private apiInstance: TransactionalEmailsApi;
+  protected readonly logger = new Logger(BrevoService.name);
+  private client: BrevoClient | undefined;
 
   constructor(protected configService: ConfigService) {
     this.brevoConfig = configService.configFastButReadOnly.brevo;
     if (!this.brevoConfig) {
       throw new Error('Brevo configuration not set!');
     }
-    this.apiInstance = new TransactionalEmailsApi();
-    this.apiInstance.setApiKey(TransactionalEmailsApiApiKeys.apiKey, this.brevoConfig.apiKey);
   }
 
   /**
    * Send a transactional email via Brevo
+   *
+   * @param to - Recipient email address
+   * @param templateId - Brevo template id
+   * @param params - Template parameters. These are rendered SERVER-SIDE by the Brevo template
+   *   engine, so any user-controlled value placed here is content-injection surface owned by
+   *   whoever wrote the template — escape it there, or do not pass it.
+   * @returns The Brevo response, `false` on missing input, `'TEST_USER!'` when excluded, `null` on failure
    */
   async sendMail(to: string, templateId: number, params?: object): Promise<unknown> {
     try {
@@ -37,25 +60,31 @@ export class BrevoService {
       }
 
       // Prepare data
-      const sendSmtpEmail: SendSmtpEmail = {
-        params,
+      const request: Brevo.SendTransacEmailRequest = {
+        headers: this.buildIdempotencyHeaders(),
+        // The public signature keeps the wider `object` so existing callers stay source-compatible;
+        // the SDK narrowed its own field to an index-signature type in v6.
+        params: params as Record<string, unknown>,
         templateId,
         to: [{ email: to }],
       };
 
       // Send email
-      const result = await this.apiInstance.sendTransacEmail(sendSmtpEmail);
-      return result.body;
+      const client = await this.getClient();
+      return await client.transactionalEmails.sendTransacEmail(request);
     } catch (error) {
-      console.error(error);
+      return this.handleSendError(error, to);
     }
-
-    // Return null if error
-    return null;
   }
 
   /**
    * Send HTML mail
+   *
+   * @param to - Recipient email address
+   * @param subject - Email subject
+   * @param html - HTML body
+   * @param options - Optional template parameters
+   * @returns The Brevo response, `false` on missing input, `'TEST_USER!'` when excluded, `null` on failure
    */
   async sendHtmlMail(
     to: string,
@@ -76,7 +105,8 @@ export class BrevoService {
       }
 
       // Prepare data
-      const sendSmtpEmail: SendSmtpEmail = {
+      const request: Brevo.SendTransacEmailRequest = {
+        headers: this.buildIdempotencyHeaders(),
         htmlContent: html,
         params: options?.params,
         sender: this.brevoConfig.sender,
@@ -85,12 +115,65 @@ export class BrevoService {
       };
 
       // Send email
-      const result = await this.apiInstance.sendTransacEmail(sendSmtpEmail);
-      return result.body;
+      const client = await this.getClient();
+      return await client.transactionalEmails.sendTransacEmail(request);
     } catch (error) {
-      console.error(error);
+      return this.handleSendError(error, to);
     }
+  }
+
+  /**
+   * Builds the per-send idempotency header.
+   *
+   * The SDK retries POSTs on 408/429/5xx. Without a key, a retry issued after a response that was
+   * actually delivered (but whose reply was lost) sends the mail twice. Brevo deduplicates on
+   * `Idempotency-Key`.
+   *
+   * @returns Custom headers for the send request
+   */
+  protected buildIdempotencyHeaders(): Record<string, unknown> {
+    return { 'Idempotency-Key': randomUUID() };
+  }
 
+  /**
+   * Lazily constructs (and memoises) the Brevo SDK client.
+   *
+   * The import is dynamic on purpose: `@getbrevo/brevo` pulls in ~580 CommonJS modules, and
+   * `BrevoService` is re-exported from the package barrel. A static import would put that cost on
+   * every consumer's cold start, including the majority that never configure Brevo at all.
+   *
+   * @returns The memoised SDK client
+   */
+  protected async getClient(): Promise<BrevoClient> {
+    if (!this.client) {
+      const { BrevoClient: BrevoClientCtor } = await import('@getbrevo/brevo');
+      this.client = new BrevoClientCtor({
+        apiKey: this.brevoConfig.apiKey,
+        // The SDK defaults to 2 retries honouring `Retry-After` with a 60 s cap PER attempt, and to
+        // no timeout at all. Both send methods are awaited inside request handlers, so those
+        // defaults let a rate-limited Brevo park a user-facing request for roughly two minutes.
+        maxRetries: this.brevoConfig.maxRetries ?? 0,
+        timeoutInSeconds: this.brevoConfig.timeoutInSeconds ?? 10,
+      });
+    }
+    return this.client;
+  }
+
+  /**
+   * Logs a failed send through the Nest logger and applies the configured failure policy.
+   *
+   * @param error - The thrown SDK error
+   * @param to - Recipient, for correlation
+   * @returns `null` (the historical contract) unless `brevo.throwOnError` is set
+   * @throws The original error when `brevo.throwOnError` is `true`
+   */
+  protected handleSendError(error: unknown, to: string): null {
+    this.logger.error(
+      `Brevo sendTransacEmail failed for ${to}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    if (this.brevoConfig.throwOnError) {
+      throw error;
+    }
     // Return null if error
     return null;
   }

package/src/core/modules/better-auth/core-better-auth-email-verification.service.ts

@@ -180,15 +180,25 @@ export class CoreBetterAuthEmailVerificationService {
     if (this.config.brevoTemplateId && this.brevoService) {
       try {
         const appName = this.getAppName();
-        await this.brevoService.sendMail(user.email, this.config.brevoTemplateId, {
+        const result = await this.brevoService.sendMail(user.email, this.config.brevoTemplateId, {
           appName,
           expiresIn: this.formatExpiresIn(this.config.expiresIn),
           link: url,
           name: user.name || user.email.split('@')[0],
         });
-        this.trackSend(user.email);
-        this.logger.debug(`Verification email sent via Brevo to ${this.maskEmail(user.email)}`);
-        return;
+
+        // `sendMail()` swallows SDK errors and resolves to `null` (unless `brevo.throwOnError` is
+        // set), so "did not throw" is NOT "was delivered". Recording a send here on a null would
+        // mark the address as mailed, log success, and skip the SMTP fallback below — leaving the
+        // user with no verification email at all on a Brevo outage or a revoked key.
+        if (result === null) {
+          this.logger.error(`Brevo verification send failed for ${this.maskEmail(user.email)} — falling back to SMTP`);
+          // Deliberately no `return`: fall through to the EmailService path.
+        } else {
+          this.trackSend(user.email);
+          this.logger.debug(`Verification email sent via Brevo to ${this.maskEmail(user.email)}`);
+          return;
+        }
       } catch (error) {
         this.logger.error(
           `Failed to send verification email via Brevo to ${this.maskEmail(user.email)}: ${error instanceof Error ? error.message : 'Unknown error'}`,

package/src/core/modules/hub/helpers/hub-mermaid.helper.spec.ts

@@ -1,6 +1,13 @@
 import { describe, expect, it } from 'vitest';
 
-import { buildErDiagram, type HubModelDescriptor } from './hub-mermaid.helper';
+// Value and type imports are deliberately split into two statements. The lt CLI's vendor
+// conversion drops an INLINE `type` specifier from a mixed import — `{ buildErDiagram, type
+// HubModelDescriptor }` arrives in a vendored project as `{ buildErDiagram }`, and the file then
+// fails to compile with TS2304. Keeping the two forms separate survives the conversion.
+// (The CLI defect is tracked separately; this keeps src/core/ vendor-safe meanwhile.)
+import type { HubModelDescriptor } from './hub-mermaid.helper';
+
+import { buildErDiagram } from './hub-mermaid.helper';
 
 describe('buildErDiagram', () => {
   const models: HubModelDescriptor[] = [

package/src/core/modules/migrate/migration-runner.ts

@@ -159,6 +159,23 @@ export class MigrationRunner {
    * compiled-production intent; the duplicate is skipped with a warning.
    */
   private async loadMigrationFiles(): Promise<MigrationFile[]> {
+    // A MISSING directory means the same thing as an EMPTY one: there are no migrations.
+    // Treat it that way instead of throwing ENOENT.
+    //
+    // This is a boot blocker otherwise: `pnpm start` is `migrate:up && start:local`, so the `&&`
+    // turns a readdirSync ENOENT into a server that will not start — with an error that does not
+    // point at the cause. And it is a state people produce routinely: "delete all migrations"
+    // reads to most as "throw the folder away".
+    //
+    // The runner already tolerates the RELATED case — a migration recorded in the database whose
+    // file is gone is non-fatal unless `NSC__MIGRATE__STRICT` is set. Only the wholly absent
+    // directory fell outside that tolerance. `down()` stays hard, consistent with its own
+    // reasoning. See DEV-2634.
+    if (!fs.existsSync(this.options.migrationsDirectory)) {
+      console.warn(`[migrate] migrations directory not found — treating as empty: ${this.options.migrationsDirectory}`);
+      return [];
+    }
+
     const files = fs
       .readdirSync(this.options.migrationsDirectory)
       .filter((file) => this.pattern.test(file))

package/src/index.ts

@@ -43,6 +43,7 @@ export * from './core/common/helpers/input.helper';
 export * from './core/common/helpers/logging.helper';
 export * from './core/common/helpers/meta.helper';
 export * from './core/common/helpers/model.helper';
+export * from './core/common/helpers/process-diagnostics.helper';
 export * from './core/common/helpers/register-enum.helper';
 export * from './core/common/helpers/scim.helper';
 export * from './core/common/helpers/service.helper';

package/src/main.ts

@@ -9,6 +9,7 @@ import envConfig from './config.env';
 import { FilterArgs } from './core/common/args/filter.args';
 import { buildCorsConfig, isCookiesEnabled, isCorsDisabled } from './core/common/helpers/cookies.helper';
 import { HttpExceptionLogFilter } from './core/common/filters/http-exception-log.filter';
+import { handleFatalBootstrapError, installProcessDiagnostics } from './core/common/helpers/process-diagnostics.helper';
 import { CorePersistenceModel } from './core/common/models/core-persistence.model';
 import { CoreAuthModel } from './core/modules/auth/core-auth.model';
 import { CoreUserModel } from './core/modules/user/core-user.model';
@@ -21,6 +22,11 @@ import { ServerModule } from './server/server.module';
  * Preparations for server start
  */
 async function bootstrap() {
+  // Make the exit reason diagnosable: log unhandled rejections without crashing, log uncaught
+  // exceptions before the restart, and label external termination signals so a silent
+  // "app crashed" always has a reason. See process-diagnostics.helper.ts for the rationale.
+  installProcessDiagnostics();
+
   // Create a new server based on express
   const server = await NestFactory.create<NestExpressApplication>(
     // Include server module, with all necessary modules for the project
@@ -106,9 +112,20 @@ async function bootstrap() {
     jsonDocumentUrl: '/api-docs-json',
   });
 
+  // Drain the event loop on SIGTERM/SIGINT so the process actually exits.
+  //
+  // This is load-bearing in a container, where `docker-entrypoint.sh` runs node under `exec` and it
+  // therefore becomes PID 1. A PID-namespace init is SIGNAL_UNKILLABLE: a userspace signal whose
+  // disposition is the default is silently discarded by the kernel, so re-raising is a no-op there.
+  // Meanwhile the listening HTTP server keeps the event loop non-empty, so nothing exits on its own
+  // and `docker stop` waits out its full grace period before SIGKILL — dropping in-flight requests
+  // and skipping every onModuleDestroy(). enableShutdownHooks() is what closes the app and drains
+  // the loop; installProcessDiagnostics() then correctly defers to it instead of re-raising.
+  server.enableShutdownHooks();
+
   // Start server on configured port
   await server.listen(envConfig.port, envConfig.hostname);
-  console.debug(`Server startet at ${await server.getUrl()}`);
+  console.debug(`Server started at ${await server.getUrl()}`);
 
   // Run command after server init
   if (envConfig.execAfterInit) {
@@ -126,5 +143,7 @@ async function bootstrap() {
   }
 }
 
-// Start server
-bootstrap();
+// Start server. A rejection here is a fatal startup failure (e.g. port already in use, DB
+// unreachable) — surface it and exit rather than let it become a silent unhandledRejection
+// that leaves a zombie process "alive" but listening on nothing.
+bootstrap().catch(handleFatalBootstrapError);