@assembly-js/app-foundation 0.0.8 → 0.0.10-rc.1

package/CLAUDE.md

@@ -25,6 +25,9 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-companies` — many-to-many with clients; placeholder companies (excluded from `listCompanies` by default for these apps)
 - `assembly-clients-companies` — REQUIRED when the app stores or scopes data by client or company: scoped tables carry BOTH a `clientId` and a `companyId` column and are filtered on the intersection (never one dimension); a client viewer always has an active `companyId`; `companyIds[]` builds pickers only and `client.companyId` is deprecated
 - `assembly-custom-fields` — workspace-defined fields, multiSelect rules
+<!-- feature:platform-mcp -->
+- `assembly-platform-mcp` — provisioning workspace configuration at build time via the scoped `mcp__platform__` tools: create a custom field the app depends on instead of shipping an app that gates on missing workspace setup. Workspace configuration only — never client-facing data.
+<!-- /feature:platform-mcp -->
 - `assembly-native-resources` — native message channels, forms, portal files/file channels: never hardcode their IDs, discover them at runtime
 - `assembly-mutations` — minimal `requestBody` rule for `update*` calls
 <!-- !feature:notification-settings -->
@@ -916,7 +919,7 @@ try {
 
 Writes (creates, updates, deletes — including `createNotification` and `markNotificationRead`) are capped at **5 concurrent per token**. `Promise.all(list.map(...))` over a recipient or record list fires every call at once; past ~5 items the excess come back `429` and either get dropped or surface to the user as a failed request. It passes a quick test and breaks once a real workspace has enough rows — so don't wait to see it fail.
 
-Cap concurrency below the bucket and retry the `429`s with backoff. Write a small `sendThrottled(items, fn)` helper in `lib/notify.ts` — concurrency 3, exponential-backoff retry on `429` — and route every list-sized write fan-out through it, notification sends and badge clears included. A **fixed handful** of calls (two or three for one event) is fine with `Promise.all` — the cap only bites when the count is driven by a list.
+Route every list-sized write fan-out through `sendThrottled(items, fn)` from `@assembly-js/app-foundation/server` — concurrency 3, exponential-backoff retry on `429`, settles instead of throwing. Do not write your own copy. Notification sends and badge clears included (for badge clears, prefer `clearClientNotifications`, which throttles internally). A **fixed handful** of calls (two or three for one event) is fine with `Promise.all` — the cap only bites when the count is driven by a list.
 
 ### Custom fields — ALWAYS discover the key dynamically, never hardcode
 
@@ -1109,7 +1112,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't detect viewer type with `try { listClients() } catch (403)`. Use `getSessionIdentity()` (server) or `useAssembly()` (client) and branch on `internalUserId` vs `clientId`.
 - ❌ Don't include `companyId` (or any other unchanged field) in `updateClient.requestBody` "for completeness". Each field in `requestBody` is treated as a write — passing `companyId` triggers a company-reassignment path that clients can't perform, and the whole update fails. Pass ONLY the fields the user is actually changing.
 - ❌ Don't hardcode mutation error messages like "Failed to save preference". Read `error` from the response body and surface it to the user.
-- ❌ Don't `Promise.all` a list-sized write fan-out (one `createNotification` / `markNotificationRead` / update per recipient or record). Writes cap at 5 concurrent per token; firing a whole list 429s and silently drops the overflow. Cap concurrency and retry 429s through a `sendThrottled` helper. A fixed handful of calls is the only exception. See "Write rate limit" above.
+- ❌ Don't `Promise.all` a list-sized write fan-out (one `createNotification` / `markNotificationRead` / update per recipient or record). Writes cap at 5 concurrent per token; firing a whole list 429s and silently drops the overflow. Use `sendThrottled` from `@assembly-js/app-foundation/server`. A fixed handful of calls is the only exception. See "Write rate limit" above.
 - ❌ Don't use title case — see "Labels, copy, and dropdowns" above.
 - ❌ Don't render raw IDs or pass a raw ID string as `value` on `ComboboxItem` — see "Select and Combobox — base-ui differences" above.
 - ❌ Don't write a scalar string to a custom field that has options. **All option-bearing custom fields are `multiSelect` in Assembly's schema** — even ones that LOOK like single-select dropdowns. The value must always be an array of option keys: `{ favorite_pizza: ['pepperoni'] }`, never `{ favorite_pizza: 'pepperoni' }`. A scalar string for a multiSelect causes a 400 with `invalid custom field option <value> provided`.

package/dist/assembly.d.ts

@@ -20,6 +20,34 @@ export declare class TokenInvalidError extends Error {
     constructor(message?: string);
 }
 export declare function getAssembly(input?: AssemblyInput): Promise<AssemblyAPI>;
+/**
+ * Runs `task` after the response is sent (Next's `after()`), with a viewer-
+ * authenticated SDK client — the ONLY supported way to defer authenticated work
+ * past the response boundary. Use it for side work that shouldn't block the
+ * render, e.g. clearing a client's notification badge on view.
+ *
+ * Why this exists: inside a bare `after()` callback the response has already
+ * gone out and `cookies()`/`headers()` are no longer reliably readable, so
+ * `getAssembly()` called there throws `TokenInvalidError` on every request —
+ * silently, since nothing surfaces to the viewer. This helper captures the
+ * viewer's credential at call time (while request scope is still live) and
+ * hands the deferred task a ready client built from it.
+ *
+ * Failures log and return — the viewer's response already succeeded, so a
+ * failed deferred task must never become an unhandled rejection.
+ *
+ * @example
+ *   // app/c/requests/[id]/page.tsx — clear the badge without blocking render
+ *   afterAssembly(async (assembly) => {
+ *     await clearClientNotifications({ assembly, clientId, ctaParams: { requestId } });
+ *   });
+ *
+ * Legacy (exchange-off) apps have no ambient bearer; pass the page's session
+ * token explicitly: `afterAssembly(task, { token })`.
+ */
+export declare function afterAssembly(task: (assembly: AssemblyAPI) => Promise<unknown>, options?: {
+    token?: string;
+}): void;
 /**
  * OFFLINE / BACKGROUND ONLY — cron jobs, webhook handlers, and any other code
  * path where there is NO user in the loop and thus no session token or bearer

package/dist/assembly.js

@@ -1,6 +1,6 @@
 import { assemblyApi } from '@assembly-js/node-sdk';
 import { cookies, headers } from 'next/headers';
-import { NextResponse } from 'next/server';
+import { after, NextResponse } from 'next/server';
 import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
 import { mintBearerFromAppKey } from './mint-bearer.js';
 // Trusted API origin for this stack, supplied by the build environment — NOT by
@@ -94,15 +94,18 @@ export class TokenInvalidError extends Error {
 export async function getAssembly(input) {
     const token = typeof input === 'string' ? input : input?.token;
     // Exchange enabled ⇒ this is a bearer-capable app, and it authenticates via
-    // the exchanged bearer ALONE. The raw session token is a one-time bootstrap
-    // credential the proxy already consumed for the cookie; it is never a request
-    // credential here (any `input` token is ignored). The SDK is initialised with
-    // the bearer only — no apiKey, no token — so every call carries
-    // `Authorization: Bearer` and NEVER an X-API-Key. No bearer means the request
-    // is unauthenticated, or is replaying a consumed token that still decrypts —
-    // either way refuse, so the client re-exchanges instead of rendering.
+    // the exchanged bearer. `resolveRequestBearer()` reads it from `cookies()`/
+    // `headers()`, which are only reliably readable during the request/render —
+    // NOT inside a deferred `next/server` `after()` callback (the response has
+    // already been sent by then, and those Dynamic APIs can silently fail to
+    // return the proxy-forwarded header or cookie there). Code that must run
+    // after the response — e.g. a badge-clear a caller wants off the render's
+    // critical path — should resolve the bearer synchronously BEFORE calling
+    // after() and pass it through explicitly as `input.token`; this honors that
+    // pre-resolved bearer instead of re-deriving it from request scope. The
+    // common case (no explicit token) is unchanged: derive from the request.
     if (isSessionExchangeEnabled()) {
-        const bearer = await resolveRequestBearer();
+        const bearer = token ?? (await resolveRequestBearer());
         if (!bearer) {
             throw new TokenInvalidError('Assembly bearer is required');
         }
@@ -146,6 +149,51 @@ export async function getAssembly(input) {
     }
     return assembly;
 }
+/**
+ * Runs `task` after the response is sent (Next's `after()`), with a viewer-
+ * authenticated SDK client — the ONLY supported way to defer authenticated work
+ * past the response boundary. Use it for side work that shouldn't block the
+ * render, e.g. clearing a client's notification badge on view.
+ *
+ * Why this exists: inside a bare `after()` callback the response has already
+ * gone out and `cookies()`/`headers()` are no longer reliably readable, so
+ * `getAssembly()` called there throws `TokenInvalidError` on every request —
+ * silently, since nothing surfaces to the viewer. This helper captures the
+ * viewer's credential at call time (while request scope is still live) and
+ * hands the deferred task a ready client built from it.
+ *
+ * Failures log and return — the viewer's response already succeeded, so a
+ * failed deferred task must never become an unhandled rejection.
+ *
+ * @example
+ *   // app/c/requests/[id]/page.tsx — clear the badge without blocking render
+ *   afterAssembly(async (assembly) => {
+ *     await clearClientNotifications({ assembly, clientId, ctaParams: { requestId } });
+ *   });
+ *
+ * Legacy (exchange-off) apps have no ambient bearer; pass the page's session
+ * token explicitly: `afterAssembly(task, { token })`.
+ */
+export function afterAssembly(task, options) {
+    // Capture the credential NOW — after() runs past the response boundary,
+    // where cookies()/headers() reads are unreliable.
+    const credential = options?.token
+        ? Promise.resolve(options.token)
+        : resolveRequestBearer().catch(() => undefined);
+    after(async () => {
+        try {
+            const token = await credential;
+            if (!token) {
+                console.error('afterAssembly: no viewer credential was available at call time; deferred task skipped');
+                return;
+            }
+            await task(await getAssembly({ token }));
+        }
+        catch (err) {
+            console.error('afterAssembly: deferred task failed', err);
+        }
+    });
+}
 // Duplicated from lib/auth.ts to avoid a circular import.
 function tokenExpiredResponse() {
     return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });

package/dist/notifications.d.ts

@@ -0,0 +1,47 @@
+export declare function sendThrottled<T, R>(items: T[], task: (item: T) => Promise<R>): Promise<PromiseSettledResult<R>[]>;
+export declare function logFailures(results: PromiseSettledResult<unknown>[], label: string): void;
+interface NotificationRecord {
+    id?: string;
+    deliveryTargets?: {
+        inProduct?: {
+            ctaParams?: Record<string, string>;
+        };
+    };
+}
+interface NotificationsClient {
+    listNotifications(args: {
+        recipientClientId: string;
+    }): Promise<{
+        data?: NotificationRecord[];
+    }>;
+    markNotificationRead(args: {
+        id: string;
+    }): Promise<unknown>;
+}
+export interface ClearClientNotificationsInput {
+    /** SDK client from getAssembly() — any client works, only two methods are used. */
+    assembly: NotificationsClient;
+    /** The viewer's clientId (e.g. from getSessionIdentity()). No-op when absent,
+     *  so callers can pass it straight through without narrowing first. */
+    clientId: string | undefined | null;
+    /** Clear only notifications whose inProduct ctaParams contain ALL of these
+     *  key/value pairs — the same ctaParams the app set on create. Omit to clear
+     *  every unread notification for the client (single-notification-kind apps). */
+    ctaParams?: Record<string, string>;
+}
+/**
+ * Clears the client portal badge: lists the client's unread in-product
+ * notifications, filters in memory by the given ctaParams (the API has no
+ * sub-recipient filter), and marks the matches read through the throttled
+ * fan-out so long lists never 429. Every createNotification({ recipientClientId })
+ * an app makes must be paired with a call to this — on view for awareness
+ * notifications, inside the completing server action for prompts.
+ *
+ * Never throws: the viewer's page or action already succeeded, so a failed
+ * clear logs and returns rather than breaking the response.
+ */
+export declare function clearClientNotifications({ assembly, clientId, ctaParams, }: ClearClientNotificationsInput): Promise<{
+    cleared: number;
+    failed: number;
+}>;
+export {};

package/dist/notifications.js

@@ -0,0 +1,83 @@
+// Notification helpers generated apps previously had to hand-write per app
+// (lib/notify.ts): a 429-aware fan-out throttle and the client badge-clear
+// pattern. They live in the package so the behavior is a deterministic import,
+// not prose the build agent re-implements (and sometimes gets wrong) each time.
+// Platform writes are capped at 5 concurrent per token; 3 leaves headroom for
+// the app's own unrelated in-flight writes.
+const CONCURRENCY = 3;
+const MAX_RETRIES = 3;
+async function withRetry(task) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await task();
+        }
+        catch (err) {
+            const status = err?.status; // SDK throws ApiError with numeric status
+            if (status !== 429 || attempt >= MAX_RETRIES)
+                throw err;
+            await new Promise((r) => setTimeout(r, 200 * 2 ** attempt + Math.random() * 100));
+        }
+    }
+}
+// Runs `task` over every item, at most CONCURRENCY in flight, retrying 429s.
+// Settles instead of throwing so one bad item never aborts the rest.
+export async function sendThrottled(items, task) {
+    const results = [];
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < items.length) {
+            const i = cursor++;
+            try {
+                results[i] = { status: 'fulfilled', value: await withRetry(() => task(items[i])) };
+            }
+            catch (reason) {
+                results[i] = { status: 'rejected', reason };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, items.length) }, worker));
+    return results;
+}
+// Log partial failures; the caller's data write already committed, so don't throw.
+export function logFailures(results, label) {
+    const failed = results.filter((r) => r.status === 'rejected').length;
+    if (failed)
+        console.error(`${failed}/${results.length} ${label} failed`);
+}
+/**
+ * Clears the client portal badge: lists the client's unread in-product
+ * notifications, filters in memory by the given ctaParams (the API has no
+ * sub-recipient filter), and marks the matches read through the throttled
+ * fan-out so long lists never 429. Every createNotification({ recipientClientId })
+ * an app makes must be paired with a call to this — on view for awareness
+ * notifications, inside the completing server action for prompts.
+ *
+ * Never throws: the viewer's page or action already succeeded, so a failed
+ * clear logs and returns rather than breaking the response.
+ */
+export async function clearClientNotifications({ assembly, clientId, ctaParams, }) {
+    if (!clientId)
+        return { cleared: 0, failed: 0 };
+    try {
+        const { data: notifications = [] } = await assembly.listNotifications({
+            recipientClientId: clientId,
+        });
+        const toClear = notifications.filter((n) => {
+            if (!n.id)
+                return false;
+            if (!ctaParams)
+                return true;
+            const params = n.deliveryTargets?.inProduct?.ctaParams;
+            return (params !== undefined &&
+                Object.entries(ctaParams).every(([k, v]) => params[k] === v));
+        });
+        const results = await sendThrottled(toClear, (n) => assembly.markNotificationRead({ id: n.id }));
+        logFailures(results, 'badge clears');
+        const failed = results.filter((r) => r.status === 'rejected').length;
+        return { cleared: results.length - failed, failed };
+    }
+    catch (err) {
+        console.error('clearClientNotifications failed', err);
+        return { cleared: 0, failed: 0 };
+    }
+}

package/dist/server.d.ts

@@ -6,6 +6,7 @@ export * from './mint-bearer.js';
 export * from './nango.js';
 export * from './app-storage.js';
 export * from './labels.js';
+export * from './notifications.js';
 export * from './api-errors.js';
 export * from './params.js';
 export * from './client.js';

package/dist/server.js

@@ -10,6 +10,7 @@ export * from './mint-bearer.js';
 export * from './nango.js';
 export * from './app-storage.js';
 export * from './labels.js';
+export * from './notifications.js';
 // Returns NextResponse, so route handlers only — but nothing here reads a
 // secret, which is why a client file may still `import type` from them.
 export * from './api-errors.js';

package/package.json

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

package/skills/assembly-notifications/SKILL.md

@@ -278,63 +278,19 @@ Frequency is not a criterion: a one-time client action is a legitimate fit ("Sig
 
 `createNotification` is a write, and a token's writes are capped at **5 concurrent** (a token-bucket limit shared across *all* the request's writes). `Promise.all(list.map(createNotification))` fires every call at once: past ~5 recipients the overflow returns `429` and is dropped or surfaces as a failed request. It passes a quick test and breaks once a workspace has enough users — so don't wait to see it fail.
 
-Cap concurrency below the bucket (3 leaves headroom) and retry 429s with backoff. No dependency — external libraries are forbidden and a small helper covers it. Define it once and reuse it for every list-sized write fan-out (sends, badge clears, batch updates):
+The foundation ships the helper — do not write your own copy:
 
 ```ts
