@assembly-js/app-foundation 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -19,6 +19,13 @@ 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.3.3
+- [new] `notifyInternalUsers` (from `@assembly-js/app-foundation/server`) notifies every internal user, or a given `recipientIds` list, on behalf of the current viewer using the installer client.
+- [guidance] The notifications skill now directs every client-triggered send to staff through `notifyInternalUsers`, since a client's own `getAssembly()` client cannot create notifications or list staff.
+
+## 0.3.2
+- [new] The `assembly-api-contract` skill teaches the build agent to write and maintain `.assembly/openapi.json` alongside `app/api` routes.
+
 ## 0.3.1
 - [guidance] The build agent now upgrades an app's bridge to 2.1.0 and its foundation package instead of skipping a deep link, mounts the location reporter, and deep-links notifications to the specific record.
 - [new] App destinations in `NavigateDestination` now accept an optional `path` for links to an app's inner page.

package/CLAUDE.md

@@ -68,6 +68,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-route-auth` — REQUIRED on every `app/api/.../[id]/route.ts` handler: `requireAuth` + `requireCompanyScope` before returning or mutating data.
 - `assembly-scheduled-work` — REQUIRED when the prompt implies anything on a schedule or while nobody has the app open (remind, daily digest, every week, follow up in N days, at a specific time): one `*/30 * * * *` Vercel cron in `vercel.json` hitting one dispatcher route, every scheduled action a row in a schedule table, `CRON_SECRET` declared in `requiredSecrets` and verified on every tick, `getOfflineAssembly()` for platform calls. Checking for due work on page load ships a schedule that never fires.
 - `assembly-route-errors` — REQUIRED in every route handler: use `handleRouteError` from `@assembly-js/app-foundation/server` in catch blocks — never return `err.message`. Validate values before they hit typed DB columns (e.g. `parseUuid` before a uuid-column lookup).
+- `assembly-api-contract` — REQUIRED whenever an `app/api` route is added, removed, or changes its request or response shape: keep `.assembly/openapi.json` (OpenAPI 3.1, `servers: [{"url": "/api"}]`, paths without the `/api` prefix) in step; cron, webhook, `assembly-*` and `privateRoutes` routes stay out.
 - `assembly-action-results` — REQUIRED when a server action refuses work the UI should explain (validation, permission, not ready to send): return `{ ok: false, message }` instead of throwing. A thrown message is redacted in production.
 - `assembly-dev-server-logs` — the dev server's stdout/stderr (server-side errors, stack traces, console output) is readable at `/tmp/dev-server.log`; check it before guessing at a 500 or broken preview.
 - Your own preview is `localhost:3000`; never fetch the public `sb-*.vercel.run` host from inside the sandbox (egress to it is blocked).

package/bin/foundation-exports.mjs

@@ -29,7 +29,7 @@ export const NON_CLIENT_EXPORTS = new Set([
   'FormatAirtableRecordsOpts', 'GenerateAppClientInput', 'GeneratedAppClient', 'GmailSendArgs', 'GmailSendResult', 'IntegrationClient',
   'InternalUserAccess', 'LEGACY_APP_IDS', 'LocationReporter', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
   'MintedBearer', 'NETWORK_CAPTURE_MESSAGE_TYPE', 'NetworkCaptureHeaderFingerprint',
-  'NetworkCaptureRecord', 'PAINTED_BEACON_EVENT', 'PAINTED_BEACON_PATH',
+  'NetworkCaptureRecord', 'NotifyInternalUsersInput', 'PAINTED_BEACON_EVENT', 'PAINTED_BEACON_PATH',
   'PORTAL_ORIGIN_COOKIE_NAME', 'PdfText', 'PrincipalAllow', 'PrincipalKind',
   'Provider', 'ProxyOpts', 'RENEW_OUTCOME_EVENT', 'RenewOutcome', 'ReplaceChildRowsResult',
   'RequestSource', 'ResolveResourceOpts', 'ResourceError', 'ResourceFieldMap',
@@ -52,7 +52,7 @@ export const NON_CLIENT_EXPORTS = new Set([
   'isDocumentRequest', 'isPaintedBeaconPath', 'isSessionExchangeEnabled', 'isUuid',
   'isValidHexColor', 'listAll', 'logCookieOutcome', 'logFailures', 'logPaintedBeacon',
   'logRenewOutcome', 'makeTestActionContext', 'mintBearerFromAppKey',
-  'mintBearerFromSessionToken', 'nextRunAfter', 'normalizeResourcePage', 'notFound',
+  'mintBearerFromSessionToken', 'nextRunAfter', 'normalizeResourcePage', 'notFound', 'notifyInternalUsers',
   'parseExchangeRejection', 'parseUuid', 'principalKind', 'readCookie', 'recordNetworkCapture',
   'redactUrl', 'replaceChildRows', 'requireAuth', 'requireCompanyScope', 'resolveFont',
   'resolveResource', 'sendThrottled', 'serializeBearerCookie', 'serializeCookieProbe',

package/dist/notifications.d.ts

@@ -44,4 +44,67 @@ export declare function clearClientNotifications({ assembly, clientId, ctaParams
     cleared: number;
     failed: number;
 }>;
+interface InternalUserRecord {
+    id: string;
+}
+interface InstallerNotificationsClient {
+    listInternalUsers(args: {
+        nextToken?: string;
+        limit?: number;
+    }): Promise<{
+        data?: InternalUserRecord[] | null;
+        nextToken?: string;
+    }>;
+    createNotification(args: {
+        requestBody: {
+            senderId: string;
+            senderCompanyId?: string;
+            recipientInternalUserId: string;
+            notificationSettingId?: string;
+            deliveryTargets: {
+                inProduct: {
+                    title: string;
+                    body: string;
+                    ctaParams: Record<string, string>;
+                };
+                email?: Record<string, unknown>;
+            };
+        };
+    }): Promise<unknown>;
+}
+interface NotifyInternalUsersDeps {
+    getAssembly: () => Promise<unknown>;
+    getInstallerAssembly: () => Promise<InstallerNotificationsClient>;
+    getIdentity: () => Promise<{
+        clientId?: string;
+        internalUserId?: string;
+        companyId?: string;
+    } | null>;
+}
+export interface NotifyInternalUsersInput {
+    title: string;
+    body: string;
+    /** Becomes the notification's inProduct ctaParams (the `/n` surface renders from these). */
+    ctaParams: Record<string, string>;
+    /** Email delivery target (subject, header, htmlBody, title); omit for in-product only. */
+    email?: Record<string, unknown>;
+    /** Per-user toggleable category declared in the manifest `notificationSettings`. */
+    notificationSettingId?: string;
+    /** Notify only these internal users; omit to notify every internal user. Limited-access staff are not filtered out: pass recipientIds when the audience must respect Client Access. */
+    recipientIds?: string[];
+}
+/**
+ * Notifies internal users on behalf of the current viewer — the only way a
+ * client-triggered event can reach staff, since a client's own getAssembly()
+ * client can neither create notifications for them nor list them. The send and
+ * the staff list use the installer client; the viewer's client is never touched.
+ *
+ * Throws only when there is no verified viewer (an auth gate, not a send
+ * failure). List and send failures never throw: the caller's data write already
+ * committed, so they are logged and returned as counts.
+ */
+export declare function notifyInternalUsers({ title, body, ctaParams, email, notificationSettingId, recipientIds }: NotifyInternalUsersInput, deps?: NotifyInternalUsersDeps): Promise<{
+    sent: number;
+    failed: number;
+}>;
 export {};

package/dist/notifications.js

@@ -2,6 +2,9 @@
 // (lib/notify.ts): a 429-aware fan-out throttle and the client badge-clear
 // pattern. They live in the package so the behavior is a deterministic import,
 // not prose the build agent re-implements (and sometimes gets wrong) each time.
+import { getAssembly, getInstallerAssembly, getSessionIdentity } from './assembly.js';
+import { getInstallerAssemblyForCaller } from './installer-caller.js';
+import { listAll } from './pagination.js';
 // Platform writes are capped at 5 concurrent per token; 3 leaves headroom for
 // the app's own unrelated in-flight writes.
 const CONCURRENCY = 3;
@@ -81,3 +84,57 @@ export async function clearClientNotifications({ assembly, clientId, ctaParams,
         return { cleared: 0, failed: 0 };
     }
 }
+const defaultNotifyDeps = {
+    getAssembly,
+    getInstallerAssembly: getInstallerAssembly,
+    getIdentity: getSessionIdentity,
+};
+/**
+ * Notifies internal users on behalf of the current viewer — the only way a
+ * client-triggered event can reach staff, since a client's own getAssembly()
+ * client can neither create notifications for them nor list them. The send and
+ * the staff list use the installer client; the viewer's client is never touched.
+ *
+ * Throws only when there is no verified viewer (an auth gate, not a send
+ * failure). List and send failures never throw: the caller's data write already
+ * committed, so they are logged and returned as counts.
+ */
+export async function notifyInternalUsers({ title, body, ctaParams, email, notificationSettingId, recipientIds }, deps = defaultNotifyDeps) {
+    // The auth gate: a missing viewer must surface, unlike the failures below.
+    await deps.getAssembly();
+    let installer;
+    try {
+        installer = (await getInstallerAssemblyForCaller(deps));
+    }
+    catch (err) {
+        console.error('notifyInternalUsers could not get the installer client', err);
+        return { sent: 0, failed: 0 };
+    }
+    const identity = await deps.getIdentity();
+    const senderId = identity?.clientId ?? identity?.internalUserId;
+    if (!senderId)
+        throw new Error('notifyInternalUsers requires a verified viewer');
+    let recipients;
+    try {
+        recipients =
+            recipientIds ??
+                (await listAll((nextToken) => installer.listInternalUsers({ nextToken, limit: 100 }))).map((u) => u.id);
+    }
+    catch (err) {
+        console.error('notifyInternalUsers could not list internal users', err);
+        return { sent: 0, failed: 0 };
+    }
+    const results = await sendThrottled(recipients, (recipientInternalUserId) => installer.createNotification({
+        requestBody: {
+            senderId,
+            // A multi-company client must name the company it acts under, or the platform rejects the send.
+            senderCompanyId: identity?.companyId,
+            recipientInternalUserId,
+            notificationSettingId,
+            deliveryTargets: { inProduct: { title, body, ctaParams }, ...(email && { email }) },
+        },
+    }));
+    logFailures(results, 'internal user notifications');
+    const failed = results.filter((r) => r.status === 'rejected').length;
+    return { sent: results.length - failed, failed };
+}

package/package.json

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

package/skills/assembly-api-contract/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: assembly-api-contract
+description: REQUIRED whenever you add, remove, or change the request or response shape of a route under app/api. Write and maintain .assembly/openapi.json, the app's OpenAPI 3.1 API contract — one operation per callable (method, path) with JSON Schema bodies; servers /api and paths without the /api prefix. Skip cron, webhook, assembly-* and privateRoutes routes.
+---
+
+Keep `.assembly/openapi.json` in step with `app/api` in the same turn as the route change. It is the document other apps and tools read to learn what this app's API accepts and returns.
+
+## When to touch it
+
+- Route added: add an operation for each exported GET, POST, PUT, PATCH or DELETE handler; never document head or options, which are not proxied.
+- Route removed, or a method removed from it: delete that operation (and the path entry once it has no operations).
+- Request body, query parameter, or response field changed: update the schemas to match.
+
+## Format
+
+- OpenAPI `3.1.0`, JSON, at `.assembly/openapi.json`. Bodies are JSON Schema.
+- Identity of an operation is `(method, path template)`. `operationId` is a label only; renaming it changes nothing.
+- `servers` is `[{ "url": "/api" }]` and `paths` are written **without** the `/api` prefix, exactly as the route scanner templates them (`app/api/projects/[projectId]/tasks/route.ts` becomes `/projects/{projectId}/tasks`). Path parameters are `{name}` using the folder's bracket name.
+- The stored document is capped at 1 MB and publishing refuses a larger one. Keep it small: describe fields, do not paste sample data.
+
+## What stays out
+
+A route is not callable by other apps, so it must not appear, when it is:
+
+- under a `cron`, `webhook` or `webhooks` segment, or a segment starting `assembly-`
+- wrapped in `cronRoute` or `automationActionRoute`
+- matched by a glob in `privateRoutes` in `.assembly/app.json` (matched against the route template, not the file path). The scanner records these as excluded, so documenting one is reported as a drift.
+
+## Worked example
+
+`app/api/projects/[projectId]/tasks/route.ts` exports `GET` (list) and `POST` (create):
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": { "title": "Project tasks", "version": "1.0.0" },
+  "servers": [{ "url": "/api" }],
+  "paths": {
+    "/projects/{projectId}/tasks": {
+      "get": {
+        "operationId": "listProjectTasks",
+        "summary": "List the tasks of a project",
+        "parameters": [
+          { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
+        ],
+        "responses": {
+          "200": {
+            "description": "The project's tasks",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["tasks"],
+                  "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } }
+                }
+              }
+            }
+          },
+          "404": { "$ref": "#/components/responses/Error" }
+        }
+      },
+      "post": {
+        "operationId": "createProjectTask",
+        "summary": "Create a task in a project",
+        "parameters": [
+          { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["title"],
+                "properties": { "title": { "type": "string", "minLength": 1 }, "dueDate": { "type": ["string", "null"], "format": "date" } }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": { "description": "The created task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } },
+          "400": { "$ref": "#/components/responses/Error" }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Task": {
+        "type": "object",
+        "required": ["id", "title", "done"],
+        "properties": {
+          "id": { "type": "string", "format": "uuid" },
+          "title": { "type": "string" },
+          "done": { "type": "boolean" },
+          "dueDate": { "type": ["string", "null"], "format": "date" }
+        }
+      }
+    },
+    "responses": {
+      "Error": {
+        "description": "Error",
+        "content": {
+          "application/json": {
+            "schema": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Document the error shape your handlers really return (see `assembly-route-errors`: `{ error }`).
+
+## Drift
+
+The platform may compare the contract with the scanned routes after a turn and report disagreements. Fix each kind at its source:
+
+- Documented operation with no route in code: remove the operation, or restore the route if it was deleted by mistake. A method the file does not export counts as missing.
+- Route in code with no operation: add the operation, unless the route is one of the excluded kinds above.
+- Same path under a different parameter name (`{id}` in the contract, `[taskId]` in the folder): Next allows one name per dynamic segment, so rename the contract's parameter to the folder's.
+- Shape mismatch (a response field renamed, a body field now required): update the schemas to what the handler returns and accepts.

package/skills/assembly-notifications/SKILL.md

@@ -95,6 +95,8 @@ Detect the notification surface by the route itself — code under `app/n/` IS t
 
 ## Creating a notification
 
+This is the **staff-triggered** pattern: the viewer's own client sends. When a client triggers a notification to staff, use `notifyInternalUsers` instead (see "Client-triggered sends to staff").
+
 ```ts
 const assembly = await getAssembly();
 const id = await getSessionIdentity();
