telegix 1.1.2 → 1.1.3

package/index.js

@@ -1,6 +1,6 @@
 /**
  * Telegix - Lightweight, Pure JavaScript Telegram Bot API Framework
- * @author KazeDevID
+ * @author Michael Agam
  * @license MIT
  */
 
@@ -13,7 +13,71 @@ export { session, MemorySessionStore, FileSessionStore } from './lib/session.js'
 export { Polling } from './lib/polling.js';
 export { createWebhookCallback } from './lib/webhook.js';
 export { fmt, Format, escapeHtml, escapeMarkdown, html, markdown } from './lib/format.js';
-export { RichMessage, RichMessageBuilder } from './lib/rich.js';
+export { Table, InputRichBlockTable, RichBlockTable } from './lib/table.js';
+export { EphemeralMessageParameters, ReplyParameters, BotCommand } from './lib/ephemeral.js';
+export {
+  RichMessage,
+  RichMessageBuilder,
+  RichMessageButton,
+  RichTextButton,
+  InputRichMessage,
+  InputRichMessageMedia,
+  RichMessageMedia,
+  InputMediaVoiceNote,
+  MediaVoiceNote,
+  InputRichBlockButtons,
+  RichBlockButtons,
+  InputRichBlockExpandableBlockQuotation,
+  RichBlockExpandableBlockQuotation,
+  InputRichBlockDocument,
+  RichBlockDocument,
+  InputRichBlockParagraph,
+  RichBlockParagraph,
+  InputRichBlockSectionHeading,
+  RichBlockSectionHeading,
+  InputRichBlockPreformatted,
+  RichBlockPreformatted,
+  InputRichBlockFooter,
+  RichBlockFooter,
+  InputRichBlockDivider,
+  RichBlockDivider,
+  InputRichBlockMathematicalExpression,
+  RichBlockMathematicalExpression,
+  RichBlockMath,
+  InputRichBlockAnchor,
+  RichBlockAnchor,
+  InputRichBlockListItem,
+  RichBlockListItem,
+  InputRichBlockList,
+  RichBlockList,
+  InputRichBlockChecklist,
+  RichBlockChecklist,
+  InputRichBlockBlockQuotation,
+  RichBlockBlockQuotation,
+  InputRichBlockPullQuotation,
+  RichBlockPullQuotation,
+  RichBlockPullQuote,
+  InputRichBlockCollage,
+  RichBlockCollage,
+  InputRichBlockSlideshow,
+  RichBlockSlideshow,
+  InputRichBlockDetails,
+  RichBlockDetails,
+  InputRichBlockMap,
+  RichBlockMap,
+  InputRichBlockAnimation,
+  RichBlockAnimation,
+  InputRichBlockAudio,
+  RichBlockAudio,
+  InputRichBlockPhoto,
+  RichBlockPhoto,
+  InputRichBlockVideo,
+  RichBlockVideo,
+  InputRichBlockVoiceNote,
+  RichBlockVoiceNote,
+  InputRichBlockThinking,
+  RichBlockThinking,
+} from './lib/rich.js';
 export { Scene, BaseScene, WizardScene, Stage } from './lib/scenes.js';
 export { I18n } from './lib/i18n.js';
 export { RateLimiter, rateLimit } from './lib/ratelimit.js';

package/lib/api.js

@@ -1,10 +1,12 @@
 /**
- * Telegix - Pure JavaScript Telegram Bot API Client
+ * Telegix - Telegram Bot API Client
  * @module telegix/api
  */
 
 import { TelegramError, NetworkError } from './errors.js';
 import { streamText as runStreamText } from './stream.js';
