@assembly-js/app-foundation 0.0.30 → 0.0.32

package/CLAUDE.md

@@ -43,7 +43,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-app-surfaces` — REQUIRED before writing `.assembly/app.json`: declare which surfaces (dashboard, client portal, notification) the app exposes; omitting the client surface keeps the app off client portal nav entirely
 - `assembly-app-bridge-header` — breadcrumbs (don't include app name), CTAs
 - `assembly-app-bridge-toast` — show toast notifications in the parent dashboard
-- `assembly-ai` — AI features via Assembly's OpenAI proxy (no API keys needed)
+- `assembly-ai` — AI features, including speech-to-text, via Assembly's OpenAI proxy (no API keys needed)
 - `assembly-storage` — app-private file uploads/downloads (NOT the portal Files module). The storage helpers come from `@assembly-js/app-foundation/server` — import them, don't rewrite them. POST only `{ fileName }` (a bare name) and store the key the platform returns; never build the S3 key yourself.
 - `assembly-integrations` (present only when third-party integrations are enabled for this workspace) — third-party providers (Slack, etc.) via `requiredIntegrations` + `getIntegration()`. If this skill is present, read it and `.claude/skills/assembly-integrations/providers/<slug>.md` before declaring an integration or writing any provider call — the skill lists what's connectable, the provider doc has that provider's gotchas — and read them first when provider data displays wrongly (wrong format, raw IDs). If it is absent, managed OAuth integrations are not available here; use `requiredSecrets` for any external service
 - `assembly-avatar-sub` — AvatarSub company badge wherever a client is rendered, including tables of your own records that reference a client; row duplication only for lists OF clients
@@ -1162,7 +1162,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 <!-- /feature:app-owned-header -->
 - ❌ Don't let two mounted components call `useAssemblyHeader` at once — e.g. a parent shell's scaffolding-era stub CTA left in place after a child took real ownership. Strict Mode hides the race in dev; the hook throws in dev and ignores the second caller in production. Delete the parent's stub the moment a child owns the slot.
 - ❌ Don't `window.open(url, '_self')` or set `window.location` for external links — use `<a target="_blank" rel="noreferrer">`.
-- ❌ Don't open one of your own route handlers by plain navigation for a download or export — `<a href="/api/…/pdf" target="_blank">`, `window.open('/api/…')`. The bearer cookie is partitioned to the portal iframe, so a new tab arrives signed out and `requireAuth` rejects it; the build passes and the link only fails in a live test. Fetch it with `authFetch`, read the response with `res.blob()`, and click a programmatic anchor on `URL.createObjectURL(blob)` with a `download` name. (`assembly-storage` shows the same flow for a route that returns a pre-signed URL as JSON rather than the bytes.)
+- ❌ Don't open one of your own route handlers by plain navigation for a download or export — `<a href="/api/…/pdf" target="_blank">`, `window.open('/api/…')`. The bearer cookie is partitioned to the portal iframe, so a new tab arrives signed out and `requireAuth` rejects it; the build passes and the link only fails in a live test. Use `downloadViaBlob(url, filename)` from `app/components/lib-client.ts` — it calls `authFetch`, reads `res.blob()`, and triggers the download via a programmatic anchor on `URL.createObjectURL(blob)`. (`assembly-storage` shows the same flow for a route that returns a pre-signed URL as JSON rather than the bytes.)
 - ❌ Don't hardcode brand colors. The portal applies the workspace theme.
 - ❌ Don't add dark mode support (`dark:` classes, `.dark` class toggling, `next-themes`, `ThemeProvider`, or `prefers-color-scheme` media queries). The assembly-ui registry is light-only and the layout forces `colorScheme: 'light'`.
 - ❌ Don't handle the session token at all — no cookie you set, no `useAssembly().token`, no `x-assembly-token` header, no `searchParams.token`. The middleware already exchanged it for a bearer cookie; call `getAssembly()` / `getAssemblyForRequest(req)` server-side and the call is authenticated.

package/dist/app-storage.js

@@ -1,9 +1,21 @@
 import { getAssembly } from './assembly.js';
+// A bearer token is a JWT: three base64url segments separated by dots, the
+// first always decoding to a JSON header (so it starts with 'eyJ'). Matching
+// the whole-string shape — not just the 'eyJ' prefix — avoids rejecting a
+// legitimate file name or storage key that happens to start with 'eyJ'.
+const JWT_SHAPE = /^eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+$/;
 // fileName must be a bare file name (e.g. 'invoice.pdf'), never a path:
 // the platform rejects any value containing '/' or '..'. Do NOT prefix
 // folders or construct the S3 key yourself — the platform scopes the key
 // to the workspace and makes it unique. Store the key it returns.
+// NOTE: takes ONE argument. If you are calling this as getUploadUrl(token, fileName)
+// (the old two-arg shape), remove the token — auth is in the bearer cookie.
 export async function getUploadUrl(fileName) {
+    // Catches the old (token, fileName) call shape where a JWT ends up as the file name.
+    if (JWT_SHAPE.test(fileName)) {
+        throw new Error('getUploadUrl: first argument looks like a session token. ' +
+            'The token argument was removed — call getUploadUrl(fileName) with the file name only.');
+    }
     const assembly = await getAssembly();
     const res = await assembly.fetch('/v1/app-storage/upload-url', {
         method: 'POST',
@@ -13,7 +25,14 @@ export async function getUploadUrl(fileName) {
         throw new Error('Upload URL request failed: ' + res.status);
     return res.json();
 }
+// NOTE: takes ONE argument. If you are calling this as getDownloadUrl(token, key)
+// (the old two-arg shape), remove the token — auth is in the bearer cookie.
 export async function getDownloadUrl(key) {
+    // Catches the old (token, key) call shape where a JWT ends up as the storage key.
+    if (JWT_SHAPE.test(key)) {
+        throw new Error('getDownloadUrl: first argument looks like a session token. ' +
+            'The token argument was removed — call getDownloadUrl(key) with the storage key only.');
+    }
     const assembly = await getAssembly();
     const res = await assembly.fetch('/v1/app-storage/download-url?key=' + encodeURIComponent(key));
     if (!res.ok)

package/dist/bridge-vnext.d.ts

@@ -0,0 +1,73 @@
+import '@assembly-js/app-bridge';
+export type NavigateDestination = {
+    to: 'home';
+} | {
+    to: 'client';
+    clientId: string;
+    tab?: string;
+} | {
+    to: 'company';
+    companyId: string;
+    tab?: string;
+} | {
+    to: 'channel';
+    channelId?: string;
+} | {
+    to: 'files';
+    channelId?: string;
+} | {
+    to: 'contract';
+    contractId: string;
+} | {
+    to: 'form';
+    formId: string;
+} | {
+    to: 'formResponse';
+    formId: string;
+    responseId: string;
+} | {
+    to: 'invoice';
+    invoiceId: string;
+} | {
+    to: 'subscription';
+    subscriptionId: string;
+} | {
+    to: 'product';
+} | {
+    to: 'helpdesk';
+} | {
+    to: 'article';
+    articleId: string;
+} | {
+    to: 'notifications';
+} | {
+    to: 'automations';
+} | {
+    to: 'settings';
+    page?: string;
+} | {
+    to: 'app';
+    installId: string;
+};
+export type NavigateToOptions = {
+    replace?: boolean;
+    newTab?: boolean;
+    timeout?: number;
+};
+export type NavigateResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+declare module '@assembly-js/app-bridge' {
+    interface AssemblyBridgeApi {
+        postToParent(message: {
+            type: string;
+            [key: string]: unknown;
+        }, options?: {
+            droppable?: boolean;
+        }): void;
+        navigateTo(destination: NavigateDestination, options?: NavigateToOptions): Promise<NavigateResult>;
+    }
+}

package/dist/bridge-vnext.js

@@ -0,0 +1,13 @@
+// The published @assembly-js/app-bridge types this package typechecks against
+// (peer >=1.3.0) predate the public postToParent and navigateTo. Both land on
+// the 2.0.0 set, where they're required interface members. Augment rather
+// than depending on an unpublished tarball; call sites guard with `?.` /
+// truthiness checks since older peers lack these at runtime.
+//
+// Exported as real types (not just declared ambiently) because an ambient
+// .d.ts that nothing imports never reaches a published package's declaration
+// output — tsc only emits/carries declarations that are part of the module
+// graph. lib-client.ts imports these types from this module instead of from
+// '@assembly-js/app-bridge' so the augmentation travels with it to consumers
+// on older peers, which don't export these names at all.
+import '@assembly-js/app-bridge';

package/dist/lib-client.d.ts

@@ -1,5 +1,7 @@
+import type { NavigateDestination, NavigateToOptions } from './bridge-vnext.js';
 export declare function reexchangeBearer(): Promise<boolean>;
 export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+export declare function downloadViaBlob(url: string, filename: string): Promise<void>;
 /**
  * Mint an in-memory bearer at load when the browser is refusing to store the
  * cookie, so the first client-side navigation is already authenticated instead
@@ -8,3 +10,13 @@ export declare function authFetch(input: RequestInfo | URL, init?: RequestInit):
  * Exported for tests; runs once at module load in the browser.
  */
 export declare function bootstrapCookielessBearer(): Promise<boolean>;
+/**
+ * Returns an onClick handler that navigates the parent Assembly portal to the
+ * given typed destination. Use in button or anchor onClick props.
+ *
+ * @example
+ * <button onClick={linkTo({ to: 'invoice', invoiceId: invoice.id })}>
+ *   View invoice
+ * </button>
+ */
+export declare function linkTo(destination: NavigateDestination, options?: NavigateToOptions): () => void;

package/dist/lib-client.js

@@ -126,6 +126,28 @@ export async function authFetch(input, init) {
     }
     return fetch(input, { ...init, headers });
 }
+// Downloads a file from url via authFetch (bearer cookie, same-origin), then
+// triggers a browser download without opening a new tab. Use this instead of
+// window.open or <a download href=url>: a new top-level tab is a different cookie
+// partition under CHIPS, so the bearer is absent and the route 401s.
+export async function downloadViaBlob(url, filename) {
+    const res = await authFetch(url);
+    if (!res.ok)
+        throw new Error(`Download failed: ${res.status}`);
+    const blob = await res.blob();
+    const objectUrl = URL.createObjectURL(blob);
+    try {
+        const a = document.createElement('a');
+        a.href = objectUrl;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+    }
+    finally {
+        URL.revokeObjectURL(objectUrl);
+    }
+}
 /**
  * Mint an in-memory bearer at load when the browser is refusing to store the
  * cookie, so the first client-side navigation is already authenticated instead
@@ -144,3 +166,22 @@ export function bootstrapCookielessBearer() {
 // Self-running, mirroring origin-bootstrap: module evaluation precedes
 // hydration, so the bearer is in hand before any component's first fetch.
 void bootstrapCookielessBearer();
+/**
+ * Returns an onClick handler that navigates the parent Assembly portal to the
+ * given typed destination. Use in button or anchor onClick props.
+ *
+ * @example
+ * <button onClick={linkTo({ to: 'invoice', invoiceId: invoice.id })}>
+ *   View invoice
+ * </button>
+ */
+export function linkTo(destination, options) {
+    return () => {
+        // navigateTo rejects when the host never answers (e.g. the nav v2 flag is
+        // off) — catch it here, since the caller only gets a void onClick handler
+        // back and has no promise of its own to attach a handler to.
+        AssemblyBridge.navigateTo?.(destination, options)?.catch((err) => {
+            console.error('linkTo: navigateTo failed', err);
+        });
+    };
+}

package/package.json

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

package/skills/assembly-ai/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-ai
-description: Use when the app needs AI features like text generation, summarization, analysis, or any LLM capability. Apps call Assembly's AI proxy — no API keys or external SDKs needed.
+description: Use when the app needs AI features like text generation, summarization, analysis, vision, speech-to-text, or any LLM capability. Apps call Assembly's AI proxy — no API keys or external SDKs needed.
 ---
 
 ## How it works
@@ -96,6 +96,29 @@ const toDataUrl = (file: File): Promise<string> =>
 
 Keep images under ~4 MB to stay within the 6 MB Lambda payload limit (base64 adds ~33% overhead). For larger images, resize on the client before converting.
 
+## Audio (speech-to-text)
+
+Record in the browser with `MediaRecorder` in the browser's native container: `audio/webm;codecs=opus`, or `audio/mp4` on Safari. Use a speech bitrate such as 24 kbps. Do not decode the recording to PCM or WAV in the browser.
+
+Transcribe on the server. Post the file as `multipart/form-data` to `/v1/ai/openai/audio/transcriptions` through `assembly.fetch()`. Use `gpt-4o-mini-transcribe` (`whisper-1` is the alternative). Do not set a JSON `Content-Type` on this call. Pass the `FormData` as the body and let the runtime set the multipart header.
+
+```typescript
+export async function transcribeAudio(file: File) {
+  const assembly = await getAssembly();
+  const body = new FormData();
+  body.append('file', file);
+  body.append('model', 'gpt-4o-mini-transcribe');
+  const response = await assembly.fetch('/v1/ai/openai/audio/transcriptions', {
+    method: 'POST',
+    body,
+  });
+  if (!response.ok) throw new Error(`AI request failed: ${response.status}`);
+  return response;
+}
+```
+
+Keep each uploaded file under 4 MB. The platform API rejects request bodies above roughly 4.5 MB with HTTP 413 before the proxy runs, and there is no richer error to catch. Keep each file under about five minutes so the upstream call also finishes inside the proxy's 27 second first-byte timeout. For longer recordings, split the recording into files that meet both bounds and persist each transcript piece as it completes.
+
 ## Model selection
 
 - Default to `gpt-4o-mini` for most tasks (fast, cheap, good enough)

package/skills/assembly-storage/SKILL.md

@@ -13,8 +13,8 @@ Use app-storage for files that belong to YOUR app. For files the user expects to
 
 **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.
+- `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.
 
 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.
 
@@ -26,7 +26,7 @@ The pre-signed URL does not lock the `Content-Type`, so any value works — set
 
 ```typescript
 'use client';
-import { authFetch } from './lib-client';
+import { authFetch } from '@/app/components/lib-client';
 
 export async function uploadFile(file: File) {
   const res = await authFetch('/api/app-storage/upload-url', {
@@ -70,7 +70,9 @@ export async function POST(request: NextRequest) {
 
 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.
+### Pattern A — route returns a pre-signed S3 URL (no proxy of bytes)
+
+Create a route that returns the pre-signed URL as JSON, then open that URL via a programmatic anchor click. The pre-signed URL carries S3 credentials directly, so no auth cookie is needed to access S3. Use `authFetch` only for the initial request to get the URL.
 
 **Route handler** (`app/api/app-storage/download/route.ts`):
 
@@ -92,6 +94,8 @@ export async function GET(request: NextRequest) {
 **Client-side download trigger:**
 
 ```typescript
+import { authFetch } from '@/app/components/lib-client';
+
 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');
@@ -106,7 +110,18 @@ async function downloadFile(key: string) {
 }
 ```
 
-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`.
+### Pattern B — route returns bytes directly (use `downloadViaBlob`)
+
+When your route fetches from S3 and streams the bytes back instead of a pre-signed URL, use `downloadViaBlob` from `app/components/lib-client.ts`. It calls `authFetch`, reads `res.blob()`, and triggers the download via a programmatic anchor — the bearer cookie is sent because the fetch is same-origin, avoiding the CHIPS partition problem that breaks `window.open` and `<a download href=…>` to a new tab.
+
+```typescript
+import { downloadViaBlob } from '@/app/components/lib-client';
+
+// In a button onClick handler:
+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`.
 
 ## Server needs the bytes (parse / process an uploaded file)