@adriangalilea/utils 2.6.0 → 2.8.0

package/README.md

@@ -462,9 +462,11 @@ Then `pnpm install`. Every `ctx.send` / `ctx.sendDocument` / `ctx.reply` / etc.
 | `@adriangalilea/utils/bot/groups` | Group-chat identity as plain functions: `chatIdOf(ctx)` (the chat id on any ctx flavour), `isGroupChat(ctx)` / `isPrivateChat(ctx)`, and `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. Every reader resolves both gramio spellings — message ctxs carry `chat`, callback ctxs (inline-button taps) only `chatId`/`message.chat` — so the same gate works in handlers and taps; read chat ids via `chatIdOf`, never `ctx.chat?.id`. 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/language` (picker surface) | The language-picker vocabulary and surfaces, so bots don't fork label lists: `flagFor` / `autonym` / `languageLabel` ("🇪🇸 Español"), `languagePickerItem({ label, codes, isActive, pick })` (the 2-up primary-highlighted MenuItem factory — storage and policy live in your closures), and `addLanguageRows(kb, { codes, pack, active?, activeStyle? })` (the raw-InlineKeyboard twin for onboarding / group-welcome keyboards; `activeStyle: "success"` when primary already marks something else on the keyboard). |
 | `@adriangalilea/utils/bot/user` | `userLabel(u)` — the conditional "[name] [@username] [id]" line every bot re-rolls for admin DMs and logs: `Ada Lovelace (@ada · 42)` / `Ada (42)` / `@ada (42)` / `id 42`, missing pieces drop instead of padding. Reads both gramio spellings (`firstName` / `first_name`); plain text by design. |
+| `@adriangalilea/utils/bot/inline-feedback` | Behavioral tripwire for BotFather's inline feedback probability (gates `chosen_inline_result`; defaults 0%, silently resets on bot transfer and inline-mode toggling, invisible to `getMe`): served-but-never-chosen crosses a threshold → throttled admin DM naming the exact BotFather switch. Storage injected as three ops; never throws into the answer path. |
 | `@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/llm` | Multi-provider LLM caller on the Vercel AI SDK — the policy layer the SDK doesn't ship. `createLlm({ providers, health? })` → `.stream(req)` (typed events: `delta` / `reasoning` / `reset` / `tool-call` / `end`) and `.complete(req)`. **Failover:** priority-ordered across OpenAI-compatible, Anthropic-compatible, and OpenRouter endpoints; multiple keys per provider (health tracked per key fingerprint); per-key circuit breaker with exponential cool-down persisted in any KV-shaped `HealthStore`; an attempt that dies after emitting yields `reset` (discard, next candidate regenerates); empty completions count as failures. **Accounting:** tokens summed across billed attempts; `costUsd` is the ACTUAL charge (OpenRouter usage accounting via `providerMetadata`, or a `cost` field on the raw usage frame) — never a price-table estimate. **Knobs:** per-model temperature, maxTokens caps, `disableThinking` mapped to each dialect. **Tools:** AI SDK `tool()` + `toolChoice` pass through (re-exported). Worker-safe; peers: `ai`, `@ai-sdk/openai-compatible`, `@ai-sdk/anthropic`, `@openrouter/ai-sdk-provider`. |
 | `@adriangalilea/utils/bot/llm` | The Telegram side of an LLM chatbot; the model side is `@adriangalilea/utils/llm`. **Output:** `streamChatReply(ctx, events, opts?)` consumes an `AsyncIterable<LlmStreamEvent>` and paints it with Telegram's native message-draft streaming (`sendMessageDraft` full-frame repaints, throttled ~1/s, keepalive under the ~30s draft TTL), then persists the finished markdown via `ctx.send`, entity-split across 4096 by `@gramio/split`. Reasoning models get a thinking phase — streams into the ephemeral draft and evaporates (`reasoning: 'preview'`, default), persists as an expandable blockquote (`'message'`), or never renders at all (`'hidden'`). Upstream `reset` (provider failover) repaints the draft from scratch. Drafts are private-chat-only (+ BotFather forum-topic mode); elsewhere the preview phase is skipped and only the final send happens. Returns `{ content, reasoning, toolCalls, usage, messages }`. The painter underneath is `@adriangalilea/utils/bot/draft` (`createDraftPreview(ctx, { render, throttleMs? })`): dependency-light (no markdown machinery), for producers that push deltas or own their per-frame rendering (plain or rich-message frames) and persist path, with `streamForensics` (render-regression + reset warnings) built in and exported standalone. **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 history-only clear when no `threadId` is present). |
