telegix 1.1.1

package/lib/scenes.js

@@ -0,0 +1,206 @@
+/**
+ * Telegix - Pure JS Scenes & Wizard Dialog Engine
+ * @module telegix/scenes
+ */
+
+import { Composer, compose } from './composer.js';
+
+export class BaseScene extends Composer {
+  /**
+   * @param {string} id - Unique Scene identifier
+   */
+  constructor(id) {
+    super();
+    if (!id || typeof id !== 'string') {
+      throw new Error('BaseScene requires a valid string ID');
+    }
+    this.id = id;
+    this.enterHandlers = [];
+    this.leaveHandlers = [];
+  }
+
+  /**
+   * Handler executed when user enters the scene
+   * @param {...Function} handlers
+   */
+  enter(...handlers) {
+    this.enterHandlers.push(...handlers);
+    return this;
+  }
+
+  /**
+   * Handler executed when user leaves the scene
+   * @param {...Function} handlers
+   */
+  leave(...handlers) {
+    this.leaveHandlers.push(...handlers);
+    return this;
+  }
+}
+
+export class WizardScene extends BaseScene {
+  /**
+   * @param {string} id - Wizard Scene ID
+   * @param {...Function} steps - Middleware step functions
+   */
+  constructor(id, ...steps) {
+    super(id);
+    this.steps = steps;
+
+    this.use(async (ctx, next) => {
+      if (!ctx.scene?.session) return next();
+      const cursor = ctx.scene.session.cursor || 0;
+      const step = this.steps[cursor];
+      if (!step) {
+        return ctx.scene.leave();
+      }
+      return step(ctx, next);
+    });
+
+    this.enter((ctx, next) => {
+      ctx.scene.session.cursor = 0;
+      const step = this.steps[0];
+      if (step) {
+        return step(ctx, next);
+      }
+      return next();
+    });
+  }
+}
+
+export class Stage extends Composer {
+  /**
+   * @param {Array<BaseScene>} scenes
+   * @param {object} [options]
+   */
+  constructor(scenes = [], options = {}) {
+    super();
+    this.scenes = new Map();
+    this.options = {
+      defaultScene: null,
+      ...options,
+    };
+
+    for (const scene of scenes) {
+      this.register(scene);
+    }
+
+    this.use(this.middleware());
+  }
+
+  /**
+   * Register a scene
+   * @param {BaseScene} scene
+   */
+  register(scene) {
+    if (!scene || !scene.id) {
+      throw new Error('Stage.register requires a valid BaseScene instance with an ID');
+    }
+    this.scenes.set(scene.id, scene);
+    return this;
+  }
+
+  /**
+   * Returns Stage middleware
+   */
+  middleware() {
+    const stageInstance = this;
+    return async (ctx, next) => {
+      if (!ctx.session) {
+        throw new Error('Telegix Stage: session middleware is required before Stage middleware!');
+      }
+
+      ctx.session.__scenes = ctx.session.__scenes || {};
+      const sceneSession = ctx.session.__scenes;
+
+      // Setup scene control helper on ctx
+      const sceneControl = {
+        get session() {
+          const currentId = sceneSession.current;
+          if (!currentId) return {};
+          sceneSession.state = sceneSession.state || {};
+          return sceneSession.state;
+        },
+        get current() {
+          const currentId = sceneSession.current;
+          return currentId ? stageInstance.scenes.get(currentId) || null : null;
+        },
+        get state() {
+          return sceneSession.state || {};
+        },
+        enter: async (sceneId, initialState = {}) => {
+          const scene = stageInstance.scenes.get(sceneId);
+          if (!scene) {
+            throw new Error(`Telegix Stage: Scene '${sceneId}' not found!`);
+          }
+          sceneSession.current = sceneId;
+          sceneSession.state = { ...initialState };
+          sceneSession.cursor = 0;
+
+          if (scene.enterHandlers.length > 0) {
+            const enterFn = compose(scene.enterHandlers);
+            await enterFn(ctx, async () => {});
+          }
+        },
+        reenter: async () => {
+          const currentId = sceneSession.current;
+          if (currentId) {
+            await sceneControl.enter(currentId, sceneSession.state);
+          }
+        },
+        leave: async () => {
+          const currentId = sceneSession.current;
+          if (currentId) {
+            const scene = stageInstance.scenes.get(currentId);
+            if (scene && scene.leaveHandlers.length > 0) {
+              const leaveFn = compose(scene.leaveHandlers);
+              await leaveFn(ctx, async () => {});
+            }
+          }
+          delete sceneSession.current;
+          delete sceneSession.state;
+          delete sceneSession.cursor;
+        },
+      };
+
+      // Setup wizard helper on ctx
+      const wizardControl = {
+        get cursor() {
+          return sceneSession.cursor || 0;
+        },
+        set cursor(val) {
+          sceneSession.cursor = val;
+        },
+        get state() {
+          return sceneControl.state;
+        },
+        selectStep: (index) => {
+          sceneSession.cursor = index;
+        },
+        next: () => {
+          sceneSession.cursor = (sceneSession.cursor || 0) + 1;
+        },
+        back: () => {
+          sceneSession.cursor = Math.max(0, (sceneSession.cursor || 0) - 1);
+        },
+      };
+
+      ctx.scene = sceneControl;
+      ctx.wizard = wizardControl;
+
+      const currentSceneId = sceneSession.current || this.options.defaultScene;
+      if (!currentSceneId) {
+        return next();
+      }
+
+      const scene = this.scenes.get(currentSceneId);
+      if (!scene) {
+        return next();
+      }
+
+      return scene.middleware()(ctx, next);
+    };
+  }
+}
+
+export const Scene = BaseScene;

