@assembly-js/app-foundation 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -19,6 +19,9 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.2.7
+- [guidance] The build agent learns to call another app through its generated client and to show an empty state naming that app when the call is refused.
+
 ## 0.2.6
 - [fix] The app keeps connecting to a portal on a custom domain, and keeps telling the editor when it has loaded, without relying on a platform setting that is being retired. Nothing visible changes.
 

package/CLAUDE.md

@@ -48,6 +48,9 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 <!-- 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 -->
+<!-- feature:cross-app-apis -->
+- `assembly-app-clients` — calling another workspace app through its generated client in `generated/apps/<appId>/` (`installerClient`, by verb and path), and rendering an empty state that names the app when the call is refused instead of a 500.
+<!-- /feature:cross-app-apis -->
 - `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
@@ -454,6 +457,9 @@ Relationships:
 
 If the user names another app, read its file in `.assembly/docs/apps/` and follow the call recipe at the top of that file. If that folder is absent, the app is not callable (it may still need the Security update). Cross-app calls from pages, server actions and routes use `getInstallerAssembly()`; cron and webhooks use `getOfflineAssembly()`. Never return another app's response to a client unfiltered — scope any client data you forward. While a person is using the app, those calls use the installer client, because the platform does not yet prove which person the call is for. Once it can, use the viewer client for that person's data and keep the installer client for staff-wide reads.
 <!-- /feature:api-resources -->
+<!-- feature:cross-app-apis -->
+When `generated/apps/<appId>/` exists for that app, call it through the generated client instead (see the `assembly-app-clients` skill); the docs recipe is the fallback for an app with no folder there.
+<!-- /feature:cross-app-apis -->
 
 ---
 

package/package.json

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

package/skills/assembly-app-clients/SKILL.md

@@ -0,0 +1,80 @@
+<!-- feature:cross-app-apis -->
+---
+name: assembly-app-clients
+description: Use when the app calls another workspace app and `generated/apps/<appId>/` exists for it. Covers reading the generated README and types, calling `installerClient` by verb and path, and rendering an empty state that names the app when the call is refused (app_not_found, operation_not_found, viewer_not_allowed, callee_error) instead of throwing a 500.
+---
+
+## Where the client lives
+
+Each app this one may call has a folder at `generated/apps/<appId>/`, refreshed by the platform at the start of every turn:
+
+- `README.md` — read it first. It lists every operation as a verb and a path, with a summary.
+- `types.d.ts` — the request and response shapes of each operation. Read the one you need before writing the call.
+- `client.ts` — exports `installerClient` and `viewerClient`.
+- `openapi.json` — the contract the other files were generated from.
+
+Never edit these files; the next refresh overwrites them. If an app has no folder here, it has published no contract: follow the call recipe in its `.assembly/docs/apps/` file instead.
+
+## Calling another app
+
+Call an operation by its verb and path, exactly as the README lists it. Paths, parameters and bodies are type-checked against the contract, so a wrong path fails the type check instead of production.
+
+```ts
+import { installerClient } from '@/generated/apps/<appId>/client';
+
+const { data, error } = await installerClient.GET('/projects/{id}', {
+  params: { path: { id } },
+});
+```
+
+Call it from server code only: pages, server actions, route handlers, cron and webhooks. Never import it into a `'use client'` component.
+
+## Installer or viewer
+
+Use `installerClient`. It calls as this app, so filter anything it returns to what the viewing client may see before you show it to a client.
+
+`viewerClient` calls as the signed-in person. The platform refuses it with `viewer_not_allowed` until it can prove which person the call is for, so use `installerClient` for now.
+
+## When the other app cannot answer
+
+The other app can be uninstalled, can drop an operation, or can fail on its own. None of these may crash the page. A refusal does not throw: the call returns no `data` and an `error` whose `code` says why.
+
+| `code` | Meaning | What to render |
+|---|---|---|
+| `app_not_found` | The app is not installed in this workspace, or this app may not call it. | Empty state: "<App name> is not available in this workspace." |
+| `operation_not_found` | The app no longer offers this operation. | Empty state: "<App name> no longer provides this." |
+| `viewer_not_allowed` | The call used `viewerClient`. | Nothing at runtime: switch the call to `installerClient`. |
+| `callee_error` | The other app answered with its own failure. The most common case at runtime. | Error state: "<App name> could not load this right now." |
+
+Branch on the result and render a state that names the app:
+
+```tsx
+import { installerClient } from '@/generated/apps/<appId>/client';
+
+const PROVIDER_NAME = 'Projects';
+const MISSING_CODES = ['app_not_found', 'operation_not_found'];
+
+function errorCode(error: unknown): string | undefined {
+  if (typeof error !== 'object' || error === null || !('code' in error)) return undefined;
+  return typeof error.code === 'string' ? error.code : undefined;
+}
+
+export default async function ProjectsPanel() {
+  const { data, error } = await installerClient.GET('/projects');
+  if (!data) {
+    const code = errorCode(error);
+    if (code && MISSING_CODES.includes(code)) {
+      return <EmptyState title={`${PROVIDER_NAME} is not available in this workspace.`} />;
+    }
+    console.error('projects call failed', code ?? error);
+    return <EmptyState title={`${PROVIDER_NAME} could not load this right now.`} />;
+  }
+  return <ProjectList projects={data} />;
+}
+```
+
+- Only the part of the page that depends on the other app shows the empty state; render the rest as usual.
+- A network failure throws instead of returning `error`. Wrap the call in `try`/`catch` where the page must still render, and show the same error state.
+- In a server action, return `{ ok: false, message }` naming the app (see `assembly-action-results`) instead of throwing.
+- In a route handler, answer with a non-500 status and a static message naming the app (see `assembly-route-errors`). Never forward the other app's message to a client.
+<!-- /feature:cross-app-apis -->