@imessaging/core 0.2.0 → 0.4.0

package/package.json

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

package/src/index.ts

@@ -1,10 +1,12 @@
 export { MemoryPeerStore } from "./memory-peer-store";
 export { createPeerKey } from "./peer-key";
-export { canEdit } from "./types";
+export { canEdit, isTelegramRecipient } from "./types";
+export type { ButtonPress, ButtonPressTransport } from "./types";
 export type {
   EditableMessage,
   EditableMessageTransport,
   EditResult,
+  EmailRecipient,
   MessageRecipient,
   MessageTransport,
   OutboundButton,
@@ -13,5 +15,6 @@ export type {
   ResolvedPeer,
   SendResult,
   TelegramPeerStore,
+  TelegramRecipient,
   TransportStatus,
 } from "./types";

package/src/peer-key.ts

@@ -1,4 +1,4 @@
-import type { MessageRecipient } from "./types";
+import { isTelegramRecipient, type MessageRecipient } from "./types";
 
 function normalizeUsername(username: string): string {
   return username.trim().replace(/^@/, "").toLowerCase();
@@ -10,6 +10,12 @@ export function createPeerKey(accountId: string, recipient: MessageRecipient): s
     throw new Error("accountId must not be empty");
   }
 
+  // Кеш пиров — телеграмный. Адрес почты сюда не кладут: ключ вида `telegram-peer:…:email:…`
+  // выглядел бы настоящим и молча жил бы в хранилище, ничего не адресуя.
+  if (!isTelegramRecipient(recipient)) {
+    throw new Error("peer key is Telegram-only and cannot be built for an email recipient");
+  }
+
   if (recipient.type === "username") {
     const username = normalizeUsername(recipient.username);
     if (!username) {

package/src/types.ts

@@ -9,7 +9,36 @@ export type TelegramIdRecipient = {
   username?: string;
 };
 
-export type MessageRecipient = UsernameRecipient | TelegramIdRecipient;
+/**
+ * Получатель письма.
+ *
+ * Адрес — самостоятельный вид получателя, а не telegram-имя с собачкой. Соблазн подставить почту
+ * в `UsernameRecipient` велик (поле тоже строковое), но тогда `createPeerKey` завёл бы для письма
+ * ключ telegram-пира, а mtproto-транспорт попытался бы разрешить адрес как @username и упал бы с
+ * сообщением про Telegram. Отдельный вариант заставляет каждый транспорт сказать вслух, работает
+ * он с этим получателем или нет.
+ */
+export type EmailRecipient = {
+  type: "email";
+  address: string;
+  /** Отображаемое имя: `Имя <адрес>`. Необязательно — без него уходит голый адрес. */
+  name?: string;
+};
+
+export type MessageRecipient = UsernameRecipient | TelegramIdRecipient | EmailRecipient;
+
+/** Получатель, адресуемый в Telegram. Сужение для транспортов, которые кроме него ничего не умеют. */
+export type TelegramRecipient = UsernameRecipient | TelegramIdRecipient;
+
+/**
+ * Телеграмный ли это получатель.
+ *
+ * Нужен транспортам как ЕДИНСТВЕННАЯ точка отказа от чужого канала: без него проверка расползётся
+ * по местам использования `recipient.id` и в каждом будет своей.
+ */
+export function isTelegramRecipient(recipient: MessageRecipient): recipient is TelegramRecipient {
+  return recipient.type !== "email";
+}
 
 export type OutboundDocument = {
   data: Uint8Array;
@@ -113,3 +142,33 @@ 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;
+}