package/lib/serialize.js

@@ -0,0 +1,141 @@
+/**
+ * Telegix - Message & Update Serializer Utility
+ * Standardizes raw Telegram updates into a clean, feature-rich structured object.
+ */
+
+export function serializeMessage(msg) {
+  if (!msg) return null;
+
+  const serialized = {
+    id: msg.message_id,
+    chatId: msg.chat?.id,
+    senderId: msg.from?.id,
+    from: msg.from || {},
+    chat: msg.chat || {},
+    date: msg.date,
+    text: msg.text || msg.caption || '',
+    type: 'unknown',
+    media: null,
+    quoted: null,
+    mentioned: [],
+    raw: msg,
+  };
+
+  // Determine message type and extract media/content
+  if (msg.text) {
+    serialized.type = 'text';
+  } else if (msg.photo && msg.photo.length > 0) {
+    serialized.type = 'photo';
+    const photo = msg.photo[msg.photo.length - 1];
+    serialized.media = {
+      fileId: photo.file_id,
+      fileUniqueId: photo.file_unique_id,
+      fileSize: photo.file_size,
+      width: photo.width,
+      height: photo.height,
+    };
+  } else if (msg.video) {
+    serialized.type = 'video';
+    serialized.media = {
+      fileId: msg.video.file_id,
+      fileUniqueId: msg.video.file_unique_id,
+      fileSize: msg.video.file_size,
+      duration: msg.video.duration,
+      mimeType: msg.video.mime_type,
+      width: msg.video.width,
+      height: msg.video.height,
+    };
+  } else if (msg.document) {
+    serialized.type = 'document';
+    serialized.media = {
+      fileId: msg.document.file_id,
+      fileUniqueId: msg.document.file_unique_id,
+      fileName: msg.document.file_name,
+      fileSize: msg.document.file_size,
+      mimeType: msg.document.mime_type,
+    };
+  } else if (msg.audio) {
+    serialized.type = 'audio';
+    serialized.media = {
+      fileId: msg.audio.file_id,
+      fileUniqueId: msg.audio.file_unique_id,
+      duration: msg.audio.duration,
+      performer: msg.audio.performer,
+      title: msg.audio.title,
+      fileSize: msg.audio.file_size,
+      mimeType: msg.audio.mime_type,
+    };
+  } else if (msg.voice) {
+    serialized.type = 'voice';
+    serialized.media = {
+      fileId: msg.voice.file_id,
+      fileUniqueId: msg.voice.file_unique_id,
+      duration: msg.voice.duration,
+      fileSize: msg.voice.file_size,
+      mimeType: msg.voice.mime_type,
+    };
+  } else if (msg.sticker) {
+    serialized.type = 'sticker';
+    serialized.media = {
+      fileId: msg.sticker.file_id,
+      fileUniqueId: msg.sticker.file_unique_id,
+      emoji: msg.sticker.emoji,
+      isAnimated: msg.sticker.is_animated,
+      isVideo: msg.sticker.is_video,
+    };
+  } else if (msg.contact) {
+    serialized.type = 'contact';
+    serialized.contact = msg.contact;
+  } else if (msg.location) {
+    serialized.type = 'location';
+    serialized.location = msg.location;
+  } else if (msg.poll) {
+    serialized.type = 'poll';
+    serialized.poll = msg.poll;
+  }
+
+  // Handle Quoted / Replied Message
+  if (msg.reply_to_message) {
+    serialized.quoted = serializeMessage(msg.reply_to_message);
+  }
+
+  // Extract mentions from entities
+  const entities = msg.entities || msg.caption_entities || [];
+  for (const entity of entities) {
+    if (entity.type === 'mention') {
+      const mentionText = serialized.text.substring(entity.offset, entity.offset + entity.length);
+      serialized.mentioned.push(mentionText);
+    }
+  }
+
+  serialized.isGroup = ['group', 'supergroup'].includes(serialized.chat?.type);
+  serialized.isPrivate = serialized.chat?.type === 'private';
+  serialized.isChannel = serialized.chat?.type === 'channel';
+
+  return serialized;
+}
+
+export function serializeUpdate(update) {
+  const result = {
+    updateId: update.update_id,
+    type: 'unknown',
+    message: null,
+    callbackQuery: update.callback_query || null,
+    inlineQuery: update.inline_query || null,
+    raw: update,
+  };
+
+  const msg = update.message || update.edited_message || update.channel_post || update.edited_channel_post || update.callback_query?.message;
+  if (msg) {
+    result.message = serializeMessage(msg);
+  }
+
+  if (update.message) result.type = 'message';
+  else if (update.callback_query) result.type = 'callback_query';
+  else if (update.inline_query) result.type = 'inline_query';
+  else if (update.chat_member) result.type = 'chat_member';
+  else if (update.chat_boost) result.type = 'chat_boost';
+  else if (update.paid_message_price_changed) result.type = 'paid_message_price_changed';
+
+  return result;
+}

