telegix 1.1.1

package/lib/markup.js

@@ -0,0 +1,321 @@
+/**
+ * Telegix - Keyboard & Markup Builder
+ * @module telegix/markup
+ */
+
+export class KeyboardBuilder {
+  constructor(buttons = []) {
+    this.keyboard = Array.isArray(buttons) ? buttons : [];
+    this.is_persistent = false;
+    this.resize_keyboard = true;
+    this.one_time_keyboard = false;
+    this.input_field_placeholder = undefined;
+    this.selective = false;
+  }
+
+  /**
+   * Returns reply_markup object directly
+   */
+  get reply_markup() {
+    return this.toJSON();
+  }
+
+  /**
+   * Resizes keyboard vertically for optimal fit
+   * @param {boolean} [resize=true]
+   * @returns {this}
+   */
+  resize(resize = true) {
+    this.resize_keyboard = Boolean(resize);
+    return this;
+  }
+
+  /**
+   * Requests clients to always show the keyboard when the regular keyboard is hidden
+   * @param {boolean} [persistent=true]
+   * @returns {this}
+   */
+  persistent(persistent = true) {
+    this.is_persistent = Boolean(persistent);
+    return this;
+  }
+
+  /**
+   * Requests clients to hide the keyboard as soon as it's been used
+   * @param {boolean} [oneTime=true]
+   * @returns {this}
+   */
+  oneTime(oneTime = true) {
+    this.one_time_keyboard = Boolean(oneTime);
+    return this;
+  }
+
+  /**
+   * The placeholder to be shown in the input field when the keyboard is active
+   * @param {string} placeholder
+   * @returns {this}
+   */
+  placeholder(placeholder) {
+    this.input_field_placeholder = placeholder;
+    return this;
+  }
+
+  /**
+   * Use this parameter if you want to show the keyboard to specific users only
+   * @param {boolean} [selective=true]
+   * @returns {this}
+   */
+  selectiveTarget(selective = true) {
+    this.selective = Boolean(selective);
+    return this;
+  }
+
+  /**
+   * Returns standard Telegram ReplyKeyboardMarkup object
+   * @returns {object}
+   */
+  toJSON() {
+    return {
+      keyboard: this.keyboard,
+      is_persistent: this.is_persistent,
+      resize_keyboard: this.resize_keyboard,
+      one_time_keyboard: this.one_time_keyboard,
+      input_field_placeholder: this.input_field_placeholder,
+      selective: this.selective,
+    };
+  }
+}
+
+export class Markup {
+  /**
+   * Create custom reply keyboard markup
+   * @param {Array<Array<object|string>|object|string>} buttons
+   * @param {object} [options]
+   * @returns {KeyboardBuilder}
+   */
+  static keyboard(buttons = [], options = {}) {
+    const formatted = Array.isArray(buttons)
+      ? buttons.map((row) => {
+          const rowArr = Array.isArray(row) ? row : [row];
+          return rowArr.map((btn) => (typeof btn === 'string' ? { text: btn } : btn));
+        })
+      : [];
+    const builder = new KeyboardBuilder(formatted);
+    if (options.resize !== undefined) builder.resize(options.resize);
+    if (options.oneTime !== undefined) builder.oneTime(options.oneTime);
+    if (options.persistent !== undefined) builder.persistent(options.persistent);
+    if (options.placeholder !== undefined) builder.placeholder(options.placeholder);
+    if (options.selective !== undefined) builder.selectiveTarget(options.selective);
+    return builder;
+  }
+
+  /**
+   * Create inline keyboard markup
+   * @param {Array<Array<object>|object>} buttons
+   * @returns {{ inline_keyboard: Array<Array<object>>, reply_markup: { inline_keyboard: Array<Array<object>> } }}
+   */
+  static inlineKeyboard(buttons = []) {
+    const inline_keyboard = Array.isArray(buttons)
+      ? buttons.map((row) => {
+          const rowArr = Array.isArray(row) ? row : [row];
+          return rowArr.map((btn) => (typeof btn === 'string' ? { text: btn, callback_data: btn } : btn));
+        })
+      : [];
+    return {
+      inline_keyboard,
+      reply_markup: { inline_keyboard },
+    };
+  }
+
+  /**
+   * Requests clients to remove the custom keyboard
+   * @param {boolean} [selective=false]
+   * @returns {{ remove_keyboard: true, selective: boolean, reply_markup: { remove_keyboard: true, selective: boolean } }}
+   */
+  static removeKeyboard(selective = false) {
+    const res = {
+      remove_keyboard: true,
+      selective: Boolean(selective),
+    };
+    return {
+      ...res,
+      reply_markup: res,
+    };
+  }
+
+  /**
+   * Displays a reply interface to the user
+   * @param {boolean} [selective=false]
+   * @param {string} [placeholder]
+   * @returns {{ force_reply: true, selective: boolean, input_field_placeholder?: string, reply_markup: object }}
+   */
+  static forceReply(selective = false, placeholder = undefined) {
+    const res = {
+      force_reply: true,
+      selective: Boolean(selective),
+    };
+    if (placeholder) {
+      res.input_field_placeholder = placeholder;
+    }
+    return {
+      ...res,
+      reply_markup: res,
+    };
+  }
+
+  /**
+   * Button builders
+   */
+  static button = {
+    /**
+     * Standard text button for reply keyboard
+     * @param {string} text
+     */
+    text: (text) => ({ text }),
+
+    /**
+     * Inline callback button
+     * @param {string} text
+     * @param {string} data
+     */
+    callback: (text, data) => ({ text, callback_data: String(data) }),
+
+    /**
+     * Inline URL button
+     * @param {string} text
+     * @param {string} url
+     */
+    url: (text, url) => ({ text, url }),
+
+    /**
+     * Web App button
+     * @param {string} text
+     * @param {string} url
+     */
+    webApp: (text, url) => ({ text, web_app: { url } }),
+
+    /**
+     * Request user contact (reply keyboard only)
+     * @param {string} text
+     */
+    contactRequest: (text) => ({ text, request_contact: true }),
+
+    /**
+     * Request user location (reply keyboard only)
+     * @param {string} text
+     */
+    locationRequest: (text) => ({ text, request_location: true }),
+
+    /**
+     * Request user poll (reply keyboard only)
+     * @param {string} text
+     * @param {'quiz'|'regular'|string} [type]
+     */
+    pollRequest: (text, type) => ({
+      text,
+      request_poll: type ? { type } : {},
+    }),
+
+    /**
+     * Switch to inline query button
+     * @param {string} text
+     * @param {string} [query='']
+     */
+    switchToChat: (text, query = '') => ({
+      text,
+      switch_inline_query: query,
+    }),
+
+    /**
+     * Switch to inline query in current chat button
+     * @param {string} text
+     * @param {string} [query='']
+     */
+    switchToCurrentChat: (text, query = '') => ({
+      text,
+      switch_inline_query_current_chat: query,
+    }),
+
+    /**
+     * Login URL button
+     * @param {string} text
+     * @param {string} url
+     * @param {object} [options]
+     */
+    login: (text, url, options = {}) => ({
+      text,
+      login_url: { url, ...options },
+    }),
+
+    /**
+     * Pay button (must be the very first button in the first row of an invoice inline keyboard)
+     * @param {string} [text='Pay']
+     */
+    pay: (text = 'Pay') => ({
+      text,
+      pay: true,
+    }),
+
+    /**
+     * Copy text button (copies copyText directly to clipboard on click)
+     * @param {string} text
+     * @param {string} copyText
+     */
+    copyText: (text, copyText) => ({
+      text,
+      copy_text: { text: String(copyText) },
+    }),
+
+    /**
+     * Request users button (reply keyboard only)
+     * @param {string} text
+     * @param {number} requestId
+     * @param {object} [options]
+     */
+    requestUsers: (text, requestId, options = {}) => ({
+      text,
+      request_users: { request_id: requestId, ...options },
+    }),
+
+    /**
+     * Request chat button (reply keyboard only)
+     * @param {string} text
+     * @param {number} requestId
+     * @param {boolean} [chatIsChannel=false]
+     * @param {object} [options]
+     */
+    requestChat: (text, requestId, chatIsChannel = false, options = {}) => ({
+      text,
+      request_chat: { request_id: requestId, chat_is_channel: Boolean(chatIsChannel), ...options },
+    }),
+
+    /**
+     * Switch to inline query chosen chat button
+     * @param {string} text
+     * @param {string} [query='']
+     * @param {object} [options]
+     */
+    switchInlineQueryChosenChat: (text, query = '', options = {}) => ({
+      text,
+      switch_inline_query_chosen_chat: { query, ...options },
+    }),
+
+    /**
+     * Play Game button
+     * @param {string} [text='Play Game']
+     */
+    game: (text = 'Play Game') => ({
+      text,
+      callback_game: {},
+    }),
+
+    /**
+     * Disabled button (Bot API 10.3)
+     * @param {string} text
+     */
+    disabled: (text) => ({
+      text,
+      disabled: true,
+    }),
+  };
+}

