@monixlite/grammy-scenes 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,9 @@
 # @monixlite/grammy-scenes
 
-Scene middleware for grammY with step-based navigation.
+A lightweight FSM (Finite State Machine) engine for Telegram bots built on grammY.
+The module implements step-based scenes with declarative step definitions, automatic transitions, session-based state management, and an extensible navigation system.
+
+---
 
 ## Installation
 
@@ -10,8 +13,22 @@ npm install @monixlite/grammy-scenes
 
 ## Requirements
 
-* Node.js >= 16
-* grammY >= 1.19
+• Node.js >= 16
+• grammY >= 1.19
+
+---
+
+## Core Concept
+
+A scene is a sequence of steps united under a common title.
+Each step is described by an object containing:
+
+• scene and step identifiers
+• a set of callbacks reacting to Telegram events (enter, message, callbackQuery)
+
+The current scene state is stored in `ctx.session.scene`.
+
+---
 
 ## Basic Usage
 
@@ -20,13 +37,10 @@ const { Bot, session } = require("grammy");
 const { Scenes } = require("@monixlite/grammy-scenes");
 
 
-const bot = new Bot(""); {
+const bot = new Bot("..."); {
     bot.use(session({
         initial: () => ({
             scene: null,
-            step: null,
-            name: null,
-            age: null,
         }),
     }));
 };
@@ -42,22 +56,100 @@ const scene = new Scenes([
 
             callbacks: {
                 enter: async (ctx) => {
-                    await ctx.reply("Введите номер:");
+                    await ctx.reply("• Enter your phone number:");
                 },
 
                 message: async (ctx) => {
-                    await ctx.reply(`Номер: ${ctx.message.text.trim()}`);
+                    ctx.session.phone = ctx.message.text.trim();
+                },
+            },
+        },
+
+        {
+            scene: {
+                title: "auth",
+                step: "confirm",
+            },
 
-                    return "stop";
+            callbacks: {
+                enter: async (ctx) => {
+                    const { phone } = ctx.session;
+
+
+                    await ctx.reply(([
+                        `• Your phone number: ${phone}`,
+                        `• Is this correct?`
+                    ]).join("\n"), {
+                        reply_markup: {
+                            inline_keyboard: [
+                                [
+                                    {
+                                        text: "• Yes",
+                                        callback_data: "confirm:yes"
+                                    },
+
+                                    {
+                                        text: "• No",
+                                        callback_data: "confirm:no"
+                                    },
+                                ],
+                            ],
+                        },
+                    });
                 },
+
+                query: [
+                    {
+                        match: /^confirm:yes$/,
+                        handler: async (ctx) => {
+                            const { phone } = ctx.session;
+
+
+                            await ctx.answerCallbackQuery();
+                            await ctx.reply(`• Thank you! Your phone number ${phone} has been saved.`);
+
+
+                            return "stop";
+                        },
+                    },
+                    {
+                        match: /^confirm:no$/,
+                        handler: async (ctx) => {
+                            await ctx.answerCallbackQuery();
+
+
+                            return "^phone";
+                        },
+                    },
+                ],
             },
         },
     ],
-]);
+], {
+    ["callbacks:enter:buttons:cancel"]: {
+        enabled: true,
+
+        component: {
+            text: "• Cancel scene •",
+            callback_data: "scene:cancel",
+        },
+    },
+});
+
+
+bot.callbackQuery("scene:cancel", async (ctx) => {
+    ctx.session.scene = null;
+
+
+    await ctx.editMessageReplyMarkup(null);
+    await ctx.answerCallbackQuery();
+
+    await ctx.reply("• Scene cancelled!");
+});
 
 
 bot.command("start", async (ctx) => {
-    await scene.enter(ctx, {
+    return await scene.enter(ctx, {
         title: "auth",
         step: "phone",
     });
@@ -69,9 +161,11 @@ bot.use(scene.middleware);
 bot.start();
 ```
 
+---
+
 ## Scene Definition
 
-Каждый шаг сцены описывается объектом:
+Each scene step is described by the following structure:
 
 ```js
 {
@@ -82,23 +176,77 @@ bot.start();
 
     callbacks: {
         enter?: (ctx) => Promise<void>,
-        message?: (ctx) => Promise<"next" | "stop" | void>,
+        update?: (ctx) => Promise<SceneResult | void>,
+        message?: (ctx) => Promise<SceneResult | void>,
+        query?: Array<{
+            match: RegExp,
+            handler: (ctx) => Promise<SceneResult | void>,
+        }>,
     },
 }
 ```
 
-### callbacks.enter
+`SceneResult` is a value that determines the next transition (described below).
+
+---
+
+## Callbacks
+
+### callbacks.enter(ctx)
+
+Triggered when entering a scene step.
+Used to send messages, keyboards, or initialize data.
+
+Details:
+
+• Executed automatically on step entry
+• Can freely use `ctx.reply`
+• If the cancel button option is enabled, it is automatically appended to the inline keyboard
+
+---
+
+### callbacks.update(ctx)
+
+Triggered on **any update** while the step is active.
+
+Details:
 
-Вызывается при входе в шаг сцены.
+• Executed before `message` and `query`
+• Receives the raw grammY context
+• Can be used for global step logic (timeouts, guards, media handling)
+• Return value controls navigation using standard SceneResult rules
 
-### callbacks.message
+---
 
-Вызывается при получении сообщения пользователя.
-Возврат `"stop"` завершает сцену.
+### callbacks.message(ctx)
+
+Triggered when a text message is received while the step is active.
+
+---
+
+### callbacks.query
+
+An array of `callbackQuery` handlers.
+
+Each handler has the following shape:
+
+```js
+{
+    match: RegExp,
+    handler: async (ctx) => SceneResult
+}
+```
+
+When `match` matches `ctx.callbackQuery.data`, the corresponding handler is executed.
+Its return value is processed using the same transition logic as `callbacks.message`.
+
+---
 
 ## Scene Control
 
-### Enter scene
+### scenes.enter(ctx, scene)
+
+Forces entry into a scene and step.
 
 ```js
 await scenes.enter(ctx, {
@@ -107,21 +255,147 @@ await scenes.enter(ctx, {
 });
 ```
 
-### Cancel scene manually
+Behavior:
+
+• Writes the scene into `ctx.session.scene`
+• Locates the step definition
+• Executes `callbacks.enter` if present
+• Temporarily overrides `ctx.reply` to append the cancel button
+
+---
+
+### Cancel a Scene Manually
+
+A scene can be terminated manually:
 
 ```js
 ctx.session.scene = null;
 ```
 
-## Middleware
+After this, the middleware stops processing scene events.
+
+---
 
-Middleware должен быть подключён **после** session middleware:
+## Middleware
 
 ```js
 bot.use(session(...));
 bot.use(scenes.middleware);
 ```
 
+The middleware:
+
+• Checks for an active scene in the session
+• Resolves the current step
+• Delegates updates to the appropriate callbacks
+• Executes step transitions
+
+The middleware **must** be registered after the session middleware.
+
+---
+
+## Step Navigation
+
+Transitions are determined by the value returned from callbacks.
+
+### Terminating a Scene
+
+• `"stop"`, `"exit"`, `"!"`
+→ `ctx.session.scene = null`
+
+---
+
+### All Transitions
+
+• `undefined` or `"next"` → move to the next step
+• `"stop" | "exit" | "!"` → terminate the scene
+• `"<" | "prev"` → move to the previous step
+• `">" | "next"` → move to the next step
+• `"^step"` → jump to a step within the current scene
+• `"^scene:step"` → jump to another scene
+• `{ step: "..." }` → jump to a specific step
+• `{ scene: { title, step } }` → jump to another scene
+
+---
+
+### Relative Transitions
+
+• `undefined` / `"next"` / `">"` → next step
+• `"prev"` / `"<"` → previous step
+
+---
+
+### Absolute Transitions
+
+• `"^step"` → step within the current scene
+• `"^scene:step"` → jump to another scene
+
+---
+
+### Object-Based Transitions
+
+```js
+return { step: "confirm" };
+```
+
+```js
+return {
+    scene: {
+        title: "auth",
+        step: "phone",
+    },
+};
+```
+
+---
+
+## Options
+
+Options are passed as the second argument to `new Scenes()`.
+
+### callbacks:enter:buttons:cancel
+
+Adds a cancel button to all messages sent inside `callbacks.enter`.
+
+```js
+{
+    "callbacks:enter:buttons:cancel": {
+        enabled: true,
+
+        component: {
+            text: "Cancel",
+            callback_data: "scene:cancel",
+        },
+    },
+}
+```
+
+Behavior:
+
+• Works only inside `callbacks.enter`
+• The button is appended automatically
+• Scene cancellation logic must be implemented by the user
+
+---
+
+## Scenes Class
+
+### new Scenes(scenes, options)
+
+Creates a scene manager instance.
+
+Parameters:
+
+• `scenes` — an array of grouped scene steps
+• `options` — configuration object
+
+Exports:
+
+• `scenes.middleware` — grammY middleware
+• `scenes.enter(ctx, scene)` — method to enter a scene
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@monixlite/grammy-scenes",
-    "version": "1.0.0",
+    "version": "1.2.0",
     "description": "Scene middleware for grammY with step-based navigation",
     "main": "src/index.js",
     "type": "commonjs",
@@ -17,4 +17,4 @@
     "peerDependencies": {
         "grammy": "^1.0.0"
     }
-}
+}

package/src/index.js

@@ -1,8 +1,10 @@
 class ScenesMiddleware {
-    constructor({ scenes }) {
+    constructor({
+        scenes,
+        options = {},
+    }) {
         this.scenes = scenes;
 
-
         this.steps = {}; {
             for (const group of scenes) {
                 for (const item of group) {
@@ -18,6 +20,20 @@ class ScenesMiddleware {
                 };
             };
         };
+
+
+        this.options = {
+            ["callbacks:enter:buttons:cancel"]: {
+                enabled: true,
+
+                component: {
+                    text: "Отменить",
+                    callback_data: "scene:cancel",
+                },
+            },
+
+            ...options,
+        };
     };
 
 
@@ -55,18 +71,17 @@ class ScenesMiddleware {
 
         const original = ctx.reply.bind(ctx); {
             ctx.reply = (text, extra = {}) => {
+                const keyboard = (extra.reply_markup?.inline_keyboard || []); {
+                    if (this.options?.["callbacks:enter:buttons:cancel"]?.enabled) keyboard.push([
+                        this.options?.["callbacks:enter:buttons:cancel"]?.component,
+                    ]);
+                };
+
+
                 return original(text, {
                     ...extra,
                     reply_markup: {
-                        inline_keyboard: [
-                            ...(extra.reply_markup?.inline_keyboard || []),
-                            [
-                                {
-                                    text: "Отменить",
-                                    callback_data: "scene:cancel",
-                                },
-                            ],
-                        ],
+                        inline_keyboard: keyboard,
                     },
                 });
             };
@@ -156,14 +171,24 @@ class ScenesMiddleware {
         };
 
 
-        if (ctx.message && current.callbacks.message) {
+        if (ctx?.update && current.callbacks?.update) {
+            const result = await current.callbacks.update(ctx);
+
+            return await this.handle(ctx, scene, result);
+        };
+
+
+        if (ctx?.message && current.callbacks?.message) {
+            if (ctx?.message?.caption) ctx.message.text ??= ctx.message.caption;
+
+
             const result = await current.callbacks.message(ctx);
 
             return await this.handle(ctx, scene, result);
         };
 
 
-        if (ctx.callbackQuery && current.callbacks.query) {
+        if (ctx?.callbackQuery && current.callbacks?.query) {
             const data = ctx.callbackQuery.data;
 
 
@@ -183,9 +208,10 @@ class ScenesMiddleware {
 
 
 class Scenes {
-    constructor(scenes) {
+    constructor(scenes, options = {}) {
         this.instance = new ScenesMiddleware({
             scenes: scenes,
+            options: options,
         });