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

package/dist/interaction-delivery.js.map

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

package/dist/manifest.d.ts

@@ -0,0 +1,3 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+declare const manifest: PaperclipPluginManifestV1;
+export default manifest;

package/dist/manifest.js

@@ -0,0 +1,111 @@
+import { PLUGIN_ID, PLUGIN_VERSION } from "./constants.js";
+const manifest = {
+    id: PLUGIN_ID,
+    apiVersion: 1,
+    version: PLUGIN_VERSION,
+    displayName: "Telegram Bot",
+    description: "Bidirectional Telegram integration: push notifications, bot commands, escalation to humans, multi-agent sessions (native + ACP), media pipeline with transcription, custom workflow commands, and proactive suggestion watches.",
+    author: "Odience Network",
+    categories: ["connector", "automation"],
+    capabilities: [
+        "companies.read",
+        "projects.read",
+        "issues.read",
+        "issues.create",
+        "issues.update",
+        "issue.comments.read",
+        "issue.comments.create",
+        "agents.read",
+        "agents.invoke",
+        "agent.sessions.create",
+        "agent.sessions.list",
+        "agent.sessions.send",
+        "agent.sessions.close",
+        "agent.tools.register",
+        "events.subscribe",
+        "events.emit",
+        "plugin.state.read",
+        "plugin.state.write",
+        "http.outbound",
+        "secrets.read-ref",
+        "activity.log.write",
+        "metrics.write",
+        "jobs.schedule",
+        "instance.settings.register",
+        "ui.page.register",
+    ],
+    entrypoints: {
+        worker: "./dist/worker.js",
+        ui: "./dist/ui",
+    },
+    ui: {
+        slots: [
+            {
+                type: "settingsPage",
+                id: "telegram-settings",
+                displayName: "Telegram Settings",
+                exportName: "TelegramSettingsPage",
+            },
+        ],
+    },
+    jobs: [
+        {
+            jobKey: "telegram-daily-digest",
+            displayName: "Telegram Digest",
+            description: "Send a summary of agent activity to Telegram (daily or bidaily).",
+            schedule: "0 * * * *",
+        },
+        {
+            jobKey: "check-escalation-timeouts",
+            displayName: "Check Escalation Timeouts",
+            description: "Check for timed-out escalations and apply default actions.",
+            schedule: "* * * * *",
+        },
+        {
+            jobKey: "check-watches",
+            displayName: "Check Proactive Watches",
+            description: "Evaluate registered watches and send suggestions when conditions are met.",
+            schedule: "*/15 * * * *",
+        },
+    ],
+    tools: [
+        {
+            name: "escalate_to_human",
+            displayName: "Escalate to Human",
+            description: "Escalate a conversation to a human when you cannot handle it confidently",
+            parametersSchema: { type: "object" },
+        },
+        {
+            name: "handoff_to_agent",
+            displayName: "Handoff to Agent",
+            description: "Hand off work to another agent in this thread",
+            parametersSchema: { type: "object" },
+        },
+        {
+            name: "discuss_with_agent",
+            displayName: "Discuss with Agent",
+            description: "Start a back-and-forth conversation with another agent",
+            parametersSchema: { type: "object" },
+        },
+        {
+            name: "register_watch",
+            displayName: "Register Watch",
+            description: "Register a proactive watch that monitors entities and sends suggestions",
+            parametersSchema: { type: "object" },
+        },
+        {
+            name: "send_to_telegram",
+            displayName: "Send Telegram Message",
+            description: "Send text and Markdown content to a Telegram chat, with optional thread and project-key file routing.",
+            parametersSchema: { type: "object" },
+        },
+        {
+            name: "send_file_to_telegram",
+            displayName: "Send File to Telegram",
+            description: "Deprecated compatibility alias for send_to_telegram.",
+            parametersSchema: { type: "object" },
+        },
+    ],
+};
+export default manifest;
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE3D,MAAM,QAAQ,GAA8B;IAC1C,EAAE,EAAE,SAAS;IACb,UAAU,EAAE,CAAC;IACb,OAAO,EAAE,cAAc;IACvB,WAAW,EAAE,cAAc;IAC3B,WAAW,EACT,iOAAiO;IACnO,MAAM,EAAE,iBAAiB;IACzB,UAAU,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;IACvC,YAAY,EAAE;QACZ,gBAAgB;QAChB,eAAe;QACf,aAAa;QACb,eAAe;QACf,eAAe;QACf,qBAAqB;QACrB,uBAAuB;QACvB,aAAa;QACb,eAAe;QACf,uBAAuB;QACvB,qBAAqB;QACrB,qBAAqB;QACrB,sBAAsB;QACtB,sBAAsB;QACtB,kBAAkB;QAClB,aAAa;QACb,mBAAmB;QACnB,oBAAoB;QACpB,eAAe;QACf,kBAAkB;QAClB,oBAAoB;QACpB,eAAe;QACf,eAAe;QACf,4BAA4B;QAC5B,kBAAkB;KACnB;IACD,WAAW,EAAE;QACX,MAAM,EAAE,kBAAkB;QAC1B,EAAE,EAAE,WAAW;KAChB;IACD,EAAE,EAAE;QACF,KAAK,EAAE;YACL;gBACE,IAAI,EAAE,cAAc;gBACpB,EAAE,EAAE,mBAAmB;gBACvB,WAAW,EAAE,mBAAmB;gBAChC,UAAU,EAAE,sBAAsB;aACnC;SACF;KACF;IACD,IAAI,EAAE;QACJ;YACE,MAAM,EAAE,uBAAuB;YAC/B,WAAW,EAAE,iBAAiB;YAC9B,WAAW,EAAE,kEAAkE;YAC/E,QAAQ,EAAE,WAAW;SACtB;QACD;YACE,MAAM,EAAE,2BAA2B;YACnC,WAAW,EAAE,2BAA2B;YACxC,WAAW,EAAE,4DAA4D;YACzE,QAAQ,EAAE,WAAW;SACtB;QACD;YACE,MAAM,EAAE,eAAe;YACvB,WAAW,EAAE,yBAAyB;YACtC,WAAW,EAAE,2EAA2E;YACxF,QAAQ,EAAE,cAAc;SACzB;KACF;IACD,KAAK,EAAE;QACL;YACE,IAAI,EAAE,mBAAmB;YACzB,WAAW,EAAE,mBAAmB;YAChC,WAAW,EAAE,0EAA0E;YACvF,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACrC;QACD;YACE,IAAI,EAAE,kBAAkB;YACxB,WAAW,EAAE,kBAAkB;YAC/B,WAAW,EAAE,+CAA+C;YAC5D,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACrC;QACD;YACE,IAAI,EAAE,oBAAoB;YAC1B,WAAW,EAAE,oBAAoB;YACjC,WAAW,EAAE,wDAAwD;YACrE,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACrC;QACD;YACE,IAAI,EAAE,gBAAgB;YACtB,WAAW,EAAE,gBAAgB;YAC7B,WAAW,EAAE,yEAAyE;YACtF,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACrC;QACD;YACE,IAAI,EAAE,kBAAkB;YACxB,WAAW,EAAE,uBAAuB;YACpC,WAAW,EAAE,uGAAuG;YACpH,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACrC;QACD;YACE,IAAI,EAAE,uBAAuB;YAC7B,WAAW,EAAE,uBAAuB;YACpC,WAAW,EAAE,sDAAsD;YACnE,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACrC;KACF;CACF,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/media-pipeline.d.ts

