@assembly-js/app-foundation 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -17,6 +17,9 @@ bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's o
 A patch release never changes what an app's build requires; a minor release may add or change a
 `bin/check-*.mjs` script. CI fails a PR that changes a check script without a minor bump over main.
 
+## 0.2.4
+- [new] Add `@assembly-js/app-foundation/codegen`, which turns another app's API description into a typed client the app can call by verb and path, and `appProxyOptions` in `/server`, which that client uses to reach the other app through the platform. Nothing in the app changes until a client is generated for it.
+
 ## 0.2.3
 - [new] The client-call scan now treats a client's own notification reads (list, mark read, mark unread) as safe, matching the routes the platform opens to clients. Nothing in the app changes.
 

package/bin/foundation-exports.mjs

@@ -1,4 +1,4 @@
-// Every name `@assembly-js/app-foundation/server` and `/client` export that is NOT a way to
+// Every name `@assembly-js/app-foundation/server`, `/client` and `/codegen` export that is NOT a way to
 // obtain an Assembly client or request context for the person using the app. The scan
 // follows viewer clients only from the sources it knows (SDK_FACTORIES, afterAssembly,
 // getRequestContext in scan-client-calls.mjs); an import from those entry points that is in
@@ -18,15 +18,15 @@
 // renews the bearer cookie; it never hands out a client.
 export const NON_CLIENT_EXPORTS = new Set([
   'APP_CSRF_HEADER', 'AUTH_UNAVAILABLE_CODE', 'ActionContext', 'ActionError',
-  'ActionErrorStatus', 'AirtableFieldSchema', 'AirtableFormattedField',
+  'ActionErrorStatus', 'AirtableFieldSchema', 'AppProxyCaller', 'AppProxyOptions', 'AirtableFormattedField',
   'AirtableFormattedRecord', 'AirtableRecord', 'AirtableSchemaResult', 'AirtableTableSchema',
   'AssemblyProxyForwardContext', 'AssemblyProxyOptions', 'AuthUnavailableError',
   'BEARER_COOKIE_NAME', 'BEARER_HEADER_NAME', 'BEARER_IN_BODY_HEADER', 'BEARER_TTL_MS',
   'CLIENT_BEARER_HEADER', 'CLIENT_FLAGS_COOKIE_NAME', 'COOKIE_OUTCOME_EVENT',
   'COOKIE_PROBE_NAME', 'Caller', 'ClearClientNotificationsInput', 'ClientAccessScope',
-  'ConnectionStatus', 'ConnectorError', 'ConnectorErrorCode', 'CookieOutcome', 'CronHandler',
+  'ConnectionStatus', 'ConnectorError', 'ContractDocumentError', 'ConnectorErrorCode', 'CookieOutcome', 'CronHandler',
   'DEFAULT_LABELS', 'EXCHANGE_REJECTION_HEADER', 'ExchangeRejectedViewer', 'ExchangedSession',
-  'FormatAirtableRecordsOpts', 'GmailSendArgs', 'GmailSendResult', 'IntegrationClient',
+  'FormatAirtableRecordsOpts', 'GenerateAppClientInput', 'GeneratedAppClient', 'GmailSendArgs', 'GmailSendResult', 'IntegrationClient',
   'InternalUserAccess', 'LEGACY_APP_IDS', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
   'MintedBearer', 'NETWORK_CAPTURE_MESSAGE_TYPE', 'NetworkCaptureHeaderFingerprint',
   'NetworkCaptureRecord', 'PAINTED_BEACON_EVENT', 'PAINTED_BEACON_PATH',
@@ -37,13 +37,13 @@ export const NON_CLIENT_EXPORTS = new Set([
   'SlackPostMessageResult', 'TOKEN_EXPIRED_HEADER', 'TokenInvalidError', 'TokenPayload',
   'TtlCache', 'VERIFY_OUTCOME_EVENT', 'VERIFY_PATH', 'VIEWER_BEARER_HEADER',
   'VerifiedIdentity', 'VerifyResult', 'Viewer', 'WorkspaceLabels', 'authUnavailableResponse',
-  'automationActionRoute', 'badRequest', 'bootstrapPortalOrigin', 'buildMimeMessage',
+  'appProxyOptions', 'automationActionRoute', 'badRequest', 'bootstrapPortalOrigin', 'buildMimeMessage',
   'canAccessClient', 'canAccessCompanies', 'classifyExchangeFailure',
   'clearClientNotifications', 'collectHeaders', 'collectXhrResponseHeaders',
   'cookielessReexchangeHeaders', 'cookiesAreBlocked', 'createAssemblyProxy',
   'createAssemblyReexchangeHandler', 'cronRoute',
   'decodeBearer', 'expandClientsByCompany', 'extractPdfText', 'fetchSessionFlags',
-  'findResource', 'formatAirtableRecords', 'getAirtableTableSchema', 'getCapturedRecords',
+  'findResource', 'formatAirtableRecords', 'generateAppClient', 'getAirtableTableSchema', 'getCapturedRecords',
   'getClientAccessScope', 'getCookielessBearer', 'getDownloadUrl', 'getInstalledAppIds', 'getIntegration',
   'getInternalUserAccess', 'getLabels', 'getSessionIdentity', 'getUploadUrl',
   'getVerifiedIdentity', 'gmailSendEmail', 'handlePaintedBeacon', 'handleRouteError',

package/dist/assembly.d.ts

@@ -102,5 +102,22 @@ export declare function getOfflineAssembly(): Promise<AssemblyAPI>;
  * in the same request reuses that bearer.
  */
 export declare function getInstallerAssembly(): Promise<AssemblyAPI>;
+export type AppProxyCaller = 'viewer' | 'installer';
+export interface AppProxyOptions {
+    baseUrl: string;
+    fetch: (input: Request) => Promise<Response>;
+}
+/**
+ * Options for calling another app's API through the platform, shaped for an
+ * `openapi-fetch` client: the generated `client.ts` passes them straight to
+ * `createClient`. The bearer is resolved on every call, so a client built at
+ * module scope still authenticates as the current request.
+ *
+ * `installer` calls as this app, with the same per-request mint as
+ * getInstallerAssembly. `viewer` forwards the signed-in user's verified bearer,
+ * which the platform refuses with `viewer_not_allowed` until it can prove which
+ * person a cross-app call is for.
+ */
+export declare function appProxyOptions(appId: string, caller: AppProxyCaller): AppProxyOptions;
 export declare function getAssemblyForRequest(req: NextRequest): Promise<AssemblyAPI | NextResponse>;
 export {};

package/dist/assembly.js

@@ -1,4 +1,4 @@
-import { assemblyApi } from '@assembly-js/node-sdk';
+import { assemblyApi, OpenAPI } from '@assembly-js/node-sdk';
 import { cookies, headers } from 'next/headers';
 import { after, NextResponse } from 'next/server';
 import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
@@ -332,8 +332,8 @@ export async function getOfflineAssembly() {
 // for the request, so keying on it shares a mint across the page without
 // keeping the bearer after the request ends. A process-wide cache would hand
 // one viewer's app bearer to the next request.
-const installerByRequest = new WeakMap();
-async function mintInstallerAssembly() {
+const installerBearerByRequest = new WeakMap();
+async function mintInstallerBearer() {
     if (!process.env.ASSEMBLY_API_KEY) {
         throw new Error('getInstallerAssembly: ASSEMBLY_API_KEY is not set — cannot mint an app-scoped bearer');
     }
@@ -341,18 +341,11 @@ async function mintInstallerAssembly() {
     if (!minted) {
         throw new Error('getInstallerAssembly: failed to mint an app-scoped bearer from the app API key');
     }
-    return getBearerAssembly(minted.bearer);
+    return minted.bearer;
 }
-/**
- * App-scoped client for use inside a user request (pages, server actions,
- * route handlers). Acts as the installing admin: anything it returns that is
- * shown to a client must be filtered by the caller. Unlike getOfflineAssembly,
- * a viewer cookie does not make this throw — that is the point of it.
- *
- * Does not attach the viewer's bearer. Each request mints once; a second call
- * in the same request reuses that bearer.
- */
-export async function getInstallerAssembly() {
+// Shared by getInstallerAssembly and the installer app proxy, so a request that
+// uses both still mints once.
+async function getInstallerBearer() {
     let headerStore;
     try {
         headerStore = await headers();
@@ -361,21 +354,62 @@ export async function getInstallerAssembly() {
         headerStore = undefined;
     }
     if (!headerStore)
-        return mintInstallerAssembly();
-    const existing = installerByRequest.get(headerStore);
+        return mintInstallerBearer();
+    const existing = installerBearerByRequest.get(headerStore);
     if (existing)
         return existing;
-    const pending = mintInstallerAssembly();
-    installerByRequest.set(headerStore, pending);
+    const pending = mintInstallerBearer();
+    installerBearerByRequest.set(headerStore, pending);
     try {
         return await pending;
     }
     catch (err) {
         // A failed mint must not stick for the rest of the request.
-        installerByRequest.delete(headerStore);
+        installerBearerByRequest.delete(headerStore);
         throw err;
     }
 }
+/**
+ * App-scoped client for use inside a user request (pages, server actions,
+ * route handlers). Acts as the installing admin: anything it returns that is
+ * shown to a client must be filtered by the caller. Unlike getOfflineAssembly,
+ * a viewer cookie does not make this throw — that is the point of it.
+ *
+ * Does not attach the viewer's bearer. Each request mints once; a second call
+ * in the same request reuses that bearer.
+ */
+export async function getInstallerAssembly() {
+    return getBearerAssembly(await getInstallerBearer());
+}
+/**
+ * Options for calling another app's API through the platform, shaped for an
+ * `openapi-fetch` client: the generated `client.ts` passes them straight to
+ * `createClient`. The bearer is resolved on every call, so a client built at
+ * module scope still authenticates as the current request.
+ *
+ * `installer` calls as this app, with the same per-request mint as
+ * getInstallerAssembly. `viewer` forwards the signed-in user's verified bearer,
+ * which the platform refuses with `viewer_not_allowed` until it can prove which
+ * person a cross-app call is for.
+ */
+export function appProxyOptions(appId, caller) {
+    const origin = (trustedBaseUrl ?? OpenAPI.BASE).replace(/\/+$/, '');
+    return {
+        baseUrl: `${origin}/v1/apps/${encodeURIComponent(appId)}/api`,
+        fetch: async (input) => {
+            const bearer = caller === 'installer' ? await getInstallerBearer() : await requireViewerBearer();
+            const request = new Request(input);
+            request.headers.set('Authorization', `Bearer ${bearer}`);
+            return fetch(request);
+        },
+    };
+}
+async function requireViewerBearer() {
+    const viewer = await resolveRequestViewer();
+    if (!viewer)
+        throw new TokenInvalidError('Assembly bearer is required');
+    return viewer.bearer;
+}
 // Returns a request-scoped SDK client authenticated for the current user.
 //
 // Exchange enabled: bearer-only. A bearer the platform verifies (proxy header or

package/dist/codegen.d.ts

@@ -0,0 +1,14 @@
+export declare class ContractDocumentError extends Error {
+    constructor(message: string);
+}
+export interface GenerateAppClientInput {
+    appId: string;
+    document: unknown;
+    contractHash: string;
+}
+export interface GeneratedAppClient {
+    typesDts: string;
+    clientTs: string;
+    readmeMd: string;
+}
+export declare function generateAppClient({ appId, document, contractHash, }: GenerateAppClientInput): Promise<GeneratedAppClient>;

package/dist/codegen.js

@@ -0,0 +1,178 @@
+// Generates a typed client for another app's API from its OpenAPI contract.
+// The sandbox runs this with plain node, so nothing here may import next/* or
+// server-only, and it never touches the network or the app's repo.
+import { createRequire } from 'node:module';
+import openapiTS, { astToString } from 'openapi-typescript';
+// The package version is the generator version: the same document and the same
+// foundation version always produce byte-identical files.
+const FOUNDATION_VERSION = createRequire(import.meta.url)('../package.json').version;
+const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+// Contracts are written as served (`/api/...`) while the client's base URL
+// already ends in `/api`. Same rule as contractTemplate in bin/check-contract-routes.mjs.
+const API_PREFIX = '/api';
+export class ContractDocumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ContractDocumentError';
+    }
+}
+function contractTemplate(contractPath) {
+    let p = contractPath.replace(/\/+$/, '');
+    if (p === API_PREFIX || p.startsWith(`${API_PREFIX}/`))
+        p = p.slice(API_PREFIX.length);
+    return p || '/';
+}
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function forEachRef(node, at, visit) {
+    if (Array.isArray(node)) {
+        node.forEach((child, i) => forEachRef(child, `${at}/${i}`, visit));
+        return;
+    }
+    if (!isObject(node))
+        return;
+    if (typeof node.$ref === 'string')
+        visit(node, at);
+    for (const [key, value] of Object.entries(node))
+        forEachRef(value, `${at}/${key}`, visit);
+}
+const pointerToken = (key) => key.replace(/~/g, '~0').replace(/\//g, '~1');
+function normalizeDocument(document) {
+    if (!isObject(document))
+        throw new ContractDocumentError('contract document must be a JSON object');
+    if (typeof document.openapi !== 'string') {
+        throw new ContractDocumentError('contract document is missing "openapi"');
+    }
+    if (!document.openapi.startsWith('3.')) {
+        throw new ContractDocumentError(`contract document "openapi" must be 3.x, got "${document.openapi}"`);
+    }
+    if (!isObject(document.paths))
+        throw new ContractDocumentError('contract document is missing "paths"');
+    let external;
+    forEachRef(document, '#', (holder, at) => {
+        if (!external && !holder.$ref.startsWith('#'))
+            external = `${at}/$ref`;
+    });
+    if (external)
+        throw new ContractDocumentError(`contract document has an external "$ref" at ${external}`);
+    const copy = structuredClone(document);
+    const paths = {};
+    const renamed = new Map();
+    for (const [documented, item] of Object.entries(copy.paths)) {
+        const template = contractTemplate(documented);
+        if (template in paths) {
+            throw new ContractDocumentError(`contract document "paths" has two entries for ${template}`);
+        }
+        paths[template] = item;
+        if (template !== documented) {
+            renamed.set(`#/paths/${pointerToken(documented)}`, `#/paths/${pointerToken(template)}`);
+        }
+    }
+    // A $ref into a renamed path item would otherwise point at a key that no longer exists.
+    forEachRef(copy, '#', (holder) => {
+        for (const [from, to] of renamed) {
+            if (holder.$ref === from || holder.$ref.startsWith(`${from}/`)) {
+                holder.$ref = to + holder.$ref.slice(from.length);
+                break;
+            }
+        }
+    });
+    return { ...copy, paths };
+}
+// openapi-typescript names an `operations` entry after each operationId; without
+// it the operation is inlined under its path, so the (verb, path) pair stays the
+// only identity the types expose.
+function stripOperationIds(paths) {
+    for (const item of Object.values(paths)) {
+        if (!isObject(item))
+            continue;
+        for (const method of HTTP_METHODS) {
+            const op = item[method];
+            if (isObject(op))
+                delete op.operationId;
+        }
+    }
+}
+const PATHS_POINTER = '#/paths/';
+const decodePointerToken = (token) => token.replace(/~1/g, '/').replace(/~0/g, '~');
+// A path item that is a $ref into another path still serves that path's operations under its own key.
+function resolvePathItem(paths, item) {
+    if (!isObject(item) || typeof item.$ref !== 'string' || !item.$ref.startsWith(PATHS_POINTER))
+        return item;
+    return paths[decodePointerToken(item.$ref.slice(PATHS_POINTER.length))];
+}
+function operationsOf(paths) {
+    const ops = [];
+    for (const [path, entry] of Object.entries(paths)) {
+        const item = resolvePathItem(paths, entry);
+        if (!isObject(item))
+            continue;
+        for (const method of HTTP_METHODS) {
+            const op = item[method];
+            if (!isObject(op))
+                continue;
+            ops.push({
+                method: method.toUpperCase(),
+                path,
+                operationId: typeof op.operationId === 'string' ? op.operationId : undefined,
+                summary: typeof op.summary === 'string' ? op.summary : undefined,
+            });
+        }
+    }
+    return ops;
+}
+const header = (contractHash) => `// Generated by @assembly-js/app-foundation ${FOUNDATION_VERSION} from contract ${contractHash}. Do not edit.\n`;
+// Fixed apart from the app id, so every generated client behaves the same way
+// and all auth mechanics stay in the package.
+function renderClient(appId) {
+    return `// Generated by @assembly-js/app-foundation ${FOUNDATION_VERSION}. Do not edit.
+import createClient from 'openapi-fetch';
+import { appProxyOptions } from '@assembly-js/app-foundation/server';
+import type { paths } from './types.js';
+
+export const APP_ID = ${JSON.stringify(appId)};
+
+// Calls as this app. Use it from pages, server actions, routes, cron and webhooks.
+export const installerClient = createClient<paths>(appProxyOptions(APP_ID, 'installer'));
+
+// Calls as the signed-in person. Refused with viewer_not_allowed for now.
+export const viewerClient = createClient<paths>(appProxyOptions(APP_ID, 'viewer'));
+`;
+}
+const cell = (s) => s.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+function renderReadme(appId, contractHash, paths) {
+    const rows = operationsOf(paths).map((op) => `| \`${op.method}\` | \`${cell(op.path)}\` | ${cell(op.operationId ?? '')} | ${cell(op.summary ?? '')} |`);
+    return `# Client for app \`${appId}\`
+
+Generated by \`@assembly-js/app-foundation\` ${FOUNDATION_VERSION} from contract \`${contractHash}\`. Do not edit these files; they are regenerated when the contract changes.
+
+Call an operation by its verb and path, exactly as listed below. The path and its parameters are type-checked against the contract.
+
+\`\`\`ts
+import { installerClient } from './client.js';
+
+const { data, error } = await installerClient.GET('/projects/{id}', {
+  params: { path: { id } },
+});
+\`\`\`
+
+- \`installerClient\` calls as this app. Use it from pages, server actions, routes, cron and webhooks, and filter anything you show to a client.
+- \`viewerClient\` calls as the signed-in person. The platform refuses it with \`viewer_not_allowed\` until it can prove which person the call is for, so use \`installerClient\` for now.
+
+## Operations
+
+| Verb | Path | Operation | Summary |
+|---|---|---|---|
+${rows.join('\n')}
+`;
+}
+export async function generateAppClient({ appId, document, contractHash, }) {
+    const normalized = normalizeDocument(document);
+    const readmeMd = renderReadme(appId, contractHash, normalized.paths);
+    stripOperationIds(normalized.paths);
+    const ast = await openapiTS(normalized, { silent: true });
+    return {
+        typesDts: header(contractHash) + astToString(ast),
+        clientTs: renderClient(appId),
+        readmeMd,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -31,11 +31,15 @@
     "./next": {
       "types": "./dist/next.d.ts",
       "default": "./dist/next.js"
+    },
+    "./codegen": {
+      "types": "./dist/codegen.d.ts",
+      "default": "./dist/codegen.js"
     }
   },
   "scripts": {
     "build": "tsc && tsc-alias && esbuild src/scripts.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/scripts.js",
-    "test": "npm run build && bun test --path-ignore-patterns='**/proxy.test.ts' --path-ignore-patterns='**/reexchange.test.ts' && bun test ./src/proxy.test.ts && bun test ./src/reexchange.test.ts && tsc -p tsconfig.replace-rows.json",
+    "test": "npm run build && bun test --path-ignore-patterns='**/proxy.test.ts' --path-ignore-patterns='**/reexchange.test.ts' && bun test ./src/proxy.test.ts && bun test ./src/reexchange.test.ts && tsc -p tsconfig.replace-rows.json && node scripts/emit-codegen-fixture.mjs && tsc -p tsconfig.codegen.json",
     "prepublishOnly": "npm run build && npm run verify:dist && npm run verify:bin",
     "verify:dist": "node scripts/verify-dist-resolves.mjs",
     "verify:bin": "node scripts/verify-bin.mjs"
@@ -71,6 +75,8 @@
   "author": "Assembly",
   "license": "MIT",
   "dependencies": {
+    "openapi-fetch": "^0.17.0",
+    "openapi-typescript": "^7.13.0",
     "unpdf": "^1.9.1"
   }
 }