rubika 1.2.5 → 1.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +233 -27
- package/bot/index.ts +1 -2
- package/client/methods/contacts/getContacts.ts +1 -1
- package/package.json +16 -6
package/README.md
CHANGED
|
@@ -1,28 +1,73 @@
|
|
|
1
|
-
<
|
|
2
|
-
|
|
3
|
-
<p><b>فریمورک قدرتمند و پرسرعت جاوااسکریپت برای ربات/سلفهای روبیکا</b></p>
|
|
4
|
-
</p>
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>🚀 Rubika Framework</h1>
|
|
5
3
|
|
|
6
|
-
|
|
4
|
+
کتابخونه قدرتمند، مدرن و پرسرعت تایپاسکریپت برای ربات/سلفهای روبیکا و شاد
|
|
5
|
+
|
|
6
|
+
[](https://www.npmjs.com/package/rubika)
|
|
7
|
+
[](https://github.com/hadi-rostami/rubika-bot/blob/master/LICENSE)
|
|
8
|
+
[](https://www.npmjs.com/package/rubika)
|
|
9
|
+
[](https://github.com/hadi-rostami/rubika-bot/stargazers)
|
|
7
10
|
|
|
8
|
-
|
|
11
|
+
</div>
|
|
9
12
|
|
|
10
|
-
|
|
11
|
-
با معماری **Filter-Base** و **Type-Safe**، شما میتوانید:
|
|
13
|
+
## 📖 معرفی rubika
|
|
12
14
|
|
|
13
|
-
-
|
|
14
|
-
- سیستم فرماندهی و مدیریت پیام حرفهای داشته باشید.
|
|
15
|
-
- با قابلیت **اسکِیبل و قابل گسترش**، پروژههای بزرگ هم مدیریت کنید.
|
|
15
|
+
`Rubika` یک کتابخونه متنباز (Open-Source)، سبک و کاملاً غیرهمزمان (Asynchronous) مبتنی بر Bun است که برای ساخت رباتها و سلفباتهای پیامرسانهای روبیکا و شاد توسعه یافته است. این کتابخونه با معماری Filter-Base و Type-Safe، هستهای قدرتمند برای مدیریت پیامها، فرمانها و رویدادها فراهم میکند و به توسعهدهندگان امکان میدهد اپلیکیشنهای مقیاسپذیر (Scalable) و با قابلیت نگهداری بالا (Maintainable) بسازند.
|
|
16
16
|
|
|
17
17
|
---
|
|
18
18
|
|
|
19
|
-
##
|
|
19
|
+
## ✨ ویژگیهای کلیدی
|
|
20
|
+
|
|
21
|
+
| دستهبندی | ویژگی | شرح |
|
|
22
|
+
| :------------ | :------------------ | :-------------------------------------------------------------------------------------- |
|
|
23
|
+
| **عملکرد** | Super-Speed | معماری غیرهمزمان (Async/Await) مبتنی بر Bun برای پاسخدهی سریع و مصرف حافظه کم |
|
|
24
|
+
| **امنیت** | Type-Safe | پشتیبانی کامل از TypeScript و JSDoc برای جلوگیری از خطاهای رایج و بهبود تجربه توسعه |
|
|
25
|
+
| **فیلترینگ** | Filter-Base | سیستم فیلترینگ چندلایه و قابل ترکیب (Composable) برای مدیریت دقیق و انعطافپذیر پیامها |
|
|
26
|
+
| **معماری** | Modular | ساختار ماژولار، سیستم پلاگین (Plugin System) و قابلیت گسترش بینهایت |
|
|
27
|
+
| **چندسکویی** | Multi-Application | پشتیبانی همزمان از پیامرسانهای روبیکا و شاد با یک کدبیس واحد |
|
|
28
|
+
| **فرمانها** | Command System | سیستم مسیریابی فرمان (Command Routing) قدرتمند با پشتیبانی از الگوهای داینامیک |
|
|
29
|
+
| **ابزارها** | Built-in Utils | ابزارهای داخلی غنی مانند Bold(), Italic(), Code() و غیره برای فرمتبندی متن |
|
|
30
|
+
| **دیپلویمنت** | Flexible Deployment | قابلیت اجرا در کنار وبسرور، Serverless و Docker |
|
|
31
|
+
|
|
32
|
+
## 🏗️ معماری فیلتر پیامها
|
|
33
|
+
|
|
34
|
+
Rubika از معماری Filter-Pipeline بهره میبرد که در آن هر پیام ورودی از زنجیرهای از فیلترها عبور میکند. این رویکرد امکان پردازش مرحلهای و مقیاسپذیر پیامها را فراهم میآورد:
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
bot.on(
|
|
38
|
+
"message",
|
|
39
|
+
[
|
|
40
|
+
Filters.isText, // فیلتر ۱: فقط پیامهای متنی
|
|
41
|
+
Filters.isGroup, // فیلتر ۲: فقط گروهها
|
|
42
|
+
],
|
|
43
|
+
async (ctx) => {
|
|
44
|
+
await ctx.reply("پیام شما در گروه دریافت شد.");
|
|
45
|
+
},
|
|
46
|
+
);
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
- نکته: برای دیدن مثال های بیشتر از فیلتر پیام ها در rubika میتوانید داکیومنت [فیلترهای پیشرفته](https://docs.hr-dev.ir/docs/bot/advanced-concepts/advanced-filters) را مطالعه نمایید.
|
|
50
|
+
|
|
51
|
+
## 📦 نصب و راهاندازی سریع
|
|
20
52
|
|
|
21
53
|
```bash
|
|
54
|
+
# use bunjs
|
|
22
55
|
bun add rubika
|
|
56
|
+
|
|
57
|
+
# or with npm
|
|
58
|
+
npm install rubika
|
|
23
59
|
```
|
|
24
60
|
|
|
25
|
-
##
|
|
61
|
+
## پیشنیازها
|
|
62
|
+
|
|
63
|
+
- رانتایم Bun نسخه ۱.۰ یا بالاتر (یا Node.js نسخه ۱۸+)
|
|
64
|
+
- توکن/اکانت ربات از روبیکا یا اکانت شاد
|
|
65
|
+
|
|
66
|
+
## راهنمای ربات (Bot)
|
|
67
|
+
|
|
68
|
+
رباتها با استفاده از کلاس Bot ایجاد میشوند و از طریق وبهوک یا Polling با سرور ارتباط برقرار میکنند.
|
|
69
|
+
|
|
70
|
+
### مثال پایه
|
|
26
71
|
|
|
27
72
|
```ts
|
|
28
73
|
import Bot, { Filters } from "rubika/bot";
|
|
@@ -42,10 +87,77 @@ bot.on("error", async (err) => {
|
|
|
42
87
|
console.log(err.message);
|
|
43
88
|
});
|
|
44
89
|
|
|
90
|
+
// use poling
|
|
45
91
|
bot.run();
|
|
92
|
+
|
|
93
|
+
// or use webhook
|
|
94
|
+
bot.run(WEBHOOK_URL, HOST, PORT);
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## کار با Context
|
|
98
|
+
|
|
99
|
+
هر هندلر یک شیء Context دریافت میکند که شامل تمام اطلاعات پیام، فرستنده و متدهای پاسخ است:
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
import { Bot, Utils, ButtonTypeEnum } from "rubika/bot";
|
|
103
|
+
|
|
104
|
+
const bot = new Bot("TOKEN_BOT");
|
|
105
|
+
|
|
106
|
+
bot.on("update", async (ctx) => {
|
|
107
|
+
// اطلاعات پیام
|
|
108
|
+
console.log(ctx.chat_id, ctx.type, ctx);
|
|
109
|
+
|
|
110
|
+
// اطلاعات فرستنده (در صورت پیام جدید)
|
|
111
|
+
if (ctx.new_message)
|
|
112
|
+
console.log(ctx.new_message.sender_id, ctx.new_message.sender_type);
|
|
113
|
+
|
|
114
|
+
// اطلاعات فرستنده (در صورت پیام ویراش)
|
|
115
|
+
if (ctx.updated_message)
|
|
116
|
+
console.log(ctx.updated_message.sender_id, ctx.updated_message.sender_type);
|
|
117
|
+
|
|
118
|
+
// نوع چت
|
|
119
|
+
// use "u0" --> User, "g0" --> Group, "c0" --> Channel
|
|
120
|
+
if (ctx.chat_id.startsWith("g0")) {
|
|
121
|
+
/* Your Codes */
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
// پاسخدهی
|
|
125
|
+
|
|
126
|
+
const keypad = {
|
|
127
|
+
rows: [
|
|
128
|
+
{
|
|
129
|
+
buttons: [
|
|
130
|
+
{
|
|
131
|
+
button_text: "ljkl",
|
|
132
|
+
id: "simple",
|
|
133
|
+
type: ButtonTypeEnum.Simple,
|
|
134
|
+
},
|
|
135
|
+
],
|
|
136
|
+
},
|
|
137
|
+
],
|
|
138
|
+
};
|
|
139
|
+
|
|
140
|
+
await ctx.reply("پاسخ ساده");
|
|
141
|
+
await ctx.reply("پاسخ با CHAT_KEYPAD", {
|
|
142
|
+
...keypad,
|
|
143
|
+
on_time_keyboard: false,
|
|
144
|
+
resize_keyboard: true,
|
|
145
|
+
});
|
|
146
|
+
await ctx.reply("پاسخ با INLINE_KEYPAD", undefined, keypad);
|
|
147
|
+
await ctx.replyImage("path/to/file", "پاسخ با تصویر");
|
|
148
|
+
|
|
149
|
+
// حذف پیام
|
|
150
|
+
await ctx.delete(); // `messae_id` اختیاری
|
|
151
|
+
|
|
152
|
+
// فرمتبندی
|
|
153
|
+
await ctx.reply(Utils.Bold("متن بولد"));
|
|
154
|
+
await ctx.reply(Utils.Italic("متن ایتالیک"));
|
|
155
|
+
});
|
|
46
156
|
```
|
|
47
157
|
|
|
48
|
-
|
|
158
|
+
- نکته: برای دریافت اطلاعات بیشتر درباره ایونت ها و ریزالت و نوع Context های دریافتی میتوانید این دو صفحه از داکیومنت ( [bot.on](https://docs.hr-dev.ir/docs/bot/events/on) , [bot.command](https://docs.hr-dev.ir/docs/bot/events/command) ) را مشاهده نمایید .
|
|
159
|
+
|
|
160
|
+
## راهنمای سلف (Self)
|
|
49
161
|
|
|
50
162
|
```ts
|
|
51
163
|
import Client from "rubika/client";
|
|
@@ -66,19 +178,113 @@ shad_client.run();
|
|
|
66
178
|
rubika_client.run();
|
|
67
179
|
```
|
|
68
180
|
|
|
69
|
-
##
|
|
181
|
+
## سیستم فرمانها (Command System)
|
|
182
|
+
|
|
183
|
+
سیستم فرماندهی Rubika از الگوهای استاتیک و داینامیک پشتیبانی میکند:
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
import { Bot, Filters } from "rubika/bot";
|
|
187
|
+
|
|
188
|
+
const bot = new Bot("TOKEN_BOT");
|
|
189
|
+
|
|
190
|
+
// normal command
|
|
191
|
+
bot.command("/start", async (ctx) => {
|
|
192
|
+
await ctx.reply("به ربات خوش آمدید!");
|
|
193
|
+
});
|
|
194
|
+
|
|
195
|
+
// command with regex
|
|
196
|
+
bot.command(
|
|
197
|
+
/^\/sum_(?<a>\d+)_(?<b>\d+)$/,
|
|
198
|
+
[Filters.isNewMessage],
|
|
199
|
+
async (ctx) => {
|
|
200
|
+
// use find key
|
|
201
|
+
const text = Filters.findKey(ctx, "text");
|
|
202
|
+
|
|
203
|
+
const [a, b] = text.split("_").slice(1);
|
|
204
|
+
await ctx.reply(`${a} + ${b} = ${Number(a) + Number(b)}`);
|
|
205
|
+
},
|
|
206
|
+
);
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## فیلترهای سفارشی
|
|
210
|
+
|
|
211
|
+
می توانید فیلتر دلخواه خود را بسازید. فیلترها تابعهایی هستند که یک context را گرفته و true یا false برمیگردانند.
|
|
212
|
+
```ts
|
|
213
|
+
import Bot, { Filters } from "rubika/bot";
|
|
214
|
+
|
|
215
|
+
const bot = new Bot("YOUR_TOKEN");
|
|
216
|
+
|
|
217
|
+
const isAdmin = (ctx) => {
|
|
218
|
+
const adminIds = ["123", "456"];
|
|
219
|
+
return adminIds.includes(ctx.new_message?.sender_id);
|
|
220
|
+
};
|
|
221
|
+
|
|
222
|
+
bot.on("update", [Filters.isNewMessage, isAdmin], async (ctx) => {
|
|
223
|
+
await ctx.reply("شما ادمین هستید!");
|
|
224
|
+
});
|
|
225
|
+
|
|
226
|
+
bot.run();
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
### استفاده از ctx.store در فیلترها
|
|
230
|
+
|
|
231
|
+
میتوانید دادههایی را بین فیلترها و هندلر منتقل کنید:
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
import Bot, { Contexts, Filters } from "rubika/bot";
|
|
235
|
+
|
|
236
|
+
const bot = new Bot("YOUR_TOKEN");
|
|
237
|
+
const adminIds = ["admin_id"];
|
|
238
|
+
|
|
239
|
+
type StoreType = {
|
|
240
|
+
isAdmin: boolean;
|
|
241
|
+
};
|
|
242
|
+
|
|
243
|
+
const isAdmin = (ctx: Contexts.Update<StoreType>) => {
|
|
244
|
+
if (ctx?.new_message)
|
|
245
|
+
ctx.store.isAdmin = adminIds.includes(ctx.new_message?.sender_id);
|
|
246
|
+
return true;
|
|
247
|
+
};
|
|
248
|
+
|
|
249
|
+
bot.on<StoreType, "update">("update", [Filters.isNewMessage, isAdmin], async (ctx) => {
|
|
250
|
+
if (ctx.store.isAdmin) await ctx.reply("شما ادمین هستید!");
|
|
251
|
+
});
|
|
252
|
+
|
|
253
|
+
bot.run();
|
|
254
|
+
```
|
|
255
|
+
## 🌐 مقایسه با سایر کتابخانههای روبیکا (بر اساس مستندات موجود)
|
|
256
|
+
|
|
257
|
+
> **نکته:** این جدول صرفاً برای آشنایی با تفاوتهای کلی طراحی شده و ممکن است برخی کتابخانهها در نسخههای جدیدتر ویژگیهایی را اضافه کرده باشند. به همه پروژههای متنباز احترام میگذاریم.
|
|
258
|
+
|
|
259
|
+
| ویژگی | Rubika | RubJS | rubika-bot-x | jsrubi | Rubibot |
|
|
260
|
+
| :--- | :---: | :---: | :---: | :---: | :---: |
|
|
261
|
+
| **پلتفرم هدف** | روبیکا + شاد | روبیکا | روبیکا | روبیکا | روبیکا |
|
|
262
|
+
| **معماری اصلی** | Filter-Pipeline | Filter-Base | Command-Handler | Callback-Based | Event-Driven |
|
|
263
|
+
| **پشتیبانی از TypeScript** | ✅ کامل (بومی + JSDoc) | ✅ کامل | ❌ ندارد | ❌ ندارد | ❌ ندارد |
|
|
264
|
+
| **کار با چند پیامرسان** | ✅ (روبیکا و شاد) | ❌ فقط روبیکا | ❌ | ❌ | ❌ |
|
|
265
|
+
| **سیستم فرمان (Command Router)** | ✅ پیشرفته (Regex, Params) | ✅ پیشرفته | ✅ ساده | ❌ دستی | ❌ |
|
|
266
|
+
| **فیلترهای پیام** | ✅ چندلایه و ترکیبی | ✅ دارد | ❌ ندارد | ⚠️ محدود | ❌ ندارد |
|
|
267
|
+
| **Context پیشرفته** | ✅ (reply, edit, delete, utils) | ✅ دارد | ✅ پایه | ❌ | ❌ |
|
|
268
|
+
| **فرمتکننده داخلی متن** | ✅ (bold, italic, code و ...) | ✅ دارد | ❌ ندارد | ❌ | ❌ |
|
|
269
|
+
| **مدیریت خطا (Error Handling)** | ✅ سراسری (Catch) | ⚠️ وجود دارد | ⚠️ محدود | ❌ ندارد | ❌ |
|
|
270
|
+
| **پشتیبانی از Webhook** | ✅ دارد | ✅ دارد | ❌ ندارد | ❌ ندارد | ❌ |
|
|
271
|
+
| **سیستم پلاگین** | ❌ (در برنامه) | ✅ دارد | ❌ ندارد | ❌ ندارد | ❌ |
|
|
272
|
+
| **آخرین بروزرسانی** | فعال (2026) | فعال (2025) | غیرفعال (2024) | غیرفعال (2024) | متوقف (2023) |
|
|
273
|
+
| **مستندات فارسی** | ✅ کامل + مثال | ✅ پایه | ⚠️ انگلیسی | ⚠️ ناقص | ❌ ندارد |
|
|
274
|
+
|
|
275
|
+
# 📚 مستندات و منابع
|
|
276
|
+
|
|
277
|
+
| منبع | لینک |
|
|
278
|
+
| :--- | :--- |
|
|
279
|
+
| 📦 npm | [npmjs.com/package/rubika](https://npmjs.com/package/rubika) |
|
|
280
|
+
| 💻 گیتهاب | [github.com/hadi-rostami/rubika-bot](https://github.com/hadi-rostami/rubika-bot) |
|
|
281
|
+
| 📢 کانال تلگرام | [t.me/rubikats_channel](https://t.me/rubikats_channel) |
|
|
282
|
+
| 💬 کانال روبیکا | [rubika.ir/rubika_ts](https://rubika.ir/rubika_ts) |
|
|
283
|
+
| 📖 مستندات کامل | [docs.hr-dev.ir](https://docs.hr-dev.ir) |
|
|
284
|
+
| 🐛 گزارش باگ | [GitHub Issues](https://github.com/hadi-rostami/rubika-bot/issues) |
|
|
70
285
|
|
|
71
|
-
| ویژگی | توضیح |
|
|
72
|
-
| -------------------- | ---------------------------------------------- |
|
|
73
|
-
| ⚡ Super-Speed | استفاده از معماری غیرهمزمان برای پاسخدهی سریع |
|
|
74
|
-
| 🛡️ Type-Safe | کمک به جلوگیری از خطاهای متداول جاوااسکریپت |
|
|
75
|
-
| 🔧 Filter-Base | سیستم فیلترینگ قدرتمند برای مدیریت پیامها |
|
|
76
|
-
| 📂 Modular | ساختار ماژولار و قابل گسترش |
|
|
77
|
-
| 🈸 Multi Application | ساخت ربات های روبیکایی و شاد |
|
|
78
286
|
|
|
79
|
-
##
|
|
287
|
+
## 📄 مجوز
|
|
288
|
+
این پروژه تحت مجوز **MIT** منتشر شده است.
|
|
80
289
|
|
|
81
|
-
- [
|
|
82
|
-
- [لینک npm](https://www.npmjs.com/package/rubika)
|
|
83
|
-
- [تلگرام](https://t.me/rubikajs_channel)
|
|
84
|
-
- [روبیکا](https://rubika.ir/rubika_js)
|
|
290
|
+
- برای جزئیات به فایل [LICENSE](LICENSE) مراجعه کنید.
|
package/bot/index.ts
CHANGED
|
@@ -2,11 +2,10 @@ import Bot from "./bot";
|
|
|
2
2
|
import { AntiSpam } from "./utils";
|
|
3
3
|
import Filters from "./filters";
|
|
4
4
|
import Utils from "../utils/formater";
|
|
5
|
-
|
|
5
|
+
export * from "./types/enums";
|
|
6
6
|
export * as Contexts from "./contexts";
|
|
7
7
|
export * from "../utils";
|
|
8
8
|
|
|
9
9
|
|
|
10
10
|
export default Bot;
|
|
11
11
|
export { Bot, Filters, Utils, AntiSpam };
|
|
12
|
-
export type { Enums };
|
package/package.json
CHANGED
|
@@ -1,14 +1,24 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rubika",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.6",
|
|
4
4
|
"author": "Hadi Rostami",
|
|
5
5
|
"main": "index.ts",
|
|
6
|
-
"description": "A modern library for Rubika
|
|
6
|
+
"description": "A modern, high-performance TypeScript library for building bots and self-bots on Rubika and Shad messaging platforms.",
|
|
7
7
|
"keywords": [
|
|
8
|
-
"
|
|
9
|
-
"
|
|
8
|
+
"rubika",
|
|
9
|
+
"shad",
|
|
10
|
+
"bot",
|
|
11
|
+
"self-bot",
|
|
12
|
+
"library",
|
|
13
|
+
"typescript",
|
|
14
|
+
"async",
|
|
10
15
|
"bun",
|
|
11
|
-
"
|
|
16
|
+
"nodejs",
|
|
17
|
+
"messaging",
|
|
18
|
+
"automation",
|
|
19
|
+
"rubika-bot",
|
|
20
|
+
"shad-bot",
|
|
21
|
+
"api"
|
|
12
22
|
],
|
|
13
23
|
"license": "MIT",
|
|
14
24
|
"type": "module",
|
|
@@ -17,4 +27,4 @@
|
|
|
17
27
|
"node-rsa": "^1.1.1",
|
|
18
28
|
"user-agents": "^1.1.669"
|
|
19
29
|
}
|
|
20
|
-
}
|
|
30
|
+
}
|