balebaazoo 1.0.0 → 1.2.0

package/README.en.md

@@ -13,13 +13,40 @@ npm install balebaazoo
 
 Requires Node.js 18+.
 
+## TypeScript setup
+
+If you see error **TS1295** (`import` in a CommonJS file), your project needs ESM config:
+
+**package.json**
+```json
+{
+  "type": "module"
+}
+```
+
+**tsconfig.json**
+```json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "verbatimModuleSyntax": true,
+    "types": ["node"]
+  }
+}
+```
+
+Use the ready-made template: [`templates/starter`](templates/starter)
+
 ## Quick start
 
 ```typescript
-import { Bot, InlineKeyboard } from "balebaazoo";
+import { Bot, InlineKeyboard, setupGracefulShutdown } from "balebaazoo";
 
 const bot = new Bot(process.env.BOT_TOKEN!);
 
+setupGracefulShutdown(bot);
+
 bot.command("start", (ctx) =>
   ctx.reply("Hello! Welcome to my bot.", {
     reply_markup: new InlineKeyboard().text("About", "about"),
@@ -31,14 +58,21 @@ bot.on("callback_query:data", async (ctx) => {
   await ctx.reply("More info...");
 });
 
-bot.start();
+void bot.start({
+  onStart: (me) => console.log(`Running as @${me.username ?? me.id}`),
+  onError: (error) => console.error(error),
+});
 ```
 
+> `bot.start()` blocks until `bot.stop()`. Use `onStart` for post-init logging.
+
 ## Features
 
 - Full Bale Bot API client with TypeScript types
 - Bot framework: middleware, filters, commands, composers
-- Polling and webhook support
+- Lifecycle: `onStart`, `setupGracefulShutdown`, `dropPendingUpdates`, `launch()`
+- Polling (with AbortSignal) and webhook support
+- `bot.catch()` and `errorHandler` middleware
 - Context shortcuts (`ctx.reply`, `ctx.replyWithPhoto`, ...)
 - Wallet payments, `askReview`, `inquireTransaction`
 - Zero runtime dependencies

package/README.md

@@ -1,3 +1,9 @@
+<div dir="rtl" lang="fa">
+
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vazirmatn@33.0.3/Vazirmatn-font-face.css">
+
+<div style="font-family: Vazirmatn, Tahoma, sans-serif;">
+
 # balebaazoo
 
 SDK مدرن و type-safe برای توسعهٔ بازو (Bot) در پیام‌رسان بله.
@@ -22,10 +28,12 @@ npm install balebaazoo
 ## شروع سریع
 
 ```typescript
-import { Bot, InlineKeyboard } from "balebaazoo";
+import { Bot, InlineKeyboard, setupGracefulShutdown } from "balebaazoo";
 
 const bot = new Bot(process.env.BOT_TOKEN!);
 
+setupGracefulShutdown(bot);
+
 bot.command("start", (ctx) =>
   ctx.reply("سلام! به بازو خوش آمدید 👋", {
     reply_markup: new InlineKeyboard().text("درباره ما", "about"),
@@ -37,18 +45,67 @@ bot.on("callback_query:data", async (ctx) => {
   await ctx.reply("اطلاعات بیشتر...");
 });
 
-bot.start();
+void bot.start({
+  onStart: (me) => console.log(`Running as @${me.username ?? me.id}`),
+  onError: (error) => console.error(error),
+});
+```
+
+> **نکته:** `bot.start()` تا زمان `bot.stop()` ادامه دارد. برای لاگ بعد از راه‌اندازی از `onStart` استفاده کنید، نه `await` بعد از `start()`.
+
+## TypeScript
+
+پروژهٔ شما باید ESM باشد:
+
+```json
+{
+  "type": "module"
+}
+```
+
+```json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "verbatimModuleSyntax": true,
+    "types": ["node"]
+  }
+}
+```
+
+قالب آماده: [`templates/starter`](templates/starter)
+
+### خطای TS1295
+
+اگر `ECMAScript imports and exports cannot be written in a CommonJS file` دیدید، `"type": "module"` را به `package.json` اضافه کنید.
+
+### خطای TS2322 با `ctx.reply()`
+
+نسخهٔ `1.0.1+` اجازه می‌دهد handler مستقیماً `ctx.reply()` را return کند:
+
+```typescript
+bot.command("start", (ctx) => ctx.reply("سلام!"));
+```
+
+### nodemon + TypeScript
+
+```json
+{
+  "watch": ["src"],
+  "ext": "ts,json",
+  "exec": "tsx src/bot.ts"
+}
 ```
 
 ## ویژگی‌ها
 
