@assembly-js/app-foundation 0.0.0 → 0.0.1-rc.1

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

@@ -0,0 +1,153 @@
+---
+name: assembly-session-token
+description: Use any time an app reads identity, fetches data, or wonders about auth/token handling. Covers the bearer lifecycle (session token exchanged once by the middleware → bearer cookie → getAssembly() → silent re-exchange on expiry), getSessionIdentity/useAssembly for identity, useServerAction/callAction for SDK-method data fetching, and authFetch for route handlers. Cross-references assembly-route-auth for requireAuth/requireCompanyScope.
+---
+
+Auth is **cookie-borne and automatic** — you never handle the session token and you never pass a token to anything. On the first load only, the parent opens your app at `…/?token=<session-token>`. The foundation middleware (`proxy.ts`) exchanges that session token exactly once (server-side, via `POST /v1/session`) for a short-lived **user-scoped bearer** and stores it in an HttpOnly, `SameSite=None` cookie. That mint is the only time the session token is ever used. Every server call your app makes reads the bearer from that cookie — `getAssembly()` returns an authenticated client with no token argument. The bearer lasts 60 minutes; when it expires, `authFetch` and `useServerAction` silently re-exchange (mint a fresh bearer from the parent's current session token via `/api/assembly-reexchange`) and retry — no reload, no code from you.
+
+Your job is to follow three rules.
+
+## Rule 1 — read identity from `getSessionIdentity()` (server) or `useAssembly()` (client)
+
+Never decode a token yourself and never call `AssemblyBridge.sessionToken.*` — that API is the foundation's, not yours.
+
+Server-side, `getSessionIdentity()` decodes the viewer from the bearer (no token, no API call). It returns `null` when unauthenticated:
+
+```ts
+import { getSessionIdentity } from '@assembly-js/app-foundation/server';
+
+const id = await getSessionIdentity();
+// { workspaceId, clientId?, companyId?, internalUserId? } | null
+if (id?.internalUserId) {
+  // internal staff — render the staff view
+} else if (id?.clientId) {
+  // client user — render their own view
+}
+```
+
+Client-side, the same fields come from `useAssembly()` — seeded from the server, so there's no token and no loading race:
+
+```tsx
+'use client';
+import { useAssembly } from '@/app/components/assembly-context';
+
+export function Greeting() {
+  const { isClient, internalUserId, clientId, workspaceId } = useAssembly();
+  return <p>{isClient ? 'Welcome' : 'Hello, teammate'}</p>;
+}
+```
+
+Branch your UI on identity **before** making data calls — it's faster and more reliable than catching a 403.
+
+## Rule 2 — fetch data with `useServerAction` (the bearer rides the cookie for you)
+
+Data fetching is done with **SDK methods inside server actions**, not by calling the Assembly API from the browser. Write a `'use server'` action that takes **no token** and calls `getAssembly()`, then run it from the client through `useServerAction` — which manages loading/error state and transparently re-exchanges + retries once if the bearer has expired:
+
+```ts
+// app/actions/clients.ts
+'use server';
+import { getAssembly } from '@assembly-js/app-foundation/server';
+
+export async function listClients() {
+  const assembly = await getAssembly(); // throws TokenInvalidError if the bearer is gone
+  return assembly.listClients({});
+}
+```
+
+```tsx
+// app/components/client-list.tsx
+'use client';
+import { useServerAction } from '@/app/components/use-server-action';
+import { listClients } from '@/app/actions/clients';
+
+export function ClientList() {
+  const { data, isLoading, error, reload } = useServerAction(() => listClients(), []);
+  // ...
+}
+```
+
+`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:
+
+```tsx
+const { callAction } = useAssembly();
+async function save(values: FormData) {
+  await callAction(() => updateClient(values));
+}
+```
+
+**Data server actions must let `TokenInvalidError` propagate** — do not wrap `getAssembly`/SDK calls in a `try/catch` that swallows the error into `null` or an empty result. The silent re-exchange only fires if the action *surfaces* the expiry.
+
+Do **not** hand-roll refresh logic: no bridge polling, no manual re-exchange + retry, no token subscriptions in components. `useServerAction`/`callAction` already do it.
+
+## Rule 3 — never touch the token in app code
+
+By the time your code runs, the bearer is already in the cookie. So:
+
+- **Never read `searchParams.token`** — not even on the entry route. The `?token=` on first load is the middleware's to consume, once. `getAssembly()` / `getSessionIdentity()` read the bearer cookie instead.
+- **Never put `?token=` in a `<Link>` / `router.push`.** Inner pages need nothing from the URL to be authenticated — auth is in the cookie. There is no `TokenLink`/`useWithToken`.
+- **Never pass a token to any function.** `getAssembly()`, server actions, and route handlers all take **no** token argument.
+- **Never store a token** in `useState`/`useRef`, a cookie you set, or anywhere else.
+
+```tsx
+// app/page.tsx — the entry page reads NO token; auth is already in the cookie.
+import { getAssembly } from '@assembly-js/app-foundation/server';
+
+export default async function Page() {
+  const assembly = await getAssembly();
+  // ...render initial server data, then hand off to client components that use useAssembly()
+}
+```
+
+## Route handlers — `authFetch` + `getAssemblyForRequest` (only when a route handler is the right tool)
+
+Server actions are the default. Use a route handler + `authFetch` only when you actually need one (streaming responses, file uploads, third-party webhooks). `authFetch` (from `app/components/lib-client.ts`) adds the required CSRF header; the bearer rides the cookie; it re-exchanges + retries once on a 401/403 from a bearer expiry:
+
+```tsx
+'use client';
+import { authFetch } from '@/app/components/lib-client';
+const res = await authFetch('/api/upload', { method: 'POST', body });
+```
+
+The handler authenticates with `getAssemblyForRequest(request)`, which returns a bearer-authenticated client or a 401 `NextResponse` (carrying the `x-assembly-token-expired` marker) — just return the `NextResponse` and `authFetch` re-exchanges and retries:
+
+```ts
+import { getAssemblyForRequest } from '@assembly-js/app-foundation/server';
+
+export async function POST(request: NextRequest) {
+  const assembly = await getAssemblyForRequest(request);
+  if (assembly instanceof NextResponse) return assembly;
+  // ...use assembly
+}
+```
+
+For `[id]`-scoped routes, guard with `requireAuth` then `requireCompanyScope` (see [[assembly-route-auth]]). `requireAuth` returns 401 (+ `x-assembly-token-expired` header) on an expired bearer; a 403 from `requireCompanyScope` is a permanent cross-tenant denial — a re-exchange will not fix it.
+
+## Background / offline work (cron, webhooks — no user present)
+
+Everything above is **request-scoped**: a user is in the loop and `getAssembly()` acts as that viewer. When there is no user session — a scheduled job or an incoming webhook — there's no bearer cookie to read. For those, call `getOfflineAssembly()` from `@assembly-js/app-foundation/server`: it mints an **app-scoped offline bearer** from your API key server-side and returns a bearer-only client.
+
+```ts
+// app/api/cron/sync/route.ts — no viewer, no cookie
+import { getOfflineAssembly } from '@assembly-js/app-foundation/server';
+
+export async function GET() {
+  const assembly = await getOfflineAssembly();
+  const { data: clients = [] } = await assembly.listClients();
+  // …background work…
+  return Response.json({ ok: true });
+}
+```
+
+It **throws** (not returns null) if `ASSEMBLY_API_KEY` is missing or the mint fails — there's no client to re-exchange in the background, so let it propagate. `getSessionIdentity()` returns `null` on this path (the bearer is the app, not a person). Only reach for this outside a request; ignore it for normal UI work.
+
+## What NOT to do
+
+- **No `AssemblyBridge.sessionToken.*` in app components** — the foundation owns the bridge; you authenticate with `getAssembly()`.
+- **No token in component `useState`/`useRef`** — there's no client-side token at all.
+- **No hand-rolled refresh/retry** — `useServerAction`/`callAction`/`authFetch` handle bearer expiry.
+- **No client-side `assemblyApi` calls** — every API call is server-side through `getAssembly()` / `getAssemblyForRequest()`.
+- **No cookies you set, no `x-assembly-token` header, no `?token=` proxy, no `TokenLink`/`useWithToken`** — the bearer cookie is the whole story.
+- **No `searchParams.token` anywhere** — not even the entry route.
+- **Don't swallow `TokenInvalidError` in data actions** — let it propagate so the re-exchange-and-retry can fire.

package/skills/assembly-storage/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: assembly-storage
+description: Stores and serves app-private files (attachments, exports, uploads only the app reads) via pre-signed S3 URLs. The client PUTs bytes directly to S3 — never proxy them through an API route. Use when an app uploads or downloads its own files; NOT for files the user wants in the portal Files tab (use the Files module / createFile for those).
+---
+
+## How it works
+
+Upload is two steps: (1) your server asks the platform for a pre-signed upload URL via `assembly.fetch()`, (2) the **client** PUTs the file straight to S3. Bytes never flow through your API route — Lambda has a 6 MB payload limit, and the pre-signed URL bypasses it. The platform derives the S3 key and scopes it to the workspace; you just store the key it returns.
+
+Use app-storage for files that belong to YOUR app. For files the user expects to see in the portal Files tab, use the Files module (`createFile`) instead.
+
+## Server helpers — `@assembly-js/app-foundation/server`
+
+**Both helpers ship in `@assembly-js/app-foundation/server`, an installed dependency** — import them; do NOT recreate or rewrite them:
+
+- `getUploadUrl(fileName)` → `{ key, uploadUrl }` — POSTs `{ fileName }` to the platform.
+- `getDownloadUrl(key)` → `{ downloadUrl }` — mints a fresh pre-signed GET.
+
+Store the `key` it returns; never construct an S3 key yourself, and never parse the original file name back out of the key — the platform normalizes the name when forming the key, so the stored `key` is not guaranteed to contain your exact `fileName`. Keep the display name as your own metadata (see "Storing and downloading"). `fileName` must be a bare file name (`invoice.pdf`), never a path — the platform rejects any fileName containing `/` or `..`. Don't prefix folders or namespaces onto it; the platform already scopes the key to the workspace and makes it unique. If you need grouping, store that in your own database alongside the key.
+
+The helpers call `getAssembly()` internally, which reads the bearer from the request cookie server-side — they take no token. `assembly.fetch()` prepends the base URL and injects auth headers — you only pass the path and body. Wrap these in a server API route (e.g. `app/api/app-storage/upload-url/route.ts`); never call `getAssembly` from a client component.
+
+## Client uploader — PUT directly to S3
+
+The pre-signed URL does not lock the `Content-Type`, so any value works — set it to the file's real MIME type so S3 stores it and downloads serve the file correctly. Send no auth headers on the PUT — the pre-signed URL already carries the credentials.
+
+```typescript
+'use client';
+import { authFetch } from './lib-client';
+
+export async function uploadFile(file: File) {
+  const res = await authFetch('/api/app-storage/upload-url', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ fileName: file.name }),
+  });
+  if (!res.ok) throw new Error('Failed to get upload URL');
+  const { key, uploadUrl } = await res.json();
+
+  const contentType = file.type || 'application/octet-stream';
+  const upload = await fetch(uploadUrl, { method: 'PUT', headers: { 'Content-Type': contentType }, body: file });
+  if (!upload.ok) throw new Error('S3 upload failed');
+
+  return { key, fileName: file.name, size: file.size, contentType };
+}
+```
+
+## Upload route handler
+
+Expose `getUploadUrl` behind an API route so the client never touches `assembly.fetch()` directly.
+
+**Route handler** (`app/api/app-storage/upload-url/route.ts`):
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { handleRouteError, getUploadUrl } from '@assembly-js/app-foundation/server';
+
+export async function POST(request: NextRequest) {
+  try {
+    const { fileName } = await request.json();
+    const { key, uploadUrl } = await getUploadUrl(fileName);
+    return NextResponse.json({ key, uploadUrl });
+  } catch (err) {
+    return handleRouteError(err, 'Upload URL request failed');
+  }
+}
+```
+
+## Storing and downloading
+
+Save the returned `key` (plus any metadata like `fileName`/`size`) in your app's own database. Pre-signed download URLs expire within hours, so generate them on demand — never embed one in rendered HTML or a cached server component.
+
+Create a route that returns the pre-signed URL as JSON, then trigger the download from a client component via `authFetch` + a programmatic anchor click. `authFetch` adds the CSRF header and the bearer rides the cookie, so the download route stays authenticated without any token in the URL.
+
+**Route handler** (`app/api/app-storage/download/route.ts`):
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { handleRouteError, getDownloadUrl } from '@assembly-js/app-foundation/server';
+
+export async function GET(request: NextRequest) {
+  try {
+    const key = request.nextUrl.searchParams.get('key') ?? '';
+    const { downloadUrl } = await getDownloadUrl(key);
+    return NextResponse.json({ downloadUrl });
+  } catch (err) {
+    return handleRouteError(err, 'Download URL request failed');
+  }
+}
+```
+
+**Client-side download trigger:**
+
+```typescript
+async function downloadFile(key: string) {
+  const res = await authFetch(`/api/app-storage/download?key=${encodeURIComponent(key)}`);
+  if (!res.ok) throw new Error('Failed to get download URL');
+  const { downloadUrl } = await res.json();
+  // Programmatic anchor click instead of window.open — Safari's popup
+  // blocker kills window.open after an async await.
+  const a = document.createElement('a');
+  a.href = downloadUrl;
+  a.target = '_blank';
+  a.rel = 'noopener';
+  a.click();
+}
+```
+
+Do NOT use `<a href>` links to the download route — plain links can't send the CSRF header `authFetch` adds, so the route rejects them with 403. Always use a button with an `onClick` that calls `authFetch`.
+
+## Server needs the bytes (parse / process an uploaded file)
+
+When the server must read the file too — extract PDF text, parse a CSV, generate a thumbnail — the
+upload still goes **client → S3 directly**; the server reads the bytes back **from S3**, never from the
+request body. Sending the file as multipart to your route "since the server needs it anyway" routes it
+through Lambda's 6 MB body cap, so a real multi-page PDF / large CSV 500s the whole route.
+
+Correct shape — the client uploads to S3 first, then hands your route only the `key`; the route fetches
+the bytes from a fresh download URL and processes them:
+
+```typescript
+// 1. client: uploadFile(file) → { key }   (the §Client uploader flow above — direct PUT to S3)
+// 2. client: POST { key } to your processing route (JSON, not multipart — no large body)
+
+// 3. app/api/<thing>/process/route.ts — read the bytes back from S3, then parse
+import { NextRequest, NextResponse } from 'next/server';
+import { handleRouteError, getDownloadUrl } from '@assembly-js/app-foundation/server';
+
+export async function POST(request: NextRequest) {
+  try {
+    const { key } = await request.json();
+    const { downloadUrl } = await getDownloadUrl(key);
+    const res = await fetch(downloadUrl);
+    // A non-200 S3 GET still resolves arrayBuffer() — with the XML error body, not
+    // the file — so check res.ok or you feed garbage to the parser.
+    if (!res.ok) throw new Error('S3 fetch failed: ' + res.status);
+    const buffer = Buffer.from(await res.arrayBuffer());
+    // ...process the buffer here; the file is already stored, no second upload.
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    return handleRouteError(err, 'Processing failed');
+  }
+}
+```
+
+The bytes still cross the network into your function (the cap is on the inbound *request body*, not on
+`fetch`), but they arrive via S3 GET, which has no Lambda payload limit. You also get the stored `key` for
+free — no second upload.
+
+## What NOT to do
+
+- Do NOT add `Authorization`/`X-API-Key` to the S3 PUT — extra headers cause `SignatureDoesNotMatch`.
+- Do NOT embed a pre-signed download URL in rendered HTML — it expires; mint a fresh one per click.
+- Do NOT construct the S3 key yourself — store the key the platform returns.
+- Do NOT put `/` in `fileName` (e.g. `uploads/${file.name}`) — the API rejects it; send the bare file name.
+- Do NOT use app-storage for files the user wants in the portal Files tab — use `createFile`.
+- Do NOT pass any auth token as a URL query parameter for downloads — use `authFetch`, which adds the CSRF header while the bearer rides the cookie.

package/skills/assembly-user-company-selector/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: assembly-user-company-selector
+description: Use when the app needs to select clients, internal users, or companies — in forms, filters, search bars, or any other selection context. This is a custom Assembly component with its own prop-based API (NOT a shadcn drop-in).
+---
+
+## Install
+
+```bash
+export PATH="$HOME/.bun/bin:$PATH" && bunx shadcn@latest add @assembly-ui/user-company-selector --yes --overwrite
+```
+
+## Usage
+
+```tsx
+import { UserCompanySelector } from "@/components/ui/user-company-selector";
+import type { Entity, EntityValue } from "@/components/ui/user-company-selector";
+```
+
+This is a **custom Assembly component** — it does NOT follow shadcn composition patterns. It is a single composed component with a prop-based API.
+
+## Map SDK resources to Entity objects
+
+Pass `companyIds` on client entities — the component automatically expands multi-company clients into separate selectable entries and shows a company avatar badge for each.
+
+```tsx
+const clientEntities: Entity[] = clients.map(c => ({
+  id: c.id,
+  label: `${c.givenName} ${c.familyName}`,
+  type: "client" as const,
+  avatarUrl: c.avatarImageUrl,
+  avatarFallbackColor: c.fallbackColor,
+  companyIds: c.companyIds ?? (c.companyId ? [c.companyId] : []),
+}));
+
+const companyEntities: Entity[] = companies.map(c => ({
+  id: c.id,
+  label: c.name,
+  type: "company" as const,
+  avatarUrl: c.iconImageUrl,
+  avatarFallbackColor: c.fallbackColor,
+}));
+
+const internalUserEntities: Entity[] = internalUsers.map(u => ({
+  id: u.id,
+  label: `${u.givenName} ${u.familyName}`,
+  type: "internalUser" as const,
+  avatarUrl: u.avatarImageUrl,
+  avatarFallbackColor: u.fallbackColor,
+}));
+```
+
+**Every company referenced by a client's `companyIds` must have a matching entry in the `companies` prop.** The component uses `companyIds` to expand a client into one selectable entry per company and renders the company's avatar badge next to each entry. If the company object is missing from `companies`, the badge cannot render and the user sees duplicate, indistinguishable client rows. Whenever clients have `companyIds`, fetch the companies with `listCompanies({ isPlaceholder: false })` (see `assembly-companies` skill) and map them to `Entity` objects as shown above — do not pass `companies={[]}` unless no client has any `companyIds`.
+
+Always include `avatarFallbackColor` from the SDK's `fallbackColor` field — without it, avatar fallbacks render as plain gray instead of the user's assigned color.
+
+`onValueChange` returns `EntityValue[]` — each value has `{ id, companyId, type, label }`. Use `companyId` (singular) for data-storage keys and scope decisions, not `companyIds`. The `label` is the display name of the selected entity. See the `assembly-clients-companies` skill for scoping patterns.
+
+## Render
+
+Always use controlled mode — pass both `value` and `onValueChange`:
+
+```tsx
+<UserCompanySelector
+  clients={clientEntities}
+  companies={companyEntities}
+  internalUsers={internalUserEntities}
+  value={selected}
+  onValueChange={(values: EntityValue[]) => {
+    // values is an array of { id, companyId, type }
+    setSelected(values);
+  }}
+  placeholder="Search users or companies…"
+/>
+```
+
+## Key props
+
+- `multiple` — enable multi-select mode (default `false`). When `false`, renders a single-select input with a clear button. When `true`, renders chips for each selection.
+- `filterClientsByCompany` — restrict to same-company clients when true (multi-select only)
+- `hideCompanies` — hide company options
+- `grouped` — group options by type
+- `disabled`, `aria-invalid`
+
+## Layout warning
+
+When `multiple` is enabled, `UserCompanySelector` renders selected values as chips. Chips can be clipped if the container is too narrow, and the input expands downward as more chips are added. Ensure enough width for chips to display without clipping and enough vertical space for the input to grow.
+
+## When to use this component
+
+Use `UserCompanySelector` any time the UI involves an Assembly person or organization record — including:
+- Form fields (e.g. "assign to", "select client")
+- Table/list filters and search bars (e.g. filtering a client table by name)
+- "Assign to" or "select team member" dropdowns
+- Any other selection or filtering context
+
+**Common mistake:** When building a table that lists people (clients, users, companies), developers often add a plain text `Input` to filter the table. This is wrong — use `UserCompanySelector` for the filter instead. It provides avatar-aware, searchable filtering out of the box.
+
+Do NOT use `Select`, `Combobox`, or a plain text `Input` for picking or filtering Assembly users or companies. `UserCompanySelector` handles avatars, multi-company clients, and search relevance automatically.

package/skills/assembly-workspace-labels/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: assembly-workspace-labels
+description: Use when the app displays "Client" or "Company" text in the UI. Workspaces can customize these labels (e.g. "Contact", "Organization"). This skill shows how to use the pre-built label helpers instead of hardcoding.
+---
+
+Workspaces can rename "Client" and "Company" to custom labels like "Contact", "Person", "Family", "Organization", or fully custom terms. **Never hardcode** "Client", "Company", "Clients", or "Companies" in user-facing UI text. Use the pre-built label helpers instead.
+
+## SDK values vs display labels
+
+The SDK entity type is always `'client'` or `'company'` — these never change regardless of the workspace's display labels. Use the SDK values in code (scope checks, entityType params, variable names). Use the display labels only in UI-facing text.
+
+## Pre-built helpers
+
+The foundation ships two helpers, one per rendering side. **Import them — do not recreate them.**
+
+### Server components: `getLabels()` from `@assembly-js/app-foundation/server`
+
+```ts
+import { getLabels } from '@assembly-js/app-foundation/server';
+
+export default async function MyPage() {
+  const { clientOne, clientMany, companyOne, companyMany } = await getLabels();
+  return <h2>{clientMany} List</h2>;
+}
+```
+
+`getLabels()` reads request headers set by the proxy middleware (zero API calls). It returns a `WorkspaceLabels` object with `clientOne`, `clientMany`, `companyOne`, `companyMany`, defaulting to "Client"/"Clients"/"Company"/"Companies".
+
+### Client components: `useLabels()` from `@/app/components/labels-context`
+
+The root layout already wraps children in `<LabelsProvider>`. In any client component:
+
+```tsx
+'use client';
+import { useLabels } from '@/app/components/labels-context';
+
+export function ClientHeading() {
+  const { clientOne, clientMany } = useLabels();
+  return <h2>{clientMany} List</h2>;
+}
+```
+
+## Rules
+
+1. **Never hardcode** "Client", "Company", "Clients", or "Companies" in user-facing strings.
+2. **Server components** — call `getLabels()` from `@assembly-js/app-foundation/server`.
+3. **Client components** — call `useLabels()` from `@/app/components/labels-context`.
+4. **SDK values in code**: `entityType: 'client'`, `record.scope === 'client'`, variable names like `clientId` — these use the raw SDK values, not the display labels.
+5. **Display labels in UI**: headings, table headers, button text, empty states, tooltips, filter options — these use the label helpers.
+6. **Do NOT call `retrieveWorkspace()` for labels** — the proxy already resolves them. The helpers read from request headers with zero extra API calls.

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

@@ -0,0 +1,100 @@
+---
+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.
+---
+
+## 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.
+
+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.
+
+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:
+
+- **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.
+
+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.
+
+## Scoping the clear
+
+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.
+
+`listNotifications` returns unread-only by default — you do not need to pass a flag to get the unread set.
+
+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.
+
+`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.
+
+## Pattern A — clear on view
+
+```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 }>;
+}) {
+  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');
+
+  return <SubmissionDetail id={submissionId} />;
+}
+```
+
+## Pattern B — clear on action
+
+```ts
+// app/(client)/tasks/[id]/complete.ts
+'use server';
+
+import { getAssembly, getSessionIdentity } from '@assembly-js/app-foundation/server';
+import { sendThrottled, logFailures } from '@/lib/notify';
+
+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' } });
+
+  const { data: notifications = [] } = await assembly.listNotifications({
+    recipientClientId: id?.clientId,
+  });
+  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');
+}
+```
+
+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.
+
+## Checklist before you call a client-facing app done
+
+- For every `createNotification({ recipientClientId })`, there is a matching `markNotificationRead` 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.