@odience-network/paperclip-plugin-telegram-enhanced 0.2.0

package/dist/constants.js

@@ -0,0 +1,71 @@
+export const PLUGIN_ID = "paperclip-plugin-telegram-enhanced";
+export const PLUGIN_VERSION = "0.2.0";
+export const MAX_AGENTS_PER_THREAD = 5;
+export const DEFAULT_CONFIG = {
+    telegramBotTokenRef: "",
+    defaultChatId: "",
+    approvalsChatId: "",
+    approvalsTopicId: "",
+    errorsChatId: "",
+    errorsTopicId: "",
+    digestChatId: "",
+    digestTopicId: "",
+    paperclipBaseUrl: "http://localhost:3100",
+    paperclipBoardApiTokenRef: "",
+    paperclipPublicUrl: "",
+    notifyOnIssueCreated: true,
+    notifyOnIssueDone: true,
+    notifyOnIssueAssigned: false,
+    onlyNotifyIfAssignedTo: "",
+    notifyOnApprovalCreated: true,
+    onlyNotifyBoardApprovals: false,
+    notifyOnAgentError: true,
+    notifyOnAgentRunStarted: false,
+    notifyOnAgentRunFinished: false,
+    enableCommands: true,
+    enableInbound: true,
+    allowedTelegramUserIds: [],
+    allowedTelegramChatIds: [],
+    // Project-key file routing (ant013 TEL-23): route outbound markdown documents
+    // to a Telegram chat/topic by Paperclip project key.
+    fileRoutes: [],
+    // TEL-23 (ant013): route run-lifecycle / "ops" chatter to dedicated ops chats
+    // per company, keeping the primary chat reserved for important signals.
+    opsRoutes: [],
+    digestMode: "off",
+    dailyDigestTime: "09:00",
+    bidailySecondTime: "17:00",
+    tridailyTimes: "07:00,13:00,19:00",
+    topicRouting: false,
+    maxAgentsPerThread: MAX_AGENTS_PER_THREAD,
+    escalationChatId: "",
+    escalationTimeoutMs: 900000,
+    escalationDefaultAction: "defer",
+    escalationHoldMessage: "Let me check on that - I'll get back to you shortly.",
+    // Phase 3: Media Pipeline
+    briefAgentId: "",
+    briefAgentChatIds: [],
+    transcriptionApiKeyRef: "",
+    // Phase 5: Proactive Suggestions
+    maxSuggestionsPerHourPerCompany: 10,
+    watchDeduplicationWindowMs: 86400000, // 24h
+};
+export const AGENT_ERROR_DEDUPLICATION_WINDOW_MS = 30 * 60 * 1000;
+export const MAX_CONVERSATION_TURNS = 50;
+export const DEFAULT_CONVERSATION_TURNS = 10;
+export const METRIC_NAMES = {
+    sent: "telegram_notifications_sent",
+    failed: "telegram_notification_failures",
+    commandsHandled: "telegram_commands_handled",
+    inboundRouted: "telegram_inbound_routed",
+    escalationsCreated: "telegram_escalations_created",
+    escalationsResolved: "telegram_escalations_resolved",
+    escalationsTimedOut: "telegram_escalations_timed_out",
+    mediaProcessed: "telegram_media_processed",
+    commandsExecuted: "telegram_custom_commands_executed",
+    suggestionsEmitted: "telegram_suggestions_emitted",
+};
+// Cross-plugin ACP event names
+export const ACP_SPAWN_EVENT = "acp-spawn";
+export const ACP_OUTPUT_EVENT = "plugin.paperclip-plugin-acp.output";
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG,oCAAoC,CAAC;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AACtC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,mBAAmB,EAAE,EAAE;IACvB,aAAa,EAAE,EAAE;IACjB,eAAe,EAAE,EAAE;IACnB,gBAAgB,EAAE,EAAE;IACpB,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE,EAAE;IACjB,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE,EAAE;IACjB,gBAAgB,EAAE,uBAAuB;IACzC,yBAAyB,EAAE,EAAE;IAC7B,kBAAkB,EAAE,EAAE;IACtB,oBAAoB,EAAE,IAAI;IAC1B,iBAAiB,EAAE,IAAI;IACvB,qBAAqB,EAAE,KAAK;IAC5B,sBAAsB,EAAE,EAAE;IAC1B,uBAAuB,EAAE,IAAI;IAC7B,wBAAwB,EAAE,KAAK;IAC/B,kBAAkB,EAAE,IAAI;IACxB,uBAAuB,EAAE,KAAK;IAC9B,wBAAwB,EAAE,KAAK;IAC/B,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;IACnB,sBAAsB,EAAE,EAAc;IACtC,sBAAsB,EAAE,EAAc;IACtC,8EAA8E;IAC9E,qDAAqD;IACrD,UAAU,EAAE,EAMV;IACF,8EAA8E;IAC9E,wEAAwE;IACxE,SAAS,EAAE,EAOT;IACF,UAAU,EAAE,KAAiD;IAC7D,eAAe,EAAE,OAAO;IACxB,iBAAiB,EAAE,OAAO;IAC1B,aAAa,EAAE,mBAAmB;IAClC,YAAY,EAAE,KAAK;IACnB,kBAAkB,EAAE,qBAAqB;IACzC,gBAAgB,EAAE,EAAE;IACpB,mBAAmB,EAAE,MAAM;IAC3B,uBAAuB,EAAE,OAAO;IAChC,qBAAqB,EAAE,sDAAsD;IAC7E,0BAA0B;IAC1B,YAAY,EAAE,EAAE;IAChB,iBAAiB,EAAE,EAAc;IACjC,sBAAsB,EAAE,EAAE;IAC1B,iCAAiC;IACjC,+BAA+B,EAAE,EAAE;IACnC,0BAA0B,EAAE,QAAQ,EAAE,MAAM;CACpC,CAAC;AAEX,MAAM,CAAC,MAAM,mCAAmC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAElE,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAE7C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,6BAA6B;IACnC,MAAM,EAAE,gCAAgC;IACxC,eAAe,EAAE,2BAA2B;IAC5C,aAAa,EAAE,yBAAyB;IACxC,kBAAkB,EAAE,8BAA8B;IAClD,mBAAmB,EAAE,+BAA+B;IACpD,mBAAmB,EAAE,gCAAgC;IACrD,cAAc,EAAE,0BAA0B;IAC1C,gBAAgB,EAAE,mCAAmC;IACrD,kBAAkB,EAAE,8BAA8B;CAC1C,CAAC;AAEX,+BAA+B;AAC/B,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAC3C,MAAM,CAAC,MAAM,gBAAgB,GAAG,oCAAoC,CAAC"}

