@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/telegram/mcp/dist/index.js

@@ -0,0 +1,198 @@
+import { initStderrTee } from "../../../../lib/mcp-stderr-tee/dist/index.js";
+initStderrTee("telegram");
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { eagerTool } from "../../../../lib/mcp-eager/dist/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { message } from "./tools/message.js";
+import { messageHistory } from "./tools/message-history.js";
+import { setWebhook, getWebhookInfo } from "./lib/telegram.js";
+const server = new McpServer({
+    name: "maxy-messaging",
+    version: "0.1.0",
+});
+eagerTool(server, "message", "Send a message via Telegram. Supports text with HTML formatting and inline keyboards for interactive choices.", {
+    channel: z.literal("telegram").describe("Delivery channel"),
+    chatId: z
+        .union([z.string(), z.number()])
+        .describe("Telegram chat ID to send to"),
+    text: z.string().describe("Message text (HTML formatting supported)"),
+    parseMode: z
+        .enum(["HTML", "Markdown", "MarkdownV2"])
+        .optional()
+        .describe("Parse mode (default: HTML)"),
+    inlineKeyboard: z
+        .array(z.array(z.object({
+        text: z.string().describe("Button label"),
+        callbackData: z
+            .string()
+            .optional()
+            .describe("Callback data for button press"),
+        url: z.string().optional().describe("URL to open on button press"),
+    })))
+        .optional()
+        .describe("Inline keyboard rows for interactive buttons"),
+}, async (params) => {
+    try {
+        const result = await message(params);
+        if (!result.sent) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Message failed: ${result.error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Message sent via ${result.channel} (ID: ${result.messageId})`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Send failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+eagerTool(server, "message-history", "Query conversation history from the message log.", {
+    channel: z.string().optional().describe("Filter by channel (telegram)"),
+    chatId: z.string().optional().describe("Filter by chat ID"),
+    limit: z.number().optional().describe("Max messages to return (default 20)"),
+}, async ({ channel, chatId, limit }) => {
+    try {
+        const history = await messageHistory({ channel, chatId, limit });
+        if (history.length === 0) {
+            return {
+                content: [
+                    { type: "text", text: "No message history found." },
+                ],
+            };
+        }
+        const formatted = history
+            .map((h) => `[${h.timestamp}] ${h.channel}/${h.chatId} (${h.role}): ${h.content.slice(0, 200)}${h.content.length > 200 ? "..." : ""}`)
+            .join("\n");
+        return {
+            content: [{ type: "text", text: formatted }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `History query failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+import { homedir } from "node:os";
+import { resolve, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+// Derive the webhook secret file path (mirrors paths.ts logic).
+// Restricted to known filenames — prevents path traversal.
+function resolveSecretFilePath(botType) {
+    let configDirName = ".maxy";
+    const platformRoot = process.env.PLATFORM_ROOT;
+    if (platformRoot) {
+        const brandPath = join(platformRoot, "config", "brand.json");
+        if (existsSync(brandPath)) {
+            try {
+                const brand = JSON.parse(readFileSync(brandPath, "utf-8"));
+                if (brand.configDir)
+                    configDirName = brand.configDir;
+            }
+            catch { /* fall back to .maxy */ }
+        }
+    }
+    const maxyDir = resolve(homedir(), configDirName);
+    const filename = botType === "admin"
+        ? ".telegram-admin-webhook-secret"
+        : ".telegram-webhook-secret";
+    return resolve(maxyDir, filename);
+}
+eagerTool(server, "telegram-webhook-register", "Register or re-register a Telegram bot webhook. Generates a cryptographic secret, persists it to disk, and passes it to the Telegram Bot API. Call this after obtaining a bot token from BotFather.", {
+    botToken: z.string().describe("Telegram bot token from BotFather"),
+    webhookUrl: z.string().url().describe("Full webhook URL including ?bot=public or ?bot=admin query param"),
+    botType: z.enum(["public", "admin"]).describe("Bot type — determines which secret file to write"),
+}, async ({ botToken, webhookUrl, botType }) => {
+    const secretFilePath = resolveSecretFilePath(botType);
+    try {
+        // Verify the token is valid by calling getMe
+        const meRes = await fetch(`https://api.telegram.org/bot${botToken}/getMe`);
+        const meData = (await meRes.json());
+        if (!meData.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid bot token: ${meData.description ?? "getMe failed"}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const botUsername = meData.result?.username ?? "unknown";
+        // Register webhook with secret generation
+        const result = await setWebhook(botToken, webhookUrl, secretFilePath);
+        if (!result.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Webhook registration failed: ${result.error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Verify registration — guarded because getWebhookInfo can fail
+        // independently of a successful registration (e.g., transient API error).
+        let verifyInfo = "";
+        try {
+            const info = await getWebhookInfo(botToken);
+            verifyInfo = `\nURL: ${info.url}\nPending updates: ${info.pendingUpdateCount}`;
+        }
+        catch {
+            verifyInfo = "\n(Could not verify — getWebhookInfo failed, but registration succeeded)";
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Webhook registered for @${botUsername}` +
+                        `\nSecret: generated and saved to ${secretFilePath}` +
+                        verifyInfo,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Webhook registration error: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/payload/platform/plugins/telegram/mcp/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/plugins/telegram/mcp/dist/lib/telegram.d.ts

@@ -0,0 +1,41 @@
+export interface TelegramSendOptions {
+    chatId: string | number;
+    text: string;
+    parseMode?: "HTML" | "Markdown" | "MarkdownV2";
+    replyMarkup?: TelegramInlineKeyboard;
+}
+export interface TelegramInlineKeyboard {
+    inline_keyboard: Array<Array<{
+        text: string;
+        callback_data?: string;
+        url?: string;
+    }>>;
+}
+export declare function sendMessage(botToken: string, options: TelegramSendOptions): Promise<{
+    ok: boolean;
+    messageId?: number;
+    error?: string;
+}>;
+/**
+ * Register a webhook URL with Telegram and generate a cryptographic secret.
+ *
+ * The secret is:
+ *   1. Generated via crypto.randomBytes (64 hex chars)
+ *   2. Passed to the Telegram Bot API as secret_token
+ *   3. Written to secretFilePath on disk ONLY after the API confirms success
+ *
+ * Telegram sends this secret in the X-Telegram-Bot-Api-Secret-Token header
+ * on every webhook delivery. The webhook route validates it before processing.
+ *
+ * If secretFilePath is omitted, no secret is generated (backward compat for tests).
+ */
+export declare function setWebhook(botToken: string, webhookUrl: string, secretFilePath?: string): Promise<{
+    ok: boolean;
+    secret?: string;
+    error?: string;
+}>;
+export declare function getWebhookInfo(botToken: string): Promise<{
+    url: string;
+    pendingUpdateCount: number;
+}>;
+//# sourceMappingURL=telegram.d.ts.map

package/payload/platform/plugins/telegram/mcp/dist/lib/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/lib/telegram.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,YAAY,CAAC;IAC/C,WAAW,CAAC,EAAE,sBAAsB,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,eAAe,EAAE,KAAK,CACpB,KAAK,CAAC;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC,CACH,CAAC;CACH;AAED,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAyB9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAmC3D;AAED,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,CAAC,CAWtD"}

package/payload/platform/plugins/telegram/mcp/dist/lib/telegram.js

@@ -0,0 +1,70 @@
+import { randomBytes } from "node:crypto";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+const TELEGRAM_API = "https://api.telegram.org";
+export async function sendMessage(botToken, options) {
+    const res = await fetch(`${TELEGRAM_API}/bot${botToken}/sendMessage`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            chat_id: options.chatId,
+            text: options.text,
+            parse_mode: options.parseMode ?? "HTML",
+            reply_markup: options.replyMarkup
+                ? JSON.stringify(options.replyMarkup)
+                : undefined,
+        }),
+    });
+    const data = (await res.json());
+    if (!data.ok) {
+        return { ok: false, error: data.description ?? "Unknown Telegram error" };
+    }
+    return { ok: true, messageId: data.result?.message_id };
+}
+/**
+ * Register a webhook URL with Telegram and generate a cryptographic secret.
+ *
+ * The secret is:
+ *   1. Generated via crypto.randomBytes (64 hex chars)
+ *   2. Passed to the Telegram Bot API as secret_token
+ *   3. Written to secretFilePath on disk ONLY after the API confirms success
+ *
+ * Telegram sends this secret in the X-Telegram-Bot-Api-Secret-Token header
+ * on every webhook delivery. The webhook route validates it before processing.
+ *
+ * If secretFilePath is omitted, no secret is generated (backward compat for tests).
+ */
+export async function setWebhook(botToken, webhookUrl, secretFilePath) {
+    const secret = secretFilePath ? randomBytes(32).toString("hex") : undefined;
+    const body = { url: webhookUrl };
+    if (secret) {
+        body.secret_token = secret;
+    }
+    const res = await fetch(`${TELEGRAM_API}/bot${botToken}/setWebhook`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const data = (await res.json());
+    if (!data.ok) {
+        return { ok: false, error: data.description ?? "Failed to set webhook" };
+    }
+    // Write secret to disk only after Telegram confirms the webhook registration.
+    // This prevents orphaned secret files when the API call fails, and avoids
+    // overwriting a working secret during a failed re-registration attempt.
+    if (secret && secretFilePath) {
+        mkdirSync(dirname(secretFilePath), { recursive: true });
+        writeFileSync(secretFilePath, secret, { mode: 0o600 });
+        console.error(`[telegram] webhook secret written to ${secretFilePath} (${secret.length} chars)`);
+    }
+    return { ok: true, secret };
+}
+export async function getWebhookInfo(botToken) {
+    const res = await fetch(`${TELEGRAM_API}/bot${botToken}/getWebhookInfo`);
+    const data = (await res.json());
+    return {
+        url: data.result.url,
+        pendingUpdateCount: data.result.pending_update_count,
+    };
+}
+//# sourceMappingURL=telegram.js.map

package/payload/platform/plugins/telegram/mcp/dist/lib/telegram.js.map

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

package/payload/platform/plugins/telegram/mcp/dist/tools/message-history.d.ts

@@ -0,0 +1,16 @@
+interface HistoryParams {
+    channel?: string;
+    chatId?: string;
+    accountId?: string;
+    limit?: number;
+}
+interface HistoryEntry {
+    channel: string;
+    chatId: string;
+    role: string;
+    content: string;
+    timestamp: string;
+}
+export declare function messageHistory(params: HistoryParams): Promise<HistoryEntry[]>;
+export {};
+//# sourceMappingURL=message-history.d.ts.map

package/payload/platform/plugins/telegram/mcp/dist/tools/message-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-history.d.ts","sourceRoot":"","sources":["../../src/tools/message-history.ts"],"names":[],"mappings":"AAyCA,UAAU,aAAa;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,YAAY,EAAE,CAAC,CAyCzB"}

package/payload/platform/plugins/telegram/mcp/dist/tools/message-history.js

@@ -0,0 +1,68 @@
+import neo4j from "neo4j-driver";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+let driver = null;
+function readPassword() {
+    if (process.env.NEO4J_PASSWORD)
+        return process.env.NEO4J_PASSWORD;
+    const passwordFile = resolve(process.env.PLATFORM_ROOT ?? resolve(import.meta.dirname, "../../../.."), "config/.neo4j-password");
+    try {
+        return readFileSync(passwordFile, "utf-8").trim();
+    }
+    catch {
+        throw new Error(`Neo4j password not found. Expected at ${passwordFile} or in NEO4J_PASSWORD env var.`);
+    }
+}
+function getSession() {
+    if (!driver) {
+        // Task 580: NEO4J_URI must be explicit. Silent default to :7687 was the
+        // vector for Task 577's orphan data in Maxy's DB from a realagent install.
+        const uri = process.env.NEO4J_URI;
+        if (!uri) {
+            throw new Error("[telegram/message-history] NEO4J_URI unset — refusing to default to bolt://localhost:7687");
+        }
+        const user = process.env.NEO4J_USER ?? "neo4j";
+        const password = readPassword();
+        console.error(`[telegram/message-history] resolved neo4j_uri=${uri}`);
+        driver = neo4j.driver(uri, neo4j.auth.basic(user, password));
+    }
+    return driver.session();
+}
+export async function messageHistory(params) {
+    const { channel, chatId, accountId, limit = 20 } = params;
+    const session = getSession();
+    try {
+        const conditions = ["m.accountId = $accountId"];
+        const queryParams = { accountId, limit };
+        if (channel) {
+            conditions.push("m.channel = $channel");
+            queryParams.channel = channel;
+        }
+        if (chatId) {
+            conditions.push("m.chatId = $chatId");
+            queryParams.chatId = chatId;
+        }
+        const query = `
+      MATCH (m:Communication)
+      WHERE ${conditions.join(" AND ")}
+      RETURN m
+      ORDER BY m.dateSent DESC
+      LIMIT $limit
+    `;
+        const result = await session.run(query, queryParams);
+        return result.records.map((record) => {
+            const m = record.get("m").properties;
+            return {
+                channel: m.channel,
+                chatId: m.chatId,
+                role: m.role,
+                content: m.content,
+                timestamp: m.dateSent,
+            };
+        });
+    }
+    finally {
+        await session.close();
+    }
+}
+//# sourceMappingURL=message-history.js.map

package/payload/platform/plugins/telegram/mcp/dist/tools/message-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-history.js","sourceRoot":"","sources":["../../src/tools/message-history.ts"],"names":[],"mappings":"AAAA,OAAO,KAAoC,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC,SAAS,YAAY;IACnB,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAElE,MAAM,YAAY,GAAG,OAAO,CAC1B,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,EACxE,wBAAwB,CACzB,CAAC;IAEF,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,yCAAyC,YAAY,gCAAgC,CACtF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,UAAU;IACjB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,wEAAwE;QACxE,2EAA2E;QAC3E,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC;QAC/C,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,iDAAiD,GAAG,EAAE,CAAC,CAAC;QACtE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC;AAC1B,CAAC;AAiBD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAqB;IAErB,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,GAAG,EAAE,EAAE,GAAG,MAAM,CAAC;IAE1D,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAE7B,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,CAAC,0BAA0B,CAAC,CAAC;QAChD,MAAM,WAAW,GAA4B,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAElE,IAAI,OAAO,EAAE,CAAC;YACZ,UAAU,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;YACxC,WAAW,CAAC,OAAO,GAAG,OAAO,CAAC;QAChC,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACX,UAAU,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YACtC,WAAW,CAAC,MAAM,GAAG,MAAM,CAAC;QAC9B,CAAC;QAED,MAAM,KAAK,GAAG;;cAEJ,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;;;;KAIjC,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAErD,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;YACnC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC;YACrC,OAAO;gBACL,OAAO,EAAE,CAAC,CAAC,OAAiB;gBAC5B,MAAM,EAAE,CAAC,CAAC,MAAgB;gBAC1B,IAAI,EAAE,CAAC,CAAC,IAAc;gBACtB,OAAO,EAAE,CAAC,CAAC,OAAiB;gBAC5B,SAAS,EAAE,CAAC,CAAC,QAAkB;aAChC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;AACH,CAAC"}

package/payload/platform/plugins/telegram/mcp/dist/tools/message.d.ts

@@ -0,0 +1,20 @@
+interface MessageParams {
+    channel: "telegram";
+    chatId: string | number;
+    text: string;
+    parseMode?: "HTML" | "Markdown" | "MarkdownV2";
+    inlineKeyboard?: Array<Array<{
+        text: string;
+        callbackData?: string;
+        url?: string;
+    }>>;
+}
+interface MessageResult {
+    sent: boolean;
+    channel: string;
+    messageId?: number;
+    error?: string;
+}
+export declare function message(params: MessageParams): Promise<MessageResult>;
+export {};
+//# sourceMappingURL=message.d.ts.map

package/payload/platform/plugins/telegram/mcp/dist/tools/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/tools/message.ts"],"names":[],"mappings":"AAEA,UAAU,aAAa;IACrB,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,YAAY,CAAC;IAC/C,cAAc,CAAC,EAAE,KAAK,CACpB,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAC7D,CAAC;CACH;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAoC3E"}

package/payload/platform/plugins/telegram/mcp/dist/tools/message.js

@@ -0,0 +1,34 @@
+import { sendMessage } from "../lib/telegram.js";
+export async function message(params) {
+    const botToken = process.env.TELEGRAM_BOT_TOKEN;
+    if (!botToken) {
+        return {
+            sent: false,
+            channel: params.channel,
+            error: "TELEGRAM_BOT_TOKEN not configured — no bot token passed to this MCP server",
+        };
+    }
+    let replyMarkup;
+    if (params.inlineKeyboard) {
+        replyMarkup = {
+            inline_keyboard: params.inlineKeyboard.map((row) => row.map((btn) => ({
+                text: btn.text,
+                callback_data: btn.callbackData,
+                url: btn.url,
+            }))),
+        };
+    }
+    const result = await sendMessage(botToken, {
+        chatId: params.chatId,
+        text: params.text,
+        parseMode: params.parseMode,
+        replyMarkup,
+    });
+    return {
+        sent: result.ok,
+        channel: "telegram",
+        messageId: result.messageId,
+        error: result.error,
+    };
+}
+//# sourceMappingURL=message.js.map

package/payload/platform/plugins/telegram/mcp/dist/tools/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../src/tools/message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA+B,MAAM,oBAAoB,CAAC;AAmB9E,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAqB;IACjD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAChD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,KAAK,EAAE,4EAA4E;SACpF,CAAC;IACJ,CAAC;IAED,IAAI,WAA+C,CAAC;IACpD,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QAC1B,WAAW,GAAG;YACZ,eAAe,EAAE,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACjD,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBAChB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,aAAa,EAAE,GAAG,CAAC,YAAY;gBAC/B,GAAG,EAAE,GAAG,CAAC,GAAG;aACb,CAAC,CAAC,CACJ;SACF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE;QACzC,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW;KACZ,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,EAAE;QACf,OAAO,EAAE,UAAU;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC;AACJ,CAAC"}

package/payload/platform/plugins/telegram/mcp/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@maxy/messaging",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "neo4j-driver": "^5.28.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/payload/platform/plugins/telegram/references/setup-guide.md

@@ -0,0 +1,50 @@
+# Telegram Setup Guide
+
+## Creating a Bot
+
+1. Open Telegram and search for **@BotFather**
+2. Start a chat and send `/newbot`
+3. Follow the prompts — choose a display name and a username (must end in `bot`)
+4. BotFather replies with a **bot token** (a long string like `123456:ABC-DEF...`)
+5. Copy the token — you'll paste it into the admin chat
+
+## Connecting the Bot
+
+1. Tell the admin agent you want to connect a Telegram bot
+2. Find the **Telegram** row and click **Connect** (or open settings if already connected)
+3. Paste the bot token from BotFather
+4. The system probes the token to verify it — you'll see the bot's username confirmed
+5. Choose whether this is an **admin bot** or a **public bot** (see below)
+6. If it's a public bot, choose a DM policy (who can message it)
+7. Click **Save & Connect**
+
+## Admin Bot vs Public Bot
+
+Each Telegram bot has an **Admin routing** toggle:
+
+- **Admin bot** (toggle ON): Only users with admin bindings can message this bot. Everyone else is silently denied. Messages route to the admin agent. No DM policy applies — it's admin-only by design.
+- **Public bot** (toggle OFF): DM policy applies to everyone equally, including admins. Messages route to the public agent. Use this for customer-facing bots.
+
+A common setup is two bots: one admin bot for the business owner, one public bot for customers.
+
+## Finding Your Telegram User ID
+
+Admin bindings require your **numeric Telegram user ID** — not your username. Usernames can be changed or claimed by someone else, so they are not safe for admin access.
+
+To find your user ID:
+
+1. Open Telegram and search for **@userinfobot**
+2. Start the chat and send `/start`
+3. The bot instantly replies with your numeric ID (e.g. `123456789`), plus your name and language
+4. Use this numeric ID when setting up admin bindings
+
+## DM Policy Options (Public Bots Only)
+
+| Policy | Behaviour |
+|--------|-----------|
+| **Respond to everyone** | Any Telegram user can message the bot and get a response |
+| **Require approval** | Unknown senders receive a pairing code; an admin must approve them |
+| **Whitelist only** | Only users in the allowlist can message the bot |
+| **Disabled** | The bot ignores all DMs |
+
+"Require approval" (pairing) is the default and recommended for most setups — it lets you control who talks to the bot without pre-configuring an allowlist.

package/payload/platform/plugins/waitlist/PLUGIN.md

@@ -0,0 +1,63 @@
+---
+name: waitlist
+description: "Waitlist lifecycle — workflow-based extraction from public conversations, admin review, and scheduled automation."
+tools:
+  - waitlist-scan
+  - waitlist-persist
+  - waitlist-list
+  - waitlist-review
+  - waitlist-setup
+  - waitlist-heal
+always: false
+embed: false
+lifecycle: {"activate": "waitlist-setup", "heal": "waitlist-heal"}
+metadata: {"platform":{"optional":true}}
+---
+
+# Waitlist
+
+Manages the waitlist lifecycle: extracting sign-ups from public conversations, reviewing entries, and scheduling automatic extraction.
+
+## How it works
+
+The **only** intake path is public agent conversations. The public agent captures name and email in conversation (via the sales plugin). This plugin uses a **workflow** (3-step pipeline) to scan those conversation transcripts, extract structured contact details and customer discovery intelligence via LLM, and create Person nodes in the graph. There are no other sources: no email inboxes, no web forms, no external imports. Do not suggest or speculate about alternative sign-up sources.
+
+### Extraction workflow
+
+The extraction runs as a standard workflow (managed by the workflows plugin):
+
+1. **Scan** (`waitlist-scan`) — queries all public conversations and returns structured transcripts
+2. **LLM extraction** — sends transcripts to the model, which extracts identity (email, given name, family name) and discovery notes (business type, role, needs, challenges, interests, engagement quality, other signals). The extraction prompt is stored in the workflow and is visible via `workflow-get` and editable via `workflow-update`.
+3. **Persist** (`waitlist-persist`) — creates/updates Person nodes idempotently via MERGE. Validates that extracted emails actually appear in source conversations (hallucination guard). Merges discovery notes with existing data (new signal enriches, never overwrites).
+
+- Entries where both name and email are found get `status: 'waitlist'`.
+- Entries where only an email is found (no name match) get `status: 'review'` — the admin resolves these manually.
+- Discovery notes are stored as a JSON string on the Person node's `discoveryNotes` property.
+
+### Modifying the extraction
+
+The extraction prompt is stored in the workflow's LLM step. The user can:
+- **View it:** `workflow-get "Waitlist lead extraction"` shows all steps including the prompt
+- **Edit it:** `workflow-update` to change what fields are extracted, adjust instructions, or modify behaviour
+- **Change the model:** update the LLM step's model field (defaults to the account's adminModel)
+
+No code changes needed to modify extraction behaviour.
+
+## When to use each tool
+
+- `waitlist-scan` — Gather public conversation transcripts. Normally called by the extraction workflow, not directly. Returns structured JSON.
+- `waitlist-persist` — Persist LLM extraction results as Person nodes. Normally called by the extraction workflow, not directly. Validates input and applies hallucination guard.
+- `waitlist-list` — Show the admin their waitlist entries with discovery notes. Highlight the review count — entries needing name resolution.
+- `waitlist-review` — Resolve flagged entries and view discovery context: add a name and change status from `review` to `waitlist` or `approved`. Also use to reject spam entries. Returns discovery notes alongside the status update.
+- `waitlist-setup` — Create the extraction workflow and a recurring scheduled event that triggers it. Default: every 4 hours. Idempotent — if the workflow already exists, returns its details. Cleans up old-style extraction events automatically. To change the schedule, cancel the existing event (via `schedule-cancel`) and run `waitlist-setup` with the new recurrence.
+
+## First-time setup
+
+When the admin first asks about waitlist management or wants to see sign-ups, run `waitlist-setup` to create the extraction workflow and schedule. Then run `workflow-execute` on the created workflow to populate entries from existing conversations, followed by `waitlist-list` to show results.
+
+## Relationship to other plugins
+
+- **Sales plugin** — handles the public-facing conversation that captures name and email. The sales plugin collects; the waitlist plugin extracts and manages.
+- **Contacts plugin** — waitlist entries are Person nodes (same schema). `contact-list` with `source: 'waitlist'` shows the same data. The waitlist tools add extraction and review workflows on top.
+- **Workflows plugin** — the extraction runs as a standard workflow. The user manages the extraction prompt and execution through workflow tools.
+- **Scheduling plugin** — `waitlist-setup` creates an Event node that triggers `workflow-execute` via the platform heartbeat. The admin can view and manage this event via scheduling tools.

package/payload/platform/plugins/waitlist/mcp/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/plugins/waitlist/mcp/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}