gramio 0.6.2 → 0.8.0

package/dist/index.d.cts

@@ -2,17 +2,147 @@ import * as _gramio_callback_data from '@gramio/callback-data';
 import { CallbackData } from '@gramio/callback-data';
 export * from '@gramio/callback-data';
 import * as _gramio_contexts from '@gramio/contexts';
-import { Context, ContextsMapping, BotLike, UpdateName, ContextType, Attachment, AttachmentsMapping, Dice, MessageOriginUser, MessageOriginChat, MessageOriginChannel, MessageOriginHiddenUser, Message, MessageEntity, TextQuote, User, LinkPreviewOptions, ExternalReplyInfo, Chat, Giveaway, PaidMediaInfo, Game, StoryAttachment, Venue, MessageContext } from '@gramio/contexts';
+import { UpdateName, MessageEventName, CustomEventName, Context, ContextsMapping, BotLike, ContextType, Attachment, AttachmentsMapping, Dice, MessageOriginUser, MessageOriginChat, MessageOriginChannel, MessageOriginHiddenUser, Message, MessageEntity, TextQuote, User, LinkPreviewOptions, ExternalReplyInfo, Chat, Giveaway, PaidMediaInfo, Game, StoryAttachment, Venue, MessageContext } from '@gramio/contexts';
 export * from '@gramio/contexts';
 export * from '@gramio/files';
 export * from '@gramio/format';
 export * from '@gramio/keyboards';
 import * as _gramio_types from '@gramio/types';
-import { APIMethods, TelegramResponseParameters, TelegramAPIResponseError, TelegramReactionTypeEmojiEmoji, TelegramUser, APIMethodParams, APIMethodReturn, SetWebhookParams, TelegramUpdate, TelegramMessageEntity } from '@gramio/types';
+import { APIMethods, TelegramResponseParameters, TelegramAPIResponseError, TelegramReactionTypeEmojiEmoji, TelegramUser, APIMethodParams, APIMethodReturn, SetWebhookParams, TelegramUpdate, TelegramBotCommandScope, TelegramMessageEntity } from '@gramio/types';
 export * from '@gramio/types';
 import * as _gramio_composer from '@gramio/composer';
