tgplus 1.0.0

package/dist/richMessage.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RichMessage = exports.RichBlocksBuilder = exports.RichHtmlBuilder = exports.RichMarkdownBuilder = void 0;
+/**
+ * Two ways to build a Rich Message (Bot API 10.1, block API added 10.2):
+ *
+ * 1. `RichMessage.markdown()` / `.html()` — write "Rich Markdown"/"Rich HTML"
+ *    text (GFM-flavored markdown: **bold**, ==marked==, ||spoiler||, `- [ ]`
+ *    task items, GFM tables, etc. — see the official docs for the full
+ *    syntax). Simplest for AI-generated or hand-written content. Inline
+ *    photos here (`.photo()`) use Rich Markdown's own `![](url)` image
+ *    syntax directly in the text — confirmed working against a real server.
+ * 2. `RichMessage.blocks()` — build the structured block tree directly
+ *    (Bot API 10.2+), for when you want guaranteed structure (e.g. a table
+ *    with real colspan/rowspan) rather than round-tripping through text.
+ *    Media blocks (photo/video/audio/animation/voice_note) reference a
+ *    separately-declared media item by id — confirmed via two live 400
+ *    errors that Telegram rejects both a missing `id` on the media item and
+ *    an inline file where it expects an `{ id }` reference. Use `.photo()`/
+ *    `.video()`/etc. here (not the markdown builder's `.photo()`) and the id
+ *    bookkeeping is handled for you.
+ *
+ * Both produce an `InputRichMessage` for `ctx.replyRich()` / `api.sendRichMessage()`.
+ */
+class RichMarkdownBuilder {
+    parts = [];
+    text(str) {
+        this.parts.push(str);
+        return this;
+    }
+    heading(str, level = 2) {
+        this.parts.push(`${"#".repeat(level)} ${str}`);
+        return this;
+    }
+    blockquote(str) {
+        this.parts.push(str.split("\n").map((l) => `> ${l}`).join("\n"));
+        return this;
+    }
+    checklist(items) {
+        const normalized = items.map((i) => (typeof i === "string" ? { label: i, done: false } : i));
+        this.parts.push(normalized.map((i) => `- [${i.done ? "x" : " "}] ${i.label}`).join("\n"));
+        return this;
+    }
+    list(items, ordered = false) {
+        this.parts.push(items.map((item, i) => (ordered ? `${i + 1}. ${item}` : `- ${item}`)).join("\n"));
+        return this;
+    }
+    table(headers, rows) {
+        const line = (cells) => `| ${cells.join(" | ")} |`;
+        this.parts.push([line(headers), line(headers.map(() => "---")), ...rows.map(line)].join("\n"));
+        return this;
+    }
+    codeBlock(code, language) {
+        this.parts.push("```" + (language ?? "") + "\n" + code + "\n```");
+        return this;
+    }
+    divider() {
+        this.parts.push("---");
+        return this;
+    }
+    /**
+     * Embeds a photo inline via Rich Markdown's own `![](url "caption")`
+     * image syntax. This does NOT use InputRichMessage.media — that field is
+     * only for RichMessage.blocks()'s structured media blocks, and is a
+     * separate mechanism. This method's output is the confirmed-working path.
+     */
+    photo(url, caption) {
+        this.parts.push(caption ? `![](${url} "${caption}")` : `![](${url})`);
+        return this;
+    }
+    build() {
+        return { markdown: this.parts.join("\n\n") };
+    }
+}
+exports.RichMarkdownBuilder = RichMarkdownBuilder;
+class RichHtmlBuilder {
+    parts = [];
+    raw(html) {
+        this.parts.push(html);
+        return this;
+    }
+    paragraph(html) {
+        this.parts.push(`<p>${html}</p>`);
+        return this;
+    }
+    heading(html, level = 2) {
+        this.parts.push(`<h${level}>${html}</h${level}>`);
+        return this;
+    }
+    build() {
+        return { html: this.parts.join("\n") };
+    }
+}
+exports.RichHtmlBuilder = RichHtmlBuilder;
+function findMediaRef(b) {
+    switch (b.type) {
+        case "photo": return b.photo;
+        case "video": return b.video;
+        case "audio": return b.audio;
+        case "animation": return b.animation;
+        case "voice_note": return b.voice_note;
+        case "document": return b.document;
+        default: return undefined;
+    }
+}
+/** Structural block-based builder (Bot API 10.2+) — produces InputRichBlock[] directly. */
+class RichBlocksBuilder {
+    blocks = [];
+    mediaItems = [];
+    mediaCounter = 0;
+    /**
+     * Declares a media item, returning its id. Prefer the .photo()/.video()/
+     * .audio()/.animation()/.voiceNote() convenience methods below, which call
+     * this for you and add the referencing block in one step — use this
+     * directly only if you're building a raw block yourself via .raw().
+     */
+    media(type, file) {
+        const id = `media-${++this.mediaCounter}`;
+        this.mediaItems.push({ id, type, media: file });
+        return id;
+    }
+    paragraph(text) {
+        this.blocks.push({ type: "paragraph", text });
+        return this;
+    }
+    heading(text, size = 2) {
+        this.blocks.push({ type: "heading", text, size });
+        return this;
+    }
+    divider() {
+        this.blocks.push({ type: "divider" });
+        return this;
+    }
+    table(cells, opts = {}) {
+        this.blocks.push({ type: "table", cells, is_bordered: opts.bordered ? true : undefined, is_striped: opts.striped ? true : undefined, caption: opts.caption });
+        return this;
+    }
+    list(items) {
+        this.blocks.push({ type: "list", items });
+        return this;
+    }
+    details(summary, blocks, open = false) {
+        this.blocks.push({ type: "details", summary, blocks, is_open: open ? true : undefined });
+        return this;
+    }
+    /** Adds a photo block, declaring its media item for you. */
+    photo(file, opts = {}) {
+        const id = this.media("photo", file);
+        this.blocks.push({ type: "photo", photo: { id }, has_spoiler: opts.hasSpoiler ? true : undefined, caption: opts.caption });
+        return this;
+    }
+    video(file, opts = {}) {
+        const id = this.media("video", file);
+        this.blocks.push({ type: "video", video: { id }, has_spoiler: opts.hasSpoiler ? true : undefined, caption: opts.caption });
+        return this;
+    }
+    audio(file, opts = {}) {
+        const id = this.media("audio", file);
+        this.blocks.push({ type: "audio", audio: { id }, caption: opts.caption });
+        return this;
+    }
+    animation(file, opts = {}) {
+        const id = this.media("animation", file);
+        this.blocks.push({ type: "animation", animation: { id }, has_spoiler: opts.hasSpoiler ? true : undefined, caption: opts.caption });
+        return this;
+    }
+    voiceNote(file, opts = {}) {
+        const id = this.media("voice_note", file);
+        this.blocks.push({ type: "voice_note", voice_note: { id }, caption: opts.caption });
+        return this;
+    }
+    /** Bot API 10.3+: adds a document (file) block. */
+    document(file, opts = {}) {
+        const id = this.media("document", file);
+        this.blocks.push({ type: "document", document: { id }, caption: opts.caption });
+        return this;
+    }
+    /** Bot API 10.3+: adds a row of buttons to the rich message. */
+    buttons(buttons) {
+        this.blocks.push({ type: "buttons", buttons });
+        return this;
+    }
+    /** Bot API 10.3+: adds an expandable/collapsible block quotation. */
+    expandableBlockquote(blocks, opts = {}) {
+        this.blocks.push({ type: "expandable_blockquote", blocks, credit: opts.credit });
+        return this;
+    }
+    /** Escape hatch for block types without a dedicated method. If it references media by id, declare that media via .media() first, or build() will throw before you ever hit Telegram's 400. */
+    raw(block) {
+        this.blocks.push(block);
+        return this;
+    }
+    build() {
+        // Dev-time check: catch a block referencing an undeclared media id
+        // locally, with a clear message, instead of letting Telegram's 400 be
+        // the first signal.
+        const declaredIds = new Set(this.mediaItems.map((m) => m.id));
+        const walk = (blocks) => {
+            for (const b of blocks) {
+                const ref = findMediaRef(b);
+                if (ref && !declaredIds.has(ref.id)) {
+                    throw new Error(`tgplus: RichBlocksBuilder block references media id "${ref.id}" that was never declared. ` +
+                        `Use .photo()/.video()/.audio()/.animation()/.voiceNote() (which declare the media for you), ` +
+                        `or call .media(type, file) yourself first and use the returned id.`);
+                }
+                if ("blocks" in b && Array.isArray(b.blocks)) {
+                    walk(b.blocks);
+                }
+            }
+        };
+        walk(this.blocks);
+        return { blocks: this.blocks, media: this.mediaItems.length ? this.mediaItems : undefined };
+    }
+}
+exports.RichBlocksBuilder = RichBlocksBuilder;
+exports.RichMessage = {
+    markdown: () => new RichMarkdownBuilder(),
+    html: () => new RichHtmlBuilder(),
+    blocks: () => new RichBlocksBuilder(),
+};
+//# sourceMappingURL=richMessage.js.map

