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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.2-rc.1",
+  "version": "0.0.2-rc.3",
   "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 '@/lib/assembly-actions';
+import { automationActionRoute, ActionError } from '@assembly-js/app-foundation/server-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 '@/lib/assembly-actions';
+import { automationActionRoute } from '@assembly-js/app-foundation/server-actions';
 import { db } from '@/lib/db';
 import { projects } from '@/lib/schema';
 import { eq } from 'drizzle-orm';

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-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