@assembly-js/app-foundation 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -15,7 +15,15 @@ from every bullet except `[guidance]`, agent work from the check scripts those `
 bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
 
 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.
+`bin/check-*.mjs` script. Sections are written by the release workflow from the files in `changes/`,
+not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
+`bump: minor` change file.
+
+## 0.2.5
+- [new] The client-call scan no longer reports reading the session's token details, a client's allowed fetch routes, or a harmless local namespace import as breaking; nothing in the app changes.
+
+## 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/client-safe-sdk-methods.mjs

@@ -1,28 +1,38 @@
-// The routes a client bearer may keep calling once clients stop acting as admin,
-// as SDK method names (the SDK is flat: `retrieveClient`, not `clients.retrieve`).
+// The routes a client bearer may keep calling once clients stop acting as admin.
 // Mirrors every route the platform marks with ClientAccessOpen, ClientAccessSelf or
 // ClientAccessGuarded under backend/platform-api; scan-client-calls.test.mjs fails when
-// the marker count drifts from this list.
-//
-//   GET  /v1/me                         -> retrieveMe
-//   GET  /v1/clients/{id}               -> retrieveClient (the client's own record only)
-//   GET  /v1/notifications              -> listNotifications
-//   POST /v1/notifications/{id}/read    -> markNotificationRead
-//   POST /v1/notifications/{id}/unread  -> markNotificationUnread
-//   GET  /v1/session/flags              -> no SDK method yet, so nothing to list; add it
-//                                          here when the SDK gains one.
+// the marker count drifts from this table. The SDK method list, the count of routes with
+// no SDK method and the `fetch` route check are all derived from the one table, so they
+// cannot disagree. The SDK is flat: `retrieveClient`, not `clients.retrieve`.
 //
+// A route with no SDK method yet (`sdkMethod: null`) is reachable only through `fetch`;
+// give it a method here when the SDK gains one.
+export const CLIENT_SAFE_ROUTES = Object.freeze([
+  { method: 'GET', path: '/v1/clients/{id}', sdkMethod: 'retrieveClient' }, // the client's own record only
+  { method: 'GET', path: '/v1/me', sdkMethod: 'retrieveMe' },
+  { method: 'GET', path: '/v1/notifications', sdkMethod: 'listNotifications' },
+  { method: 'POST', path: '/v1/notifications/{id}/read', sdkMethod: 'markNotificationRead' },
+  { method: 'POST', path: '/v1/notifications/{id}/unread', sdkMethod: 'markNotificationUnread' },
+  { method: 'GET', path: '/v1/session/flags', sdkMethod: null },
+].map(Object.freeze));
+
 // retrieveClient is allowlisted by name: whether the id is the viewer's own is a runtime
 // fact a static scan cannot see. The notification routes are open to clients, and the
 // platform pins a client caller to their own notifications. Creating, retrieving and
 // deleting a notification stay off the list: those routes are not open to clients.
-export const CLIENT_SAFE_SDK_METHODS = Object.freeze([
-  'retrieveClient',
-  'retrieveMe',
-  'listNotifications',
-  'markNotificationRead',
-  'markNotificationUnread',
-]);
+export const CLIENT_SAFE_SDK_METHODS = Object.freeze(
+  CLIENT_SAFE_ROUTES.flatMap((r) => (r.sdkMethod ? [r.sdkMethod] : [])),
+);
+
+// Marked client-safe routes that no SDK method reaches yet.
+export const CLIENT_SAFE_ROUTES_WITHOUT_SDK_METHOD = CLIENT_SAFE_ROUTES.filter((r) => !r.sdkMethod).length;
+
+// `{id}` stands for exactly one non-empty path segment.
+// The id segment excludes `.` and `%` so `.`, `..` and `%2e` forms that URL normalisation resolves elsewhere fail closed.
+const routePattern = (route) =>
+  new RegExp(`^${route.path.split('/').map((seg) => (seg === '{id}' ? '[A-Za-z0-9_-]+' : seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))).join('/')}$`);
+const ROUTE_MATCHERS = CLIENT_SAFE_ROUTES.map((route) => ({ method: route.method, pattern: routePattern(route) }));
 
-// Marked client-safe routes that no SDK method reaches yet (the list above says which).
-export const CLIENT_SAFE_ROUTES_WITHOUT_SDK_METHOD = 1;
+// Whether `fetch(path, { method })` hits a client-safe route; `path` has no query string.
+export const isClientSafeRoute = (method, path) =>
+  ROUTE_MATCHERS.some((m) => m.method === method.toUpperCase() && m.pattern.test(path));

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/bin/scan-client-calls.mjs

@@ -23,7 +23,7 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { CLIENT_SAFE_SDK_METHODS } from './client-safe-sdk-methods.mjs';
+import { CLIENT_SAFE_SDK_METHODS, isClientSafeRoute } from './client-safe-sdk-methods.mjs';
 import { NON_CLIENT_EXPORTS } from './foundation-exports.mjs';
 import {
   EXCLUDING_WRAPPERS,
@@ -94,6 +94,11 @@ export const SDK_METHOD_SHAPE = /^(?:(?:list|retrieve|create|update|delete|send|
 // `fetch` and `sendWebhook` are the flat client methods the codegen services do not declare, and
 // the verb pattern cannot match; `fetch` is how apps reach non-SDK endpoints such as the AI proxy.
 export const SDK_METHOD_EXTRAS = new Set(['fetch', 'sendWebhook']);
+// SDK methods that only read the token already in hand, so a viewer calling them reaches no endpoint.
+// Skipped at projection, not collection, so per-file facts stay reusable.
+const NON_NETWORK_SDK_METHODS = new Set(['getTokenPayload']);
+const FETCH_METHOD = 'fetch';
+const DEFAULT_FETCH_HTTP_METHOD = 'GET';
 const SDK_SERVICES_DIR = '../codegen/api/services';
 const SDK_SERVICE_FILE = /Service\.d\.ts$/;
 const SDK_STATIC_METHOD = /static (\w+)\(/g;
@@ -178,7 +183,9 @@ function scriptKind(ts, file) {
 // `calls` are every method call on a tagged receiver, `defeaters` are the
 // constructs that stop the scan following a viewer receiver, `specifiers` the
 // module specifiers it imports.
-export function collectFileFacts(ts, file, text, sdkMethods = null) {
+// `localExportsFactory(spec)` says whether a local module exports an SDK factory; without it every
+// local namespace import is tracked.
+export function collectFileFacts(ts, file, text, sdkMethods = null, localExportsFactory = null) {
   const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(ts, file));
   const calls = [];
   const defeaters = [];
@@ -194,6 +201,26 @@ export function collectFileFacts(ts, file, text, sdkMethods = null) {
 
   const isLiteralText = (n) => n && (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n));
 
+  // The literal route and HTTP method of a `fetch(path, init?)` call, or null when either is not
+  // literal, so the projection fails closed. A missing method option is a GET.
+  const fetchRoute = (call) => {
+    const [pathArg, init] = call.arguments;
+    if (!isLiteralText(pathArg)) return null;
+    let method = DEFAULT_FETCH_HTTP_METHOD;
+    if (init) {
+      if (!ts.isObjectLiteralExpression(init)) return null;
+      for (const prop of init.properties) {
+        if (ts.isSpreadAssignment(prop) || (prop.name && ts.isComputedPropertyName(prop.name))) return null;
+        if (prop.name?.text !== 'method') continue;
+        if (!ts.isPropertyAssignment(prop) || !isLiteralText(prop.initializer)) return null;
+        method = prop.initializer.text;
+      }
+    }
+    // The SDK prepends the slash a path is missing, so `v1/me` requests `/v1/me`.
+    const routePath = pathArg.text.startsWith('/') ? pathArg.text : `/${pathArg.text}`;
+    return { path: routePath.replace(/[?#].*$/, ''), method };
+  };
+
   // --- imports ------------------------------------------------------------
   const acceptsFactories = (spec) => LOCAL_SPECIFIER.test(spec) || SDK_SPECIFIER.test(spec);
   for (const stmt of sf.statements) {
@@ -214,7 +241,12 @@ export function collectFileFacts(ts, file, text, sdkMethods = null) {
         }
       }
       if (!bindings || !acceptsFactories(spec)) continue;
-      if (ts.isNamespaceImport(bindings)) namespaceLocals.add(bindings.name.text);
+      if (ts.isNamespaceImport(bindings)) {
+        // A namespace of a module with no factory (a drizzle schema) cannot hand out a client.
+        if (!localExportsFactory || !LOCAL_SPECIFIER.test(spec) || localExportsFactory(spec)) {
+          namespaceLocals.add(bindings.name.text);
+        }
+      }
       else {
         for (const el of bindings.elements) {
           const imported = (el.propertyName ?? el.name).text;
@@ -337,7 +369,12 @@ export function collectFileFacts(ts, file, text, sdkMethods = null) {
     const parent = cur.parent;
     if (!parent) return;
 
-    const recordCall = (method, at) => calls.push({ line: lineOf(sf, at), method, provenance });
+    const recordCall = (method, at, call) => calls.push({
+      line: lineOf(sf, at),
+      method,
+      provenance,
+      ...(method === FETCH_METHOD ? { route: fetchRoute(call) } : {}),
+    });
 
     if (ts.isPropertyAccessExpression(parent) && parent.expression === cur) {
       const call = parent.parent;
@@ -352,14 +389,14 @@ export function collectFileFacts(ts, file, text, sdkMethods = null) {
         if (viewer) defeat(parent, DEFEATER.PROMISE_CHAIN);
         return;
       }
-      recordCall(name, parent.name);
+      recordCall(name, parent.name, call);
       return;
     }
     if (ts.isElementAccessExpression(parent) && parent.expression === cur) {
       const arg = parent.argumentExpression;
       const call = parent.parent;
       if (isLiteralText(arg) && call && ts.isCallExpression(call) && call.expression === parent) {
-        recordCall(arg.text, arg);
+        recordCall(arg.text, arg, call);
       } else if (viewer) defeat(parent, DEFEATER.DYNAMIC_ACCESS);
       return;
     }
@@ -880,9 +917,28 @@ export function createAnalysis(root) {
     return null;
   };
 
+  // Over-approximates (a mention plus any `export`): tracking too much only costs a defeater.
+  const FACTORY_NAME = new RegExp(`\\b(?:${[...Object.keys(SDK_FACTORIES), AFTER_ASSEMBLY, REQUEST_CONTEXT].join('|')})\\b`);
+  const STAR_REEXPORT = /export\s*(?:\*(?:\s*as\s+\w+)?|\{[^}]*\})\s*from\s*['"]([^'"]+)['"]/g;
+  const exportsFactory = (file, seen = new Set()) => {
+    if (seen.has(file)) return false;
+    seen.add(file);
+    const text = read(file);
+    if (/\bexport\b/.test(text) && FACTORY_NAME.test(text)) return true;
+    return [...text.matchAll(STAR_REEXPORT)].some(([, spec]) => {
+      if (SDK_SPECIFIER.test(spec)) return true;
+      const target = LOCAL_SPECIFIER.test(spec) ? resolve(file, spec) : null;
+      return target ? exportsFactory(target, seen) : false;
+    });
+  };
+
   const factsFor = (file) => {
     if (!facts.has(file)) {
-      const raw = collectFileFacts(ts, file, read(file), sdkMethods);
+      const localExportsFactory = (spec) => {
+        const target = resolve(file, spec);
+        return target ? exportsFactory(target) : true;
+      };
+      const raw = collectFileFacts(ts, file, read(file), sdkMethods, localExportsFactory);
       const imports = [];
       const defeaters = [...raw.defeaters];
       for (const spec of raw.specifiers) {
@@ -938,7 +994,9 @@ export function projectClientReachable(analysis, allowlist = CLIENT_SAFE_SDK_MET
     const gated = [...reaching].every((e) => gatedSet.has(e));
     const { calls, defeaters } = analysis.facts(file);
     for (const c of calls) {
-      if (c.provenance === PROVENANCE_VIEWER && !allowed.has(c.method)) {
+      if (c.provenance !== PROVENANCE_VIEWER || NON_NETWORK_SDK_METHODS.has(c.method)) continue;
+      if (c.method === FETCH_METHOD && c.route && isClientSafeRoute(c.route.method, c.route.path)) continue;
+      if (!allowed.has(c.method)) {
         findings.push({ file, line: c.line, method: c.method, provenance: c.provenance, entry, gated });
       }
     }

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.5",
   "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"
   }
 }