@assembly-js/app-foundation 0.0.22 → 0.0.24

package/dist/lib-client.js

@@ -5,7 +5,7 @@
 // never be dragged into the Edge middleware bundle that imports ./client
 // (proxy.ts pulls constants from that barrel).
 import { AssemblyBridge } from '@assembly-js/app-bridge';
-import { APP_CSRF_HEADER, TOKEN_EXPIRED_HEADER } from './session-exchange.js';
+import { APP_CSRF_HEADER, logRenewOutcome, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
 const REEXCHANGE_PATH = '/api/assembly-reexchange';
 // Single-flight gate for renewals. Session tokens are single-use for exchange:
 // when the 60-minute bearer expires, every in-flight fetch on the page 401s at
@@ -33,23 +33,32 @@ async function renewBearer() {
     let token = AssemblyBridge.sessionToken.getCurrent()?.token ?? '';
     // Proactively refresh: we're recovering from an expiry, so avoid re-minting
     // from a session token that may itself be stale.
+    let bridgeRefreshFailed = false;
     try {
         const refreshed = await AssemblyBridge.sessionToken.refresh();
         token = refreshed?.token ?? token;
     }
     catch {
         // Ignore: fall back to the current token below.
+        bridgeRefreshFailed = true;
     }
-    if (!token)
+    if (!token) {
+        logRenewOutcome('no_token', { bridgeRefreshFailed });
         return false;
+    }
     try {
         const res = await fetch(REEXCHANGE_PATH, {
             method: 'POST',
             headers: { 'x-assembly-token': token, [APP_CSRF_HEADER]: '1' },
         });
+        logRenewOutcome(res.ok ? 'renewed' : 'rejected', {
+            bridgeRefreshFailed,
+            status: res.status,
+        });
         return res.ok;
     }
     catch {
+        logRenewOutcome('unavailable', { bridgeRefreshFailed });
         return false;
     }
 }

package/dist/nango.d.ts

@@ -217,3 +217,5 @@ export declare function slackPostMessage(slack: IntegrationClient, args: {
     channel: string;
     text: string;
 }): Promise<SlackPostMessageResult>;
+/** Slack history returns mention tokens, not names. Resolve them before render. */
+export declare function slackResolveMentions(slack: IntegrationClient, text: string): Promise<string>;

package/dist/nango.js

@@ -496,3 +496,119 @@ export async function slackPostMessage(slack, args) {
     }
     return { ok: result.ok, ts: result.ts, channelId, error: result.error };
 }
