@tgify/tgify 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-2019 Vitaly Domnikov
+Copyright (c) 2020-2023 The Telegraf Contributors
+Copyright (c) 2026 IATNAOD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,356 @@
+<header>
+
+<div align="center">
+<h1 align="center">tgify</h1>
+
+<p>Modern Telegram Bot API framework for Node.js</p>
+
+<a href="https://core.telegram.org/bots/api">
+	<img src="https://img.shields.io/badge/Bot%20API-v7.1-f36caf.svg?style=flat-square" alt="Bot API Version" />
+</a>
+<a href="https://packagephobia.com/result?p=tgify,node-telegram-bot-api">
+	<img src="https://flat.badgen.net/packagephobia/install/tgify" alt="install size" />
+</a>
+<a href="https://github.com/IATNAOD/tgify">
+	<img src="https://img.shields.io/github/languages/top/IATNAOD/tgify?style=flat-square&logo=github" alt="GitHub top language" />
+</a>
+</div>
+
+</header>
+
+## Introduction
+
+Bots are special [Telegram](https://telegram.org) accounts designed to handle messages automatically.
+Users can interact with bots by sending them command messages in private or group chats.
+These accounts serve as an interface for code running somewhere on your server.
+
+Tgify is a library that makes it simple for you to develop your own Telegram bots using JavaScript or [TypeScript](https://www.typescriptlang.org/).
+
+### Features
+
+- Full [Telegram Bot API 7.1](https://core.telegram.org/bots/api) support
+- [Excellent TypeScript typings](https://github.com/IATNAOD/tgify/releases/tag/v4.0.0)
+- [Lightweight](https://packagephobia.com/result?p=tgify,node-telegram-bot-api)
+- [AWS **λ**](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html)
+  / [Firebase](https://firebase.google.com/products/functions/)
+  / [Glitch](https://glitch.com/edit/#!/dashing-light)
+  / [Fly.io](https://fly.io/docs/languages-and-frameworks/node)
+  / Whatever ready
+- `http/https/fastify/Connect.js/express.js` compatible webhooks
+- Extensible
+
+### Example
+
+```js
+const { Telegraf } = require('telegraf')
+const { message } = require('telegraf/filters')
+
+const bot = new Telegraf(process.env.BOT_TOKEN)
+bot.start((ctx) => ctx.reply('Welcome'))
+bot.help((ctx) => ctx.reply('Send me a sticker'))
+bot.on(message('sticker'), (ctx) => ctx.reply('👍'))
+bot.hears('hi', (ctx) => ctx.reply('Hey there'))
+bot.launch()
+
+// Enable graceful stop
+process.once('SIGINT', () => bot.stop('SIGINT'))
+process.once('SIGTERM', () => bot.stop('SIGTERM'))
+```
+
+```js
+const { Telegraf } = require('telegraf')
+
+const bot = new Telegraf(process.env.BOT_TOKEN)
+bot.command('oldschool', (ctx) => ctx.reply('Hello'))
+bot.command('hipster', Telegraf.reply('λ'))
+bot.launch()
+
+// Enable graceful stop
+process.once('SIGINT', () => bot.stop('SIGINT'))
+process.once('SIGTERM', () => bot.stop('SIGTERM'))
+```
+
+For additional bot examples see the new [`docs repo`](https://github.com/feathers-studio/telegraf-docs/).
+
+### Resources
+
+- [Getting started](#getting-started)
+- [GitHub Discussions](https://github.com/IATNAOD/tgify/discussions)
+- [Dependent repositories](https://libraries.io/npm/tgify/dependent_repositories)
+
+## Getting started
+
+### Telegram token
+
+To use the [Telegram Bot API](https://core.telegram.org/bots/api),
+you first have to [get a bot account](https://core.telegram.org/bots)
+by [chatting with BotFather](https://core.telegram.org/bots#6-botfather).
+
+BotFather will give you a _token_, something like `123456789:AbCdefGhIJKlmNoPQRsTUVwxyZ`.
+
+### Installation
+
+```shellscript
+$ npm install tgify
+```
+
+or
+
+```shellscript
+$ yarn add tgify
+```
+
+or
+
+```shellscript
+$ pnpm add tgify
+```
+
+### `Telegraf` class
+
+[`Telegraf`] instance represents your bot. It's responsible for obtaining updates and passing them to your handlers.
+
+Start by [listening to commands](https://telegraf.js.org/classes/Telegraf-1.html#command) and [launching](https://telegraf.js.org/classes/Telegraf-1.html#launch) your bot.
+
+### `Context` class
+
+`ctx` you can see in every example is a [`Context`] instance.
+[`Telegraf`] creates one for each incoming update and passes it to your middleware.
+It contains the `update`, `botInfo`, and `telegram` for making arbitrary Bot API requests,
+as well as shorthand methods and getters.
+
+This is probably the class you'll be using the most.
+
+#### Shorthand methods
+
+```js
+import { Telegraf } from 'telegraf'
+import { message } from 'telegraf/filters'
+
+const bot = new Telegraf(process.env.BOT_TOKEN)
+
+bot.command('quit', async (ctx) => {
+  // Explicit usage
+  await ctx.telegram.leaveChat(ctx.message.chat.id)
+
+  // Using context shortcut
+  await ctx.leaveChat()
+})
+
+bot.on(message('text'), async (ctx) => {
+  // Explicit usage
+  await ctx.telegram.sendMessage(ctx.message.chat.id, `Hello ${ctx.state.role}`)
+
+  // Using context shortcut
+  await ctx.reply(`Hello ${ctx.state.role}`)
+})
+
+bot.on('callback_query', async (ctx) => {
+  // Explicit usage
+  await ctx.telegram.answerCbQuery(ctx.callbackQuery.id)
+
+  // Using context shortcut
+  await ctx.answerCbQuery()
+})
+
+bot.on('inline_query', async (ctx) => {
+  const result = []
+  // Explicit usage
+  await ctx.telegram.answerInlineQuery(ctx.inlineQuery.id, result)
+
+  // Using context shortcut
+  await ctx.answerInlineQuery(result)
+})
+
+bot.launch()
+
+// Enable graceful stop
+process.once('SIGINT', () => bot.stop('SIGINT'))
+process.once('SIGTERM', () => bot.stop('SIGTERM'))
+```
+
+## Production
+
+### Webhooks
+
+```TS
+import { Telegraf } from "telegraf";
+import { message } from 'telegraf/filters';
+
+const bot = new Telegraf(token);
+
+bot.on(message("text"), ctx => ctx.reply("Hello"));
+
+// Start webhook via launch method (preferred)
+bot.launch({
+  webhook: {
+    // Public domain for webhook; e.g.: example.com
+    domain: webhookDomain,
+
+    // Port to listen on; e.g.: 8080
+    port: port,
+
+    // Optional path to listen for.
+    // `bot.secretPathComponent()` will be used by default
+    path: webhookPath,
+
+    // Optional secret to be sent back in a header for security.
+    // e.g.: `crypto.randomBytes(64).toString("hex")`
+    secretToken: randomAlphaNumericString,
+  },
+});
+```
+
+Use `createWebhook()` if you want to attach Telegraf to an existing http server.
+
+<!-- global bot, tlsOptions -->
+
+```TS
+import { createServer } from "http";
+
+createServer(await bot.createWebhook({ domain: "example.com" })).listen(3000);
+```
+
+```TS
+import { createServer } from "https";
+
+createServer(tlsOptions, await bot.createWebhook({ domain: "example.com" })).listen(8443);
+```
+
+- [AWS Lambda example integration](https://github.com/feathers-studio/telegraf-docs/tree/master/examples/functions/aws-lambda)
+- [Google Cloud Functions example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/functions/google-cloud-function.ts)
+- [`express` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/express.ts)
+- [`fastify` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/fastify.ts)
+- [`koa` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/koa.ts)
+- [Cloudflare Workers integration module](https://github.com/Tsuk1ko/cfworker-middware-telegraf)
+- Use [`bot.handleUpdate`](https://telegraf.js.org/classes/Telegraf-1.html#handleupdate) to write new integrations
+
+### Error handling
+
+If middleware throws an error or times out, Telegraf calls `bot.handleError`. If it rethrows, update source closes, and then the error is printed to console and process terminates. If it does not rethrow, the error is swallowed.
+
+Default `bot.handleError` always rethrows. You can overwrite it using `bot.catch` if you need to.
+
+⚠️ Swallowing unknown errors might leave the process in invalid state!
+
+ℹ️ In production, `systemd` or [`pm2`](https://www.npmjs.com/package/pm2) can restart your bot if it exits for any reason.
+
+## Advanced topics
+
+### Working with files
+
+Supported file sources:
+
+- `Existing file_id`
+- `File path`
+- `Url`
+- `Buffer`
+- `ReadStream`
+
+Also, you can provide an optional name of a file as `filename` when you send the file.
+
+<!-- global bot, fs -->
+
+```js
+bot.on('message', async (ctx) => {
+  // resend existing file by file_id
+  await ctx.replyWithSticker('123123jkbhj6b')
+
+  // send file
+  await ctx.replyWithVideo(Input.fromLocalFile('/path/to/video.mp4'))
+
+  // send stream
+  await ctx.replyWithVideo(
+    Input.fromReadableStream(fs.createReadStream('/path/to/video.mp4'))
+  )
+
+  // send buffer
+  await ctx.replyWithVoice(Input.fromBuffer(Buffer.alloc()))
+
+  // send url via Telegram server
+  await ctx.replyWithPhoto(Input.fromURL('https://picsum.photos/200/300/'))
+
+  // pipe url content
+  await ctx.replyWithPhoto(
+    Input.fromURLStream('https://picsum.photos/200/300/?random', 'kitten.jpg')
+  )
+})
+```
+
+### Middleware
+
+In addition to `ctx: Context`, each middleware receives `next: () => Promise<void>`.
+
+As in Koa and some other middleware-based libraries,
+`await next()` will call next middleware and wait for it to finish:
+
+```TS
+import { Telegraf } from 'telegraf';
+import { message } from 'telegraf/filters';
+
+const bot = new Telegraf(process.env.BOT_TOKEN);
+
+bot.use(async (ctx, next) => {
+  console.time(`Processing update ${ctx.update.update_id}`);
+  await next() // runs next middleware
+  // runs after next middleware finishes
+  console.timeEnd(`Processing update ${ctx.update.update_id}`);
+})
+
+bot.on(message('text'), (ctx) => ctx.reply('Hello World'));
+bot.launch();
+
+// Enable graceful stop
+process.once('SIGINT', () => bot.stop('SIGINT'));
+process.once('SIGTERM', () => bot.stop('SIGTERM'));
+```
+
+With this simple ability, you can:
+
+- extract information from updates and then `await next()` to avoid disrupting other middleware,
+- like [`Composer`] and [`Router`], `await next()` for updates you don't wish to handle,
+- like [`session`] and [`Scenes`], [extend the context](#extending-context) by mutating `ctx` before `await next()`,
+- [intercept API calls](https://github.com/telegraf/telegraf/discussions/1267#discussioncomment-254525),
+- reuse [other people's code](https://www.npmjs.com/search?q=telegraf-),
+- do whatever **you** come up with!
+
+[`Telegraf`]: https://telegraf.js.org/classes/Telegraf-1.html
+[`Composer`]: https://telegraf.js.org/classes/Composer.html
+[`Context`]: https://telegraf.js.org/classes/Context.html
+[`Router`]: https://telegraf.js.org/classes/Router.html
+[`session`]: https://telegraf.js.org/modules.html#session
+[`Scenes`]: https://telegraf.js.org/modules/Scenes.html
+
+### Usage with TypeScript
+
+Tgify is written in TypeScript and therefore ships with declaration files for the entire library.
+Moreover, it includes types for the complete Telegram API via the [`typegram`](https://github.com/KnorpelSenf/typegram) package.
+While most types of Tgify's API surface are self-explanatory, there's some notable things to keep in mind.
+
+#### Extending `Context`
+
+The exact shape of `ctx` can vary based on the installed middleware.
+Some custom middleware might register properties on the context object that Telegraf is not aware of.
+Consequently, you can change the type of `ctx` to fit your needs in order for you to have proper TypeScript types for your data.
+This is done through Generics:
+
+```ts
+import { Context, Telegraf } from 'telegraf'
+
+// Define your own context type
+interface MyContext extends Context {
+  myProp?: string
+  myOtherProp?: number
+}
+
+// Create your bot and tell it about your context type
+const bot = new Telegraf<MyContext>('SECRET TOKEN')
+
+// Register middleware and launch your bot as usual
+bot.use((ctx, next) => {
+  // Yay, `myProp` is now available here as `string | undefined`!
+  ctx.myProp = ctx.chat?.first_name?.toUpperCase()
+  return next()
+})
+// ...
+```

package/filters.d.ts

@@ -0,0 +1 @@
+export * from './typings/filters'

package/filters.js

@@ -0,0 +1 @@
+module.exports = require('./lib/filters')

package/format.d.ts

@@ -0,0 +1 @@
+export * from './typings/format'

package/format.js

@@ -0,0 +1 @@
+module.exports = require('./lib/format')

package/future.d.ts

@@ -0,0 +1 @@
+export * from './typings/future'

package/future.js

@@ -0,0 +1 @@
+module.exports = require('./lib/future')

package/lib/button.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.text = text;
+exports.contactRequest = contactRequest;
+exports.locationRequest = locationRequest;
+exports.pollRequest = pollRequest;
+exports.userRequest = userRequest;
+exports.botRequest = botRequest;
+exports.groupRequest = groupRequest;
+exports.channelRequest = channelRequest;
+exports.url = url;
+exports.callback = callback;
+exports.switchToChat = switchToChat;
+exports.switchToCurrentChat = switchToCurrentChat;
+exports.game = game;
+exports.pay = pay;
+exports.login = login;
+exports.webApp = webApp;
+function text(text, hide = false) {
+    return { text, hide };
+}
+function contactRequest(text, hide = false) {
+    return { text, request_contact: true, hide };
+}
+function locationRequest(text, hide = false) {
+    return { text, request_location: true, hide };
+}
+function pollRequest(text, type, hide = false) {
+    return { text, request_poll: { type }, hide };
+}
+function userRequest(text, 
+/** Must fit in a signed 32 bit int */
+request_id, extra, hide = false) {
+    return {
+        text,
+        request_users: { request_id, ...extra },
+        hide,
+    };
+}
+function botRequest(text, 
+/** Must fit in a signed 32 bit int */
+request_id, extra, hide = false) {
+    return {
+        text,
+        request_users: { request_id, user_is_bot: true, ...extra },
+        hide,
+    };
+}
+function groupRequest(text, 
+/** Must fit in a signed 32 bit int */
+request_id, extra, hide = false) {
+    return {
+        text,
+        request_chat: { request_id, chat_is_channel: false, ...extra },
+        hide,
+    };
+}
+function channelRequest(text, 
+/** Must fit in a signed 32 bit int */
+request_id, extra, hide = false) {
+    return {
+        text,
+        request_chat: { request_id, chat_is_channel: true, ...extra },
+        hide,
+    };
+}
+function url(text, url, hide = false) {
+    return { text, url, hide };
+}
+function callback(text, data, hide = false) {
+    return { text, callback_data: data, hide };
+}
+function switchToChat(text, value, hide = false) {
+    return { text, switch_inline_query: value, hide };
+}
+function switchToCurrentChat(text, value, hide = false) {
+    return { text, switch_inline_query_current_chat: value, hide };
+}
+function game(text, hide = false) {
+    return { text, callback_game: {}, hide };
+}
+function pay(text, hide = false) {
+    return { text, pay: true, hide };
+}
+function login(text, url, opts = {}, hide = false) {
+    return {
+        text,
+        login_url: { ...opts, url },
+        hide,
+    };
+}
+function webApp(text, url, hide = false
+// works as both InlineKeyboardButton and KeyboardButton
+) {
+    return {
+        text,
+        web_app: { url },
+        hide,
+    };
+}

package/lib/cli.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import d from 'debug';
+import parse from 'mri';
+import path from 'path';
+import { Telegraf } from './index.js';
+const debug = d('telegraf:cli');
+const helpMsg = `Usage: telegraf [opts] <bot-file>
+
+  -t  Bot token [$BOT_TOKEN]
+  -d  Webhook domain [$BOT_DOMAIN]
+  -H  Webhook host [0.0.0.0]
+  -p  Webhook port [$PORT or 3000]
+  -l  Enable logs
+  -h  Show this help message
+  -m  Bot API method to run directly
+  -D  Data to pass to the Bot API method`;
+const help = () => console.log(helpMsg);
+/**
+ * Runs the cli program and returns exit code
+ */
+export async function main(argv, env = {}) {
+    const args = parse(argv, {
+        alias: {
+            // string params, all optional
+            t: 'token',
+            d: 'domain',
+            m: 'method',
+            D: 'data',
+            // defaults exist
+            H: 'host',
+            p: 'port',
+            // boolean params
+            l: 'logs',
+            h: 'help',
+        },
+        boolean: ['h', 'l'],
+        default: {
+            H: '0.0.0.0',
+            p: env.PORT || '3000',
+        },
+    });
+    if (args.help) {
+        help();
+        return 0;
+    }
+    const token = args.token || env.BOT_TOKEN;
+    const domain = args.domain || env.BOT_DOMAIN;
+    if (!token) {
+        console.error('Please supply Bot Token');
+        help();
+        return 1;
+    }
+    const bot = new Telegraf(token);
+    if (args.method) {
+        const method = args.method;
+        console.log(await bot.telegram.callApi(method, JSON.parse(args.data || '{}')));
+        return 0;
+    }
+    let [, , file] = args._;
+    if (!file) {
+        try {
+            const packageJson = (await import(path.resolve(process.cwd(), 'package.json')));
+            file = packageJson.main || 'index.js';
+            // eslint-disable-next-line no-empty
+        }
+        catch (err) { }
+    }
+    if (!file) {
+        console.error('Please supply a bot handler file.\n');
+        help();
+        return 2;
+    }
+    if (file[0] !== '/')
+        file = path.resolve(process.cwd(), file);
+    try {
+        if (args.logs)
+            d.enable('telegraf:*');
+        const mod = await import(file);
+        const botHandler = mod.botHandler || mod.default;
+        const httpHandler = mod.httpHandler;
+        const tlsOptions = mod.tlsOptions;
+        const config = {};
+        if (domain) {
+            config.webhook = {
+                domain,
+                host: args.host,
+                port: Number(args.port),
+                tlsOptions,
+                cb: httpHandler,
+            };
+        }
+        bot.use(botHandler);
+        debug(`Starting module ${file}`);
+        await bot.launch(config);
+    }
+    catch (err) {
+        console.error(`Error launching bot from ${file}`, err === null || err === void 0 ? void 0 : err.stack);
+        return 3;
+    }
+    // Enable graceful stop
+    process.once('SIGINT', () => bot.stop('SIGINT'));
+    process.once('SIGTERM', () => bot.stop('SIGTERM'));
+    return 0;
+}
+process.exitCode = await main(process.argv, process.env);