@xmanrui/dsh-im 1.4.0 → 2.0.0

package/src/channels/telegram/telegram-api.mjs

@@ -1,5 +1,6 @@
 import { fetchFileStream } from '../shared/file-download.mjs';
 import { fetchImageBuffer } from '../shared/image-prompt.mjs';
+import { t } from '../shared/i18n.mjs';
 
 const DEFAULT_BASE_URL = 'https://api.telegram.org/';
 const TELEGRAM_FILE_HOSTS = Object.freeze(['api.telegram.org']);
@@ -35,33 +36,52 @@ function preserveProviderMetadata(target, source) {
   return target;
 }
 
-function telegramArtifactProviderError(cause) {
+function inputRichMessage(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('A Telegram rich message is required');
+  }
+  const formats = ['markdown', 'html', 'blocks'].filter((key) => value[key] !== undefined);
+  if (formats.length !== 1) {
+    throw new TypeError('A Telegram rich message requires exactly one format');
+  }
+  const selected = formats[0];
+  if ((selected === 'markdown' || selected === 'html')
+    && (typeof value[selected] !== 'string' || !value[selected].trim())) {
+    throw new TypeError('Telegram rich message text is invalid');
+  }
+  if (selected === 'blocks' && !Array.isArray(value.blocks)) {
+    throw new TypeError('Telegram rich message blocks are invalid');
+  }
+  return value;
+}
+
+function telegramArtifactProviderError(cause, mediaLabel = 'document') {
   const providerCode = Number(cause?.providerCode);
   const status = Number(cause?.status);
   const message = cleanString(cause?.message) ?? '';
   let code = 'artifact-provider-rejected';
-  let summary = 'Telegram rejected the document.';
+  let summary = `Telegram rejected the ${mediaLabel}.`;
   if (providerCode === 401 || providerCode === 403 || status === 401 || status === 403) {
     code = 'artifact-permission-required';
-    summary = 'Telegram denied permission to send the document.';
+    summary = `Telegram denied permission to send the ${mediaLabel}.`;
   } else if (providerCode === 413 || status === 413
     || /(?:file|request|entity).{0,20}(?:too (?:big|large)|size limit)|too (?:big|large)/i.test(message)) {
     code = 'artifact-too-large';
-    summary = 'The document exceeds Telegram\'s size limit.';
+    summary = `The ${mediaLabel} exceeds Telegram's size limit.`;
   } else if (providerCode === 429 || status === 429) {
     code = 'artifact-rate-limited';
-    summary = 'Telegram rate-limited document delivery.';
+    summary = `Telegram rate-limited ${mediaLabel} delivery.`;
   } else if (providerCode >= 500 || status >= 500) {
     code = 'artifact-delivery-uncertain';
-    summary = 'Telegram document delivery result is uncertain.';
+    summary = `Telegram ${mediaLabel} delivery result is uncertain.`;
   }
   const error = new Error(summary, { cause });
   error.code = code;
   return preserveProviderMetadata(error, cause);
 }
 
-function uncertainTelegramDelivery(cause) {
-  const error = new Error('Telegram document delivery result is uncertain', { cause });
+function uncertainTelegramDelivery(cause, mediaLabel = 'document') {
+  const error = new Error(`Telegram ${mediaLabel} delivery result is uncertain`, { cause });
   error.code = 'artifact-delivery-uncertain';
   return preserveProviderMetadata(error, cause);
 }
@@ -183,16 +203,71 @@ export class TelegramApi {
     }, { signal });
   }
 
