@assembly-js/app-foundation 0.0.12 → 0.0.13

package/CLAUDE.md

@@ -41,7 +41,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-app-bridge-toast` — show toast notifications in the parent dashboard
 - `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, don't rewrite. POST only `{ fileName }` and store the returned key; never build the S3 key yourself.
-- `assembly-integrations` (present only when third-party integrations are enabled) — third-party providers (Slack, etc.) via `requiredIntegrations` + `getIntegration()`; read before declaring an integration or writing a provider call — lists what's connectable and each provider's gotchas. Absent: managed OAuth isn't available, use `requiredSecrets` instead
+- `assembly-integrations` (present only when third-party integrations are enabled) — third-party providers (Slack, etc.) via `requiredIntegrations` + `getIntegration()`; read the skill and `.claude/skills/assembly-integrations/providers/<slug>.md` before declaring an integration or writing a provider call, and first when provider data displays wrongly (wrong format, raw IDs). Absent: managed OAuth isn't available, use `requiredSecrets` instead
 - `assembly-avatar-sub` — AvatarSub company badge wherever a client is rendered, including tables of your own records referencing 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

package/dist/nango.js

@@ -122,8 +122,9 @@ export async function getIntegration(provider) {
         delete: withMethod('DELETE'),
         // Synchronously triggers a pre-built Nango Action and returns its normalized
         // result inline as JSON. The whole `input` object is the action input.
-        // The available actions are listed in the assembly-integrations skill —
-        // never guess a name not on that list (an unknown name fails at runtime).
+        // Action names live in the assembly-integrations skill index; signatures
+        // live only in providers/<slug>.md — never guess a name or input shape
+        // (an unknown name fails at runtime).
         // A script-level failure throws ConnectorError with code 'action_failed'
         // and the provider error in `detail`.
         action: async (name, input) => {

package/package.json

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

package/render-context.mjs

@@ -82,9 +82,12 @@ export function renderFeatureGates(content, features) {
 // Replaces each catalog token with the markdown Go rendered for it. A token with no
 // entry is left alone: the config omits catalogs when the workspace cannot reach a
 // provider, and the surrounding prose is written to read correctly either way.
+// Keys are the full token strings, including per-slug markers
+// (`<!-- ASSEMBLY_ACTIONS:slack -->`) alongside the legacy globals.
 export function substituteCatalogs(content, catalogs) {
   let out = content;
   for (const [token, markdown] of Object.entries(catalogs ?? {})) {
+    if (!token) continue;
     out = out.split(token).join(markdown);
   }
   return out;

package/skills/assembly-integrations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-integrations
-description: Use BEFORE declaring requiredIntegrations in .assembly/app.json or calling getIntegration() from @assembly-js/app-foundation/server (Slack + other providers). Covers manifest declaration, the broker client, per-provider gotchas (pagination, IDs vs names, membership), ConnectorError handling.
+description: Use BEFORE declaring requiredIntegrations in .assembly/app.json or calling getIntegration() from @assembly-js/app-foundation/server, and when provider data displays wrongly (wrong format, raw IDs). Covers manifest declaration and the connector broker client. Read .claude/skills/assembly-integrations/providers/<slug>.md before any action() call for that provider and first when displayed provider data looks wrong.
 ---
 
 ## How it works
@@ -21,7 +21,7 @@ The flow:
 
 The Nango whitelist takes priority. If the provider is one of the supported providers below, always use `requiredIntegrations` — it gives the admin a one-click OAuth flow and Assembly manages token refresh for you.
 
-Supported providers (the v1 whitelist):
+Supported providers (the v1 whitelist). Action signatures exist only in the provider docs; never invent an action name:
 
 <!-- ASSEMBLY_PROVIDERS -->
 
@@ -40,7 +40,7 @@ Add a top-level `requiredIntegrations` array to `.assembly/app.json`. Each entry
 ```
 
 - `provider` must be one of the supported keys above.
-- `scopes` lists the provider's OAuth scopes; request the minimum your app needs.
+- `scopes` lists the provider's OAuth scopes; request the minimum your app needs. Per-provider scope recommendations live in that provider's doc.
 
 ## Calling the API
 
@@ -52,65 +52,19 @@ import { getIntegration } from '@assembly-js/app-foundation/server';
 
 `getIntegration(provider)` resolves to a thin client:
 
-- **`action(name, input)`** — synchronously trigger a pre-built Nango Action and get its normalized result back inline as already-parsed JSON. Actions are vetted server-side implementations that stay fixed as providers evolve — **use the pre-built action whenever one below covers the operation.** Only the names listed below exist: never invent an action name (an unknown name fails at runtime after a full round trip).
+- **`action(name, input)`** — synchronously trigger a pre-built Nango Action and get its normalized result back inline as already-parsed JSON. Actions are vetted server-side implementations that stay fixed as providers evolve — **use the pre-built action whenever one in that provider's doc covers the operation.** Action signatures exist only in the provider docs; never invent an action name (an unknown name fails at runtime after a full round trip). Do not call `action()` for a provider before reading `.claude/skills/assembly-integrations/providers/<slug>.md`.
 - **`proxy(opts)`** plus verb sugar **`get` / `post` / `put` / `patch` / `delete`(opts)** — relay an arbitrary provider HTTP call, for everything an action doesn't cover. `opts` = `{ endpoint, method?, data?, params?, headers? }`. Each returns the **raw `Response`** (the provider's status/headers/body, relayed transparently) — read it with `await res.json()` / `await res.text()`.
 - **`status()`** — read the workspace's stored connection state (`{ provider, connected, status }`) without touching the provider. See "Checking whether a provider is connected" below.
 
-### Pre-built actions
-
-<!-- ASSEMBLY_ACTIONS -->
-
 ### Resource inputs
 
-Some action inputs are flagged above as **resource inputs**: the value is the ID of something that lives in the provider (a channel, a spreadsheet, a list), and users do not know these IDs. **Never collect a resource input with a free-text ID field.** Use the foundation `ResourcePicker` component if your foundation provides one; otherwise build the same pattern yourself: a select/combobox whose options come from your own API route calling the annotated resolver action, rendering each item's label field and storing its id field **verbatim** as the input value. Apply any note on the annotation (a required filter, a resolver parameter, a multi-select shape) in the fetch. When an annotation says a resource input has no connectable resolver, fall back to a clearly labeled, validated field (e.g. paste the resource's URL and extract the ID from it) — still never a bare "enter the ID" box.
-
-### Example: post a message to Slack
-
-```typescript
-// app/api/slack/post/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { getIntegration, slackPostMessage } from '@assembly-js/app-foundation/server';
-
-export async function POST(request: NextRequest) {
-  const { channel, text } = await request.json();
-  const slack = await getIntegration('slack');
-  const result = await slackPostMessage(slack, { channel, text });
-  if (!result.ok) {
-    // result.error is Slack's code — 'not_in_channel' means the bot must be
-    // invited to the channel in Slack; 'channel_not_found' means a bad name.
-    return NextResponse.json({ error: result.error }, { status: 502 });
-  }
-  return NextResponse.json(result);
-}
-```
-
-### Example: read a channel's recent messages (action)
-
-```typescript
-// app/api/slack/history/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { getIntegration } from '@assembly-js/app-foundation/server';
-
-export async function GET(request: NextRequest) {
-  const channelId = request.nextUrl.searchParams.get('channelId') ?? '';
-  const slack = await getIntegration('slack');
-  const history = await slack.action('get-conversation-history', {
-    channel_id: channelId,
-    limit: 10,
-  });
-  return NextResponse.json(history);
-}
-```
-
-For an operation no action covers, relay the provider call through the proxy verbs — e.g.
-`slack.post({ endpoint: '/chat.update', data: { channel: channelId, ts, text } })` returns the raw
-provider `Response`.
+Some action inputs are flagged in the provider docs as **resource inputs**: the value is the ID of something that lives in the provider (a channel, a spreadsheet, a list), and users do not know these IDs. **Never collect a resource input with a free-text ID field.** Use the foundation `ResourcePicker` component if your foundation provides one; otherwise build the same pattern yourself: a select/combobox whose options come from your own API route calling the annotated resolver action, rendering each item's label field and storing its id field **verbatim** as the input value. Apply any note on the annotation (a required filter, a resolver parameter, a multi-select shape) in the fetch. When an annotation says a resource input has no connectable resolver, fall back to a clearly labeled, validated field (e.g. paste the resource's URL and extract the ID from it) — still never a bare "enter the ID" box.
 
 ## Letting the user pick a provider resource — ResourcePicker + resolveResource
 
 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 `@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.
+- **`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 in that provider's doc. 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
@@ -137,20 +91,6 @@ const [channel, setChannel] = useState<ResourceOption | null>(null);
 <ResourcePicker fetchPage={searchChannels} value={channel} onValueChange={setChannel} placeholder="Search channels…" />
 ```
 
-## Slack specifics
-
-- **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 '@assembly-js/app-foundation/server';
-
-const slack = await getIntegration('slack');
-const channelId = await slackFindChannelId(slack, 'general');
-```
-
 ## Error handling
 
 A connector call throws a **`ConnectorError`** (with `.code`, `.provider`, `.status`) when the broker returns a structured failure. Catch it and render an empty/error state instead of crashing the page. The codes:
@@ -203,3 +143,4 @@ const { connected, status } = await slack.status();
 - Do NOT install `@nangohq/node` or reference any `NANGO_*` environment variables — there are none; the broker is the only path to a connected provider.
 - Do NOT use `requiredIntegrations` for a provider outside the supported whitelist — fall back to `requiredSecrets`.
 - Do NOT infer "not connected" from a call failing (a non-2xx, a thrown error, a 404 from a wrong endpoint). A connection you can see in **Manage connections** stays connected regardless of individual call failures. Use `isConnected(provider)` / `status()` (above) for connectivity checks — never a live provider call.
+- Do NOT call `action()` for a provider, or invent an action name or input shape, without reading `.claude/skills/assembly-integrations/providers/<slug>.md` first.

package/skills/assembly-integrations/providers/airtable.md

@@ -0,0 +1,9 @@
+# Airtable
+
+Pagination keys and the `fields` param disagree across actions — copy the signature below, do not reuse a neighbour's names.
+
+- **Pagination:** `list-bases` takes `cursor` and returns `nextOffset`. `list-records` takes `offset` and returns `offset`. Passing the wrong key silently drops the next page.
+- **`fields` is overloaded:** on `list-records` it is an array of field names to return; on `create-record` / `update-record` it is a name-or-id-keyed map of values to write. An array on a write, or a map on a read, is rejected.
+- Resolve `baseId` with `list-bases` and table/field names with `get-base-schema` before writes. `tableIdOrName` accepts either; schema field ids survive a user renaming the column.
+
+<!-- ASSEMBLY_ACTIONS:airtable -->

package/skills/assembly-integrations/providers/calendly.md

@@ -0,0 +1,7 @@
+# Calendly
+
+Resources are addressed by full URI in results, but inputs take a bare UUID. Chaining `list-scheduled-events` into `list-event-invitees` means splitting the last path segment off the event's `uri` — no result field carries the bare uuid, so no picker can store it verbatim.
+
+The connection's own user is resolved internally; no user parameter is required.
+
+<!-- ASSEMBLY_ACTIONS:calendly -->

package/skills/assembly-integrations/providers/clickup.md

@@ -0,0 +1,11 @@
+# ClickUp
+
+Hierarchy is workspace → space → folder → list → task. `list-teams` is the only action that takes no id; every other level needs its parent. ClickUp calls a workspace a team.
+
+Walk down: `list-teams` → `list-spaces` (`team_id`) → `list-folders` (`space_id`) → `list-lists` (exactly one of `folder_id` or `space_id`; `space_id` returns lists sitting outside any folder) → `list-tasks` (`list_id`).
+
+- **create-task vs update-task:** the same task comes back with nested `status` / `priority` / `assignee` objects from one and flattened scalars from the other. `assignees` is a flat array of numeric user ids on create, and `{ add, rem }` on update.
+- **User ids:** `list-users` returns string ids; the task actions want numbers. Cast before writing — a picker that stores the string verbatim is rejected.
+- Dates are unix milliseconds. Priority is 1 (urgent) through 4 (low).
+
+<!-- ASSEMBLY_ACTIONS:clickup -->

package/skills/assembly-integrations/providers/dropbox.md

@@ -0,0 +1,7 @@
+# Dropbox
+
+Files are addressed by path, not id. `list-folder` entries carry `path_display` for follow-up calls; `download-file` also accepts an `id:...` identifier.
+
+`list-folder` reports only `.tag` / `id` / `name` / `path_lower` / `path_display` per entry. The `rev` that `upload-file`'s `update` mode requires comes only from `get-file-or-folder-metadata` (and only for files). Mode `add` creates, `overwrite` replaces, `update` needs the current rev.
+
+<!-- ASSEMBLY_ACTIONS:dropbox -->

package/skills/assembly-integrations/providers/gmail.md

@@ -0,0 +1,7 @@
+# Gmail
+
+Send-only: `gmail.send` is Google's one sensitive-tier Gmail scope; every read/draft scope is restricted (CASA audit), so those actions are unvendored. Do not invent a list or read action, and do not declare a read scope.
+
+`send-message` takes `raw`: the complete RFC 2822 MIME message, base64url-encoded. `threadId` makes it a reply; there is no in-catalog resolver for threads, so collect it from a previous send result, not a picker.
+
+<!-- ASSEMBLY_ACTIONS:gmail -->

package/skills/assembly-integrations/providers/google-calendar.md

@@ -0,0 +1,7 @@
+# Google Calendar
+
+`calendarId` defaults to `primary` on `list-events`. `create-event` requires `calendarId` plus `start` / `end` as `{ dateTime, timeZone? }` in RFC3339.
+
+`list-events` paginates with `cursor` in and `nextPageToken` out. `update-event` is a patch — only supplied fields change.
+
+<!-- ASSEMBLY_ACTIONS:google-calendar -->

package/skills/assembly-integrations/providers/google-drive.md

@@ -0,0 +1,7 @@
+# Google Drive
+
+`folderId` / `parentId` default to the drive root. `find-file` `query` takes Drive search syntax (e.g. `name contains 'report'` or a MIME-type filter). `upload-document` accepts plain text or base64 content up to 5 MB.
+
+`list-files-non-unified` lists only the immediate children of a folder.
+
+<!-- ASSEMBLY_ACTIONS:google-drive -->

package/skills/assembly-integrations/providers/google-sheet.md

@@ -0,0 +1,9 @@
+# Google Sheets
+
+Sheets has no in-provider listing. Spreadsheets live in Drive.
+
+When `google-drive` is on the supported-provider list, declare it too and resolve `spreadsheetId` via Drive `find-file` with query `mimeType='application/vnd.google-apps.spreadsheet'` (id field `id`, label `name`). When Drive is not connectable, collect the spreadsheet URL and extract the id — never a bare "enter the ID" box.
+
+Ranges are A1 notation; `values` is a 2D array of rows. `get-values` reads, `append-values-to-spreadsheet` appends to the table found in the range, `update-values` overwrites an exact range.
+
+<!-- ASSEMBLY_ACTIONS:google-sheet -->

package/skills/assembly-integrations/providers/hubspot.md

@@ -0,0 +1,10 @@
+# HubSpot
+
+Shapes are inconsistent across objects. Read each signature below — do not generalise casing, id-param names, or list result keys from a neighbouring entry.
+
+- **List result keys:** `list-contacts` and `list-deals` return `contacts` / `deals`; `list-companies` returns `items`.
+- **Id params:** `update-contact` takes `contactId`, `update-deal` takes `dealId`, `update-company` takes plain `id`.
+- **Name casing:** `create-contact` uses `firstname` / `lastname`; `update-contact` uses `firstName` / `lastName`. `create-deal` uses `dealName`; `update-deal` uses `dealname`.
+- **Pipelines:** `fetch-pipelines` resolves the ids `create-deal` / `update-deal` need (`objectType` defaults to `deals`). `dealstage` is nested under each pipeline — no flat picker metadata exists, so resolve it from the pipeline payload rather than inventing a stage resolver.
+
+<!-- ASSEMBLY_ACTIONS:hubspot -->

package/skills/assembly-integrations/providers/quickbooks.md

@@ -0,0 +1,9 @@
+# QuickBooks
+
+Writes use optimistic locking: updates need the record's current `SyncToken`. `get-invoice` returns `syncToken`; `get-customer`, `list-customers`, and `create-customer` omit it, so `update-customer` cannot be chained from this action set alone — read the current token through the proxy before updating.
+
+Casing is mixed: `create-invoice` takes camelCase; every other write takes QuickBooks' PascalCase. List result keys are `items` except `list-payments` (`payments`). Read each signature below.
+
+`CustomerRef` / `itemRef` / `LinkedTxn` shapes are in the catalog. Multi-account connections are keyed by `realmId`.
+
+<!-- ASSEMBLY_ACTIONS:quickbooks -->

package/skills/assembly-integrations/providers/slack.md

@@ -0,0 +1,27 @@
+# Slack
+
+Writes need membership, not just visibility. `send-message` reaches public channels without joining; other writes fail `not_in_channel` until the bot joins.
+
+- **Post 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.** It handles cursor pagination (a single `conversations.list` misses channels in large workspaces), name normalization, scope fallback, rate limits, and caching. Use the returned ID; most Slack methods reject a `#name` with `invalid_arguments`.
+- **Other writes (reactions, uploads):** on `not_in_channel`, call `join-channel` with the channel ID, then retry once. Private channels fail `method_not_supported_for_channel_type` — tell the user to invite the bot instead of retrying.
+- **Scopes:** `chat:write.public` lets posting reach any public channel without joining, so only the other writes need `join-channel`. Add `groups:read` if the app must find private channels.
+
+```typescript
+import { getIntegration, slackFindChannelId, slackPostMessage } from '@assembly-js/app-foundation/server';
+
+const slack = await getIntegration('slack');
+const channelId = await slackFindChannelId(slack, 'general');
+const posted = await slackPostMessage(slack, { channel: '#general', text: 'Hello' });
+```
+
+```typescript
+const history = await slack.action('get-conversation-history', {
+  channel_id: channelId,
+  limit: 10,
+});
+```
+
+For an operation no action covers, relay through the proxy — e.g. `slack.post({ endpoint: '/chat.update', data: { channel: channelId, ts, text } })`.
+
+<!-- ASSEMBLY_ACTIONS:slack -->

package/skills/assembly-integrations/providers/stripe.md

@@ -0,0 +1,7 @@
+# Stripe
+
+List cursors are the id of the last item on the previous page (Stripe's `starting_after`), not an opaque token. Passing a `next_cursor` from another provider, or anything that is not an item id, skips or repeats pages.
+
+`get-customer` returns the customer flat, not wrapped. Email filters on `list-customers` are case-sensitive exact matches.
+
+<!-- ASSEMBLY_ACTIONS:stripe -->

package/skills/assembly-integrations/providers/twilio.md

@@ -0,0 +1,8 @@
+# Twilio
+
+Most actions resolve the Account SID from the connection — except `create-call`, which requires `account_sid` as input. Each `list-incoming-phone-numbers` item carries `account_sid`; read it from there rather than inventing a sid source.
+
+- **`list-incoming-phone-numbers` is the camelCase outlier** (`friendlyName`, `phoneNumber`, `pageSize`). Every other Twilio action is snake_case.
+- `send-sms` requires exactly one of `from` (a number the account owns — resolve via `list-incoming-phone-numbers`) or `messaging_service_sid`.
+
+<!-- ASSEMBLY_ACTIONS:twilio -->

package/skills/assembly-integrations/providers/xero.md

@@ -0,0 +1,10 @@
+# Xero
+
+Every call is tenant-scoped. The templates resolve the organisation from `connection_config.tenant_id` (snake_case on the wire), then `metadata.tenantId`, then a live `/connections` lookup that errors when the token spans several organisations. Use `list-tenants` to get the `tenantId` that scopes the rest.
+
+Shapes and pagination disagree across actions — read each signature below.
+
+- **Pagination:** `list-contacts` / `list-invoices` use page numbers (`page` / `next_page`). `list-accounts` uses a cursor (`cursor` / `next_cursor`). `list-payments` returns `Pagination` / `NextPage`.
+- **Casing:** writes are mostly PascalCase (`Name`, `ContactID`, `InvoiceID`); `create-invoice` / `create-payment` take snake_case; `get-contact` returns camelCase; `list-payments` output keys are PascalCase.
+
+<!-- ASSEMBLY_ACTIONS:xero -->