@assembly-js/app-foundation 0.0.20 → 0.0.21

package/CLAUDE.md

@@ -644,6 +644,8 @@ import { loadItems } from '@/app/actions/items';
 export default function MyWidget() {
   const { data: items, isLoading, error, reload } = useServerAction(() => loadItems(), []);
   // `deps` ([]) works like useEffect deps — list anything the action closes over.
+  // Deps must be primitives (an id, a cursor, `items.length`). A derived array or
+  // object is a new identity every render and spins the page in a fetch loop.
 }
 ```
 

package/dist/mint-bearer.d.ts

@@ -21,6 +21,7 @@ export interface MintSessionOptions {
     cookieSessionId?: string;
 }
 export declare function mintBearerFromSessionToken(token: string, options?: MintSessionOptions): Promise<MintOutcome>;
+export declare function fetchSessionFlags(bearer: string): Promise<string[] | null>;
 export interface MintedAppBearer {
     bearer: string;
     bearerExpiresAt: number;

package/dist/mint-bearer.js

@@ -90,6 +90,7 @@ export async function mintBearerFromSessionToken(token, options) {
                 notificationId: json.session?.notificationId || undefined,
                 instanceId: json.session?.instanceId || undefined,
                 sessionId: payload.tokenId,
+                flags: json.flags?.length ? json.flags : undefined,
             },
         };
     }
@@ -102,6 +103,39 @@ export async function mintBearerFromSessionToken(token, options) {
         clearTimeout(timeoutId);
     }
 }
+// Non-destructive read; a hung call only delays one cookie refresh, so give it
+// far less rope than the exchange.
+const FLAGS_TIMEOUT_MS = 5_000;
+// Re-resolves the app-foundation-visible flags for the workspace behind an
+// already-minted bearer (GET /v1/session/flags). The freshness half of the
+// flag channel: the exchange response seeds the proxy's flags cookie at mint
+// time, and this refreshes it on the cookie's own cadence — no re-mint, no
+// auth churn. Returns null when the value could not be determined (network
+// failure, expired bearer, malformed body) so the caller can keep whatever it
+// has rather than treating the miss as "all flags off".
+export async function fetchSessionFlags(bearer) {
+    const base = (mintBaseUrl ?? OpenAPI.BASE).replace(/\/$/, '');
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FLAGS_TIMEOUT_MS);
+    try {
+        const resp = await fetch(`${base}/v1/session/flags`, {
+            headers: { Authorization: `Bearer ${bearer}` },
+            signal: controller.signal,
+        });
+        if (!resp.ok)
+            return null;
+        const json = (await resp.json());
+        if (!Array.isArray(json.flags))
+            return null;
+        return json.flags.filter((f) => typeof f === 'string');
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
 // Mints a short-lived, APP-scoped bearer from the app API key ALONE by calling
 // platform-api POST /v1/token (client-credentials). There is NO session token
 // and NO user in the loop: this is the OFFLINE/background path (cron, webhooks)

package/dist/nango.d.ts

@@ -12,8 +12,9 @@ export declare class ConnectorError extends Error {
     readonly status: number;
     /**
      * For `action_failed`: what the action script threw — usually the
-     * provider-level failure, e.g. `{ type: 'slack_error', message, response }`
-     * where `response.error` is Slack's error code.
+     * provider-level failure. Scripts disagree on where the provider's error
+     * code sits inside it (`response.error`, `error`, or `message`), so don't
+     * read it by hand: for Slack use `slackErrorCode(err)`.
      */
     readonly detail?: unknown;
     constructor(args: {
@@ -120,6 +121,49 @@ export interface ResolveResourceOpts {
  * }
  */
 export declare function resolveResource(provider: Provider, resolverAction: string, opts: ResolveResourceOpts): Promise<ResourcePage>;
+/**
+ * Slack's error code (e.g. 'not_in_channel', 'channel_not_found',
+ * 'is_archived') from a failed Slack action, or undefined when `err` is not an
+ * action failure. Branch on this instead of reading `err.detail` yourself: the
+ * vendored Slack scripts put the code in different places (`response.error`,
+ * `error`, or `message`), and this reads them in that order.
+ *
+ * ```typescript
+ * try {
+ *   await slack.action('get-conversation-history', { channel_id, limit: 10 });
+ * } catch (err) {
+ *   if (slackErrorCode(err) === 'not_in_channel') {
+ *     // join with the channel ID and retry once; private channels can't be
+ *     // self-joined — tell the user to invite the bot instead
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+export declare function slackErrorCode(err: unknown): string | undefined;
+export interface SlackChannel {
+    /** Channel ID (`C…`/`G…`) — what every other Slack call takes. */
+    id: string;
+    /** Channel name without the leading '#'. Slack keeps these lowercase. */
+    name: string;
+    /** True for private channels (listed only when the bot is a member and the connection has `groups:read`). */
+    isPrivate: boolean;
+}
+/**
+ * Every channel the bot can see, sorted by name. Use this to populate a
+ * channel dropdown instead of paging the `list-channels` action yourself: that
+ * action tops out at 200 per page and a large workspace needs dozens of
+ * sequential calls, which is a 20–30 second dropdown. This walks
+ * conversations.list at Slack's maximum page size and handles rate limits and
+ * the private-channel scope fallback. Not cached: the client carries no
+ * workspace identity to key on, and an app transfer briefly serves two
+ * workspaces from one deployment.
+ *
+ * Public channels are listed whether or not the bot has joined; private
+ * channels only when it is already a member. Listing a channel does not make
+ * it readable — see slackFindChannelId for the membership rules.
+ */
+export declare function slackListChannels(slack: IntegrationClient): Promise<SlackChannel[]>;
 /**
  * Resolve a Slack channel name to its ID, walking the cursor-paginated
  * conversations.list until found (Slack treats `limit` as a per-page cap and
@@ -134,10 +178,11 @@ export declare function resolveResource(provider: Provider, resolverAction: stri
  * methods reject a `#name` with `invalid_arguments`.
  *
  * Membership: public channels are listed whether or not the bot joined, but
- * posting still needs membership — on a `not_in_channel` error from
- * chat.postMessage, call conversations.join with the ID and retry once.
- * Private channels are listed only when the bot is already a member (and only
- * when the connection has the groups:read scope — without it this helper
+ * everything except posting (`send-message`) needs membership — reading
+ * history, adding reactions, inviting users all fail `not_in_channel` until
+ * the bot joins. On that code, call `join-channel` with the ID and retry
+ * once. Private channels are listed only when the bot is already a member (and
+ * only when the connection has the groups:read scope — without it this helper
  * automatically falls back to public channels only). A private channel cannot
  * be self-joined: surface "invite the bot to #channel in Slack" to the user.
  */

package/dist/nango.js

@@ -10,8 +10,9 @@ export class ConnectorError extends Error {
     status;
     /**
      * For `action_failed`: what the action script threw — usually the
-     * provider-level failure, e.g. `{ type: 'slack_error', message, response }`
-     * where `response.error` is Slack's error code.
+     * provider-level failure. Scripts disagree on where the provider's error
+     * code sits inside it (`response.error`, `error`, or `message`), so don't
+     * read it by hand: for Slack use `slackErrorCode(err)`.
      */
     detail;
     constructor(args) {
@@ -281,47 +282,40 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
- * Resolve a Slack channel name to its ID, walking the cursor-paginated
- * conversations.list until found (Slack treats `limit` as a per-page cap and
- * may return fewer; a single un-paginated call misses channels in large
- * workspaces). Input is normalized (leading '#' stripped, lowercased — Slack
- * channel names are always lowercase). Resolved IDs are memoized for the
- * process lifetime; Slack rate limits (conversations.list is a low-tier
- * method) are absorbed by waiting and resuming from the same cursor.
+ * Slack's error code (e.g. 'not_in_channel', 'channel_not_found',
+ * 'is_archived') from a failed Slack action, or undefined when `err` is not an
+ * action failure. Branch on this instead of reading `err.detail` yourself: the
+ * vendored Slack scripts put the code in different places (`response.error`,
+ * `error`, or `message`), and this reads them in that order.
  *
- * Use the returned ID for every follow-up call — conversations.join /
- * conversations.history / chat.postMessage should all be given IDs; most
- * methods reject a `#name` with `invalid_arguments`.
- *
- * Membership: public channels are listed whether or not the bot joined, but
- * posting still needs membership — on a `not_in_channel` error from
- * chat.postMessage, call conversations.join with the ID and retry once.
- * Private channels are listed only when the bot is already a member (and only
- * when the connection has the groups:read scope — without it this helper
- * automatically falls back to public channels only). A private channel cannot
- * be self-joined: surface "invite the bot to #channel in Slack" to the user.
+ * ```typescript
+ * try {
+ *   await slack.action('get-conversation-history', { channel_id, limit: 10 });
+ * } catch (err) {
+ *   if (slackErrorCode(err) === 'not_in_channel') {
+ *     // join with the channel ID and retry once; private channels can't be
+ *     // self-joined — tell the user to invite the bot instead
+ *   }
+ *   throw err;
+ * }
+ * ```
  */
-export async function slackFindChannelId(slack, name) {
-    const target = name.replace(/^#/, '').trim().toLowerCase();
-    if (!target)
-        return null;
-    const cached = slackChannelIdCache.get(target);
-    if (cached)
-        return cached;
-    const fields = {
-        id: 'id',
-        label: 'name',
-        items: 'channels',
-        nextCursor: 'response_metadata.next_cursor',
-    };
+export function slackErrorCode(err) {
+    if (!(err instanceof ConnectorError) || err.code !== 'action_failed')
+        return undefined;
+    const detail = err.detail;
+    const code = detail?.response?.error ?? detail?.error ?? detail?.message;
+    return typeof code === 'string' ? code : undefined;
+}
+// One-page fetcher over conversations.list that owns the Slack quirks a naive
+// walk gets wrong: rate-limit waits resume from the SAME cursor (throwing would
+// discard the walk and a retry would restart from page 1), and a missing_scope
+// for private_channel (no groups:read) fails the WHOLE first call, so retrying
+// public-only from the same cursor restarts the walk correctly.
+function slackChannelPageFetcher(slack) {
     let types = 'public_channel,private_channel';
     let rateLimitWaits = 0;
-    // findResource drives the cursor walk; this fetcher owns the Slack quirks —
-    // rate-limit waits resume from the SAME cursor (throwing would discard the
-    // walk and a retry would restart from page 1), and a missing_scope for
-    // private_channel (no groups:read) fails the WHOLE first call, so retrying
-    // public-only from the same cursor restarts the walk correctly.
-    const fetchPage = async (cursor) => {
+    return async (cursor) => {
         for (;;) {
             let res;
             try {
@@ -361,14 +355,90 @@ export async function slackFindChannelId(slack, name) {
                 }
                 throw new Error(data.error ?? 'Slack conversations.list failed');
             }
-            return normalizeResourcePage(data, fields, { requestCursor: cursor });
+            const channels = [];
+            for (const channel of data.channels ?? []) {
+                if (!channel.id || !channel.name)
+                    continue;
+                channels.push({
+                    id: channel.id,
+                    name: channel.name,
+                    isPrivate: channel.is_private === true,
+                });
+            }
+            // Slack sends an empty string, not an absent key, on the last page; a
+            // cursor identical to the one just used would loop forever.
+            const next = data.response_metadata?.next_cursor || undefined;
+            return { channels, nextCursor: next && next !== cursor ? next : undefined };
         }
     };
+}
+/**
+ * Every channel the bot can see, sorted by name. Use this to populate a
+ * channel dropdown instead of paging the `list-channels` action yourself: that
+ * action tops out at 200 per page and a large workspace needs dozens of
+ * sequential calls, which is a 20–30 second dropdown. This walks
+ * conversations.list at Slack's maximum page size and handles rate limits and
+ * the private-channel scope fallback. Not cached: the client carries no
+ * workspace identity to key on, and an app transfer briefly serves two
+ * workspaces from one deployment.
+ *
+ * Public channels are listed whether or not the bot has joined; private
+ * channels only when it is already a member. Listing a channel does not make
+ * it readable — see slackFindChannelId for the membership rules.
+ */
+export async function slackListChannels(slack) {
+    const fetchPage = slackChannelPageFetcher(slack);
+    const channels = [];
+    let cursor;
+    for (let page = 0; page < SLACK_LIST_MAX_PAGES; page++) {
+        const result = await fetchPage(cursor);
+        channels.push(...result.channels);
+        if (!result.nextCursor)
+            break;
+        cursor = result.nextCursor;
+    }
+    channels.sort((a, b) => a.name.localeCompare(b.name));
+    return channels;
+}
+/**
+ * Resolve a Slack channel name to its ID, walking the cursor-paginated
+ * conversations.list until found (Slack treats `limit` as a per-page cap and
+ * may return fewer; a single un-paginated call misses channels in large
+ * workspaces). Input is normalized (leading '#' stripped, lowercased — Slack
+ * channel names are always lowercase). Resolved IDs are memoized for the
+ * process lifetime; Slack rate limits (conversations.list is a low-tier
+ * method) are absorbed by waiting and resuming from the same cursor.
+ *
+ * Use the returned ID for every follow-up call — conversations.join /
+ * conversations.history / chat.postMessage should all be given IDs; most
+ * methods reject a `#name` with `invalid_arguments`.
+ *
+ * Membership: public channels are listed whether or not the bot joined, but
+ * everything except posting (`send-message`) needs membership — reading
+ * history, adding reactions, inviting users all fail `not_in_channel` until
+ * the bot joins. On that code, call `join-channel` with the ID and retry
+ * once. Private channels are listed only when the bot is already a member (and
+ * only when the connection has the groups:read scope — without it this helper
+ * automatically falls back to public channels only). A private channel cannot
+ * be self-joined: surface "invite the bot to #channel in Slack" to the user.
+ */
+export async function slackFindChannelId(slack, name) {
+    const target = name.replace(/^#/, '').trim().toLowerCase();
+    if (!target)
+        return null;
+    const cached = slackChannelIdCache.get(target);
+    if (cached)
+        return cached;
+    const fetchPage = slackChannelPageFetcher(slack);
     // Slack channel names are always lowercase, so an exact label match is the
     // same comparison the raw walk made against channel.name.
-    const hit = await findResource(fetchPage, (option) => option.label === target, {
-        maxPages: SLACK_LIST_MAX_PAGES,
-    });
+    const hit = await findResource(async (cursor) => {
+        const page = await fetchPage(cursor);
+        return {
+            options: page.channels.map((channel) => ({ id: channel.id, label: channel.name })),
+            nextCursor: page.nextCursor,
+        };
+    }, (option) => option.label === target, { maxPages: SLACK_LIST_MAX_PAGES });
     if (hit)
         slackChannelIdCache.set(target, hit.id);
     return hit?.id ?? null;
@@ -408,12 +478,9 @@ export async function slackPostMessage(slack, args) {
             return { ok: result.ok, ts: result.ts };
         }
         catch (err) {
-            if (err instanceof ConnectorError && err.code === 'action_failed') {
-                const detail = err.detail;
-                const slackError = detail?.response?.error ?? detail?.message;
-                if (typeof slackError === 'string')
-                    return { ok: false, error: slackError };
-            }
+            const slackError = slackErrorCode(err);
+            if (slackError)
+                return { ok: false, error: slackError };
             throw err;
         }
     };

package/dist/session-exchange.d.ts

@@ -20,5 +20,17 @@ export interface ExchangedSession {
     /** Session token this bearer was exchanged from — lets the proxy tell a
      *  reload of an already-exchanged token apart from a new open. */
     sessionId?: string;
+    /** Keys of whichever PostHog flags — from platform-api's small, explicit
+     *  app-foundation-visible-flags allowlist (session.go's appFoundationVisibleFlags) — are on
+     *  for this workspace. Not every flag: most are irrelevant or sensitive and
+     *  never reach this channel. Sourced from the exchange RESPONSE at mint time
+     *  (see mint-bearer.ts), deliberately not a bearer claim — flags are
+     *  configuration with their own freshness (refresh via fetchSessionFlags),
+     *  so decodeBearer never populates this. Use hasFlag() to check one; any
+     *  AND/OR combination is the caller's own logic over this raw set. */
+    flags?: string[];
 }
+/** Whether a decoded session carries the given flag key. Null-safe so callers
+ *  can chain straight off decodeBearer()'s result without a separate guard. */
+export declare function hasFlag(session: ExchangedSession | null, key: string): boolean;
 export declare function decodeBearer(bearer: string): ExchangedSession | null;

package/dist/session-exchange.js

@@ -73,6 +73,11 @@ export function parseExchangeRejection(value) {
 export function isSessionExchangeEnabled() {
     return process.env.ENABLE_APP_SESSION_TOKEN_EXCHANGE === 'true';
 }
+/** Whether a decoded session carries the given flag key. Null-safe so callers
+ *  can chain straight off decodeBearer()'s result without a separate guard. */
+export function hasFlag(session, key) {
+    return session?.flags?.includes(key) ?? false;
+}
 // Decodes a base64url JWT segment to a UTF-8 string using only Web APIs (atob,
 // TextDecoder), so decodeBearer runs in BOTH the Edge middleware runtime (proxy)
 // and the Node route-handler runtime (requireAuth / getAssemblyForRequest) —

package/package.json

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

package/skills/assembly-integrations/SKILL.md

@@ -98,7 +98,7 @@ A connector call throws a **`ConnectorError`** (with `.code`, `.provider`, `.sta
 - `connection_required` / `needs_reauth` / `needs_reauth_scope` — the workspace admin needs to (re)connect the provider in app settings. Render a "needs setup / reconnect" state, not a crash.
 - `connection_throttled` — too many calls on the shared connection; back off and retry.
 - `connector_unavailable` — the provider or Nango is temporarily unavailable.
-- `action_failed` — the pre-built action ran but the provider rejected the operation. The provider-level failure is in `err.detail` (e.g. `detail.response.error` is Slack's error code) — branch on it the way you would on a proxy response's error field.
+- `action_failed` — the pre-built action ran but the provider rejected the operation. The provider-level failure is in `err.detail`, but scripts disagree on where the provider's code sits inside it, so never read `detail` by hand. For Slack call `slackErrorCode(err)` (returns e.g. `'not_in_channel'`, `'is_archived'`) and branch on that; for other providers branch on `err.detail` the way you would on a proxy response's error field.
 - `app_key_required` / `provider_not_declared` — a wiring bug: you called from an unauthenticated scope, or didn't declare the provider in `requiredIntegrations`. Fix the call site / manifest.
 - `invalid_request` — malformed relay input (bad action name, unreadable body). Fix the call site.
 

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

@@ -1,25 +1,41 @@
 # Slack
 
-Writes need membership, not just visibility. `send-message` reaches public channels without joining; other writes fail `not_in_channel` until the bot joins.
+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.
 
 - **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`.
-- **Other writes (reactions, invites):** on `not_in_channel`, call `join-channel` with the channel ID, then retry once. Private channels fail `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 writes need `join-channel`. Add `groups:read` if the app must find private channels.
+- **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.
+- **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.
 
 ```typescript
-import { getIntegration, slackFindChannelId, slackPostMessage } from '@assembly-js/app-foundation/server';
+import {
+  getIntegration,
+  slackErrorCode,
+  slackFindChannelId,
+  slackListChannels,
+  slackPostMessage,
+} 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' });
 ```
 
 ```typescript
-const history = await slack.action('get-conversation-history', {
-  channel_id: channelId,
-  limit: 10,
-});
+// Reads need membership too: join on not_in_channel and retry once.
+async function history(channelId: string) {
+  const input = { channel_id: channelId, limit: 10 };
+  try {
+    return await slack.action('get-conversation-history', input);
+  } catch (err) {
+    if (slackErrorCode(err) !== 'not_in_channel') throw err;
+    await slack.action('join-channel', { channel_id: channelId });
+    return slack.action('get-conversation-history', input);
+  }
+}
 ```
 
 For an operation no action covers, relay through the proxy — e.g. `slack.post({ endpoint: '/chat.update', data: { channel: channelId, ts, text } })`.

package/skills/assembly-session-token/SKILL.md

@@ -66,6 +66,8 @@ export function ClientList() {
 }
 ```
 
+`deps` works like a `useEffect` dependency array, with one rule: **deps must be primitives** — an id, a cursor, a `length`, a boolean. A derived array or object (`records`, `{ baseId }`, `items.filter(...)`) is a new identity on every render, so the action re-runs, its state update re-renders, and the page spins forever without a network call or an error to point at. Pass `records.length` or the id the array came from instead.
+
 `deps` works like a `useEffect` dependency array — list any values your action closes over so it re-runs when they change.
 
 For an imperative one-off (a button handler, a mutation), use `callAction` from `useAssembly()` — same re-exchange-and-retry behavior, no hook: