@assembly-js/app-foundation 0.0.19 → 0.0.21

package/CLAUDE.md

@@ -188,15 +188,14 @@ Because the app runs in an iframe inside the parent dashboard, several normal Ne
 - **Action buttons go in the header — set via the `useAssemblyHeader` hook.** Submit, Save, Edit, Create — any primary page-level action MUST live in the header (`primaryCta`), not a `<Button>` in the page body. Secondary actions use `secondaryCta`; overflow/tertiary actions use `actionsMenu`. Drive all of it through the `useAssemblyHeader` hook (`app/components/use-assembly-header.ts`) — **never call `AssemblyBridge.header.set*` from your own `useEffect`** (that hand-rolling is what makes header buttons vanish after a re-render). See `.claude/skills/assembly-app-bridge-header/SKILL.md` for the full API.
   **Exception: the notification surface (`/n`).** The Notification Center embeds the `/n` route in a plain `<iframe>` without app bridge header support. `useAssemblyHeader` calls are silently ignored — header CTAs never appear. On the notification surface, render primary actions as inline `<Button>` elements in the page body. Detect the notification surface by the route — code under `app/n/` IS the surface; for a shared component pass an explicit prop from the `/n` page rather than inferring from `payload.notificationId`, which is best-effort under the session-exchange flow. This exception applies ONLY to the `/n` route; all other surfaces MUST use the header. **Do not reuse a component that calls `useAssemblyHeader` on the `/n` surface** — if it also has an inline action button, both the header CTA and the inline button will render on non-notification surfaces (duplicate CTAs). Either create a separate component for `/n` or accept a prop that switches between header and inline CTAs.
 - **Theme + fonts.** The portal pushes the workspace's theme to the iframe via `app-bridge`. Don't hardcode brand colors; use neutrals + Tailwind defaults and let the parent's theme show through where appropriate.
-- **`allowedDevOrigins` is required in `next.config.ts`.** Next.js 15.3+ blocks cross-origin requests to the dev server by default. Because the app renders in an iframe whose parent origin differs from the dev server hostname (a `*.vercel.run` subdomain), the JS bundle is blocked without this config. Read the sandbox hostname from the `SANDBOX_HOST` env var (set automatically) and add it as a literal string:
+- **`next.config.ts` is platform-owned — never edit it. Your Next config lives in `app.config.ts`.** The wrapper in `next.config.ts` (`withAssemblyDev` from `@assembly-js/app-foundation/next`) spreads `app.config.ts` and applies the iframe-preview invariants on top: `allowedDevOrigins` for the sandbox host (without it the app renders but has zero interactivity — hydration JavaScript is blocked cross-origin) and disabling the React debug channel (without it the preview hangs forever for users on WebSocket-blocking networks). Put your configuration in `app.config.ts`:
   ```ts
-  // next.config.ts — the hostname is patched automatically before bun dev
-  // starts, but if you rewrite next.config.ts, include it:
-  const nextConfig: NextConfig = {
-    allowedDevOrigins: ['sb-XXXX.vercel.run'], // use $SANDBOX_HOST value
+  // app.config.ts — app-owned; the platform wrapper applies invariants on top
+  const appConfig: NextConfig = {
+    serverExternalPackages: ["sharp", "canvas", "@napi-rs/canvas"],
   };
   ```
-  Without this, the app appears to render (server HTML loads) but has zero interactivity — buttons, forms, and client components don't work because hydration JavaScript is blocked. **The dev server startup patches this automatically — but if you rewrite `next.config.ts`, preserve the `allowedDevOrigins` entry.**
+  `bun run build` fails (`check:next-config`) if `next.config.ts` is rewritten away from the wrapper form.
 - **Leave `instrumentation-client.ts` in place.** It's a dev-only preview helper (hides Next's red error overlay and relays build status to the builder preview) that no-ops in production. Don't remove or repurpose it.
 - **`localStorage` works** but is scoped per-origin — the app's own Vercel domain. Useful for caching, not for sharing state with the parent.
 - **Mobile-first layout with appropriate width.** The app renders in the iframe and must work down to 320 px. Design mobile-first: start with a single-column layout and scale up with `sm:`/`md:`/`lg:` breakpoints. **Content width depends on the app type:** most apps (tables, dashboards, boards) should use the full available width. Form-centric, single-column, or text-heavy apps that would look sparse at full width should center their content in a narrower column (`max-w-3xl mx-auto`). If the task description or plan specifies a content width, follow it; otherwise choose whichever looks better for the content. **When narrowing, place the `max-w-*` wrapper as the outermost page-level container** — outside `Tabs`, filter bars, and all other page chrome — so everything aligns to the same column. Do not narrow only the inner content of each tab panel while leaving `TabsList` or other siblings full-width.
