@mikitasazan/notify 1.8.0 → 1.9.0

package/dist/render.d.ts

@@ -1,56 +1,59 @@
 /**
- * Один рендерер на тип события, все по одному каркасу — утверждён
- * владельцем 20.08.2026 после ~15 живых раундов в тестовом форуме:
+ * One renderer per event type, all built on one skeleton — approved by
+ * the owner on 20.08.2026 after ~15 live rounds in the test forum:
  *
- *   #тип #экземпляр
- *   значок <b>Тип:</b> действие
+ *   #type #instance
+ *   icon <b>Type:</b> action
  *
- *   <b>Ярлык:</b> значение
- *   <blockquote>цитата чужого текста — тело коммита, тело задачи</blockquote>
+ *   <b>Label:</b> value
+ *   <blockquote>quoted text from someone else — commit body, task body</blockquote>
  *
- *   <i><u>Группа</u></i>
- *   <b>#N (overdue):</b> <a>заголовок</a>
+ *   <i><u>Group</u></i>
+ *   <b>#N (overdue):</b> <a>title</a>
  *
- *   <b>Ярлык:</b> значение   ← действия/направления
+ *   <b>Label:</b> value   ← actions/directions
  *
- * Три уровня начертания, никогда не смешиваются: поле — жирный ярлык с
- * большой буквы + обычное значение; группа — курсив+подчёркивание, без
- * жирности и без двоеточия; строка 2 (тип) — тот же закон поля. Пустая
- * строка разделяет БЛОКИ ПО СМЫСЛУ (шапка / суть / действия), не механически
- * после каждой строки.
+ * Three levels of styling, never mixed: a field is a bold, capitalized
+ * label plus a plain value; a group is italic+underline, no bold and no
+ * colon; line 2 (the type) follows the same field rule. A blank line
+ * separates BLOCKS BY MEANING (header / body / actions), not mechanically
+ * after every line.
  */
-import { type NotifyEvent } from './events.ts';
-/** Экранируется ВСЁ, что пришло снаружи — теги ставит только шаблон. */
+import { ICON, type NotifyEvent } from './events.ts';
+/** Escapes EVERYTHING that comes from outside — only the template adds tags. */
 export declare const esc: (v: unknown) => string;
 /**
- * Telegram режет сообщение на 4096 символах — режем сами, по возможности по
- * границе строки.
+ * Telegram cuts a message at 4096 characters — we cut it ourselves first,
+ * on a line boundary where possible.
  *
- * Два подвоха, оба приводили к ТИХОЙ потере сообщения:
- * 1. Резать строго по последнему `\n` нельзя: если длинный кусок идёт одной
- *    строкой (стектрейс, вывод команды — самый частый `detail` у инцидента),
- *    последний перевод строки стоит ПЕРЕД ним, и содержимое выбрасывалось
- *    целиком — приходил заголовок без единого факта о поломке.
- * 2. Резать посреди HTML-тега или сущности тоже нельзя: Telegram отвечает
- *    `400 can't parse entities`, а 4xx мы считаем постоянной ошибкой и не
- *    повторяем — сообщение исчезало совсем.
+ * Two traps, both caused a SILENT loss of the message:
+ * 1. Cutting strictly at the last `\n` does not work: if a long chunk runs
+ *    as one line (a stack trace, command output — the most common `detail`
+ *    on an incident), the last line break sits BEFORE it, and the whole
+ *    content got dropped — only the heading arrived, with not a single
+ *    fact about what broke.
+ * 2. Cutting in the middle of an HTML tag or entity does not work either:
+ *    Telegram replies `400 can't parse entities`, and we treat a 4xx as a
+ *    permanent error and do not retry — the message disappeared for good.
  */
 export declare const clampMessage: (text: string, limit?: number) => string;
 export declare const slug: (raw: string) => string;
 /**
- * Экземпляр-тег: что именно это конкретное событие (ветка, окружение,
- * задача, номер) — по нему разборщик сверяет 🔴 с более поздней зелёной
- * карточкой ТОГО ЖЕ экземпляра. Явный `key` побеждает всегда; без него —
- * выводится из самых стабильных полей типа (ветка/окружение важнее заголовка,
- * потому что заголовок у регулярной задачи не меняется, а у отчёта как раз
- * заголовок и есть единственное стабильное поле).
+ * The instance tag: exactly which concrete event this is (branch,
+ * environment, task, number) — the parser uses it to match a 🔴 against a
+ * later green card of the SAME instance. An explicit `key` always wins;
+ * without one, it is derived from the type's most stable fields (branch/
+ * environment outrank the title, because a recurring task's title does not
+ * change, while for a report the title is exactly the one stable field it
+ * has).
  */
 export declare const eventKey: (e: NotifyEvent) => string;
 /**
- * Третий тег — ИСХОД, и он есть всегда. Владелец: «не хватает тега fail или
- * похожего, чтобы фейлы можно было группировать и ок можно было группировать».
- * Одно нажатие в Telegram собирает все падения проекта разом, каким бы типом
- * они ни пришли — выкатка, проверка, задача по расписанию, авария.
+ * The third tag is the OUTCOME, and it is always there. The owner: "I'm
+ * missing a fail tag or something like it, so failures can be grouped and
+ * ok can be grouped." One tap in Telegram collects every failure of a
+ * project at once, no matter what type it arrived as — a deploy, a check,
+ * a scheduled task, an incident.
  *
  * The value comes from the ICON, never from the status word. The icon is
  * already the single source of truth for the sound, and a second list of "what
@@ -62,21 +65,26 @@ export declare const eventKey: (e: NotifyEvent) => string;
  * `#fail` under a 🚫 and said so. Nor is a task that has simply gone quiet —
  * nobody knows yet whether it broke, and `#unknown` is the honest word for it.
  */
