@adriangalilea/utils 0.6.0 → 0.8.0

package/dist/bot/coalesce.js

@@ -0,0 +1,155 @@
+/**
+ * Coalesce client-split inbound messages.
+ *
+ * Telegram clients (Desktop / iOS / web) split a single message > 4096
+ * chars into multiple `sendMessage` calls before they ever reach the
+ * server. The bot receives them as **separate** `message` updates with
+ * no marker linking them. This middleware joins them back into one
+ * event so your handlers see the full text.
+ *
+ *     user pastes 8000 chars → client splits in 2 → bot gets 2 updates
+ *                                                            │
+ *                                                            ▼
+ *                                                 coalesce middleware
+ *                                                            │
+ *                                                     hold + join
+ *                                                            │
+ *                                                            ▼
+ *                                              handler sees ONE event
+ *                                              with full ctx.text
+ *
+ * ## Detection rule (strict)
+ *
+ * We coalesce only when ALL hold. Otherwise fragments pass through
+ * as separate events — false negatives are preferred over silently
+ * merging unrelated messages.
+ *
+ *   1. Same chat.
+ *   2. Same user (override with `acrossUsers: true`).
+ *   3. Leading fragment length ≥ `minLeadingLength` (a current
+ *      guess — see the type definition for the default and the
+ *      reasoning). Short messages never start a real client split.
+ *   4. Each subsequent fragment within `windowMs` of the previous.
+ *
+ * ## Known caveats
+ *
+ *   - `ctx.entities` is cleared on coalesced messages — per-fragment
+ *     entity offsets would point at the wrong characters once joined.
+ *     Plain-text consumers don't care; formatted-input consumers
+ *     should disable this plugin.
+ *   - In-memory buffer; doesn't survive bot restart mid-burst.
+ *
+ * Peer deps: `gramio`.
+ *
+ * @example
+ * import { Bot } from 'gramio'
+ * import { coalesceLongMessages } from '@adriangalilea/utils/bot/coalesce'
+ *
+ * const bot = new Bot(process.env.BOT_TOKEN!)
+ *   .extend(coalesceLongMessages())     // ← before .on / .command handlers
+ *   .on('message', (ctx) => {
+ *     // ctx.text is the full pasted text even if Telegram split it
+ *     return ctx.send(`got ${ctx.text?.length} chars`)
+ *   })
+ *
+ * @example  Power-user escape hatch
+ *
+ * import { isCoalescent } from '@adriangalilea/utils/bot/coalesce'
+ *
+ * if (isCoalescent(prev, curr)) {
+ *   // do your own thing
+ * }
+ */
+import { Plugin } from 'gramio';
+// Current guess. Real Telegram clients split at natural boundaries
+// (newline / paragraph / sentence) before the 4096 cap, but we don't
+// yet have a solid dataset of where they actually land. Adjust as
+// real-world data comes in. Single source of truth — both
+// `isCoalescent` and the middleware read from here.
+const DEFAULT_MIN_LEADING_LENGTH = 3750;
+const DEFAULT_WINDOW_MS = 500;
+const DEFAULT_ACROSS_USERS = false;
+export const isCoalescent = (prev, curr, opts = {}) => {
+    const minLeadingLength = opts.minLeadingLength ?? DEFAULT_MIN_LEADING_LENGTH;
+    const windowMs = opts.windowMs ?? DEFAULT_WINDOW_MS;
+    const acrossUsers = opts.acrossUsers ?? DEFAULT_ACROSS_USERS;
+    if (prev.chatId !== curr.chatId)
+        return false;
+    if (!acrossUsers && prev.userId !== curr.userId)
+        return false;
+    if (prev.text.length < minLeadingLength)
+        return false;
+    if (curr.dateMs - prev.dateMs > windowMs)
+        return false;
+    return true;
+};
+export const coalesceLongMessages = (opts = {}) => {
+    const minLeadingLength = opts.minLeadingLength ?? DEFAULT_MIN_LEADING_LENGTH;
+    const windowMs = opts.windowMs ?? DEFAULT_WINDOW_MS;
+    const acrossUsers = opts.acrossUsers ?? DEFAULT_ACROSS_USERS;
+    const log = opts.log ?? false;
+    const dbg = (msg) => {
+        if (log)
+            console.error(`[coalesce] ${msg}`);
+    };
+    // Keyed per `<chatId>:<userId>` (or `<chatId>` when acrossUsers).
+    // Buffer lives only as long as fragments are still arriving — gets
+    // deleted on flush.
+    const buffers = new Map();
+    const keyFor = (chatId, userId) => acrossUsers ? `${chatId}` : `${chatId}:${userId}`;
+    return new Plugin('@adriangalilea/utils/bot/coalesce').use(async (ctx, next) => {
+        if (!ctx.is('message') || ctx.text === undefined)
+            return next();
+        const key = keyFor(ctx.chat.id, ctx.from.id);
+        const existing = buffers.get(key);
+        if (existing) {
+            // Continuation fragment — fold into the held buffer and reset
+            // the timer. No length check on continuations: once a buffer
+            // is open, anything within the window joins (the tail of a
+            // split is typically short). We don't call next(); this update
+            // is swallowed. The first fragment held by `existing.flush`
+            // will eventually fire next() with the combined text.
+            dbg(`join key=${key} len=${ctx.text.length} buffered=${existing.text.length}→${existing.text.length + ctx.text.length}`);
+            clearTimeout(existing.timer);
+            existing.text += ctx.text;
+            existing.timer = setTimeout(existing.flush, windowMs);
+            return;
+        }
+        if (ctx.text.length < minLeadingLength) {
+            // Short message → can never be the leading fragment of a real
+            // client split. Zero-latency passthrough.
+            dbg(`passthrough key=${key} len=${ctx.text.length} (<${minLeadingLength})`);
+            return next();
+        }
+        // Suspicious leading fragment: hold + start the wait window.
+        // Returns a Promise that only resolves after the buffer flushes
+        // (next() of THIS ctx is called with the combined text). This
+        // keeps gramio's middleware chain awaiting until we're done.
+        dbg(`open key=${key} len=${ctx.text.length} (≥${minLeadingLength}, wait ${windowMs}ms)`);
+        return new Promise((resolve, reject) => {
+            const buffered = {
+                text: ctx.text,
+                timer: setTimeout(() => buffered.flush(), windowMs),
+                flush: () => {
+                    // Detach from the map FIRST so any fragment arriving mid-flush
+                    // starts a fresh buffer instead of re-entering this one.
+                    dbg(`flush key=${key} total=${buffered.text.length}`);
+                    buffers.delete(key);
+                    // gramio's MessageContext exposes `text` as an accessor
+                    // with both `get` and `set` — assignment is the supported
+                    // way to override. We don't touch `entities`: fragment-1
+                    // entities reference fragment-1 text only, but plain-text
+                    // consumers (the sensible use of this plugin) ignore them.
+                    // Formatted-input consumers should disable the plugin.
+                    ctx.text = buffered.text;
+                    // Hand off to the rest of the chain. Resolve outer Promise
+                    // once the chain (and any downstream awaits) settles, so
+                    // gramio considers this middleware fully done.
+                    Promise.resolve(next()).then(() => resolve(), reject);
+                },
+            };
+            buffers.set(key, buffered);
+        });
+    });
+};
+//# sourceMappingURL=coalesce.js.map

