Посібник по плагінам для grammY

Якщо ви бажаєте розробити свій власний плагін та опублікувати його, або якщо ви хочете дізнатися, як працюють плагіни grammY за кулісами, то це місце для вас!

Зверніть увагу, що вже є опис плагінів grammY та їх функцій. Ця стаття — це глибоке занурення в їх внутрішні процеси.

Типи плагінів в grammY

Є два основних типи плагінів в grammY:

Плагіни проміжного обробника: задачею плагіна є повернути функцію проміжного обробника, яку можна використовувати в боті grammY.
Плагіни-перетворювачі: задачею плагіна є повернути функцію-перетворювач, яку можна використовувати в боті grammY.

Проте іноді ви можете знайти плагіни, які роблять обидві речі. Також є інші пакети, які не є функціями проміжних обробників або перетворювачів, але ми також називаємо їх плагінами, оскільки вони розширюють функціональність grammY різними способами.

Правила контрибʼютингу

Ви можете опублікувати свій плагін в одному з наступних варіантів:

Опублікувати як офіційний плагін.
Опублікувати як плагін від сторонніх розробників.

Якщо ви вирішите опублікувати свій плагін як сторонній, ми все ще можемо запропонувати вам видне місце на цьому вебсайті. Однак, ми віддаємо перевагу, якщо ви опублікуєте свій плагін в організації grammyjs на GitHub, зробивши його офіційним плагіном. В такому випадку вам буде надано доступ до публікації на GitHub та npm. Крім того, ви будете відповідальні за підтримку свого коду.

Перед тим як перейти до деяких практичних прикладів, є кілька правил, на які потрібно звернути увагу, якщо ви хочете, щоб ваші плагіни були включені до списку на цьому вебсайті.

Необхідно мати файл README на GitHub та npm з короткими та чіткими інструкціями щодо використання плагіна.
Поясніть призначення вашого плагіна та як його використовувати, додавши сторінку до документації. Якщо ви не впевнені, як це зробити, ми можемо створити сторінку за вас.
Оберіть ліцензію з дозволом на використання: наприклад, MIT або ISC.

Нарешті, ви повинні знати, що хоча grammY підтримує як Node.js, так і Deno, він є проєктом, спрямованим на Deno, і ми також підтримуємо написання плагінів для Deno (згодом й у стилі!). Є корисний інструмент під назвою deno2node, який транспілює ваш код з Deno на Node.js, щоб ми могли однаково добре підтримувати обидві платформи. Підтримка Deno є обовʼязковою тільки для офіційних плагінів, але не для плагінів сторонніх розробників. Утім, ми дуже рекомендуємо спробувати Deno. Ви не захочете повертатися назад.

Розробка тестового плагіну проміжного обробника

Припустимо, ми хотіли б розробити плагін, який дозволить відповідати лише певним користувачам! Наприклад, ми можемо вирішити відповідати тільки людям, чиє імʼя містить певне слово. Бот просто відмовиться працювати з будь-ким іншим.

Ось приклад:

// plugin.ts

// Імпортуємо типи з grammY, ми реекспортуємо їх в `deps.deno.ts`.
import type { Context, Middleware, NextFunction } from "./deps.deno.ts";

// Ваш плагін може мати одну основну функцію, яка створює проміжний обробник.
export function onlyAccept<C extends Context>(str: string): Middleware<C> {
  // Створюємо та повертаємо проміжний обробник.
  return async (ctx, next) => {
    // Отримуємо імʼя користувача.
    const name = ctx.from?.first_name;
    // Допускаємо оновлення, якщо воно відповідає умовам.
    if (name === undefined || name.includes(str)) {
      // Викликаємо нижній проміжний обробник
      await next();
    } else {
      // Якщо не відповідає умовам, скажемо, що ми з такими не працюємо.
      await ctx.reply(`Я не буду з вами розмовляти! Ви не цікавитеся ${str}!`);
    }
  };
}

Тепер ми можемо використовувати це в реальному боті:

// Код плагіну знаходиться у файлі з назвою `plugin.ts`
import { onlyAccept } from "./plugin.ts";
import { Bot } from "./deps.deno.ts";

const bot = new Bot("");

bot.use(onlyAccept("grammY"));

bot.on("message", (ctx) => ctx.reply("Ви пройшли проміжний обробник плагіну!"));

bot.start();

Ось і все! Ви створили власний плагін, чи не так? Але не так швидко. Нам ще потрібно упакувати його, але перед цим давайте подивимося на плагіни-перетворювачі.

Розробка тестового плагіну-перетворювача

Уявіть, що ви пишете плагін, який автоматично надсилає відповідну дію чату щоразу, коли бот надсилає документ. Це означає, що під час надсилання файлу, користувачі автоматично побачать “відправляє файл…” як статус. Досить круто, чи не так?

// plugin.ts
import type { Transformer } from "./deps.deno.ts";

