@uniora/mailer-smtp 0.3.0

package/LICENSE

@@ -0,0 +1,91 @@
+Required Notice: Copyright 2026 CodexSploitx (https://github.com/CodexSploitx/uniora)
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,41 @@
+# @uniora/mailer-smtp
+
+SMTP delivery for [UNIORA](https://github.com/CodexSploitx/uniora) invitations. It implements `InvitationSender` from `@uniora/core`, reads its settings from `UNIORA_SMTP_*` environment variables and ships professional, responsive, dark-mode-aware templates in English, Spanish, Portuguese, French, German and Italian.
+
+```ts
+import { createInvitationService } from "@uniora/core";
+import { createSmtpInvitationSenderFromEnv } from "@uniora/mailer-smtp";
+
+const sender = createSmtpInvitationSenderFromEnv(process.env, {
+  brandName: "Acme",
+  brandColor: "#0f766e",
+  logoUrl: "https://acme.com/logo.png",
+  supportEmail: "help@acme.com",
+  resolveInviterName: async (identity) => (await db.users.find(identity.subject))?.name,
+});
+await sender.verify(); // optional startup check: connects and authenticates
+
+const invitations = createInvitationService({ storage, sender, acceptUrl: (t) => `https://app.acme.com/invite/${t}` });
+```
+
+## Configuration
+
+| Variable | Default | |
+| --- | --- | --- |
+| `UNIORA_SMTP_HOST` | — | **required**, bare host name |
+| `UNIORA_SMTP_PORT` | `587` | `465` uses implicit TLS, otherwise STARTTLS |
+| `UNIORA_SMTP_SECURE` | `true` only on 465 | force implicit TLS |
+| `UNIORA_SMTP_USER` / `UNIORA_SMTP_PASS` | — | both or neither |
+| `UNIORA_SMTP_FROM` | — | **required**, `Name <addr>` or `addr` |
+| `UNIORA_SMTP_REPLY_TO` | — | optional |
+| `UNIORA_SMTP_REQUIRE_TLS` | `true` | refuse to send unencrypted |
+| `UNIORA_SMTP_TLS_REJECT_UNAUTHORIZED` | `true` | verify the server certificate |
+
+Anything missing or malformed throws one `SmtpConfigError` listing every problem — at startup, not on the first invitation.
+
+## Behaviour
+
+- **Retries, timeouts and bookkeeping** are done by `createInvitationService`; this package classifies failures: bad credentials and any `5xx`/rejected recipient are permanent (no retry), network errors and `4xx` are transient.
+- **Templates are safe by construction**: every interpolated value is escaped, the Subject is forced onto one line, the link must be `http(s)`, the logo `https`, the brand color a `#rrggbb`.
+- **Own template?** Pass `template: (message, context) => ({ subject, html, text })`. **Own provider?** Implement `InvitationSender` yourself — nothing else in UNIORA changes.
+- Each message carries `Auto-Submitted: auto-generated` and an `X-Entity-Ref-ID` (invitation id + attempt) for correlating provider logs. The token never appears in headers or logs.

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * SMTP settings, read from the environment. UNIORA never ships credentials and
+ * never guesses: the mailer refuses to start until the minimum is present, and
+ * says everything that is wrong in one error.
+ *
+ *   UNIORA_SMTP_HOST      required   e.g. smtp.postmarkapp.com
+ *   UNIORA_SMTP_PORT      587        465 = implicit TLS, 587/25 = STARTTLS
+ *   UNIORA_SMTP_SECURE    auto       "true" for implicit TLS (default: true only on 465)
+ *   UNIORA_SMTP_USER      optional   with PASS; both or neither
+ *   UNIORA_SMTP_PASS      optional
+ *   UNIORA_SMTP_FROM      required   "Acme <no-reply@acme.com>" or a bare address
+ *   UNIORA_SMTP_REPLY_TO  optional
+ *   UNIORA_SMTP_REQUIRE_TLS        true   refuse to send over a plain-text connection
+ *   UNIORA_SMTP_TLS_REJECT_UNAUTHORIZED  true   verify the server certificate
+ */
+export interface SmtpConfig {
+    host: string;
+    port: number;
+    /** Implicit TLS (SMTPS). When false the connection is upgraded with STARTTLS. */
+    secure: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+    from: string;
+    replyTo?: string;
+    /** Fail instead of falling back to an unencrypted session. Ignored when `secure`. */
+    requireTLS: boolean;
+    rejectUnauthorized: boolean;
+}
+export declare class SmtpConfigError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+type Env = Readonly<Record<string, string | undefined>>;
+/** A header-safe address: no line breaks (header injection), one mailbox. */
+export declare function isSafeMailbox(value: string): boolean;
+export declare function loadSmtpConfig(env?: Env): SmtpConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,65 @@
+export class SmtpConfigError extends Error {
+    problems;
+    constructor(problems) {
+        super(`Invalid SMTP configuration:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
+        this.problems = problems;
+        this.name = "SmtpConfigError";
+    }
+}
+function bool(value, fallback, name, problems) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes"].includes(normalized))
+        return true;
+    if (["false", "0", "no"].includes(normalized))
+        return false;
+    problems.push(`${name} must be "true" or "false" (got "${value}").`);
+    return fallback;
+}
+/** A header-safe address: no line breaks (header injection), one mailbox. */
+export function isSafeMailbox(value) {
+    return !/[\r\n\u0000]/.test(value) && /^(?:[^<>@]*<)?[^\s<>@,;]+@[^\s<>@,;]+\.[^\s<>@,;]+>?$/.test(value.trim());
+}
+export function loadSmtpConfig(env = process.env) {
+    const problems = [];
+    const get = (key) => env[key]?.trim() || undefined;
+    const host = get("UNIORA_SMTP_HOST");
+    if (!host)
+        problems.push("UNIORA_SMTP_HOST is required.");
+    else if (/[\s/]/.test(host))
+        problems.push("UNIORA_SMTP_HOST must be a bare host name (no scheme, path or spaces).");
+    const portText = get("UNIORA_SMTP_PORT");
+    const port = portText === undefined ? 587 : Number(portText);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        problems.push(`UNIORA_SMTP_PORT must be an integer between 1 and 65535 (got "${portText}").`);
+    }
+    const secure = bool(env.UNIORA_SMTP_SECURE, port === 465, "UNIORA_SMTP_SECURE", problems);
+    const requireTLS = bool(env.UNIORA_SMTP_REQUIRE_TLS, true, "UNIORA_SMTP_REQUIRE_TLS", problems);
+    const rejectUnauthorized = bool(env.UNIORA_SMTP_TLS_REJECT_UNAUTHORIZED, true, "UNIORA_SMTP_TLS_REJECT_UNAUTHORIZED", problems);
+    const user = get("UNIORA_SMTP_USER");
+    const pass = env.UNIORA_SMTP_PASS === undefined || env.UNIORA_SMTP_PASS === "" ? undefined : env.UNIORA_SMTP_PASS;
+    if ((user === undefined) !== (pass === undefined)) {
+        problems.push("UNIORA_SMTP_USER and UNIORA_SMTP_PASS must be set together (or both left empty).");
+    }
+    const from = get("UNIORA_SMTP_FROM");
+    if (!from)
+        problems.push("UNIORA_SMTP_FROM is required (e.g. \"Acme <no-reply@acme.com>\").");
+    else if (!isSafeMailbox(from))
+        problems.push("UNIORA_SMTP_FROM must be a single valid address, optionally with a display name.");
+    const replyTo = get("UNIORA_SMTP_REPLY_TO");
+    if (replyTo && !isSafeMailbox(replyTo))
+        problems.push("UNIORA_SMTP_REPLY_TO must be a single valid address.");
+    if (problems.length > 0)
+        throw new SmtpConfigError(problems);
+    return {
+        host: host,
+        port,
+        secure,
+        auth: user !== undefined && pass !== undefined ? { user, pass } : undefined,
+        from: from,
+        replyTo,
+        requireTLS,
+        rejectUnauthorized,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { SmtpConfig } from "./config.js";
+export { isSafeMailbox, loadSmtpConfig, SmtpConfigError } from "./config.js";
+export type { EmailLocale, InvitationStrings } from "./locales.js";
+export { DEFAULT_LOCALE, resolveLocale, STRINGS } from "./locales.js";
+export type { InvitationTemplate, InvitationTemplateContext, InvitationTemplateOptions, RenderedEmail, } from "./templates.js";
+export { escapeHtml, renderInvitationEmail } from "./templates.js";
+export type { MailTransport, SmtpInvitationSender, SmtpInvitationSenderOptions } from "./sender.js";
+export { createSmtpInvitationSender, createSmtpInvitationSenderFromEnv, isPermanentSmtpFailure } from "./sender.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { isSafeMailbox, loadSmtpConfig, SmtpConfigError } from "./config.js";
+export { DEFAULT_LOCALE, resolveLocale, STRINGS } from "./locales.js";
+export { escapeHtml, renderInvitationEmail } from "./templates.js";
+export { createSmtpInvitationSender, createSmtpInvitationSenderFromEnv, isPermanentSmtpFailure } from "./sender.js";

package/dist/locales.d.ts

@@ -0,0 +1,22 @@
+export type EmailLocale = "en" | "es" | "pt" | "fr" | "de" | "it";
+export interface InvitationStrings {
+    /** `{org}` is replaced (and escaped by the renderer). */
+    subject: string;
+    preheader: string;
+    heading: string;
+    /** With a known inviter: `{inviter}` and `{org}`. */
+    introWithInviter: string;
+    intro: string;
+    roleOne: string;
+    roleMany: string;
+    button: string;
+    expires: string;
+    fallback: string;
+    ignore: string;
+    sentBy: string;
+    help: string;
+}
+export declare const DEFAULT_LOCALE: EmailLocale;
+export declare const STRINGS: Record<EmailLocale, InvitationStrings>;
+/** `es-MX` → `es`, `PT_br` → `pt`; anything unsupported falls back to the default. */
+export declare function resolveLocale(requested: string | undefined, fallback?: EmailLocale): EmailLocale;

package/dist/locales.js

@@ -0,0 +1,98 @@
+export const DEFAULT_LOCALE = "en";
+export const STRINGS = {
+    en: {
+        subject: "You're invited to join {org}",
+        preheader: "Accept your invitation to join {org}.",
+        heading: "You're invited to join {org}",
+        introWithInviter: "{inviter} has invited you to join {org}.",
+        intro: "You have been invited to join {org}.",
+        roleOne: "Your role",
+        roleMany: "Your roles",
+        button: "Accept invitation",
+        expires: "This invitation expires on {date}.",
+        fallback: "If the button doesn't work, copy and paste this link into your browser:",
+        ignore: "Weren't expecting this? You can safely ignore this e-mail — nothing happens until you accept.",
+        sentBy: "Sent by {brand}",
+        help: "Questions? Contact {support}.",
+    },
+    es: {
+        subject: "Te invitaron a unirte a {org}",
+        preheader: "Acepta tu invitación para unirte a {org}.",
+        heading: "Te invitaron a unirte a {org}",
+        introWithInviter: "{inviter} te ha invitado a unirte a {org}.",
+        intro: "Has sido invitado/a a unirte a {org}.",
+        roleOne: "Tu rol",
+        roleMany: "Tus roles",
+        button: "Aceptar invitación",
+        expires: "Esta invitación vence el {date}.",
+        fallback: "Si el botón no funciona, copia y pega este enlace en tu navegador:",
+        ignore: "¿No esperabas esto? Puedes ignorar este correo sin problema: no pasa nada hasta que aceptes.",
+        sentBy: "Enviado por {brand}",
+        help: "¿Dudas? Escribe a {support}.",
+    },
+    pt: {
+        subject: "Você foi convidado(a) para entrar em {org}",
+        preheader: "Aceite o convite para entrar em {org}.",
+        heading: "Você foi convidado(a) para entrar em {org}",
+        introWithInviter: "{inviter} convidou você para entrar em {org}.",
+        intro: "Você foi convidado(a) para entrar em {org}.",
+        roleOne: "Seu papel",
+        roleMany: "Seus papéis",
+        button: "Aceitar convite",
+        expires: "Este convite expira em {date}.",
+        fallback: "Se o botão não funcionar, copie e cole este link no navegador:",
+        ignore: "Não esperava por isso? Pode ignorar este e-mail com segurança: nada acontece até você aceitar.",
+        sentBy: "Enviado por {brand}",
+        help: "Dúvidas? Fale com {support}.",
+    },
+    fr: {
+        subject: "Vous êtes invité(e) à rejoindre {org}",
+        preheader: "Acceptez votre invitation à rejoindre {org}.",
+        heading: "Vous êtes invité(e) à rejoindre {org}",
+        introWithInviter: "{inviter} vous invite à rejoindre {org}.",
+        intro: "Vous avez été invité(e) à rejoindre {org}.",
+        roleOne: "Votre rôle",
+        roleMany: "Vos rôles",
+        button: "Accepter l'invitation",
+        expires: "Cette invitation expire le {date}.",
+        fallback: "Si le bouton ne fonctionne pas, copiez ce lien dans votre navigateur :",
+        ignore: "Vous n'attendiez rien ? Ignorez simplement cet e-mail : rien ne se passe tant que vous n'acceptez pas.",
+        sentBy: "Envoyé par {brand}",
+        help: "Une question ? Contactez {support}.",
+    },
+    de: {
+        subject: "Einladung zu {org}",
+        preheader: "Nehmen Sie die Einladung zu {org} an.",
+        heading: "Sie wurden zu {org} eingeladen",
+        introWithInviter: "{inviter} hat Sie zu {org} eingeladen.",
+        intro: "Sie wurden zu {org} eingeladen.",
+        roleOne: "Ihre Rolle",
+        roleMany: "Ihre Rollen",
+        button: "Einladung annehmen",
+        expires: "Diese Einladung läuft am {date} ab.",
+        fallback: "Falls die Schaltfläche nicht funktioniert, kopieren Sie diesen Link in Ihren Browser:",
+        ignore: "Nicht erwartet? Sie können diese E-Mail ignorieren – ohne Ihre Zusage passiert nichts.",
+        sentBy: "Gesendet von {brand}",
+        help: "Fragen? Schreiben Sie an {support}.",
+    },
+    it: {
+        subject: "Sei stato/a invitato/a a unirti a {org}",
+        preheader: "Accetta l'invito a unirti a {org}.",
+        heading: "Sei stato/a invitato/a a unirti a {org}",
+        introWithInviter: "{inviter} ti ha invitato/a a unirti a {org}.",
+        intro: "Sei stato/a invitato/a a unirti a {org}.",
+        roleOne: "Il tuo ruolo",
+        roleMany: "I tuoi ruoli",
+        button: "Accetta l'invito",
+        expires: "Questo invito scade il {date}.",
+        fallback: "Se il pulsante non funziona, copia e incolla questo link nel browser:",
+        ignore: "Non te lo aspettavi? Puoi ignorare questa e-mail: non succede nulla finché non accetti.",
+        sentBy: "Inviato da {brand}",
+        help: "Domande? Scrivi a {support}.",
+    },
+};
+/** `es-MX` → `es`, `PT_br` → `pt`; anything unsupported falls back to the default. */
+export function resolveLocale(requested, fallback = DEFAULT_LOCALE) {
+    const language = requested?.trim().toLowerCase().split(/[-_]/)[0];
+    return language && language in STRINGS ? language : fallback;
+}

package/dist/sender.d.ts

@@ -0,0 +1,50 @@
+import { type Identity, type InvitationSender } from "@uniora/core";
+import { type SmtpConfig } from "./config.js";
+import { type InvitationTemplate, type InvitationTemplateOptions } from "./templates.js";
+/** The slice of a nodemailer transport the sender uses — lets tests (and other transports) plug in. */
+export interface MailTransport {
+    sendMail(mail: {
+        from: string;
+        to: string;
+        replyTo?: string;
+        subject: string;
+        html: string;
+        text: string;
+        headers?: Record<string, string>;
+    }): Promise<unknown>;
+    verify?(): Promise<unknown>;
+    close?(): void;
+}
+export interface SmtpInvitationSenderOptions extends InvitationTemplateOptions {
+    /** Defaults to `loadSmtpConfig(process.env)` — i.e. the `UNIORA_SMTP_*` variables. */
+    config?: SmtpConfig;
+    /** Bring your own transport (tests, a different nodemailer setup). When set, `config` is only used for From/Reply-To. */
+    transport?: MailTransport;
+    /** Full control of subject, HTML and text. Defaults to `renderInvitationEmail`. */
+    template?: InvitationTemplate;
+    /** Turns the inviter's identity into a display name for the e-mail, e.g. a lookup in your user table. */
+    resolveInviterName?: (identity: Identity) => Promise<string | undefined> | string | undefined;
+    /** Connection pooling for the built-in transport. Default `true`. */
+    pool?: boolean;
+}
+export interface SmtpInvitationSender extends InvitationSender {
+    /** Opens a connection and authenticates, without sending anything. Use at startup or in a health check. */
+    verify(): Promise<void>;
+    /** Closes pooled connections. */
+    close(): void;
+}
+/**
+ * Failures a retry can't fix: bad credentials, a rejected sender/recipient or
+ * any 5xx reply. Network trouble, timeouts and 4xx (greylisting, throttling,
+ * mailbox busy) are transient and worth another attempt.
+ */
+export declare function isPermanentSmtpFailure(error: unknown): boolean;
+/**
+ * The SMTP implementation of `InvitationSender`. Plug it into
+ * `createInvitationService({ sender })`; retries, timeouts and delivery
+ * bookkeeping are the service's job, so this only has to render, send and
+ * classify failures correctly.
+ */
+export declare function createSmtpInvitationSender(options?: SmtpInvitationSenderOptions): SmtpInvitationSender;
+/** `createSmtpInvitationSender` configured entirely from `UNIORA_SMTP_*`; throws `SmtpConfigError` listing everything missing. */
+export declare function createSmtpInvitationSenderFromEnv(env?: Readonly<Record<string, string | undefined>>, options?: Omit<SmtpInvitationSenderOptions, "config">): SmtpInvitationSender;

package/dist/sender.js

@@ -0,0 +1,111 @@
+import { createTransport } from "nodemailer";
+import { InvitationDeliveryError } from "@uniora/core";
+import { loadSmtpConfig } from "./config.js";
+import { renderInvitationEmail, } from "./templates.js";
+/**
+ * Failures a retry can't fix: bad credentials, a rejected sender/recipient or
+ * any 5xx reply. Network trouble, timeouts and 4xx (greylisting, throttling,
+ * mailbox busy) are transient and worth another attempt.
+ */
+export function isPermanentSmtpFailure(error) {
+    const { code, responseCode } = (error ?? {});
+    if (code === "EAUTH")
+        return true;
+    if (typeof responseCode === "number")
+        return responseCode >= 500 && responseCode < 600;
+    return code === "EENVELOPE" || code === "EMESSAGE";
+}
+function toDeliveryError(error) {
+    const { code, responseCode, message } = (error ?? {});
+    const detail = [typeof code === "string" ? code : undefined, typeof responseCode === "number" ? String(responseCode) : undefined]
+        .filter(Boolean)
+        .join(" ");
+    const text = `SMTP delivery failed${detail ? ` (${detail})` : ""}: ${typeof message === "string" ? message : String(error)}`;
+    return new InvitationDeliveryError(text, isPermanentSmtpFailure(error), { cause: error });
+}
+function buildTransport(config, pool) {
+    const smtp = {
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+        requireTLS: !config.secure && config.requireTLS,
+        auth: config.auth,
+        tls: { rejectUnauthorized: config.rejectUnauthorized, minVersion: "TLSv1.2" },
+        // Below the delivery engine's per-attempt budget, so a dead server fails
+        // here with a real error instead of by an abandoned promise.
+        connectionTimeout: 10_000,
+        greetingTimeout: 10_000,
+        socketTimeout: 20_000,
+    };
+    const transporter = pool
+        ? createTransport({ ...smtp, pool: true, maxConnections: 3 })
+        : createTransport(smtp);
+    return transporter;
+}
+/**
+ * The SMTP implementation of `InvitationSender`. Plug it into
+ * `createInvitationService({ sender })`; retries, timeouts and delivery
+ * bookkeeping are the service's job, so this only has to render, send and
+ * classify failures correctly.
+ */
+export function createSmtpInvitationSender(options = {}) {
+    const config = options.config ?? loadSmtpConfig();
+    const template = options.template ?? renderInvitationEmail;
+    const transport = options.transport ?? buildTransport(config, options.pool ?? true);
+    return {
+        async send(message, context) {
+            let inviterName;
+            try {
+                inviterName = await options.resolveInviterName?.(message.invitedBy);
+            }
+            catch {
+                inviterName = undefined; // a failed name lookup must never block the invitation
+            }
+            const rendered = await template(message, {
+                brandName: options.brandName,
+                brandColor: options.brandColor,
+                logoUrl: options.logoUrl,
+                supportEmail: options.supportEmail,
+                defaultLocale: options.defaultLocale,
+                inviterName,
+            });
+            try {
+                await transport.sendMail({
+                    from: config.from,
+                    to: message.to,
+                    replyTo: config.replyTo,
+                    subject: rendered.subject,
+                    html: rendered.html,
+                    text: rendered.text,
+                    headers: {
+                        // Machine-generated transactional mail: keeps auto-responders quiet.
+                        "Auto-Submitted": "auto-generated",
+                        "X-Auto-Response-Suppress": "All",
+                        // Correlates provider logs with the invitation without exposing the token.
+                        "X-Entity-Ref-ID": `${message.invitationId}.${context.attempt}`,
+                    },
+                });
+            }
+            catch (error) {
+                throw toDeliveryError(error);
+            }
+        },
+        async verify() {
+            if (!transport.verify)
+                return;
+            try {
+                await transport.verify();
+            }
+            catch (error) {
+                throw toDeliveryError(error);
+            }
+        },
+        close() {
+            transport.close?.();
+        },
+    };
+}
+/** `createSmtpInvitationSender` configured entirely from `UNIORA_SMTP_*`; throws `SmtpConfigError` listing everything missing. */
+export function createSmtpInvitationSenderFromEnv(env = process.env, options = {}) {
+    return createSmtpInvitationSender({ ...options, config: loadSmtpConfig(env) });
+}

package/dist/templates.d.ts

@@ -0,0 +1,36 @@
+import type { InvitationMessage } from "@uniora/core";
+import { type EmailLocale } from "./locales.js";
+export interface RenderedEmail {
+    subject: string;
+    html: string;
+    text: string;
+}
+export interface InvitationTemplateOptions {
+    /** Shown in the header and footer. Default: the organization's name is used as the header and "UNIORA" in the footer. */
+    brandName?: string;
+    /** `#rrggbb` accent for the button and header rule. Default indigo. */
+    brandColor?: string;
+    /** Absolute https URL of a logo (max ~180×48 px works best). Omitted → text header. */
+    logoUrl?: string;
+    /** Shown in the footer help line. */
+    supportEmail?: string;
+    /** Used when `message.locale` is missing or unsupported. Default `en`. */
+    defaultLocale?: EmailLocale;
+}
+export interface InvitationTemplateContext extends InvitationTemplateOptions {
+    /** Display name of the person who invited, when you can resolve one. */
+    inviterName?: string;
+}
+/** Replace this to take full control of the e-mail (any markup, any copy). */
+export type InvitationTemplate = (message: InvitationMessage, context: InvitationTemplateContext) => RenderedEmail | Promise<RenderedEmail>;
+export declare function escapeHtml(value: string): string;
+/** One line, bounded: names go into the Subject header and must never carry line breaks. */
+export declare function singleLine(value: string, max?: number): string;
+/**
+ * The default invitation e-mail: a responsive, table-based layout that holds up
+ * in Outlook, Gmail and Apple Mail (inline styles, a bulletproof button with a
+ * VML fallback, a hidden preheader, dark-mode support) plus a plain-text
+ * alternative. Everything interpolated is escaped, the link must be http(s)
+ * and the Subject is forced onto one line.
+ */
+export declare function renderInvitationEmail(message: InvitationMessage, context?: InvitationTemplateContext): RenderedEmail;

package/dist/templates.js

@@ -0,0 +1,164 @@
+import { DEFAULT_LOCALE, resolveLocale, STRINGS } from "./locales.js";
+const DEFAULT_COLOR = "#4f46e5";
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+/** One line, bounded: names go into the Subject header and must never carry line breaks. */
+export function singleLine(value, max = 80) {
+    const flat = value.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, " ").replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+function fill(template, values) {
+    return template.replace(/\{(\w+)\}/g, (match, key) => values[key] ?? match);
+}
+function safeColor(color) {
+    return color && /^#[0-9a-f]{6}$/i.test(color) ? color.toLowerCase() : DEFAULT_COLOR;
+}
+/** Black or white, whichever reads better on `hex` (WCAG relative luminance). */
+function readableOn(hex) {
+    const [r, g, b] = [1, 3, 5].map((index) => {
+        const channel = parseInt(hex.slice(index, index + 2), 16) / 255;
+        return channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+    });
+    const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    return luminance > 0.4 ? "#111827" : "#ffffff";
+}
+function assertHttpUrl(value, what, httpsOnly = false) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError(`${what} must be an absolute URL.`);
+    }
+    const allowed = httpsOnly ? ["https:"] : ["https:", "http:"];
+    if (!allowed.includes(url.protocol))
+        throw new TypeError(`${what} must use ${httpsOnly ? "https" : "http(s)"}.`);
+    return url.toString();
+}
+function formatDate(date, locale) {
+    try {
+        return `${new Intl.DateTimeFormat(locale, { dateStyle: "long", timeStyle: "short", timeZone: "UTC" }).format(date)} UTC`;
+    }
+    catch {
+        return date.toISOString();
+    }
+}
+/**
+ * The default invitation e-mail: a responsive, table-based layout that holds up
+ * in Outlook, Gmail and Apple Mail (inline styles, a bulletproof button with a
+ * VML fallback, a hidden preheader, dark-mode support) plus a plain-text
+ * alternative. Everything interpolated is escaped, the link must be http(s)
+ * and the Subject is forced onto one line.
+ */
+export function renderInvitationEmail(message, context = {}) {
+    const locale = resolveLocale(message.locale, context.defaultLocale ?? DEFAULT_LOCALE);
+    const t = STRINGS[locale];
+    const acceptUrl = assertHttpUrl(message.acceptUrl, "acceptUrl");
+    const logoUrl = context.logoUrl ? assertHttpUrl(context.logoUrl, "logoUrl", true) : undefined;
+    const color = safeColor(context.brandColor);
+    const onColor = readableOn(color);
+    const org = singleLine(message.organization.name, 120);
+    const brand = singleLine(context.brandName ?? "UNIORA", 60);
+    const inviter = context.inviterName ? singleLine(context.inviterName, 80) : undefined;
+    const roles = message.roleNames.map((role) => singleLine(role, 60)).filter(Boolean);
+    const when = formatDate(message.expiresAt, locale);
+    const support = context.supportEmail ? singleLine(context.supportEmail, 120) : undefined;
+    const subject = singleLine(fill(t.subject, { org }), 150);
+    const introText = inviter ? fill(t.introWithInviter, { inviter, org }) : fill(t.intro, { org });
+    const roleLabel = roles.length > 1 ? t.roleMany : t.roleOne;
+    const heading = fill(t.heading, { org });
+    const preheader = fill(t.preheader, { org });
+    const expires = fill(t.expires, { date: when });
+    const sentBy = fill(t.sentBy, { brand });
+    const help = support ? fill(t.help, { support }) : undefined;
+    // Each interpolated value is escaped on its own and then emphasised, so a
+    // hostile name can't break out of the markup (and `$` in a name is inert).
+    const e = escapeHtml;
+    const introHtml = (inviter ? t.introWithInviter : t.intro)
+        .split(/(\{org\}|\{inviter\})/)
+        .map((part) => part === "{org}" ? `<strong>${e(org)}</strong>` : part === "{inviter}" ? `<strong>${e(inviter ?? "")}</strong>` : e(part))
+        .join("");
+    const url = e(acceptUrl);
+    const header = logoUrl
+        ? `<img src="${e(logoUrl)}" alt="${e(brand)}" height="32" style="display:block;border:0;height:32px;width:auto;max-width:180px;">`
+        : `<span style="font-size:18px;font-weight:700;letter-spacing:.2px;color:#111827;" class="ink">${e(brand)}</span>`;
+    const roleBlock = roles.length
+        ? `<tr><td style="padding:0 40px 24px 40px;">
+        <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%" class="panel" style="background:#f3f4f6;border-radius:10px;">
+          <tr><td style="padding:14px 18px;font-size:13px;line-height:20px;color:#6b7280;" class="muted">${e(roleLabel)}</td></tr>
+          <tr><td style="padding:0 18px 14px 18px;font-size:15px;line-height:22px;font-weight:600;color:#111827;" class="ink">${roles.map(e).join(" · ")}</td></tr>
+        </table>
+      </td></tr>`
+        : "";
+    const html = `<!doctype html>
+<html lang="${locale}" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<meta name="supported-color-schemes" content="light dark">
+<title>${e(subject)}</title>
+<!--[if mso]><noscript><xml><o:OfficeDocumentSettings><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml></noscript><![endif]-->
+<style>
+  body,table,td,a{-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;}
+  table,td{mso-table-lspace:0;mso-table-rspace:0;}
+  img{-ms-interpolation-mode:bicubic;}
+  @media (max-width:620px){ .container{width:100%!important;} .px{padding-left:24px!important;padding-right:24px!important;} }
+  @media (prefers-color-scheme:dark){
+    .bg{background:#0b0f19!important;} .card{background:#111827!important;border-color:#1f2937!important;}
+    .ink{color:#f9fafb!important;} .body{color:#d1d5db!important;} .muted{color:#9ca3af!important;}
+    .panel{background:#1f2937!important;} .rule{border-top-color:#1f2937!important;} .link{color:#a5b4fc!important;}
+  }
+</style>
+</head>
+<body class="bg" style="margin:0;padding:0;background:#f4f5f7;">
+<div style="display:none;max-height:0;overflow:hidden;opacity:0;color:transparent;mso-hide:all;">${e(preheader)}&#847;&zwnj;&nbsp;&#847;&zwnj;&nbsp;&#847;&zwnj;&nbsp;</div>
+<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%" class="bg" style="background:#f4f5f7;">
+<tr><td align="center" style="padding:32px 16px;">
+  <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="560" class="container card" style="width:560px;max-width:560px;background:#ffffff;border:1px solid #e5e7eb;border-radius:14px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;">
+    <tr><td class="px" style="padding:28px 40px 20px 40px;border-bottom:3px solid ${color};border-radius:14px 14px 0 0;">${header}</td></tr>
+    <tr><td class="px ink" style="padding:32px 40px 8px 40px;font-size:24px;line-height:32px;font-weight:700;color:#111827;">${e(heading)}</td></tr>
+    <tr><td class="px body" style="padding:8px 40px 24px 40px;font-size:16px;line-height:26px;color:#374151;">${introHtml}</td></tr>
+    ${roleBlock}
+    <tr><td class="px" align="left" style="padding:0 40px 24px 40px;">
+      <!--[if mso]><v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" href="${url}" style="height:48px;v-text-anchor:middle;width:240px;" arcsize="20%" stroke="f" fillcolor="${color}"><w:anchorlock xmlns:w="urn:schemas-microsoft-com:office:word"/><center style="color:${onColor};font-family:Arial,sans-serif;font-size:16px;font-weight:bold;">${e(t.button)}</center></v:roundrect><![endif]-->
+      <!--[if !mso]><!-- --><a href="${url}" target="_blank" rel="noopener" style="display:inline-block;background:${color};color:${onColor};font-size:16px;line-height:48px;font-weight:600;text-decoration:none;padding:0 32px;border-radius:10px;mso-hide:all;">${e(t.button)}</a><!--<![endif]-->
+    </td></tr>
+    <tr><td class="px muted" style="padding:0 40px 8px 40px;font-size:14px;line-height:22px;color:#6b7280;">${e(expires)}</td></tr>
+    <tr><td class="px muted" style="padding:16px 40px 4px 40px;font-size:13px;line-height:20px;color:#6b7280;">${e(t.fallback)}</td></tr>
+    <tr><td class="px" style="padding:0 40px 24px 40px;font-size:13px;line-height:20px;word-break:break-all;"><a class="link" href="${url}" style="color:${color};text-decoration:underline;">${url}</a></td></tr>
+    <tr><td class="px" style="padding:0 40px;"><div class="rule" style="border-top:1px solid #e5e7eb;font-size:0;line-height:0;">&nbsp;</div></td></tr>
+    <tr><td class="px muted" style="padding:20px 40px 6px 40px;font-size:13px;line-height:20px;color:#6b7280;">${e(t.ignore)}</td></tr>
+    <tr><td class="px muted" style="padding:6px 40px ${help ? "6px" : "28px"} 40px;font-size:12px;line-height:18px;color:#9ca3af;">${e(sentBy)}</td></tr>
+    ${help ? `<tr><td class="px muted" style="padding:0 40px 28px 40px;font-size:12px;line-height:18px;color:#9ca3af;">${e(help)}</td></tr>` : ""}
+  </table>
+</td></tr>
+</table>
+</body>
+</html>`;
+    const text = [
+        heading,
+        "",
+        introText,
+        roles.length ? `${roleLabel}: ${roles.join(", ")}` : undefined,
+        "",
+        `${t.button}: ${acceptUrl}`,
+        "",
+        expires,
+        "",
+        t.ignore,
+        "",
+        "--",
+        sentBy,
+        help,
+    ]
+        .filter((line) => line !== undefined)
+        .join("\n");
+    return { subject, html, text };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@uniora/mailer-smtp",
+  "version": "0.3.0",
+  "description": "SMTP delivery for UNIORA invitations: configured from .env, with professional multilingual e-mail templates",
+  "license": "PolyForm-Shield-1.0.0",
+  "keywords": [
+    "uniora",
+    "smtp",
+    "email",
+    "invitations",
+    "nodemailer"
+  ],
+  "homepage": "https://github.com/CodexSploitx/uniora#readme",
+  "bugs": {
+    "url": "https://github.com/CodexSploitx/uniora/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CodexSploitx/uniora.git",
+    "directory": "packages/mailer-smtp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "nodemailer": "^10.0.6",
+    "@uniora/core": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/smtp-server": "^3.5.13",
+    "smtp-server": "^3.19.17",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}