@assembly-js/app-foundation 0.0.33 → 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/package.json

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

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