package/dist/richMessage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"richMessage.js","sourceRoot":"","sources":["../src/richMessage.ts"],"names":[],"mappings":"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"}

package/dist/scenes.d.ts

@@ -0,0 +1,57 @@
+import { Context } from "./context";
+import { Middleware } from "./composer";
+/**
+ * Multi-step conversations: "ask name → ask age → confirm". Requires
+ * `session()` middleware mounted first (Scenes stores its cursor + collected
+ * answers inside ctx.session).
+ * *   const signup = new WizardScene<Context>('signup', [
+ *     async (ctx) => { await ctx.reply('What is your name?'); await ctx.wizard.next(); },
+ *     async (ctx) => { ctx.wizard.state.name = ctx.text; await ctx.reply('How old are you?'); await ctx.wizard.next(); },
+ *     async (ctx) => { ctx.wizard.state.age = ctx.text; await ctx.reply(`Thanks ${ctx.wizard.state.name}!`); await ctx.scene.leave(); },
+ *   ]);
+ *
+ *   const stage = new Stage([signup]);
+ *   bot.use(session());
+ *   bot.use(stage.middleware());
+ *   bot.command('signup', (ctx) => ctx.scene.enter('signup'));
+ *
+ * Each step function runs once per incoming update while the scene is active.
+ * Call `ctx.wizard.next()` at the end of a step once you're ready to move on —
+ * it only advances the pointer; the next step's body runs when the *next*
+ * update arrives, not immediately (so "ask for name" and "ask for age" don't
+ * both fire in the same turn).
+ */
+export interface WizardState {
+    cursor: number;
+    state: Record<string, unknown>;
+    /** Advance to the next step within this same update (e.g. to skip a step programmatically). */
+    next: () => Promise<void>;
+    /** Jump straight to a specific step index (0-based), e.g. to go "back". */
+    selectStep: (index: number) => Promise<void>;
+}
+export interface SceneApi {
+    enter: (sceneId: string, initialState?: Record<string, unknown>) => Promise<void>;
+    leave: () => Promise<void>;
+    current: string | undefined;
+}
+export type WizardContext<C extends Context = Context> = C & {
+    wizard: WizardState;
+    scene: SceneApi;
+};
+export type SceneStep<C extends Context = Context> = (ctx: WizardContext<C>) => unknown | Promise<unknown>;
+export declare class WizardScene<C extends Context = Context> {
+    readonly id: string;
+    private steps;
+    constructor(id: string, steps: SceneStep<C>[]);
+    runStep(ctx: C, index: number): Promise<void>;
+    get stepCount(): number;
+}
+/** Registers scenes and installs the routing middleware that dispatches updates to whichever scene is active. */
+export declare class Stage<C extends Context = Context> {
+    private scenes;
+    constructor(scenes?: WizardScene<C>[]);
+    register(...scenes: WizardScene<C>[]): this;
+    middleware(): Middleware<C>;
+    private buildWizardState;
+    private runCurrent;
+}

