telegix 1.1.1 → 1.1.2

package/lib/link-preview.js

@@ -0,0 +1,256 @@
+/**
+ * Telegix - Adjustable Link Preview Builder (Bot API 7.0+)
+ * Provides fluent options to control link preview rendering, media size,
+ * positioning above/below text, or disabling link previews.
+ * @module telegix/link-preview
+ */
+
+export class LinkPreview {
+  /**
+   * @param {object} [options]
+   * @param {boolean} [options.is_disabled]
+   * @param {string} [options.url]
+   * @param {boolean} [options.prefer_small_media]
+   * @param {boolean} [options.prefer_large_media]
+   * @param {boolean} [options.show_above_text]
+   */
+  constructor(options = {}) {
+    this._options = { ...options };
+  }
+
+  /**
+   * Disable the link preview entirely
+   * @param {boolean} [disabled=true]
+   * @returns {this}
+   */
+  disable(disabled = true) {
+    if (disabled) {
+      this._options.is_disabled = true;
+    } else {
+      delete this._options.is_disabled;
+    }
+    return this;
+  }
+
+  /**
+   * Set specific URL to preview
+   * @param {string} url
+   * @returns {this}
+   */
+  url(url) {
+    this._options.url = String(url);
+    return this;
+  }
+
+  /**
+   * Shrink preview media into a small square thumbnail
+   * @param {boolean} [prefer=true]
+   * @returns {this}
+   */
+  smallMedia(prefer = true) {
+    if (prefer) {
+      this._options.prefer_small_media = true;
+      delete this._options.prefer_large_media;
+    } else {
+      delete this._options.prefer_small_media;
+    }
+    return this;
+  }
+
+  /**
+   * Expand preview media into a large preview card
+   * @param {boolean} [prefer=true]
+   * @returns {this}
+   */
+  largeMedia(prefer = true) {
+    if (prefer) {
+      this._options.prefer_large_media = true;
+      delete this._options.prefer_small_media;
+    } else {
+      delete this._options.prefer_large_media;
+    }
+    return this;
+  }
+
+  /**
+   * Position the link preview card ABOVE the message text
+   * @param {boolean} [above=true]
+   * @returns {this}
+   */
+  showAbove(above = true) {
+    if (above) {
+      this._options.show_above_text = true;
+    } else {
+      delete this._options.show_above_text;
+    }
+    return this;
+  }
+
+  /**
+   * Position the link preview card ABOVE the message text (alias)
+   * @param {boolean} [above=true]
+   * @returns {this}
+   */
+  aboveText(above = true) {
+    return this.showAbove(above);
+  }
+
+  /**
+   * Position the link preview card BELOW the message text
+   * @param {boolean} [below=true]
+   * @returns {this}
+   */
+  showBelow(below = true) {
+    if (below) {
+      delete this._options.show_above_text;
+    } else {
+      this._options.show_above_text = true;
+    }
+    return this;
+  }
+
+  /**
+   * Position the link preview card BELOW the message text (alias)
+   * @param {boolean} [below=true]
+   * @returns {this}
+   */
+  belowText(below = true) {
+    return this.showBelow(below);
+  }
+
+  /**
+   * Disable the link preview entirely (alias)
+   * @param {boolean} [disabled=true]
+   * @returns {this}
+   */
+  disabled(disabled = true) {
+    return this.disable(disabled);
+  }
+
+  /**
+   * Enable the link preview
+   * @returns {this}
+   */
+  enable() {
+    return this.disable(false);
+  }
+
+  /**
+   * Returns LinkPreviewOptions payload object
+   * @returns {object}
+   */
+  toJSON() {
+    const res = {};
+    if (this._options.is_disabled !== undefined && this._options.is_disabled !== null) {
+      res.is_disabled = Boolean(this._options.is_disabled);
+    }
+    if (this._options.url) {
+      res.url = String(this._options.url);
+    }
+    if (this._options.prefer_small_media) {
+      res.prefer_small_media = true;
+    }
+    if (this._options.prefer_large_media) {
+      res.prefer_large_media = true;
+    }
+    if (this._options.show_above_text) {
+      res.show_above_text = true;
+    }
+    return res;
+  }
+
+  /**
+   * Wraps as Telegram extra parameter
+   * @returns {{ link_preview_options: object }}
+   */
+  toExtra() {
+    return {
+      link_preview_options: this.toJSON(),
+    };
+  }
+
+  // --- Static Factory Methods ---
+
+  /**
+   * Create LinkPreview builder instance
+   * @param {string|object} [urlOrOptions]
+   * @param {object} [options]
+   * @returns {LinkPreview}
+   */
+  static create(urlOrOptions, options = {}) {
+    if (typeof urlOrOptions === 'string') {
+      const lp = new LinkPreview(options);
+      lp.url(urlOrOptions);
+      return lp;
+    }
+    if (typeof urlOrOptions === 'object' && urlOrOptions !== null) {
+      return new LinkPreview({ ...urlOrOptions, ...options });
+    }
+    return new LinkPreview(options);
+  }
+
+  /**
+   * Create LinkPreview with options
+   * @param {object} options
+   * @returns {LinkPreview}
+   */
+  static options(options = {}) {
+    return new LinkPreview(options);
+  }
+
+  /**
+   * Create disabled link preview options
+   * @returns {LinkPreview}
+   */
+  static disabled() {
+    return new LinkPreview({ is_disabled: true });
+  }
+
+  /**
+   * Create link preview with small media thumbnail
+   * @param {string} [url]
+   * @param {boolean} [showAbove=false]
+   * @returns {LinkPreview}
+   */
+  static small(url, showAbove = false) {
+    const lp = new LinkPreview({ prefer_small_media: true, show_above_text: Boolean(showAbove) });
+    if (url) lp.url(url);
+    return lp;
+  }
+
+  /**
+   * Create link preview with large media card
+   * @param {string} [url]
+   * @param {boolean} [showAbove=false]
+   * @returns {LinkPreview}
+   */
+  static large(url, showAbove = false) {
+    const lp = new LinkPreview({ prefer_large_media: true, show_above_text: Boolean(showAbove) });
+    if (url) lp.url(url);
+    return lp;
+  }
+
+  /**
+   * Create link preview positioned above message text
+   * @param {string} [url]
+   * @param {object} [options]
+   * @returns {LinkPreview}
+   */
+  static above(url, options = {}) {
+    const lp = new LinkPreview({ show_above_text: true, ...options });
+    if (url) lp.url(url);
+    return lp;
+  }
+
+  /**
+   * Create link preview positioned below message text
+   * @param {string} [url]
+   * @param {object} [options]
+   * @returns {LinkPreview}
+   */
+  static below(url, options = {}) {
+    const lp = new LinkPreview({ show_above_text: false, ...options });
+    if (url) lp.url(url);
+    return lp;
+  }
+}

