@assembly-js/app-foundation 0.0.25-rc.4 → 0.0.25-rc.6

package/CLAUDE.md

@@ -56,6 +56,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-route-auth` — REQUIRED on every `app/api/.../[id]/route.ts` handler: `requireAuth` + `requireCompanyScope` before returning or mutating data.
 - `assembly-scheduled-work` — REQUIRED when the prompt implies anything on a schedule or while nobody has the app open (remind, daily digest, every week, follow up in N days, at a specific time): one `*/30 * * * *` Vercel cron in `vercel.json` hitting one dispatcher route, every scheduled action a row in a schedule table, `CRON_SECRET` declared in `requiredSecrets` and verified on every tick, `getOfflineAssembly()` for platform calls. Checking for due work on page load ships a schedule that never fires.
 - `assembly-route-errors` — REQUIRED in every route handler: use `handleRouteError` from `@assembly-js/app-foundation/server` in catch blocks — never return `err.message`. Validate values before they hit typed DB columns (e.g. `parseUuid` before a uuid-column lookup).
+- `assembly-action-results` — REQUIRED when a server action refuses work the UI should explain (validation, permission, not ready to send): return `{ ok: false, message }` instead of throwing. A thrown message is redacted in production.
 - `assembly-dev-server-logs` — the dev server's stdout/stderr (server-side errors, stack traces, console output) is readable at `/tmp/dev-server.log`; check it before guessing at a 500 or broken preview.
 
 ---
@@ -1147,6 +1148,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 `throw new Error` with a sentence the user should read from a server action. Production redacts that throw, so the toast shows a generic React error and the response is HTTP 500. Return `{ ok: false, message }` and toast `message`. Let `TokenInvalidError` and unexpected failures throw. See `assembly-action-results`.
 - ❌ 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.

package/package.json

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

package/skills/assembly-action-results/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: assembly-action-results
+description: REQUIRED when a server action refuses work for a reason the UI should show — validation, permission, or not ready (a draft that cannot be sent yet). Return { ok: false, message } instead of throwing. A thrown Error is redacted in production to a generic React error, so the toast shows that instead of your sentence. Let TokenInvalidError and unexpected failures still throw.
+---
+
+Production Next.js redacts a thrown server-action error before it reaches the client. The name, code, and message become "An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details." (React error #441), and the response is HTTP 500. The sentence you threw stays in the server log. A toast that reads `err.message` shows the redacted string.
+
+Return the refusal as data. Throw only for failures the user should not read, and for `TokenInvalidError` — `callAction` renews the bearer only when the action throws.
+
+## The rule
+
+```ts
+'use server';
+
+export type SendProposalResult =
+  | { ok: true; detail: ProposalDetail }
+  | { ok: false; message: string };
+
+export async function sendProposal(id: string): Promise<SendProposalResult> {
+  const viewer = await getViewerContext(); // TokenInvalidError must throw
+  if (!viewer || viewer.kind !== 'internal') {
+    return { ok: false, message: 'Only staff can send proposals' };
+  }
+  if (!hasContentBlock) {
+    return { ok: false, message: 'Add at least one content block before sending' };
+  }
+  return { ok: true, detail };
+}
+```
+
+```tsx
+const result = await callAction(() => sendProposal(id));
+if (!result.ok) {
+  AssemblyBridge.toast.show({
+    title: 'Could not send proposal',
+    description: result.message,
+    variant: 'error',
+  });
+  return;
+}
+```
+
+Leave off `{ idempotent: true }` for a write. `callAction` re-runs an idempotent call after any throw, including one that happens after the write already landed. Pass it only when a second call is a no-op, such as a conditional `draft` to `sent` update.
+
+Name the control the user can act on. "Add at least one section" does not help when the editor's heading is "Content blocks".
+
+## What still throws
+
+- Bearer expiry (`TokenInvalidError` from `getAssembly()`). Returning it as `{ ok: false }` stops the silent re-exchange.
+- Unexpected failures (the database driver, an SDK 500). Leave those thrown. Do not copy `err.message` into the returned `message` — that string can be a driver error.
+
+Route handlers return JSON and a status. Use `assembly-route-errors` there, not this result shape.

package/skills/assembly-scheduled-work/SKILL.md

@@ -117,6 +117,9 @@ export const GET = cronRoute(async () => {
       ran++;
     } catch (err) {
       // One failing row must not poison the batch; leave it for the next tick.
+      // The error log is how the platform learns an action failed inside a
+      // tick that still returns 200 — keep it.
+      console.error('scheduled action failed', claimed.action, err);
       await db
         .update(scheduledActions)
         .set({ status: 'pending', claimedAt: null, lastError: err instanceof Error ? err.message : String(err) })