gramio 0.10.0 → 0.12.0

package/dist/index.cjs

@@ -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');
@@ -199,9 +197,17 @@ 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);
     });
   },
@@ -719,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);
@@ -938,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
@@ -1303,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,

package/dist/index.d.cts

@@ -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,8 +185,9 @@ 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, triggerOrHandler: RegExp | string | ((context: Ctx<"inline_query">) => boolean) | ((context: Ctx<"inline_query"> & {
         args: RegExpMatchArray | null;
@@ -233,8 +235,9 @@ 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, triggerOrHandler: RegExp | string | ((context: Ctx<"inline_query">) => boolean) | ((context: Ctx<"inline_query"> & {
         args: RegExpMatchArray | null;
@@ -424,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> & {
                 "~": {
@@ -513,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> & {
                 "~": {
@@ -840,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
@@ -1248,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
      *
@@ -1524,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

package/dist/index.d.ts

@@ -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,8 +185,9 @@ 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, triggerOrHandler: RegExp | string | ((context: Ctx<"inline_query">) => boolean) | ((context: Ctx<"inline_query"> & {
         args: RegExpMatchArray | null;
@@ -233,8 +235,9 @@ 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, triggerOrHandler: RegExp | string | ((context: Ctx<"inline_query">) => boolean) | ((context: Ctx<"inline_query"> & {
         args: RegExpMatchArray | null;
@@ -424,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> & {
                 "~": {
@@ -513,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> & {
                 "~": {
@@ -840,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
@@ -1248,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
      *
@@ -1524,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

package/dist/index.js

@@ -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';
@@ -201,9 +199,17 @@ 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);
     });
   },
@@ -721,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);
@@ -940,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
@@ -1305,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,

package/dist/rich.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var rich = require('@gramio/format/rich');
+
+
+
+Object.keys(rich).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return rich[k]; }
+	});
+});

package/dist/rich.d.cts

@@ -0,0 +1 @@
+export * from '@gramio/format/rich';

package/dist/rich.d.ts

@@ -0,0 +1 @@
+export * from '@gramio/format/rich';

package/dist/rich.js

@@ -0,0 +1 @@
+export * from '@gramio/format/rich';

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "gramio",
 	"type": "module",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"description": "Powerful, extensible and really type-safe Telegram Bot API framework",
 	"main": "dist/index.cjs",
 	"module": "dist/index.js",
@@ -26,6 +26,16 @@
 				"types": "./dist/utils.d.cts",
 				"default": "./dist/utils.cjs"
 			}
+		},
+		"./rich": {
+			"import": {
+				"types": "./dist/rich.d.ts",
+				"default": "./dist/rich.js"
+			},
+			"require": {
+				"types": "./dist/rich.d.cts",
+				"default": "./dist/rich.cjs"
+			}
 		}
 	},
 	"keywords": [
@@ -65,12 +75,12 @@
 	},
 	"dependencies": {
 		"@gramio/callback-data": "^0.1.0",
-		"@gramio/composer": "^0.4.1",
-		"@gramio/contexts": "^0.7.0",
-		"@gramio/files": "^0.5.0",
-		"@gramio/format": "^0.8.0",
+		"@gramio/composer": "^0.5.0",
+		"@gramio/contexts": "^0.9.0",
+		"@gramio/files": "^0.6.1",
+		"@gramio/format": "^0.9.0",
 		"@gramio/keyboards": "^1.4.0",
-		"@gramio/types": "^10.0.0",
+		"@gramio/types": "^10.1.0",
 		"debug": "^4.4.3"
 	},
 	"files": [