@rhizogrip/spore-plugin-telegram 0.9.0 → 0.10.0

package/README.md

@@ -92,6 +92,17 @@ that does not reach the spore through this bot is refused, and the log says why.
 
 A turn started with `spore send` is shown only there; no chat is told.
 
+## Approvals
+
+An approval your program asks in a chat this bot reaches
+([INTEGRATION §Asking a person to approve](../../INTEGRATION.md#asking-a-person-to-approve)) is
+posted as a message — the request's `telegram` body, `{ "html": "…" }` in Telegram's HTML, or its
+`default` text and facts, a line each — with a button per option on its own row, green for
+`positive` and red for `destructive` where the Telegram app shows colours. A press is taken only
+from someone the approval names, and Telegram shows them `Apply — recorded`, or why it was not
+taken. The message is then edited: replaced by the body your hook answered, or kept with its
+buttons gone and who chose what below.
+
 ## The allow-list is the routing
 
 A bot's `people` say who may talk to it in private and which spore each reaches, as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizogrip/spore-plugin-telegram",
-  "version": "0.9.0",
+  "version": "0.10.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",
@@ -31,13 +31,13 @@
     "marked": "^18.0.11"
   },
   "peerDependencies": {
-    "@rhizogrip/spore": "^1.23.0"
+    "@rhizogrip/spore": "^1.24.0"
   },
   "scripts": {
     "test": "vitest run"
   },
   "spore": {
-    "works": "^1.23.0",
+    "works": "^1.24.0",
     "services": {
       "telegram": {
         "what": "a bot of yours in Telegram chats, each chat reaching its spore",

package/src/adapter.js

@@ -6,7 +6,7 @@
 
 import { SporeError } from '@rhizogrip/spore'
 
-import { toHtml } from './format.js'
+import { escape, toHtml } from './format.js'
 
 const COMMAND = /^\/([a-z]+)(@\w+)?(?:\s+(.+))?$/is
 const NOT_MODIFIED = /message is not modified/
@@ -31,6 +31,8 @@ const PERSON_FIELDS = ['spore', 'details', 'show', 'brief']
 const GROUP_FIELDS = ['spores', 'people', 'details', 'show', 'overhear', 'brief']
 const PERSON = /^\d+$/
 const GROUP = /^-\d+$/
+const STYLES = { positive: 'success', destructive: 'danger' }
+const BODY = 'a Telegram body is { "html": "<Telegram\'s HTML, at most 4096 characters>" }'
 
 const said = (err) => [err.message, err.detail].filter(Boolean).join(' — ')
 
@@ -113,7 +115,7 @@ export const TELEGRAM = {
   routes,
   usage: { help: `${HELP}; ${EXTEND}.`, briefHelp: `${HELP}.`, extend: '/extend wall 30m, /extend cost 1.50 or /extend rounds 20' },
   limits: { message: 4096, file: 50 * 1024 * 1024, editEveryMs: 2500, typingEveryMs: 4000 },
-  can: { upload: true, remove: true, react: true, typing: true, reply: true },
+  can: { upload: true, remove: true, react: true, typing: true, reply: true, choose: true },
   showShared: 'react',
   reactions: REACTIONS,
   hint (err, { file, bot }) {
@@ -132,6 +134,32 @@ export const TELEGRAM = {
 
 const FILES = ['photo', 'document', 'video', 'audio', 'voice', 'video_note', 'animation', 'sticker']
 
+const personOf = ({ id, first_name: first, last_name: last, username }) =>
+  ({ id: String(id), name: `${[first, last].filter(Boolean).join(' ')}${username ? ` (@${username})` : ''}`, username, groups: [] })
+
+const whereOf = (chat) => chat.type === 'private' ? 'a private chat on Telegram' : `the Telegram group "${chat.title}"`
+
+/** What an approval shows, in Telegram's HTML: the host's own, or the default body — its text, then each fact on a line. */
+const htmlOf = ({ native, fallback }) => native
+  ? native.html
+  : [
+      fallback.text ? toHtml(fallback.text) : null,
+      fallback.facts?.length ? fallback.facts.map(([label, value]) => `<b>${escape(label)}</b>: ${escape(value)}`).join('\n') : null
+    ].filter(Boolean).join('\n\n')
+
+/** A press on one of the bot's buttons as the relay takes it, or null for one on a message Telegram no longer shows. */
+export function choiceOf (query) {
+  if (!query.message?.chat) return null
+  return {
+    conversation: String(query.message.chat.id),
+    note: query.message.message_id,
+    data: query.data ?? null,
+    inputs: null,
+    person: personOf(query.from),
+    where: whereOf(query.message.chat)
+  }
+}
+
 /** Whether the bot's own `@username` is among what Telegram marked as mentions. */
 const mentions = (message, me) => {
   const source = message.text ?? message.caption ?? ''
@@ -157,14 +185,13 @@ export function normalize (update, bot, me) {
   const addressed = !shared || Boolean(command && (command[2] || VERBS.has(command[1].toLowerCase()))) ||
     mentions(message, me) || message.reply_to_message?.from?.id === me.id
   const text = command ? written : written?.replace(new RegExp(`@${me.username}\\b[,:]?\\s*`, 'gi'), '').trim() || null
-  const { first_name: first, last_name: last, username } = message.from
   return {
     id: `${bot}:${update.update_id}`,
     conversation: String(message.chat.id),
     message: message.message_id,
-    person: { id: String(message.from.id), name: `${[first, last].filter(Boolean).join(' ')}${username ? ` (@${username})` : ''}`, username, groups: [] },
+    person: personOf(message.from),
     spore: null,
-    where: shared ? `the Telegram group "${message.chat.title}"` : 'a private chat on Telegram',
+    where: whereOf(message.chat),
     shared,
     text,
     command: command ? { verb: command[1].toLowerCase(), args: command[3] ?? '' } : null,
@@ -187,11 +214,12 @@ export function createAdapter ({ telegram, bot, me }) {
     },
 
     /**
-     * One long poll after another until `signal` aborts. An update is handed to `onMessage` and
-     * awaited before the offset moves past it, since moving it is what confirms the update to
-     * Telegram: a message is confirmed only once the spore has it.
+     * One long poll after another until `signal` aborts. An update is handed to `onMessage`, or a
+     * press to `onChoice`, and awaited before the offset moves past it, since moving it is what
+     * confirms the update to Telegram: a message is confirmed only once the spore has it, and a
+     * press once it is written down.
      */
-    async listen ({ onMessage, signal, log, sleep }) {
+    async listen ({ onMessage, onChoice, signal, log, sleep }) {
       let offset
       let backoff = 1000
       while (!signal.aborted) {
@@ -211,8 +239,16 @@ export function createAdapter ({ telegram, bot, me }) {
           continue
         }
         for (const update of updates) {
-          const message = normalize(update, bot, me)
-          if (message) await onMessage(message)
+          const query = update.callback_query
+          if (query) {
+            const acknowledge = (text) => telegram.answer(query.id, text)
+            const choice = choiceOf(query)
+            if (choice) await onChoice({ ...choice, acknowledge })
+            else await acknowledge(null).catch(err => log(`a press was not answered — ${said(err)}`))
+          } else {
+            const message = normalize(update, bot, me)
+            if (message) await onMessage(message)
+          }
           offset = update.update_id + 1
         }
       }
@@ -244,6 +280,30 @@ export function createAdapter ({ telegram, bot, me }) {
 
     react: (conversation, message, emoji) => telegram.react(Number(conversation), message, emoji),
 
-    typing: (conversation) => telegram.typing(Number(conversation))
+    typing: (conversation) => telegram.typing(Number(conversation)),
+
+    checkBody: (native) => {
+      const fits = Object.keys(native).every(key => key === 'html') && typeof native.html === 'string' && native.html.trim() !== '' && native.html.length <= 4096
+      return fits ? null : BODY
+    },
+
+    /** The question, each choice a button on its own row, coloured where it has a style. */
+    ask: async (conversation, shown, choices) => {
+      const text = htmlOf(shown)
+      const keyboard = choices.map(choice => [{ text: choice.label, callback_data: choice.data, ...(choice.style ? { style: STYLES[choice.style] } : {}) }])
+      const message = await telegram.ask(Number(conversation), text, keyboard)
+      return { note: message.message_id, shown: { text, parse_mode: 'HTML', reply_markup: { inline_keyboard: keyboard } } }
+    },
+
+    /** The question closed: replaced by `native` or `fallback`, or kept as `shown` with how it ended below. */
+    settle: async (conversation, note, replacement) => {
+      const text = replacement.shown ? `${replacement.shown.text}\n\n<b>${escape(replacement.outcome)}</b>` : htmlOf(replacement)
+      try {
+        await telegram.close(Number(conversation), Number(note), text)
+      } catch (err) {
+        if (!NOT_MODIFIED.test(err.detail ?? '')) throw err
+      }
+      return { text, parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } }
+    }
   }
 }

package/src/api.js

@@ -49,7 +49,7 @@ export function createTelegram (token, { fetchImpl = fetch, base = BASE } = {})
   return {
     /** `offset` confirms every update before it to Telegram. */
     updates: (offset, { seconds = 30, signal } = {}) =>
-      call('getUpdates', { offset, timeout: seconds, allowed_updates: ['message'] }, { timeoutMs: (seconds + 15) * 1000, signal }),
+      call('getUpdates', { offset, timeout: seconds, allowed_updates: ['message', 'callback_query'] }, { timeoutMs: (seconds + 15) * 1000, signal }),
 
     say: (chat, text, { answering = null, html = false } = {}) => call('sendMessage', {
       chat_id: chat,
@@ -62,6 +62,28 @@ export function createTelegram (token, { fetchImpl = fetch, base = BASE } = {})
     revise: (chat, message, text) =>
       call('editMessageText', { chat_id: chat, message_id: message, text, link_preview_options: { is_disabled: true } }),
 
+    /** A question in Telegram's HTML with `keyboard`, rows of inline buttons, under it. */
+    ask: (chat, html, keyboard) => call('sendMessage', {
+      chat_id: chat,
+      text: html,
+      parse_mode: 'HTML',
+      link_preview_options: { is_disabled: true },
+      reply_markup: { inline_keyboard: keyboard }
+    }),
+
+    /** A question's text replaced, and its buttons gone. */
+    close: (chat, message, html) => call('editMessageText', {
+      chat_id: chat,
+      message_id: message,
+      text: html,
+      parse_mode: 'HTML',
+      link_preview_options: { is_disabled: true },
+      reply_markup: { inline_keyboard: [] }
+    }),
+
+    /** A press answered, with `text` as the short notice Telegram shows, or none. */
+    answer: (query, text) => call('answerCallbackQuery', { callback_query_id: query, ...(text ? { text } : {}) }),
+
     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. */

package/src/format.js

@@ -9,7 +9,7 @@ import { Lexer } from 'marked'
 
 const LINKABLE = /^(https?:|mailto:|tg:)/i
 
-const escape = (text) => String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+export 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('')