package/dist/escalation.d.ts

@@ -0,0 +1,42 @@
+import type { PluginContext } from "@paperclipai/plugin-sdk";
+export type EscalationReason = "low_confidence" | "explicit_request" | "policy_violation" | "unknown_intent";
+export type EscalationEvent = {
+    escalationId: string;
+    agentId: string;
+    agentName?: string;
+    companyId: string;
+    reason: EscalationReason;
+    context: {
+        conversationHistory: Array<{
+            role: string;
+            text: string;
+        }>;
+        agentReasoning: string;
+        suggestedActions: string[];
+        suggestedReply?: string;
+        confidenceScore?: number;
+    };
+    timeout: {
+        durationMs: number;
+        defaultAction: "defer" | "auto_reply" | "close";
+    };
+    originChatId?: string;
+    originThreadId?: string;
+    originMessageId?: string;
+    transport?: "native" | "acp";
+    sessionId?: string;
+};
+export type EscalationResponse = {
+    escalationId: string;
+    responderId: string;
+    responseText: string;
+    action: "reply_to_customer" | "override_suggested" | "dismiss";
+};
+export declare class EscalationManager {
+    create(ctx: PluginContext, token: string, event: EscalationEvent, escalationChatId: string): Promise<void>;
+    handleCallback(ctx: PluginContext, token: string, action: string, escalationId: string, actor: string, callbackQueryId: string, chatId: string | null, messageId: number | undefined): Promise<void>;
+    respond(ctx: PluginContext, token: string, escalationId: string, response: EscalationResponse): Promise<void>;
+    private resolve;
+    checkTimeouts(ctx: PluginContext, token: string): Promise<void>;
+    private removePending;
+}

package/dist/escalation.js

