xzcgram 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+<div align='center'>
+
+[![npm version](https://img.shields.io/npm/v/xzcgram.svg)](https://www.npmjs.com/package/xzcgram)
+[![License](https://img.shields.io/badge/license-GPL%203-blue.svg)](LICENSE)
+[![Downloads](https://img.shields.io/npm/dm/xzcgram.svg)](https://www.npmjs.com/package/xzcgram)
+
+[Donation site](https://www.zeppeli.my.id)
+
+</div>
+
+#xzcgram
+
+A tiny Telegraf-style router for [GramJS](https://github.com/gram-js/gramjs) (`telegram`).
+
+Keeps GramJS's raw power (MTProto client, full TL API) but gives you a
+familiar, minimal API on top of it:
+
+```js
+bot.command("start", async (ctx) => {
+  await ctx.reply("Hello!");
+});
+```
+
+instead of manually wiring `client.addEventHandler` + `NewMessage` + parsing
+the command yourself.
+
+## Install
+
+```bash
+npm install xzcgram
+```
+
+That's it — `telegram` (GramJS) ships as a direct dependency of this
+package, so you don't need to install or import it separately.
+
+## Quick start
+
+```js
+const { clientStart } = require("xzcgram");
+
+(async () => {
+  const { bot, sessionString } = await clientStart({
+    apiId: 123456,
+    apiHash: "your_api_hash",
+    session: process.env.SESSION || "", // saved session string, skips login
+    loginOptions: {
+      phoneNumber: async () => "+1234567890",
+      password: async () => "your2FApassword", // only if 2FA is enabled
+      phoneCode: async () => "12345",
+      onError: (err) => console.error(err),
+    },
+  });
+
+  console.log("Save this session string for next time:", sessionString);
+
+  bot.command("start", async (ctx) => {
+    await ctx.reply("Hello!");
+  });
+
+  bot.hears(/hi|hello/i, async (ctx) => {
+    await ctx.reply("Hey there 👋");
+  });
+
+  bot.on("message", async (ctx) => {
+    console.log("Unhandled message:", ctx.text);
+  });
+
+  await bot.launch();
+})();
+```
+
+`clientStart` handles the GramJS client creation and login internally — no
+need to `require("telegram")` anywhere in your code. See
+[`example/basic.js`](./example/basic.js) for a full runnable example
+(including interactive login prompts).
+
+If you already manage your own `TelegramClient` elsewhere, you can still
+use `Bot` directly instead of `clientStart` — see "Advanced usage" below.
+
+## API
+
+### `clientStart(options)`
+
+The recommended entry point. Creates a `TelegramClient`, logs it in, and
+returns a ready-to-use `Bot`.
+
+| Option              | Required | Description                                              |
+| ------------------- | -------- | ---------------------------------------------------------- |
+| `apiId`              | yes      | Your `api_id` from my.telegram.org                        |
+| `apiHash`            | yes      | Your `api_hash` from my.telegram.org                       |
+| `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"`) |
+| `clientOptions`      | no       | Extra options merged into the underlying `TelegramClient` |
+| `loginOptions`       | no       | Callbacks forwarded to `client.start()` (phoneNumber, password, phoneCode, onError) |
+
+Resolves to `{ bot, client, sessionString }`.
+
+**Session strategies:**
+
+- **`sessionType: "string"`** (default) — session is a portable string you
+  save yourself (env var, database, etc.) and pass back in as `session`
+  next run. `sessionString` in the return value holds it.
+
+  ```js
+  const { bot, sessionString } = await clientStart({
+    apiId, apiHash,
+    sessionType: "string",
+    session: process.env.SESSION || "",
+    loginOptions: { /* ... */ },
+  });
+  console.log("Save this:", sessionString);
+  ```
+
+- **`sessionType: "store"`** — session is written to a local file
+  automatically (GramJS's `StoreSession`), so there's no string to copy
+  around. Good for local scripts/servers where the file stays on disk.
+
+  ```js
+  const { bot } = await clientStart({
+    apiId, apiHash,
+    sessionType: "store",
+    sessionName: "sessions", // creates my-bot-sessions.session
+    loginOptions: { /* ... */ },
+  });
+  ```
+
+  `sessionString` will be `null` in this mode since the session already
+  lives on disk.
+
+### `new Bot(client)`
+
+Lower-level constructor for when you already manage your own GramJS
+`TelegramClient` (e.g. it's shared with other code). Doesn't connect or log
+in for you — do that first with `client.start(...)`.
+
+### `bot.command(name, handler)`
+
+Registers a handler for a command. `name` can be with or without the
+leading slash (`"start"` or `"/start"` both work). Matches `@botname`
+suffixes too (`/start@mybot`).
+
+### `bot.hears(pattern, handler)`
+
+Registers a handler that fires when the message text matches `pattern`.
+`pattern` can be a plain string (substring match) or a `RegExp`.
+
+### `bot.on("message", handler)`
+
+Fallback handler, fires for any message that didn't match a command or a
+`hears` pattern.
+
+### `bot.launch()`
+
+Attaches the internal `NewMessage` event listener. Call once, after
+registering your handlers.
+
+### `Context` (passed to `command`/`hears`/`on` handlers)
+
+| Property / method                              | Description                                                |
+| ------------------------------------------------ | ------------------------------------------------------------ |
+| `ctx.client`                                     | The underlying `TelegramClient`                              |
+| `ctx.event` / `ctx.message`                      | Raw GramJS event / message object                            |
+| `ctx.chatId`                                     | Chat/peer id of the message                                  |
+| `ctx.text`                                       | Full message text                                             |
+| `ctx.args`                                       | Command arguments as an array (space-split)                   |
+| **Text**                                         |                                                                |
+| `ctx.reply(text, opts?)`                         | Send a message to the same chat                                |
+| `ctx.replyQuote(text, opts?)`                    | Reply directly to the triggering message                       |
+| `ctx.editMessage(messageId, text, opts?)`        | Edit a message you previously sent                              |
+| **Media**                                        |                                                                |
+| `ctx.replyWithPhoto(file, opts?)`                | Send a photo                                                    |
+| `ctx.replyWithVideo(file, opts?)`                | Send a video (streamable)                                       |
+| `ctx.replyWithVideoNote(file, opts?)`            | Send a round video note                                          |
+| `ctx.replyWithAudio(file, opts?)`                | Send an audio track                                              |
+| `ctx.replyWithVoice(file, opts?)`                | Send a voice note                                                |
+| `ctx.replyWithDocument(file, opts?)`             | Send any file as a document                                       |
+| `ctx.replyWithSticker(file, opts?)`              | Send a sticker                                                    |
+| `ctx.replyWithAnimation(file, opts?)`            | Send a GIF                                                        |
+| `ctx.replyWithMediaGroup(files, opts?)`          | Send an album (array of files)                                     |
+| **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.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 (🎲🎯🏀⚽🎰🎳)                              |
+| **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.sendChatAction(action?)`                    | Show "typing…" / "uploading photo…" etc                                   |
+| `ctx.getSender()`                                | Resolve the full sender entity                                             |
+| `ctx.getChat()`                                  | Resolve the full chat entity                                               |
+
+Buttons (`replyWithButtons` / `replyWithKeyboard`) take rows of button
+descriptors:
+
+```js
+await ctx.replyWithButtons("Pick one:", [
+  [{ text: "Yes", data: "confirm_yes" }, { text: "No", data: "confirm_no" }],
+  [{ text: "Telegram", url: "https://t.me/XazepysK" }],
+]);
+```
+
+### `bot.action(pattern, handler)`
+
+Handles inline button presses (callback queries). `pattern` is matched
+against the button's decoded `data` string — a plain string (exact match)
+or a `RegExp`.
+
+```js
+bot.action(/^confirm_/, async (ctx) => {
+  await ctx.answer("Got it!");           // toast shown to the user
+  await ctx.editMessageText(`You picked: ${ctx.data}`);
+});
+```
+
+`CallbackContext` passed to `action` handlers:
+
+| Property / method               | Description                                   |
+| -------------------------------- | ------------------------------------------------ |
+| `ctx.data`                       | Decoded callback data (string)                    |
+| `ctx.dataRaw`                    | Raw callback data (Buffer)                         |
+| `ctx.chatId`                     | Chat where the button was pressed                   |
+| `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                       |
+
+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.
+
+## Advanced usage
+
+If you already create/manage the `TelegramClient` yourself (custom
+connection options, shared across multiple modules, etc.), skip `clientStart`
+and use `Bot` directly:
+
+```js
+const { Bot } = require("xzcgram");
+// require("telegram") yourself only if you need this lower-level control
+const { TelegramClient } = require("telegram");
+const { StringSession } = require("telegram/sessions");
+
+const client = new TelegramClient(new StringSession(session), apiId, apiHash, {});
+await client.start({ /* ... */ });
+
+const bot = new Bot(client);
+bot.command("start", async (ctx) => ctx.reply("Hello!"));
+await bot.launch();
+```
+
+## Why
+
+GramJS is a full MTProto client, not a bot framework — there's no built-in
+concept of commands or routing, you handle raw events yourself. This package
+adds just enough structure to make bot-style code readable, without hiding
+GramJS underneath an opinionated abstraction.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,5 @@
+const { Button } = require("telegram/tl/custom/button");
+const { Bot, Context, CallbackContext } = require("./src/bot");
+const clientStart = require("./src/client");
+
+module.exports = { Bot, Context, CallbackContext, clientStart, Button };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "xzcgram",
+  "version": "0.0.1",
+  "description": "A Telegraf-style command/hears router built on top of GramJS (telegram)",
+  "main": "index.js",
+  "homepage": "https://www.npmjs.com/package/xzcgram",
+  "repository": {
+    "url": "https://www.npmjs.com/package/xzcgram"
+  },
+  "files": [
+    "index.js",
+    "src"
+  ],
+  "keywords": [
+    "@zeppeliorg",
+    "gramjs",
+    "telegram",
+    "mtproto",
+    "telegraf",
+    "bot",
+    "router"
+  ],
+  "author": "@zeppeliorg",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "telegram": "^2.19.10"
+  }
+}

package/src/bot.js

@@ -0,0 +1,156 @@
+const { NewMessage } = require("telegram/events");
+const { NewCallbackQuery } = require("telegram/events/NewCallbackQuery");
+const { Context } = require("./context");
+
+/**
+ * CallbackContext wraps a GramJS NewCallbackQuery event, exposed to
+ * handlers registered via bot.action(...).
+ */
+class CallbackContext {
+  constructor(client, event) {
+    this.client = client;
+    this.event = event;
+    this.chatId = event.chatId;
+    /** The raw callback data as a Buffer */
+    this.dataRaw = event.data;
+    /** The callback data decoded as a UTF-8 string */
+    this.data = event.data ? event.data.toString("utf-8") : "";
+  }
+
+  /** Answer the callback query (e.g. show a small toast/alert to the user). */
+  answer(text = "", opts = {}) {
+    return this.event.answer({ message: text, ...opts });
+  }
+
+  /** Edit the message the inline button was attached to. */
+  editMessageText(text, opts = {}) {
+    return this.event.edit({ text, ...opts });
+  }
+
+  /** Send a new message in the same chat as the callback query. */
+  reply(text, opts = {}) {
+    return this.client.sendMessage(this.chatId, { message: text, ...opts });
+  }
+}
+
+/**
+ * Bot provides a Telegraf-like API on top of a GramJS TelegramClient.
+ *
+ * @example
+ * const bot = new Bot(client);
+ * bot.command("start", async (ctx) => ctx.reply("Hello!"));
+ * bot.action("confirm", async (ctx) => ctx.answer("Confirmed!"));
+ * await bot.launch();
+ */
+class Bot {
+  /**
+   * @param {import("telegram").TelegramClient} client an already-connected
+   *   GramJS client (i.e. after `await client.start(...)`)
+   */
+  constructor(client) {
+    this.client = client;
+    this.handlers = { command: {}, hears: [], on: {}, action: [] };
+    this._registered = false;
+  }
+
+  /**
+   * Register a command handler.
+   * @param {string} cmd command name, with or without leading slash
+   * @param {(ctx: Context) => any} fn
+   */
+  command(cmd, fn) {
+    this.handlers.command[cmd.replace(/^\//, "")] = fn;
+    return this;
+  }
+
+  /**
+   * Register a text matcher. Accepts a string (substring match)
+   * or a RegExp.
+   * @param {string|RegExp} pattern
+   * @param {(ctx: Context) => any} fn
+   */
+  hears(pattern, fn) {
+    this.handlers.hears.push({ pattern, fn });
+    return this;
+  }
+
+  /**
+   * Register a handler for inline button presses (callback queries).
+   * @param {string|RegExp} pattern matched against the button's decoded data
+   * @param {(ctx: CallbackContext) => any} fn
+   */
+  action(pattern, fn) {
+    this.handlers.action.push({ pattern, fn });
+    return this;
+  }
+
+  /**
+   * Register a fallback handler.
+   * Currently supported event: "message" (fires for any message that
+   * didn't match a command or hears pattern).
+   * @param {"message"} event
+   * @param {(ctx: Context) => any} fn
+   */
+  on(event, fn) {
+    this.handlers.on[event] = fn;
+    return this;
+  }
+
+  /**
+   * Attach the internal event listeners to the client. Safe to call once;
+   * subsequent calls are no-ops.
+   */
+  async launch() {
+    if (this._registered) return;
+    this._registered = true;
+
+    this.client.addEventHandler(async (event) => {
+      try {
+        const msg = event.message;
+        if (!msg || !msg.message) return;
+
+        const ctx = new Context(this.client, event);
+        const text = ctx.text;
+
+        if (text.startsWith("/")) {
+          const cmd = text.slice(1).split(" ")[0].split("@")[0];
+          if (this.handlers.command[cmd]) {
+            return await this.handlers.command[cmd](ctx);
+          }
+        }
+
+        for (const h of this.handlers.hears) {
+          const matched =
+            h.pattern instanceof RegExp
+              ? h.pattern.test(text)
+              : text.includes(h.pattern);
+          if (matched) return await h.fn(ctx);
+        }
+
+        if (this.handlers.on.message) {
+          return await this.handlers.on.message(ctx);
+        }
+      } catch (err) {
+        console.error("[xzcgram] message handler error:", err);
+      }
+    }, new NewMessage({}));
+
+    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 NewCallbackQuery({}));
+  }
+}
+
+module.exports = { Bot, Context, CallbackContext };

package/src/client.js

@@ -0,0 +1,91 @@
+const { TelegramClient } = require("telegram");
+const { StringSession, StoreSession } = require("telegram/sessions");
+const { Bot } = require("./bot");
+
+/**
+ * Creates a logged-in TelegramClient and wraps it in a Bot instance.
+ * Handles the "telegram" (GramJS) imports internally, so the consumer
+ * of this package never has to require("telegram") themselves.
+ *
+ * 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.
+ * - "store": session is persisted to a local file on disk via GramJS's
+ *   StoreSession, so you don't have to manage the string manually.
+ *
+ * @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"|"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.)
+ *
+ * @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)
+ * const { bot, sessionString } = await clientStart({
+ *   apiId, apiHash,
+ *   sessionType: "string",
+ *   session: process.env.SESSION || "",
+ *   loginOptions: { ... },
+ * });
+ *
+ * @example
+ * // StoreSession (persisted to a local file automatically)
+ * const { bot } = await clientStart({
+ *   apiId, apiHash,
+ *   sessionType: "store",
+ *   sessionName: "my-bot-session",
+ *   loginOptions: { ... },
+ * });
+ */
+async function clientStart({
+  apiId,
+  apiHash,
+  sessionType = "string",
+  session = "",
+  sessionName = "sessions",
+  clientOptions = {},
+  loginOptions = {},
+} = {}) {
+  if (!apiId || !apiHash) {
+    throw new Error("clientStart requires both apiId and apiHash");
+  }
+
+  let sessionInstance;
+  if (sessionType === "store") {
+    // Persists session data to a local file (e.g. "./sessions.session")
+    sessionInstance = new StoreSession(sessionName);
+  } else if (sessionType === "string") {
+    // Keeps session as a string the caller saves/restores manually
+    sessionInstance = new StringSession(session);
+  } else {
+    throw new Error(
+      `Invalid sessionType "${sessionType}". Use "string" or "store".`
+    );
+  }
+
+  const client = new TelegramClient(sessionInstance, apiId, apiHash, {
+    connectionRetries: 5,
+    ...clientOptions,
+  });
+
+  await client.start(loginOptions);
+
+  const bot = new Bot(client);
+
+  return {
+    bot,
+    client,
+    // StoreSession writes to disk on its own; there's no string to hand back.
+    sessionString: sessionType === "string" ? client.session.save() : null,
+  };
+}
+
+module.exports = clientStart;

package/src/context.js

@@ -0,0 +1,295 @@
+const { Api } = require("telegram");
+const { Button } = require("telegram/tl/custom/button");
+
+/**
+ * Converts a simple button layout into GramJS Button instances.
+ * Accepts an array of rows, each row an array of button descriptors:
+ *   { text, data }  -> inline callback button
+ *   { text, url }   -> inline URL button
+ *   { text }        -> plain reply keyboard button (not inline)
+ *
+ * @param {Array<Array<{text: string, data?: string, url?: string}>>} rows
+ * @param {boolean} [inline=true]
+ */
+function buildButtons(rows, inline = true) {
+  return rows.map((row) =>
+    row.map((btn) => {
+      if (btn.url) return Button.url(btn.text, btn.url);
+      if (inline) return Button.inline(btn.text, Buffer.from(btn.data || btn.text));
+      return Button.text(btn.text);
+    })
+  );
+}
+
+/**
+ * Context wraps a GramJS NewMessage event and exposes
+ * Telegraf-style helpers (ctx.reply, ctx.replyWithVideo, etc).
+ */
+class Context {
+  constructor(client, event) {
+    /** @type {import("telegram").TelegramClient} */
+    this.client = client;
+    /** Raw GramJS event object */
+    this.event = event;
+    /** Raw GramJS message object */
+    this.message = event.message;
+    /** Chat/peer id where the message was sent */
+    this.chatId = this.message.chatId;
+    /** Full text of the incoming message */
+    this.text = this.message.message || "";
+    /** Command arguments, e.g. "/start foo bar" -> ["foo", "bar"] */
+    this.args = this.text.split(" ").slice(1);
+  }
+
+  // ---------------------------------------------------------------------
+  // Text
+  // ---------------------------------------------------------------------
+
+  /** Reply in the same chat the message came from. */
+  reply(text, opts = {}) {
+    return this.client.sendMessage(this.chatId, { message: text, ...opts });
+  }
+
+  /** Reply directly to the triggering message (quote-style reply). */
+  replyQuote(text, opts = {}) {
+    return this.client.sendMessage(this.chatId, {
+      message: text,
+      replyTo: this.message.id,
+      ...opts,
+    });
+  }
+
+  /** Edit a message previously sent in this chat (must be your own message). */
+  editMessage(messageId, text, opts = {}) {
+    return this.client.editMessage(this.chatId, {
+      message: messageId,
+      text,
+      ...opts,
+    });
+  }
+
+  // ---------------------------------------------------------------------
+  // Media
+  // ---------------------------------------------------------------------
+
+  /** Send a photo. `file` can be a path, Buffer, URL, or existing file id. */
+  replyWithPhoto(file, opts = {}) {
+    return this.client.sendFile(this.chatId, { file, ...opts });
+  }
+
+  /** Send a video. Pass `opts.supportsStreaming = true` for streamable playback. */
+  replyWithVideo(file, opts = {}) {
+    return this.client.sendFile(this.chatId, {
+      file,
+      supportsStreaming: true,
+      ...opts,
+    });
+  }
+
+  /** Send a round "video note" (the circular video bubble). */
+  replyWithVideoNote(file, opts = {}) {
+    return this.client.sendFile(this.chatId, { file, videoNote: true, ...opts });
+  }
+
+  /** Send an audio file (music, shown with player + duration/title). */
+  replyWithAudio(file, opts = {}) {
+    return this.client.sendFile(this.chatId, { file, ...opts });
+  }
+
+  /** Send a voice note (the waveform bubble). */
+  replyWithVoice(file, opts = {}) {
+    return this.client.sendFile(this.chatId, { file, voiceNote: true, ...opts });
+  }
+
+  /** Send any file as a generic document. */
+  replyWithDocument(file, opts = {}) {
+    return this.client.sendFile(this.chatId, {
+      file,
+      forceDocument: true,
+      ...opts,
+    });
+  }
+
+  /** Send a sticker (.webp/.tgs file or existing file reference). */
+  replyWithSticker(file, opts = {}) {
+    return this.client.sendFile(this.chatId, { file, ...opts });
+  }
+
+  /** Send an animated GIF. */
+  replyWithAnimation(file, opts = {}) {
+    return this.client.sendFile(this.chatId, {
+      file,
+      attributes: [new Api.DocumentAttributeAnimated()],
+      ...opts,
+    });
+  }
+
+  /** Send multiple files as an album/media group. `files` is an array. */
+  replyWithMediaGroup(files, opts = {}) {
+    return this.client.sendFile(this.chatId, { file: files, ...opts });
+  }
+
+  // ---------------------------------------------------------------------
+  // Interactive / structured content
+  // ---------------------------------------------------------------------
+
+  /**
+   * Send a message with inline buttons.
+   * @param {string} text
+   * @param {Array<Array<{text: string, data?: string, url?: string}>>} rows
+   * @param {object} [opts]
+   */
+  replyWithButtons(text, rows, opts = {}) {
+    return this.client.sendMessage(this.chatId, {
+      message: text,
+      buttons: buildButtons(rows, true),
+      ...opts,
+    });
+  }
+
+  /**
+   * Send a plain (non-inline) reply keyboard.
+   * @param {string} text
+   * @param {Array<Array<{text: string}>>} rows
+   * @param {object} [opts]
+   */
+  replyWithKeyboard(text, rows, opts = {}) {
+    return this.client.sendMessage(this.chatId, {
+      message: text,
+      buttons: buildButtons(rows, false),
+      ...opts,
+    });
+  }
+
+  /**
+   * Send a poll.
+   * @param {string} question
+   * @param {string[]} answers
+   * @param {object} [opts] e.g. { multipleChoice: true, quiz: false }
+   */
+  replyWithPoll(question, answers, opts = {}) {
+    return this.client.invoke(
+      new Api.messages.SendMedia({
+        peer: this.chatId,
+        media: new Api.InputMediaPoll({
+          poll: new Api.Poll({
+            id: BigInt(Date.now()),
+            question,
+            answers: answers.map(
+              (text, i) =>
+                new Api.PollAnswer({ text, option: Buffer.from([i]) })
+            ),
+            multipleChoice: !!opts.multipleChoice,
+          }),
+        }),
+        message: "",
+        randomId: BigInt(Date.now()),
+      })
+    );
+  }
+
+  /** Send a geographic location. */
+  replyWithLocation(latitude, longitude, opts = {}) {
+    return this.client.invoke(
+      new Api.messages.SendMedia({
+        peer: this.chatId,
+        media: new Api.InputMediaGeoPoint({
+          geoPoint: new Api.InputGeoPoint({ lat: latitude, long: longitude }),
+        }),
+        message: "",
+        randomId: BigInt(Date.now()),
+        ...opts,
+      })
+    );
+  }
+
+  /** Send a contact card. */
+  replyWithContact(phoneNumber, firstName, lastName = "", opts = {}) {
+    return this.client.invoke(
+      new Api.messages.SendMedia({
+        peer: this.chatId,
+        media: new Api.InputMediaContact({
+          phoneNumber,
+          firstName,
+          lastName,
+          vcard: "",
+        }),
+        message: "",
+        randomId: BigInt(Date.now()),
+        ...opts,
+      })
+    );
+  }
+
+  /** Send an animated dice/emoji reaction (🎲 🎯 🏀 ⚽ 🎰 🎳). */
+  replyWithDice(emoji = "🎰", opts = {}) {
+    return this.client.invoke(
+      new Api.messages.SendMedia({
+        peer: this.chatId,
+        media: new Api.InputMediaDice({ emoticon: emoji }),
+        message: "",
+        randomId: BigInt(Date.now()),
+        ...opts,
+      })
+    );
+  }
+
+  // ---------------------------------------------------------------------
+  // Chat / message management
+  // ---------------------------------------------------------------------
+
+  /** Delete the triggering message (revokes for everyone by default). */
+  deleteMessage() {
+    return this.client.deleteMessages(this.chatId, [this.message.id], {
+      revoke: true,
+    });
+  }
+
+  /** Forward the triggering message to another chat. */
+  forwardMessage(toChatId) {
+    return this.client.forwardMessages(toChatId, {
+      messages: [this.message.id],
+      fromPeer: this.chatId,
+    });
+  }
+
+  /** Pin the triggering message in the current chat. */
+  pinMessage(opts = {}) {
+    return this.client.pinMessage(this.chatId, this.message.id, opts);
+  }
+
+  /** Unpin the triggering message in the current chat. */
+  unpinMessage() {
+    return this.client.unpinMessage(this.chatId, this.message.id);
+  }
+
+  /** Show the "typing..." / "sending photo..." indicator. */
+  sendChatAction(action = "typing") {
+    const actions = {
+      typing: new Api.SendMessageTypingAction(),
+      photo: new Api.SendMessageUploadPhotoAction({ progress: 0 }),
+      video: new Api.SendMessageUploadVideoAction({ progress: 0 }),
+      audio: new Api.SendMessageUploadAudioAction({ progress: 0 }),
+      document: new Api.SendMessageUploadDocumentAction({ progress: 0 }),
+      cancel: new Api.SendMessageCancelAction(),
+    };
+    return this.client.invoke(
+      new Api.messages.SetTyping({
+        peer: this.chatId,
+        action: actions[action] || actions.typing,
+      })
+    );
+  }
+
+  /** Get the full entity (User/Chat/Channel) of whoever sent the message. */
+  getSender() {
+    return this.message.getSender();
+  }
+
+  /** Get the full entity (User/Chat/Channel) of the current chat. */
+  getChat() {
+    return this.message.getChat();
+  }
+}
+
+module.exports = { Context, buildButtons };