@rhizogrip/spore-plugin-telegram 0.7.0 → 0.8.0

package/README.md

@@ -8,7 +8,7 @@ no `spore plugin allow`: `spore service` offers it once it is installed.
 npm i -g @rhizogrip/spore-plugin-telegram
 echo 'TRIAGE_BOT_TOKEN=…' >> ~/.config/spore/environment     # from @BotFather; it never reaches a spore
 mkdir -p ~/.config/spore/telegram
-echo '{"token": "${TRIAGE_BOT_TOKEN}", "chats": {"148392011": "triage"}}' > ~/.config/spore/telegram/triage.json
+echo '{"token": "${TRIAGE_BOT_TOKEN}", "people": {"148392011": "triage"}}' > ~/.config/spore/telegram/triage.json
 spore service define telegram@triage && spore service start telegram@triage
 ```
 
@@ -19,9 +19,9 @@ cannot read, or while another process reads the same bot's updates.
 ## One bot per file
 
 Each bot is a file, `~/.config/spore/telegram/<bot>.json`, and a service instance of its
-own, `telegram@<bot>`: its name, its avatar, its token, its chats and its state. A spore that
-should have a face of its own on Telegram gets its own bot. One bot may still reach several
-spores, and one spore may be reached through several bots. A chat of a bot is
+own, `telegram@<bot>`: its name, its avatar, its token, its people and groups, and its state. A
+spore that should have a face of its own on Telegram gets its own bot. One bot may still reach
+several spores, and one spore may be reached through several bots. A chat of a bot is
 `telegram:<bot>/<chat id>` wherever spore names a place an answer goes. No bot's token is
 passed to a spore's runner.
 
@@ -45,8 +45,9 @@ passed to a spore's runner.
 
 ## A turn in a chat
 
-Write to the bot and the message goes to the spore the chat is mapped to, which is told who
-wrote it and where — your name and username, the private chat or the group. The bot posts
+Write to the bot in private and the message goes to the spore your id is mapped to; in a group,
+mention it or reply to it (below). The spore is told who 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`. The
@@ -93,10 +94,19 @@ A turn started with `spore send` is shown only there; no chat is told.
 
 ## The allow-list is the routing
 
-A bot's `chats` say which chats may talk to it and which spore each reaches, as
-`{ "<chat id>": "<spore>" }`. They are read on every message and followed as they change, so
-a chat is added, moved or removed by editing a line. It lives beside `config.json` and
-`sources.json`. Spores cannot read or change it.
+A bot's `people` say who may talk to it in private and which spore each reaches, as
+`{ "<user id>": "<spore>" }` — a private chat's id is its person's. Its `groups` say which groups
+it serves, each with its spore and who there may address it:
+
+```json
+{ "token": "${TRIAGE_BOT_TOKEN}",
+  "people": { "148392011": "triage" },
+  "groups": { "-1001234567": { "spores": ["triage"], "people": ["148392011", "*"] } } }
+```
+
+Both are read on every message and followed as they change, so a person or a group is added,
+moved or removed by editing a line. The file lives beside `config.json` and `sources.json`. Spores
+cannot read or change it.
 
 While a turn works, its chat is shown what kind of call ran — `reading a file`, `running a
 command`, `asking forgejo` by the source's name, a run of the same one counted, a slow one
@@ -104,12 +114,12 @@ timed, a command that exited non-zero given its exit code, a call that failed ma
 machine, and a command line or a path is yours. A chat can ask for the calls themselves:
 
 ```json
-{ "token": "${TRIAGE_BOT_TOKEN}", "chats": { "148392011": { "spore": "triage", "details": true } } }
+{ "token": "${TRIAGE_BOT_TOKEN}", "people": { "148392011": { "spore": "triage", "details": true } } }
 ```
 
 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.
+read the commands; the others keep the kinds. A group takes `"details": true` the same way.
 
 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