@@ -327,7 +326,7 @@ Server components, route handlers, and server actions run in **Node on Vercel**
 
 - **Visual work** (draw a chart, render on a canvas) is **client** work — load the library with `next/dynamic` + `ssr: false`, never in server code.
 - **Fuzzy extraction** (pull fields from a document, classify, summarize) is usually better done through the **AI proxy** (see `assembly-ai`) than a parsing lib — no native binding, no serverless hazard.
-- **Genuine server-side data work** (transform an image, parse bytes) must use a Node-native library: add native/CommonJS packages (e.g. `sharp`) to `serverExternalPackages` in `next.config.ts` (bundling breaks the binding), and give any dep that's loaded dynamically or transitively a static, string-literal import in server code — the deploy tracer can't follow dynamic requires, so such a package silently won't exist in the deployed function even though preview works.
+- **Genuine server-side data work** (transform an image, parse bytes) must use a Node-native library: add native/CommonJS packages (e.g. `sharp`) to `serverExternalPackages` in `app.config.ts` (bundling breaks the binding), and give any dep that's loaded dynamically or transitively a static, string-literal import in server code — the deploy tracer can't follow dynamic requires, so such a package silently won't exist in the deployed function even though preview works.
 - **Browser-only packages** (touch `window`/`document`/`DOMMatrix`/`HTMLCanvasElement` at import *or during operations*) can't run server-side at all — `serverExternalPackages` doesn't help and dynamic `import()` only defers the crash. Use a Node-native alternative or move the work client-side.
 
 ---
