@assembly-js/app-foundation 0.0.37 → 0.0.38

package/CLAUDE.md

@@ -1197,7 +1197,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 re-notify a still-true condition from a cron. Mark a recipient sent only after `createNotification` succeeds, and clear that record when the condition ends unless the alert is once per billing period; keep those successful outcomes until the period resets, even if usage dips below the threshold. 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/package.json

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

package/skills/assembly-notifications/SKILL.md

@@ -10,7 +10,9 @@ description: Use when the app must notify internal users or clients, or needs pe
 
 ## Mental model
 
-Send a notification when something happens that the recipient should know about and didn't cause themselves — action required (review, approve, respond) or awareness (status changes, completions, new messages). Skip routine reads, navigation, and trivial state changes. Under-send rather than over-send.
+Send a notification when something happens that the recipient should know about — action required (review, approve, respond) or awareness (status changes, completions, new messages). Skip routine reads, navigation, trivial state changes, and routine confirmations of the recipient's own actions.
+
+For a required condition alert (a retainer reaching 90%, going over its allowance, or a budget crossing its limit), the audience is everyone specified by the requirement who has access, including the user whose action crossed the threshold. A sole admin logging usage must still receive the staff alert. Choose recipients by access; use the actor as sender without automatically removing them from the audience.
 
 Every notification is three decisions: **audience** (internal users and/or clients), **channel** (in-product, email, or both), and **context on arrival** (what the recipient sees and can do). Get those right; the rest is mechanics.
 
@@ -338,17 +340,11 @@ Option 2 is cheaper (no list call) and more reliable. Pick option 1 when you don
 
 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.
+Track each condition occurrence in the app's own table, keyed by subject and condition (include the billing period for a recurring allowance). Resolve the eligible audience before claiming the occurrence: an empty audience creates no sent marker.
 
-```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, /* ... */ } }),
-);
-```
+A concurrency claim reserves work; it is not proof of delivery. Keep pending claims retryable after a failure or an expired lease, and mark a recipient sent only after their `createNotification` succeeds. On partial failure, retry the failed recipients and skip those already sent. If there is only one recipient, track that outcome on the occurrence itself. Clear the occurrence when the condition ends if recurrence should alert again. For once-per-period threshold alerts, keep successful outcomes through dips below the threshold and use a new occurrence when the period resets.
+
+A permanent marker written before fan-out can consume an alert without sending anything. Marking the whole occurrence sent after `sendThrottled` is also insufficient: it returns per-recipient outcomes, so check failures before declaring delivery complete.
 
 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.
 
@@ -461,7 +457,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 re-send a condition alert to recipients already notified for that occurrence. Keep failed sends retryable and track successful outcomes (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-scheduled-work/SKILL.md

@@ -144,7 +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 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. Mark a recipient sent only after `createNotification` succeeds, and clear that record when the condition ends unless the alert is once per billing period; keep those successful outcomes until the period resets, even if usage dips below the threshold. 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.