@@ -0,0 +1,47 @@
+import type { PluginContext } from "@paperclipai/plugin-sdk";
+type MediaConfig = {
+    briefAgentId: string;
+    briefAgentChatIds: string[];
+    transcriptionApiKeyRef: string;
+    publicUrl?: string;
+};
+type TelegramMediaMessage = {
+    message_id: number;
+    chat: {
+        id: number;
+    };
+    message_thread_id?: number;
+    from?: {
+        id: number;
+        username?: string;
+        first_name?: string;
+    };
+    voice?: {
+        file_id: string;
+        duration: number;
+        mime_type?: string;
+    };
+    audio?: {
+        file_id: string;
+        duration: number;
+        title?: string;
+        mime_type?: string;
+    };
+    video_note?: {
+        file_id: string;
+        duration: number;
+    };
+    document?: {
+        file_id: string;
+        file_name?: string;
+        mime_type?: string;
+    };
+    photo?: Array<{
+        file_id: string;
+        width: number;
+        height: number;
+    }>;
+    caption?: string;
+};
+export declare function handleMediaMessage(ctx: PluginContext, token: string, msg: TelegramMediaMessage, config: MediaConfig, companyId: string): Promise<boolean>;
+export {};

package/dist/media-pipeline.js

@@ -0,0 +1,162 @@
+import { sendMessage, escapeMarkdownV2, sendChatAction } from "./telegram-api.js";
+import { METRIC_NAMES } from "./constants.js";
+import { getSessions, wakeAgentWithIssue } from "./acp-bridge.js";
+import { resolveMappedProjectIdForTopic } from "./topic-projects.js";
+const TELEGRAM_API = "https://api.telegram.org";
+export async function handleMediaMessage(ctx, token, msg, config, companyId) {
+    const chatId = String(msg.chat.id);
+    const threadId = msg.message_thread_id;
+    // Determine if this is an intake channel (brief agent) or an agent thread
+    const isIntakeChannel = config.briefAgentChatIds.includes(chatId);
+    const hasActiveSession = threadId
+        ? (await getSessions(ctx, chatId, threadId)).some((s) => s.status === "active")
+        : false;
+    if (!isIntakeChannel && !hasActiveSession) {
+        return false; // Not a media-relevant context
+    }
+    await sendChatAction(ctx, token, chatId);
+    // Extract media file info
+    const fileId = extractFileId(msg);
+    if (!fileId)
+        return false;
+    const isAudio = !!(msg.voice || msg.audio || msg.video_note);
+    let textContent = msg.caption ?? "";
+    // Transcribe audio/voice if applicable
+    if (isAudio && config.transcriptionApiKeyRef) {
+        try {
+            const transcription = await transcribeAudio(ctx, token, fileId, config.transcriptionApiKeyRef);
+            if (transcription) {
+                textContent = transcription;
+                // Send transcription preview
+                await sendMessage(ctx, token, chatId, `${escapeMarkdownV2("\ud83c\udfa4")} *Transcription:*\n${escapeMarkdownV2(textContent.slice(0, 500))}${textContent.length > 500 ? escapeMarkdownV2("...") : ""}`, {
+                    parseMode: "MarkdownV2",
+                    messageThreadId: threadId,
+                    replyToMessageId: msg.message_id,
+                });
+            }
+        }
+        catch (err) {
+            ctx.logger.error("Transcription failed", { error: String(err) });
+            textContent = msg.caption ?? "[Audio - transcription failed]";
+        }
+    }
+    if (isIntakeChannel && config.briefAgentId) {
+        // Route to Brief Agent via one-shot invocation
+        try {
+            const prompt = buildBriefPrompt(msg, textContent);
+            const { runId } = await ctx.agents.invoke(config.briefAgentId, companyId, {
+                prompt,
+                reason: "media_intake",
+            });
+            const hasPublicUrl = config.publicUrl && config.publicUrl.startsWith("https://");
+            const inlineKeyboard = hasPublicUrl
+                ? [[{ text: "View Run ↗", url: `${config.publicUrl}/agents/${config.briefAgentId}/runs/${runId}` }]]
+                : undefined;
+            await sendMessage(ctx, token, chatId, `${escapeMarkdownV2("\ud83d\udcdd")} Media sent to Brief Agent \\(run: \`${escapeMarkdownV2(runId)}\`\\)`, {
+                parseMode: "MarkdownV2",
+                messageThreadId: threadId,
+                replyToMessageId: msg.message_id,
+                inlineKeyboard,
+            });
+            ctx.logger.info("Media routed to brief agent", { runId, briefAgentId: config.briefAgentId });
+        }
+        catch (err) {
+            ctx.logger.error("Failed to invoke brief agent", { error: String(err) });
+            await sendMessage(ctx, token, chatId, `Failed to route media to brief agent: ${String(err)}`, { messageThreadId: threadId });
+        }
+    }
+    else if (hasActiveSession && threadId) {
+        // Route to the active agent in the thread
+        const sessions = await getSessions(ctx, chatId, threadId);
+        const activeSessions = sessions.filter((s) => s.status === "active");
+        const target = activeSessions.sort((a, b) => new Date(b.lastActivityAt).getTime() - new Date(a.lastActivityAt).getTime())[0];
+        if (target) {
+            const mediaLabel = isAudio ? "Audio message" : msg.photo ? "Photo" : "Document";
+            const prompt = `[${mediaLabel}] ${textContent || "(no caption)"}`;
+            const projectId = await resolveMappedProjectIdForTopic(ctx, chatId, companyId, threadId);
+            if (target.transport === "native") {
+                await wakeAgentWithIssue(ctx, target.agentId, companyId, prompt, "media_message", projectId);
+            }
+            else {
+                ctx.events.emit("acp-spawn", companyId, {
+                    type: "message",
+                    sessionId: target.sessionId,
+                    chatId,
+                    threadId,
+                    text: prompt,
+                });
+            }
+        }
+    }
+    await ctx.metrics.write(METRIC_NAMES.mediaProcessed, 1);
+    return true;
+}
+function extractFileId(msg) {
+    if (msg.voice)
+        return msg.voice.file_id;
+    if (msg.audio)
+        return msg.audio.file_id;
+    if (msg.video_note)
+        return msg.video_note.file_id;
+    if (msg.document)
+        return msg.document.file_id;
+    if (msg.photo && msg.photo.length > 0) {
+        // Use the largest photo
+        return msg.photo.sort((a, b) => b.width * b.height - a.width * a.height)[0].file_id;
+    }
+    return null;
+}
+async function transcribeAudio(ctx, botToken, fileId, transcriptionApiKeyRef) {
+    // 1. Get file path from Telegram (JSON response — ctx.http.fetch works fine for this)
+    const fileRes = await ctx.http.fetch(`${TELEGRAM_API}/bot${botToken}/getFile?file_id=${fileId}`, { method: "GET" });
+    const fileData = (await fileRes.json());
+    if (!fileData.ok || !fileData.result?.file_path) {
+        ctx.logger.error("Failed to get file path from Telegram", { fileId });
+        return null;
+    }
+    // 2. Download binary audio using native fetch (bypasses RPC bridge UTF-8 corruption)
+    const downloadUrl = `${TELEGRAM_API}/file/bot${botToken}/${fileData.result.file_path}`;
+    const audioRes = await fetch(downloadUrl);
+    const audioBuffer = Buffer.from(await audioRes.arrayBuffer());
+    // 3. Resolve the OpenAI API key from Paperclip secrets
+    const apiKey = await ctx.secrets.resolve(transcriptionApiKeyRef);
+    // 4. Build multipart form data manually (native FormData + Blob works in Node 18+)
+    const formData = new FormData();
+    formData.append("file", new Blob([audioBuffer], { type: "audio/ogg" }), "audio.ogg");
+    formData.append("model", "whisper-1");
+    // 5. Send to Whisper API using native fetch (FormData can't be serialized through RPC bridge)
+    const whisperRes = await fetch("https://api.openai.com/v1/audio/transcriptions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: formData,
+    });
+    const whisperData = (await whisperRes.json());
+    return whisperData.text ?? null;
+}
+function buildBriefPrompt(msg, textContent) {
+    const parts = [];
+    if (msg.voice) {
+        parts.push(`[Voice message, ${msg.voice.duration}s]`);
+    }
+    else if (msg.audio) {
+        parts.push(`[Audio: ${msg.audio.title ?? "untitled"}, ${msg.audio.duration}s]`);
+    }
+    else if (msg.video_note) {
+        parts.push(`[Video note, ${msg.video_note.duration}s]`);
+    }
+    else if (msg.document) {
+        parts.push(`[Document: ${msg.document.file_name ?? "unknown"}]`);
+    }
+    else if (msg.photo) {
+        parts.push("[Photo]");
+    }
+    if (textContent) {
+        parts.push(textContent);
+    }
+    const sender = msg.from?.username ?? msg.from?.first_name ?? "unknown";
+    parts.push(`\nFrom: ${sender}`);
+    return parts.join("\n");
+}
+//# sourceMappingURL=media-pipeline.js.map