package/lib/payment.js

@@ -0,0 +1,91 @@
+/**
+ * Telegix - Telegram Payment & Invoice Builder
+ */
+
+export class InvoiceBuilder {
+  constructor(title, description, payload, currency, prices) {
+    this.invoice = {
+      title,
+      description,
+      payload,
+      currency: currency || 'XTR', // Telegram Stars default or USD, RUB, etc.
+      prices: prices || [],
+    };
+  }
+
+  providerToken(token) {
+    if (token) this.invoice.provider_token = token;
+    return this;
+  }
+
+  addPrice(label, amount) {
+    this.invoice.prices.push({ label, amount });
+    return this;
+  }
+
+  maxTipAmount(amount) {
+    this.invoice.max_tip_amount = amount;
+    return this;
+  }
+
+  suggestedTipAmounts(amounts) {
+    this.invoice.suggested_tip_amounts = amounts;
+    return this;
+  }
+
+  photo(url, width, height, size) {
+    if (url) this.invoice.photo_url = url;
+    if (width) this.invoice.photo_width = width;
+    if (height) this.invoice.photo_height = height;
+    if (size) this.invoice.photo_size = size;
+    return this;
+  }
+
+  need(options = {}) {
+    if (options.name) this.invoice.need_name = true;
+    if (options.phoneNumber) this.invoice.need_phone_number = true;
+    if (options.email) this.invoice.need_email = true;
+    if (options.shippingAddress) this.invoice.need_shipping_address = true;
+    return this;
+  }
+
+  send(ctx, chatId) {
+    const targetChatId = chatId || ctx.chat?.id || ctx.chatId;
+    if (!targetChatId) {
+      throw new Error('Target chat ID is required to send invoice');
+    }
+    const { title, description, payload, currency, prices, ...extra } = this.invoice;
+    return ctx.telegram.sendInvoice(
+      targetChatId,
+      title,
+      description,
+      payload,
+      currency,
+      prices,
+      extra
+    );
+  }
+
+  build() {
+    return { ...this.invoice };
+  }
+}
+
+/**
+ * Validates shipping query response
+ */
+export function answerShippingQuery(ctx, ok, options = {}) {
+  const shippingQueryId = ctx.shippingQuery?.id || options.shippingQueryId || (typeof ctx === 'string' ? ctx : null);
+  if (!shippingQueryId) throw new Error('Shipping Query ID is missing');
+  return ctx.telegram.answerShippingQuery(shippingQueryId, ok, options);
+}
+
+/**
+ * Validates pre-checkout query response
+ */
+export function answerPreCheckoutQuery(ctx, ok, options = {}) {
+  const preCheckoutQueryId = ctx.preCheckoutQuery?.id || options.preCheckoutQueryId || (typeof ctx === 'string' ? ctx : null);
+  if (!preCheckoutQueryId) throw new Error('Pre-Checkout Query ID is missing');
+  const errorMsg = typeof options === 'string' ? options : options.errorMessage;
+  return ctx.telegram.answerPreCheckoutQuery(preCheckoutQueryId, ok, errorMsg);
+}