@@ -0,0 +1,252 @@
+import { sendMessage, editMessage, escapeMarkdownV2, truncateAtWord } from "./telegram-api.js";
+import { wakeAgentWithIssue } from "./acp-bridge.js";
+import { displayNameFromFields, resolveAgentDisplayName } from "./agent-labels.js";
+const REASON_LABELS = {
+    low_confidence: "Low Confidence",
+    explicit_request: "User Requested Human",
+    policy_violation: "Policy Violation",
+    unknown_intent: "Unknown Intent",
+};
+function esc(s) {
+    return escapeMarkdownV2(s);
+}
+export class EscalationManager {
+    async create(ctx, token, event, escalationChatId) {
+        const reasonLabel = REASON_LABELS[event.reason] ?? event.reason;
+        const confidence = event.context.confidenceScore != null
+            ? ` \\(${esc(String(Math.round(event.context.confidenceScore * 100)))}%\\)`
+            : "";
+        const agentLabel = displayNameFromFields(event.agentName)
+            ?? await resolveAgentDisplayName(ctx, event.companyId, event.agentId)
+            ?? event.agentId;
+        const lines = [
+            `${esc("\u26a0\ufe0f")} *Escalation*`,
+            `${esc("Reason:")} ${esc(reasonLabel)}${confidence}`,
+            "",
+            `*Agent:* ${esc(agentLabel)}`,
+            `*Reasoning:* ${esc(event.context.agentReasoning ? truncateAtWord(event.context.agentReasoning, 500) : "No details provided")}`,
+        ];
+        if (event.context.suggestedActions.length > 0) {
+            lines.push("");
+            lines.push("*Suggested actions:*");
+            for (const action of event.context.suggestedActions.slice(0, 5)) {
+                lines.push(`  ${esc("-")} ${esc(action)}`);
+            }
+        }
+        if (event.context.suggestedReply) {
+            lines.push("");
+            lines.push("*Suggested reply:*");
+            lines.push(`${esc(">")} ${esc(truncateAtWord(event.context.suggestedReply, 300))}`);
+        }
+        lines.push("");
+        lines.push(`ID: \`${esc(event.escalationId)}\``);
+        const buttons = [];
+        if (event.context.suggestedReply) {
+            buttons.push([
+                { text: "Send Suggested Reply", callback_data: `esc_suggested_${event.escalationId}` },
+            ]);
+        }
+        buttons.push([
+            { text: "Reply", callback_data: `esc_reply_${event.escalationId}` },
+            { text: "Override", callback_data: `esc_override_${event.escalationId}` },
+            { text: "Dismiss", callback_data: `esc_dismiss_${event.escalationId}` },
+        ]);
+        const messageId = await sendMessage(ctx, token, escalationChatId, lines.join("\n"), {
+            parseMode: "MarkdownV2",
+            inlineKeyboard: buttons,
+        });
+        if (!messageId) {
+            ctx.logger.error("Failed to send escalation message", { escalationId: event.escalationId });
+            return;
+        }
+        const timeoutAt = new Date(Date.now() + event.timeout.durationMs).toISOString();
+        const stored = {
+            escalationId: event.escalationId,
+            agentId: event.agentId,
+            agentName: agentLabel,
+            companyId: event.companyId,
+            reason: event.reason,
+            agentReasoning: event.context.agentReasoning,
+            suggestedReply: event.context.suggestedReply,
+            suggestedActions: event.context.suggestedActions,
+            confidenceScore: event.context.confidenceScore,
+            originChatId: event.originChatId,
+            originThreadId: event.originThreadId,
+            originMessageId: event.originMessageId,
+            escalationChatId,
+            escalationMessageId: String(messageId),
+            status: "pending",
+            createdAt: new Date().toISOString(),
+            timeoutAt,
+            defaultAction: event.timeout.defaultAction,
+            transport: event.transport,
+            sessionId: event.sessionId,
+        };
+        await ctx.state.set({ scopeKind: "instance", stateKey: `escalation_${event.escalationId}` }, stored);
+        // Map the escalation message back so replies can be routed
+        await ctx.state.set({ scopeKind: "instance", stateKey: `msg_${escalationChatId}_${messageId}` }, {
+            entityId: event.escalationId,
+            entityType: "escalation",
+            companyId: event.companyId,
+            eventType: "escalation.created",
+        });
+        // Track pending escalation IDs for timeout checks
+        const pendingIds = await ctx.state.get({
+            scopeKind: "instance",
+            stateKey: "escalation_pending_ids",
+        }) ?? [];
+        pendingIds.push(event.escalationId);
+        await ctx.state.set({ scopeKind: "instance", stateKey: "escalation_pending_ids" }, pendingIds);
+        ctx.logger.info("Escalation created", {
+            escalationId: event.escalationId,
+            reason: event.reason,
+            timeoutAt,
+        });
+    }
+    async handleCallback(ctx, token, action, escalationId, actor, callbackQueryId, chatId, messageId) {
+        const stored = await ctx.state.get({
+            scopeKind: "instance",
+            stateKey: `escalation_${escalationId}`,
+        });
+        if (!stored || stored.status !== "pending") {
+            return;
+        }
+        switch (action) {
+            case "suggested": {
+                if (!stored.suggestedReply)
+                    break;
+                await this.resolve(ctx, token, stored, {
+                    escalationId,
+                    responderId: `telegram:${actor}`,
+                    responseText: stored.suggestedReply,
+                    action: "reply_to_customer",
+                });
+                break;
+            }
+            case "reply": {
+                if (chatId && messageId) {
+                    await editMessage(ctx, token, chatId, messageId, `${esc("\u26a0\ufe0f")} *Escalation* \\- *Awaiting your reply*\n\n${esc("Reply to this message with your response to the customer.")}`, { parseMode: "MarkdownV2" });
+                }
+                break;
+            }
+            case "dismiss": {
+                await this.resolve(ctx, token, stored, {
+                    escalationId,
+                    responderId: `telegram:${actor}`,
+                    responseText: "",
+                    action: "dismiss",
+                });
+                break;
+            }
+            case "override": {
+                if (chatId && messageId) {
+                    await editMessage(ctx, token, chatId, messageId, `${esc("\u26a0\ufe0f")} *Escalation* \\- *Override mode*\n\n${esc("Reply to this message with your custom response.")}`, { parseMode: "MarkdownV2" });
+                }
+                break;
+            }
+        }
+    }
+    async respond(ctx, token, escalationId, response) {
+        const stored = await ctx.state.get({
+            scopeKind: "instance",
+            stateKey: `escalation_${escalationId}`,
+        });
+        if (!stored || stored.status !== "pending") {
+            ctx.logger.warn("Escalation respond called for non-pending escalation", { escalationId });
+            return;
+        }
+        await this.resolve(ctx, token, stored, response);
+    }
+    async resolve(ctx, token, stored, response) {
+        stored.status = "resolved";
+        await ctx.state.set({ scopeKind: "instance", stateKey: `escalation_${stored.escalationId}` }, stored);
+        await this.removePending(ctx, stored.escalationId);
+        const statusLabel = response.action === "dismiss" ? "Dismissed" : "Resolved";
+        await editMessage(ctx, token, stored.escalationChatId, Number(stored.escalationMessageId), `${esc("\u2705")} *Escalation ${statusLabel}* by ${esc(response.responderId)}\n\nID: \`${esc(stored.escalationId)}\``, { parseMode: "MarkdownV2" });
+        // Route reply back via the correct transport
+        if (response.action === "reply_to_customer" && response.responseText) {
+            if (stored.transport === "native" && stored.agentId) {
+                await wakeAgentWithIssue(ctx, stored.agentId, stored.companyId, `[Human escalation response] ${response.responseText}`, "escalation_reply");
+            }
+            else if (stored.transport === "acp" && stored.sessionId) {
+                // Route back via ACP event
+                ctx.events.emit("acp-spawn", stored.companyId, {
+                    type: "message",
+                    sessionId: stored.sessionId,
+                    text: `[Human escalation response] ${response.responseText}`,
+                });
+            }
+            // Also send to the originating Telegram chat if available
+            if (stored.originChatId) {
+                await sendMessage(ctx, token, stored.originChatId, esc(response.responseText), {
+                    parseMode: "MarkdownV2",
+                    messageThreadId: stored.originThreadId ? Number(stored.originThreadId) : undefined,
+                    replyToMessageId: stored.originMessageId ? Number(stored.originMessageId) : undefined,
+                });
+            }
+        }
+        // Emit resolution event - companyId is SECOND arg
+        ctx.events.emit("escalation.resolved", stored.companyId, {
+            escalationId: stored.escalationId,
+            agentId: stored.agentId,
+            responderId: response.responderId,
+            responseText: response.responseText,
+            action: response.action,
+        });
+        ctx.logger.info("Escalation resolved", {
+            escalationId: stored.escalationId,
+            action: response.action,
+            responderId: response.responderId,
+        });
+    }
+    async checkTimeouts(ctx, token) {
+        const pendingIds = await ctx.state.get({
+            scopeKind: "instance",
+            stateKey: "escalation_pending_ids",
+        }) ?? [];
+        if (pendingIds.length === 0)
+            return;
+        const now = Date.now();
+        for (const escalationId of pendingIds) {
+            const stored = await ctx.state.get({
+                scopeKind: "instance",
+                stateKey: `escalation_${escalationId}`,
+            });
+            if (!stored || stored.status !== "pending") {
+                await this.removePending(ctx, escalationId);
+                continue;
+            }
+            const timeoutAt = new Date(stored.timeoutAt).getTime();
+            if (now < timeoutAt)
+                continue;
+            ctx.logger.info("Escalation timed out", { escalationId, defaultAction: stored.defaultAction });
+            stored.status = "timed_out";
+            await ctx.state.set({ scopeKind: "instance", stateKey: `escalation_${escalationId}` }, stored);
+            await this.removePending(ctx, escalationId);
+            await editMessage(ctx, token, stored.escalationChatId, Number(stored.escalationMessageId), `${esc("\u23f0")} *Escalation Timed Out*\n\nDefault action: ${esc(stored.defaultAction)}\nID: \`${esc(escalationId)}\``, { parseMode: "MarkdownV2" });
+            // Emit timeout event - companyId is SECOND arg
+            ctx.events.emit("escalation.timed_out", stored.companyId, {
+                escalationId,
+                agentId: stored.agentId,
+                defaultAction: stored.defaultAction,
+                suggestedReply: stored.suggestedReply,
+            });
+            if (stored.defaultAction === "auto_reply" && stored.suggestedReply && stored.originChatId) {
+                await sendMessage(ctx, token, stored.originChatId, esc(stored.suggestedReply), {
+                    parseMode: "MarkdownV2",
+                    messageThreadId: stored.originThreadId ? Number(stored.originThreadId) : undefined,
+                    replyToMessageId: stored.originMessageId ? Number(stored.originMessageId) : undefined,
+                });
+            }
+        }
+    }
+    async removePending(ctx, escalationId) {
+        const pendingIds = await ctx.state.get({
+            scopeKind: "instance",
+            stateKey: "escalation_pending_ids",
+        }) ?? [];
+        const updated = pendingIds.filter((id) => id !== escalationId);
+        await ctx.state.set({ scopeKind: "instance", stateKey: "escalation_pending_ids" }, updated);
+    }
+}
+//# sourceMappingURL=escalation.js.map