+| `@adriangalilea/utils/bot/metrics` | Self-serve product measurement, the flags pattern applied to counting: `defineMetrics(spec, { write, funnels? })` — declare a metric once (counter / timing, `perUser: true` for uniques·repeat·retention·funnels), `bump()`/`record()` at the call site (fire-and-forget, never throws), `describe()` is the schema panels render generically so a new metric reaches every panel with zero panel edits. Storage = one injected atomic day-bucket upsert (aggregate row + per-user row when `user` given); per-user rows are personal data — wipe on forget, prune by age. Money stays in ledgers. |
 | `@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. |
 | `@adriangalilea/utils/bot/payments` | `botPayments({ session, storage, paysupport, paysupportHint?, legal, waiver, vip?, credits?, perks? })` — Telegram Stars monetization in one drop-in plugin. **Three axes, all optional:** `vip` (positional tier ladder — single rung in v1 is just `vip: [{...}]`, ladder is `vip: [{...}, {...}]`; ids are `vip.1`, `vip.2`, …), `credits` (consumable balance + top-up packs `credits.1`, `credits.2`, …), `perks` (orthogonal one-shot unlocks `perks.<key>`). **Surface:** `ctx.payments.atLeast('vip')` / `atLeast('vip.2')` (typed rank check), `ctx.payments.tier()` / `.tier.level()` / `.tier.label()`, `ctx.payments.credits.{balance, consume, tryConsume}` (throws `InsufficientCredits`), `ctx.payments.has(perkId)`, `await ctx.payments.require('vip', { feature? })` (gate that sends a localized upgrade prompt deep-linked to `/settings → 💎 VIP`), `await ctx.payments.invoice(productKey)` (threads Art. 103(m) TRLGDCU consent inline before `sendInvoice`). **Owns:** waiver consent flow (versioned text → forces re-consent on bump, snapshotted on every charge for audit), `/paysupport` slash command (Telegram ToS §6.5; `paysupportHint` overrides the where-to-manage-charges line when your menu isn't `/settings`), idempotent `successful_payment` fulfillment via `pay:idempotency:{chargeId}` sentinel, lazy subscription expiry (no cron needed), tier upgrade auto-cancel of the lower rung's renewal, and admin-DM refund approval (mirror of `accessControl`'s [✅ Aprobar][❌ Denegar] pattern). **Returns:** `{ plugin, menuItem, payouts, onFulfilled }` — `menuItem` is the drop-in `💎 VIP` entry for `botMenu`; `payouts.{record, list, export, exportForUsers}` is the Fragment payout ledger (you receive TON, log the EUR conversion, export time-windowed CSV/JSON for your gestor); `onFulfilled(productKey \| '*', handler)` / `onRefunded(...)` register fire-and-forget hooks (purchase applied / admin-approved refund — a revenue ledger writes on one, reverses on the other). **Stars-only by design** — Telegram ToS §6.2 forbids third-party payment providers for digital goods. Crypto Pay deferred (MiCA risk); Stripe-outside-Telegram is a future v2 channel. Full compliance memo (Spanish-autónomo seller-of-record analysis, Verifactu vs Crea y Crece, MiCA, Art. 103(m) waiver text, GDPR retention) in `src/bot/payments/CLAUDE.md`. |
 | `@adriangalilea/utils/bot/create` | `createBot<S>({ token?, storage?, initial?, admins?, language?, menu?, access?, payments?, handlers?, worker? })` — the composer (see "One bot file, ideation → production" above). Returns `{ build, session, poll, isMain, fetch }`: `poll()` long-polls, `export default app` is a complete Worker, `app.session(ctx)` / the `handlers` callback's `session(ctx)` is the TYPED accessor for your `S` fields. Owns storage+session wiring; resolves storage per environment (D1 binding → `bot/storage-d1`; `BOT_PERSIST` path → sqlite, `redis://` → redis, lazily-imported optional peers; else announced-ephemeral memory) — or pass `storage: (env) => Storage` when the choice is env-dependent (e.g. a D1 binding not named `DB`). Boot NARRATES the composition (`session: memory …`, `features: language(en,es) · menu(/settings)`) so every implicit decision is visible where you're looking. Runnable demo: `pnpm demo:bot`. |

