@rhizogrip/spore-plugin-teams 0.1.0 → 0.2.0

package/README.md

@@ -18,12 +18,25 @@ spore service define teams@ops && spore service start teams@ops
 
 ## The bot
 
-Teams reaches a bot through Azure: an **Azure Bot**, single-tenant, whose app registration in
-Entra ID gives the bot file its `app` (the Microsoft App ID), its `tenant`, and a client secret,
-kept in `environment` under the variable `secret` names. The Azure Bot's messaging endpoint is a
-public HTTPS address of yours ending in `/api/messages`, which your proxy forwards to `listen` —
-a loopback address: the service never faces the internet itself. Turn on the Azure Bot's Teams
-channel, and install a Teams app for the bot in your tenant with the personal and team scopes.
+Teams reaches a bot through Azure: an **Azure Bot**, made in the Azure portal with *Single Tenant*
+as its type and a new Microsoft App ID — Microsoft no longer makes multi-tenant bots, and the
+service asks your tenant for its token. Its app registration in Entra ID gives the bot file its
+`app` (the Microsoft App ID), its `tenant`, and a client secret — the secret's value, kept in
+`environment` under the variable `secret` names. The Azure Bot's messaging endpoint is a public
+HTTPS address of yours, which your proxy forwards to `listen` — a loopback address: the service
+never faces the internet itself. With nginx, a path per bot:
+
+```nginx
+location = /ops/api/messages { proxy_pass http://127.0.0.1:3978/api/messages; }
+```
+
+Turn on the Azure Bot's Microsoft Teams channel. Then a Teams app for the bot, in the Teams
+Developer Portal: under App features, a bot with the Microsoft App ID, in the personal and team
+scopes. A manifest of version 1.25 or later with the team scope must say
+`"supportsChannelFeatures": "tier1"`, or Teams refuses the package; it lets the app into private
+and shared channels too, which the service does not serve yet, so leave it out of those. Publish
+it to your organization and approve it in the Teams admin center, under Manage apps: an app
+uploaded for one person can stay blocked by the tenant's app policies.
 
 Every activity is checked before it is read: a token Microsoft signed for this app id, with a key
 it endorses for Teams, for the `serviceUrl` the activity names. One that fails is answered 401 and
@@ -47,6 +60,14 @@ the channel, written out. A channel has one spore: the bot speaks there as itsel
 is a second bot. `details` shows the calls themselves in the `working…` message rather than their
 kinds. The file is read on every message, so a person or a channel is added by editing a line.
 
