npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

tgfancy

v0.13.0

Published

A Fancy, Higher-Level Wrapper for Telegram Bot API

Downloads

290

Readme

tgfancy

A Fancy, Higher-Level Wrapper for Telegram Bot API

Built on top of node-telegram-bot-api.

:construction: Work In Progress :construction:

Version Supported Node.js Versions Build Status Coverage Status Dependency Status

installation:

$ npm install tgfancy --save

sample usage:

const Tgfancy = require("tgfancy");
const bot = new Tgfancy(token, {
    // all options to 'tgfancy' MUST be placed under the
    // 'tgfancy' key, as shown below
    tgfancy: {
        option: "value",
    },
});

bot.sendMessage(chatId, "text message");

introduction:

tgfancy is basically node-telegram-bot-api on steroids. Therefore, you MUST know how to work with node-telegram-bot-api before using this wrapper. tgfancy is a drop-in replacement!

tgfancy provides ALL the methods exposed by TelegramBot from node-telegram-bot-api. This means that all the methods from TelegramBot are available on Tgfancy. This also includes the constructor.

fanciness:

Here comes the fanciness

tgfancy adds the following fanciness:

Have a look at the API Reference.

feature options:

Most of the features are enabled by default. Such a feature (enabled by default) is similar to doing something like:

const bot = new Tgfancy(token, {
    tgfancy: {
        feature: true,  // 'true' to enable!
    },
});

Such a feature can be disabled like so:

const bot = new Tgfancy(token, {
    tgfancy: {
        feature: false, // 'false' to disable!
    },
});

If a feature allows more options, you may pass an object, instead of true, like:

const bot = new Tgfancy(token, {
    tgfancy: {
        feature: {          // feature will be enabled!
            key: "value",   // feature option
        },
    },
});

See example at example/feature-toggled.js.


Ordered sending:

Using an internal queue, we can ensure messages are sent, to a specific chat, in order without having to implement the wait-for-response-to-send-next-message logic.

Feature option: orderedSending (see above)

For example,

bot.sendMessage(chatId, "first message");
bot.sendMessage(chatId, "second message");

With tgfancy, you are guaranteed that "first message" will be sent before "second message".

Fancied functions: [ "sendAudio", "sendDocument", "sendGame", "sendInvoice", "sendLocation", "sendMessage", "sendPhoto", "sendSticker", "sendVenue", "sendVideo", "sendVideoNote", "sendVoice", ]

An earlier discussion on this feature can be found here. See example at example/queued-up.js.


Text paging:

The Tgfancy#sendMessage(chatId, message) automatically pages messages, that is, if message is longer than the maximum limit of 4096 characters, the message is split into multiple parts. These parts are sent serially, one after the other.

The page number, for example [01/10], is prefixed to the text.

Feature option: textPaging (see above)

For example,

// 'veryLongText' is a message that contains more than 4096 characters
// Usually, trying to send this message would result in the API returning
// an error.
bot.sendMessage(chatId, veryLongText)
    .then(function(messages) {
        // 'messages' is an Array containing Message objects from
        // the Telegram API, for each of the parts
        console.log("message has been sent in multiple pages");
    }).catch(function(error) {
        console.error(error);
    });

Note: We do not support sending messages that'd result into more than 99 parts.

See example at example/paging-text.js.


chat ID resolution:

Usernames are automatically resolved to the target's corresponding unique identifier. By default, this resolution uses the PWRTelegram API.

Feature option: chatIdResolution (see above)

For example,

bot.sendMessage("@gochomugo", "Message sent using username");

However, it is possible to define a custom function used to perform these resolutions. The function must have the signature, resolve(token, chatId, callback). The callback must have the signature callback(error, target), where target is an object representing the target entity.

const bot = new Tgfancy(token, {
    tgfancy: {
        chatIdResolution: {
            resolve(token, chatId, callback) {
                // perform the resolution
                // ... snip ...
                return callback(null, user);
            },
        },
    },
});

Fancied functions: [ "deleteChatPhoto", "deleteChatStickerSet", "deleteMessage", "exportChatInviteLink", "forwardMessage", "getChat", "getChatAdministrators", "getChatMember", "getChatMembersCount", "getUserProfilePhotos", "kickChatMember", "leaveChat", "pinChatMessage", "promoteChatMember", "restrictChatMember", "sendAudio", "sendChatAction", "sendContact", "sendDocument", "sendGame", "sendInvoice", "sendLocation", "sendMediaGroup", "sendMessage", "sendPhoto", "sendSticker", "sendVenue", "sendVideo", "sendVideoNote", "sendVoice", "setChatDescription", "setChatPhoto", "setChatStickerSet", "setChatTitle", "setGameScore", "unbanChatMember", "unpinChatMessage", ]

See example at example/resolve-chatid.js.

Note: The Chat ID is resolved before the request is queued. Consider this, if order of messages gets messed up, when using this resolution.

If you want to manually resolve a chat ID, take a look at Tgfancy#resolveChatId. For example,

bot.resolveChatId(chatId)
    .then(function(result) {
        console.log(result);
    });

Rate-Limiting:

Any request that encounters a 429 error i.e. rate-limiting error will be retried after some time (as advised by the Telegram API or 1 minute by default). The request will be retried for a number of times, until it succeeds or the maximum number of retries has been reached

Feature option: ratelimiting (see above)

For example,

