@assembly-js/app-foundation 0.0.35 → 0.0.36

package/CLAUDE.md

@@ -198,6 +198,8 @@ Relationships:
 
 **Listing companies for users.** `listCompanies` excludes **placeholder** companies (nameless solo-client stand-ins) by default for app-builder apps, so company dropdowns, tables, and filters won't show blank "ghost" rows — you don't need to filter them yourself. To *include* placeholders (e.g. to surface solo clients), pass `listCompanies({ isPlaceholder: true })` explicitly. See `assembly-companies` skill.
 
+**App isolation.** `listAppInstalls`/`retrieveAppInstall` tell you which apps are installed (id, appId, type, icon, and other install metadata), and `listAppConnections`/`createAppConnection` manage manual embed and link connections between installed apps — that's real, supported SDK surface, and requests to inspect an install or set up one of those connections are not out of bounds. None of it reaches another app's own data, though: you have no access to another installed app's database, tables, or any other internal data, and there is no SDK call that reads or writes another app's data store. If a request needs another app's private data, say only that it isn't possible and stop — no alternatives and no follow-up question. In user-facing chat, call them apps, not custom apps. Do not propose a bridge: no endpoint or API on the other app, no webhook, push, or sync, and nothing the user has to paste between chats. Do not volunteer automations, clients, companies, custom fields, or an Assembly module as a substitute. If the user explicitly asks to call an existing registered API exposed by another app, that is supported API access rather than database access; never suggest it unprompted. Likewise, if the request itself explicitly asks for automations, CRM data, or an installed module's supported data (for example invoices), that is a separate supported request. Never reach another app's database directly.
+
 ---
 
 ## Iframe constraints — read before writing UI
@@ -1179,6 +1181,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't hardcode mutation error messages like "Failed to save preference". Read `error` from the response body and surface it to the user.
 - ❌ Don't `throw new Error` with a sentence the user should read from a server action. Production redacts that throw, so the toast shows a generic React error and the response is HTTP 500. Return `{ ok: false, message }` and toast `message`. Let `TokenInvalidError` and unexpected failures throw. See `assembly-action-results`.
 - ❌ Don't `Promise.all` a list-sized write fan-out (one `createNotification` / `markNotificationRead` / update per recipient or record). Writes cap at 5 concurrent per token; firing a whole list 429s and silently drops the overflow. Use `sendThrottled` from `@assembly-js/app-foundation/server`. A fixed handful of calls is the only exception. See "Write rate limit" above.
+- ❌ Don't re-notify a still-true condition from a cron. Record the alert on the subject before the send and clear it when the condition ends. See "Recurring conditions" in `assembly-notifications`.
 - ❌ Don't use title case — see "Labels, copy, and dropdowns" above.
 - ❌ Don't render raw IDs or pass a raw ID string as `value` on `ComboboxItem` — see "Select and Combobox — base-ui differences" above.
 - ❌ Don't write a scalar string to a custom field that has options. **All option-bearing custom fields are `multiSelect` in Assembly's schema** — even ones that LOOK like single-select dropdowns. The value must always be an array of option keys: `{ favorite_pizza: ['pepperoni'] }`, never `{ favorite_pizza: 'pepperoni' }`. A scalar string for a multiSelect causes a 400 with `invalid custom field option <value> provided`.

package/bin/validate-manifest.mjs

@@ -18,8 +18,11 @@ const MAX_NOTIFICATION_SETTINGS = 50;
 // Setting ids are permanent: they key each internal user's saved toggles and
 // are passed as notificationSettingId on createNotification, so the validator
 // requires stable author-chosen ids instead of letting the platform generate
