Rubigram 🤖

Rubigram یک فریم‌ورک مدرن، تایپ‌سیف و ماژولار برای توسعه ربات روبیکا با استفاده از Rubika Bot API، با امکانات پیشرفته و معماری قابل توسعه.

فهرست مطالب

• ویژگی‌ها
• نصب
• شروع سریع
• آموزش کامل استفاده
  • فرآیند پردازش میدل‌ویر
  • ذخیره‌سازی و مدیریت نشست
  • افزونه مدیریت گروه
• API مرجع
• تست و اجرا
• لایسنس

ویژگی‌ها

• ⚡ تایپ‌سیف و مدرن: پیاده‌سازی کامل TypeScript با بهره‌مندی از واردسازی ESM و تایپ‌های قوی.
• 🧩 گردش میدل‌ویر: معماری مشابه اکسپرس برای زنجیره‌‌سازی میدل‌ویرها با متدهای bot.use(), bot.command(), bot.hears() و bot.on().
• 💾 ذخیره‌ساز قابل پلاگین: پشتیبانی داخلی از MemoryStorage و SqliteStorage با امکان تعریف TTL و توسعه ذخیره‌ساز اختصاصی.
• 👥 پکیج مدیریت گروه: قابلیت‌های پیشرفته برای مدیریت گروه‌ها از جمله: قفل لینک، جستجوی پیام، میوت/آن‌میوت، هشدار و ردیابی اعضا.
• 🛡 دسترسی به API رسمی: بدون هیچ واسط یا پوشش غیراستاندارد و فقط با استفاده از Rubika Bot API رسمی.
• 📦 توسعه‌پذیری ماژولار: ایجاد افزونه و میدل‌ویر دلخواه و توسعه بسیار آسان.

نصب

برای نصب با استفاده از npm کافی است:

npm install rubigram

یا با استفاده از yarn:

yarn add rubigram

شروع سریع

یک ربات ساده بسازید:

import { Rubigram } from "rubigram";

const bot = new Rubigram("YOUR_BOT_TOKEN"); // توکن ربات‌تان را جایگزین کنید

// ثبت فرمان start
bot.command("start", async (ctx) => {
  await ctx.reply("سلام! به روبیگرام خوش آمدید 🎉");
});

// بازتاب پیام متنی
bot.on("message", async (ctx) => {
  if (ctx.text) {
    await ctx.reply(`شما گفتید: ${ctx.text}`);
  }
});

// آغاز دریافت پیام (Polling)
bot.start();

آموزش کامل استفاده

فرآیند پردازش میدل‌ویر

Rubigram قابلیت استفاده از میدل‌ویرهای چند مرحله‌ای و شخصی‌سازی شده را در اختیار شما می‌گذارد.
مثال:

bot.use(async (ctx, next) => {
  console.log(`[${ctx.chatId}] دریافت پیام!`);
  await next();
});

ذخیره‌سازی و مدیریت نشست (Session)

برای حفظ اطلاعات هر کاربر (مثلا شمارنده یا هر داده دلخواه):

import { Rubigram, session, SqliteStorage } from "rubigram";

// تایپ داده دلخواه برای هر نشست کاربر
interface MySessionData {
  counter: number;
}

const bot = new Rubigram("YOUR_BOT_TOKEN");
const storage = new SqliteStorage<MySessionData>({ path: "./sessions.db" });

bot.use(
  session({
    storage, // می‌توانید به‌جای Sqlite از MemoryStorage هم استفاده کنید
    initial: () => ({ counter: 0 }),
  }),
);

bot.command("count", async (ctx) => {
  ctx.session.counter += 1;
  await ctx.reply(`شمارشگر شما: ${ctx.session.counter}`);
});

bot.start();

توسعه ذخیره‌ساز سفارشی

با پیاده‌سازی interface مخصوص، می‌توانید ذخیره‌سازی اختصاصی خودتان را اضافه کنید.

افزونه مدیریت گروه (Group Management)

همراه Rubigram یک افزونه مدیریتی کامل برای گروه‌ها ارائه شده:

import { Rubigram, GroupManager, MemoryStorage } from "rubigram";

const bot = new Rubigram("YOUR_BOT_TOKEN");
const groupManager = new GroupManager(new MemoryStorage());

// اتصال میدل‌ویر افزونه
bot.use(groupManager.middleware());

// مثال: قفل اشتراک‌گذاری لینک
bot.command("lock_link", async (ctx) => {
  if (ctx.chatId) {
    await groupManager.setLockLink(ctx.chatId, true);
    await ctx.reply("🔒 اشتراک‌گذاری لینک در این گروه قفل شد.");
  }
});

bot.start();

قابلیت‌های گروه: قفل لینک/فایل/تصویر،‌ هشدار، میوت و ... (مستندات بیشتر: docs/group-management.md)

API مرجع

Rubigram مبتنی بر TypeScript است و تمام اینترفیس‌ها، تایپ‌ها و متدهای مهم به صورت کامل مستندسازی شده‌اند.
برخی کلاس‌ها و متدهای کلیدی:

• Rubigram: کلاس اصلی ربات
• bot.command(name, handler): ثبت دستور بات (مانند فرمان start)
• bot.on(type, handler): دریافت انواع رویدادها مثل پیام
• ctx.reply(text, [options]): ارسال پیام
• session({storage, initial}): راه‌اندازی نشست کاربر
• GroupManager: مدیریت پیشرفته گروه
• و ...

برای مشاهده مستندات کامل تایپ‌ها به types.ts مراجعه کنید.

تست و اجرا

• اجرای پروژه:
  فایلتان را با node اجرا کنید (مثلا: node bot.js یا با ts-node برای پروژه‌های TypeScript).
• اگر Bot Token معتبر باشد، ربات شروع به دریافت و پاسخ به پیام‌ها خواهد کرد.

سوالات رایج

• آیا می‌توان چند میدل‌ویر زنجیره‌ای تعریف کرد؟ بله، هر تعداد دلخواه میدل‌ویر قابل اضافه شدن است و ترتیب اجرا رعایت می‌شود.
• ذخیره‌سازی کجاست؟
  به صورت پیش‌فرض MemoryStorage ارایه شده، اما برای ذخیره‌سازی پایدار SQLite یا هر ذخیره‌ساز دلخواه قابل استفاده است.
• آیا امکان توسعه افزونه وجود دارد؟
  بله، معماری کاملا باز و توسعه‌پذیر است.

لایسنس

MIT © Mani Lipour
این پروژه متن‌‌باز است و استفاده، توسعه و گسترش آن آزاد می‌باشد.