@rhizogrip/spore-plugin-teams 0.1.0 → 0.3.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.
 
@@ -82,6 +104,19 @@ spore's `replyTo` in `config.json`: `teams:<bot>/<object id>` for a person — t
 personal chat with them if they never wrote to it — or `teams:<bot>/<channel id>`, a new post in
 the channel. A place this bot's file does not route to the spore is refused, and the log says why.
 
+## Approvals
+
+An approval your program asks in a personal chat or a channel this bot reaches
+([INTEGRATION §Asking a person to approve](../../INTEGRATION.md#asking-a-person-to-approve)) is
+posted as an Adaptive Card — the request's `teams` card, or its `default` text and facts drawn as
+a `TextBlock` and a `FactSet` — with an `Action.Execute` button per option, added by the bot. A
+card of your own must be version 1.4 or later and carry no `Action.Submit`, `Action.Execute` or
+`refresh` of its own; `Action.OpenUrl` is fine. A press is Microsoft's signed `adaptiveCard/action`
+invoke, taken only from someone the approval names and answered at once — `Apply — recorded`, or
+why it was not taken; what the person filled in on the card's inputs comes with it. The card is
+then updated: replaced by the body your hook answered, or kept with its buttons gone and who chose
+what below.
+
 ## What it guarantees
 
 - **A message reaches its spore once,** under `teams:<conversation id>:<activity id>` as its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizogrip/spore-plugin-teams",
-  "version": "0.1.0",
+  "version": "0.3.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.24.0"
   },
   "scripts": {
     "test": "vitest run"
   },
   "spore": {
-    "works": "^1.22.0",
+    "works": "^1.24.0",
     "services": {
       "teams": {
         "what": "a bot of yours in Microsoft Teams, each personal chat and channel reaching its spore",

package/src/adapter.js

@@ -8,20 +8,29 @@
 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'])
 const THREAD = ';messageid='
 const COMMAND = /^\/([a-z]+)(?:\s+(.+))?$/is
 const SERVICE_URL = 'https://smba.trafficmanager.net/teams/'
+const CARD = 'application/vnd.microsoft.card.adaptive'
+const PRESSED = 'spore'
+const ANSWERING = new Set(['Action.Submit', 'Action.Execute'])
 const SHAPE = '{ "app": "<app id>", "tenant": "<tenant id>", "secret": "${OPS_TEAMS_SECRET}", "listen": "127.0.0.1:3978", "people": { "<object id>": "<spore>" }, "channels": { "<channel id>": { "spores": ["<spore>"], "people": ["<object id>"] } } }' // eslint-disable-line no-template-curly-in-string
 
 const invalid = (path, problem, detail = `a bot is ${SHAPE}`) => new SporeError(`${path} ${problem}`, { type: 'TEAMS_BOT_INVALID', detail })
 
 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 +50,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 +73,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,9 +109,9 @@ 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 },
+  can: { upload: false, remove: true, react: false, typing: false, reply: true, choose: true },
   reactions: null,
   showShared: 'working',
   hint (err, { file }) {
@@ -153,6 +164,48 @@ export function normalize (activity) {
 
 const tenantOf = (activity) => activity.conversation?.tenantId ?? activity.channelData?.tenant?.id
 
+/** Whether anything in a card, however deep — an action set, a select action, a refresh — sends a press back to the bot. */
+const answersBack = (value) => Array.isArray(value)
+  ? value.some(answersBack)
+  : record(value) && (ANSWERING.has(value.type) || Object.values(value).some(answersBack))
+
+/** What an approval shows, as an Adaptive Card: the host's own, or the default body — its text, then its facts. */
+const cardOf = ({ native, fallback }) => native
+  ? structuredClone(native)
+  : {
+      type: 'AdaptiveCard',
+      $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
+      version: '1.5',
+      body: [
+        ...(fallback.text ? [{ type: 'TextBlock', text: fallback.text, wrap: true }] : []),
+        ...(fallback.facts?.length ? [{ type: 'FactSet', facts: fallback.facts.map(([title, value]) => ({ title, value })) }] : [])
+      ]
+    }
+
+/** The card as it was shown, the relay's buttons gone and how it ended below. */
+const closed = (card, outcome) => ({
+  ...card,
+  body: [...(card.body ?? []), { type: 'TextBlock', text: `**${outcome}**`, wrap: true }],
+  actions: (card.actions ?? []).filter(action => !(record(action.data) && Object.hasOwn(action.data, PRESSED)))
+})
+
+/**
+ * A press on one of the relay's buttons, as the relay takes it, from an `adaptiveCard/action`
+ * invoke: what Teams merged into the action's data besides the relay's own is what the person
+ * filled in.
+ */
+export function choiceOf (activity) {
+  const personal = activity.conversation.conversationType === 'personal'
+  const { [PRESSED]: data = null, ...inputs } = record(activity.value?.action?.data) ? activity.value.action.data : {}
+  return {
+    conversation: personal ? activity.from.aadObjectId : activity.conversation.id,
+    data,
+    inputs: Object.keys(inputs).length ? inputs : null,
+    person: { id: activity.from.aadObjectId, name: activity.from.name, groups: [] },
+    where: personal ? 'a personal chat in Teams' : 'a Teams channel'
+  }
+}
+
 /**
  * The live adapter. `receive({ onActivity, signal, log })` is the transport — the listener, or a
  * test's — and hands over each activity already checked. A post to a person goes to the chat they
@@ -204,6 +257,33 @@ export function createAdapter ({ connector, receive, app, tenant }) {
     ...(answering === null ? {} : { replyToId: answering })
   })
 
+  /** An activity into a conversation, answering its note: a person's chat, made when there is none yet; a thread; or a new post in a channel. */
+  const into = async (conversation, act) => {
+    if (!conversation.startsWith('19:')) {
+      const chat = await chatOf(conversation)
+      return `${chat} ${await connector.send(serviceOf(conversation), chat, act)}`
+    }
+    if (conversation.includes(THREAD)) return `${conversation} ${await connector.send(serviceOf(conversation), conversation, act)}`
+    const { replyToId, ...root } = act
+    const made = await connector.create(serviceOf(conversation), { isGroup: true, channelData: { channel: { id: conversation }, tenant: { id: tenant } }, activity: root })
+    return `${made.id} ${made.activityId}`
+  }
+
+  /**
+   * An invoke from one of the relay's buttons handed to `onChoice`, and answered as Teams wants an
+   * `adaptiveCard/action` answered: a short message, what the relay acknowledged it with.
+   */
+  const press = async (one, onChoice, log) => {
+    const answered = (value) => ({ statusCode: 200, type: 'application/vnd.microsoft.activity.message', value })
+    if (!one.from?.aadObjectId) {
+      log(`a press in ${one.conversation.id} from ${one.from?.name ?? 'someone'} with no Entra object id, not taken`)
+      return answered('who pressed this is not known')
+    }
+    let said = 'this button no longer does anything'
+    await onChoice({ ...choiceOf(one), acknowledge: async (text) => { if (text) said = text } })
+    return answered(said)
+  }
+
   return {
     ...TEAMS,
 
@@ -212,12 +292,13 @@ export function createAdapter ({ connector, receive, app, tenant }) {
       save = persist
     },
 
-    listen: ({ onMessage, signal, log }) => receive({
+    listen: ({ onMessage, onChoice, signal, log }) => receive({
       signal,
       log,
       onActivity: async (one) => {
         if (tenantOf(one) !== tenant) return log(`dropped an activity from tenant ${tenantOf(one)}: this bot serves ${tenant}`)
         remember(one)
+        if (one.type === 'invoke' && one.name === 'adaptiveCard/action' && one.value?.trigger !== 'automatic') return press(one, onChoice, log)
         if (one.type !== 'message') return
         if (one.conversation.conversationType === 'groupChat') return log(`group chat ${one.conversation.id}: group chats are not served yet`)
         if (!one.from?.aadObjectId) return log(`a message in ${one.conversation.id} from ${one.from?.name ?? 'someone'} with no Entra object id, not taken`)
@@ -225,17 +306,7 @@ export function createAdapter ({ connector, receive, app, tenant }) {
       }
     }),
 
-    post: async (conversation, text, { answering = null, markdown = false } = {}) => {
-      if (!conversation.startsWith('19:')) {
-        const chat = await chatOf(conversation)
-        return `${chat} ${await connector.send(serviceOf(conversation), chat, activity(text, { markdown, answering }))}`
-      }
-      if (conversation.includes(THREAD)) {
-        return `${conversation} ${await connector.send(serviceOf(conversation), conversation, activity(text, { markdown, answering }))}`
-      }
-      const made = await connector.create(serviceOf(conversation), { isGroup: true, channelData: { channel: { id: conversation }, tenant: { id: tenant } }, activity: activity(text, { markdown }) })
-      return `${made.id} ${made.activityId}`
-    },
+    post: (conversation, text, { answering = null, markdown = false } = {}) => into(conversation, activity(text, { markdown, answering })),
 
     edit: async (conversation, note, text) => {
       const where = placeOf(note)
@@ -245,6 +316,32 @@ export function createAdapter ({ connector, receive, app, tenant }) {
     remove: async (conversation, note) => {
       const where = placeOf(note)
       await connector.remove(serviceOf(conversation), where.conversation, where.id)
+    },
+
+    checkBody: (native) => {
+      if (native.type !== 'AdaptiveCard' || !(Number(native.version) >= 1.4)) {
+        return 'a Teams body is an Adaptive Card of version 1.4 or later, as { "type": "AdaptiveCard", "version": "1.5", "body": [ … ] }'
+      }
+      if (answersBack(native)) return 'a Teams body carries no Action.Submit or Action.Execute, nor a refresh — the buttons that answer are the ones spore adds'
+      return null
+    },
+
+    /** The question as a card, each choice an `Action.Execute` under it. */
+    ask: async (conversation, shown, choices) => {
+      const card = cardOf(shown)
+      card.actions = [
+        ...(card.actions ?? []),
+        ...choices.map(choice => ({ type: 'Action.Execute', title: choice.label, verb: 'answer', data: { [PRESSED]: choice.data }, ...(choice.style ? { style: choice.style } : {}) }))
+      ]
+      return { note: await into(conversation, { type: 'message', attachments: [{ contentType: CARD, content: card }] }), shown: card }
+    },
+
+    /** The question closed: replaced by `native` or `fallback`, or kept as `shown` with how it ended below. */
+    settle: async (conversation, note, replacement) => {
+      const card = replacement.shown ? closed(replacement.shown, replacement.outcome) : cardOf(replacement)
+      const where = placeOf(note)
+      await connector.update(serviceOf(conversation), where.conversation, where.id, { type: 'message', id: where.id, attachments: [{ contentType: CARD, content: card }] })
+      return card
     }
   }
 }

package/src/server.js

@@ -2,7 +2,7 @@
  * Where the Bot Connector delivers: `POST /api/messages` on a loopback address, which the
  * operator's proxy makes the bot's public HTTPS endpoint. An activity is checked before it is
  * read, and answered 200 only once `onActivity` has it, so one the service could not take is
- * delivered again.
+ * delivered again — with the body `onActivity` answers, where an invoke needs one.
  */
 
 import { createServer } from 'node:http'
@@ -45,12 +45,14 @@ export function serve ({ host, port, verify, onActivity, signal, log, listening
       log(`refused an activity: ${refused}`)
       return answer(401)
     }
+    let reply
     try {
-      await onActivity(activity)
+      reply = await onActivity(activity)
     } catch (err) {
       log(`activity ${activity.id} not taken — ${err.message}${err.detail ? ` — ${err.detail}` : ''}`)
       return answer(500)
     }
+    if (typeof reply === 'object' && reply !== null) return response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(reply))
     answer(200)
   })