@adriangalilea/utils 1.9.0 → 1.10.0

package/README.md

@@ -443,6 +443,7 @@ Then `pnpm install`. Every `ctx.send` / `ctx.sendDocument` / `ctx.reply` / etc.
 | `@adriangalilea/utils/bot/profile` | `syncBotProfile(bot, { name?, description?, about?, photo?, commands?, expects?, adminIds? })` — the bot's Telegram-facing identity as CODE, never BotFather: localized name / description / About / public command list, reconciled idempotently on every boot (get → compare → set per field per language; unchanged values cost one read, so cold-start firing is rate-limit-free). `expects: { inline: true }` declares the BotFather-only capabilities the code assumes — a mismatch (inline mode off on an inline-dependent bot) DMs the admins, since the API can only detect it, not fix it. Never throws; failures log and the bot keeps running. |
 | `@adriangalilea/utils/bot/access-control` | Personal-bot ACL — gates non-admin/non-default users; admin gets DM with `[✅ Aprobar][❌ Denegar]` on first attempt; `/access` opens a persistent menu (revoke / reapprove / list pending). Backed by `@gramio/session` per-user + a small index. **Native alternative**: BotFather → Bot Settings → Access → "Restrict bot usage" — flat allow-list at Telegram. Use this plugin when you want in-bot approval flow instead of a BotFather round-trip; both can coexist. |
 | `@adriangalilea/utils/bot/allow-list` | Static allow-list by **id and/or @username** — stateless, no session/storage. `allowList({ ids?, usernames? })` is a plugin that decorates `ctx.allowed` (boolean); gate in your handlers (`if (!ctx.allowed) return`). `makeAllowList(...)` is the pure framework-free predicate. The light counterpart to `access-control` (which adds an approve/deny flow + revocable store, needing session+storage). Username caveat: a `@username` is optional and mutable, and the Bot API can't resolve username→id ahead of time — prefer `ids` when known, `usernames` is the pragmatic fallback. |
