npm - gramio - Versions diffs - 0.9.0 → 0.11.0 - Mend

gramio 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/dist/index.cjs CHANGED Viewed

@@ -5,8 +5,6 @@ var contexts = require('@gramio/contexts');
 var files = require('@gramio/files');
 var format = require('@gramio/format');
 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-BKLnNOBm.cjs');
 var composer = require('@gramio/composer');
@@ -35,7 +33,8 @@ const ALL_NAMES = [
   "chat_join_request",
   "chat_boost",
   "removed_chat_boost",
-  "managed_bot"
+  "managed_bot",
+  "guest_message"
 ];
 const MESSAGE_PARENT_TYPES = [
   "message",
@@ -198,13 +197,23 @@ const methods = composer.defineComposerMethods({
         return macroHandler ? macroHandler(context, composer.noopNext) : handler(context);
       });
     }
+    if (typeof trigger === "function") {
+      return this.on("chosen_inline_result", (context, next) => {
+        if (!trigger(context)) return next();
+        context.args = null;
+        return macroHandler ? macroHandler(context, composer.noopNext) : handler(context);
+      });
+    }
     return this.on("chosen_inline_result", (context, next) => {
-      if (!trigger(context)) return next();
+      if (!context.resultId || !trigger.filter(context.resultId)) return next();
       context.args = null;
+      context.queryData = trigger.unpack(context.resultId);
       return macroHandler ? macroHandler(context, composer.noopNext) : handler(context);
     });
   },
-  inlineQuery(trigger, handler, options = {}) {
+  inlineQuery(triggerOrHandler, maybeHandler, options = {}) {
+    const trigger = maybeHandler === void 0 ? (() => true) : triggerOrHandler;
+    const handler = maybeHandler ?? triggerOrHandler;
     if (options.onResult) this.chosenInlineResult(trigger, options.onResult);
     const { onResult: _, ...macroOptions } = options;
     const hasMacros = Object.keys(macroOptions).length > 0;
@@ -229,6 +238,32 @@ const methods = composer.defineComposerMethods({
       return macroHandler ? macroHandler(context, composer.noopNext) : handler(context);
     });
   },
+  guestQuery(triggerOrHandler, maybeHandler, macroOptions) {
+    const trigger = maybeHandler === void 0 ? (() => true) : triggerOrHandler;
+    const handler = maybeHandler ?? triggerOrHandler;
+    const macroHandler = macroOptions ? composer.buildFromOptions(this["~"].macros, macroOptions, handler) : null;
+    if (typeof trigger === "string") {
+      return this.on("guest_message", (context, next) => {
+        const text = context.text ?? context.caption;
+        if (text !== trigger) return next();
+        context.args = null;
+        return macroHandler ? macroHandler(context, composer.noopNext) : handler(context);
+      });
+    }
+    if (trigger instanceof RegExp) {
+      return this.on("guest_message", (context, next) => {
+        const text = context.text ?? context.caption;
+        if (!text || !trigger.test(text)) return next();
+        context.args = text.match(trigger);
+        return macroHandler ? macroHandler(context, composer.noopNext) : handler(context);
+      });
+    }
+    return this.on("guest_message", (context, next) => {
+      if (!trigger(context)) return next();
+      context.args = null;
+      return macroHandler ? macroHandler(context, composer.noopNext) : handler(context);
+    });
+  },
   hears(trigger, handler, macroOptions) {
     const macroHandler = macroOptions ? composer.buildFromOptions(this["~"].macros, macroOptions, handler) : null;
     if (typeof trigger === "string") {
@@ -690,6 +725,7 @@ class Updates {
           })
         );
         this.isRequestActive = false;
+        if (!this.isStarted) break;
         const updateId = updates.at(-1)?.update_id;
         this.offset = updateId ? updateId + 1 : this.offset;
         this.queue.addBatch(updates);
@@ -909,28 +945,26 @@ class Bot {
     }
     return fn();
   }