-- **Type-safe** — تایپ‌های کامل TypeScript برای API و handlerها
-- **Middleware** — سیستم middleware و `Composer` برای ساختار ماژولار
-- **Filter queries** — `message:text`، `callback_query:data`، `pre_checkout_query` و ...
-- **Shortcuts** — `ctx.reply()`، `ctx.replyWithPhoto()`، `ctx.answerCallbackQuery()`
-- **Polling و Webhook** — `bot.start()` و `webhookFromJson()`
-- **Bale-native** — `askReview`، `inquireTransaction`، کیف‌پول، Markdown بله
-- **بدون dependency** — فقط Node.js 18+ با fetch بومی
+- **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+
 
 ## مثال‌ها
 
@@ -68,3 +125,6 @@ npm test
 ## لایسنس
 
 GPL-3.0-or-later
+
+</div>
+</div>

package/dist/index.cjs

@@ -94,6 +94,9 @@ async function isFilePath(source) {
   if (source.startsWith("http://") || source.startsWith("https://")) {
     return false;
   }
+  if (!looksLikePath(source)) {
+    return false;
+  }
   try {
     const info = await promises.stat(source);
     return info.isFile();
@@ -101,6 +104,9 @@ async function isFilePath(source) {
     return false;
   }
 }
+function looksLikePath(source) {
+  return source.startsWith("./") || source.startsWith("../") || source.includes("/") || source.includes("\\");
+}
 
 // src/api/client.ts
 var DEFAULT_API_BASE = "https://tapi.bale.ai";
@@ -123,12 +129,15 @@ var Api = class {
   methodUrl(method) {
     return `${this.baseUrl}/bot${this.token}/${method}`;
   }
-  async call(method, params) {
+  async call(method, params, options) {
     let attempt = 0;
     while (true) {
       try {
-        return await this.invoke(method, params);
+        return await this.invoke(method, params, options);
       } catch (error) {
+        if (options?.signal?.aborted || isAbortError(error)) {
+          throw error;
+        }
         if (error instanceof BaleAPIError && error.errorCode === 429 && attempt < this.maxRetries) {
           const retryAfter = (error.parameters?.retry_after ?? 1) * 1e3;
           await sleep(retryAfter);
@@ -139,7 +148,7 @@ var Api = class {
       }
     }
   }
-  async invoke(method, params) {
+  async invoke(method, params, options) {
     const { body } = await this.prepareBody(params ?? {});
     const headers = {};
     if (!(body instanceof FormData)) {
@@ -149,7 +158,7 @@ var Api = class {
       method: "POST",
       headers,
       body: body instanceof FormData ? body : JSON.stringify(body ?? {})
-    });
+    }, options);
   }
   async downloadFile(filePath) {
     const url = `${this.fileBaseUrl}/${filePath}`;
@@ -191,8 +200,8 @@ var Api = class {
     }
     return { body: formData, isMultipart: true };
   }
-  async request(method, init) {
-    const response = await this.fetchWithRetry(this.methodUrl(method), init);
+  async request(method, init, options) {
+    const response = await this.fetchWithRetry(this.methodUrl(method), init, options);
     const payload = await response.json();
     if (!payload.ok) {
       throw new BaleAPIError(
@@ -203,12 +212,18 @@ var Api = class {
     }
     return payload.result;
   }
-  async fetchWithRetry(url, init) {
+  async fetchWithRetry(url, init, options) {
     let attempt = 0;
     let lastError;
     while (attempt <= this.maxRetries) {
+      if (options?.signal?.aborted) {
+        throw new DOMException("The operation was aborted", "AbortError");
+      }
       try {
-        const response = await this.fetchFn(url, init);
+        const response = await this.fetchFn(url, {
+          ...init,
+          signal: options?.signal
+        });
         if (response.status === 429) {
           const retryAfter = Number(response.headers.get("retry-after") ?? "1");
           await sleep(retryAfter * 1e3);
@@ -223,6 +238,9 @@ var Api = class {
         return response;
       } catch (error) {
         lastError = error;
+        if (isAbortError(error) || options?.signal?.aborted) {
+          throw error;
+        }
         if (attempt >= this.maxRetries) {
           break;
         }
@@ -238,8 +256,8 @@ var Api = class {
   getMe() {
     return this.call("getMe");
   }
-  getUpdates(params) {
-    return this.call("getUpdates", asParams(params));
+  getUpdates(params, options) {
+    return this.call("getUpdates", asParams(params), options);
   }
   setWebhook(params) {
     return this.call("setWebhook", asParams(params));
@@ -427,6 +445,9 @@ function appendFormValue(formData, key, value) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function isAbortError(error) {
+  return error instanceof Error && (error.name === "AbortError" || error.message.includes("aborted"));
+}
 
 // src/middleware/types.ts
 function isMiddlewareObject(value) {
@@ -497,12 +518,10 @@ function extractCommand(text) {
 
 // src/filters/query.ts
 function matchesFilter(ctx, filter) {
-  const updateMatches = matchUpdate(ctx.update);
-  return updateMatches.includes(filter);
+  return ctx.updateTypes.includes(filter);
 }
 function matchesAnyFilter(ctx, filters) {
-  const updateMatches = matchUpdate(ctx.update);
-  return filters.some((filter) => updateMatches.includes(filter));
+  return filters.some((filter) => ctx.updateTypes.includes(filter));
 }
 function matchesChatType(ctx, chatType) {
   const chat = ctx.chat;
@@ -615,6 +634,7 @@ var Context = class {
   update;
   botInfo;
   callbackQueryAnswered = false;
+  _updateTypes;
   constructor(options) {
     this.api = options.api;
     this.update = options.update;
@@ -623,6 +643,12 @@ var Context = class {
   get updateId() {
     return this.update.update_id;
   }
+  get updateTypes() {
+    if (!this._updateTypes) {
+      this._updateTypes = matchUpdate(this.update);
+    }
+    return this._updateTypes;
+  }
   get message() {
     return this.update.message ?? this.update.edited_message;
   }
@@ -782,21 +808,14 @@ function autoAnswerCallback() {
     }
   };
 }
-function errorHandler(onError) {
-  return async (ctx, next) => {
-    try {
-      await next();
-    } catch (error) {
-      await onError(error, ctx);
-    }
-  };
-}
 
 // src/runner/polling.ts
 var PollingRunner = class {
   running = false;
   abortController;
   offset = 0;
+  loopPromise;
+  backoffAttempt = 0;
   async start(bot, options = {}) {
     if (this.running) {
       throw new Error("Polling is already running");
@@ -807,14 +826,22 @@ var PollingRunner = class {
     const onError = options.onError ?? ((error) => {
       console.error("[balebaazoo] polling error:", error);
     });
+    this.loopPromise = this.runLoop(bot, options, signal, onError);
+    await this.loopPromise;
+  }
+  async runLoop(bot, options, signal, onError) {
     while (this.running && !signal.aborted) {
       try {
-        const updates = await bot.api.getUpdates({
-          offset: this.offset,
-          limit: options.limit ?? 100,
-          timeout: options.timeout ?? 30,
-          allowed_updates: options.allowedUpdates
-        });
+        const updates = await bot.api.getUpdates(
+          {
+            offset: this.offset,
+            limit: options.limit ?? 100,
+            timeout: options.timeout ?? 30,
+            allowed_updates: options.allowedUpdates
+          },
+          { signal }
+        );
+        this.backoffAttempt = 0;
         for (const update of updates) {
           this.offset = update.update_id + 1;
           try {
@@ -827,23 +854,49 @@ var PollingRunner = class {
           break;
         }
       } catch (error) {
-        if (signal.aborted) break;
+        if (signal.aborted || isAbortError2(error)) {
+          break;
+        }
+        if (error instanceof BaleAPIError && error.errorCode === 401) {
+          onError(error);
+          this.running = false;
+          break;
+        }
         onError(error);
-        await sleep2(1e3);
+        await sleep2(backoffDelay(this.backoffAttempt));
+        this.backoffAttempt++;
       }
     }
   }
+  setOffset(offset) {
+    this.offset = offset;
+  }
   async stop() {
     this.running = false;
     this.abortController?.abort();
+    await this.loopPromise;
   }
 };
+function isAbortError2(error) {
+  return error instanceof Error && (error.name === "AbortError" || error.message.includes("aborted"));
+}
+function backoffDelay(attempt) {
+  const base = 1e3;
+  const max = 3e4;
+  const exponential = Math.min(base * 2 ** attempt, max);
+  const jitter = Math.random() * 0.3 * exponential;
+  return Math.floor(exponential + jitter);
+}
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function createWebhookHandler(bot, getUpdate, options = {}) {
   await bot.init();
   const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+  const onError = options.onError ?? ((error) => {
+    console.error("[balebaazoo] webhook error:", error);
+    return new Response("Internal Server Error", { status: 500 });
+  });
   return async (request) => {
     if (request.method !== "POST") {
       return new Response("Method Not Allowed", { status: 405 });
@@ -868,8 +921,8 @@ async function createWebhookHandler(bot, getUpdate, options = {}) {
       await bot.handleUpdate(update);
       return new Response("OK", { status: 200 });
     } catch (error) {
-      console.error("[balebaazoo] webhook error:", error);
-      return new Response("Internal Server Error", { status: 500 });
+      const response = onError(error);
+      return response ?? new Response("Internal Server Error", { status: 500 });
     }
   };
 }
@@ -885,6 +938,7 @@ var Bot = class extends Composer {
   botInfo;
   polling = new PollingRunner();
   autoAnswer;
+  catchHandler;
   constructor(token, options = {}) {
     const api = new Api({ token, ...options });
     super();
@@ -901,9 +955,22 @@ var Bot = class extends Composer {
     }
     return this.botInfo;
   }
+  catch(handler) {
+    this.catchHandler = handler;
+    return this;
+  }
   async handleUpdate(update) {
+    await this.init();
     const ctx = this.createContext(update);
-    await this.middleware()(ctx, async () => void 0);
+    try {
+      await this.middleware()(ctx, async () => void 0);
+    } catch (error) {
+      if (this.catchHandler) {
+        await this.catchHandler(error, ctx);
+        return;
+      }
+      throw error;
+    }
   }
   createContext(update) {
     return new Context({
@@ -913,9 +980,44 @@ var Bot = class extends Composer {
     });
   }
   async start(options = {}) {
-    await this.init();
+    const onError = options.onError ?? ((error) => {
+      console.error("[balebaazoo] polling error:", error);
+    });
+    try {
+      await this.init();
+    } catch (error) {
+      onError(error);
+      return;
+    }
+    if (options.dropPendingUpdates) {
+      try {
+        const updates = await this.api.getUpdates({
+          offset: -1,
+          limit: 1,
+          timeout: 0
+        });
+        if (updates.length > 0) {
+          const last = updates[updates.length - 1];
+          this.polling.setOffset(last.update_id + 1);
+        }
+      } catch (error) {
+        onError(error);
+        return;
+      }
+    }
+    if (options.onStart) {
+      try {
+        await options.onStart(this.botInfo);
+      } catch (error) {
+        onError(error);
+        return;
+      }
+    }
     await this.polling.start(this, options);
   }
+  launch(options) {
+    return this.start(options);
+  }
   async stop() {
     await this.polling.stop();
   }
@@ -1012,6 +1114,30 @@ function removeKeyboard() {
   return { remove_keyboard: true };
 }
 
+// src/middleware/error-handler.ts
+function errorHandler(onError) {
+  return async (ctx, next) => {
+    try {
+      await next();
+    } catch (error) {
+      await onError(error, ctx);
+    }
+  };
+}
+
+// src/runner/shutdown.ts
+function setupGracefulShutdown(bot, options = {}) {
+  const signals = options.signals ?? ["SIGINT", "SIGTERM"];
+  for (const signal of signals) {
+    process.once(signal, () => {
+      void (async () => {
+        await bot.stop();
+        await options.onShutdown?.();
+      })();
+    });
+  }
+}
+
 exports.Api = Api;
 exports.BaleAPIError = BaleAPIError;
 exports.BaleError = BaleError;
@@ -1041,6 +1167,7 @@ exports.md = md;
 exports.normalizeMiddleware = normalizeMiddleware;
 exports.removeKeyboard = removeKeyboard;
 exports.runMiddleware = runMiddleware;
+exports.setupGracefulShutdown = setupGracefulShutdown;
 exports.spoiler = spoiler;
 exports.webhookFromJson = webhookFromJson;
 //# sourceMappingURL=index.cjs.map