package/dist/bot/coalesce.js.map

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

package/dist/bot/index.d.ts

@@ -13,5 +13,9 @@
  */
 export * from './kit.js';
 export * from './access-control.js';
+export * from './coalesce.js';
 export * from './llm-stream.js';
+export * from './menu.js';
+export * from './language.js';
+export * from './message-history.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,UAAU,CAAA;AACxB,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,UAAU,CAAA;AACxB,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA"}

package/dist/bot/index.js

@@ -13,5 +13,9 @@
  */
 export * from './kit.js';
 export * from './access-control.js';
+export * from './coalesce.js';
 export * from './llm-stream.js';
+export * from './menu.js';
+export * from './language.js';
+export * from './message-history.js';
 //# sourceMappingURL=index.js.map

package/dist/bot/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,UAAU,CAAA;AACxB,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,UAAU,CAAA;AACxB,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../../src/bot/kit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAK/B,MAAM,MAAM,oBAAoB,GAAG;IACjC,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACvC,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,KAAK,CAAA;CACtC,CAAA;AAED,eAAO,MAAM,aAAa,GACxB,KAAK,MAAM,EACX,OAAM,oBAAyB,KAC9B,OAAO,CAAC,IAAI,CAiCd,CAAA;AAID,MAAM,MAAM,mBAAmB,GAAG;IAChC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,OAAM,mBAAwB;;;;;;;;MAqB1D,CAAA"}
+{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../../src/bot/kit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAK/B,MAAM,MAAM,oBAAoB,GAAG;IACjC,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACvC,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,KAAK,CAAA;CACtC,CAAA;AAED,eAAO,MAAM,aAAa,GACxB,KAAK,MAAM,EACX,OAAM,oBAAyB,KAC9B,OAAO,CAAC,IAAI,CAwCd,CAAA;AAID,MAAM,MAAM,mBAAmB,GAAG;IAChC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,OAAM,mBAAwB;;;;;;;;MAqB1D,CAAA"}

package/dist/bot/kit.js

@@ -29,6 +29,12 @@ export const gracefulStart = async (bot, opts = {}) => {
     };
     process.on('SIGINT', () => void stop('SIGINT'));
     process.on('SIGTERM', () => void stop('SIGTERM'));
+    // Publish all `.command(name, { description }, …)` registrations to
+    // Telegram via `setMyCommands`. Hashes scopes internally so unchanged
+    // metadata doesn't burn rate-limit budget. Hidden / un-described
+    // commands are skipped.
+    // See https://gramio.dev/triggers/command.html#how-synccommands-works
+    bot.onStart(() => bot.syncCommands());
     await bot.start();
 };
 export const adminContext = (opts = {}) => {

package/dist/bot/kit.js.map

@@ -1 +1 @@
-{"version":3,"file":"kit.js","sourceRoot":"","sources":["../../src/bot/kit.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAA;AAexC,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAChC,GAAW,EACX,OAA6B,EAAE,EAChB,EAAE;IACjB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACjF,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,IAAI,MAAM,CAAA;IAE/C,IAAI,QAAQ,GAAG,KAAK,CAAA;IAEpB,MAAM,IAAI,GAAG,KAAK,EAAE,MAAc,EAAE,EAAE;QACpC,IAAI,QAAQ;YAAE,OAAM;QACpB,QAAQ,GAAG,IAAI,CAAA;QACf,GAAG,CAAC,SAAS,MAAM,2BAA2B,CAAC,CAAA;QAE/C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,OAAO,CAAC,KAAK,CAAC,2BAA2B,OAAO,IAAI,CAAC,CAAA;YACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC,EAAE,OAAO,CAAC,CAAA;QACX,KAAK,CAAC,KAAK,EAAE,EAAE,CAAA;QAEf,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;YAChB,MAAM,IAAI,CAAC,UAAU,EAAE,EAAE,CAAA;YACzB,GAAG,CAAC,sBAAsB,CAAC,CAAA;QAC7B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,sBAAsB,EAAE,CAAC,CAAC,CAAA;QAC1C,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAA;QAClC,CAAC;IACH,CAAC,CAAA;IAED,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC/C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAA;IAEjD,MAAM,GAAG,CAAC,KAAK,EAAE,CAAA;AACnB,CAAC,CAAA;AASD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAA4B,EAAE,EAAE,EAAE;IAC7D,qFAAqF;IACrF,+EAA+E;IAC/E,oEAAoE;IACpE,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAA;IAE/D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,mEAAmE;YACjE,6CAA6C,CAChD,CAAA;IACH,CAAC;IAED,OAAO,IAAI,MAAM,CAAC,gCAAgC,CAAC;SAChD,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;SACrB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAChB,sEAAsE;QACtE,mEAAmE;QACnE,yDAAyD;QACzD,OAAO,EAAE,UAAU,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO;KACvD,CAAC,CAAC,CAAA;AACP,CAAC,CAAA"}
+{"version":3,"file":"kit.js","sourceRoot":"","sources":["../../src/bot/kit.ts"],"names":[],"mappings":"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"}

package/dist/bot/language.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Per-user language preference for GramIO bots.
+ *
+ * Follows gramio's canonical "shared infrastructure" pattern (see
+ * [Composer docs — Production Architecture](https://gramio.dev/extend/middleware.html#production-architecture)):
+ * the bot's session is extended once at the top level by the user,
+ * and each feature plugin declares it as a required dependency.
+ * gramio's runtime deduplication ensures the session derive runs
+ * exactly once per update; TypeScript flows the session's data shape
+ * into every plugin that `.extend()`s it.
+ *
+ * ## What this plugin owns
+ *
+ *   - Validates the supported BCP-47 language tags via `Intl.getCanonicalLocales`
+ *   - Resolves `ctx.lang` on every event (override → Telegram hint → default)
+ *   - Persists the user's chosen language as `ctx.session.language`
+ *   - Provides a `menuItem` for a `botMenu`'s language picker
+ *
+ * ## What this plugin does NOT own
+ *
+ *   - The session itself. The user creates it (`session(...)`) and
+ *     extends it at bot level before this plugin.
+ *   - GDPR machinery. A language preference is trivially covered by
+ *     [Telegram's Standard Bot Privacy Policy](https://telegram.org/privacy-tpa)
+ *     under "data necessary to function".
+ *
+ * ## Resolution priority for `ctx.lang`
+ *
+ *   1. `ctx.session.language` — stored override
+ *   2. `ctx.from.languageCode` — Telegram-detected user lang, only in
+ *      user-scoped resolution (in groups it would flicker per-speaker)
+ *   3. `default` — the fallback passed at construction
+ *
+ * Peer deps: `gramio`, `@gramio/session`.
+ *
+ * @example
+ * import { Bot } from 'gramio'
+ * import { session } from '@gramio/session'
+ * import { redisStorage } from '@gramio/storage-redis'
+ * import { language } from '@adriangalilea/utils/bot/language'
+ *
+ * const userSession = session({
+ *   storage: redisStorage(),
+ *   key: 'session',
+ *   initial: () => ({}),     // plugins add their fields by convention
+ * })
+ *
+ * const lang = language({
+ *   session: userSession,
+ *   supported: ['en','es'] as const,
+ *   default: 'en',
+ * })
+ *
+ * const bot = new Bot(process.env.BOT_TOKEN!)
+ *   .extend(userSession)        // ← FIRST: ctx.session lands on the real ctx
+ *   .extend(lang.plugin)        // declares userSession as dep; runtime dedup
+ *   .command('hello', (ctx) => ctx.send({ en: 'Hello', es: 'Hola' }[ctx.lang]))
+ */
+import { type DeriveDefinitions, Plugin } from 'gramio';
+import { session } from '@gramio/session';
+import type { MenuItem } from './menu.js';
+/** Branded BCP-47 language tag — obtainable only via the validators below. */
+export type LangCode = string & {
+    readonly __langCode: unique symbol;
+};
+/**
+ * Validate + canonicalize a BCP-47 tag using the standard
+ * `Intl.getCanonicalLocales`. Throws `RangeError` on invalid input.
+ * Canonicalizes casing: `'en-us'` → `'en-US'`.
+ */
+export declare const parseLangCode: (s: string) => LangCode;
+/** Non-throwing type guard. Same parser path as `parseLangCode`. */
+export declare const isLangCode: (s: unknown) => s is LangCode;
+export type LanguageScopeStrategy = 'user' | 'chat';
+export type LanguageScope = LanguageScopeStrategy | {
+    private?: LanguageScopeStrategy;
+    group?: LanguageScopeStrategy;
+    supergroup?: LanguageScopeStrategy;
+    channel?: LanguageScopeStrategy;
+};
+/** Loose session shape — the plugin only touches the `language` field. */
+type SessionLike = {
+    language?: string;
+};
+/** @internal — kept unexported so it doesn't clash with peers' refs. */
+type LangSessionPluginRef = ReturnType<typeof session<SessionLike, 'session'>>;
+export type LanguageOptions<Langs extends readonly string[]> = {
+    /**
+     * The session plugin to read/write `ctx.session.language` from.
+     * Must be extended on the bot before this plugin (gramio's runtime
+     * dedup ensures the session derive only runs once per update).
+     */
+    session: LangSessionPluginRef;
+    /** Tuple of BCP-47 tags. Each validated via `Intl.getCanonicalLocales`. */
+    supported: Langs;
+    /** Must be a member of `supported`. */
+    default: Langs[number];
+    /** See module docstring. Per chat-type override possible. */
+    scope?: LanguageScope;
+    /**
+     * Override per-language menu label. Default uses an emoji flag prefix
+     * derived from the language code.
+     */
+    labels?: Partial<Record<Langs[number], string>>;
+    /** Header text for the language sub-menu. Default `'🌐 Language'`. */
+    menuLabel?: string;
+};
+export type LanguageFeature<Lang extends string> = {
+    plugin: ReturnType<typeof buildLanguagePlugin<Lang>>;
+    menuItem: MenuItem;
+};
+type LanguageDerives<Lang extends string> = {
+    lang: Lang;
+};
+export declare const language: <const Langs extends readonly string[]>(opts: LanguageOptions<Langs>) => LanguageFeature<Langs[number]>;
+declare const buildLanguagePlugin: <Lang extends string>(args: {
+    sessionPlugin: LangSessionPluginRef;
+    canonicalSet: ReadonlySet<string>;
+    defaultLanguage: Lang;
+    matchSupported: (s: string | undefined) => Lang | undefined;
+    scopeOpt: LanguageScope | undefined;
+}) => Plugin<{}, DeriveDefinitions & {
+    global: LanguageDerives<Lang>;
+} & {
+    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: {
+        lang: Lang;
+    };
+    callback_query: {
+        lang: Lang;
+    };
+}, {}>;
+export {};
+//# sourceMappingURL=language.d.ts.map

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

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