@assembly-js/app-foundation 0.0.28 → 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

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.28",
+  "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 {