+A bot that serves people who should see their answers and not the machinery takes `"brief": true`
+beside `people` and `channels`: each conversation 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 channel takes
+`"brief"` as well, `false` to be told everything in a brief bot; `details` is refused beside it.
+
 Someone not in the file gets silence, and the log gets the line to add:
 
 ```
@@ -61,7 +82,8 @@ In a personal chat, anything written reaches the spore. In a channel, a message
 it mentions the bot, and the mention is not part of what the spore is told; the spore is told who
 wrote and where. The bot posts `working…` and shows what kind of call runs as it runs; the answer
 is a new message — in a channel, in the thread of the message it answers — and `working…` is then
-removed, or marked `answered below` where Teams will not remove it. The answer is sent as Teams
+removed, or marked `answered below` where Teams will not remove it; in a channel thread, Teams shows
+`This message has been deleted.` where it was. The answer is sent as Teams
 markdown. What the turn left in `data/out/` is named, one line a file: files do not cross yet,
 either way.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizogrip/spore-plugin-teams",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Microsoft Teams for spores: a bot of yours in personal chats and channels, each reaching its spore, run as a service",
   "author": {
     "name": "Christophe Le Bars",
@@ -28,13 +28,13 @@
     "NOTICE"
   ],
   "peerDependencies": {
-    "@rhizogrip/spore": "^1.22.0"
+    "@rhizogrip/spore": "^1.23.0"
   },
   "scripts": {
     "test": "vitest run"
   },
   "spore": {
-    "works": "^1.22.0",
+    "works": "^1.23.0",
     "services": {
       "teams": {
         "what": "a bot of yours in Microsoft Teams, each personal chat and channel reaching its spore",

package/src/adapter.js

@@ -8,8 +8,8 @@
 import { SporeError } from '@rhizogrip/spore'
 
 const FIELDS = ['app', 'tenant', 'secret', 'listen', 'people', 'channels']
-const PERSON_FIELDS = ['spore', 'details']
-const CHANNEL_FIELDS = ['spores', 'people', 'details']
+const PERSON_FIELDS = ['spore', 'details', 'brief']
+const CHANNEL_FIELDS = ['spores', 'people', 'details', 'brief']
 const PERSON = /^[0-9a-f][0-9a-f-]*$/i
 const CHANNEL = /^19:[^\s;]+@thread\.[a-z0-9]+$/i
 const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost'])
@@ -22,6 +22,12 @@ const invalid = (path, problem, detail = `a bot is ${SHAPE}`) => new SporeError(
 
 const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
 
+const flags = (path, kind, id, entry) => {
+  for (const name of ['details', 'brief']) {
+    if (entry[name] !== undefined && typeof entry[name] !== 'boolean') throw invalid(path, `has a ${kind} ${id} whose ${name} is not true or false`)
+  }
+}
+
 const strays = (path, kind, id, entry, takes) => {
   const extra = Object.keys(entry).filter(key => !takes.includes(key))
   if (!extra.length) return
@@ -41,9 +47,10 @@ export function listenOf (raw, path) {
 
 /**
  * The bot's app and tenant, where it listens, and its routing: `people`, each person's personal
- * chat by their Entra object id — `"<spore>"` or `{ "spore", "details" }` — and `channels`, each
- * standard channel by its id, with its one spore and who may address it there: object ids, or `*`
- * for everyone in the channel. `details` shows the calls themselves rather than their kinds.
+ * chat by their Entra object id — `"<spore>"` or `{ "spore", "details", "brief" }` — and `channels`,
+ * each standard channel by its id, with its one spore and who may address it there: object ids, or
+ * `*` for everyone in the channel. `details` shows the calls themselves rather than their kinds;
+ * `brief` is the bot's own, for this conversation.
  */
 function routes (raw, path) {
   for (const field of ['app', 'tenant']) {
@@ -63,28 +70,29 @@ function routes (raw, path) {
     if (!PERSON.test(person)) throw invalid(path, `names "${person}" among its people, which is not an Entra object id`, 'a person is their object id in Entra ID; a channel\'s id begins 19: and goes under channels')
     if (record(entry)) {
       strays(path, 'person', person, entry, PERSON_FIELDS)
-      if (entry.details !== undefined && typeof entry.details !== 'boolean') throw invalid(path, `has a person ${person} whose details is not true or false`)
+      flags(path, 'person', person, entry)
     }
     const spore = record(entry) ? 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 object id against the name of the spore they reach, or { "spore": "<name>", "details": true }')
-    table.set(person, { spores: [spore], details: record(entry) && entry.details === true, show: null, people: null, overhear: false })
+    table.set(person, { spores: [spore], details: record(entry) && entry.details === true, show: null, brief: record(entry) ? entry.brief ?? null : null, people: null, overhear: false })
   }
   for (const [channel, entry] of entries('channels')) {
     if (!CHANNEL.test(channel)) throw invalid(path, `names "${channel}" among its channels, which is not a channel id`, 'a channel id is 19:…@thread.tacv2, from the channel\'s link in Teams')
     if (!record(entry)) throw invalid(path, `has a channel ${channel} that is not { "spores": [...], "people": [...] }`)
     strays(path, 'channel', channel, entry, CHANNEL_FIELDS)
-    if (entry.details !== undefined && typeof entry.details !== 'boolean') throw invalid(path, `has a channel ${channel} whose details is not true or false`)
+    flags(path, 'channel', channel, entry)
     if (!Array.isArray(entry.spores) || !entry.spores.length || !entry.spores.every(spore => typeof spore === 'string' && spore)) throw invalid(path, `has a channel ${channel} with no spores`)
     if (entry.spores.length > 1) throw invalid(path, `gives channel ${channel} ${entry.spores.length} spores`, 'a bot speaks in a channel as itself, so a channel 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 channel ${channel} whose people are not object ids or *`, 'people is who may address its spore — ["<object id>", …], or ["*"] for everyone in the channel, written out')
     }
-    table.set(channel, { spores: entry.spores, details: entry.details === true, show: null, people: entry.people, overhear: false })
+    table.set(channel, { spores: entry.spores, details: entry.details === true, show: null, brief: entry.brief ?? null, people: entry.people, overhear: false })
   }
   return table
 }
 
-const HELP = 'Anything you write to me in a personal chat goes to the spore; in a channel, mention 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 a personal chat goes to the spore; in a channel, mention 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 TEAMS = {
   kind: 'teams',
@@ -98,7 +106,7 @@ export const TEAMS = {
   example: SHAPE,
   routes,
   routeOf: (conversation) => conversation.split(THREAD)[0],
-  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: 40000, file: 0, editEveryMs: 2500, typingEveryMs: 4000 },
   can: { upload: false, remove: true, react: false, typing: false, reply: true },
   reactions: null,