@tstdl/base 0.93.36 → 0.93.38

package/source/mail/README.md

@@ -1,225 +0,0 @@
-# @tstdl/mail
-
-A robust module for sending emails with powerful templating capabilities and pluggable mail clients.
-
-## Table of Contents
-
-- [Features](#features)
-- [Core Concepts](#core-concepts)
-- [Usage](#usage)
-  - [1. Configuration](#1-configuration)
-  - [2. Sending a Simple Email](#2-sending-a-simple-email)
-  - [3. Sending a Template-Based Email](#3-sending-a-template-based-email)
-  - [4. Using a Specific Client Configuration](#4-using-a-specific-client-configuration)
-- [API Summary](#api-summary)
-
-## Features
-
-- **Pluggable Mail Clients**: Abstracted `MailClient` allows for different sending backends. A `NodemailerMailClient` is provided out-of-the-box.
-- **Powerful Templating**: Integrates with `@tstdl/templates` to generate email subjects, HTML, and text bodies from templates and context data.
-- **Automatic Logging**: Every mail-sending attempt is logged to the database, including data, results, and errors, for auditing and debugging.
-- **Flexible Configuration**: Easily configure default clients, connection settings (host, port, auth), and default mail data (e.g., a global `from` address).
-- **Database Integration**: Includes schema and migration logic for mail logs.
-
-## Core Concepts
-
-### MailService
-
-The `MailService` is the central component of this module. It provides a high-level API for sending emails. It handles:
-- Rendering templates via the `@tstdl/templates` module.
-- Interacting with a `MailClient` to perform the actual sending.
-- Automatically logging every transaction to the `MailLog` database table.
-
-### MailClient
-
-`MailClient` is an abstract class that defines the contract for a mail-sending implementation. This allows you to swap out the underlying email provider without changing your application code. This module includes `NodemailerMailClient`, a ready-to-use implementation based on the popular Nodemailer library.
-
-### MailTemplate
-
-A `MailTemplate` is a specific type of template used to define the structure of an email. It allows you to specify templates for the `subject`, `html` body, and `text` body of an email. These are then rendered by the `MailService` using context data you provide.
-
-### Configuration and Migration
-
-Before using the module, it must be configured via the `configureMail` function in your application's bootstrap phase. This is where you specify the database connection, the `MailClient` implementation to use (e.g., `NodemailerMailClient`), and default settings. The `migrateMailSchema` function should also be called to set up the necessary `mail.log` table in your database.
-
-## Usage
-
-### 1. Configuration
-
-First, configure the mail module during your application's startup. This example sets up the `NodemailerMailClient` with SMTP settings and a default `from` address.
-
-```typescript
-// in your bootstrap.ts
-import { configureMail, NodemailerMailClient } from '@tstdl/mail';
-import { connect } from '@tstdl/base';
-
-// Bootstrap application...
-connect();
-
-configureMail({
-  // Use the main application database connection
-  database: { connection: 'default' },
-
-  // Specify the client implementation
-  client: NodemailerMailClient,
-
-  // Provide default connection settings for the client
-  defaultClientConfig: {
-    host: 'smtp.example.com',
-    port: 587,
-    auth: {
-      user: 'user@example.com',
-      password: 'your-password'
-    }
-  },
-
-  // Set default mail data, like a global "from" address
-  defaultData: {
-    from: { name: 'MyApp Support', address: 'support@myapp.com' }
-  }
-});
-
-// Run database migrations
-await migrateMailSchema();
-```
-
-### 2. Sending a Simple Email
-
-Inject `MailService` into your class and use the `send()` method.
-
-```typescript
-import { Singleton, inject } from '@tstdl/injector';
-import { MailService } from '@tstdl/mail';
-
-@Singleton()
-export class NotificationService {
-  readonly #mailService = inject(MailService);
-
-  async sendPasswordResetNotification(email: string, name: string): Promise<void> {
-    await this.#mailService.send({
-      to: { name, address: email },
-      subject: 'Your Password Reset Request',
-      content: {
-        text: 'You requested a password reset. Please follow the instructions...',
-        html: '<p>You requested a password reset. Please follow the instructions...</p>'
-      }
-    });
-  }
-}
-```
-
-### 3. Sending a Template-Based Email
-
-For more complex or reusable emails, define a `MailTemplate`.
-
-**a. Define the Template**
-
-```typescript
-// in user.mail-templates.ts
-import { mailTemplate } from '@tstdl/mail';
-import { jsxTemplateField, stringTemplateField } from '@tstdl/templates/resolvers';
-import type { User } from './user.model.js';
-
-type WelcomeMailContext = {
-  user: User;
-  loginUrl: string;
-};
-
-export const welcomeMailTemplate = mailTemplate<WelcomeMailContext>('user-welcome', {
-  subject: stringTemplateField({
-    renderer: 'string',
-    template: 'Welcome to our platform, {{ user.firstName }}!'
-  }),
-  html: jsxTemplateField({
-    renderer: 'mjml-jsx', // or 'jsx'
-    template: ({ user, loginUrl }) => (
-      <div>
-        <h1>Hi {user.firstName},</h1>
-        <p>Welcome! We are excited to have you on board.</p>
-        <a href={loginUrl}>Click here to log in</a>
-      </div>
-    )
-  }),
-  text: stringTemplateField({
-    renderer: 'string',
-    template: 'Hi {{ user.firstName }},\nWelcome! We are excited to have you on board.\nLog in here: {{ loginUrl }}'
-  })
-});
-```
-
-**b. Send the Templated Email**
-
-Use the `sendTemplate()` method to render and send the email.
-
-```typescript
-import { Singleton, inject } from '@tstdl/injector';
-import { MailService } from '@tstdl/mail';
-import { welcomeMailTemplate } from './user.mail-templates.js';
-import type { User } from './user.model.js';
-
-@Singleton()
-export class UserOnboardingService {
-  readonly #mailService = inject(MailService);
-
-  async sendWelcomeEmail(user: User): Promise<void> {
-    const context = {
-      user,
-      loginUrl: 'https://myapp.com/login'
-    };
-
-    await this.#mailService.sendTemplate(
-      welcomeMailTemplate,
-      { to: user.email },
-      context
-    );
-  }
-}
-```
-
-### 4. Using a Specific Client Configuration
-
-You can override the default client configuration for a single `send` or `sendTemplate` call by passing a `MailClientConfig` object.
-
-```typescript
-import { Singleton, inject } from '@tstdl/injector';
-import { MailService, type MailClientConfig } from '@tstdl/mail';
-
-@Singleton()
-export class TransactionalEmailService {
-  readonly #mailService = inject(MailService);
-
-  async sendHighPriorityEmail(email: string): Promise<void> {
-    // Use a different SMTP server for high-priority transactional emails
-    const highPriorityConfig: MailClientConfig = {
-      host: 'smtp.transactional.example.com',
-      port: 587,
-      auth: {
-        user: 'transactional-user',
-        password: 'transactional-password'
-      }
-    };
-
-    await this.#mailService.send(
-      {
-        to: email,
-        subject: 'Important Account Update',
-        content: { text: '...' }
-      },
-      highPriorityConfig
-    );
-  }
-}
-```
-
-## API Summary
-
-| Class/Function                 | Description                                                                                                                              |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `MailService`                  | The main service for sending emails.                                                                                                     |
-| `MailService.send()`           | `(data: MailData, config?: MailClientConfig) => Promise<MailSendResult>`<br>Sends an email using the provided data and optional config.     |
-| `MailService.sendTemplate()`   | `(template: MailTemplate, data: MailData, context: object, config?: MailClientConfig) => Promise<MailSendResult>`<br>Sends a templated email. |
-| `MailClient`                   | Abstract class for mail client implementations.                                                                                          |
-| `NodemailerMailClient`         | An implementation of `MailClient` using Nodemailer.                                                                                      |
-| `configureMail()`              | `(config: MailModuleConfig) => void`<br>Configures the mail module during application startup.                                            |
-| `migrateMailSchema()`          | `() => Promise<void>`<br>Runs database migrations for the mail module.                                                                    |
-| `mailTemplate()`               | `(name: string, fields: MailTemplateFields) => MailTemplate`<br>A helper function to create a type-safe `MailTemplate` definition.         |

package/source/mail/clients/index.ts

@@ -1 +0,0 @@
-export * from './nodemailer.mail-client.js';

package/source/mail/clients/nodemailer.mail-client.ts

@@ -1,90 +0,0 @@
-import type SMTPTransport = require('nodemailer/lib/smtp-transport'); // eslint-disable-line @typescript-eslint/no-require-imports
-import type { Transporter } from 'nodemailer';
-import { createTransport } from 'nodemailer';
-
-import { Singleton, inject, injectArgument } from '#/injector/index.js';
-import { Injector } from '#/injector/injector.js';
-import type { WritableOneOrMany } from '#/types/index.js';
-import { assertDefined, isUndefined } from '#/utils/type-guards.js';
-import { MailClient, MailClientConfig } from '../mail.client.js';
-import type { MailAddress, MailData, MailSendResult } from '../models/index.js';
-
-@Singleton()
-export class NodemailerMailClient extends MailClient implements Disposable {
-  readonly #stack = new DisposableStack();
-  readonly #transports = new Map<string, Transporter<SMTPTransport.SentMessageInfo>>();
-  readonly #defaultClientConfig = injectArgument(this, { optional: true }) ?? inject(MailClientConfig, undefined, { optional: true });
-
-  [Symbol.dispose](): void {
-    this.#stack.dispose();
-  }
-
-  async send(data: MailData, clientConfig?: MailClientConfig): Promise<MailSendResult> {
-    const config = clientConfig ?? this.#defaultClientConfig;
-    assertDefined(config, 'No mail client config provided.');
-
-    const transport = this.getTransport(config);
-
-    const result = await transport.sendMail({
-      from: data.from,
-      sender: data.sender,
-      to: data.to as WritableOneOrMany<MailAddress>,
-      cc: data.cc as WritableOneOrMany<MailAddress>,
-      bcc: data.bcc as WritableOneOrMany<MailAddress>,
-      replyTo: data.replyTo,
-      inReplyTo: data.inReplyTo,
-      references: data.references as WritableOneOrMany<string>,
-      subject: data.subject,
-      text: data.content.text,
-      html: data.content.html,
-      headers: data.headers,
-    });
-
-    return {
-      messageId: result.messageId,
-      accepted: result.accepted,
-      rejected: result.rejected,
-      pending: result.pending,
-    };
-  }
-
-  private getTransport(config: MailClientConfig): Transporter<SMTPTransport.SentMessageInfo> {
-    const options = convertConfig(config);
-    const optionsJson = JSON.stringify(options);
-
-    if (this.#transports.has(optionsJson)) {
-      return this.#transports.get(optionsJson)!;
-    }
-
-    const transport = createTransport(options);
-    this.#transports.set(optionsJson, transport);
-
-    this.#stack.adopt(transport, () => transport.close());
-
-    return transport;
-  }
-}
-
-function convertConfig(config: MailClientConfig): SMTPTransport.Options {
-  return {
-    host: config.host,
-    port: config.port,
-    secure: config.secure ?? (config.port == 465),
-    auth: isUndefined(config.auth)
-      ? undefined
-      : {
-        type: 'login',
-        user: config.auth.user,
-        pass: config.auth.password,
-      },
-  };
-}
-
-/**
- * @param register whether to register for {@link MailClient}
- */
-export function configureNodemailerMailClient(register: boolean = true): void {
-  if (register) {
-    Injector.registerSingleton(NodemailerMailClient, { useToken: MailClient });
-  }
-}

package/source/mail/drizzle/0000_previous_malcolm_colcord.sql

@@ -1,13 +0,0 @@
-CREATE TABLE "mail"."log" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"timestamp" timestamp with time zone NOT NULL,
-	"template" text,
-	"data" jsonb NOT NULL,
-	"send_result" jsonb,
-	"errors" text[],
-	"revision" integer NOT NULL,
-	"revision_timestamp" timestamp with time zone NOT NULL,
-	"create_timestamp" timestamp with time zone NOT NULL,
-	"delete_timestamp" timestamp with time zone,
-	"attributes" jsonb DEFAULT '{}'::jsonb NOT NULL
-);

package/source/mail/drizzle/0001_flimsy_bloodscream.sql

@@ -1,5 +0,0 @@
-ALTER TABLE "mail"."log" DROP COLUMN "revision";--> statement-breakpoint
-ALTER TABLE "mail"."log" DROP COLUMN "revision_timestamp";--> statement-breakpoint
-ALTER TABLE "mail"."log" DROP COLUMN "create_timestamp";--> statement-breakpoint
-ALTER TABLE "mail"."log" DROP COLUMN "delete_timestamp";--> statement-breakpoint
-ALTER TABLE "mail"."log" DROP COLUMN "attributes";

package/source/mail/drizzle/meta/0000_snapshot.json

@@ -1,100 +0,0 @@
-{
-  "id": "f8cdba37-11b9-477a-9f5a-5ef4b5026011",
-  "prevId": "00000000-0000-0000-0000-000000000000",
-  "version": "7",
-  "dialect": "postgresql",
-  "tables": {
-    "mail.log": {
-      "name": "log",
-      "schema": "mail",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "uuid",
-          "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
-        },
-        "timestamp": {
-          "name": "timestamp",
-          "type": "timestamp with time zone",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "template": {
-          "name": "template",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false
-        },
-        "data": {
-          "name": "data",
-          "type": "jsonb",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "send_result": {
-          "name": "send_result",
-          "type": "jsonb",
-          "primaryKey": false,
-          "notNull": false
-        },
-        "errors": {
-          "name": "errors",
-          "type": "text[]",
-          "primaryKey": false,
-          "notNull": false
-        },
-        "revision": {
-          "name": "revision",
-          "type": "integer",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "revision_timestamp": {
-          "name": "revision_timestamp",
-          "type": "timestamp with time zone",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "create_timestamp": {
-          "name": "create_timestamp",
-          "type": "timestamp with time zone",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "delete_timestamp": {
-          "name": "delete_timestamp",
-          "type": "timestamp with time zone",
-          "primaryKey": false,
-          "notNull": false
-        },
-        "attributes": {
-          "name": "attributes",
-          "type": "jsonb",
-          "primaryKey": false,
-          "notNull": true,
-          "default": "'{}'::jsonb"
-        }
-      },
-      "indexes": {},
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "policies": {},
-      "checkConstraints": {},
-      "isRLSEnabled": false
-    }
-  },
-  "enums": {},
-  "schemas": {},
-  "sequences": {},
-  "roles": {},
-  "policies": {},
-  "views": {},
-  "_meta": {
-    "columns": {},
-    "schemas": {},
-    "tables": {}
-  }
-}

package/source/mail/drizzle/meta/0001_snapshot.json

@@ -1,69 +0,0 @@
-{
-  "id": "28ddafef-64f4-437d-9406-82a02c76570e",
-  "prevId": "f8cdba37-11b9-477a-9f5a-5ef4b5026011",
-  "version": "7",
-  "dialect": "postgresql",
-  "tables": {
-    "mail.log": {
-      "name": "log",
-      "schema": "mail",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "uuid",
-          "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
-        },
-        "timestamp": {
-          "name": "timestamp",
-          "type": "timestamp with time zone",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "template": {
-          "name": "template",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false
-        },
-        "data": {
-          "name": "data",
-          "type": "jsonb",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "send_result": {
-          "name": "send_result",
-          "type": "jsonb",
-          "primaryKey": false,
-          "notNull": false
-        },
-        "errors": {
-          "name": "errors",
-          "type": "text[]",
-          "primaryKey": false,
-          "notNull": false
-        }
-      },
-      "indexes": {},
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "policies": {},
-      "checkConstraints": {},
-      "isRLSEnabled": false
-    }
-  },
-  "enums": {},
-  "schemas": {},
-  "sequences": {},
-  "roles": {},
-  "policies": {},
-  "views": {},
-  "_meta": {
-    "columns": {},
-    "schemas": {},
-    "tables": {}
-  }
-}

package/source/mail/drizzle/meta/_journal.json

@@ -1,20 +0,0 @@
-{
-  "version": "7",
-  "dialect": "postgresql",
-  "entries": [
-    {
-      "idx": 0,
-      "version": "7",
-      "when": 1740059198387,
-      "tag": "0000_previous_malcolm_colcord",
-      "breakpoints": true
-    },
-    {
-      "idx": 1,
-      "version": "7",
-      "when": 1761124592125,
-      "tag": "0001_flimsy_bloodscream",
-      "breakpoints": true
-    }
-  ]
-}

package/source/mail/drizzle.config.ts

@@ -1,13 +0,0 @@
-import { relative, resolve } from 'node:path';
-
-import { defineConfig } from 'drizzle-kit';
-
-export default defineConfig({
-  dialect: 'postgresql',
-  out: relative('./', resolve(__dirname, './drizzle/').replace('dist', 'source')),
-  schema: resolve(__dirname, './models/schemas.js'),
-  migrations: {
-    schema: 'mail',
-    table: '_migrations'
-  }
-});

package/source/mail/index.ts

@@ -1,12 +0,0 @@
-/**
- * Send mails with template support
- *
- * @module Mail
- */
-
-export * from './clients/index.js';
-export * from './mail.client.js';
-export * from './mail.service.js';
-export * from './models/index.js';
-export * from './module.js';
-export * from './tokens.js';

package/source/mail/mail.client.ts

@@ -1,33 +0,0 @@
-import { resolveArgumentType, type Resolvable } from '#/injector/index.js';
-import { BooleanProperty, NumberProperty, StringProperty } from '#/schema/index.js';
-import { Optional } from '#/schema/schemas/optional.js';
-import type { MailData, MailSendResult } from './models/index.js';
-
-export class MailClientAuthConfig {
-  @StringProperty()
-  user: string;
-
-  @StringProperty()
-  password: string;
-}
-
-export class MailClientConfig {
-  @StringProperty()
-  host: string;
-
-  @NumberProperty()
-  port: number;
-
-  /** Enable TLS (if not defined it is automatically set depending on port) */
-  @BooleanProperty({ optional: true })
-  secure?: boolean;
-
-  @Optional(MailClientAuthConfig)
-  auth?: MailClientAuthConfig;
-}
-
-export abstract class MailClient implements Resolvable<MailClientConfig> {
-  declare readonly [resolveArgumentType]: MailClientConfig;
-
-  abstract send(data: MailData, clientConfig?: MailClientConfig): Promise<MailSendResult>;
-}

package/source/mail/mail.service.ts

@@ -1,73 +0,0 @@
-import { Singleton, inject, provide } from '#/injector/index.js';
-import { Logger } from '#/logger/index.js';
-import { DatabaseConfig, EntityRepositoryConfig, injectRepository } from '#/orm/server/index.js';
-import { TemplateService } from '#/templates/template.service.js';
-import type { TypedOmit } from '#/types/index.js';
-import { currentTimestamp } from '#/utils/date-time.js';
-import { formatError } from '#/utils/format-error.js';
-import { assertDefined } from '#/utils/type-guards.js';
-import { MailClient, MailClientConfig } from './mail.client.js';
-import { MailLog, type MailData, type MailSendResult, type MailTemplate } from './models/index.js';
-import { MailModuleConfig } from './module.js';
-import { MAIL_DEFAULT_DATA } from './tokens.js';
-
-@Singleton({
-  providers: [
-    provide(EntityRepositoryConfig, { useValue: { schema: 'mail' } }),
-    provide(DatabaseConfig, { useFactory: (_, context) => context.resolve(MailModuleConfig).database ?? context.resolve(DatabaseConfig, undefined, { skipSelf: 2 }) }),
-  ],
-})
-export class MailService {
-  readonly #mailClient = inject(MailClient);
-  readonly #templateService = inject(TemplateService);
-  readonly #mailLogRepository = injectRepository(MailLog);
-  readonly #defaultClientConfig = inject(MailClientConfig, undefined, { optional: true });
-  readonly #defaultData = inject(MAIL_DEFAULT_DATA, undefined, { optional: true });
-  readonly #logger = inject(Logger, 'MailService');
-
-  async send(mailData: MailData, clientConfig?: MailClientConfig): Promise<MailSendResult>;
-  /** @deprecated internal */
-  async send(mailData: MailData, clientConfig?: MailClientConfig, templateName?: string): Promise<MailSendResult>;
-  async send(mailData: MailData, clientConfigOrTemplateName?: MailClientConfig, templateNameOrNothing?: string): Promise<MailSendResult> {
-    const clientConfig = (typeof clientConfigOrTemplateName == 'object') ? clientConfigOrTemplateName : this.#defaultClientConfig;
-    const templateName = (typeof clientConfigOrTemplateName == 'object') ? templateNameOrNothing : clientConfigOrTemplateName;
-    assertDefined(clientConfig, 'No mail client config provided.');
-
-    const data: MailData = { ...this.#defaultData, ...mailData };
-
-    let mailLog: MailLog | undefined;
-
-    mailLog = await this.#mailLogRepository.insert({
-      timestamp: currentTimestamp(),
-      template: templateName ?? null,
-      data,
-      sendResult: null,
-      errors: null,
-    });
-
-    try {
-      const result = await this.#mailClient.send(data, clientConfig);
-      await this.#mailLogRepository.update(mailLog.id, { sendResult: result });
-
-      return result;
-    }
-    catch (error) {
-      try {
-        await this.#mailLogRepository.update(mailLog.id, { errors: [formatError(error)] });
-      }
-      catch (logError) {
-        this.#logger.error(logError as Error);
-      }
-
-      throw error;
-    }
-  }
-
-  async sendTemplate<Context extends object>(keyOrTemplate: string | MailTemplate<Context>, mailData: TypedOmit<MailData, 'content' | 'subject'>, templateContext?: Context, clientConfig?: MailClientConfig): Promise<MailSendResult> {
-    const { name, fields: { subject, html, text } } = await this.#templateService.render(keyOrTemplate, templateContext);
-
-    const fullMailData = { ...mailData, subject, content: { html, text } };
-
-    return await this.send(fullMailData, clientConfig, name);
-  }
-}

package/source/mail/models/index.ts

@@ -1,7 +0,0 @@
-export * from './mail-address.model.js';
-export * from './mail-content.model.js';
-export * from './mail-data.model.js';
-export * from './mail-log.model.js';
-export * from './mail-send-result.model.js';
-export * from './mail-template.model.js';
-export * from './schemas.js';

package/source/mail/models/mail-address.model.ts

@@ -1 +0,0 @@
-export type MailAddress = string | { name: string, address: string };

package/source/mail/models/mail-content.model.ts

@@ -1,4 +0,0 @@
-export type MailContent = {
-  text?: string,
-  html?: string
-};