@assembly-js/app-foundation 0.0.2-rc.1 → 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.1",
+  "version": "0.0.2",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

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-integrations/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: assembly-integrations
-description: Use BEFORE declaring requiredIntegrations in .assembly/app.json and before writing any call through getIntegration() from @/lib/nango (Slack and other OAuth providers — supported list inside). Covers manifest declaration, the broker client, per-provider gotchas (pagination, IDs vs names, membership/join), and ConnectorError handling.
+description: Use BEFORE declaring requiredIntegrations in .assembly/app.json and before writing any call through getIntegration() from @assembly-js/app-foundation/server (Slack and other OAuth providers — supported list inside). Covers manifest declaration, the broker client, per-provider gotchas (pagination, IDs vs names, membership/join), and ConnectorError handling.
 ---
 
 ## How it works
 
 When your app needs to talk to a third-party provider's API, declare the provider in `requiredIntegrations` in `.assembly/app.json`. The workspace admin connects the provider once via an OAuth popup; Assembly stores the connection through Nango.
 
-At runtime you call the provider through `getIntegration(provider)` from `@/lib/nango`. Calls go to the Assembly **connector broker** over your app's own authenticated session — you never see, handle, or store OAuth tokens or any Nango credentials, and there are **no per-provider environment variables**. The broker resolves the workspace's connection server-side (from your app's identity) and relays the provider's response back to you.
+At runtime you call the provider through `getIntegration(provider)` from `@assembly-js/app-foundation/server`. Calls go to the Assembly **connector broker** over your app's own authenticated session — you never see, handle, or store OAuth tokens or any Nango credentials, and there are **no per-provider environment variables**. The broker resolves the workspace's connection server-side (from your app's identity) and relays the provider's response back to you.
 
 The flow:
 
@@ -47,7 +47,7 @@ Add a top-level `requiredIntegrations` array to `.assembly/app.json`. Each entry
 `getIntegration` is **async** and must run **server-side, inside an authenticated request scope** — an API route handler, a server component, or a server action where `getAssembly()` can read the viewer bearer cookie. It authenticates to the broker as the current viewer the same way every other data call does — no `x-assembly-token` header, no token argument. Do **not** call it from a client component, from a background/cron job, or outside a user request — it will fail to authenticate. In practice: call it from a route handler invoked via `authFetch`, or from a server component/action that uses `getAssembly()`.
 
 ```typescript
-import { getIntegration } from '@/lib/nango';
+import { getIntegration } from '@assembly-js/app-foundation/server';
 ```
 
 `getIntegration(provider)` resolves to a thin client:
@@ -69,7 +69,7 @@ Some action inputs are flagged above as **resource inputs**: the value is the ID
 ```typescript
 // app/api/slack/post/route.ts
 import { NextRequest, NextResponse } from 'next/server';
-import { getIntegration, slackPostMessage } from '@/lib/nango';
+import { getIntegration, slackPostMessage } from '@assembly-js/app-foundation/server';
 
 export async function POST(request: NextRequest) {
   const { channel, text } = await request.json();
@@ -89,7 +89,7 @@ export async function POST(request: NextRequest) {
 ```typescript
 // app/api/slack/history/route.ts
 import { NextRequest, NextResponse } from 'next/server';
-import { getIntegration } from '@/lib/nango';
+import { getIntegration } from '@assembly-js/app-foundation/server';
 
 export async function GET(request: NextRequest) {
   const channelId = request.nextUrl.searchParams.get('channelId') ?? '';
@@ -110,13 +110,13 @@ provider `Response`.
 
 When the UI needs the user to choose a provider-side resource (a Slack channel, a Drive folder, a spreadsheet, an Airtable base), do NOT hand-roll the combobox plumbing — the foundation ships both halves:
 
-- **`resolveResource(provider, resolverAction, { query?, cursor?, fields, queryInput?, cursorInput?, input? })`** from `@/lib/nango` — server-side. Runs the resolver action and normalizes the provider's shape to `{ id, label }` options plus `nextCursor`. It returns a serializable `ResourcePage` — broker failures come back as `{ ok: false, error: { code, provider } }` instead of throwing, so the result survives a Server Action boundary (a thrown error is redacted in production). `fields` maps the action's result shape (dot paths allowed) — read it off the action's catalog signature above. Pass `queryInput` only when the action has a server-side search input; otherwise each page is filtered by label locally.
+- **`resolveResource(provider, resolverAction, { query?, cursor?, fields, queryInput?, cursorInput?, input? })`** from `@assembly-js/app-foundation/server` — server-side. Runs the resolver action and normalizes the provider's shape to `{ id, label }` options plus `nextCursor`. It returns a serializable `ResourcePage` — broker failures come back as `{ ok: false, error: { code, provider } }` instead of throwing, so the result survives a Server Action boundary (a thrown error is redacted in production). `fields` maps the action's result shape (dot paths allowed) — read it off the action's catalog signature above. Pass `queryInput` only when the action has a server-side search input; otherwise each page is filtered by label locally.
 - **`<ResourcePicker>`** from `@/app/components/resource-picker` — client-side searchable combobox with debounced search, cursor pagination ("Load more"), loading/empty states, and connector-error surfaces (`needs_reauth` renders a reconnect hint instead of an empty list). Store `value.id`, render `value.label`.
 
 ```typescript
 // app/actions/channels.ts
 'use server';
-import { resolveResource } from '@/lib/nango';
+import { resolveResource } from '@assembly-js/app-foundation/server';
 
 export async function searchChannels(args: { query: string; cursor?: string }) {
   // list-channels returns { conversations, next_cursor? } and has no query
@@ -131,7 +131,7 @@ export async function searchChannels(args: { query: string; cursor?: string }) {
 ```tsx
 // client component
 import { ResourcePicker } from '@/app/components/resource-picker';
-import type { ResourceOption } from '@/lib/resource-resolution';
+import type { ResourceOption } from '@assembly-js/app-foundation/client';
 
 const [channel, setChannel] = useState<ResourceOption | null>(null);
 <ResourcePicker fetchPage={searchChannels} value={channel} onValueChange={setChannel} placeholder="Search channels…" />
@@ -139,13 +139,13 @@ const [channel, setChannel] = useState<ResourceOption | null>(null);
 
 ## Slack specifics
 
-- **Post messages with `slackPostMessage` from `@/lib/nango` — never hand-roll `chat.postMessage`.** It resolves a `#name` to the channel ID, posts, and on `not_in_channel` joins the channel and retries once. Slack-level failures come back as `{ ok: false, error }`; on `not_in_channel` render "invite the bot to #channel in Slack" (private channels cannot be self-joined).
-- **Resolve channel names with `slackFindChannelId` from `@/lib/nango` for every other per-channel call — never hand-roll the lookup.** It handles cursor pagination (a single `conversations.list` call misses channels in large workspaces), name normalization, scope fallback, rate limits, and caching. Use the returned ID for every follow-up call; most Slack methods reject a `#name` with `invalid_arguments`.
+- **Post messages with `slackPostMessage` from `@assembly-js/app-foundation/server` — never hand-roll `chat.postMessage`.** It resolves a `#name` to the channel ID, posts, and on `not_in_channel` joins the channel and retries once. Slack-level failures come back as `{ ok: false, error }`; on `not_in_channel` render "invite the bot to #channel in Slack" (private channels cannot be self-joined).
+- **Resolve channel names with `slackFindChannelId` from `@assembly-js/app-foundation/server` for every other per-channel call — never hand-roll the lookup.** It handles cursor pagination (a single `conversations.list` call misses channels in large workspaces), name normalization, scope fallback, rate limits, and caching. Use the returned ID for every follow-up call; most Slack methods reject a `#name` with `invalid_arguments`.
 - **Writes need membership, not just visibility.** `slackPostMessage` handles this for posting. For any other write (reactions, uploads), a `not_in_channel` error means join first: the `join-channel` action with the channel ID, then retry once. Private channels cannot be self-joined — they fail `method_not_supported_for_channel_type`, so tell the user to invite the bot instead of retrying.
 - **Scopes:** `chat:write.public` lets posting reach any public channel without joining it, so only the other writes need `join-channel`. Add `groups:read` if the app must find private channels.
 
 ```typescript
-import { getIntegration, slackFindChannelId } from '@/lib/nango';
+import { getIntegration, slackFindChannelId } from '@assembly-js/app-foundation/server';
 
 const slack = await getIntegration('slack');
 const channelId = await slackFindChannelId(slack, 'general');
@@ -163,7 +163,7 @@ A connector call throws a **`ConnectorError`** (with `.code`, `.provider`, `.sta
 - `invalid_request` — malformed relay input (bad action name, unreadable body). Fix the call site.
 
 ```typescript
-import { getIntegration } from '@/lib/nango';
+import { getIntegration } from '@assembly-js/app-foundation/server';
 
 try {
   const slack = await getIntegration('slack');
@@ -178,10 +178,10 @@ try {
 
 ### Checking whether a provider is connected
 
-To gate UI on connectivity ("show a Connect prompt if Slack isn't connected"), use the **`isConnected`** helper from `@/lib/nango`. It asks the broker's read-only status endpoint for the stored connection state — **no provider call is made**, so it is cheap, has no side effects, and an unrelated call failure can never masquerade as "not connected". Do **not** probe by making a provider call and branching on whether it succeeded — a provider `404`/`400`/`500`, `action_failed`, or `connector_unavailable` all mean the connection **exists** and that call merely failed.
+To gate UI on connectivity ("show a Connect prompt if Slack isn't connected"), use the **`isConnected`** helper from `@assembly-js/app-foundation/server`. It asks the broker's read-only status endpoint for the stored connection state — **no provider call is made**, so it is cheap, has no side effects, and an unrelated call failure can never masquerade as "not connected". Do **not** probe by making a provider call and branching on whether it succeeded — a provider `404`/`400`/`500`, `action_failed`, or `connector_unavailable` all mean the connection **exists** and that call merely failed.
 
 ```typescript
-import { isConnected } from '@/lib/nango';
+import { isConnected } from '@assembly-js/app-foundation/server';
 
 const slackConnected = await isConnected('slack');
 ```
@@ -189,7 +189,7 @@ const slackConnected = await isConnected('slack');
 When the UI needs to distinguish *why* a provider isn't usable (render "Connect" vs "Reconnect"), read the full state from the client's **`status()`** method instead — it returns `{ provider, connected, status }` where `status` is `connected`, `connection_required`, `needs_reauth`, or `needs_reauth_scope`:
 
 ```typescript
-import { getIntegration } from '@/lib/nango';
+import { getIntegration } from '@assembly-js/app-foundation/server';
 
 const slack = await getIntegration('slack');
 const { connected, status } = await slack.status();

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.

package/skills/assembly-notifications/SKILL.md

@@ -106,11 +106,11 @@ await assembly.createNotification({
 });
 ```
 
-The examples here are **request-scoped** — a user is present, so `getAssembly()` reads the bearer from the request cookie and acts as that viewer. For a **background send with no user in the loop** (a scheduled job or an incoming webhook), there is no bearer cookie: call `getOfflineAssembly()` from `@/lib/assembly`, which mints an app-scoped **offline bearer** from your API key server-side. In that path `getSessionIdentity()` returns `null`, so choose a `senderId` explicitly (e.g. a system/admin internal user) rather than reading it from identity.
+The examples here are **request-scoped** — a user is present, so `getAssembly()` reads the bearer from the request cookie and acts as that viewer. For a **background send with no user in the loop** (a scheduled job or an incoming webhook), there is no bearer cookie: call `getOfflineAssembly()` from `@assembly-js/app-foundation/server`, which mints an app-scoped **offline bearer** from your API key server-side. In that path `getSessionIdentity()` returns `null`, so choose a `senderId` explicitly (e.g. a system/admin internal user) rather than reading it from identity.
 
 ```ts
 // app/api/cron/reminders/route.ts — background send, no viewer
-import { getOfflineAssembly } from '@/lib/assembly';
+import { getOfflineAssembly } from '@assembly-js/app-foundation/server';
 
 export async function GET() {
   const assembly = await getOfflineAssembly(); // app-scoped bearer, no cookie