Add OAuth-protected MCP server with generated API client packages
This commit is contained in:
1 parent
26e236c95c
commit
65bf19e067
235 files changed
+33755
-3199
No files matched your search
@@ -0,0 +1,335 @@
|
||||
/**
|
||||
* Generates `packages/api-client/src/generated/*` from `public/openapi.json`.
|
||||
*
|
||||
* pnpm generate:api-client write generated files
|
||||
* pnpm generate:api-client --check fail if generated files are stale
|
||||
*
|
||||
* The OpenAPI document is the single source of truth: operation IDs become client method names,
|
||||
* parameter/body/response schemas become input/output types. Never edit generated files by hand.
|
||||
*/
|
||||
import { execFile } from 'node:child_process';
|
||||
import { mkdir, readFile, writeFile } from 'node:fs/promises';
|
||||
import path from 'node:path';
|
||||
import { promisify } from 'node:util';
|
||||
import openapiTS, { astToString } from 'openapi-typescript';
|
||||
|
||||
const execFileAsync = promisify(execFile);
|
||||
const projectRoot = process.cwd();
|
||||
const specFile = path.join(projectRoot, 'public', 'openapi.json');
|
||||
const outputDir = path.join(projectRoot, 'packages', 'api-client', 'src', 'generated');
|
||||
const check = process.argv.includes('--check');
|
||||
|
||||
const HEADER = `// GENERATED FILE. DO NOT EDIT.
|
||||
// Source: public/openapi.json — regenerate with \`pnpm generate:api\`.
|
||||
`;
|
||||
|
||||
const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const;
|
||||
type HttpMethod = (typeof HTTP_METHODS)[number];
|
||||
const INCLUDED_AUDIENCES = new Set(['public', 'collect']);
|
||||
const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
|
||||
|
||||
interface OpenApiParameter {
|
||||
name: string;
|
||||
in: 'path' | 'query' | 'header' | 'cookie';
|
||||
required?: boolean;
|
||||
}
|
||||
|
||||
interface OpenApiOperation {
|
||||
operationId?: string;
|
||||
summary?: string;
|
||||
description?: string;
|
||||
tags?: string[];
|
||||
parameters?: OpenApiParameter[];
|
||||
requestBody?: { required?: boolean };
|
||||
'x-umami-audience'?: string;
|
||||
'x-umami-oauth-scope'?: string;
|
||||
}
|
||||
|
||||
interface OpenApiDocument {
|
||||
info: { version: string };
|
||||
paths: Record<string, Record<string, OpenApiOperation>>;
|
||||
}
|
||||
|
||||
interface OperationDefinition {
|
||||
operationId: string;
|
||||
method: HttpMethod;
|
||||
path: string;
|
||||
summary: string;
|
||||
description?: string;
|
||||
tags: string[];
|
||||
pathParams: string[];
|
||||
queryParams: string[];
|
||||
requiredQueryParams: string[];
|
||||
hasBody: boolean;
|
||||
bodyRequired: boolean;
|
||||
scope?: string;
|
||||
}
|
||||
|
||||
function collectOperations(document: OpenApiDocument): OperationDefinition[] {
|
||||
const operations: OperationDefinition[] = [];
|
||||
const seen = new Map<string, string>();
|
||||
const errors: string[] = [];
|
||||
|
||||
for (const [route, pathItem] of Object.entries(document.paths)) {
|
||||
for (const method of HTTP_METHODS) {
|
||||
const operation = pathItem[method];
|
||||
|
||||
if (!operation) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const key = `${method.toUpperCase()} ${route}`;
|
||||
const audience = operation['x-umami-audience'] ?? 'public';
|
||||
|
||||
if (!INCLUDED_AUDIENCES.has(audience)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const operationId = operation.operationId;
|
||||
|
||||
if (!operationId) {
|
||||
errors.push(`${key} has no operationId.`);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!IDENTIFIER.test(operationId)) {
|
||||
errors.push(`${key} has an operationId that is not a valid identifier: ${operationId}`);
|
||||
continue;
|
||||
}
|
||||
|
||||
const previous = seen.get(operationId);
|
||||
|
||||
if (previous) {
|
||||
errors.push(`Duplicate operationId ${operationId}: ${previous} and ${key}`);
|
||||
continue;
|
||||
}
|
||||
|
||||
seen.set(operationId, key);
|
||||
|
||||
const parameters = operation.parameters ?? [];
|
||||
const pathParams = [...route.matchAll(/\{([^}]+)}/g)].map(match => match[1]);
|
||||
const queryParams = parameters
|
||||
.filter(parameter => parameter.in === 'query')
|
||||
.map(parameter => parameter.name);
|
||||
const requiredQueryParams = parameters
|
||||
.filter(parameter => parameter.in === 'query' && parameter.required)
|
||||
.map(parameter => parameter.name);
|
||||
|
||||
operations.push({
|
||||
operationId,
|
||||
method,
|
||||
path: route,
|
||||
summary: operation.summary ?? operationId,
|
||||
description: operation.description,
|
||||
tags: operation.tags ?? [],
|
||||
pathParams,
|
||||
queryParams,
|
||||
requiredQueryParams,
|
||||
hasBody: !!operation.requestBody,
|
||||
bodyRequired: operation.requestBody?.required !== false && !!operation.requestBody,
|
||||
scope: operation['x-umami-oauth-scope'],
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (errors.length) {
|
||||
throw new Error(`Cannot generate API client:\n${errors.map(error => `- ${error}`).join('\n')}`);
|
||||
}
|
||||
|
||||
return operations.sort((left, right) => left.operationId.localeCompare(right.operationId));
|
||||
}
|
||||
|
||||
function jsDoc(lines: (string | undefined)[]) {
|
||||
const content = lines.filter((line): line is string => !!line);
|
||||
|
||||
if (!content.length) {
|
||||
return '';
|
||||
}
|
||||
|
||||
return ` /**\n${content.map(line => ` * ${line.replace(/\*\//g, '* /')}`).join('\n')}\n */\n`;
|
||||
}
|
||||
|
||||
function renderOperations(operations: OperationDefinition[], version: string) {
|
||||
const table = operations
|
||||
.map(operation => {
|
||||
const fields = [
|
||||
`operationId: '${operation.operationId}'`,
|
||||
`method: '${operation.method}'`,
|
||||
`path: '${operation.path}'`,
|
||||
`pathParams: [${operation.pathParams.map(name => `'${name}'`).join(', ')}]`,
|
||||
`queryParams: [${operation.queryParams.map(name => `'${name}'`).join(', ')}]`,
|
||||
`hasBody: ${operation.hasBody}`,
|
||||
...(operation.scope ? [`scope: '${operation.scope}'`] : []),
|
||||
];
|
||||
|
||||
return ` ${operation.operationId}: { ${fields.join(', ')} },`;
|
||||
})
|
||||
.join('\n');
|
||||
|
||||
const methods = operations
|
||||
.map(operation => {
|
||||
const inputOptional =
|
||||
!operation.pathParams.length &&
|
||||
!operation.requiredQueryParams.length &&
|
||||
!operation.bodyRequired;
|
||||
const doc = jsDoc([
|
||||
operation.summary,
|
||||
operation.description ? '' : undefined,
|
||||
operation.description,
|
||||
'',
|
||||
`\`${operation.method.toUpperCase()} ${operation.path}\``,
|
||||
operation.scope ? `OAuth scope: \`${operation.scope}\`` : undefined,
|
||||
]);
|
||||
const id = operation.operationId;
|
||||
|
||||
return `${doc} ${id}(input${inputOptional ? '?' : ''}: OperationInput<'${id}'>, options?: RequestOptions): Promise<OperationOutput<'${id}'>> {
|
||||
return this.execute('${id}', input, options);
|
||||
}`;
|
||||
})
|
||||
.join('\n\n');
|
||||
|
||||
return `${HEADER}
|
||||
import type { RequestOptions } from '../types';
|
||||
import type { components, operations as OperationTypes } from './types';
|
||||
|
||||
export const API_VERSION = '${version}';
|
||||
|
||||
export type HttpMethod = ${HTTP_METHODS.map(method => `'${method}'`).join(' | ')};
|
||||
|
||||
export interface OperationDefinition {
|
||||
readonly operationId: string;
|
||||
readonly method: HttpMethod;
|
||||
readonly path: string;
|
||||
readonly pathParams: readonly string[];
|
||||
readonly queryParams: readonly string[];
|
||||
readonly hasBody: boolean;
|
||||
readonly scope?: string;
|
||||
}
|
||||
|
||||
export const operations = {
|
||||
${table}
|
||||
} as const satisfies Record<string, OperationDefinition>;
|
||||
|
||||
export type OperationId = keyof typeof operations;
|
||||
|
||||
export type Schemas = components['schemas'];
|
||||
|
||||
type Clean<T> = [T] extends [never] ? Record<never, never> : T;
|
||||
|
||||
type OperationPathParams<K extends OperationId> = OperationTypes[K]['parameters'] extends {
|
||||
path: infer P;
|
||||
}
|
||||
? Clean<P>
|
||||
: Record<never, never>;
|
||||
|
||||
type OperationQuery<K extends OperationId> = Clean<
|
||||
NonNullable<OperationTypes[K]['parameters']['query']>
|
||||
>;
|
||||
|
||||
type OperationBody<K extends OperationId> = OperationTypes[K] extends { requestBody?: infer R }
|
||||
? NonNullable<R> extends { content: { 'application/json': infer B } }
|
||||
? Clean<B>
|
||||
: Record<never, never>
|
||||
: Record<never, never>;
|
||||
|
||||
export type OperationInput<K extends OperationId> = OperationPathParams<K> &
|
||||
OperationQuery<K> &
|
||||
OperationBody<K> &
|
||||
Record<string, unknown>;
|
||||
|
||||
export type OperationOutput<K extends OperationId> = OperationTypes[K]['responses'] extends {
|
||||
200: { content: { 'application/json': infer R } };
|
||||
}
|
||||
? R
|
||||
: unknown;
|
||||
|
||||
export abstract class GeneratedUmamiClient {
|
||||
protected abstract execute<K extends OperationId>(
|
||||
operationId: K,
|
||||
input: Record<string, unknown> | undefined,
|
||||
options?: RequestOptions,
|
||||
): Promise<OperationOutput<K>>;
|
||||
|
||||
${methods}
|
||||
}
|
||||
`;
|
||||
}
|
||||
|
||||
async function format(files: string[]) {
|
||||
const biome = path.join(
|
||||
projectRoot,
|
||||
'node_modules',
|
||||
'.bin',
|
||||
process.platform === 'win32' ? 'biome.cmd' : 'biome',
|
||||
);
|
||||
|
||||
await execFileAsync(biome, ['format', '--write', ...files], {
|
||||
cwd: projectRoot,
|
||||
shell: process.platform === 'win32',
|
||||
});
|
||||
}
|
||||
|
||||
async function readExisting(file: string) {
|
||||
try {
|
||||
return await readFile(file, 'utf8');
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
const document = JSON.parse(await readFile(specFile, 'utf8')) as OpenApiDocument;
|
||||
const operations = collectOperations(document);
|
||||
const ast = await openapiTS(document as never, {
|
||||
alphabetize: true,
|
||||
exportType: false,
|
||||
});
|
||||
|
||||
const files: Record<string, string> = {
|
||||
'types.ts': `${HEADER}\n${astToString(ast)}`,
|
||||
'operations.ts': renderOperations(operations, document.info.version),
|
||||
};
|
||||
|
||||
const tmpDir = path.join(outputDir, check ? '.check' : '');
|
||||
|
||||
await mkdir(tmpDir, { recursive: true });
|
||||
|
||||
const written: string[] = [];
|
||||
|
||||
for (const [name, content] of Object.entries(files)) {
|
||||
const file = path.join(tmpDir, name);
|
||||
await writeFile(file, content, 'utf8');
|
||||
written.push(file);
|
||||
}
|
||||
|
||||
await format(written);
|
||||
|
||||
if (check) {
|
||||
let stale = false;
|
||||
|
||||
for (const name of Object.keys(files)) {
|
||||
const [expected, actual] = await Promise.all([
|
||||
readFile(path.join(tmpDir, name), 'utf8'),
|
||||
readExisting(path.join(outputDir, name)),
|
||||
]);
|
||||
|
||||
if (expected !== actual) {
|
||||
console.error(
|
||||
`packages/api-client/src/generated/${name} is stale. Run \`pnpm generate:api\`.`,
|
||||
);
|
||||
stale = true;
|
||||
}
|
||||
}
|
||||
|
||||
const { rm } = await import('node:fs/promises');
|
||||
await rm(tmpDir, { recursive: true, force: true });
|
||||
|
||||
if (stale) {
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(`API client is up to date (${operations.length} operations).`);
|
||||
} else {
|
||||
console.log(
|
||||
`Generated ${operations.length} operations into ${path.relative(projectRoot, outputDir)}.`,
|
||||
);
|
||||
}
|
||||
Reference in new issue
Block a user