-// lib/notify.ts — throttle a write fan-out under the 5-concurrent cap, retry 429s.
-const CONCURRENCY = 3;
-const MAX_RETRIES = 4;
-
-async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
-  for (let attempt = 0; ; attempt++) {
-    try {
-      return await fn();
-    } catch (err) {
-      const status = (err as { status?: number })?.status; // SDK throws ApiError with numeric status
-      if (status !== 429 || attempt >= MAX_RETRIES) throw err;
-      await new Promise((r) => setTimeout(r, 200 * 2 ** attempt + Math.random() * 100));
-    }
-  }
-}
-
-// Runs `task` over every item, at most CONCURRENCY in flight, retrying 429s.
-// Settles instead of throwing so one bad item never aborts the rest.
-export async function sendThrottled<T, R>(
-  items: T[],
-  task: (item: T) => Promise<R>,
-): Promise<PromiseSettledResult<R>[]> {
-  const results: PromiseSettledResult<R>[] = [];
-  let cursor = 0;
-  const worker = async () => {
-    while (cursor < items.length) {
-      const i = cursor++;
-      try {
-        results[i] = { status: 'fulfilled', value: await withRetry(() => task(items[i])) };
-      } catch (reason) {
-        results[i] = { status: 'rejected', reason };
-      }
-    }
-  };
-  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, items.length) }, worker));
-  return results;
-}
+import { sendThrottled, logFailures } from '@assembly-js/app-foundation/server';
 