-  async downloadFile(attachment, path) {
-    function getFileId(attachment2) {
-      if (attachment2 instanceof contexts.PhotoAttachment) {
-        return attachment2.bigSize.fileId;
-      }
-      if ("fileId" in attachment2 && typeof attachment2.fileId === "string")
-        return attachment2.fileId;
-      if ("file_id" in attachment2) return attachment2.file_id;
-      throw new Error("Invalid attachment");
-    }
-    const fileId = typeof attachment === "string" ? attachment : getFileId(attachment);
-    const file = await this.api.getFile({ file_id: fileId });
-    const url = `${this.options.api.baseURL.replace("/bot", "/file/bot")}${this.options.token}/${file.file_path}`;
-    const res = await fetch(url);
-    if (path) {
-      if (!res.body)
-        throw new Error("Response without body (should be never throw)");
-      await fs.writeFile(path, node_stream.Readable.fromWeb(res.body));
-      return path;
-    }
-    const buffer = await res.arrayBuffer();
-    return buffer;
+  downloadFile(attachment, path) {
+    const input = attachment;
+    return path ? files.downloadFile(this, input, path) : files.downloadFile(this, input);
+  }
+  /**
+   * Get a shareable download link for a file.
+   *
+   * When {@link BotOptions.files | `files.baseURL`} is set (e.g. a local Bot API
+   * server with the bundled file server), the link is **token-less and path-based**
+   * — safe to hand to users. Otherwise it falls back to the classic
+   * `…/file/bot<token>/<path>` URL (which contains the bot token).
+   *
+   * @example
+   * ```ts
+   * const link = await bot.getFileLink(ctx.document.fileId);
+   * await ctx.reply(`Download: ${link}`);
+   * ```
+   */
+  getFileLink(attachment) {
+    return files.downloadFile(this, attachment).link();
   }
   /**
    * Register custom class-error for type-safe catch in `onError` hook
@@ -1274,7 +1308,32 @@ class Bot {
     );
     return this;
   }
-  /** Register handler to `chosen_inline_result` update */
+  /**
+   * Register handler to `chosen_inline_result` update
+   *
+   * Accepts a `CallbackData` schema for type-safe filtering on `result_id`:
+   *
+   * @example
+   * ```ts
+   * const trackRef = new CallbackData("track").string("src").string("id");
+   *
+   * new Bot()
+   *     .on("inline_query", async (ctx) => {
+   *         await ctx.answer(tracks.map((t) => ({
+   *             type: "audio",
+   *             id: trackRef.pack({ src: t.source, id: t.id }),
+   *             audio_url: t.url,
+   *             title: t.title,
+   *         })));
+   *     })
+   *     .chosenInlineResult(trackRef, (ctx) => {
+   *         ctx.queryData; // { src: string; id: string }
+   *     });
+   * ```
+   *
+   * String/RegExp/predicate triggers filter on `context.query` (the user's
+   * typed text); the `CallbackData` schema filters on `context.resultId`.
+   */
   chosenInlineResult(trigger, handler, options) {
     this.updates.composer.chosenInlineResult(
       trigger,
@@ -1283,49 +1342,18 @@ class Bot {
     );
     return this;
   }
-  /**
-   * Register handler to `inline_query` update
-   *
-   * @example
-   * ```ts
-   * new Bot().inlineQuery(
-   *     /regular expression with (.*)/i,
-   *     async (context) => {
-   *         if (context.args) {
-   *             await context.answer(
-   *                 [
-   *                     InlineQueryResult.article(
-   *                         "id-1",
-   *                         context.args[1],
-   *                         InputMessageContent.text("some"),
-   *                         {
-   *                             reply_markup: new InlineKeyboard().text(
-   *                                 "some",
-   *                                 "callback-data"
-   *                             ),
-   *                         }
-   *                     ),
-   *                 ],
-   *                 {
-   *                     cache_time: 0,
-   *                 }
-   *             );
-   *         }
-   *     },
-   *     {
-   *         onResult: (context) => context.editText("Message edited!"),
-   *     }
-   * );
-   * ```
-   * */
-  inlineQuery(trigger, handler, options) {
+  inlineQuery(triggerOrHandler, handler, options) {
     this.updates.composer.inlineQuery(
-      trigger,
+      triggerOrHandler,
       handler,
       options
     );
     return this;
   }
+  guestQuery(triggerOrHandler, handler, options) {
+    this.updates.composer.guestQuery(triggerOrHandler, handler, options);
+    return this;
+  }
   /**
    * Register handler to `message` and `business_message` event
    *

package/dist/index.d.cts CHANGED Viewed

@@ -4,6 +4,7 @@ export * from '@gramio/callback-data';
 import * as _gramio_contexts 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';
+import { FileSource, TelegramFileDownload } from '@gramio/files';
 export * from '@gramio/files';
 export * from '@gramio/format';
 export * from '@gramio/keyboards';
@@ -12,7 +13,7 @@ import { APIMethods, TelegramResponseParameters, TelegramAPIResponseError, Teleg
 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';
+export { ContextCallback, DeriveFromOptions, DeriveHandler, EventComposer, EventQueue, HandlerOptions, MacroDef, MacroDefinitions, MacroDeriveType, MacroHooks, MacroOptionType, Middleware, Next, WithCtx, WithDecorate, WithDerives, WithEventDerive, WithExtend, buildFromOptions, compose, noopNext, skip, stop } from '@gramio/composer';
 /**
  * Telegram Bot API top-level update type name.
@@ -184,16 +185,24 @@ declare const methods: {
     callbackQuery<TThis extends GramIOLike<TThis>, Trigger extends CallbackData | string | RegExp>(this: TThis, trigger: Trigger, handler: (context: Ctx<"callback_query"> & {
         queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : Trigger extends RegExp ? RegExpMatchArray : never;
     } & EventContextOf<TThis, "callback_query">) => unknown, macroOptions?: Record<string, unknown>): TThis;
-    chosenInlineResult<TThis extends GramIOLike<TThis>>(this: TThis, trigger: RegExp | string | ((context: Ctx<"chosen_inline_result">) => boolean), handler: (context: Ctx<"chosen_inline_result"> & {
+    chosenInlineResult<TThis extends GramIOLike<TThis>, Trigger extends CallbackData | RegExp | string | ((context: Ctx<"chosen_inline_result">) => boolean)>(this: TThis, trigger: Trigger, handler: (context: Ctx<"chosen_inline_result"> & {
         args: RegExpMatchArray | null;
+        queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : never;
     } & EventContextOf<TThis, "chosen_inline_result">) => unknown, macroOptions?: Record<string, unknown>): TThis;
-    inlineQuery<TThis extends GramIOLike<TThis>>(this: TThis, trigger: RegExp | string | ((context: Ctx<"inline_query">) => boolean), handler: (context: Ctx<"inline_query"> & {
+    inlineQuery<TThis extends GramIOLike<TThis>>(this: TThis, triggerOrHandler: RegExp | string | ((context: Ctx<"inline_query">) => boolean) | ((context: Ctx<"inline_query"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "inline_query">) => unknown), maybeHandler?: (context: Ctx<"inline_query"> & {
         args: RegExpMatchArray | null;
     } & EventContextOf<TThis, "inline_query">) => unknown, options?: {
         onResult?: (context: Ctx<"chosen_inline_result"> & {
             args: RegExpMatchArray | null;
         } & EventContextOf<TThis, "chosen_inline_result">) => unknown;
     } & Record<string, unknown>): TThis;
+    guestQuery<TThis extends GramIOLike<TThis>>(this: TThis, triggerOrHandler: RegExp | string | ((context: Ctx<"guest_message">) => boolean) | ((context: Ctx<"guest_message"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "guest_message">) => unknown), maybeHandler?: (context: Ctx<"guest_message"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "guest_message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
     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;
@@ -216,6 +225,7 @@ declare module "@gramio/composer" {
         hears: (typeof methods)["hears"];
         reaction: (typeof methods)["reaction"];
         inlineQuery: (typeof methods)["inlineQuery"];
+        guestQuery: (typeof methods)["guestQuery"];
         chosenInlineResult: (typeof methods)["chosenInlineResult"];
         startParameter: (typeof methods)["startParameter"];
     }
@@ -225,16 +235,24 @@ declare const Composer: _gramio_composer.EventComposerConstructor<Context<AnyBot
     callbackQuery<TThis extends GramIOLike<TThis>, Trigger extends CallbackData | string | RegExp>(this: TThis, trigger: Trigger, handler: (context: Ctx<"callback_query"> & {
         queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : Trigger extends RegExp ? RegExpMatchArray : never;
     } & EventContextOf<TThis, "callback_query">) => unknown, macroOptions?: Record<string, unknown>): TThis;
-    chosenInlineResult<TThis extends GramIOLike<TThis>>(this: TThis, trigger: RegExp | string | ((context: Ctx<"chosen_inline_result">) => boolean), handler: (context: Ctx<"chosen_inline_result"> & {
+    chosenInlineResult<TThis extends GramIOLike<TThis>, Trigger extends CallbackData | RegExp | string | ((context: Ctx<"chosen_inline_result">) => boolean)>(this: TThis, trigger: Trigger, handler: (context: Ctx<"chosen_inline_result"> & {
         args: RegExpMatchArray | null;
+        queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : never;
     } & EventContextOf<TThis, "chosen_inline_result">) => unknown, macroOptions?: Record<string, unknown>): TThis;
-    inlineQuery<TThis extends GramIOLike<TThis>>(this: TThis, trigger: RegExp | string | ((context: Ctx<"inline_query">) => boolean), handler: (context: Ctx<"inline_query"> & {
+    inlineQuery<TThis extends GramIOLike<TThis>>(this: TThis, triggerOrHandler: RegExp | string | ((context: Ctx<"inline_query">) => boolean) | ((context: Ctx<"inline_query"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "inline_query">) => unknown), maybeHandler?: (context: Ctx<"inline_query"> & {
         args: RegExpMatchArray | null;
     } & EventContextOf<TThis, "inline_query">) => unknown, options?: {
         onResult?: (context: Ctx<"chosen_inline_result"> & {
             args: RegExpMatchArray | null;
         } & EventContextOf<TThis, "chosen_inline_result">) => unknown;
     } & Record<string, unknown>): TThis;
+    guestQuery<TThis extends GramIOLike<TThis>>(this: TThis, triggerOrHandler: RegExp | string | ((context: Ctx<"guest_message">) => boolean) | ((context: Ctx<"guest_message"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "guest_message">) => unknown), maybeHandler?: (context: Ctx<"guest_message"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "guest_message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
     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;
@@ -325,6 +343,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             edited_channel_post: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">;
             business_message: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">;
             edited_business_message: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">;
+            guest_message: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">;
             deleted_business_messages: _gramio_contexts.BusinessMessagesDeletedContext<AnyBot>;
             business_connection: _gramio_contexts.BusinessConnectionContext<AnyBot>;
             migrate_from_chat_id: _gramio_contexts.MigrateFromChatIdContext<AnyBot>;
@@ -408,8 +427,9 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, trigger: RegExp | string | ((context: _gramio_contexts.ChosenInlineResultContext<AnyBot>) => boolean), handler: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
+            }, Trigger extends _gramio_callback_data.CallbackData | RegExp | string | ((context: _gramio_contexts.ChosenInlineResultContext<AnyBot>) => boolean)>(this: TThis, trigger: Trigger, handler: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
                 args: RegExpMatchArray | null;
+                queryData: Trigger extends _gramio_callback_data.CallbackData ? ReturnType<Trigger["unpack"]> : never;
             } & _gramio_composer.EventContextOf<TThis, "chosen_inline_result">) => unknown, macroOptions?: Record<string, unknown>): TThis;
             inlineQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
@@ -418,13 +438,27 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, trigger: RegExp | string | ((context: _gramio_contexts.InlineQueryContext<AnyBot>) => boolean), handler: (context: _gramio_contexts.InlineQueryContext<AnyBot> & {
+            }>(this: TThis, triggerOrHandler: RegExp | string | ((context: _gramio_contexts.InlineQueryContext<AnyBot>) => boolean) | ((context: _gramio_contexts.InlineQueryContext<AnyBot> & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "inline_query">) => unknown), maybeHandler?: (context: _gramio_contexts.InlineQueryContext<AnyBot> & {
                 args: RegExpMatchArray | null;
             } & _gramio_composer.EventContextOf<TThis, "inline_query">) => unknown, options?: {
                 onResult?: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
                     args: RegExpMatchArray | null;
                 } & _gramio_composer.EventContextOf<TThis, "chosen_inline_result">) => unknown;
             } & Record<string, unknown>): TThis;
+            guestQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
+                "~": {
+                    macros: MacroDefinitions;
+                    commandsMeta?: Map<string, unknown>;
+                    Derives?: Record<string, object>;
+                };
+                chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
+            }>(this: TThis, triggerOrHandler: RegExp | string | ((context: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) => boolean) | ((context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "guest_message">) => unknown), maybeHandler?: (context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "guest_message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
             hears<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
@@ -483,8 +517,9 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, trigger: RegExp | string | ((context: _gramio_contexts.ChosenInlineResultContext<AnyBot>) => boolean), handler: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
+            }, Trigger extends _gramio_callback_data.CallbackData | RegExp | string | ((context: _gramio_contexts.ChosenInlineResultContext<AnyBot>) => boolean)>(this: TThis, trigger: Trigger, handler: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
                 args: RegExpMatchArray | null;
+                queryData: Trigger extends _gramio_callback_data.CallbackData ? ReturnType<Trigger["unpack"]> : never;
             } & _gramio_composer.EventContextOf<TThis, "chosen_inline_result">) => unknown, macroOptions?: Record<string, unknown>): TThis;
             inlineQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
@@ -493,13 +528,27 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, trigger: RegExp | string | ((context: _gramio_contexts.InlineQueryContext<AnyBot>) => boolean), handler: (context: _gramio_contexts.InlineQueryContext<AnyBot> & {
+            }>(this: TThis, triggerOrHandler: RegExp | string | ((context: _gramio_contexts.InlineQueryContext<AnyBot>) => boolean) | ((context: _gramio_contexts.InlineQueryContext<AnyBot> & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "inline_query">) => unknown), maybeHandler?: (context: _gramio_contexts.InlineQueryContext<AnyBot> & {
                 args: RegExpMatchArray | null;
             } & _gramio_composer.EventContextOf<TThis, "inline_query">) => unknown, options?: {
                 onResult?: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
                     args: RegExpMatchArray | null;
                 } & _gramio_composer.EventContextOf<TThis, "chosen_inline_result">) => unknown;
             } & Record<string, unknown>): TThis;
+            guestQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
+                "~": {
+                    macros: MacroDefinitions;
+                    commandsMeta?: Map<string, unknown>;
+                    Derives?: Record<string, object>;
+                };
+                chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
+            }>(this: TThis, triggerOrHandler: RegExp | string | ((context: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) => boolean) | ((context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "guest_message">) => unknown), maybeHandler?: (context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "guest_message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
             hears<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
@@ -750,6 +799,8 @@ interface Plugin<Errors, Derives, Macros> {
     reaction: (typeof methods)["reaction"];
     /** Register inline query handler */
     inlineQuery: (typeof methods)["inlineQuery"];
+    /** Register guest query (`guest_message`) handler */
+    guestQuery: (typeof methods)["guestQuery"];
     /** Register chosen inline result handler */
     chosenInlineResult: (typeof methods)["chosenInlineResult"];
     /** Register deep-link parameter handler */
@@ -794,6 +845,30 @@ interface BotOptions {
          */
         retryGetUpdatesWait?: number;
     };
+    /**
+     * File download/serving options — mainly for a **local Bot API server**.
+     *
+     * @example
+     * ```ts
+     * const bot = new Bot(token, {
+     *     api: { baseURL: "http://telegram-bot-api:8081/bot" },
+     *     files: {
+     *         // bot.getFileLink() and ctx.download() resolve to this (token-less) URL
+     *         baseURL: "http://telegram-bot-api:8080",
+     *     },
+     * });
+     * ```
+     */
+    files?: {
+        /** How to fetch file bytes. @default "auto" */
+        source?: FileSource;
+        /** Working directory of the local Bot API server — the prefix of the absolute `file_path` it returns. @default "/var/lib/telegram-bot-api" */
+        localDir?: string;
+        /** Where that working dir is mounted on the bot's side (for `source: "disk"` when bot & server share a volume at a different path). Defaults to `localDir`. */
+        mountDir?: string;
+        /** Public base URL where the working dir is served (e.g. the bundled file server / nginx). Enables token-less {@link Bot.getFileLink} and `source: "rewrite"`. */
+        baseURL?: string;
+    };
 }
 /**
  * Handler is a function with context and next function arguments
@@ -1202,10 +1277,27 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      */
     downloadFile(attachment: Attachment | {
         file_id: string;
-    } | string): Promise<ArrayBuffer>;
+    } | string): TelegramFileDownload;
     downloadFile(attachment: Attachment | {
         file_id: string;
     } | string, path: string): Promise<string>;
