balebaazoo 1.2.2 → 1.4.0

package/README.md

@@ -6,7 +6,7 @@ SDK مدرن و type-safe برای توسعهٔ بازو (Bot) در پیام‌
 
 بر پایهٔ [مستندات رسمی API بازوی بله](https://docs.bale.ai/) ساخته شده است.
 
-**English:** [README.en.md](README.en.md) · **مستندات فارسی:** [docs/fa/usage.md](docs/fa/usage.md)
+**English:** [README.en.md](README.en.md) · **مستندات فارسی:** [docs/fa/usage.md](docs/fa/usage.md) · **سایت مستندات:** https://hadimardanian.github.io/baleBaazooSDK/fa/usage.html
 
 ## نصب
 
@@ -48,11 +48,13 @@ void bot.start({
 
 </div>
 
-> **نکته:** `bot.start()` تا زمان `bot.stop()` ادامه دارد. برای لاگ بعد از راه‌اندازی از `onStart` استفاده کنید، نه `await` بعد از `start()`.
+<blockquote dir="rtl">
+<p><strong>نکته:</strong> تابع <code dir="ltr">bot.start()</code> تا زمان <code dir="ltr">bot.stop()</code> ادامه دارد. برای لاگ بعد از راه‌اندازی از <code dir="ltr">onStart</code> استفاده کنید، نه <code dir="ltr">await</code> بعد از <code dir="ltr">start()</code>.</p>
+</blockquote>
 
 ## TypeScript
 
-پروژهٔ شما باید ESM باشد:
+<p dir="rtl">پروژهٔ شما باید <code dir="ltr">ESM</code> باشد:</p>
 
 <div dir="ltr">
 
@@ -79,15 +81,15 @@ void bot.start({
 
 </div>
 
-قالب آماده: [`templates/starter`](templates/starter)
+<p dir="rtl">قالب آماده: <a href="templates/starter"><code dir="ltr">templates/starter</code></a></p>
 
 ### خطای TS1295
 
-اگر `ECMAScript imports and exports cannot be written in a CommonJS file` دیدید، `"type": "module"` را به `package.json` اضافه کنید.
+<p dir="rtl">اگر خطای <code dir="ltr">ECMAScript imports and exports cannot be written in a CommonJS file</code> دیدید، <code dir="ltr">"type": "module"</code> را به <code dir="ltr">package.json</code> اضافه کنید.</p>
 
-### خطای TS2322 با `ctx.reply()`
+### خطای TS2322 با ctx.reply
 
-نسخهٔ `1.0.1+` اجازه می‌دهد handler مستقیماً `ctx.reply()` را return کند:
+<p dir="rtl">نسخهٔ <code dir="ltr">1.0.1+</code> اجازه می‌دهد handler مستقیماً <code dir="ltr">ctx.reply()</code> را return کند:</p>
 
 <div dir="ltr">
 
@@ -113,19 +115,23 @@ bot.command("start", (ctx) => ctx.reply("سلام!"));
 
 ## ویژگی‌ها
 
-- **Type-safe** — تایپ‌های کامل TypeScript
-- **Middleware** — `Composer`، `bot.catch()`، `errorHandler`
-- **Lifecycle** — `onStart`، `setupGracefulShutdown`، `dropPendingUpdates`، `launch()`
-- **Polling و Webhook** — long polling با AbortSignal و webhook handler
-- **Bale-native** — `askReview`، `inquireTransaction`، کیف‌پول
-- **بدون dependency** — Node.js 18+
+<ul dir="rtl">
+<li><strong>Type-safe</strong> — تایپ‌های کامل TypeScript</li>
+<li><strong>Middleware</strong> — <code dir="ltr">Composer</code>، <code dir="ltr">bot.catch()</code>، <code dir="ltr">errorHandler</code></li>
+<li><strong>Lifecycle</strong> — <code dir="ltr">onStart</code>، <code dir="ltr">setupGracefulShutdown</code>، <code dir="ltr">dropPendingUpdates</code>، <code dir="ltr">launch()</code></li>
+<li><strong>Polling و Webhook</strong> — long polling با AbortSignal و webhook handler</li>
+<li><strong>Bale-native</strong> — <code dir="ltr">askReview</code>، <code dir="ltr">inquireTransaction</code>، کیف‌پول</li>
+<li><strong>بدون dependency</strong> — Node.js 18+</li>
+</ul>
 
 ## مثال‌ها
 
-- [`examples/echo-bot.ts`](examples/echo-bot.ts)
-- [`examples/inline-keyboard.ts`](examples/inline-keyboard.ts)
-- [`examples/payment-bot.ts`](examples/payment-bot.ts)
-- [`examples/webhook-server.ts`](examples/webhook-server.ts)
+<ul dir="rtl">
+<li><a href="examples/echo-bot.ts"><code dir="ltr">examples/echo-bot.ts</code></a></li>
+<li><a href="examples/inline-keyboard.ts"><code dir="ltr">examples/inline-keyboard.ts</code></a></li>
+<li><a href="examples/payment-bot.ts"><code dir="ltr">examples/payment-bot.ts</code></a></li>
+<li><a href="examples/webhook-server.ts"><code dir="ltr">examples/webhook-server.ts</code></a></li>
+</ul>
 
 ## توسعه
 

package/dist/index.cjs

@@ -416,7 +416,13 @@ var Api = class {
     return this.call("answerPreCheckoutQuery", asParams(params));
   }
   inquireTransaction(params) {
-    return this.call("inquireTransaction", asParams(params));
+    const transactionId = params.transaction_id || params.provider_payment_charge_id;
+    if (!transactionId) {
+      throw new Error("transaction_id is required for inquireTransaction");
+    }
+    return this.call("inquireTransaction", {
+      transaction_id: transactionId
+    });
   }
 };
 function asParams(params) {
@@ -473,6 +479,13 @@ function matchUpdate(update) {
   const matches = [];
   if (update.message) {
     matches.push("message");
+    if (update.message.animation) matches.push("message:animation");
+    if (update.message.new_chat_members?.length) {
+      matches.push("message:new_chat_members");
+    }
+    if (update.message.left_chat_member) {
+      matches.push("message:left_chat_member");
+    }
     if (update.message.text !== void 0) matches.push("message:text");
     if (update.message.photo) matches.push("message:photo");
     if (update.message.document) matches.push("message:document");
@@ -532,20 +545,32 @@ function matchesChatType(ctx, chatType) {
 
 // src/composer.ts
 var Composer = class _Composer {
-  handler;
   registered = [];
+  dirty = true;
+  snapshot = [];
+  cachedHandler;
   constructor(...middleware) {
     this.registered.push(...middleware.map(normalizeMiddleware));
-    this.handler = async (ctx, next) => {
-      await runMiddleware(this.registered, ctx);
-      await next();
-    };
+    this.markDirty();
+  }
+  markDirty() {
+    this.dirty = true;
+    this.cachedHandler = void 0;
   }
   middleware() {
-    return this.handler;
+    if (!this.cachedHandler || this.dirty) {
+      this.snapshot = [...this.registered];
+      this.cachedHandler = async (ctx, next) => {
+        await runMiddleware(this.snapshot, ctx);
+        await next();
+      };
+      this.dirty = false;
+    }
+    return this.cachedHandler;
   }
   use(...middleware) {
     this.registered.push(...middleware.map(normalizeMiddleware));
+    this.markDirty();
     return this;
   }
   on(filter, ...middleware) {
@@ -569,6 +594,7 @@ var Composer = class _Composer {
       );
     });
     composer.registered.push(...middleware);
+    this.markDirty();
     return this;
   }
   command(command, ...middleware) {
@@ -623,6 +649,17 @@ var Composer = class _Composer {
       ...middleware
     );
   }
+  static compose(...composers) {
+    const result = new _Composer();
+    for (const item of composers) {
+      if (item instanceof _Composer) {
+        result.use(item);
+      } else {
+        result.use(item);
+      }
+    }
+    return result;
+  }
 };
 function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -635,6 +672,8 @@ var Context = class {
   botInfo;
   callbackQueryAnswered = false;
   _updateTypes;
+  session = {};
+  state = {};
   constructor(options) {
     this.api = options.api;
     this.update = options.update;
@@ -733,6 +772,54 @@ var Context = class {
     const chatId = this.requireChatId();
     return this.api.sendInvoice({ chat_id: chatId, ...params });
   }
+  targetMessage() {
+    return this.callbackQuery?.message ?? this.message;
+  }
+  async editMessageText(text, extra) {
+    const message = this.targetMessage();
+    if (!message) {
+      throw new Error("No message to edit in context");
+    }
+    return this.api.editMessageText({
+      chat_id: message.chat.id,
+      message_id: message.message_id,
+      text,
+      ...extra
+    });
+  }
+  async deleteMessage(params) {
+    const message = this.targetMessage();
+    const chatId = params?.chat_id ?? message?.chat.id ?? this.chatId;
+    const messageId = params?.message_id ?? message?.message_id;
+    if (chatId === void 0 || messageId === void 0) {
+      throw new Error("No message to delete in context");
+    }
+    return this.api.deleteMessage({ chat_id: chatId, message_id: messageId });
+  }
+  async forwardMessage(toChatId, params) {
+    const message = this.targetMessage();
+    if (!message && !params?.from_chat_id) {
+      throw new Error("No source message in context");
+    }
+    return this.api.forwardMessage({
+      chat_id: toChatId,
+      from_chat_id: params?.from_chat_id ?? message.chat.id,
+      message_id: params?.message_id ?? message.message_id,
+      ...params
+    });
+  }
+  async copyMessage(toChatId, params) {
+    const message = this.targetMessage();
+    if (!message && !params?.from_chat_id) {
+      throw new Error("No source message in context");
+    }
+    return this.api.copyMessage({
+      chat_id: toChatId,
+      from_chat_id: params?.from_chat_id ?? message.chat.id,
+      message_id: params?.message_id ?? message.message_id,
+      ...params
+    });
+  }
   async sendChatAction(action) {
     const chatId = this.requireChatId();
     return this.api.sendChatAction({ chat_id: chatId, action });
@@ -842,14 +929,7 @@ var PollingRunner = class {
           { signal }
         );
         this.backoffAttempt = 0;
-        for (const update of updates) {
-          this.offset = update.update_id + 1;
-          try {
-            await bot.handleUpdate(update);
-          } catch (error) {
-            onError(error);
-          }
-        }
+        await this.processUpdates(bot, updates, options, onError);
         if (updates.length === 0 && signal.aborted) {
           break;
         }
@@ -868,6 +948,34 @@ var PollingRunner = class {
       }
     }
   }
+  async processUpdates(bot, updates, options, onError) {
+    const concurrency = Math.max(1, options.concurrency ?? 1);
+    if (concurrency === 1) {
+      for (const update of updates) {
+        this.offset = update.update_id + 1;
+        try {
+          await bot.handleUpdate(update);
+        } catch (error) {
+          onError(error);
+        }
+      }
+      return;
+    }
+    let index = 0;
+    const workers = Array.from({ length: Math.min(concurrency, updates.length) }, async () => {
+      while (index < updates.length) {
+        const current = index++;
+        const update = updates[current];
+        this.offset = update.update_id + 1;
+        try {
+          await bot.handleUpdate(update);
+        } catch (error) {
+          onError(error);
+        }
+      }
+    });
+    await Promise.all(workers);
+  }
   setOffset(offset) {
     this.offset = offset;
   }
@@ -935,7 +1043,7 @@ async function webhookFromJson(bot) {
 // src/bot.ts
 var Bot = class extends Composer {
   api;
-  botInfo;
+  _botInfo;
   polling = new PollingRunner();
   autoAnswer;
   catchHandler;
@@ -943,17 +1051,23 @@ var Bot = class extends Composer {
     const api = new Api({ token, ...options });
     super();
     this.api = api;
-    this.botInfo = options.botInfo;
+    this._botInfo = options.botInfo;
     this.autoAnswer = options.autoAnswerCallback ?? true;
     if (this.autoAnswer) {
       this.use(autoAnswerCallback());
     }
   }
+  get telegram() {
+    return this.api;
+  }
+  get botInfo() {
+    return this._botInfo;
+  }
   async init() {
-    if (!this.botInfo) {
-      this.botInfo = await this.api.getMe();
+    if (!this._botInfo) {
+      this._botInfo = await this.api.getMe();
     }
-    return this.botInfo;
+    return this._botInfo;
   }
   catch(handler) {
     this.catchHandler = handler;
@@ -976,7 +1090,7 @@ var Bot = class extends Composer {
     return new Context({
       api: this.api,
       update,
-      botInfo: this.botInfo
+      botInfo: this._botInfo
     });
   }
   async start(options = {}) {
@@ -1007,7 +1121,7 @@ var Bot = class extends Composer {
     }
     if (options.onStart) {
       try {
-        await options.onStart(this.botInfo);
+        await options.onStart(this._botInfo);
       } catch (error) {
         onError(error);
         return;
@@ -1018,6 +1132,13 @@ var Bot = class extends Composer {
   launch(options) {
     return this.start(options);
   }
+  async switchToPolling(options = {}) {
+    await this.api.deleteWebhook();
+    await this.start({
+      ...options,
+      dropPendingUpdates: options.dropPendingUpdates ?? true
+    });
+  }
   async stop() {
     await this.polling.stop();
   }
@@ -1138,6 +1259,132 @@ function setupGracefulShutdown(bot, options = {}) {
   }
 }
 
+// src/scenes/index.ts
+var Scene = class extends Composer {
+  id;
+  enterMiddleware = [];
+  leaveMiddleware = [];
+  constructor(id, ...middleware) {
+    super(...middleware);
+    this.id = id;
+  }
+  enter(...middleware) {
+    this.enterMiddleware.push(...middleware);
+    return this;
+  }
+  leave(...middleware) {
+    this.leaveMiddleware.push(...middleware);
+    return this;
+  }
+  async runEnter(ctx) {
+    await runMiddleware(this.enterMiddleware, ctx);
+  }
+  async runLeave(ctx) {
+    await runMiddleware(this.leaveMiddleware, ctx);
+  }
+};
+var Stage = class extends Composer {
+  scenes = /* @__PURE__ */ new Map();
+  register(...scenes) {
+    for (const scene of scenes) {
+      this.scenes.set(scene.id, scene);
+    }
+    return this;
+  }
+  getScene(id) {
+    return this.scenes.get(id);
+  }
+  async enter(ctx, sceneId, state = {}) {
+    const scene = this.scenes.get(sceneId);
+    if (!scene) {
+      throw new Error(`Scene "${sceneId}" is not registered`);
+    }
+    const session2 = ctx.session;
+    const currentId = session2.__scene?.id;
+    if (currentId && currentId !== sceneId) {
+      const current = this.scenes.get(currentId);
+      if (current) {
+        await leaveScene(ctx, current);
+      }
+    }
+    await enterScene(ctx, sceneId, scene, state);
+  }
+  async leave(ctx) {
+    const session2 = ctx.session;
+    const sceneId = session2.__scene?.id;
+    if (!sceneId) return;
+    const scene = this.scenes.get(sceneId);
+    if (scene) {
+      await leaveScene(ctx, scene);
+    }
+  }
+  middleware() {
+    const sceneMiddleware = super.middleware();
+    return async (ctx, next) => {
+      const session2 = ctx.session;
+      const sceneId = session2.__scene?.id;
+      if (!sceneId) {
+        await sceneMiddleware(ctx, next);
+        return;
+      }
+      const scene = this.scenes.get(sceneId);
+      if (!scene) {
+        delete session2.__scene;
+        await sceneMiddleware(ctx, next);
+        return;
+      }
+      await scene.middleware()(ctx, next);
+    };
+  }
+};
+async function enterScene(ctx, sceneId, scene, initialState = {}) {
+  const session2 = ctx.session;
+  session2.__scene = { ...initialState, id: sceneId };
+  await scene.runEnter(ctx);
+}
+async function leaveScene(ctx, scene) {
+  const session2 = ctx.session;
+  await scene.runLeave(ctx);
+  delete session2.__scene;
+}
+
+// src/session/memory.ts
+function memorySessionStore() {
+  const data = /* @__PURE__ */ new Map();
+  return {
+    get: (key) => data.get(key),
+    set: (key, value) => {
+      data.set(key, value);
+    },
+    delete: (key) => {
+      data.delete(key);
+    }
+  };
+}
+
+// src/session/index.ts
+function session(options) {
+  const store = options.store ?? memorySessionStore();
+  return async (ctx, next) => {
+    const key = options.getSessionKey(ctx);
+    if (!key) {
+      await next();
+      return;
+    }
+    let current = store.get(key) ?? options.defaultSession(ctx);
+    Object.defineProperty(ctx, "session", {
+      configurable: true,
+      enumerable: true,
+      get: () => current,
+      set: (value) => {
+        current = value;
+      }
+    });
+    await next();
+    store.set(key, current);
+  };
+}
+
 exports.Api = Api;
 exports.BaleAPIError = BaleAPIError;
 exports.BaleError = BaleError;
@@ -1150,23 +1397,29 @@ exports.InlineKeyboard = InlineKeyboard;
 exports.InputFile = InputFile;
 exports.PollingRunner = PollingRunner;
 exports.ReplyKeyboard = ReplyKeyboard;
+exports.Scene = Scene;
+exports.Stage = Stage;
 exports.autoAnswerCallback = autoAnswerCallback;
 exports.bold = bold;
 exports.createWebhookHandler = createWebhookHandler;
+exports.enterScene = enterScene;
 exports.errorHandler = errorHandler;
 exports.extractCommand = extractCommand;
 exports.isFilePath = isFilePath;
 exports.isMiddlewareObject = isMiddlewareObject;
 exports.italic = italic;
+exports.leaveScene = leaveScene;
 exports.link = link;
 exports.matchUpdate = matchUpdate;
 exports.matchesAnyFilter = matchesAnyFilter;
 exports.matchesChatType = matchesChatType;
 exports.matchesFilter = matchesFilter;
 exports.md = md;
+exports.memorySessionStore = memorySessionStore;
 exports.normalizeMiddleware = normalizeMiddleware;
 exports.removeKeyboard = removeKeyboard;
 exports.runMiddleware = runMiddleware;
+exports.session = session;
 exports.setupGracefulShutdown = setupGracefulShutdown;
 exports.spoiler = spoiler;
 exports.webhookFromJson = webhookFromJson;