+// Memoize successful mention lookups so a history page does not re-hit Slack
+// for the same ID. Misses stay uncached so a later reconnect can succeed.
+const SLACK_MENTION_RE = /<@([UW][A-Z0-9]+)(?:\|([^>]+))?>|<#([CG][A-Z0-9]+)(?:\|([^>]+))?>|<!subteam\^(S[A-Z0-9]+)(?:\|([^>]+))?>/g;
+const slackMentionNameCache = new Map();
+const SLACK_MENTION_FALLBACK = {
+    user: 'a user',
+    channel: 'a channel',
+    subteam: 'a user group',
+};
+function slackMentionRe() {
+    return new RegExp(SLACK_MENTION_RE.source, 'g');
+}
+function withMentionSigil(label, sigil) {
+    return label.startsWith(sigil) ? label : `${sigil}${label}`;
+}
+async function slackLookupJson(slack, endpoint, params) {
+    try {
+        const res = await slack.get({ endpoint, params });
+        const data = (await res.json());
+        if (!data.ok)
+            return null;
+        return data;
+    }
+    catch {
+        // Lookup is best-effort: a missing scope or a vanished user must not
+        // fail the whole history render.
+        return null;
+    }
+}
+function slackUserDisplayName(user) {
+    const display = user.profile?.display_name?.trim();
+    if (display)
+        return display;
+    const real = user.profile?.real_name?.trim() || user.real_name?.trim();
+    if (real)
+        return real;
+    return user.name?.trim() || undefined;
+}
+async function slackResolveUserName(slack, id) {
+    const cacheKey = `user:${id}`;
+    const cached = slackMentionNameCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const data = await slackLookupJson(slack, '/users.info', { user: id });
+    const user = data?.user;
+    const name = user ? slackUserDisplayName(user) : undefined;
+    if (!name)
+        return SLACK_MENTION_FALLBACK.user;
+    const label = withMentionSigil(name, '@');
+    slackMentionNameCache.set(cacheKey, label);
+    return label;
+}
+async function slackResolveChannelName(slack, id) {
+    const cacheKey = `channel:${id}`;
+    const cached = slackMentionNameCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const data = await slackLookupJson(slack, '/conversations.info', { channel: id });
+    const channel = data?.channel;
+    const name = channel?.name?.trim();
+    if (!name)
+        return SLACK_MENTION_FALLBACK.channel;
+    const label = withMentionSigil(name, '#');
+    slackMentionNameCache.set(cacheKey, label);
+    return label;
+}
+async function slackResolveSubteamName(slack, id) {
+    const cacheKey = `subteam:${id}`;
+    const cached = slackMentionNameCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const data = await slackLookupJson(slack, '/usergroups.info', { usergroup: id });
+    const group = data?.usergroup;
+    const name = group?.handle?.trim() || group?.name?.trim();
+    if (!name)
+        return SLACK_MENTION_FALLBACK.subteam;
+    const label = withMentionSigil(name, '@');
+    slackMentionNameCache.set(cacheKey, label);
+    return label;
+}
+/** Slack history returns mention tokens, not names. Resolve them before render. */
+export async function slackResolveMentions(slack, text) {
+    if (!text)
+        return text;
+    const replacements = new Map();
+    const lookups = new Map();
+    for (const match of text.matchAll(slackMentionRe())) {
+        const [raw, userId, userLabel, channelId, channelLabel, subteamId, subteamLabel] = match;
+        if (replacements.has(raw) || lookups.has(raw))
+            continue;
+        if (userLabel) {
+            replacements.set(raw, withMentionSigil(userLabel, '@'));
+        }
+        else if (channelLabel) {
+            replacements.set(raw, withMentionSigil(channelLabel, '#'));
+        }
+        else if (subteamLabel) {
+            replacements.set(raw, withMentionSigil(subteamLabel, '@'));
+        }
+        else if (userId) {
+            lookups.set(raw, slackResolveUserName(slack, userId));
+        }
+        else if (channelId) {
+            lookups.set(raw, slackResolveChannelName(slack, channelId));
+        }
+        else if (subteamId) {
+            lookups.set(raw, slackResolveSubteamName(slack, subteamId));
+        }
+    }
+    await Promise.all([...lookups.entries()].map(async ([raw, pending]) => {
+        replacements.set(raw, await pending);
+    }));
+    if (replacements.size === 0)
+        return text;
+    return text.replace(slackMentionRe(), (raw) => replacements.get(raw) ?? raw);
+}

package/dist/session-exchange.d.ts

