@assembly-js/app-foundation 0.0.53 → 0.0.54

package/CHANGELOG.md

@@ -14,6 +14,10 @@ A foundation update reads the sections between an app's version and the target:
 from every bullet except `[guidance]`, agent work from the check scripts those `[action]`
 bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
 
+## 0.0.54
+- [new] Add `isAppInstalled` and `getInstalledAppIds`, helpers an app can adopt to check which optional modules are installed in its workspace.
+- [guidance] The build agent is taught to check that a module is installed before relying on features that depend on it.
+
 ## 0.0.53
 - [action] A page or server action that calls a helper exported from a client-component file errors for every visitor who opens it; the build now reports the call, and the helper moves to a plain module both sides import.
 - [guidance] Tell the build agent that a helper shared between a server-rendered page and a client component belongs in a plain module, not the client component's file.

package/CLAUDE.md

@@ -167,7 +167,9 @@ Before adding a feature, check whether Assembly already covers it. If it does, *
 
 **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.
+**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 building on one, confirm it is installed: gate the feature with `isAppInstalled(assembly, <appId>)` from `@assembly-js/app-foundation/server` and render an honest "<app> isn't installed in this workspace" state when it is false; the plan's module list is the build-time source of truth. 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.
+
+**Never ask the user to test a client-facing write (a form request, message, invoice, notification) on a real client.** Suggest a throwaway test client instead, and say before the first test that a form request can't be undone from the app — it can only be removed in the dashboard.
 
 - **Messages** — Direct messaging between staff and clients. SDK groups: Messages, MessageChannels.
 - **Files** — Secure file/folder sharing. *For app-private uploads (attachments, exports) use the storage helpers from `@assembly-js/app-foundation/server` (see the `assembly-storage` skill) instead — Files is only for files the user wants in the portal Files tab.* SDK groups: Files, FileChannels.

package/dist/app-installs.d.ts

@@ -0,0 +1,17 @@
+import type { AssemblyAPI } from '@assembly-js/node-sdk';
+/**
+ * @deprecated Built-in modules are being replaced by generated apps, so this
+ * map will be removed. Prefer an appId you resolved from the workspace; use
+ * these only to gate a feature on a module that still ships built in.
+ */
+export declare const LEGACY_APP_IDS: {
+    readonly messages: "38323633-6465-6132-3730-383065323230";
+    readonly billing: "64346438-6461-6431-6565-366361383434";
+    readonly files: "33343966-3136-6166-6561-343739303432";
+    readonly contracts: "34633033-3365-6561-6332-386434316430";
+    readonly forms: "66666663-3861-6633-3830-323337613065";
+    readonly helpdesk: "30643961-3563-3361-3035-396231663435";
+    readonly tasks: "0e1dff29-1ce3-40ac-b58d-264097f6b319";
+};
+export declare function getInstalledAppIds(assembly: AssemblyAPI): Promise<Set<string>>;
+export declare function isAppInstalled(assembly: AssemblyAPI, appId: string): Promise<boolean>;

package/dist/app-installs.js

@@ -0,0 +1,34 @@
+// Every node-sdk call for install lookups lives in getInstalledAppIds, so the
+// node-sdk namespace migration is a one-line change here and never reaches
+// generated apps.
+/**
+ * @deprecated Built-in modules are being replaced by generated apps, so this
+ * map will be removed. Prefer an appId you resolved from the workspace; use
+ * these only to gate a feature on a module that still ships built in.
+ */
+export const LEGACY_APP_IDS = {
+    messages: '38323633-6465-6132-3730-383065323230',
+    billing: '64346438-6461-6431-6565-366361383434',
+    files: '33343966-3136-6166-6561-343739303432',
+    contracts: '34633033-3365-6561-6332-386434316430',
+    forms: '66666663-3861-6633-3830-323337613065',
+    helpdesk: '30643961-3563-3361-3035-396231663435',
+    tasks: '0e1dff29-1ce3-40ac-b58d-264097f6b319',
+};
+// A disabled install is dropped: it is present in the list but its surfaces and
+// API behave as if the app were not there.
+export async function getInstalledAppIds(assembly) {
+    try {
+        const installs = await assembly.listAppInstalls({});
+        return new Set(installs.filter((i) => !i.disabled && i.appId).map((i) => i.appId));
+    }
+    catch (err) {
+        // Fails closed so a lookup error renders the "not installed" state instead
+        // of throwing into the page.
+        console.error('getInstalledAppIds: listAppInstalls failed', err);
+        return new Set();
+    }
+}
+export async function isAppInstalled(assembly, appId) {
+    return (await getInstalledAppIds(assembly)).has(appId);
+}

package/dist/server.d.ts

@@ -3,6 +3,7 @@ export * from './assembly.js';
 export * from './action-route.js';
 export * from './auth.js';
 export * from './client-access.js';
+export * from './app-installs.js';
 export * from './mint-bearer.js';
 export * from './verify-bearer.js';
 export * from './nango.js';

package/dist/server.js

@@ -7,6 +7,7 @@ export * from './assembly.js';
 export * from './action-route.js';
 export * from './auth.js';
 export * from './client-access.js';
+export * from './app-installs.js';
 export * from './mint-bearer.js';
 export * from './verify-bearer.js';
 export * from './nango.js';

package/package.json

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

package/skills/assembly-native-resources/SKILL.md

@@ -9,6 +9,10 @@ description: Use any time the app references a native Assembly message channel,
 
 Discover instead. The pattern is always the same two steps: **list, then match on a stable attribute** the workspace owner controls (a title, a name), or resolve the resource from the current request's identity. Never a literal.
 
+## Check the app is installed first
+
+Gate any feature that depends on another app with `isAppInstalled(assembly, <appId>)` from `@assembly-js/app-foundation/server`, and show an honest "<app> isn't installed in this workspace" state when it is false. It works the same for core, marketplace and custom apps.
+
 ## Discovering a form
 
 A form's display name is on `fields`, not on the form itself. Walk every page — matching by name against only the first page reports the form as missing once the workspace has more than a page of forms:
@@ -31,6 +35,8 @@ await assembly.requestFormResponse({
 });
 ```
 
+**Testing a form request:** never ask the user to send one to a real client. Suggest a throwaway test client, and say before the first test that a request can't be undone from the app — it can only be removed in the dashboard.
+
 There is **no** method for a custom app to submit answers to a native form — you can request a response from a client and read `listFormResponses`, nothing more. Build your own form (see `assembly-forms`) if the app needs to collect the answers itself.
 
 ## Discovering a message channel