rubika

v1.2.6

Published

3 months ago

A modern, high-performance TypeScript library for building bots and self-bots on Rubika and Shad messaging platforms.

Downloads

102

0High
0Medium
0Low

hadirostami

rubika shad bot self-bot library typescript async bun nodejs messaging automation rubika-bot shad-bot api

کتابخونه قدرتمند، مدرن و پرسرعت تایپ‌اسکریپت برای ربات/سلف‌های روبیکا و شاد

📖 معرفی rubika

Rubika یک کتابخونه متن‌باز (Open-Source)، سبک و کاملاً غیرهمزمان (Asynchronous) مبتنی بر Bun است که برای ساخت ربات‌ها و سلف‌بات‌های پیام‌رسان‌های روبیکا و شاد توسعه یافته است. این کتابخونه با معماری Filter-Base و Type-Safe، هسته‌ای قدرتمند برای مدیریت پیام‌ها، فرمان‌ها و رویدادها فراهم می‌کند و به توسعه‌دهندگان امکان می‌دهد اپلیکیشن‌های مقیاس‌پذیر (Scalable) و با قابلیت نگهداری بالا (Maintainable) بسازند.

✨ ویژگی‌های کلیدی

🏗️ معماری فیلتر پیام‌ها

Rubika از معماری Filter-Pipeline بهره می‌برد که در آن هر پیام ورودی از زنجیره‌ای از فیلترها عبور می‌کند. این رویکرد امکان پردازش مرحله‌ای و مقیاس‌پذیر پیام‌ها را فراهم می‌آورد:

bot.on(
  "message",
  [
    Filters.isText, // فیلتر ۱: فقط پیام‌های متنی
    Filters.isGroup, // فیلتر ۲: فقط گروه‌ها
  ],
  async (ctx) => {
    await ctx.reply("پیام شما در گروه دریافت شد.");
  },
);

نکته: برای دیدن مثال های بیشتر از فیلتر پیام ها در rubika میتوانید داکیومنت فیلترهای پیشرفته را مطالعه نمایید.

📦 نصب و راه‌اندازی سریع

# use bunjs
bun add rubika

# or with npm
npm install rubika

پیش‌نیازها

رانتایم Bun نسخه ۱.۰ یا بالاتر (یا Node.js نسخه ۱۸+)
توکن/اکانت ربات از روبیکا یا اکانت شاد

راهنمای ربات (Bot)

ربات‌ها با استفاده از کلاس Bot ایجاد می‌شوند و از طریق وب‌هوک یا Polling با سرور ارتباط برقرار می‌کنند.

مثال پایه

import Bot, { Filters } from "rubika/bot";

const bot = new Bot("TOKEN_BOT");

bot.command("/start", async (ctx) => {
  await ctx.reply("🤖 ربات استارت شد");
});

bot.on("update", [Filters.isText], async (ctx) => {
  await ctx.reply("سلام 😎");
});

bot.on("error", async (err) => {
  await err.bot.sendMessage("CHAT_ID", err.message);
  console.log(err.message);
});

// use poling
bot.run();

// or use webhook
bot.run(WEBHOOK_URL, HOST, PORT);

کار با Context

هر هندلر یک شیء Context دریافت می‌کند که شامل تمام اطلاعات پیام، فرستنده و متدهای پاسخ است:

import { Bot, Utils, ButtonTypeEnum } from "rubika/bot";

const bot = new Bot("TOKEN_BOT");

bot.on("update", async (ctx) => {
  // اطلاعات پیام
  console.log(ctx.chat_id, ctx.type, ctx);

  // اطلاعات فرستنده (در صورت پیام جدید)
  if (ctx.new_message)
    console.log(ctx.new_message.sender_id, ctx.new_message.sender_type);

  // اطلاعات فرستنده (در صورت پیام ویراش)
  if (ctx.updated_message)
    console.log(ctx.updated_message.sender_id, ctx.updated_message.sender_type);

  // نوع چت
  // use "u0" --> User, "g0" --> Group, "c0" --> Channel
  if (ctx.chat_id.startsWith("g0")) {
    /* Your Codes */
  }

  // پاسخ‌دهی

  const keypad = {
    rows: [
      {
        buttons: [
          {
            button_text: "ljkl",
            id: "simple",
            type: ButtonTypeEnum.Simple,
          },
        ],
      },
    ],
  };

  await ctx.reply("پاسخ ساده");
  await ctx.reply("پاسخ با CHAT_KEYPAD", {
    ...keypad,
    on_time_keyboard: false,
    resize_keyboard: true,
  });
  await ctx.reply("پاسخ با INLINE_KEYPAD", undefined, keypad);
  await ctx.replyImage("path/to/file", "پاسخ با تصویر");

  // حذف پیام
  await ctx.delete(); // `messae_id` اختیاری

  // فرمت‌بندی
  await ctx.reply(Utils.Bold("متن بولد"));
  await ctx.reply(Utils.Italic("متن ایتالیک"));
});