@@ -159,6 +161,24 @@ export async function GET() {
 
 Send a fragment, not a document, and don't attempt layout or branding: every tag outside that list — `div`, `table`, headings, `img`, `class`, inline styles, `script` — is stripped server-side with no error, leaving its text run together unformatted, and the platform's email template supplies the frame. The plain-text alternative is derived from `htmlBody` automatically; pass `body` alongside it only to write that text yourself.
 
+### Client-triggered sends to staff
+
+A client's own `getAssembly()` client **cannot create notifications or list internal users** — those calls fail for a client viewer. Every send to staff that a client triggers (a submission, a decision, a message) goes through `notifyInternalUsers`, which checks the viewer is verified, then lists staff and sends with the installer client, using the viewer's `clientId` and `companyId` as sender:
+
+```ts
+import { notifyInternalUsers } from '@assembly-js/app-foundation/server';
+
+// After the client's write committed. Never throws on send failures; returns counts.
+const { sent, failed } = await notifyInternalUsers({
+  title: 'New submission received',
+  body: 'Jane Doe submitted their brand questionnaire.',
+  ctaParams: { submissionId: submission.id },
+  // email, notificationSettingId and recipientIds (default: every internal user) are optional
+});
+```
+
+Keep `getAssembly()` for notifications a **staff member** triggers — that viewer's client can send them directly.
+
 ### Company scoping, by recipient type
 
 Every notification is scoped to a company, and which field supplies it depends on **who the recipient is** — the part that trips up multi-company clients:
@@ -169,22 +189,19 @@ Every notification is scoped to a company, and which field supplies it depends o
 The field is only *required* when the relevant party belongs to more than one company (single-company members are auto-inferred), but passing the company id when you have it (e.g. `id.companyId` from `getSessionIdentity()`) is always safe.
 
 ```ts
-// Multi-company client (sender) notifying internal staff: senderCompanyId required,
-// recipientCompanyId does NOT apply (recipient is internal).
-const id = await getSessionIdentity();
-await assembly.createNotification({
-  requestBody: {
-    senderId: id?.clientId,
-    senderCompanyId: id?.companyId, // the company the client is acting under
-    recipientInternalUserId: assignedStaffId,
-    deliveryTargets: { inProduct: { title: 'Client approved the proposal', ctaParams: { proposalId: proposal.id } } },
-  },
+// Multi-company client (sender) notifying internal staff: notifyInternalUsers sets senderId and
+// senderCompanyId from the viewer; recipientCompanyId does NOT apply (recipient is internal).
+await notifyInternalUsers({
+  title: 'Client approved the proposal',
+  ctaParams: { proposalId: proposal.id },
+  body: 'The client approved the proposal.',
+  recipientIds: [assignedStaffId],
 });
 ```
 
 To notify multiple recipients (e.g., several internal users), make one `createNotification` call per recipient. See "Apps with multiple notification types" below.
 
-**`listInternalUsers` / `listClients` are paginated** — one call returns only the first page. To notify *everyone*, collect all recipients before fanning out, or you'll silently skip later-page recipients. `listAll` from `@assembly-js/app-foundation/client` does the walk — import it, don't rewrite it:
+**`listInternalUsers` / `listClients` are paginated** — one call returns only the first page. To notify *everyone* from a staff-triggered event, collect all recipients before fanning out, or you'll silently skip later-page recipients (a client-triggered event uses `notifyInternalUsers`, which walks every page itself). `listAll` from `@assembly-js/app-foundation/client` does the walk — import it, don't rewrite it:
 
 ```ts
 import { listAll } from '@assembly-js/app-foundation/client';
@@ -365,17 +382,15 @@ Either way, the clear is one foundation call — `clearClientNotifications({ ass
 
 Each notification type is its own `createNotification` call with its own `ctaParams` shape.
 
-For an event that needs multiple recipients (e.g., a submission notifies the assigned staff member and the requesting client), make one `createNotification` call per recipient. Each call can have different `ctaParams` — internal users typically want a filter scoped to the client; clients want a deep link to their own record. A fixed pair like this stays under the 5-concurrent cap, so a plain `Promise.all` is fine; reach for `sendThrottled` only when the count is driven by a list.
+For an event that needs multiple recipients (e.g., a submission notifies the assigned staff member and the requesting client), send one notification per recipient; when a client triggers it, the staff one goes through `notifyInternalUsers` (the viewer client cannot create it). Each call can have different `ctaParams` — internal users typically want a filter scoped to the client; clients want a deep link to their own record. A fixed pair like this stays under the 5-concurrent cap, so a plain `Promise.all` is fine; reach for `sendThrottled` only when the count is driven by a list.
 
 ```ts
 await Promise.all([
-  assembly.createNotification({ requestBody: {
-    senderId: clientId, recipientInternalUserId: assignedStaffId,
-    deliveryTargets: { inProduct: {
-      title: 'New submission', body: `${clientName} submitted ${formName}.`,
-      ctaParams: { submissionId: submission.id, view: 'review' },
-    } },
-  } }),
+  notifyInternalUsers({
+    title: 'New submission', body: `${clientName} submitted ${formName}.`,
+    ctaParams: { submissionId: submission.id, view: 'review' },
+    recipientIds: [assignedStaffId],
+  }),
   assembly.createNotification({ requestBody: {
     senderId: clientId, recipientClientId: clientId,
     deliveryTargets: { inProduct: {
@@ -388,15 +403,17 @@ await Promise.all([
 
 ### Fanning out to internal users with Client Access
 
-For a client- or company-scoped event whose audience is "all internal users with access," filter yourself — notifying a user about a client they can't access violates the permission model and may leak client info. Users with `isClientAccessLimited: false` see everyone; those with `true` see only clients whose company is in their `companyAccessList`. Every client has a company (real or placeholder), so the company check covers all clients.
+For a client- or company-scoped event whose audience is "all internal users with access," filter yourself, then pass the result to `notifyInternalUsers` as `recipientIds` — notifying a user about a client they can't access violates the permission model and may leak client info. Users with `isClientAccessLimited: false` see everyone; those with `true` see only clients whose company is in their `companyAccessList`. Every client has a company (real or placeholder), so the company check covers all clients.
 
 ```ts
 const { companyIds = [] } = await assembly.retrieveClient({ id: clientId });
 
+// A client viewer cannot list staff, so list with the installer client.
+const installer = await getInstallerAssembly();
 const internalUsers = [];
 let nextToken: string | undefined;
 do {
-  const page = await assembly.listInternalUsers({ nextToken });
+  const page = await installer.listInternalUsers({ nextToken });
   internalUsers.push(...(page.data ?? []));
   nextToken = page.nextToken ?? undefined;
 } while (nextToken);
@@ -409,16 +426,12 @@ const recipients = internalUsers.filter(
 );
 // Add `.filter((u) => u.role === 'admin')` when the plan is admins/staff only.
 
-const results = await sendThrottled(recipients, (u) =>
-  assembly.createNotification({
-    requestBody: {
-      senderId: clientId,
-      recipientInternalUserId: u.id,
-      deliveryTargets: { inProduct: { title: 'New submission', ctaParams: { submissionId: submission.id } } },
-    },
-  }),
-);
-logFailures(results, 'notifications');
+await notifyInternalUsers({
+  title: 'New submission',
+  body: 'A client submitted a new request.',
+  ctaParams: { submissionId: submission.id },
+  recipientIds: recipients.map((u) => u.id),
+});
 ```
 
 A company-scoped event uses `companyId` directly — same filter, same shape. Workspace-wide notifications (tied to no client or company) go to all internal users, no filter.