+  async sendRichMessage({
+    chatId,
+    richMessage,
+    replyToMessageId,
+    messageThreadId,
+    signal,
+  }) {
+    return this.#call('sendRichMessage', {
+      chat_id: chatId,
+      rich_message: inputRichMessage(richMessage),
+      ...(replyToMessageId ? {
+        reply_parameters: { message_id: replyToMessageId, allow_sending_without_reply: true },
+      } : {}),
+      ...(messageThreadId ? { message_thread_id: messageThreadId } : {}),
+    }, { signal });
+  }
+
+  async sendRichMessageDraft({ chatId, draftId, richMessage, messageThreadId, signal }) {
+    if (!Number.isSafeInteger(draftId) || draftId === 0) {
+      throw new TypeError('Telegram rich message draft id must be a non-zero integer');
+    }
+    return this.#call('sendRichMessageDraft', {
+      chat_id: chatId,
+      draft_id: draftId,
+      rich_message: inputRichMessage(richMessage),
+      ...(messageThreadId ? { message_thread_id: messageThreadId } : {}),
+    }, { signal });
+  }
+
   async sendDocument({ chatId, file, replyToMessageId, messageThreadId, signal }) {
+    return this.#sendArtifact('sendDocument', 'document', 'document', {
+      chatId,
+      file,
+      replyToMessageId,
+      messageThreadId,
+      signal,
+    });
+  }
+
+  async sendPhoto({ chatId, file, replyToMessageId, messageThreadId, signal }) {
+    return this.#sendArtifact('sendPhoto', 'photo', 'photo', {
+      chatId,
+      file,
+      replyToMessageId,
+      messageThreadId,
+      signal,
+    });
+  }
+
+  async #sendArtifact(method, fieldName, mediaLabel, {
+    chatId,
+    file,
+    replyToMessageId,
+    messageThreadId,
+    signal,
+  }) {
     if (!file || typeof file !== 'object'
       || typeof file.fileName !== 'string' || !file.fileName
       || !Buffer.isBuffer(file.bytes)) {
-      throw new TypeError('A Telegram document is required');
+      throw new TypeError(`A Telegram ${mediaLabel} is required`);
     }
     const payload = new FormData();
     payload.append('chat_id', String(chatId));
     payload.append(
-      'document',
+      fieldName,
       new Blob([file.bytes], { type: file.mediaType ?? 'application/octet-stream' }),
       file.fileName,
     );
@@ -206,26 +281,34 @@ export class TelegramApi {
     if (signal?.aborted) throw abortReason(signal);
     const uploadSignal = requestSignal(signal, this.#fileUploadTimeoutMs);
     try {
-      return await this.#call('sendDocument', payload, {
+      return await this.#call(method, payload, {
         signal: uploadSignal,
         timeoutMs: this.#fileUploadTimeoutMs,
         multipart: true,
       });
     } catch (error) {
       if (signal?.aborted) throw abortReason(signal);
+      if (error?.deliveryOutcome === 'unknown') {
+        throw uncertainTelegramDelivery(error?.cause ?? error, mediaLabel);
+      }
       if (error?.code?.startsWith?.('telegram-')) {
-        throw telegramArtifactProviderError(error);
+        throw telegramArtifactProviderError(error, mediaLabel);
       }
-      throw uncertainTelegramDelivery(error);
+      throw uncertainTelegramDelivery(error, mediaLabel);
     }
   }
 
-  async editMessageText({ chatId, messageId, text, signal }) {
+  async editMessageText({ chatId, messageId, text, richMessage, signal }) {
+    if ((text === undefined) === (richMessage === undefined)) {
+      throw new TypeError('Telegram message edit requires exactly one of text or richMessage');
+    }
     return this.#call('editMessageText', {
       chat_id: chatId,
       message_id: messageId,
-      text,
-      link_preview_options: { is_disabled: true },
+      ...(text === undefined ? { rich_message: inputRichMessage(richMessage) } : {
+        text,
+        link_preview_options: { is_disabled: true },
+      }),
     }, { signal });
   }
 
@@ -257,6 +340,7 @@ export class TelegramApi {
   }
 
   async #call(method, payload, { signal, timeoutMs = 15_000, multipart = false } = {}) {
