telegix 1.1.1

package/lib/errors.js

@@ -0,0 +1,67 @@
+/**
+ * Telegix - Telegram Bot API Error Classes
+ * @module telegix/errors
+ */
+
+export class TelegixError extends Error {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message);
+    this.name = 'TelegixError';
+  }
+}
+
+export class TelegramError extends TelegixError {
+  /**
+   * @param {object} response - Telegram API response
+   * @param {number} [response.error_code] - HTTP/Telegram error code (e.g. 400, 401, 403, 404, 429)
+   * @param {string} [response.description] - Description from Telegram
+   * @param {object} [response.parameters] - Extra parameters (e.g. retry_after, migrate_to_chat_id)
+   * @param {string} [method] - The Telegram method that was called
+   * @param {object} [payload] - The payload that was sent
+   */
+  constructor(response, method = '', payload = {}) {
+    const errorCode = response?.error_code || 500;
+    const description = response?.description || 'Unknown Telegram API Error';
+    super(`Telegram API Error [${errorCode}]: ${description} (Method: ${method})`);
+    this.name = 'TelegramError';
+    this.errorCode = errorCode;
+    this.description = description;
+    this.parameters = response?.parameters || {};
+    this.method = method;
+    this.payload = payload;
+
+    if (this.parameters.retry_after) {
+      this.retryAfter = this.parameters.retry_after;
+    }
+    if (this.parameters.migrate_to_chat_id) {
+      this.migrateToChatId = this.parameters.migrate_to_chat_id;
+    }
+  }
+}
+
+export class NetworkError extends TelegixError {
+  /**
+   * @param {Error} error - Underlying network error
+   * @param {string} [method] - The Telegram method
+   */
+  constructor(error, method = '') {
+    super(`Network Error while calling ${method}: ${error.message}`);
+    this.name = 'NetworkError';
+    this.cause = error;
+    this.method = method;
+  }
+}
+
+export class PollingError extends TelegixError {
+  /**
+   * @param {Error} error - Original error
+   */
+  constructor(error) {
+    super(`Polling Error: ${error.message}`);
+    this.name = 'PollingError';
+    this.cause = error;
+  }
+}

package/lib/format.js