-import { ComposerLike, MacroDefinitions, EventContextOf, EventComposer, MacroDef, Next, EventQueue, HandlerOptions, DeriveFromOptions } from '@gramio/composer';
-export { ContextCallback, DeriveFromOptions, EventComposer, EventQueue, HandlerOptions, MacroDef, MacroDefinitions, MacroDeriveType, MacroHooks, MacroOptionType, Middleware, Next, WithCtx, buildFromOptions, compose, noopNext, skip, stop } from '@gramio/composer';
+import { ComposerLike, MacroDefinitions, CommandMeta, EventContextOf, EventComposer, MacroDef, Next, EventQueue, HandlerOptions, DeriveFromOptions } from '@gramio/composer';
+export { CommandMeta, ContextCallback, DeriveFromOptions, EventComposer, EventQueue, HandlerOptions, MacroDef, MacroDefinitions, MacroDeriveType, MacroHooks, MacroOptionType, Middleware, Next, ScopeShorthand, WithCtx, buildFromOptions, compose, noopNext, skip, stop } from '@gramio/composer';
+
+/**
+ * Telegram Bot API top-level update type name.
+ * Valid values for `allowed_updates` in `getUpdates` / `setWebhook`.
+ */
+type AllowedUpdateName = Exclude<UpdateName, MessageEventName | CustomEventName>;
+/** The 3 types Telegram excludes by default (must be explicitly requested). */
+declare const OPT_IN_TYPES: readonly AllowedUpdateName[];
+/**
+ * Maps any event name to the `AllowedUpdateName` values needed in `allowed_updates`.
+ *
+ * - Top-level update names → themselves
+ * - Sub-message events (MessageEventName) → all 5 message-carrying parent types
+ * - Unknown names (filter names like "text") → `undefined` (skipped)
+ */
+declare function mapEventToAllowedUpdates(event: string): readonly AllowedUpdateName[] | undefined;
+/**
+ * Detect which of the 3 opt-in types have handlers registered.
+ * Used by `bot.start()` for default auto opt-in behavior.
+ */
+declare function detectOptInUpdates(registeredEvents: Set<string>): AllowedUpdateName[];
+/**
+ * Fluent, immutable builder for the Telegram Bot API `allowed_updates` list.
+ *
+ * Instances directly extend `Array<AllowedUpdateName>`, so they can be passed
+ * wherever `allowedUpdates` is expected without any conversion.
+ *
+ * @example
+ * ```typescript
+ * import { AllowedUpdatesFilter } from "gramio";
+ *
+ * // All updates (opt-in types included: chat_member, message_reaction, message_reaction_count)
+ * bot.start({ allowedUpdates: AllowedUpdatesFilter.all });
+ *
+ * // Telegram's default set (opt-in types excluded)
+ * bot.start({ allowedUpdates: AllowedUpdatesFilter.default });
+ *
+ * // Explicit list
+ * bot.start({ allowedUpdates: AllowedUpdatesFilter.only("message", "callback_query") });
+ *
+ * // All except poll events
+ * bot.start({ allowedUpdates: AllowedUpdatesFilter.all.except("poll", "poll_answer") });
+ *
+ * // Default + opt-in to chat_member
+ * bot.start({ allowedUpdates: AllowedUpdatesFilter.default.add("chat_member") });
+ * ```
+ */
+declare class AllowedUpdatesFilter extends Array<AllowedUpdateName> {
+    /** @internal use static factory methods instead */
+    constructor(updates: readonly AllowedUpdateName[]);
+    /**
+     * All update types, including the opt-in ones:
+     * `chat_member`, `message_reaction`, and `message_reaction_count`.
+     */
+    static get all(): AllowedUpdatesFilter;
+    /**
+     * 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(): AllowedUpdatesFilter;
+    /**
+     * Create a filter with **exactly** the specified update types.
+     *
+     * @example
+     * ```typescript
+     * AllowedUpdatesFilter.only("message", "callback_query", "inline_query")
+     * ```
+     */
+    static only(...types: AllowedUpdateName[]): AllowedUpdatesFilter;
+    /**
+     * 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: AllowedUpdateName[]): AllowedUpdatesFilter;
+    /**
+     * Return a new filter with the given types **removed**.
+     *
+     * @example
+     * ```typescript
+     * AllowedUpdatesFilter.all.except("poll", "poll_answer", "chosen_inline_result")
+     * ```
+     */
+    except(...types: AllowedUpdateName[]): AllowedUpdatesFilter;
+    /** Convert to a plain `AllowedUpdateName[]` array. */
+    toArray(): AllowedUpdateName[];
+}
+/**
+ * Build an {@link AllowedUpdatesFilter} automatically from a bot's registered
+ * `.on()` handlers (including handlers from extended plugins).
+ *
+ * Returns **only** the update types that handlers explicitly register for.
+ * Use this for strict filtering — Telegram will only send these update types.
+ *
+ * **Note:** filter-only `.on(filterFn, handler)` and `.use()` middleware
+ * do not declare specific events and are not included.
+ * Manually `.add()` additional types if needed.
+ *
+ * Call after all handlers/plugins are registered (or after `bot.init()`).
+ *
+ * @example
+ * ```typescript
+ * const bot = new Bot(token)
+ *     .command("start", handler)
+ *     .callbackQuery("data", handler);
+ *
+ * bot.start({ allowedUpdates: buildAllowedUpdates(bot) });
+ * // → allowed_updates: ["message", "business_message", "callback_query"]
+ *
+ * // With customization:
+ * bot.start({ allowedUpdates: buildAllowedUpdates(bot).add("poll") });
+ * ```
+ */
+declare function buildAllowedUpdates(bot: {
+    updates: {
+        composer: {
+            registeredEvents(): Set<string>;
+        };
+    };
+}): AllowedUpdatesFilter;
 
 /** Symbol to determine which error kind is it */
 declare const ErrorKind: symbol;