package/lib/session.js

@@ -0,0 +1,145 @@
+/**
+ * Telegix - Session Management Middleware
+ * @module telegix/session
+ */
+
+import fs from 'fs/promises';
+
+export class MemorySessionStore {
+  constructor(ttl = Infinity) {
+    this.map = new Map();
+    this.ttl = ttl;
+  }
+
+  async get(key) {
+    const item = this.map.get(key);
+    if (!item) return undefined;
+    if (Date.now() > item.expiresAt) {
+      this.map.delete(key);
+      return undefined;
+    }
+    return item.value;
+  }
+
+  async set(key, value) {
+    const expiresAt = this.ttl === Infinity ? Infinity : Date.now() + this.ttl;
+    this.map.set(key, { value, expiresAt });
+  }
+
+  async delete(key) {
+    this.map.delete(key);
+  }
+
+  async clear() {
+    this.map.clear();
+  }
+}
+
+export class FileSessionStore {
+  constructor(filePath = 'telegix_sessions.json', ttl = Infinity) {
+    this.filePath = filePath;
+    this.ttl = ttl;
+    this.cache = null;
+    this.loaded = false;
+  }
+
+  async _load() {
+    if (this.loaded) return;
+    try {
+      const data = await fs.readFile(this.filePath, 'utf8');
+      const parsed = JSON.parse(data);
+      this.cache = new Map(Object.entries(parsed));
+    } catch {
+      this.cache = new Map();
+    }
+    this.loaded = true;
+  }
+
+  async _save() {
+    if (!this.cache) return;
+    try {
+      const obj = Object.fromEntries(this.cache.entries());
+      await fs.writeFile(this.filePath, JSON.stringify(obj, null, 2), 'utf8');
+    } catch (err) {
+      console.error('Telegix FileSessionStore save error:', err);
+    }
+  }
+
+  async get(key) {
+    await this._load();
+    const item = this.cache.get(key);
+    if (!item) return undefined;
+    if (Date.now() > item.expiresAt) {
+      this.cache.delete(key);
+      await this._save();
+      return undefined;
+    }
+    return item.value;
+  }
+
+  async set(key, value) {
+    await this._load();
+    const expiresAt = this.ttl === Infinity ? Infinity : Date.now() + this.ttl;
+    this.cache.set(key, { value, expiresAt });
+    await this._save();
+  }
+
+  async delete(key) {
+    await this._load();
+    this.cache.delete(key);
+    await this._save();
+  }
+
+  async clear() {
+    await this._load();
+    this.cache.clear();
+    await this._save();
+  }
+}
+
+/**
+ * Session middleware for Telegix
+ * @param {object} [options]
+ * @param {Function} [options.getSessionKey] - Custom function returning session key
+ * @param {object} [options.store] - Session store implementing get/set/delete
+ * @param {Function} [options.initial] - Function returning initial session data
+ * @param {number} [options.ttl] - Time-to-live in ms for default memory store
+ * @returns {Function} Telegix middleware
+ */
+export function session(options = {}) {
+  const store = options.store || new MemorySessionStore(options.ttl);
+  const getSessionKey =
+    options.getSessionKey ||
+    ((ctx) => {
+      const chatId = ctx.chatId;
+      const userId = ctx.userId;
+      if (!chatId && !userId) return null;
+      return `${chatId ?? ''}:${userId ?? ''}`;
+    });
+  const initial = options.initial || (() => ({}));
+
+  return async (ctx, next) => {
+    const key = getSessionKey(ctx);
+    if (!key) {
+      return next();
+    }
+
+    let sessionData = await store.get(key);
+    if (sessionData === undefined || sessionData === null) {
+      sessionData = initial(ctx);
+    }
+
+    // Attach session to ctx
+    ctx.session = sessionData;
+
+    try {
+      await next();
+    } finally {
+      if (ctx.session === null || ctx.session === undefined) {
+        await store.delete(key);
+      } else {
+        await store.set(key, ctx.session);
+      }
+    }
+  };
+}

