@imessaging/core 0.4.0 → 0.6.0

package/package.json

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

package/src/index.ts

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

package/src/types.ts

@@ -152,6 +152,14 @@ export interface TelegramPeerStore {
 export type ButtonPress = {
   /** Кто нажал. `null` — отправитель неизвестен каналу. */
   senderId: number | null;
+  /**
+   * В каком чате нажали. `undefined` — канал чата не назвал.
+   *
+   * Нужен затем, что нажатие и сообщение одного чата обязаны исполняться по очереди: карточка
+   * живёт в чате, и ответ на кнопку, обогнавший идущий ответ агента, приходит человеку раньше того,
+   * на что он отвечает. По одному отправителю это не построить — в группе он не равен чату.
+   */
+  chatId?: string;
   data: string;
   /**
    * Подтвердить нажатие, показав человеку текст.
@@ -172,3 +180,105 @@ 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";
+}
+
+/**
+ * Канал, умеющий отметить сообщение прочитанным.
+ *
+ * Не украшение: пока отметки нет, у собеседника горит непрочитанное, а у бота или учётной записи
+ * копится счётчик, по которому потом не отличить обработанное от пропущенного.
+ */
+export interface ReadReceiptTransport extends MessageTransport {
+  /** Отметить прочитанным всё до `messageId` включительно. */
+  markRead(recipient: MessageRecipient, messageId: string): Promise<void>;
+}
+
+export function canMarkRead(transport: MessageTransport): transport is ReadReceiptTransport {
+  return typeof (transport as ReadReceiptTransport).markRead === "function";
+}