@adriangalilea/utils 0.7.0 → 0.9.0

package/dist/bot/language.js

@@ -0,0 +1,250 @@
+/**
+ * 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';
+import { say } from '../say/index.js';
+/**
+ * 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;
+    }
+};
+const buildSayer = (ctx, lang, fallback) => {
+    const resolve = (value) => value[lang] ?? value[fallback] ?? say(value, lang);
+    const fn = ((value) => resolve(value));
+    const c = ctx;
+    fn.send = (value, params) => {
+        if (typeof c.send !== 'function') {
+            throw new TypeError('ctx.say.send: ctx.send is not available on this event');
+        }
+        return c.send(resolve(value), params);
+    };
+    fn.edit = (value, params) => {
+        if (typeof c.editText !== 'function') {
+            throw new TypeError('ctx.say.edit: ctx.editText is only available on callback_query events');
+        }
+        return c.editText(resolve(value), params);
+    };
+    fn.answer = (value, params) => {
+        if (typeof c.answer !== 'function') {
+            throw new TypeError('ctx.say.answer: ctx.answer is only available on callback_query events');
+        }
+        return c.answer({ text: resolve(value), ...(params ?? {}) });
+    };
+    return fn;
+};
+// ─── 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 ?? { en: '🌐 Language', es: '🌐 Idioma' };
+    // 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) => {
+        const resolveLang = () => {
+            // 1) stored override
+            const stored = ctx.session.language;
+            if (stored && canonicalSet.has(stored))
+                return 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 hint;
+            }
+            // 3) configured default
+            return defaultLanguage;
+        };
+        const lang = resolveLang();
+        return { lang, say: buildSayer(ctx, 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,189 @@
+/**
+ * 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';
+import { type Polyglot } from '../say/index.js';
+type MenuCtx = {
+    bot: unknown;
+    from?: {
+        id: number;
+    };
+    chat?: {
+        id: number;
+        type: string;
+    };
+    session?: {
+        language?: string;
+    };
+};
+/**
+ * Anything a button or header can render as. Authoring a polyglot
+ * label is just an inline `{ en, es }` literal — `say()` resolves it
+ * to the recipient's language at render time.
+ *
+ *   label: 'Static'
+ *   label: { en: 'Settings', es: 'Ajustes' }
+ *   label: (ctx) => `Hi ${ctx.from?.firstName}`
+ *   label: (ctx) => ({ en: `Hi ${name}`, es: `Hola ${name}` })
+ */
+type Label = string | Polyglot<string> | ((ctx: MenuCtx) => string | Polyglot<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

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