@assembly-js/app-foundation 0.0.36 → 0.0.37

package/CLAUDE.md

@@ -714,9 +714,25 @@ For an imperative one-off (button handler, mutation), use `callAction` from `use
 - **Actions take no token.** Never accept, read, or pass a token — `getAssembly()` resolves the bearer itself. Never touch `AssemblyBridge.sessionToken.*` in a component or copy anything into your own `useState`/`useRef`.
 - **Data actions must let `TokenInvalidError` propagate** — never `try/catch` it into `null`/empty. The auto-retry only fires if the action surfaces the expiry. And never hand-roll refresh/retry; `useServerAction`/`callAction` already do it.
 
+#### Server action or route handler?
+
+A client-to-server call is a server action by default. Its argument is a TypeScript parameter, so a payload that does not match the signature fails `tsc` in your inner loop. A route handler's body is an untyped wire contract — `JSON.stringify` on one side, `request.json()` on the other — and nothing checks that the two agree until a user sends the first request, which you cannot do from the sandbox. A mismatch `tsc` would catch in an action ships silently through a route and 400s for every user.
+
+Write a route handler only when the caller needs a raw `Response` — streamed bytes, a file download, a webhook or cron entry point — or when the caller is not this app's own client component. When you do, define the body schema in a shared `lib/` module with no server-only imports, and type the client's payload with `z.input<typeof schema>` so the compiler checks the wire shape:
+
+```ts
+// lib/reply-contract.ts — imported by both the route and the component (`bun add zod` if it is not installed yet)
+import { z } from 'zod';
+export const replyBody = z.object({ parentId: z.string().uuid().nullish(), text: z.string().min(1) });
+export type ReplyBody = z.input<typeof replyBody>;
+
+// app/api/replies/route.ts: const parsed = replyBody.safeParse(await request.json());
+// component:               const body: ReplyBody = { parentId, text }; // tsc rejects what the route would 400
+```
+
 #### Client → server via route handlers — `authFetch`
 
-For mutations and route-handler calls from client components, use `authFetch` from `app/components/lib-client.ts`. The bearer rides the cookie automatically; `authFetch` adds the required CSRF header and re-exchanges + retries once on a bearer expiry:
+For the route-handler calls that remain, use `authFetch` from `app/components/lib-client.ts`. The bearer rides the cookie automatically; `authFetch` adds the required CSRF header and re-exchanges + retries once on a bearer expiry:
 
 ```tsx
 'use client';

package/dist/replace-rows.js

@@ -33,7 +33,8 @@ async function runStatements(db, statements) {
         return;
     }
     const batch = db.batch;
-    await batch([first, ...rest]);
+    // drizzle's batch reads this.session, so it must be invoked on db, never as a bare function.
+    await batch.call(db, [first, ...rest]);
 }
 export async function replaceChildRows(db, spec) {
     // Ids exist before the delete is built, so a row added in this save is on the keep-list.

package/package.json

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

package/skills/assembly-ai/SKILL.md

@@ -37,25 +37,26 @@ export async function chatCompletion(messages: Array<{ role: string; content: st
 
 ## Server-side only
 
-ALL AI calls MUST happen server-side (API routes, server components, server actions). Never call the AI proxy from client components.
+ALL AI calls MUST happen server-side (server actions, server components, route handlers). Never call the AI proxy from client components.
 
-Example Next.js API route:
+Expose an AI call to the client as a server action — its arguments are type-checked end to end, so a payload mismatch fails `tsc` instead of the user's first request. Reserve a route handler for the streaming case below, where the client needs the raw `Response`.
 
 ```typescript
-// app/api/ai/summarize/route.ts
-import { NextRequest, NextResponse } from 'next/server';
+// app/actions/summarize.ts
+'use server';
 import { chatCompletion } from '@/lib/ai';
 
-export async function POST(request: NextRequest) {
-  const { text } = await request.json();
+export async function summarize(text: string): Promise<string> {
   const response = await chatCompletion([
     { role: 'user', content: `Summarize the following:\n\n${text}` },
   ]);
   const data = await response.json();
-  return NextResponse.json({ summary: data.choices[0].message.content });
+  return data.choices[0].message.content;
 }
 ```
 
+From a client component: `const summary = await callAction(() => summarize(text), { idempotent: true });` — the call writes nothing, so it is safe to re-run after a bearer renewal.
+
 ## Vision (image inputs)
 
 The proxy supports OpenAI's vision API. Use `gpt-4o` with the multi-part content format to analyze images. The `content` field becomes an array of typed parts instead of a plain string: