@adriangalilea/utils 0.7.0 → 0.9.0

package/dist/bot/menu.js

@@ -0,0 +1,331 @@
+/**
+ * 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';
+import { say } from '../say/index.js';
+const FALLBACK_LANG = 'en';
+const ctxLang = (ctx) => ctx.session?.language ?? FALLBACK_LANG;
+const DEFAULT_COMMAND = 'settings';
+const DEFAULT_DESCRIPTION = 'Open settings menu';
+const DEFAULT_PRIVACY_URL = 'https://telegram.org/privacy-tpa';
+const DEFAULT_HEADER = { en: '⚙️ Settings', es: '⚙️ Ajustes' };
+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) => {
+    const resolved = typeof l === 'function' ? l(ctx) : l;
+    if (typeof resolved === 'string')
+        return resolved;
+    return say(resolved, ctxLang(ctx));
+};
+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();
+    }
+    const lang = ctxLang(ctx);
+    if (parentPath.length === 0) {
+        // GDPR rights buttons at the root view.
+        if (menu._opts.personalData) {
+            kb.text(say({ en: '🗑 Forget my data', es: '🗑 Olvidar mis datos' }, lang), actCb.pack({ path: '_forget' }));
+            kb.row();
+            kb.text(say({ en: '📥 Export my data', es: '📥 Exportar mis datos' }, lang), exportCb.pack({}));
+            kb.row();
+        }
+        // Privacy link.
+        kb.url(say({ en: '📖 Privacy', es: '📖 Privacidad' }, lang), menu._opts.privacy);
+        kb.row();
+    }
+    else {
+        const backPath = parentPath.slice(0, -1).join('.');
+        kb.text(say({ en: '⬅️ Back', es: '⬅️ Volver' }, lang), navCb.pack({ path: backPath || '_root' }));
+    }
+    return kb;
+};
+const renderConfirmForget = (lang) => new InlineKeyboard()
+    .text(say({ en: '✅ Confirm delete', es: '✅ Confirmar borrado' }, lang), forgetConfirmCb.pack({}))
+    .row()
+    .text(say({ en: '⬅️ Cancel', es: '⬅️ Cancelar' }, lang), 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 lang = ctxLang(ctx);
+        const raw = ctx.queryData.path;
+        const segments = raw === '_root' ? [] : raw.split('.');
+        const items = itemsForPath(menu._items, segments);
+        if (!items) {
+            await ctx.answer({
+                text: say({ en: 'Menu out of date.', es: 'Menú obsoleto.' }, lang),
+            });
+            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 lang = ctxLang(ctx);
+        const raw = ctx.queryData.path;
+        if (raw === '_forget') {
+            await ctx.answer({});
+            try {
+                await ctx.editText(say({
+                    en: '⚠️ Delete all your data?\n\n' +
+                        'This removes the session record we keep about you ' +
+                        '(preferences, history, access state). Not reversible.',
+                    es: '⚠️ ¿Borrar todos tus datos?\n\n' +
+                        'Esto elimina el registro de sesión que guardamos sobre ti ' +
+                        '(preferencias, historial, estado de acceso). No se puede deshacer.',
+                }, lang), { reply_markup: renderConfirmForget(lang) });
+            }
+            catch {
+                /* ignore */
+            }
+            return;
+        }
+        const item = itemForPath(menu._items, raw.split('.'));
+        if (!item || !('action' in item)) {
+            await ctx.answer({
+                text: say({ en: 'Item not found.', es: 'Elemento no encontrado.' }, lang),
+            });
+            return;
+        }
+        await ctx.answer({});
+        await item.action(ctx);
+    })
+        // Forget — confirm path
+        .callbackQuery(forgetConfirmCb, async (ctx) => {
+        const lang = ctxLang(ctx);
+        if (!personalData) {
+            await ctx.answer({
+                text: say({ en: 'Not configured.', es: 'No configurado.' }, lang),
+                show_alert: true,
+            });
+            return;
+        }
+        const userId = ctx.from?.id;
+        if (userId === undefined)
+            return ctx.answer({
+                text: say({ en: 'No user.', es: 'Sin usuario.' }, lang),
+            });
+        try {
+            await personalData.storage.delete(personalData.sessionKey(userId));
+            await ctx.answer({
+                text: say({ en: 'Deleted.', es: 'Borrado.' }, lang),
+            });
+            try {
+                await ctx.editText(say({
+                    en: '✅ Your data has been deleted.',
+                    es: '✅ Tus datos han sido borrados.',
+                }, lang));
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        catch (e) {
+            console.error('[menu] /forget failed', e);
+            await ctx.answer({
+                text: say({ en: 'Failed.', es: 'Falló.' }, lang),
+            });
+            await ctx.send(say({
+                en: `❌ Could not delete your data.\n\nPlease contact ${adminContact}.`,
+                es: `❌ No se han podido borrar tus datos.\n\nContacta con ${adminContact}.`,
+            }, lang));
+        }
+    })
+        .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) => {
+        const lang = ctxLang(ctx);
+        if (!personalData) {
+            await ctx.answer({
+                text: say({ en: 'Not configured.', es: 'No configurado.' }, lang),
+                show_alert: true,
+            });
+            return;
+        }
+        const userId = ctx.from?.id;
+        if (userId === undefined)
+            return ctx.answer({
+                text: say({ en: 'No user.', es: 'Sin usuario.' }, lang),
+            });
+        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: say({ en: '📥 Your data export', es: '📥 Exportación de tus datos' }, lang),
+            });
+        }
+        catch (e) {
+            console.error('[menu] /export sendDocument failed', e);
+            await ctx.send(say({
+                en: `❌ Could not send your data export.\n\nPlease contact ${adminContact}.`,
+                es: `❌ No se ha podido enviar la exportación de tus datos.\n\nContacta con ${adminContact}.`,
+            }, lang));
+        }
+    });
+};
+//# 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"}