+| `@adriangalilea/utils/bot/groups` | Group-chat identity as plain functions: `isGroupChat(ctx)` / `isPrivateChat(ctx)` + `isGroupAdmin(ctx, { chatId?, userId? }?)` — the `getChatMember` creator/administrator check behind every admin-gated group setting (auto-summary toggles, "dismiss" buttons on group welcomes), chat/user defaulted from the ctx. Takes real gramio ctxs and `MenuCtx` with no cast; a miswired ctx panics, an API rejection fails closed (`false`). Composition over policy: bot-owner override stays at your call site (`ctx.isAdmin \|\| await isGroupAdmin(ctx)`). |
 | `@adriangalilea/utils/bot/coalesce` | Joins client-split inbound messages back into one. When a user pastes >4096 chars, Telegram clients fragment it into separate `message` updates with no marker. Middleware detects the burst and emits one combined event. |
 | `@adriangalilea/utils/bot/llm` | The full LLM-chatbot pipeline in one module. **Input:** `streamChat(response)` parses OpenAI-compatible SSE (OpenAI, vllm, mlx-lm, llama.cpp, Together, Groq, …) into a typed `AsyncGenerator<{type: 'content' \| 'reasoning', text}>`. **Output:** `ctx.startStream()` (low-level: debounced markdown to Telegram, 4000-char split, exposes `wasPartial` after `.end()`). `ctx.startChatStream(response)` (high-level: consumes the stream, renders reasoning as a Telegram `expandable_blockquote` entity + content as streamed markdown — both go through `markdownToFormattable` with graceful degradation — returns `{ content, reasoning }`). **History:** `llmHistory({...})` returns `.plugin` (decorates `ctx.llm` with `.add() / .get() / .clear() / .all() / .clearAll()`, per-(user, thread) OpenAI `ChatMessage` shape, persisted in the shared session record so the menu's 🗑 Forget wipes it automatically) AND `.menuItem` (drop-in "🗑 Delete this thread" for `botMenu` — wipes the LLM history AND calls `deleteForumTopic` so the Telegram thread + all its messages disappear from the chat; falls back to Redis-only clear when no `threadId` is present). |
 | `@adriangalilea/utils/bot/menu` | `botMenu({ command, description, items, privacy?, personalData?, adminContact })` — `/settings` command + InlineKeyboard router. Root view always renders a `🛡️ Privacy & data` submenu button that wraps the privacy policy link plus (if `personalData: { storage }`) 🗑 Forget + 📥 Export buttons. Items take `keepRow` (render on the same row as the next item — e.g. a two-per-row language picker) and `rootExtra` (render at the bottom of the root menu, below Privacy & data). `label` / `header` / `style` / `visible` resolvers may be **async** (read your db at render time — never cache render strings in the session); `parseMode: 'HTML'` renders the header formatted (you own escaping); `personalData.onForget(ctx, userId)` wipes YOUR tables inside the same try as the session delete, so Forget either forgets everything or reports failure. `toggleMenuItem({ id, read, write, label: { off, on }, toast? })` — convenience factory for boolean-toggle items with dynamic label + optional toast, storage-agnostic via `read`/`write` closures. |

package/dist/bot/groups.d.ts

@@ -0,0 +1,33 @@
+/** Minimum ctx shape the chat-type predicates read. */
+export type ChatTypeCtx = {
+    chat?: {
+        type?: string;
+    };
+};
+/** Minimum ctx shape `isGroupAdmin` reads. `bot` is the running gramio Bot — typed
+ *  `unknown` so MenuCtx and every real ctx assign without a cast; its
+ *  `api.getChatMember` is asserted at call time. */
+export type GroupAdminCtx = {
+    bot: unknown;
+    chat?: {
+        id?: number;
+    };
+    from?: {
+        id?: number;
+    };
+};
+/** True for a group or supergroup chat. */
+export declare const isGroupChat: (ctx: ChatTypeCtx) => boolean;
+/** True for a 1:1 private chat. */
+export declare const isPrivateChat: (ctx: ChatTypeCtx) => boolean;
+/**
+ * Whether a user is a creator/administrator of a group, per `getChatMember`. Chat and
+ * user default to the ctx's own (`ctx.chat.id`, `ctx.from.id` — gramio's own
+ * parameter-defaulting idiom); pass `chatId` / `userId` for cross-chat checks. Missing
+ * ids (an actor-less service event) or an API rejection answer `false`.
+ */
+export declare function isGroupAdmin(ctx: GroupAdminCtx, opts?: {
+    chatId?: number;
+    userId?: number;
+}): Promise<boolean>;
+//# sourceMappingURL=groups.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../src/bot/groups.ts"],"names":[],"mappings":"AAqCA,uDAAuD;AACvD,MAAM,MAAM,WAAW,GAAG;IACzB,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzB,CAAC;AAEF;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG;IAC3B,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvB,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvB,CAAC;AAcF,2CAA2C;AAC3C,eAAO,MAAM,WAAW,GAAI,KAAK,WAAW,KAAG,OACe,CAAC;AAE/D,mCAAmC;AACnC,eAAO,MAAM,aAAa,GAAI,KAAK,WAAW,KAAG,OACpB,CAAC;AAE9B;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,GAAG,EAAE,aAAa,EAClB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC,OAAO,CAAC,CAkBlB"}

package/dist/bot/groups.js

@@ -0,0 +1,68 @@
+/**
+ * Group-chat identity — chat-type predicates and the group-admin check. Worker-safe
+ * (no env, no OS).
+ *
+ * Telegram's Bot API has no "is this user a group admin?" primitive and neither does
+ * gramio: the raw material is `getChatMember` returning a member whose `status` may be
+ * `"creator"` or `"administrator"`. Every bot with an admin-gated group setting re-rolls
+ * that check; this module rolls it ONCE.
+ *
+ * These take minimum structural ctx shapes (the `bot/ctx.ts` philosophy) that real
+ * gramio contexts AND `bot/menu`'s `MenuCtx` satisfy by duck typing — a menu action
+ * gates with `isGroupAdmin(ctx)`, no cast. `ctx.bot` stays `unknown` for exactly that
+ * assignability (MenuCtx's own choice); a ctx whose bot has no `api.getChatMember`
+ * PANICS — a miswire screams, it doesn't read as "not admin".
+ *
+ * `isGroupAdmin` FAILS CLOSED on the API call itself: a `getChatMember` rejection (user
+ * never seen in the chat, network, the bot removed mid-tap) answers `false`, never
+ * throws — it is a permission gate, and a gate that throws breaks the surface it guards
+ * (a menu tap's single answerCallbackQuery, a command reply). That rejection is the
+ * messy real world; denial is the only honest answer to "I couldn't verify".
+ *
+ * Anonymous-admin caveat: an admin posting anonymously wears the group's own identity
+ * in `message.from` (the GroupAnonymousBot), so a MESSAGE from them fails this check.
+ * Callback taps always carry the real user, so inline-button gates (the settings case)
+ * are unaffected.
+ *
+ * @example
+ * // Gate a group-wide toggle: the bot's own admins always may, otherwise the
+ * // tapper must hold power over THIS group. (Policy composes at the call site.)
+ * if (!ctx.isAdmin && !(await isGroupAdmin(ctx))) return tr("groupAdminsOnly")
+ *
+ * @example
+ * // Cross-chat: is user 42 an admin of chat -100123?
+ * await isGroupAdmin(ctx, { chatId: -100123, userId: 42 })
+ */
+import { assert } from "../offensive.js";
+// The two chat-member statuses that hold power over a group. Not exported: the
+// contract is the question `isGroupAdmin` answers, never status comparison.
+const GROUP_ADMIN_STATUSES = new Set(["creator", "administrator"]);
+/** True for a group or supergroup chat. */
+export const isGroupChat = (ctx) => ctx.chat?.type === "group" || ctx.chat?.type === "supergroup";
+/** True for a 1:1 private chat. */
+export const isPrivateChat = (ctx) => ctx.chat?.type === "private";
+/**
+ * Whether a user is a creator/administrator of a group, per `getChatMember`. Chat and
+ * user default to the ctx's own (`ctx.chat.id`, `ctx.from.id` — gramio's own
+ * parameter-defaulting idiom); pass `chatId` / `userId` for cross-chat checks. Missing
+ * ids (an actor-less service event) or an API rejection answer `false`.
+ */
+export async function isGroupAdmin(ctx, opts = {}) {
+    const chatId = opts.chatId ?? ctx.chat?.id;
+    const userId = opts.userId ?? ctx.from?.id;
+    if (chatId === undefined || userId === undefined)
+        return false;
+    const bot = ctx.bot;
+    assert(typeof bot?.api?.getChatMember === "function", "isGroupAdmin: ctx.bot.api.getChatMember missing — not a gramio ctx?");
+    try {
+        const member = await bot.api.getChatMember({
+            chat_id: chatId,
+            user_id: userId,
+        });
+        return GROUP_ADMIN_STATUSES.has(member.status ?? "");
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=groups.js.map

package/dist/bot/groups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../src/bot/groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAwBzC,+EAA+E;AAC/E,4EAA4E;AAC5E,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC;AAEnE,2CAA2C;AAC3C,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAgB,EAAW,EAAE,CACxD,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,YAAY,CAAC;AAE/D,mCAAmC;AACnC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAgB,EAAW,EAAE,CAC1D,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,GAAkB,EAClB,OAA6C,EAAE;IAE/C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;IAC3C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC/D,MAAM,GAAG,GAAG,GAAG,CAAC,GAAsD,CAAC;IACvE,MAAM,CACL,OAAO,GAAG,EAAE,GAAG,EAAE,aAAa,KAAK,UAAU,EAC7C,qEAAqE,CACrE,CAAC;IACF,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC;YAC1C,OAAO,EAAE,MAAM;YACf,OAAO,EAAE,MAAM;SACf,CAAC,CAAC;QACH,OAAO,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC"}

package/dist/bot/index.d.ts

@@ -16,6 +16,7 @@ export * from "./admin.js";
 export * from "./callbacks.js";
 export * from "./coalesce.js";
 export * from "./ctx.js";
+export * from "./groups.js";
 export * from "./keys.js";
 export * from "./kit.js";
 export * from "./language.js";

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;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}

package/dist/bot/index.js

@@ -16,6 +16,7 @@ export * from "./admin.js";
 export * from "./callbacks.js";
 export * from "./coalesce.js";
 export * from "./ctx.js";
+export * from "./groups.js";
 export * from "./keys.js";
 export * from "./kit.js";
 export * from "./language.js";

package/dist/bot/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "1.9.0",
+	"version": "1.10.0",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -127,6 +127,10 @@
 		"./bot/flags": {
 			"types": "./dist/bot/flags.d.ts",
 			"default": "./dist/bot/flags.js"
+		},
+		"./bot/groups": {
+			"types": "./dist/bot/groups.d.ts",
+			"default": "./dist/bot/groups.js"
 		}
 	},
 	"files": [
@@ -151,7 +155,8 @@
 		"test:worker-safe": "pnpm run build && tsx tests/worker-safe-test.ts",
 		"demo:bot": "tsx tests/create-demo.ts",
 		"test:tg-html": "tsx tests/tg-html-test.ts",
-		"test:flags": "tsx tests/flags-test.ts"
+		"test:flags": "tsx tests/flags-test.ts",
+		"test:groups": "tsx tests/groups-test.ts"
 	},
 	"keywords": [
 		"typescript",