package/dist/escalation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.js","sourceRoot":"","sources":["../src/escalation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AA+DnF,MAAM,aAAa,GAAqC;IACtD,cAAc,EAAE,gBAAgB;IAChC,gBAAgB,EAAE,sBAAsB;IACxC,gBAAgB,EAAE,kBAAkB;IACpC,cAAc,EAAE,gBAAgB;CACjC,CAAC;AAEF,SAAS,GAAG,CAAC,CAAS;IACpB,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,OAAO,iBAAiB;IAC5B,KAAK,CAAC,MAAM,CACV,GAAkB,EAClB,KAAa,EACb,KAAsB,EACtB,gBAAwB;QAExB,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC;QAChE,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,eAAe,IAAI,IAAI;YACtD,CAAC,CAAC,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,eAAe,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM;YAC3E,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,SAAS,CAAC;eACpD,MAAM,uBAAuB,CAAC,GAAG,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;eAClE,KAAK,CAAC,OAAO,CAAC;QAEnB,MAAM,KAAK,GAAa;YACtB,GAAG,GAAG,CAAC,cAAc,CAAC,eAAe;YACrC,GAAG,GAAG,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,UAAU,EAAE;YACpD,EAAE;YACF,YAAY,GAAG,CAAC,UAAU,CAAC,EAAE;YAC7B,gBAAgB,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,EAAE;SAChI,CAAC;QAEF,IAAI,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;YACnC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;gBAChE,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;QACtF,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,EAAE,CAAC;QACnB,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,IAAI,EAAE,sBAAsB,EAAE,aAAa,EAAE,iBAAiB,KAAK,CAAC,YAAY,EAAE,EAAE;aACvF,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,KAAK,CAAC,YAAY,EAAE,EAAE;YACnE,EAAE,IAAI,EAAE,UAAU,EAAE,aAAa,EAAE,gBAAgB,KAAK,CAAC,YAAY,EAAE,EAAE;YACzE,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,KAAK,CAAC,YAAY,EAAE,EAAE;SACxE,CAAC,CAAC;QAEH,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YAClF,SAAS,EAAE,YAAY;YACvB,cAAc,EAAE,OAAO;SACxB,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,EAAE,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;YAC5F,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;QAEhF,MAAM,MAAM,GAAqB;YAC/B,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,SAAS,EAAE,UAAU;YACrB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,cAAc;YAC5C,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,cAAc;YAC5C,gBAAgB,EAAE,KAAK,CAAC,OAAO,CAAC,gBAAgB;YAChD,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,eAAe;YAC9C,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,eAAe,EAAE,KAAK,CAAC,eAAe;YACtC,gBAAgB;YAChB,mBAAmB,EAAE,MAAM,CAAC,SAAS,CAAC;YACtC,MAAM,EAAE,SAAS;YACjB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,SAAS;YACT,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,aAAa;YAC1C,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;SAC3B,CAAC;QAEF,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CACjB,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,KAAK,CAAC,YAAY,EAAE,EAAE,EACvE,MAAM,CACP,CAAC;QAEF,2DAA2D;QAC3D,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CACjB,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,gBAAgB,IAAI,SAAS,EAAE,EAAE,EAC3E;YACE,QAAQ,EAAE,KAAK,CAAC,YAAY;YAC5B,UAAU,EAAE,YAAY;YACxB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,SAAS,EAAE,oBAAoB;SAChC,CACF,CAAC;QAEF,kDAAkD;QAClD,MAAM,UAAU,GAAI,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;YACtC,SAAS,EAAE,UAAU;YACrB,QAAQ,EAAE,wBAAwB;SACnC,CAAqB,IAAI,EAAE,CAAC;QAC7B,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACpC,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CACjB,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,wBAAwB,EAAE,EAC7D,UAAU,CACX,CAAC;QAEF,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE;YACpC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,SAAS;SACV,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,GAAkB,EAClB,KAAa,EACb,MAAc,EACd,YAAoB,EACpB,KAAa,EACb,eAAuB,EACvB,MAAqB,EACrB,SAA6B;QAE7B,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;YACjC,SAAS,EAAE,UAAU;YACrB,QAAQ,EAAE,cAAc,YAAY,EAAE;SACvC,CAA4B,CAAC;QAE9B,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC3C,OAAO;QACT,CAAC;QAED,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,IAAI,CAAC,MAAM,CAAC,cAAc;oBAAE,MAAM;gBAClC,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE;oBACrC,YAAY;oBACZ,WAAW,EAAE,YAAY,KAAK,EAAE;oBAChC,YAAY,EAAE,MAAM,CAAC,cAAc;oBACnC,MAAM,EAAE,mBAAmB;iBAC5B,CAAC,CAAC;gBACH,MAAM;YACR,CAAC;YACD,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;oBACxB,MAAM,WAAW,CACf,GAAG,EACH,KAAK,EACL,MAAM,EACN,SAAS,EACT,GAAG,GAAG,CAAC,cAAc,CAAC,8CAA8C,GAAG,CAAC,2DAA2D,CAAC,EAAE,EACtI,EAAE,SAAS,EAAE,YAAY,EAAE,CAC5B,CAAC;gBACJ,CAAC;gBACD,MAAM;YACR,CAAC;YACD,KAAK,SAAS,CAAC,CAAC,CAAC;gBACf,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE;oBACrC,YAAY;oBACZ,WAAW,EAAE,YAAY,KAAK,EAAE;oBAChC,YAAY,EAAE,EAAE;oBAChB,MAAM,EAAE,SAAS;iBAClB,CAAC,CAAC;gBACH,MAAM;YACR,CAAC;YACD,KAAK,UAAU,CAAC,CAAC,CAAC;gBAChB,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;oBACxB,MAAM,WAAW,CACf,GAAG,EACH,KAAK,EACL,MAAM,EACN,SAAS,EACT,GAAG,GAAG,CAAC,cAAc,CAAC,wCAAwC,GAAG,CAAC,kDAAkD,CAAC,EAAE,EACvH,EAAE,SAAS,EAAE,YAAY,EAAE,CAC5B,CAAC;gBACJ,CAAC;gBACD,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO,CACX,GAAkB,EAClB,KAAa,EACb,YAAoB,EACpB,QAA4B;QAE5B,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;YACjC,SAAS,EAAE,UAAU;YACrB,QAAQ,EAAE,cAAc,YAAY,EAAE;SACvC,CAA4B,CAAC;QAE9B,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC3C,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,sDAAsD,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;YAC1F,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IAEO,KAAK,CAAC,OAAO,CACnB,GAAkB,EAClB,KAAa,EACb,MAAwB,EACxB,QAA4B;QAE5B,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC;QAC3B,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CACjB,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,MAAM,CAAC,YAAY,EAAE,EAAE,EACxE,MAAM,CACP,CAAC;QAEF,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;QAEnD,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC;QAC7E,MAAM,WAAW,CACf,GAAG,EACH,KAAK,EACL,MAAM,CAAC,gBAAgB,EACvB,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAClC,GAAG,GAAG,CAAC,QAAQ,CAAC,gBAAgB,WAAW,QAAQ,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,aAAa,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,EACrH,EAAE,SAAS,EAAE,YAAY,EAAE,CAC5B,CAAC;QAEF,6CAA6C;QAC7C,IAAI,QAAQ,CAAC,MAAM,KAAK,mBAAmB,IAAI,QAAQ,CAAC,YAAY,EAAE,CAAC;YACrE,IAAI,MAAM,CAAC,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpD,MAAM,kBAAkB,CACtB,GAAG,EACH,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,SAAS,EAChB,+BAA+B,QAAQ,CAAC,YAAY,EAAE,EACtD,kBAAkB,CACnB,CAAC;YACJ,CAAC;iBAAM,IAAI,MAAM,CAAC,SAAS,KAAK,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBAC1D,2BAA2B;gBAC3B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE;oBAC7C,IAAI,EAAE,SAAS;oBACf,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,IAAI,EAAE,+BAA+B,QAAQ,CAAC,YAAY,EAAE;iBAC7D,CAAC,CAAC;YACL,CAAC;YAED,0DAA0D;YAC1D,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;gBACxB,MAAM,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE;oBAC7E,SAAS,EAAE,YAAY;oBACvB,eAAe,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS;oBAClF,gBAAgB,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS;iBACtF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,kDAAkD;QAClD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,SAAS,EAAE;YACvD,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,MAAM,EAAE,QAAQ,CAAC,MAAM;SACxB,CAAC,CAAC;QAEH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE;YACrC,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,WAAW,EAAE,QAAQ,CAAC,WAAW;SAClC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,GAAkB,EAAE,KAAa;QACnD,MAAM,UAAU,GAAI,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;YACtC,SAAS,EAAE,UAAU;YACrB,QAAQ,EAAE,wBAAwB;SACnC,CAAqB,IAAI,EAAE,CAAC;QAE7B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAEpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,KAAK,MAAM,YAAY,IAAI,UAAU,EAAE,CAAC;YACtC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;gBACjC,SAAS,EAAE,UAAU;gBACrB,QAAQ,EAAE,cAAc,YAAY,EAAE;aACvC,CAA4B,CAAC;YAE9B,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC3C,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;gBAC5C,SAAS;YACX,CAAC;YAED,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;YACvD,IAAI,GAAG,GAAG,SAAS;gBAAE,SAAS;YAE9B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;YAE/F,MAAM,CAAC,MAAM,GAAG,WAAW,CAAC;YAC5B,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CACjB,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,YAAY,EAAE,EAAE,EACjE,MAAM,CACP,CAAC;YAEF,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;YAE5C,MAAM,WAAW,CACf,GAAG,EACH,KAAK,EACL,MAAM,CAAC,gBAAgB,EACvB,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAClC,GAAG,GAAG,CAAC,QAAQ,CAAC,8CAA8C,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,GAAG,CAAC,YAAY,CAAC,IAAI,EACvH,EAAE,SAAS,EAAE,YAAY,EAAE,CAC5B,CAAC;YAEF,+CAA+C;YAC/C,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,SAAS,EAAE;gBACxD,YAAY;gBACZ,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,aAAa,EAAE,MAAM,CAAC,aAAa;gBACnC,cAAc,EAAE,MAAM,CAAC,cAAc;aACtC,CAAC,CAAC;YAEH,IAAI,MAAM,CAAC,aAAa,KAAK,YAAY,IAAI,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;gBAC1F,MAAM,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE;oBAC7E,SAAS,EAAE,YAAY;oBACvB,eAAe,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS;oBAClF,gBAAgB,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS;iBACtF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,aAAa,CAAC,GAAkB,EAAE,YAAoB;QAClE,MAAM,UAAU,GAAI,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;YACtC,SAAS,EAAE,UAAU;YACrB,QAAQ,EAAE,wBAAwB;SACnC,CAAqB,IAAI,EAAE,CAAC;QAE7B,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,YAAY,CAAC,CAAC;QAC/D,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CACjB,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,wBAAwB,EAAE,EAC7D,OAAO,CACR,CAAC;IACJ,CAAC;CACF"}

