@rubytech/create-maxy-code 0.1.581 → 0.1.583

package/payload/platform/lib/telegram-reach/dist/index.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStorableChannelKey = isStorableChannelKey;
+exports.isBusinessChannelKey = isBusinessChannelKey;
+exports.channelKeyToFileStem = channelKeyToFileStem;
+exports.fileStemToChannelKey = fileStemToChannelKey;
+exports.collectTelegramReach = collectTelegramReach;
+/**
+ * Task 2625 — which Telegram chats a registered bot can already message.
+ *
+ * Telegram does not let a bot open a conversation: the person must message it
+ * first (core.telegram.org/bots). So "can I reach X" is answerable only from
+ * what has already arrived, and the record of that is the message store the
+ * webhook writes. Before this module nothing enumerated it, and the agent
+ * refused a send that one telegram-card call would have made.
+ *
+ * Shared rather than duplicated plugin-side, unlike the live-location and card
+ * stores: BOTH callers need this same walk — the MCP tool answers one account on
+ * demand, the hourly census counts every account — so duplicating it would mean
+ * writing the walk twice and holding it together with a boundary test. The
+ * filename rule lives here too, and `ui/app/lib/telegram/message-store.ts`
+ * re-exports it, so the store that writes a filename and the walk that reads one
+ * cannot disagree.
+ *
+ * Path-free by construction: the caller passes `storeDir`. The plugin derives it
+ * from PLATFORM_ROOT and the server from the brand config dir, and neither
+ * derivation belongs in a library that must not know what a brand is.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Is this a channel key that can safely become a path segment?
+ *
+ * Both halves of an admin key are Telegram numeric ids (a bot id is positive; a
+ * chat or sender id is an integer and is negative for groups), so requiring
+ * exactly that is both the truthful shape check and a complete traversal guard:
+ * no `.`, `/` or `\` can survive it.
+ *
+ * Task 2615 — the business shape `<botId>:biz:<senderId>` joins the guard rather
+ * than bypassing it. Both alternatives are anchored and admit only digits, an
+ * optional leading minus and the literal `biz`, so neither can carry a `.`, `/`
+ * or `\` either.
+ */
+function isStorableChannelKey(channelKey) {
+    return /^-?\d+:-?\d+$/.test(channelKey) || /^-?\d+:biz:-?\d+$/.test(channelKey);
+}
+/** Task 2615 — is this the three-part business shape?
+ *
+ *  Its own predicate rather than a `.includes(':biz:')` at each caller: a
+ *  business conversation is reached through the business-connection send route
+ *  and its 24-hour window, not by addressing a chat id, so anything that answers
+ *  "can we message this person now" has to be able to tell the two apart. */
+function isBusinessChannelKey(channelKey) {
+    return /^-?\d+:biz:-?\d+$/.test(channelKey);
+}
+/** The filename stem for a channel key.
+ *
+ *  Throws on a key that is neither two numeric ids nor the business shape.
+ *  Refusing loudly is correct here: every caller reaches this with a key it has
+ *  already validated, so an unstorable key means a caller skipped its guard, and
+ *  silently sanitising it would build a path nobody asked for. */
+function channelKeyToFileStem(channelKey) {
+    if (!isStorableChannelKey(channelKey)) {
+        throw new Error(`telegram-message-store: refusing unstorable channelKey ${JSON.stringify(channelKey)}`);
+    }
+    // Task 2615 — every colon, not only the first: a business key has two.
+    return channelKey.replaceAll(":", "_");
+}
+/** The inverse of `channelKeyToFileStem`.
+ *
+ *  Task 2615 — a stem whose second segment is exactly `biz` is a three-part
+ *  business key. Otherwise only the FIRST `_` is a separator, because both halves
+ *  of an admin key are numeric Telegram ids and nothing later in that stem is
+ *  one. */
+function fileStemToChannelKey(stem) {
+    const i = stem.indexOf("_");
+    if (i <= 0)
+        return stem;
+    const rest = stem.slice(i + 1);
+    if (rest.startsWith("biz_")) {
+        return `${stem.slice(0, i)}:biz:${rest.slice("biz_".length)}`;
+    }
+    return `${stem.slice(0, i)}:${rest}`;
+}
+function parseLines(raw) {
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // A partial write from a crash mid-append is skipped, never fatal: one
+            // corrupt line must not hide every other chat in the account.
+        }
+    }
+    return out;
+}
+/** Every conversation file's newest inbound PRIVATE row, keyed
+ *  `<botId>:<senderId>`, plus the message rows read getting there. */
+function scanStore(storeDir) {
+    const newest = new Map();
+    let storeRows = 0;
+    if (!storeDir || !(0, node_fs_1.existsSync)(storeDir))
+        return { newest, storeRows };
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(storeDir);
+    }
+    catch {
+        return { newest, storeRows };
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".jsonl"))
+            continue;
+        const stem = entry.slice(0, -".jsonl".length);
+        const channelKey = fileStemToChannelKey(stem);
+        if (!isStorableChannelKey(channelKey))
+            continue;
+        // Task 2615's business conversations are skipped entirely, rows included.
+        // A business chat is NOT reached by addressing a chat id: it needs the
+        // business-connection send route and its own 24-hour window, which Task 2625
+        // put out of scope. Listing one here would report it as sendable with
+        // telegram-card, which is the same wrong answer in the opposite direction to
+        // the refusal this tool exists to prevent.
+        if (isBusinessChannelKey(channelKey))
+            continue;
+        const botId = channelKey.slice(0, channelKey.indexOf(":"));
+        let raw;
+        try {
+            raw = (0, node_fs_1.readFileSync)((0, node_path_1.join)(storeDir, entry), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const row of parseLines(raw)) {
+            // An update row is a patch, not a message: counting it would inflate
+            // storeRows and it carries no sender at all.
+            if (row.kind === "update")
+                continue;
+            storeRows += 1;
+            if (row.origin !== "inbound")
+                continue;
+            const chatId = typeof row.chatId === "string" ? row.chatId : null;
+            const senderId = typeof row.senderId === "string" ? row.senderId : null;
+            const dateSent = typeof row.dateSent === "string" ? row.dateSent : null;
+            if (chatId === null || senderId === null || dateSent === null)
+                continue;
+            // Private chats only. A DM chat id equals the sender id; a group's differs
+            // (telegram-gateway.ts:66-68). A group is not a route to a person.
+            if (chatId !== senderId)
+                continue;
+            const key = `${botId}:${senderId}`;
+            const prev = newest.get(key);
+            if (prev !== undefined && prev.dateSent.localeCompare(dateSent) >= 0)
+                continue;
+            newest.set(key, {
+                chatId,
+                senderId,
+                senderName: typeof row.senderName === "string" ? row.senderName : null,
+                dateSent,
+            });
+        }
+    }
+    return { newest, storeRows };
+}
+/** Reachability for one account: every registered bot, the private chats that
+ *  have messaged it, and the allowlisted people who have not. */
+function collectTelegramReach(input) {
+    const { newest, storeRows } = scanStore(input.storeDir);
+    const bots = input.bots.map((bot) => {
+        const adminUsers = bot.adminUsers ?? [];
+        const adminSet = new Set(adminUsers.map((u) => String(u)));
+        const chats = [];
+        const seen = new Set();
+        for (const [key, row] of newest) {
+            if (key.slice(0, key.indexOf(":")) !== bot.id)
+                continue;
+            seen.add(row.senderId);
+            chats.push({
+                chatId: row.chatId,
+                senderId: row.senderId,
+                displayName: row.senderName,
+                lastInbound: row.dateSent,
+                admin: adminSet.has(row.senderId),
+                reachable: true,
+            });
+        }
+        chats.sort((a, b) => (b.lastInbound ?? "").localeCompare(a.lastInbound ?? ""));
+        for (const user of adminUsers) {
+            const senderId = String(user);
+            if (seen.has(senderId))
+                continue;
+            // Listed, never messaged. Reported rather than omitted, because "we are
+            // allowed to talk to them" and "they have opened the chat" are different
+            // facts and only the second one makes a send possible.
+            chats.push({
+                chatId: null,
+                senderId,
+                displayName: null,
+                lastInbound: null,
+                admin: true,
+                reachable: false,
+            });
+        }
+        return { botId: bot.id, role: bot.role, adminUsers, chats };
+    });
+    return { bots, storeRows };
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/telegram-reach/dist/index.js.map

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

package/payload/platform/lib/telegram-reach/src/__tests__/telegram-reach.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  collectTelegramReach,
+  isStorableChannelKey,
+  isBusinessChannelKey,
+  channelKeyToFileStem,
+  fileStemToChannelKey,
+} from "../index.js";
+
+const BOT = "8801383568";
+const KIT = "8860040117";
+const NEO = "1311221864";
+const GROUP = "-1002222222222";
+
+let storeDir: string;
+
+/** One inbound message row, in the shape message-store.ts writes. */
+const inbound = (over: Record<string, unknown> = {}) => ({
+  messageId: `telegram:acct:${BOT}:${KIT}:in:1`,
+  sessionId: "s",
+  dateSent: "2026-08-09T07:46:31.000Z",
+  body: "hello",
+  fromMe: false,
+  senderId: KIT,
+  senderName: "Kit Smalley",
+  chatId: KIT,
+  channelKey: `${BOT}:${KIT}`,
+  scope: "admin",
+  origin: "inbound",
+  createdAt: "2026-08-09T07:46:31.000Z",
+  ...over,
+});
+
+function writeConversation(channelKey: string, rows: unknown[]): void {
+  const file = join(storeDir, `${channelKeyToFileStem(channelKey)}.jsonl`);
+  writeFileSync(file, rows.map((r) => JSON.stringify(r)).join("\n") + "\n", "utf8");
+}
+
+beforeEach(() => {
+  storeDir = mkdtempSync(join(tmpdir(), "tg-reach-"));
+});
+
+afterEach(() => {
+  rmSync(storeDir, { recursive: true, force: true });
+});
+
+describe("the key helpers", () => {
+  it("accepts two numeric ids and rejects a traversal", () => {
+    expect(isStorableChannelKey(`${BOT}:${KIT}`)).toBe(true);
+    expect(isStorableChannelKey(`${BOT}:${GROUP}`)).toBe(true);
+    expect(isStorableChannelKey("../../../../etc/passwd:x")).toBe(false);
+  });
+
+  it("round-trips a key through its filename stem", () => {
+    expect(fileStemToChannelKey(channelKeyToFileStem(`${BOT}:${KIT}`))).toBe(`${BOT}:${KIT}`);
+  });
+
+  // Task 2615's three-part business shape. Round-tripping it is what keeps its
+  // conversations readable at all; telling it apart is what keeps them out of
+  // the reachable list.
+  it("round-trips a business key and recognises it as one", () => {
+    const biz = `${BOT}:biz:${KIT}`;
+    expect(isStorableChannelKey(biz)).toBe(true);
+    expect(channelKeyToFileStem(biz)).toBe(`${BOT}_biz_${KIT}`);
+    expect(fileStemToChannelKey(`${BOT}_biz_${KIT}`)).toBe(biz);
+    expect(isBusinessChannelKey(biz)).toBe(true);
+    expect(isBusinessChannelKey(`${BOT}:${KIT}`)).toBe(false);
+  });
+
+  it("refuses to build a stem from an unstorable key", () => {
+    expect(() => channelKeyToFileStem("a/b:c")).toThrow(/refusing unstorable channelKey/);
+  });
+});
+
+describe("collectTelegramReach", () => {
+  it("reports one entry per registered bot", () => {
+    const out = collectTelegramReach({
+      storeDir,
+      bots: [
+        { id: BOT, role: "admin", adminUsers: [] },
+        { id: "7777777777", role: "public" },
+      ],
+    });
+    expect(out.bots.map((b) => b.botId)).toEqual([BOT, "7777777777"]);
+  });
+
+  it("returns an empty chat list for a bot with no inbound, not an error", () => {
+    const out = collectTelegramReach({ storeDir, bots: [{ id: BOT, role: "admin" }] });
+    expect(out.bots[0].chats).toEqual([]);
+    expect(out.storeRows).toBe(0);
+  });
+
+  it("lists a chat that has messaged, with the newest inbound name and time", () => {
+    writeConversation(`${BOT}:${KIT}`, [
+      inbound(),
+      inbound({
+        messageId: "m2",
+        dateSent: "2026-08-09T09:00:00.000Z",
+        senderName: "Kit S",
+      }),
+    ]);
+    const out = collectTelegramReach({ storeDir, bots: [{ id: BOT, role: "admin" }] });
+    expect(out.bots[0].chats).toEqual([
+      {
+        chatId: KIT,
+        senderId: KIT,
+        displayName: "Kit S",
+        lastInbound: "2026-08-09T09:00:00.000Z",
+        admin: false,
+        reachable: true,
+      },
+    ]);
+    expect(out.storeRows).toBe(2);
+  });
+
+  it("marks a chat that is also an adminUsers entry", () => {
+    writeConversation(`${BOT}:${KIT}`, [inbound()]);
+    const out = collectTelegramReach({
+      storeDir,
+      bots: [{ id: BOT, role: "admin", adminUsers: [Number(KIT)] }],
+    });
+    expect(out.bots[0].chats[0].admin).toBe(true);
+  });
+
+  it("lists an adminUsers entry that has never messaged as not reachable", () => {
+    const out = collectTelegramReach({
+      storeDir,
+      bots: [{ id: BOT, role: "admin", adminUsers: [Number(KIT)] }],
+    });
+    expect(out.bots[0].chats).toEqual([
+      {
+        chatId: null,
+        senderId: KIT,
+        displayName: null,
+        lastInbound: null,
+        admin: true,
+        reachable: false,
+      },
+    ]);
+  });
+
+  it("excludes a group: its chatId differs from its senderId", () => {
+    writeConversation(`${BOT}:${KIT}`, [inbound({ chatId: GROUP })]);
+    const out = collectTelegramReach({ storeDir, bots: [{ id: BOT, role: "admin" }] });
+    expect(out.bots[0].chats).toEqual([]);
+    expect(out.storeRows).toBe(1);
+  });
+
+  it("does not make a chat reachable on agent or operator rows alone", () => {
+    writeConversation(`${BOT}:${KIT}`, [
+      inbound({ origin: "agent" }),
+      inbound({ messageId: "m2", origin: "operator-manual" }),
+    ]);
+    const out = collectTelegramReach({ storeDir, bots: [{ id: BOT, role: "admin" }] });
+    expect(out.bots[0].chats).toEqual([]);
+    expect(out.storeRows).toBe(2);
+  });
+
+  it("never counts an update row as a message and never makes it a chat", () => {
+    writeConversation(`${BOT}:${KIT}`, [
+      { kind: "update", targetMessageId: "m1", body: "x", createdAt: "2026-08-09T07:47:00.000Z" },
+    ]);
+    const out = collectTelegramReach({ storeDir, bots: [{ id: BOT, role: "admin" }] });
+    expect(out.storeRows).toBe(0);
+    expect(out.bots[0].chats).toEqual([]);
+  });
+
+  it("counts rows belonging to an unregistered bot, so a mis-scoped bot list is visible", () => {
+    writeConversation(`9999999999:${KIT}`, [inbound({ channelKey: `9999999999:${KIT}` })]);
+    const out = collectTelegramReach({ storeDir, bots: [{ id: BOT, role: "admin" }] });
+    expect(out.bots[0].chats).toEqual([]);
+    expect(out.storeRows).toBe(1);
+  });
+
+  // A business chat is reached through the business-connection route and its
+  // 24-hour window, never by addressing a chat id, so reporting one here would
+  // be the same wrong answer as the refusal this tool exists to prevent, only in
+  // the opposite direction. Its rows are not counted either: they were never
+  // walked.
+  it("skips a business conversation entirely, rows included", () => {
+    writeConversation(`${BOT}:biz:${KIT}`, [inbound({ channelKey: `${BOT}:biz:${KIT}` })]);
+    const out = collectTelegramReach({ storeDir, bots: [{ id: BOT, role: "admin" }] });
+    expect(out.bots[0].chats).toEqual([]);
+    expect(out.storeRows).toBe(0);
+  });
+
+  it("reads an absent store directory as no rows rather than throwing", () => {
+    const out = collectTelegramReach({
+      storeDir: join(storeDir, "nope"),
+      bots: [{ id: BOT, role: "admin" }],
+    });
+    expect(out.storeRows).toBe(0);
+    expect(out.bots[0].chats).toEqual([]);
+  });
+
+  it("orders reachable chats newest first, then the never-messaged admins", () => {
+    writeConversation(`${BOT}:${KIT}`, [inbound()]);
+    writeConversation(`${BOT}:${NEO}`, [
+      inbound({
+        senderId: NEO,
+        chatId: NEO,
+        channelKey: `${BOT}:${NEO}`,
+        senderName: "Neo",
+        dateSent: "2026-08-09T08:08:12.000Z",
+      }),
+    ]);
+    const out = collectTelegramReach({
+      storeDir,
+      bots: [{ id: BOT, role: "admin", adminUsers: [Number(KIT), 5555555555] }],
+    });
+    expect(out.bots[0].chats.map((c) => c.senderId)).toEqual([NEO, KIT, "5555555555"]);
+  });
+});