package/lib/polling.js

@@ -0,0 +1,101 @@
+/**
+ * Telegix - Long Polling Engine
+ * @module telegix/polling
+ */
+
+import { PollingError } from './errors.js';
+
+export class Polling {
+  /**
+   * @param {import('./api.js').Telegram} telegram
+   * @param {Function} updateHandler - (update: object) => Promise<void>
+   * @param {object} [options]
+   */
+  constructor(telegram, updateHandler, options = {}) {
+    this.telegram = telegram;
+    this.updateHandler = updateHandler;
+    this.options = {
+      timeout: 30,
+      limit: 100,
+      allowedUpdates: undefined,
+      dropPendingUpdates: false,
+      retryInterval: 3000,
+      ...options,
+    };
+    this.offset = 0;
+    this.isRunning = false;
+    this.abortController = null;
+  }
+
+  /**
+   * Start long polling loop
+   */
+  async start() {
+    if (this.isRunning) return;
+    this.isRunning = true;
+
+    // Delete webhook if exists or drop pending updates
+    try {
+      if (this.options.dropPendingUpdates) {
+        await this.telegram.deleteWebhook({ drop_pending_updates: true });
+      }
+    } catch {
+      // Ignore initial webhook check error
+    }
+
+    this._loop();
+  }
+
+  /**
+   * @private
+   */
+  async _loop() {
+    while (this.isRunning) {
+      this.abortController = new AbortController();
+
+      try {
+        const updates = await this.telegram.getUpdates(
+          this.offset,
+          this.options.limit,
+          this.options.timeout,
+          this.options.allowedUpdates
+        );
+
+        if (!this.isRunning) break;
+
+        if (Array.isArray(updates) && updates.length > 0) {
+          for (const update of updates) {
+            this.offset = update.update_id + 1;
+            try {
+              await this.updateHandler(update);
+            } catch (err) {
+              if (this.options.onError) {
+                this.options.onError(new PollingError(err));
+              }
+            }
+          }
+        }
+      } catch (err) {
+        if (!this.isRunning) break;
+
+        if (this.options.onError) {
+          this.options.onError(new PollingError(err));
+        }
+
+        // Retry delay on error / 429
+        const retryDelay = err.retryAfter ? err.retryAfter * 1000 : this.options.retryInterval;
+        await new Promise((resolve) => setTimeout(resolve, retryDelay));
+      }
+    }
+  }
+
+  /**
+   * Stop polling gracefully
+   */
+  async stop() {
+    this.isRunning = false;
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+  }
+}