package/dist/media-pipeline.js.map

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

package/dist/notification-filters.d.ts

@@ -0,0 +1,23 @@
+import type { PluginEvent } from "@paperclipai/plugin-sdk";
+/**
+ * Forward an `issue.updated` event as a "blocked" notification only when the issue
+ * transitioned to `status === "blocked"` AND it is owned by a human/board user
+ * (`assigneeUserId` is non-null/non-empty). Agent-only blocked issues are noise.
+ */
+export declare function shouldNotifyIssueBlocked(event: PluginEvent, enabled: boolean): boolean;
+/**
+ * Normalize a configured board-usernames value (array or comma/whitespace-separated
+ * string) into a deduped list of lowercase handles with any leading `@` stripped.
+ */
+export declare function parseBoardUsernames(value: unknown): string[];
+/**
+ * Word-boundary-aware, case-insensitive `@username` matcher. `@board` matches
+ * "ping @board please" but not "@boardroom" (trailing boundary) nor "me@board.com"
+ * (leading boundary — avoids email false positives).
+ */
+export declare function matchesBoardMention(text: string, usernames: string[]): boolean;
+/**
+ * Forward an `issue.comment.created` event only when the comment body @-mentions one
+ * of the configured board usernames.
+ */
+export declare function shouldNotifyBoardMention(event: PluginEvent, enabled: boolean, boardUsernames: string[]): boolean;

