const { OpengramContext: Context } = require('./context') const { getEntities, getText } = require('./core/helpers/utils') /** * The composer is the heart of the middleware system in Opengram. It is also the * super class of `Opengram`. * * Whenever you call `use` or `on` or some of the other * methods on your bot, you are in fact using the underlying composer instance * to register your middleware. */ class Composer { /** * Constructs a new composer based on the provided middleware. If no * middleware is given, the composer instance will simply make all context * objects pass through without touching them. * * @param {Middleware} fns The middlewares to compose as arguments */ constructor (...fns) { this.handler = Composer.compose(fns) } /** * Registers some middleware(s) that receives all updates. It is installed by * concatenating it to the end of all previously installed middleware. * * Often, this method is used to install middleware(s) that behaves like a * plugin, for example session middleware. * ```js * bot.use(session()) * ``` * * You can pass middleware separated by commas as arguments or as a chain of calls: * ```js * const { Opengram, Stage, session } = require('opengram') * const bot = require('opengram') * const stage = new Stage([...]) * bot.use(session(), stage) // As arguments * ``` * or * ```js * const { Opengram, Stage, session } = require('opengram') * const bot = require('opengram') * const stage = new Stage([...]) * bot // As chain of calls * .use(session()) * .use(stage) * ``` * * This method returns a new instance of {@link Composer}. * * @param {Middleware} fns The middleware(s) to register as arguments * @return {Composer} */ use (...fns) { this.handler = Composer.compose([this.handler, ...fns]) return this } /** * Registers some middleware(s) that will only be executed for some specific * updates, namely those matching the provided filter query. Filter queries * are a concise way to specify which updates you are interested in. * * Here are some examples of valid filter queries: * ```js * // All kinds of message updates * bot.on('message', ctx => { ... }) * * // Text messages * bot.on('text', ctx => { ... }) * * // Messages with document * bot.on('document', ctx => { ... }) * ``` * * It is possible to pass multiple filter queries in an array, i.e. * ```js * // Matches all messages that contain a video or audio * bot.on(['audio', 'video'], ctx => { ... }) * ``` * * Your middleware will be executed if _any of the provided filter queries_ * matches (logical OR). * * This method returns same as {@link Composer#use}. * * @param {UpdateType|UpdateSubtype|Array<UpdateType|UpdateSubtype>} updateTypes The update type or array of update types to use, * may also be an array or string * @param {Middleware} fns The middleware(s) to register with the given types as argument(s) * @return {Composer} */ on (updateTypes, ...fns) { return this.use(Composer.mount(updateTypes, ...fns)) } /** * Registers some middleware(s) that will only be executed when the message / channel post * contains some text (in media caption too). Is it possible to pass a regular expression to match: * ```js * // Match some text (exact match) * bot.hears('I love anime', ctx => ctx.reply('I love too')) * * // Match a regular expression * bot.hears(/\/echo (.+)/, ctx => ctx.reply(ctx.match[1])) * ``` * * > Note how `ctx.match` will contain the result of the regular expression. * > So `ctx.match[1]` refers to the part of the regex that was matched by `(.+)`, * > i.e. the text that comes after "/echo". * * You can also paste function (or array of functions) that takes the value and context as arguments and returns true * or false (or some `Truthy` result) based on them. This can be used, for example, for dynamic text matching at i18n. * **The result returned by the function will be available from** `ctx.match` * * ```js * bot.hears( * (value, ctx) => { * //... some checks ... * return ['some', 'data'] * }, * ctx => ctx.reply(`I love ${ctx.match[0]} ${ctx.match[1]}`) // Replies at all with "I love some data" * ) * ``` * * You can pass an array of triggers. Your middleware will be executed if at * least one of them matches. * * Both text and captions of the received messages will be scanned. For * example, when a photo is sent to the chat and its caption matches the * trigger, your middleware will be executed. * * If you only want to match text messages and not captions, you can do * this: * ```js * const { Composer: { hears } } = require('opengram') * // Only matches text messages for the regex * bot.on('text', hears(/\/echo (.+)/, ctx => { ... })) * ``` * * > _**Be careful, the example above may not work as expected if `channelMode` is enabled.**_ * > * > By default `text` type not match channel posts, but `channel_post` matched as `text` type and * > `ctx.message` potentially `undefined` * > when `channelMode` enabled. You can add additional chat type check for this case * * @param {Trigger|Trigger[]} triggers The text / array of * texts / regex / function to look for * @param {Middleware} fns The middleware(s) to register as argument(s) */ hears (triggers, ...fns) { return this.use(Composer.hears(triggers, ...fns)) } /** * Registers some middleware(s) that will only be executed when a certain * command is found. * ```js * // Reacts to /start commands * bot.command('start', ctx => { ... }) * // Reacts to /help commands * bot.command('help', ctx => { ... }) * ``` * * > **Note:** Commands are not matched in the middle of the text. * * ```js * bot.command('start', ctx => { ... }) * // ... does not match: * // A message saying: “some text /start some more text” * // A photo message with the caption “some text /start some more text” * ``` * * By default, commands are detected in channel posts and media captions, too. This means that * `ctx.message` for channel post or `ctx.message.text` for media is potentially `undefined`, * so you should use `ctx.channelPost` and `ctx.message.caption` accordingly * for channel posts. Alternatively, if you * want to limit your bot to finding commands only in private and group * chats, you can use * * ```js * const { Opengram, Composer: { command } } = require('opengram') * // ... * bot.on('message', command('start', ctx => ctx.reply('Only private / group messages or media with caption')))` * ``` * * or using {@link Composer.chatType}: * * ```js * const { Opengram, Composer, Composer: { command } } = require('opengram') * // ... * bot.use( * Composer.chatType( * ["private", "group", "supergroup"], * command('start', ctx => ctx.reply('Only private / group messages or media with caption')) * ) * ) * ``` * * for match all message exclude channel posts, or * * ```js * const { Opengram, Composer: { command } } = require('opengram') * // ... * bot.on('text', command('start', ctx => ctx.reply('Math commands only text, not media captions'))) * ``` * * for match only text message, not media caption * or even store a message-only version of your bot in a variable like so: * * > _**Be careful, the example above may not work as expected if `channelMode` is enabled.**_ * > * > By default `text` type not match channel posts, but `channel_post` matched as `text` type and * > `ctx.message` potentially `undefined` * > when `channelMode` enabled. You can add additional chat type check for this case * * @param {string|string[]|'start'|'settings'|'help'} commands The command or array of commands to look for * @param {Middleware} fns The middleware(s) to register as arguments */ command (commands, ...fns) { return this.use(Composer.command(commands, ...fns)) } /** * Registers some middleware(s) for callback queries, i.e. the updates that * Telegram delivers to your bot when a user clicks an inline button (that * is a button under a message). * * This method is essentially the same as calling * ```js * bot.on('callback_query', ctx => { ... }) * ``` * but it also allows you to match the query data against a given text or * regular expression. * * ```js * // Create an inline keyboard * const keyboard = Markup.inlineKeyboard([ * Markup.callbackButton('Go!', 'button-payload') * ]) * // Send a message with the keyboard * await bot.telegram.sendMessage(chat_id, 'Press a button!', keyboard.extra()) * // Listen to users pressing buttons with that specific payload * bot.action('button-payload', ctx => { ... }) * * // Listen to users pressing any button your bot ever sent * bot.on('callback_query', ctx => { ... }) * ``` * * Always remember to call * {@link Telegram#answerCbQuery} or {@link OpengramContext#answerCbQuery} * — even if you don't perform any action: {@linkplain https://core.telegram.org/bots/api#answercallbackquery} * ```js * bot.on('callback_query', async ctx => { * await ctx.answerCbQuery() * }) * ``` * * You can pass one or an array of triggers (Regexp / strings). Your middleware(s) will be executed if at * least one of them matches. * * > Note how `ctx.match` will contain the result of the regular expression. * > So `ctx.match[1]` refers to the part of the regexp that was matched by `([0-9]+)`, * > i.e. the text that comes after "button:". * > ```js * > bot.action(/button:([0-9]+)/, ctx => ctx.reply(`You choose button with number ${ctx.match[1]} in payload`)) * > const keyboard = Markup.inlineKeyboard([ * > Markup.callbackButton('Button 1', 'button:1'), * > Markup.callbackButton('Button 2', 'button:2'), * > Markup.callbackButton('Button 3', 'button:3') * > ]) * > await bot.telegram.sendMessage(chat_id, 'Press a button!', keyboard.extra()) * > ``` * * You can also paste function (or array of functions) that takes the value and context as arguments and returns true * or false (or some `Truthy` result) based on them. This can be used, for example, for dynamic text matching at i18n. * **The result returned by the function will be available from** `ctx.match` * * ```js * bot.action( * (value, ctx) => { * //... some checks ... * return ['some', 'data'] * }, * // Show cb query answer for all queries with "I love some data" * ctx => ctx.answerCbQuery(`I love ${ctx.match[0]} ${ctx.match[1]}`) * ) * ``` * * @param {Trigger|Trigger[]} triggers One or an array of * regular expressions / strings to search in the payload * @param {Middleware} fns The middleware(s) to register as arguments * @return {Composer} */ action (triggers, ...fns) { return this.use(Composer.action(triggers, ...fns)) } /** * Registers middleware for inline queries. Telegram sends an inline query * to your bot whenever a user types `@your_bot_name ...` into a text field * in Telegram. * * Your bot will then receive the entered search query and can * respond with a number of results (text, images, etc.) that the user can * pick from to send a message _via_ your bot to the respective chat. * Check [here](https://core.telegram.org/bots/inline) to read more about inline bots. * * > Note that you have to enable inline mode for you bot by contacting * > [@BotFather](https://t.me/BotFather) first. * * ```js * // Listen for users typing `@your_bot_name query` * bot.inlineQuery('query', async ctx => { * // Answer the inline query, confer https://core.telegram.org/bots/api#answerinlinequery * await ctx.answerInlineQuery( ... ) * }) * ``` * * You can pass one or an array of triggers (Regexp / strings). Your middleware(s) will be executed if at * least one of them matches. * * > Note how `ctx.match` will contain the result of the regular expression. * > So `ctx.match[1]` refers to the part of the regexp that was matched by `([0-9]+)`, * > i.e. the text that comes after "query:". * ```js * // Listen for users typing `@your_bot_name query` * bot.inlineQuery(/query:([0-9]+)/, async ctx => { * // Answer the inline query, confer https://core.telegram.org/bots/api#answerinlinequery * await ctx.answerInlineQuery([{ * type: 'article', * id: Math.random(), * title: 'Regex test', * cache_time: 1, * description: `Query Regex result: ${ctx.match[1]}`, * input_message_content: { * message_text: `Query Regex result: ${ctx.match[1]}`, * } * }]) * }) * ``` * * You can also paste function (or array of functions) that takes the value and context as arguments and returns true * or false (or some `Truthy` result) based on them. This can be used, for example, for dynamic text matching at i18n. * **The result returned by the function will be available from** `ctx.match` * * ```js * bot.inlineQuery( * (value, ctx) => { * //... some checks ... * return ['some', 'data'] * }, * // Show cb query answer for all queries with "I love some data" * ctx => ctx.answerInlineQuery([{ * type: 'article', * id: Math.random(), * title: 'Regex test', * cache_time: 1, * description: `I love ${ctx.match[0]} ${ctx.match[1]}`, * input_message_content: { * message_text: `I love ${ctx.match[0]} ${ctx.match[1]}`, * } * }]) * }) * ``` * * @param {Trigger|Trigger[]} triggers The inline query text * or array of text to match * @param {Middleware} fns The middleware(s) to register * @return {Composer} */ inlineQuery (triggers, ...fns) { return this.use(Composer.inlineQuery(triggers, ...fns)) } /** * Registers some middleware(s) for game queries, i.e. the updates that * Telegram delivers to your bot when a user clicks an inline button for the * HTML5 games platform on Telegram. * * This method is essentially the same as calling * ```js * bot.on('callback_query', ctx => { * if (ctx.callbackQuery.game_short_name) { * ... * } * }) * ``` * * @param {Middleware} fns The middleware to register as arguments * @return {Composer} */ gameQuery (...fns) { return this.use(Composer.gameQuery(...fns)) } /** * Registers middleware behind a custom filter function that operates on the * context object and decides whether to execute the middleware. * * In other words, the middleware(s) after that middleware will only be executed if the given predicate * returns `false` for the given context object. Note that the predicate * may be asynchronous, i.e. it can return a Promise of a boolean. * * This method is the same using `filter` (normal usage) with a negated * predicate. * * ```js * // Drop all message updates sent more than 6 hr in all middlewares / handlers registered after bot.drop(...) * bot.drop(ctx => { * if(!ctx.message) return false // Drop only messages * return (Date.now() / 1000) - ctx.message.date < 60 * 60 * 6 * }) * // Called only for messages with date < 6 hr after send * bot.on('message', () => ctx.reply('Good, update date less then 6 hours!')) * ``` * * @param {PredicateFn|boolean} predicate The predicate to check. Can be async, returns boolean or Promise with boolean * @return {Composer} */ drop (predicate) { return this.use(Composer.drop(predicate)) } /** * Registers middleware(s) behind a custom filter function that operates on the * context object and decides whether to execute the middleware. In * other words, the middleware will only be executed if the given predicate * returns `true` for the given context object. Otherwise, it will be * skipped and the next middleware will be executed. * * In other words, the middleware after that middleware will only be executed if the given predicate * returns `true` for the given context object. Note that the predicate * may be asynchronous, i.e. it can return a Promise of a boolean. * ```js * // Only process every second update * bot.filter(ctx => ctx.update.update_id % 2 === 0) * bot.on('message', ctx => ctx.reply('Update id of this message is divided by two without a remainder')) * ``` * * @param {PredicateFn|boolean} predicate The predicate to check. Can be async, returns boolean or Promise with boolean * @return {Composer} */ filter (predicate) { return this.use(Composer.filter(predicate)) } /** * Registers some middleware(s) that will only be executed if a certain entity is present in the update * * This method matches entity in channel post, message and media caption * * @param {EntityPredicate} predicate The predicate to check. Can be async, returns boolean or Promise with boolean * @param {Middleware} fns The middleware(s) to register * @return {Composer} */ entity (predicate, ...fns) { return this.use(Composer.entity(predicate, ...fns)) } /** * Registers some middleware(s) that will only be executed if `custom_emoji` entity is present in the update * * Shortcut to `Composer.entity('custom_emoji', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ customEmoji (...args) { return this.use(Composer.customEmoji(...args)) } /** * Registers some middleware(s) that will only be executed if `email` entity is present in the update * * Shortcut to `Composer.entity('email', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ email (...args) { return this.use(Composer.email(...args)) } /** * Registers some middleware(s) that will only be executed if `phone` entity is present in the update * * Shortcut to `Composer.entity('phone', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ phone (...args) { return this.use(Composer.phone(...args)) } /** * Registers some middleware(s) that will only be executed if `url` entity is present in the update * * Shortcut to `Composer.entity('url', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ url (...args) { return this.use(Composer.url(...args)) } /** * Registers some middleware(s) that will only be executed if `text_link` entity is present in the update * * Shortcut to `Composer.entity('text_link', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ textLink (...args) { return this.use(Composer.textLink(...args)) } /** * Registers some middleware(s) that will only be executed if `text_mention` entity is present in the update * * Shortcut to `Composer.entity('text_mention', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ textMention (...args) { return this.use(Composer.textMention(...args)) } /** * Registers some middleware(s) that will only be executed if `mention` entity is present in the update * * Shortcut to `Composer.entity('mention', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ mention (...args) { return this.use(Composer.mention(...args)) } /** * Registers some middleware(s) that will only be executed if `hashtag` entity is present in the update * * Shortcut to `Composer.entity('hashtag', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ hashtag (...args) { return this.use(Composer.hashtag(...args)) } /** * Registers some middleware(s) that will only be executed if `hashtag` entity is present in the update * * Shortcut to `Composer.entity('cashtag', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ cashtag (...args) { return this.use(Composer.cashtag(...args)) } /** * Registers some middleware(s) that will only be executed if `spoiler` entity is present in the update * * Shortcut to `Composer.entity('spoiler', ...)` * * This method matches entity in channel post, message and media caption * * @param {Middleware} args The middleware(s) to register * @return {Composer} */ spoiler (...args) { return this.use(Composer.spoiler(...args)) } /** * Registers some middleware that will only be executed when `/start` command is found. * * Shortcut to `Composer.command('start', ...)`, but with additional functionally, when you use this and * deep linking, you can get start payload from `ctx.startPayload` * * For example if user start the bot from link like this: `http://t.me/examplebot?start=1234` * * With this code, bot reply user with text of start payload: * * ```js * bot.start(ctx => ctx.reply(`Start payload: ${ctx.startPayload}`)) // Reply with "Start payload: 1234" * ``` * * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ start (...fns) { return this.command('start', Composer.tap((ctx) => { const entity = ctx.message.entities[0] ctx.startPayload = ctx.message.text.slice(entity.length + 1) }), ...fns) } /** * Registers some middleware that will only be executed when `/help` command is found. * * Shortcut to `Composer.command('help', ...)` * * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ help (...fns) { return this.command('help', ...fns) } /** * Registers some middleware that will only be executed when `/settings` command is found. * * Shortcut to `Composer.command('settings', ...)` * * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ settings (...fns) { return this.command('settings', ...fns) } /** * Returns the middleware to embed * * @return {Middleware} */ middleware () { return this.handler } /** * Generates and return middleware for reply with given arguments, has same arguments like in Opengram, * context method `reply` * * Usage example: * ```js * // Send message with text "I do not support group chats" when receive update from group chat * bot.use( * Composer.groupChat(Composer.reply('I do not support group chats')) * ) * ``` * * @see https://core.telegram.org/bots/api#sendmessage * @param {string} text Text of the message to be sent, 1-4096 characters after entities parsing * @param {ExtraSendMessage|Extra} [extra] Other parameters * @throws {TelegramError} * @return {Middleware<Promise<Message>>} */ static reply (text, extra) { return (ctx) => ctx.reply(text, extra) } /** * Generates middleware that catches all errors in the middleware(s) given to it and outputs them to the console * * @param {Middleware} fns Middlewares * @return {Middleware} */ static catchAll (...fns) { return Composer.catch((err) => { console.error() console.error((err.stack || err.toString()).replace(/^/gm, ' ')) console.error() }, ...fns) } /** * Generates middleware that catches all errors in the middleware(s) given to it and calls given error handler * * @param {Function} errorHandler Error handler which takes error and context object as arguments * @param {Middleware} fns Middleware(s) * @return {Middleware} */ static catch (errorHandler, ...fns) { const handler = Composer.compose(fns) return (ctx, next) => Promise.resolve(handler(ctx, next)) .catch((err) => errorHandler(err, ctx)) } /** * Registers some middleware that runs concurrently to the executing middleware stack. * Runs the middleware at the next event loop using * [setImmediate](https://nodejs.dev/en/learn/understanding-setimmediate) and force call `next()` * * For example, you can use that method for saving metrics and other non-priority or optional features in background * * > ❗️ If you call next in this middleware, then nothing will happen, it will be ignored * * @param {Middleware} middleware The middleware to run concurrently * @return {Middleware} */ static fork (middleware) { const handler = Composer.unwrap(middleware) return (ctx, next) => { setImmediate(handler, ctx, Composer.safePassThru()) return next(ctx) } } /** * Middleware that calls a middleware or chain of middleware and calls the `next`, whether it called `next` or not. * Allows you to execute some code and continue execution regardless of its result. * * @param {Middleware} middleware The middleware to run without access to next * @return {Middleware} */ static tap (middleware) { const handler = Composer.unwrap(middleware) return async (ctx, next) => { await Promise.resolve( handler(ctx, Composer.safePassThru()) ) return next(ctx) } } /** * Generates middleware which call next middleware * * For example, you can use it with {@link Composer.branch} or other to skip middleware (make middleware optional) * * @return {Middleware} */ static passThru () { return (ctx, next) => next(ctx) } /** * * Generates middleware which call next middleware if `next` function exists or returns empty resolved promise * * This method is similar to `Composer.passThru()`, but calls `next` if exists, otherwise returns resolved promise * * @return {Middleware} */ static safePassThru () { return (ctx, next) => typeof next === 'function' ? next(ctx) : Promise.resolve() } /** * Lazily asynchronously returns some middleware that can be generated on the fly for each context. * Pass a factory function that creates some middleware * * The factory function will be called once per context, and its result will be executed with the context object. * ```js * // The middleware returned by `createMyMiddleware` will be used only once * bot.use( * Composer.lazy(ctx => createMyMiddleware(ctx)) * ) * ``` * * You may generate this middleware in an `async` fashion. * * @param {Function} factoryFn The factory function creating the middleware * @throws {TypeError} * @return {Middleware<Promise>} */ static lazy (factoryFn) { if (typeof factoryFn !== 'function') { throw new TypeError('Argument must be a function') } return async (ctx, next) => { const middleware = await Promise.resolve(factoryFn(ctx)) return Composer.unwrap(middleware)(ctx, next) } } /** * Method that generates a middleware to output the content of the context with indented beautiful in * console using serialization * * The default for logs is `console.log`, you can pass your own log function in argument: * * ```js * const myOwnLogFn = (data) => console.log('[Logs]', data) * bot.use(Composer.log(myOwnLogFn)) * ``` * * @param {Function} logFn Custom log function * @return {Middleware} */ static log (logFn = console.log) { return Composer.fork((ctx) => logFn(JSON.stringify(ctx.update, null, 2))) } /** * * Allows you to branch between two cases for a given context object. * * This method takes a predicate function that is tested once per context * object. If it returns `true`, the first supplied middleware is executed. * If it returns `false`, the second supplied middleware is executed. Note * that the predicate may be asynchronous, i.e. it can return a Promise of a boolean. * * ```js * bot.use( * Composer.branch( * (ctx) => ctx.from.is_premium, * (ctx) => ctx.reply('This mw executed only for premium users'), * (ctx) => ctx.reply('Buy premium :(') * ) * ) * ``` * * @param {PredicateFn|boolean} predicate The predicate to check. Can be async, returns boolean or Promise with boolean * @param {Middleware} trueMiddleware The middleware for the `true` case * @param {Middleware} [falseMiddleware] The middleware for the `false` case * @return {Middleware} */ static branch (predicate, trueMiddleware, falseMiddleware) { if (typeof predicate !== 'function') { return predicate ? trueMiddleware : falseMiddleware } return Composer.lazy((ctx) => Promise.resolve(predicate(ctx)) .then((value) => value ? trueMiddleware : falseMiddleware)) } /** * Generates middleware that makes given middleware(s) optional * * Example * ```js * bot.use( * Composer.optional( * (ctx) => ctx.from.is_premium, // Check premium * // The handlers from below will be executed only if predict returns true * async (ctx, next) => { * await ctx.reply('This mw and below will be executed only for premium users') * return next() * }, * (ctx) => { * // ...other middleware.. ...code..., * }, * (ctx) => { * // ...other middleware.. ...code..., * }, * ) * ) * ``` * * @param {PredicateFn|boolean} predicate The predicate to check. Can be async, returns boolean or Promise with boolean * @param {Middleware} fns Middleware(s) * @return {Middleware} */ static optional (predicate, ...fns) { return Composer.branch(predicate, Composer.compose(fns), Composer.safePassThru()) } /** * Generates middleware behind a custom filter function that operates on the * context object and decides whether to execute the middleware. In * other words, the middleware will only be executed if the given predicate * returns `true` for the given context object. Otherwise, it will be * skipped and the next middleware will be executed. * * In other words, the middleware after that middleware will only be executed if the given predicate * returns `true` for the given context object. Note that the predicate * may be asynchronous, i.e. it can return a Promise of a boolean. * * ```js * // Only process every second update * bot.on( * 'message', * Composer.filter(ctx => ctx.update.update_id % 2 === 0) * ctx => ctx.reply('Update id of this message is divided by two without a remainder') * ) * ``` * * @param {PredicateFn|boolean} predicate The predicate to check. Can be async, returns boolean or Promise with boolean * @return {Middleware} */ static filter (predicate) { return Composer.branch(predicate, Composer.safePassThru(), () => { }) } /** * Generates middleware behind a custom filter function that operates on the * context object and decides whether to execute the middleware. * * In other words, the middleware(s) after that middleware will only be executed if the given predicate * returns `false` for the given context object. Note that the predicate * may be asynchronous, i.e. it can return a Promise of a boolean. * * This method is the same using `filter` (normal usage) with a negated * predicate. * * ```js * // Drop all message updates sent more than 6 hr in all middlewares / handlers registered after bot.drop(...) * const mw = Composer.drop(ctx => { * if(!ctx.message) return false // Drop only messages * return (Date.now() / 1000) - ctx.message.date < 60 * 60 * 6 * }) * // Called only for messages with date < 6 hr after send * bot.on('message', mw, () => ctx.reply('Good, update date less then 6 hours!')) * ``` * * @param {PredicateFn|boolean} predicate The predicate to check. Can be async, returns boolean or Promise with boolean * @return {Middleware} */ static drop (predicate) { return Composer.branch(predicate, () => { }, Composer.safePassThru()) } static dispatch (routeFn, handlers) { if (typeof routeFn === 'function') { return Composer.lazy(async (ctx) => { const route = await Promise.resolve( routeFn(ctx) ) return handlers[route] }) } else { return handlers[routeFn] } } /** * Generates middleware that execute given middleware(s) only for some specific * updates, namely those matching the provided filter query. Filter queries * are a concise way to specify which updates you are interested in. * * Here are some examples of valid filter queries: * ```js * // All kinds of message updates * bot.use( * Composer.mount('message', ctx => { ... }) * ) * * // Text messages * bot.use( * Composer.mount('text', ctx => { ... }) * ) * * // Messages with document * bot.use( * Composer.mount('document', ctx => { ... }) * ) * ``` * * It is possible to pass multiple filter queries in an array, i.e. * ```js * // Matches all messages that contain a video or audio * bot.use( * Composer.mount(['audio', 'video'], ctx => { ... }) * ) * ``` * * Your middleware will be executed if _any of the provided filter queries_ * matches (logical OR). * * @param {UpdateType|UpdateSubtype|Array<UpdateType|UpdateSubtype>} updateType The update type or array of update types to use, * may also be an array or string * @param {Middleware} fns The middleware(s) to register with the given types as argument(s) * @return {Middleware} */ static mount (updateType, ...fns) { const updateTypes = normalizeTextArguments(updateType) const predicate = (ctx) => { return updateTypes.includes(ctx.updateType) || updateTypes .some( (type) => ctx.updateSubTypes.includes(type) ) } return Composer.optional(predicate, ...fns) } /** * Generates middleware that execute given middlewares if a certain entity is present in the update * * This method matches entity in channel post, message and media caption * * @param {EntityPredicate} predicate The predicate to check. Entity name or predicate function. * If function provided, it can be sync only and returns boolean * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ static entity (predicate, ...fns) { if (typeof predicate !== 'function') { const entityTypes = normalizeTextArguments(predicate) return Composer.entity((entity) => entityTypes.includes(entity.type), ...fns) } return Composer.optional((ctx) => { const message = ctx.message || ctx.channelPost const entities = getEntities(message) const text = getText(message) return entities && entities.some((entity) => predicate(entity, text.substring(entity.offset, entity.offset + entity.length), ctx) ) }, ...fns) } static entityText (entityType, predicate, ...fns) { if (fns.length === 0) { return Array.isArray(predicate) ? Composer.entity(entityType, ...predicate) : Composer.entity(entityType, predicate) } const triggers = normalizeTriggers(predicate) return Composer.entity(({ type }, value, ctx) => { if (type !== entityType) { return false } for (const trigger of triggers) { ctx.match = trigger(value, ctx) if (ctx.match) { return true } } }, ...fns) } static customEmoji (customEmoji, ...fns) { return Composer.entityText('custom_emoji', customEmoji, ...fns) } static email (email, ...fns) { return Composer.entityText('email', email, ...fns) } static phone (number, ...fns) { return Composer.entityText('phone_number', number, ...fns) } static url (url, ...fns) { return Composer.entityText('url', url, ...fns) } static textLink (link, ...fns) { return Composer.entityText('text_link', link, ...fns) } static textMention (mention, ...fns) { return Composer.entityText('text_mention', mention, ...fns) } static mention (mention, ...fns) { return Composer.entityText('mention', normalizeTextArguments(mention, '@'), ...fns) } static hashtag (hashtag, ...fns) { return Composer.entityText('hashtag', normalizeTextArguments(hashtag, '#'), ...fns) } static cashtag (cashtag, ...fns) { return Composer.entityText('cashtag', normalizeTextArguments(cashtag, '$'), ...fns) } static spoiler (text, ...fns) { return Composer.entityText('spoiler', text, ...fns) } /** * Generates middleware that execute given middlewares when some given trigger(s) returns true * * Triggers are executed for channel post / message text / callback query / inline query * * Example: * ```js * Composer.match (/[a-z]/, ...fns) * * Composer.match ([/[a-z]/, /[0-9]/], ...fns) * * Composer.match ((value, context) => { * // ...checks... * } , ...fns) * * Composer.match ( * (value, context) => { * // ...checks... * }, * (value, context) => { * // ...checks... * }, * ...fns * ) * ``` * * @param {Trigger|Trigger[]} triggers The text / array of * texts / regex / function to look for * @param {Middleware} fns The middleware(s) to register as argument(s) */ static match (triggers, ...fns) { return Composer.optional((ctx) => { const text = getText(ctx.message) || getText(ctx.channelPost) || getText(ctx.callbackQuery) || (ctx.inlineQuery && ctx.inlineQuery.query) for (const trigger of triggers) { ctx.match = trigger(text, ctx) if (ctx.match) { return true } } }, ...fns) } /** * Generates middleware that execute given middlewares when the message / channel post * contains some text (in media caption too). Is it possible to pass a regular expression to match: * ```js * // Match some text (exact match) * bot.use( * Composer.hears('I love anime', ctx => ctx.reply('I love too')) * ) * * // Match a regular expression * bot.use( * Composer.hears(/\/echo (.+)/, ctx => ctx.reply(ctx.match[1])) * ) * ``` * * > Note how `ctx.match` will contain the result of the regular expression. * > So `ctx.match[1]` refers to the part of the regex that was matched by `(.+)`, * > i.e. the text that comes after "/echo". * * You can also paste function (or array of functions) that takes the value and context as arguments and returns true * or false (or some `Truthy` result) based on them. This can be used, for example, for dynamic text matching at i18n. * **The result returned by the function will be available from** `ctx.match` * * ```js * bot.use( * Composer.hears( * (value, ctx) => { * //... some checks ... * return ['some', 'data'] * }, * ctx => ctx.reply(`I love ${ctx.match[0]} ${ctx.match[1]}`) // Replies at all with "I love some data" * ) * ) * ``` * * You can pass an array of triggers. Your middleware will be executed if at * least one of them matches. * * Both text and captions of the received messages will be scanned. For * example, when a photo is sent to the chat and its caption matches the * trigger, your middleware will be executed. * * If you only want to match text messages and not captions, you can do * this: * ```js * // Only matches text messages for the regex * bot.on('text', Composer.hears(/\/echo (.+)/, ctx => { ... })) * ``` * * > _**Be careful, the example above may not work as expected if `channelMode` is enabled.**_ * > * > By default `text` type not match channel posts, but `channel_post` matched as `text` type and * > `ctx.message` potentially `undefined` * > when `channelMode` enabled. You can add additional chat type check for this case * * @param {Trigger|Trigger[]} triggers The text / array of * texts / regex / function to look for * @param {Middleware} fns The middleware(s) to register as argument(s) */ static hears (triggers, ...fns) { return Composer.mount('text', Composer.match(normalizeTriggers(triggers), ...fns)) } /** * Generates middleware that execute given middlewares will only be executed if a certain command is found. * * ```js * // Reacts to /start commands * bot.use( * Composer.command('start', ctx => { ... }) * ) * // Reacts to /help commands * bot.use( * Composer.command('help', ctx => { ... }) * ) * ``` * * > **Note:** Commands are not matched in the middle of the text. * * ```js * bot.use( * Composer.command('start', ctx => { ... }) * ) * // ... does not match: * // A message saying: “some text /start some more text” * // A photo message with the caption “some text /start some more text” * ``` * * By default, commands are detected in channel posts and media captions, too. This means that * `ctx.message` for channel post or `ctx.message.text` for media is potentially `undefined`, * so you should use `ctx.channelPost` and `ctx.message.caption` accordingly * for channel posts. Alternatively, if you * want to limit your bot to finding commands only in private and group * chats, you can use * * ```js * const { Opengram, Composer: { command } } = require('opengram') * // ... * bot.on('message', command('start', ctx => ctx.reply('Only private / group messages or media with caption')))` * ``` * * or using {@link Composer.chatType}: * * ```js * const { Opengram, Composer, Composer: { command } } = require('opengram') * // ... * bot.use( * Composer.chatType( * ["private", "group", "supergroup"], * command('start', ctx => ctx.reply('Only private / group messages or media with caption')) * ) * ) * ``` * * for match all message exclude channel posts, or * * ```js * const { Opengram, Composer: { command } } = require('opengram') * // ... * bot.on('text', command('start', ctx => ctx.reply('Math commands only text, not media captions'))) * ``` * * for match only text message, not media caption * or even store a message-only version of your bot in a variable like so: * * > _**Be careful, the example above may not work as expected if `channelMode` is enabled.**_ * > * > By default `text` type not match channel posts, but `channel_post` matched as `text` type and * > `ctx.message` potentially `undefined` * > when `channelMode` enabled. You can add additional chat type check for this case * * @param {string|string[]|'start'|'settings'|'help'} command The command or array of commands to look for * @param {Middleware} fns The middleware(s) to register as arguments */ static command (command, ...fns) { if (fns.length === 0) { return Composer.entity('bot_command', command) } const commands = normalizeTextArguments(command, '/') return Composer.mount(['message', 'channel_post'], Composer.lazy((ctx) => { const groupCommands = ctx.me && (ctx.chat.type === 'group' || ctx.chat.type === 'supergroup') ? commands.map((command) => `${command}@${ctx.me}`) : [] return Composer.entity( (entity, value) => ( entity.offset === 0 && entity.type === 'bot_command' && (commands.includes(value) || groupCommands.includes(value)) ), ...fns) })) } /** * Generates middleware that execute given middlewares will only be executed for certain callback queries, i.e. * the updates that * * Telegram delivers to your bot when a user clicks an inline button (that * is a button under a message). * * This method is essentially the same as calling * ```js * bot.on('callback_query', ctx => { ... }) * ``` * but it also allows you to match the query data against a given text or * regular expression. * * ```js * // Create an inline keyboard * const keyboard = Markup.inlineKeyboard([ * Markup.callbackButton('Go!', 'button-payload') * ]) * // Send a message with the keyboard * await bot.telegram.sendMessage(chat_id, 'Press a button!', keyboard.extra()) * // Listen to users pressing buttons with that specific payload * bot.use( * Composer.action('button-payload', ctx => { ... }) * ) * * // Listen to users pressing any button your bot ever sent * bot.on('callback_query', ctx => { ... }) * ``` * * Always remember to call * {@link Telegram#answerCbQuery} or {@link OpengramContext#answerCbQuery} * — even if you don't perform any action: {@linkplain https://core.telegram.org/bots/api#answercallbackquery} * ```js * bot.on('callback_query', async ctx => { * await ctx.answerCbQuery() * }) * ``` * * You can pass one or an array of triggers (Regexp / strings). Your middleware(s) will be executed if at * least one of them matches. * * > Note how `ctx.match` will contain the result of the regular expression. * > So `ctx.match[1]` refers to the part of the regexp that was matched by `([0-9]+)`, * > i.e. the text that comes after "button:". * > ```js * > const mw = Composer.action(/button:([0-9]+)/, ctx => ctx.reply(`You choose button with number ${ctx.match[1]} in payload`)) * > const keyboard = Markup.inlineKeyboard([ * > Markup.callbackButton('Button 1', 'button:1'), * > Markup.callbackButton('Button 2', 'button:2'), * > Markup.callbackButton('Button 3', 'button:3') * > ]) * > * > bot.use(mw) * > await bot.telegram.sendMessage(chat_id, 'Press a button!', keyboard.extra()) * > ``` * * You can also paste function (or array of functions) that takes the value and context as arguments and returns true * or false (or some `Truthy` result) based on them. This can be used, for example, for dynamic text matching at i18n. * **The result returned by the function will be available from** `ctx.match` * * ```js * bot.use( * Composer.action( * (value, ctx) => { * //... some checks ... * return ['some', 'data'] * }, * // Show cb query answer for all queries with "I love some data" * ctx => ctx.answerCbQuery(`I love ${ctx.match[0]} ${ctx.match[1]}`) * ) * ) * ``` * * @param {Trigger|Trigger[]} triggers One or an array of * regular expressions / strings to search in the payload * @param {Middleware} fns The middleware(s) to register as arguments * @return {Middleware} */ static action (triggers, ...fns) { return Composer.mount('callback_query', Composer.match(normalizeTriggers(triggers), ...fns)) } /** * Generates middleware that execute given middleware(s) will only be executed for certain inline queries. * Telegram sends an inline query to your bot whenever a user types `@your_bot_name ...` into a text field * in Telegram. * * Your bot will then receive the entered search query and can * respond with a number of results (text, images, etc.) that the user can * pick from to send a message _via_ your bot to the respective chat. * Check [here](https://core.telegram.org/bots/inline) to read more about inline bots. * * > Note that you have to enable inline mode for you bot by contacting * > [@BotFather](https://t.me/BotFather) first. * * ```js * // Listen for users typing `@your_bot_name query` * bot.use( * Composer.inlineQuery('query', async ctx => { * // Answer the inline query, confer https://core.telegram.org/bots/api#answerinlinequery * await ctx.answerInlineQuery( ... ) * }) * ) * ``` * * You can pass one or an array of triggers (Regexp / strings). Your middleware(s) will be executed if at * least one of them matches. * * > Note how `ctx.match` will contain the result of the regular expression. * > So `ctx.match[1]` refers to the part of the regexp that was matched by `([0-9]+)`, * > i.e. the text that comes after "query:". * ```js * // Listen for users typing `@your_bot_name query` * bot.use( * Composer.inlineQuery(/query:([0-9]+)/, async ctx => { * // Answer the inline query, confer https://core.telegram.org/bots/api#answerinlinequery * await ctx.answerInlineQuery([{ * type: 'article', * id: Math.random(), * title: 'Regex test', * cache_time: 1, * description: `Query Regex result: ${ctx.match[1]}`, * input_message_content: { * message_text: `Query Regex result: ${ctx.match[1]}`, * } * }]) * }) * ) * ``` * * You can also paste function (or array of functions) that takes the value and context as arguments and returns true * or false (or some `Truthy` result) based on them. This can be used, for example, for dynamic text matching at i18n. * **The result returned by the function will be available from** `ctx.match` * * ```js * bot.inlineQuery( * (value, ctx) => { * //... some checks ... * return ['some', 'data'] * }, * // Show cb query answer for all queries with "I love some data" * ctx => ctx.answerInlineQuery([{ * type: 'article', * id: Math.random(), * title: 'Regex test', * cache_time: 1, * description: `I love ${ctx.match[0]} ${ctx.match[1]}`, * input_message_content: { * message_text: `I love ${ctx.match[0]} ${ctx.match[1]}`, * } * }]) * }) * ``` * * @param {Trigger|Trigger[]} triggers The inline query text * or array of text to match * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ static inlineQuery (triggers, ...fns) { return Composer.mount('inline_query', Composer.match(normalizeTriggers(triggers), ...fns)) } /** * Generates and returns a middleware that runs the given middleware(s) only for when array of given id's contains * user id or predicate function returns true for given context * * Access-control list - allows you to create guards for middlewares * * Usage example: * ```js * bot.use( * Composer.admin( * 1234567890, * Composer.reply('Some middleware for admin of bot - 1234567890') * ) * ) * * bot.use( * Composer.admin( * [1234567890, 09876543], * Composer.reply('Some middleware for admins of bot - 1234567890 and 09876543') * ) * ) * * * function checkIsAdmin (ctx) { * // ... * return true * } * * bot.use( * Composer.admin( * ctx => checkIsAdmin(ctx), * Composer.reply('Some middleware for admins of bot') * ) * ) * ``` * * @param {PredicateFn|number|number[]} userId The predicate to check or user id / array of user id's * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ static acl (userId, ...fns) { if (typeof userId === 'function') { return Composer.optional(userId, ...fns) } const allowed = Array.isArray(userId) ? userId : [userId] return Composer.optional((ctx) => !ctx.from || allowed.includes(ctx.from.id), ...fns) } /** * Generates and returns a middleware that runs the given middleware(s) only for updates user has one of given * member statuses of chat * * Usage example: * ```js * bot.use( * Composer.memberStatus( * ["creator", "administrator"], * Composer.reply('I work only for chat creator and administrator ') * ) * ) * ``` * * @param {ChatMemberStatus[]|ChatMemberStatus} status Member status of array of statuses * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ static memberStatus (status, ...fns) { const statuses = Array.isArray(status) ? status : [status] return Composer.optional((ctx) => ctx.message && ctx.getChatMember(ctx.message.from.id) .then(member => member && statuses.includes(member.status)) , ...fns) } /** * Generates and returns a middleware that runs the given middleware(s) only for updates if member * status = `creator` or 'administrator' * * Usage example: * ```js * bot.use( * Composer.admin( * Composer.reply('I work only when called by chat creator and administrator ') * ) * ) * ``` * * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ static admin (...fns) { return Composer.memberStatus(['administrator', 'creator'], ...fns) } /** * Generates and returns a middleware that runs the given middleware(s) only for updates if member status = `creator` * * Usage example: * ```js * bot.use( * Composer.creator( * Composer.reply('I work only when called by chat creator') * ) * ) * ``` * * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ static creator (...fns) { return Composer.memberStatus('creator', ...fns) } /** * Registers some middleware for certain chat types only. * * For example, you can use this method to only receive * updates from private chats. The four chat types are `channel`, `supergroup`, `group`, and `private`. * This is especially useful when combined with other filtering logic. * * For example, this is how can you respond to /start commands only from private chats: * * Usage example: * ```js * const privateZone = new Composer() * privateZone.command("start", ctx => { ... }) * * bot.use( * Composer.chatType('private', privateZone) * ) * * bot.use( * Composer.chatType('supergroup', Composer.reply('I work only in supergroups chats')) * ) * * bot.use( * Composer.chatType(['supergroup', 'group'], Composer.reply('I work only in supergroup + group chats')) * ) * ``` * * ```js * const onlyGroup = new Composer() * * onlyGroup.hears(...) * onlyGroup.command(...) * // ... * bot.use( * Composer.chatType('group', onlyGroup) * ) * ``` * * @param {ChatType[]|ChatType} type Chat type or array of shat types * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ static chatType (type, ...fns) { const types = Array.isArray(type) ? type : [type] return Composer.optional((ctx) => { const chat = ctx.chat return chat !== undefined && types.includes(chat.type) }, ...fns) } /** * Generates and returns a middleware that runs the given middleware only for updates from "private" (DM) * * Usage example: * ```js * // Send message with text "I do not support group chats" when receive update from group chat * bot.use( * Composer.privateChat(Composer.reply('I work only in group chats')) * ) * ``` * * Isolate private commands: * ```js * const private = new Composer() * * private.hears(...) * private.command(...) * * bot.use( * Composer.privateChat(private) * ) * ``` * * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ static privateChat (...fns) { return Composer.chatType('private', ...fns) } /** * Creates and returns a middleware that runs the given middleware only for updates from "group" and "supergroup". * * Usage example: * ```js * // Send message with text "I do not support group chats" when receive update from group chat * bot.use( * Composer.groupChat(Composer.reply('I do not support group chats')) * ) * ``` * * Isolate group commands: * ```js * const group = new Composer() * * group.hears(...) * group.command(...) * * bot.use( * Composer.groupChat(group) * ) * ``` * * @param {Middleware} fns The middleware(s) to register * @return {Middleware} */ static groupChat (...fns) { return Composer.chatType(['group', 'supergroup'], ...fns) } static gameQuery (...fns) { return Composer.mount( 'callback_query', Composer.optional((ctx) => !!ctx.callbackQuery.game_short_name, ...fns) ) } /** * Method used for unwrapping middleware, when middleware has method with name `middleware` (middleware factory) * {@link Composer.unwrap} calls him and return result * * This method used in some other {@link Composer} methods, like {@link Composer.compose}, {@link Composer.lazy} and * other * * @param {Middleware} handler The middleware for unwrap * @throws {Error} * @return {Middleware} */ static unwrap (handler) { if (!handler) { throw new Error('Handler is undefined') } return typeof handler.middleware === 'function' ? handler.middleware() : handler } /** * Used for compose array of middlewares * * @param {Middleware[]} middlewares The middlewares for compose * @throws {Error|TypeError} * @return {Middleware} */ static compose (middlewares) { if (!Array.isArray(middlewares)) { throw new TypeError('Middlewares must be an array') } if (middlewares.length === 0) { return Composer.safePassThru() } if (middlewares.length === 1) { return Composer.unwrap(middlewares[0]) } /** * @param {OpengramContext} ctx Context Object * @param {Function} next Next middleware */ function run (ctx, next) { let index = -1 return execute(0, ctx) /** * @param {number} i Middleware index * @param {OpengramContext} context Next middleware */ async function execute (i, context) { if (!(context instanceof Context)) { throw new Error('next(ctx) called with invalid context') } if (i <= index) { throw new Error('next() called multiple times') } index = i const handler = middlewares[i] ? Composer.unwrap(middlewares[i]) : next if (!handler) { return } await handler(context, async (ctx = context) => { await execute(i + 1, ctx) }) } } return run } } /** * Converts single triggers to array of triggers and regex / strings to predicate functions * * @private * @param {Trigger|Trigger[]} triggers The text / array of * texts / regex / function to look for * @throws {TypeError} * @return {TriggerPredicateFn[]} */ function normalizeTriggers (triggers) { if (!Array.isArray(triggers)) { triggers = [triggers] } return triggers.map((trigger) => { if (!trigger) { throw new TypeError('Invalid trigger') } if (typeof trigger === 'function') { return trigger } if (trigger instanceof RegExp) { return (value) => { trigger.lastIndex = 0 return trigger.exec(value || '') } } return (value) => trigger === value ? value : null }) } /** * Converts given argument to array if not array, filter empty arguments. * If prefix given, adds prefix if not exists * * ```js * normalizeTextArguments('name') // Returns ['name'] * normalizeTextArguments(['name', 'name1']) // Returns ['name', 'name1'] * normalizeTextArguments(['@name', 'name1'], '@') // Returns ['@name', '@name1'] * ``` * * @private * @param {string|string[]} argument Arguments to normalize * @param {string} [prefix] Prefix * @return {string[]} */ function normalizeTextArguments (argument, prefix) { const args = Array.isArray(argument) ? argument : [argument] return args .filter(Boolean) .map((arg) => prefix && typeof arg === 'string' && !arg.startsWith(prefix) ? `${prefix}${arg}` : arg) } module.exports = Composer
Opengram
Modules
Classes
Namespaces
Global
