@xbibzlibrary/telebibz 0.1.10 → 0.1.12

package/dist-cjs/src/core/bot.js

@@ -11,6 +11,7 @@ const storage_js_1 = require("../storage/storage.js");
 const plugin_js_1 = require("../plugins/plugin.js");
 const logger_js_1 = require("../observability/logger.js");
 const terminal_js_1 = require("../branding/terminal.js");
+const conversation_js_1 = require("../state/conversation.js");
 class Bot {
     api;
     router;
@@ -64,6 +65,30 @@ class Bot {
     onText(text, handler) { this.router.text(text, handler); return this; }
     onRegex(expression, handler) { this.router.regex(expression, handler); return this; }
     usePlugin(plugin) { this.plugins.use(plugin); return this; }
+    /**
+     * Routes subsequent messages to the active Wizard step for the same chat/user.
+     * The application starts the wizard once with `wizard.run(ctx, key)`; this
+     * middleware keeps routing replies until the wizard is completed or cancelled.
+     */
+    useWizard(wizard, options = {}) {
+        const cancelCommand = options.cancelCommand ?? "/cancel";
+        this.use(async (ctx, next) => {
+            const message = ctx.message;
+            const key = (0, conversation_js_1.conversationKeyFromContext)(ctx);
+            const state = await wizard.manager.getAsync(key);
+            if (!message?.text || state?.status !== "active") {
+                await next();
+                return;
+            }
+            if (message.text.trim() === cancelCommand) {
+                wizard.manager.cancel(key);
+                await ctx.reply("Conversation cancelled.");
+                return;
+            }
+            await wizard.run(ctx, key);
+        });
+        return this;
+    }
     async init() {
         if (this.statusValue === "initialized" || this.statusValue === "running")
             return this;
@@ -106,6 +131,7 @@ class Bot {
         await this.events.emit("bot:stopping", { bot: this });
         this.pollingAbort?.abort();
         this.pollingAbort = undefined;
+        await this.plugins.stop();
         await this.plugins.dispose();
         this.statusValue = "stopped";
         this.logger.info("bot.stopped");
@@ -134,7 +160,7 @@ class Bot {
             ?? update.edited_business_message
             ?? update.guest_message
             ?? update.callback_query?.message;
-        const key = message?.chat?.id !== undefined ? `${message.chat.id}:${message.from?.id ?? "anonymous"}` : `update:${update.update_id}`;
+        const key = this.conversationKey(update);
         const session = await this.session.get(key) ?? {};
         if (!this.me)
             await this.init();
@@ -153,6 +179,7 @@ class Bot {
             await this.events.emit("callback", { data: update.callback_query.data ?? "", update });
         const pipeline = (0, compose_js_1.compose)([...this.middlewares, async (context) => this.router.handle(context)]);
         try {
+            await this.plugins.update(ctx);
             await pipeline(ctx);
             await this.session.set(key, ctx.session);
         }
@@ -165,6 +192,21 @@ class Bot {
             throw error;
         }
     }
+    conversationKey(update) {
+        const message = update.message
+            ?? update.edited_message
+            ?? update.channel_post
+            ?? update.edited_channel_post
+            ?? update.business_message
+            ?? update.edited_business_message
+            ?? update.guest_message
+            ?? update.callback_query?.message;
+        if (message?.chat?.id !== undefined)
+            return `${message.chat.id}:${message.from?.id ?? "anonymous"}`;
+        if (update.callback_query?.from?.id !== undefined)
+            return `user:${update.callback_query.from.id}`;
+        return `update:${update.update_id}`;
+    }
     async waitForRetry(delayMs, signal) {
         if (signal.aborted)
             return false;

package/dist-cjs/src/core/events.js

@@ -18,8 +18,19 @@ class EventBus {
     }
     async emit(event, payload) {
         const listeners = [...(this.listeners.get(event) ?? [])];
-        for (const listener of listeners)
-            await listener(payload);
+        const errors = [];
+        for (const listener of listeners) {
+            try {
+                await listener(payload);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, `One or more listeners failed for event ${String(event)}`);
     }
     removeAllListeners() { this.listeners.clear(); }
     listenerCount(event) { return this.listeners.get(event)?.size ?? 0; }

package/dist-cjs/src/observability/logger.js

@@ -52,6 +52,22 @@ function updateType(update) {
         return "callback_query";
     if (update.inline_query)
         return "inline_query";
+    if (update.business_message)
+        return "business_message";
+    if (update.edited_business_message)
+        return "edited_business_message";
+    if (update.guest_message)
+        return "guest_message";
+    if (update.edited_guest_message)
+        return "edited_guest_message";
+    if (update.message_reaction)
+        return "message_reaction";
+    if (update.message_reaction_count)
+        return "message_reaction_count";
+    if (update.chat_boost)
+        return "chat_boost";
+    if (update.removed_chat_boost)
+        return "removed_chat_boost";
     if (update.message)
         return "message";
     if (update.edited_message)
@@ -74,7 +90,7 @@ function updateType(update) {
 }
 function summarizeUpdate(update, includeContent = false) {
     const callback = update.callback_query;
-    const message = update.message ?? update.edited_message ?? update.channel_post ?? update.edited_channel_post ?? update.business_message ?? update.edited_business_message ?? callback?.message;
+    const message = (update.message ?? update.edited_message ?? update.channel_post ?? update.edited_channel_post ?? update.business_message ?? update.edited_business_message ?? update.guest_message ?? update.edited_guest_message ?? callback?.message);
     const summary = { updateId: update.update_id, type: updateType(update) };
     if (message?.chat?.id !== undefined)
         summary.chatId = message.chat.id;

package/dist-cjs/src/plugins/plugin.js

@@ -14,7 +14,28 @@ class PluginManager {
     plugins = [];
     api;
     constructor(bot) {
-        this.api = { bot, services: new ServiceContainer(), registerMiddleware: () => undefined, registerRoute: () => undefined };
+        const host = bot;
+        this.api = {
+            bot,
+            services: new ServiceContainer(),
+            registerMiddleware: (middleware) => {
+                if (typeof middleware !== "function" || !host.use)
+                    throw new TypeError("Plugin middleware must be a function and the bot must support use().");
+                host.use(middleware);
+            },
+            registerRoute: (route) => {
+                if (typeof route === "function") {
+                    route(bot);
+                    return;
+                }
+                if (!route || typeof route !== "object" || !host.router?.route)
+                    throw new TypeError("Plugin route must be a registration function or route descriptor.");
+                const descriptor = route;
+                if (typeof descriptor.matcher !== "function" || !Array.isArray(descriptor.middleware) || descriptor.middleware.some((item) => typeof item !== "function"))
+                    throw new TypeError("Plugin route descriptor is invalid.");
+                host.router.route(descriptor.matcher, ...descriptor.middleware);
+            },
+        };
     }
     use(plugin) { if (this.plugins.some((existing) => existing.name === plugin.name))
         throw new Error(`Plugin already registered: ${plugin.name}`); this.plugins.push(plugin); return this; }

package/dist-cjs/src/queue/queue.js

@@ -42,10 +42,17 @@ class TaskQueue {
         return false; job.status = "cancelled"; this.controllers.get(id)?.abort(); return true; }
     async onIdle() { while (this.pending.some((job) => job.status === "queued") || this.active)
         await sleep(10); }
-    async close() { this.closed = true; this.draining = false; for (const id of this.controllers.keys())
-        this.cancel(id); for (const job of this.pending)
-        if (job.status === "queued")
-            job.status = "cancelled"; this.pending.length = 0; }
+    async close() {
+        this.closed = true;
+        this.draining = false;
+        for (const id of this.controllers.keys())
+            this.cancel(id);
+        for (const job of this.pending)
+            if (job.status === "queued")
+                job.status = "cancelled";
+        this.pending.length = 0;
+        await this.onIdle();
+    }
     async drain() {
         if (this.draining || this.closed)
             return;

package/dist-cjs/src/state/conversation.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Wizard = exports.ConversationManager = exports.ConversationFlow = void 0;
+exports.conversationKeyFromContext = conversationKeyFromContext;
 const storage_js_1 = require("../storage/storage.js");
+function conversationKeyFromContext(ctx) {
+    return ctx.chat?.id !== undefined ? `${ctx.chat.id}:${ctx.from?.id ?? "anonymous"}` : `update:${ctx.update.update_id}`;
+}
 class ConversationFlow {
     ctx;
     state;
@@ -27,7 +31,13 @@ class ConversationManager {
     start(key, name, values = {}) {
         const state = { name, step: 0, values, status: "active", updatedAt: Date.now() };
         this.active.set(key, state);
-        void this.storage.set(key, state);
+        void this.storage.set(key, state).catch(() => undefined);
+        return state;
+    }
+    async startAsync(key, name, values = {}) {
+        const state = { name, step: 0, values, status: "active", updatedAt: Date.now() };
+        this.active.set(key, state);
+        await this.storage.set(key, state);
         return state;
     }
     get(key) { return this.active.get(key); }
@@ -46,7 +56,7 @@ class ConversationManager {
             return false;
         state.status = "cancelled";
         state.updatedAt = Date.now();
-        void this.storage.set(key, state);
+        void this.storage.set(key, state).catch(() => undefined);
         return true;
     }
     async cancelAsync(key) {
@@ -86,15 +96,21 @@ class ConversationManager {
         return removed;
     }
     async run(ctx, key, name, steps) {
-        const state = (await this.getAsync(key)) ?? this.start(key, name);
+        const existing = await this.getAsync(key);
+        const state = existing ?? await this.startAsync(key, name);
         if (state.name !== name)
             throw new Error(`Conversation ${key} belongs to ${state.name}, not ${name}`);
+        if (state.status !== "active")
+            return state;
         const flow = new ConversationFlow(ctx, state);
         const step = steps[state.step];
         if (!step)
             state.status = "completed";
-        else
+        else {
             await step(flow);
+            if (state.step >= steps.length)
+                state.status = "completed";
+        }
         state.updatedAt = Date.now();
         await this.storage.set(key, state);
         this.active.set(key, state);
@@ -104,8 +120,20 @@ class ConversationManager {
 exports.ConversationManager = ConversationManager;
 class Wizard {
     stepsList = [];
+    defaultManager;
+    constructor(manager) {
+        this.defaultManager = manager ?? new ConversationManager();
+    }
     step(step) { this.stepsList.push(step); return this; }
-    async run(ctx, key, manager = new ConversationManager()) { return manager.run(ctx, key, "wizard", this.stepsList.map((step) => step.run)); }
+    /**
+     * Runs the active step for a conversation key. The default manager belongs to
+     * this Wizard instance and is intentionally reused across updates; passing a
+     * manager is useful when the application owns persistent storage explicitly.
+     */
+    async run(ctx, key = conversationKeyFromContext(ctx), manager) {
+        return (manager ?? this.defaultManager).run(ctx, key, "wizard", this.stepsList.map((step) => step.run));
+    }
     get steps() { return this.stepsList; }
+    get manager() { return this.defaultManager; }
 }
 exports.Wizard = Wizard;

package/dist-cjs/src/storage/storage.js

@@ -115,7 +115,7 @@ class RedisStorage {
     key(key) { return `${this.prefix}${key}`; }
     unkey(key) { return key.slice(this.prefix.length); }
     async get(key) { const value = await this.client.get(this.key(key)); return value === null ? undefined : JSON.parse(value); }
-    async set(key, value, options = {}) { const ttl = options.ttlMs; const redisOptions = ttl === undefined ? {} : ttl >= 1000 ? { PX: Math.max(1, Math.floor(ttl)) } : { PX: Math.max(1, Math.floor(ttl)) }; await this.client.set(this.key(key), JSON.stringify(value), redisOptions); }
+    async set(key, value, options = {}) { const ttl = options.ttlMs; const redisOptions = ttl === undefined ? {} : { PX: Math.max(1, Math.floor(ttl)) }; await this.client.set(this.key(key), JSON.stringify(value), redisOptions); }
     async delete(key) { return (await this.client.del(this.key(key))) > 0; }
     async has(key) { return (await this.client.exists(this.key(key))) > 0; }
     async clear() { const keys = await this.client.keys(`${this.prefix}*`); if (keys.length)

package/dist-cjs/src/telegram-features.js

@@ -48,6 +48,8 @@ function validateWebAppInitData(initData, botToken, maxAgeSeconds = 86_400, nowM
     if (!Number.isFinite(maxAgeSeconds) || maxAgeSeconds < 0)
         throw new RangeError("maxAgeSeconds must be non-negative");
     const parsed = parseWebAppInitData(initData);
+    if (!/^[0-9a-fA-F]{64}$/.test(parsed.hash))
+        throw new Error("Web App init data hash must be a 64-character hexadecimal string");
     const checkString = Object.entries(parsed.data).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
     const secret = (0, node_crypto_1.createHmac)("sha256", "WebAppData").update(botToken).digest();
     const expected = (0, node_crypto_1.createHmac)("sha256", secret).update(checkString).digest("hex");

package/dist-cjs/src/webhook/handler.js

@@ -1,13 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebhookHandler = createWebhookHandler;
+const node_crypto_1 = require("node:crypto");
 function createWebhookHandler(bot, options = {}) {
     const maxBodyBytes = options.maxBodyBytes ?? 1_048_576;
     return async (request) => {
         if (request.method !== "POST")
             return new Response("Method Not Allowed", { status: 405, headers: { allow: "POST" } });
-        if (options.secretToken && request.headers.get("x-telegram-bot-api-secret-token") !== options.secretToken)
+        if (options.secretToken && !secureEqual(request.headers.get("x-telegram-bot-api-secret-token") ?? "", options.secretToken))
             return new Response("Unauthorized", { status: 401 });
+        const contentType = request.headers.get("content-type") ?? "";
+        if (!/^application\/json(?:\s*;|\s*$)/i.test(contentType))
+            return new Response("Unsupported Media Type", { status: 415 });
         const contentLength = Number(request.headers.get("content-length") ?? 0);
         if (contentLength > maxBodyBytes)
             return new Response("Payload Too Large", { status: 413 });
@@ -27,3 +31,8 @@ function createWebhookHandler(bot, options = {}) {
         }
     };
 }
+function secureEqual(left, right) {
+    const leftBuffer = Buffer.from(left, "utf8");
+    const rightBuffer = Buffer.from(right, "utf8");
+    return leftBuffer.length === rightBuffer.length && (0, node_crypto_1.timingSafeEqual)(leftBuffer, rightBuffer);
+}

package/docs/API.id.md

@@ -4,7 +4,7 @@
 
 ![telebibz overview](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
 
-Dokumen ini adalah referensi API untuk `@xbibzlibrary/telebibz@0.1.4`. Seluruh signature dan perilaku yang dijelaskan di sini dipetakan dari source TypeScript yang diekspor package. Jika suatu tipe Telegram belum memiliki pemetaan parameter/result khusus, package tetap menyediakan akses runtime melalui API dinamis, tetapi tipe parameternya masih generik.
+Dokumen ini adalah referensi API untuk rilis `@xbibzlibrary/telebibz` yang sedang dipublikasikan. Seluruh signature dan perilaku yang dijelaskan di sini dipetakan dari source TypeScript yang diekspor package. Jika suatu tipe Telegram belum memiliki pemetaan parameter/result khusus, package tetap menyediakan akses runtime melalui API dinamis, tetapi tipe parameternya masih generik.
 
 > **Status implementasi.** Dokumentasi ini menjelaskan kemampuan yang tersedia pada rilis saat ini. `JsonFileStorage`, storage Redis/SQL/Mongo berbasis driver, session/conversation berbasis Storage, cron lima field lengkap, `MenuController`, terminal status output branded, structured logging dengan redaction, validasi Web App, `PaymentsClient`, dan declaration `TelegramTypes` sudah tersedia. Core method map tetap khusus untuk inferensi request/result tertentu, sedangkan `api.raw()` tersedia untuk method Telegram berikutnya.
 
@@ -1239,8 +1239,8 @@ interface MenuItem {
   label: string;
   callbackData?: string;
   url?: string;
-  visible?: boolean | (() => boolean | Promise<boolean>);
-  permission?: string;
+  visible?: boolean | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
+  permission?: string | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
 }
 ```
 

package/docs/API.md

@@ -3,7 +3,7 @@
 
 ![telebibz overview](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
 
-This document is the API reference for `@xbibzlibrary/telebibz@0.1.4`. All signatures and behaviors described here are mapped from the package's exported TypeScript source. If a Telegram type does not have a specific parameter/result mapping, the package still provides runtime access via a dynamic API, but the parameter types remain generic.
+This document is the API reference for the current published `@xbibzlibrary/telebibz` release. All signatures and behaviors described here are mapped from the package's exported TypeScript source. If a Telegram type does not have a specific parameter/result mapping, the package still provides runtime access via a dynamic API, but the parameter types remain generic.
 
 > **Implementation status.** This documentation describes the capabilities available in the current release. `JsonFileStorage`, driver-based Redis/SQL/Mongo storage, storage-backed sessions/conversations, full five-field cron, `MenuController`, terminal branding, structured redacted logging, Web App validation, PaymentsClient, and vendored `TelegramTypes` declarations are included. The core method map remains specialized for selected request/result inference, while `api.raw()` remains available for future Telegram methods.
 
@@ -147,6 +147,24 @@ usePlugin(plugin: Plugin<Context<S>>): this
 
 Registers a plugin. Plugin names must be unique.
 
+### `bot.useWizard(wizard, options?)`
+
+```ts
+useWizard(wizard: Wizard<S>, options?: { cancelCommand?: string }): this
+```
+
+Installs conversation middleware for a `Wizard`. Once an application starts the wizard with `wizard.run(ctx)`, subsequent text messages from the same chat/user are automatically routed to the active step until the wizard is completed or cancelled. The default conversation key is `${chat.id}:${from.id}`; `/cancel` cancels the active wizard by default.
+
+```ts
+const wizard = new Wizard()
+  .step({ id: "prompt-name", run: async (flow) => { flow.next(); await flow.ctx.reply("Siapa nama kamu?"); } })
+  .step({ id: "name", run: async (flow) => { flow.set("name", flow.ctx.message?.text?.trim()); flow.next(); await flow.ctx.reply("Berapa umur kamu?"); } })
+  .step({ id: "age", run: (flow) => { const age = Number(flow.ctx.message?.text?.trim()); if (!Number.isInteger(age)) return; flow.set("age", age); flow.next(); } });
+
+bot.useWizard(wizard);
+bot.command("start", (ctx) => wizard.run(ctx));
+```
+
 ### `bot.init()`
 
 ```ts
@@ -1140,8 +1158,9 @@ new Wizard<S>()
 | Method/property | Description |
 |---|---|
 | `step(definition)` | Adds a step and returns the wizard. `optional` is stored in the definition but not specially handled by the runner. |
-| `run(ctx, key, manager?)` | Runs the wizard steps via `ConversationManager` with the name `"wizard"`. |
+| `run(ctx, key?, manager?)` | Runs the active wizard step. If `key` is omitted, it uses `${chat.id}:${from.id}` and reuses the Wizard's default manager across updates. |
 | `steps` | Read-only list of steps. |
+| `manager` | Reusable `ConversationManager<S>` for `bot.useWizard()` or explicit state inspection. |
 
 ### Forms
 
@@ -1238,8 +1257,8 @@ interface MenuItem {
   label: string;
   callbackData?: string;
   url?: string;
-  visible?: boolean | (() => boolean | Promise<boolean>);
-  permission?: string;
+  visible?: boolean | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
+  permission?: string | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
 }
 ```
 

package/docs/API.zh-CN.md

@@ -4,7 +4,7 @@
 
 ![telebibz 概览](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
 
-本文件是 `@xbibzlibrary/telebibz@0.1.4` 的 API 参考。此处描述的所有签名和行为均映射自该包导出的 TypeScript 源代码。如果某个 Telegram 类型尚未有特定的参数/结果映射，该包仍通过动态 API 提供运行时访问，但其参数类型仍为通用类型。
+本文件是当前发布的 `@xbibzlibrary/telebibz` API 参考。此处描述的所有签名和行为均映射自该包导出的 TypeScript 源代码。如果某个 Telegram 类型尚未有特定的参数/结果映射，该包仍通过动态 API 提供运行时访问，但其参数类型仍为通用类型。
 
 > **实现状态。** 本文档说明当前版本中可用的功能。`JsonFileStorage`、基于 driver 的 Redis/SQL/Mongo storage、基于 Storage 的 session/conversation、完整五字段 cron、`MenuController`、带 branding 的 terminal status output、带 redaction 的 structured logging、Web App 验证、`PaymentsClient` 和 `TelegramTypes` declaration 均已提供。core method map 仍主要为特定 request/result inference 提供类型，未来 Telegram method 可通过 `api.raw()` 访问。
 
@@ -1233,8 +1233,8 @@ interface MenuItem {
   label: string;
   callbackData?: string;
   url?: string;
-  visible?: boolean | (() => boolean | Promise<boolean>);
-  permission?: string;
+  visible?: boolean | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
+  permission?: string | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xbibzlibrary/telebibz",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Production-grade, strongly typed Telegram Bot API SDK and framework for Node.js and TypeScript.",
   "type": "module",
   "private": false,