gramio 0.5.0 → 0.6.1

package/dist/index.js

@@ -9,177 +9,181 @@ 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, I as IS_BUN, a as simplifyObject, t as timeoutWebhook } from './utils-En0iVLWH.js';
-import { createComposer, noopNext, eventTypes, EventQueue } from '@gramio/composer';
-export { EventQueue, compose, noopNext, skip, stop } from '@gramio/composer';
+import { E as ErrorKind, w as withRetries, T as TelegramError, s as sleep, d as debug$updates, I as IS_BUN, a as simplifyObject, t as timeoutWebhook } from './utils-DqK73ALI.js';
+import { defineComposerMethods, buildFromOptions, noopNext, createComposer, eventTypes, EventQueue } from '@gramio/composer';
+export { EventQueue, buildFromOptions, compose, noopNext, skip, stop } from '@gramio/composer';
 
-const { Composer } = createComposer({
-  discriminator: (ctx) => ctx.updateType,
-  types: eventTypes(),
-  methods: {
-    reaction(trigger, handler) {
-      const reactions = Array.isArray(trigger) ? trigger : [trigger];
-      return this.on("message_reaction", (context, next) => {
-        const newReactions = [];
-        for (const reaction of context.newReactions) {
-          if (reaction.type !== "emoji") continue;
-          const foundIndex = context.oldReactions.findIndex(
-            (oldReaction) => oldReaction.type === "emoji" && oldReaction.emoji === reaction.emoji
-          );
-          if (foundIndex === -1) {
-            newReactions.push(reaction);
-          } else {
-            context.oldReactions.splice(foundIndex, 1);
-          }
+const methods = defineComposerMethods({
+  reaction(trigger, handler, macroOptions) {
+    const reactions = Array.isArray(trigger) ? trigger : [trigger];
+    const macroHandler = macroOptions ? buildFromOptions(this["~"].macros, macroOptions, handler) : null;
+    return this.on(
+      "message_reaction",
+      (context, next) => {
+        const oldEmojis = /* @__PURE__ */ new Set();
+        for (const r of context.oldReactions) {
+          if (r.type === "emoji") oldEmojis.add(r.emoji);
         }
-        if (!newReactions.some(
-          (x) => x.type === "emoji" && reactions.includes(x.emoji)
-        ))
-          return next();
-        return handler(context);
-      });
-    },
-    callbackQuery(trigger, handler) {
-      if (typeof trigger === "string") {
-        return this.on("callback_query", (context, next) => {
-          if (context.data !== trigger) return next();
-          return handler(context);
-        });
-      }
-      if (trigger instanceof RegExp) {
-        return this.on("callback_query", (context, next) => {
-          if (!context.data || !trigger.test(context.data)) return next();
-          context.queryData = context.data.match(trigger);
-          return handler(context);
-        });
+        const hasNewMatchingReaction = context.newReactions.some(
+          (reaction) => reaction.type === "emoji" && !oldEmojis.has(reaction.emoji) && reactions.includes(reaction.emoji)
+        );
+        if (!hasNewMatchingReaction) return next();
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
       }
-      const regexp = trigger.regexp();
+    );
+  },
+  callbackQuery(trigger, handler, macroOptions) {
+    const macroHandler = macroOptions ? buildFromOptions(this["~"].macros, macroOptions, handler) : null;
+    if (typeof trigger === "string") {
       return this.on("callback_query", (context, next) => {
-        if (!context.data || !regexp.test(context.data)) return next();
-        context.queryData = trigger.unpack(context.data);
-        return handler(context);
+        if (context.data !== trigger) return next();
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
       });
-    },
-    chosenInlineResult(trigger, handler) {
-      if (typeof trigger === "string") {
-        return this.on("chosen_inline_result", (context, next) => {
-          if (context.query !== trigger) return next();
-          context.args = null;
-          return handler(context);
-        });
-      }
-      if (trigger instanceof RegExp) {
-        return this.on("chosen_inline_result", (context, next) => {
-          if (!trigger.test(context.query)) return next();
-          context.args = context.query?.match(trigger);
-          return handler(context);
-        });
-      }
+    }
+    if (trigger instanceof RegExp) {
+      return this.on("callback_query", (context, next) => {
+        if (!context.data || !trigger.test(context.data)) return next();
+        context.queryData = context.data.match(trigger);
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
+      });
+    }
+    return this.on("callback_query", (context, next) => {
+      if (!context.data || !trigger.filter(context.data)) return next();
+      context.queryData = trigger.unpack(context.data);
+      return macroHandler ? macroHandler(context, noopNext) : handler(context);
+    });
+  },
+  chosenInlineResult(trigger, handler, macroOptions) {
+    const macroHandler = macroOptions ? buildFromOptions(this["~"].macros, macroOptions, handler) : null;
+    if (typeof trigger === "string") {
       return this.on("chosen_inline_result", (context, next) => {
-        if (!trigger(context)) return next();
+        if (context.query !== trigger) return next();
         context.args = null;
-        return handler(context);
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
       });
-    },
-    inlineQuery(trigger, handler, options = {}) {
-      if (options.onResult)
-        this.chosenInlineResult(trigger, options.onResult);
-      if (typeof trigger === "string") {
-        return this.on("inline_query", (context, next) => {
-          if (context.query !== trigger) return next();
-          context.args = null;
-          return handler(context);
-        });
-      }
-      if (trigger instanceof RegExp) {
-        return this.on("inline_query", (context, next) => {
-          if (!trigger.test(context.query)) return next();
-          context.args = context.query?.match(trigger);
-          return handler(context);
-        });
-      }
+    }
+    if (trigger instanceof RegExp) {
+      return this.on("chosen_inline_result", (context, next) => {
+        if (!trigger.test(context.query)) return next();
+        context.args = context.query?.match(trigger);
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
+      });
+    }
+    return this.on("chosen_inline_result", (context, next) => {
+      if (!trigger(context)) return next();
+      context.args = null;
+      return macroHandler ? macroHandler(context, noopNext) : handler(context);
+    });
+  },
+  inlineQuery(trigger, handler, options = {}) {
+    if (options.onResult) this.chosenInlineResult(trigger, options.onResult);
+    const { onResult: _, ...macroOptions } = options;
+    const hasMacros = Object.keys(macroOptions).length > 0;
+    const macroHandler = hasMacros ? buildFromOptions(this["~"].macros, macroOptions, handler) : null;
+    if (typeof trigger === "string") {
       return this.on("inline_query", (context, next) => {
-        if (!trigger(context)) return next();
+        if (context.query !== trigger) return next();
         context.args = null;
-        return handler(context);
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
       });
-    },
-    hears(trigger, handler) {
-      if (typeof trigger === "string") {
-        return this.on("message", (context, next) => {
-          if ((context.text ?? context.caption) !== trigger) return next();
-          context.args = null;
-          return handler(context);
-        });
-      }
-      if (Array.isArray(trigger)) {
-        return this.on("message", (context, next) => {
-          const text = context.text ?? context.caption;
-          if (!text || !trigger.includes(text)) return next();
-          context.args = null;
-          return handler(context);
-        });
-      }
-      if (trigger instanceof RegExp) {
-        return this.on("message", (context, next) => {
-          const text = context.text ?? context.caption;
-          if (!text || !trigger.test(text)) return next();
-          context.args = text.match(trigger);
-          return handler(context);
-        });
-      }
+    }
+    if (trigger instanceof RegExp) {
+      return this.on("inline_query", (context, next) => {
+        if (!trigger.test(context.query)) return next();
+        context.args = context.query?.match(trigger);
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
+      });
+    }
+    return this.on("inline_query", (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") {
       return this.on("message", (context, next) => {
-        if (typeof trigger !== "function" || !trigger(context)) return next();
+        if ((context.text ?? context.caption) !== trigger) return next();
         context.args = null;
-        return handler(context);
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
       });
-    },
-    command(command, handler) {
-      const normalizedCommands = typeof command === "string" ? [command] : Array.from(command);
-      for (const cmd of normalizedCommands) {
-        if (cmd.startsWith("/"))
-          throw new Error(`Do not use / in command name (${cmd})`);
-      }
-      return this.on(["message", "business_message"], (context, next) => {
-        if (context.entities?.some((entity) => {
-          if (entity.type !== "bot_command" || entity.offset > 0)
-            return false;
-          const botInfo = context.bot.info;
-          const cmd = context.text?.slice(1, entity.length)?.replace(
-            botInfo?.username ? `@${botInfo.username}` : /@[a-zA-Z0-9_]+/,
-            ""
-          );
-          context.args = context.text?.slice(entity.length).trim() || null;
-          return normalizedCommands.some(
-            (normalizedCommand) => cmd === normalizedCommand
-          );
-        }))
-          return handler(context);
-        return next();
+    }
+    if (Array.isArray(trigger)) {
+      return this.on("message", (context, next) => {
+        const text = context.text ?? context.caption;
+        if (!text || !trigger.includes(text)) return next();
+        context.args = null;
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
       });
-    },
-    startParameter(parameter, handler) {
-      if (parameter instanceof RegExp) {
-        return this.on("message", (context, next) => {
-          if (!context.rawStartPayload || !parameter.test(context.rawStartPayload))
-            return next();
-          return handler(context, noopNext);
-        });
-      }
-      if (Array.isArray(parameter)) {
-        return this.on("message", (context, next) => {
-          if (!context.rawStartPayload || !parameter.includes(context.rawStartPayload))
-            return next();
-          return handler(context, noopNext);
-        });
+    }
+    if (trigger instanceof RegExp) {
+      return this.on("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("message", (context, next) => {
+      if (typeof trigger !== "function" || !trigger(context)) return next();
+      context.args = null;
+      return macroHandler ? macroHandler(context, noopNext) : handler(context);
+    });
+  },
+  command(command, handler, macroOptions) {
+    const normalizedCommands = typeof command === "string" ? [command] : Array.from(command);
+    for (const cmd of normalizedCommands) {
+      if (cmd.startsWith("/"))
+        throw new Error(`Do not use / in command name (${cmd})`);
+    }
+    const macroHandler = macroOptions ? buildFromOptions(this["~"].macros, macroOptions, handler) : null;
+    return this.on(["message", "business_message"], (context, next) => {
+      const entity = context.entities?.find((entity2) => {
+        if (entity2.type !== "bot_command" || entity2.offset > 0) return false;
+        const botInfo = context.bot.info;
+        const cmd = context.text?.slice(1, entity2.length)?.replace(
+          botInfo?.username ? `@${botInfo.username}` : /@[a-zA-Z0-9_]+/,
+          ""
+        );
+        return normalizedCommands.some(
+          (normalizedCommand) => cmd === normalizedCommand
+        );
+      });
+      if (entity) {
+        context.args = context.text?.slice(entity.length).trim() || null;
+        return macroHandler ? macroHandler(context, noopNext) : handler(context);
       }
+      return next();
+    });
+  },
+  startParameter(parameter, handler, macroOptions) {
+    const macroHandler = macroOptions ? buildFromOptions(this["~"].macros, macroOptions, handler) : null;
+    if (parameter instanceof RegExp) {
+      return this.on("message", (context, next) => {
+        if (!context.rawStartPayload || !parameter.test(context.rawStartPayload))
+          return next();
+        return macroHandler ? macroHandler(context, noopNext) : handler(context, noopNext);
+      });
+    }
+    if (Array.isArray(parameter)) {
       return this.on("message", (context, next) => {
-        if (context.rawStartPayload !== parameter) return next();
-        return handler(context, noopNext);
+        if (!context.rawStartPayload || !parameter.includes(context.rawStartPayload))
+          return next();
+        return macroHandler ? macroHandler(context, noopNext) : handler(context, noopNext);
       });
     }
+    return this.on("message", (context, next) => {
+      if (!context.rawStartPayload || context.rawStartPayload !== parameter) return next();
+      return macroHandler ? macroHandler(context, noopNext) : handler(context, noopNext);
+    });
   }
 });
+const { Composer } = createComposer({
+  discriminator: (ctx) => ctx.updateType,
+  types: eventTypes(),
+  methods
+});
 
 class Plugin {
   /**
@@ -197,6 +201,8 @@ class Plugin {
     Errors: {},
     /** remap generic type. {} in runtime */
     Derives: {},
+    /** remap generic type. {} in runtime */
+    Macros: {},
     /**	Composer */
     composer: new Composer(),
     /** Store plugin preRequests hooks */
@@ -273,9 +279,27 @@ class Plugin {
     }
     return this;
   }
-  /** Register handler to one or many Updates */
-  on(updateName, handler) {
-    this._.composer.on(updateName, handler);
+  macro(nameOrDefs, definition) {
+    this._.composer.macro(nameOrDefs, definition);
+    return this;
+  }
+  on(updateNameOrFilter, filterOrHandler, handler) {
+    if (typeof updateNameOrFilter === "function") {
+      this._.composer.on(updateNameOrFilter, filterOrHandler);
+      return this;
+    }
+    if (handler) {
+      this._.composer.on(
+        updateNameOrFilter,
+        filterOrHandler,
+        handler
+      );
+    } else {
+      this._.composer.on(
+        updateNameOrFilter,
+        filterOrHandler
+      );
+    }
     return this;
   }
   /** Register handler to any Updates */
@@ -765,6 +789,10 @@ class Bot {
     );
     return this;
   }
+  macro(nameOrDefs, definition) {
+    this.updates.composer.macro(nameOrDefs, definition);
+    return this;
+  }
   /**
    * This hook called when the bot is `started`.
    *
@@ -859,22 +887,26 @@ class Bot {
     }
     return this;
   }
-  // onExperimental(
-  // 	// filter: Filters,
-  // 	filter: (
-  // 		f: Filters<
-  // 			Context<typeof this> & Derives["global"],
-  // 			[{ equal: { prop: number }; addition: { some: () => 2 } }]
-  // 		>,
-  // 	) => Filters,
-  // 	handler: Handler<Context<typeof this> & Derives["global"]>,
-  // ) {}
-  /** Register handler to one or many Updates */
-  on(updateName, handler) {
-    this.updates.composer.on(
-      updateName,
-      handler
-    );
+  on(updateNameOrFilter, filterOrHandler, handler) {
+    if (typeof updateNameOrFilter === "function") {
+      this.updates.composer.on(
+        updateNameOrFilter,
+        filterOrHandler
+      );
+      return this;
+    }
+    if (handler) {
+      this.updates.composer.on(
+        updateNameOrFilter,
+        filterOrHandler,
+        handler
+      );
+    } else {
+      this.updates.composer.on(
+        updateNameOrFilter,
+        filterOrHandler
+      );
+    }
     return this;
   }
   /** Register handler to any Updates */
@@ -899,6 +931,11 @@ class Bot {
     if (plugin._.composer["~"].middlewares.length) {
       plugin._.composer.as("scoped");
       this.updates.composer.extend(plugin._.composer);
+    } else if (Object.keys(plugin._.composer["~"].macros).length) {
+      Object.assign(
+        this.updates.composer["~"].macros,
+        plugin._.composer["~"].macros
+      );
     }
     this.decorate(plugin._.decorators);
     for (const [key, value] of Object.entries(plugin._.errorsDefinitions)) {
@@ -949,8 +986,8 @@ class Bot {
    * });
    * ```
    * */
-  reaction(trigger, handler) {
-    this.updates.composer.reaction(trigger, handler);
+  reaction(trigger, handler, options) {
+    this.updates.composer.reaction(trigger, handler, options);
     return this;
   }
   /**
@@ -976,13 +1013,21 @@ class Bot {
    *     });
    * ```
    */
-  callbackQuery(trigger, handler) {
-    this.updates.composer.callbackQuery(trigger, handler);
+  callbackQuery(trigger, handler, options) {
+    this.updates.composer.callbackQuery(
+      trigger,
+      handler,
+      options
+    );
     return this;
   }
   /** Register handler to `chosen_inline_result` update */
-  chosenInlineResult(trigger, handler) {
-    this.updates.composer.chosenInlineResult(trigger, handler);
+  chosenInlineResult(trigger, handler, options) {
+    this.updates.composer.chosenInlineResult(
+      trigger,
+      handler,
+      options
+    );
     return this;
   }
   /**
@@ -1020,7 +1065,7 @@ class Bot {
    * );
    * ```
    * */
-  inlineQuery(trigger, handler, options = {}) {
+  inlineQuery(trigger, handler, options) {
     this.updates.composer.inlineQuery(
       trigger,
       handler,
@@ -1038,8 +1083,8 @@ class Bot {
    * });
    * ```
    */
-  hears(trigger, handler) {
-    this.updates.composer.hears(trigger, handler);
+  hears(trigger, handler, options) {
+    this.updates.composer.hears(trigger, handler, options);
     return this;
   }
   /**
@@ -1052,8 +1097,8 @@ class Bot {
    * });
    * ```
    */
-  command(command, handler) {
-    this.updates.composer.command(command, handler);
+  command(command, handler, options) {
+    this.updates.composer.command(command, handler, options);
     return this;
   }
   /**
@@ -1066,8 +1111,12 @@ class Bot {
    * });
    * ```
    */
-  startParameter(parameter, handler) {
-    this.updates.composer.startParameter(parameter, handler);
+  startParameter(parameter, handler, options) {
+    this.updates.composer.startParameter(
+      parameter,
+      handler,
+      options
+    );
     return this;
   }
   /** Currently not isolated!!! */
@@ -1178,13 +1227,185 @@ class Bot {
   }
 }
 
+const forwardOriginFilter = ((type) => {
+  if (type === void 0) {
+    return ((ctx) => ctx.hasForwardOrigin());
+  }
+  return ((ctx) => ctx.hasForwardOrigin() && ctx.forwardOrigin?.type === type);
+});
+const senderChatFilter = ((type) => {
+  if (type === void 0) {
+    return ((ctx) => ctx.hasSenderChat());
+  }
+  return ((ctx) => ctx.hasSenderChat() && ctx.senderChat?.type === type);
+});
+function createAttachmentFilter(type) {
+  return ((ctx) => ctx.hasAttachmentType(type));
+}
+const filters = {
+  // ── Attachment filters ──────────────────────────────────────────────
+  photo: createAttachmentFilter("photo"),
+  video: createAttachmentFilter("video"),
+  document: createAttachmentFilter("document"),
+  audio: createAttachmentFilter("audio"),
+  sticker: createAttachmentFilter("sticker"),
+  voice: createAttachmentFilter("voice"),
+  videoNote: createAttachmentFilter("video_note"),
+  animation: createAttachmentFilter("animation"),
+  contact: createAttachmentFilter("contact"),
+  location: createAttachmentFilter("location"),
+  poll: createAttachmentFilter("poll"),
+  /** Matches any message that has an attachment */
+  media: ((ctx) => ctx.hasAttachment()),
+  // ── Text & caption ──────────────────────────────────────────────────
+  /** Matches messages that have text */
+  text: ((ctx) => ctx.hasText()),
+  /** Matches messages that have a caption */
+  caption: ((ctx) => ctx.hasCaption()),
+  // ── Message content & structure ─────────────────────────────────────
+  /** Matches messages that contain a dice */
+  dice: ((ctx) => ctx.hasDice()),
+  /** Matches forwarded messages. Call without args for any origin, or pass a type to narrow precisely. */
+  forwardOrigin: forwardOriginFilter,
+  /** Matches messages that are replies */
+  reply: ((ctx) => ctx.hasReplyMessage()),
+  /** Matches messages that have text entities */
+  entities: ((ctx) => ctx.hasEntities()),
+  /** Matches messages that have caption entities */
+  captionEntities: ((ctx) => ctx.hasCaptionEntities()),
+  /** Matches messages that have a quote */
+  quote: ((ctx) => ctx.hasQuote()),
+  /** Matches messages sent via a bot */
+  viaBot: ((ctx) => ctx.hasViaBot()),
+  /** Matches messages that have link preview options */
+  linkPreview: ((ctx) => ctx.hasLinkPreviewOptions()),
+  /** Matches messages with a /start payload */
+  startPayload: ((ctx) => ctx.hasStartPayload()),
+  /** Matches messages with a raw /start payload string */
+  rawStartPayload: ((ctx) => ctx.rawStartPayload !== void 0),
+  /** Matches messages with an author signature */
+  authorSignature: ((ctx) => ctx.hasAuthorSignature()),
+  /** Matches messages with external reply info */
+  replyInfo: ((ctx) => ctx.hasReplyInfo()),
+  /** Matches contexts that have a sender (from user) */
+  hasFrom: ((ctx) => ctx.hasFrom()),
+  /** Matches messages sent on behalf of a chat. Pass a type to also narrow `senderChat.type`. */
+  senderChat: senderChatFilter,
+  /** Matches giveaway messages */
+  giveaway: ((ctx) => ctx.isGiveaway()),
+  /** Matches messages with paid media */
+  paidMedia: ((ctx) => ctx.paidMedia !== void 0),
+  // ── Raw property narrowing ──────────────────────────────────────────
+  /** Matches messages with a game */
+  game: ((ctx) => ctx.game !== void 0),
+  /** Matches messages with a story */
+  story: ((ctx) => ctx.story !== void 0),
+  /** Matches messages with an effect ID */
+  effectId: ((ctx) => ctx.effectId !== void 0),
+  /** Matches messages that belong to a media group */
+  mediaGroup: ((ctx) => ctx.mediaGroupId !== void 0),
+  /** Matches messages with a venue */
+  venue: ((ctx) => ctx.venue !== void 0),
+  // ── Sender/chat property filters (boolean, no narrowing) ────────────
+  /** Matches messages from bot accounts */
+  isBot: (ctx) => ctx.from?.isBot() === true,
+  /** Matches messages from premium users */
+  isPremium: (ctx) => ctx.from?.isPremium() === true,
+  /** Matches messages in forum (topic) chats */
+  isForum: (ctx) => ctx.isForum === true,
+  // ── Message state filters ───────────────────────────────────────────
+  /** Matches service messages */
+  service: (ctx) => ctx.isServiceMessage?.() ?? false,
+  /** Matches messages in topics */
+  topicMessage: (ctx) => ctx.isTopicMessage?.() ?? false,
+  /** Matches media with spoiler. Narrows `attachment` to confirm media is present. */
+  mediaSpoiler: ((ctx) => ctx.hasAttachment() && ctx.hasMediaSpoiler?.() === true),
+  /** Matches messages with protected content. No type narrowing. */
+  protectedContent: (ctx) => ctx.hasProtectedContent?.() === true,
+  /** Matches messages sent while user was offline. No type narrowing. */
+  fromOffline: (ctx) => ctx.isFromOffline?.() === true,
+  // ── Callback query specific filters ─────────────────────────────────
+  /** Matches callback queries that have an associated message */
+  hasMessage: ((ctx) => ctx.hasMessage?.()),
+  /** Matches callback queries that have data */
+  hasData: ((ctx) => ctx.hasData?.()),
+  /** Matches callback queries with an inline message ID */
+  hasInlineMessageId: ((ctx) => ctx.hasInlineMessageId?.()),
+  /** Matches callback queries with a game short name */
+  hasGameShortName: ((ctx) => ctx.hasGameShortName?.()),
+  // ── Parameterized entity filters ────────────────────────────────────
+  /** Matches messages with a specific text entity type */
+  entity(type) {
+    return ((ctx) => ctx.hasEntities(type));
+  },
+  /** Matches messages with a specific caption entity type */
+  captionEntity(type) {
+    return ((ctx) => ctx.hasCaptionEntities(type));
+  },
+  // ── Chat type shortcuts ─────────────────────────────────────────────
+  /** Matches messages from a specific chat type. Narrows both `chatType` and `chat.type`. */
+  chat(type) {
+    return ((ctx) => ctx.chatType === type);
+  },
+  /** Matches private (DM) chats. Narrows both `chatType` and `chat.type`. */
+  pm: ((ctx) => ctx.chatType === "private"),
+  /** Matches group chats. Narrows both `chatType` and `chat.type`. */
+  group: ((ctx) => ctx.chatType === "group"),
+  /** Matches supergroup chats. Narrows both `chatType` and `chat.type`. */
+  supergroup: ((ctx) => ctx.chatType === "supergroup"),
+  /** Matches channel chats. Narrows both `chatType` and `chat.type`. */
+  channel: ((ctx) => ctx.chatType === "channel"),
+  // ── Parameterized filters ───────────────────────────────────────────
+  /** Matches messages from specific user(s). No type narrowing. */
+  from(userId) {
+    const ids = Array.isArray(userId) ? userId : [userId];
+    return (ctx) => ctx.senderId !== void 0 && ids.includes(ctx.senderId);
+  },
+  /** Matches messages in specific chat(s). No type narrowing. */
+  chatId(chatId) {
+    const ids = Array.isArray(chatId) ? chatId : [chatId];
+    return (ctx) => ids.includes(ctx.chatId);
+  },
+  /** Matches messages whose text/caption matches the regex, sets `ctx.match` */
+  regex(pattern) {
+    return ((ctx) => {
+      const value = ctx.text ?? ctx.caption;
+      if (!value) return false;
+      const result = value.match(pattern);
+      if (!result) return false;
+      ctx.match = result;
+      return true;
+    });
+  },
+  // ── Composition ─────────────────────────────────────────────────────
+  /** Intersection: both filters must match */
+  and(f1, f2) {
+    return ((ctx) => f1(ctx) && f2(ctx));
+  },
+  /** Union: either filter must match */
+  or(f1, f2) {
+    return ((ctx) => f1(ctx) || f2(ctx));
+  },
+  /** Negation: inverts the filter (no type narrowing) */
+  not(f) {
+    return (ctx) => !f(ctx);
+  },
+  /** Variadic intersection: all filters must match */
+  every(...filters2) {
+    return ((ctx) => filters2.every((f) => f(ctx)));
+  },
+  /** Variadic union: any filter must match */
+  some(...filters2) {
+    return ((ctx) => filters2.some((f) => f(ctx)));
+  }
+};
+
 const SECRET_TOKEN_HEADER = "X-Telegram-Bot-Api-Secret-Token";
 const WRONG_TOKEN_ERROR = "secret token is invalid";
 const RESPONSE_OK = "ok!";
 const responseOK = () => new Response(RESPONSE_OK);
 const responseUnauthorized = () => new Response(WRONG_TOKEN_ERROR, {
   status: 401
-  // @ts-ignore
 });
 const frameworks = {
   elysia: ({ body, headers }) => ({
@@ -1278,7 +1499,11 @@ function webhookHandler(bot, framework, secretTokenOrOptions) {
       const timeoutOptions = typeof shouldWaitOptions === "object" ? shouldWaitOptions : void 0;
       const timeout = timeoutOptions?.timeout ?? 3e4;
       const onTimeout = timeoutOptions?.onTimeout ?? "throw";
-      await timeoutWebhook(bot.updates.handleUpdate(await update), timeout, onTimeout);
+      await timeoutWebhook(
+        bot.updates.handleUpdate(await update),
+        timeout,
+        onTimeout
+      );
       if (response) return response();
     }
   });
@@ -1286,4 +1511,4 @@ function webhookHandler(bot, framework, secretTokenOrOptions) {
 
 Symbol.metadata ??= Symbol("Symbol.metadata");
 
-export { Bot, Composer, ErrorKind, Plugin, TelegramError, Updates, webhookHandler };
+export { Bot, Composer, ErrorKind, Plugin, TelegramError, Updates, filters, webhookHandler };