@imessaging/core 0.3.0 → 0.5.0

package/package.json

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

package/src/index.ts

@@ -1,6 +1,15 @@
 export { MemoryPeerStore } from "./memory-peer-store";
 export { createPeerKey } from "./peer-key";
-export { canEdit, isTelegramRecipient } from "./types";
+export { canEdit, canReceive, canShowTyping, hasCommandMenu, isTelegramRecipient } from "./types";
+export type { ButtonPress, ButtonPressTransport } from "./types";
+export type {
+  ChannelCommand,
+  CommandMenuTransport,
+  IncomingAttachment,
+  IncomingMessage,
+  IncomingMessageTransport,
+  TypingTransport,
+} from "./types";
 export type {
   EditableMessage,
   EditableMessageTransport,

package/src/types.ts

@@ -142,3 +142,120 @@ export interface TelegramPeerStore {
   ): Promise<void>;
   delete(accountId: string, recipient: MessageRecipient): Promise<void>;
 }
+
+/**
+ * Нажатие на кнопку под сообщением.
+ *
+ * `data` — то, что положили в `OutboundButton.callbackData`. Транспорт не пытается его понимать:
+ * смысл строки принадлежит продукту, а не каналу связи.
+ */
+export type ButtonPress = {
+  /** Кто нажал. `null` — отправитель неизвестен каналу. */
+  senderId: number | null;
+  data: string;
+  /**
+   * Подтвердить нажатие, показав человеку текст.
+   *
+   * Вызывать ОБЯЗАТЕЛЬНО: Telegram крутит на кнопке часы, пока не получит ответ, и человек видит
+   * зависшую кнопку даже при успешно выполненном действии.
+   */
+  answer(text: string): Promise<void>;
+};
+
+/**
+ * Канал, умеющий не только слать, но и ПРИНИМАТЬ нажатия.
+ *
+ * Отдельно от `MessageTransport`, потому что умеют не все: почта кнопок не имеет вовсе, а
+ * реализация, которая только шлёт, не должна объяснять, почему у неё пустой приём.
+ */
+export interface ButtonPressTransport {
+  /** Подписаться на нажатия. Возврат — функция отписки. */
+  onButtonPress(handler: (press: ButtonPress) => void | Promise<void>): () => void;
+}
+
+/**
+ * Вложение входящего сообщения.
+ *
+ * Только описание: байты достаёт транспорт (`download`), потому что адрес файла у каждого канала
+ * свой и живёт он вместе с учёткой, а не с сообщением.
+ */
+export type IncomingAttachment = {
+  /** Идентификатор файла В КАНАЛЕ. Смысла вне своего транспорта не имеет. */
+  id: string;
+  filename: string;
+  mimeType?: string;
+  sizeBytes?: number;
+};
+
+/**
+ * Входящее сообщение — общий вид для всех каналов.
+ *
+ * `transportId` и `accountId` входят В САМО сообщение, а не подставляются потребителем: один
+ * продукт слушает несколько учёток сразу, и `chatId` уникален только внутри пары «канал + учётка».
+ */
+export type IncomingMessage = {
+  transportId: string;
+  accountId: string;
+  chatId: string;
+  chatType: "user" | "group" | "channel";
+  /** Кто написал. `null` — канал отправителя не называет (рассылка, служебное событие). */
+  senderId: string | null;
+  senderUsername?: string;
+  messageId: string;
+  text: string;
+  attachments: IncomingAttachment[];
+  replyToMessageId?: string;
+  threadId?: number;
+};
+
+/**
+ * Канал, умеющий ПРИНИМАТЬ сообщения.
+ *
+ * Отдельно от `MessageTransport` по той же причине, что и `ButtonPressTransport`: принимать умеет
+ * не всякий канал — почте это несвойственно вовсе, — и обещать приём всем транспортам значит
+ * заставить половину из них объяснять пустоту.
+ */
+export interface IncomingMessageTransport extends MessageTransport {
+  /** Подписаться на входящие. Возврат — функция отписки. */
+  onMessage(handler: (message: IncomingMessage) => void | Promise<void>): () => void;
+  /** Байты вложения. Отдельным вызовом: скачивать всё подряд дороже, чем разобрать текст. */
+  download(attachment: IncomingAttachment): Promise<Uint8Array>;
+}
+
+export function canReceive(transport: MessageTransport): transport is IncomingMessageTransport {
+  return typeof (transport as IncomingMessageTransport).onMessage === "function";
+}
+
+/** Пункт меню команд канала: `/menu` и подпись рядом с ним. */
+export type ChannelCommand = {
+  /** Без ведущей косой черты. */
+  command: string;
+  description: string;
+};
+
+/**
+ * Канал с меню команд.
+ *
+ * Нужен ровно затем, чтобы продукт не звал Bot API мимо транспорта: меню — свойство канала, а не
+ * сообщения, и без него единственным способом убрать постоянную клавиатуру был бы прямой вызов.
+ */
+export interface CommandMenuTransport extends MessageTransport {
+  setCommands(commands: ChannelCommand[]): Promise<void>;
+}
+
+export function hasCommandMenu(transport: MessageTransport): transport is CommandMenuTransport {
+  return typeof (transport as CommandMenuTransport).setCommands === "function";
+}
+
+/**
+ * Канал, умеющий показать «печатает…».
+ *
+ * Не украшение: ход агента занимает секунды, и без признака работы человек пишет второй раз.
+ */
+export interface TypingTransport extends MessageTransport {
+  typing(recipient: MessageRecipient): Promise<void>;
+}
+
+export function canShowTyping(transport: MessageTransport): transport is TypingTransport {
+  return typeof (transport as TypingTransport).typing === "function";
+}