@assembly-js/app-foundation 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -19,6 +19,12 @@ 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.
+
 ## 0.2.5
 - [new] The client-call scan no longer reports reading the session's token details, a client's allowed fetch routes, or a harmless local namespace import as breaking; nothing in the app 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/bin/foundation-exports.mjs

@@ -30,7 +30,7 @@ export const NON_CLIENT_EXPORTS = new Set([
   'InternalUserAccess', 'LEGACY_APP_IDS', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
   'MintedBearer', 'NETWORK_CAPTURE_MESSAGE_TYPE', 'NetworkCaptureHeaderFingerprint',
   'NetworkCaptureRecord', 'PAINTED_BEACON_EVENT', 'PAINTED_BEACON_PATH',
-  'PORTAL_ORIGIN_COOKIE_NAME', 'PREVIEW_V2_FLAG', 'PdfText', 'PrincipalAllow', 'PrincipalKind',
+  'PORTAL_ORIGIN_COOKIE_NAME', 'PdfText', 'PrincipalAllow', 'PrincipalKind',
   'Provider', 'ProxyOpts', 'RENEW_OUTCOME_EVENT', 'RenewOutcome', 'ReplaceChildRowsResult',
   'RequestSource', 'ResolveResourceOpts', 'ResourceError', 'ResourceFieldMap',
   'ResourceOption', 'ResourcePage', 'ScheduleCadence', 'SlackChannel',

package/dist/origin-bootstrap.d.ts

@@ -1,6 +1,5 @@
 export declare const PORTAL_ORIGIN_COOKIE_NAME = "assembly-portal-origin";
 export declare const CLIENT_FLAGS_COOKIE_NAME = "assembly-flags";
-export declare const PREVIEW_V2_FLAG = "app-builder-preview-v2";
 /**
  * Reads a single cookie by name from a cookie string (defaults to
  * `document.cookie`). Shared by every module that reads a proxy-mirrored
@@ -9,14 +8,13 @@ export declare const PREVIEW_V2_FLAG = "app-builder-preview-v2";
 export declare function readCookie(name: string, cookieString?: string): string | null;
 /**
  * Whether the given flag key is present in the proxy-mirrored flags cookie.
- * Exported for other vNext modules (e.g. the paint beacon) to check the same
- * cookie without re-parsing it themselves.
+ * Exported so client modules can gate on a flag without re-parsing the cookie.
  */
 export declare function hasClientFlag(key: string, cookieString?: string): boolean;
 /**
  * Register the workspace's portal origin with the bridge allowlist — from the
- * proxy-set cookie when the preview-v2 flag is on, from the legacy framing
- * origin otherwise. Returns the origin it registered, or null when there was
- * nothing to do. Exported for tests; runs once at module load in the browser.
+ * proxy-set cookie when it is readable, from the framing origin otherwise.
+ * Returns the origin it registered, or null when there was nothing to do.
+ * Exported for tests; runs once at module load in the browser.
  */
 export declare function bootstrapPortalOrigin(cookieString?: string): string | null;

package/dist/origin-bootstrap.js

@@ -2,20 +2,18 @@
 // evaluation precedes hydration — so the workspace's portal origin joins the
 // bridge allowlist before any component's first header/session-token call.
 //
-// The preview-v2 flag selects WHICH trust source registers the origin — it
-// never selects whether anything registers at all (flag-off must keep custom
-// portal domains working exactly as pre-vNext package versions did):
+// Two trust sources, in order:
 //
-//  - flag ON: the proxy-set cookie. The value is platform-resolved, never
-//    inferred client-side — the proxy already fetches workspace.portalUrl for
-//    its CSP frame-ancestors header and mirrors it into this client-readable
-//    cookie. Immune to the navigation-state poisoning below.
-//  - flag OFF (or flags cookie unreadable): the legacy browser-reported
-//    framing origin (ancestorOrigins, referrer fallback). Trusting it is
-//    sound because the proxy's CSP frame-ancestors already gates who may
-//    frame the app, but it rides navigation state — strip-able by privacy
-//    modes and poisoned by in-iframe reloads — which is why the cookie path
-//    replaces it.
+//  - the proxy-set cookie. The value is platform-resolved, never inferred
+//    client-side — the proxy already fetches workspace.portalUrl for its CSP
+//    frame-ancestors header and mirrors it into this client-readable cookie.
+//    Immune to the navigation-state poisoning below.
+//  - when that cookie is unreadable (a browser blocking the app's cookies):
+//    the browser-reported framing origin (ancestorOrigins, referrer
+//    fallback). Trusting it is sound because the proxy's CSP frame-ancestors
+//    already gates who may frame the app, but it rides navigation state —
+//    strip-able by privacy modes and poisoned by in-iframe reloads — which is
+//    why the cookie comes first.
 //
 // The bridge has no trust bypass, so one of these registrations is the only
 // way a custom portal domain becomes a valid parent (dashboard/platform
@@ -29,7 +27,6 @@ export const PORTAL_ORIGIN_COOKIE_NAME = 'assembly-portal-origin';
 // plain, comma-separated cookie on every request (set or cleared, never
 // left stale).
 export const CLIENT_FLAGS_COOKIE_NAME = 'assembly-flags';
-export const PREVIEW_V2_FLAG = 'app-builder-preview-v2';
 /**
  * Reads a single cookie by name from a cookie string (defaults to
  * `document.cookie`). Shared by every module that reads a proxy-mirrored
@@ -51,8 +48,7 @@ export function readCookie(name, cookieString) {
 }
 /**
  * Whether the given flag key is present in the proxy-mirrored flags cookie.
- * Exported for other vNext modules (e.g. the paint beacon) to check the same
- * cookie without re-parsing it themselves.
+ * Exported so client modules can gate on a flag without re-parsing the cookie.
  */
 export function hasClientFlag(key, cookieString) {
     const raw = readCookie(CLIENT_FLAGS_COOKIE_NAME, cookieString);
@@ -61,11 +57,11 @@ export function hasClientFlag(key, cookieString) {
     return raw.split(',').includes(key);
 }
 /**
- * Legacy (pre-vNext) framing-origin resolution: `location.ancestorOrigins`
+ * Framing-origin resolution for when the portal-origin cookie is unreadable: `location.ancestorOrigins`
  * (browser-attested; Chromium/WebKit), falling back to `document.referrer`
  * (Firefox). Null outside an iframe or when neither source is available.
  */
-function resolveLegacyParentOrigin() {
+function resolveFramingOrigin() {
     if (typeof window === 'undefined')
         return null;
     if (window.parent === window)
@@ -85,25 +81,20 @@ function resolveLegacyParentOrigin() {
 }
 /**
  * Register the workspace's portal origin with the bridge allowlist — from the
- * proxy-set cookie when the preview-v2 flag is on, from the legacy framing
- * origin otherwise. Returns the origin it registered, or null when there was
- * nothing to do. Exported for tests; runs once at module load in the browser.
+ * proxy-set cookie when it is readable, from the framing origin otherwise.
+ * Returns the origin it registered, or null when there was nothing to do.
+ * Exported for tests; runs once at module load in the browser.
  */
 export function bootstrapPortalOrigin(cookieString) {
-    if (!hasClientFlag(PREVIEW_V2_FLAG, cookieString)) {
-        // Flag off: behave exactly like pre-vNext package versions so custom
-        // portal domains keep a working bridge — and so turning the flag OFF is
-        // a true rollback, not a third state. Https-only: local dev origins are
-        // already on the default allowlist.
-        const origin = resolveLegacyParentOrigin();
+    const record = readCookie(PORTAL_ORIGIN_COOKIE_NAME, cookieString);
+    if (!record) {
+        // Https-only: local dev origins are already on the default allowlist.
+        const origin = resolveFramingOrigin();
         if (!origin || !origin.startsWith('https://'))
             return null;
         AssemblyBridge.configure({ additionalOrigins: [origin] });
         return origin;
     }
-    const record = readCookie(PORTAL_ORIGIN_COOKIE_NAME, cookieString);
-    if (!record)
-        return null;
     // Accept only a bare https origin — anything else (paths, http, garbage)
     // is not a value the proxy writes and must not reach the allowlist.
     try {

package/dist/paint-beacon.js

@@ -6,13 +6,7 @@
 // The HTTP route is handled in proxy.ts via the helpers below (same
 // package-delegation pattern as session-exchange). The bridge post rides
 // buffer-until-learned, so a paint that beats the parent's hello is not lost.
-//
-// Gated on the preview-v2 flag (see origin-bootstrap.ts's hasClientFlag):
-// installPaintBeacon() no-ops for a flag-off workspace, so the client never
-// calls sendBeacon and the proxy's route never sees a request — no need to
-// separately gate handlePaintedBeacon() below.
 import { AssemblyBridge } from '@assembly-js/app-bridge';
-import { hasClientFlag, PREVIEW_V2_FLAG } from './origin-bootstrap.js';
 export const PAINTED_BEACON_PATH = '/__assembly/painted';
 export const PAINTED_BEACON_EVENT = 'assembly.painted';
 let scheduled = false;
@@ -46,9 +40,7 @@ function firePaintBeacon() {
  * hydration + rAF wins. Does nothing on the server.
  */
 export function installPaintBeacon() {
-    if (typeof window === 'undefined' || scheduled)
-        return;
-    if (!hasClientFlag(PREVIEW_V2_FLAG))
+    if (typeof window === 'undefined' || typeof document === 'undefined' || scheduled)
         return;
     scheduled = true;
     const afterPaint = () => {

package/package.json

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