@memo-industries/paperclip-telegram-notifier

Paperclip plugin that pushes board notifications to Telegram when something needs the board's attention:

| Event (SDK) | Condition | Message | |---|---|---| | approval.created | — | ❓ Новый вопрос борду | | issue.updated | transition → in_review | 👀 На ревью | | issue.updated | transition → blocked | ⛔ Заблокировано |

Part of the MemoDiary Paperclip development process. See docs/DESIGN.md.

Status

v1 implemented and verified. Pure logic lives in tested modules (config, format, notify-rules, telegram, deep-links). Worker is null-safe. Full test suite is green, tsc --noEmit is clean, and npm run build emits dist/worker.js + dist/manifest.js.

How it works

• Subscribes to domain events via ctx.events.on.
• Domain event payloads are typed unknown, so on issue.updated the worker re-reads the issue (ctx.issues.get) and detects a transition by comparing against the last status stored in ctx.state (per-issue). It only notifies when the status changes into in_review / blocked.
• Config is operator-editable via the host-rendered form (manifest.instanceConfigSchema): bot token (secret ref), chat id, deep-link base URL, company prefix, and per-event toggles. No custom UI bundle in v1.
• A dedicated plugin page (sidebar entry "Telegram Notifier") surfaces the last 50 delivery diagnostics ("Показать логи") and an npm version check ("Обновить"). The page reads worker-side diagnostics / update-status bridge handlers; the settings auto-form is unchanged. Actually performing an update from the page is a future step (needs a host plugin-update endpoint).
• The bot token is stored as a Paperclip secret and resolved with ctx.secrets.resolve (capability secrets.read-ref).

Capabilities

events.subscribe, issues.read, http.outbound, secrets.read-ref, plugin.state.read, plugin.state.write, ui.page.register, ui.sidebar.register.

Develop

npm install
npm run typecheck
npm test
npm run build      # bundles dist/worker.js + dist/manifest.js + dist/ui/index.js

Deploy

Target instance is a separate server (paperclip.example.com). Supported path: publish this package to npm and install it into the Paperclip instance at runtime. Provide a Telegram bot token (via @BotFather) and chat id in the plugin settings after install.

Roadmap

• v1: one-way notifications (this).
• v2 (optional): onWebhook to accept Telegram replies (e.g. approve MEM-123) and apply the board decision in Paperclip.
• Optional jobs.schedule hourly safety digest for any missed event.