@rhizogrip/spore-plugin-telegram 0.9.0 → 0.11.0

package/README.md

@@ -73,8 +73,12 @@ says so in your `working…` message, and the next turn answers it.
 /extend wall 30m   give it more — wall, cost or rounds — up to the extend.<limit> its spore.cmk grants
 ```
 
-Only text reaches a spore for now: a photo's or a document's caption goes to it, and you are told
-the file did not; a message with nothing written in it is told only text reaches a spore.
+A photo, a document, a voice note, a video or a sticker reaches the spore with its caption, fetched
+by the service up to the 20 MB Telegram lets a bot fetch, or the bot file's `"files": "10MB"` —
+`false` takes none. An album is one message: its parts are held until none has come for a second,
+and confirmed to Telegram only once the spore has them all. A file that does not come is told to
+you, and to the spore, with why. In a group that overhears, what is sent around the spore is named
+to it and not fetched.
 
 ## Turns nobody in a chat started
 
@@ -92,6 +96,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.11.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.26.0"
   },
   "scripts": {
     "test": "vitest run"
   },
   "spore": {
-    "works": "^1.23.0",
+    "works": "^1.26.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,10 @@ 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 FETCH_MOST = 20 * 1024 * 1024
+const ALBUM_QUIET_MS = 1000
+const BODY = 'a Telegram body is { "html": "<Telegram\'s HTML, at most 4096 characters>" }'
 
 const said = (err) => [err.message, err.detail].filter(Boolean).join(' — ')
 
@@ -112,8 +116,8 @@ export const TELEGRAM = {
   example: SHAPE,
   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 },
+  limits: { message: 4096, file: 50 * 1024 * 1024, fetch: FETCH_MOST, editEveryMs: 2500, typingEveryMs: 4000 },
+  can: { upload: true, remove: true, react: true, typing: true, reply: true, choose: true },
   showShared: 'react',
   reactions: REACTIONS,
   hint (err, { file, bot }) {
@@ -130,7 +134,67 @@ export const TELEGRAM = {
     : `refused chat ${message.conversation}${message.person.username ? ` (@${message.person.username})` : ''} — to allow it, add "${message.conversation}": "<a spore>" to the people of ${botFile}`
 }
 
-const FILES = ['photo', 'document', 'video', 'audio', 'voice', 'video_note', 'animation', 'sticker']
+const KINDS = {
+  document: (file) => [file.mime_type ?? null, ''],
+  video: (file) => [file.mime_type ?? 'video/mp4', '.mp4'],
+  audio: (file) => [file.mime_type ?? 'audio/mpeg', '.mp3'],
+  animation: (file) => [file.mime_type ?? 'video/mp4', '.mp4'],
+  voice: (file) => [file.mime_type ?? 'audio/ogg', '.ogg'],
+  video_note: () => ['video/mp4', '.mp4'],
+  sticker: (file) => file.is_animated ? ['application/x-tgsticker', '.tgs'] : file.is_video ? ['video/webm', '.webm'] : ['image/webp', '.webp']
+}
+
+/**
+ * The files a message carries, as the relay lists them: the largest size of a photo, and the one
+ * file of any other kind, each under its own name or one made of its kind and Telegram's id for
+ * it. One Telegram will not let a bot fetch is listed with why.
+ */
+function filesOf (message) {
+  const found = []
+  const photo = message.photo?.at(-1)
+  if (photo) found.push({ name: `photo-${photo.file_unique_id}.jpg`, mime: 'image/jpeg', bytes: photo.file_size ?? null, id: photo.file_id })
+  for (const [kind, typed] of Object.entries(KINDS)) {
+    const file = message[kind]
+    if (!file) continue
+    const [mime, extension] = typed(file)
+    found.push({ name: file.file_name ?? `${kind.replace('_', '-')}-${file.file_unique_id}${extension}`, mime, bytes: file.file_size ?? null, id: file.file_id })
+  }
+  return found.map(({ id, ...file }) => file.bytes !== null && file.bytes > FETCH_MOST
+    ? { ...file, ref: null, why: 'Telegram lets a bot fetch files up to 20 MB' }
+    : { ...file, ref: id })
+}
+
+/** An album's parts as one message: what its captioned part said, and every part's files. */
+export function merged (messages) {
+  const said = messages.find(message => message.text !== null) ?? messages[0]
+  return { ...said, files: messages.flatMap(message => message.files), addresses: messages.some(message => message.addresses === null) ? null : [] }
+}
+
+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) => {
@@ -157,19 +221,18 @@ 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,
     addresses: addressed ? null : [],
-    files: FILES.filter(kind => message[kind]).length
+    files: filesOf(message)
   }
 }
 
@@ -187,17 +250,40 @@ 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. An album's parts are held, unconfirmed, until none has come for
+     * a second, and handed on as one message.
      */
-    async listen ({ onMessage, signal, log, sleep }) {
+    async listen ({ onMessage, onChoice, signal, log, sleep }) {
       let offset
+      let seen = -1
+      let album = null
       let backoff = 1000
+      const take = async (update) => {
+        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)}`))
+          return
+        }
+        const message = normalize(update, bot, me)
+        if (message) await onMessage(message)
+      }
+      const flush = async () => {
+        const { parts } = album
+        album = null
+        const messages = parts.map(update => normalize(update, bot, me)).filter(Boolean)
+        if (messages.length) await onMessage(merged(messages))
+        offset = parts.at(-1).update_id + 1
+      }
       while (!signal.aborted) {
         let updates
         try {
-          updates = await telegram.updates(offset, { signal })
+          updates = await telegram.updates(offset, { seconds: album ? 0 : 30, signal })
           backoff = 1000
         } catch (err) {
           if (signal.aborted) break
@@ -210,11 +296,21 @@ export function createAdapter ({ telegram, bot, me }) {
           backoff = Math.min(backoff * 2, 60_000)
           continue
         }
-        for (const update of updates) {
-          const message = normalize(update, bot, me)
-          if (message) await onMessage(message)
+        const fresh = updates.filter(update => update.update_id > seen)
+        if (album && !fresh.some(update => update.message?.media_group_id === album.id)) await flush()
+        for (const update of fresh) {
+          seen = update.update_id
+          const group = update.message?.media_group_id
+          if (album && group !== album.id) await flush()
+          if (group) {
+            album ??= { id: group, parts: [] }
+            album.parts.push(update)
+            continue
+          }
+          await take(update)
           offset = update.update_id + 1
         }
+        if (album) await sleep(ALBUM_QUIET_MS)
       }
       if (offset !== undefined) {
         await telegram.updates(offset, { seconds: 0 }).catch(err => log(`could not confirm the last updates — ${said(err)}`))
@@ -244,6 +340,32 @@ 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)),
+
+    fetch: async (ref, { most }) => telegram.download((await telegram.file(ref)).file_path, { most }),
+
+    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

@@ -8,6 +8,7 @@ import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 
 import { SporeError } from '@rhizogrip/spore'
+import { download } from '@rhizogrip/spore/relay'
 
 const BASE = 'https://api.telegram.org'
 
@@ -49,7 +50,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 +63,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. */
@@ -78,6 +101,12 @@ export function createTelegram (token, { fetchImpl = fetch, base = BASE } = {})
       return call('sendDocument', form, { timeoutMs: 300_000 })
     },
 
-    me: () => call('getMe')
+    me: () => call('getMe'),
+
+    /** Where Telegram keeps a file a person sent: `{ file_path, file_size }`. */
+    file: (id) => call('getFile', { file_id: id }),
+
+    /** A file's bytes by its `file_path`, refused past `most`. */
+    download: (path, { most }) => download(`${base}/file/bot${token}/${path}`, { most, fetchImpl })
   }
 }

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('')