@adriangalilea/utils 0.7.0 → 0.8.0

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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"}

package/dist/bot/language.js

@@ -0,0 +1,222 @@
+/**
+ * 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 { CallbackData, Plugin } from 'gramio';
+/**
+ * Validate + canonicalize a BCP-47 tag using the standard
+ * `Intl.getCanonicalLocales`. Throws `RangeError` on invalid input.
+ * Canonicalizes casing: `'en-us'` → `'en-US'`.
+ */
+export const parseLangCode = (s) => Intl.getCanonicalLocales(s)[0];
+/** Non-throwing type guard. Same parser path as `parseLangCode`. */
+export const isLangCode = (s) => {
+    if (typeof s !== 'string')
+        return false;
+    try {
+        Intl.getCanonicalLocales(s);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+// ─── scope helpers ─────────────────────────────────────────────────
+const DEFAULT_SCOPE = {
+    private: 'user',
+    group: 'chat',
+    supergroup: 'chat',
+    channel: 'chat',
+};
+const resolveScope = (scope, chatType) => {
+    if (typeof scope === 'string')
+        return scope;
+    const t = chatType;
+    return scope?.[t] ?? DEFAULT_SCOPE[t] ?? 'user';
+};
+// ─── flag emoji (best-effort) ──────────────────────────────────────
+const REGIONLESS_FLAGS = {
+    en: '🇬🇧', es: '🇪🇸', fr: '🇫🇷', de: '🇩🇪', it: '🇮🇹',
+    pt: '🇵🇹', ru: '🇷🇺', zh: '🇨🇳', ja: '🇯🇵', ko: '🇰🇷',
+    ar: '🇸🇦', tr: '🇹🇷', pl: '🇵🇱', nl: '🇳🇱', uk: '🇺🇦',
+};
+const regionToFlag = (region) => String.fromCodePoint(...region.toUpperCase().split('').map((c) => 0x1f1a5 + c.charCodeAt(0)));
+const flagFor = (lang) => {
+    const parts = lang.split('-');
+    if (parts.length > 1) {
+        const region = parts.find((p) => /^[A-Z]{2}$/.test(p));
+        if (region)
+            return regionToFlag(region);
+    }
+    return REGIONLESS_FLAGS[parts[0].toLowerCase()] ?? '🌐';
+};
+const autonym = (lang) => {
+    try {
+        const dn = new Intl.DisplayNames([lang], { type: 'language' });
+        return dn.of(lang) ?? lang;
+    }
+    catch {
+        return lang;
+    }
+};
+const defaultLabel = (lang) => `${flagFor(lang)} ${autonym(lang)}`;
+// ─── callback schema ───────────────────────────────────────────────
+const setLangCb = new CallbackData('lang').string('code');
+// ─── feature factory ───────────────────────────────────────────────
+export const language = (opts) => {
+    const scopeOpt = opts.scope;
+    const labels = (opts.labels ?? {});
+    const menuLabel = opts.menuLabel ?? '🌐 Language';
+    // Canonicalize all supported tags at construction.
+    const canonical = opts.supported.map((l) => {
+        try {
+            return Intl.getCanonicalLocales(l)[0];
+        }
+        catch {
+            throw new Error(`language: "${l}" is not a valid BCP-47 tag (per Intl.getCanonicalLocales)`);
+        }
+    });
+    const canonicalSet = new Set(canonical);
+    let defaultLanguage;
+    try {
+        defaultLanguage = Intl.getCanonicalLocales(opts.default)[0];
+    }
+    catch {
+        throw new Error(`language: default "${opts.default}" is not a valid BCP-47 tag`);
+    }
+    if (!canonicalSet.has(defaultLanguage)) {
+        throw new Error(`language: default "${defaultLanguage}" is not in supported[]`);
+    }
+    const matchSupported = (s) => {
+        if (!s)
+            return undefined;
+        try {
+            const c = Intl.getCanonicalLocales(s)[0];
+            if (canonicalSet.has(c))
+                return c;
+        }
+        catch {
+            // fall through
+        }
+        return undefined;
+    };
+    const plugin = buildLanguagePlugin({
+        sessionPlugin: opts.session,
+        canonicalSet,
+        defaultLanguage,
+        matchSupported,
+        scopeOpt,
+    });
+    const menuItem = {
+        id: 'lang',
+        label: menuLabel,
+        submenu: canonical.map((l) => ({
+            id: l,
+            label: (ctx) => {
+                const current = ctx.lang;
+                const marker = current === l ? '●' : '○';
+                const base = labels[l] ?? defaultLabel(l);
+                return `${marker} ${base}`;
+            },
+            action: async (ctx) => {
+                // ctx.session is the shared session record. Mutating any
+                // field on it goes through @gramio/session's Proxy and
+                // auto-persists. We own the `language` field by convention.
+                const c = ctx;
+                c.session.language = l;
+                await c.answer({ text: `✓ ${l}` });
+                try {
+                    await c.delete?.();
+                }
+                catch {
+                    // not always deletable
+                }
+            },
+        })),
+    };
+    return { plugin, menuItem };
+};
+// ─── plugin builder ────────────────────────────────────────────────
+const buildLanguagePlugin = (args) => {
+    const { sessionPlugin, canonicalSet, defaultLanguage, matchSupported, scopeOpt } = args;
+    return (new Plugin('@adriangalilea/utils/bot/language')
+        // Declare the session as a dependency. gramio's runtime dedupes
+        // this against the bot's top-level session extension so the
+        // session derive runs exactly once per update — but the types
+        // (ctx.session: SessionLike) flow into our handlers below.
+        .extend(sessionPlugin)
+        .derive(['message', 'callback_query'], (ctx) => {
+        // 1) stored override
+        const stored = ctx.session.language;
+        if (stored && canonicalSet.has(stored)) {
+            return { lang: stored };
+        }
+        // 2) Telegram hint — only when in user-scoped resolution
+        const chatType = ctx.is('message')
+            ? ctx.chat.type
+            : ctx.message?.chat.type ?? 'private';
+        const strategy = resolveScope(scopeOpt, chatType);
+        if (strategy === 'user') {
+            const hint = matchSupported(ctx.from.languageCode);
+            if (hint)
+                return { lang: hint };
+        }
+        // 3) configured default
+        return { lang: defaultLanguage };
+    }));
+};
+//# sourceMappingURL=language.js.map

package/dist/bot/language.js.map

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

package/dist/bot/menu.d.ts

@@ -0,0 +1,175 @@
+/**
+ * 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 { Plugin } from 'gramio';
+import type { Storage } from '@gramio/storage';
+type MenuCtx = {
+    bot: unknown;
+    from?: {
+        id: number;
+    };
+    chat?: {
+        id: number;
+        type: string;
+    };
+};
+type Label = string | ((ctx: MenuCtx) => string);
+type Predicate = (ctx: MenuCtx) => boolean;
+type Action = (ctx: MenuCtx) => Promise<void> | void;
+export type MenuItem = {
+    id: string;
+    label: Label;
+    action: Action;
+    order?: number;
+    visible?: Predicate;
+} | {
+    id: string;
+    label: Label;
+    url: string;
+    order?: number;
+    visible?: Predicate;
+} | {
+    id: string;
+    label: Label;
+    submenu: MenuItem[];
+    order?: number;
+    visible?: Predicate;
+};
+export type PersonalDataOptions = {
+    /**
+     * Storage backend where each user's data lives. Must be the SAME
+     * instance you passed to your `session(...)` plugin — that's how
+     * /forget and /export reach the right keys.
+     */
+    storage: Storage;
+    /**
+     * How to compute the storage key for a given user id. Defaults to
+     * `String(userId)` — matching `@gramio/session`'s default
+     * `getSessionKey`. Override if your session uses a custom
+     * `getSessionKey`.
+     */
+    sessionKey?: (userId: number) => string;
+};
+export type BotMenuOptions = {
+    /** Slash command that opens the menu. Default `'settings'`. */
+    command?: string;
+    /** Description shown in Telegram's command list. */
+    description?: string;
+    /** Items rendered top-down (sorted by `order`, then registration). */
+    items?: MenuItem[];
+    /**
+     * URL to your privacy policy. Defaults to Telegram's Standard Bot
+     * Privacy Policy. Override when you retain content or process data
+     * beyond what the standard covers.
+     */
+    privacy?: string;
+    /**
+     * Header text rendered above the keyboard.
+     */
+    header?: Label;
+    /**
+     * Contact the user can reach when something fails (export error,
+     * etc.). **Required** — a bot that asks users to trust it with
+     * data must always offer a human to talk to when the automated
+     * paths fail.
+     */
+    adminContact: string;
+    /**
+     * Enables 🗑 Forget my data and 📥 Export my data buttons. Pass
+     * the storage instance backing your `session()`. If omitted, the
+     * buttons don't appear (use this for bots with no per-user state
+     * beyond what Telegram's standard policy covers).
+     */
+    personalData?: PersonalDataOptions;
+};
+type ResolvedPersonalData = {
+    storage: Storage;
+    sessionKey: (userId: number) => string;
+};
+type ResolvedOpts = {
+    command: string;
+    description: string;
+    privacy: string;
+    header: Label;
+    adminContact: string;
+    personalData: ResolvedPersonalData | null;
+};
+export declare class BotMenu {
+    /** @internal */
+    readonly _items: MenuItem[];
+    /** @internal */
+    readonly _opts: ResolvedOpts;
+    constructor(opts: BotMenuOptions);
+    /** Append a custom item. Mutates the menu. */
+    add(item: MenuItem): this;
+    /** The gramio plugin: registers the slash command + all callback handlers. */
+    get plugin(): Plugin<{}, import("gramio").DeriveDefinitions, {}>;
+}
+export declare const botMenu: (opts: BotMenuOptions) => BotMenu;
+export {};
+//# sourceMappingURL=menu.d.ts.map