@@ -15,6 +15,12 @@ export type CookieOutcome = 'served_from_cookie' | 'minted' | `fail_closed:${str
 export declare function logCookieOutcome(outcome: CookieOutcome, detail?: {
     rejectedToken?: string;
 }): void;
+export declare const RENEW_OUTCOME_EVENT = "assembly.renew_outcome";
+export type RenewOutcome = 'renewed' | 'no_token' | 'rejected' | 'unavailable';
+export declare function logRenewOutcome(outcome: RenewOutcome, detail?: {
+    bridgeRefreshFailed?: boolean;
+    status?: number;
+}): void;
 export declare function isDocumentRequest(request: {
     method: string;
     headers: {

package/dist/session-exchange.js

@@ -88,6 +88,25 @@ detail) {
         ...(detail?.rejectedToken ? { rejected_token: detail.rejectedToken } : {}),
     }));
 }
+// One structured line per bearer renewal attempt. The renewal path is the one
+// an idle session takes on its way back: the 60-minute bearer has expired and
+// everything now depends on the parent still holding an exchangeable session
+// token. Today every way that can fail collapses into the same `false`, so a
+// dead parent bridge, a refused token and a network blip are indistinguishable
+// after the fact. Outcomes are a closed set, mirroring COOKIE_OUTCOME_EVENT.
+export const RENEW_OUTCOME_EVENT = 'assembly.renew_outcome';
+export function logRenewOutcome(outcome, 
+// `bridgeRefreshFailed` records that the pre-renewal token refresh threw and
+// we fell back to the token already in hand — on its own that is survivable,
+// but paired with a rejection it names the parent as the failing side.
+detail) {
+    console.log(JSON.stringify({
+        event_type: RENEW_OUTCOME_EVENT,
+        outcome,
+        ...(detail?.bridgeRefreshFailed ? { bridge_refresh_failed: true } : {}),
+        ...(typeof detail?.status === 'number' ? { status: detail.status } : {}),
+    }));
+}
 // Two-tier detection: Sec-Fetch-Dest when the browser sends it (all evergreen
 // browsers; 'iframe' is what an embedded app's navigations carry), Accept
 // text/html otherwise. Deliberately NOT matching `*/*`: browser fetch() GETs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-integrations/providers/slack.md

@@ -2,12 +2,15 @@
 
 Everything except `send-message` needs membership, not just visibility. Posting reaches any public channel without joining (`chat:write.public`); reading history, adding reactions, and inviting users all fail `not_in_channel` until the bot joins.
 
+- **Warn before the wall.** When the app reads from a channel — history, reactions, invites, or scheduled messages — tell the user at build time that the bot needs to be invited to that channel, and render a visible "Invite @Assembly to this channel" hint next to any channel picker.
+- **Check first, don't wait for the failure.** Call `get-channel-info` and read `is_member` before the first read/react/invite/schedule call on a channel, instead of waiting for the `not_in_channel` failure. Keep the reactive join-and-retry below as the fallback for when the pre-flight check was skipped or state changed since.
 - **Post with `slackPostMessage` from `@assembly-js/app-foundation/server` — never hand-roll `chat.postMessage`.** It resolves a `#name` to the channel ID, posts, and on `not_in_channel` joins the channel and retries once. Slack-level failures come back as `{ ok: false, error }`; on `not_in_channel` render "invite the bot to #channel in Slack" (private channels cannot be self-joined).
 - **List channels with `slackListChannels` from `@assembly-js/app-foundation/server` — never page the `list-channels` action yourself.** That action returns at most 200 per page, so a large workspace is dozens of sequential calls and a 20–30 second dropdown; the helper walks at Slack's maximum page size and handles rate limits and the private-channel scope fallback. It returns `{ id, name, isPrivate }` sorted by name.
 - **Resolve channel names with `slackFindChannelId` from `@assembly-js/app-foundation/server` for every other per-channel call.** It handles cursor pagination (a single `conversations.list` misses channels in large workspaces), name normalization, scope fallback, rate limits, and caching. Use the returned ID; most Slack methods reject a `#name` with `invalid_arguments`.
 - **Read the Slack error code with `slackErrorCode(err)` from `@assembly-js/app-foundation/server` — never read `err.detail` yourself.** The vendored scripts put the code in different places inside `detail`; the helper returns it (`'not_in_channel'`, `'channel_not_found'`, `'is_archived'`, …) or `undefined` when the error isn't a Slack rejection.
+- **Resolve mention IDs with `slackResolveMentions` from `@assembly-js/app-foundation/server` before rendering Slack message text.** History returns raw `<@U…>`, `<#C…|name>`, and `<!subteam^ID>` tokens. The helper replaces them with display names and falls back to "a user" / "a channel" / "a user group" when a lookup fails or `usergroups:read` is missing. Leave `<!here>` / `<!channel>` / `<!everyone>` as-is.
 - **Every other per-channel call (history, reactions, invites):** when `slackErrorCode(err) === 'not_in_channel'`, call `join-channel` with the channel ID, then retry once. Private channels fail the join with `method_not_supported_for_channel_type` — tell the user to invite the bot instead of retrying.
-- **Scopes:** `chat:write.public` lets posting reach any public channel without joining, so only the other calls need `join-channel` (which needs `channels:join`). Add `groups:read` if the app must find private channels.
+- **Scopes:** `chat:write.public` lets posting reach any public channel without joining, so only the other calls need `join-channel` (which needs `channels:join`). Add `groups:read` if the app must find private channels. `usergroups:read` is what lets `slackResolveMentions` name a `<!subteam^…>` token; without it the helper falls back to "a user group".
 
 ```typescript
 import {
@@ -16,12 +19,14 @@ import {
   slackFindChannelId,
   slackListChannels,
   slackPostMessage,
+  slackResolveMentions,
 } from '@assembly-js/app-foundation/server';
 
 const slack = await getIntegration('slack');
 const channels = await slackListChannels(slack); // dropdown options
 const channelId = await slackFindChannelId(slack, 'general');
 const posted = await slackPostMessage(slack, { channel: '#general', text: 'Hello' });
+const readable = await slackResolveMentions(slack, rawMessageText);
 ```
 
 ```typescript