-// Log partial failures; the caller's data write already committed, so don't throw.
-export function logFailures(results: PromiseSettledResult<unknown>[], label: string) {
-  const failed = results.filter((r) => r.status === 'rejected').length;
-  if (failed) console.error(`${failed}/${results.length} ${label} failed`);
-}
-```
-
-Route every recipient-list fan-out through it, then log partial failures:
-
-```ts
 const results = await sendThrottled(recipients, (u) =>
   assembly.createNotification({ requestBody: { senderId, recipientInternalUserId: u.id, deliveryTargets } }),
 );
 logFailures(results, 'notifications');
 ```
 
+`sendThrottled` runs at most 3 tasks in flight and retries 429s with backoff; it settles instead of throwing so one bad item never aborts the rest. `logFailures` logs partial failures without throwing (the caller's data write already committed). Route every recipient-list write fan-out through it — sends, badge clears, batch updates.
+
 A **fixed handful** of calls (two or three for one event) never exceeds the bucket — a plain `Promise.all` is fine there. The cap only bites when the count is driven by a list. The same helper applies to `markNotificationRead` badge clears (see the `clearing-client-notifications` skill).
 
 ### Avoiding duplicates
@@ -376,9 +332,9 @@ Because clients see a badge counter rather than a Notification Center, every `cr
 - **Clear on view** — for informational notifications. Mark read when the client opens the corresponding content (a status update, a reply, a ready deliverable).
 - **Clear on action** — for notifications that ask the client to *do* something. Mark read inside the server action that completes the work (filling a form, marking a task done, granting an approval) — clearing on view would drop the prompt before they act.
 