-// ones that would rotate on every deploy.
-const KEBAB_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+// ones that would rotate on every deploy. Hyphens and underscores are both
+// stable (a UUID is hyphenated and already matches). Rejecting underscores
+// failed the build when the user or the plan named a category that way
+// (past_due). This check does not rewrite ids already saved on the app.
+const NOTIFICATION_SETTING_ID = /^[a-z0-9]+([_-][a-z0-9]+)*$/;
 
 function fail(lines) {
   console.error('');
@@ -166,10 +169,11 @@ if (doc.notificationSettings !== undefined) {
           errors.push(at + ' must be an object with "id", "label", and "surfaces".');
           return;
         }
-        if (typeof setting.id !== 'string' || !KEBAB_ID.test(setting.id)) {
+        if (typeof setting.id !== 'string' || !NOTIFICATION_SETTING_ID.test(setting.id)) {
           errors.push(
             at +
-              '.id is required and must be kebab-case (e.g. "task-completed"). Ids are permanent — ' +
+              '.id is required and must be lowercase letters, digits, hyphens, or underscores ' +
+              '(e.g. "task-completed" or "past_due"). Ids are permanent — ' +
               "they key each internal user's saved toggles and are passed as notificationSettingId " +
               'when creating notifications.',
           );

package/dist/replace-rows.d.ts

@@ -0,0 +1,27 @@
+type BatchDb = {
+    batch(queries: never): Promise<unknown>;
+};
+export type ReplaceChildRowsResult = {
+    ok: true;
+    ids: string[];
+} | {
+    ok: false;
+    message: string;
+};
+type ReplaceChildRowsSpec<TRow extends {
+    id?: string;
+}, TDelete extends PromiseLike<unknown>, TUpsert extends PromiseLike<unknown>> = {
+    rows: readonly TRow[];
+    removeAll: () => TDelete;
+    removeMissing: (keepIds: readonly string[]) => TDelete;
+    upsert: (row: TRow & {
+        id: string;
+    }) => TUpsert;
+    readIds: () => Promise<ReadonlyArray<{
+        id: string;
+    }>>;
+};
+export declare function replaceChildRows<TRow extends {
+    id?: string;
+}, TDelete extends PromiseLike<unknown>, TUpsert extends PromiseLike<unknown>>(db: BatchDb, spec: ReplaceChildRowsSpec<TRow, TDelete, TUpsert>): Promise<ReplaceChildRowsResult>;
+export {};

package/dist/replace-rows.js

@@ -0,0 +1,51 @@
+// Replacing a parent's child rows is where generated apps drop data. The failure
+// that shows up once a parent already has children: insert the new rows, then
+// delete every id that was not in a keep-list built only from rows that already
+// had ids. The insert's id was never on that list, so the same batch deletes it.
+//
+// The neon-http batch method is generic over a one-or-more tuple. Putting that
+// tuple on this parameter makes a real `db` fail to assign, which pushes the
+// cast out to every call site. A function that accepts a specific tuple is
+// assignable to one that accepts `never`, so the cast stays here.
+const childRowsMismatchMessage = 'Save did not keep every row';
+function rowId(row) {
+    if (typeof row.id === 'string' && row.id !== '') {
+        return row;
+    }
+    return { ...row, id: crypto.randomUUID() };
+}
+function sameIds(expected, actual) {
+    const want = new Set(expected);
+    const got = new Set(actual);
+    if (want.size !== got.size)
+        return false;
+    for (const id of want) {
+        if (!got.has(id))
+            return false;
+    }
+    return true;
+}
+async function runStatements(db, statements) {
+    const [first, ...rest] = statements;
+    // One statement is the empty-payload delete. neon-http batch wants two or more.
+    if (rest.length === 0) {
+        await first;
+        return;
+    }
+    const batch = db.batch;
+    await batch([first, ...rest]);
+}
+export async function replaceChildRows(db, spec) {
+    // Ids exist before the delete is built, so a row added in this save is on the keep-list.
+    const written = spec.rows.map(rowId);
+    const statements = written.length === 0
+        ? [spec.removeAll()]
+        : [spec.removeMissing(written.map((row) => row.id)), ...written.map((row) => spec.upsert(row))];
+    await runStatements(db, statements);
+    const found = await spec.readIds();
+    const ids = written.map((row) => row.id);
+    if (!sameIds(ids, found.map((row) => row.id))) {
+        return { ok: false, message: childRowsMismatchMessage };
+    }
+    return { ok: true, ids };
+}

package/dist/server.d.ts

@@ -10,6 +10,7 @@ export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';
 export * from './cron.js';
+export * from './replace-rows.js';
 export * from './api-errors.js';
 export * from './params.js';
 export * from './client.js';

package/dist/server.js

@@ -14,6 +14,7 @@ export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';
 export * from './cron.js';
+export * from './replace-rows.js';
 // Returns NextResponse, so route handlers only — but nothing here reads a
 // secret, which is why a client file may still `import type` from them.
 export * from './api-errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.35",
+  "version": "0.0.36",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -30,7 +30,7 @@
   },
   "scripts": {
     "build": "tsc && tsc-alias",
-    "test": "bun test",
+    "test": "bun test && tsc -p tsconfig.replace-rows.json",
     "prepublishOnly": "npm run build && npm run verify:dist && npm run verify:bin",
     "verify:dist": "node scripts/verify-dist-resolves.mjs",
     "verify:bin": "node scripts/verify-bin.mjs"
@@ -44,8 +44,10 @@
   "devDependencies": {
     "@assembly-js/app-bridge": "1.3.0",
     "@assembly-js/node-sdk": "4.2.4",
+    "@neondatabase/serverless": "^1.1.0",
     "@types/bun": "^1.1.0",
     "@types/node": "^22",
+    "drizzle-orm": "^0.45.2",
     "next": "^15.5.0",
     "server-only": "^0.0.1",
     "tsc-alias": "^1.9.1",

package/skills/assembly-notifications/SKILL.md

@@ -334,6 +334,24 @@ await markSubmissionNotified(submission.id);
 
 Option 2 is cheaper (no list call) and more reliable. Pick option 1 when you don't control the trigger schema.
 
+### Recurring conditions
+
+A cron that scans for a condition still being true — unassigned for a day, overdue, no reply — selects the same rows on every tick. `createNotification` does not remember a previous send, so each tick creates another copy for every recipient. `sendThrottled` only spaces that flood out; it does not stop it.
+
+Record the alert on the subject, in the app's own table, before sending. Key it by the subject and the condition (one thread, one kind), not by the recipient. Skip the send when that marker is set. Clear the marker when the condition ends (the thread is assigned, a reply arrives) so a later recurrence can alert again.
+
+```ts
+// Unique on (threadId, kind). Write the marker first so a tick that dies
+// mid-send skips the rest next time instead of notifying everyone again.
+if (await alreadyAlerted(thread.id, 'stale-unassigned')) continue;
+await markAlerted(thread.id, 'stale-unassigned');
+await sendThrottled(recipients, (u) =>
+  assembly.createNotification({ requestBody: { recipientInternalUserId: u.id, /* ... */ } }),
+);
+```
+
+Do not use `listNotifications` to decide. A sweep will not page the whole center, and a notification the recipient already read still has to count.
+
 ## Clearing the client portal badge
 
 Because clients see a badge counter rather than a Notification Center, every `createNotification({ recipientClientId })` is only half the job — the app must `markNotificationRead` at the right moment or the badge sticks forever. Leaving it unhandled is the most common bug in client-facing apps. There are two patterns:
@@ -443,6 +461,7 @@ Each client gets their own badge and clears it independently. `recipientCompanyI
 ## What NOT to do
 
 - Do not `Promise.all` a recipient-list fan-out. Writes cap at 5 concurrent; firing a whole list at once 429s and drops notifications. Use `sendThrottled` (see "Throttling fan-outs"). A fixed handful of calls is the only exception.
+- Do not re-send a cron alert because the same condition is still true. Record it on the subject before the send and clear that record when the condition ends (see "Recurring conditions").
 - Do not use `recipientId` — deprecated. Use `recipientClientId` or `recipientInternalUserId`.
 - Do not pass `recipientCompanyId` alone as a recipient. The API rejects it. To notify a company, fan out across its clients (see "Notifying a company").
 - Do not omit the company id when a multi-company client is involved. Notifying a multi-company client needs `recipientCompanyId` (`400 "company ID is required when notifying a client"`); a multi-company client *sending* to an internal user needs `senderCompanyId` (`400 "sender company ID is invalid based on sender"`). Single-company members are auto-inferred. See "Company scoping, by recipient type."

package/skills/assembly-record-writes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-record-writes
-description: REQUIRED when a form creates a persisted record that a later save or update also writes, especially when the payload includes nested rows (packages, add-ons, line items, blocks, children). Create and save must call one writer so create cannot drop fields the form submitted. A success toast after create does not mean those rows were stored.
+description: REQUIRED when a form creates a persisted record that a later save or update also writes, or when a save replaces nested rows (packages, add-ons, line items, blocks, children). Create and save must call one writer so create cannot drop fields the form submitted. Replacing those rows deletes missing ids before the upsert and reads them back before success. A success toast does not mean the rows were stored.
 ---
 
 A create form often submits the same payload a later edit form saves: parent columns plus nested collections. If create inserts only the parent (and maybe one child table and an audit event) while save writes the rest, the first submit looks successful and the editor opens empty. The redirect after create does not call save.
@@ -9,31 +9,66 @@ A create form often submits the same payload a later edit form saves: parent col
 
 One function writes the submitted payload. Create calls it for a new id; save calls it for an existing id.
 
+Leave these off the shared payload. They belong to the path that owns them:
+
+- ids, timestamps, a draft status, an audit-event row
+- a control flag that chooses an action (for example "send immediately") and is not itself stored, unless save stores that same flag
+- fields that appear only on a later edit form
+
+If the form submits it, the create call chain writes it, including by calling the shared writer.
+
+## Replacing child rows
+
+Import `replaceChildRows` from `@assembly-js/app-foundation/server`. Do not reimplement it. Inserting new rows and then deleting every id missing from a keep-list of only the rows that already had ids deletes the rows just inserted. That only shows up once the parent already has children, so the first save looks fine.
+
+When the user adds a row, assign `crypto.randomUUID()` on the client before submit. The helper also assigns any id that arrives empty, before it builds the delete, so a missing id cannot fall off the keep-list.
+
+Call the helper only for a collection the form submitted (`input.packages !== undefined`). An omitted collection stays as it is. An empty array means the user cleared that collection: every child of that parent is deleted. The helper uses a delete-all for that case and does not emit `id NOT IN ()`.
+
+Upsert the parent by id first. A save does not delete and recreate the parent. Then one `replaceChildRows` per submitted collection. The helper deletes missing ids before the upserts, in one `db.batch` when there is more than one statement. Do not use `db.transaction` (see `assembly-db-transactions`). On conflict, update a child only when it already belongs to this parent, so a submitted id from another record cannot change that record.
+
+If the result is `{ ok: false, message }`, return that from the server action. The message is `Save did not keep every row`. Do not toast success. The check compares ids only.
+
 ```ts
+import { replaceChildRows } from '@assembly-js/app-foundation/server';
+import { and, eq, notInArray } from 'drizzle-orm';
+import { db } from '@/lib/db';
+import { packages, proposals } from '@/lib/schema';
+
 async function writeProposal(id: string, input: ProposalInput) {
   await db.insert(proposals).values({ id, title: input.title, intro: input.intro })
     .onConflictDoUpdate({ target: proposals.id, set: { title: input.title, intro: input.intro } });
-  await replaceRows(packages, id, input.packages);
-  await replaceRows(addOns, id, input.addOns);
-  await replaceRows(blocks, id, input.blocks);
+
+  if (input.packages !== undefined) {
+    const replaced = await replaceChildRows(db, {
+      rows: input.packages,
+      removeAll: () => db.delete(packages).where(eq(packages.proposalId, id)),
+      removeMissing: (keepIds) =>
+        db.delete(packages).where(and(eq(packages.proposalId, id), notInArray(packages.id, [...keepIds]))),
+      upsert: (row) =>
+        db.insert(packages).values({ id: row.id, proposalId: id, name: row.name })
+          .onConflictDoUpdate({
+            target: packages.id,
+            set: { name: row.name },
+            where: eq(packages.proposalId, id),
+          }),
+      readIds: () => db.select({ id: packages.id }).from(packages).where(eq(packages.proposalId, id)),
+    });
+    if (!replaced.ok) return replaced;
+  }
 }
 
 export async function createProposal(input: ProposalInput) {
   const id = crypto.randomUUID();
-  await writeProposal(id, input);
+  const written = await writeProposal(id, input);
+  if (written) return written;
   await recordEvent(id, 'draft_created');
-  return id;
+  return { ok: true, id };
 }
 
 export async function saveProposal(id: string, input: ProposalInput) {
-  await writeProposal(id, input);
+  const written = await writeProposal(id, input);
+  if (written) return written;
+  return { ok: true };
 }
 ```
-
-Leave these off the shared payload. They belong to the path that owns them:
-
-- ids, timestamps, a draft status, an audit-event row
-- a control flag that chooses an action (for example "send immediately") and is not itself stored, unless save stores that same flag
-- fields that appear only on a later edit form
-
-If the form submits it, the create call chain writes it, including by calling the shared writer.

package/skills/assembly-scheduled-work/SKILL.md

@@ -144,6 +144,7 @@ Rules that fall out of this:
 
 - **`cronRoute` is not optional.** The route is a public URL; without the wrapper anyone who guesses it can trigger the app's scheduled work under the app's own credentials. Never hand-roll the header check.
 - **Use `getOfflineAssembly()`** for every platform call — there is no viewer and no cookie. `getSessionIdentity()` is `null` here, so a notification's `senderId` must be chosen explicitly (a system/admin internal user); see `assembly-notifications`.
+- **A scan that notifies must remember what it already sent.** Selecting every row that still matches (unassigned, overdue, unanswered) and calling `createNotification` notifies that same set again on the next tick. Record the alert on the subject before the send and clear it when the condition ends. See `assembly-notifications` ("Recurring conditions").
 - **A missed tick is harmless.** Vercel does not retry, but the row stays due until it is marked, so the next tick picks it up. Never mark a row done before its work succeeded.
 - **A stuck row frees itself.** If Vercel stops the function mid-run, the catch never runs and the row stays `running`; the stale-claim clause lets the next tick reclaim it after 15 minutes. Keep `claimedAt` and that clause — without them one hang parks a row forever.
 - **Never compute the next run by adding minutes to `now`.** Use `nextRunAfter`: it anchors to the scheduled time, skips missed occurrences, and keeps daily cadences on their local wall-clock time across daylight-saving changes.
@@ -174,4 +175,5 @@ Insert a row with `nextRunAt` in the past, run that, and confirm the side effect
 - ❌ Don't skip `cronRoute` or compare the header yourself.
 - ❌ Don't type, invent, or default `CRON_SECRET`. Declare it; the platform mints it.
 - ❌ Don't call `getAssembly()` in the dispatcher. There is no viewer; use `getOfflineAssembly()`.
+- ❌ Don't notify from a sweep without a per-subject marker. The next tick selects the same rows and sends again.
 - ❌ Don't replace `vercel.json`. Add `crons` to it.