@assembly-js/app-foundation 0.6.5 → 0.7.0

package/CHANGELOG.md

@@ -19,6 +19,13 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.7.0
+- [new] `deleteFile(key)` in `@assembly-js/app-foundation/server` permanently deletes a file stored with app-storage.
+- [guidance] The assembly-storage skill documents `deleteFile`: deletion is permanent, so apps that want recovery hide the record first and delete the file later.
+
+## 0.6.6
+- [guidance] The build agent ends a chat turn by describing what changed instead of reporting its type-check, build, or the screens it didn't open, and knows the platform builds the app after every turn. It still claims "fixed" or "working" only for what it exercised, and talks about verification when asked or when fixing a reported bug.
+
 ## 0.6.5
 - [guidance] The `assembly-storage` skill says the `assembly` option of `detectPdfFields` is only an opt-in flag. The `assembly-ai` skill and the `assembly.fetch()` prose now call the AI proxy on the installer client (`getInstallerAssembly()`, gated by `await getAssembly()` first) instead of the viewer's client.
 - [behavior] `detectPdfFields` now runs its AI step on the installer client, and degrades to a warning when there is no verified viewer. `options.assembly` is deprecated and ignored; passing it still opts in to the AI step.

package/CLAUDE.md

@@ -684,17 +684,17 @@ export PATH="$HOME/.bun/bin:$PATH" && bun add <extra-package>
 
 ### Inner verification loop — type-check, don't full-build
 
-Use `bunx tsc --noEmit` to verify your changes while iterating. It runs in 2–3s and gives you the full, untruncated type errors. Reserve `bun run build` (~15–20s for a full Next build) for the **final** check at the end of the task, not after every edit. Running `bun run build` between trivial edits adds ~15s of dead time per cycle.
+Use `bunx tsc --noEmit` to check changes while iterating (2–3s, full type errors). After every chat turn that changes app code, the platform runs the type-check and a full build and sends failures back for you to fix, so skip `bun run build` unless the task asks for a build or you changed `lib/schema.ts` and need the new tables now.
 
 ```bash
 # Inner loop — after edits, every few changes:
 export PATH="$HOME/.bun/bin:$PATH" && bunx tsc --noEmit
 
-# Final check — once, at the end of the task:
+# Full build — only when the task asks for one:
 export PATH="$HOME/.bun/bin:$PATH" && bun run build
 ```
 
-If `tsc --noEmit` is clean and the task says "verify the build", run `bun run build` once and move on — don't loop on it.
+When the task says "verify the build", run `bun run build` once.
 
 `bun run build` also validates `.assembly/app.json` (it runs the manifest validator first) and **fails** if the manifest is malformed or a key is misplaced — most commonly a surface like `notification` written at the top level instead of under `surfaces`. If the build stops with a `.assembly/app.json is invalid` error, fix the manifest as the message instructs — every surface belongs under the `surfaces` key. Run `bun run validate:manifest` to check it on its own.
 
