@adriangalilea/utils 2.6.0 → 2.7.0

package/dist/bot/index.d.ts

@@ -18,6 +18,7 @@ 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";

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,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/bot/index.js

@@ -18,6 +18,7 @@ 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";

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,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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.6.0",
+	"version": "2.7.0",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -147,6 +147,10 @@
 		"./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"
 		}
 	},
 	"files": [