package/dist/scenes.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stage = exports.WizardScene = void 0;
+const SESSION_KEY = "__tgplus_scene";
+function sceneSession(ctx) {
+    if (!ctx.session) {
+        throw new Error("Scenes require session() middleware to be mounted before stage.middleware(). See tgplus README.");
+    }
+    const existing = ctx.session[SESSION_KEY];
+    if (existing)
+        return existing;
+    const fresh = { cursor: 0, state: {} };
+    ctx.session[SESSION_KEY] = fresh;
+    return fresh;
+}
+class WizardScene {
+    id;
+    steps;
+    constructor(id, steps) {
+        this.id = id;
+        this.steps = steps;
+    }
+    async runStep(ctx, index) {
+        const step = this.steps[index];
+        if (!step)
+            return; // past the last step
+        await step(ctx);
+    }
+    get stepCount() {
+        return this.steps.length;
+    }
+}
+exports.WizardScene = WizardScene;
+/** Registers scenes and installs the routing middleware that dispatches updates to whichever scene is active. */
+class Stage {
+    scenes = new Map();
+    constructor(scenes = []) {
+        for (const s of scenes)
+            this.scenes.set(s.id, s);
+    }
+    register(...scenes) {
+        for (const s of scenes)
+            this.scenes.set(s.id, s);
+        return this;
+    }
+    middleware() {
+        return async (ctx, next) => {
+            const sess = sceneSession(ctx);
+            const wizardCtx = ctx;
+            wizardCtx.scene = {
+                get current() { return sess.current; },
+                enter: async (sceneId, initialState = {}) => {
+                    if (!this.scenes.has(sceneId))
+                        throw new Error(`tgplus: no scene registered with id "${sceneId}"`);
+                    sess.current = sceneId;
+                    sess.cursor = 0;
+                    sess.state = initialState;
+                    await this.runCurrent(ctx, sess);
+                },
+                leave: async () => {
+                    sess.current = undefined;
+                    sess.cursor = 0;
+                    sess.state = {};
+                },
+            };
+            if (sess.current && this.scenes.has(sess.current)) {
+                wizardCtx.wizard = this.buildWizardState(ctx, sess);
+                await this.runCurrent(ctx, sess);
+                return; // a scene owns this update — don't fall through to other handlers
+            }
+            return next();
+        };
+    }
+    buildWizardState(ctx, sess) {
+        return {
+            cursor: sess.cursor,
+            state: sess.state,
+            // Advances the pointer only — the next step body runs when the *next* update arrives,
+            // not immediately, so e.g. "ask for name" and "ask for age" don't both fire in one turn.
+            next: async () => {
+                sess.cursor += 1;
+                const scene = this.scenes.get(sess.current);
+                if (!scene || sess.cursor >= scene.stepCount) {
+                    sess.current = undefined;
+                    sess.cursor = 0;
+                }
+            },
+            // Jumps the pointer AND runs that step immediately — useful for "go back to step 2 right now".
+            selectStep: async (index) => {
+                sess.cursor = index;
+                ctx.wizard = this.buildWizardState(ctx, sess);
+                await this.scenes.get(sess.current)?.runStep(ctx, index);
+            },
+        };
+    }
+    async runCurrent(ctx, sess) {
+        const scene = this.scenes.get(sess.current);
+        if (!scene)
+            return;
+        ctx.wizard = this.buildWizardState(ctx, sess);
+        await scene.runStep(ctx, sess.cursor);
+    }
+}
+exports.Stage = Stage;
+//# sourceMappingURL=scenes.js.map

