@rhizogrip/spore-plugin-telegram 0.4.0 → 0.6.0

package/README.md

@@ -49,7 +49,9 @@ Write to the bot and the message goes to the spore the chat is mapped to, which
 wrote it and where — your name and username, the private chat or the group. The bot posts
 `working…` and shows which tools run as they run. When the turn ends, the answer arrives as a new
 message replying to yours, so it notifies you however long the turn took, and `working…` is
-removed; one Telegram will no longer let the bot remove, past 48 hours, says `answered below`. How
+removed; one Telegram will no longer let the bot remove, past 48 hours, says `answered below`. The
+answer's Markdown is shown as Telegram formats it — bold, italic, code, code blocks, links, quotes;
+a heading as a bold line, a table in a monospace block — and as plain text if Telegram refuses it. How
 the turn ended is added only when it makes the answer partial — a wrap or a stop. A longer answer
 than Telegram's 4096 continues in further messages. What the turn left in `data/out/` follows as
 documents, up to the 50 a turn hands back, then a line counting the rest; a file over Telegram's
@@ -109,6 +111,18 @@ It is then shown `reading data/report.md`, `running git log --oneline -5`,
 `source forgejo --path …` — the first line, cut short. Choose it for a chat you would let
 read the commands; the others keep the kinds.
 
+A chat can be shown a turn more quietly, which is what a group gets unless its entry says
+otherwise: `"show": "react"` puts a 🫡 on your message when the spore takes it and shows Telegram's
+`typing…` while the turn runs, then takes the 🫡 off when the answer arrives — or puts a 💔 there
+when the turn ended without one. `"show": "working"` is the `working…` message, what a private
+chat gets; `"show": "both"` is both. The bot's two emoji are its own to choose, from the ones
+Telegram lets a bot react with (✅ and ❌ are not among them; the log lists them when one is refused):
+
+```json
+{ "token": "${OPS_BOT_TOKEN}", "react": { "taken": "👀", "failed": "🤷" },
+  "chats": { "-1001234567": { "spore": "triage", "show": "react" } } }
+```
+
 Two chats may point at one spore and then share its conversation. A reply goes to the
 chat that asked; a turn nobody in a chat started goes to the spore's default.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizogrip/spore-plugin-telegram",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Telegram for spores: a bot of yours in chats, each chat reaching its spore, run as a service",
   "author": {
     "name": "Christophe Le Bars",
@@ -27,14 +27,17 @@
     "README.md",
     "NOTICE"
   ],