package/dist/bot/index.d.ts

@@ -18,11 +18,13 @@ export * from "./coalesce.js";
 export * from "./ctx.js";
 export * from "./draft.js";
 export * from "./groups.js";
+export * from "./inline-feedback.js";
 export * from "./keys.js";
 export * from "./kit.js";
 export * from "./language.js";
 export * from "./llm.js";
 export * from "./menu.js";
+export * from "./metrics.js";
 export * from "./notify.js";
 export * from "./payments/index.js";
 export * from "./storage.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,YAAY,CAAC;AAC3B,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;AAC7B,cAAc,WAAW,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,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/bot/index.js

@@ -18,11 +18,13 @@ export * from "./coalesce.js";
 export * from "./ctx.js";
 export * from "./draft.js";
 export * from "./groups.js";
+export * from "./inline-feedback.js";
 export * from "./keys.js";
 export * from "./kit.js";
 export * from "./language.js";
 export * from "./llm.js";
 export * from "./menu.js";
+export * from "./metrics.js";
 export * from "./notify.js";
 export * from "./payments/index.js";
 export * from "./storage.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,YAAY,CAAC;AAC3B,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;AAC7B,cAAc,WAAW,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,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/bot/inline-feedback.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Inline-feedback tripwire — behavioral detection for a BotFather setting the
+ * Bot API cannot see.
+ *
+ * `chosen_inline_result` delivery is gated by BotFather's inline FEEDBACK
+ * probability, which defaults to 0% and silently RESETS on bot transfer and
+ * on inline-mode toggling. At 0%, taps post the placeholder client-side but
+ * the bot never hears about them, so nothing ever fills in — and `getMe`
+ * reports nothing (the profile `expects` drift-check is blind here). The
+ * asymmetry IS measurable though: results keep getting served while a chosen
+ * event never arrives.
+ *
+ * Storage is injected as three atomic-ish ops (wire to D1/Redis/anything);
+ * this module owns the thresholds, the throttle, and the operator message.
+ * Thresholds are deliberately lazy — this is a drift alarm, not a metric.
+ *
+ * @example
+ * const probe = inlineFeedbackProbe({
+ *   bump: () => store.bumpInlineServed(ctx),
+ *   reset: () => store.recordInlineChosen(ctx, Date.now()),
+ *   markAlerted: () => store.markInlineAlerted(ctx, Date.now()),
+ *   adminIds: () => deps.adminIds(),
+ * })
+ * bot.inlineQuery(async (ctx) => { …answer with results…; await probe.onServed(ctx.bot) })
+ * bot.chosenInlineResult(() => true, async (ctx) => { await probe.onChosen(); … })
+ */
+import type { Bot } from "gramio";
+export interface InlineFeedbackProbeOptions {
+    /** Increment the served counter, returning the new count + when the last alert fired. */
+    bump: () => Promise<{
+        served: number;
+        lastAlertAt: number | null;
+    }>;
+    /** A chosen event arrived: feedback works, the counter starts over. */
+    reset: () => Promise<void>;
+    /** Persist that the alert fired (also zeroes the counter downstream). */
+    markAlerted: () => Promise<void>;
+    adminIds: () => Promise<readonly number[]> | readonly number[];
+    /** Served results (WITH content — empty answers prove nothing) before the alarm. Default 25. */
+    threshold?: number;
+    /** Minimum ms between alerts. Default 24h. */
+    alertEveryMs?: number;
+    /** Called with the alarm line before the DM goes out (wire your logger). */
+    onTrip?: (message: string) => void;
+}
+export interface InlineFeedbackProbe {
+    /** Call after answering an inline query WITH results. Never throws. */
+    onServed(bot: Bot): Promise<void>;
+    /** Call from the chosen_inline_result handler. Never throws. */
+    onChosen(): Promise<void>;
+}
+export declare function inlineFeedbackProbe(opts: InlineFeedbackProbeOptions): InlineFeedbackProbe;
+//# sourceMappingURL=inline-feedback.d.ts.map

