Telegram-bot-utils NPM

Telegram Bot Utils

A package helps you deploy your application easily on bot.

This document is still at very early stage.

API reference still on the way 🚧

Example Usage

npm i telegram_bot_utils

Simply use with Node.js Telegram Bot API.

Start your bot

const TelegramBot = require('node-telegram-bot-api')
const botMgr = require('telegram_bot_utils').botMgr

const token = process.env.BOT_TOKEN || 'token'

const bot = new TelegramBot(token, { polling: true })
const botUtils = botMgr.add('bot_username')

bot.on('message', (msg) => {
    mamoru.onMessage(msg)
})

Command

Add a command

botUtils.command.add(
    'echo',
    (args, msg, userData) => {
        bot.sendMessage(
            msg.chat.id,
            args
                .map((v, i) => {
                    return `argument[${i}]: ${v}\n`
                })
                .join('')
        )
    },
    {
        filter: 'public',
    }
)

Arguments check

botUtils.command.add(
    'arg_test',
    (args, msg, userData) => {
        bot.sendMessage(msg.chat.id, 'passed')
    },
    {
        filter: 'public',
        argument_check: [
            { type: 'boolean' },
            {
                type: 'integer',
                default_value: 4,
                range: 'function',
                range_function: (arg) => {
                    return arg <= 5
                },
            },
        ],
        argument_error_function: (_msg, err) => {
            if (err instanceof TypeError) {
                const e = 'name: ' + err.name
                bot.sendMessage(
                    _msg.chat.id,
                    `error: ${e}\n\`${err.message}\``,
                    {
                        parse_mode: 'MarkdownV2',
                    }
                )
            } else if (err instanceof RangeError) {
                const e = 'name: ' + err.name
                bot.sendMessage(
                    _msg.chat.id,
                    `error: ${e}\n\`${err.message}\``,
                    {
                        parse_mode: 'MarkdownV2',
                    }
                )
            }
        },
    }
)

Application

For this package, application are using for user data storage, execution priority checking and make your functions more clear. Almost everything binds with application: commands, input listeners, tasks and handle of callback querys.

Add applications

botUtils.application.add('calculator')
botUtils.application.add('groupUtils', {
    priority: -1,
    is_group_need_bind: true,
})

Bind app with chat

// bind app 'aria2Helper' with chat id -123456
botUtils.application.get('aria2Helper').chatBind.add(-123456, {
    passive: true,
})

// unbind app 'aria2Helper' with chat id -123456
botUtils.application.get('aria2Helper').chatBind.delete(-123456)

Bind on command

botUtils.addCommand(
    'bind',
    (args, msg, userData) => {
        botUtils.setApplicationBind(args[1], msg.chat.id)
        bot.sendMessage(msg.chat.id, `binded app: ${args[1]}`)
    },
    {
        application_name: '_global',
        filter: 'public',
        argument_check: [
            {
                type: 'string',
                range: 'function',
                range_function: (name) => {
                    return (
                        botUtils
                            .listApplications()
                            .map((app) => {
                                return app.name
                            })
                            .indexOf(name) !== -1
                    )
                },
            },
        ],
        argument_error_function: (_msg, err) => {
            if (err instanceof RangeError) {
                const e = 'name: ' + err.name
                bot.sendMessage(
                    _msg.chat.id,
                    `error: ${e}\n\`${err.message}\``,
                    {
                        parse_mode: 'MarkdownV2',
                    }
                )
            }
        },
    }
)

InputListener

Can be useful on force input needed case ( setting to block command trigger or using apps' priority to block other input listener

botUtils.addCommand(
    'echo_listener',
    (args, msg, appData) => {
        botUtils.addInputListener(
            msg.chat,
            msg.from,
            (msg, userData) => {
                const text = msg.text
                if (text === 'stop!') {
                    bot.sendMessage(msg.chat.id, 'okay')
                    return true
                } else {
                    bot.sendMessage(msg.chat.id, text)
                    return false
                }
            },
            {
                available_count: Infinity,
                pass_to_command: true,
                init_function: (chat, user, userData) => {
                    bot.sendMessage(chat.id, `let's talk!`)
                },
            }
        )
    },
    {
        filter: 'public',
    }
)

Task

Just use this as a normal timer or making some scheduled and repeat tasks.

botUtils.defTask(
    'msgPerMin',
    (rec, recMan, userData) => {
        bot.sendMessage(
            rec.chat_id,
            `task: ${Date.now()} at ${rec.executed_counts}`
        )
    },
    60, // seconds
    Infinity,
    {
        timeout: 20, // also seconds
        import_policy: 'next-restart',
        timeout_action: (rec, recMan, userData) => {
            bot.sendMessage(rec.chat_id, `sorry for late`)
            // recMan.kill()
        },
    }
)

botUtils.addCommand(
    'msgPerMin',
    (args, msg, appData) => {
        bot.sendMessage(msg.chat.id, 'task started.')
        botUtils.startTask('msgPerMin', msg.chat.id, msg.from.id, true)
    },
    {
        filter: 'public',
    }
)

Group Utilities

A simple verify bot for your group:

botUtils.addApplication('groupVerify', {
    priority: -1,
    final_app: true,
    is_group_need_bind: true,
    link_chat_free: false,
    link_user_free: false,
})
const genRandom = require('telegram_bot_utils/dist/utils').genRandom

bot.on('message', (msg) => {
    botUtils.groupUtils().joinListener(msg, () => {
        botUtils.addInputListener(
            msg.chat,
            msg.from,
            (_msg, userData) => {
                const code = userData.get(['code'])
                if (code === _msg.text) {
                    bot.sendMessage(_msg.chat.id, 'welcome new member!', {})
                    userData.set(null)
                    return true
                }
                return false
            },
            {
                application_name: 'groupVerify',
                available_count: 3,
                pass_to_other_listener: false,
                pass_to_command: false,
                init_function: (chat, user, userData) => {
                    const code = genRandom(6)
                    userData.set(code, ['code'])
                    bot.sendMessage(
                        chat.id,
                        `verify code for [${user.first_name}](tg://user?id=${user.id})\n\`${code}\``,
                        { parse_mode: 'MarkdownV2' }
                    )
                },
                final_function: (chat, user, userData) => {
                    userData.set(null)
                    bot.kickChatMember(chat.id, user.id)
                    bot.sendMessage(
                        chat.id,
                        `kicked out ${user.first_name} of group`
                    )
                },
            }
        )
    })
    botUtils.groupUtils().leftListener(msg, () => {
        console.log(`someone left`)
    })
})