@assembly-js/app-foundation 0.0.32 → 0.0.34

package/CLAUDE.md

@@ -43,6 +43,9 @@ 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
+<!-- feature:deep-link-bridge-nav -->
+- `assembly-platform-links` — link platform records (client, company, invoice, contract, form, file) to their portal detail page via `linkTo()`; never hand-build a host URL. Also links between workspace apps by install id. Check the app's installed app-bridge first (see the skill) — `navigateTo` doesn't exist on older peers — and only link staff-only destinations (client, company, form, etc.) from the dashboard surface, never the client portal.
+<!-- /feature:deep-link-bridge-nav -->
 - `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

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.32",
+  "version": "0.0.34",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

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 -->

package/skills/assembly-platform-links/SKILL.md

@@ -0,0 +1,169 @@
+<!-- feature:deep-link-bridge-nav -->
+---
+name: assembly-platform-links
+description: Use whenever the app shows a platform record (client, company, invoice, contract, form, file) that the user should be able to navigate to, or when linking between workspace apps. Covers linkTo() for click handlers and AssemblyBridge.navigateTo() when you need the result. Never hand-build a host URL.
+---
+
+## Before you start: confirm this app's bridge supports `navigateTo`
+
+`navigateTo` only exists on app-bridge 2.x. An app's bridge version is frozen at birth — some apps are still running an older peer with no runtime implementation of it at all. On those, a `linkTo()` button still renders but clicking it does nothing: the optional-chain in its onClick silently no-ops.
+
+Before writing any `linkTo()` or `AssemblyBridge.navigateTo()` call, check what this app actually has installed:
+
+```bash
+grep -q navigateTo node_modules/@assembly-js/app-bridge/dist/index.d.ts && echo supported || echo unsupported
+```
+
+If it reports `unsupported`, do not use this skill — there is no supported way for this app to trigger platform navigation yet. Skip the link rather than ship a button that silently does nothing.
+
+## When to reach for this skill
+
+Any time the app renders a **name or reference to a platform entity** — a client name, a company badge, an invoice number, a contract, a form, a file — offer a link that opens the platform's canonical detail page, on surfaces where that destination is reachable (see the "Client portal" column in the destination catalog below). Internal/staff users can navigate to any destination. Clients in the portal can only reach the destinations marked available there — their own invoices, contracts, help articles, files, channels, and other installed apps — not `client`, `company`, `form`, or the other staff-only destinations, which the host rejects for a client viewer.
+
+Do not hand-build a URL. The host URL is opaque to the app and the path varies across deployments and surfaces. Use `linkTo()` or `AssemblyBridge.navigateTo()` instead.
+
+## The helper: `linkTo(destination)`
+
+`linkTo` (from `@assembly-js/app-foundation/lib-client`) returns a `() => void` onClick handler. Wire it to a `<button>` or anchor `onClick` prop. It calls `AssemblyBridge.navigateTo`, swallows the promise, and logs any failure to the console — you get a clean side-effect-free click handler without managing the promise yourself.
+
+```tsx
+'use client';
+import { linkTo } from '@assembly-js/app-foundation/lib-client';
+
+// ✅ RIGHT — navigates the host to the client's detail page
+<button onClick={linkTo({ to: 'client', clientId: client.id })}>
+  {client.name}
+</button>
+
+// ✅ RIGHT — open in a new tab (internal user surface)
+<button onClick={linkTo({ to: 'invoice', invoiceId: invoice.id }, { newTab: true })}>
+  View invoice
+</button>
+```
+
+## The direct call: `AssemblyBridge.navigateTo()`
+
+When you need to know whether navigation succeeded — for example, to show a toast if the host can't open the record, or to disable a button after a failed attempt — call `navigateTo` directly and inspect the result.
+
+```tsx
+'use client';
+import { AssemblyBridge } from '@assembly-js/app-bridge';
+
+const result = await AssemblyBridge.navigateTo?.({ to: 'client', clientId });
+if (result?.ok === false) {
+  // Host declined (viewer lacks permission or destination is gated)
+  setLinkDisabled(true);
+}
+```
+
+Always call it as `AssemblyBridge.navigateTo?.()` with the optional-chain. The method is absent on app-bridge peers below 2.0.0; the `?.` silently no-ops rather than throwing.
+
+## Destination catalog
+
+The host rejects staff-only destinations when the viewer is a client in the portal — navigation resolves to `{ ok: false, reason: 'not_permitted' }` (and a `linkTo()` button just does nothing, since it swallows the result). Only render a link to a destination from the client portal surface when "Client portal" below is Yes.
+
+| Destination | Required fields | Optional | Client portal |
+|---|---|---|---|
+| `client` | `clientId` | `tab` | No — staff only |
+| `company` | `companyId` | `tab` | No — staff only |
+| `invoice` | `invoiceId` | — | Yes |
+| `subscription` | `subscriptionId` | — | No — staff only |
+| `contract` | `contractId` | — | Yes |
+| `form` | `formId` | — | No — staff only |
+| `formResponse` | `formId`, `responseId` | — | No — staff only |
+| `article` | `articleId` | — | Yes |
+| `files` | — | `channelId` | Yes |
+| `channel` | — | `channelId` | Yes |
+| `app` | `installId` | — | Yes, if the target app is installed for that viewer |
+| `home` | — | — | No — staff only |
+| `product` | — | — | No — staff only |
+| `helpdesk` | — | — | Yes |
+| `notifications` | — | — | No — staff only |
+| `automations` | — | — | No — staff only |
+| `settings` | — | `page` | No — staff only |
+
+## Linking to another workspace app
+
+When the workspace has multiple apps and the user should navigate between them, use the target app's **install id** — neither the token payload nor `useAssembly()` expose it (those only carry `instanceId`, for the app currently open). Look the companion app up server-side with `listAppInstalls()` and match it by `displayName`, the same name-matching pattern used for custom fields — never hardcode an install id, installs are minted per workspace:
+
+```ts
+// Server-side (route handler or server action)
+import { getAssembly } from '@assembly-js/app-foundation/server';
+
+const assembly = await getAssembly();
+const installs = await assembly.listAppInstalls({});
+const invoicing = installs.find((i) => i.displayName?.toLowerCase().includes('invoicing'));
+```
+
+```tsx
+// ✅ RIGHT — links to a companion app by install id looked up server-side
+<button onClick={linkTo({ to: 'app', installId: invoicing.id })}>
+  Open Invoicing
+</button>
+```
+
+Pass the install id, not a deployment URL or a hand-built path.
+
+## Internal surface example
+
+An internal user sees a table of clients. Each row has a link that opens the client's Assembly CRM page:
+
+```tsx
+'use client';
+import { linkTo } from '@assembly-js/app-foundation/lib-client';
+import { ExternalLink } from 'lucide-react';
+
+export function ClientRow({ client }: { client: Client }) {
+  return (
+    <tr>
+      <td>
+        <button
+          onClick={linkTo({ to: 'client', clientId: client.id })}
+          className="flex items-center gap-1 text-sm text-blue-600 hover:underline"
+        >
+          {client.name}
+          <ExternalLink className="h-3 w-3" />
+        </button>
+      </td>
+    </tr>
+  );
+}
+```
+
+## Client portal surface example
+
+A client sees their own invoices. Each row links to the invoice record in the portal:
+
+```tsx
+'use client';
+import { linkTo } from '@assembly-js/app-foundation/lib-client';
+
+export function InvoiceRow({ invoice }: { invoice: Invoice }) {
+  return (
+    <tr>
+      <td>
+        <button
+          onClick={linkTo({ to: 'invoice', invoiceId: invoice.id })}
+          className="text-sm text-blue-600 hover:underline"
+        >
+          {invoice.number}
+        </button>
+      </td>
+    </tr>
+  );
+}
+```
+
+## What NOT to do
+
+```tsx
+// ❌ WRONG — hand-building a host URL (opaque, breaks across deployments)
+window.open(`https://app.assembly.com/clients/${clientId}`, '_blank');
+
+// ❌ WRONG — plain <a> with a guessed platform path
+<a href={`/clients/${clientId}`}>View client</a>
+
+// ❌ WRONG — calling navigateTo without optional-chain (throws on older peers)
+await AssemblyBridge.navigateTo({ to: 'client', clientId });
+```
+<!-- /feature:deep-link-bridge-nav -->