package/dist/notification-filters.js

@@ -0,0 +1,93 @@
+/**
+ * Anti-flood notification filters.
+ *
+ * Ported from tue-Jonas/paperclip-plugin-telegram (TWB-94, commit 03b6e99) — see
+ * TWB-FORK.md. The fork diverged from our v0.3.0 line (it removed the settings UI
+ * and secret-ref validation we keep), so the *logic* is re-implemented here against
+ * our worker rather than applying the fork's branch diff.
+ *
+ * These predicates gate noisy notifications behind config flags so the board chat
+ * only hears signal:
+ *  - issue blocked: forward `issue.updated` only when the issue is genuinely blocked
+ *    AND a human/board (assigneeUserId) owns it.
+ *  - board mention: forward `issue.comment.created` only when a configured board
+ *    username is @-mentioned (word-boundary aware, case-insensitive).
+ *
+ * Note: run-started / run-finished gating (the other half of TWB-94) already exists
+ * in our worker post-v0.3.0 via `notifyOnAgentRunStarted` / `notifyOnAgentRunFinished`
+ * (both default off), so it is not re-implemented here.
+ */
+function isNonEmptyValue(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    return true;
+}
+/**
+ * Forward an `issue.updated` event as a "blocked" notification only when the issue
+ * transitioned to `status === "blocked"` AND it is owned by a human/board user
+ * (`assigneeUserId` is non-null/non-empty). Agent-only blocked issues are noise.
+ */
+export function shouldNotifyIssueBlocked(event, enabled) {
+    if (!enabled)
+        return false;
+    const payload = event.payload;
+    if (payload.status !== "blocked")
+        return false;
+    return isNonEmptyValue(payload.assigneeUserId);
+}
+/**
+ * Normalize a configured board-usernames value (array or comma/whitespace-separated
+ * string) into a deduped list of lowercase handles with any leading `@` stripped.
+ */
+export function parseBoardUsernames(value) {
+    const raw = Array.isArray(value)
+        ? value.map((entry) => String(entry))
+        : typeof value === "string"
+            ? value.split(/[\s,]+/)
+            : [];
+    const seen = new Set();
+    for (const entry of raw) {
+        const handle = entry.trim().replace(/^@+/, "").toLowerCase();
+        if (handle)
+            seen.add(handle);
+    }
+    return [...seen];
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Word-boundary-aware, case-insensitive `@username` matcher. `@board` matches
+ * "ping @board please" but not "@boardroom" (trailing boundary) nor "me@board.com"
+ * (leading boundary — avoids email false positives).
+ */
+export function matchesBoardMention(text, usernames) {
+    if (!text || usernames.length === 0)
+        return false;
+    for (const handle of usernames) {
+        const re = new RegExp(`(?<![a-z0-9_])@${escapeRegExp(handle)}(?![a-z0-9_])`, "i");
+        if (re.test(text))
+            return true;
+    }
+    return false;
+}
+function extractCommentBody(payload) {
+    const candidate = (typeof payload.body === "string" && payload.body) ||
+        (typeof payload.comment === "string" && payload.comment) ||
+        (typeof payload.text === "string" && payload.text) ||
+        "";
+    return candidate;
+}
+/**
+ * Forward an `issue.comment.created` event only when the comment body @-mentions one
+ * of the configured board usernames.
+ */
+export function shouldNotifyBoardMention(event, enabled, boardUsernames) {
+    if (!enabled || boardUsernames.length === 0)
+        return false;
+    const payload = event.payload;
+    return matchesBoardMention(extractCommentBody(payload), boardUsernames);
+}
+//# sourceMappingURL=notification-filters.js.map

package/dist/notification-filters.js.map

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

package/dist/paperclip-api.d.ts

@@ -0,0 +1,25 @@
+import type { PluginContext } from "@paperclipai/plugin-sdk";
+/**
+ * Structured error for non-2xx Paperclip API responses. Ported from tue-Jonas
+ * `PaperclipApiError` (TWX-328) onto our worker/commands layout: it preserves
+ * the original throw message so existing callers/tests keep matching on
+ * "Paperclip API request failed with <status>" while also exposing `status` and
+ * `detail` so callers can classify conflicts (e.g. stale decision callbacks).
+ */
+export declare class PaperclipApiError extends Error {
+    readonly status: number;
+    readonly detail: string;
+    constructor(status: number, detail: string);
+}
+/**
+ * Classifies "the decision is no longer actionable" conflicts so a stale inline
+ * button press (TWX-328) is acknowledged gracefully instead of surfacing a raw
+ * API error. Covers both shapes seen across Paperclip surfaces:
+ *   - interaction conflicts: 409 "Interaction has already been resolved"
+ *   - approval conflicts:    422 "Only pending or revision requested approvals
+ *     can be approved/rejected" (an approval decided through another channel,
+ *     expired, or already resolved in the opposite direction).
+ */
+export declare function isAlreadyResolvedConflict(error: unknown): boolean;
+export declare function fetchPaperclipApi(ctx: PluginContext, url: string, init?: RequestInit): Promise<Response>;
+export declare function buildPaperclipAuthHeaders(boardApiToken?: string): Record<string, string>;

package/dist/paperclip-api.js

@@ -0,0 +1,69 @@
+/**
+ * Structured error for non-2xx Paperclip API responses. Ported from tue-Jonas
+ * `PaperclipApiError` (TWX-328) onto our worker/commands layout: it preserves
+ * the original throw message so existing callers/tests keep matching on
+ * "Paperclip API request failed with <status>" while also exposing `status` and
+ * `detail` so callers can classify conflicts (e.g. stale decision callbacks).
+ */
+export class PaperclipApiError extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        const suffix = detail ? `: ${detail}` : "";
+        super(`Paperclip API request failed with ${status}${suffix}`);
+        this.name = "PaperclipApiError";
+        this.status = status;
+        this.detail = detail;
+    }
+}
+/**
+ * Classifies "the decision is no longer actionable" conflicts so a stale inline
+ * button press (TWX-328) is acknowledged gracefully instead of surfacing a raw
+ * API error. Covers both shapes seen across Paperclip surfaces:
+ *   - interaction conflicts: 409 "Interaction has already been resolved"
+ *   - approval conflicts:    422 "Only pending or revision requested approvals
+ *     can be approved/rejected" (an approval decided through another channel,
+ *     expired, or already resolved in the opposite direction).
+ */
+export function isAlreadyResolvedConflict(error) {
+    const record = error && typeof error === "object" ? error : null;
+    const status = typeof record?.status === "number" ? record.status : null;
+    const detail = typeof record?.detail === "string" ? record.detail : "";
+    if (status !== 409 && status !== 422)
+        return false;
+    return /already been (?:resolved|decided)|already (?:resolved|decided)|only pending(?: or revision requested)? approvals can be/i.test(detail);
+}
+function isLoopbackUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(parsed.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+export async function fetchPaperclipApi(ctx, url, init) {
+    const response = isLoopbackUrl(url)
+        ? await fetch(url, init)
+        : await ctx.http.fetch(url, init);
+    if (!response.ok) {
+        let body = "";
+        try {
+            body = await response.text();
+        }
+        catch {
+            body = "";
+        }
+        const detail = body ? body.slice(0, 300) : "";
+        throw new PaperclipApiError(response.status, detail);
+    }
+    return response;
+}
+export function buildPaperclipAuthHeaders(boardApiToken) {
+    return boardApiToken
+        ? {
+            Authorization: `Bearer ${boardApiToken}`,
+        }
+        : {};
+}
+//# sourceMappingURL=paperclip-api.js.map

package/dist/paperclip-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip-api.js","sourceRoot":"","sources":["../src/paperclip-api.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,MAAM,CAAS;IACf,MAAM,CAAS;IAExB,YAAY,MAAc,EAAE,MAAc;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,KAAK,CAAC,qCAAqC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACtD,MAAM,MAAM,GACV,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,KAAiC,CAAC,CAAC,CAAC,IAAI,CAAC;IACjF,MAAM,MAAM,GAAG,OAAO,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACzE,MAAM,MAAM,GAAG,OAAO,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACnD,OAAO,0HAA0H,CAAC,IAAI,CACpI,MAAM,CACP,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,GAAW;IAChC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAkB,EAClB,GAAW,EACX,IAAkB;IAElB,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC;QACjC,CAAC,CAAC,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC;QACxB,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAEpC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,iBAAiB,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,aAAsB;IAEtB,OAAO,aAAa;QAClB,CAAC,CAAC;YACE,aAAa,EAAE,UAAU,aAAa,EAAE;SACzC;QACH,CAAC,CAAC,EAAE,CAAC;AACT,CAAC"}

package/dist/polling-offset.d.ts

@@ -0,0 +1,22 @@
+import type { PluginContext } from "@paperclipai/plugin-sdk";
+export declare const TELEGRAM_LAST_UPDATE_ID_STATE_KEY = "telegram-last-update-id";
+export declare function getPersistedTelegramUpdateOffset(ctx: PluginContext): Promise<number>;
+export declare function persistTelegramUpdateOffset(ctx: PluginContext, updateId: number): Promise<void>;
+type PollingLogger = Pick<PluginContext["logger"], "error">;
+export declare function handleTelegramUpdateThenPersistOffset(options: {
+    updateId: number;
+    lastUpdateId: number;
+    handleUpdate: () => Promise<void>;
+    persistOffset: (updateId: number) => Promise<void>;
+    logger: PollingLogger;
+}): Promise<number>;
+export declare function processTelegramUpdateBatch<TUpdate extends {
+    update_id: number;
+}>(options: {
+    updates: TUpdate[];
+    lastUpdateId: number;
+    handleUpdate: (update: TUpdate) => Promise<void>;
+    persistOffset: (updateId: number) => Promise<void>;
+    logger: PollingLogger;
+}): Promise<number>;
+export {};