-Either way, list the client's unread notifications and filter in memory by the `ctaParams` you set on create, then clear only those — there is no server-side filter below the recipient level.
+Either way, the clear is one foundation call — `clearClientNotifications({ assembly, clientId, ctaParams })` from `@assembly-js/app-foundation/server` — which lists, filters by your `ctaParams`, and marks read with throttling built in.
 
-**If your app sends any client notification, load the `clearing-client-notifications` skill** for the full pattern, code for both cases, and the pre-ship checklist. Don't consider a client-facing app done until the matching clear is implemented and you can name where it runs.
+**If your app sends any client notification, load the `clearing-client-notifications` skill** for where to place the call in both patterns and the pre-ship checklist. Don't consider a client-facing app done until the matching clear is implemented and you can name where it runs.
 
 ## Apps with multiple notification types
 

package/skills/assembly-platform-mcp/SKILL.md

@@ -0,0 +1,23 @@
+<!-- feature:platform-mcp -->
+---
+name: assembly-platform-mcp
+description: Use when the app you are building depends on workspace configuration that does not exist yet — most commonly a custom field on clients or companies (the user asked for "call clients at their phone number" and no Phone-type client field exists). You have a scoped platform MCP server (tool prefix mcp__platform__) for provisioning that configuration at build time instead of shipping an app that gates on missing workspace setup. Workspace configuration only — never client-facing data (no creating clients, sending messages, notifications, or invoices).
+---
+
+## Provisioning custom fields at build time
+
+You have a scoped platform MCP server (tool prefix `mcp__platform__`). When the app you are building depends on a custom field the workspace does not have yet — the user asked for "call clients at their phone number" and no Phone-type client field exists — provision it yourself at build time instead of shipping an app that gates on missing workspace config:
+
+```
+mcp__platform__custom_fields with action "list"        — check what exists first
+mcp__platform__custom_fields with action "create"      — create the missing field
+```
+
+Rules:
+
+- **Check before creating** (`list`, match case-insensitively by name) — never create a duplicate of a field that already exists under a slightly different name.
+- **Creating a field does not replace graceful handling.** The app's runtime code must still handle the field being absent or renamed later (discover by name, render a setup hint — see the assembly-custom-fields skill for the runtime contract) — you provision the field the app *starts* with; you don't get to assume it forever.
+- **Never delete fields.** Deletion is not available to you by policy: fields carry data on real client records.
+- **This tool is for workspace configuration only.** Do not reach for `mcp__platform__*` to create clients, send messages/notifications/invoices, or touch any client-facing data — those denials are enforced server-side and the attempt wastes a turn.
+- Tell the user in chat, in product terms, when you create a field ("I added a Phone number field to your client records so the app can call them").
+<!-- /feature:platform-mcp -->