+    /**
+     * Get a shareable download link for a file.
+     *
+     * When {@link BotOptions.files | `files.baseURL`} is set (e.g. a local Bot API
+     * server with the bundled file server), the link is **token-less and path-based**
+     * — safe to hand to users. Otherwise it falls back to the classic
+     * `…/file/bot<token>/<path>` URL (which contains the bot token).
+     *
+     * @example
+     * ```ts
+     * const link = await bot.getFileLink(ctx.document.fileId);
+     * await ctx.reply(`Download: ${link}`);
+     * ```
+     */
+    getFileLink(attachment: Attachment | {
+        file_id: string;
+    } | string): Promise<string>;
     /**
      * Register custom class-error for type-safe catch in `onError` hook
      *
@@ -1478,9 +1570,35 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      * ```
      */
     callbackQuery<Trigger extends CallbackData | string | RegExp, TOptions extends HandlerOptions<CallbackQueryShorthandContext<typeof this, Trigger>, Macros> = {}>(trigger: Trigger, handler: (context: CallbackQueryShorthandContext<typeof this, Trigger> & DeriveFromOptions<Macros, TOptions>) => unknown, options?: TOptions): this;
-    /** Register handler to `chosen_inline_result` update */
-    chosenInlineResult<Ctx = ContextType<typeof this, "chosen_inline_result">, TOptions extends HandlerOptions<Ctx, Macros> = {}>(trigger: RegExp | string | ((context: Ctx) => boolean), handler: (context: Ctx & {
+    /**
+     * Register handler to `chosen_inline_result` update
+     *
+     * Accepts a `CallbackData` schema for type-safe filtering on `result_id`:
+     *
+     * @example
+     * ```ts
+     * const trackRef = new CallbackData("track").string("src").string("id");
+     *
+     * new Bot()
+     *     .on("inline_query", async (ctx) => {
+     *         await ctx.answer(tracks.map((t) => ({
+     *             type: "audio",
+     *             id: trackRef.pack({ src: t.source, id: t.id }),
+     *             audio_url: t.url,
+     *             title: t.title,
+     *         })));
+     *     })
+     *     .chosenInlineResult(trackRef, (ctx) => {
+     *         ctx.queryData; // { src: string; id: string }
+     *     });
+     * ```
+     *
+     * String/RegExp/predicate triggers filter on `context.query` (the user's
+     * typed text); the `CallbackData` schema filters on `context.resultId`.
+     */
+    chosenInlineResult<Trigger extends CallbackData | RegExp | string | ((context: ContextType<typeof this, "chosen_inline_result">) => boolean), Ctx = ContextType<typeof this, "chosen_inline_result">, TOptions extends HandlerOptions<Ctx, Macros> = {}>(trigger: Trigger, handler: (context: Ctx & {
         args: RegExpMatchArray | null;
+        queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : never;
     } & DeriveFromOptions<Macros, TOptions>) => unknown, options?: TOptions): this;
     /**
      * Register handler to `inline_query` update
@@ -1517,6 +1635,9 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      * );
      * ```
      * */
+    inlineQuery<Ctx = ContextType<typeof this, "inline_query">>(handler: (context: Ctx & {
+        args: RegExpMatchArray | null;
+    }) => unknown): this;
     inlineQuery<Ctx = ContextType<typeof this, "inline_query">>(trigger: RegExp | string | ((context: Ctx) => boolean), handler: (context: Ctx & {
         args: RegExpMatchArray | null;
     }) => unknown, options?: HandlerOptions<Ctx, Macros> & {
@@ -1524,6 +1645,34 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
             args: RegExpMatchArray | null;
         }) => unknown;
     }): this;
+    /**
+     * Register handler to `guest_message` update — a message sent to the bot
+     * from a chat where the bot is not a member, via a guest query.
+     *
+     * Reply with {@link MessageContext.answerGuestQuery `context.answerGuestQuery()`}
+     * (NOT `context.send`/`context.reply`, which target a chat the bot can't post to).
+     *
+     * @example
+     * ```ts
+     * new Bot().guestQuery(/^find (.*)/i, async (context) => {
+     *     await context.answerGuestQuery({
+     *         type: "text",
+     *         text: `Looking up ${context.args?.[1]}…`,
+     *     });
+     * });
+     *
+     * // No-trigger form — match any guest message:
+     * new Bot().guestQuery(async (context) => {
+     *     await context.answerGuestQuery({ type: "text", text: "Hi!" });
+     * });
+     * ```
+     * */
+    guestQuery<Ctx = ContextType<typeof this, "guest_message">>(handler: (context: Ctx & {
+        args: RegExpMatchArray | null;
+    }) => unknown): this;
+    guestQuery<Ctx = ContextType<typeof this, "guest_message">>(trigger: RegExp | string | ((context: Ctx) => boolean), handler: (context: Ctx & {
+        args: RegExpMatchArray | null;
+    }) => unknown, options?: HandlerOptions<Ctx, Macros>): this;
     /**
      * Register handler to `message` and `business_message` event
      *
@@ -1996,7 +2145,7 @@ interface WebhookHandlerOptions {
  * });
  * ```
  */
-declare function webhookHandler<Framework extends keyof typeof frameworks>(bot: Bot, framework: Framework, secretTokenOrOptions?: string | WebhookHandlerOptions): ReturnType<(typeof frameworks)[Framework]> extends {
+declare function webhookHandler<Framework extends keyof typeof frameworks>(bot: AnyBot, framework: Framework, secretTokenOrOptions?: string | WebhookHandlerOptions): ReturnType<(typeof frameworks)[Framework]> extends {
     response: () => any;
 } ? (...args: Parameters<(typeof frameworks)[Framework]>) => ReturnType<ReturnType<(typeof frameworks)[Framework]>["response"]> : (...args: Parameters<(typeof frameworks)[Framework]>) => void;

package/dist/index.d.ts CHANGED Viewed

@@ -4,6 +4,7 @@ export * from '@gramio/callback-data';
 import * as _gramio_contexts 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';
+import { FileSource, TelegramFileDownload } from '@gramio/files';
 export * from '@gramio/files';
 export * from '@gramio/format';
 export * from '@gramio/keyboards';
@@ -12,7 +13,7 @@ import { APIMethods, TelegramResponseParameters, TelegramAPIResponseError, Teleg
 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';
+export { ContextCallback, DeriveFromOptions, DeriveHandler, EventComposer, EventQueue, HandlerOptions, MacroDef, MacroDefinitions, MacroDeriveType, MacroHooks, MacroOptionType, Middleware, Next, WithCtx, WithDecorate, WithDerives, WithEventDerive, WithExtend, buildFromOptions, compose, noopNext, skip, stop } from '@gramio/composer';
 /**
  * Telegram Bot API top-level update type name.
@@ -184,16 +185,24 @@ declare const methods: {
     callbackQuery<TThis extends GramIOLike<TThis>, Trigger extends CallbackData | string | RegExp>(this: TThis, trigger: Trigger, handler: (context: Ctx<"callback_query"> & {
         queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : Trigger extends RegExp ? RegExpMatchArray : never;
     } & EventContextOf<TThis, "callback_query">) => unknown, macroOptions?: Record<string, unknown>): TThis;
-    chosenInlineResult<TThis extends GramIOLike<TThis>>(this: TThis, trigger: RegExp | string | ((context: Ctx<"chosen_inline_result">) => boolean), handler: (context: Ctx<"chosen_inline_result"> & {
+    chosenInlineResult<TThis extends GramIOLike<TThis>, Trigger extends CallbackData | RegExp | string | ((context: Ctx<"chosen_inline_result">) => boolean)>(this: TThis, trigger: Trigger, handler: (context: Ctx<"chosen_inline_result"> & {
         args: RegExpMatchArray | null;
+        queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : never;
     } & EventContextOf<TThis, "chosen_inline_result">) => unknown, macroOptions?: Record<string, unknown>): TThis;
-    inlineQuery<TThis extends GramIOLike<TThis>>(this: TThis, trigger: RegExp | string | ((context: Ctx<"inline_query">) => boolean), handler: (context: Ctx<"inline_query"> & {
+    inlineQuery<TThis extends GramIOLike<TThis>>(this: TThis, triggerOrHandler: RegExp | string | ((context: Ctx<"inline_query">) => boolean) | ((context: Ctx<"inline_query"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "inline_query">) => unknown), maybeHandler?: (context: Ctx<"inline_query"> & {
         args: RegExpMatchArray | null;
     } & EventContextOf<TThis, "inline_query">) => unknown, options?: {
         onResult?: (context: Ctx<"chosen_inline_result"> & {
             args: RegExpMatchArray | null;
         } & EventContextOf<TThis, "chosen_inline_result">) => unknown;
     } & Record<string, unknown>): TThis;
+    guestQuery<TThis extends GramIOLike<TThis>>(this: TThis, triggerOrHandler: RegExp | string | ((context: Ctx<"guest_message">) => boolean) | ((context: Ctx<"guest_message"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "guest_message">) => unknown), maybeHandler?: (context: Ctx<"guest_message"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "guest_message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
     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;
@@ -216,6 +225,7 @@ declare module "@gramio/composer" {
         hears: (typeof methods)["hears"];
         reaction: (typeof methods)["reaction"];
         inlineQuery: (typeof methods)["inlineQuery"];
+        guestQuery: (typeof methods)["guestQuery"];
         chosenInlineResult: (typeof methods)["chosenInlineResult"];
         startParameter: (typeof methods)["startParameter"];
     }
@@ -225,16 +235,24 @@ declare const Composer: _gramio_composer.EventComposerConstructor<Context<AnyBot
     callbackQuery<TThis extends GramIOLike<TThis>, Trigger extends CallbackData | string | RegExp>(this: TThis, trigger: Trigger, handler: (context: Ctx<"callback_query"> & {
         queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : Trigger extends RegExp ? RegExpMatchArray : never;
     } & EventContextOf<TThis, "callback_query">) => unknown, macroOptions?: Record<string, unknown>): TThis;
-    chosenInlineResult<TThis extends GramIOLike<TThis>>(this: TThis, trigger: RegExp | string | ((context: Ctx<"chosen_inline_result">) => boolean), handler: (context: Ctx<"chosen_inline_result"> & {
+    chosenInlineResult<TThis extends GramIOLike<TThis>, Trigger extends CallbackData | RegExp | string | ((context: Ctx<"chosen_inline_result">) => boolean)>(this: TThis, trigger: Trigger, handler: (context: Ctx<"chosen_inline_result"> & {
         args: RegExpMatchArray | null;
+        queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : never;
     } & EventContextOf<TThis, "chosen_inline_result">) => unknown, macroOptions?: Record<string, unknown>): TThis;
-    inlineQuery<TThis extends GramIOLike<TThis>>(this: TThis, trigger: RegExp | string | ((context: Ctx<"inline_query">) => boolean), handler: (context: Ctx<"inline_query"> & {
+    inlineQuery<TThis extends GramIOLike<TThis>>(this: TThis, triggerOrHandler: RegExp | string | ((context: Ctx<"inline_query">) => boolean) | ((context: Ctx<"inline_query"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "inline_query">) => unknown), maybeHandler?: (context: Ctx<"inline_query"> & {
         args: RegExpMatchArray | null;
     } & EventContextOf<TThis, "inline_query">) => unknown, options?: {
         onResult?: (context: Ctx<"chosen_inline_result"> & {
             args: RegExpMatchArray | null;
         } & EventContextOf<TThis, "chosen_inline_result">) => unknown;
     } & Record<string, unknown>): TThis;
+    guestQuery<TThis extends GramIOLike<TThis>>(this: TThis, triggerOrHandler: RegExp | string | ((context: Ctx<"guest_message">) => boolean) | ((context: Ctx<"guest_message"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "guest_message">) => unknown), maybeHandler?: (context: Ctx<"guest_message"> & {
+        args: RegExpMatchArray | null;
+    } & EventContextOf<TThis, "guest_message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
     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;
@@ -325,6 +343,7 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
             edited_channel_post: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">;
             business_message: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">;
             edited_business_message: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">;
+            guest_message: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">;
             deleted_business_messages: _gramio_contexts.BusinessMessagesDeletedContext<AnyBot>;
             business_connection: _gramio_contexts.BusinessConnectionContext<AnyBot>;
             migrate_from_chat_id: _gramio_contexts.MigrateFromChatIdContext<AnyBot>;
@@ -408,8 +427,9 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, trigger: RegExp | string | ((context: _gramio_contexts.ChosenInlineResultContext<AnyBot>) => boolean), handler: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
+            }, Trigger extends _gramio_callback_data.CallbackData | RegExp | string | ((context: _gramio_contexts.ChosenInlineResultContext<AnyBot>) => boolean)>(this: TThis, trigger: Trigger, handler: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
                 args: RegExpMatchArray | null;
+                queryData: Trigger extends _gramio_callback_data.CallbackData ? ReturnType<Trigger["unpack"]> : never;
             } & _gramio_composer.EventContextOf<TThis, "chosen_inline_result">) => unknown, macroOptions?: Record<string, unknown>): TThis;
             inlineQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
@@ -418,13 +438,27 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, trigger: RegExp | string | ((context: _gramio_contexts.InlineQueryContext<AnyBot>) => boolean), handler: (context: _gramio_contexts.InlineQueryContext<AnyBot> & {
+            }>(this: TThis, triggerOrHandler: RegExp | string | ((context: _gramio_contexts.InlineQueryContext<AnyBot>) => boolean) | ((context: _gramio_contexts.InlineQueryContext<AnyBot> & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "inline_query">) => unknown), maybeHandler?: (context: _gramio_contexts.InlineQueryContext<AnyBot> & {
                 args: RegExpMatchArray | null;
             } & _gramio_composer.EventContextOf<TThis, "inline_query">) => unknown, options?: {
                 onResult?: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
                     args: RegExpMatchArray | null;
                 } & _gramio_composer.EventContextOf<TThis, "chosen_inline_result">) => unknown;
             } & Record<string, unknown>): TThis;
+            guestQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
+                "~": {
+                    macros: MacroDefinitions;
+                    commandsMeta?: Map<string, unknown>;
+                    Derives?: Record<string, object>;
+                };
+                chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
+            }>(this: TThis, triggerOrHandler: RegExp | string | ((context: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) => boolean) | ((context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "guest_message">) => unknown), maybeHandler?: (context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "guest_message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
             hears<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
@@ -483,8 +517,9 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, trigger: RegExp | string | ((context: _gramio_contexts.ChosenInlineResultContext<AnyBot>) => boolean), handler: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
+            }, Trigger extends _gramio_callback_data.CallbackData | RegExp | string | ((context: _gramio_contexts.ChosenInlineResultContext<AnyBot>) => boolean)>(this: TThis, trigger: Trigger, handler: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
                 args: RegExpMatchArray | null;
+                queryData: Trigger extends _gramio_callback_data.CallbackData ? ReturnType<Trigger["unpack"]> : never;
             } & _gramio_composer.EventContextOf<TThis, "chosen_inline_result">) => unknown, macroOptions?: Record<string, unknown>): TThis;
             inlineQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
@@ -493,13 +528,27 @@ declare class Plugin<Errors extends ErrorDefinitions = {}, Derives extends Deriv
                     Derives?: Record<string, object>;
                 };
                 chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
-            }>(this: TThis, trigger: RegExp | string | ((context: _gramio_contexts.InlineQueryContext<AnyBot>) => boolean), handler: (context: _gramio_contexts.InlineQueryContext<AnyBot> & {
+            }>(this: TThis, triggerOrHandler: RegExp | string | ((context: _gramio_contexts.InlineQueryContext<AnyBot>) => boolean) | ((context: _gramio_contexts.InlineQueryContext<AnyBot> & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "inline_query">) => unknown), maybeHandler?: (context: _gramio_contexts.InlineQueryContext<AnyBot> & {
                 args: RegExpMatchArray | null;
             } & _gramio_composer.EventContextOf<TThis, "inline_query">) => unknown, options?: {
                 onResult?: (context: _gramio_contexts.ChosenInlineResultContext<AnyBot> & {
                     args: RegExpMatchArray | null;
                 } & _gramio_composer.EventContextOf<TThis, "chosen_inline_result">) => unknown;
             } & Record<string, unknown>): TThis;
+            guestQuery<TThis extends _gramio_composer.ComposerLike<TThis> & {
+                "~": {
+                    macros: MacroDefinitions;
+                    commandsMeta?: Map<string, unknown>;
+                    Derives?: Record<string, object>;
+                };
+                chosenInlineResult(trigger: any, handler: any, macroOptions?: any): TThis;
+            }>(this: TThis, triggerOrHandler: RegExp | string | ((context: _gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) => boolean) | ((context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "guest_message">) => unknown), maybeHandler?: (context: (_gramio_contexts.MessageContext<AnyBot> & _gramio_contexts.Require<_gramio_contexts.MessageContext<AnyBot>, "from">) & {
+                args: RegExpMatchArray | null;
+            } & _gramio_composer.EventContextOf<TThis, "guest_message">) => unknown, macroOptions?: Record<string, unknown>): TThis;
             hears<TThis extends _gramio_composer.ComposerLike<TThis> & {
                 "~": {
                     macros: MacroDefinitions;
@@ -750,6 +799,8 @@ interface Plugin<Errors, Derives, Macros> {
     reaction: (typeof methods)["reaction"];
     /** Register inline query handler */
     inlineQuery: (typeof methods)["inlineQuery"];
+    /** Register guest query (`guest_message`) handler */
+    guestQuery: (typeof methods)["guestQuery"];
     /** Register chosen inline result handler */
     chosenInlineResult: (typeof methods)["chosenInlineResult"];
     /** Register deep-link parameter handler */
@@ -794,6 +845,30 @@ interface BotOptions {
          */
         retryGetUpdatesWait?: number;
     };
+    /**
+     * File download/serving options — mainly for a **local Bot API server**.
+     *
+     * @example
+     * ```ts
+     * const bot = new Bot(token, {
+     *     api: { baseURL: "http://telegram-bot-api:8081/bot" },
+     *     files: {
+     *         // bot.getFileLink() and ctx.download() resolve to this (token-less) URL
+     *         baseURL: "http://telegram-bot-api:8080",
+     *     },
+     * });
+     * ```
+     */
+    files?: {
+        /** How to fetch file bytes. @default "auto" */
+        source?: FileSource;
+        /** Working directory of the local Bot API server — the prefix of the absolute `file_path` it returns. @default "/var/lib/telegram-bot-api" */
+        localDir?: string;
+        /** Where that working dir is mounted on the bot's side (for `source: "disk"` when bot & server share a volume at a different path). Defaults to `localDir`. */
+        mountDir?: string;
+        /** Public base URL where the working dir is served (e.g. the bundled file server / nginx). Enables token-less {@link Bot.getFileLink} and `source: "rewrite"`. */
+        baseURL?: string;
+    };
 }
 /**
  * Handler is a function with context and next function arguments
@@ -1202,10 +1277,27 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      */
     downloadFile(attachment: Attachment | {
         file_id: string;
-    } | string): Promise<ArrayBuffer>;
+    } | string): TelegramFileDownload;
     downloadFile(attachment: Attachment | {
         file_id: string;
     } | string, path: string): Promise<string>;