@@ -0,0 +1,115 @@
+/**
+ * Telegix - Text Formatting Engine (HTML & MarkdownV2)
+ * @module telegix/format
+ */
+
+/**
+ * Escape HTML special characters for Telegram Bot API
+ * @param {string} text
+ * @returns {string}
+ */
+export function escapeHtml(text) {
+  if (text === null || text === undefined) return '';
+  return String(text)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Escape MarkdownV2 special characters for Telegram Bot API
+ * Characters: _ * [ ] ( ) ~ ` > # + - = | { } . !
+ * @param {string} text
+ * @returns {string}
+ */
+export function escapeMarkdown(text) {
+  if (text === null || text === undefined) return '';
+  return String(text).replace(/([_*\[\]()~`>#+\-=|{}.!\\])/g, '\\$1');
+}
+
+/**
+ * HTML Formatting Helpers
+ */
+export const html = {
+  escape: escapeHtml,
+  bold: (text) => `<b>${escapeHtml(text)}</b>`,
+  italic: (text) => `<i>${escapeHtml(text)}</i>`,
+  underline: (text) => `<u>${escapeHtml(text)}</u>`,
+  strikethrough: (text) => `<s>${escapeHtml(text)}</s>`,
+  spoiler: (text) => `<span class="tg-spoiler">${escapeHtml(text)}</span>`,
+  code: (text) => `<code>${escapeHtml(text)}</code>`,
+  pre: (codeText, language = '') => {
+    const langAttr = language ? ` class="language-${escapeHtml(language)}"` : '';
+    return `<pre><code${langAttr}>${escapeHtml(codeText)}</code></pre>`;
+  },
+  link: (text, url) => `<a href="${escapeHtml(url)}">${escapeHtml(text)}</a>`,
+  mention: (text, userId) => `<a href="tg://user?id=${userId}">${escapeHtml(text)}</a>`,
+  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>`,
+};
+
+/**
+ * MarkdownV2 Formatting Helpers
+ */
+export const markdown = {
+  escape: escapeMarkdown,
+  bold: (text) => `*${escapeMarkdown(text)}*`,
+  italic: (text) => `_${escapeMarkdown(text)}_`,
+  underline: (text) => `__${escapeMarkdown(text)}__`,
+  strikethrough: (text) => `~${escapeMarkdown(text)}~`,
+  spoiler: (text) => `||${escapeMarkdown(text)}||`,
+  code: (text) => `\`${escapeMarkdown(text)}\``,
+  pre: (codeText, language = '') => `\`\`\`${language}\n${codeText.replace(/\\/g, '\\\\').replace(/`/g, '\\`')}\n\`\`\``,
+  link: (text, url) => `[${escapeMarkdown(text)}](${url.replace(/([)\\])/g, '\\$1')})`,
+  mention: (text, userId) => `[${escapeMarkdown(text)}](tg://user?id=${userId})`,
+  customEmoji: (text, customEmojiId) => `![${escapeMarkdown(text)}](tg://emoji?id=${customEmojiId})`,
+  quote: (text) => text.split('\n').map((line) => `>${escapeMarkdown(line)}`).join('\n'),
+  expandableBlockquote: (text) => `**>${escapeMarkdown(text)}||`,
+};
+
+/**
+ * Tagged template literal for safe HTML formatting
+ * Example: fmt`Hello <b>${username}</b>! Your balance is ${100} Stars.`
+ * @param {TemplateStringsArray} strings
+ * @param {...any} values
+ * @returns {string}
+ */
+export function fmt(strings, ...values) {
+  let result = '';
+  for (let i = 0; i < strings.length; i++) {
+    result += strings[i];
+    if (i < values.length) {
+      const val = values[i];
+      // If it's already an HTML string with formatting or null/undefined
+      if (val === null || val === undefined) {
+        // do nothing
+      } else if (typeof val === 'object' && val.rawHtml) {
+        result += val.rawHtml;
+      } else {
+        result += escapeHtml(String(val));
+      }
+    }
+  }
+  return result;
+}
+
+// Attach helper methods directly to fmt
+fmt.bold = html.bold;
+fmt.italic = html.italic;
+fmt.underline = html.underline;
+fmt.strikethrough = html.strikethrough;
+fmt.spoiler = html.spoiler;
+fmt.code = html.code;
+fmt.pre = html.pre;
+fmt.link = html.link;
+fmt.mention = html.mention;
+fmt.customEmoji = html.customEmoji;
+fmt.quote = html.quote;
+fmt.expandableBlockquote = html.expandableBlockquote;
+fmt.escape = escapeHtml;
+fmt.html = html;
+fmt.markdown = markdown;
+fmt.raw = (str) => ({ rawHtml: String(str) });
+
+export const Format = fmt;

package/lib/i18n.js