package/skills/clearing-client-notifications/SKILL.md

@@ -1,100 +1,97 @@
 ---
 name: clearing-client-notifications
-description: REQUIRED whenever the app calls createNotification with recipientClientId. Use when building any client-facing view that shows content a client was notified about, or any client action that completes something a notification prompted — so the portal sidebar badge clears. Covers the two clearing patterns (clear-on-view vs clear-on-action) with markNotificationRead.
+description: REQUIRED whenever the app calls createNotification with recipientClientId. Use when building any client-facing view that shows content a client was notified about, or any client action that completes something a notification prompted — so the portal sidebar badge clears. Covers the two clearing patterns (clear-on-view vs clear-on-action) with the foundation's clearClientNotifications helper.
 ---
 
 ## Why this exists
 
-Clients do not have a Notification Center. When you send an in-product notification to a client (`recipientClientId`), the portal shows a **counter badge** next to the app in the sidebar. Nothing clears that badge automatically — the app must call `markNotificationRead` at the right moment. If you create client notifications and never clear them, the badge sticks forever. **This is the single most common bug in client-facing apps**, and it is invisible during a quick demo: the notification arrives correctly, so the create path looks done, but the badge never goes down.
+Clients do not have a Notification Center. When you send an in-product notification to a client (`recipientClientId`), the portal shows a **counter badge** next to the app in the sidebar. Nothing clears that badge automatically — the app must clear it at the right moment. If you create client notifications and never clear them, the badge sticks forever. **This is the single most common bug in client-facing apps**, and it is invisible during a quick demo: the notification arrives correctly, so the create path looks done, but the badge never goes down.
 
