@rhizogrip/spore-plugin-telegram 0.8.0 → 0.9.0

package/README.md

@@ -121,6 +121,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
@@ -143,8 +152,8 @@ refused chat 148392011 (@alice) — to allow it, add "148392011": "<a spore>" to
 ```
 
 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
+group the file does not name is told nothing either, when someone there writes `/status@<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.
 
@@ -152,11 +161,14 @@ someone trying the bot without reading its log.
 
 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.
+A message reaches the spore when it replies to one of the bot's messages, is a command for it —
+`/status`, or `/status@triage_bot` where several bots share the group; a command naming another bot
+is not seen — or mentions the bot (`@triage_bot what failed?`). Telegram hands a bot a mention 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 of its groups when it starts.
+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 addresses 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.
@@ -170,10 +182,8 @@ A group can let its spore hear what is said there that is not to it:
 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.
+read by its next turn, so choose it for a group whose talk the spore should follow. It needs the
+bot's privacy mode off, or the bot an admin of the group, as a mention does.
 
 ## What it keeps
 

package/package.json

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

package/src/adapter.js

@@ -27,8 +27,8 @@ 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+$/
 
@@ -43,6 +43,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 +52,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 +76,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,7 +111,7 @@ 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 },
   showShared: 'react',
@@ -173,11 +177,12 @@ export function createAdapter ({ telegram, bot, me }) {
   return {
     ...TELEGRAM,
 
-    /** Each group that overhears, said when the bot gets only what is addressed to it. */
+    /** Each group, said when the bot's privacy mode keeps mentions — and what it would overhear — from 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`)
+        if (Number(group) >= 0) continue
+        log(`group ${group}: @${me.username} gets only commands for it and replies to its messages there, no mention${overhear ? ' and nothing to overhear' : ''} — turn its privacy mode off with /setprivacy in @BotFather and add it to the group again, or make it an admin of the group`)
       }
     },