@assembly-js/app-foundation 0.0.2-rc.3 → 0.0.2

package/CLAUDE.md

@@ -39,7 +39,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-ai` — AI features via Assembly's OpenAI proxy (no API keys needed)
 - `assembly-storage` — app-private file uploads/downloads (NOT the portal Files module). The storage helpers come from `@assembly-js/app-foundation/server` — import them, don't rewrite them. POST only `{ fileName }` (a bare name) and store the key the platform returns; never build the S3 key yourself.
 - `assembly-integrations` (present only when third-party integrations are enabled for this workspace) — third-party providers (Slack, etc.) via `requiredIntegrations` + `getIntegration()`. If this skill is present, read it before declaring an integration or writing any provider call — it lists what's connectable and each provider's gotchas. If it is absent, managed OAuth integrations are not available here; use `requiredSecrets` for any external service
-- `assembly-avatar-sub` — row-duplication + AvatarSub pattern for showing which company a client row represents (multi-company clients)
+- `assembly-avatar-sub` — AvatarSub company badge wherever a client is rendered, including tables of your own records that reference a client; row duplication only for lists OF clients
 - `assembly-user-company-selector` — UserCompanySelector for picking clients, internal users, companies
 - `assembly-forms` — react-hook-form + zod + Field component validation pattern
 - `assembly-semantic-colors` — semantic color variants (info, success, warning, destructive) for Badge and Alert

package/dist/client-access.d.ts

@@ -0,0 +1,10 @@
+import type { AssemblyAPI } from '@assembly-js/node-sdk';
+export interface ClientAccessScope {
+    isLimited: boolean;
+    allowedCompanyIds: Set<string>;
+}
+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 {
+    companyIds?: string[];
+}>(scope: ClientAccessScope, client: T): boolean;

package/dist/client-access.js

@@ -0,0 +1,62 @@
+import { getAssembly } from './assembly.js';
+const UNRESTRICTED = {
+    isLimited: false,
+    allowedCompanyIds: new Set(),
+};
+// Denies everything: a limited scope with an empty allow-list. Used when the
+// viewer's access can't be resolved.
+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
+// 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) {
+    try {
+        // Same narrowing as requireCompanyScope: a session token string on the
+        // legacy path, an already-authenticated instance on the bearer path.
+        const assembly = typeof tokenOrAssembly === 'string' || tokenOrAssembly === undefined
+            ? 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 ?? []),
+        };
+    }
+    catch {
+        return DENY_ALL;
+    }
+}
+// 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,
+// so a limited viewer passes iff at least one of the resource's companies is on
+// their allow-list. Every client belongs to at least one company (real or
+// placeholder), which is what makes the company check sufficient for clients too.
+//
+// A resource with no companies is denied to a limited viewer: there is nothing to
+// match against the allow-list, and guessing would leak.
+export function canAccessCompanies(scope, companyIds) {
+    if (!scope.isLimited)
+        return true;
+    if (!companyIds || companyIds.length === 0)
+        return false;
+    return companyIds.some((id) => scope.allowedCompanyIds.has(id));
+}
+// Convenience for the common case of filtering client records. Generic over the
+// caller's row type because apps filter reshaped client objects (joined, picked,
+// extended) rather than raw SDK records; the constraint names the only field read.
+export function canAccessClient(scope, client) {
+    return canAccessCompanies(scope, client.companyIds);
+}

package/dist/server.d.ts

@@ -1,6 +1,7 @@
 import 'server-only';
 export * from './assembly.js';
 export * from './auth.js';
+export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
 export * from './app-storage.js';

package/dist/server.js

@@ -5,6 +5,7 @@
 import 'server-only';
 export * from './assembly.js';
 export * from './auth.js';
+export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
 export * from './app-storage.js';

package/package.json

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

package/skills/assembly-automations/SKILL.md

@@ -355,7 +355,7 @@ Each action route is then just the handler, served at the record's `baseUrl`:
 
 ```ts
 // app/api/assembly/time-entries/route.ts — the record's baseUrl
-import { automationActionRoute, ActionError } from '@assembly-js/app-foundation/server-actions';
+import { automationActionRoute, ActionError } from '@/lib/assembly-actions';
 import { db } from '@/lib/db';
 import { timeEntries } from '@/lib/schema';
 
@@ -423,7 +423,7 @@ Serve the route with the same wrapper as actions — its token check is what aut
 
 ```ts
 // app/api/assembly/projects/route.ts — the options record's baseUrl
-import { automationActionRoute } from '@assembly-js/app-foundation/server-actions';
+import { automationActionRoute } from '@/lib/assembly-actions';
 import { db } from '@/lib/db';
 import { projects } from '@/lib/schema';
 import { eq } from 'drizzle-orm';

package/skills/assembly-avatar-sub/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-avatar-sub
-description: Use when building a list or table that shows clients alongside their companies and a client can belong to multiple companies. Covers the row-duplication + AvatarSub pattern for disambiguating which company a row represents.
+description: Use whenever a client's name or avatar is rendered in a list, table, card, or detail header — including a table of the app's own records (reports, requests, tasks, invoices) that merely reference a client, not just a client directory. Clients belong to many companies, so a client shown without its company is ambiguous. Covers the AvatarSub company badge and the row-duplication pattern via expandClientsByCompany.
 ---
 
 `AvatarSub` renders a single nested sub-avatar overlaid at the bottom-right of the parent avatar. It always contains exactly one `Avatar`.
@@ -17,20 +17,33 @@ export PATH="$HOME/.bun/bin:$PATH" && bunx shadcn@latest add @assembly-ui/avatar
 
 ## When to use
 
-A client belongs to 2+ companies and the list needs to show which company each row represents. The pattern is **row duplication** — show the client once per company, each row with a single `AvatarSub` for that company.
+Anywhere a client's name or avatar appears, the company it belongs to is part of its identity — a client can belong to many companies, so a bare name is ambiguous. Two different situations, and picking the wrong one is the usual mistake:
+
+**Case A — a list OF clients** (a client directory, a picker, a "who has access" table). One client can legitimately occupy several rows, so use **row duplication**: one row per company, each with a single `AvatarSub`.
 
 - **0 or 1 company → no sub-avatar.** No disambiguation needed.
 - **2+ companies → one row per company**, each with a single `AvatarSub`.
 
+**Case B — a list of the app's own records that reference a client** (reports, requests, tasks, invoices, documents — the far more common table). **Do NOT duplicate rows**: a record belongs to exactly one client-and-company pair, so duplicating it would invent records that don't exist. Instead render a single `AvatarSub` for the company the record is scoped to, read from the record's own `companyId`:
+
+```tsx
+const company = row.companyId ? companiesMap.get(row.companyId) : undefined;
+// …render the client avatar with a single AvatarSub for `company`
+```
+
+If a record's rows are scoped to a company in some cases and to a client in others, badge the client-scoped ones with their `companyId` and leave a company-scoped row's own avatar unbadged — it is already unambiguous.
+
+Skipping the badge in Case B is the most common miss: the table looks fine until two clients share a name, or the same client appears under two companies, and staff cannot tell the rows apart.
+
 ## Anti-patterns — never do any of these
 
 - Do NOT render multiple `AvatarSub` elements on the same avatar.
 - Do NOT use `AvatarGroup` of small company avatars next to or on top of a client avatar.
 - Do NOT show all of a client's companies on a single row with stacked badges.
 
-The sub-avatar disambiguates *which* company a row represents, not *how many* companies a client has. The only correct multi-company pattern is row duplication.
+The sub-avatar disambiguates *which* company a row represents, not *how many* companies a client has. In Case A, row duplication is the only correct way to show a multi-company client; in Case B the record already names its company, so one badge per row is correct and duplication is wrong.
 
-## Row-duplication pattern
+## Row-duplication pattern (Case A)
 
 Use `expandClientsByCompany` — do NOT hand-roll the expansion. It returns one row per company for multi-company clients (each with its own `displayCompanyId`) and a single `displayCompanyId: null` row for clients with 0 or 1 companies.
 

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

@@ -30,30 +30,36 @@ On `retrieveInternalUser` / `listInternalUsers`, each internal user may carry:
 
 Access is **company-scoped**: a limited user can see a client iff **any** of the client's `companyIds` is in their `companyAccessList`. Every client belongs to at least one company (real or placeholder), so the company check covers all clients. This matches `users.User.IsAccessAllowed` in the backend.
 
-The session token carries only `internalUserId` — not the access fields. Load the viewer's scope once per request when you need it:
+## Pre-built helpers
+
+`@assembly-js/app-foundation/server` exports these — import them, do not rewrite the check.
 
 ```ts
+import {
+  getSessionIdentity,
+  getClientAccessScope,
+  canAccessCompanies,
+  canAccessClient,
+} from '@assembly-js/app-foundation/server';
+
 const identity = await getSessionIdentity();
 if (!identity?.internalUserId) return; // not an internal viewer
 
-const viewer = await assembly.retrieveInternalUser({ id: identity.internalUserId });
-const isLimited = viewer.isClientAccessLimited === true;
-const accessList = viewer.companyAccessList ?? [];
+// The session token carries only internalUserId, never the access fields, so
+// resolve the scope once per request and reuse it.
+const scope = await getClientAccessScope(identity.internalUserId);
 
-function canAccessCompany(companyId: string): boolean {
-  if (!isLimited) return true;
-  return accessList.includes(companyId);
-}
-
-function canAccessClient(client: { companyIds?: string[] }): boolean {
-  if (!isLimited) return true;
-  return (client.companyIds ?? []).some((id) => accessList.includes(id));
-}
+canAccessClient(scope, client);          // a client row (reads client.companyIds)
+canAccessCompanies(scope, [company.id]); // any company-scoped resource
 ```
 
+`getClientAccessScope` **fails closed**: if the viewer's access can't be resolved it denies
+everything rather than falling back to full access. Do not catch and widen that to
+"unrestricted" — an unverified viewer must never receive a full-access user's visibility.
+
 ### What to scope
 
-- **SDK lists and pickers** — `listClients`, `listCompanies`, and any UI built from them (tables, `UserCompanySelector` options) must only include clients/companies the viewer can access. Filter each page after fetch, or skip rows that fail `canAccessClient` / `canAccessCompany`. Do not assume the platform API filtered the list for you.
+- **SDK lists and pickers** — `listClients`, `listCompanies`, and any UI built from them (tables, `UserCompanySelector` options) must only include clients/companies the viewer can access. Filter each page after fetch, or skip rows that fail `canAccessClient` / `canAccessCompanies`. Do not assume the platform API filtered the list for you.
 - **App-owned data** — queries against your Postgres tables must apply the same rule: when the viewer is limited, restrict rows to `companyId IN companyAccessList` (and for client-owned rows, ensure the client is accessible). `requireCompanyScope` lets every internal user through — it enforces client-vs-staff isolation, not Client Access. See `assembly-route-auth` and `assembly-clients-companies`.
 - **CRM-tab context** — when the token already carries a `clientId` or `companyId`, the viewer was routed to a record they can access; scope to that tab as usual. The global Dashboard main view still needs the filters above.
 - **Fan-out to other internal users** (notifications, assignments) — filter recipients by their access to the relevant client/company.