max2tg 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# max2tg
+
+Конвертер событий (updates) мессенджера **MAX** в события **Telegram Bot API**.
+
+---
+
+## Установка
+
+```bash
+npm install max2tg
+```
+
+---
+
+## Быстрый старт
+
+```js
+const { convertMaxToTelegram, convertBatch } = require('max2tg');
+
+// Одно событие → массив Telegram updates
+const updates = convertMaxToTelegram(maxUpdate);
+
+// Массив событий → плоский массив Telegram updates
+const updates = convertBatch(maxUpdates);
+```
+
+### Пример в webhook-обработчике
+
+```js
+const express = require('express');
+const { convertMaxToTelegram } = require('max2tg');
+
+const app = express();
+app.use(express.json());
+
+// Webhook от MAX
+app.post('/webhook/max', (req, res) => {
+  const tgUpdates = convertMaxToTelegram(req.body);
+
+  for (const update of tgUpdates) {
+    handleTelegramUpdate(update); // ваш общий обработчик
+  }
+
+  res.sendStatus(200);
+});
+
+// Webhook от Telegram
+app.post('/webhook/telegram', (req, res) => {
+  handleTelegramUpdate(req.body);
+  res.sendStatus(200);
+});
+```
+
+---
+
+## Поддерживаемые типы событий
+
+### `bot_started` → `message` с командой `/start`
+Активация бота пользователем, в том числе с `start payload`.
+
+### `message_created` → `message`
+Поддержка всех видов вложений, включая геопозицию, документы, стикеры и альбомы. 
+Ответы на сообщение, пересланные сообщения, сообщения с клавиатурой и форматированием.
+
+### `message_callback` → `callback_query`
+Нажатие пользователя на инлайн-кнопку.
+
+---
+
+## Ограничения
+
+Поле file_id всегда равен null, на замену приходит _max_url и _max_token.
+
+---
+
+## Лицензия
+
+MIT

package/index.js