@@ -44,6 +174,7 @@ type Ctx<K extends keyof ContextsMapping<AnyBot>> = InstanceType<ContextsMapping
 type GramIOLike<T> = ComposerLike<T> & {
     "~": {
         macros: MacroDefinitions;
+        commandsMeta: Map<string, CommandMeta>;
         Derives?: Record<string, object>;
     };
     chosenInlineResult(trigger: any, handler: any, macroOptions?: any): T;
@@ -52,6 +183,7 @@ type GramIOLike<T> = ComposerLike<T> & {
 declare module "@gramio/composer" {
     interface EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives, TMethods, TMacros> {
         extend<P extends AnyPlugin>(plugin: P): EventComposer<TBase, TEventMap, TIn, TOut & P["_"]["Derives"]["global"], TExposed, TDerives & Omit<P["_"]["Derives"], "global">, TMethods, TMacros & P["_"]["Macros"]>;
+        registeredEvents(): Set<string>;
     }
 }
 declare const Composer: _gramio_composer.EventComposerConstructor<Context<AnyBot>, TelegramEventMap, {
@@ -72,9 +204,11 @@ declare const Composer: _gramio_composer.EventComposerConstructor<Context<AnyBot
     hears<TThis extends GramIOLike<TThis>>(this: TThis, trigger: RegExp | MaybeArray<string> | ((context: Ctx<"message">) => boolean), handler: (context: Ctx<"message"> & {
         args: RegExpMatchArray | null;
     } & EventContextOf<TThis, "message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
-    command<TThis extends GramIOLike<TThis>>(this: TThis, command: MaybeArray<string>, handler: (context: Ctx<"message"> & {
+    command<TThis extends GramIOLike<TThis>>(this: TThis, command: MaybeArray<string>, handlerOrMeta: ((context: Ctx<"message"> & {
         args: string | null;
-    } & EventContextOf<TThis, "message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
+    } & EventContextOf<TThis, "message">) => unknown) | CommandMeta, handlerOrOptions?: ((context: Ctx<"message"> & {
+        args: string | null;
+    } & EventContextOf<TThis, "message">) => unknown) | Record<string, unknown>, macroOptions?: Record<string, unknown>): TThis;
     startParameter<TThis extends GramIOLike<TThis>>(this: TThis, parameter: RegExp | MaybeArray<string>, handler: Handler<Ctx<"message"> & {
         rawStartPayload: string;
     } & EventContextOf<TThis, "message">>, macroOptions?: Record<string, unknown>): TThis;
@@ -214,6 +348,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             reaction<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -221,6 +356,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             callbackQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -230,6 +366,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             chosenInlineResult<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -239,6 +376,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             inlineQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -252,6 +390,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             hears<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -261,15 +400,19 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             command<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, command: MaybeArray<string>, handler: (context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+            }>(this: TThis, command: MaybeArray<string>, handlerOrMeta: ((context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
                 args: string | null;
-            } & _gramio_composer.EventContextOf<TThis, "message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
+            } & _gramio_composer.EventContextOf<TThis, "message">) => unknown) | _gramio_composer.CommandMeta, handlerOrOptions?: ((context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: string | null;
+            } & _gramio_composer.EventContextOf<TThis, "message">) => unknown) | Record<string, unknown>, macroOptions?: Record<string, unknown>): TThis;
             startParameter<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -280,6 +423,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             reaction<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -287,6 +431,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             callbackQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -296,6 +441,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             chosenInlineResult<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -305,6 +451,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             inlineQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -318,6 +465,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             hears<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -327,15 +475,19 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             command<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, command: MaybeArray<string>, handler: (context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+            }>(this: TThis, command: MaybeArray<string>, handlerOrMeta: ((context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
                 args: string | null;
-            } & _gramio_composer.EventContextOf<TThis, "message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
+            } & _gramio_composer.EventContextOf<TThis, "message">) => unknown) | _gramio_composer.CommandMeta, handlerOrOptions?: ((context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: string | null;
+            } & _gramio_composer.EventContextOf<TThis, "message">) => unknown) | Record<string, unknown>, macroOptions?: Record<string, unknown>): TThis;
             startParameter<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
+                    commandsMeta: Map<string, _gramio_composer.CommandMeta>;
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
@@ -494,7 +646,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
      * 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}`);
@@ -515,7 +667,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
      * 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}`);
      *     }