@@ -0,0 +1,158 @@
+/**
+ * Telegix - Internationalization (i18n) Middleware & Helper
+ * @module telegix/i18n
+ */
+
+function getNestedValue(obj, path) {
+  if (!obj || typeof obj !== 'object') return undefined;
+  if (obj[path] !== undefined) return obj[path];
+  
+  const keys = path.split('.');
+  let current = obj;
+  for (const k of keys) {
+    if (current && typeof current === 'object' && k in current) {
+      current = current[k];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+export class I18n {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.defaultLocale='en']
+   * @param {object} [options.translations={}]
+   * @param {Function} [options.localeFn]
+   * @param {boolean} [options.useSession=true]
+   */
+  constructor(options = {}) {
+    this.defaultLocale = options.defaultLocale || 'en';
+    this.translations = options.translations || {};
+    this.useSession = options.useSession !== false;
+    this.localeFn =
+      options.localeFn ||
+      ((ctx) => {
+        if (this.useSession && ctx.session) {
+          const sessionLocale = ctx.session.__locale || ctx.session.locale || ctx.session.language;
+          if (sessionLocale) return sessionLocale;
+        }
+        return ctx.from?.language_code || this.defaultLocale;
+      });
+  }
+
+  /**
+   * Register or add translations for a locale
+   * @param {string} locale
+   * @param {object} dict
+   */
+  addTranslation(locale, dict) {
+    this.translations[locale] = {
+      ...(this.translations[locale] || {}),
+      ...dict,
+    };
+    return this;
+  }
+
+  /**
+   * Add multiple translation dictionaries
+   * @param {Record<string, object>} translations
+   */
+  addTranslations(translations = {}) {
+    for (const [locale, dict] of Object.entries(translations)) {
+      this.addTranslation(locale, dict);
+    }
+    return this;
+  }
+
+  /**
+   * Translate a key with optional interpolation params and pluralization
+   * @param {string} locale
+   * @param {string} key
+   * @param {object} [params]
+   * @returns {string}
+   */
+  t(locale, key, params = {}) {
+    const activeDict = this.translations[locale] || {};
+    const defaultDict = this.translations[this.defaultLocale] || {};
+
+    let val = getNestedValue(activeDict, key);
+    if (val === undefined) {
+      val = getNestedValue(defaultDict, key);
+    }
+    if (val === undefined) {
+      val = key;
+    }
+
+    // Handle pluralization if val is an object (e.g. { one: '1 item', other: '{{count}} items' })
+    if (typeof val === 'object' && val !== null) {
+      const count = Number(params.count);
+      if (!isNaN(count)) {
+        if (count === 0 && val.zero) {
+          val = val.zero;
+        } else if (count === 1 && val.one) {
+          val = val.one;
+        } else if (val.other) {
+          val = val.other;
+        } else {
+          val = JSON.stringify(val);
+        }
+      } else {
+        val = JSON.stringify(val);
+      }
+    }
+
+    let text = String(val);
+
+    // Interpolate variables like {{name}} or {name}
+    for (const [k, v] of Object.entries(params)) {
+      text = text.replace(new RegExp(`{{\\s*${k}\\s*}}`, 'g'), String(v));
+      text = text.replace(new RegExp(`{\\s*${k}\\s*}`, 'g'), String(v));
+    }
+
+    return text;
+  }
+
+  /**
+   * Create i18n middleware for Telegix
+   */
+  middleware() {
+    return (ctx, next) => {
+      let rawLocale = this.localeFn(ctx) || this.defaultLocale;
+      // If locale like 'en-US' or 'id-ID', check exact first, then language prefix
+      let activeLocale = this.defaultLocale;
+      if (this.translations[rawLocale]) {
+        activeLocale = rawLocale;
+      } else {
+        const prefix = String(rawLocale).split('-')[0].toLowerCase();
+        if (this.translations[prefix]) {
+          activeLocale = prefix;
+        }
+      }
+
+      const self = this;
+      const i18nContext = {
+        get locale() {
+          return activeLocale;
+        },
+        set locale(newLocale) {
+          activeLocale = newLocale;
+          if (self.useSession && ctx.session) {
+            ctx.session.__locale = newLocale;
+          }
+        },
+        setLocale(newLocale) {
+          this.locale = newLocale;
+          return activeLocale;
+        },
+        t: (key, params) => self.t(activeLocale, key, params),
+      };
+
+      ctx.i18n = i18nContext;
+      ctx.t = (key, params) => i18nContext.t(key, params);
+
+      return next();
+    };
+  }
+}

package/lib/inline-debounce.js

@@ -0,0 +1,49 @@
+/**
+ * Telegix - Inline Query Debouncer & Cache Helper
+ */
+
+const queryCache = new Map();
+const debounceTimers = new Map();
+
+/**
+ * Middleware or helper to debounce inline queries and cache results
+ * @param {object} [options] - { windowMs?: number, cacheTtlMs?: number }
+ */
+export function inlineDebounceMiddleware(options = {}) {
+  const windowMs = options.windowMs || 300;
+  const cacheTtlMs = options.cacheTtlMs || 60000;
+
+  return async (ctx, next) => {
+    if (!ctx.inlineQuery) {
+      return next();
+    }
+
+    const userId = ctx.from?.id;
+    const query = ctx.inlineQuery.query || '';
+    if (!userId) return next();
+
+    const cacheKey = `${userId}:${query}`;
+    const now = Date.now();
+
+    // Check cache
+    if (queryCache.has(cacheKey)) {
+      const cached = queryCache.get(cacheKey);
+      if (now - cached.timestamp < cacheTtlMs) {
+        return ctx.answerInlineQuery(cached.results, cached.options);
+      } else {
+        queryCache.delete(cacheKey);
+      }
+    }
+
+    // Attach cache helper to ctx
+    ctx.cacheInlineResults = (results, extraOptions = {}) => {
+      queryCache.set(cacheKey, {
+        results,
+        options: extraOptions,
+        timestamp: Date.now(),
+      });
+    };
+
+    return next();
+  };
+}

package/lib/inline.js

@@ -0,0 +1,79 @@
+/**
+ * Telegix - Inline Query Pagination & Result Builders
+ */
+
+export class InlineQueryResultBuilder {
+  static article(id, title, messageText, options = {}) {
+    return {
+      type: 'article',
+      id: String(id),
+      title,
+      input_message_content: {
+        message_text: messageText,
+        parse_mode: options.parseMode || 'HTML',
+        ...options.inputMessageContent,
+      },
+      description: options.description,
+      thumb_url: options.thumbUrl,
+      thumb_width: options.thumbWidth,
+      thumb_height: options.thumbHeight,
+      reply_markup: options.replyMarkup,
+    };
+  }
+
+  static photo(id, photoUrl, options = {}) {
+    return {
+      type: 'photo',
+      id: String(id),
+      photo_url: photoUrl,
+      thumb_url: options.thumbUrl || photoUrl,
+      caption: options.caption,
+      parse_mode: options.parseMode || 'HTML',
+      caption_entities: options.captionEntities,
+      description: options.description,
+      title: options.title,
+      reply_markup: options.replyMarkup,
+      photo_width: options.photoWidth,
+      photo_height: options.photoHeight,
+    };
+  }
+
+  static document(id, documentUrl, title, options = {}) {
+    return {
+      type: 'document',
+      id: String(id),
+      title,
+      document_url: documentUrl,
+      mime_type: options.mimeType || 'application/pdf',
+      caption: options.caption,
+      description: options.description,
+      reply_markup: options.replyMarkup,
+    };
+  }
+}
+
+/**
+ * Helper to paginate and answer inline queries easily
+ * @param {object} ctx - Context
+ * @param {Array} items - All items to paginate
+ * @param {Function} formatterFn - Function(item, index) returning InlineQueryResult
+ * @param {object} [options] - { limit: 10, cacheTime: 300, isPersonal: true }
+ */
+export async function paginateInlineQuery(ctx, items, formatterFn, options = {}) {
+  const limit = options.limit || 10;
+  const cacheTime = options.cacheTime !== undefined ? options.cacheTime : 300;
+  const isPersonal = options.isPersonal !== undefined ? options.isPersonal : true;
+
+  const offset = parseInt(ctx.inlineQuery?.offset || '0', 10) || 0;
+  const pageItems = items.slice(offset, offset + limit);
+
+  const results = pageItems.map((item, index) => formatterFn(item, offset + index));
+  const nextOffset = offset + limit < items.length ? String(offset + limit) : '';
+
+  return ctx.answerInlineQuery(results, {
+    next_offset: nextOffset,
+    cache_time: cacheTime,
+    is_personal: isPersonal,
+    ...options.extra,
+  });
+}

package/lib/markdownv2.js

@@ -0,0 +1,29 @@
+/**
+ * Telegix - MarkdownV2 Escape Utility
+ */
+
+/**
+ * Escapes special characters for Telegram MarkdownV2 format.
+ * Characters to escape: _ * [ ] ( ) ~ ` > # + - = | { } . !
+ * @param {string} str - Raw text string to escape
+ * @returns {string} Escaped string safe for MarkdownV2
+ */
+export function escapeMarkdownV2(str) {
+  if (typeof str !== 'string') return '';
+  return str.replace(/[_*[\]()~`>#+\-=|{}.!]/g, '\\$&');
+}
+
+/**
+ * Helper to build safe MarkdownV2 snippets
+ */
+export const mdv2 = {
+  escape: escapeMarkdownV2,
+  bold: (text) => `*${escapeMarkdownV2(text)}*`,
+  italic: (text) => `_${escapeMarkdownV2(text)}_`,
+  underline: (text) => `__${escapeMarkdownV2(text)}__`,
+  strikethrough: (text) => `~${escapeMarkdownV2(text)}~`,
+  spoiler: (text) => `||${escapeMarkdownV2(text)}||`,
+  code: (text) => `\`${text.replace(/`/g, '\\`')}\``,
+  pre: (text, language = '') => `\`\`\`${language}\n${text}\n\`\`\``,
+  link: (text, url) => `[${escapeMarkdownV2(text)}](${url})`,
+};