@imessaging/core 0.7.4 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imessaging/core",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Core messaging transport contracts and Telegram peer storage",
   "keywords": [
     "messaging",

package/src/index.ts

@@ -1,3 +1,16 @@
+export {
+  formatText,
+  formattedOf,
+  isSafeUrl,
+  parseHtml,
+  parseMarkdown,
+  toHtml,
+  toPlainText,
+  type FormattedText,
+  type TextEntity,
+  type TextEntityType,
+  type TextFormat,
+} from "./markup";
 export { MemoryPeerStore } from "./memory-peer-store";
 export { createPeerKey } from "./peer-key";
 export {

package/src/markup.ts

@@ -0,0 +1,400 @@
+/**
+ * Разметка исходящего текста — одна модель на все каналы.
+ *
+ * Сообщение пишется один раз (`format: "markdown"` или `"html"`), а каждый транспорт сам решает, во что
+ * его превратить: Telegram и MAX получают HTML, почта — HTML и простой текст, hh — простой текст.
+ * Раньше это делал каждый потребитель у себя, и у почты конвертера не было вовсе: `**Чек-лист: 92%**`
+ * доезжал до кандидата звёздочками.
+ *
+ * Промежуточная форма — текст плюс выделения со смещениями в кодовых единицах UTF-16. Так её меряет
+ * и Telegram, и JS-строка, поэтому `slice` по смещению точен и на эмодзи.
+ */
+
+/** Как написан исходный текст сообщения. */
+export type TextFormat = "plain" | "markdown" | "html";
+
+export type TextEntityType = "bold" | "italic" | "underline" | "strike" | "code" | "pre" | "link";
+
+export type TextEntity = {
+  type: TextEntityType;
+  offset: number;
+  length: number;
+  /** Адрес ссылки — только у `link`. */
+  url?: string;
+  /** Язык блока кода — только у `pre`, если был указан. */
+  language?: string;
+};
+
+export type FormattedText = { text: string; entities: TextEntity[] };
+
+const ESCAPABLE = "\\`*_[]()~#-.!>|";
+const WORD = /[\p{L}\p{N}_]/u;
+const isWord = (ch: string | undefined) => ch !== undefined && WORD.test(ch);
+const isSpace = (ch: string | undefined) => ch === undefined || /\s/.test(ch);
+
+type Builder = { text: string; entities: TextEntity[] };
+
+function wrap(
+  out: Builder,
+  type: TextEntityType,
+  write: () => void,
+  extra: Partial<TextEntity> = {},
+): void {
+  const offset = out.text.length;
+  const at = out.entities.length;
+  write();
+  const length = out.text.length - offset;
+  // Внешнее выделение ставится ПЕРЕД вложенными: сериализатору нужен порядок «снаружи внутрь».
+  if (length > 0) out.entities.splice(at, 0, { type, offset, length, ...extra });
+}
+
+/** Закрывающий разделитель на той же строке: выделение через перевод строки — почти всегда опечатка. */
+function findCloser(
+  src: string,
+  from: number,
+  delimiter: string,
+  accept: (at: number) => boolean,
+): number {
+  let at = src.indexOf(delimiter, from);
+  while (at !== -1) {
+    if (src.slice(from, at).includes("\n")) return -1;
+    if (accept(at)) return at;
+    at = src.indexOf(delimiter, at + 1);
+  }
+  return -1;
+}
+
+function parseInline(src: string, out: Builder): void {
+  let i = 0;
+  while (i < src.length) {
+    const ch = src[i]!;
+    const next = src[i + 1];
+
+    if (ch === "\\" && next !== undefined && ESCAPABLE.includes(next)) {
+      out.text += next;
+      i += 2;
+      continue;
+    }
+
+    if (ch === "`") {
+      const end = src.indexOf("`", i + 1);
+      if (end > i + 1 && !src.slice(i + 1, end).includes("\n")) {
+        wrap(out, "code", () => (out.text += src.slice(i + 1, end)));
+        i = end + 1;
+        continue;
+      }
+    }
+
+    // Ссылка разбирается раньше выделений: иначе `_` внутри адреса стал бы курсивом.
+    if (ch === "[") {
+      const m = /^\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)/.exec(src.slice(i));
+      if (m) {
+        wrap(out, "link", () => parseInline(m[1]!, out), { url: m[2]! });
+        i += m[0].length;
+        continue;
+      }
+    }
+
+    const pair = src.slice(i, i + 2);
+    if (pair === "**" || pair === "__" || pair === "~~") {
+      // `__` — жирный только на границе слова: `snake__case` остаётся как есть.
+      const bounded = pair === "__";
+      if (!isSpace(src[i + 2]) && !(bounded && isWord(src[i - 1]))) {
+        const end = findCloser(
+          src,
+          i + 2,
+          pair,
+          (at) => at > i + 2 && !isSpace(src[at - 1]) && !(bounded && isWord(src[at + 2])),
+        );
+        if (end !== -1) {
+          wrap(out, pair === "~~" ? "strike" : "bold", () =>
+            parseInline(src.slice(i + 2, end), out),
+          );
+          i = end + 2;
+          continue;
+        }
+      }
+    }
+
+    if ((ch === "*" || ch === "_") && next !== ch && !isSpace(next)) {
+      // `_` — только на границе слова: иначе съедался бы в `stack_ids`, `@oksana_avd` и путях файлов.
+      const bounded = ch === "_";
+      if (!(bounded && isWord(src[i - 1]))) {
+        const end = findCloser(
+          src,
+          i + 1,
+          ch,
+          (at) =>
+            at > i + 1 &&
+            !isSpace(src[at - 1]) &&
+            src[at + 1] !== ch &&
+            !(bounded && isWord(src[at + 1])),
+        );
+        if (end !== -1) {
+          wrap(out, "italic", () => parseInline(src.slice(i + 1, end), out));
+          i = end + 1;
+          continue;
+        }
+      }
+    }
+
+    out.text += ch;
+    i += 1;
+  }
+}
+
+/**
+ * Markdown в том виде, в каком его пишут люди и модели: `**жирный**`, `__жирный__`, `*курсив*`, `_курсив_`,
+ * `~~зачёркнутый~~`, `` `код` ``, ```` ```блок``` ````, `[текст](https://…)`, `# заголовок`, `\*` — буквальная звёздочка.
+ * Заголовок становится жирной строкой, `* пункт` — `- пункт`: ни заголовков, ни списков в мессенджерах нет.
+ */
+export function parseMarkdown(source: string): FormattedText {
+  const out: Builder = { text: "", entities: [] };
+  const src = source.replace(/\r\n?/g, "\n");
+  // Язык — только если за ним перевод строки: в ```текст``` слово — содержимое, а не язык.
+  const fence = /```(?:([\w+-]+)\n|\n)?([\s\S]*?)```/g;
+  let last = 0;
+  for (const m of src.matchAll(fence)) {
+    parseLines(src.slice(last, m.index), out);
+    const language = m[1] || undefined;
+    wrap(out, "pre", () => (out.text += m[2]!.replace(/\n$/, "")), language ? { language } : {});
+    last = m.index + m[0].length;
+  }
+  parseLines(src.slice(last), out);
+  return out;
+}
+
+function parseLines(block: string, out: Builder): void {
+  const lines = block.split("\n");
+  lines.forEach((line, n) => {
+    if (n > 0) out.text += "\n";
+    const heading = /^#{1,6}\s+(.*?)\s*#*$/.exec(line);
+    if (heading) {
+      wrap(out, "bold", () => parseInline(heading[1]!, out));
+      return;
+    }
+    parseInline(line.replace(/^(\s*)[*•●·]\s+/, "$1- "), out);
+  });
+}
+
+const HTML_TAGS: Record<string, TextEntityType> = {
+  b: "bold",
+  strong: "bold",
+  i: "italic",
+  em: "italic",
+  u: "underline",
+  ins: "underline",
+  s: "strike",
+  strike: "strike",
+  del: "strike",
+  code: "code",
+  pre: "pre",
+  a: "link",
+};
+
+function decodeHtml(s: string): string {
+  return s.replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos|nbsp);/gi, (whole, name: string) => {
+    const lower = name.toLowerCase();
+    if (lower.startsWith("#x")) return String.fromCodePoint(Number.parseInt(lower.slice(2), 16));
+    if (lower.startsWith("#")) return String.fromCodePoint(Number.parseInt(lower.slice(1), 10));
+    return { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00a0" }[lower] ?? whole;
+  });
+}
+
+/**
+ * HTML в подмножестве Telegram: `b/strong`, `i/em`, `u/ins`, `s/strike/del`, `code`, `pre`, `a href`, `br`.
+ * Незнакомый тег снимается, текст внутри остаётся: письмо и hh не должны получить `<span>` буквами.
+ */
+export function parseHtml(source: string): FormattedText {
+  const out: Builder = { text: "", entities: [] };
+  const open: {
+    type: TextEntityType;
+    offset: number;
+    at: number;
+    tag: string;
+    url?: string;
+    language?: string;
+  }[] = [];
+  const tag = /<(\/?)([a-z][a-z0-9-]*)\b([^>]*)>/gi;
+  let last = 0;
+  for (const m of source.matchAll(tag)) {
+    out.text += decodeHtml(source.slice(last, m.index));
+    last = m.index + m[0].length;
+    const [, closing, rawName, attrs] = m;
+    const name = rawName!.toLowerCase();
+    if (name === "br") {
+      out.text += "\n";
+      continue;
+    }
+    const type = HTML_TAGS[name];
+    if (!type) continue;
+    if (!closing) {
+      const href = type === "link" ? /href\s*=\s*["']([^"']*)["']/i.exec(attrs!)?.[1] : undefined;
+      const decoded = href === undefined ? undefined : decodeHtml(href).trim();
+      const url = isSafeUrl(decoded) ? decoded : undefined;
+      // `<pre><code class="language-ts">` — язык живёт на вложенном `code`, а блок один.
+      const language = /class\s*=\s*["']language-([\w+-]+)["']/i.exec(attrs!)?.[1];
+      const parentPre = open.at(-1)?.type === "pre";
+      if (type === "code" && parentPre) {
+        if (language) open.at(-1)!.language = language;
+        open.push({ type, offset: -1, at: -1, tag: name });
+        continue;
+      }
+      open.push({
+        type,
+        offset: out.text.length,
+        at: out.entities.length,
+        tag: name,
+        ...(url ? { url } : {}),
+        ...(language ? { language } : {}),
+      });
+      continue;
+    }
+    const index = open.findLastIndex((o) => o.tag === name);
+    if (index === -1) continue;
+    const [entry] = open.splice(index, 1);
+    if (!entry || entry.offset < 0) continue;
+    const length = out.text.length - entry.offset;
+    if (length === 0 || (entry.type === "link" && !entry.url)) continue;
+    out.entities.splice(entry.at, 0, {
+      type: entry.type,
+      offset: entry.offset,
+      length,
+      ...(entry.url ? { url: entry.url } : {}),
+      ...(entry.language ? { language: entry.language } : {}),
+    });
+  }
+  out.text += decodeHtml(source.slice(last));
+  return out;
+}
+
+/** Выделения сообщения с заданным `format`; без него — `undefined`, и транспорт идёт прежним путём через `parseMode`. */
+export function formattedOf(message: {
+  text: string;
+  format?: TextFormat;
+}): FormattedText | undefined {
+  return message.format === undefined ? undefined : formatText(message.text, message.format);
+}
+
+export function formatText(text: string, format: TextFormat): FormattedText {
+  if (format === "markdown") return parseMarkdown(text);
+  if (format === "html") return parseHtml(text);
+  return { text, entities: [] };
+}
+
+/**
+ * Схемы, которые ссылка может нести. `javascript:` и `data:` в письме — это исполняемый код в HTML,
+ * поэтому такая ссылка остаётся текстом и в разборе, и в выводе.
+ */
+const SAFE_URL = /^(https?:\/\/|mailto:|tg:\/\/)/i;
+export const isSafeUrl = (url: string | undefined): url is string =>
+  url !== undefined && SAFE_URL.test(url.trim());
+
+const escapeHtml = (s: string) =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const escapeAttribute = (s: string) => escapeHtml(s).replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+
+function openTag(e: TextEntity): string {
+  switch (e.type) {
+    case "bold":
+      return "<b>";
+    case "italic":
+      return "<i>";
+    case "underline":
+      return "<u>";
+    case "strike":
+      return "<s>";
+    case "code":
+      return "<code>";
+    case "pre":
+      return e.language ? `<pre><code class="language-${escapeAttribute(e.language)}">` : "<pre>";
+    case "link":
+      return `<a href="${escapeAttribute(e.url ?? "")}">`;
+  }
+}
+
+function closeTag(e: TextEntity): string {
+  const name = {
+    bold: "b",
+    italic: "i",
+    underline: "u",
+    strike: "s",
+    code: "code",
+    pre: "pre",
+    link: "a",
+  }[e.type];
+  return e.type === "pre" && e.language ? "</code></pre>" : `</${name}>`;
+}
+
+/** Сортировка «снаружи внутрь»: раньше начало, при равном — длиннее; при полном совпадении — порядок разбора. */
+function ordered(entities: TextEntity[]): TextEntity[] {
+  return entities
+    .map((e, index) => ({ e, index }))
+    .sort((a, b) => a.e.offset - b.e.offset || b.e.length - a.e.length || a.index - b.index)
+    .map(({ e }) => e);
+}
+
+/**
+ * Подмножество HTML, которое понимают и Telegram, и MAX. `lineBreaks: "br"` — для письма, где перевод
+ * строки без тега схлопнется в пробел; внутри `pre` переводы остаются как есть.
+ */
+export function toHtml(
+  formatted: FormattedText,
+  options: { lineBreaks?: "newline" | "br" } = {},
+): string {
+  const { text } = formatted;
+  const stack: TextEntity[] = [];
+  // Выделения собраны потребителем, а не только нашими разборщиками: небезопасная ссылка выводится текстом.
+  const pending = ordered(formatted.entities.filter((e) => e.type !== "link" || isSafeUrl(e.url)));
+  let html = "";
+  let pos = 0;
+
+  const emit = (until: number) => {
+    const chunk = escapeHtml(text.slice(pos, until));
+    const inPre = stack.some((e) => e.type === "pre");
+    html += options.lineBreaks === "br" && !inPre ? chunk.replace(/\n/g, "<br>\n") : chunk;
+    pos = until;
+  };
+
+  while (pos < text.length || stack.length > 0 || pending.length > 0) {
+    const top = stack.at(-1);
+    const nextOpen = pending[0];
+    const topEnd = top ? top.offset + top.length : Number.POSITIVE_INFINITY;
+    if (top && (!nextOpen || topEnd <= nextOpen.offset)) {
+      emit(topEnd);
+      html += closeTag(stack.pop()!);
+      continue;
+    }
+    if (nextOpen) {
+      emit(nextOpen.offset);
+      // Пересечение без вложенности в Telegram возможно; в HTML нет — обрезаем по внешнему.
+      const clipped = top
+        ? { ...nextOpen, length: Math.min(nextOpen.length, topEnd - nextOpen.offset) }
+        : nextOpen;
+      html += openTag(clipped);
+      stack.push(clipped);
+      pending.shift();
+      continue;
+    }
+    emit(text.length);
+  }
+  return html;
+}
+
+/**
+ * Простой текст: выделения снимаются, ссылка раскрывается в `текст: адрес` — в письме и на hh по ней
+ * кликают глазами. Ссылка, чей текст и есть адрес, не удваивается.
+ */
+export function toPlainText(formatted: FormattedText): string {
+  const links = formatted.entities
+    .filter((e) => e.type === "link" && e.url)
+    .sort((a, b) => b.offset - a.offset);
+  let text = formatted.text;
+  for (const link of links) {
+    const end = link.offset + link.length;
+    const label = text.slice(link.offset, end);
+    if (label.trim() === link.url || `${label.trim()}/` === link.url) continue;
+    text = `${text.slice(0, end)}: ${link.url}${text.slice(end)}`;
+  }
+  return text;
+}

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { TextFormat } from "./markup";
+
 export type UsernameRecipient = {
   type: "username";
   username: string;
@@ -82,6 +84,13 @@ export type OutboundMessage = {
   threadId?: number;
   documents?: OutboundDocument[];
   buttons?: OutboundButton[][];
+  /**
+   * Как написан `text`: транспорт сам переводит разметку в формат своего канала — Telegram и MAX
+   * получают выделения, почта HTML и простой текст, hh простой текст. Не задан — прежнее поведение
+   * через `parseMode`.
+   */
+  format?: TextFormat;
+  /** @deprecated Режим разбора Telegram, уходит в канал как есть. Вместо него — `format`; заданы оба — действует `format`. */
   parseMode?: "HTML" | "Markdown" | "MarkdownV2";
   metadata?: Readonly<Record<string, unknown>>;
 };
@@ -106,6 +115,13 @@ export type EditableMessage = {
   messageId: string;
   text: string;
   buttons?: OutboundButton[][];
+  /**
+   * Как написан `text`: транспорт сам переводит разметку в формат своего канала — Telegram и MAX
+   * получают выделения, почта HTML и простой текст, hh простой текст. Не задан — прежнее поведение
+   * через `parseMode`.
+   */
+  format?: TextFormat;
+  /** @deprecated Режим разбора Telegram, уходит в канал как есть. Вместо него — `format`; заданы оба — действует `format`. */
   parseMode?: "HTML" | "Markdown" | "MarkdownV2";
 };