@adriangalilea/utils 2.15.0 → 2.16.1

package/dist/bot/reactions.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Message-reaction arbitration: ONE owner for the bot's reaction on each
+ * message. Telegram's setMessageReaction REPLACES the bot's whole reaction
+ * set, so independent features reacting to the same message (an "on it" ack,
+ * an outcome, a side-feature's shrug) silently clobber each other — last
+ * writer wins, and the client shows flickering swaps.
+ *
+ * The fix is semantic states with ranks, arbitrated per message:
+ *
+ *   const status = reactionPolicy({
+ *     working: { emoji: "🫡", rank: 1 },
+ *     offTopic: { emoji: "🤷", rank: 2 },
+ *     failed:  { emoji: "👎", rank: 3 },
+ *     done:    { emoji: "🫡", rank: 4 },   // same emoji as working: no API call, but locks out offTopic
+ *   });
+ *   const r = status.for(ctx);
+ *   await r.set("working");   // applied
+ *   await r.set("done");      // rank bookkeeping only (same emoji) — zero API calls, zero flicker
+ *   await r.set("offTopic");  // REJECTED: outranked by done — the shrug never lands
+ *
+ * Guarantees:
+ *  - a state only applies when its rank is >= the current state's rank
+ *    (equal rank may refine; strictly lower is rejected — returns false);
+ *  - setting the current state again is a no-op (idempotent, no API call);
+ *  - a transition between states sharing an emoji makes NO API call
+ *    (rank bookkeeping without flicker);
+ *  - react() failures are swallowed — reactions are decoration, they must
+ *    never break the flow that set them;
+ *  - state is keyed by chat:message, so one policy instance serves every
+ *    message concurrently, and is bounded (reactions are transient
+ *    request-lifetime coordination, not durable state).
+ */
+export interface ReactionStateSpec {
+    /** The Telegram reaction emoji this state renders as. */
+    emoji: string;
+    /** Arbitration rank: a state only applies over an equal-or-lower rank. */
+    rank: number;
+}
+/** The context surface read off the ctx: the message identity plus gramio's react().
+ *  `for()` takes `unknown` and narrows structurally (gramio's react() param is an
+ *  emoji-literal union, which no portable signature satisfies in strict variance) —
+ *  a ctx without a callable react() screams instead of silently not reacting. */
+export interface ReactionCtx {
+    id?: number;
+    chatId?: number;
+    chat?: {
+        id?: number;
+    };
+    react(emoji: string): Promise<unknown>;
+}
+export interface ReactionHandle<S extends string> {
+    /** The current state on this message, or null if none was set. */
+    state(): S | null;
+    /**
+     * Request a state. Applies (and reacts, if the emoji changes) only when
+     * not outranked by the current state. Returns whether the state holds
+     * after the call (true also for an idempotent re-set).
+     */
+    set(next: S): Promise<boolean>;
+}
+/** Declare the reaction vocabulary once; get per-message arbitrated handles. */
+export declare function reactionPolicy<S extends Record<string, ReactionStateSpec>>(states: S): {
+    /** The arbitrated handle for THIS ctx's message (keyed chat:message). */
+    for(context: unknown): ReactionHandle<keyof S & string>;
+};
+//# sourceMappingURL=reactions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reactions.d.ts","sourceRoot":"","sources":["../../src/bot/reactions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,iBAAiB;IACjC,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;iFAGiF;AACjF,MAAM,WAAW,WAAW;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM;IAC/C,kEAAkE;IAClE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAClB;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/B;AAMD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAInF,yEAAyE;iBAC5D,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;EAuBxD"}

package/dist/bot/reactions.js

@@ -0,0 +1,71 @@
+/**
+ * Message-reaction arbitration: ONE owner for the bot's reaction on each
+ * message. Telegram's setMessageReaction REPLACES the bot's whole reaction
+ * set, so independent features reacting to the same message (an "on it" ack,
+ * an outcome, a side-feature's shrug) silently clobber each other — last
+ * writer wins, and the client shows flickering swaps.
+ *
+ * The fix is semantic states with ranks, arbitrated per message:
+ *
+ *   const status = reactionPolicy({
+ *     working: { emoji: "🫡", rank: 1 },
+ *     offTopic: { emoji: "🤷", rank: 2 },
+ *     failed:  { emoji: "👎", rank: 3 },
+ *     done:    { emoji: "🫡", rank: 4 },   // same emoji as working: no API call, but locks out offTopic
+ *   });
+ *   const r = status.for(ctx);
+ *   await r.set("working");   // applied
+ *   await r.set("done");      // rank bookkeeping only (same emoji) — zero API calls, zero flicker
+ *   await r.set("offTopic");  // REJECTED: outranked by done — the shrug never lands
+ *
+ * Guarantees:
+ *  - a state only applies when its rank is >= the current state's rank
+ *    (equal rank may refine; strictly lower is rejected — returns false);
+ *  - setting the current state again is a no-op (idempotent, no API call);
+ *  - a transition between states sharing an emoji makes NO API call
+ *    (rank bookkeeping without flicker);
+ *  - react() failures are swallowed — reactions are decoration, they must
+ *    never break the flow that set them;
+ *  - state is keyed by chat:message, so one policy instance serves every
+ *    message concurrently, and is bounded (reactions are transient
+ *    request-lifetime coordination, not durable state).
+ */
+// Transient per-isolate coordination, not durable state: bound it so a
+// long-lived isolate can't grow the map without limit.
+const MAX_TRACKED_MESSAGES = 512;
+/** Declare the reaction vocabulary once; get per-message arbitrated handles. */
+export function reactionPolicy(states) {
+    const current = new Map();
+    return {
+        /** The arbitrated handle for THIS ctx's message (keyed chat:message). */
+        for(context) {
+            const ctx = context;
+            if (typeof ctx.react !== "function")
+                throw new Error("reactionPolicy.for: ctx has no react()");
+            const chat = ctx.chatId ?? ctx.chat?.id;
+            const key = `${chat}:${ctx.id}`;
+            return {
+                state: () => current.get(key) ?? null,
+                async set(next) {
+                    const spec = states[next];
+                    if (!spec)
+                        throw new Error(`unknown reaction state: ${String(next)}`);
+                    const prev = current.get(key);
+                    if (prev === next)
+                        return true; // idempotent
+                    if (prev !== undefined && spec.rank < states[prev].rank)
+                        return false; // outranked
+                    if (!current.has(key) && current.size >= MAX_TRACKED_MESSAGES)
+                        current.clear();
+                    current.set(key, next);
+                    // Same emoji under a new state: bookkeeping only — no API call, no flicker.
+                    if (prev !== undefined && states[prev].emoji === spec.emoji)
+                        return true;
+                    await ctx.react(spec.emoji).catch(() => { });
+                    return true;
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=reactions.js.map

package/dist/bot/reactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactions.js","sourceRoot":"","sources":["../../src/bot/reactions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA+BH,uEAAuE;AACvE,uDAAuD;AACvD,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,gFAAgF;AAChF,MAAM,UAAU,cAAc,CAA8C,MAAS;IACpF,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;IAEpD,OAAO;QACN,yEAAyE;QACzE,GAAG,CAAC,OAAgB;YACnB,MAAM,GAAG,GAAG,OAAsB,CAAC;YACnC,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU;gBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC/F,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;YACxC,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;YAChC,OAAO;gBACN,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI;gBACrC,KAAK,CAAC,GAAG,CAAC,IAAI;oBACb,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;oBAC1B,IAAI,CAAC,IAAI;wBAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACtE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;oBAC9B,IAAI,IAAI,KAAK,IAAI;wBAAE,OAAO,IAAI,CAAC,CAAC,aAAa;oBAC7C,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI;wBAAE,OAAO,KAAK,CAAC,CAAC,YAAY;oBACnF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,IAAI,oBAAoB;wBAAE,OAAO,CAAC,KAAK,EAAE,CAAC;oBAC/E,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;oBACvB,4EAA4E;oBAC5E,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;wBAAE,OAAO,IAAI,CAAC;oBACzE,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBAC5C,OAAO,IAAI,CAAC;gBACb,CAAC;aACD,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.15.0",
+	"version": "2.16.1",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -156,6 +156,10 @@
 			"types": "./dist/bot/urls.d.ts",
 			"default": "./dist/bot/urls.js"
 		},
+		"./bot/reactions": {
+			"types": "./dist/bot/reactions.d.ts",
+			"default": "./dist/bot/reactions.js"
+		},
 		"./llm": {
 			"types": "./dist/llm/index.d.ts",
 			"default": "./dist/llm/index.js"
@@ -200,7 +204,8 @@
 		"test:tg-md": "tsx tests/tg-md-test.ts",
 		"test:self-echo": "tsx tests/self-echo-test.ts",
 		"test:url": "tsx tests/url-test.ts",
-		"test:bot-urls": "tsx tests/bot-urls-test.ts"
+		"test:bot-urls": "tsx tests/bot-urls-test.ts",
+		"test:reactions": "tsx tests/reactions-test.ts"
 	},
 	"keywords": [
 		"typescript",