@@ -120,7 +130,7 @@ Telegram lets a bot react with (✅ and ❌ are not among them; the log lists th
 
 ```json
 { "token": "${OPS_BOT_TOKEN}", "react": { "taken": "👀", "failed": "🤷" },
-  "chats": { "-1001234567": { "spore": "triage", "show": "react" } } }
+  "people": { "148392011": { "spore": "triage", "show": "react" } } }
 ```
 
 Two chats may point at one spore and then share its conversation. A reply goes to the
@@ -129,13 +139,41 @@ chat that asked; a turn nobody in a chat started goes to the spore's default.
 A chat not in the file gets silence, and the log gets the line to add:
 
 ```
-refused chat 148392011 (@alice) — to allow it, add "148392011": "<a spore>" to the chats of …/telegram/triage.json
+refused chat 148392011 (@alice) — to allow it, add "148392011": "<a spore>" to the people of …/telegram/triage.json
+```
+
+which is also how you learn your own user id: start with `"people": {}` and message the bot. A
+group the file does not name is told nothing either, when someone there mentions the bot; the log
+says the `groups` entry to add, its id negative. Where a spore's `replyTo` default is one of this
+bot's chats, that chat is told the same line, once per chat the file does not name, so you hear of
+someone trying the bot without reading its log.
+
+## A group
+
+A group has one spore — in a group the bot speaks as itself, so a second spore there is a second
+bot — and `people`, who may address it: user ids, or `"*"` for everyone in the group, written out.
+A message reaches the spore when it mentions the bot (`@triage_bot what failed?`), replies to one of
+its messages, or is a command for it — `/status`, or `/status@triage_bot` where several bots share
+the group; a command naming another bot is not seen. Anything else said there is not for the
+spore, and the bot's mention is not part of what the spore is told. Someone the entry does not list
+who mentions the bot gets silence, and the log gets the line that would let them in.
+
+`/status` is for anyone listed; `/stop`, `/wrap` and `/extend` are for the people the entry names
+by id — not everyone `"*"` lets talk — and anyone else is told so.
+
+A group can let its spore hear what is said there that is not to it:
+
+```json
+"groups": { "-1001234567": { "spores": ["triage"], "people": ["148392011", "209876543"], "overhear": true } }
 ```
 
-which is also how you learn your own chat id: start with `"chats": {}` and message the bot. A
-group's id is negative, and it is the group you add rather than the people in it. Where a spore's
-`replyTo` default is one of this bot's chats, that chat is told the same line, once per chat the
-file does not name, so you hear of someone trying the bot without reading its log.
+What the people it lists say in the group then reaches the spore as overheard: no turn starts for
+it and no answer is owed, and the next turn the spore runs reads it as what was said around it, the
+latest 100 messages at a time. It is everything they say there, kept in the spore's records and
+read by its next turn, so choose it for a group whose talk the spore should follow. Telegram gives a
+bot what is not said to it only with its privacy mode off — `/setprivacy` in @BotFather, then the
+bot added to the group again — or as an admin of the group; with neither, the service says so for
+each group that overhears when it starts.
 
 ## What it keeps
 

package/bin/spore-telegram.js

@@ -14,6 +14,6 @@ await runService({
   open: async ({ bot, credentials }) => {
     const telegram = createTelegram(credentials.token)
     const me = await telegram.me()
-    return { adapter: createAdapter({ telegram, bot }), who: `@${me.username}` }
+    return { adapter: createAdapter({ telegram, bot, me }), who: `@${me.username}` }
   }
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizogrip/spore-plugin-telegram",
-  "version": "0.7.0",
+  "version": "0.8.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.20.0"
+    "@rhizogrip/spore": "^1.21.0"
   },
   "scripts": {
     "test": "vitest run"
   },
   "spore": {
-    "works": "^1.20.0",
+    "works": "^1.21.0",
     "services": {
       "telegram": {
         "what": "a bot of yours in Telegram chats, each chat reaching its spore",

package/src/adapter.js

@@ -1,7 +1,7 @@
 /**
  * Telegram for the relay (`@rhizogrip/spore/relay`): the bot file it reads, the long poll that
- * hears chats, and the Bot API calls that answer them. A chat is a conversation, keyed by its id;
- * the bot file maps each to the spore it reaches.
+ * hears chats, and the Bot API calls that answer them. A chat is a conversation, keyed by its id:
+ * a private chat's is its person's, under `people`, and a group's is negative, under `groups`.
  */
 
 import { SporeError } from '@rhizogrip/spore'
@@ -11,7 +11,8 @@ 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
+const SHAPE = '{ "token": "${TRIAGE_BOT_TOKEN}", "people": { "<your user id>": "<spore>" }, "groups": { "<group id>": { "spores": ["<spore>"], "people": ["<user id>"] } } }' // eslint-disable-line no-template-curly-in-string
+const VERBS = new Set(['status', 'stop', 'wrap', 'extend', 'help'])
 
 /** What a bot may react with: `ReactionTypeEmoji` in the Bot API. */
 const REACTIONS = [
@@ -25,40 +26,75 @@ const REACTIONS = [
   '🤷', '🤷‍♀', '😡'
 ]
 
-const FIELDS = ['token', 'chats', 'react']
-const CHAT_FIELDS = ['spore', 'details', 'show']
+const FIELDS = ['token', 'people', 'groups', 'react']
+const PERSON_FIELDS = ['spore', 'details', 'show']
+const GROUP_FIELDS = ['spores', 'people', 'details', 'show', 'overhear']
+const PERSON = /^\d+$/
+const GROUP = /^-\d+$/
 
 const said = (err) => [err.message, err.detail].filter(Boolean).join(' — ')
 
-const invalid = (path, problem, detail) => new SporeError(`${path} ${problem}`, { type: 'TELEGRAM_BOT_INVALID', detail })
+const invalid = (path, problem, detail = `a bot is ${SHAPE}`) => new SporeError(`${path} ${problem}`, { type: 'TELEGRAM_BOT_INVALID', detail })
+
+const strays = (path, kind, id, entry, takes) => {
+  const extra = Object.keys(entry).filter(key => !takes.includes(key))
+  if (!extra.length) return
+  const bots = extra.filter(key => FIELDS.includes(key))
+  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 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`)
+  }
+}
 
 /**
- * `{ "<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.
+ * 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.
  */
 function routes (raw, path) {
-  if (typeof raw.chats !== 'object' || raw.chats === null || Array.isArray(raw.chats)) {
-    throw invalid(path, 'has no chats', 'chats is { "<chatId>": "<spore>" } — {} while you learn your chat id: the log names every chat it refuses')
+  if (raw.people === undefined && raw.groups === undefined) {
+    throw invalid(path, 'has no people and no groups', `a bot is ${SHAPE} — "people": {} while you learn your user id: the log names every chat it refuses`)
+  }
+  const entries = (field) => {
+    const value = raw[field] ?? {}
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) throw invalid(path, `has ${field} that is not { "<id>": … }`)
+    return Object.entries(value)
   }
   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 => !CHAT_FIELDS.includes(key)) : []
-    if (extra.length) {
-      const bots = extra.filter(key => FIELDS.includes(key))
-      throw invalid(path, `gives chat ${chat} ${extra.join(', ')}, which a chat does not take`, `a chat takes ${CHAT_FIELDS.join(', ')}${bots.length ? `; ${bots.join(', ')} is the bot's, beside chats` : ''}`)
+  for (const [person, entry] of entries('people')) {
+    if (!PERSON.test(person)) throw invalid(path, `names "${person}" among its people, which is not a person's id`, 'a person\'s id is a positive number; a group\'s is negative, and goes under groups')
+    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'])
     }
-    if (typeof spore !== 'string' || !spore || (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, "show": "react" }')
+    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 })
+  }
+  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'])
+    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(chat, { spores: [spore], details: typeof entry === 'object' && entry.details === true, show: typeof entry === 'object' ? entry.show ?? null : null, people: null })
+    table.set(group, { spores: entry.spores, details: entry.details === true, show: entry.show ?? null, people: entry.people, overhear: entry.overhear === true })
   }
   return table
 }
 
-const HELP = 'Anything you write here goes to the spore. /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; /extend wall 30m gives it more, as far as its spore.cmk allows.'
 
 export const TELEGRAM = {
   kind: 'telegram',
@@ -79,23 +115,44 @@ export const TELEGRAM = {
   hint (err, { file, bot }) {
     if (err.type === 'TELEGRAM_NO_BOT') {
       const variable = `${bot.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_BOT_TOKEN`
-      return `mkdir -p ${file.slice(0, file.lastIndexOf('/'))} && echo '{"token": "$\{${variable}}", "chats": {}}' > ${file}\n  with chats {}, start the bot and message it — the log names every chat it refuses, with its id`
+      return `mkdir -p ${file.slice(0, file.lastIndexOf('/'))} && echo '{"token": "$\{${variable}}", "people": {}}' > ${file}\n  with people {}, start the bot and message it — the log names every chat it refuses, with its id`
     }
     if (err.type === 'TELEGRAM_FAILED') return `the token comes from @BotFather, in the variable ${file} names`
     if (err.type === 'TELEGRAM_CONFLICT') return 'one bot token is read by one process — stop the other one, or remove its webhook'
     return null
   },
-  refusal: (message, botFile) =>
-    `refused chat ${message.conversation}${message.person.username ? ` (@${message.person.username})` : ''} — to allow it, add "${message.conversation}": "<a spore>" to the chats of ${botFile}`
+  refusal: (message, botFile) => message.shared
+    ? `refused ${message.where}, chat ${message.conversation} — to allow it, add "${message.conversation}": { "spores": ["<a spore>"], "people": ["${message.person.id}"] } to the groups of ${botFile}`
+    : `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']
 
-export function normalize (update, bot) {
+/** Whether the bot's own `@username` is among what Telegram marked as mentions. */
+const mentions = (message, me) => {
+  const source = message.text ?? message.caption ?? ''
+  const own = `@${me.username}`.toLowerCase()
+  return (message.entities ?? message.caption_entities ?? [])
+    .some(entity => entity.type === 'mention' && source.slice(entity.offset, entity.offset + entity.length).toLowerCase() === own)
+}
+
+/**
+ * An update as the relay takes it, or null for none it takes: what is not a chat message, and a
+ * command naming another bot. In a group, a message reaches the spore when it mentions the bot,
+ * replies to one of its messages, or is a command for it — one of the relay's verbs, or one naming
+ * this bot; anything else names no spore (`addresses: []`). The bot's mention is not part of what
+ * was said to the spore.
+ */
+export function normalize (update, bot, me) {
   const message = update.message
   if (message?.chat?.id === undefined) return null
-  const text = (message.text ?? message.caption ?? '').trim() || null
-  const command = text?.match(COMMAND)
+  const written = (message.text ?? message.caption ?? '').trim() || null
+  const command = written?.match(COMMAND)
+  if (command?.[2] && command[2].slice(1).toLowerCase() !== me.username.toLowerCase()) return null
+  const shared = message.chat.type !== 'private'
+  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}`,
@@ -103,19 +160,27 @@ export function normalize (update, bot) {
     message: message.message_id,
     person: { id: String(message.from.id), name: `${[first, last].filter(Boolean).join(' ')}${username ? ` (@${username})` : ''}`, username, groups: [] },
     spore: null,
-    where: message.chat.type === 'private' ? 'a private chat on Telegram' : `the Telegram group "${message.chat.title}"`,
-    shared: message.chat.type !== 'private',
+    where: shared ? `the Telegram group "${message.chat.title}"` : 'a private chat on Telegram',
+    shared,
     text,
     command: command ? { verb: command[1].toLowerCase(), args: command[3] ?? '' } : null,
-    addresses: null,
+    addresses: addressed ? null : [],
     files: FILES.filter(kind => message[kind]).length
   }
 }
 
-export function createAdapter ({ telegram, bot }) {
+export function createAdapter ({ telegram, bot, me }) {
   return {
     ...TELEGRAM,
 
+    /** Each group that overhears, said when the bot gets only what is addressed to it. */
+    prepare: async (table, log) => {
+      if (me.can_read_all_group_messages) return
+      for (const [group, { overhear }] of table) {
+        if (overhear) log(`group ${group} overhears, and @${me.username} gets only what is said to it there: turn its privacy mode off with /setprivacy in @BotFather and add it to the group again, or make it an admin of the group`)
+      }
+    },
+
     /**
      * 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
@@ -141,7 +206,7 @@ export function createAdapter ({ telegram, bot }) {
           continue
         }
         for (const update of updates) {
-          const message = normalize(update, bot)
+          const message = normalize(update, bot, me)
           if (message) await onMessage(message)
           offset = update.update_id + 1
         }