fix(slack): keep buttons + link to renewal docs on action-required errors

For expired refresh token and 403 not-owner failures, show
":warning: Action required, see thread…" with Approve/Reject still
visible so the admin can retry, and post a thread message with a
clickable link to the README renewal section.

Author: rofe

src/graph.js

@@ -3,6 +3,17 @@
  * Pure fetch, no SDK.
  */
 
+const RENEW_TOKEN_URL = 'https://github.com/adobe-rnd/teams-admin-agent#renewing-the-delegated-refresh-token';
+
+/** Error subclass used to signal "the admin must fix something before the retry will succeed". */
+export class ActionRequiredError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ActionRequiredError';
+    this.actionRequired = true;
+  }
+}
+
 let _graphToken = { value: null, expiresAt: 0 };
 
 async function getGraphToken(env) {
@@ -45,8 +56,8 @@ async function graphApiWithToken(accessToken, path, method = 'GET', body = null)
   const resText = await res.text();
   if (!res.ok) {
     if (res.status === 403 && path.includes('/members')) {
-      throw new Error(
-        '403 Forbidden — the account from /auth/microsoft must be an owner of this team. If the invitee is a guest, your tenant may block adding guests via Graph; add them manually in Teams if needed.',
+      throw new ActionRequiredError(
+        `The account associated with the delegated refresh token is not an owner of this team. Sign in as a team owner and renew the token by following the steps in <${RENEW_TOKEN_URL}|the README>, then click Approve again. If the invitee is a guest, your tenant may also block adding guests via Graph — add them manually in Teams if needed.`,
       );
     }
     if (res.status === 403 && path.includes('/invitations')) {
@@ -152,8 +163,8 @@ export async function resolveUser(env, email) {
 export async function sendInvitation(env, email, options = {}) {
   const token = await getDelegatedToken(env);
   if (!token) {
-    throw new Error(
-      'DELEGATED_REFRESH_TOKEN is required to send invitations. Visit GET /auth/microsoft, sign in, then set the refresh token.',
+    throw new ActionRequiredError(
+      `The delegated refresh token is missing or expired. Renew it by following the steps in <${RENEW_TOKEN_URL}|the README>, then click Approve again.`,
     );
   }
   const body = {
@@ -180,8 +191,8 @@ export async function addTeamMember(env, teamId, email, options = {}) {
     if (!err.message?.includes('User not found')) throw err;
     const delegatedToken = await getDelegatedToken(env);
     if (!delegatedToken) {
-      throw new Error(
-        'DELEGATED_REFRESH_TOKEN is required. Visit GET /auth/microsoft, sign in as a team owner, then set the returned refresh token as DELEGATED_REFRESH_TOKEN.',
+      throw new ActionRequiredError(
+        `The delegated refresh token is missing or expired. Renew it by following the steps in <${RENEW_TOKEN_URL}|the README>, then click Approve again.`,
       );
     }
     const invitation = await sendInvitation(env, email, { displayName: options.displayName });

src/slack.js

@@ -73,6 +73,55 @@ function spinnerBlocks(request, env, opts) {
   ];
 }
 
+/** Approve/Reject actions block — reused so the buttons can be re-rendered after recoverable errors. */
+function approvalActionsBlock(request) {
+  return {
+    type: 'actions',
+    block_id: 'approval_actions',
+    elements: [
+      {
+        type: 'button',
+        text: { type: 'plain_text', text: 'Approve' },
+        style: 'primary',
+        action_id: 'approve_request',
+        value: String(request.id),
+      },
+      {
+        type: 'button',
+        text: { type: 'plain_text', text: 'Reject' },
+        style: 'danger',
+        action_id: 'reject_request',
+        value: String(request.id),
+      },
+    ],
+  };
+}
+
+/** Blocks shown when the approval failed with a fixable cause (expired token, not owner, …). Keeps the buttons so the admin can retry after fixing the issue. */
+function actionRequiredBlocks(request, env, opts) {
+  return [
+    ...cardBodyBlocks(request, env, opts),
+    { type: 'section', text: { type: 'mrkdwn', text: ':warning: Action required, see thread…' } },
+    approvalActionsBlock(request),
+  ];
+}
+
+/** Post the failure detail as a threaded reply. Action-required errors are rendered as mrkdwn so the README link in the message is clickable; other errors stay in a code block. */
+async function postErrorThread(env, channelId, messageTs, err, actionRequired) {
+  const message = String(err.message ?? err);
+  const text = actionRequired
+    ? message
+    : '```\n' + message.slice(0, 2900).replace(/```/g, '`​``') + '\n```';
+  await slack(env, 'chat.postMessage', {
+    channel: channelId,
+    thread_ts: messageTs,
+    text: actionRequired ? message : 'Error response',
+    blocks: [
+      { type: 'section', text: { type: 'mrkdwn', text } },
+    ],
+  });
+}
+
 // ── Post one approval card per email ────────────────────────────
 
 export async function postApprovalCard(env, request) {
@@ -100,26 +149,7 @@ export async function postApprovalCard(env, request) {
     text: `${requester} requested to invite ${request.member_email} to ${request.team_name}`,
     blocks: [
       ...cardBodyBlocks(request, env, opts),
-      {
-        type: 'actions',
-        block_id: 'approval_actions',
-        elements: [
-          {
-            type: 'button',
-            text: { type: 'plain_text', text: 'Approve' },
-            style: 'primary',
-            action_id: 'approve_request',
-            value: String(request.id),
-          },
-          {
-            type: 'button',
-            text: { type: 'plain_text', text: 'Reject' },
-            style: 'danger',
-            action_id: 'reject_request',
-            value: String(request.id),
-          },
-        ],
-      },
+      approvalActionsBlock(request),
     ],
   });
 
@@ -365,34 +395,24 @@ async function handleApprove(payload, action, env) {
     console.error('Approve failed:', err);
     const channelId = payload.channel?.id ?? payload.container?.channel_id ?? env.SLACK_ADMIN_CHANNEL_ID;
     const messageTs = payload.message?.ts ?? payload.container?.message_ts ?? request.slack_message_ts;
-    const errorCardText = ':warning: An error occurred…';
+    const actionRequired = err.actionRequired === true;
+    const errorCardText = actionRequired ? ':warning: Action required, see thread…' : ':warning: An error occurred…';
     if (messageTs) {
       try {
         const fallbackText = `${request.requester_email ?? request.requester_name} requested to invite ${request.member_email} to ${request.team_name}\n${errorCardText}`;
+        const blocks = actionRequired
+          ? actionRequiredBlocks(request, env, { displayName: resolvedDisplayName })
+          : [
+              ...cardBodyBlocks(request, env, { displayName: resolvedDisplayName }),
+              { type: 'section', text: { type: 'mrkdwn', text: errorCardText } },
+            ];
         await slack(env, 'chat.update', {
           channel: channelId,
           ts: messageTs,
           text: fallbackText,
-          blocks: [
-            ...cardBodyBlocks(request, env, { displayName: resolvedDisplayName }),
-            { type: 'section', text: { type: 'mrkdwn', text: errorCardText } },
-          ],
-        });
-        const errorSnippet = String(err.message ?? err).slice(0, 2900);
-        await slack(env, 'chat.postMessage', {
-          channel: channelId,
-          thread_ts: messageTs,
-          text: 'Error response',
-          blocks: [
-            {
-              type: 'section',
-              text: {
-                type: 'mrkdwn',
-                text: '```\n' + errorSnippet.replace(/```/g, '`\u200b``') + '\n```',
-              },
-            },
-          ],
+          blocks,
         });
+        await postErrorThread(env, channelId, messageTs, err, actionRequired);
       } catch (updateErr) {
         console.error('chat.update (approve error) failed:', updateErr);
         const errorText = `Failed to add member: ${err.message}`;
@@ -678,31 +698,21 @@ async function handleApproveDisplayNameSubmission(payload, env, displayName) {
     console.error('Approve (display name) failed:', err);
     if (ts) {
       try {
-        const errorCardText = ':warning: An error occurred…';
+        const actionRequired = err.actionRequired === true;
+        const errorCardText = actionRequired ? ':warning: Action required, see thread…' : ':warning: An error occurred…';
+        const blocks = actionRequired
+          ? actionRequiredBlocks(request, env, { displayName })
+          : [
+              ...cardBodyBlocks(request, env, { displayName }),
+              { type: 'section', text: { type: 'mrkdwn', text: errorCardText } },
+            ];
         await slack(env, 'chat.update', {
           channel,
           ts,
           text: `${request.requester_email ?? request.requester_name} requested to invite ${request.member_email} to ${request.team_name}\n${errorCardText}`,
-          blocks: [
-            ...cardBodyBlocks(request, env, { displayName }),
-            { type: 'section', text: { type: 'mrkdwn', text: errorCardText } },
-          ],
-        });
-        const errorSnippet = String(err.message ?? err).slice(0, 2900);
-        await slack(env, 'chat.postMessage', {
-          channel,
-          thread_ts: ts,
-          text: 'Error response',
-          blocks: [
-            {
-              type: 'section',
-              text: {
-                type: 'mrkdwn',
-                text: '```\n' + errorSnippet.replace(/```/g, '`\u200b``') + '\n```',
-              },
-            },
-          ],
+          blocks,
         });
+        await postErrorThread(env, channel, ts, err, actionRequired);
       } catch (updateErr) {
         console.error('chat.update (approve error) failed:', updateErr);
       }