const bot = new Tgfancy(token, {
    tgfancy: {
        // options for this fanciness
        ratelimiting: {
            // number of times to retry a request before giving up
            maxRetries: 10,         // default: 10
            // number of milliseconds to wait before retrying the
            // request (if API does not advise us otherwise!)
            timeout: 1000 * 60,     // default: 60000 (1 minute)
            // (optional) function invoked whenever this fanciness handles
            // any ratelimiting error.
            // this is useful for debugging and analysing your bot
            // behavior
            notify(methodName, ...args) {   // default: undefined
                // 'methodName' is the name of the invoked method
                // 'args' is an array of the arguments passed to the method
                // do something useful here
                // ...snip...
            },
            // maximum number of milliseconds to allow for waiting
            // in backoff-mode before retrying the request.
            // This is important to avoid situations where the server
            // can cause lengthy timeouts e.g. too long of a wait-time
            // that is causes adverse effects on efficiency and performance.
            maxBackoff: 1000 * 60 * 5,      // default: 5 minutes
        },
    },
});

Fancied functions: [ "addStickerToSet", "answerCallbackQuery", "answerInlineQuery", "answerPreCheckoutQuery", "answerShippingQuery", "createNewStickerSet", "deleteChatPhoto", "deleteChatStickerSet", "deleteMessage", "deleteStickerFromSet", "downloadFile", "editMessageCaption", "editMessageLiveLocation", "editMessageReplyMarkup", "editMessageText", "exportChatInviteLink", "forwardMessage", "getChat", "getChatAdministrators", "getChatMember", "getChatMembersCount", "getFile", "getFileLink", "getGameHighScores", "getStickerSet", "getUpdates", "getUserProfilePhotos", "kickChatMember", "leaveChat", "pinChatMessage", "promoteChatMember", "restrictChatMember", "sendAudio", "sendChatAction", "sendContact", "sendDocument", "sendGame", "sendInvoice", "sendLocation", "sendMediaGroup", "sendMessage", "sendPhoto", "sendSticker", "sendVenue", "sendVideo", "sendVideoNote", "sendVoice", "setChatDescription", "setChatPhoto", "setChatStickerSet", "setChatTitle", "setGameScore", "setStickerPositionInSet", "setWebHook", "stopMessageLiveLocation", "unbanChatMember", "unpinChatMessage", "uploadStickerFile", ]

An earlier discussion on this feature can be found here. See example at example/ratelimited.js.


Emojification:

Any Github-flavoured Markdown emoji, such as :heart: can be replaced automatically with their corresponding Unicode values. By default, uses the node-emoji library (Go give a star!). Disabled by default.

Feature option: emojification (see above)

For example,

const bot = new Tgfancy(token, {
    tgfancy: {
        emojification: true,
    },
});
bot.sendMessage(chatId, "Message text with :heart: emoji")
    .then(function(msg) {
        // 'msg' is the Message sent to the chat
        console.log(msg.text); // => "Message text with ❤️ emoji"
    });

However, it is possible to define a custom function used to perform emojification. The function must have the signature, emojify(text) and return the emojified text.

const bot = new Tgfancy(token, {
    tgfancy: {
        emojification: {
            emojify(text) {
                // emojify here
                // ... snip ...
                return emojifiedText;
            },
        },
    },
});

Fancied functions: ["sendMessage", "editMessageText"]

See example at example/emojified.js.


Fetching Updates via WebSocket:

In addition to polling and web-hooks, this introduces another mechanism for fetching your updates: WebSocket. While currently it is not officially supported by Telegram, we have a bridge up and running that you can connect to for this purpose. Disabled by default.

Feature option: webSocket (see above)

For example,

const bot = new Tgfancy(token, {
    tgfancy: {
        webSocket: true,
    },
});

The current default bridge is at wss://telegram-websocket-bridge-qalwkrjzzs.now.sh and is being run by @GingerPlusPlus.

You can specify more options as so:

const bot = new Tgfancy(token, {
    tgfancy: {
        webSocket: {
            // specify a custom URL for a different bridge
            url: "wss://telegram-websocket-bridge-qalwkrjzzs.now.sh",
            // immediately open the websocket
            autoOpen: true,
        },
    },
});

See example at example/web-socket.js.


Kick-without-Ban:

You can kick a user without banning them, that is, they will be able to rejoin the group using invite links, etc.

By default, Tgfancy kicks the user through Tgfancy#kickChatMember() using the default API method kickChatMember. Passing false as the last argument to Tgfancy#kickChatMember() will make Tgfancy executes the API method unbanChatMember() right after kicking the chat member, effectively kicking the user, without banning them.

Feature option: kickWithoutBan (see above)

For example,

// The last argument is called 'ban', is optional and
// defaults to 'true'. Passing 'false' causes Tgfancy execute
// 'unbanChatMember' right after kicking the user.
bot.kickChatMember(chatId, userId, false);

See example at example/kick-only.js.


Openshift WebHook:

It is easier to set up webhook for your bot on Openshift. Enabling this feature allows automatic detection if running on Openshift and setting up web-hook for the bot instance.

Feature option: openshiftWebHook (see above)

For example,

const bot = new Tgfancy(token, {
    tgfancy: {
        openshiftWebHook: true, // enable this feature
    },
});

Note that polling and fetching updates via WebSocket are automatically disabled if the web-hook is set. This allows you to use polling or WebSocket locally, but use a web-hook on Openshift. For example,

const bot = new Tgfancy(token, {
    polling: true, // use polling unless disabled by Openshift-WebHook feature
    tgfancy: {
        openshiftWebHook: true,
    },
});

You may also define default web-hook parameters to be used, if the bot is not running on Openshift. For example,

const bot = new Tgfancy(token, {
    webHook: { /* your parameters here */ }, // used if NOT on Openshift
    tgfancy: {
        openshiftWebHook: true,
    },
});

license:

The MIT License (MIT)

Copyright (c) 2016 GochoMugo (www.gmugo.in)