@mtcute/dispatcher 0.1.0

package/cjs/state/update-state.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateState = exports.RateLimitError = void 0;
+/* eslint-disable dot-notation */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const client_1 = require("@mtcute/client");
+const utils_js_1 = require("@mtcute/client/utils.js");
+/**
+ * Error thrown by `.rateLimit()`
+ */
+class RateLimitError extends client_1.MtcuteError {
+    constructor(reset) {
+        super('You are being rate limited.');
+        this.reset = reset;
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * State of the current update.
+ *
+ * @template State  Type that represents the state
+ * @template SceneName  Possible scene names
+ */
+class UpdateState {
+    constructor(storage, key, scene, scoped, customStorage, customKey) {
+        this._storage = storage;
+        this._key = key;
+        this._scene = scene;
+        this._scoped = scoped;
+        this._localStorage = customStorage ?? storage;
+        this._localKeyBase = customKey ?? key;
+        this._updateLocalKey();
+    }
+    /** Name of the current scene */
+    get scene() {
+        return this._scene;
+    }
+    _updateLocalKey() {
+        if (!this._scoped)
+            this._localKey = this._localKeyBase;
+        else {
+            this._localKey = this._scene ? this._scene + '_' + this._localKeyBase : this._localKeyBase;
+        }
+    }
+    async get(fallback, force) {
+        if (typeof fallback === 'boolean') {
+            force = fallback;
+            fallback = undefined;
+        }
+        if (!force && this._cached !== undefined) {
+            if (!this._cached && fallback) {
+                return typeof fallback === 'function' ? fallback() : fallback;
+            }
+            return this._cached;
+        }
+        let res = (await this._localStorage.getState(this._localKey));
+        if (!res && fallback) {
+            res = typeof fallback === 'function' ? fallback() : fallback;
+        }
+        this._cached = res;
+        return res;
+    }
+    /**
+     * Set new state to the storage
+     *
+     * @param state  New state
+     * @param ttl  TTL for the new state (in seconds)
+     */
+    async set(state, ttl) {
+        this._cached = state;
+        await this._localStorage.setState(this._localKey, state, ttl);
+    }
+    /**
+     * Merge the given object to the current state.
+     *
+     * > **Note**: If the storage currently has no state,
+     * > then `fallback` must be provided.
+     *
+     * Basically a shorthand to calling `.get()`,
+     * modifying and then calling `.set()`
+     *
+     * @param state  State to be merged
+     * @param fallback  Default state
+     * @param ttl  TTL for the new state (in seconds)
+     * @param forceLoad  Whether to force load the old state from storage
+     */
+    async merge(state, params = {}) {
+        const { fallback, ttl, forceLoad } = params;
+        const old = await this.get(forceLoad);
+        if (!old) {
+            if (!fallback) {
+                throw new client_1.MtArgumentError('Cannot use merge on empty state without fallback.');
+            }
+            const fallback_ = typeof fallback === 'function' ? fallback() : fallback;
+            await this.set({ ...fallback_, ...state }, ttl);
+        }
+        else {
+            await this.set({ ...old, ...state }, ttl);
+        }
+        // _cached is set by .set()
+        return this._cached;
+    }
+    /**
+     * Delete the state from the storage
+     */
+    async delete() {
+        this._cached = null;
+        await this._localStorage.deleteState(this._localKey);
+    }
+    /**
+     * Enter some scene
+     */
+    async enter(scene, params) {
+        const { with: with_, ttl, reset = true } = params ?? {};
+        if (reset && this._scoped)
+            await this.delete();
+        if (!scene['_scene']) {
+            throw new client_1.MtArgumentError('Cannot enter a non-scene Dispatcher');
+        }
+        if (!scene['_parent']) {
+            throw new client_1.MtArgumentError('This scene has not been registered');
+        }
+        this._scene = scene['_scene'];
+        this._scoped = scene['_sceneScoped'];
+        this._updateLocalKey();
+        await this._storage.setCurrentScene(this._key, this._scene, ttl);
+        if (with_) {
+            if (scene['_customStateKeyDelegate']) {
+                throw new client_1.MtArgumentError('Cannot use `with` parameter when the scene uses a custom state key delegate');
+            }
+            await scene.getState(this._key).set(with_, ttl);
+        }
+    }
+    /**
+     * Exit from current scene to the root
+     *
+     * @param reset
+     *     Whether to reset scene state (only applicable in case this is a scoped scene)
+     */
+    async exit(reset = true) {
+        if (reset && this._scoped)
+            await this.delete();
+        this._scene = null;
+        this._updateLocalKey();
+        await this._storage.deleteCurrentScene(this._key);
+    }
+    /**
+     * Rate limit some handler.
+     *
+     * When the rate limit exceeds, {@link RateLimitError} is thrown.
+     *
+     * This is a simple rate-limiting solution that uses
+     * the same key as the state. If you need something more
+     * sophisticated and/or customizable, you'll have to implement
+     * your own rate-limiter.
+     *
+     * > **Note**: `key` is used to prefix the local key
+     * > derived using the given key delegate.
+     *
+     * @param key  Key of the rate limit
+     * @param limit  Maximum number of requests in `window`
+     * @param window  Window size in seconds
+     * @returns  Tuple containing the number of remaining and
+     *   unix time in ms when the user can try again
+     */
+    async rateLimit(key, limit, window) {
+        const [remaining, reset] = await this._localStorage.getRateLimit(`${key}:${this._localKey}`, limit, window);
+        if (!remaining) {
+            throw new RateLimitError(reset);
+        }
+        return [remaining - 1, reset];
+    }
+    /**
+     * Throttle some handler.
+     *
+     * When the rate limit exceeds, this function waits for it to reset.
+     *
+     * This is a simple wrapper over {@link rateLimit}, and follows the same logic.
+     *
+     * > **Note**: `key` is used to prefix the local key
+     * > derived using the given key delegate.
+     *
+     * @param key  Key of the rate limit
+     * @param limit  Maximum number of requests in `window`
+     * @param window  Window size in seconds
+     * @returns  Tuple containing the number of remaining and
+     *   unix time in ms when the user can try again
+     */
+    async throttle(key, limit, window) {
+        try {
+            return await this.rateLimit(key, limit, window);
+        }
+        catch (e) {
+            if (e instanceof RateLimitError) {
+                await (0, utils_js_1.sleep)(e.reset - Date.now());
+                return this.throttle(key, limit, window);
+            }
+            throw e;
+        }
+    }
+    /**
+     * Reset the rate limit
+     *
+     * @param key  Key of the rate limit
+     */
+    async resetRateLimit(key) {
+        await this._localStorage.resetRateLimit(`${key}:${this._localKey}`);
+    }
+}
+exports.UpdateState = UpdateState;
+//# sourceMappingURL=update-state.js.map

package/cjs/state/update-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-state.js","sourceRoot":"","sources":["../../../src/state/update-state.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable dot-notation */\n/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { MtArgumentError, MtcuteError } from '@mtcute/client'\nimport { sleep } from '@mtcute/client/utils.js'\n\nimport type { Dispatcher } from '../dispatcher.js'\nimport { IStateStorage } from './storage.js'\n\n/**\n * Error thrown by `.rateLimit()`\n */\nexport class RateLimitError extends MtcuteError {\n    constructor(readonly reset: number) {\n        super('You are being rate limited.')\n    }\n}\n\n/**\n * State of the current update.\n *\n * @template State  Type that represents the state\n * @template SceneName  Possible scene names\n */\nexport class UpdateState<State extends object> {\n    private _key: string\n    private _localKey!: string\n\n    private _storage: IStateStorage\n\n    private _scene: string | null\n    private _scoped?: boolean\n    private _cached?: State | null\n\n    private _localStorage: IStateStorage\n    private _localKeyBase: string\n\n    constructor(\n        storage: IStateStorage,\n        key: string,\n        scene: string | null,\n        scoped?: boolean,\n        customStorage?: IStateStorage,\n        customKey?: string,\n    ) {\n        this._storage = storage\n        this._key = key\n        this._scene = scene\n        this._scoped = scoped\n\n        this._localStorage = customStorage ?? storage\n        this._localKeyBase = customKey ?? key\n\n        this._updateLocalKey()\n    }\n\n    /** Name of the current scene */\n    get scene(): string | null {\n        return this._scene\n    }\n\n    private _updateLocalKey(): void {\n        if (!this._scoped) this._localKey = this._localKeyBase\n        else {\n            this._localKey = this._scene ? this._scene + '_' + this._localKeyBase : this._localKeyBase\n        }\n    }\n\n    /**\n     * Retrieve the state from the storage, falling back to default\n     * if not found\n     *\n     * @param fallback  Default state value\n     * @param force  Whether to ignore cached state (def. `false`)\n     */\n    async get(fallback: State | (() => State), force?: boolean): Promise<State>\n\n    /**\n     * Retrieve the state from the storage, falling back to default\n     * if not found\n     *\n     * @param fallback  Default state value\n     * @param force  Whether to ignore cached state (def. `false`)\n     */\n    async get(fallback?: State | (() => State), force?: boolean): Promise<State | null>\n    /**\n     * Retrieve the state from the storage\n     *\n     * @param force  Whether to ignore cached state (def. `false`)\n     */\n    async get(force?: boolean): Promise<State | null>\n    async get(fallback?: State | (() => State) | boolean, force?: boolean): Promise<State | null> {\n        if (typeof fallback === 'boolean') {\n            force = fallback\n            fallback = undefined\n        }\n\n        if (!force && this._cached !== undefined) {\n            if (!this._cached && fallback) {\n                return typeof fallback === 'function' ? fallback() : fallback\n            }\n\n            return this._cached\n        }\n\n        let res = (await this._localStorage.getState(this._localKey)) as State | null\n\n        if (!res && fallback) {\n            res = typeof fallback === 'function' ? fallback() : fallback\n        }\n        this._cached = res\n\n        return res\n    }\n\n    /**\n     * Set new state to the storage\n     *\n     * @param state  New state\n     * @param ttl  TTL for the new state (in seconds)\n     */\n    async set(state: State, ttl?: number): Promise<void> {\n        this._cached = state\n        await this._localStorage.setState(this._localKey, state, ttl)\n    }\n\n    /**\n     * Merge the given object to the current state.\n     *\n     * > **Note**: If the storage currently has no state,\n     * > then `fallback` must be provided.\n     *\n     * Basically a shorthand to calling `.get()`,\n     * modifying and then calling `.set()`\n     *\n     * @param state  State to be merged\n     * @param fallback  Default state\n     * @param ttl  TTL for the new state (in seconds)\n     * @param forceLoad  Whether to force load the old state from storage\n     */\n    async merge(\n        state: Partial<State>,\n        params: {\n            fallback?: State | (() => State)\n            ttl?: number\n            forceLoad?: boolean\n        } = {},\n    ): Promise<State> {\n        const { fallback, ttl, forceLoad } = params\n\n        const old = await this.get(forceLoad)\n\n        if (!old) {\n            if (!fallback) {\n                throw new MtArgumentError('Cannot use merge on empty state without fallback.')\n            }\n\n            const fallback_ = typeof fallback === 'function' ? fallback() : fallback\n\n            await this.set({ ...fallback_, ...state }, ttl)\n        } else {\n            await this.set({ ...old, ...state }, ttl)\n        }\n\n        // _cached is set by .set()\n\n        return this._cached!\n    }\n\n    /**\n     * Delete the state from the storage\n     */\n    async delete(): Promise<void> {\n        this._cached = null\n        await this._localStorage.deleteState(this._localKey)\n    }\n\n    /**\n     * Enter some scene\n     */\n    async enter<SceneState extends object, Scene extends Dispatcher<SceneState>>(\n        scene: Scene,\n        params?: {\n            /**\n             * Initial state for the scene\n             *\n             * Note that this will only work if the scene uses the same key delegate as this state.\n             */\n            with?: SceneState\n\n            /** TTL for the scene (in seconds) */\n            ttl?: number\n\n            /**\n             * If currently in a scoped scene, whether to reset the state\n             *\n             * @default  true\n             */\n            reset?: boolean\n        },\n    ): Promise<void> {\n        const { with: with_, ttl, reset = true } = params ?? {}\n\n        if (reset && this._scoped) await this.delete()\n\n        if (!scene['_scene']) {\n            throw new MtArgumentError('Cannot enter a non-scene Dispatcher')\n        }\n\n        if (!scene['_parent']) {\n            throw new MtArgumentError('This scene has not been registered')\n        }\n\n        this._scene = scene['_scene']\n        this._scoped = scene['_sceneScoped']\n        this._updateLocalKey()\n\n        await this._storage.setCurrentScene(this._key, this._scene, ttl)\n\n        if (with_) {\n            if (scene['_customStateKeyDelegate']) {\n                throw new MtArgumentError('Cannot use `with` parameter when the scene uses a custom state key delegate')\n            }\n\n            await scene.getState(this._key).set(with_, ttl)\n        }\n    }\n\n    /**\n     * Exit from current scene to the root\n     *\n     * @param reset\n     *     Whether to reset scene state (only applicable in case this is a scoped scene)\n     */\n    async exit(reset = true): Promise<void> {\n        if (reset && this._scoped) await this.delete()\n        this._scene = null\n        this._updateLocalKey()\n        await this._storage.deleteCurrentScene(this._key)\n    }\n\n    /**\n     * Rate limit some handler.\n     *\n     * When the rate limit exceeds, {@link RateLimitError} is thrown.\n     *\n     * This is a simple rate-limiting solution that uses\n     * the same key as the state. If you need something more\n     * sophisticated and/or customizable, you'll have to implement\n     * your own rate-limiter.\n     *\n     * > **Note**: `key` is used to prefix the local key\n     * > derived using the given key delegate.\n     *\n     * @param key  Key of the rate limit\n     * @param limit  Maximum number of requests in `window`\n     * @param window  Window size in seconds\n     * @returns  Tuple containing the number of remaining and\n     *   unix time in ms when the user can try again\n     */\n    async rateLimit(key: string, limit: number, window: number): Promise<[number, number]> {\n        const [remaining, reset] = await this._localStorage.getRateLimit(`${key}:${this._localKey}`, limit, window)\n\n        if (!remaining) {\n            throw new RateLimitError(reset)\n        }\n\n        return [remaining - 1, reset]\n    }\n\n    /**\n     * Throttle some handler.\n     *\n     * When the rate limit exceeds, this function waits for it to reset.\n     *\n     * This is a simple wrapper over {@link rateLimit}, and follows the same logic.\n     *\n     * > **Note**: `key` is used to prefix the local key\n     * > derived using the given key delegate.\n     *\n     * @param key  Key of the rate limit\n     * @param limit  Maximum number of requests in `window`\n     * @param window  Window size in seconds\n     * @returns  Tuple containing the number of remaining and\n     *   unix time in ms when the user can try again\n     */\n    async throttle(key: string, limit: number, window: number): Promise<[number, number]> {\n        try {\n            return await this.rateLimit(key, limit, window)\n        } catch (e: unknown) {\n            if (e instanceof RateLimitError) {\n                await sleep(e.reset - Date.now())\n\n                return this.throttle(key, limit, window)\n            }\n\n            throw e\n        }\n    }\n\n    /**\n     * Reset the rate limit\n     *\n     * @param key  Key of the rate limit\n     */\n    async resetRateLimit(key: string): Promise<void> {\n        await this._localStorage.resetRateLimit(`${key}:${this._localKey}`)\n    }\n}\n"]}

package/cjs/wizard.d.ts

@@ -0,0 +1,60 @@
+import { MaybeAsync } from '@mtcute/client';
+import { MessageContext } from './context/message.js';
+import { Dispatcher } from './dispatcher.js';
+import { filters } from './filters/index.js';
+import { UpdateState } from './state/update-state.js';
+/**
+ * Action for the wizard scene.
+ *
+ * `Next`: Continue to the next registered step
+ * (or exit, if this is the last step)
+ *
+ * `Stay`: Stay on the same step
+ *
+ * `Exit`: Exit from the wizard scene
+ *
+ * You can also return a `number` to jump to that step
+ */
+export declare enum WizardSceneAction {
+    Next = "next",
+    Stay = "stay",
+    Exit = "exit"
+}
+interface WizardInternalState {
+    $step?: number;
+}
+/**
+ * Wizard is a special type of Dispatcher
+ * that can be used to simplify implementing
+ * step-by-step scenes.
+ */
+export declare class WizardScene<State extends object> extends Dispatcher<State & WizardInternalState> {
+    private _steps;
+    private _defaultState;
+    setDefaultState(defaultState: State): void;
+    /**
+     * Get the total number of registered steps
+     */
+    get totalSteps(): number;
+    /**
+     * Go to the Nth step
+     */
+    goToStep(state: UpdateState<WizardInternalState>, step: number): Promise<void>;
+    /**
+     * Skip N steps
+     */
+    skip(state: UpdateState<WizardInternalState>, count?: number): Promise<void>;
+    /**
+     * Filter that will only pass if the current step is `step`
+     */
+    static onNthStep(step: number): filters.UpdateFilter<any, {}, WizardInternalState>;
+    /**
+     * Filter that will only pass if the current step is the one after last one added
+     */
+    onCurrentStep(): filters.UpdateFilter<any, {}, WizardInternalState>;
+    /**
+     * Add a step to the wizard
+     */
+    addStep(handler: (msg: MessageContext, state: UpdateState<State & WizardInternalState>) => MaybeAsync<WizardSceneAction | number>): void;
+}
+export {};

package/cjs/wizard.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WizardScene = exports.WizardSceneAction = void 0;
+const dispatcher_js_1 = require("./dispatcher.js");
+const index_js_1 = require("./filters/index.js");
+/**
+ * Action for the wizard scene.
+ *
+ * `Next`: Continue to the next registered step
+ * (or exit, if this is the last step)
+ *
+ * `Stay`: Stay on the same step
+ *
+ * `Exit`: Exit from the wizard scene
+ *
+ * You can also return a `number` to jump to that step
+ */
+var WizardSceneAction;
+(function (WizardSceneAction) {
+    WizardSceneAction["Next"] = "next";
+    WizardSceneAction["Stay"] = "stay";
+    WizardSceneAction["Exit"] = "exit";
+})(WizardSceneAction = exports.WizardSceneAction || (exports.WizardSceneAction = {}));
+/**
+ * Wizard is a special type of Dispatcher
+ * that can be used to simplify implementing
+ * step-by-step scenes.
+ */
+class WizardScene extends dispatcher_js_1.Dispatcher {
+    constructor() {
+        super(...arguments);
+        this._steps = 0;
+        this._defaultState = {};
+    }
+    setDefaultState(defaultState) {
+        this._defaultState = defaultState;
+    }
+    /**
+     * Get the total number of registered steps
+     */
+    get totalSteps() {
+        return this._steps;
+    }
+    /**
+     * Go to the Nth step
+     */
+    async goToStep(state, step) {
+        if (step >= this._steps) {
+            await state.exit();
+        }
+        else {
+            await state.merge({ $step: step }, this._defaultState);
+        }
+    }
+    /**
+     * Skip N steps
+     */
+    async skip(state, count = 1) {
+        const { $step } = (await state.get()) || {};
+        if ($step === undefined)
+            throw new Error('Wizard state is not initialized');
+        return this.goToStep(state, $step + count);
+    }
+    /**
+     * Filter that will only pass if the current step is `step`
+     */
+    static onNthStep(step) {
+        const filter = index_js_1.filters.state((it) => it.$step === step);
+        if (step === 0)
+            return index_js_1.filters.or(index_js_1.filters.stateEmpty, filter);
+        return filter;
+    }
+    /**
+     * Filter that will only pass if the current step is the one after last one added
+     */
+    onCurrentStep() {
+        return WizardScene.onNthStep(this._steps);
+    }
+    /**
+     * Add a step to the wizard
+     */
+    addStep(handler) {
+        const step = this._steps++;
+        this.onNewMessage(WizardScene.onNthStep(step), async (msg, state) => {
+            const result = await handler(msg, state);
+            if (typeof result === 'number') {
+                await this.goToStep(state, result);
+                return;
+            }
+            switch (result) {
+                case 'next': {
+                    await this.goToStep(state, step + 1);
+                    break;
+                }
+                case 'exit':
+                    await state.exit();
+                    break;
+            }
+        });
+    }
+}
+exports.WizardScene = WizardScene;
+//# sourceMappingURL=wizard.js.map

package/cjs/wizard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard.js","sourceRoot":"","sources":["../../src/wizard.ts"],"names":[],"mappings":";;;AAGA,mDAA4C;AAC5C,iDAA4C;AAG5C;;;;;;;;;;;GAWG;AACH,IAAY,iBAIX;AAJD,WAAY,iBAAiB;IACzB,kCAAa,CAAA;IACb,kCAAa,CAAA;IACb,kCAAa,CAAA;AACjB,CAAC,EAJW,iBAAiB,GAAjB,yBAAiB,KAAjB,yBAAiB,QAI5B;AAMD;;;;GAIG;AACH,MAAa,WAAkC,SAAQ,0BAAuC;IAA9F;;QACY,WAAM,GAAG,CAAC,CAAA;QAEV,kBAAa,GAAgC,EAAiC,CAAA;IAmF1F,CAAC;IAjFG,eAAe,CAAC,YAAmB;QAC/B,IAAI,CAAC,aAAa,GAAG,YAA2C,CAAA;IACpE,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,MAAM,CAAA;IACtB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAuC,EAAE,IAAY;QAChE,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE;YACrB,MAAM,KAAK,CAAC,IAAI,EAAE,CAAA;SACrB;aAAM;YACH,MAAM,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,IAAI,CAAC,aAAa,CAAC,CAAA;SACzD;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,KAAuC,EAAE,KAAK,GAAG,CAAC;QACzD,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAA;QAC3C,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;QAE3E,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAA;IAC9C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,IAAY;QACzB,MAAM,MAAM,GAAG,kBAAO,CAAC,KAAK,CAAsB,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAA;QAE5E,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,kBAAO,CAAC,EAAE,CAAC,kBAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;QAE7D,OAAO,MAAM,CAAA;IACjB,CAAC;IAED;;OAEG;IACH,aAAa;QACT,OAAO,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC7C,CAAC;IAED;;OAEG;IACH,OAAO,CACH,OAG2C;QAE3C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;QAE1B,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;YAChE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YAExC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE;gBAC5B,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;gBAElC,OAAM;aACT;YAED,QAAQ,MAAM,EAAE;gBACZ,KAAK,MAAM,CAAC,CAAC;oBACT,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,CAAA;oBACpC,MAAK;iBACR;gBACD,KAAK,MAAM;oBACP,MAAM,KAAK,CAAC,IAAI,EAAE,CAAA;oBAClB,MAAK;aACZ;QACL,CAAC,CAAC,CAAA;IACN,CAAC;CACJ;AAtFD,kCAsFC","sourcesContent":["import { MaybeAsync } from '@mtcute/client'\n\nimport { MessageContext } from './context/message.js'\nimport { Dispatcher } from './dispatcher.js'\nimport { filters } from './filters/index.js'\nimport { UpdateState } from './state/update-state.js'\n\n/**\n * Action for the wizard scene.\n *\n * `Next`: Continue to the next registered step\n * (or exit, if this is the last step)\n *\n * `Stay`: Stay on the same step\n *\n * `Exit`: Exit from the wizard scene\n *\n * You can also return a `number` to jump to that step\n */\nexport enum WizardSceneAction {\n    Next = 'next',\n    Stay = 'stay',\n    Exit = 'exit',\n}\n\ninterface WizardInternalState {\n    $step?: number\n}\n\n/**\n * Wizard is a special type of Dispatcher\n * that can be used to simplify implementing\n * step-by-step scenes.\n */\nexport class WizardScene<State extends object> extends Dispatcher<State & WizardInternalState> {\n    private _steps = 0\n\n    private _defaultState: State & WizardInternalState = {} as State & WizardInternalState\n\n    setDefaultState(defaultState: State): void {\n        this._defaultState = defaultState as State & WizardInternalState\n    }\n\n    /**\n     * Get the total number of registered steps\n     */\n    get totalSteps(): number {\n        return this._steps\n    }\n\n    /**\n     * Go to the Nth step\n     */\n    async goToStep(state: UpdateState<WizardInternalState>, step: number) {\n        if (step >= this._steps) {\n            await state.exit()\n        } else {\n            await state.merge({ $step: step }, this._defaultState)\n        }\n    }\n\n    /**\n     * Skip N steps\n     */\n    async skip(state: UpdateState<WizardInternalState>, count = 1) {\n        const { $step } = (await state.get()) || {}\n        if ($step === undefined) throw new Error('Wizard state is not initialized')\n\n        return this.goToStep(state, $step + count)\n    }\n\n    /**\n     * Filter that will only pass if the current step is `step`\n     */\n    static onNthStep(step: number) {\n        const filter = filters.state<WizardInternalState>((it) => it.$step === step)\n\n        if (step === 0) return filters.or(filters.stateEmpty, filter)\n\n        return filter\n    }\n\n    /**\n     * Filter that will only pass if the current step is the one after last one added\n     */\n    onCurrentStep() {\n        return WizardScene.onNthStep(this._steps)\n    }\n\n    /**\n     * Add a step to the wizard\n     */\n    addStep(\n        handler: (\n            msg: MessageContext,\n            state: UpdateState<State & WizardInternalState>,\n        ) => MaybeAsync<WizardSceneAction | number>,\n    ): void {\n        const step = this._steps++\n\n        this.onNewMessage(WizardScene.onNthStep(step), async (msg, state) => {\n            const result = await handler(msg, state)\n\n            if (typeof result === 'number') {\n                await this.goToStep(state, result)\n\n                return\n            }\n\n            switch (result) {\n                case 'next': {\n                    await this.goToStep(state, step + 1)\n                    break\n                }\n                case 'exit':\n                    await state.exit()\n                    break\n            }\n        })\n    }\n}\n"]}

package/esm/callback-data-builder.d.ts

@@ -0,0 +1,43 @@
+import { CallbackQuery, MaybeArray } from '@mtcute/client';
+import { UpdateFilter } from './filters/types.js';
+/**
+ * Callback data builder, inspired by [aiogram](https://github.com/aiogram/aiogram).
+ *
+ * This can be used to simplify management of different callbacks.
+ *
+ * [Learn more in the docs](/guide/topics/keyboards.html#callback-data-builders)
+ */
+export declare class CallbackDataBuilder<T extends string> {
+    prefix: string;
+    private readonly _fields;
+    sep: string;
+    /**
+     * @param prefix  Prefix for the data. Use something unique across your bot.
+     * @param fields  Field names in the order they will be serialized.
+     */
+    constructor(prefix: string, ...fields: T[]);
+    /**
+     * Build a callback data string
+     *
+     * @param obj  Object containing the data
+     */
+    build(obj: Record<T, string>): string;
+    /**
+     * Parse callback data to object
+     *
+     * @param data  Callback data as string
+     */
+    parse(data: string): Record<T, string>;
+    /**
+     * Create a filter for this callback data.
+     *
+     * > **Note**: `params` object will be compiled to a RegExp,
+     * > so avoid using characters that have special meaning in regex,
+     * > or use RegExp directly to let the IDE guide you.
+     *
+     * @param params
+     */
+    filter(params: Partial<Record<T, MaybeArray<string | RegExp>>>): UpdateFilter<CallbackQuery, {
+        match: Record<T, string>;
+    }>;
+}

package/esm/callback-data-builder.js

@@ -0,0 +1,95 @@
+import { MtArgumentError } from '@mtcute/client';
+/**
+ * Callback data builder, inspired by [aiogram](https://github.com/aiogram/aiogram).
+ *
+ * This can be used to simplify management of different callbacks.
+ *
+ * [Learn more in the docs](/guide/topics/keyboards.html#callback-data-builders)
+ */
+export class CallbackDataBuilder {
+    /**
+     * @param prefix  Prefix for the data. Use something unique across your bot.
+     * @param fields  Field names in the order they will be serialized.
+     */
+    constructor(prefix, ...fields) {
+        this.prefix = prefix;
+        this.sep = ':';
+        this._fields = fields;
+    }
+    /**
+     * Build a callback data string
+     *
+     * @param obj  Object containing the data
+     */
+    build(obj) {
+        const ret = this.prefix +
+            this.sep +
+            this._fields
+                .map((f) => {
+                const val = obj[f];
+                if (val.includes(this.sep)) {
+                    throw new MtArgumentError(`Value for ${f} ${val} contains separator ${this.sep} and cannot be used.`);
+                }
+                return val;
+            })
+                .join(this.sep);
+        if (ret.length > 64) {
+            throw new MtArgumentError('Resulting callback data is too long.');
+        }
+        return ret;
+    }
+    /**
+     * Parse callback data to object
+     *
+     * @param data  Callback data as string
+     */
+    parse(data) {
+        const parts = data.split(this.sep);
+        if (parts[0] !== this.prefix) {
+            throw new MtArgumentError('Invalid data passed');
+        }
+        if (parts.length !== this._fields.length + 1) {
+            throw new MtArgumentError('Invalid data passed');
+        }
+        const ret = {};
+        parts.forEach((it, idx) => {
+            ret[this._fields[idx - 1]] = it;
+        });
+        return ret;
+    }
+    /**
+     * Create a filter for this callback data.
+     *
+     * > **Note**: `params` object will be compiled to a RegExp,
+     * > so avoid using characters that have special meaning in regex,
+     * > or use RegExp directly to let the IDE guide you.
+     *
+     * @param params
+     */
+    filter(params) {
+        const parts = [];
+        this._fields.forEach((field) => {
+            if (!(field in params)) {
+                parts.push(`[^${this.sep}]*?`);
+                return;
+            }
+            const value = params[field];
+            if (Array.isArray(value)) {
+                parts.push(`(${value.map((i) => (typeof i === 'string' ? i : i.source)).join('|')})`);
+            }
+            else {
+                // noinspection SuspiciousTypeOfGuard
+                parts.push(typeof value === 'string' ? value : value.source);
+            }
+        });
+        const regex = new RegExp(`^${this.prefix}${this.sep}${parts.join(this.sep)}$`);
+        return (query) => {
+            const m = query.dataStr?.match(regex);
+            if (!m)
+                return false;
+            query.match = this.parse(m[0]);
+            return true;
+        };
+    }
+}
+//# sourceMappingURL=callback-data-builder.js.map

package/esm/callback-data-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-data-builder.js","sourceRoot":"","sources":["../../src/callback-data-builder.ts"],"names":[],"mappings":"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","sourcesContent":["import { CallbackQuery, MaybeArray, MtArgumentError } from '@mtcute/client'\n\nimport { UpdateFilter } from './filters/types.js'\n\n/**\n * Callback data builder, inspired by [aiogram](https://github.com/aiogram/aiogram).\n *\n * This can be used to simplify management of different callbacks.\n *\n * [Learn more in the docs](/guide/topics/keyboards.html#callback-data-builders)\n */\nexport class CallbackDataBuilder<T extends string> {\n    private readonly _fields: T[]\n\n    sep = ':'\n\n    /**\n     * @param prefix  Prefix for the data. Use something unique across your bot.\n     * @param fields  Field names in the order they will be serialized.\n     */\n    constructor(\n        public prefix: string,\n        ...fields: T[]\n    ) {\n        this._fields = fields\n    }\n\n    /**\n     * Build a callback data string\n     *\n     * @param obj  Object containing the data\n     */\n    build(obj: Record<T, string>): string {\n        const ret =\n            this.prefix +\n            this.sep +\n            this._fields\n                .map((f) => {\n                    const val = obj[f]\n\n                    if (val.includes(this.sep)) {\n                        throw new MtArgumentError(\n                            `Value for ${f} ${val} contains separator ${this.sep} and cannot be used.`,\n                        )\n                    }\n\n                    return val\n                })\n                .join(this.sep)\n\n        if (ret.length > 64) {\n            throw new MtArgumentError('Resulting callback data is too long.')\n        }\n\n        return ret\n    }\n\n    /**\n     * Parse callback data to object\n     *\n     * @param data  Callback data as string\n     */\n    parse(data: string): Record<T, string> {\n        const parts = data.split(this.sep)\n\n        if (parts[0] !== this.prefix) {\n            throw new MtArgumentError('Invalid data passed')\n        }\n\n        if (parts.length !== this._fields.length + 1) {\n            throw new MtArgumentError('Invalid data passed')\n        }\n\n        const ret = {} as Record<T, string>\n        parts.forEach((it, idx) => {\n            ret[this._fields[idx - 1]] = it\n        })\n\n        return ret\n    }\n\n    /**\n     * Create a filter for this callback data.\n     *\n     * > **Note**: `params` object will be compiled to a RegExp,\n     * > so avoid using characters that have special meaning in regex,\n     * > or use RegExp directly to let the IDE guide you.\n     *\n     * @param params\n     */\n    filter(params: Partial<Record<T, MaybeArray<string | RegExp>>>): UpdateFilter<\n        CallbackQuery,\n        {\n            match: Record<T, string>\n        }\n    > {\n        const parts: string[] = []\n\n        this._fields.forEach((field) => {\n            if (!(field in params)) {\n                parts.push(`[^${this.sep}]*?`)\n\n                return\n            }\n\n            const value = params[field]\n\n            if (Array.isArray(value)) {\n                parts.push(`(${value.map((i) => (typeof i === 'string' ? i : i.source)).join('|')})`)\n            } else {\n                // noinspection SuspiciousTypeOfGuard\n                parts.push(typeof value === 'string' ? value : (value as RegExp).source)\n            }\n        })\n\n        const regex = new RegExp(`^${this.prefix}${this.sep}${parts.join(this.sep)}$`)\n\n        return (query) => {\n            const m = query.dataStr?.match(regex)\n            if (!m) return false\n            ;(\n                query as CallbackQuery & {\n                    match: Record<T, string>\n                }\n            ).match = this.parse(m[0])\n\n            return true\n        }\n    }\n}\n"]}

package/esm/context/base.d.ts

@@ -0,0 +1,8 @@
+import { ParsedUpdate, TelegramClient } from '@mtcute/client';
+export type UpdateContext<T> = T & {
+    client: TelegramClient;
+    _name: Extract<ParsedUpdate, {
+        data: T;
+    }>['name'];
+};
+export type UpdateContextDistributed<T> = T extends never ? never : UpdateContext<T>;

package/esm/context/base.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=base.js.map

package/esm/context/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/context/base.ts"],"names":[],"mappings":"","sourcesContent":["import { ParsedUpdate, TelegramClient } from '@mtcute/client'\n\nexport type UpdateContext<T> = T & {\n    client: TelegramClient\n    _name: Extract<ParsedUpdate, { data: T }>['name']\n}\n\nexport type UpdateContextDistributed<T> = T extends never ? never : UpdateContext<T>\n"]}

package/esm/context/callback-query.d.ts

@@ -0,0 +1,27 @@
+import { CallbackQuery, TelegramClient } from '@mtcute/client';
+import { UpdateContext } from './base.js';
+/**
+ * Context of a callback query update.
+ *
+ * This is a subclass of {@link CallbackQuery}, so all its fields are also available.
+ */
+export declare class CallbackQueryContext extends CallbackQuery implements UpdateContext<CallbackQuery> {
+    readonly client: TelegramClient;
+    readonly _name = "callback_query";
+    constructor(client: TelegramClient, query: CallbackQuery);
+    /** Answer to this callback query */
+    answer(params: Parameters<TelegramClient['answerCallbackQuery']>[1]): Promise<void>;
+    /**
+     *      * Message that contained the callback button that was clicked.
+     *
+     * Note that the message may have been deleted, in which case
+     * `MessageNotFoundError` is thrown.
+     *
+     * Can only be used if `isInline = false`
+     */
+    getMessage(): Promise<import("@mtcute/client").Message>;
+    /**
+     * Edit the message that contained the callback button that was clicked.
+     */
+    editMessage(params: Omit<Parameters<TelegramClient['editInlineMessage']>[0], 'messageId'>): Promise<void | import("@mtcute/client").Message>;
+}

package/esm/context/callback-query.js

@@ -0,0 +1,52 @@
+import { CallbackQuery, getMarkedPeerId, MtArgumentError, MtMessageNotFoundError } from '@mtcute/client';
+/**
+ * Context of a callback query update.
+ *
+ * This is a subclass of {@link CallbackQuery}, so all its fields are also available.
+ */
+export class CallbackQueryContext extends CallbackQuery {
+    constructor(client, query) {
+        super(query.raw, query._peers);
+        this.client = client;
+        this._name = 'callback_query';
+    }
+    /** Answer to this callback query */
+    answer(params) {
+        return this.client.answerCallbackQuery(this.id, params);
+    }
+    /**
+     *      * Message that contained the callback button that was clicked.
+     *
+     * Note that the message may have been deleted, in which case
+     * `MessageNotFoundError` is thrown.
+     *
+     * Can only be used if `isInline = false`
+     */
+    async getMessage() {
+        if (this.raw._ !== 'updateBotCallbackQuery') {
+            throw new MtArgumentError('Cannot get message for inline callback query');
+        }
+        const [msg] = await this.client.getMessages(this.raw.peer, this.raw.msgId);
+        if (!msg) {
+            throw new MtMessageNotFoundError(getMarkedPeerId(this.raw.peer), this.raw.msgId, 'Message not found');
+        }
+        return msg;
+    }
+    /**
+     * Edit the message that contained the callback button that was clicked.
+     */
+    async editMessage(params) {
+        if (this.raw._ === 'updateInlineBotCallbackQuery') {
+            return this.client.editInlineMessage({
+                messageId: this.raw.msgId,
+                ...params,
+            });
+        }
+        return this.client.editMessage({
+            chatId: this.raw.peer,
+            message: this.raw.msgId,
+            ...params,
+        });
+    }
+}
+//# sourceMappingURL=callback-query.js.map