@assembly-js/app-foundation 0.0.33 → 0.0.35

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
@@ -157,7 +160,9 @@ Before adding a feature, check whether Assembly already covers it. If it does, *
 **Then ask who should perform it — you or the platform.** Reaching a module through the SDK is right when the user is doing the thing *now*: they pressed a button and are watching it happen. When the effect should instead happen *in reaction to* something that happens in the app ("when a project is completed, message the client"), that is a workflow that integrates with the Assembly platform, and **the platform performs it, not your code.** The test is where the effect lands: on Assembly's own data rather than only in your app's tables. Decide this **before** you write or plan the call — read the `assembly-automations` skill to decide it, and don't reach for the module's SDK method until you have.
 <!-- /feature:api-resources -->
 
-**Built-in modules (core, available in every portal):**
+**Always available (every workspace):** Clients, companies, and custom fields — see "The data model" below. Use them; do not rebuild them. Notification infrastructure (`listNotifications`, `createNotification`, `deleteNotification`, `markNotificationRead`, `markNotificationUnread`) is also always available.
+
+**Optional modules (may or may not be installed in this workspace):** Messages, Files, Contracts, Forms, Billing, Knowledge Base, Tasks, and Notes. Before suggesting one or calling its SDK, confirm it is installed — call `listAppInstalls`. If it is installed, use it through the SDK; do not rebuild it. If it is not installed, do not suggest it, do not plan the app around it, and do not ask the user to install it.
 
 | Module | What it does | Reach via SDK |
 |---|---|---|
@@ -169,10 +174,9 @@ Before adding a feature, check whether Assembly already covers it. If it does, *
 | Billing | Invoices, subscriptions, payments | `createInvoice`, `listInvoices`, `retrieveInvoice`, `listInvoiceTemplates`, `createSubscription`, `listSubscriptions`, `retrieveSubscription`, `cancelSubscription`, `listSubscriptionTemplates`, `listProducts`, `retrieveProduct`, `listPrices`, `retrievePrice`, `listPayments` |
 | Knowledge Base | Help articles / docs | (no SDK methods today; render-only) |
 | Tasks | Assign tasks to clients/team | `retrieveTasks`, `createTask`, `retrieveTask`, `updateTask`, `deleteTask`, `listTaskTemplates`, `retrieveTaskTemplate` |
-| Notifications | In-app notification feed | `listNotifications`, `createNotification`, `deleteNotification`, `markNotificationRead`, `markNotificationUnread` |
 | Notes | Per-client/company internal notes | `createNote`, `listNotes`, `retrieveNote`, `updateNote`, `deleteNote` |
 
-If the user's prompt says "build a CRM," the answer is mostly **wire up the existing Clients + Companies + Notes + Tasks modules in a custom view** — not invent your own.
+If the user's prompt says "build a CRM," the answer is mostly **wire up the existing Clients + Companies** (and any optional modules that are actually installed) **in a custom view** — not invent your own.
 
 ---
 
@@ -329,7 +333,7 @@ Pair it with a server-component or page-level guard so the user sees a friendly
 
 A Postgres database is provisioned for this app. `DATABASE_URL` is already in your shell environment.
 
-Use it for any persistent data that Assembly's built-in modules don't cover (custom records, time entries, app-specific state, etc.). **Check the built-in modules table first** — prefer Assembly SDK data over custom tables when a module already covers the need.
+Use it for any persistent data that Assembly's modules don't cover (custom records, time entries, app-specific state, etc.). **Check the modules section above first** — prefer Assembly SDK data over custom tables when an installed module already covers the need.
 
 **`drizzle-orm`, `@neondatabase/serverless`, and `drizzle-kit` are pre-installed. `lib/db.ts`, `lib/schema.ts`, and `drizzle.config.ts` are already in the repo.** Do NOT run `bun add` for these packages or recreate those files.
 
@@ -1152,7 +1156,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't decode the session token client-side. It's encrypted; only the SDK on the server can read it.
 - ❌ Don't use `URLSearchParams` on `window.location` to read the token in App Router server components — use the typed `searchParams` prop.
 - ❌ Don't make Assembly API calls from client components without a server-side proxy. The apiKey can't leave the server.
-- ❌ Don't reinvent built-in Assembly features (Messages, Files, Forms, Tasks, Billing) — call the SDK methods listed above.
+- ❌ Don't reinvent Clients, Companies, or custom fields — they are always available via the SDK. For Messages, Files, Forms, Tasks, Billing, Contracts, Notes, or Knowledge Base: confirm the module is installed (`listAppInstalls`) first; if it is, call the SDK methods listed above rather than rebuilding it. If it is not installed, do not suggest it or plan around it.
 - ❌ Don't use `assembly.clients.list()` — the SDK is flat. Use `assembly.listClients(...)`.
 - ❌ Don't cache decoded payloads for >30s — token rotates every 5 min and the user could be different on the next call (rare, but possible if a session is shared across tabs).
 <!-- !feature:app-owned-header -->
@@ -1212,5 +1216,5 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 <!-- !feature:app-owned-header -->
 6. **Use `AssemblyBridge.header.*`** for breadcrumbs/CTAs in client components. Don't render your own. (Exception: the notification surface `/n` has no header — render CTAs as inline buttons there.)
 <!-- /feature:app-owned-header -->
-7. **Don't reinvent Messages/Files/Forms/Tasks/Billing.** Wire them up via SDK.
+7. **Don't reinvent Clients/Companies/custom fields.** For Messages/Files/Forms/Tasks/Billing and similar optional modules, confirm they are installed (`listAppInstalls`) before wiring them via SDK — and skip them if they aren't.
 8. **Keep infrastructure plumbing out of chat.** Don't volunteer ASSEMBLY_ENV, COPILOT_ENV, token encryption, API key internals, or internal file names unprompted. Mid-build SDK auth warnings are expected — never surface them to the user. (Answering a user's direct technical question is fine.)

package/package.json

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