// Головна функція плагіну
export function autoChatAction(): Transformer {
  // Створюємо та повертаємо функцію-перетворювач.
  return async (prev, method, payload, signal) => {
    // Збережемо ідентифікатор встановленого інтервалу, щоби потім можна було очистити його.
    let handle: ReturnType<typeof setTimeout> | undefined;
    if (method === "sendDocument" && "chat_id" in payload) {
      // Тепер ми знаємо, що документ було надіслано.
      const actionPayload = {
        chat_id: payload.chat_id,
        action: "upload_document",
      };
      // Постійно встановлюємо дію чату під час завантаження файлу.
      handle ??= setInterval(() => {
        prev("sendChatAction", actionPayload).catch(console.error);
      }, 5000);
    }

    try {
      // Запускаємо справжній метод із бота.
      return await prev(method, payload, signal);
    } finally {
      // Очищаємо інтервал, щоб припинити надсилання дії в чат клієнту.
      clearInterval(handle);
    }
  };
}

Тепер ми можемо використовувати це в реальному боті:

import { Bot, InputFile } from "./deps.deno.ts";
// Код плагіну знаходиться у файлі з назвою `plugin.ts`
import { autoChatAction } from "./plugin.ts";

// Створюємо екземпляр бота.
const bot = new Bot("");

// Використовуємо плагін.
bot.api.config.use(autoChatAction());

bot.hears("Надішли мені документ", async (ctx) => {
  // Якщо користувач надішле цю команду, ми надішлемо йому pdf-файл (для демонстраційних цілей)
  await ctx.replyWithDocument(new InputFile("/tmp/document.pdf"));
});

// запускаємо бота
bot.start();

Тепер щоразу, коли ми відправляємо документ, дія чату upload_document буде відправлена нашому клієнту. Зверніть увагу, що це було зроблено для демонстраційних цілей. Telegram рекомендує використовувати дії чату тільки тоді, коли “відповідь від бота буде займати відчутний час на доставку”. Імовірно, вам не потрібно встановлювати статус, якщо файл дуже малий, тому тут є деякі оптимізації, які можна зробити.

Перехід у плагін

Незалежно від того, який тип плагіна ви створили, ви повинні запакувати його в пакет. Це досить просте завдання. Немає конкретних правил щодо того, як це зробити, і npm — ваша перлина, але щоб все було організовано, у нас є для вас пропозиція шаблону. Ви можете завантажити код шаблону плагіна з нашого репозиторію на GitHub і почати розробляти свій плагін без витрачення часу на налаштування.

Початкова структура каталогів:

asciiart

plugin-template/
├─ src/
│  ├─ deps.deno.ts
│  ├─ deps.node.ts
│  └─ index.ts
├─ package.json
├─ tsconfig.json
└─ README.md

deps.deno.ts та deps.node.ts: це для розробників, які бажають написати плагін для Deno, а потім транспілювати його для Node.js. Як зазначалося раніше, ми використовуємо інструмент deno2node для транспіляції нашого коду з Deno на Node.js. У deno2node є функція, яка дозволяє надавати йому файли, специфічні для середовища виконання. Ці файли повинні бути поруч із іншими файлами та мають назву зі структурою іменування *.deno.ts та *.node.ts, як пояснено в документації. Саме тому є два файли: deps.deno.ts та deps.node.ts. Якщо є якісь залежності, специфічні для Node.js, помістіть їх у deps.node.ts, в іншому випадку залиште його порожнім.

Примітка: ви також можете використовувати інші інструменти, такі як deno dnt, для траспіляції вашого коду Deno, або використовувати іншу структуру каталогів. Інструменти, які ви використовуєте, не важливі — головне, що писати код для Deno краще і простіше.

tsconfig.json: конфігураційний файл компілятора TypeScript, який використовується deno2node для транспіляції вашого коду. У репозиторії надається типовий конфігураційний файл як пропозиція. Він відповідає конфігурації TypeScript, яку використовує Deno внутрішньо, і ми рекомендуємо, щоб ви залишалися з цією конфігурацією.

package.json: файл package.json для версіонування вашого плагіна в npm. Переконайтеся, що зміните його згідно з вашим проєктом.

README.md: інструкції щодо використання плагіну. Переконайтеся, що зміните його згідно з вашим проєктом.

index.ts: файл, що містить бізнес-логіку вашого плагіна, тобто ваш основний код плагіну.

Шаблон плагіну

Якщо ви хочете розробити плагін для grammY, але не знаєте, з чого почати, ми дуже рекомендуємо використовувати код шаблону, що знаходиться у нашому репозиторії. Ви можете клонувати код до себе та почати програмувати, користуючись тим, що було розглянуто у цій статті. У цьому репозиторії також є додаткові корисні файли: наприклад, .editorconfig, LICENSE, .gitignore тощо, але ви можете видалити їх за потреби.

Мені не подобається Deno

Ну що ж, ви багато втрачаєте! Але ви також можете писати свої плагіни тільки для Node.js. Ви все ще можете опублікувати плагін і додати його до списку сторонніх плагінів на цьому вебсайті. У такому випадку ви можете використовувати будь-яку структуру каталогів, яку бажаєте, якщо вона організована, як будь-який інший проєкт npm. Просто встановіть grammY через npm з npm install grammy і починайте програмувати.

Як опублікувати мій плагін?

Якщо у вас є готовий плагін, ви можете просто створити pull request на GitHub відповідно до правил контрибʼютингу або повідомити нас у чаті спільноти для подальшої допомоги.

Посібник по плагінам для grammY ​

Типи плагінів в grammY ​

Правила контрибʼютингу ​

Розробка тестового плагіну проміжного обробника ​

Розробка тестового плагіну-перетворювача ​

Перехід у плагін ​

Шаблон плагіну ​

Мені не подобається Deno ​

Як опублікувати мій плагін? ​