-Treat every `createNotification({ recipientClientId })` as half of a pair. The other half — the `markNotificationRead` that clears it — lives in a *different file* (the client's view route or server action), so it's easy to forget. If your app sends any client notification, you are not finished until the matching clear is implemented and you can name where it runs.
+Treat every `createNotification({ recipientClientId })` as half of a pair. The other half — the clear — lives in a *different file* (the client's view route or server action), so it's easy to forget. If your app sends any client notification, you are not finished until the matching clear is implemented and you can name where it runs.
 
 This does not apply to internal users (their Notification Center auto-clears) or to email-only notifications (no badge). It applies precisely when the recipient is a client and `deliveryTargets.inProduct` is set.
 
-## Pick the pattern by intent
-
-There are two valid clearing patterns. Choosing the wrong one is its own bug:
+## The helper
 
-- **Clear on view** — the notification is informational ("here's something new to see"). Clear it when the client opens the corresponding content. Examples: a status update, a reply, a deliverable ready to download, a new resource posted.
-- **Clear on action** — the notification is asking the client to *do* something. Clearing on view is wrong here: the client opens the page, doesn't finish, leaves, and the prompt is gone. Clear it inside the server action that completes the work. Examples: a form to fill out, a task to mark done, an approval to grant, an RSVP to submit.
+Do not hand-roll the clear. The foundation ships it:
 
-If you clear on view when you should clear on action, you drop reminders the client still needs. If you clear on action when view was right, the badge lingers because the client may never take a discrete action. Match the pattern to what the notification is asking for.
+```ts
+import { clearClientNotifications } from '@assembly-js/app-foundation/server';
 
-## Scoping the clear
+await clearClientNotifications({
+  assembly,               // from getAssembly()
+  clientId: id?.clientId, // from getSessionIdentity(); safe to pass undefined (no-op)
+  ctaParams: { submissionId }, // clear only notifications created with these ctaParams
+});
+```
 
-Custom apps can't filter `listNotifications` below the recipient level — there is no `appId`, `resourceId`, or `ctaParams` filter on the API. So list the client's unread notifications and **filter in memory by the `ctaParams` you set on create**, then clear only those. This keeps you from clearing unrelated notifications the client hasn't seen yet.
+It lists the client's unread notifications, filters in memory by your `ctaParams` (the API has no sub-recipient filter), and marks the matches read through a throttled fan-out that retries 429s — so a long list never trips the 5-concurrent write cap. It never throws: the viewer's page or action already succeeded, so a failed clear logs instead of breaking the response. Omit `ctaParams` only when the app sends a single kind of client notification and the client is landing on the obvious "inbox" view.
 
-`listNotifications` returns unread-only by default — you do not need to pass a flag to get the unread set.
+## Pick the pattern by intent
 
-If your app only ever sends one kind of client notification and the client lands on the obvious "inbox" view, clearing all unread for that recipient on view is acceptable.
+There are two valid clearing patterns. Choosing the wrong one is its own bug:
 
-`markNotificationRead` is a write, and writes are capped at **5 concurrent** per token — so don't `Promise.all` the clears over a list that could exceed a handful, or the overflow `429`s and the badge silently stays up. Fan out through a `sendThrottled(items, fn)` helper in `lib/notify.ts` — concurrency 3, exponential-backoff retry on `429`. The examples below import it alongside a `logFailures(results)` helper that reports rejected entries; write both if the app does not have them yet.
+- **Clear on view** — the notification is informational ("here's something new to see"). Call `clearClientNotifications` in the server component that renders the corresponding content. Examples: a status update, a reply, a deliverable ready to download, a new resource posted.
+- **Clear on action** — the notification is asking the client to *do* something. Clearing on view is wrong here: the client opens the page, doesn't finish, leaves, and the prompt is gone. Call `clearClientNotifications` inside the `'use server'` action that completes the work, after the work's own write. Examples: a form to fill out, a task to mark done, an approval to grant, an RSVP to submit.
 
-## Pattern A — clear on view
+If you clear on view when you should clear on action, you drop reminders the client still needs. If you clear on action when view was right, the badge lingers because the client may never take a discrete action. Match the pattern to what the notification is asking for.
 
 ```tsx
-// app/(client)/submissions/[id]/page.tsx
-import { getAssembly, getSessionIdentity } from '@assembly-js/app-foundation/server';
-import { sendThrottled, logFailures } from '@/lib/notify';
-
-export default async function SubmissionView({
-  params,
-}: {
-  params: Promise<{ id: string }>;
-}) {
+// Pattern A — clear on view: app/(client)/submissions/[id]/page.tsx
+import { getAssembly, getSessionIdentity, clearClientNotifications } from '@assembly-js/app-foundation/server';
+
+export default async function SubmissionView({ params }: { params: Promise<{ id: string }> }) {
   const assembly = await getAssembly();
   const id = await getSessionIdentity();
   const { id: submissionId } = await params;
 
-  // Clear unread notifications tied to this submission. listNotifications is unread-only by default.
-  const { data: notifications = [] } = await assembly.listNotifications({
-    recipientClientId: id?.clientId,
-  });
-  const toClear = notifications.filter(
-    (n) => n.deliveryTargets?.inProduct?.ctaParams?.submissionId === submissionId,
-  );
-
-  const results = await sendThrottled(toClear, (n) => assembly.markNotificationRead({ id: n.id! }));
-  logFailures(results, 'badge clears');
+  await clearClientNotifications({ assembly, clientId: id?.clientId, ctaParams: { submissionId } });
 
   return <SubmissionDetail id={submissionId} />;
 }
 ```
 
-## Pattern B — clear on action
-
 ```ts
-// app/(client)/tasks/[id]/complete.ts
+// Pattern B — clear on action: app/(client)/tasks/[id]/complete.ts
 'use server';
-
-import { getAssembly, getSessionIdentity } from '@assembly-js/app-foundation/server';
-import { sendThrottled, logFailures } from '@/lib/notify';
+import { getAssembly, getSessionIdentity, clearClientNotifications } from '@assembly-js/app-foundation/server';
 
 export async function completeTask(taskId: string) {
   const assembly = await getAssembly();
   const id = await getSessionIdentity();
 
-  // Complete the requested work first, then clear the notification that prompted it.
   await assembly.updateTask({ id: taskId, requestBody: { status: 'completed' } });
+  await clearClientNotifications({ assembly, clientId: id?.clientId, ctaParams: { taskId } });
+}
+```
+
+Assembly Forms are completed in Assembly's built-in Forms UI. The SDK can assign them with `requestFormResponse` and read submissions with `listFormResponses`, but it does not expose a method for a custom app to submit answers. Never invent a form-submission SDK method. For a form owned by the custom app, persist its data to the app's database before clearing the matching notification.
 
-  const { data: notifications = [] } = await assembly.listNotifications({
-    recipientClientId: id?.clientId,
+## Deferring the clear off the render's critical path
+
+Never wrap `getAssembly()` in a bare `after()`: once the response has gone out, `cookies()`/`headers()` are no longer reliably readable, so the deferred `getAssembly()` throws `TokenInvalidError` on every request and the clear silently never runs. If the clear should not block the render, use the foundation's `afterAssembly` — it captures the viewer's credential at call time and hands the deferred task a ready client:
+
+```tsx
+import { getSessionIdentity, afterAssembly, clearClientNotifications } from '@assembly-js/app-foundation/server';
+
+export default async function SubmissionView({ params }: { params: Promise<{ id: string }> }) {
+  const id = await getSessionIdentity();
+  const { id: submissionId } = await params;
+
+  afterAssembly(async (assembly) => {
+    await clearClientNotifications({ assembly, clientId: id?.clientId, ctaParams: { submissionId } });
   });
-  const toClear = notifications.filter(
-    (n) => n.deliveryTargets?.inProduct?.ctaParams?.taskId === taskId,
-  );
 
-  const results = await sendThrottled(toClear, (n) => assembly.markNotificationRead({ id: n.id! }));
-  logFailures(results, 'badge clears');
+  return <SubmissionDetail id={submissionId} />;
 }
 ```
 
-Assembly Forms are completed in Assembly's built-in Forms UI. The SDK can assign them with `requestFormResponse` and read submissions with `listFormResponses`, but it does not expose a method for a custom app to submit answers. Never invent a form-submission SDK method. For a form owned by the custom app, persist its data to the app's database before clearing the matching notification.
+The synchronous form is the default; reach for `afterAssembly` only when the view genuinely shouldn't wait on the clear.
 
 ## Checklist before you call a client-facing app done
 
-- For every `createNotification({ recipientClientId })`, there is a matching `markNotificationRead` somewhere in the client flow.
+- For every `createNotification({ recipientClientId })`, there is a matching `clearClientNotifications` somewhere in the client flow.
 - The clear runs from the **server** (a server component/route or a `'use server'` action), never from client-side code.
 - The pattern matches the intent — view for awareness, action for prompts.
 - The clear is scoped by `ctaParams` so it only marks the notifications the client actually engaged with.
-- The clear fans out through `sendThrottled`, not a bare `Promise.all`, so a long list of clears doesn't 429.
+- Any deferred clear goes through `afterAssembly`, never a bare `after()` around `getAssembly()`.