نکته: برای دریافت اطلاعات بیشتر درباره ایونت ها و ریزالت و نوع Context های دریافتی میتوانید این دو صفحه از داکیومنت ( bot.on , bot.command ) را مشاهده نمایید .

راهنمای سلف (Self)

import Client from "rubika/client";

const shad_client = new Client("shad", "Shad");
const rubika_client = new Client("rubika", "Rubika");

// Shad
shad_client.on("message", async (ctx) => console.log(ctx));
shad_client.on("error", async (err) => console.log(err));

// Rubika
rubika_client.on("message", async (ctx) => console.log(ctx));
rubika_client.on("error", async (err) => console.log(err));

// start (self)-bots
shad_client.run();
rubika_client.run();

سیستم فرمان‌ها (Command System)

سیستم فرمان‌دهی Rubika از الگوهای استاتیک و داینامیک پشتیبانی می‌کند:

import { Bot, Filters } from "rubika/bot";

const bot = new Bot("TOKEN_BOT");

// normal command
bot.command("/start", async (ctx) => {
  await ctx.reply("به ربات خوش آمدید!");
});

// command with regex
bot.command(
  /^\/sum_(?<a>\d+)_(?<b>\d+)$/,
  [Filters.isNewMessage],
  async (ctx) => {
    // use find key
    const text = Filters.findKey(ctx, "text");

    const [a, b] = text.split("_").slice(1);
    await ctx.reply(`${a} + ${b} = ${Number(a) + Number(b)}`);
  },
);

فیلترهای سفارشی

می توانید فیلتر دلخواه خود را بسازید. فیلترها تابع‌هایی هستند که یک context را گرفته و true یا false برمی‌گردانند.

import Bot, { Filters } from "rubika/bot";

const bot = new Bot("YOUR_TOKEN");

const isAdmin = (ctx) => {
  const adminIds = ["123", "456"];
  return adminIds.includes(ctx.new_message?.sender_id);
};

bot.on("update", [Filters.isNewMessage, isAdmin], async (ctx) => {
  await ctx.reply("شما ادمین هستید!");
});

bot.run();

استفاده از ctx.store در فیلترها

می‌توانید داده‌هایی را بین فیلترها و هندلر منتقل کنید:

import Bot, { Contexts, Filters } from "rubika/bot";

const bot = new Bot("YOUR_TOKEN");
const adminIds = ["admin_id"];

type StoreType = {
  isAdmin: boolean;
};

const isAdmin = (ctx: Contexts.Update<StoreType>) => {
  if (ctx?.new_message)
    ctx.store.isAdmin = adminIds.includes(ctx.new_message?.sender_id);
  return true;
};

bot.on<StoreType, "update">("update", [Filters.isNewMessage, isAdmin], async (ctx) => {
  if (ctx.store.isAdmin) await ctx.reply("شما ادمین هستید!");
});

bot.run();

🌐 مقایسه با سایر کتابخانه‌های روبیکا (بر اساس مستندات موجود)

نکته: این جدول صرفاً برای آشنایی با تفاوت‌های کلی طراحی شده و ممکن است برخی کتابخانه‌ها در نسخه‌های جدیدتر ویژگی‌هایی را اضافه کرده باشند. به همه پروژه‌های متن‌باز احترام می‌گذاریم.

📚 مستندات و منابع

📄 مجوز

این پروژه تحت مجوز MIT منتشر شده است.

برای جزئیات به فایل LICENSE مراجعه کنید.