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

package/dist/mint-bearer.js

@@ -0,0 +1,152 @@
+import { assemblyApi, OpenAPI } from '@assembly-js/node-sdk';
+import { BEARER_TTL_MS, classifyExchangeFailure, } from './session-exchange';
+// Trusted API origin for this stack (build-env supplied); empty in prod where
+// the SDK default is correct.
+const mintBaseUrl = process.env.ASSEMBLY_API_BASE_URL || undefined;
+// Loose bound for the destructive /session exchange. Aborting it does NOT undo
+// the server-side mint — the single-use session token is consumed either way —
+// so an early abort strands the caller with no bearer AND a spent token. Wait
+// out a cold platform-api lambda rather than risk that.
+const EXCHANGE_TIMEOUT_MS = 15_000;
+// Trades a single-use session token for a short-lived, user-scoped bearer by
+// calling platform-api POST /v1/session. This is the ONE sanctioned use of the
+// app API key as a request credential — it mints the bearer; every subsequent
+// data call uses the bearer alone.
+//
+// Shared by the proxy (first-load exchange) and the /api/assembly-reexchange
+// route (silent renewal on bearer expiry). Deliberately uses only assemblyApi +
+// fetch so it is safe in BOTH the Edge middleware runtime and the Node route-
+// handler runtime.
+//
+// On failure returns ok:false with a reason (see MintFailure) so the caller can
+// tell a spent token from an exchange it simply could not complete.
+export async function mintBearerFromSessionToken(token) {
+    let assembly;
+    try {
+        assembly = await assemblyApi({
+            apiKey: process.env.ASSEMBLY_API_KEY ?? '',
+            token,
+            baseUrl: mintBaseUrl,
+        });
+    }
+    catch {
+        return { ok: false, reason: 'rejected' };
+    }
+    // An exchange-capable app now receives a slim token carrying only workspaceId
+    // + tokenId (see marketplace_application CreateAppToken), so identity
+    // (clientId/internalUserId/companyId) is NOT read from the decrypted payload —
+    // it is sourced below from the /session response, the authoritative
+    // server-side record that backs both slim and legacy full tokens.
+    let payload = null;
+    if (typeof assembly.getTokenPayload === 'function') {
+        try {
+            payload = await assembly.getTokenPayload();
+        }
+        catch { }
+    }
+    // Undecodable, or no tokenId → not exchange-capable. Fail closed: a bearer-
+    // capable app never authenticates from a raw token.
+    if (!payload?.workspaceId || !payload.tokenId) {
+        return { ok: false, reason: 'rejected' };
+    }
+    const now = Date.now();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), EXCHANGE_TIMEOUT_MS);
+    try {
+        const resp = await assembly.fetch('/v1/session', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId: payload.tokenId }),
+            signal: controller.signal,
+        });
+        if (!resp.ok) {
+            return {
+                ok: false,
+                reason: classifyExchangeFailure(resp.status),
+            };
+        }
+        // session.* mirrors platform-api's ExchangeResponse.Session — the
+        // authoritative server-side record backing the (possibly slim) token, so
+        // identity is sourced from it rather than the decrypted token payload.
+        const json = await resp.json();
+        const bearerExpiresAt = Math.min(json.tokenExpiresAt * 1_000, now + BEARER_TTL_MS);
+        return {
+            ok: true,
+            bearer: json.token,
+            bearerExpiresAt,
+            session: {
+                workspaceId: json.session?.portalId || payload.workspaceId,
+                clientId: json.session?.clientUserId || undefined,
+                internalUserId: json.session?.internalUserId || undefined,
+                companyId: json.session?.companyId || undefined,
+                notificationId: json.session?.notificationId || undefined,
+                instanceId: json.session?.instanceId || undefined,
+                sessionId: payload.tokenId,
+            },
+        };
+    }
+    catch {
+        // Network failure, or the abort above fired. Either way the exchange did not
+        // complete, so we cannot claim the token was spent.
+        return { ok: false, reason: 'unavailable' };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+// Mints a short-lived, APP-scoped bearer from the app API key ALONE by calling
+// platform-api POST /v1/token (client-credentials). There is NO session token
+// and NO user in the loop: this is the OFFLINE/background path (cron, webhooks)
+// where no iframe ever handed us a session token to exchange. The app key mints
+// the bearer once; every subsequent data call then uses that bearer alone.
+//
+// Uses a runtime-agnostic fetch (safe in BOTH the Edge middleware and Node route-
+// handler runtimes) with the same abort-based timeout as the session exchange,
+// and fails closed (null) on any error — including a malformed 2xx — so a caller
+// never proceeds with a missing or bad credential.
+export async function mintBearerFromAppKey() {
+    const apiKey = process.env.ASSEMBLY_API_KEY;
+    if (!apiKey)
+        return null;
+    // Client-credentials mint: POST /v1/token authenticated by the app key sent as
+    // X-API-Key. Unlike mintBearerFromSessionToken (which decrypts a session token
+    // and lets the SDK derive the header), there is no token here, and the SDK only
+    // turns a bare apiKey into an X-API-Key in local/staging env modes — so in prod
+    // `assemblyApi({ apiKey })` would fail closed before ever reaching /v1/token.
+    // Send the credential directly against the trusted build-env base (or the SDK
+    // default in prod, where it is already correct).
+    const base = (mintBaseUrl ?? OpenAPI.BASE).replace(/\/$/, '');
+    const now = Date.now();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), EXCHANGE_TIMEOUT_MS);
+    try {
+        const resp = await fetch(`${base}/v1/token`, {
+            method: 'POST',
+            headers: { 'X-API-Key': apiKey },
+            signal: controller.signal,
+        });
+        if (!resp.ok)
+            return null;
+        const json = (await resp.json());
+        // Fail closed on a malformed or already-expired 2xx: a missing/mistyped token
+        // would yield a client that sends `Authorization: Bearer undefined`, a
+        // missing/NaN tokenExpiresAt would produce `bearerExpiresAt: NaN`, and an
+        // expiry at/before now would return a bearer whose first data call fails with
+        // auth errors instead of failing closed here at mint time. None is usable.
+        if (typeof json.token !== 'string' ||
+            json.token.length === 0 ||
+            typeof json.tokenExpiresAt !== 'number' ||
+            !Number.isFinite(json.tokenExpiresAt) ||
+            json.tokenExpiresAt * 1_000 <= now) {
+            return null;
+        }
+        const bearerExpiresAt = Math.min(json.tokenExpiresAt * 1_000, now + BEARER_TTL_MS);
+        return { bearer: json.token, bearerExpiresAt };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/dist/nango.d.ts

@@ -0,0 +1,174 @@
+import { type ResourceFieldMap, type ResourcePage } from './resource-resolution';
+export type Provider = 'slack' | 'gmail' | 'google-calendar' | 'google-drive' | 'google-sheet' | 'hubspot' | 'salesforce' | 'notion' | 'linear' | 'stripe' | 'github';
+export type ConnectorErrorCode = 'app_key_required' | 'provider_not_declared' | 'connection_required' | 'needs_reauth' | 'needs_reauth_scope' | 'connection_throttled' | 'connector_unavailable' | 'action_failed' | 'invalid_request';
+export interface ConnectionStatus {
+    provider: string;
+    connected: boolean;
+    status: 'connected' | 'connection_required' | 'needs_reauth' | 'needs_reauth_scope' | string;
+}
+export declare class ConnectorError extends Error {
+    readonly code: ConnectorErrorCode | string;
+    readonly provider: string;
+    readonly status: number;
+    /**
+     * 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.
+     */
+    readonly detail?: unknown;
+    constructor(args: {
+        code: ConnectorErrorCode | string;
+        provider: string;
+        status: number;
+        detail?: unknown;
+    });
+}
+export interface ProxyOpts {
+    endpoint: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | string;
+    data?: unknown;
+    params?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+}
+/**
+ * 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 declare function getIntegration(provider: Provider): Promise<{
+    proxy: (opts: ProxyOpts) => Promise<Response>;
+    get: (opts: Omit<ProxyOpts, "method">) => Promise<Response>;
+    post: (opts: Omit<ProxyOpts, "method">) => Promise<Response>;
+    put: (opts: Omit<ProxyOpts, "method">) => Promise<Response>;
+    patch: (opts: Omit<ProxyOpts, "method">) => Promise<Response>;
+    delete: (opts: Omit<ProxyOpts, "method">) => Promise<Response>;
+    action: <T = unknown>(name: string, input?: unknown) => Promise<T>;
+    status: () => Promise<ConnectionStatus>;
+    records: (_model: string, _query?: Record<string, unknown>) => never;
+}>;
+export type IntegrationClient = Awaited<ReturnType<typeof getIntegration>>;
+/**
+ * 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 declare function isConnected(provider: Provider): Promise<boolean>;
+export interface ResolveResourceOpts {
+    /** Search text. Trimmed; an empty query returns the unfiltered first page. */
+    query?: string;
+    /** Opaque next-page cursor from the previous page's result. */
+    cursor?: string;
+    /** Where id/label/items/cursor live on the action's result — take it from the action's catalog signature. */
+    fields: ResourceFieldMap;
+    /**
+     * Action input key that carries the search query. Omit when the resolver
+     * action has no server-side search — the fetched page is then filtered by
+     * label locally instead.
+     */
+    queryInput?: string;
+    /** Action input key that carries the page cursor. Defaults to 'cursor'. */
+    cursorInput?: string;
+    /** Extra action input merged verbatim (e.g. `{ baseId }` for Airtable). */
+    input?: Record<string, unknown>;
+}
+/**
+ * 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 declare function resolveResource(provider: Provider, resolverAction: string, opts: ResolveResourceOpts): Promise<ResourcePage>;
+/**
+ * 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 declare function slackFindChannelId(slack: IntegrationClient, name: string): Promise<string | null>;
+export interface SlackPostMessageResult {
+    ok: boolean;
+    /** Timestamp ID of the posted message (present when ok). */
+    ts?: string;
+    /** Resolved channel ID (present once the channel was found). */
+    channelId?: string;
+    /** Slack error code when not ok, e.g. 'channel_not_found', 'not_in_channel'. */
+    error?: string;
+}
+/**
+ * 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 declare function slackPostMessage(slack: IntegrationClient, args: {
+    channel: string;
+    text: string;
+}): Promise<SlackPostMessageResult>;