package/lib/telegix.js

@@ -0,0 +1,176 @@
+/**
+ * Telegix - Pure JavaScript Telegram Bot Framework
+ * @module telegix
+ */
+
+import { Composer } from './composer.js';
+import { Telegram } from './api.js';
+import { Context } from './context.js';
+import { Polling } from './polling.js';
+import { createWebhookCallback } from './webhook.js';
+import { TelegixError } from './errors.js';
+
+export class Telegix extends Composer {
+  /**
+   * @param {string} token - Telegram Bot Token from @BotFather
+   * @param {object} [options]
+   * @param {string} [options.apiRoot='https://api.telegram.org']
+   * @param {boolean} [options.testEnv=false]
+   * @param {number} [options.timeout=60000]
+   * @param {object} [options.botInfo] - Pre-fetched bot info
+   */
+  constructor(token, options = {}) {
+    super();
+
+    if (!token || typeof token !== 'string') {
+      throw new TelegixError('Telegix: Telegram Bot Token is required.');
+    }
+
+    this.token = token.trim();
+    this.options = options;
+    this.telegram = new Telegram(this.token, options);
+    this.api = this.telegram; // alias
+    this.botInfo = options.botInfo || null;
+    this.polling = null;
+    this.errorHandler = (err, ctx) => {
+      console.error('Telegix Error:', err);
+    };
+  }
+
+  /**
+   * Custom error catcher
+   * @param {Function} handler - (err: Error, ctx?: Context) => void
+   * @returns {this}
+   */
+  catch(handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('Telegix.catch() expects a function handler');
+    }
+    this.errorHandler = handler;
+    return this;
+  }
+
+  /**
+   * Handle an incoming Telegram update object
+   * @param {object} update
+   * @returns {Promise<void>}
+   */
+  async handleUpdate(update) {
+    if (!update || typeof update !== 'object') return;
+
+    const ctx = new Context(update, this.telegram, this.botInfo);
+    try {
+      const fn = this.middleware();
+      await fn(ctx, () => Promise.resolve());
+    } catch (err) {
+      if (this.errorHandler) {
+        await this.errorHandler(err, ctx);
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Start polling for updates
+   * @param {object} [options]
+   * @returns {Promise<void>}
+   */
+  async startPolling(options = {}) {
+    if (this.polling) {
+      await this.polling.stop();
+    }
+
+    if (!this.botInfo) {
+      try {
+        this.botInfo = await this.telegram.getMe();
+      } catch (err) {
+        console.warn('Telegix: Warning: Could not fetch getMe() before polling:', err.message);
+      }
+    }
+
+    this.polling = new Polling(
+      this.telegram,
+      (update) => this.handleUpdate(update),
+      {
+        onError: (err) => {
+          if (this.errorHandler) this.errorHandler(err);
+        },
+        ...options,
+      }
+    );
+
+    await this.polling.start();
+  }
+
+  /**
+   * Stop bot polling
+   * @param {string} [reason]
+   */
+  async stop(reason = 'manual') {
+    if (this.polling) {
+      await this.polling.stop();
+      this.polling = null;
+    }
+  }
+
+  /**
+   * Launch bot using long-polling or webhook
+   * @param {object} [options]
+   * @param {object|boolean} [options.polling=true] - Long polling configuration or true
+   * @param {object} [options.webhook] - Webhook configuration { domain, hookPath, port, secretToken }
+   * @param {boolean} [options.dropPendingUpdates=false]
+   * @returns {Promise<object>} Bot Info
+   */
+  async launch(options = {}) {
+    // 1. Fetch bot info
+    if (!this.botInfo) {
+      this.botInfo = await this.telegram.getMe();
+    }
+
+    console.log(`🚀 Telegix Bot started: @${this.botInfo.username} (ID: ${this.botInfo.id})`);
+
+    // 2. Setup shutdown hooks
+    const handleExit = (signal) => {
+      console.log(`\n🛑 Telegix Bot stopping due to ${signal}...`);
+      this.stop(signal).then(() => {
+        process.exit(0);
+      });
+    };
+
+    if (typeof process !== 'undefined' && process.once) {
+      process.once('SIGINT', () => handleExit('SIGINT'));
+      process.once('SIGTERM', () => handleExit('SIGTERM'));
+    }
+
+    // 3. Webhook or Polling
+    if (options.webhook) {
+      const { domain, hookPath = '/telegix-webhook', port = 3000, secretToken } = options.webhook;
+      const url = `${domain.replace(/\/$/, '')}${hookPath.startsWith('/') ? hookPath : `/${hookPath}`}`;
+
+      await this.telegram.setWebhook(url, {
+        secret_token: secretToken,
+        drop_pending_updates: options.dropPendingUpdates,
+      });
+
+      console.log(`🔗 Webhook set to: ${url}`);
+    } else {
+      const pollingOptions =
+        typeof options.polling === 'object'
+          ? options.polling
+          : { dropPendingUpdates: options.dropPendingUpdates };
+      await this.startPolling(pollingOptions);
+    }
+
+    return this.botInfo;
+  }
+
+  /**
+   * Returns a standard HTTP webhook callback handler
+   * @param {string} [path='/']
+   * @param {object} [options]
+   */
+  webhookCallback(path = '/', options = {}) {
+    return createWebhookCallback(this, path, options);
+  }
+}