+    if (signal?.aborted) throw abortReason(signal);
     const url = new URL(this.#baseUrl);
     url.pathname = `${url.pathname.replace(/\/$/, '')}/bot${this.#token}/${method}`;
     let response;
@@ -269,8 +353,14 @@ export class TelegramApi {
         redirect: 'error',
       });
     } catch (error) {
-      if (error?.name === 'AbortError' || error?.name === 'TimeoutError') throw error;
-      throw new Error(`Telegram ${method} transport failed`);
+      const transport = new Error(`Telegram ${method} transport failed`, { cause: error });
+      transport.code = error?.name === 'TimeoutError'
+        ? 'telegram-timeout'
+        : error?.name === 'AbortError'
+          ? 'telegram-aborted-after-dispatch'
+          : 'telegram-transport-error';
+      transport.deliveryOutcome = 'unknown';
+      throw transport;
     }
     let body;
     try {
@@ -278,6 +368,8 @@ export class TelegramApi {
     } catch {
       const error = new Error(`Telegram ${method} returned invalid JSON`);
       error.status = response?.status;
+      error.code = 'telegram-response-invalid';
+      error.deliveryOutcome = 'unknown';
       throw error;
     }
     if (!response.ok || body?.ok !== true) {
@@ -303,7 +395,7 @@ export async function inspectTelegramToken(token, options = {}) {
   if (!bot?.id || bot?.is_bot !== true) throw new Error('Telegram token does not belong to a bot');
   return {
     platformId: String(bot.id),
-    name: cleanString([bot.first_name, bot.last_name].filter(Boolean).join(' ')) ?? 'Telegram机器人',
+    name: cleanString([bot.first_name, bot.last_name].filter(Boolean).join(' ')) ?? t('Telegram机器人'),
     username: cleanString(bot.username),
   };
 }

package/src/channels/telegram/telegram-rich-message.mjs

@@ -0,0 +1,147 @@
+export const TELEGRAM_RICH_TEXT_LIMIT = 30_000;
+export const TELEGRAM_REGULAR_TEXT_LIMIT = 4_000;
+
+function textValue(value) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new TypeError('Telegram message text must be a non-empty string');
+  }
+  return value;
+}
+
+function escapedCharacterLength(value) {
+  if (value === '&') return 5;
+  if (value === '<' || value === '>') return 4;
+  return 1;
+}
+
+function escapedLength(value) {
+  return Array.from(value).reduce((total, character) => (
+    total + escapedCharacterLength(character)
+  ), 0);
+}
+
+function preferredCut(points, offset, hardEnd, limit) {
+  const minimum = offset + Math.floor(limit * 0.5);
+  for (let index = hardEnd - 1; index >= minimum; index -= 1) {
+    if (points[index] === '\n' || points[index] === ' ') return index + 1;
+  }
+  return hardEnd;
+}
+
+function splitText(value, limit, characterLength = () => 1) {
+  if (typeof value !== 'string') throw new TypeError('Telegram message text must be a string');
+  if (!value) return [];
+  const points = Array.from(value);
+  const chunks = [];
+  let offset = 0;
+  while (offset < points.length) {
+    let end = offset;
+    let length = 0;
+    while (end < points.length) {
+      const nextLength = characterLength(points[end]);
+      if (length + nextLength > limit) break;
+      length += nextLength;
+      end += 1;
+    }
+    if (end === offset) throw new Error('Telegram message character exceeds the chunk limit');
+    if (end < points.length) end = preferredCut(points, offset, end, limit);
+    chunks.push(points.slice(offset, end).join(''));
+    offset = end;
+  }
+  return chunks;
+}
+
+function fenceMarkers(markdown) {
+  return [...markdown.matchAll(/^```[^\n]*(?:\n|$)/gm)];
+}
+
+function assertCompleteFences(markdown) {
+  const markers = fenceMarkers(markdown);
+  if (markers.length % 2 !== 0) {
+    throw new Error('Telegram Rich Markdown contains an unfinished code fence');
+  }
+  return markers;
+}
+
+function escapedMarkdown(value) {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+function plainRichChunks(source, limit) {
+  return splitText(source, limit, escapedCharacterLength).map((chunk) => ({
+    source: chunk,
+    markdown: escapedMarkdown(chunk),
+  }));
+}
+
+function fencedRichChunks(source, opening, closing, limit) {
+  const body = source.slice(opening.length, source.length - closing.length);
+  const wrapperLength = escapedLength(opening)
+    + Math.max(escapedLength(closing), escapedLength('```'))
+    + 1;
+  const bodyLimit = limit - wrapperLength;
+  if (bodyLimit < 1) throw new Error('Telegram Rich Markdown code fence exceeds the limit');
+  const bodyChunks = splitText(body, bodyLimit, escapedCharacterLength);
+  return bodyChunks.map((bodyChunk, index) => {
+    const last = index === bodyChunks.length - 1;
+    const separator = bodyChunk.endsWith('\n') ? '' : '\n';
+    const renderedClosing = last ? closing : '```';
+    const sourceChunk = `${index === 0 ? opening : ''}${bodyChunk}${last ? closing : ''}`;
+    const markdown = escapedMarkdown(`${opening}${bodyChunk}${separator}${renderedClosing}`);
+    if (Array.from(markdown).length > limit) {
+      throw new Error('Telegram Rich Markdown code block exceeds the limit');
+    }
+    return { source: sourceChunk, markdown };
+  });
+}
+
+export function toTelegramRichMarkdown(value) {
+  const markdown = textValue(value);
+  assertCompleteFences(markdown);
+  // Rich Markdown also accepts HTML tags. Escape entities first so encoded or
+  // raw model output cannot be interpreted as Telegram-specific markup.
+  return escapedMarkdown(markdown);
+}
+
+export function splitTelegramRichMarkdown(value, limit = TELEGRAM_RICH_TEXT_LIMIT) {
+  if (!Number.isInteger(limit) || limit < 128 || limit > 32_768) {
+    throw new TypeError('Telegram Rich Markdown limit is invalid');
+  }
+  const source = textValue(value);
+  const markers = assertCompleteFences(source);
+  const complete = escapedMarkdown(source);
+  if (Array.from(complete).length <= limit) return [{ source, markdown: complete }];
+
+  const chunks = [];
+  let cursor = 0;
+  for (let index = 0; index < markers.length; index += 2) {
+    const opening = markers[index];
+    const closing = markers[index + 1];
+    if (opening.index > cursor) {
+      chunks.push(...plainRichChunks(source.slice(cursor, opening.index), limit));
+    }
+    const end = closing.index + closing[0].length;
+    const fenced = source.slice(opening.index, end);
+    const rendered = escapedMarkdown(fenced);
+    if (Array.from(rendered).length <= limit) {
+      chunks.push({ source: fenced, markdown: rendered });
+    } else {
+      chunks.push(...fencedRichChunks(fenced, opening[0], closing[0], limit));
+    }
+    cursor = end;
+  }
+  if (cursor < source.length) chunks.push(...plainRichChunks(source.slice(cursor), limit));
+  return chunks;
+}
+
+export function splitTelegramRegularText(value, limit = TELEGRAM_REGULAR_TEXT_LIMIT) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 4_096) {
+    throw new TypeError('Telegram regular message limit is invalid');
+  }
+  // Keep Telegram's established 4000 UTF-16-unit boundary without ever cutting
+  // a surrogate pair in half.
+  return splitText(textValue(value), limit, (character) => character.length);
+}