-export declare const OUTCOME_TAG: Readonly<Record<string, string>>;
-export declare const outcomeTag: (e: NotifyEvent) => string;
+/** Every icon the package can print — the key space of the outcome table. */
+type Icon = (typeof ICON)[keyof typeof ICON];
+/** The five words the third tag is allowed to be, and there is no sixth. */
+type OutcomeTag = 'ok' | 'fail' | 'off' | 'unknown' | 'news';
 /**
- * Строка тегов для свободного HTML (`sendReport`). Тег — это ФИЛЬТР владельца,
- * и к формату тела он отношения не имеет: дневной отчёт остаётся свободным
- * текстом, но перестаёт быть единственной карточкой без тегов. Раньше ключ
- * висел хвостом в `<i><code>#ключ</code></i>` — это старый формат, до того как
- * теги переехали первой строкой.
+ * The type is `Record` over EVERY icon, not over `string`. A new icon added to
+ * `ICON` without a word here now fails to compile. Under the old loose type it
+ * fell through a `?? 'news'` default instead: a card whose outcome nobody had
+ * decided was indistinguishable from a card that is genuinely just news, and
+ * nothing anywhere went red. `news` is therefore written out for each icon
+ * that means it, never left to a fallback.
  */
-export declare const reportTags: (key: string) => string;
+export declare const OUTCOME_TAG: Readonly<Record<Icon, OutcomeTag>>;
+export declare const outcomeTag: (e: NotifyEvent) => OutcomeTag;
 /**
- * Рендерит событие в готовый HTML-текст, обрезанный под лимит Telegram.
- * Теги — ПЕРВАЯ строка, добавляются до обрезки (не после, как раньше): они
- * несут и человеческий фильтр, и машинный ключ разборщика — обрезанная
- * карточка без них была бы не только некликабельной, но и невидимой
- * разборщику ровно на самых длинных, то есть самых важных сообщениях.
+ * Renders an event into finished HTML text, cut to Telegram's limit.
+ * Tags are the FIRST line, added before the cut (not after, as before):
+ * they carry both the human filter and the parser's machine key — a card
+ * cut without them would be not only unclickable but invisible to the
+ * parser on exactly the longest, meaning the most important, messages.
  */
 export declare const render: (e: NotifyEvent) => string;
+export {};