@imessaging/core 0.1.0 → 0.3.0

package/package.json

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

package/src/index.ts

@@ -1,6 +1,11 @@
 export { MemoryPeerStore } from "./memory-peer-store";
 export { createPeerKey } from "./peer-key";
+export { canEdit, isTelegramRecipient } from "./types";
 export type {
+  EditableMessage,
+  EditableMessageTransport,
+  EditResult,
+  EmailRecipient,
   MessageRecipient,
   MessageTransport,
   OutboundButton,
@@ -9,5 +14,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;
@@ -41,6 +70,29 @@ export type SendResult = {
   recipientId: string;
 };
 
+/**
+ * Правка уже отправленного сообщения.
+ *
+ * Адресуется парой «получатель + идентификатор сообщения»: сам по себе идентификатор в Telegram
+ * не уникален, он нумеруется В ПРЕДЕЛАХ чата, и без получателя правка ушла бы не туда.
+ *
+ * Вложения не правятся: у отправленного сообщения меняется текст и разметка, а документы уже
+ * доставлены отдельными сообщениями. Обещать здесь `documents` значило бы обещать невыполнимое.
+ */
+export type EditableMessage = {
+  recipient: MessageRecipient;
+  messageId: string;
+  text: string;
+  buttons?: OutboundButton[][];
+  parseMode?: "HTML" | "Markdown" | "MarkdownV2";
+};
+
+export type EditResult = {
+  transportId: string;
+  messageId: string;
+  recipientId: string;
+};
+
 export type TransportStatus = {
   connected: boolean;
   transportId: string;
@@ -57,6 +109,21 @@ export interface MessageTransport {
   getStatus(): Promise<TransportStatus>;
 }
 
+/**
+ * Транспорт, умеющий править отправленное.
+ *
+ * Отдельный интерфейс, а не метод в `MessageTransport`: править умеет не всякий канал, и обещать
+ * это всем транспортам значит заставить каждый новый бросать «не поддерживается». Потребитель
+ * спрашивает возможность типом (`canEdit`), а не ловит исключение.
+ */
+export interface EditableMessageTransport extends MessageTransport {
+  edit(message: EditableMessage): Promise<EditResult>;
+}
+
+export function canEdit(transport: MessageTransport): transport is EditableMessageTransport {
+  return typeof (transport as EditableMessageTransport).edit === "function";
+}
+
 export type ResolvedPeer = {
   type: "user" | "group" | "channel";
   id: string;