package/dist/scenes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenes.js","sourceRoot":"","sources":["../src/scenes.ts"],"names":[],"mappings":"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"}

package/dist/session-redis.d.ts

@@ -0,0 +1,27 @@
+import { SessionStore } from "./session";
+/**
+ * Duck-typed on purpose: works with `ioredis`, `redis` (node-redis v4+), or
+ * anything else exposing get/set/del as async methods — no hard dependency
+ * on any specific Redis client package.
+ */
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+}
+export interface RedisSessionStoreOptions {
+    /** Key prefix so tgplus sessions don't collide with other data in the same Redis instance. Default: "tgplus:session:" */
+    prefix?: string;
+    /** Expire sessions after N seconds of inactivity (e.g. 86400 for one day). Omit for no expiry. */
+    ttlSeconds?: number;
+}
+export declare class RedisSessionStore<S = unknown> implements SessionStore<S> {
+    private client;
+    private opts;
+    private prefix;
+    constructor(client: RedisLikeClient, opts?: RedisSessionStoreOptions);
+    private key;
+    get(key: string): Promise<S | undefined>;
+    set(key: string, value: S): Promise<void>;
+    delete(key: string): Promise<void>;
+}

package/dist/session-redis.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisSessionStore = void 0;
+class RedisSessionStore {
+    client;
+    opts;
+    prefix;
+    constructor(client, opts = {}) {
+        this.client = client;
+        this.opts = opts;
+        this.prefix = opts.prefix ?? "tgplus:session:";
+    }
+    key(k) {
+        return `${this.prefix}${k}`;
+    }
+    async get(key) {
+        const raw = await this.client.get(this.key(key));
+        return raw ? JSON.parse(raw) : undefined;
+    }
+    async set(key, value) {
+        const raw = JSON.stringify(value);
+        if (this.opts.ttlSeconds) {
+            // Works for both ioredis (`set(key, val, 'EX', n)`) and node-redis v4 (`set(key, val, {EX: n})`) callers
+            // who pass ttlSeconds — we call the lowest common denominator form here and let it no-op if unsupported.
+            await this.client.set(this.key(key), raw, "EX", this.opts.ttlSeconds);
+        }
+        else {
+            await this.client.set(this.key(key), raw);
+        }
+    }
+    async delete(key) {
+        await this.client.del(this.key(key));
+    }
+}
+exports.RedisSessionStore = RedisSessionStore;
+//# sourceMappingURL=session-redis.js.map