@@ -720,7 +872,7 @@ declare namespace Hooks {
      * 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}`);
@@ -736,6 +888,7 @@ declare namespace Hooks {
         plugins: string[];
         info: TelegramUser;
         updatesFrom: "webhook" | "long-polling";
+        bot: BotLike;
     }) => unknown;
     /**
      * Type for `onStop` hook
@@ -745,7 +898,7 @@ declare namespace Hooks {
      * 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}`);
      *     }
@@ -760,6 +913,7 @@ declare namespace Hooks {
     type OnStop = (context: {
         plugins: string[];
         info: TelegramUser;
+        bot: BotLike;
     }) => unknown;
     /**
      * Type for `onResponseError` hook
@@ -823,13 +977,53 @@ interface BotStartOptions {
     webhook?: BotStartOptionsWebhook;
     longPolling?: BotStartOptionsLongPolling;
     dropPendingUpdates?: boolean;
-    allowedUpdates?: AllowedUpdates;
+    /**
+     * Which update types to receive from Telegram.
+     *
+     * - **`undefined`** (default) — Telegram's default set, plus automatic opt-in
+     *   for `chat_member`, `message_reaction`, and `message_reaction_count` if
+     *   the bot has handlers registered for them.
+     * - **`"strict"`** — only receive update types that handlers explicitly
+     *   register for via `.on()`. Equivalent to `AllowedUpdatesFilter.from(bot)`.
+     *   Filter-only `.on()` and `.use()` are not included.
+     * - **`AllowedUpdatesFilter` / array** — explicit list of update types.
+     *
+     * @example
+     * ```typescript
+     * // Auto opt-in (default): Telegram default + auto chat_member/reaction if needed
+     * bot.start();
+     *
+     * // Strict: only registered events
+     * bot.start({ allowedUpdates: "strict" });
+     *
+     * // Manual
+     * bot.start({ allowedUpdates: AllowedUpdatesFilter.all });
+     *
+     * // Strict + customize
+     * bot.start({ allowedUpdates: AllowedUpdatesFilter.from(bot).add("poll") });
+     * ```
+     */
+    allowedUpdates?: AllowedUpdates | "strict";
     deleteWebhook?: boolean | "on-conflict-with-polling";
 }
 interface PollingStartOptions {
     dropPendingUpdates?: boolean;
     deleteWebhookOnConflict?: boolean;
 }
+/** Minimal key-value storage interface compatible with `@gramio/storage` */
+interface SyncStorage {
+    get(key: string): string | undefined | Promise<string | undefined>;
+    set(key: string, value: string): void | Promise<void>;
+}
+/** Options for {@link Bot.syncCommands} */
+interface SyncCommandsOptions {
+    /** Storage for caching sync hashes. When provided, only changed groups trigger API calls. */
+    storage?: SyncStorage;
+    /** Delete commands for scopes not declared by any command. @default false */
+    cleanUnusedScopes?: boolean;
+    /** Command names to exclude from syncing (in addition to commands with `hide: true`) */
+    exclude?: string[];
+}
 
 declare class Updates {
     private readonly bot;
@@ -1043,7 +1237,7 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      * 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}`);
@@ -1064,7 +1258,7 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      * 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}`);
      *     }