package/lib/prompt.js

@@ -0,0 +1,62 @@
+/**
+ * Telegix - Context Prompt Helper & Conversation Handler
+ */
+
+const activePrompts = new Map(); // key: `${chatId}:${userId}` -> callback(text)
+
+export function promptMiddleware() {
+  return async (ctx, next) => {
+    const chatId = ctx.chat?.id || ctx.chatId;
+    const userId = ctx.from?.id || ctx.userId;
+    const text = ctx.message?.text || ctx.message?.caption || ctx.msg?.text || ctx.msg?.caption;
+
+    if (chatId && userId && (text !== undefined || ctx.message || ctx.msg)) {
+      const key = `${chatId}:${userId}`;
+      if (activePrompts.has(key)) {
+        const handler = activePrompts.get(key);
+        activePrompts.delete(key);
+        handler(text, ctx);
+        return; // Consume update for the prompt
+      }
+    }
+
+    // Attach prompt helper to context
+    ctx.prompt = async (textMessage, options = {}) => {
+      const targetChatId = ctx.chat?.id || ctx.chatId;
+      const targetUserId = ctx.from?.id || ctx.userId;
+      if (!targetChatId || !targetUserId) {
+        throw new Error('Cannot prompt without chat ID and user ID');
+      }
+
+      const timeoutMs = options.timeoutMs || 60000; // default 1 minute
+      await ctx.reply(textMessage, options.extra);
+
+      return new Promise((resolve, reject) => {
+        const key = `${targetChatId}:${targetUserId}`;
+        
+        // If there's an existing prompt, cancel it
+        if (activePrompts.has(key)) {
+          activePrompts.delete(key);
+        }
+
+        const timer = setTimeout(() => {
+          if (activePrompts.has(key)) {
+            activePrompts.delete(key);
+            reject(new Error('Prompt timed out'));
+          }
+        }, timeoutMs);
+
+        activePrompts.set(key, (responseText, promptCtx) => {
+          clearTimeout(timer);
+          if (options.returnContext) {
+            resolve({ text: responseText, ctx: promptCtx });
+          } else {
+            resolve(responseText);
+          }
+        });
+      });
+    };
+
+    return next();
+  };
+}

package/lib/ratelimit.js

@@ -0,0 +1,59 @@
+/**
+ * Telegix - Rate Limiter & Throttling Middleware
+ */
+
+export class RateLimiter {
+  constructor(options = {}) {
+    this.windowMs = options.windowMs || 3000; // 3 seconds window by default
+    this.limit = options.limit || 3; // Max 3 requests per window
+    this.keyFn = options.keyFn || ((ctx) => ctx.userId || ctx.chatId);
+    this.handler = options.handler || (async (ctx) => {
+      await ctx.reply('⚠️ Too many requests. Please slow down.');
+    });
+    this.storage = new Map();
+
+    const cleanup = setInterval(() => {
+      const now = Date.now();
+      for (const [key, data] of this.storage.entries()) {
+        if (now > data.resetTime) {
+          this.storage.delete(key);
+        }
+      }
+    }, Math.max(this.windowMs, 10000));
+    if (cleanup.unref) cleanup.unref();
+  }
+
+  middleware() {
+    return async (ctx, next) => {
+      const key = this.keyFn(ctx);
+      if (!key) return next();
+
+      const now = Date.now();
+      let record = this.storage.get(key);
+
+      if (!record || now > record.resetTime) {
+        record = {
+          count: 1,
+          resetTime: now + this.windowMs,
+        };
+        this.storage.set(key, record);
+        return next();
+      }
+
+      record.count++;
+      if (record.count > this.limit) {
+        return this.handler(ctx, next);
+      }
+
+      return next();
+    };
+  }
+}
+
+/**
+ * Convenience factory function
+ */
+export function rateLimit(options) {
+  const limiter = new RateLimiter(options);
+  return limiter.middleware();
+}