package/dist/session-redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-redis.js","sourceRoot":"","sources":["../src/session-redis.ts"],"names":[],"mappings":";;;AAoBA,MAAa,iBAAiB;IAGR;IAAiC;IAF7C,MAAM,CAAS;IAEvB,YAAoB,MAAuB,EAAU,OAAiC,EAAE;QAApE,WAAM,GAAN,MAAM,CAAiB;QAAU,SAAI,GAAJ,IAAI,CAA+B;QACtF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,iBAAiB,CAAC;IACjD,CAAC;IAEO,GAAG,CAAC,CAAS;QACnB,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACjD,OAAO,GAAG,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAQ;QAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACzB,yGAAyG;YACzG,yGAAyG;YACzG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACxE,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC;CACF;AA9BD,8CA8BC"}

package/dist/session-sqlite.d.ts

@@ -0,0 +1,29 @@
+import { SessionStore } from "./session";
+/**
+ * Duck-typed on purpose: works with `better-sqlite3` (the common choice for
+ * self-hosted bots that don't want to run Redis) without a hard dependency
+ * on it. Any object exposing this synchronous shape works — including an
+ * in-memory fake for tests.
+ */
+export interface SqliteLikeDatabase {
+    exec(sql: string): unknown;
+    prepare(sql: string): {
+        run(...params: unknown[]): unknown;
+        get(...params: unknown[]): unknown;
+    };
+}
+export interface SqliteSessionStoreOptions {
+    /** Table name to store sessions in. Must be a plain identifier (letters, numbers, underscores) — validated to avoid building unsafe SQL. Default: "tgplus_sessions". */
+    tableName?: string;
+}
+export declare class SqliteSessionStore<S = unknown> implements SessionStore<S> {
+    private db;
+    private tableName;
+    private getStmt;
+    private setStmt;
+    private deleteStmt;
+    constructor(db: SqliteLikeDatabase, opts?: SqliteSessionStoreOptions);
+    get(key: string): S | undefined;
+    set(key: string, value: S): void;
+    delete(key: string): void;
+}

package/dist/session-sqlite.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteSessionStore = void 0;
+const VALID_TABLE_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+class SqliteSessionStore {
+    db;
+    tableName;
+    getStmt;
+    setStmt;
+    deleteStmt;
+    constructor(db, opts = {}) {
+        this.db = db;
+        this.tableName = opts.tableName ?? "tgplus_sessions";
+        if (!VALID_TABLE_NAME.test(this.tableName)) {
+            throw new Error(`tgplus: invalid SqliteSessionStore tableName "${this.tableName}" — must match ${VALID_TABLE_NAME}`);
+        }
+        this.db.exec(`CREATE TABLE IF NOT EXISTS ${this.tableName} (key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
+        this.getStmt = this.db.prepare(`SELECT value FROM ${this.tableName} WHERE key = ?`);
+        this.setStmt = this.db.prepare(`INSERT INTO ${this.tableName} (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`);
+        this.deleteStmt = this.db.prepare(`DELETE FROM ${this.tableName} WHERE key = ?`);
+    }
+    get(key) {
+        const row = this.getStmt.get(key);
+        return row ? JSON.parse(row.value) : undefined;
+    }
+    set(key, value) {
+        this.setStmt.run(key, JSON.stringify(value));
+    }
+    delete(key) {
+        this.deleteStmt.run(key);
+    }
+}
+exports.SqliteSessionStore = SqliteSessionStore;
+//# sourceMappingURL=session-sqlite.js.map

package/dist/session-sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-sqlite.js","sourceRoot":"","sources":["../src/session-sqlite.ts"],"names":[],"mappings":";;;AAqBA,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD,MAAa,kBAAkB;IAMT;IALZ,SAAS,CAAS;IAClB,OAAO,CAA4C;IACnD,OAAO,CAA4C;IACnD,UAAU,CAA4C;IAE9D,YAAoB,EAAsB,EAAE,OAAkC,EAAE;QAA5D,OAAE,GAAF,EAAE,CAAoB;QACxC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,iBAAiB,CAAC;QACrD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,iDAAiD,IAAI,CAAC,SAAS,kBAAkB,gBAAgB,EAAE,CAAC,CAAC;QACvH,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,8BAA8B,IAAI,CAAC,SAAS,8CAA8C,CAAC,CAAC;QACzG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,qBAAqB,IAAI,CAAC,SAAS,gBAAgB,CAAC,CAAC;QACpF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAC5B,eAAe,IAAI,CAAC,SAAS,mFAAmF,CACjH,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,eAAe,IAAI,CAAC,SAAS,gBAAgB,CAAC,CAAC;IACnF,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAkC,CAAC;QACnE,OAAO,GAAG,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACxD,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF;AA/BD,gDA+BC"}

package/dist/session.d.ts

@@ -0,0 +1,30 @@
+import { Context } from "./context";
+import { Middleware } from "./composer";
+/**
+ * Pluggable session storage. Swap MemorySessionStore for RedisSessionStore
+ * (see session-redis.ts) in production — same interface, no other code changes.
+ */
+export interface SessionStore<S = unknown> {
+    get(key: string): Promise<S | undefined> | S | undefined;
+    set(key: string, value: S): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+}
+/** Default store: fine for local dev/single-process bots. State is lost on restart. */
+export declare class MemorySessionStore<S = unknown> implements SessionStore<S> {
+    private map;
+    get(key: string): S | undefined;
+    set(key: string, value: S): void;
+    delete(key: string): void;
+}
+export interface SessionOptions<S> {
+    store?: SessionStore<S>;
+    /** Defaults to one session per chat. Use e.g. `ctx => ctx.from?.id` for a per-user session instead. */
+    getSessionKey?: (ctx: Context) => string | undefined;
+    defaultSession?: () => S;
+}
+/**
+ * Attaches `ctx.session` (persisted via `store` across updates, keyed per chat
+ * by default) and saves it back automatically after your handlers run —
+ * you just read/write `ctx.session.whatever` like a plain object.
+ */
+export declare function session<S extends object = Record<string, unknown>>(opts?: SessionOptions<S>): Middleware<Context>;

package/dist/session.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemorySessionStore = void 0;
+exports.session = session;
+/** Default store: fine for local dev/single-process bots. State is lost on restart. */
+class MemorySessionStore {
+    map = new Map();
+    get(key) { return this.map.get(key); }
+    set(key, value) { this.map.set(key, value); }
+    delete(key) { this.map.delete(key); }
+}
+exports.MemorySessionStore = MemorySessionStore;
+/**
+ * Attaches `ctx.session` (persisted via `store` across updates, keyed per chat
+ * by default) and saves it back automatically after your handlers run —
+ * you just read/write `ctx.session.whatever` like a plain object.
+ */
+function session(opts = {}) {
+    const store = opts.store ?? new MemorySessionStore();
+    const getKey = opts.getSessionKey ?? ((ctx) => (ctx.chat ? String(ctx.chat.id) : undefined));
+    const makeDefault = opts.defaultSession ?? (() => ({}));
+    return async (ctx, next) => {
+        const key = getKey(ctx);
+        if (key === undefined)
+            return next();
+        const existing = await store.get(key);
+        ctx.session = (existing ?? makeDefault());
+        await next();
+        if (ctx.session === undefined)
+            await store.delete(key);
+        else
+            await store.set(key, ctx.session);
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":";;;AAiCA,0BAiBC;AArCD,uFAAuF;AACvF,MAAa,kBAAkB;IACrB,GAAG,GAAG,IAAI,GAAG,EAAa,CAAC;IACnC,GAAG,CAAC,GAAW,IAAI,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9C,GAAG,CAAC,GAAW,EAAE,KAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACxD,MAAM,CAAC,GAAW,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC9C;AALD,gDAKC;AASD;;;;GAIG;AACH,SAAgB,OAAO,CAA6C,OAA0B,EAAE;IAC9F,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,kBAAkB,EAAK,CAAC;IACxD,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IACtG,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,IAAI,CAAC,GAAM,EAAE,CAAC,CAAC,EAAQ,CAAA,CAAC,CAAC;IAEhE,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACzB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,EAAE,CAAC;QAErC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,GAAG,CAAC,OAAO,GAAG,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAuC,CAAC;QAEhF,MAAM,IAAI,EAAE,CAAC;QAEb,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS;YAAE,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;;YAClD,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,OAAuB,CAAC,CAAC;IACzD,CAAC,CAAC;AACJ,CAAC"}