charness 0.0.0-stage → 3.1.0

package/dist/threadRouting.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * @description Pure routing-decision logic — extracted from `bot.ts` so
+ * the gating rules (plan §8) can be unit-tested without booting Telegraf,
+ * parsing ENV, or pulling in 30+ adapter dependencies.
+ *
+ * The Telegram `Context` object carries everything we need:
+ *   - `ctx.chat` → forum supergroup detection + chat-id allowlist gate
+ *   - `ctx.message` (or `ctx.callbackQuery.message`) →
+ *     `message_thread_id` + `is_topic_message`
+ *
+ * Both fields are passed in by `bot.ts:getThreadKey` after pulling them
+ * from the live context, so this module can stay free of Telegraf imports.
+ *
+ * The `GENERAL_THREAD_ID = 1` constant is the magic number for the
+ * General forum topic — Telegram returns the thread id either as `1` or
+ * (sometimes) as `undefined` for posts in General; we normalise both to 1.
+ *
+ * Plan §11 Этап 7 / R2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chatModeValues = exports.DM_GENERAL_THREAD_ID = exports.GENERAL_THREAD_ID = void 0;
+exports.checkIsChatMode = checkIsChatMode;
+exports.resolveThreadKey = resolveThreadKey;
+exports.resolveDmThreadKey = resolveDmThreadKey;
+exports.checkIsDmThreadKey = checkIsDmThreadKey;
+exports.resolveThreadKeyForMode = resolveThreadKeyForMode;
+exports.checkIsGeneralTopic = checkIsGeneralTopic;
+exports.resolvePairingCandidate = resolvePairingCandidate;
+const sessionKeyCodec_1 = require("./connectors/telegram/sessionKeyCodec");
+/** Telegram's stable id for the General forum topic. */
+exports.GENERAL_THREAD_ID = 1;
+/**
+ * @description "General" thread id in the owner-DM surface. A message posted to
+ * the DM's main thread carries NO `message_thread_id`; we normalise that to `0`
+ * (distinct from the supergroup's `1`) so the two surfaces never collide in a
+ * persisted `SessionKey` and `checkIsGeneral` can stay mode-aware.
+ */
+exports.DM_GENERAL_THREAD_ID = 0;
+/** The valid {@link ChatMode} values, for env validation. */
+exports.chatModeValues = ['group', 'dm', 'both'];
+/** Type guard: is `value` a valid {@link ChatMode}? */
+function checkIsChatMode(value) {
+    return exports.chatModeValues.includes(value);
+}
+/**
+ * @description Compute the `SessionKey` for an incoming Telegram update,
+ * or return `null` if the bot should silently ignore it.
+ *
+ * Gating rules (plan §8):
+ *   1. Chat is a forum supergroup (`type === 'supergroup'` AND `is_forum`).
+ *   2. `chat.id === allowedGroupId`.
+ *   3. If a `message_thread_id` is present, `is_topic_message` must be
+ *      `true` — guards against plain reply-threads in non-forum
+ *      supergroups, which also carry `message_thread_id` but are NOT
+ *      topics (plan §4.3 point 2, T7).
+ *   4. Missing `message_thread_id` → General topic (id 1).
+ */
+function resolveThreadKey(input, allowedGroupId) {
+    const chat = input.chat;
+    if (!chat || chat.type !== 'supergroup')
+        return null;
+    if (!chat.is_forum)
+        return null;
+    if (chat.id !== allowedGroupId)
+        return null;
+    // Callback-query updates carry the originating message under
+    // `ctx.callbackQuery.message`. Either source is fine — they share the
+    // forum-topic fields by Telegram's data model.
+    const msg = input.message ?? input.callbackQueryMessage;
+    const rawThreadId = msg?.message_thread_id;
+    const isTopicMessage = msg?.is_topic_message;
+    // Reply-threads in non-forum supergroups also carry message_thread_id.
+    // We've already gated on `is_forum`, but a forum supergroup can still
+    // host a reply on the General-topic root — `is_topic_message` is `false`
+    // in that case and we should NOT mis-route it to a custom topic id.
+    if (rawThreadId && !isTopicMessage)
+        return null;
+    const threadId = rawThreadId ?? exports.GENERAL_THREAD_ID;
+    return (0, sessionKeyCodec_1.makeTelegramKey)(chat.id, threadId);
+}
+/**
+ * @description Compute the `SessionKey` for an incoming update in DM mode, or
+ * `null` if the bot should ignore it.
+ *
+ * The DM surface accepts updates ONLY from the OWNER'S private chat — and the
+ * owner's private-chat id IS the owner's user id, so a single equality both
+ * gates the chat and identifies the owner:
+ *   1. `chat.type === 'private'` — any non-DM update is ignored here.
+ *   2. `chat.id === ownerUserId` — only the owner's DM, never another user's.
+ *
+ * The thread is the DM-topic's `message_thread_id`; a message in the DM's main
+ * thread carries none → normalised to {@link DM_GENERAL_THREAD_ID} (0). Unlike
+ * the supergroup path there is no `is_topic_message` gate: a private chat has no
+ * reply-thread/topic ambiguity to disambiguate.
+ */
+function resolveDmThreadKey(input, ownerUserId) {
+    const chat = input.chat;
+    if (!chat || chat.type !== 'private')
+        return null;
+    if (chat.id !== ownerUserId)
+        return null;
+    const msg = input.message ?? input.callbackQueryMessage;
+    const threadId = msg?.message_thread_id ?? exports.DM_GENERAL_THREAD_ID;
+    return (0, sessionKeyCodec_1.makeTelegramKey)(chat.id, threadId);
+}
+/**
+ * @description Per-chat discriminator: does `key` belong to the DM surface? A DM
+ * key's `chatId` is the owner's user id (`resolveDmThreadKey` gates
+ * `chat.id === ownerUserId`), so the equality both identifies the surface and
+ * re-asserts the owner. Always false when the DM surface is inert — then
+ * `ownerUserId` is `NaN`, which never equals a real chat id anyway, but the guard
+ * makes a group-only `both` unambiguously group.
+ */
+function checkIsDmThreadKey(key, ownerUserId, isDmSurfaceActive) {
+    if (!isDmSurfaceActive)
+        return false;
+    // A predicate must answer, not throw: a key from another platform simply
+    // isn't this Telegram surface's DM.
+    if (!(0, sessionKeyCodec_1.checkIsTelegramKey)(key))
+        return false;
+    return (0, sessionKeyCodec_1.getTelegramChatId)(key) === ownerUserId;
+}
+/**
+ * @description Resolve the `SessionKey` for an update across BOTH surfaces, per
+ * {@link ChatMode}. The two resolvers are disjoint (a private chat vs. a forum
+ * supergroup), so trying both in `both` is unambiguous — an update matches at
+ * most one. The owner-DM resolver runs first when the DM surface is live
+ * (skipped when inert); the group resolver runs unless we are DM-only. A
+ * non-matching surface returns `null` → drop. The single composition behind
+ * `bot.ts:getThreadKey`, kept pure here so it is unit-testable.
+ */
+function resolveThreadKeyForMode(input, routing) {
+    if (routing.isDmSurfaceActive) {
+        const dmKey = resolveDmThreadKey(input, routing.ownerUserId);
+        if (dmKey)
+            return dmKey;
+    }
+    if (routing.mode === 'dm')
+        return null;
+    return resolveThreadKey(input, routing.allowedGroupId);
+}
+/**
+ * @description Convenience: is this the General topic? Used by command
+ * handlers that have different semantics in General vs. a thematic topic
+ * (e.g. `/ls` is General-only, `/bind` is topic-only).
+ *
+ * Mode-aware: the supergroup surface marks General with `1`, the DM surface
+ * with `0` (no `message_thread_id`). Pass the active {@link ChatMode} so the
+ * right marker is checked.
+ */
+function checkIsGeneralTopic(key, mode = 'group') {
+    if (!(0, sessionKeyCodec_1.checkIsTelegramKey)(key))
+        return false;
+    const generalThreadId = mode === 'dm' ? exports.DM_GENERAL_THREAD_ID : exports.GENERAL_THREAD_ID;
+    return (0, sessionKeyCodec_1.getTelegramThreadId)(key) === generalThreadId;
+}
+/**
+ * @description Decide whether an incoming update's chat is STRUCTURALLY a
+ * pairing candidate. Returns the chat id to pair, or `null`.
+ *
+ * Eligible only when ALL hold:
+ *   1. Not locked by a numeric `ALLOWED_GROUP_ID` env.
+ *   2. No effective group id yet (`currentGroupId === null`).
+ *   3. The chat is a forum supergroup (same gate as {@link resolveThreadKey}).
+ *
+ * The actor's authority — they must be a creator/administrator of the group, so
+ * a random group can't hijack pairing — is verified separately and
+ * asynchronously by the caller via `getChatAdministrators`; it can't live in a
+ * pure helper.
+ */
+function resolvePairingCandidate(input) {
+    if (input.isEnvLocked)
+        return null;
+    if (input.currentGroupId !== null)
+        return null;
+    const { chat } = input;
+    if (!chat || chat.type !== 'supergroup' || !chat.is_forum)
+        return null;
+    return chat.id;
+}
+//# sourceMappingURL=threadRouting.js.map

package/dist/threadRouting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threadRouting.js","sourceRoot":"","sources":["../src/threadRouting.ts"],"names":[],"mappings":"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"}