gramio 0.6.2 → 0.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Bot API](https://img.shields.io/badge/Bot%20API-9.4-blue?logo=telegram&style=flat&labelColor=000&color=3b82f6)](https://core.telegram.org/bots/api)
+[![Bot API](https://img.shields.io/badge/Bot%20API-9.5-blue?logo=telegram&style=flat&labelColor=000&color=3b82f6)](https://core.telegram.org/bots/api)
 [![npm](https://img.shields.io/npm/v/gramio?logo=npm&style=flat&labelColor=000&color=3b82f6)](https://www.npmjs.org/package/gramio)
 [![npm downloads](https://img.shields.io/npm/dw/gramio?logo=npm&style=flat&labelColor=000&color=3b82f6)](https://www.npmjs.org/package/gramio)
 [![JSR](https://jsr.io/badges/@gramio/core)](https://jsr.io/@gramio/core)

package/dist/index.cjs

@@ -8,9 +8,139 @@ var keyboards = require('@gramio/keyboards');
 var fs = require('node:fs/promises');
 var node_stream = require('node:stream');
 var debug = require('debug');
-var utils = require('./utils-DCXj-tb5.cjs');
+var utils = require('./utils-BKLnNOBm.cjs');
 var composer = require('@gramio/composer');
 
+const ALL_NAMES = [
+  "message",
+  "edited_message",
+  "channel_post",
+  "edited_channel_post",
+  "business_connection",
+  "business_message",
+  "edited_business_message",
+  "deleted_business_messages",
+  "message_reaction",
+  "message_reaction_count",
+  "inline_query",
+  "chosen_inline_result",
+  "callback_query",
+  "shipping_query",
+  "pre_checkout_query",
+  "purchased_paid_media",
+  "poll",
+  "poll_answer",
+  "my_chat_member",
+  "chat_member",
+  "chat_join_request",
+  "chat_boost",
+  "removed_chat_boost"
+];
+const MESSAGE_PARENT_TYPES = [
+  "message",
+  "edited_message",
+  "channel_post",
+  "edited_channel_post",
+  "business_message"
+];
+const OPT_IN_TYPES = [
+  "chat_member",
+  "message_reaction",
+  "message_reaction_count"
+];
+const KNOWN_EVENTS = new Set(Object.keys(contexts.contextsMappings));
+const ALL_NAMES_SET = new Set(ALL_NAMES);
+function mapEventToAllowedUpdates(event) {
+  if (ALL_NAMES_SET.has(event)) return [event];
+  if (KNOWN_EVENTS.has(event)) return MESSAGE_PARENT_TYPES;
+  return void 0;
+}
+function detectOptInUpdates(registeredEvents) {
+  return OPT_IN_TYPES.filter((type) => registeredEvents.has(type));
+}
+class AllowedUpdatesFilter extends Array {
+  /** @internal use static factory methods instead */
+  constructor(updates) {
+    super(...updates);
+  }
+  /**
+   * All update types, including the opt-in ones:
+   * `chat_member`, `message_reaction`, and `message_reaction_count`.
+   */
+  static get all() {
+    return new AllowedUpdatesFilter(ALL_NAMES);
+  }
+  /**
+   * Telegram's **default** update set.
+   *
+   * Receive all updates _except_ `chat_member`, `message_reaction`, and
+   * `message_reaction_count` — the three types that Telegram requires to be
+   * explicitly listed in `allowed_updates`.
+   *
+   * This matches what Telegram does when `allowed_updates` is omitted or
+   * passed as an empty array.
+   */
+  static get default() {
+    return AllowedUpdatesFilter.all.except(
+      "chat_member",
+      "message_reaction",
+      "message_reaction_count"
+    );
+  }
+  /**
+   * Create a filter with **exactly** the specified update types.
+   *
+   * @example
+   * ```typescript
+   * AllowedUpdatesFilter.only("message", "callback_query", "inline_query")
+   * ```
+   */
+  static only(...types) {
+    return new AllowedUpdatesFilter(types);
+  }
+  /**
+   * Return a new filter with the given types **added**.
+   * Already-present types are silently deduplicated.
+   *
+   * @example
+   * ```typescript
+   * AllowedUpdatesFilter.default.add("chat_member", "message_reaction")
+   * ```
+   */
+  add(...types) {
+    const set = new Set(this);
+    for (const t of types) set.add(t);
+    return new AllowedUpdatesFilter([...set]);
+  }
+  /**
+   * Return a new filter with the given types **removed**.
+   *
+   * @example
+   * ```typescript
+   * AllowedUpdatesFilter.all.except("poll", "poll_answer", "chosen_inline_result")
+   * ```
+   */
+  except(...types) {
+    const excluded = new Set(types);
+    return new AllowedUpdatesFilter(
+      Array.from(this).filter((t) => !excluded.has(t))
+    );
+  }
+  /** Convert to a plain `AllowedUpdateName[]` array. */
+  toArray() {
+    return Array.from(this);
+  }
+}
+function buildAllowedUpdates(bot) {
+  const registeredEvents = bot.updates.composer.registeredEvents();
+  const allowedSet = /* @__PURE__ */ new Set();
+  for (const event of registeredEvents) {
+    const mapped = mapEventToAllowedUpdates(event);
+    if (mapped) for (const name of mapped) allowedSet.add(name);
+  }
+  return new AllowedUpdatesFilter([...allowedSet]);
+}
+
 const methods = composer.defineComposerMethods({
   reaction(trigger, handler, macroOptions) {
     const reactions = Array.isArray(trigger) ? trigger : [trigger];
@@ -129,13 +259,32 @@ const methods = composer.defineComposerMethods({
       return macroHandler ? macroHandler(context, composer.noopNext) : handler(context);
     });
   },
-  command(command, handler, macroOptions) {
+  command(command, handlerOrMeta, handlerOrOptions, macroOptions) {
+    let handler;
+    let meta;
+    let resolvedMacroOptions;
+    if (typeof handlerOrMeta === "function") {
+      handler = handlerOrMeta;
+      resolvedMacroOptions = handlerOrOptions;
+    } else {
+      meta = handlerOrMeta;
+      handler = handlerOrOptions;
+      resolvedMacroOptions = macroOptions;
+    }
     const normalizedCommands = typeof command === "string" ? [command] : Array.from(command);
     for (const cmd of normalizedCommands) {
       if (cmd.startsWith("/"))
         throw new Error(`Do not use / in command name (${cmd})`);
     }
-    const macroHandler = macroOptions ? composer.buildFromOptions(this["~"].macros, macroOptions, handler) : null;
+    if (meta) {
+      if (!this["~"].commandsMeta) {
+        this["~"].commandsMeta = /* @__PURE__ */ new Map();
+      }
+      for (const cmd of normalizedCommands) {
+        this["~"].commandsMeta.set(cmd, meta);
+      }
+    }
+    const macroHandler = resolvedMacroOptions ? composer.buildFromOptions(this["~"].macros, resolvedMacroOptions, handler) : null;
     return this.on(["message", "business_message"], (context, next) => {
       const entity = context.entities?.find((entity2) => {
         if (entity2.type !== "bot_command" || entity2.offset > 0) return false;
@@ -182,6 +331,35 @@ const { Composer } = composer.createComposer({
   types: composer.eventTypes(),
   methods
 });
+if (typeof Composer.prototype.registeredEvents !== "function") {
+  Composer.prototype.registeredEvents = function() {
+    const events = /* @__PURE__ */ new Set();
+    for (const mw of this["~"].middlewares) {
+      if ((mw.type === "on" || mw.type === "derive") && mw.name) {
+        for (const part of mw.name.split("|")) {
+          const eventPart = part.includes(":") ? part.split(":")[0] : part;
+          if (eventPart) events.add(eventPart);
+        }
+      }
+    }
+    return events;
+  };
+}
+{
+  const originalExtend = Composer.prototype.extend;
+  Composer.prototype.extend = function(other) {
+    const result = originalExtend.call(this, other);
+    if (other["~"]?.commandsMeta) {
+      if (!this["~"].commandsMeta) {
+        this["~"].commandsMeta = /* @__PURE__ */ new Map();
+      }
+      for (const [cmd, meta] of other["~"].commandsMeta) {
+        this["~"].commandsMeta.set(cmd, meta);
+      }
+    }
+    return result;
+  };
+}
 
 class Plugin {
   /**
@@ -341,7 +519,7 @@ class Plugin {
    * import { Bot } from "gramio";
    *
    * const bot = new Bot(process.env.TOKEN!).onStart(
-   *     ({ plugins, info, updatesFrom }) => {
+   *     ({ plugins, info, updatesFrom, bot }) => {
    *         console.log(`plugin list - ${plugins.join(", ")}`);
    *         console.log(`bot username is @${info.username}`);
    * 		   console.log(`updates from ${updatesFrom}`);
@@ -365,7 +543,7 @@ class Plugin {
    * import { Bot } from "gramio";
    *
    * const bot = new Bot(process.env.TOKEN!).onStop(
-   *     ({ plugins, info, updatesFrom }) => {
+   *     ({ plugins, info, bot }) => {
    *         console.log(`plugin list - ${plugins.join(", ")}`);
    *         console.log(`bot username is @${info.username}`);
    *     }
@@ -794,7 +972,7 @@ class Bot {
    * import { Bot } from "gramio";
    *
    * const bot = new Bot(process.env.TOKEN!).onStart(
-   *     ({ plugins, info, updatesFrom }) => {
+   *     ({ plugins, info, updatesFrom, bot }) => {
    *         console.log(`plugin list - ${plugins.join(", ")}`);
    *         console.log(`bot username is @${info.username}`);
    * 		   console.log(`updates from ${updatesFrom}`);
@@ -818,7 +996,7 @@ class Bot {
    * import { Bot } from "gramio";
    *
    * const bot = new Bot(process.env.TOKEN!).onStop(
-   *     ({ plugins, info, updatesFrom }) => {
+   *     ({ plugins, info, bot }) => {
    *         console.log(`plugin list - ${plugins.join(", ")}`);
    *         console.log(`bot username is @${info.username}`);
    *     }
@@ -1085,18 +1263,8 @@ class Bot {
     this.updates.composer.hears(trigger, handler, options);
     return this;
   }
-  /**
-   * Register handler to `message` and `business_message` event when entities contains a command
-   *
-   * @example
-   * ```ts
-   * new Bot().command("start", async (context) => {
-   *     return context.send(`You message is /start ${context.args}`);
-   * });
-   * ```
-   */
-  command(command, handler, options) {
-    this.updates.composer.command(command, handler, options);
+  command(command, handlerOrMeta, handlerOrOptions, macroOptions) {
+    this.updates.composer.command(command, handlerOrMeta, handlerOrOptions, macroOptions);
     return this;
   }
   /**
@@ -1121,6 +1289,96 @@ class Bot {
   group(grouped) {
     return grouped(this);
   }
+  /**
+   * Sync registered command metadata with the Telegram API.
+   *
+   * Groups commands by `{scope, language_code}` and calls `setMyCommands` for each group.
+   * When a `storage` is provided, hashes each payload and skips unchanged groups.
+   *
+   * @example
+   * ```ts
+   * bot.onStart(() => bot.syncCommands());
+   * ```
+   */
+  async syncCommands(options) {
+    const commandsMeta = this.updates.composer["~"].commandsMeta ?? /* @__PURE__ */ new Map();
+    if (commandsMeta.size === 0) return;
+    const storage = options?.storage;
+    const botId = this.info?.id;
+    const excludeSet = options?.exclude ? new Set(options.exclude) : void 0;
+    const groups = /* @__PURE__ */ new Map();
+    const getOrCreateGroup = (scope, langCode) => {
+      const key = `${JSON.stringify(scope ?? { type: "default" })}:${langCode}`;
+      let group = groups.get(key);
+      if (!group) {
+        group = { scope, language_code: langCode || void 0, commands: [] };
+        groups.set(key, group);
+      }
+      return group;
+    };
+    for (const [name, meta] of commandsMeta) {
+      if (meta.hide) continue;
+      if (excludeSet?.has(name)) continue;
+      const scopes = meta.scopes ? meta.scopes.map(
+        (s) => typeof s === "string" ? { type: s } : s
+      ) : [void 0];
+      for (const scope of scopes) {
+        getOrCreateGroup(scope, "").commands.push({
+          command: name,
+          description: meta.description
+        });
+        if (meta.locales) {
+          for (const [lang, desc] of Object.entries(meta.locales)) {
+            getOrCreateGroup(scope, lang).commands.push({
+              command: name,
+              description: desc
+            });
+          }
+        }
+      }
+    }
+    for (const [key, group] of groups) {
+      if (group.commands.length > 100) {
+        throw new Error(
+          `Too many commands (${group.commands.length}) for scope ${key}. Telegram allows max 100 per scope+language.`
+        );
+      }
+    }
+    for (const [, group] of groups) {
+      const payload = {
+        commands: group.commands,
+        scope: group.scope,
+        language_code: group.language_code
+      };
+      if (storage) {
+        const hash = utils.simpleHash(JSON.stringify(payload));
+        const storageKey = `gramio:commands:${botId ?? "unknown"}:${JSON.stringify(group.scope ?? { type: "default" })}:${group.language_code ?? ""}`;
+        const stored = await storage.get(storageKey);
+        if (stored === hash) continue;
+        await this.api.setMyCommands(payload);
+        await storage.set(storageKey, hash);
+      } else {
+        await this.api.setMyCommands(payload);
+      }
+    }
+    if (options?.cleanUnusedScopes) {
+      const declaredScopes = /* @__PURE__ */ new Set();
+      for (const [, group] of groups) {
+        declaredScopes.add(JSON.stringify(group.scope ?? { type: "default" }));
+      }
+      const allScopes = [
+        { type: "default" },
+        { type: "all_private_chats" },
+        { type: "all_group_chats" },
+        { type: "all_chat_administrators" }
+      ];
+      for (const scope of allScopes) {
+        if (!declaredScopes.has(JSON.stringify(scope))) {
+          await this.api.deleteMyCommands({ scope });
+        }
+      }
+    }
+  }
   /**
    * Init bot. Call it manually only if you doesn't use {@link Bot.start}
    */
@@ -1159,10 +1417,21 @@ class Bot {
     webhook,
     longPolling,
     dropPendingUpdates,
-    allowedUpdates,
+    allowedUpdates: allowedUpdatesRaw,
     deleteWebhook: deleteWebhookRaw
   } = {}) {
     await this.init();
+    let allowedUpdates;
+    if (allowedUpdatesRaw === "strict") {
+      allowedUpdates = buildAllowedUpdates(this);
+    } else if (allowedUpdatesRaw === void 0) {
+      const optIn = detectOptInUpdates(
+        this.updates.composer.registeredEvents()
+      );
+      allowedUpdates = optIn.length > 0 ? AllowedUpdatesFilter.default.add(...optIn) : void 0;
+    } else {
+      allowedUpdates = allowedUpdatesRaw;
+    }
     const deleteWebhook = deleteWebhookRaw ?? "on-conflict-with-polling";
     if (!webhook) {
       if (deleteWebhook === true)
@@ -1185,7 +1454,8 @@ class Bot {
         plugins: this.dependencies,
         // biome-ignore lint/style/noNonNullAssertion: bot.init() guarantees this.info
         info: this.info,
-        updatesFrom: "long-polling"
+        updatesFrom: "long-polling",
+        bot: this
       });
       return this.info;
     }
@@ -1203,7 +1473,8 @@ class Bot {
       plugins: this.dependencies,
       // biome-ignore lint/style/noNonNullAssertion: bot.init() guarantees this.info
       info: this.info,
-      updatesFrom: "webhook"
+      updatesFrom: "webhook",
+      bot: this
     });
     return this.info;
   }
@@ -1220,7 +1491,8 @@ class Bot {
     await this.runImmutableHooks("onStop", {
       plugins: this.dependencies,
       // biome-ignore lint/style/noNonNullAssertion: bot.init() guarantees this.info
-      info: this.info
+      info: this.info,
+      bot: this
     });
   }
 }
@@ -1535,11 +1807,16 @@ Object.defineProperty(exports, "stop", {
 	enumerable: true,
 	get: function () { return composer.stop; }
 });
+exports.AllowedUpdatesFilter = AllowedUpdatesFilter;
 exports.Bot = Bot;
 exports.Composer = Composer;
+exports.OPT_IN_TYPES = OPT_IN_TYPES;
 exports.Plugin = Plugin;
 exports.Updates = Updates;
+exports.buildAllowedUpdates = buildAllowedUpdates;
+exports.detectOptInUpdates = detectOptInUpdates;
 exports.filters = filters;
+exports.mapEventToAllowedUpdates = mapEventToAllowedUpdates;
 exports.webhookHandler = webhookHandler;
 Object.keys(callbackData).forEach(function (k) {
 	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {