@adriangalilea/utils 0.7.0 → 0.8.0

package/dist/bot/menu.d.ts.map

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

package/dist/bot/menu.js

@@ -0,0 +1,284 @@
+/**
+ * Composable settings menu — registers a single slash command, renders
+ * an `InlineKeyboard`, routes callbacks. Features (language, history,
+ * etc.) contribute items; the bot builder adds custom items inline.
+ *
+ * ## Why menu is a separate primitive
+ *
+ * The user-facing menu is just UI — composing items. Features (per-user
+ * state, recording, gates) have their OWN runtime behaviour independent
+ * of any menu.
+ *
+ * ## GDPR rights (Forget / Export)
+ *
+ * If you pass `personalData: { storage }`, the menu adds two buttons:
+ *
+ *   - 🗑 Forget my data — `storage.delete(sessionKey(userId))`
+ *   - 📥 Export my data — `storage.get(sessionKey(userId))` → JSON file
+ *
+ * Because all per-user state across our plugins lives in ONE shared
+ * session record (see `bot/language`, `bot/message-history`), wiping
+ * or exporting that single key covers everything in one shot. No
+ * registry, no cascade, no per-plugin coordination.
+ *
+ * The `sessionKey` option defaults to `String(userId)` — matching
+ * `@gramio/session`'s default `getSessionKey: (ctx) => `${ctx.senderId}`.
+ * If you customize the session's `getSessionKey`, pass a matching
+ * function here.
+ *
+ * ## Privacy URL
+ *
+ * `privacy` defaults to [Telegram's Standard Bot Privacy Policy](https://telegram.org/privacy-tpa).
+ * Override when you retain content or process data beyond what the
+ * standard covers.
+ *
+ * Peer deps: `gramio`, `@gramio/storage`.
+ *
+ * @example  Personal LLM bot — language only, no retention
+ *
+ * import { language } from '@adriangalilea/utils/bot/language'
+ * import { botMenu } from '@adriangalilea/utils/bot/menu'
+ *
+ * const lang = language({ session: userSession, supported: ['en','es'] as const, default: 'en' })
+ *
+ * const menu = botMenu({
+ *   command: 'settings',
+ *   description: 'Open settings',
+ *   adminContact: '@adriangalilea',
+ *   items: [lang.menuItem],
+ * })
+ *
+ * bot.extend(userSession).extend(lang.plugin).extend(menu.plugin)
+ *
+ * @example  Bot with retention — adds Forget/Export
+ *
+ * const menu = botMenu({
+ *   command: 'settings',
+ *   description: 'Open settings',
+ *   adminContact: '@adriangalilea',
+ *   privacy: 'https://yourbot.com/privacy',
+ *   personalData: { storage },              // ← enables Forget/Export
+ *   items: [lang.menuItem],
+ * })
+ *
+ * bot
+ *   .extend(userSession)
+ *   .extend(history.plugin)
+ *   .extend(menu.plugin)
+ */
+import { CallbackData, InlineKeyboard, Plugin, } from 'gramio';
+const DEFAULT_COMMAND = 'settings';
+const DEFAULT_DESCRIPTION = 'Open settings menu';
+const DEFAULT_PRIVACY_URL = 'https://telegram.org/privacy-tpa';
+const DEFAULT_HEADER = '⚙️ Settings';
+const DEFAULT_SESSION_KEY = (userId) => String(userId);
+// ─── callback data schemas ─────────────────────────────────────────
+const navCb = new CallbackData('mNav').string('path');
+const actCb = new CallbackData('mAct').string('path');
+const forgetConfirmCb = new CallbackData('mFcfm');
+const forgetCancelCb = new CallbackData('mFcnl');
+const exportCb = new CallbackData('mExp');
+export class BotMenu {
+    /** @internal */
+    _items;
+    /** @internal */
+    _opts;
+    constructor(opts) {
+        this._items = [...(opts.items ?? [])];
+        this._opts = {
+            command: opts.command ?? DEFAULT_COMMAND,
+            description: opts.description ?? DEFAULT_DESCRIPTION,
+            privacy: opts.privacy ?? DEFAULT_PRIVACY_URL,
+            header: opts.header ?? DEFAULT_HEADER,
+            adminContact: opts.adminContact,
+            personalData: opts.personalData
+                ? {
+                    storage: opts.personalData.storage,
+                    sessionKey: opts.personalData.sessionKey ?? DEFAULT_SESSION_KEY,
+                }
+                : null,
+        };
+    }
+    /** Append a custom item. Mutates the menu. */
+    add(item) {
+        this._items.push(item);
+        return this;
+    }
+    /** The gramio plugin: registers the slash command + all callback handlers. */
+    get plugin() {
+        return buildMenuPlugin(this);
+    }
+}
+export const botMenu = (opts) => new BotMenu(opts);
+// ─── internal: rendering + plugin ──────────────────────────────────
+const labelOf = (l, ctx) => typeof l === 'function' ? l(ctx) : l;
+const itemsForPath = (root, path) => {
+    if (path.length === 0)
+        return root;
+    const [head, ...rest] = path;
+    const found = root.find((i) => i.id === head);
+    if (!found || !('submenu' in found))
+        return null;
+    return itemsForPath(found.submenu, rest);
+};
+const itemForPath = (root, path) => {
+    if (path.length === 0)
+        return null;
+    let current = root;
+    let last;
+    for (const segment of path) {
+        if (!current)
+            return null;
+        last = current.find((i) => i.id === segment);
+        if (!last)
+            return null;
+        current = 'submenu' in last ? last.submenu : undefined;
+    }
+    return last ?? null;
+};
+const renderKeyboard = (menu, items, ctx, parentPath) => {
+    const kb = new InlineKeyboard();
+    const sorted = [...items]
+        .filter((i) => (i.visible ? i.visible(ctx) : true))
+        .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+    for (const item of sorted) {
+        const path = [...parentPath, item.id].join('.');
+        const label = labelOf(item.label, ctx);
+        if ('action' in item) {
+            kb.text(label, actCb.pack({ path }));
+        }
+        else if ('url' in item) {
+            kb.url(label, item.url);
+        }
+        else {
+            kb.text(label, navCb.pack({ path }));
+        }
+        kb.row();
+    }
+    if (parentPath.length === 0) {
+        // GDPR rights buttons at the root view.
+        if (menu._opts.personalData) {
+            kb.text('🗑 Forget my data', actCb.pack({ path: '_forget' }));
+            kb.row();
+            kb.text('📥 Export my data', exportCb.pack({}));
+            kb.row();
+        }
+        // Privacy link.
+        kb.url('📖 Privacy', menu._opts.privacy);
+        kb.row();
+    }
+    else {
+        const backPath = parentPath.slice(0, -1).join('.');
+        kb.text('⬅️ Back', navCb.pack({ path: backPath || '_root' }));
+    }
+    return kb;
+};
+const renderConfirmForget = () => new InlineKeyboard()
+    .text('✅ Confirm delete', forgetConfirmCb.pack({}))
+    .row()
+    .text('⬅️ Cancel', forgetCancelCb.pack({}));
+const buildMenuPlugin = (menu) => {
+    const { command, description, header, personalData, adminContact } = menu._opts;
+    return new Plugin('@adriangalilea/utils/bot/menu')
+        .command(command, { description }, async (ctx) => {
+        const kb = renderKeyboard(menu, menu._items, ctx, []);
+        await ctx.send(labelOf(header, ctx), { reply_markup: kb });
+    })
+        // Navigate (root / submenu)
+        .callbackQuery(navCb, async (ctx) => {
+        const raw = ctx.queryData.path;
+        const segments = raw === '_root' ? [] : raw.split('.');
+        const items = itemsForPath(menu._items, segments);
+        if (!items) {
+            await ctx.answer({ text: 'Menu out of date.' });
+            return;
+        }
+        await ctx.answer({});
+        const kb = renderKeyboard(menu, items, ctx, segments);
+        try {
+            await ctx.editText(labelOf(header, ctx), { reply_markup: kb });
+        }
+        catch {
+            // message too old to edit
+        }
+    })
+        // Action items + the forget pre-confirmation
+        .callbackQuery(actCb, async (ctx) => {
+        const raw = ctx.queryData.path;
+        if (raw === '_forget') {
+            await ctx.answer({});
+            try {
+                await ctx.editText('⚠️ Delete all your data?\n\n' +
+                    'This removes the session record we keep about you ' +
+                    '(preferences, history, access state). Not reversible.', { reply_markup: renderConfirmForget() });
+            }
+            catch {
+                /* ignore */
+            }
+            return;
+        }
+        const item = itemForPath(menu._items, raw.split('.'));
+        if (!item || !('action' in item)) {
+            await ctx.answer({ text: 'Item not found.' });
+            return;
+        }
+        await ctx.answer({});
+        await item.action(ctx);
+    })
+        // Forget — confirm path
+        .callbackQuery(forgetConfirmCb, async (ctx) => {
+        if (!personalData) {
+            await ctx.answer({ text: 'Not configured.', show_alert: true });
+            return;
+        }
+        const userId = ctx.from?.id;
+        if (userId === undefined)
+            return ctx.answer({ text: 'No user.' });
+        try {
+            await personalData.storage.delete(personalData.sessionKey(userId));
+            await ctx.answer({ text: 'Deleted.' });
+            try {
+                await ctx.editText('✅ Your data has been deleted.');
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        catch (e) {
+            console.error('[menu] /forget failed', e);
+            await ctx.answer({ text: 'Failed.' });
+            await ctx.send(`❌ Could not delete your data.\n\nPlease contact ${adminContact}.`);
+        }
+    })
+        .callbackQuery(forgetCancelCb, async (ctx) => {
+        await ctx.answer({});
+        const kb = renderKeyboard(menu, menu._items, ctx, []);
+        try {
+            await ctx.editText(labelOf(header, ctx), { reply_markup: kb });
+        }
+        catch {
+            /* ignore */
+        }
+    })
+        // Export — JSON file with the user's whole session record
+        .callbackQuery(exportCb, async (ctx) => {
+        if (!personalData) {
+            await ctx.answer({ text: 'Not configured.', show_alert: true });
+            return;
+        }
+        const userId = ctx.from?.id;
+        if (userId === undefined)
+            return ctx.answer({ text: 'No user.' });
+        const record = (await personalData.storage.get(personalData.sessionKey(userId))) ?? {};
+        const file = new File([JSON.stringify({ userId, exportedAt: Date.now(), data: record }, null, 2)], `my-data-${userId}-${Date.now()}.json`, { type: 'application/json' });
+        await ctx.answer({});
+        try {
+            await ctx.sendDocument(file, { caption: '📥 Your data export' });
+        }
+        catch (e) {
+            console.error('[menu] /export sendDocument failed', e);
+            await ctx.send(`❌ Could not send your data export.\n\nPlease contact ${adminContact}.`);
+        }
+    });
+};
+//# sourceMappingURL=menu.js.map

package/dist/bot/menu.js.map

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

package/dist/bot/message-history.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Per-user rolling message history for GramIO bots — opt-in, with
+ * retention.
+ *
+ * Follows the same shared-session pattern as `bot/language`: the
+ * user creates a `session()` once at bot level, and each feature
+ * plugin (including this one) declares it as a dependency. gramio
+ * dedupes the runtime extension; the types flow.
+ *
+ * ## What this plugin owns
+ *
+ *   - Appends each incoming user message to `ctx.session.history.items`
+ *   - Prunes entries older than `retentionDays` or beyond `maxMessages`
+ *   - Exposes a read-only pruned snapshot at `ctx.history` for handlers
+ *
+ * ## GDPR caveat — retention IS personal data
+ *
+ * Unlike `bot/language` (preference data, covered by Telegram's standard
+ * privacy policy), retaining user **message content** is the one thing
+ * the [standard policy](https://telegram.org/privacy-tpa) does NOT cover
+ * by default. If you extend `messageHistory`, you should:
+ *
+ *   1. Set a custom `privacy` URL on your `botMenu` describing what you
+ *      retain and for how long.
+ *   2. Pass `personalData: { storage }` to your `botMenu` so 🗑 Forget
+ *      and 📥 Export buttons appear — letting users see and delete
+ *      the data you keep about them.
+ *
+ * These are not enforced by this plugin (would couple it to menu); they
+ * are documented as the bot author's legal responsibility.
+ *
+ * ## Storage layout
+ *
+ * Lives entirely inside the shared session record:
+ *
+ *   storage[String(senderId)] = {
+ *     ...other plugins' fields,
+ *     history: { items: [HistoryEntry, ...] }
+ *   }
+ *
+ * Peer deps: `gramio`, `@gramio/session`.
+ *
+ * @example
+ * import { Bot } from 'gramio'
+ * import { session } from '@gramio/session'
+ * import { redisStorage } from '@gramio/storage-redis'
+ * import { messageHistory } from '@adriangalilea/utils/bot/message-history'
+ *
+ * const userSession = session({ storage: redisStorage(), key: 'session', initial: () => ({}) })
+ *
+ * const history = messageHistory({
+ *   session: userSession,
+ *   maxMessages: 100,
+ *   retentionDays: 7,
+ * })
+ *
+ * const bot = new Bot(process.env.BOT_TOKEN!)
+ *   .extend(userSession)
+ *   .extend(history.plugin)
+ *   .command('replay', (ctx) => {
+ *     const last = ctx.history.slice(-3).map((e) => e.text).join('\n---\n')
+ *     return ctx.send(last || '(no history)')
+ *   })
+ */
+import { type DeriveDefinitions, Plugin } from 'gramio';
+import { session } from '@gramio/session';
+export type HistoryEntry = {
+    /** Telegram message id. */
+    messageId: number;
+    /** Unix seconds (Telegram's `message.date`). */
+    date: number;
+    /** Message text, or empty string if non-text. */
+    text: string;
+};
+export type HistoryRecord = {
+    items: HistoryEntry[];
+};
+/** Loose session shape — this plugin only touches the `history` field. */
+type SessionLike = {
+    history?: HistoryRecord;
+};
+/** @internal — kept unexported so it doesn't clash with peers' refs. */
+type HistorySessionPluginRef = ReturnType<typeof session<SessionLike, 'session'>>;
+export type MessageHistoryOptions = {
+    /**
+     * Shared session plugin. This plugin extends it for the type flow;
+     * gramio's runtime dedup ensures it only runs once per update.
+     */
+    session: HistorySessionPluginRef;
+    /** Ring buffer cap. Oldest entries dropped when exceeded. */
+    maxMessages: number;
+    /** Entries older than this (in days) are dropped on read. */
+    retentionDays: number;
+};
+export type MessageHistoryFeature = {
+    plugin: ReturnType<typeof buildHistoryPlugin>;
+};
+type HistoryDerives = {
+    history: ReadonlyArray<HistoryEntry>;
+};
+export declare const messageHistory: (opts: MessageHistoryOptions) => MessageHistoryFeature;
+declare const buildHistoryPlugin: (args: {
+    sessionPlugin: HistorySessionPluginRef;
+    maxMessages: number;
+    retentionDays: number;
+}) => Plugin<{}, DeriveDefinitions & {
+    global: HistoryDerives;
+} & {
+    message: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    channel_post: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    inline_query: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chosen_inline_result: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    callback_query: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    shipping_query: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    pre_checkout_query: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    poll_answer: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chat_join_request: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_members: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_title: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_photo: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    delete_chat_photo: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    group_chat_created: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    message_auto_delete_timer_changed: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    migrate_to_chat_id: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    migrate_from_chat_id: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    pinned_message: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    invoice: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    successful_payment: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chat_shared: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    proximity_alert_triggered: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_scheduled: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_started: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_ended: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_participants_invited: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    web_app_data: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    location: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    passport_data: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+} & {
+    message: HistoryDerives;
+    callback_query: HistoryDerives;
+}, {}>;
+export {};
+//# sourceMappingURL=message-history.d.ts.map

package/dist/bot/message-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-history.d.ts","sourceRoot":"","sources":["../../src/bot/message-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAIzC,MAAM,MAAM,YAAY,GAAG;IACzB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB,CAAA;AAED,0EAA0E;AAC1E,KAAK,WAAW,GAAG;IAAE,OAAO,CAAC,EAAE,aAAa,CAAA;CAAE,CAAA;AAE9C,wEAAwE;AACxE,KAAK,uBAAuB,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAA;AAEjF,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;OAGG;IACH,OAAO,EAAE,uBAAuB,CAAA;IAChC,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAA;IACnB,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAA;CAC9C,CAAA;AAID,KAAK,cAAc,GAAG;IACpB,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;CACrC,CAAA;AAgBD,eAAO,MAAM,cAAc,GAAI,MAAM,qBAAqB,KAAG,qBAW5D,CAAA;AAID,QAAA,MAAM,kBAAkB,GAAI,MAAM;IAChC,aAAa,EAAE,uBAAuB,CAAA;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;CACtB;YAGqD,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA8BnE,CAAA"}

package/dist/bot/message-history.js

@@ -0,0 +1,111 @@
+/**
+ * Per-user rolling message history for GramIO bots — opt-in, with
+ * retention.
+ *
+ * Follows the same shared-session pattern as `bot/language`: the
+ * user creates a `session()` once at bot level, and each feature
+ * plugin (including this one) declares it as a dependency. gramio
+ * dedupes the runtime extension; the types flow.
+ *
+ * ## What this plugin owns
+ *
+ *   - Appends each incoming user message to `ctx.session.history.items`
+ *   - Prunes entries older than `retentionDays` or beyond `maxMessages`
+ *   - Exposes a read-only pruned snapshot at `ctx.history` for handlers
+ *
+ * ## GDPR caveat — retention IS personal data
+ *
+ * Unlike `bot/language` (preference data, covered by Telegram's standard
+ * privacy policy), retaining user **message content** is the one thing
+ * the [standard policy](https://telegram.org/privacy-tpa) does NOT cover
+ * by default. If you extend `messageHistory`, you should:
+ *
+ *   1. Set a custom `privacy` URL on your `botMenu` describing what you
+ *      retain and for how long.
+ *   2. Pass `personalData: { storage }` to your `botMenu` so 🗑 Forget
+ *      and 📥 Export buttons appear — letting users see and delete
+ *      the data you keep about them.
+ *
+ * These are not enforced by this plugin (would couple it to menu); they
+ * are documented as the bot author's legal responsibility.
+ *
+ * ## Storage layout
+ *
+ * Lives entirely inside the shared session record:
+ *
+ *   storage[String(senderId)] = {
+ *     ...other plugins' fields,
+ *     history: { items: [HistoryEntry, ...] }
+ *   }
+ *
+ * Peer deps: `gramio`, `@gramio/session`.
+ *
+ * @example
+ * import { Bot } from 'gramio'
+ * import { session } from '@gramio/session'
+ * import { redisStorage } from '@gramio/storage-redis'
+ * import { messageHistory } from '@adriangalilea/utils/bot/message-history'
+ *
+ * const userSession = session({ storage: redisStorage(), key: 'session', initial: () => ({}) })
+ *
+ * const history = messageHistory({
+ *   session: userSession,
+ *   maxMessages: 100,
+ *   retentionDays: 7,
+ * })
+ *
+ * const bot = new Bot(process.env.BOT_TOKEN!)
+ *   .extend(userSession)
+ *   .extend(history.plugin)
+ *   .command('replay', (ctx) => {
+ *     const last = ctx.history.slice(-3).map((e) => e.text).join('\n---\n')
+ *     return ctx.send(last || '(no history)')
+ *   })
+ */
+import { Plugin } from 'gramio';
+// ─── helpers ───────────────────────────────────────────────────────
+const prune = (items, maxMessages, retentionDays) => {
+    const cutoffSec = Math.floor(Date.now() / 1000) - retentionDays * 86400;
+    const fresh = items.filter((e) => e.date >= cutoffSec);
+    return fresh.slice(-maxMessages);
+};
+// ─── feature factory ───────────────────────────────────────────────
+export const messageHistory = (opts) => {
+    if (opts.maxMessages <= 0)
+        throw new Error('messageHistory: maxMessages must be > 0');
+    if (opts.retentionDays <= 0)
+        throw new Error('messageHistory: retentionDays must be > 0');
+    const plugin = buildHistoryPlugin({
+        sessionPlugin: opts.session,
+        maxMessages: opts.maxMessages,
+        retentionDays: opts.retentionDays,
+    });
+    return { plugin };
+};
+// ─── plugin builder ────────────────────────────────────────────────
+const buildHistoryPlugin = (args) => {
+    const { sessionPlugin, maxMessages, retentionDays } = args;
+    return new Plugin('@adriangalilea/utils/bot/message-history')
+        .extend(sessionPlugin)
+        // Record incoming messages with text. Service messages, edits,
+        // and callback queries don't append — only direct user input.
+        .on('message', async (ctx, next) => {
+        if (ctx.text !== undefined) {
+            const entry = {
+                messageId: ctx.id,
+                date: ctx.payload.date,
+                text: ctx.text,
+            };
+            const cur = ctx.session.history?.items ?? [];
+            ctx.session.history = {
+                items: [...prune(cur, maxMessages, retentionDays), entry].slice(-maxMessages),
+            };
+        }
+        return next();
+    })
+        // Pruned read-only view for handlers downstream.
+        .derive(['message', 'callback_query'], (ctx) => ({
+        history: prune(ctx.session.history?.items ?? [], maxMessages, retentionDays),
+    }));
+};
+//# sourceMappingURL=message-history.js.map