@@ -0,0 +1,547 @@
+/**
+ * Конвертер событий (updates) из формата MAX в формат Telegram Bot API.
+ *
+ * Поддерживаемые типы событий MAX:
+ *   - bot_started          → /start (message с командой)
+ *   - message_created      → message (text / sticker / document / location /
+ *                            forwarded photo / forwarded album)
+ *   - message_callback     → callback_query
+ ** /
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+/** Переводит миллисекундный Unix-timestamp в секундный (Telegram). */
+const toSec = (ms) => Math.floor(ms / 1000);
+
+/** update_id генерируем из timestamp (секунды). Принимает ms или sec. */
+const toUpdateId = (ts) => ts > 1e12 ? Math.floor(ts / 1000) : ts;
+
+/**
+ * Собирает минимальный объект Chat из данных MAX.
+ * MAX хранит chat_id и user_id в recipient; для личных диалогов
+ * Telegram использует тот же id что и у пользователя.
+ */
+function buildChat(maxUser) {
+  return {
+    id: maxUser.user_id,          // в диалоге chat.id = user.id
+    type: "private",
+    first_name: maxUser.first_name,
+    last_name: maxUser.last_name ?? undefined,
+    username: maxUser.username ?? undefined,
+  };
+}
+
+/**
+ * Собирает объект From/User из данных MAX.
+ */
+function buildFrom(maxUser) {
+  return {
+    id: maxUser.user_id,
+    is_bot: maxUser.is_bot ?? false,
+    first_name: maxUser.first_name,
+    last_name: maxUser.last_name ?? undefined,
+    username: maxUser.username ?? undefined,
+    language_code: undefined,     // MAX не передаёт language_code
+  };
+}
+
+// ─── markup (MAX) → entities (Telegram) ─────────────────────────────────────
+
+const MAX_MARKUP_TO_TG_ENTITY = {
+  strong: "bold",
+  em: "italic",
+  pre: "pre",
+  code: "code",
+  link: "url",
+  strikethrough: "strikethrough",
+  underline: "underline",
+};
+
+/**
+ * Конвертирует MAX markup-массив в массив Telegram MessageEntity.
+ * Дубликаты (MAX иногда присылает одну и ту же метку дважды) убираются.
+ */
+function convertMarkup(markup = []) {
+  const seen = new Set();
+  const entities = [];
+
+  for (const m of markup) {
+    const type = MAX_MARKUP_TO_TG_ENTITY[m.type];
+    if (!type) continue;
+
+    const key = `${type}:${m.from}:${m.length}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    entities.push({ type, offset: m.from, length: m.length });
+  }
+
+  return entities.length ? entities : undefined;
+}
+
+// ─── inline_keyboard (MAX) → reply_markup (Telegram) ────────────────────────
+
+/**
+ * MAX button → Telegram InlineKeyboardButton
+ *
+ * Типы MAX: link | callback | (возможно request_geo, request_contact и др.)
+ */
+function convertButton(maxBtn) {
+  const tgBtn = { text: maxBtn.text };
+
+  if (maxBtn.type === "link" || maxBtn.url) {
+    tgBtn.url = maxBtn.url;
+  } else if (maxBtn.type === "callback") {
+    tgBtn.callback_data = maxBtn.payload ?? "";
+  }
+
+  return tgBtn;
+}
+
+function convertInlineKeyboard(attachment) {
+  if (!attachment || attachment.type !== "inline_keyboard") return undefined;
+  const rows = attachment.payload?.buttons ?? [];
+  return {
+    inline_keyboard: rows.map((row) => row.map(convertButton)),
+  };
+}
+
+// ─── attachments ─────────────────────────────────────────────────────────────
+
+/**
+ * Извлекает первый inline_keyboard из массива вложений MAX.
+ */
+function extractKeyboard(attachments = []) {
+  return (
+    attachments.find((a) => a.type === "inline_keyboard") ?? null
+  );
+}
+
+/**
+ * Строит объект Telegram стикера из MAX-вложения типа sticker.
+ * В MAX нет file_id — передаём только то, что есть.
+ */
+function buildSticker(att) {
+  return {
+    // file_id недоступен из MAX — ставим заглушку; реальный file_id
+    // получить нельзя без загрузки файла через Telegram API.
+    file_id: null,
+    file_unique_id: null,
+    width: att.width ?? 512,
+    height: att.height ?? 512,
+    is_animated: false,
+    is_video: false,
+    type: "regular",
+    thumbnail: att.payload?.url
+      ? {
+          file_id: null,
+          file_unique_id: null,
+          width: att.width ?? 128,
+          height: att.height ?? 128,
+        }
+      : undefined,
+    // Нативный URL стикера (MAX-специфично, не часть TG API)
+    _max_url: att.payload?.url,
+  };
+}
+
+/**
+ * Строит объект Telegram Document из MAX-вложения типа file.
+ */
+function buildDocument(att) {
+  return {
+    file_id: null,            // недоступен без Telegram
+    file_unique_id: null,
+    file_name: att.filename ?? undefined,
+    file_size: att.size ?? undefined,
+    // Прямая ссылка из MAX (временная, требует токена)
+    _max_url: att.payload?.url,
+    _max_token: att.payload?.token,
+  };
+}
+
+/**
+ * Строит массив PhotoSize (один размер) из MAX-вложения типа image.
+ */
+function buildPhoto(att) {
+  return [
+    {
+      file_id: null,
+      file_unique_id: null,
+      width: 0,
+      height: 0,
+      _max_url: att.payload?.url,
+      _max_token: att.payload?.token,
+    },
+  ];
+}
+
+/**
+ * Строит Telegram Location из MAX-вложения типа location.
+ */
+function buildLocation(att) {
+  return {
+    latitude: att.latitude,
+    longitude: att.longitude,
+  };
+}
+
+// ─── forward origin ──────────────────────────────────────────────────────────
+
+/**
+ * Строит forward_origin из MAX link.type === 'forward'.
+ * MAX хранит sender пересланного сообщения; если это бот/канал — channel,
+ * иначе — user.
+ */
+function buildForwardOrigin(maxLink, dateMs) {
+  if (!maxLink || maxLink.type !== "forward") return {};
+
+  const date = toSec(dateMs);
+  const sender = maxLink.sender ?? {};
+
+  if (sender.is_bot || !sender.user_id) {
+    // Предполагаем канал / публичный источник
+    return {
+      forward_origin: {
+        type: "channel",
+        date,
+        chat: {
+          id: maxLink.chat_id || 0,
+          type: "channel",
+          title: sender.first_name ?? "Unknown",
+          username: sender.username ?? undefined,
+        },
+        message_id: 0,
+      },
+    };
+  }
+
+  return {
+    forward_origin: {
+      type: "user",
+      date,
+      sender_user: buildFrom(sender),
+    },
+  };
+}
+
+// ─── reply_to_message ────────────────────────────────────────────────────────
+
+/**
+ * Строит упрощённый reply_to_message из MAX link.type === 'reply'.
+ */
+function buildReplyTo(maxLink, chat) {
+  if (!maxLink || maxLink.type !== "reply") return {};
+
+  const sender = maxLink.sender ?? {};
+  return {
+    reply_to_message: {
+      message_id: maxLink.message?.mid ?? null,
+      chat,
+      from: buildFrom(sender),
+      date: 0,
+      text: maxLink.message?.text ?? "",
+    },
+  };
+}
+
+// ─── конвертеры по update_type ───────────────────────────────────────────────
+
+/**
+ * bot_started → Telegram update с /start
+ */
+function convertBotStarted(maxUpdate) {
+  const user = maxUpdate.user;
+  const chat = buildChat(user);
+  const from = buildFrom(user);
+  const date = toSec(maxUpdate.timestamp);
+
+  const startText = maxUpdate.payload
+    ? `/start ${maxUpdate.payload}`
+    : "/start";
+
+  const entities = [{ type: "bot_command", offset: 0, length: 6 }];
+
+  return {
+    update_id: toUpdateId(maxUpdate.timestamp),
+    message: {
+      message_id: String(toSec(maxUpdate.timestamp)), // bot_started не имеет mid — используем timestamp
+      from,
+      chat,
+      date,
+      text: startText,
+      entities,
+    },
+  };
+}
+
+/**
+ * message_created → Telegram update (message / стикер / документ /
+ *                   геопозиция / forward / album-item)
+ *
+ * Возвращает МАССИВ updates — один или несколько (для альбомов).
+ */
+function convertMessageCreated(maxUpdate) {
+  const msg = maxUpdate.message;
+  const body = msg.body;
+  const sender = msg.sender;
+  const ts = toSec(msg.timestamp);
+  const chat = buildChat(sender);
+  const from = buildFrom(sender);
+  const link = msg.link ?? null;
+
+  // Базовая обёртка Telegram message
+  const mid = body.mid ?? null;
+  const base = {
+    message_id: mid,          // MAX mid передаётся как строка
+    from,
+    chat,
+    date: ts,
+  };
+
+  // Forward/reply мета
+  const forwardMeta = buildForwardOrigin(link, msg.timestamp);
+  const replyMeta = buildReplyTo(link, chat);
+
+  const attachments = body.attachments ?? [];
+
+  // ── Стикер ──────────────────────────────────────────────────────────────
+  const stickerAtt = attachments.find((a) => a.type === "sticker");
+  if (stickerAtt) {
+    return [
+      {
+        update_id: toUpdateId(msg.timestamp),
+        message: { ...base, sticker: buildSticker(stickerAtt) },
+      },
+    ];
+  }
+
+  // ── Геопозиция ───────────────────────────────────────────────────────────
+  const locationAtt = attachments.find((a) => a.type === "location");
+  if (locationAtt) {
+    return [
+      {
+        update_id: toUpdateId(msg.timestamp),
+        message: { ...base, location: buildLocation(locationAtt) },
+      },
+    ];
+  }
+
+  // ── Файл / документ ──────────────────────────────────────────────────────
+  const fileAtt = attachments.find((a) => a.type === "file");
+  if (fileAtt) {
+    return [
+      {
+        update_id: toUpdateId(msg.timestamp),
+        message: {
+          ...base,
+          document: buildDocument(fileAtt),
+          caption: body.text || undefined,
+        },
+      },
+    ];
+  }
+
+  // ── Видео ─────────────────────────────────────────────────────────────────
+  const videoAtt = attachments.find((a) => a.type === "video");
+
+  // ── Изображения ──────────────────────────────────────────────────────────
+  const imageAtts = attachments.filter((a) => a.type === "image");
+
+  // ── Альбом (видео + изображения или несколько изображений) ───────────────
+  // MAX присылает всё одним событием; Telegram шлёт каждый элемент отдельно
+  // с общим media_group_id. Генерируем несколько updates.
+  const mediaItems = [
+    ...(videoAtt ? [{ type: "video", att: videoAtt }] : []),
+    ...imageAtts.map((att) => ({ type: "image", att })),
+  ];
+
+  if (mediaItems.length > 1) {
+    const mediaGroupId = String(Date.now()); // псевдо media_group_id
+    const caption = body.text || undefined;
+    const captionEntities = convertMarkup(body.markup);
+
+    return mediaItems.map((item, idx) => {
+      const isFirst = idx === 0;
+      const tgMsg = {
+        ...base,
+        ...forwardMeta,
+        media_group_id: mediaGroupId,
+      };
+
+      if (item.type === "video") {
+        tgMsg.video = {
+          file_id: null,
+          file_unique_id: null,
+          width: 0,
+          height: 0,
+          duration: item.att.duration ?? 0,
+          _max_url: item.att.payload?.url,
+        };
+      } else {
+        tgMsg.photo = buildPhoto(item.att);
+      }
+
+      // Caption только к первому элементу (как в Telegram)
+      if (isFirst && caption) {
+        tgMsg.caption = caption;
+        if (captionEntities) tgMsg.caption_entities = captionEntities;
+      }
+
+      return { update_id: toUpdateId(msg.timestamp) + idx, message: tgMsg };
+    });
+  }
+
+  // ── Одиночное изображение ─────────────────────────────────────────────────
+  if (mediaItems.length === 1) {
+    const item = mediaItems[0];
+    const tgMsg = { ...base, ...forwardMeta, ...replyMeta };
+
+    if (item.type === "video") {
+      tgMsg.video = {
+        file_id: null,
+        file_unique_id: null,
+        width: 0,
+        height: 0,
+        duration: item.att.duration ?? 0,
+        _max_url: item.att.payload?.url,
+      };
+    } else {
+      tgMsg.photo = buildPhoto(item.att);
+    }
+
+    const caption = body.text || undefined;
+    if (caption) {
+      tgMsg.caption = caption;
+      const ents = convertMarkup(body.markup);
+      if (ents) tgMsg.caption_entities = ents;
+    }
+
+    return [{ update_id: toUpdateId(msg.timestamp), message: tgMsg }];
+  }
+
+  // ── Inline keyboard в теле сообщения (бот → пользователь) ────────────────
+  const kbAtt = extractKeyboard(attachments);
+  const replyMarkup = convertInlineKeyboard(kbAtt);
+
+  // ── Обычный текст ─────────────────────────────────────────────────────────
+  const text = body.text ?? "";
+  const entities = convertMarkup(body.markup);
+
+  const tgMsg = {
+    ...base,
+    ...forwardMeta,
+    ...replyMeta,
+    text,
+  };
+  if (entities) tgMsg.entities = entities;
+  if (replyMarkup) tgMsg.reply_markup = replyMarkup;
+
+  return [{ update_id: toUpdateId(msg.timestamp), message: tgMsg }];
+}
+
+/**
+ * message_callback → Telegram callback_query
+ */
+function convertMessageCallback(maxUpdate) {
+  const cb = maxUpdate.callback;
+  const user = cb.user;
+  const from = buildFrom(user);
+  const chat = buildChat(user);
+
+  return {
+    update_id: toUpdateId(cb.timestamp),
+    callback_query: {
+      id: String(cb.timestamp),
+      from,
+      message: {
+        message_id: maxUpdate.message?.body?.mid ?? String(toSec(cb.timestamp)),
+        from: {
+          id: 0,
+          is_bot: true,
+          first_name: "Bot",
+        },
+        chat,
+        date: toSec(cb.timestamp),
+        text: maxUpdate.message?.body?.text ?? "",
+        reply_markup: (() => {
+          const kbAtt = extractKeyboard(maxUpdate.message?.body?.attachments ?? []);
+          return convertInlineKeyboard(kbAtt);
+        })(),
+      },
+      chat_instance: String(chat.id),
+      data: cb.payload ?? "",
+    },
+  };
+}
+
+// ─── главная функция ─────────────────────────────────────────────────────────
+
+/**
+ * Конвертирует одно MAX-событие в один или несколько Telegram-updates.
+ *
+ * @param {object} maxUpdate  — тело события из MAX (поле `max` в тестовом JSON)
+ * @returns {object[]}        — массив Telegram update-объектов
+ */
+function convertMaxToTelegram(maxUpdate) {
+  const type = maxUpdate.update_type;
+
+  switch (type) {
+    case "bot_started":
+      return [convertBotStarted(maxUpdate)];
+
+    case "message_created":
+      return convertMessageCreated(maxUpdate);
+
+    case "message_callback":
+      return [convertMessageCallback(maxUpdate)];
+
+    default:
+      console.warn(`[max-to-telegram] Неизвестный update_type: "${type}"`);
+      return [];
+  }
+}
+
+/**
+ * Удобная обёртка: принимает массив MAX-событий, возвращает плоский
+ * массив Telegram updates.
+ *
+ * @param {object[]} maxUpdates
+ * @returns {object[]}
+ */
+function convertBatch(maxUpdates) {
+  return maxUpdates.flatMap(convertMaxToTelegram);
+}
+
+module.exports = { convertMaxToTelegram, convertBatch };
+
+// ════════════════════════════════════════════════════════════════════════════
+// NOTES — Нюансы и ограничения
+// ════════════════════════════════════════════════════════════════════════════
+//
+// 1. file_id / file_unique_id поля выставляются в null.
+//    Добавляются (_max_url + _max_token)
+//
+// 2. message_id
+//    В MAX строка вида "mid.xxxxx" передаётся в поле message_id.
+//
+// 3. Альбомы (media group)
+//    MAX присылает весь альбом одним событием message_created с несколькими
+//    вложениями. Telegram рассылает каждый элемент отдельным update с единым
+//    media_group_id. convertMessageCreated возвращает массив — разошлите каждый
+//    элемент отдельно или обработайте весь массив как альбом.
+//
+// 4. callback_data
+//    MAX payload передаётся в callback_data без изменений. Если payload
+//    длиннее 64 байт — Telegram Bot API вернёт ошибку при отправке.
+//    Рекомендуется хранить длинные payload на стороне бэкенда и передавать
+//    лишь короткий ключ уже на уровне формирования кнопок в MAX.
+//
+// 5. Forward origin из приватных источников
+//    Если оригинал переслан из закрытого чата, MAX может не передать
+//    полные данные отправителя. forward_origin.chat.id будет 0.
+//
+// 6. update_id
+//     Генерируется из Unix-timestamp события (в секундах). При нескольких
+//     событиях в одну секунду возможны коллизии — для альбомов используется
+//     timestamp + порядковый индекс элемента.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "max2tg",
+  "version": "1.0.0",
+  "description": "MAX to Telegram event style converter",
+  "main": "index.js",
+  "keywords": [
+    "max",
+    "telegram",
+    "bot",
+    "converter",
+    "adapter"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/azizbots/max2tg.git"
+  }
+}