@assembly-js/app-foundation 0.0.27 → 0.0.29

package/CLAUDE.md

@@ -20,7 +20,7 @@ When a request implies a scope or permission change, apply it and report the pro
 
 Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them by name as you reach for the relevant concept — don't re-read this file's general sections when a skill exists. Available skills:
 
-- `assembly-internal-users` — staff in the Dashboard; Client Access permissions (`isClientAccessLimited`, `companyAccessList`) and scoping internal views to allowed companies
+- `assembly-internal-users` — staff in the Dashboard; workspace role (`admin` or `staff`) for admin-only features; Client Access permissions (`isClientAccessLimited`, `companyAccessList`) and scoping internal views to allowed companies
 - `assembly-client-users` — customers in the Client Portal
 - `assembly-companies` — many-to-many with clients; placeholder companies (excluded from `listCompanies` by default for these apps)
 - `assembly-clients-companies` — REQUIRED when the app stores or scopes data by client or company: scoped tables carry BOTH a `clientId` and a `companyId` column and are filtered on the intersection (never one dimension); a client viewer always has an active `companyId`; `companyIds[]` builds pickers only and `client.companyId` is deprecated
@@ -52,6 +52,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-semantic-colors` — semantic color variants (info, success, warning, destructive) for Badge and Alert
 - `assembly-workspace-labels` — workspace-customized display labels for clients/companies. The server helper comes from `@assembly-js/app-foundation/server`, the `useLabels()` hook from the repo — import them, don't rewrite them.
 - `assembly-db-transactions` — REQUIRED when a route makes more than one DB write: `db.transaction()` is unsupported on neon-http and 500s. Use `db.batch([...])` for atomic multi-writes, sequential awaits otherwise.
+- `assembly-record-writes` — REQUIRED when a form creates a record that a later save also writes, especially with nested rows (packages, add-ons, line items, blocks): create and save call one writer so create cannot drop submitted fields.
 - `assembly-session-token` — the bearer lifecycle and how to read identity or fetch data: `getSessionIdentity()`/`useAssembly()`, `useServerAction`/`callAction`, `authFetch`. You never handle a token yourself.
 - `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.
