@rhizogrip/spore-plugin-telegram 0.8.1 → 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
@@ -121,6 +132,15 @@ 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 group takes `"details": true` the same way.
 
+A bot that serves people who should see their answers and not the machinery — your customers, say —
+takes `"brief": true` beside `people` and `groups`: each chat is then told its spore's state and its
+answers, and nothing of how it runs. `/status` says `working`, `idle`, `paused` or how many messages
+wait — never the model, the spend, the turns or the limits; an answer comes without how the turn
+ended, a turn with none says `no answer this time` and the log says why; a limit reached shows as
+`wrapping up`; and `/extend` is not offered, since what a turn may spend is yours. A person or a
+group takes `"brief"` as well, `false` to be told everything in a brief bot; `details` is refused
+beside it.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizogrip/spore-plugin-telegram",
-  "version": "0.8.1",
+  "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.21.0"
+    "@rhizogrip/spore": "^1.24.0"
   },
   "scripts": {
     "test": "vitest run"
   },
   "spore": {
-    "works": "^1.21.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/
@@ -27,10 +27,12 @@ const REACTIONS = [
 ]
 
 const FIELDS = ['token', 'people', 'groups', 'react']
-const PERSON_FIELDS = ['spore', 'details', 'show']
-const GROUP_FIELDS = ['spores', 'people', 'details', 'show', 'overhear']
+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(' — ')
 
@@ -43,6 +45,8 @@ const strays = (path, kind, id, entry, takes) => {
   throw invalid(path, `gives ${kind} ${id} ${extra.join(', ')}, which a ${kind} does not take`, `a ${kind} takes ${takes.join(', ')}${bots.length ? `; ${bots.join(', ')} is the bot's, beside people and groups` : ''}`)
 }
 
+const briefOf = (entry) => typeof entry.brief === 'boolean' ? entry.brief : null
+
 const flags = (path, kind, id, entry, names) => {
   for (const name of names) {
     if (entry[name] !== undefined && typeof entry[name] !== 'boolean') throw invalid(path, `has a ${kind} ${id} whose ${name} is not true or false`)
@@ -50,13 +54,14 @@ const flags = (path, kind, id, entry, names) => {
 }
 
 /**
- * The private chats, `people: { "<person id>": "<spore>" }` or `{ "spore", "details", "show" }`,
- * and the groups, `groups: { "<group id>": { "spores": ["<spore>"], "people": [...], "details",
- * "show", "overhear" } }`. `details` shows a chat 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` how a turn
- * shows itself there. A group names who may address its spore — user ids, or `*` for everyone in it
- * — and has one spore: in a group a bot speaks as itself, so a second spore is a second bot.
- * `overhear` gives the spore what they say there that is not to it.
+ * The private chats, `people: { "<person id>": "<spore>" }` or `{ "spore", "details", "show",
+ * "brief" }`, and the groups, `groups: { "<group id>": { "spores": ["<spore>"], "people": [...],
+ * "details", "show", "overhear", "brief" } }`. `details` shows a chat 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` how a turn shows itself there; `brief` the bot's own, for this chat. A group names
+ * who may address its spore — user ids, or `*` for everyone in it — and has one spore: in a group a
+ * bot speaks as itself, so a second spore is a second bot. `overhear` gives the spore what they say
+ * there that is not to it.
  */
 function routes (raw, path) {
   if (raw.people === undefined && raw.groups === undefined) {
@@ -73,28 +78,29 @@ function routes (raw, path) {
     const shaped = typeof entry === 'object' && entry !== null && !Array.isArray(entry)
     if (shaped) {
       strays(path, 'person', person, entry, PERSON_FIELDS)
-      flags(path, 'person', person, entry, ['details'])
+      flags(path, 'person', person, entry, ['details', 'brief'])
     }
     const spore = shaped ? entry.spore : entry
     if (typeof spore !== 'string' || !spore) throw invalid(path, `maps person ${person} to something that is not a spore`, 'each person is their id against the name of the spore they reach, or { "spore": "<name>", "details": true, "show": "react" }')
-    table.set(person, { spores: [spore], details: shaped && entry.details === true, show: shaped ? entry.show ?? null : null, people: null, overhear: false })
+    table.set(person, { spores: [spore], details: shaped && entry.details === true, show: shaped ? entry.show ?? null : null, brief: shaped ? briefOf(entry) : null, people: null, overhear: false })
   }
   for (const [group, entry] of entries('groups')) {
     if (!GROUP.test(group)) throw invalid(path, `names "${group}" among its groups, which is not a group's id`, 'a group\'s id is negative (-100… for a supergroup); a person\'s goes under people')
     if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) throw invalid(path, `has a group ${group} that is not { "spores": [...], "people": [...] }`)
     strays(path, 'group', group, entry, GROUP_FIELDS)
-    flags(path, 'group', group, entry, ['details', 'overhear'])
+    flags(path, 'group', group, entry, ['details', 'overhear', 'brief'])
     if (!Array.isArray(entry.spores) || !entry.spores.length || !entry.spores.every(spore => typeof spore === 'string' && spore)) throw invalid(path, `has a group ${group} with no spores`)
     if (entry.spores.length > 1) throw invalid(path, `gives group ${group} ${entry.spores.length} spores`, 'a bot speaks in a group as itself, so a group has one spore — a second spore there is a second bot')
     if (!Array.isArray(entry.people) || !entry.people.every(who => who === '*' || (typeof who === 'string' && PERSON.test(who)))) {
       throw invalid(path, `has a group ${group} whose people are not user ids or *`, 'people is who may address its spore — ["<user id>", …], or ["*"] for everyone in the group, written out')
     }
-    table.set(group, { spores: entry.spores, details: entry.details === true, show: entry.show ?? null, people: entry.people, overhear: entry.overhear === true })
+    table.set(group, { spores: entry.spores, details: entry.details === true, show: entry.show ?? null, brief: briefOf(entry), people: entry.people, overhear: entry.overhear === true })
   }
   return table
 }
 
-const HELP = 'Anything you write to me in private goes to the spore; in a group, mention me or reply to me. /status says what it is doing; /stop ends the turn it is running and sets aside what you sent that it had not read; /wrap [10m] asks it to wrap up; /extend wall 30m gives it more, as far as its spore.cmk allows.'
+const HELP = 'Anything you write to me in private goes to the spore; in a group, mention me or reply to me. /status says what it is doing; /stop ends the turn it is running and sets aside what you sent that it had not read; /wrap [10m] asks it to wrap up'
+const EXTEND = '/extend wall 30m gives it more, as far as its spore.cmk allows'
 
 export const TELEGRAM = {
   kind: 'telegram',
@@ -107,9 +113,9 @@ export const TELEGRAM = {
   refusals: ['TELEGRAM_CONFLICT'],
   example: SHAPE,
   routes,
-  usage: { help: HELP, extend: '/extend wall 30m, /extend cost 1.50 or /extend rounds 20' },
+  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 }) {
@@ -128,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 ?? ''
@@ -153,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,
@@ -183,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) {
@@ -207,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
         }
       }
@@ -240,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('')