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

package/sendMessage/wappi.ts

@@ -25,11 +25,31 @@ interface WappiFileMessageData extends WappiMessageData {
     fileName: string;
 }
 
+/**
+ * Ответ Wappi в той части, которую разбирает класс.
+ *
+ * Описан по фактически читаемым полям, а не по всему API. Поля `check` и `haveContact`
+ * в ответе Wappi отсутствуют — их дописывает сам класс в объект ответа, поэтому
+ * в интерфейсе они обязаны быть, иначе присваивание не пройдёт тайпчек
+ */
+interface WappiResponse {
+    status?: string;
+    detail?: string;
+    on_max?: boolean;
+    on_whatsapp?: boolean;
+    contact?: unknown;
+    /** Дописывается классом: номер пригоден для отправки */
+    check?: boolean;
+    /** Дописывается классом: контакт найден или создан */
+    haveContact?: boolean;
+}
+
 /** Стандартный результат операции */
 interface WappiResult {
     error: boolean;
     message: string;
-    data: any;
+    /** Ответ Wappi как есть — форму задаёт сервис, потребитель приводит сам */
+    data: unknown;
     /**
      * Ответа не дождались. Отличает «проверка сказала нет» от «проверки не было»:
      * без этого признака вызывающий код принимает таймаут за отрицательный ответ.
@@ -93,7 +113,7 @@ export class Wappi {
             url = `https://wappi.pro/maxapi/sync/message/send?${sendOpenLine}profile_id=${profile_id}`;
         }
 
-        let data: any;
+        let data: WappiResponse;
         try {
             const res = await fetchWithTimeout(
                 url!,
@@ -110,7 +130,7 @@ export class Wappi {
                 },
                 FETCH_TIMEOUTS.send
             );
-            data = await res.json();
+            data = (await res.json()) as WappiResponse;
         } catch (error: unknown) {
             // Метод исторически без try/catch — перехватываем только таймаут, который сами
             // и вводим, чтобы не появился новый путь исключений там, где его сегодня нет.
@@ -202,7 +222,7 @@ export class Wappi {
             url = `https://wappi.pro/maxapi/async/message/file/url/send?${sendOpenLine}profile_id=${profile_id}`;
         }
 
-        let data: any;
+        let data: WappiResponse;
         try {
             // В теле уходит base64 файла — бюджет transfer, а не send
             const res = await fetchWithTimeout(
@@ -223,7 +243,7 @@ export class Wappi {
                 },
                 FETCH_TIMEOUTS.transfer
             );
-            data = await res.json();
+            data = (await res.json()) as WappiResponse;
         } catch (error: unknown) {
             // Перехватываем только таймаут, остальные ошибки ведут себя как раньше
             if (!isTimeoutError(error)) throw error;
@@ -265,9 +285,14 @@ export class Wappi {
             const contactCheck = await this.getContactTelegramWappi(phone);
 
             // 2 Если существует, то номер в телеге есть, можем отправлять сообщение
-            if (!contactCheck.error && contactCheck.data.haveContact) {
-                contactCheck.data.check = true;
-                return { error: false, message: `Номер ${phone} проверен для мессенджера ${messangerType}`, data: contactCheck.data };
+            // Приведение, а не проверка: `data` объявлен unknown только в публичном типе,
+            // внутри класса это всегда разобранный ответ Wappi. На ошибке там null,
+            // но до чтения поля не доходит — первым проверяется `!contactCheck.error`,
+            // порядок вычисления тот же, что и до 4.0.0
+            const contactData = contactCheck.data as WappiResponse;
+            if (!contactCheck.error && contactData.haveContact) {
+                contactData.check = true;
+                return { error: false, message: `Номер ${phone} проверен для мессенджера ${messangerType}`, data: contactData };
             }
 
             // Ответа не дождались — это не «контакта нет». Создавать контакт вслепую нельзя:
@@ -280,14 +305,15 @@ export class Wappi {
 
             // 3 Если не существует, то номера в телеге нет, пробуем создать
             const addContactResult = await this.addContactTelegramWappi(phone);
+            const addedData = addContactResult.data as WappiResponse;
 
             if (!addContactResult.error) {
                 // Если получается создать, отправляем информацию
-                addContactResult.data.check = true;
-                return { error: false, message: `Номер ${phone} успешно добавлен и проверен для мессенджера ${messangerType}`, data: addContactResult.data };
+                addedData.check = true;
+                return { error: false, message: `Номер ${phone} успешно добавлен и проверен для мессенджера ${messangerType}`, data: addedData };
             }
             // Если не получается, то отправляем информацию об ошибке
-            return { error: true, message: `Не удалось проверить и добавить номер ${phone} в Telegram: ${addContactResult.message}`, data: addContactResult.data };
+            return { error: true, message: `Не удалось проверить и добавить номер ${phone} в Telegram: ${addContactResult.message}`, data: addedData };
         }
         if (messangerType === "max") {
             token = this.maxAuth.token;
@@ -295,7 +321,7 @@ export class Wappi {
             url = `https://wappi.pro/maxapi/sync/contact/check?profile_id=${profile_id}&phone=${phone}`;
         }
 
-        let data: any;
+        let data: WappiResponse;
         try {
             const res = await fetchWithTimeout(
                 url!,
@@ -308,7 +334,7 @@ export class Wappi {
                 },
                 FETCH_TIMEOUTS.api
             );
-            data = await res.json();
+            data = (await res.json()) as WappiResponse;
         } catch (error: unknown) {
             // Перехватываем только таймаут, остальные ошибки ведут себя как раньше
             if (!isTimeoutError(error)) throw error;
@@ -353,7 +379,7 @@ export class Wappi {
                 FETCH_TIMEOUTS.api
             );
 
-            const data: any = await res.json();
+            const data = (await res.json()) as WappiResponse;
 
             if (data.status !== "done") {
                 return { error: true, message: `Ошибка получения контакта ${phone} из Telegram`, data };
@@ -405,7 +431,7 @@ export class Wappi {
                 FETCH_TIMEOUTS.send
             );
 
-            const data: any = await res.json();
+            const data = (await res.json()) as WappiResponse;
             if (data.status !== "done") {
                 return { error: true, message: `Ошибка создания контакта ${phone} в Telegram`, data };
             }

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"];