xzcgram 0.0.1 → 0.0.3

package/README.md

@@ -8,7 +8,7 @@
 
 </div>
 
-#xzcgram
+# xzcgram
 
 A tiny Telegraf-style router for [GramJS](https://github.com/gram-js/gramjs) (`telegram`).
 
@@ -88,6 +88,7 @@ returns a ready-to-use `Bot`.
 | ------------------- | -------- | ---------------------------------------------------------- |
 | `apiId`              | yes      | Your `api_id` from my.telegram.org                        |
 | `apiHash`            | yes      | Your `api_hash` from my.telegram.org                       |
+| `botToken`           | no       | A bot token from @BotFather — logs in as that **bot** instead of a user account (skips `loginOptions` entirely) |
 | `sessionType`        | no       | `"string"` (default) or `"store"` — see below              |
 | `session`            | no       | Saved session string, used when `sessionType` is `"string"` |
 | `sessionName`        | no       | Session file name, used when `sessionType` is `"store"` (default `"xzcgram"`) |
@@ -128,6 +129,40 @@ Resolves to `{ bot, client, sessionString }`.
   `sessionString` will be `null` in this mode since the session already
   lives on disk.
 
+**Logging in as a bot instead of a user:**
+
+Pass `botToken` (from [@BotFather](https://t.me/BotFather)) and skip
+`loginOptions` entirely — no phone number, code, or password needed:
+
+```js
+const { bot } = await clientStart({
+  apiId,
+  apiHash,
+  botToken: "123456:ABC-your-bot-token-from-BotFather",
+  sessionType: "store",
+  sessionName: "my-bot",
+});
+
+bot.command("start", async (ctx) => {
+  await ctx.reply("Hello! I'm running as a bot account.");
+});
+
+await bot.launch();
+```
+
+Everything else (`bot.command`, `bot.hears`, `bot.action`, `ctx.reply*`,
+etc.) works the same either way. A couple of things differ because
+Telegram treats bot accounts differently from user accounts:
+- Bots can only see messages sent directly to them or in chats/groups
+  they've been added to — they can't read arbitrary chats like a user
+  session can.
+- Some `ctx.*` methods that act on "your own account" (`updateProfile`,
+  `updateUsername`, `setOnlineStatus`, `getPrivacySettings`, `blockUser`,
+  etc.) either behave differently or aren't meaningful for bots — those
+  are really aimed at user-account sessions.
+- Admin-type actions (`banUser`, `promoteUser`, etc.) still work, but the
+  bot itself needs the relevant admin rights in that chat first.
+
 ### `new Bot(client)`
 
 Lower-level constructor for when you already manage your own GramJS
@@ -164,6 +199,20 @@ registering your handlers.
 | `ctx.chatId`                                     | Chat/peer id of the message                                  |
 | `ctx.text`                                       | Full message text                                             |
 | `ctx.args`                                       | Command arguments as an array (space-split)                   |
+| **Metadata**                                     |                                                                |
+| `ctx.senderId`                                   | Id of whoever sent the message                                |
+| `ctx.date` / `ctx.editDate`                      | Unix timestamp sent / last edited                              |
+| `ctx.viaBotId`                                   | Id of the inline bot used to send this, if any                |
+| `ctx.viaBusinessBotId`                           | Id of the Business-connected bot used to send this, if any    |
+| `ctx.isPrivate` / `ctx.isGroup` / `ctx.isChannel`| What kind of chat this is                                     |
+| `ctx.replyToMsgId` / `ctx.isReply`               | Id of the message being replied to, if any                    |
+| `ctx.replyMessage`                               | **Promise** resolving to the replied-to message(s) (`[]` if not a reply) — `await` it |
+| `ctx.fwdFrom` / `ctx.isForwarded`                | Forward header info, if the message was forwarded             |
+| `ctx.entities`                                   | Message entities (bold, links, mentions, etc.)                |
+| `ctx.media` / `ctx.hasMedia` / `ctx.mediaType`   | Raw attached media, whether it exists, and its type            |
+| `ctx.silent` / `ctx.out` / `ctx.pinned`          | Sent silently / sent by us / currently pinned                  |
+| `ctx.groupedId`                                  | Album id, if this message is part of a media group             |
+| `ctx.peer()`                                     | Resolves the correct input peer for the current chat (used internally, but callable directly) |
 | **Text**                                         |                                                                |
 | `ctx.reply(text, opts?)`                         | Send a message to the same chat                                |
 | `ctx.replyQuote(text, opts?)`                    | Reply directly to the triggering message                       |
@@ -181,18 +230,91 @@ registering your handlers.
 | **Interactive**                                  |                                                                |
 | `ctx.replyWithButtons(text, rows, opts?)`        | Send a message with inline buttons                                  |
 | `ctx.replyWithKeyboard(text, rows, opts?)`       | Send a message with a plain reply keyboard                          |
-| `ctx.replyWithPoll(question, answers, opts?)`    | Send a poll                                                          |
+| `ctx.replyWithPoll(question, answers, opts?)`    | Send a poll (`opts`: `multipleChoice`, `quiz`, `publicVoters`)        |
 | `ctx.replyWithLocation(lat, long, opts?)`        | Send a location                                                       |
 | `ctx.replyWithContact(phone, firstName, last?)`  | Send a contact card                                                    |
-| `ctx.replyWithDice(emoji?, opts?)`               | Send an animated dice/emoji (🎲🎯🏀⚽🎰🎳)                              |
+| `ctx.replyWithDice(emoji?, opts?)`               | Send an animated dice/emoji (default 🎰; also 🎲🎯🏀⚽🎳)                    |
 | **Chat management**                              |                                                                |
-| `ctx.deleteMessage()`                            | Delete the triggering message (revoke for all)                          |
-| `ctx.forwardMessage(toChatId)`                   | Forward the triggering message elsewhere                                 |
-| `ctx.pinMessage(opts?)`                          | Pin the triggering message                                                |
-| `ctx.unpinMessage()`                             | Unpin the triggering message                                              |
+| `ctx.deleteMessage(id?)`                         | Delete a message (defaults to the triggering one, revokes for all) |
+| `ctx.forwardMessage(toChatId, id?)`              | Forward a message (defaults to the triggering one) elsewhere         |
+| `ctx.pinMessage(id?, opts?)`                     | Pin a message (defaults to the triggering one)                       |
+| `ctx.unpinMessage(id?)`                          | Unpin a message (defaults to the triggering one)                     |
 | `ctx.sendChatAction(action?)`                    | Show "typing…" / "uploading photo…" etc                                   |
 | `ctx.getSender()`                                | Resolve the full sender entity                                             |
 | `ctx.getChat()`                                  | Resolve the full chat entity                                               |
+| `ctx.replyViaBot(bot, query?, opts?)`            | Send a message "via @bot" using an inline query result                     |
+| **More media / interaction**                     |                                                                |
+| `ctx.replyWithVenue(lat, long, title, address, opts?)` | Send a venue (pinned location + name/address)                        |
+| `ctx.replyWithLiveLocation(lat, long, period?, opts?)` | Send a live-updating location (period in seconds, 60–86400)          |
+| `ctx.react(id?, emoji?, opts?)`                  | React to a message (defaults to the triggering one); empty/null emoji removes it |
+| `ctx.copyMessage(toChatId, opts?)`               | Re-send the triggering message's content elsewhere, no "Forwarded from" header |
+| `ctx.markAsRead(peer?)`                          | Mark a chat as read (defaults to the current chat)                          |
+| `ctx.downloadMedia(opts?)`                       | Download the triggering message's attached media (Buffer, or see `saveMediaMessage`) |
+| `ctx.editMessageMedia(messageId, file, opts?)`   | Swap the media on a message you previously sent                             |
+| **Voice / text / poll**                          |                                                                |
+| `ctx.transcribeVoice(id?)`                       | Transcribe a voice note (defaults to the triggering message)                |
+| `ctx.translateText(text, toLang)`                | Translate arbitrary text (pass the text explicitly, e.g. `ctx.text`)         |
+| `ctx.votePoll(id, options)`                      | Vote on a poll message — **`id` is required as the 1st arg**, pass `undefined` to default to the triggering message (see note below) |
+| `ctx.retractVote(id?)`                           | Retract your vote on that poll                                              |
+| **Contacts / history**                           |                                                                |
+| `ctx.blockUser(userId?)` / `ctx.unblockUser(userId?)` | Block/unblock a user (defaults to the sender of the triggering message) |
+| `ctx.getHistory(peer?, limit?, opts?)`           | Fetch recent messages (defaults to the current chat)                          |
+| `ctx.searchMessages(query, opts?)`               | Search messages in the current chat                                          |
+| `ctx.unpinAllMessages(peer?)`                    | Unpin every pinned message (defaults to the current chat)                     |
+| `ctx.getParticipants(opts?)`                     | List members of the current group/channel                                     |
+| `ctx.getEntityByUsername(username)`              | Get metadata for a user/chat/channel by @username                            |
+| **Channel/group management** *(supergroup/channel unless noted)* |                                                    |
+| `ctx.banUser(userId, opts?)`                     | Ban a user (can't rejoin unless unbanned)                                     |
+| `ctx.unbanUser(userId)`                          | Clear all restrictions on a user                                              |
+| `ctx.kickUser(userId)`                           | Remove a user, but they CAN rejoin (works in basic groups too)                |
+| `ctx.promoteUser(userId, rights?, rank?)`        | Make a user admin                                                              |
+| `ctx.demoteUser(userId)`                         | Strip a user's admin rights                                                    |
+| `ctx.inviteToChannel(userIds)`                   | Invite one or more users to the current channel/supergroup                    |
+| `ctx.setChatTitle(id, title)`                    | Rename a chat — **pass `null`/`undefined` as `id` to target the current chat** (see note below) |
+| `ctx.setChatPhoto(id, file)`                     | Change a chat's photo — same `id` rule as `setChatTitle`                       |
+| `ctx.joinChannel(id)`                            | Join a channel/group by @username, id, or entity                              |
+| `ctx.joinByInvite(hash)`                         | Join a private chat via invite hash (the part after `t.me/+`)                  |
+| `ctx.leaveChannel(id?)`                          | Leave a channel/group (defaults to the current chat)                          |
+| **Stickers & GIFs**                              |                                                                |
+| `ctx.searchStickers(emoji)`                      | Find stickers matching an emoji                                                 |
+| `ctx.getStickerSet(shortName)`                   | Get a sticker set's full info + documents                                        |
+| `ctx.searchGifs(query, offset?)`                 | Search Telegram's global GIF results                                             |
+| `ctx.saveGif(document, unsave?)`                 | Save/unsave a GIF to "Saved GIFs"                                                 |
+| **Privacy & account settings**                   |                                                                |
+| `ctx.getPrivacySettings(key?)`                   | Get your privacy rules for a key (phoneNumber, lastSeen, etc.)                    |
+| `ctx.updateProfile(opts?)`                       | Update your first/last name and bio                                               |
+| `ctx.updateUsername(username)`                   | Change your @username                                                              |
+| `ctx.setOnlineStatus(online?)`                   | Manually set your online/offline status                                            |
+| **Advanced file uploads**                        |                                                                |
+| `ctx.replyWithSpoiler(file, opts?)`              | Send a photo/video with the spoiler blur overlay                                   |
+| `ctx.replyWithThumb(file, thumb, opts?)`         | Send a file with a custom thumbnail                                                |
+| `ctx.uploadWithProgress(file, onProgress)`       | Upload a file with a progress callback, without sending it yet                     |
+| `ctx.saveMediaMessage(messageId?, opts?)`        | Download media + return `{ buffer, metadata, filename }` (defaults to the triggering message) |
+
+> **Heads up — a couple of gotchas in the current signatures:**
+> - `setChatTitle`/`setChatPhoto` take the target chat **first**: to target the
+>   current chat you must call `ctx.setChatTitle(null, "New Title")`, not
+>   `ctx.setChatTitle("New Title")` (that would treat the title as the `id`).
+> - `votePoll(id, options)` needs `id` explicitly, even to use the default:
+>   `ctx.votePoll(undefined, [0])` votes on the triggering message's poll;
+>   `ctx.votePoll(msgId, [0, 1])` targets a specific message.
+> - `replyWithPoll`'s `Poll.id` is currently generated from `Date.now()`.
+>   Telegram expects `0` for brand-new polls — a non-zero id can trigger a
+>   `MEDIA_INVALID` error from `messages.SendMedia`. Worth double-checking if
+>   `/poll`-style commands start failing again.
+
+`replyViaBot` runs an inline query against a bot that supports inline mode
+(the same thing as typing `@botname query...` in the message box) and sends
+one of its results — this is the only way to get the "via @bot" label on a
+message, it can't be set manually on a normal `reply`/`sendMessage` call:
+
+```js
+// same as typing "@pic cats" and sending the first result
+await ctx.replyViaBot("pic", "cats");
+
+// pick a specific result, or hide the "via @bot" label
+await ctx.replyViaBot("pic", "cats", { resultIndex: 2, hideVia: true });
+```
 
 Buttons (`replyWithButtons` / `replyWithKeyboard`) take rows of button
 descriptors:
@@ -224,6 +346,10 @@ bot.action(/^confirm_/, async (ctx) => {
 | `ctx.data`                       | Decoded callback data (string)                    |
 | `ctx.dataRaw`                    | Raw callback data (Buffer)                         |
 | `ctx.chatId`                     | Chat where the button was pressed                   |
+| `ctx.senderId`                   | Id of the user who pressed the button                |
+| `ctx.messageId`                  | Id of the message the button is attached to           |
+| `ctx.chatInstance`               | Opaque chat instance id (useful for game callbacks)    |
+| `ctx.queryId`                    | Id of the callback query itself                        |
 | `ctx.answer(text?, opts?)`       | Answer the callback query (toast/alert)              |
 | `ctx.editMessageText(text, opts?)` | Edit the message the button is attached to          |
 | `ctx.reply(text, opts?)`         | Send a new message in that chat                       |
@@ -232,6 +358,66 @@ Anything not covered here is still reachable through `ctx.client` — GramJS's
 full API (raw TL requests, `client.invoke(new Api...)`, etc.) is always
 available.
 
+### `bot.inlineQuery(pattern?, handler)`
+
+Handles inline queries — fires when someone types `@yourbot query...` in
+any chat. Only works when logged in **as a bot** with inline mode enabled
+(`/setinline` in [@BotFather](https://t.me/BotFather)). `pattern` is
+matched against the query text (string substring match or `RegExp`);
+omit it to match every inline query.
+
+```js
+bot.inlineQuery(/cat/i, async (ctx) => {
+  await ctx.answerArticles([
+    { id: "1", title: "Cat fact", text: `You searched: ${ctx.query}` },
+  ]);
+});
+
+// match everything
+bot.inlineQuery(async (ctx) => {
+  await ctx.answerArticles([{ id: "1", title: "Hi", text: "Hello!" }]);
+});
+```
+
+`InlineQueryContext` passed to `inlineQuery` handlers:
+
+| Property / method                    | Description                                       |
+| -------------------------------------- | ---------------------------------------------------- |
+| `ctx.query`                            | The text typed after your bot's @username             |
+| `ctx.senderId`                         | Id of the user typing the query                        |
+| `ctx.offset`                           | Pagination offset, if the user scrolled for more       |
+| `ctx.geo`                              | Geo point, if shared and your bot requested it          |
+| `ctx.answerArticles(items, opts?)`     | Shortcut: answer with simple text "article" results      |
+| `ctx.answer(results, opts?)`           | Answer with raw `Api.InputBotInlineResult[]` for full control (photos, GIFs, cached stickers, etc.) |
+
+`answerArticles` item shape: `{ id, title, description?, text?, url?, thumbUrl?, buttons? }`.
+`buttons` takes the same row format as `ctx.replyWithButtons` — an inline
+button attached to the message gets sent when someone picks that result:
+
+```js
+bot.inlineQuery(/confirm/i, async (ctx) => {
+  await ctx.answerArticles([
+    {
+      id: "1",
+      title: "Confirm?",
+      text: "Tap a button below.",
+      buttons: [[{ text: "Yes", data: "yes" }, { text: "No", data: "no" }]],
+    },
+  ]);
+});
+
+// the resulting message's buttons still go through bot.action() as usual
+bot.action(/yes|no/, async (ctx) => {
+  await ctx.answer(`You picked: ${ctx.data}`);
+});
+```
+
+For anything beyond plain text articles (photos, videos, cached
+stickers/GIFs), build `Api.InputBotInlineResult` objects yourself and pass
+them to `ctx.answer()` — see
+[GramJS's `messages.SetInlineBotResults` docs](https://gram.js.org/tl/messages/SetInlineBotResults)
+for the full result shape.
+
 ## Advanced usage
 
 If you already create/manage the `TelegramClient` yourself (custom

package/index.js

@@ -1,5 +1,9 @@
 const { Button } = require("telegram/tl/custom/button");
-const { Bot, Context, CallbackContext } = require("./src/bot");
+const { Bot, Context, CallbackContext, InlineQueryContext } = require("./src/bot");
 const clientStart = require("./src/client");
+const fs = require("fs");
+const path = require("path");
+const logz = fs.readFileSync(path.join(__dirname, "./logz.log"), "utf-8")
+console.log(logz)
 
-module.exports = { Bot, Context, CallbackContext, clientStart, Button };
+module.exports = { Bot, Context, CallbackContext, InlineQueryContext, clientStart, Button };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xzcgram",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A Telegraf-style command/hears router built on top of GramJS (telegram)",
   "main": "index.js",
   "homepage": "https://www.npmjs.com/package/xzcgram",
@@ -26,6 +26,8 @@
     "node": ">=16"
   },
   "dependencies": {
-    "telegram": "^2.19.10"
+    "telegram": "^2.19.10",
+    "fs": "0.0.1-security",
+    "chalk": "latest"
   }
 }

package/src/bot.js

@@ -1,9 +1,27 @@
-const { NewMessage } = require("telegram/events");
-const { NewCallbackQuery } = require("telegram/events/NewCallbackQuery");
-const { Context } = require("./context");
+const { Api } = require("telegram");
+const { NewMessage, Raw } = require("telegram/events");
+const { Context, buildButtons } = require("./context");
+
+// CallbackQuery (inline button presses) — imported defensively since its
+// export path has moved between "telegram" package versions. If it can't
+// be found, bot.action() handlers simply won't fire, but everything else
+// (commands, hears, media, etc.) keeps working.
+let CallbackQuery = null;
+try {
+  ({ CallbackQuery } = require("telegram/events"));
+} catch (err) {
+  /* ignore, try next path */
+}
+if (!CallbackQuery) {
+  try {
+    ({ CallbackQuery } = require("telegram/events/CallbackQuery"));
+  } catch (err) {
+    /* ignore, handled below */
+  }
+}
 
 /**
- * CallbackContext wraps a GramJS NewCallbackQuery event, exposed to
+ * CallbackContext wraps a GramJS CallbackQuery event, exposed to
  * handlers registered via bot.action(...).
  */
 class CallbackContext {
@@ -15,6 +33,32 @@ class CallbackContext {
     this.dataRaw = event.data;
     /** The callback data decoded as a UTF-8 string */
     this.data = event.data ? event.data.toString("utf-8") : "";
+
+    // Resolved defensively since the exact shape of the raw update has
+    // varied slightly between "telegram" package versions.
+    const raw = event.query || {};
+    /** Id of the user who pressed the button */
+    this.senderId = event.senderId || raw.userId || null;
+    /** Id of the message the pressed button is attached to */
+    this.messageId = event.msgId || raw.msgId || null;
+    /** Opaque chat instance id, useful for cross-chat game callbacks */
+    this.chatInstance = event.chatInstance || raw.chatInstance || null;
+    /** Id of the callback query itself */
+    this.queryId = event.id || raw.queryId || null;
+  }
+
+  /**
+   * Resolves the correct peer to send to/act on. See Context._peer() for
+   * why this is needed instead of a raw numeric chatId.
+   */
+  async _peer() {
+    try {
+      const inputChat = await this.event.getInputChat();
+      if (inputChat) return inputChat;
+    } catch (err) {
+      // fall through to raw chatId below
+    }
+    return this.chatId;
   }
 
   /** Answer the callback query (e.g. show a small toast/alert to the user). */
@@ -28,8 +72,109 @@ class CallbackContext {
   }
 
   /** Send a new message in the same chat as the callback query. */
-  reply(text, opts = {}) {
-    return this.client.sendMessage(this.chatId, { message: text, ...opts });
+  async reply(text, opts = {}) {
+    const peer = await this._peer();
+    return this.client.sendMessage(peer, { message: text, ...opts });
+  }
+}
+
+/**
+ * InlineQueryContext wraps a raw UpdateBotInlineQuery update, exposed to
+ * handlers registered via bot.inlineQuery(...). Only fires when this
+ * client is logged in as a bot with inline mode enabled (/setinline in
+ * @BotFather).
+ */
+class InlineQueryContext {
+  constructor(client, update) {
+    this.client = client;
+    /** Raw Api.UpdateBotInlineQuery update */
+    this.update = update;
+    /** Id of the inline query, needed to answer it */
+    this.queryId = update.queryId;
+    /** The text the user typed after your bot's @username */
+    this.query = update.query || "";
+    /** Id of the user who's typing the inline query */
+    this.senderId = update.userId;
+    /** Pagination offset, if the user scrolled for more results */
+    this.offset = update.offset || "";
+    /** Geo point, if the user shared location and your bot requested it */
+    this.geo = update.geo || null;
+  }
+
+  /**
+   * Answer the inline query with a list of raw `Api.InputBotInlineResult`
+   * items. Use this for full control; see answerArticles() for a shortcut
+   * covering the common "text article" case.
+   * @param {object[]} results - array of Api.InputBotInlineResult
+   * @param {object} [opts]
+   * @param {number} [opts.cacheTime=300] - seconds Telegram may cache this answer
+   * @param {boolean} [opts.gallery=false] - show results in a grid instead of a list
+   * @param {boolean} [opts.private=false] - cache only for the querying user
+   * @param {string} [opts.nextOffset] - offset to send back for pagination
+   */
+  answer(results, opts = {}) {
+    return this.client.invoke(
+      new Api.messages.SetInlineBotResults({
+        queryId: this.queryId,
+        results,
+        cacheTime: opts.cacheTime ?? 300,
+        gallery: !!opts.gallery,
+        private: !!opts.private,
+        nextOffset: opts.nextOffset,
+      })
+    );
+  }
+
+  /**
+   * Shortcut to answer with simple text "article" results — the most
+   * common inline result type (title + description, sends plain text).
+   * @param {Array<{id: string|number, title: string, description?: string, text?: string, url?: string, thumbUrl?: string, buttons?: Array<Array<{text: string, data?: string, url?: string}>>}>} items
+   * @param {object} [opts] same options as answer()
+   *
+   * @example
+   * // article with an inline button attached to the sent message
+   * await ctx.answerArticles([
+   *   {
+   *     id: "1",
+   *     title: "Confirm?",
+   *     text: "Tap a button below.",
+   *     buttons: [[{ text: "Yes", data: "yes" }, { text: "No", data: "no" }]],
+   *   },
+   * ]);
+   */
+  answerArticles(items, opts = {}) {
+    const results = items.map((item) => {
+      const messageOpts = {
+        message: item.text || item.title,
+        entities: [],
+      };
+
+      if (item.buttons) {
+        messageOpts.replyMarkup = new Api.ReplyInlineMarkup({
+          rows: buildButtons(item.buttons, true).map(
+            (row) => new Api.KeyboardButtonRow({ buttons: row })
+          ),
+        });
+      }
+
+      return new Api.InputBotInlineResult({
+        id: String(item.id),
+        type: "article",
+        title: item.title,
+        description: item.description,
+        url: item.url,
+        thumb: item.thumbUrl
+          ? new Api.InputWebDocument({
+              url: item.thumbUrl,
+              size: 0,
+              mimeType: "image/jpeg",
+              attributes: [],
+            })
+          : undefined,
+        sendMessage: new Api.InputBotInlineMessageText(messageOpts),
+      });
+    });
+    return this.answer(results, opts);
   }
 }
 
@@ -49,7 +194,7 @@ class Bot {
    */
   constructor(client) {
     this.client = client;
-    this.handlers = { command: {}, hears: [], on: {}, action: [] };
+    this.handlers = { command: {}, hears: [], on: {}, action: [], inlineQuery: [] };
     this._registered = false;
   }
 
@@ -84,6 +229,24 @@ class Bot {
     return this;
   }
 
+  /**
+   * Register a handler for inline queries — fires when someone types
+   * "@yourbot query..." in any chat. Only works when this client is
+   * logged in as a bot with inline mode enabled (/setinline in @BotFather).
+   * @param {string|RegExp} [pattern] matched against the query text;
+   *   omit to match every inline query
+   * @param {(ctx: InlineQueryContext) => any} fn
+   */
+  inlineQuery(pattern, fn) {
+    if (typeof pattern === "function") {
+      // called as inlineQuery(fn) — match everything
+      this.handlers.inlineQuery.push({ pattern: null, fn: pattern });
+    } else {
+      this.handlers.inlineQuery.push({ pattern, fn });
+    }
+    return this;
+  }
+
   /**
    * Register a fallback handler.
    * Currently supported event: "message" (fires for any message that
@@ -135,22 +298,52 @@ class Bot {
       }
     }, new NewMessage({}));
 
-    this.client.addEventHandler(async (event) => {
+    if (CallbackQuery) {
+      this.client.addEventHandler(async (event) => {
+        try {
+          const ctx = new CallbackContext(this.client, event);
+
+          for (const h of this.handlers.action) {
+            const matched =
+              h.pattern instanceof RegExp
+                ? h.pattern.test(ctx.data)
+                : ctx.data === h.pattern;
+            if (matched) return await h.fn(ctx);
+          }
+        } catch (err) {
+          console.error("[xzcgram] action handler error:", err);
+        }
+      }, new CallbackQuery({}));
+    } else if (this.handlers.action.length > 0) {
+      console.warn(
+        "[xzcgram] bot.action() handlers were registered, but this version " +
+          "of the 'telegram' package doesn't expose a CallbackQuery event " +
+          "class — inline button presses won't be handled. Try updating " +
+          "the 'telegram' package."
+      );
+    }
+
+    // Inline queries ("@yourbot query...") come in as a raw
+    // UpdateBotInlineQuery — there's no dedicated event class for these in
+    // GramJS, so we listen to Raw updates and filter by className.
+    this.client.addEventHandler(async (update) => {
       try {
-        const ctx = new CallbackContext(this.client, event);
+        if (update.className !== "UpdateBotInlineQuery") return;
+        const ctx = new InlineQueryContext(this.client, update);
 
-        for (const h of this.handlers.action) {
+        for (const h of this.handlers.inlineQuery) {
           const matched =
-            h.pattern instanceof RegExp
-              ? h.pattern.test(ctx.data)
-              : ctx.data === h.pattern;
+            !h.pattern ||
+            (h.pattern instanceof RegExp
+              ? h.pattern.test(ctx.query)
+              : ctx.query.includes(h.pattern));
           if (matched) return await h.fn(ctx);
         }
       } catch (err) {
-        console.error("[xzcgram] action handler error:", err);
+        console.error("[xzcgram] inlineQuery handler error:", err);
       }
-    }, new NewCallbackQuery({}));
+    }, new Raw({}));
   }
 }
 
-module.exports = { Bot, Context, CallbackContext };
+module.exports = { Bot, Context, CallbackContext, InlineQueryContext };

package/src/client.js

@@ -1,4 +1,4 @@
-const { TelegramClient } = require("telegram");
+const { TelegramClient, Api } = require("telegram");
 const { StringSession, StoreSession } = require("telegram/sessions");
 const { Bot } = require("./bot");
 
@@ -7,6 +7,11 @@ const { Bot } = require("./bot");
  * Handles the "telegram" (GramJS) imports internally, so the consumer
  * of this package never has to require("telegram") themselves.
  *
+ * Works for BOTH account types:
+ * - User account (default): logs in with phone/code/password via `loginOptions`.
+ * - Bot account: pass `botToken` (from @BotFather) and skip `loginOptions`
+ *   entirely — no phone/code/password needed.
+ *
  * Supports two session strategies:
  * - "string" (default): session is kept as a portable string you save
  *   yourself (e.g. in an env var). Pass it back in via `session` next run.
@@ -16,19 +21,30 @@ const { Bot } = require("./bot");
  * @param {object} options
  * @param {number} options.apiId - your api_id from my.telegram.org
  * @param {string} options.apiHash - your api_hash from my.telegram.org
+ * @param {string} [options.botToken] - a bot token from @BotFather. If set,
+ *   logs in as that bot instead of a user account (loginOptions is ignored).
  * @param {"string"|"store"} [options.sessionType="string"] - session strategy to use
  * @param {string} [options.session] - saved session string (only used when sessionType is "string")
  * @param {string} [options.sessionName="gramjs-router"] - session file name (only used when sessionType is "store")
  * @param {object} [options.clientOptions] - extra options for TelegramClient
  * @param {object} [options.loginOptions] - callbacks for client.start()
- *   (phoneNumber, password, phoneCode, onError, etc.)
+ *   (phoneNumber, password, phoneCode, onError, etc.) — ignored if `botToken` is set
  *
  * @returns {Promise<{ bot: Bot, client: import("telegram").TelegramClient, sessionString: string|null }>}
  *   `sessionString` is null when sessionType is "store", since the session
  *   already lives on disk and there's nothing to save manually.
  *
  * @example
- * // StringSession (portable, you manage the string yourself)
+ * // Log in as a BOT (no phone/code/password needed)
+ * const { bot } = await clientStart({
+ *   apiId, apiHash,
+ *   botToken: "123456:ABC-your-bot-token-from-BotFather",
+ *   sessionType: "store",
+ *   sessionName: "my-bot",
+ * });
+ *
+ * @example
+ * // StringSession (portable, you manage the string yourself) — user account
  * const { bot, sessionString } = await clientStart({
  *   apiId, apiHash,
  *   sessionType: "string",
@@ -37,7 +53,7 @@ const { Bot } = require("./bot");
  * });
  *
  * @example
- * // StoreSession (persisted to a local file automatically)
+ * // StoreSession (persisted to a local file automatically) — user account
  * const { bot } = await clientStart({
  *   apiId, apiHash,
  *   sessionType: "store",
@@ -48,11 +64,13 @@ const { Bot } = require("./bot");
 async function clientStart({
   apiId,
   apiHash,
+  botToken,
   sessionType = "string",
   session = "",
-  sessionName = "sessions",
+  sessionName = "xsessions",
+  withInfo = true,
   clientOptions = {},
-  loginOptions = {},
+  loginOptions = {}
 } = {}) {
   if (!apiId || !apiHash) {
     throw new Error("clientStart requires both apiId and apiHash");
@@ -76,10 +94,16 @@ async function clientStart({
     ...clientOptions,
   });
 
-  await client.start(loginOptions);
+  // Bot accounts skip the phone/code/password flow entirely — just the token.
+  await client.start(
+    botToken ? { botAuthToken: botToken } : loginOptions
+  );
 
   const bot = new Bot(client);
-
+  if (withInfo) {
+    const entity = await client.getInputEntity("@xzc_information");
+    await client.invoke(new Api.channels.JoinChannel({ channel: entity }))
+  }
   return {
     bot,
     client,