+import { Table, InputRichBlockTable } from './table.js';
+import { ReplyParameters, BotCommand, EphemeralMessageParameters } from './ephemeral.js';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -17,7 +19,15 @@ import path from 'node:path';
 export function isUploadableFile(value, key = '') {
   if (!value) return false;
   if (typeof value === 'string') return false;
-  if (key === 'link_preview_options' || key === 'reply_parameters' || key === 'reply_markup') {
+  if (
+    key === 'link_preview_options' ||
+    key === 'reply_parameters' ||
+    key === 'reply_markup' ||
+    key === 'ephemeral_message_parameters' ||
+    key === 'ephemeral_parameters' ||
+    key === 'blocks' ||
+    key === 'media'
+  ) {
     return false;
   }
   if (value instanceof Blob || value instanceof Uint8Array || Buffer.isBuffer(value)) return true;
@@ -228,6 +238,57 @@ export function normalizeTelegramPayload(payload) {
     delete norm.disable_web_page_preview;
   }
 
+  // 7. Handle reply_parameters (Telegram Bot API 10.2+)
+  if (norm.reply_parameters && typeof norm.reply_parameters.toJSON === 'function') {
+    norm.reply_parameters = norm.reply_parameters.toJSON();
+  }
+  if (!norm.reply_parameters) {
+    if (norm.ephemeral_message_id !== undefined && norm.reply_to_message_id === undefined) {
+      norm.reply_parameters = {
+        ephemeral_message_id: Number(norm.ephemeral_message_id),
+        ...(norm.allow_sending_without_reply !== undefined ? { allow_sending_without_reply: Boolean(norm.allow_sending_without_reply) } : {}),
+      };
+      delete norm.ephemeral_message_id;
+      delete norm.allow_sending_without_reply;
+    } else if (norm.reply_to_message_id !== undefined) {
+      norm.reply_parameters = {
+        message_id: Number(norm.reply_to_message_id),
+        ...(norm.allow_sending_without_reply !== undefined ? { allow_sending_without_reply: Boolean(norm.allow_sending_without_reply) } : {}),
+        ...(norm.ephemeral_message_id !== undefined ? { ephemeral_message_id: Number(norm.ephemeral_message_id) } : {}),
+      };
+      delete norm.reply_to_message_id;
+      delete norm.allow_sending_without_reply;
+      delete norm.ephemeral_message_id;
+    }
+  } else if (norm.reply_parameters && typeof norm.reply_parameters === 'object') {
+    if (norm.ephemeral_message_id !== undefined && norm.reply_parameters.ephemeral_message_id === undefined) {
+      norm.reply_parameters.ephemeral_message_id = Number(norm.ephemeral_message_id);
+      delete norm.ephemeral_message_id;
+    }
+  }
+
+  // 8. Handle ephemeral_message_parameters (Telegram Bot API 10.2 / 10.3)
+  if (norm.ephemeral_message_parameters) {
+    if (typeof norm.ephemeral_message_parameters.toJSON === 'function') {
+      norm.ephemeral_message_parameters = norm.ephemeral_message_parameters.toJSON();
+    } else if (typeof norm.ephemeral_message_parameters === 'number') {
+      norm.ephemeral_message_parameters = { lifetime: norm.ephemeral_message_parameters };
+    }
+  } else if (norm.ephemeral_parameters) {
+    if (typeof norm.ephemeral_parameters.toJSON === 'function') {
+      norm.ephemeral_message_parameters = norm.ephemeral_parameters.toJSON();
+    } else if (typeof norm.ephemeral_parameters === 'number') {
+      norm.ephemeral_message_parameters = { lifetime: norm.ephemeral_parameters };
+    } else {
+      norm.ephemeral_message_parameters = { ...norm.ephemeral_parameters };
+    }
+  } else if (norm.receiver_user_id !== undefined || norm.callback_query_id !== undefined) {
+    norm.ephemeral_message_parameters = {
+      ...(norm.receiver_user_id !== undefined ? { receiver_user_id: norm.receiver_user_id } : {}),
+      ...(norm.callback_query_id !== undefined ? { callback_query_id: norm.callback_query_id } : {}),
+    };
+  }
+
   return norm;
 }
 
@@ -284,6 +345,12 @@ export class Telegram {
         hasUpload = true;
         break;
       }
+      if (key === 'media' && normalizedPayload[key] && typeof normalizedPayload[key] === 'object') {
+        if (isUploadableFile(normalizedPayload[key].media, 'media')) {
+          hasUpload = true;
+          break;
+        }
+      }
     }
 
     let requestInit = {
@@ -296,7 +363,17 @@ export class Telegram {
       for (const [key, value] of Object.entries(normalizedPayload)) {
         if (value === undefined || value === null) continue;
 
-        if (isUploadableFile(value, key)) {
+        if (key === 'media' && typeof value === 'object' && value.media && isUploadableFile(value.media, 'media')) {
+          const { blob, filename } = await normalizeFileSource(value.media, 'media');
+          const attachName = `media_file_${Date.now()}`;
+          if (typeof blob === 'string') {
+            formData.append(attachName, blob);
+          } else {
+            formData.append(attachName, blob, filename || 'file');
+          }
+          const mediaObj = { ...value, media: `attach://${attachName}` };
+          formData.append('media', JSON.stringify(mediaObj));
+        } else if (isUploadableFile(value, key)) {
           const { blob, filename } = await normalizeFileSource(value, key);
           if (typeof blob === 'string') {
             formData.append(key, blob);
@@ -463,6 +540,22 @@ export class Telegram {
     return this.call('sendPhoto', { chat_id: chatId, photo, ...extra });
   }
 
+  /**
+   * Send a live photo (photo with short video - Bot API 10.2+)
+   * @param {number|string} chatId
+   * @param {any} photo - Photo file_id, URL, or input file
+   * @param {any} video - Video loop file_id, URL, or input file (max 10s, 10MB)
+   * @param {object} [extra] - Extra parameters (receiver_user_id, callback_query_id, caption, etc.)
+   */
+  sendLivePhoto(chatId, photo, video, extra = {}) {
+    return this.call('sendLivePhoto', {
+      chat_id: chatId,
+      photo,
+      video,
+      ...extra,
+    });
+  }
+
   /**
    * Send audio
    */
@@ -967,7 +1060,10 @@ export class Telegram {
    * Bot commands and metadata
    */
   setMyCommands(commands, extra = {}) {
-    return this.call('setMyCommands', { commands, ...extra });
+    const serialized = Array.isArray(commands)
+      ? commands.map((cmd) => (typeof cmd?.toJSON === 'function' ? cmd.toJSON() : cmd))
+      : commands;
+    return this.call('setMyCommands', { commands: serialized, ...extra });
   }
 
   deleteMyCommands(extra = {}) {
@@ -1703,9 +1799,9 @@ export class Telegram {
   }
 
   /**
-   * Send an ephemeral message
+   * Send an ephemeral message (Bot API 10.3 EphemeralMessageParameters)
    * @param {number|string} chatId
-   * @param {string} text
+   * @param {string|object} text
    * @param {object|number} [ephemeralParameters={}]
    * @param {object} [extra={}]
    */
@@ -1713,14 +1809,28 @@ export class Telegram {
     let params = ephemeralParameters;
     if (typeof ephemeralParameters === 'number') {
       params = { lifetime: ephemeralParameters };
+    } else if (ephemeralParameters && typeof ephemeralParameters.toJSON === 'function') {
+      params = ephemeralParameters.toJSON();
     }
     const payload = {
       chat_id: chatId,
-      text,
-      ...(params && typeof params === 'object' ? { ephemeral_parameters: params } : {}),
+      text: typeof text === 'string' ? text : (text?.text || String(text)),
+      ...(params && typeof params === 'object'
+        ? {
+            ephemeral_message_parameters: params,
+            ephemeral_parameters: params,
+          }
+        : {}),
       ...extra,
     };
 
+    if (text && typeof text === 'object' && (text.blocks || typeof text.compile === 'function')) {
+      const compiled = typeof text.compile === 'function' ? text.compile() : text;
+      payload.text = compiled.text;
+      if (compiled.blocks) payload.blocks = compiled.blocks;
+      if (compiled.reply_markup && !payload.reply_markup) payload.reply_markup = compiled.reply_markup;
+    }
+
     const autoDeleteSeconds =
       params?.autoDeleteSeconds ||
       params?.lifetime ||
@@ -1734,7 +1844,7 @@ export class Telegram {
         err.description?.includes('Unknown method') ||
         err.description?.includes('Bad Request')
       ) {
-        const msg = await this.sendMessage(chatId, text, extra);
+        const msg = await this.sendMessage(chatId, payload.text, extra);
         if (autoDeleteSeconds && msg?.message_id) {
           setTimeout(() => {
             this.deleteMessage(chatId, msg.message_id).catch(() => {});
@@ -1747,23 +1857,159 @@ export class Telegram {
   }
 
   /**
-   * Edit ephemeral message text
+   * Send a formatted table to a chat (HTML Table or Native Bot API 10.3 Card)
+   * @param {number|string} chatId
+   * @param {Array<string>|Table|InputRichBlockTable} headersOrTable
+   * @param {Array<Array<any>>} [rows=[]]
+   * @param {object} [options={}]
+   */
+  sendTable(chatId, headersOrTable, rows = [], options = {}) {
+    if (options.rich === true || options.card === true || options.style === 'card' || options.native === true) {
+      return this.sendRichTable(chatId, headersOrTable, rows, options);
+    }
+    let tableHtml;
+    if (headersOrTable instanceof Table || (headersOrTable && typeof headersOrTable.toHtml === 'function')) {
+      tableHtml = headersOrTable.toHtml(options);
+    } else {
+      tableHtml = Table.html(headersOrTable, rows, options);
+    }
+    return this.sendMessage(chatId, tableHtml, {
+      parse_mode: 'HTML',
+      ...options,
+    });
+  }
+
+  /**
+   * Send a native Bot API 10.3 Rich Message Table (renders modern card table UI)
+   * @param {number|string} chatId
+   * @param {Array<string>|Table|InputRichBlockTable|object} headersOrTable
+   * @param {Array<Array<any>>} [rows=[]]
+   * @param {object} [options={}]
+   */
+  sendRichTable(chatId, headersOrTable, rows = [], options = {}) {
+    let block;
+    if (headersOrTable instanceof InputRichBlockTable) {
+      block = headersOrTable;
+    } else if (headersOrTable instanceof Table) {
+      block = new InputRichBlockTable(headersOrTable.headers, headersOrTable.rows, {
+        is_compact: headersOrTable.is_compact,
+        is_bordered: headersOrTable.is_bordered,
+        is_striped: headersOrTable.is_striped,
+        caption: headersOrTable.caption,
+        alignments: headersOrTable._alignments,
+        title: headersOrTable._title,
+        col1Width: headersOrTable.col1Width,
+        ...options,
+      });
+    } else if (headersOrTable && typeof headersOrTable === 'object' && !Array.isArray(headersOrTable)) {
+      block = new InputRichBlockTable(headersOrTable);
+    } else {
+      block = new InputRichBlockTable(headersOrTable, rows, { is_bordered: true, ...options });
+    }
+
+    const titleText = options.title || block.title || '';
+    const caption = options.caption || block.caption || '';
+    const headerPrefix = titleText ? `<b>${titleText}</b>\n\n` : '';
+    const footerSuffix = caption ? `\n\n<i>${caption}</i>` : '';
+
+    return this.sendRichMessage(chatId, {
+      text: `${headerPrefix}${block.toHtml()}${footerSuffix}`,
+      parse_mode: 'HTML',
+      blocks: [block.toJSON()],
+    }, options);
+  }
+
+  /**
+   * Send a Card Table to a chat (as Rich Block or styled SVG Card Image)
+   * @param {number|string} chatId
+   * @param {Array<string>|Table} headersOrTable
+   * @param {Array<Array<any>>} [rows=[]]
+   * @param {object} [options={}]
+   */
+  sendTableCard(chatId, headersOrTable, rows = [], options = {}) {
+    if (options.asImage || options.photo || options.image) {
+      const table = headersOrTable instanceof Table
+        ? headersOrTable
+        : new Table(headersOrTable, rows, options);
+      const svgBuffer = table.toBuffer(options);
+      return this.sendPhoto(chatId, {
+        source: svgBuffer,
+        filename: 'table-card.svg',
+      }, {
+        caption: options.caption || options.title || '',
+        parse_mode: options.parse_mode || 'HTML',
+        ...options,
+      });
+    }
+
+    return this.sendRichTable(chatId, headersOrTable, rows, { is_bordered: true, ...options });
+  }
+
+  /**
+   * Send multiple stacked card tables (e.g. SYSTEM and PROFILE cards)
+   * @param {number|string} chatId
+   * @param {Array<Table|object>} tables
+   * @param {object} [options={}]
+   */
+  sendCardTables(chatId, tables, options = {}) {
+    if (options.asImage || options.photo || options.image) {
+      const svg = Table.multiCardSvg(tables, options);
+      const buffer = Buffer.from(svg, 'utf-8');
+      return this.sendPhoto(chatId, {
+        source: buffer,
+        filename: 'tables-cards.svg',
+      }, {
+        caption: options.caption || '',
+        parse_mode: options.parse_mode || 'HTML',
+        ...options,
+      });
+    }
+
+    const list = Array.isArray(tables) ? tables : [tables];
+    const blocks = list.map((t) => {
+      const tableInst = t instanceof Table ? t : (t instanceof InputRichBlockTable ? t : new Table(t));
+      return tableInst.toRichBlock ? tableInst.toRichBlock() : tableInst.toJSON();
+    });
+
+    const htmlParts = list.map((t) => {
+      if (typeof t?.toHtml === 'function') return t.toHtml();
+      return new Table(t).toHtml();
+    });
+
+    return this.sendRichMessage(chatId, {
+      text: htmlParts.join('\n\n'),
+      parse_mode: 'HTML',
+      blocks,
+    }, options);
+  }
+
+  /**
+   * Edit ephemeral message text (Bot API 10.3 supports rich_message)
    * @param {number|string} chatId
    * @param {number} messageId
-   * @param {string} text
+   * @param {string|object} text
    * @param {object} [extra]
    */
   editEphemeralMessageText(chatId, messageId, text, extra = {}) {
-    return this.call('editEphemeralMessageText', {
+    const payload = {
       chat_id: chatId,
       message_id: messageId,
-      text,
       ...extra,
-    });
+    };
+    if (extra.rich_message) {
+      payload.rich_message = typeof extra.rich_message.toJSON === 'function'
+        ? extra.rich_message.toJSON()
+        : extra.rich_message;
+    } else if (text && typeof text === 'object' && (text.blocks || typeof text.compile === 'function' || typeof text.toJSON === 'function')) {
+      payload.rich_message = typeof text.compile === 'function' ? text.compile() : (typeof text.toJSON === 'function' ? text.toJSON() : text);
+    } else {
+      payload.text = String(text);
+    }
+    return this.call('editEphemeralMessageText', payload);
   }
 
   /**
-   * Edit ephemeral message media
+   * Edit ephemeral message media (Bot API 10.3 supports file upload)
    * @param {number|string} chatId
    * @param {number} messageId
    * @param {object} media
@@ -1779,19 +2025,23 @@ export class Telegram {
   }
 
   /**
-   * Edit ephemeral message caption
+   * Edit ephemeral message caption (Bot API 10.3 supports show_caption_above_media)
    * @param {number|string} chatId
    * @param {number} messageId
    * @param {string} caption
    * @param {object} [extra]
    */
   editEphemeralMessageCaption(chatId, messageId, caption, extra = {}) {
-    return this.call('editEphemeralMessageCaption', {
+    const payload = {
       chat_id: chatId,
       message_id: messageId,
       caption,
       ...extra,
-    });
+    };
+    if (extra.show_caption_above_media !== undefined) {
+      payload.show_caption_above_media = Boolean(extra.show_caption_above_media);
+    }
+    return this.call('editEphemeralMessageCaption', payload);
   }
 
   /**
@@ -1916,3 +2166,5 @@ export class Telegram {
     return runStreamText(this, chatId, textStream, { ...options, useDraft: true });
   }
 }
+
+export { ReplyParameters, BotCommand, EphemeralMessageParameters };