package/lib/markdownv2.js

@@ -26,4 +26,7 @@ export const mdv2 = {
   code: (text) => `\`${text.replace(/`/g, '\\`')}\``,
   pre: (text, language = '') => `\`\`\`${language}\n${text}\n\`\`\``,
   link: (text, url) => `[${escapeMarkdownV2(text)}](${url})`,
+  quote: (text) => text.split('\n').map((line) => `>${escapeMarkdownV2(line)}`).join('\n'),
+  expandableQuote: (text) => `**>${escapeMarkdownV2(text)}||`,
+  collapsibleQuote: (text) => `**>${escapeMarkdownV2(text)}||`,
 };

package/lib/markup.js

@@ -170,22 +170,134 @@ export class Markup {
     /**
      * Standard text button for reply keyboard
      * @param {string} text
+     * @param {object} [options]
      */
-    text: (text) => ({ text }),
+    text: (text, options = {}) => ({ text, ...options }),
 
     /**
      * Inline callback button
      * @param {string} text
-     * @param {string} data
+     * @param {string|number} data
+     * @param {object} [options]
      */
-    callback: (text, data) => ({ text, callback_data: String(data) }),
+    callback: (text, data, options = {}) => ({ text, callback_data: String(data), ...options }),
 
     /**
      * Inline URL button
      * @param {string} text
      * @param {string} url
+     * @param {object} [options]
+     */
+    url: (text, url, options = {}) => ({ text, url, ...options }),
+
+    /**
+     * Primary colored button (Blue / Main Action - Bot API 9.4+)
+     * @param {string} text
+     * @param {string|number|object} [dataOrUrl]
+     * @param {object} [options]
+     */
+    primary: (text, dataOrUrl, options = {}) => {
+      let base = {};
+      if (typeof dataOrUrl === 'string') {
+        if (/^(https?:\/\/|tg:\/\/)/i.test(dataOrUrl)) {
+          base = { url: dataOrUrl };
+        } else {
+          base = { callback_data: dataOrUrl };
+        }
+      } else if (typeof dataOrUrl === 'number') {
+        base = { callback_data: String(dataOrUrl) };
+      } else if (typeof dataOrUrl === 'object' && dataOrUrl !== null) {
+        base = dataOrUrl;
+      }
+      return {
+        text,
+        style: 'primary',
+        ...base,
+        ...options,
+      };
+    },
+
+    /**
+     * Danger colored button (Red / Destructive Action - Bot API 9.4+)
+     * @param {string} text
+     * @param {string|number|object} [dataOrUrl]
+     * @param {object} [options]
+     */
+    danger: (text, dataOrUrl, options = {}) => {
+      let base = {};
+      if (typeof dataOrUrl === 'string') {
+        if (/^(https?:\/\/|tg:\/\/)/i.test(dataOrUrl)) {
+          base = { url: dataOrUrl };
+        } else {
+          base = { callback_data: dataOrUrl };
+        }
+      } else if (typeof dataOrUrl === 'number') {
+        base = { callback_data: String(dataOrUrl) };
+      } else if (typeof dataOrUrl === 'object' && dataOrUrl !== null) {
+        base = dataOrUrl;
+      }
+      return {
+        text,
+        style: 'danger',
+        ...base,
+        ...options,
+      };
+    },
+
+    /**
+     * Success colored button (Green / Positive Action - Bot API 9.4+)
+     * @param {string} text
+     * @param {string|number|object} [dataOrUrl]
+     * @param {object} [options]
+     */
+    success: (text, dataOrUrl, options = {}) => {
+      let base = {};
+      if (typeof dataOrUrl === 'string') {
+        if (/^(https?:\/\/|tg:\/\/)/i.test(dataOrUrl)) {
+          base = { url: dataOrUrl };
+        } else {
+          base = { callback_data: dataOrUrl };
+        }
+      } else if (typeof dataOrUrl === 'number') {
+        base = { callback_data: String(dataOrUrl) };
+      } else if (typeof dataOrUrl === 'object' && dataOrUrl !== null) {
+        base = dataOrUrl;
+      }
+      return {
+        text,
+        style: 'success',
+        ...base,
+        ...options,
+      };
+    },
+
+    /**
+     * Generic colored button helper (Bot API 9.4+)
+     * @param {string} text
+     * @param {'primary'|'danger'|'success'} style
+     * @param {string|number|object} [dataOrUrl]
+     * @param {object} [options]
      */
-    url: (text, url) => ({ text, url }),
+    colored: (text, style, dataOrUrl, options = {}) => {
+      let base = {};
+      if (typeof dataOrUrl === 'string') {
+        if (/^(https?:\/\/|tg:\/\/)/i.test(dataOrUrl)) {
+          base = { url: dataOrUrl };
+        } else {
+          base = { callback_data: dataOrUrl };
+        }
+      } else if (typeof dataOrUrl === 'number') {
+        base = { callback_data: String(dataOrUrl) };
+      } else if (typeof dataOrUrl === 'object' && dataOrUrl !== null) {
+        base = dataOrUrl;
+      }
+      return {
+        text,
+        style,
+        ...base,
+        ...options,
+      };
+    },
 
     /**
      * Web App button

package/lib/rich.js

@@ -171,6 +171,15 @@ export class RichMessageBuilder {
     return this.quote(text, true);
   }
 
+  /**
+   * Add a collapsible / expandable blockquote (alias)
+   * @param {string} text
+   * @returns {this}
+   */
+  collapsibleQuote(text) {
+    return this.quote(text, true);
+  }
+
   /**
    * Add spoiler block
    * @param {string} text
@@ -370,6 +379,51 @@ export class RichMessageBuilder {
     return this.button(Markup.button.url(text, url));
   }
 
+  /**
+   * Add primary colored button (Blue - Bot API 9.4+)
+   * @param {string} text
+   * @param {string|number|object} dataOrUrl
+   * @param {object} [options]
+   * @returns {this}
+   */
+  primary(text, dataOrUrl, options = {}) {
+    return this.button(Markup.button.primary(text, dataOrUrl, options));
+  }
+
+  /**
+   * Add danger colored button (Red - Bot API 9.4+)
+   * @param {string} text
+   * @param {string|number|object} dataOrUrl
+   * @param {object} [options]
+   * @returns {this}
+   */
+  danger(text, dataOrUrl, options = {}) {
+    return this.button(Markup.button.danger(text, dataOrUrl, options));
+  }
+
+  /**
+   * Add success colored button (Green - Bot API 9.4+)
+   * @param {string} text
+   * @param {string|number|object} dataOrUrl
+   * @param {object} [options]
+   * @returns {this}
+   */
+  success(text, dataOrUrl, options = {}) {
+    return this.button(Markup.button.success(text, dataOrUrl, options));
+  }
+
+  /**
+   * Add generic colored button (Bot API 9.4+)
+   * @param {string} text
+   * @param {'primary'|'danger'|'success'} style
+   * @param {string|number|object} dataOrUrl
+   * @param {object} [options]
+   * @returns {this}
+   */
+  colored(text, style, dataOrUrl, options = {}) {
+    return this.button(Markup.button.colored(text, style, dataOrUrl, options));
+  }
+
   /**
    * Add Bot API 10.3 disabled button
    * @param {string} text