@andrey4emk/npm-app-back-b24 3.8.2 → 3.9.0

package/sendMessage/email.ts

@@ -1,4 +1,5 @@
-import nodemailer from "nodemailer";
+import nodemailer, { type SendMailOptions } from "nodemailer";
+import { logs } from "../logs/logs.ts";
 import { fetchWithTimeout, FETCH_TIMEOUTS } from "../utils/fetchRetry.ts";
 
 // ==================== Типы ====================
@@ -9,6 +10,12 @@ interface EmailAuthParam {
     pass: string;
 }
 
+/** Вложение письма */
+interface EmailAttachment {
+    filename: string;
+    content: Buffer;
+}
+
 /** Данные для отправки письма */
 interface EmailData {
     to: string;
@@ -17,7 +24,7 @@ interface EmailData {
     html?: string;
     fileUrl?: string;
     fileName?: string;
-    attachments?: { filename: string; content: Buffer }[] | null;
+    attachments?: EmailAttachment[] | null;
 }
 
 /** Результат отправки письма */
@@ -27,66 +34,260 @@ interface EmailResult {
     info?: unknown;
 }
 
+/**
+ * Ответ транспорта в той части, которую разбирает класс.
+ *
+ * Собственный узкий тип, а не `SentMessageInfo` из `@types/nodemailer`: там он
+ * объявлен как `any`, и в сигнатуру пакета это тянуть нельзя.
+ */
+export interface SendMailInfo {
+    accepted?: unknown;
+    rejected?: unknown;
+    response?: unknown;
+}
+
+/**
+ * Минимальный контракт транспорта — ровно то, что использует класс.
+ *
+ * Второй аргумент конструктора существует ради тестов и подмены транспорта
+ * у потребителя; по умолчанию класс поднимает SMTP Яндекса сам.
+ */
+export interface MailTransport {
+    sendMail(mail: SendMailOptions): Promise<SendMailInfo>;
+}
+
+// ==================== Утилиты ====================
+
+/**
+ * Грубая проверка адреса: непустая строка без пробелов, одна собака,
+ * непустые части слева и справа.
+ *
+ * Полная валидация адресов регуляркой — известная ловушка, и она здесь не нужна:
+ * цель — отсечь пустую строку и явный мусор, отказ сервера всё равно проверяется
+ * по ответу. Точку в домене не требуем: внутрикорпоративные адреса без точки существуют.
+ */
+function isLikelyEmail(value: unknown): value is string {
+    if (typeof value !== "string") return false;
+    if (/\s/.test(value)) return false;
+
+    const parts = value.split("@");
+    if (parts.length !== 2) return false;
+
+    const [local, domain] = parts;
+    return Boolean(local) && Boolean(domain);
+}
+
+/**
+ * Приводит адрес к той форме, в которой его возвращает почтовый сервер.
+ *
+ * Сравнивать «как передали» нельзя: конверт письма строит nodemailer, и в `accepted`
+ * приходит адрес из конверта — домен в punycode, угловые скобки сняты. Живой адрес
+ * `ivan@пример.рф` возвращался как `ivan@xn--e1afmkfd.xn--p1ai`, с исходным не совпадал,
+ * и доставленное письмо объявлялось недоставленным.
+ *
+ * Применяется к обеим сторонам сравнения. Локальная часть приводится к нижнему регистру
+ * намеренно: формально она регистрозависима, но здесь адрес сверяется сам с собой,
+ * а не с чужим.
+ */
+function normalizeAddress(value: string): string {
+    let address = value.trim();
+
+    if (address.startsWith("<") && address.endsWith(">")) {
+        address = address.slice(1, -1).trim();
+    }
+
+    // Разделяем по последней собаке: в локальной части она допустима в кавычках
+    const separator = address.lastIndexOf("@");
+    if (separator <= 0) return address.toLowerCase();
+
+    const local = address.slice(0, separator);
+    const domain = address.slice(separator + 1);
+
+    let host: string;
+    try {
+        // Доступный в Node способ получить punycode-форму домена: разбор хоста в URL
+        // делает то же преобразование, что и nodemailer при построении конверта
+        host = new URL(`http://${domain}`).hostname;
+    } catch {
+        // Домен как хост не разбирается (пустой, с недопустимым символом) — сверяем как есть
+        host = domain.toLowerCase();
+    }
+
+    return `${local.toLowerCase()}@${host}`;
+}
+
+/**
+ * Приводит `accepted`/`rejected` к списку нормализованных адресов.
+ *
+ * Элементы приходят строкой либо объектом `{ name, address }` — форма зависит
+ * от того, как адрес был передан в `sendMail`.
+ */
+function toAddressList(value: unknown): string[] {
+    if (!Array.isArray(value)) return [];
+
+    const addresses: string[] = [];
+
+    for (const item of value as unknown[]) {
+        if (typeof item === "string") {
+            addresses.push(item);
+            continue;
+        }
+
+        if (item && typeof item === "object") {
+            const address = (item as { address?: unknown }).address;
+            if (typeof address === "string") addresses.push(address);
+        }
+    }
+
+    return addresses.map((address) => normalizeAddress(address)).filter((address) => address !== "");
+}
+
+/**
+ * Имя для скачанного вложения: явно переданное `fileName`, иначе последний
+ * сегмент пути из URL (без query), иначе запасное `attachment`.
+ *
+ * Прежде здесь стояло `dataMail.fileName!`, и письмо с `fileUrl` без имени
+ * уезжало с вложением без имени файла.
+ */
+function resolveAttachmentName(fileUrl: string, fileName?: string): string {
+    const explicit = fileName?.trim();
+    if (explicit) return explicit;
+
+    try {
+        const segment = new URL(fileUrl).pathname.split("/").pop();
+        const decoded = segment ? decodeURIComponent(segment) : "";
+        if (decoded) return decoded;
+    } catch {
+        // Адрес может быть относительным или битым — тогда берём запасное имя
+    }
+
+    return "attachment";
+}
+
 // ==================== Класс ====================
 
 export class Email {
     private auth: EmailAuthParam;
-    private transporter: ReturnType<typeof nodemailer.createTransport>;
+    private transporter: MailTransport;
 
-    constructor(auth: EmailAuthParam) {
+    constructor(auth: EmailAuthParam, transporter?: MailTransport) {
         this.auth = auth;
-        this.transporter = nodemailer.createTransport({
-            auth: {
-                user: this.auth.user,
-                pass: this.auth.pass,
-            },
-            host: "smtp.yandex.ru",
-            port: 465, // 465 = SMTPS, 587 = STARTTLS
-            secure: true, // true для 465
-            // Дефолты nodemailer (соединение 2 мин, приветствие 30с, сокет 10 мин) слишком щедры:
-            // письмо с вложением уходит на Яндекс за секунды, а 10 минут молчания сокета
-            // блокируют вызывающую очередь
-            connectionTimeout: 15_000,
-            greetingTimeout: 10_000,
-            socketTimeout: 120_000,
-        });
+        this.transporter =
+            transporter ??
+            nodemailer.createTransport({
+                auth: {
+                    user: this.auth.user,
+                    pass: this.auth.pass,
+                },
+                host: "smtp.yandex.ru",
+                port: 465, // 465 = SMTPS, 587 = STARTTLS
+                secure: true, // true для 465
+                // Дефолты nodemailer (соединение 2 мин, приветствие 30с, сокет 10 мин) слишком щедры:
+                // письмо с вложением уходит на Яндекс за секунды, а 10 минут молчания сокета
+                // блокируют вызывающую очередь
+                connectionTimeout: 15_000,
+                greetingTimeout: 10_000,
+                socketTimeout: 120_000,
+            });
     }
 
+    /**
+     * Отправляет письмо получателю, копию — на адрес отправителя.
+     *
+     * Адрес получателя проверяется до вызова транспорта: пустой или мусорный `to`
+     * раньше давал «успешную» отправку копии себе и ни одной жалобы в логе.
+     *
+     * Вложения вызывающего (`attachments`) сохраняются и дополняются файлом,
+     * скачанным по `fileUrl`. Входной объект не мутируется.
+     *
+     * @param dataMail — адресат, тема, тело письма, вложения
+     * @returns `{ error, message?, info? }`; `error: true` приходит и тогда, когда
+     *          сервер принял копию отправителю, но отверг получателя
+     */
     async send(dataMail: EmailData): Promise<EmailResult> {
         try {
-            // Если прислали ссылку на файл, то скачиваем его и добавляем в attachments
+            const to = typeof dataMail.to === "string" ? dataMail.to.trim() : "";
+            if (!isLikelyEmail(to)) {
+                return { error: true, message: `Email: адрес получателя некорректен ('${String(dataMail.to)}') — письмо не отправлено` };
+            }
+
+            // Вложения вызывающего не затираем и входной объект не мутируем:
+            // `attachments` и пара `fileUrl`/`fileName` объявлены независимыми полями,
+            // ни одно не документировано как «вместо». Тот, кто заполнил оба, хочет оба;
+            // замена молча теряла данные. Порядок: сначала переданные, затем скачанное
+            const attachments: EmailAttachment[] = [...(dataMail.attachments ?? [])];
+
             if (dataMail.fileUrl) {
                 const resDownloadFile = await this.downloadFileToUrl(dataMail.fileUrl);
-                if (resDownloadFile.error) {
+                if (resDownloadFile.error || !resDownloadFile.buffer) {
                     // Подстановка вместо возможного undefined: при exactOptionalPropertyTypes
                     // у потребителя явный undefined не подходит полю message?: string
                     return { error: true, message: resDownloadFile.message ?? "Не удалось скачать файл по fileUrl" };
                 }
-                dataMail.attachments = [
-                    {
-                        filename: dataMail.fileName!,
-                        content: resDownloadFile.buffer!,
-                    },
-                ];
-            } else {
-                dataMail.attachments = null;
+
+                attachments.push({
+                    filename: resolveAttachmentName(dataMail.fileUrl, dataMail.fileName),
+                    content: resDownloadFile.buffer,
+                });
             }
 
             const info = await this.transporter.sendMail({
                 from: `Натяжные потолки Репа. <${this.auth.user}>`,
-                to: [dataMail.to, this.auth.user],
+                to: [to, this.auth.user],
                 subject: dataMail.subject,
                 text: dataMail.text,
                 html: dataMail.html,
-                attachments: dataMail.attachments ?? undefined,
+                attachments: attachments.length > 0 ? attachments : undefined,
             });
-            return { error: false, info };
+
+            return this.checkDelivery(to, info);
         } catch (error: unknown) {
             const message = error instanceof Error ? error.message : String(error);
             return { error: true, message };
         }
     }
 
+    /**
+     * Проверяет по ответу транспорта, принял ли сервер основного адресата.
+     *
+     * В `to` всегда уходит пара «получатель + отправитель», а `sendMail` резолвится,
+     * если принят хотя бы один адрес. Без этой проверки отказ по получателю
+     * возвращался вызывающему как `error: false`.
+     *
+     * Отказ логируется не здесь: результат уходит вызывающему, а уровень `error`
+     * дублировался бы в чат B24. От таймаутов отправки в `Smsgold`/`Wappi` случай
+     * отличается тем, что статус известен — сервер прямо сказал «не принял».
+     */
+    private checkDelivery(to: string, info: SendMailInfo): EmailResult {
+        const hasReport = Array.isArray(info?.accepted) || Array.isArray(info?.rejected);
+
+        // Транспорт вообще не сообщил, какие адреса приняты. Отказ здесь не выдумываем:
+        // у SMTP-транспорта эти поля есть всегда, а объявить успешно доставленное письмо
+        // ошибкой — регресс хуже исходного дефекта. Успех плюс строка в лог
+        if (!hasReport) {
+            logs.add("Email: транспорт не сообщил, какие адреса приняты — проверить доставку нечем", "warn");
+            return { error: false, info };
+        }
+
+        // Обе стороны сравнения нормализуем одинаково: сервер отдаёт адреса из конверта,
+        // а не в том виде, в каком их передали
+        const target = normalizeAddress(to);
+        const accepted = toAddressList(info.accepted);
+        const rejected = toAddressList(info.rejected);
+
+        if (rejected.includes(target) || !accepted.includes(target)) {
+            const response = typeof info.response === "string" && info.response.trim() !== "" ? ` Ответ сервера: ${info.response}` : "";
+
+            return {
+                error: true,
+                message: `Email: почтовый сервер не принял адрес получателя ${to}, письмо ему не ушло (копия отправителю могла уйти).${response}`,
+                info,
+            };
+        }
+
+        return { error: false, info };
+    }
+
     private async downloadFileToUrl(fileUrl: string): Promise<{ error: boolean; message?: string; buffer?: Buffer }> {
         try {
             const response = await fetchWithTimeout(fileUrl, undefined, FETCH_TIMEOUTS.transfer);

package/utils/fetchRetry.ts

@@ -31,7 +31,15 @@ function isValidTimeout(value: number): boolean {
 }
 
 /**
- * Читает бюджет запроса из переменной окружения `FETCH_TIMEOUT_MS`.
+ * Верхняя граница подозрительного бюджета: значение от 1 до 999 мс почти наверняка
+ * означает, что человек написал секунды вместо миллисекунд.
+ *
+ * Ноль сюда не входит — это задокументированное выключение таймаута.
+ */
+const SUSPICIOUS_TIMEOUT_MAX_MS = 999;
+
+/**
+ * Читает бюджет запроса из переменной окружения `name`.
  *
  * `dotenv.config()` вызывается в `logs/logs.ts`, а этот модуль импортирует `logs`
  * первой строкой — значит к моменту чтения `process.env` файл `.env` уже загружен.
@@ -39,15 +47,38 @@ function isValidTimeout(value: number): boolean {
  * Значение принимается, только если это целое число >= 0 (0 означает «без таймаута»).
  * Любой мусор в переменной не должен молча превращаться в `NaN` или в обрезанное
  * `parseInt`-число, поэтому проверяем фактом и падаем на дефолт с записью в лог.
+ * Пустая строка и строка из пробелов считаются «переменная не задана» — молча дефолт.
+ *
+ * Значение от 1 до 999 применяется как есть, но с записью `warn`: столько миллисекунд
+ * не хватит ни одному живому запросу, и это типовая путаница секунд с миллисекундами.
+ * Молча такое значение пропускать нельзя — на бюджетах отправки оно превращается
+ * в массовую недоставку с «неизвестным статусом» и потоком `error` в чат портала.
+ *
+ * Экспортируется по двум причинам: одинаковая семантика для всех бюджетов пакета
+ * (дефолт `fetchRetry` и каждый из `FETCH_TIMEOUTS` читаются одной и той же функцией)
+ * и проверяемость тестом без запуска дочернего процесса.
+ *
+ * Важно: все чтения происходят **один раз при загрузке модуля**. Правка `process.env`
+ * в рантайме на уже вычисленные константы не влияет.
+ *
+ * @param name — имя переменной окружения
+ * @param fallback — значение, если переменная не задана или непригодна
+ * @returns бюджет в мс
  */
-function readTimeoutFromEnv(): number {
-    const raw = process.env.FETCH_TIMEOUT_MS;
-    if (raw === undefined || raw.trim() === "") return FALLBACK_TIMEOUT_MS;
+export function readTimeoutFromEnv(name: string, fallback: number): number {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "") return fallback;
 
     const parsed = Number(raw);
     if (!isValidTimeout(parsed)) {
-        logs.add(`FETCH_TIMEOUT_MS: значение '${raw}' непригодно (нужно целое от 0 до ${MAX_TIMEOUT_MS}) — берём ${FALLBACK_TIMEOUT_MS}мс`, "warn");
-        return FALLBACK_TIMEOUT_MS;
+        logs.add(`${name}: значение '${raw}' непригодно (нужно целое от 0 до ${MAX_TIMEOUT_MS}) — берём ${fallback}мс`, "warn");
+        return fallback;
+    }
+
+    // Значение применяем как есть: аварийный рычаг остаётся в руках у человека,
+    // мы только делаем подозрительный ввод видимым
+    if (parsed >= 1 && parsed <= SUSPICIOUS_TIMEOUT_MAX_MS) {
+        logs.add(`${name}: значение '${raw}' похоже на секунды, а нужны миллисекунды — бюджет ${parsed}мс применён как есть`, "warn");
     }
 
     return parsed;
@@ -58,7 +89,13 @@ function readTimeoutFromEnv(): number {
  * из `FETCH_TIMEOUT_MS`, иначе 60 000. Значение 0 полностью выключает таймаут —
  * это аварийный рычаг для случая, когда дефолт обрывает живой долгий запрос.
  */
-export const DEFAULT_FETCH_TIMEOUT_MS: number = readTimeoutFromEnv();
+export const DEFAULT_FETCH_TIMEOUT_MS: number = readTimeoutFromEnv("FETCH_TIMEOUT_MS", FALLBACK_TIMEOUT_MS);
+
+/** Дефолты именованных бюджетов до чтения окружения, мс */
+const FALLBACK_TIMEOUTS = { quick: 10_000, api: 20_000, send: 30_000, transfer: 60_000 } as const;
+
+/** Имя именованного бюджета пакета */
+export type FetchTimeoutName = keyof typeof FALLBACK_TIMEOUTS;
 
 /**
  * Именованные бюджеты для вызовов внутри пакета: смысл каждого запроса тут известен,
@@ -68,8 +105,32 @@ export const DEFAULT_FETCH_TIMEOUT_MS: number = readTimeoutFromEnv();
  * - `api` — короткое чтение (проверка номера, список лицензий, получение контакта);
  * - `send` — отправка текста, создание контакта, отправка SMS;
  * - `transfer` — скачивание файла и отправка файла/вложения.
+ *
+ * Каждый бюджет переопределяется своей переменной окружения:
+ *
+ * | Ключ | Переменная | Дефолт, мс |
+ * |---|---|---|
+ * | `quick` | `FETCH_TIMEOUT_QUICK_MS` | 10 000 |
+ * | `api` | `FETCH_TIMEOUT_API_MS` | 20 000 |
+ * | `send` | `FETCH_TIMEOUT_SEND_MS` | 30 000 |
+ * | `transfer` | `FETCH_TIMEOUT_TRANSFER_MS` | 60 000 |
+ *
+ * Значения читаются один раз при загрузке модуля: правка `process.env` в рантайме
+ * их не двигает, менять бюджет нужно до старта процесса.
+ *
+ * Значение 0 выключает таймаут для этого бюджета целиком. Это аварийный рычаг,
+ * и у отправок (`send`, `transfer`) он снимает заодно защиту «неизвестный статус
+ * доставки»: при нуле зависшая отправка снова держится до таймаутов undici,
+ * а `unknownDelivery` в `Smsgold` не выставится никогда.
+ *
+ * Непригодное значение защиту молча не выключает: одна строка `warn` и дефолт.
  */
-export const FETCH_TIMEOUTS = { quick: 10_000, api: 20_000, send: 30_000, transfer: 60_000 } as const;
+export const FETCH_TIMEOUTS: Readonly<Record<FetchTimeoutName, number>> = {
+    quick: readTimeoutFromEnv("FETCH_TIMEOUT_QUICK_MS", FALLBACK_TIMEOUTS.quick),
+    api: readTimeoutFromEnv("FETCH_TIMEOUT_API_MS", FALLBACK_TIMEOUTS.api),
+    send: readTimeoutFromEnv("FETCH_TIMEOUT_SEND_MS", FALLBACK_TIMEOUTS.send),
+    transfer: readTimeoutFromEnv("FETCH_TIMEOUT_TRANSFER_MS", FALLBACK_TIMEOUTS.transfer),
+};
 
 /** Читает `name` с произвольного значения ошибки, не полагаясь на её тип */
 function getErrorName(error: unknown): string | null {
@@ -135,7 +196,7 @@ export function isNetworkError(error: unknown): boolean {
 
 /**
  * Коды, доказывающие, что соединение не было установлено: DNS не разрешился либо
- * хост отверг подключение. Запрос при таких ошибках гарантированно не дошёл до сервера.
+ * хост отверг подключение. Соединение с целевым хостом не состоялось.
  */
 const PRE_CONNECTION_ERROR_CODES = ["ENOTFOUND", "EAI_AGAIN", "EAI_NODATA", "ECONNREFUSED", "ENETUNREACH", "EHOSTUNREACH", "ENETDOWN"];