+  "dependencies": {
+    "marked": "^18.0.11"
+  },
   "peerDependencies": {
-    "@rhizogrip/spore": "^1.15.0"
+    "@rhizogrip/spore": "^1.18.0"
   },
   "scripts": {
     "test": "vitest run"
   },
   "spore": {
-    "works": "^1.15.0",
+    "works": "^1.18.0",
     "services": {
       "telegram": {
         "what": "a bot of yours in Telegram chats, each chat reaching its spore",

package/src/adapter.js

@@ -6,18 +6,34 @@
 
 import { SporeError } from '@rhizogrip/spore'
 
+import { toHtml } from './format.js'
+
 const COMMAND = /^\/([a-z]+)(@\w+)?(?:\s+(.+))?$/is
 const NOT_MODIFIED = /message is not modified/
+const CANNOT_PARSE = /can't parse entities/i
 const SHAPE = '{ "token": "${TRIAGE_BOT_TOKEN}", "chats": { "<chat id>": "<spore>" } }' // eslint-disable-line no-template-curly-in-string
 
+/** What a bot may react with: `ReactionTypeEmoji` in the Bot API. */
+const REACTIONS = [
+  '❤', '👍', '👎', '🔥', '🥰', '👏', '😁', '🤔', '🤯', '😱',
+  '🤬', '😢', '🎉', '🤩', '🤮', '💩', '🙏', '👌', '🕊', '🤡',
+  '🥱', '🥴', '😍', '🐳', '❤‍🔥', '🌚', '🌭', '💯', '🤣', '⚡',
+  '🍌', '🏆', '💔', '🤨', '😐', '🍓', '🍾', '💋', '🖕', '😈',
+  '😴', '😭', '🤓', '👻', '👨‍💻', '👀', '🎃', '🙈', '😇', '😨',
+  '🤝', '✍', '🤗', '🫡', '🎅', '🎄', '☃', '💅', '🤪', '🗿',
+  '🆒', '💘', '🙉', '🦄', '😘', '💊', '🙊', '😎', '👾', '🤷‍♂',
+  '🤷', '🤷‍♀', '😡'
+]
+
 const said = (err) => [err.message, err.detail].filter(Boolean).join(' — ')
 
 const invalid = (path, problem, detail) => new SporeError(`${path} ${problem}`, { type: 'TELEGRAM_BOT_INVALID', detail })
 
 /**
- * `{ "<chat id>": "<spore>" }`, or `{ "<chat id>": { "spore": "<spore>", "details": true } }` for a
- * chat shown what each call does — its command or path — rather than only what kind of call it
- * is: a Telegram message leaves the machine, so that is a choice made per chat.
+ * `{ "<chat id>": "<spore>" }`, or `{ "<chat id>": { "spore": "<spore>", "details": true, "show":
+ * "react" } }`: `details` for a chat shown what each call does — its command or path — rather than
+ * only what kind of call it is, since a Telegram message leaves the machine; `show` for how a turn
+ * shows itself there.
  */
 function routes (raw, path) {
   if (typeof raw.chats !== 'object' || raw.chats === null || Array.isArray(raw.chats)) {
@@ -26,11 +42,11 @@ function routes (raw, path) {
   const table = new Map()
   for (const [chat, entry] of Object.entries(raw.chats)) {
     const spore = typeof entry === 'string' ? entry : entry?.spore
-    const extra = typeof entry === 'object' && entry !== null ? Object.keys(entry).filter(key => !['spore', 'details'].includes(key)) : []
+    const extra = typeof entry === 'object' && entry !== null ? Object.keys(entry).filter(key => !['spore', 'details', 'show'].includes(key)) : []
     if (typeof spore !== 'string' || !spore || extra.length || (typeof entry === 'object' && entry.details !== undefined && typeof entry.details !== 'boolean')) {
-      throw invalid(path, `maps ${chat} to something that is not a spore`, 'each chat is a chat id against the name of a spore it may reach, or { "spore": "<name>", "details": true }')
+      throw invalid(path, `maps ${chat} to something that is not a spore`, 'each chat is a chat id against the name of a spore it may reach, or { "spore": "<name>", "details": true, "show": "react" }')
     }
-    table.set(chat, { spores: [spore], details: typeof entry === 'object' && entry.details === true })
+    table.set(chat, { spores: [spore], details: typeof entry === 'object' && entry.details === true, show: typeof entry === 'object' ? entry.show ?? null : null })
   }
   return table
 }
@@ -41,7 +57,7 @@ export const TELEGRAM = {
   kind: 'telegram',
   label: 'Telegram',
   noun: 'chat',
-  fields: ['token', 'chats'],
+  fields: ['token', 'chats', 'react'],
   credentials: ['token'],
   stateFields: [],
   sourceVariables: [],
@@ -49,8 +65,9 @@ export const TELEGRAM = {
   example: SHAPE,
   routes,
   usage: { help: HELP, extend: '/extend wall 30m, /extend cost 1.50 or /extend rounds 20' },
-  limits: { message: 4096, file: 50 * 1024 * 1024, editEveryMs: 2500 },
-  can: { upload: true, remove: true },
+  limits: { message: 4096, file: 50 * 1024 * 1024, editEveryMs: 2500, typingEveryMs: 4000 },
+  can: { upload: true, remove: true, react: true, typing: true },
+  reactions: REACTIONS,
   hint (err, { file, bot }) {
     if (err.type === 'TELEGRAM_NO_BOT') {
       const variable = `${bot.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_BOT_TOKEN`
@@ -78,6 +95,7 @@ export function normalize (update, bot) {
     message: message.message_id,
     person: { id: String(message.from.id), name: `${[first, last].filter(Boolean).join(' ')}${username ? ` (@${username})` : ''}`, username },
     where: message.chat.type === 'private' ? 'a private chat on Telegram' : `the Telegram group "${message.chat.title}"`,
+    shared: message.chat.type !== 'private',
     text,
     command: command ? { verb: command[1].toLowerCase(), args: command[3] ?? '' } : null,
     addresses: null,
@@ -124,7 +142,14 @@ export function createAdapter ({ telegram, bot }) {
       }
     },
 
-    post: async (conversation, text, { answering = null } = {}) => (await telegram.say(Number(conversation), text, { answering })).message_id,
+    post: async (conversation, text, { answering = null, markdown = false } = {}) => {
+      try {
+        return (await telegram.say(Number(conversation), markdown ? toHtml(text) : text, { answering, html: markdown })).message_id
+      } catch (err) {
+        if (!markdown || !CANNOT_PARSE.test(err.detail ?? '')) throw err
+        throw new SporeError('Telegram refused the formatting', { type: 'TELEGRAM_FORMAT_REFUSED', detail: err.detail, context: { formatRefused: true } })
+      }
+    },
 
     edit: async (conversation, note, text) => {
       try {
@@ -136,6 +161,10 @@ export function createAdapter ({ telegram, bot }) {
 
     remove: (conversation, note) => telegram.remove(Number(conversation), note),
 
-    upload: (conversation, file, caption) => telegram.document(Number(conversation), file, caption)
+    upload: (conversation, file, caption) => telegram.document(Number(conversation), file, caption),
+
+    react: (conversation, message, emoji) => telegram.react(Number(conversation), message, emoji),
+
+    typing: (conversation) => telegram.typing(Number(conversation))
   }
 }

package/src/api.js

@@ -51,10 +51,11 @@ export function createTelegram (token, { fetchImpl = fetch, base = BASE } = {})
     updates: (offset, { seconds = 30, signal } = {}) =>
       call('getUpdates', { offset, timeout: seconds, allowed_updates: ['message'] }, { timeoutMs: (seconds + 15) * 1000, signal }),
 
-    say: (chat, text, { answering = null } = {}) => call('sendMessage', {
+    say: (chat, text, { answering = null, html = false } = {}) => call('sendMessage', {
       chat_id: chat,
       text,
       link_preview_options: { is_disabled: true },
+      ...(html ? { parse_mode: 'HTML' } : {}),
       ...(answering === null ? {} : { reply_parameters: { message_id: answering, allow_sending_without_reply: true } })
     }),
 
@@ -63,6 +64,12 @@ export function createTelegram (token, { fetchImpl = fetch, base = BASE } = {})
 
     remove: (chat, message) => call('deleteMessage', { chat_id: chat, message_id: message }),
 
+    /** `emoji` on the message as the bot's one reaction, or none when it is null. */
+    react: (chat, message, emoji) =>
+      call('setMessageReaction', { chat_id: chat, message_id: message, reaction: emoji === null ? [] : [{ type: 'emoji', emoji }] }),
+
+    typing: (chat) => call('sendChatAction', { chat_id: chat, action: 'typing' }),
+
     document: (chat, { path, mime }, caption) => {
       const form = new FormData()
       form.append('chat_id', String(chat))

package/src/format.js

@@ -0,0 +1,76 @@
+/**
+ * Markdown, as a model writes it, in the HTML Telegram renders. Bold, italic, strikethrough, code,
+ * code blocks with their language, links and quotes are Telegram's own; a heading becomes a bold
+ * line, a list keeps its bullets as text, a table becomes a monospace block. Telegram refuses a
+ * message holding any tag outside its small set, so everything else is escaped and shown as written.
+ */
+
+import { Lexer } from 'marked'
+
+const LINKABLE = /^(https?:|mailto:|tg:)/i
+
+const escape = (text) => String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+const attribute = (text) => escape(text).replace(/"/g, '&quot;')
+
+const plain = (tokens) => tokens.map(token => (token.tokens ? plain(token.tokens) : token.text ?? '')).join('')
+
+function inline (tokens) {
+  return tokens.map((token) => {
+    if (token.type === 'strong') return `<b>${inline(token.tokens)}</b>`
+    if (token.type === 'em') return `<i>${inline(token.tokens)}</i>`
+    if (token.type === 'del') return `<s>${inline(token.tokens)}</s>`
+    if (token.type === 'codespan') return `<code>${escape(token.text)}</code>`
+    if (token.type === 'br') return '\n'
+    if (token.type === 'link') return LINKABLE.test(token.href) ? `<a href="${attribute(token.href)}">${inline(token.tokens)}</a>` : inline(token.tokens)
+    if (token.type === 'image') return LINKABLE.test(token.href) ? `<a href="${attribute(token.href)}">${escape(token.text || token.href)}</a>` : escape(token.text)
+    if (token.type === 'text') return token.tokens ? inline(token.tokens) : escape(token.text)
+    if (token.type === 'escape') return escape(token.text)
+    if (token.type === 'checkbox') return token.checked ? '☑ ' : '☐ '
+    return escape(token.raw)
+  }).join('')
+}
+
+function list (token, depth) {
+  const indent = '  '.repeat(depth)
+  return token.items.map((item, i) => {
+    const mark = token.ordered ? `${Number(token.start) + i}.` : '•'
+    const box = item.tokens.filter(child => child.type === 'checkbox').map(child => inline([child])).join('')
+    const parts = item.tokens.filter(child => child.type !== 'checkbox').map(child => (child.type === 'list' ? list(child, depth + 1) : block([child], depth + 1)))
+    return `${indent}${mark} ${box}${parts.join('\n')}`
+  }).join('\n')
+}
+
+function table (token) {
+  const rows = [token.header, ...token.rows].map(row => row.map(cell => plain(cell.tokens)))
+  const widths = rows[0].map((_, column) => Math.max(...rows.map(row => row[column].length)))
+  const line = (row) => row.map((cell, column) => cell.padEnd(widths[column])).join(' | ').trimEnd()
+  return `<pre>${escape([line(rows[0]), widths.map(width => '-'.repeat(width)).join('-+-'), ...rows.slice(1).map(line)].join('\n'))}</pre>`
+}
+
+function block (tokens, depth = 0) {
+  const out = []
+  for (const token of tokens) {
+    if (token.type === 'space') continue
+    if (token.type === 'code') {
+      const language = token.lang?.split(/\s/)[0]
+      out.push(`<pre><code${language ? ` class="language-${attribute(language)}"` : ''}>${escape(token.text)}</code></pre>`)
+    } else if (token.type === 'heading') {
+      out.push(`<b>${inline(token.tokens)}</b>`)
+    } else if (token.type === 'paragraph' || token.type === 'text') {
+      out.push(inline(token.tokens ?? [token]))
+    } else if (token.type === 'blockquote') {
+      out.push(`<blockquote>${block(token.tokens, depth)}</blockquote>`)
+    } else if (token.type === 'list') {
+      out.push(list(token, depth))
+    } else if (token.type === 'table') {
+      out.push(table(token))
+    } else if (token.type === 'hr') {
+      out.push('──────────')
+    } else {
+      out.push(escape(token.raw.trimEnd()))
+    }
+  }
+  return out.join('\n\n')
+}
+
+export const toHtml = (markdown) => block(Lexer.lex(String(markdown)))