@@ -713,9 +713,9 @@ If `tsc --noEmit` is clean and the task says "verify the build", run `bun run bu
 
 `tsc --noEmit` and `bun run build` prove the code compiles and the static checks pass. Neither renders a page, so both stay green while a page 500s for every visitor — a function passed into a client component, a browser-only import in server code, a field the sample record happened to have. A query against the sandbox database or an SDK call shows the data is there, not that the page reading it renders.
 
-You cannot open the app as a signed-in client or team member, and you cannot see the published app or its logs. The builder preview is the user's own signed-in session, so the one runtime signal you have is the dev-server log (`assembly-dev-server-logs`): after changing a page or route, read it for new errors before calling the change done, and when nothing has requested the changed screen yet, ask the user to open it in the preview.
+You cannot open the app as a signed-in client or team member, and you cannot see the published app or its logs. The builder preview is the user's own signed-in session, so the one runtime signal you have is the dev-server log (`assembly-dev-server-logs`): after changing a page or route, read it and fix any new errors before calling the change done. Mention it only if something is wrong.
 
-Close every turn, and answer every "does it work" or "is it safe to publish", by naming the checks that ran in those terms and the screens you could not open — which page, as which kind of user — so the user opens them. Say this unprompted, every time, not only when the prompt asks for a manual check. Say "fixed", "working", or "good to publish" only for behaviour you exercised; otherwise say what you checked and what is still unseen.
+Close a turn by describing what changed, in product terms — no tool or command names, no list of what you did not open or run. A limitation the user will hit is worth one line ("test cases still reset on reload; I can move them into the database"). Speak about verification only when the user asks whether something works or is safe to publish, or the turn fixes a bug they reported; then say in product terms what you exercised, or whether you reproduced the bug and saw it gone. Say "fixed", "working", or "good to publish" only for behaviour you exercised.
 
 When the user reports that the published app errors, do not blame a cold start, caching, or a stale tab without evidence. Ask for the page, who was signed in, and the exact error text or code; reproduce it in the sandbox — the same screen in the preview or the same request against the dev server — and read the dev-server log. If you cannot reproduce it, say so and ask for those details rather than asking the user to reload.
 
@@ -1510,7 +1510,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ 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 preview a PDF (or any file) in an `<iframe>`, `<embed>` or `<object>` — the portal frame is sandboxed and Chrome won't run its PDF viewer inside it, so the preview renders blank while the build passes. Open the pre-signed URL in a new tab (`assembly-storage` Pattern A) or render pages to a canvas client-side with `next/dynamic` + `ssr: false`.
 - ❌ Don't build a PDF-to-form feature on AcroForm fields alone. Call `detectPdfFields` and branch on `method`: `none` and `xfa` need a visible explanation plus a manual add-field path, and `text` fields are suggestions the user must be able to edit before saving. Plenty of real forms are Word exports, scans or XFA, so an AcroForm-only app tells those users their form is empty.
-- ❌ Don't call a change verified, working, or safe to publish because `tsc --noEmit` and `bun run build` passed — name the checks that ran and the signed-in screens left unopened. See "What a passing build proves" above.
+- ❌ Don't call a change verified, working, or safe to publish because `tsc --noEmit` and `bun run build` passed, and don't close a turn with a report of your checks. See "What a passing build proves" above.
 - ❌ Don't pass a function — or an object that holds one, like a question/field config with `visibleWhen`, `validate`, `render`, or `format` callbacks — as a prop from a server component or page into a `'use client'` component. Props cross that boundary as serialized data, so the render throws `Functions cannot be passed directly to Client Components` and the page 500s for every visitor no matter what the record holds. `tsc --noEmit` and `bun run build` both pass. Keep such a config in a shared module the client component imports itself, or express the logic as data (`{ showWhen: { field: 'entityType', equals: 'llc' } }`) and interpret it client-side.
 - ❌ Don't call a function imported from a `'use client'` file from a server component, layout, or server action — e.g. an answer formatter defined in the client component file that the `/n` notification page also renders. The server gets a client reference, not the function, so the render throws and the route 500s for every visitor; `tsc --noEmit` passes. A `'use client'` file should export only components and hooks; put a shared helper in a plain module (`lib/…`) both sides import. `bun run build` fails on this (`check:client-boundary`).
 - ❌ 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.

package/bin/foundation-exports.mjs

@@ -44,7 +44,7 @@ export const NON_CLIENT_EXPORTS = new Set([
   'createAssemblyReexchangeHandler', 'cronRoute',
   'decodeBearer', 'detectPdfFields', 'expandClientsByCompany', 'extractPdfText', 'fetchSessionFlags',
   'findResource', 'formatAirtableRecords', 'generateAppClient', 'getAirtableTableSchema', 'getCapturedRecords',
-  'getClientAccessScope', 'getCookielessBearer', 'getDownloadUrl', 'getInstalledAppIds', 'getIntegration',
+  'getClientAccessScope', 'getCookielessBearer', 'getDownloadUrl', 'deleteFile', 'getInstalledAppIds', 'getIntegration',
   'getInternalUserAccess', 'getLabels', 'getSessionIdentity', 'getUploadUrl',
   'getVerifiedIdentity', 'gmailSendEmail', 'handlePaintedBeacon', 'handleRouteError',
   'hasClientFlag', 'hasFlag', 'installFetchCapture', 'installNetworkCapture',

package/dist/app-storage.d.ts

@@ -5,3 +5,4 @@ export declare function getUploadUrl(fileName: string): Promise<{
 export declare function getDownloadUrl(key: string): Promise<{
     downloadUrl: string;
 }>;
+export declare function deleteFile(key: string): Promise<void>;

package/dist/app-storage.js

@@ -40,3 +40,15 @@ export async function getDownloadUrl(key) {
         throw new Error('Download URL request failed: ' + res.status);
     return res.json();
 }
+// NOTE: takes ONE argument. Deletion is permanent — the platform keeps no copy
+// to restore, so apps that want recovery must hide the record first.
+export async function deleteFile(key) {
+    if (JWT_SHAPE.test(key)) {
+        throw new Error('deleteFile: first argument looks like a session token. ' +
+            'The token argument was removed — call deleteFile(key) with the storage key only.');
+    }
+    const assembly = await getInstallerAssemblyForCaller();
+    const res = await assembly.fetch('/v1/app-storage/object?key=' + encodeURIComponent(key), { method: 'DELETE' });
+    if (!res.ok)
+        throw new Error('Delete request failed: ' + res.status);
+}

package/package.json

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

package/skills/assembly-storage/SKILL.md

@@ -11,10 +11,11 @@ Use app-storage for files that belong to YOUR app. For files the user expects to
 
 ## 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:
+**All three 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. Takes **one argument** (the file name only). If you were calling it as `getUploadUrl(token, fileName)` (an old two-arg shape), remove the token — auth is in the bearer cookie and the function will throw if a token is passed as the file name.
 - `getDownloadUrl(key)` → `{ downloadUrl }` — mints a fresh pre-signed GET. Takes **one argument** (the storage key only). Same note: remove any leading token argument.
+- `deleteFile(key)` → `void` — permanently deletes the stored object. Takes **one argument** (the storage key only); the function throws if a token is passed as the key. Deletion is irreversible, so keep the keys in your own database to know what to delete.
 
 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.
 
@@ -123,6 +124,30 @@ await downloadViaBlob(`/api/items/${id}/download`, 'report.pdf');
 
 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` or `downloadViaBlob`.
 
+## Deleting a file
+
+`deleteFile(key)` removes the object from storage. Deletion is **permanent and irreversible** — there is no trash, no undo, and no version to restore. If your app needs recovery (an "undo", a trash view, soft-delete), hide the record in your own database first and call `deleteFile` only later, once the user can no longer bring it back.
+
+**Route handler** (`app/api/app-storage/delete/route.ts`):
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { handleRouteError, deleteFile } from '@assembly-js/app-foundation/server';
+
+export async function DELETE(request: NextRequest) {
+  try {
+    const id = request.nextUrl.searchParams.get('id') ?? '';
+    const key = await getStoredFileKey(id); // your own database lookup by record id
+    await deleteFile(key);
+    return new NextResponse(null, { status: 204 });
+  } catch (err) {
+    return handleRouteError(err, 'Delete request failed');
+  }
+}
+```
+
+Only delete keys you stored yourself (look the key up from your own database by record id rather than trusting a key sent by the client), and remove or hide your own record at the same time.
+
 ## 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
@@ -189,5 +214,6 @@ switch (detection.method) {
 - 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 call `deleteFile` expecting to recover the file later — deletion is permanent; hide the record first and delete the file after the recovery window.
 - 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.