package/dist/file-routing.d.ts

@@ -0,0 +1,51 @@
+export type TelegramFileRoute = {
+    name?: unknown;
+    enabled?: unknown;
+    projectKey?: unknown;
+    chatId?: unknown;
+    topicId?: unknown;
+};
+export type NormalizedTelegramFileRoute = {
+    name: string;
+    projectKey: string;
+    chatId: string;
+    topicId?: number;
+};
+export type FileRouteValidationIssue = {
+    index?: number;
+    field: "fileRoutes" | "name" | "projectKey" | "chatId" | "topicId";
+    message: string;
+};
+export type FileRouteValidationResult = {
+    routes: NormalizedTelegramFileRoute[];
+    issues: FileRouteValidationIssue[];
+    duplicateProjectKeys: string[];
+};
+export type TelegramFileDestination = {
+    ok: true;
+    chatId: string;
+    topicId?: number;
+    source: "explicit" | "file_route" | "legacy_fallback";
+    routeName?: string;
+    projectKey?: string;
+    issueIdentifier?: string;
+} | {
+    ok: false;
+    code: "missing_destination" | "missing_route_context" | "unknown_project_route" | "ambiguous_route" | "invalid_route_config" | "conflicting_destination" | "unresolved_issue";
+    message: string;
+    projectKey?: string;
+    issueIdentifier?: string;
+};
+export type TelegramFileDestinationRequest = {
+    explicitChatId?: string | null;
+    explicitThreadId?: number;
+    issueId?: string | null;
+    issueIdentifier?: string | null;
+    projectKey?: string | null;
+    lookupIssueIdentifier?: (issueId: string) => Promise<string | null>;
+};
+export declare function normalizeProjectKey(value: unknown): string | null;
+export declare function parseProjectKeyFromIssueIdentifier(value: unknown): string | null;
+export declare function validateTelegramFileRoutes(value: unknown): FileRouteValidationResult;
+export declare function getTelegramFileRouteSaveErrors(value: unknown): string[];
+export declare function resolveTelegramFileDestination(fileRoutes: unknown, request: TelegramFileDestinationRequest): Promise<TelegramFileDestination>;

package/dist/file-routing.js

@@ -0,0 +1,212 @@
+// Ported from ant013/paperclip-plugin-telegram (TEL-23, commit 45fea97):
+// "route Telegram file sends by project key". Self-contained validation and
+// destination-resolution helpers for outbound Telegram file routing.
+const PROJECT_KEY_PATTERN = /^[A-Z][A-Z0-9]*$/;
+const ISSUE_IDENTIFIER_PATTERN = /^([A-Z][A-Z0-9]*)-\d+$/;
+const CHAT_ID_PATTERN = /^-?\d+$/;
+const TOPIC_ID_PATTERN = /^\d+$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cleanString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function routeEnabled(value) {
+    return value !== false;
+}
+export function normalizeProjectKey(value) {
+    const normalized = cleanString(value).toUpperCase();
+    return PROJECT_KEY_PATTERN.test(normalized) ? normalized : null;
+}
+export function parseProjectKeyFromIssueIdentifier(value) {
+    const issueIdentifier = cleanString(value).toUpperCase();
+    const match = ISSUE_IDENTIFIER_PATTERN.exec(issueIdentifier);
+    return match?.[1] ?? null;
+}
+export function validateTelegramFileRoutes(value) {
+    const routes = [];
+    const issues = [];
+    if (value === undefined || value === null) {
+        return { routes, issues, duplicateProjectKeys: [] };
+    }
+    if (!Array.isArray(value)) {
+        return {
+            routes,
+            issues: [{ field: "fileRoutes", message: "fileRoutes must be an array." }],
+            duplicateProjectKeys: [],
+        };
+    }
+    for (const [index, route] of value.entries()) {
+        if (!isRecord(route)) {
+            issues.push({ index, field: "fileRoutes", message: "Enabled file routes must be objects." });
+            continue;
+        }
+        if (!routeEnabled(route.enabled)) {
+            continue;
+        }
+        const name = cleanString(route.name);
+        const projectKey = cleanString(route.projectKey);
+        const chatId = cleanString(route.chatId);
+        const rawTopicId = cleanString(route.topicId);
+        let valid = true;
+        if (!name) {
+            issues.push({ index, field: "name", message: "Enabled file routes need a name." });
+            valid = false;
+        }
+        if (!PROJECT_KEY_PATTERN.test(projectKey)) {
+            issues.push({ index, field: "projectKey", message: "Project key must use uppercase letters and numbers." });
+            valid = false;
+        }
+        if (!CHAT_ID_PATTERN.test(chatId)) {
+            issues.push({ index, field: "chatId", message: "Enabled file routes need a numeric Telegram chat ID." });
+            valid = false;
+        }
+        if (rawTopicId && !TOPIC_ID_PATTERN.test(rawTopicId)) {
+            issues.push({ index, field: "topicId", message: "Topic ID must be numeric when provided." });
+            valid = false;
+        }
+        if (valid) {
+            routes.push({
+                name,
+                projectKey,
+                chatId,
+                topicId: rawTopicId ? Number(rawTopicId) : undefined,
+            });
+        }
+    }
+    const duplicateNames = findDuplicates(routes.map((route) => route.name));
+    for (const name of duplicateNames) {
+        issues.push({ field: "name", message: `Enabled file route names must be unique: ${name}.` });
+    }
+    return {
+        routes,
+        issues,
+        duplicateProjectKeys: findDuplicates(routes.map((route) => route.projectKey)),
+    };
+}
+export function getTelegramFileRouteSaveErrors(value) {
+    const validation = validateTelegramFileRoutes(value);
+    return [
+        ...validation.issues.map((issue) => issue.message),
+        ...validation.duplicateProjectKeys.map((projectKey) => `Enabled file routes must not duplicate project key ${projectKey}.`),
+    ];
+}
+export async function resolveTelegramFileDestination(fileRoutes, request) {
+    const hasExplicitChat = Boolean(request.explicitChatId);
+    const hasExplicitThread = request.explicitThreadId !== undefined;
+    const hasRouteInput = Boolean(request.projectKey || request.issueIdentifier || request.issueId);
+    if (!hasRouteInput) {
+        if (hasExplicitChat) {
+            return { ok: true, source: "explicit", chatId: request.explicitChatId };
+        }
+        return { ok: true, source: "legacy_fallback", chatId: "" };
+    }
+    if (hasExplicitChat || hasExplicitThread) {
+        return {
+            ok: false,
+            code: "conflicting_destination",
+            message: "Route-aware Telegram file sends cannot also set chatId or threadId.",
+        };
+    }
+    const routeContext = await resolveRouteContext(request);
+    if (!routeContext.ok)
+        return routeContext;
+    const validation = validateTelegramFileRoutes(fileRoutes);
+    if (validation.issues.length > 0) {
+        return {
+            ok: false,
+            code: "invalid_route_config",
+            message: "Telegram file route configuration has invalid enabled routes.",
+            projectKey: routeContext.projectKey,
+            issueIdentifier: routeContext.issueIdentifier,
+        };
+    }
+    const matches = validation.routes.filter((route) => route.projectKey === routeContext.projectKey);
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            code: "unknown_project_route",
+            message: `No enabled Telegram file route matches project key ${routeContext.projectKey}.`,
+            projectKey: routeContext.projectKey,
+            issueIdentifier: routeContext.issueIdentifier,
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            ok: false,
+            code: "ambiguous_route",
+            message: `Multiple enabled Telegram file routes match project key ${routeContext.projectKey}.`,
+            projectKey: routeContext.projectKey,
+            issueIdentifier: routeContext.issueIdentifier,
+        };
+    }
+    const route = matches[0];
+    return {
+        ok: true,
+        source: "file_route",
+        chatId: route.chatId,
+        topicId: route.topicId,
+        routeName: route.name,
+        projectKey: route.projectKey,
+        issueIdentifier: routeContext.issueIdentifier,
+    };
+}
+function findDuplicates(values) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const value of values) {
+        if (seen.has(value)) {
+            duplicates.add(value);
+        }
+        else {
+            seen.add(value);
+        }
+    }
+    return [...duplicates].sort();
+}
+async function resolveRouteContext(request) {
+    const issueId = cleanString(request.issueId);
+    let resolvedIssueIdentifier;
+    if (issueId) {
+        const lookupResult = await request.lookupIssueIdentifier?.(issueId);
+        if (!lookupResult) {
+            return {
+                ok: false,
+                code: "unresolved_issue",
+                message: "Could not resolve the Paperclip issue for Telegram file routing.",
+            };
+        }
+        resolvedIssueIdentifier = lookupResult.toUpperCase();
+    }
+    const explicitProjectKey = normalizeProjectKey(request.projectKey);
+    if (explicitProjectKey) {
+        return {
+            ok: true,
+            projectKey: explicitProjectKey,
+            issueIdentifier: cleanString(request.issueIdentifier).toUpperCase() || resolvedIssueIdentifier,
+        };
+    }
+    const issueIdentifier = cleanString(request.issueIdentifier).toUpperCase() || resolvedIssueIdentifier;
+    const projectKeyFromIdentifier = parseProjectKeyFromIssueIdentifier(issueIdentifier);
+    if (projectKeyFromIdentifier) {
+        return {
+            ok: true,
+            projectKey: projectKeyFromIdentifier,
+            issueIdentifier,
+        };
+    }
+    if (resolvedIssueIdentifier) {
+        return {
+            ok: false,
+            code: "missing_route_context",
+            message: "Resolved issue identifier does not contain a routable project key.",
+            issueIdentifier: resolvedIssueIdentifier,
+        };
+    }
+    return {
+        ok: false,
+        code: "missing_route_context",
+        message: "Telegram file routing needs projectKey, issueIdentifier, or issueId.",
+    };
+}
+//# sourceMappingURL=file-routing.js.map