@assembly-js/app-foundation 0.6.6 → 0.7.1

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.1
+- [fix] The location reporter no longer sends the host's embed-session params (`token`, `clientId`, `companyId`) with the app's location, so they never reach the host URL or a copied deep link.
+
+## 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.
 

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/dist/location-prefix.d.ts

@@ -1,3 +1,9 @@
+export declare const HOST_SESSION_PARAMS: string[];
+/**
+ * The app's own query string with the host's embed-session params removed,
+ * as a `?`-prefixed string, or '' when nothing is left.
+ */
+export declare function stripHostSessionParams(searchParams: URLSearchParams): string;
 export declare function getSurfacePrefixes(): string[];
 export declare const SURFACE_PREFIXES: string[];
 /**

package/dist/location-prefix.js

@@ -1,4 +1,19 @@
 const DEFAULT_PREFIXES = ['/c', '/n'];
+// The host puts these on the iframe src to open the embed session. They are
+// not part of the app's location, and reporting them would put the token in
+// the host URL, browser history and every copied deep link.
+export const HOST_SESSION_PARAMS = ['token', 'clientId', 'companyId'];
+/**
+ * The app's own query string with the host's embed-session params removed,
+ * as a `?`-prefixed string, or '' when nothing is left.
+ */
+export function stripHostSessionParams(searchParams) {
+    const own = new URLSearchParams(searchParams);
+    for (const key of HOST_SESSION_PARAMS)
+        own.delete(key);
+    const qs = own.toString();
+    return qs ? `?${qs}` : '';
+}
 // Read surface prefixes from the build-time env value injected by withAssemblyDev.
 // Falls back to the historical /c and /n defaults so apps on an older image
 // continue to work without a rebuild.

package/dist/location-reporter.js

@@ -2,7 +2,7 @@
 import { Suspense, createElement, useEffect, useRef } from 'react';
 import { usePathname, useSearchParams, useRouter } from 'next/navigation';
 import { AssemblyBridge } from '@assembly-js/app-bridge';
-import { getSurfacePrefix, stripPrefix, addPrefix } from './location-prefix.js';
+import { getSurfacePrefix, stripPrefix, addPrefix, stripHostSessionParams } from './location-prefix.js';
 function LocationReporterInner() {
     const pathname = usePathname();
     const searchParams = useSearchParams();
@@ -19,8 +19,7 @@ function LocationReporterInner() {
         if (!bridgeLocation)
             return;
         const path = stripPrefix(pathname, prefix);
-        const qs = searchParams.toString();
-        bridgeLocation.report(path, qs ? `?${qs}` : '');
+        bridgeLocation.report(path, stripHostSessionParams(searchParams));
     }, [bridgeLocation, pathname, searchParams, prefix]);
     // Register the navigate handler once; rely on prefixRef for the current prefix.
     useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.6.6",
+  "version": "0.7.1",
   "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.