telegix 1.1.1 → 1.1.2

package/index.d.ts

@@ -92,6 +92,10 @@ export class Markup {
     text(text: string): object;
     callback(text: string, data: string): object;
     url(text: string, url: string): object;
+    primary(text: string, dataOrUrl?: string | number | object, options?: object): object;
+    danger(text: string, dataOrUrl?: string | number | object, options?: object): object;
+    success(text: string, dataOrUrl?: string | number | object, options?: object): object;
+    colored(text: string, style: 'primary' | 'danger' | 'success', dataOrUrl?: string | number | object, options?: object): object;
     webApp(text: string, url: string): object;
     contactRequest(text: string): object;
     locationRequest(text: string): object;
@@ -208,6 +212,14 @@ export class Context {
   replyWithPaidMedia(starCount: number, media: any[], extra?: object): Promise<Message>;
   replyWithSticker(sticker: any, extra?: object): Promise<Message>;
   replyWithGame(gameShortName: string, extra?: object): Promise<Message>;
+  replyWithLinkPreview(text: string, linkPreviewOptions: LinkPreview | object, extra?: object): Promise<Message>;
+  replyWithCollapsibleQuote(text: string, extra?: object): Promise<Message>;
+  replyWithExpandableQuote(text: string, extra?: object): Promise<Message>;
+  replyWithWebApp(text: string, webAppUrl: string, buttonText?: string, extra?: object): Promise<Message>;
+  streamText(textStream: any, options?: object): Promise<any>;
+  streamDraft(textStream: any, options?: object): Promise<any>;
+  savePreparedInlineMessage(result: object, options?: object): Promise<{ id: string; expiration_date: number }>;
+  validateWebAppInitData(initDataStr: string, options?: object): any;
   createForumTopic(name: string, extra?: object): Promise<any>;
   editForumTopic(messageThreadId?: number, extra?: object): Promise<boolean>;
   closeForumTopic(messageThreadId?: number): Promise<boolean>;
@@ -228,6 +240,7 @@ export class Context {
   sendRichMessageDraft(draft: any, extra?: object): Promise<boolean>;
   react(emoji: string | any[]): Promise<boolean>;
   answerCallbackQuery(text?: string, options?: object): Promise<boolean>;
+  answerCbQuery(text?: string, options?: object): Promise<boolean>;
   answerInlineQuery(results: any[], options?: object): Promise<boolean>;
   editMessageText(text: string, extra?: object): Promise<Message | boolean>;
   editMessageCaption(caption: string, extra?: object): Promise<Message | boolean>;
@@ -332,6 +345,7 @@ export class RichMessageBuilder {
   code(codeText: string, language?: string): this;
   quote(text: string, expandable?: boolean): this;
   expandableQuote(text: string): this;
+  collapsibleQuote(text: string): this;
   spoiler(text: string): this;
   link(text: string, url: string): this;
   mention(text: string, userId: number | string): this;
@@ -347,6 +361,10 @@ export class RichMessageBuilder {
   row(...buttons: object[]): this;
   callback(text: string, data: string): this;
   url(text: string, url: string): this;
+  primary(text: string, dataOrUrl?: string | number | object, options?: object): this;
+  danger(text: string, dataOrUrl?: string | number | object, options?: object): this;
+  success(text: string, dataOrUrl?: string | number | object, options?: object): this;
+  colored(text: string, style: 'primary' | 'danger' | 'success', dataOrUrl?: string | number | object, options?: object): this;
   disabled(text: string): this;
   webApp(text: string, webAppUrl: string): this;
   copyText(text: string, textToCopy: string): this;
@@ -402,6 +420,9 @@ export class Telegram {
   setManagedBotAccessSettings(userId: number, settings?: object, extra?: object): Promise<boolean>;
   getUserPersonalChatMessages(userId: number, extra?: object): Promise<any>;
   sendMessageDraft(chatId: number | string, text: string, extra?: object): Promise<boolean>;
+  savePreparedInlineMessage(userId: number, result: object, options?: object): Promise<{ id: string; expiration_date: number }>;
+  streamText(chatId: number | string, textStream: any, options?: object): Promise<{ message_id?: number; text: string; done: boolean }>;
+  streamDraft(chatId: number | string, textStream: any, options?: object): Promise<{ message_id?: number; text: string; done: boolean }>;
   setWebhook(url: string, extra?: object): Promise<boolean>;
   deleteWebhook(extra?: object): Promise<boolean>;
   getWebhookInfo(): Promise<any>;
@@ -481,7 +502,106 @@ export function paginateInlineQuery(ctx: Context, items: any[], formatterFn: (it
 
 export function albumMiddleware(options?: { windowMs?: number }): Middleware;
 
+export interface LinkPreviewOptions {
+  is_disabled?: boolean;
+  url?: string;
+  prefer_small_media?: boolean;
+  prefer_large_media?: boolean;
+  show_above_text?: boolean;
+}
+
+export class LinkPreview {
+  constructor(url?: string);
+  url(url: string): this;
+  disabled(disabled?: boolean): this;
+  disable(): this;
+  enable(): this;
+  smallMedia(small?: boolean): this;
+  largeMedia(large?: boolean): this;
+  aboveText(above?: boolean): this;
+  belowText(): this;
+  toJSON(): LinkPreviewOptions;
+  static create(url?: string): LinkPreview;
+  static disabled(): LinkPreview;
+  static small(url?: string): LinkPreview;
+  static large(url?: string): LinkPreview;
+  static above(url?: string): LinkPreview;
+}
+
+export function toTextStream(input: any): AsyncIterable<string>;
+export function streamText(
+  telegram: Telegram,
+  chatId: number | string,
+  textStream: any,
+  options?: {
+    intervalMs?: number;
+    minDeltaChars?: number;
+    useDraft?: boolean;
+    extra?: object;
+    draftId?: number;
+    initialMessage?: string;
+    onProgress?: (text: string, count: number) => void;
+    onError?: (err: Error) => void;
+  }
+): Promise<{ message_id?: number; text: string; done: boolean }>;
+
 export function validateWebAppInitData(initDataStr: string, botToken: string, options?: { maxAgeSeconds?: number }): any;
+export function parseWebAppInitData(initDataStr: string): any;
+export function createMiniAppLaunchUrl(botUsername: string, appShortName: string, startParam?: string): string;
+
+export class MiniAppLoadingScreen {
+  constructor(options?: {
+    title?: string;
+    icon?: string;
+    lightColor?: string;
+    darkColor?: string;
+    lightBg?: string;
+    darkBg?: string;
+    skeleton?: boolean;
+  });
+  setIcon(icon: string): this;
+  setTitle(title: string): this;
+  setColors(lightColor: string, darkColor: string): this;
+  setSkeleton(enabled?: boolean): this;
+  toCSS(): string;
+  toHTML(): string;
+}
+
+export function generateMiniAppLoadingScreen(options?: any): string;
+
+export const MiniApp: {
+  isInsideTelegram(): boolean;
+  webApp: any;
+  fullscreen: {
+    request(): boolean;
+    exit(): boolean;
+    isActive(): boolean;
+    onChange(callback: (isFullscreen: boolean) => void): void;
+    onFailed(callback: (err: any) => void): void;
+  };
+  motion: {
+    startAccelerometer(options?: { refresh_rate?: number }): boolean;
+    stopAccelerometer(): boolean;
+    onAccelerometer(callback: (data: { x: number; y: number; z: number }) => void): void;
+    startDeviceOrientation(options?: { refresh_rate?: number; need_absolute?: boolean }): boolean;
+    stopDeviceOrientation(): boolean;
+    onOrientation(callback: (data: { alpha: number; beta: number; gamma: number; absolute: boolean }) => void): void;
+    startGyroscope(options?: { refresh_rate?: number }): boolean;
+    stopGyroscope(): boolean;
+    onGyroscope(callback: (data: { x: number; y: number; z: number }) => void): void;
+  };
+  homeScreen: {
+    addToHomeScreen(): boolean;
+    checkStatus(callback: (status: 'unsupported' | 'unknown' | 'added' | 'missed') => void): void;
+  };
+  sharePreparedMessage(preparedMessageId: string): boolean;
+  downloadFile(params: { url: string; file_name: string }): boolean;
+  haptics: {
+    impact(style?: string): void;
+    notification(type?: string): void;
+    selection(): void;
+  };
+};
 
 export function promptMiddleware(): Middleware;
 

package/index.js

@@ -1,5 +1,5 @@
 /**
- * Telegix - Lightweight Telegram Bot API Framework
+ * Telegix - Lightweight, Pure JavaScript Telegram Bot API Framework
  * @author KazeDevID
  * @license MIT
  */
@@ -20,7 +20,16 @@ export { RateLimiter, rateLimit } from './lib/ratelimit.js';
 export { serializeMessage, serializeUpdate } from './lib/serialize.js';
 export { InlineQueryResultBuilder, paginateInlineQuery } from './lib/inline.js';
 export { albumMiddleware } from './lib/album.js';
-export { validateWebAppInitData } from './lib/webapp.js';
+export {
+  validateWebAppInitData,
+  parseWebAppInitData,
+  createMiniAppLaunchUrl,
+  MiniAppLoadingScreen,
+  generateMiniAppLoadingScreen,
+  MiniApp,
+} from './lib/webapp.js';
+export { streamText, toTextStream } from './lib/stream.js';
+export { LinkPreview } from './lib/link-preview.js';
 export { promptMiddleware } from './lib/prompt.js';
 export { escapeMarkdownV2, mdv2 } from './lib/markdownv2.js';
 export { inlineDebounceMiddleware } from './lib/inline-debounce.js';

package/lib/api.js

@@ -4,20 +4,38 @@
  */
 
 import { TelegramError, NetworkError } from './errors.js';
+import { streamText as runStreamText } from './stream.js';
 import fs from 'node:fs';
 import path from 'node:path';
 
 /**
  * Checks if value is a file/stream/buffer that needs multipart/form-data upload
  * @param {any} value
+ * @param {string} [key='']
  * @returns {boolean}
  */
-export function isUploadableFile(value) {
+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') {
+    return false;
+  }
   if (value instanceof Blob || value instanceof Uint8Array || Buffer.isBuffer(value)) return true;
-  if (typeof value === 'object' && ('source' in value || 'url' in value)) return true;
-  if (typeof value === 'object' && typeof value.pipe === 'function') return true; // Stream
+  if (typeof value === 'object') {
+    // If it's a LinkPreview or has link preview options properties, it's not a file
+    if (
+      value._options !== undefined ||
+      value.prefer_small_media !== undefined ||
+      value.prefer_large_media !== undefined ||
+      value.show_above_text !== undefined ||
+      value.is_disabled !== undefined
+    ) {
+      return false;
+    }
+    if ('source' in value) return true;
+    if (typeof value.pipe === 'function') return true; // Stream
+    if ('url' in value && key !== 'link_preview_options') return true;
+  }
   return false;
 }
 
@@ -201,6 +219,15 @@ export function normalizeTelegramPayload(payload) {
     }
   }
 
+  // 6. Handle link_preview_options and legacy disable_web_page_preview
+  if (norm.link_preview_options && typeof norm.link_preview_options.toJSON === 'function') {
+    norm.link_preview_options = norm.link_preview_options.toJSON();
+  }
+  if (norm.disable_web_page_preview !== undefined && !norm.link_preview_options) {
+    norm.link_preview_options = { is_disabled: Boolean(norm.disable_web_page_preview) };
+    delete norm.disable_web_page_preview;
+  }
+
   return norm;
 }
 
@@ -253,7 +280,7 @@ export class Telegram {
 
     // Check if any payload property is an uploadable file
     for (const key of Object.keys(normalizedPayload)) {
-      if (isUploadableFile(normalizedPayload[key])) {
+      if (isUploadableFile(normalizedPayload[key], key)) {
         hasUpload = true;
         break;
       }
@@ -269,7 +296,7 @@ export class Telegram {
       for (const [key, value] of Object.entries(normalizedPayload)) {
         if (value === undefined || value === null) continue;
 
-        if (isUploadableFile(value)) {
+        if (isUploadableFile(value, key)) {
           const { blob, filename } = await normalizeFileSource(value, key);
           if (typeof blob === 'string') {
             formData.append(key, blob);
@@ -298,6 +325,14 @@ export class Telegram {
       }
       delete cleanPayload.toJSON;
 
+      // Special Telegram API parameters that Telegram requires as JSON-serialized strings
+      const jsonStringParams = ['link_preview_options', 'reply_parameters', 'reply_markup'];
+      for (const param of jsonStringParams) {
+        if (cleanPayload[param] && typeof cleanPayload[param] === 'object') {
+          cleanPayload[param] = JSON.stringify(cleanPayload[param]);
+        }
+      }
+
       requestInit.headers = {
         'Content-Type': 'application/json',
       };
@@ -802,6 +837,13 @@ export class Telegram {
     });
   }
 
+  /**
+   * Alias for answerCallbackQuery
+   */
+  answerCbQuery(callbackQueryId, extra = {}) {
+    return this.answerCallbackQuery(callbackQueryId, extra);
+  }
+
   /**
    * Edit message text
    */
@@ -1345,20 +1387,6 @@ export class Telegram {
     });
   }
 
-  /**
-   * Save prepared inline message for mini-app sharing
-   * @param {number} userId
-   * @param {object} result - InlineQueryResult
-   * @param {object} [extra] - allow_user_chats, allow_bot_chats, allow_group_chats, allow_channel_chats
-   */
-  savePreparedInlineMessage(userId, result, extra = {}) {
-    return this.call('savePreparedInlineMessage', {
-      user_id: userId,
-      result,
-      ...extra,
-    });
-  }
-
   // ==========================================
   // Stickers & Custom Emojis
   // ==========================================
@@ -1837,4 +1865,54 @@ export class Telegram {
       ...extra,
     });
   }
+
+  /**
+   * Save a prepared inline message for a Telegram Mini App user (Bot API 8.0+)
+   * @param {number} userId - Unique identifier of target user who can send the message
+   * @param {object} result - InlineQueryResult object describing the message to be sent
+   * @param {object} [options] - Allowed chats options (allow_user_chats, allow_bot_chats, allow_group_chats, allow_channel_chats)
+   * @returns {Promise<{ id: string, expiration_date: number }>}
+   */
+  savePreparedInlineMessage(userId, result, options = {}) {
+    if (!userId) {
+      throw new Error('Telegram.savePreparedInlineMessage(userId, result) requires a valid userId.');
+    }
+    if (!result) {
+      throw new Error('Telegram.savePreparedInlineMessage(userId, result) requires a valid result object.');
+    }
+
+    const payload = {
+      user_id: userId,
+      result: typeof result.toJSON === 'function' ? result.toJSON() : result,
+      allow_user_chats: options.allow_user_chats ?? true,
+      allow_bot_chats: options.allow_bot_chats ?? true,
+      allow_group_chats: options.allow_group_chats ?? true,
+      allow_channel_chats: options.allow_channel_chats ?? true,
+      ...options,
+    };
+
+    return this.call('savePreparedInlineMessage', payload);
+  }
+
+  /**
+   * Stream text response into a Telegram chat with throttling, token buffering, and rate limit protection
+   * @param {number|string} chatId
+   * @param {AsyncIterable<string>|Iterable<string>|ReadableStream|Array<string>} textStream
+   * @param {object} [options]
+   * @returns {Promise<{ message_id?: number, text: string, done: boolean }>}
+   */
+  streamText(chatId, textStream, options = {}) {
+    return runStreamText(this, chatId, textStream, options);
+  }
+
+  /**
+   * Stream live draft response into a Telegram chat (using Bot API live draft updates)
+   * @param {number|string} chatId
+   * @param {AsyncIterable<string>|Iterable<string>|ReadableStream|Array<string>} textStream
+   * @param {object} [options]
+   * @returns {Promise<{ message_id?: number, text: string, done: boolean }>}
+   */
+  streamDraft(chatId, textStream, options = {}) {
+    return runStreamText(this, chatId, textStream, { ...options, useDraft: true });
+  }
 }

package/lib/context.js

@@ -4,6 +4,9 @@
  */
 
 import { serializeMessage, serializeUpdate } from './serialize.js';
+import { escapeHtml } from './format.js';
+import { validateWebAppInitData } from './webapp.js';
+import { LinkPreview } from './link-preview.js';
 
 export class Context {
   /**
@@ -505,6 +508,15 @@ export class Context {
     });
   }
 
+  /**
+   * Answer callback query (alias for answerCallbackQuery)
+   * @param {string} [text]
+   * @param {object} [options]
+   */
+  answerCbQuery(text = '', options = {}) {
+    return this.answerCallbackQuery(text, options);
+  }
+
   /**
    * Answer inline query
    * @param {Array<object>} results
@@ -967,4 +979,103 @@ export class Context {
     }
     return this.telegram.setManagedBotAccessSettings(userId, settings);
   }
+
+  /**
+   * Stream text response to the current chat with rate-limit protection and token buffering
+   * @param {AsyncIterable<string>|Iterable<string>|ReadableStream|Array<string>} textStream
+   * @param {object} [options]
+   * @returns {Promise<{ message_id?: number, text: string, done: boolean }>}
+   */
+  streamText(textStream, options = {}) {
+    return this.telegram.streamText(this._assertChat(), textStream, options);
+  }
+
+  /**
+   * Stream live draft response to the current chat
+   * @param {AsyncIterable<string>|Iterable<string>|ReadableStream|Array<string>} textStream
+   * @param {object} [options]
+   * @returns {Promise<{ message_id?: number, text: string, done: boolean }>}
+   */
+  streamDraft(textStream, options = {}) {
+    return this.telegram.streamDraft(this._assertChat(), textStream, options);
+  }
+
+  /**
+   * Reply with customizable link preview options (Bot API 7.0+)
+   * @param {string} text
+   * @param {LinkPreview|object} linkPreviewOptions
+   * @param {object} [extra]
+   */
+  replyWithLinkPreview(text, linkPreviewOptions, extra = {}) {
+    const previewOptions = typeof linkPreviewOptions?.toJSON === 'function'
+      ? linkPreviewOptions.toJSON()
+      : linkPreviewOptions;
+    return this.reply(text, {
+      link_preview_options: previewOptions,
+      ...extra,
+    });
+  }
+
+  /**
+   * Reply with collapsible quote blockquote (HTML format)
+   * @param {string} text - Quoted text content
+   * @param {object} [extra]
+   */
+  replyWithCollapsibleQuote(text, extra = {}) {
+    const formatted = `<blockquote expandable>${escapeHtml(text)}</blockquote>`;
+    return this.reply(formatted, {
+      parse_mode: 'HTML',
+      ...extra,
+    });
+  }
+
+  /**
+   * Reply with expandable quote blockquote (alias for replyWithCollapsibleQuote)
+   * @param {string} text
+   * @param {object} [extra]
+   */
+  replyWithExpandableQuote(text, extra = {}) {
+    return this.replyWithCollapsibleQuote(text, extra);
+  }
+
+  /**
+   * Save a prepared inline message for the current user (Bot API 8.0+)
+   * @param {object} result - InlineQueryResult object
+   * @param {object} [options]
+   * @returns {Promise<{ id: string, expiration_date: number }>}
+   */
+  savePreparedInlineMessage(result, options = {}) {
+    if (!this.userId) {
+      throw new Error('Telegix Context: savePreparedInlineMessage() requires user context.');
+    }
+    return this.telegram.savePreparedInlineMessage(this.userId, result, options);
+  }
+
+  /**
+   * Validate Web App initData string with the bot token
+   * @param {string} initDataStr
+   * @param {object} [options]
+   * @returns {object|null}
+   */
+  validateWebAppInitData(initDataStr, options = {}) {
+    return validateWebAppInitData(initDataStr, this.telegram.token, options);
+  }
+
+  /**
+   * Reply with a message containing a Telegram Mini App button
+   * @param {string} text
+   * @param {string} webAppUrl
+   * @param {string} [buttonText='Open App']
+   * @param {object} [extra]
+   */
+  replyWithWebApp(text, webAppUrl, buttonText = 'Open App', extra = {}) {
+    return this.reply(text, {
+      reply_markup: {
+        inline_keyboard: [
+          [{ text: buttonText, web_app: { url: webAppUrl } }],
+        ],
+      },
+      ...extra,
+    });
+  }
 }

package/lib/format.js

@@ -47,6 +47,8 @@ export const html = {
   customEmoji: (text, customEmojiId) => `<tg-emoji emoji-id="${customEmojiId}">${escapeHtml(text)}</tg-emoji>`,
   quote: (text) => `<blockquote>${escapeHtml(text)}</blockquote>`,
   expandableBlockquote: (text) => `<blockquote expandable>${escapeHtml(text)}</blockquote>`,
+  expandableQuote: (text) => `<blockquote expandable>${escapeHtml(text)}</blockquote>`,
+  collapsibleQuote: (text) => `<blockquote expandable>${escapeHtml(text)}</blockquote>`,
 };
 
 /**
@@ -66,6 +68,8 @@ export const markdown = {
   customEmoji: (text, customEmojiId) => `![${escapeMarkdown(text)}](tg://emoji?id=${customEmojiId})`,
   quote: (text) => text.split('\n').map((line) => `>${escapeMarkdown(line)}`).join('\n'),
   expandableBlockquote: (text) => `**>${escapeMarkdown(text)}||`,
+  expandableQuote: (text) => `**>${escapeMarkdown(text)}||`,
+  collapsibleQuote: (text) => `**>${escapeMarkdown(text)}||`,
 };
 
 /**
@@ -107,6 +111,8 @@ fmt.mention = html.mention;
 fmt.customEmoji = html.customEmoji;
 fmt.quote = html.quote;
 fmt.expandableBlockquote = html.expandableBlockquote;
+fmt.expandableQuote = html.expandableQuote;
+fmt.collapsibleQuote = html.collapsibleQuote;
 fmt.escape = escapeHtml;
 fmt.html = html;
 fmt.markdown = markdown;