package/dist/bot/inline-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-feedback.d.ts","sourceRoot":"","sources":["../../src/bot/inline-feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAGlC,MAAM,WAAW,0BAA0B;IAC1C,yFAAyF;IACzF,IAAI,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACpE,uEAAuE;IACvE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,yEAAyE;IACzE,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,SAAS,MAAM,EAAE,CAAC;IAC/D,gGAAgG;IAChG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,gEAAgE;IAChE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAKD,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,0BAA0B,GAC9B,mBAAmB,CA6BrB"}

package/dist/bot/inline-feedback.js

@@ -0,0 +1,59 @@
+/**
+ * Inline-feedback tripwire — behavioral detection for a BotFather setting the
+ * Bot API cannot see.
+ *
+ * `chosen_inline_result` delivery is gated by BotFather's inline FEEDBACK
+ * probability, which defaults to 0% and silently RESETS on bot transfer and
+ * on inline-mode toggling. At 0%, taps post the placeholder client-side but
+ * the bot never hears about them, so nothing ever fills in — and `getMe`
+ * reports nothing (the profile `expects` drift-check is blind here). The
+ * asymmetry IS measurable though: results keep getting served while a chosen
+ * event never arrives.
+ *
+ * Storage is injected as three atomic-ish ops (wire to D1/Redis/anything);
+ * this module owns the thresholds, the throttle, and the operator message.
+ * Thresholds are deliberately lazy — this is a drift alarm, not a metric.
+ *
+ * @example
+ * const probe = inlineFeedbackProbe({
+ *   bump: () => store.bumpInlineServed(ctx),
+ *   reset: () => store.recordInlineChosen(ctx, Date.now()),
+ *   markAlerted: () => store.markInlineAlerted(ctx, Date.now()),
+ *   adminIds: () => deps.adminIds(),
+ * })
+ * bot.inlineQuery(async (ctx) => { …answer with results…; await probe.onServed(ctx.bot) })
+ * bot.chosenInlineResult(() => true, async (ctx) => { await probe.onChosen(); … })
+ */
+import { notifyAdmins } from "./notify.js";
+const DEFAULT_THRESHOLD = 25;
+const DEFAULT_ALERT_EVERY_MS = 24 * 60 * 60 * 1000;
+export function inlineFeedbackProbe(opts) {
+    const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+    const alertEveryMs = opts.alertEveryMs ?? DEFAULT_ALERT_EVERY_MS;
+    return {
+        async onServed(bot) {
+            try {
+                const { served, lastAlertAt } = await opts.bump();
+                if (served < threshold)
+                    return;
+                const now = Date.now();
+                if (lastAlertAt !== null && now - lastAlertAt < alertEveryMs)
+                    return;
+                await opts.markAlerted();
+                const line = `inline feedback looks DISABLED: ${served} inline results served since the last chosen_inline_result`;
+                opts.onTrip?.(line);
+                const ids = await opts.adminIds();
+                await notifyAdmins(bot, ids, `⚠️ ${line}.\n` +
+                    "Taps post the placeholder but the bot never hears about them, so nothing ever fills in.\n" +
+                    "@BotFather → /setinlinefeedback → this bot → 100%. (It resets to 0% on bot TRANSFER and on inline-mode toggling.)");
+            }
+            catch {
+                // best-effort: the probe must never break the inline answer path
+            }
+        },
+        async onChosen() {
+            await opts.reset().catch(() => { });
+        },
+    };
+}
+//# sourceMappingURL=inline-feedback.js.map