+    /**
+     * Get a shareable download link for a file.
+     *
+     * When {@link BotOptions.files | `files.baseURL`} is set (e.g. a local Bot API
+     * server with the bundled file server), the link is **token-less and path-based**
+     * — safe to hand to users. Otherwise it falls back to the classic
+     * `…/file/bot<token>/<path>` URL (which contains the bot token).
+     *
+     * @example
+     * ```ts
+     * const link = await bot.getFileLink(ctx.document.fileId);
+     * await ctx.reply(`Download: ${link}`);
+     * ```
+     */
+    getFileLink(attachment: Attachment | {
+        file_id: string;
+    } | string): Promise<string>;
     /**
      * Register custom class-error for type-safe catch in `onError` hook
      *
@@ -1478,9 +1570,35 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      * ```
      */
     callbackQuery<Trigger extends CallbackData | string | RegExp, TOptions extends HandlerOptions<CallbackQueryShorthandContext<typeof this, Trigger>, Macros> = {}>(trigger: Trigger, handler: (context: CallbackQueryShorthandContext<typeof this, Trigger> & DeriveFromOptions<Macros, TOptions>) => unknown, options?: TOptions): this;
-    /** Register handler to `chosen_inline_result` update */
-    chosenInlineResult<Ctx = ContextType<typeof this, "chosen_inline_result">, TOptions extends HandlerOptions<Ctx, Macros> = {}>(trigger: RegExp | string | ((context: Ctx) => boolean), handler: (context: Ctx & {
+    /**
+     * Register handler to `chosen_inline_result` update
+     *
+     * Accepts a `CallbackData` schema for type-safe filtering on `result_id`:
+     *
+     * @example
+     * ```ts
+     * const trackRef = new CallbackData("track").string("src").string("id");
+     *
+     * new Bot()
+     *     .on("inline_query", async (ctx) => {
+     *         await ctx.answer(tracks.map((t) => ({
+     *             type: "audio",
+     *             id: trackRef.pack({ src: t.source, id: t.id }),
+     *             audio_url: t.url,
+     *             title: t.title,
+     *         })));
+     *     })
+     *     .chosenInlineResult(trackRef, (ctx) => {
+     *         ctx.queryData; // { src: string; id: string }
+     *     });
+     * ```
+     *
+     * String/RegExp/predicate triggers filter on `context.query` (the user's
+     * typed text); the `CallbackData` schema filters on `context.resultId`.
+     */
+    chosenInlineResult<Trigger extends CallbackData | RegExp | string | ((context: ContextType<typeof this, "chosen_inline_result">) => boolean), Ctx = ContextType<typeof this, "chosen_inline_result">, TOptions extends HandlerOptions<Ctx, Macros> = {}>(trigger: Trigger, handler: (context: Ctx & {
         args: RegExpMatchArray | null;
+        queryData: Trigger extends CallbackData ? ReturnType<Trigger["unpack"]> : never;
     } & DeriveFromOptions<Macros, TOptions>) => unknown, options?: TOptions): this;
     /**
      * Register handler to `inline_query` update
@@ -1517,6 +1635,9 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
      * );
      * ```
      * */
+    inlineQuery<Ctx = ContextType<typeof this, "inline_query">>(handler: (context: Ctx & {
+        args: RegExpMatchArray | null;
+    }) => unknown): this;
     inlineQuery<Ctx = ContextType<typeof this, "inline_query">>(trigger: RegExp | string | ((context: Ctx) => boolean), handler: (context: Ctx & {
         args: RegExpMatchArray | null;
     }) => unknown, options?: HandlerOptions<Ctx, Macros> & {
@@ -1524,6 +1645,34 @@ declare class Bot<Errors extends ErrorDefinitions = {}, Derives extends DeriveDe
             args: RegExpMatchArray | null;
         }) => unknown;
     }): this;
+    /**
+     * Register handler to `guest_message` update — a message sent to the bot
+     * from a chat where the bot is not a member, via a guest query.
+     *
+     * Reply with {@link MessageContext.answerGuestQuery `context.answerGuestQuery()`}
+     * (NOT `context.send`/`context.reply`, which target a chat the bot can't post to).
+     *
+     * @example
+     * ```ts
+     * new Bot().guestQuery(/^find (.*)/i, async (context) => {
+     *     await context.answerGuestQuery({
+     *         type: "text",
+     *         text: `Looking up ${context.args?.[1]}…`,
+     *     });
+     * });
+     *
+     * // No-trigger form — match any guest message:
+     * new Bot().guestQuery(async (context) => {
+     *     await context.answerGuestQuery({ type: "text", text: "Hi!" });
+     * });
+     * ```
+     * */
+    guestQuery<Ctx = ContextType<typeof this, "guest_message">>(handler: (context: Ctx & {
+        args: RegExpMatchArray | null;
+    }) => unknown): this;
+    guestQuery<Ctx = ContextType<typeof this, "guest_message">>(trigger: RegExp | string | ((context: Ctx) => boolean), handler: (context: Ctx & {
+        args: RegExpMatchArray | null;
+    }) => unknown, options?: HandlerOptions<Ctx, Macros>): this;
     /**
      * Register handler to `message` and `business_message` event
      *
@@ -1996,7 +2145,7 @@ interface WebhookHandlerOptions {
  * });
  * ```
  */
-declare function webhookHandler<Framework extends keyof typeof frameworks>(bot: Bot, framework: Framework, secretTokenOrOptions?: string | WebhookHandlerOptions): ReturnType<(typeof frameworks)[Framework]> extends {
+declare function webhookHandler<Framework extends keyof typeof frameworks>(bot: AnyBot, framework: Framework, secretTokenOrOptions?: string | WebhookHandlerOptions): ReturnType<(typeof frameworks)[Framework]> extends {
     response: () => any;
 } ? (...args: Parameters<(typeof frameworks)[Framework]>) => ReturnType<ReturnType<(typeof frameworks)[Framework]>["response"]> : (...args: Parameters<(typeof frameworks)[Framework]>) => void;

package/dist/index.js CHANGED Viewed

@@ -1,13 +1,11 @@
 export * from '@gramio/callback-data';
-import { contextsMappings, PhotoAttachment } from '@gramio/contexts';
+import { contextsMappings } from '@gramio/contexts';
 export * from '@gramio/contexts';
-import { isMediaUpload, convertJsonToFormData, extractFilesToFormData } from '@gramio/files';
+import { downloadFile, isMediaUpload, convertJsonToFormData, extractFilesToFormData } from '@gramio/files';
 export * from '@gramio/files';
 import { FormattableMap } from '@gramio/format';
 export * from '@gramio/format';
 export * from '@gramio/keyboards';
-import fs from 'node:fs/promises';
-import { Readable } from 'node:stream';
 import debug from 'debug';
 import { E as ErrorKind, w as withRetries, T as TelegramError, s as sleep, d as debug$updates, a as simpleHash, I as IS_BUN, b as simplifyObject, t as timeoutWebhook } from './utils-1ejkKLIB.js';
 import { defineComposerMethods, buildFromOptions, noopNext, createComposer, eventTypes, EventQueue } from '@gramio/composer';
@@ -37,7 +35,8 @@ const ALL_NAMES = [
   "chat_join_request",
   "chat_boost",
   "removed_chat_boost",
-  "managed_bot"
+  "managed_bot",
+  "guest_message"
 ];
 const MESSAGE_PARENT_TYPES = [
   "message",
@@ -200,13 +199,23 @@ const methods = defineComposerMethods({
         return macroHandler ? macroHandler(context, noopNext) : handler(context);
       });
     }
+    if (typeof trigger === "function") {
+      return this.on("chosen_inline_result", (context, next) => {
+        if (!trigger(context)) return next();
+        context.args = null;
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
+      });
+    }
     return this.on("chosen_inline_result", (context, next) => {
-      if (!trigger(context)) return next();
+      if (!context.resultId || !trigger.filter(context.resultId)) return next();
       context.args = null;
+      context.queryData = trigger.unpack(context.resultId);
       return macroHandler ? macroHandler(context, noopNext) : handler(context);
     });
   },
-  inlineQuery(trigger, handler, options = {}) {
+  inlineQuery(triggerOrHandler, maybeHandler, options = {}) {
+    const trigger = maybeHandler === void 0 ? (() => true) : triggerOrHandler;
+    const handler = maybeHandler ?? triggerOrHandler;
     if (options.onResult) this.chosenInlineResult(trigger, options.onResult);
     const { onResult: _, ...macroOptions } = options;
     const hasMacros = Object.keys(macroOptions).length > 0;
@@ -231,6 +240,32 @@ const methods = defineComposerMethods({
       return macroHandler ? macroHandler(context, noopNext) : handler(context);
     });
   },
+  guestQuery(triggerOrHandler, maybeHandler, macroOptions) {
+    const trigger = maybeHandler === void 0 ? (() => true) : triggerOrHandler;
+    const handler = maybeHandler ?? triggerOrHandler;
+    const macroHandler = macroOptions ? buildFromOptions(this["~"].macros, macroOptions, handler) : null;
+    if (typeof trigger === "string") {
+      return this.on("guest_message", (context, next) => {
+        const text = context.text ?? context.caption;
+        if (text !== trigger) return next();
+        context.args = null;
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
+      });
+    }
+    if (trigger instanceof RegExp) {
+      return this.on("guest_message", (context, next) => {
+        const text = context.text ?? context.caption;
+        if (!text || !trigger.test(text)) return next();
+        context.args = text.match(trigger);
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
+      });
+    }
+    return this.on("guest_message", (context, next) => {
+      if (!trigger(context)) return next();
+      context.args = null;
+      return macroHandler ? macroHandler(context, noopNext) : handler(context);
+    });
+  },
   hears(trigger, handler, macroOptions) {
     const macroHandler = macroOptions ? buildFromOptions(this["~"].macros, macroOptions, handler) : null;
     if (typeof trigger === "string") {
@@ -692,6 +727,7 @@ class Updates {
           })
         );
         this.isRequestActive = false;
+        if (!this.isStarted) break;
         const updateId = updates.at(-1)?.update_id;
         this.offset = updateId ? updateId + 1 : this.offset;
         this.queue.addBatch(updates);
@@ -911,28 +947,26 @@ class Bot {
     }
     return fn();
   }
-  async downloadFile(attachment, path) {
-    function getFileId(attachment2) {
-      if (attachment2 instanceof PhotoAttachment) {
-        return attachment2.bigSize.fileId;
-      }
-      if ("fileId" in attachment2 && typeof attachment2.fileId === "string")
-        return attachment2.fileId;
-      if ("file_id" in attachment2) return attachment2.file_id;
-      throw new Error("Invalid attachment");
-    }
-    const fileId = typeof attachment === "string" ? attachment : getFileId(attachment);
-    const file = await this.api.getFile({ file_id: fileId });
-    const url = `${this.options.api.baseURL.replace("/bot", "/file/bot")}${this.options.token}/${file.file_path}`;
-    const res = await fetch(url);
-    if (path) {
-      if (!res.body)
-        throw new Error("Response without body (should be never throw)");
-      await fs.writeFile(path, Readable.fromWeb(res.body));
-      return path;
-    }
-    const buffer = await res.arrayBuffer();
-    return buffer;
+  downloadFile(attachment, path) {
+    const input = attachment;
+    return path ? downloadFile(this, input, path) : downloadFile(this, input);
+  }
+  /**
+   * Get a shareable download link for a file.
+   *
+   * When {@link BotOptions.files | `files.baseURL`} is set (e.g. a local Bot API
+   * server with the bundled file server), the link is **token-less and path-based**
+   * — safe to hand to users. Otherwise it falls back to the classic
+   * `…/file/bot<token>/<path>` URL (which contains the bot token).
+   *
+   * @example
+   * ```ts
+   * const link = await bot.getFileLink(ctx.document.fileId);
+   * await ctx.reply(`Download: ${link}`);
+   * ```
+   */
+  getFileLink(attachment) {
+    return downloadFile(this, attachment).link();
   }
   /**
    * Register custom class-error for type-safe catch in `onError` hook
@@ -1276,7 +1310,32 @@ class Bot {
     );
     return this;
   }
-  /** Register handler to `chosen_inline_result` update */
+  /**
+   * Register handler to `chosen_inline_result` update
+   *
+   * Accepts a `CallbackData` schema for type-safe filtering on `result_id`:
+   *
+   * @example
+   * ```ts
+   * const trackRef = new CallbackData("track").string("src").string("id");
+   *
+   * new Bot()
+   *     .on("inline_query", async (ctx) => {
+   *         await ctx.answer(tracks.map((t) => ({
+   *             type: "audio",
+   *             id: trackRef.pack({ src: t.source, id: t.id }),
+   *             audio_url: t.url,
+   *             title: t.title,
+   *         })));
+   *     })
+   *     .chosenInlineResult(trackRef, (ctx) => {
+   *         ctx.queryData; // { src: string; id: string }
+   *     });
+   * ```
+   *
+   * String/RegExp/predicate triggers filter on `context.query` (the user's
+   * typed text); the `CallbackData` schema filters on `context.resultId`.
+   */
   chosenInlineResult(trigger, handler, options) {
     this.updates.composer.chosenInlineResult(
       trigger,
@@ -1285,49 +1344,18 @@ class Bot {
     );
     return this;
   }
-  /**
-   * Register handler to `inline_query` update
-   *
-   * @example
-   * ```ts
-   * new Bot().inlineQuery(
-   *     /regular expression with (.*)/i,
-   *     async (context) => {
-   *         if (context.args) {
-   *             await context.answer(
-   *                 [
-   *                     InlineQueryResult.article(
-   *                         "id-1",
-   *                         context.args[1],
-   *                         InputMessageContent.text("some"),
-   *                         {
-   *                             reply_markup: new InlineKeyboard().text(
-   *                                 "some",
-   *                                 "callback-data"
-   *                             ),
-   *                         }
-   *                     ),
-   *                 ],
-   *                 {
-   *                     cache_time: 0,
-   *                 }
-   *             );
-   *         }
-   *     },
-   *     {
-   *         onResult: (context) => context.editText("Message edited!"),
-   *     }
-   * );
-   * ```
-   * */
-  inlineQuery(trigger, handler, options) {
+  inlineQuery(triggerOrHandler, handler, options) {
     this.updates.composer.inlineQuery(
-      trigger,
+      triggerOrHandler,
       handler,
       options
     );
     return this;
   }
+  guestQuery(triggerOrHandler, handler, options) {
+    this.updates.composer.guestQuery(triggerOrHandler, handler, options);
+    return this;
+  }
   /**
    * Register handler to `message` and `business_message` event
    *

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
 	"name": "gramio",
 	"type": "module",
-	"version": "0.9.0",
+	"version": "0.11.0",
 	"description": "Powerful, extensible and really type-safe Telegram Bot API framework",
 	"main": "dist/index.cjs",
 	"module": "dist/index.js",
@@ -55,25 +55,28 @@
 	"author": "kravets",
 	"license": "MIT",
 	"devDependencies": {
-		"@biomejs/biome": "2.4.4",
-		"@gramio/test": "^0.5.0",
-		"@types/bun": "^1.3.9",
-		"@types/debug": "^4.1.12",
+		"@biomejs/biome": "2.4.14",
+		"@gramio/test": "^0.7.0",
+		"@types/bun": "^1.3.13",
+		"@types/debug": "^4.1.13",
 		"expect-type": "^1.3.0",
 		"pkgroll": "^2.27.0",
 		"typescript": "^5.9.3"
 	},
 	"dependencies": {
 		"@gramio/callback-data": "^0.1.0",
-		"@gramio/composer": "^0.4.1",
-		"@gramio/contexts": "^0.6.1",
-		"@gramio/files": "^0.4.0",
-		"@gramio/format": "^0.7.0",
+		"@gramio/composer": "^0.5.0",
+		"@gramio/contexts": "^0.8.0",
+		"@gramio/files": "^0.6.1",
+		"@gramio/format": "^0.8.0",
 		"@gramio/keyboards": "^1.4.0",
-		"@gramio/types": "^9.6.1",
+		"@gramio/types": "^10.0.0",
 		"debug": "^4.4.3"
 	},
 	"files": [
 		"dist"
-	]
+	],
+	"overrides": {
+		"@gramio/types": "$@gramio/types"
+	}
 }