@assembly-js/app-foundation 0.0.31 → 0.0.33

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

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,3 +1,4 @@
+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>;
@@ -9,3 +10,13 @@ export declare function downloadViaBlob(url: string, filename: string): Promise<
  * 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

@@ -166,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/dist/next.js

@@ -1,25 +1,59 @@
+// Dev-invariant wrapper for generated apps' Next config. Each app's
+// next.config.ts is platform-owned boilerplate — `export default
+// withAssemblyDev(appConfig)` — so the preview invariants live here in the
+// versioned package instead of as config keys the build agent must know to
+// preserve when it edits its own app.config.ts.
+import * as fs from 'fs';
+import * as path from 'path';
+// Read non-root surface paths from the app manifest so location-prefix.ts can
+// discover them at runtime instead of relying on the hardcoded /c and /n defaults.
+function readSurfacePrefixes() {
+    try {
+        const manifestPath = path.join(process.cwd(), '.assembly', 'app.json');
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        const prefixes = Object.values(manifest.surfaces ?? {})
+            .map((s) => s.path)
+            .filter((p) => typeof p === 'string' && p !== '/');
+        return prefixes.length > 0 ? JSON.stringify(prefixes) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function withAssemblyDev(config = {}) {
+    // Inject manifest-derived surface prefixes into the client bundle so
+    // location-prefix.ts honours whatever paths the app declares.
+    const surfacePrefixesJson = readSurfacePrefixes();
+    const baseConfig = surfacePrefixesJson
+        ? {
+            ...config,
+            env: {
+                ...config.env,
+                NEXT_PUBLIC_ASSEMBLY_SURFACE_PREFIXES: surfacePrefixesJson,
+            },
+        }
+        : config;
     // Production builds (deploys) have no dev server, no HMR socket, and no
-    // sandbox host — the wrapper is a pass-through there.
+    // sandbox host — only the env injection above applies there.
     if (process.env.NODE_ENV === 'production')
-        return config;
+        return baseConfig;
     const sandboxHost = process.env.SANDBOX_HOST;
     const allowedDevOrigins = sandboxHost
-        ? [...new Set([sandboxHost, ...(config.allowedDevOrigins ?? [])])]
-        : config.allowedDevOrigins;
+        ? [...new Set([sandboxHost, ...(baseConfig.allowedDevOrigins ?? [])])]
+        : baseConfig.allowedDevOrigins;
     // A dev WebSocket that never connects would otherwise hang hydration forever
     // on Next 16.3+. Debug data falls back to the flight stream, so
     // nothing user-visible is lost. Cast because this package type-checks against
     // its Next 15 devDependency, which predates the flag; runtimes that predate
     // it ignore the unknown key.
     const experimental = {
-        ...config.experimental,
+        ...baseConfig.experimental,
         reactDebugChannel: false,
     };
     return {
-        ...config,
+        ...baseConfig,
         ...(allowedDevOrigins ? { allowedDevOrigins } : {}),
-        devIndicators: config.devIndicators ?? false,
+        devIndicators: baseConfig.devIndicators ?? false,
         experimental,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "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-app-surfaces/SKILL.md

@@ -25,7 +25,7 @@ If you are unsure, default to **internal-only**. Do not add a client surface unl
 }
 ```
 
-- `internal` is **required** — every Vibe app must have a dashboard surface. `client` is optional; omit it for internal-only apps. `notification` is optional; declare it only when the app uses `ctaParams` in notifications (see below).
+- `internal` is **required** — every Vibe app must have a dashboard surface. `client` is optional; omit it for internal-only apps. `notification` is optional; declare it when opening a notification should land on a specific record (see below).
 - `path` is the route within your app for that surface. Must start with `/`. Use `/` for the surface's root; use distinct sub-paths if both surfaces share one Next.js app.
 - Generate the corresponding routes in your app code. E.g. if you declare `client.path = "/c"`, you must have a `/c` page in the app.
 
@@ -58,7 +58,7 @@ The app's API contract (automation triggers/actions, webhook events) is NOT an `
 
 ## The `notification` surface
 
-When an app sends notifications with `ctaParams`, the Notification Center needs to know where to send the user when they click the notification's CTA. Declare a `notification` surface to set that destination URL.
+When a notification should open a specific record, declare a `notification` surface. That path is what the Notification Center embeds; it is not a button the app renders.
 
 ```json
 {
@@ -71,10 +71,10 @@ When an app sends notifications with `ctaParams`, the Notification Center needs
 
 When `notification` is declared:
 - The build pipeline sets `notificationUrl` on the marketplace app to `<deployURL>/n`.
-- When a user clicks a notification CTA, the portal opens the app at `notificationUrl?token=<jwt>&<ctaParams>`.
+- Opening the notification embeds that URL in the Notification Center detail panel, with the token and `ctaParams` as search params. If `notificationUrl` is empty, the panel has no iframe: it shows the body and an "Open {app name}" button that opens the app's main view, and non-reserved `ctaParams` are forwarded as search params on that view.
 - Your `/n` page shows its context-specific content from the `ctaParams` in the URL. Those always arrive; `notificationId` from the token payload is best-effort under the session-exchange flow, so never gate the record render on it.
 
-**Declare the `notification` surface whenever the app sends notifications with `ctaParams`.** If notifications have no `ctaParams`, the surface is optional. See the `assembly-notifications` skill for the full CTA params pattern.
+**Declare the `notification` surface, and pass `ctaParams` that identify the record, whenever a notification should open that record.** A send with neither is only correct when the destination is the app's main view. See the `assembly-notifications` skill.
 
 ## Examples
 

package/skills/assembly-notifications/SKILL.md

@@ -29,7 +29,9 @@ The audience changes the experience and the code:
 
 ## Notification surfaces
 
-A surface is the embedded view the Notification Center renders when an internal user opens a notification. It's a route (conventionally `/n`) that reads the notification context — `notificationId` from the token payload plus your `ctaParams` — and renders the most useful thing: a filtered list of the items referenced, a single record with its key actions, or a status summary. When there's nothing more useful than "here's what happened, click to go deeper," skip it — the Notification Center then falls back to the title, body, and CTA from your `createNotification` call.
+A surface is the embedded view the Notification Center renders when an internal user opens a notification. It's a route (conventionally `/n`) that reads your `ctaParams` off the URL and renders the record they name.
+
+Declare the surface, and pass `ctaParams` that identify the record, whenever opening the notification should land on that record (one retainer, one submission, one task). Without the surface the Center shows the title and body, plus a platform button labeled "Open {app name}" that opens the app's main view. Non-reserved `ctaParams` are forwarded as search params on that main view. Skip the surface only when that main view is the right destination.
 
 Surfaces are internal-only. Clients don't render one, but `ctaParams` still travel with the notification and become URL search params on an email CTA click — that's how a client landing from an email gets enough context.
 
@@ -142,7 +144,7 @@ export async function GET() {
 - `senderType` — read-side only. Automatically populated from `senderId` (client, internal user, or company). You do not set it on create.
 - `deliveryTargets.inProduct` — include to make the notification appear in the Notification Center (for internal users) or trigger the badge (for clients). Requires `title`. `body` and `ctaParams` are optional. Omit entirely for email-only notifications.
 - `deliveryTargets.email` — include to send an email. `subject`, `header`, and `title` (CTA button label) are required, plus one body: `htmlBody` for formatted content (see below) or `body` for plain text. Either `inProduct` or `email` must be present; both is also valid.
-- `ctaParams` — a plain object of string key/value pairs that become URL search params when the user engages with the notification. Pass as an object — never `JSON.stringify()`. **Values must be strings** — stringify numbers and booleans yourself (e.g., `{ count: '3' }`, not `{ count: 3 }`). Nested objects aren't supported. Used by both the email CTA and the Notification Center surface.
+- `ctaParams` — a plain object of string key/value pairs that become URL search params when the user engages with the notification. Pass as an object — never `JSON.stringify()`. **Values must be strings** — stringify numbers and booleans yourself (e.g., `{ count: '3' }`, not `{ count: 3 }`). Nested objects aren't supported. Used by both the email CTA and the Notification Center surface. A notification about one record always includes the id that selects it (`{ retainerId: retainer.id }`). Title and body text do not.
 <!-- feature:notification-settings -->
 - `notificationSettingId` — the id of one of the app's declared notification settings (see "Per-user notification settings" below). Pass it on **every** send of a declared category so internal users' Product/Email toggles apply. Omit it for sends with no declared setting.
 <!-- /feature:notification-settings -->