@crewhaus/channel-adapter-telegram 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/channel-adapter-telegram",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "Telegram channel adapter: secret_token webhook verification, message/edited_message/callback_query parsing, group + topic session keying (Section 33)",
   "main": "src/index.ts",
@@ -12,7 +12,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.3"
+    "@crewhaus/errors": "0.1.4"
   },
   "license": "Apache-2.0",
   "author": {

package/src/index.test.ts

@@ -568,6 +568,82 @@ describe("sendReply / setTyping (T3)", () => {
   });
 });
 
+describe("react (Phase 3 §3.2)", () => {
+  function captureFetch() {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const f = (async (input: string | Request | URL, init?: RequestInit) => {
+      calls.push({ url: String(input), init: init ?? {} });
+      return new Response(JSON.stringify({ ok: true, result: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+    return { calls, fetch: f };
+  }
+
+  const event: InboundEvent = {
+    idempotencyKey: "100001",
+    workspaceId: "4242",
+    channelId: "4242",
+    userId: "4242",
+    ts: "7",
+    text: "hello",
+    subtype: "message",
+  };
+
+  test("posts setMessageReaction with chat_id, message_id, and a mapped allowed emoji", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = createTelegramAdapter(
+      { botToken: BOT_TOKEN, secretToken: SECRET },
+      { apiBaseUrl: "https://test.telegram.local", fetch: f },
+    );
+    expect(a.react).toBeDefined();
+    await a.react?.({ event, emoji: "eyes" });
+    expect(calls.length).toBe(1);
+    expect(calls[0]?.url).toBe(`https://test.telegram.local/bot${BOT_TOKEN}/setMessageReaction`);
+    const body = JSON.parse(String(calls[0]?.init.body));
+    expect(body.chat_id).toBe(4242);
+    expect(body.message_id).toBe(7);
+    expect(body.reaction).toEqual([{ type: "emoji", emoji: "👀" }]);
+  });
+
+  test("maps white_check_mark/warning to Telegram-allowed emoji", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = createTelegramAdapter(
+      { botToken: BOT_TOKEN, secretToken: SECRET },
+      { apiBaseUrl: "https://test.telegram.local", fetch: f },
+    );
+    await a.react?.({ event, emoji: "white_check_mark" });
+    await a.react?.({ event, emoji: "warning" });
+    expect(JSON.parse(String(calls[0]?.init.body)).reaction[0].emoji).toBe("👍");
+    expect(JSON.parse(String(calls[1]?.init.body)).reaction[0].emoji).toBe("😱");
+  });
+
+  test("rejects when chat/message id is not numeric", async () => {
+    const { fetch: f } = captureFetch();
+    const a = createTelegramAdapter(
+      { botToken: BOT_TOKEN, secretToken: SECRET },
+      { apiBaseUrl: "https://test.telegram.local", fetch: f },
+    );
+    await expect(a.react?.({ event: { ...event, ts: "nope" }, emoji: "eyes" })).rejects.toThrow(
+      TelegramAdapterError,
+    );
+  });
+
+  test("throws on Telegram-side ok:false (router swallows it)", async () => {
+    const f = (async () =>
+      new Response(JSON.stringify({ ok: false, description: "REACTION_INVALID" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+    const a = createTelegramAdapter(
+      { botToken: BOT_TOKEN, secretToken: SECRET },
+      { apiBaseUrl: "https://test.telegram.local", fetch: f },
+    );
+    await expect(a.react?.({ event, emoji: "eyes" })).rejects.toThrow(/REACTION_INVALID/);
+  });
+});
+
 describe("apiBaseUrl resolution", () => {
   const event: InboundEvent = {
     idempotencyKey: "1",

package/src/index.ts

@@ -20,6 +20,7 @@
  *
  * sendReply: POST to `https://api.telegram.org/bot<token>/sendMessage`.
  * setTyping: POST `sendChatAction` with `action=typing`.
+ * react: POST `setMessageReaction` (Bot API 7.0) — best-effort status emoji.
  */
 import { CrewhausError } from "@crewhaus/errors";
 import { verifyTelegramSecret } from "./verify.js";
@@ -75,6 +76,14 @@ export interface ChannelAdapter {
   parseInbound(req: RawRequest): ParsedInbound;
   sendReply(args: { event: InboundEvent; text: string }): Promise<void>;
   setTyping(args: { event: InboundEvent }): Promise<void>;
+  /**
+   * Phase 3 §3.2 — add an emoji reaction to an inbound message as a
+   * lightweight status acknowledgement (eyes/white_check_mark/warning).
+   * Telegram restricts reactions to a fixed emoji set, so the channel-generic
+   * status names are mapped to the nearest allowed reaction. Optional — the
+   * session-router skips the hook when an adapter leaves it undefined.
+   */
+  react?(args: { event: InboundEvent; emoji: string }): Promise<void>;
 }
 
 export type TelegramAdapterConfig = {
@@ -90,6 +99,15 @@ export type TelegramAdapterOptions = {
 
 const DEFAULT_API_BASE_URL = "https://api.telegram.org";
 
+// Telegram's `setMessageReaction` only accepts emoji from a fixed allowed set
+// (✅ and ⚠️ are NOT in it), so map the channel-generic status names to the
+// nearest allowed reaction. An unrecognised name is passed through verbatim.
+const TELEGRAM_REACTION_EMOJI: Record<string, string> = {
+  eyes: "👀",
+  white_check_mark: "👍",
+  warning: "😱",
+};
+
 export function createTelegramAdapter(
   config: TelegramAdapterConfig,
   opts: TelegramAdapterOptions = {},
@@ -242,6 +260,45 @@ export function createTelegramAdapter(
       });
       // setTyping is best-effort; a non-200 here should not fail the run.
     },
+
+    // Phase 3 §3.2 — emoji reactions via Bot API 7.0 `setMessageReaction`.
+    // chat_id comes from the raw chat id (workspaceId); message_id from `ts`.
+    async react(args: { event: InboundEvent; emoji: string }): Promise<void> {
+      const url = botEndpoint("setMessageReaction");
+      const chatId = Number.parseInt(args.event.workspaceId, 10);
+      const messageId = Number.parseInt(args.event.ts, 10);
+      if (!Number.isFinite(chatId) || !Number.isFinite(messageId)) {
+        throw new TelegramAdapterError(
+          `invalid chat/message id for reaction: ${args.event.workspaceId}/${args.event.ts}`,
+        );
+      }
+      const emoji = TELEGRAM_REACTION_EMOJI[args.emoji] ?? args.emoji;
+      const res = await doFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          chat_id: chatId,
+          message_id: messageId,
+          reaction: [{ type: "emoji", emoji }],
+        }),
+      });
+      // Reactions are best-effort — the session-router catches and continues so
+      // a flaky/disallowed reaction never aborts message processing.
+      if (!res.ok) {
+        throw new TelegramAdapterError(
+          `setMessageReaction failed: ${res.status} ${res.statusText}`,
+        );
+      }
+      const ct = res.headers.get("content-type") ?? "";
+      if (ct.includes("application/json")) {
+        const json = (await res.json()) as { ok?: boolean; description?: string };
+        if (json.ok === false) {
+          throw new TelegramAdapterError(
+            `setMessageReaction error: ${json.description ?? "unknown"}`,
+          );
+        }
+      }
+    },
   };
 }