@adriangalilea/utils 0.12.0 → 0.13.0

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

@@ -1,279 +0,0 @@
-/**
- * Per-user rolling message history for GramIO bots — opt-in, with
- * retention, **sharded by thread**.
- *
- * Each user has one session record. Inside that record, `history` keeps
- * a separate ring buffer per thread:
- *
- *     storage[userId].history.shards = {
- *       'general':   [ ...entries from no-thread messages ],
- *       '12345':     [ ...entries from message_thread_id=12345 ],
- *       '98765':     [ ...entries from message_thread_id=98765 ],
- *     }
- *
- * This makes the plugin compatible with both forum-supergroup topics
- * and BotFather's Threaded Mode for private chats (which is the whole
- * point of those features: parallel conversations with separate
- * context). `ctx.history` returns ONLY the slice for the current
- * thread; `ctx.allHistory` returns the full sharded map when you need
- * a cross-thread view (e.g. for `/export`).
- *
- * Thread key: `String(ctx.threadId)`, or `'general'` when no thread.
- *
- * ## What this plugin owns
- *
- *   - Appends each incoming user message to the shard for its thread
- *   - Prunes per-shard by `retentionDays` and `maxMessages`
- *   - Exposes `ctx.history` (current thread's pruned slice) and
- *     `ctx.allHistory` (full map) to 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.
- *
- * 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,         // cap per-thread
- *   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 in this thread)')
- *   })
- */
-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;
-};
-/**
- * Per-thread shards. Key is `String(ctx.threadId)` or `'general'`
- * when no thread. Each shard is an independently capped + pruned
- * ring buffer.
- */
-export type HistoryRecord = {
-    shards: {
-        [threadKey: string]: 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 **per thread**. 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 = {
-    /** Pruned snapshot for the CURRENT thread only. */
-    history: ReadonlyArray<HistoryEntry>;
-    /**
-     * Pruned snapshot of all threads, keyed by thread (`'general'` or
-     * stringified threadId). Use for cross-thread views (e.g. /export).
-     */
-    allHistory: Readonly<{
-        [threadKey: string]: 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

@@ -1 +0,0 @@
-{"version":3,"file":"message-history.d.ts","sourceRoot":"","sources":["../../src/bot/message-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;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;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE;QAAE,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CAAA;KAAE,CAAA;CAChD,CAAA;AAaD,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,4EAA4E;IAC5E,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,mDAAmD;IACnD,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IACpC;;;OAGG;IACH,UAAU,EAAE,QAAQ,CAAC;QAAE,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,CAAA;KAAE,CAAC,CAAA;CAC3E,CAAA;AA6BD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAqCnE,CAAA"}

package/dist/bot/message-history.js

@@ -1,142 +0,0 @@
-/**
- * Per-user rolling message history for GramIO bots — opt-in, with
- * retention, **sharded by thread**.
- *
- * Each user has one session record. Inside that record, `history` keeps
- * a separate ring buffer per thread:
- *
- *     storage[userId].history.shards = {
- *       'general':   [ ...entries from no-thread messages ],
- *       '12345':     [ ...entries from message_thread_id=12345 ],
- *       '98765':     [ ...entries from message_thread_id=98765 ],
- *     }
- *
- * This makes the plugin compatible with both forum-supergroup topics
- * and BotFather's Threaded Mode for private chats (which is the whole
- * point of those features: parallel conversations with separate
- * context). `ctx.history` returns ONLY the slice for the current
- * thread; `ctx.allHistory` returns the full sharded map when you need
- * a cross-thread view (e.g. for `/export`).
- *
- * Thread key: `String(ctx.threadId)`, or `'general'` when no thread.
- *
- * ## What this plugin owns
- *
- *   - Appends each incoming user message to the shard for its thread
- *   - Prunes per-shard by `retentionDays` and `maxMessages`
- *   - Exposes `ctx.history` (current thread's pruned slice) and
- *     `ctx.allHistory` (full map) to 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.
- *
- * 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,         // cap per-thread
- *   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 in this thread)')
- *   })
- */
-import { Plugin } from 'gramio';
-const GENERAL_THREAD = 'general';
-const threadKey = (ctx) => {
-    // Message events: ctx.threadId. Callback events: ctx.message.threadId.
-    const tid = ctx.threadId ?? ctx.message?.threadId;
-    return tid !== undefined ? String(tid) : GENERAL_THREAD;
-};
-// ─── 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);
-};
-const pruneAll = (shards, maxMessages, retentionDays) => {
-    const out = {};
-    for (const k of Object.keys(shards)) {
-        const pruned = prune(shards[k], maxMessages, retentionDays);
-        if (pruned.length > 0)
-            out[k] = pruned;
-    }
-    return out;
-};
-// ─── 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 into their thread's shard.
-        // 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 key = threadKey(ctx);
-            const shards = { ...(ctx.session.history?.shards ?? {}) };
-            const cur = shards[key] ?? [];
-            shards[key] = [
-                ...prune(cur, maxMessages, retentionDays),
-                entry,
-            ].slice(-maxMessages);
-            ctx.session.history = { shards };
-        }
-        return next();
-    })
-        // Read-only views for handlers downstream.
-        .derive(['message', 'callback_query'], (ctx) => {
-        const shards = ctx.session.history?.shards ?? {};
-        const allPruned = pruneAll(shards, maxMessages, retentionDays);
-        const key = threadKey(ctx);
-        return {
-            history: (allPruned[key] ?? []),
-            allHistory: allPruned,
-        };
-    });
-};
-//# sourceMappingURL=message-history.js.map

package/dist/bot/message-history.js.map

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