@assembly-js/app-foundation 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -19,6 +19,10 @@ 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.
 

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.2",
+  "version": "0.3.3",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

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.