@@ -1280,10 +1474,22 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      *     return context.send(`You message is /start ${context.args}`);
      * });
      * ```
+     *
+     * @example
+     * ```ts
+     * // With metadata — description will be synced via syncCommands()
+     * new Bot().command("start", {
+     *     description: "Start the bot",
+     *     locales: { ru: "Запустить бота" },
+     * }, (context) => context.send("Hello!"));
+     * ```
      */
     command<TOptions extends HandlerOptions<ContextType<typeof this, "message">, Macros> = {}>(command: MaybeArray<string>, handler: (context: ContextType<typeof this, "message"> & {
         args: string | null;
-    } & DeriveFromOptions<Macros, TOptions>) => unknown, options?: TOptions): this;
+    } & DeriveFromOptions<Macros, TOptions>) => unknown, options?: TOptions): typeof this;
+    command<TOptions extends HandlerOptions<ContextType<typeof this, "message">, Macros> = {}>(command: MaybeArray<string>, meta: CommandMeta<TelegramBotCommandScope>, handler: (context: ContextType<typeof this, "message"> & {
+        args: string | null;
+    } & DeriveFromOptions<Macros, TOptions>) => unknown, options?: TOptions): typeof this;
     /**
      * Register handler to `start` command when start parameter is matched
      *
@@ -1301,6 +1507,18 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
     } & DeriveFromOptions<Macros, TOptions>>, options?: TOptions): this;
     /** Currently not isolated!!! */
     group(grouped: (bot: typeof this) => AnyBot): typeof 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());
+     * ```
+     */
+    syncCommands(options?: SyncCommandsOptions): Promise<void>;
     /**
      * Init bot. Call it manually only if you doesn't use {@link Bot.start}
      */
@@ -1319,7 +1537,7 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      * bot.start();
      * ```
      */
-    start({ webhook, longPolling, dropPendingUpdates, allowedUpdates, deleteWebhook: deleteWebhookRaw, }?: BotStartOptions): Promise<TelegramUser>;
+    start({ webhook, longPolling, dropPendingUpdates, allowedUpdates: allowedUpdatesRaw, deleteWebhook: deleteWebhookRaw, }?: BotStartOptions): Promise<TelegramUser>;
     /**
      * Stops receiving events via long-polling or webhook
      * */
@@ -1710,5 +1928,5 @@ declare function webhookHandler<Framework extends keyof typeof frameworks>(bot:
     response: () => any;
 } ? (...args: Parameters<(typeof frameworks)[Framework]>) => ReturnType<ReturnType<(typeof frameworks)[Framework]>["response"]> : (...args: Parameters<(typeof frameworks)[Framework]>) => void;
 
-export { Bot, Composer, ErrorKind, Hooks, Plugin, TelegramError, Updates, filters, webhookHandler };
-export type { AllowedUpdates, AnyBot, AnyPlugin, BotOptions, BotStartOptions, BotStartOptionsLongPolling, BotStartOptionsWebhook, CallbackQueryShorthandContext, DeriveDefinitions, ErrorDefinitions, Filter, Handler, MaybePromise, MaybeSuppressedParams, MaybeSuppressedReturn, PollingStartOptions, Suppress, SuppressedAPIMethodParams, SuppressedAPIMethodReturn, SuppressedAPIMethods, WebhookHandlerOptions, WebhookHandlerOptionsShouldWait, WebhookHandlers };
+export { AllowedUpdatesFilter, Bot, Composer, ErrorKind, Hooks, OPT_IN_TYPES, Plugin, TelegramError, Updates, buildAllowedUpdates, detectOptInUpdates, filters, mapEventToAllowedUpdates, webhookHandler };
+export type { AllowedUpdateName, AllowedUpdates, AnyBot, AnyPlugin, BotOptions, BotStartOptions, BotStartOptionsLongPolling, BotStartOptionsWebhook, CallbackQueryShorthandContext, DeriveDefinitions, ErrorDefinitions, Filter, Handler, MaybePromise, MaybeSuppressedParams, MaybeSuppressedReturn, PollingStartOptions, Suppress, SuppressedAPIMethodParams, SuppressedAPIMethodReturn, SuppressedAPIMethods, SyncCommandsOptions, SyncStorage, WebhookHandlerOptions, WebhookHandlerOptionsShouldWait, WebhookHandlers };