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

package/dist/nango.js

@@ -0,0 +1,430 @@
+import { getAssembly } from './assembly.js';
+import { findResource, normalizeResourcePage, TtlCache, } from './resource-resolution.js';
+// Thrown when the broker returns a structured `{ error, provider }` fail-closed
+// response. Catch it server-side and branch on `code` to render the right empty
+// state (e.g. "reconnect required" for needs_reauth, "not configured" for
+// connection_required). `status` is the broker's HTTP status for the response.
+export class ConnectorError extends Error {
+    code;
+    provider;
+    status;
+    /**
+     * For `action_failed`: what the action script threw — usually the
+     * provider-level failure, e.g. `{ type: 'slack_error', message, response }`
+     * where `response.error` is Slack's error code.
+     */
+    detail;
+    constructor(args) {
+        super(`Connector ${args.provider} error: ${args.code}`);
+        this.name = 'ConnectorError';
+        this.code = args.code;
+        this.provider = args.provider;
+        this.status = args.status;
+        this.detail = args.detail;
+    }
+}
+// Build the broker proxy path: /v1/connectors/:provider/proxy/<endpoint>?<params>.
+// The provider path is the URL suffix after /proxy/; query params are appended.
+function buildProxyPath(provider, endpoint, params) {
+    const cleanEndpoint = endpoint.replace(/^\//, '');
+    let path = `/v1/connectors/${provider}/proxy/${cleanEndpoint}`;
+    if (params) {
+        const search = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined)
+                search.set(key, String(value));
+        }
+        const qs = search.toString();
+        if (qs)
+            path += `?${qs}`;
+    }
+    return path;
+}
+// Reads a structured `{ error, provider }` fail-closed response off a non-2xx
+// broker response and throws ConnectorError. On a 2xx this is a no-op.
+async function throwIfBrokerError(res, provider) {
+    if (res.ok)
+        return;
+    let code = `http_${res.status}`;
+    let detail;
+    try {
+        const cloned = res.clone();
+        const body = (await cloned.json());
+        // A relayed Nango error nests the code (`{ error: { code } }`); the
+        // broker's own fail-closed responses use a flat string.
+        if (typeof body?.error === 'string')
+            code = body.error;
+        else if (typeof body?.error?.code === 'string')
+            code = body.error.code;
+        detail = body?.detail;
+    }
+    catch {
+        // Non-JSON error body (rare) — fall back to the http_<status> code.
+    }
+    throw new ConnectorError({ code, provider, status: res.status, detail });
+}
+/**
+ * Returns a thin, server-side-only client for a connected provider. Every method
+ * POSTs to the Assembly connector broker (`/v1/connectors/:provider/...`) via
+ * getAssembly().fetch — there is no Nango client and no provider credentials in
+ * the app. The broker resolves the workspace's connection server-side and
+ * relays the provider response transparently.
+ *
+ * MUST be called from server-side code only (API routes, server components,
+ * server actions) within an authenticated request scope. `getAssembly()` reads
+ * the viewer bearer from the request cookie (same as every other data call);
+ * there is no `x-assembly-token` header and no token argument. Background/cron
+ * calls with no viewer are out of scope for v1 — see connector Phase-2.
+ */
+export async function getIntegration(provider) {
+    const assembly = await getAssembly();
+    // Relays a provider HTTP call through the broker's universal proxy. The broker
+    // endpoint is always POST-ed (so a body carries through); the real provider
+    // verb travels in X-Connector-Method (default GET). The provider response is
+    // relayed transparently, so we return the raw Response for the caller to read
+    // (.json(), .text(), status, headers).
+    const proxy = async (opts) => {
+        const method = (opts.method ?? 'GET').toUpperCase();
+        const path = buildProxyPath(provider, opts.endpoint, opts.params);
+        // Named proxyHeaders (not `headers`) so callers' opts.headers stay distinct
+        // from this local map.
+        const proxyHeaders = {
+            ...(opts.headers ?? {}),
+            'X-Connector-Method': method,
+        };
+        const init = { method: 'POST', headers: proxyHeaders };
+        if (opts.data !== undefined) {
+            if (typeof opts.data === 'string') {
+                init.body = opts.data;
+            }
+            else {
+                init.body = JSON.stringify(opts.data);
+                // fetch defaults string bodies to text/plain; the broker forwards the
+                // content-type to the provider, so declare JSON unless the caller set
+                // their own content type.
+                const hasContentType = Object.keys(proxyHeaders).some((key) => key.toLowerCase() === 'content-type');
+                if (!hasContentType)
+                    proxyHeaders['Content-Type'] = 'application/json';
+            }
+        }
+        const res = await assembly.fetch(path, init);
+        await throwIfBrokerError(res, provider);
+        return res;
+    };
+    // Verb sugar: same as proxy() but pins the provider HTTP method.
+    const withMethod = (method) => (opts) => proxy({ ...opts, method });
+    return {
+        proxy,
+        get: withMethod('GET'),
+        post: withMethod('POST'),
+        put: withMethod('PUT'),
+        patch: withMethod('PATCH'),
+        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).
+        // A script-level failure throws ConnectorError with code 'action_failed'
+        // and the provider error in `detail`.
+        action: async (name, input) => {
+            const path = `/v1/connectors/${provider}/action/${encodeURIComponent(name)}`;
+            const res = await assembly.fetch(path, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(input ?? {}),
+            });
+            await throwIfBrokerError(res, provider);
+            return (await res.json());
+        },
+        // Reads the workspace's stored connection state from the broker — no
+        // provider round-trip, no side effects. Gate errors (provider_not_declared,
+        // app_key_required) still throw ConnectorError; a missing or reauth-needing
+        // connection is a normal `{ connected: false, status }` result. Prefer the
+        // isConnected() helper for a plain boolean.
+        status: async () => {
+            const res = await assembly.fetch(`/v1/connectors/${provider}/status`, {
+                method: 'GET',
+            });
+            await throwIfBrokerError(res, provider);
+            return (await res.json());
+        },
+        // Reserved seam for the future two-way sync surface (read synced records via
+        // the broker). Not implemented in v1 — declare it so call sites and the
+        // backend sync endpoint can land additively without changing this signature.
+        records: (_model, _query) => {
+            throw new Error('getIntegration().records is not supported in v1');
+        },
+    };
+}
+// The ONLY ConnectorError codes that mean a provider is genuinely not usable
+// by this app. Every other outcome — connector_unavailable, a transport blip —
+// leaves the stored connection intact; a connectivity check must never treat
+// those as "not connected".
+const NOT_CONNECTED_CODES = new Set([
+    'connection_required',
+    'needs_reauth',
+    'needs_reauth_scope',
+    'provider_not_declared',
+    'app_key_required',
+]);
+/**
+ * Report whether a provider is connected for the current workspace via the
+ * broker's read-only status endpoint — no provider call is made, so an
+ * unrelated call failure can never masquerade as "not connected".
+ *
+ *   - status says connected                 → true
+ *   - status says connection_required /
+ *     needs_reauth / needs_reauth_scope     → false (user must (re)connect)
+ *   - provider_not_declared / app_key_required → false (a wiring bug — the
+ *     provider is unusable until the manifest / call site is fixed)
+ *   - the status call itself fails
+ *     (connector_unavailable, transport)    → true (unknown ≠ disconnected; a
+ *     healthy connection must never render a Connect prompt over a blip)
+ *
+ * Do NOT hand-roll connectivity checks by making a provider call and branching
+ * on whether it succeeded — that reports a healthy connection as "not
+ * connected" the moment any unrelated call fails (the classic bug: probing a
+ * non-existent endpoint 404s, and the app shows "not connected" while real
+ * reads/writes succeed).
+ */
+export async function isConnected(provider) {
+    try {
+        const integration = await getIntegration(provider);
+        const { connected } = await integration.status();
+        return connected;
+    }
+    catch (err) {
+        if (err instanceof ConnectorError && NOT_CONNECTED_CODES.has(err.code)) {
+            return false;
+        }
+        return true;
+    }
+}
+// Short-lived memo of resolver pages so a user typing in a picker doesn't
+// re-hit the (often rate-limited) provider for every keystroke revisit. Safe
+// to share across requests: a deployment serves one workspace and connections
+// are workspace-scoped. Errors are never cached.
+const resolveResourceCache = new TtlCache(200);
+const RESOLVE_RESOURCE_CACHE_TTL_MS = 30_000;
+/**
+ * Fetch one page of provider resources as normalized `{ id, label }` options —
+ * the server half of a resource picker (channel/folder/spreadsheet/base
+ * selection). Runs the resolver action through the broker and maps the result
+ * via `fields`, so apps never re-derive pagination, id/label mapping, or
+ * connector error handling per picker.
+ *
+ * Returns a serializable ResourcePage rather than throwing ConnectorError:
+ * call it from a server action and hand the result (or the action itself) to
+ * `<ResourcePicker>`, which renders the matching option list, "Load more",
+ * and reconnect/error states. Non-connector errors still propagate.
+ *
+ * @example
+ * // app/actions/channels.ts
+ * 'use server';
+ * import { getIntegration, resolveResource } from '@assembly-js/app-foundation/server';
+ *
+ * export async function searchChannels(args: { query: string; cursor?: string }) {
+ *   // list-channels 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' },
+ *   });
+ * }
+ */
+export async function resolveResource(provider, resolverAction, opts) {
+    const query = opts.query?.trim() || undefined;
+    const actionInput = { ...(opts.input ?? {}) };
+    if (query && opts.queryInput)
+        actionInput[opts.queryInput] = query;
+    if (opts.cursor)
+        actionInput[opts.cursorInput ?? 'cursor'] = opts.cursor;
+    const cacheKey = JSON.stringify([
+        provider,
+        resolverAction,
+        actionInput,
+        opts.fields,
+        query,
+    ]);
+    const cached = resolveResourceCache.get(cacheKey);
+    if (cached)
+        return cached;
+    let raw;
+    try {
+        const integration = await getIntegration(provider);
+        raw = await integration.action(resolverAction, actionInput);
+    }
+    catch (err) {
+        if (err instanceof ConnectorError) {
+            return { ok: false, error: { code: err.code, provider: err.provider } };
+        }
+        throw err;
+    }
+    const page = normalizeResourcePage(raw, opts.fields, {
+        // When the action searched server-side, don't second-guess its matching
+        // with a literal substring filter.
+        query: opts.queryInput ? undefined : query,
+        requestCursor: opts.cursor,
+    });
+    const result = { ok: true, ...page };
+    resolveResourceCache.set(cacheKey, result, RESOLVE_RESOURCE_CACHE_TTL_MS);
+    return result;
+}
+// Process-lifetime memo of resolved channel IDs so repeated sends don't
+// re-walk the (rate-limited) channel list. Names are stored normalized.
+// Misses are not cached — the channel may be created later.
+const slackChannelIdCache = new Map();
+const SLACK_LIST_PAGE_LIMIT = '999'; // Slack caps below 1000; fewer, bigger pages
+const SLACK_LIST_MAX_PAGES = 100; // defensive bound; trust but cap the cursor
+const SLACK_RATE_LIMIT_MAX_WAITS = 3;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Resolve a Slack channel name to its ID, walking the cursor-paginated
+ * conversations.list until found (Slack treats `limit` as a per-page cap and
+ * may return fewer; a single un-paginated call misses channels in large
+ * workspaces). Input is normalized (leading '#' stripped, lowercased — Slack
+ * channel names are always lowercase). Resolved IDs are memoized for the
+ * process lifetime; Slack rate limits (conversations.list is a low-tier
+ * method) are absorbed by waiting and resuming from the same cursor.
+ *
+ * Use the returned ID for every follow-up call — conversations.join /
+ * conversations.history / chat.postMessage should all be given IDs; most
+ * methods reject a `#name` with `invalid_arguments`.
+ *
+ * Membership: public channels are listed whether or not the bot joined, but
+ * posting still needs membership — on a `not_in_channel` error from
+ * chat.postMessage, call conversations.join with the ID and retry once.
+ * Private channels are listed only when the bot is already a member (and only
+ * when the connection has the groups:read scope — without it this helper
+ * automatically falls back to public channels only). A private channel cannot
+ * be self-joined: surface "invite the bot to #channel in Slack" to the user.
+ */
+export async function slackFindChannelId(slack, name) {
+    const target = name.replace(/^#/, '').trim().toLowerCase();
+    if (!target)
+        return null;
+    const cached = slackChannelIdCache.get(target);
+    if (cached)
+        return cached;
+    const fields = {
+        id: 'id',
+        label: 'name',
+        items: 'channels',
+        nextCursor: 'response_metadata.next_cursor',
+    };
+    let types = 'public_channel,private_channel';
+    let rateLimitWaits = 0;
+    // findResource drives the cursor walk; this fetcher owns the Slack quirks —
+    // rate-limit waits resume from the SAME cursor (throwing would discard the
+    // walk and a retry would restart from page 1), and a missing_scope for
+    // private_channel (no groups:read) fails the WHOLE first call, so retrying
+    // public-only from the same cursor restarts the walk correctly.
+    const fetchPage = async (cursor) => {
+        for (;;) {
+            let res;
+            try {
+                res = await slack.get({
+                    endpoint: '/conversations.list',
+                    params: {
+                        types,
+                        limit: SLACK_LIST_PAGE_LIMIT,
+                        exclude_archived: 'true',
+                        ...(cursor ? { cursor } : {}),
+                    },
+                });
+            }
+            catch (err) {
+                // A provider 429 relays through the broker as a ConnectorError with
+                // the provider's status.
+                if (err instanceof ConnectorError &&
+                    err.status === 429 &&
+                    rateLimitWaits < SLACK_RATE_LIMIT_MAX_WAITS) {
+                    rateLimitWaits++;
+                    await sleep(Math.min(10_000 * rateLimitWaits, 30_000));
+                    continue;
+                }
+                throw err;
+            }
+            const data = (await res.json());
+            if (!data.ok) {
+                if (data.error === 'missing_scope' && types !== 'public_channel') {
+                    types = 'public_channel';
+                    continue;
+                }
+                if (data.error === 'ratelimited' &&
+                    rateLimitWaits < SLACK_RATE_LIMIT_MAX_WAITS) {
+                    rateLimitWaits++;
+                    await sleep(Math.min(10_000 * rateLimitWaits, 30_000));
+                    continue;
+                }
+                throw new Error(data.error ?? 'Slack conversations.list failed');
+            }
+            return normalizeResourcePage(data, fields, { requestCursor: cursor });
+        }
+    };
+    // Slack channel names are always lowercase, so an exact label match is the
+    // same comparison the raw walk made against channel.name.
+    const hit = await findResource(fetchPage, (option) => option.label === target, {
+        maxPages: SLACK_LIST_MAX_PAGES,
+    });
+    if (hit)
+        slackChannelIdCache.set(target, hit.id);
+    return hit?.id ?? null;
+}
+// Slack channel/group IDs (C…/G…) pass through slackPostMessage untouched;
+// anything else is treated as a name and resolved first.
+const SLACK_CHANNEL_ID_RE = /^[CG][A-Z0-9]{6,}$/;
+/**
+ * Post a message to a Slack channel by name or ID. Use this instead of calling
+ * the send-message action or chat.postMessage yourself: it resolves `#name` →
+ * ID via slackFindChannelId (Slack rejects names with `invalid_arguments`),
+ * sends via the pre-built `send-message` action, and on `not_in_channel` it
+ * joins the channel and retries once (posting can require membership; joining
+ * needs the `channels:join` scope).
+ *
+ * Slack-level failures come back as `{ ok: false, error }` rather than throwing,
+ * so render the right state per code:
+ * - `channel_not_found` — no such channel; check the name.
+ * - `not_in_channel` — the bot couldn't self-join (private channel, or
+ *   `channels:join` not declared in the manifest scopes): tell the user to
+ *   invite the bot to the channel in Slack.
+ * Broker-level failures (provider not connected, throttled) still throw
+ * ConnectorError like every other call.
+ */
+export async function slackPostMessage(slack, args) {
+    const channelId = SLACK_CHANNEL_ID_RE.test(args.channel)
+        ? args.channel
+        : await slackFindChannelId(slack, args.channel);
+    if (!channelId)
+        return { ok: false, error: 'channel_not_found' };
+    // The send-message action throws on Slack-level failure (relayed as
+    // ConnectorError 'action_failed' with the thrown payload in detail); map
+    // that back to `{ ok: false, error }` so callers branch on one shape.
+    const post = async () => {
+        try {
+            const result = await slack.action('send-message', { channel_id: channelId, text: args.text });
+            return { ok: result.ok, ts: result.ts };
+        }
+        catch (err) {
+            if (err instanceof ConnectorError && err.code === 'action_failed') {
+                const detail = err.detail;
+                const slackError = detail?.response?.error ?? detail?.message;
+                if (typeof slackError === 'string')
+                    return { ok: false, error: slackError };
+            }
+            throw err;
+        }
+    };
+    let result = await post();
+    if (!result.ok && result.error === 'not_in_channel') {
+        const joinRes = await slack.post({
+            endpoint: '/conversations.join',
+            data: { channel: channelId },
+        });
+        const join = (await joinRes.json());
+        if (join.ok)
+            result = await post();
+    }
+    return { ok: result.ok, ts: result.ts, channelId, error: result.error };
+}

package/dist/network-capture.d.ts

@@ -0,0 +1,36 @@
+export declare const NETWORK_CAPTURE_MESSAGE_TYPE: "assembly.debug.network";
+export interface NetworkCaptureHeaderFingerprint {
+    present: true;
+    /** Auth scheme word (e.g. "Bearer", "Basic") when the value looks like "<scheme> <token>". */
+    scheme?: string;
+    /** Bounded prefix of the value (after the scheme, if any) — never the full secret. */
+    prefix: string;
+    /** Length of the original, un-redacted value. */
+    len: number;
+}
+type RedactedHeaderValue = string | NetworkCaptureHeaderFingerprint;
+export interface NetworkCaptureRecord {
+    id: string;
+    source: 'fetch' | 'xhr';
+    method: string;
+    url: string;
+    status: number | null;
+    ok: boolean | null;
+    startedAt: number;
+    durationMs: number;
+    requestHeaders: Record<string, RedactedHeaderValue>;
+    responseHeaders: Record<string, RedactedHeaderValue>;
+    requestBodySnippet?: string;
+    responseBodySnippet?: string;
+    error?: string;
+}
+export declare function redactUrl(rawUrl: string): string;
+export declare function collectHeaders(headers: HeadersInit | Headers | null | undefined): Record<string, RedactedHeaderValue>;
+export declare function collectXhrResponseHeaders(raw: string): Record<string, RedactedHeaderValue>;
+export declare function snippetFromRequestBody(body: unknown): string | undefined;
+export declare function getCapturedRecords(): readonly NetworkCaptureRecord[];
+export declare function recordNetworkCapture(record: NetworkCaptureRecord): void;
+export declare function installFetchCapture(): void;
+export declare function installXhrCapture(): void;
+export declare function installNetworkCapture(): void;
+export {};