@prototype/telegram

Prototype VIP — unified Telegram library

مكتبة واحدة تدمج أقوى أفكار مكتبات وسكربتات تليجرام (grammY · Telegraf · aiogram · Telethon/Pyrogram · the-guard-bot · lucyna · Anjani …) في واجهة Node جاهزة لبوت Proto.

npm name: @prototype/telegram — متاح (تم التحقق 2026-10-08).
ملاحظة: npm لا يقبل حروف كبيرة في الاسم؛ @Prototype/telegram غير صالح، استخدم @prototype/telegram.

Install

npm i @prototype/telegram
# grammy + أدوات (jimp, pdfkit, mathjs, cheerio, chess.js …) و teleproto (MTProto) بيتسطبوا تلقائياً

Quick start

const { createBot } = require("@prototype/telegram");

const bot = createBot(process.env.BOT_TOKEN, {
  lang: "ar",
  owners: [123456789],
  modules: [
    "antiflood",
    "antilink",
    "antibot",
    "antichannel",
    "captcha",
    "federation",
    "filters",
    "welcome",
    "serviceCleaner",
  ],
  buttonTheme: "smart", // classic | smart | ocean | forest
  welcomeText: "👋 أهلاً {mention} في *{title}*",
  floodLimit: 6,
  floodWindowMs: 4000,
});

bot.command("start", (ctx) => ctx.reply("Proto VIP 🚀"));
bot.start();

Modules

| Module | Source inspiration | What it does | |--------|-------------------|--------------| | buttonStyles | Proto VIP | primary / success / danger auto colors | | i18n | Proto + aiogram | ar / en strings + register() | | antiflood | Guard / aiogram | rate limit per user | | antilink | Shikari / Marie | block URLs / t.me | | antibot | the-guard-bot | kick bots added by members | | antichannel | Shikari | block anonymous channel posts | | captcha | group managers | math button captcha on join | | federation | Anjani / Marie | shared ban list + /fban | | filters | lucyna / Anjani | keyword → reply triggers | | welcome | all managers | welcome/goodbye templates | | serviceCleaner | Shikari | delete join/leave/pin/vc service msgs | | shop | Proto VIP | price helpers (server + install) | | ratings | Proto VIP | 1–5 star store | | fileManager | Proto fileStudio | scaffold (host integrates full UI) |

MTProto (optional)

const { createClient } = require("@prototype/telegram/mtproto");

const client = await createClient({
  apiId: process.env.API_ID,
  apiHash: process.env.API_HASH,
  session: process.env.SESSION || "",
});
await client.start({ /* phone / code callbacks */ });

يمكّن: يوزربوت، تاريخ كامل، تحميل أصلي، multi-account، raw TL.

Payments helpers

const { starsInvoice, vodafoneCopyButton } = require("@prototype/telegram/payments");

Design notes

• لا إعادة اختراع العجلة: الطبقة الأساسية = grammY (peer dependency).
• موديولات اختيارية: فعّل اللي تحتاجه فقط.
• أفكار من Python/PHP: Federations، captcha، anti-service، filters — متعرّبة لـ JS.
• متوافق مع بوت Proto الحالي: button styles، shop pricing، i18n AR/EN.

Roadmap

• [x] Scaffold + core modules
• [ ] Persist stores (Redis / SQLite adapters)
• [ ] Full fileManager port from Proto
• [ ] Stars payment middleware
• [x] Publish-ready for npm under @prototype/telegram (v0.5.0)

Fast session store (from Prototype VIP Baileys pattern)

نفس فلسفة الجلسات السريعة في @prototypevip/baileys (SQLite WAL + mmap + cache) — بدون أي كود واتساب:

const { createSqliteStore, createSessionStore } = require("@prototype/telegram");

// generic KV (federation, lang, settings…)
const kv = createSqliteStore("./data/proto", "settings");
kv.set("theme", "smart");
console.log(kv.get("theme"));

// MTProto string sessions
const sessions = createSessionStore("./data/mtproto-sessions");
sessions.save("main", sessionString);
const s = sessions.load("main");

PRAGMA المستخدم: WAL · synchronous=NORMAL · temp_store=MEMORY · cache_size=-128000 · mmap_size=500MB · checkpoint عند الإغلاق.

Message basics (منشن · استقبال · قراءة)

كل ctx بعد createBot يتزود تلقائيًا:

| الخاصية / الدالة | المعنى | |------------------|--------| | ctx.msgText | نص الرسالة أو الـ caption | | ctx.msgType | text / photo / video / … | | ctx.mentions | قائمة المنشنات (mention + text_mention) | | ctx.isBotMentioned() | هل البوت متنشن أو الرد عليه؟ | | ctx.commandArgs | باقي الأمر بعد /cmd | | ctx.mentionHtml() / mentionMarkdown() | منشن HTML/Markdown للمستخدم |

bot.on("message", async (ctx) => {
  if (ctx.isBotMentioned()) {
    await ctx.reply(`نعم يا ${ctx.mentionHtml()}؟`, { parse_mode: "HTML" });
  }
  console.log(ctx.msgType, ctx.mentions);
});

// helpers مباشرة
const { parseMentions, isMentioned, markRead } = require("@prototype/telegram").utils;

markRead يعمل عبر MTProto (messages.ReadHistory). Bot API لا يوفّر read receipts يدوية.