package/dist/bot/inline-feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-feedback.js","sourceRoot":"","sources":["../../src/bot/inline-feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAyB3C,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAC7B,MAAM,sBAAsB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnD,MAAM,UAAU,mBAAmB,CAClC,IAAgC;IAEhC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,iBAAiB,CAAC;IACtD,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,sBAAsB,CAAC;IACjE,OAAO;QACN,KAAK,CAAC,QAAQ,CAAC,GAAG;YACjB,IAAI,CAAC;gBACJ,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;gBAClD,IAAI,MAAM,GAAG,SAAS;oBAAE,OAAO;gBAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACvB,IAAI,WAAW,KAAK,IAAI,IAAI,GAAG,GAAG,WAAW,GAAG,YAAY;oBAAE,OAAO;gBACrE,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;gBACzB,MAAM,IAAI,GAAG,mCAAmC,MAAM,4DAA4D,CAAC;gBACnH,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;gBACpB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClC,MAAM,YAAY,CACjB,GAAyC,EACzC,GAAG,EACH,MAAM,IAAI,KAAK;oBACd,2FAA2F;oBAC3F,mHAAmH,CACpH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACR,iEAAiE;YAClE,CAAC;QACF,CAAC;QACD,KAAK,CAAC,QAAQ;YACb,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACpC,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/bot/metrics.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Metric registry — self-serve product measurement, the `bot/flags` pattern
+ * applied to counting. Declare a metric ONCE in code and it exists
+ * everywhere: `metrics.<key>.bump()` / `.record(value)` at the call site,
+ * generic day-bucketed storage underneath (no migration per metric), and
+ * `metrics.describe()` as the schema admin panels render generically — a new
+ * metric reaches every panel with zero panel edits.
+ *
+ * Built to answer PRODUCT questions, not just count:
+ *   volume     how many times           → counter
+ *   averages   how long / how big       → timing (count + sum → avg)
+ *   uniques    how many distinct users  → perUser: true
+ *   repeat     used it again same day?  → per-user day rows with count > 1
+ *   retention  came back another day?   → same user on ≥ 2 distinct days
+ *   funnels    of those who did A, who did B → declared pairs over the
+ *              shared user space; panels render conversion % generically
+ *   depth      how far do they go       → per-user daily counts distribute
+ *
+ * Storage is ONE injected write op; the atomic upserts live with the
+ * consumer's database. Contract: always add (count, sum) to the day bucket
+ * for `key`; when `user` is present, ALSO to the per-user day bucket, e.g.:
+ *
+ *   INSERT INTO metric (key, day, count, sum) VALUES (?1, date('now'), ?2, ?3)
+ *     ON CONFLICT (key, day) DO UPDATE SET count = count + ?2, sum = sum + ?3;
+ *   -- and when user is present:
+ *   INSERT INTO metric_user (key, user, day, count, sum) VALUES (?1, ?4, date('now'), ?2, ?3)
+ *     ON CONFLICT (key, user, day) DO UPDATE SET count = count + ?2, sum = sum + ?3;
+ *
+ * Per-user rows are personal data: wipe them in your forget-user path, and
+ * prune by age (growth is users × metrics × days). Writes are FIRE-AND-FORGET
+ * and never throw — measurement must never break the product. The registry
+ * IS the cardinality cap: keys are declared identifiers, never free-form
+ * strings. Money stays in ledgers; this is operational/product counting.
+ *
+ * @example
+ * const metrics = defineMetrics({
+ *   chapterOpens: { kind: "counter", label: "chapter opens", perUser: true },
+ *   chapterPages: { kind: "counter", label: "chapter pages", perUser: true, help: "Back/Next taps" },
+ *   chapterLatency: { kind: "timing", label: "chapter latency", unit: "ms" },
+ * }, {
+ *   write: (key, addCount, addSum, user) => store.metricBump(key, addCount, addSum, user),
+ *   funnels: [["chapterOpens", "chapterPages"]],
+ * })
+ *
+ * void metrics.chapterOpens.bump({ user: ctx.from.id })
+ * void metrics.chapterLatency.record(Date.now() - startedAt)
+ * metrics.describe() // → { metrics: [...], funnels: [...] } — panels iterate this
+ */
+/** One metric declaration. `perUser: true` unlocks uniques/repeat/retention/funnels for it. */
+export type MetricSpec = {
+    kind: "counter";
+    label: string;
+    help?: string;
+    perUser?: boolean;
+} | {
+    kind: "timing";
+    label: string;
+    help?: string;
+    unit?: string;
+    perUser?: boolean;
+};
+export interface MetricsOptions<Keys extends string = string> {
+    /**
+     * The atomic day-bucket upsert(s): add `addCount`/`addSum` to today's row
+     * for `key`, and — when `user` is present — to the per-user day row too
+     * (one batch). Failures are swallowed by the registry; make the op itself
+     * atomic.
+     */
+    write: (key: string, addCount: number, addSum: number, user?: number) => Promise<unknown>;
+    /**
+     * Declared conversion pairs over perUser metrics ("of users who did FROM,
+     * how many did TO"). Panels render these generically; they are queries
+     * over the shared user space, not extra storage.
+     */
+    funnels?: ReadonlyArray<readonly [Keys, Keys]>;
+}
+export interface CounterHandle {
+    /** Count `n` events (default 1); pass `user` on perUser metrics. Fire-and-forget, never throws. */
+    bump(opts?: {
+        user?: number;
+        n?: number;
+    }): Promise<void>;
+}
+export interface TimingHandle {
+    /** Record one sample; pass `user` on perUser metrics. Fire-and-forget, never throws. */
+    record(value: number, opts?: {
+        user?: number;
+    }): Promise<void>;
+}
+export interface MetricsSchema {
+    metrics: Array<{
+        key: string;
+    } & MetricSpec>;
+    funnels: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+export type Metrics<Spec extends Record<string, MetricSpec>> = {
+    [K in keyof Spec]: Spec[K]["kind"] extends "counter" ? CounterHandle : TimingHandle;
+} & {
+    /** The registry schema, for panels to render generically. */
+    describe(): MetricsSchema;
+};
+export declare function defineMetrics<const Spec extends Record<string, MetricSpec>>(spec: Spec, opts: MetricsOptions<Extract<keyof Spec, string>>): Metrics<Spec>;
+//# sourceMappingURL=metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/bot/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,+FAA+F;AAC/F,MAAM,MAAM,UAAU,GACnB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEL,MAAM,WAAW,cAAc,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IAC3D;;;;;OAKG;IACH,KAAK,EAAE,CACN,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,KACT,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,aAAa;IAC7B,mGAAmG;IACnG,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AACD,MAAM,WAAW,YAAY;IAC5B,wFAAwF;IACxF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,CAAC,CAAC;IAC7C,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7C;AAED,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI;KAC7D,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,SAAS,GACjD,aAAa,GACb,YAAY;CACf,GAAG;IACH,6DAA6D;IAC7D,QAAQ,IAAI,aAAa,CAAC;CAC1B,CAAC;AAEF,wBAAgB,aAAa,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAC1E,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,MAAM,CAAC,CAAC,GAC/C,OAAO,CAAC,IAAI,CAAC,CA2Cf"}

package/dist/bot/metrics.js

@@ -0,0 +1,91 @@
+/**
+ * Metric registry — self-serve product measurement, the `bot/flags` pattern
+ * applied to counting. Declare a metric ONCE in code and it exists
+ * everywhere: `metrics.<key>.bump()` / `.record(value)` at the call site,
+ * generic day-bucketed storage underneath (no migration per metric), and
+ * `metrics.describe()` as the schema admin panels render generically — a new
+ * metric reaches every panel with zero panel edits.
+ *
+ * Built to answer PRODUCT questions, not just count:
+ *   volume     how many times           → counter
+ *   averages   how long / how big       → timing (count + sum → avg)
+ *   uniques    how many distinct users  → perUser: true
+ *   repeat     used it again same day?  → per-user day rows with count > 1
+ *   retention  came back another day?   → same user on ≥ 2 distinct days
+ *   funnels    of those who did A, who did B → declared pairs over the
+ *              shared user space; panels render conversion % generically
+ *   depth      how far do they go       → per-user daily counts distribute
+ *
+ * Storage is ONE injected write op; the atomic upserts live with the
+ * consumer's database. Contract: always add (count, sum) to the day bucket
+ * for `key`; when `user` is present, ALSO to the per-user day bucket, e.g.:
+ *
+ *   INSERT INTO metric (key, day, count, sum) VALUES (?1, date('now'), ?2, ?3)
+ *     ON CONFLICT (key, day) DO UPDATE SET count = count + ?2, sum = sum + ?3;
+ *   -- and when user is present:
+ *   INSERT INTO metric_user (key, user, day, count, sum) VALUES (?1, ?4, date('now'), ?2, ?3)
+ *     ON CONFLICT (key, user, day) DO UPDATE SET count = count + ?2, sum = sum + ?3;
+ *
+ * Per-user rows are personal data: wipe them in your forget-user path, and
+ * prune by age (growth is users × metrics × days). Writes are FIRE-AND-FORGET
+ * and never throw — measurement must never break the product. The registry
+ * IS the cardinality cap: keys are declared identifiers, never free-form
+ * strings. Money stays in ledgers; this is operational/product counting.
+ *
+ * @example
+ * const metrics = defineMetrics({
+ *   chapterOpens: { kind: "counter", label: "chapter opens", perUser: true },
+ *   chapterPages: { kind: "counter", label: "chapter pages", perUser: true, help: "Back/Next taps" },
+ *   chapterLatency: { kind: "timing", label: "chapter latency", unit: "ms" },
+ * }, {
+ *   write: (key, addCount, addSum, user) => store.metricBump(key, addCount, addSum, user),
+ *   funnels: [["chapterOpens", "chapterPages"]],
+ * })
+ *
+ * void metrics.chapterOpens.bump({ user: ctx.from.id })
+ * void metrics.chapterLatency.record(Date.now() - startedAt)
+ * metrics.describe() // → { metrics: [...], funnels: [...] } — panels iterate this
+ */
+export function defineMetrics(spec, opts) {
+    for (const [key, s] of Object.entries(spec)) {
+        if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(key))
+            throw new Error(`metrics: invalid key "${key}"`);
+        if (!s.label)
+            throw new Error(`metrics: "${key}" needs a label`);
+    }
+    for (const [from, to] of opts.funnels ?? []) {
+        for (const k of [from, to]) {
+            if (!spec[k])
+                throw new Error(`metrics: funnel references unknown metric "${k}"`);
+            if (!spec[k].perUser)
+                throw new Error(`metrics: funnel metric "${k}" must be perUser (funnels join on user)`);
+        }
+    }
+    const out = {};
+    for (const [key, s] of Object.entries(spec)) {
+        out[key] =
+            s.kind === "counter"
+                ? {
+                    async bump(o) {
+                        await opts
+                            .write(key, o?.n ?? 1, 0, s.perUser ? o?.user : undefined)
+                            .catch(() => { });
+                    },
+                }
+                : {
+                    async record(value, o) {
+                        await opts
+                            .write(key, 1, value, s.perUser ? o?.user : undefined)
+                            .catch(() => { });
+                    },
+                };
+    }
+    return {
+        ...out,
+        describe: () => ({
+            metrics: Object.entries(spec).map(([key, s]) => ({ key, ...s })),
+            funnels: (opts.funnels ?? []).map(([from, to]) => ({ from, to })),
+        }),
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/bot/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/bot/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAyDH,MAAM,UAAU,aAAa,CAC5B,IAAU,EACV,IAAiD;IAEjD,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,GAAG,CAAC,CAAC;QAClD,IAAI,CAAC,CAAC,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,iBAAiB,CAAC,CAAC;IAClE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QAC7C,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,GAAG,CAAC,CAAC;YACrE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO;gBACnB,MAAM,IAAI,KAAK,CACd,2BAA2B,CAAC,0CAA0C,CACtE,CAAC;QACJ,CAAC;IACF,CAAC;IAED,MAAM,GAAG,GAAiD,EAAE,CAAC;IAC7D,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,GAAG,CAAC;YACP,CAAC,CAAC,IAAI,KAAK,SAAS;gBACnB,CAAC,CAAC;oBACA,KAAK,CAAC,IAAI,CAAC,CAAiC;wBAC3C,MAAM,IAAI;6BACR,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;6BACzD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACnB,CAAC;iBACD;gBACF,CAAC,CAAC;oBACA,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,CAAqB;wBAChD,MAAM,IAAI;6BACR,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;6BACrD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACnB,CAAC;iBACD,CAAC;IACN,CAAC;IACD,OAAO;QACN,GAAG,GAAG;QACN,QAAQ,EAAE,GAAkB,EAAE,CAAC,CAAC;YAC/B,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YAChE,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;SACjE,CAAC;KACe,CAAC;AACpB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.6.0",
+	"version": "2.8.0",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -147,6 +147,14 @@
 		"./llm": {
 			"types": "./dist/llm/index.d.ts",
 			"default": "./dist/llm/index.js"
+		},
+		"./bot/inline-feedback": {
+			"types": "./dist/bot/inline-feedback.d.ts",
+			"default": "./dist/bot/inline-feedback.js"
+		},
+		"./bot/metrics": {
+			"types": "./dist/bot/metrics.d.ts",
+			"default": "./dist/bot/metrics.js"
 		}
 	},
 	"files": [