@@ -349,6 +350,7 @@ export const items = pgTable('items', {
 - Use `drizzle-kit push` (not `migrate`) — no migration files; schema is pushed directly.
 - Use `@neondatabase/serverless` with `drizzle-orm/neon-http` — not `pg` or `postgres.js`. It's the standard driver for the Vercel serverless (Node) runtime this app deploys to; `lib/db.ts` already wires it up.
 - **No interactive transactions.** `db.transaction(async (tx) => …)` is unsupported on neon-http and throws (a 500). For atomic multi-writes use `db.batch([...])`; otherwise sequential `await`s. See the `assembly-db-transactions` skill.
+- **Create writes every field the create form submits.** If a later save writes nested rows (packages, add-ons, blocks), create calls that same writer with the submitted payload. A success toast and a redirect to the editor do not save. See `assembly-record-writes`.
 - `DATABASE_URL` is already in the shell env. Do NOT hardcode it or write it to `.env.local`.
 - Use `db` from `lib/db.ts` in **server components, server actions, and route handlers only** — never in client components. This is enforced: `lib/db.ts` imports `server-only`, so pulling it (or anything that imports it, e.g. a lib file re-exporting constants) into a `'use client'` module fails `bun run build`. Keep client-shared constants/types in their own file, not next to server queries.
 - **Validate values before they hit typed columns — not because they arrived as route params.** Route segments can be slugs or external ids. When the next step is a uuid-column lookup, use `parseUuid` / `isUuid` from `@assembly-js/app-foundation/server` so a bad value 400/404s instead of Postgres throwing `invalid input syntax for type uuid`. In server components/pages: `if (!isUuid(id)) notFound()` before the query.

package/dist/client-access.d.ts

@@ -3,6 +3,11 @@ export interface ClientAccessScope {
     isLimited: boolean;
     allowedCompanyIds: Set<string>;
 }
+export interface InternalUserAccess {
+    isWorkspaceAdmin: boolean;
+    scope: ClientAccessScope;
+}
+export declare function getInternalUserAccess(internalUserId: string, tokenOrAssembly?: string | AssemblyAPI): Promise<InternalUserAccess>;
 export declare function getClientAccessScope(internalUserId: string, tokenOrAssembly?: string | AssemblyAPI): Promise<ClientAccessScope>;
 export declare function canAccessCompanies(scope: ClientAccessScope, companyIds: string[] | null | undefined): boolean;
 export declare function canAccessClient<T extends {

package/dist/client-access.js

@@ -9,17 +9,16 @@ const DENY_ALL = {
     isLimited: true,
     allowedCompanyIds: new Set(),
 };
-// Resolves the Client Access scope for an internal user.
-//
-// Fails closed: if the lookup fails we return DENY_ALL rather than treating the
-// viewer as unrestricted. An unverified viewer must not be handed the access of
-// a full-access one — the caller sees empty lists (or a 404 via
+const NO_ACCESS = { isWorkspaceAdmin: false, scope: DENY_ALL };
+// Fails closed: if the lookup fails we return NO_ACCESS rather than treating the
+// viewer as an unrestricted admin. An unverified viewer must not be handed the
+// access of a full-access one — the caller sees empty lists (or a 404 via
 // canAccessCompanies) instead of another workspace member's data. Callers that
 // prefer to surface a transient failure should catch it upstream and retry.
 //
-// The session token carries only `internalUserId`, never the access fields, so
-// this costs one `retrieveInternalUser` per request that needs it.
-export async function getClientAccessScope(internalUserId, tokenOrAssembly) {
+// The session token carries only `internalUserId`, never the role or access
+// fields, so this costs one `retrieveInternalUser` per request that needs it.
+export async function getInternalUserAccess(internalUserId, tokenOrAssembly) {
     try {
         // Same narrowing as requireCompanyScope: a session token string on the
         // legacy path, an already-authenticated instance on the bearer path.
@@ -27,17 +26,19 @@ export async function getClientAccessScope(internalUserId, tokenOrAssembly) {
             ? await getAssembly(tokenOrAssembly)
             : tokenOrAssembly;
         const user = await assembly.retrieveInternalUser({ id: internalUserId });
-        if (user.isClientAccessLimited !== true)
-            return UNRESTRICTED;
-        return {
-            isLimited: true,
-            allowedCompanyIds: new Set(user.companyAccessList ?? []),
-        };
+        const scope = user.isClientAccessLimited === true
+            ? { isLimited: true, allowedCompanyIds: new Set(user.companyAccessList ?? []) }
+            : UNRESTRICTED;
+        return { isWorkspaceAdmin: user.role === 'admin', scope };
     }
     catch {
-        return DENY_ALL;
+        return NO_ACCESS;
     }
 }
+// Resolves only the Client Access scope, for callers that never gate on role.
+export async function getClientAccessScope(internalUserId, tokenOrAssembly) {
+    return (await getInternalUserAccess(internalUserId, tokenOrAssembly)).scope;
+}
 // True when the viewer may see a resource belonging to any of `companyIds`.
 //
 // Mirrors the platform's own users.User.IsAccessAllowed: access is company-scoped,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -43,7 +43,7 @@
   },
   "devDependencies": {
     "@assembly-js/app-bridge": "1.3.0",
-    "@assembly-js/node-sdk": "4.2.3-beta.2",
+    "@assembly-js/node-sdk": "4.2.4",
     "@types/bun": "^1.1.0",
     "@types/node": "^22",
     "next": "^15.5.0",

package/skills/assembly-internal-users/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-internal-users
-description: Use when the app reads/lists internal users, or an internal viewer browses clients/companies in the Dashboard. Covers Client Access (isClientAccessLimited, companyAccessList) scoping. Internal users sign into the Dashboard only. Detect via tokenPayload.internalUserId.
+description: Use when the app reads/lists internal users, gates a feature to workspace admins (role is "admin" or "staff"), or an internal viewer browses clients/companies in the Dashboard. Covers Client Access (isClientAccessLimited, companyAccessList) scoping. Internal users sign into the Dashboard only. Detect via tokenPayload.internalUserId.
 ---
 
 Internal users are the **business team** running the Assembly workspace. They sign into the Dashboard at the workspace's domain, never the branded Client Portal. They have full read/write power over clients, companies, files, etc. — **within their Client Access scope** (see below).
@@ -23,6 +23,24 @@ If `internalUserId` is set, the current viewer is staff. (`clientId` is set for
 - `listInternalUsers({ nextToken, limit })` — paged list of all staff in the workspace
 - `retrieveInternalUser({ id })` — single record by id
 
+## Workspace role — admins vs staff
+
+Every internal user has a workspace role: `"admin"` or `"staff"`. The workspace owner is an admin. When the app has admin-only features ("admins manage templates", "only admins can change settings"), gate them on this role. Do not invent an app-level role table or admin list for this, and never leave the check stubbed off until a role source is "confirmed": this is the role source.
+
+```ts
+import { getInternalUserAccess, getSessionIdentity } from '@assembly-js/app-foundation/server';
+
+const identity = await getSessionIdentity();
+if (!identity?.internalUserId) return { ok: false, message: 'Only your team can manage templates.' };
+
+const access = await getInternalUserAccess(identity.internalUserId);
+if (!access.isWorkspaceAdmin) {
+  return { ok: false, message: 'Only workspace admins can manage templates.' };
+}
+```
+
+Apply the same check on the server action or route, not only in the UI. `access.scope` is the viewer's Client Access scope from the same lookup (below). If the app needs its own job titles beyond admin and staff (approver, manager), store those in the app; workspace admins must still be able to manage them.
+
 ## Client Access permissions
 
 Client Access is a **workspace-level** setting (configured in workspace settings, not inside your app). By default every internal user can see all clients and companies. Admins can limit an internal user to specific companies; that limit ripples through the platform.
@@ -36,7 +54,7 @@ Access is **company-scoped**: a limited user can see a client iff **any** of the
 
 ## Pre-built helpers
 
-`@assembly-js/app-foundation/server` exports these — import them, do not rewrite the check.
+`@assembly-js/app-foundation/server` exports these — import them, do not rewrite the check. When the request also needs the admin check, call `getInternalUserAccess` once and use its `scope` instead of a second lookup.
 
 ```ts
 import {

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

@@ -0,0 +1,39 @@
+---
+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.
+---
+
+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.
+
+## The rule
+
+One function writes the submitted payload. Create calls it for a new id; save calls it for an existing id.
+
+```ts
+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);
+}
+
+export async function createProposal(input: ProposalInput) {
+  const id = crypto.randomUUID();
+  await writeProposal(id, input);
+  await recordEvent(id, 'draft_created');
+  return id;
+}
+
+export async function saveProposal(id: string, input: ProposalInput) {
+  await writeProposal(id, input);
+}
+```
+
+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.