Security note about WhatsApp fork

نسخ قديمة من @prototypevip/baileys عليها تنبيه أمني عام (malware advisory).
مكتبة تليجرام لا تعتمد على baileys ولا تنسخ أي منطق حظر/ترخيص — فقط نمط تخزين SQLite السريع من usePrototypeAuthState المحلي عندكم.

License

MIT © Prototype VIP

HTTP layer (v0.3.0) — one client instead of axios + node-fetch + form-data + formdata-node + request

Built only on node:http / node:https / node:zlib (no dependencies). Same API surface the bot uses:

const { http } = require("@prototype/telegram");
const { axios, fetch, FormData, request } = http;

const r = await axios.get(url, { params: { q: 1 }, timeout: 15000, responseType: "arraybuffer" });
const j = await (await fetch(url, { method: "POST", body: form, headers: form.getHeaders() })).json();

• axios — get/post/put/patch/delete/head/request/create, baseURL, params, headers, JSON/urlencoded/multipart/stream bodies, responseType json|text|arraybuffer|stream|blob, timeout (socket idle), validateStatus, redirects, maxContentLength, maxBodyLength, signal, auth, httpAgent/httpsAgent, transformResponse, gzip/deflate/br, interceptors, AxiosError.
• fetch — node-fetch v2/v3 surface (json/text/buffer/arrayBuffer/blob/clone, Headers, redirect, size, timeout, FetchError).
• FormData — form-data compatible (+ spec methods and Blob values).
• request — callback style incl. .form() / formData / json / qs.
• http.install() — makes require("axios" | "node-fetch" | "form-data" | "formdata-node" | "request") resolve to these implementations for your own files only (never inside node_modules). PROTO_HTTP=native disables it.

Not supported (not needed by the bot): axios proxy/env-proxy, upload/download progress, socketPath, cookie jars. Tests: npm test (HTTP layer + moderation, 27 tests).

Moderation engine (v0.4.0)

The group guard used by Proto.Vip — deletes the offending message, counts a violation, then mutes / kicks / bans at the limit (admins are never punished; the bot tells the group when it cannot act on an admin). Tested with real grammY against a fake Telegram API (test/moderation.test.js) and inside the real bot (bot.js).

const { createModeration } = require("@prototype/telegram").modules.moderation;
const mod = createModeration({
  store: chatSettings,            // getSettings/updateSettings/addWarning/getWarningLog/resetWarnings/recordModUser (or createMemoryStore())
  isFederationBanned: (id) => false,
  langOf: (chatId, settings) => (settings.lang === "en" ? "en" : "ar"),
  onSeen: (ctx, settings) => {},  // e.g. remember members
  unmuteButton: (kb, label, data) => kb.text(label, data),
});
bot.use(mod.guard());

Per-chat flags: antibot antiflood(+floodLimit) antispam antilink antiswear antiphoto antisticker antivideo antivoice antigif antimention antiforward antichannel · maxWarnings (3) · punishAction mute|kick|ban · lang ar|en. Admin lookups are cached for 30 s (adminCacheMs).

Bundled utility dependencies (v0.5.0+)

المكتبة بتسطّب معاها: grammy, jimp, pdfkit, mathjs, cheerio, chess.js, chalk, fs-extra, mime-types, moment-timezone, node-webpmux, qs, tough-cookie, yt-search, fluent-ffmpeg, arabic-reshaper, @vitalets/google-translate-api وغيرهم.

const { deps } = require("@prototype/telegram");   // lazy getters — مفيش حاجة بتتحمل إلا لما تستخدمها
const { Chess } = deps["chess.js"];

Requires Node >= 22 (chalk@6, [email protected], [email protected], mime@4 … حزم ESM بتتحمل عن طريق require()).

0.1.3 / 0.1.4 modules (opt-in by name — modules: true does not enable them)

const { createBot, createScene, Stage, inlineKeyboard } = require("@prototypevip/telegram");

const bot = createBot(process.env.BOT_TOKEN, {
  modules: [
    "antiflood", "welcome", "serviceCleaner",
    ["session", { storage: "sqlite", store: require("@prototypevip/telegram").createSqliteStore("./data") }],
    "retry", "logger",
  ],
});

// wizard: .step() = one step per update, ctx.scene.next() moves on; .command()/.on() are scene-wide
const reg = createScene("register")
  .enter((ctx) => ctx.reply("اسمك؟"))
  .command("cancel", async (ctx) => { await ctx.reply("تم الإلغاء"); await ctx.scene.leave(); })
  .step(async (ctx) => { ctx.scene.session.name = ctx.message.text; await ctx.reply("سنك؟"); ctx.scene.next(); })
  .step(async (ctx) => { await ctx.reply(`تم: ${ctx.scene.session.name} / ${ctx.message.text}`); await ctx.scene.leave(); });

bot.use(new Stage([reg]).middleware());
bot.command("register", (ctx) => ctx.scene.enter("register"));
bot.command("menu", (ctx) => ctx.reply("اختر:", { reply_markup: inlineKeyboard().text("OK", "ok").style("success").text("رجوع", "back") }));

Webhook: require("@prototypevip/telegram").webhook.webhookCallback(bot, { secretToken, timeoutMs }) (calls bot.init() for you).