@@ -645,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.
 }
 ```
 
@@ -1124,7 +1125,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't hand-roll UI components (`<button>`, `<input>`, `<dialog>`, `<table>`, etc.) when a shadcn component exists. See the Design system section for install instructions. Using `Link`/`<a className={buttonVariants(...)}>` for a button-looking link is the intentional exception.
 
 - ❌ Don't add a manual close button (a `<DialogClose>` render or any X button) inside `DialogContent`. `DialogContent` already ships a built-in close button (`showCloseButton` defaults to `true`); adding another produces two overlapping X icons in the top-right corner. Only pass `showCloseButton={false}` when a custom affordance genuinely replaces the built-in one.
-- ❌ Don't skip `allowedDevOrigins` in `next.config.ts`. The iframe preview will render static HTML but JavaScript never loads (no hydration, no interactivity). If you rewrite `next.config.ts`, read `$SANDBOX_HOST` from the shell env and add it as a literal string in the config.
+- ❌ Don't edit `next.config.ts` — it's the platform-owned wrapper that keeps the preview working (cross-origin hydration, WebSocket-blocked networks), and `bun run build` fails if it's rewritten. Your Next configuration belongs in `app.config.ts`.
 - ❌ Don't import a native or browser-only library into server code without the serverless setup — `bun run build` passes but the deployed route crashes at request time. Decide the layer first per "Server runs in serverless Node" above.
 - ❌ Don't use `Select` or `Combobox` to pick any Assembly person or organization record (clients, internal users, team members, staff, companies). Always use `UserCompanySelector` — in forms, filters, dropdowns, "assign to" controls, everywhere.
 - ❌ Don't use `Combobox` when the user asks for a "dropdown" or "select" — use `Select`. Only use `Combobox` when the user explicitly needs type-to-search/filter functionality for non-user/non-company data.

package/bin/check-next-config.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Fails the build when next.config has been rewritten away from the
+// platform-owned wrapper form. Dependency-free on purpose: it runs inside the
+// generated app's sandbox before any deps beyond Node exist.
+//
+// next.config.ts is platform boilerplate: `export default withAssemblyDev(appConfig)`.
+// The wrapper (from @assembly-js/app-foundation/next) applies the dev-preview
+// invariants — allowedDevOrigins from the sandbox host, and disabling the React
+// debug channel, whose loss silently hangs hydration forever on Next 16.3+ when
+// the dev WebSocket can't connect. Agents legitimately need Next config
+// (serverExternalPackages etc.) — that lives in app.config.ts, which the
+// wrapper spreads. Prose rules get skipped; a failing build doesn't.
+//
+// An app without app.config.ts predates the wrapper split (cloned from an older
+// foundation). There the wrapper form was never the contract, so this check
+// exits 0 — those apps are protected by the boot/restart patch scripts instead.
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const CONFIG_FILES = ['next.config.ts', 'next.config.mjs', 'next.config.js'];
+const APP_CONFIG_FILES = ['app.config.ts', 'app.config.mjs', 'app.config.js'];
+
+if (!APP_CONFIG_FILES.some((f) => existsSync(join(ROOT, f)))) {
+  process.exit(0); // pre-wrapper app: not this check's contract
+}
+
+const present = CONFIG_FILES.filter((f) => existsSync(join(ROOT, f)));
+
+// A second config file shadows the wrapper: Next loads only one of them, and
+// its pick may be the unwrapped copy — so validating just the canonical file
+// would bless a config the server never runs.
+if (present.length > 1) {
+  console.error(
+    `check-next-config: multiple next.config files found (${present.join(', ')}). ` +
+      'next.config.ts is the platform-owned wrapper — delete the other config file(s) ' +
+      'and put your Next configuration in app.config.ts instead.',
+  );
+  process.exit(1);
+}
+
+const configFile = present[0];
+if (!configFile) {
+  console.error(
+    'check-next-config: no next.config.{ts,mjs,js} found. Restore the platform-owned wrapper:\n\n' +
+      '  import { withAssemblyDev } from "@assembly-js/app-foundation/next";\n' +
+      '  import appConfig from "./app.config";\n' +
+      '  export default withAssemblyDev(appConfig);\n',
+  );
+  process.exit(1);
+}
+
+const content = readFileSync(join(ROOT, configFile), 'utf8');
+const importsWrapper = /from\s+['"]@assembly-js\/app-foundation\/next['"]/.test(content);
+const exportsWrapped = /export\s+default\s+withAssemblyDev\s*\(/.test(content);
+
+if (importsWrapper && exportsWrapped) {
+  process.exit(0);
+}
+
+console.error(
+  `check-next-config: ${configFile} is platform-owned and must stay in the wrapper form:\n\n` +
+    '  import { withAssemblyDev } from "@assembly-js/app-foundation/next";\n' +
+    '  import appConfig from "./app.config";\n' +
+    '  export default withAssemblyDev(appConfig);\n\n' +
+    'Put your Next configuration (serverExternalPackages, experimental flags, …) in app.config.ts — ' +
+    'the wrapper spreads it and applies the Assembly dev-preview invariants on top. ' +
+    'Editing next.config.ts directly drops those invariants and permanently breaks the preview ' +
+    'for users on WebSocket-blocking networks.',
+);
+process.exit(1);

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/next.d.ts

@@ -0,0 +1,2 @@
+import type { NextConfig } from 'next';
+export declare function withAssemblyDev(config?: NextConfig): NextConfig;

package/dist/next.js

@@ -0,0 +1,25 @@
+export function withAssemblyDev(config = {}) {
+    // Production builds (deploys) have no dev server, no HMR socket, and no
+    // sandbox host — the wrapper is a pass-through there.
+    if (process.env.NODE_ENV === 'production')
+        return config;
+    const sandboxHost = process.env.SANDBOX_HOST;
+    const allowedDevOrigins = sandboxHost
+        ? [...new Set([sandboxHost, ...(config.allowedDevOrigins ?? [])])]
+        : config.allowedDevOrigins;
+    // A dev WebSocket that never connects would otherwise hang hydration forever
+    // on Next 16.3+. Debug data falls back to the flight stream, so
+    // nothing user-visible is lost. Cast because this package type-checks against
+    // its Next 15 devDependency, which predates the flag; runtimes that predate
+    // it ignore the unknown key.
+    const experimental = {
+        ...config.experimental,
+        reactDebugChannel: false,
+    };
+    return {
+        ...config,
+        ...(allowedDevOrigins ? { allowedDevOrigins } : {}),
+        devIndicators: config.devIndicators ?? false,
+        experimental,
+    };
+}

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.19",
+  "version": "0.0.21",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -22,6 +22,10 @@
     "./lib-client": {
       "types": "./dist/lib-client.d.ts",
       "default": "./dist/lib-client.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
     }
   },
   "scripts": {

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: