@assembly-js/app-foundation 0.0.1-rc.2 → 0.0.2-rc.1

package/skills/assembly-integrations/SKILL.md

@@ -0,0 +1,205 @@
+---
+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.
+---
+
+## 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.
+
+The flow:
+
+1. You declare `requiredIntegrations` in the manifest.
+2. The app parks in an `awaiting_config` state until every declared integration is connected (the same gate that waits on `requiredSecrets`).
+3. The admin connects each provider via the OAuth popup in the app builder UI.
+4. Once all integrations are connected, the deploy proceeds.
+5. Your server-side code calls `getIntegration(provider)` to reach the provider's API through the broker.
+
+## When to use this vs requiredSecrets
+
+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):
+
+<!-- ASSEMBLY_PROVIDERS -->
+
+For anything **not** on this list (a provider with only an API key, an internal service, a niche SaaS), fall back to a static `requiredSecret`. Do not try to shoehorn an unsupported provider into `requiredIntegrations` — the build will fail with an "unsupported provider" error.
+
+## Manifest declaration
+
+Add a top-level `requiredIntegrations` array to `.assembly/app.json`. Each entry is a provider key plus the OAuth scopes your app needs:
+
+```json
+{
+  "requiredIntegrations": [
+    { "provider": "slack", "scopes": ["chat:write", "channels:read"] }
+  ]
+}
+```
+
+- `provider` must be one of the supported keys above.
+- `scopes` lists the provider's OAuth scopes; request the minimum your app needs.
+
+## Calling the API
+
+`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';
+```
+
+`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).
+- **`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 '@/lib/nango';
+
+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 '@/lib/nango';
+
+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`.
+
+## 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 `@/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.
+- **`<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';
+
+export async function searchChannels(args: { query: string; cursor?: string }) {
+  // list-channels returns { conversations, next_cursor? } and has no query
+  // input, so pages are label-filtered locally.
+  return resolveResource('slack', 'list-channels', {
+    ...args,
+    fields: { id: 'id', label: 'name', items: 'conversations', nextCursor: 'next_cursor' },
+  });
+}
+```
+
+```tsx
+// client component
+import { ResourcePicker } from '@/app/components/resource-picker';
+import type { ResourceOption } from '@/lib/resource-resolution';
+
+const [channel, setChannel] = useState<ResourceOption | null>(null);
+<ResourcePicker fetchPage={searchChannels} value={channel} onValueChange={setChannel} placeholder="Search channels…" />
+```
+
+## 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`.
+- **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';
+
+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:
+
+- `connection_required` / `needs_reauth` / `needs_reauth_scope` — the workspace admin needs to (re)connect the provider in app settings. Render a "needs setup / reconnect" state, not a crash.
+- `connection_throttled` — too many calls on the shared connection; back off and retry.
+- `connector_unavailable` — the provider or Nango is temporarily unavailable.
+- `action_failed` — the pre-built action ran but the provider rejected the operation. The provider-level failure is in `err.detail` (e.g. `detail.response.error` is Slack's error code) — branch on it the way you would on a proxy response's error field.
+- `app_key_required` / `provider_not_declared` — a wiring bug: you called from an unauthenticated scope, or didn't declare the provider in `requiredIntegrations`. Fix the call site / manifest.
+- `invalid_request` — malformed relay input (bad action name, unreadable body). Fix the call site.
+
+```typescript
+import { getIntegration } from '@/lib/nango';
+
+try {
+  const slack = await getIntegration('slack');
+  const res = await slack.get({ endpoint: '/conversations.list' });
+  const data = await res.json();
+  // ... use data
+} catch (err) {
+  // err is a ConnectorError — branch on err.code to pick the right empty state
+  return NextResponse.json({ error: 'Integration unavailable' }, { status: 503 });
+}
+```
+
+### 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.
+
+```typescript
+import { isConnected } from '@/lib/nango';
+
+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';
+
+const slack = await getIntegration('slack');
+const { connected, status } = await slack.status();
+```
+
+## What NOT to do
+
+- Do NOT call `getIntegration` from client components, from background/cron code, or outside a user request — it authenticates via `getAssembly()` (bearer cookie) and fails without a viewer. Server-side, authenticated request scope only.
+- Do NOT persist, log, or cache OAuth tokens or connection details — the broker holds and resolves everything; you only ever get relayed responses.
+- Do NOT install or import a provider's own SDK (`@slack/web-api`, `googleapis`, `@hubspot/api-client`, etc.). Always go through `getIntegration(provider)`.
+- 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.