@imessaging/telegram-mtproto 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imessaging/telegram-mtproto",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Telegram MTProto user-account transport for imessaging",
   "keywords": [
     "messaging",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@imessaging/core": "0.5.0",
+    "@imessaging/core": "0.6.0",
     "big-integer": "^1.6.52"
   },
   "peerDependencies": {

package/src/incoming.ts

@@ -0,0 +1,199 @@
+import type { IncomingAttachment, IncomingMessage } from "@imessaging/core";
+
+/** Пир MTProto в той части, по которой определяется чат. Приходит из `Api.TypePeer`. */
+export type MtprotoPeerLike = {
+  className?: string;
+  userId?: { toString(): string };
+  chatId?: { toString(): string };
+  channelId?: { toString(): string };
+};
+
+/** Сообщение MTProto в той части, которая переносится в общий вид. */
+export type MtprotoMessageLike = {
+  id: number | string;
+  message?: string;
+  /** `true` — сообщение отправлено САМОЙ учётной записью. */
+  out?: boolean;
+  peerId?: MtprotoPeerLike;
+  fromId?: MtprotoPeerLike;
+  media?: MtprotoMediaLike;
+  replyTo?: { replyToMsgId?: number | string };
+  /**
+   * Отправитель целиком — его приносит обновление вместе с `accessHash`.
+   *
+   * Нужен не ради имени: по одному номеру ответить нельзя, пока собеседник клиенту неизвестен, а
+   * `accessHash` живёт только здесь. Поле необязательное: в обновлении его может не быть.
+   */
+  sender?: { username?: string; accessHash?: { toString(): string } | string | number };
+};
+
+export type MtprotoMediaLike = {
+  className?: string;
+  document?: {
+    mimeType?: string;
+    size?: { toString(): string } | number;
+    attributes?: { className?: string; fileName?: string }[];
+  };
+  photo?: unknown;
+};
+
+/**
+ * Пир → пара «чат и его вид».
+ *
+ * `chatId` берётся из пира, а НЕ из отправителя: в группе они разные, и перепутав их, ответ уехал
+ * бы в личку тому, кто написал в общий чат.
+ */
+export function peerToChat(peer: MtprotoPeerLike | undefined): {
+  chatId: string;
+  chatType: IncomingMessage["chatType"];
+} {
+  if (peer?.channelId !== undefined)
+    return { chatId: peer.channelId.toString(), chatType: "channel" };
+  if (peer?.chatId !== undefined) return { chatId: peer.chatId.toString(), chatType: "group" };
+  if (peer?.userId !== undefined) return { chatId: peer.userId.toString(), chatType: "user" };
+  throw new Error("MTProto peer without userId, chatId or channelId");
+}
+
+/**
+ * Что приехало файлом.
+ *
+ * Имя ищется среди атрибутов документа: у MTProto оно не поле, а один из атрибутов, и его может не
+ * быть вовсе. Разбор форматов ведётся по имени, поэтому подставляется своё.
+ *
+ * Идентификатор вложения — пара «чат и сообщение», а не идентификатор файла: у MTProto скачивание
+ * идёт от СООБЩЕНИЯ, и file_id, как в Bot API, здесь просто не существует.
+ */
+export function collectAttachments(
+  message: MtprotoMessageLike,
+  chatId: string,
+): IncomingAttachment[] {
+  const media = message.media;
+  if (!media) return [];
+  const id = `${chatId}:${message.id}`;
+
+  if (media.document) {
+    const named = media.document.attributes?.find(
+      (attribute) => attribute.className === "DocumentAttributeFilename",
+    );
+    const size = media.document.size;
+    return [
+      {
+        id,
+        filename: named?.fileName ?? "document",
+        mimeType: media.document.mimeType,
+        sizeBytes: size === undefined ? undefined : Number(size.toString()),
+      },
+    ];
+  }
+  if (media.photo) {
+    return [{ id, filename: "photo.jpg", mimeType: "image/jpeg" }];
+  }
+  return [];
+}
+
+/**
+ * Сообщение живой учётной записи → общий вид.
+ *
+ * Вынесено отдельной функцией по той же причине, что и у бота: это ЕДИНСТВЕННОЕ место, где теряются
+ * поля, и потеря не падает — она видна только тем, что агент не знает, на что ему отвечают.
+ */
+export function toIncomingMessage(
+  message: MtprotoMessageLike,
+  transportId: string,
+  accountId: string,
+): IncomingMessage {
+  const { chatId, chatType } = peerToChat(message.peerId);
+  // Отправителя в личке MTProto не называет: `fromId` заполняется в группах, а в диалоге один на
+  // один он и есть собеседник, то есть сам чат.
+  const senderId = message.fromId
+    ? peerToChat(message.fromId).chatId
+    : chatType === "user"
+      ? chatId
+      : null;
+
+  return {
+    transportId,
+    accountId,
+    chatId,
+    chatType,
+    senderId,
+    // Имя отправителя: по нему отвечают, когда номер клиенту неизвестен, и по нему же продукты
+    // связывают человека со своей учётной записью.
+    senderUsername: message.sender?.username,
+    messageId: String(message.id),
+    text: message.message ?? "",
+    attachments: collectAttachments(message, chatId),
+    replyToMessageId:
+      message.replyTo?.replyToMsgId === undefined
+        ? undefined
+        : String(message.replyTo.replyToMsgId),
+  };
+}
+
+/**
+ * Набор подписчиков на входящие и раздача им сообщения.
+ *
+ * Отдельным классом, а не полем транспорта, потому что это единственная часть приёма, которую можно
+ * проверить без сети: правило «своё сообщение не отдаём» живёт здесь, и оно важнее остального —
+ * живая учётная запись видит и то, что отправила сама, и без него шлюз отвечает на свой же ответ.
+ */
+export class IncomingDispatcher {
+  private readonly handlers = new Set<(message: IncomingMessage) => void | Promise<void>>();
+
+  add(handler: (message: IncomingMessage) => void | Promise<void>): () => void {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+
+  get size(): number {
+    return this.handlers.size;
+  }
+
+  /** Раздаёт входящее подписчикам. Своё исходящее не раздаётся никому. */
+  async dispatch(
+    message: MtprotoMessageLike,
+    transportId: string,
+    accountId: string,
+  ): Promise<boolean> {
+    if (message.out === true) return false;
+    if (this.handlers.size === 0) return false;
+    const incoming = toIncomingMessage(message, transportId, accountId);
+    for (const handler of this.handlers) await handler(incoming);
+    return true;
+  }
+}
+
+/** Клиент MTProto в той части, которой достаточно для скачивания. Объявлен ради двойника в тесте. */
+export type DownloadingClient = {
+  getMessages(peer: string, params: { ids: number[] }): Promise<{ media?: unknown }[]>;
+  downloadMedia(message: unknown): Promise<Buffer | Uint8Array | undefined>;
+};
+
+/**
+ * Скачивание вложения по паре «чат и сообщение».
+ *
+ * Сообщение перезапрашивается, а не хранится: держать его до скачивания значило бы держать в
+ * памяти каждое входящее с файлом на случай, что файл однажды спросят.
+ */
+export async function downloadFromMessage(
+  client: DownloadingClient,
+  attachment: { id: string },
+): Promise<Uint8Array> {
+  const separator = attachment.id.lastIndexOf(":");
+  if (separator <= 0) {
+    throw new Error(`Attachment id ${attachment.id} is not a "<chat>:<message>" pair`);
+  }
+  const chatId = attachment.id.slice(0, separator);
+  const messageId = Number(attachment.id.slice(separator + 1));
+  if (!Number.isInteger(messageId)) {
+    throw new Error(`Attachment id ${attachment.id} carries a non-numeric message id`);
+  }
+
+  const [message] = await client.getMessages(chatId, { ids: [messageId] });
+  if (!message) throw new Error(`Message ${attachment.id} is gone`);
+  const bytes = await client.downloadMedia(message);
+  if (!bytes) throw new Error(`Message ${attachment.id} carries no downloadable media`);
+  return new Uint8Array(bytes);
+}

package/src/index.ts

@@ -2,3 +2,14 @@ export {
   TelegramMtprotoTransport,
   type TelegramMtprotoTransportOptions,
 } from "./telegram-mtproto-transport";
+export {
+  collectAttachments,
+  downloadFromMessage,
+  IncomingDispatcher,
+  peerToChat,
+  toIncomingMessage,
+  type DownloadingClient,
+  type MtprotoMediaLike,
+  type MtprotoMessageLike,
+  type MtprotoPeerLike,
+} from "./incoming";

package/src/telegram-mtproto-transport.ts

@@ -1,6 +1,10 @@
 import type {
   ButtonPress,
   ButtonPressTransport,
+  IncomingAttachment,
+  IncomingMessage,
+  IncomingMessageTransport,
+  ReadReceiptTransport,
   EditableMessage,
   EditableMessageTransport,
   EditResult,
@@ -10,15 +14,25 @@ import type {
   SendResult,
   TelegramPeerStore,
   TransportStatus,
+  TypingTransport,
 } from "@imessaging/core";
 import { isTelegramRecipient, MemoryPeerStore } from "@imessaging/core";
+import { peerToChat } from "./incoming";
 import bigInt from "big-integer";
 import { Api, TelegramClient } from "telegram";
 import { CustomFile } from "telegram/client/uploads";
 import { CallbackQuery } from "telegram/events/CallbackQuery";
+import { NewMessage } from "telegram/events/NewMessage";
 import type { TelegramClientParams } from "telegram/client/telegramBaseClient";
 import { StringSession } from "telegram/sessions";
 
+import {
+  downloadFromMessage,
+  IncomingDispatcher,
+  type DownloadingClient,
+  type MtprotoMessageLike,
+} from "./incoming";
+
 export type TelegramMtprotoTransportOptions = {
   accountId: string;
   apiId: number;
@@ -57,12 +71,21 @@ function isChannel(chat: Api.TypeChat): chat is Api.Channel {
   return chat.className === "Channel";
 }
 
-export class TelegramMtprotoTransport implements EditableMessageTransport, ButtonPressTransport {
+export class TelegramMtprotoTransport
+  implements
+    EditableMessageTransport,
+    ButtonPressTransport,
+    IncomingMessageTransport,
+    ReadReceiptTransport,
+    TypingTransport
+{
   readonly id: string;
   private readonly client: TelegramClient;
   private readonly peerStore: TelegramPeerStore;
   private connected = false;
   private lastActivityAt?: Date;
+  private readonly incoming = new IncomingDispatcher();
+  private incomingListener: ((event: unknown) => void) | null = null;
 
   constructor(private readonly options: TelegramMtprotoTransportOptions) {
     if (!options.accountId.trim()) throw new Error("accountId must not be empty");
@@ -106,11 +129,13 @@ export class TelegramMtprotoTransport implements EditableMessageTransport, Butto
     const listener = (event: unknown): void => {
       const query = event as {
         data?: Buffer | Uint8Array;
+        chatId?: { toString?: () => string };
         senderId?: { toJSNumber?: () => number };
         answer?: (options: { message: string; alert: boolean }) => Promise<unknown>;
       };
       const press: ButtonPress = {
         senderId: query.senderId?.toJSNumber?.() ?? null,
+        chatId: query.chatId?.toString?.(),
         data: query.data === undefined ? "" : Buffer.from(query.data).toString("utf8"),
         answer: async (text: string) => {
           await query.answer?.({ message: text, alert: true });
@@ -122,6 +147,100 @@ export class TelegramMtprotoTransport implements EditableMessageTransport, Butto
     return () => this.client.removeEventHandler(listener, new CallbackQuery({}));
   }
 
+  /**
+   * Подписка на входящие.
+   *
+   * Опрос ЗАПУСКАЕТСЯ ПОДПИСКОЙ, а не соединением — то же правило, что у бота: учётная запись,
+   * которая только шлёт, не должна забирать себе обновления.
+   */
+  onMessage(handler: (message: IncomingMessage) => void | Promise<void>): () => void {
+    const remove = this.incoming.add(handler);
+    this.startListeningIfNeeded();
+    return () => {
+      remove();
+      this.stopListeningIfIdle();
+    };
+  }
+
+  private startListeningIfNeeded(): void {
+    if (this.incomingListener !== null || this.incoming.size === 0) return;
+    const listener = (event: unknown): void => {
+      const message = (event as { message?: MtprotoMessageLike }).message;
+      if (!message) return;
+      this.lastActivityAt = new Date();
+      // Собеседника запоминаем СРАЗУ: ответить ему по одному номеру нельзя, `accessHash` приносит
+      // только это обновление, и к следующему ходу его уже негде взять.
+      void this.rememberSender(message);
+      void this.incoming.dispatch(message, this.id, this.options.accountId);
+    };
+    this.incomingListener = listener;
+    this.client.addEventHandler(listener, new NewMessage({}));
+  }
+
+  /**
+   * Запомнить написавшего нам человека.
+   *
+   * Отказ здесь ничего не ломает и не сообщается: приём сообщения важнее, чем возможность
+   * ответить по номеру, а без записи остаётся ответ по имени.
+   */
+  private async rememberSender(message: MtprotoMessageLike): Promise<void> {
+    try {
+      const hash = message.sender?.accessHash;
+      if (hash === undefined || hash === null) return;
+      const { chatId, chatType } = peerToChat(message.peerId);
+      // В группе отправитель и чат — разные пиры, и запись сложила бы одно вместо другого.
+      if (chatType !== "user") return;
+      const recipient = { type: "user", id: chatId } as const;
+      await this.peerStore.set(
+        this.options.accountId,
+        recipient,
+        {
+          type: "user",
+          id: chatId,
+          accessHash: String(hash),
+          username: message.sender?.username,
+          resolvedAt: new Date().toISOString(),
+        },
+        this.options.peerTtlSeconds,
+      );
+    } catch {
+      // приём важнее записи
+    }
+  }
+
+  private stopListeningIfIdle(): void {
+    if (this.incoming.size > 0 || this.incomingListener === null) return;
+    this.client.removeEventHandler(this.incomingListener, new NewMessage({}));
+    this.incomingListener = null;
+  }
+
+  /**
+   * Байты вложения.
+   *
+   * Идентификатор — пара «чат и сообщение»: у MTProto скачивание идёт от СООБЩЕНИЯ, а `file_id`,
+   * как в Bot API, здесь не существует вовсе.
+   */
+  async download(attachment: IncomingAttachment): Promise<Uint8Array> {
+    return downloadFromMessage(this.client as unknown as DownloadingClient, attachment);
+  }
+
+  /** Отметить прочитанным. Иначе у собеседника горит непрочитанное, хотя мы уже отвечаем. */
+  async markRead(recipient: MessageRecipient, messageId: string): Promise<void> {
+    const peer = await this.getInputPeer(recipient);
+    await this.client.markAsRead(peer, Number(messageId));
+  }
+
+  /** «Печатает…». Ход агента занимает секунды, и без признака работы человек пишет второй раз. */
+  async typing(recipient: MessageRecipient): Promise<void> {
+    if (!isTelegramRecipient(recipient)) {
+      throw new Error("Telegram account cannot show typing to an email recipient");
+    }
+    const peer = await this.getInputPeer(recipient);
+    await this.client.invoke(
+      new Api.messages.SetTyping({ peer, action: new Api.SendMessageTypingAction() }),
+    );
+  }
+
   async disconnect(): Promise<void> {
     await this.client.disconnect();
     this.connected = false;
@@ -190,6 +309,12 @@ export class TelegramMtprotoTransport implements EditableMessageTransport, Butto
     const cached = await this.peerStore.get(this.options.accountId, recipient);
     if (cached) return this.toInputPeer(cached);
 
+    // Собеседник, который НАМ НАПИСАЛ, уже известен: обновление принесло его вместе с access hash,
+    // и клиент держит его у себя. Спрашиваем сначала клиента — иначе ответить на входящее нельзя
+    // без @username, а у человека его может не быть вовсе.
+    const known = await this.knownInputPeer(recipient);
+    if (known) return known;
+
     const resolved = await this.resolvePeer(recipient);
     await this.peerStore.set(
       this.options.accountId,
@@ -200,6 +325,21 @@ export class TelegramMtprotoTransport implements EditableMessageTransport, Butto
     return this.toInputPeer(resolved);
   }
 
+  /**
+   * Собеседник, уже известный клиенту.
+   *
+   * `null` — не известен, и тогда остаётся разрешение по имени. Отказ здесь НЕ ошибка: он значит
+   * «мы этому человеку ещё не писали и он нам тоже», а не поломку.
+   */
+  private async knownInputPeer(recipient: MessageRecipient): Promise<Api.TypeInputPeer | null> {
+    if (recipient.type === "email" || recipient.type === "username") return null;
+    try {
+      return await this.client.getInputEntity(bigInt(recipient.id));
+    } catch {
+      return null;
+    }
+  }
+
   private async resolvePeer(recipient: MessageRecipient): Promise<ResolvedPeer> {
     // Почтовый получатель сюда доходить не должен: разрешать адрес как @username бессмысленно, а
     // сообщение об отказе тогда врало бы про Telegram.