@beignet/core 0.0.1

package/src/openapi/index.ts

@@ -0,0 +1,865 @@
+/**
+ * @beignet/core/openapi
+ *
+ * OpenAPI 3.1 generation from Beignet contracts
+ */
+
+import { type ZodTypeAny, z } from "zod";
+import {
+  type AnyContract,
+  type ContractLike,
+  getContractHeaderSchemas,
+  methodSupportsRequestBody,
+  parsePathTemplate,
+  resolveContract,
+  STANDARD_ERROR_RESPONSE_SCHEMA,
+} from "../contracts";
+import {
+  createZodIntrospector,
+  type SchemaIntrospector,
+} from "./schema-introspector";
+
+// Re-export the introspector types for consumers who want custom implementations
+export {
+  createZodIntrospector,
+  type SchemaIntrospector,
+} from "./schema-introspector";
+
+/**
+ * OpenAPI 3.1 Info Object
+ */
+export interface OpenAPIInfo {
+  title: string;
+  version: string;
+  description?: string;
+  termsOfService?: string;
+  contact?: {
+    name?: string;
+    url?: string;
+    email?: string;
+  };
+  license?: {
+    name: string;
+    url?: string;
+  };
+}
+
+/**
+ * OpenAPI 3.1 Server Object
+ */
+export interface OpenAPIServer {
+  url: string;
+  description?: string;
+  variables?: Record<
+    string,
+    {
+      default: string;
+      enum?: string[];
+      description?: string;
+    }
+  >;
+}
+
+/**
+ * OpenAPI 3.1 Security Scheme Object
+ */
+export type OpenAPISecurityScheme =
+  | {
+      type: "apiKey";
+      name: string;
+      in: "query" | "header" | "cookie";
+      description?: string;
+    }
+  | {
+      type: "http";
+      scheme: string;
+      bearerFormat?: string;
+      description?: string;
+    }
+  | {
+      type: "oauth2";
+      flows: Record<string, unknown>;
+      description?: string;
+    }
+  | {
+      type: "openIdConnect";
+      openIdConnectUrl: string;
+      description?: string;
+    };
+
+/**
+ * Schema or Reference object for OpenAPI
+ */
+export type SchemaObject = Record<string, unknown>;
+export type ReferenceObject = { $ref: string };
+
+/**
+ * OpenAPI Parameter Object
+ */
+export interface ParameterObject {
+  name: string;
+  in: "path" | "query" | "header" | "cookie";
+  required?: boolean;
+  schema?: SchemaObject | ReferenceObject;
+  description?: string;
+  deprecated?: boolean;
+}
+
+/**
+ * OpenAPI Request Body Object
+ */
+export interface RequestBodyObject {
+  required?: boolean;
+  description?: string;
+  content: Record<
+    string,
+    {
+      schema?: SchemaObject | ReferenceObject;
+    }
+  >;
+}
+
+/**
+ * OpenAPI Response Object
+ */
+export interface ResponseObject {
+  description: string;
+  content?: Record<
+    string,
+    {
+      schema?: SchemaObject | ReferenceObject;
+      examples?: Record<
+        string,
+        {
+          summary?: string;
+          value?: unknown;
+        }
+      >;
+    }
+  >;
+}
+
+/**
+ * OpenAPI Operation Object
+ */
+export interface OperationObject {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  deprecated?: boolean;
+  externalDocs?: {
+    description?: string;
+    url: string;
+  };
+  security?: Array<Record<string, string[]>>;
+  parameters?: ParameterObject[];
+  requestBody?: RequestBodyObject;
+  responses: Record<string, ResponseObject>;
+}
+
+/**
+ * OpenAPI Path Item Object
+ */
+export interface PathItemObject {
+  get?: OperationObject;
+  post?: OperationObject;
+  put?: OperationObject;
+  patch?: OperationObject;
+  delete?: OperationObject;
+  head?: OperationObject;
+  options?: OperationObject;
+}
+
+/**
+ * OpenAPI Paths Object
+ */
+export type PathsObject = Record<string, PathItemObject>;
+
+/**
+ * OpenAPI Components Object
+ */
+export interface ComponentsObject {
+  schemas?: Record<string, SchemaObject>;
+  securitySchemes?: Record<string, OpenAPISecurityScheme>;
+}
+
+/**
+ * OpenAPI 3.1 Document
+ */
+export interface OpenAPIObject {
+  openapi: "3.1.0";
+  info: OpenAPIInfo;
+  servers?: OpenAPIServer[];
+  paths: PathsObject;
+  components?: ComponentsObject;
+  security?: Array<Record<string, string[]>>;
+}
+
+/**
+ * Options for generating OpenAPI spec
+ */
+export interface OpenAPIGeneratorOptions {
+  /** API title */
+  title: string;
+  /** API version */
+  version: string;
+  /** API description */
+  description?: string;
+  /** Server configurations */
+  servers?: OpenAPIServer[];
+  /** Media type for JSON content (default: application/json) */
+  jsonMediaType?: string;
+  /** Security schemes for authentication */
+  securitySchemes?: Record<string, OpenAPISecurityScheme>;
+  /** Global security requirements */
+  security?: Array<Record<string, string[]>>;
+  /**
+   * Schema introspector for reading metadata from schema objects.
+   * Defaults to a Zod introspector. Provide a custom implementation
+   * to support other schema libraries.
+   */
+  schemaIntrospector?: SchemaIntrospector;
+}
+
+/**
+ * Internal state for generator
+ */
+type GeneratorState = {
+  components: ComponentsObject;
+  jsonMediaType: string;
+  introspector: SchemaIntrospector;
+};
+
+type SchemaIO = "input" | "output";
+
+/**
+ * Type for contracts that can be passed to the generator.
+ * Accepts both ContractBuilder instances and plain HttpContractConfig objects.
+ */
+export type ContractInput = ContractLike;
+
+/**
+ * Convert an array of contracts to an OpenAPI 3.1 document
+ *
+ * @param contracts - Array of HTTP contracts (ContractBuilder instances or configs)
+ * @param options - OpenAPI generation options
+ * @returns OpenAPI 3.1 document object
+ *
+ * @example
+ * ```ts
+ * import { contractsToOpenAPI } from "@beignet/core/openapi";
+ * import { getTodo, listTodos } from "./contracts";
+ *
+ * const spec = contractsToOpenAPI(
+ *   [getTodo, listTodos],
+ *   {
+ *     title: "Todo API",
+ *     version: "1.0.0",
+ *     servers: [{ url: "https://api.example.com" }],
+ *   }
+ * );
+ * ```
+ */
+export function contractsToOpenAPI(
+  contracts: readonly ContractInput[],
+  options: OpenAPIGeneratorOptions,
+): OpenAPIObject {
+  const paths: PathsObject = {};
+  const components: ComponentsObject = {
+    schemas: {},
+    securitySchemes: options.securitySchemes ?? {},
+  };
+
+  const state: GeneratorState = {
+    components,
+    jsonMediaType: options.jsonMediaType ?? "application/json",
+    introspector: options.schemaIntrospector ?? createZodIntrospector(),
+  };
+
+  for (const contract of contracts) {
+    const config = resolveContract(contract);
+    addContractToPaths(config, paths, state);
+  }
+
+  const openapi: OpenAPIObject = {
+    openapi: "3.1.0",
+    info: {
+      title: options.title,
+      version: options.version,
+      description: options.description,
+    },
+    servers: options.servers,
+    paths,
+    components:
+      Object.keys(components.schemas ?? {}).length > 0 ||
+      Object.keys(components.securitySchemes ?? {}).length > 0
+        ? components
+        : undefined,
+    security: options.security,
+  };
+
+  return openapi;
+}
+
+// =============================================================================
+// OpenAPI Generation Helpers
+// =============================================================================
+
+/**
+ * Add a single contract to the paths object
+ */
+function addContractToPaths(
+  contract: AnyContract,
+  paths: PathsObject,
+  state: GeneratorState,
+): void {
+  const pathKey = parsePathTemplate(contract.path).openApiPath;
+  if (!paths[pathKey]) {
+    paths[pathKey] = {};
+  }
+  const pathItem = paths[pathKey];
+
+  const meta = contract.metadata?.openapi;
+
+  const operation: OperationObject = {
+    operationId: meta?.operationId ?? contract.name,
+    summary: meta?.summary,
+    description: meta?.description,
+    tags: meta?.tags,
+    deprecated: meta?.deprecated,
+    externalDocs: meta?.externalDocs,
+    security: meta?.security,
+    parameters: [],
+    responses: {},
+  };
+
+  addPathParams(contract, operation, state);
+  addQueryParams(contract, operation, state);
+  addHeaderParams(contract, operation, state);
+  addRequestBody(contract, operation, state);
+  addResponses(contract, operation, state);
+
+  // Clean up empty parameters array
+  if (operation.parameters?.length === 0) {
+    delete operation.parameters;
+  }
+
+  const methodKey = contract.method.toLowerCase() as
+    | "get"
+    | "post"
+    | "put"
+    | "patch"
+    | "delete"
+    | "head"
+    | "options";
+
+  pathItem[methodKey] = operation;
+}
+
+function addParameter(
+  operation: OperationObject,
+  parameter: ParameterObject,
+): void {
+  if (!operation.parameters) {
+    operation.parameters = [];
+  }
+
+  const existingIndex = operation.parameters.findIndex(
+    (existing) =>
+      existing.in === parameter.in && existing.name === parameter.name,
+  );
+  if (existingIndex >= 0) {
+    operation.parameters[existingIndex] = parameter;
+    return;
+  }
+
+  operation.parameters.push(parameter);
+}
+
+/**
+ * Add path parameters from contract to operation.
+ */
+function addPathParams(
+  contract: AnyContract,
+  operation: OperationObject,
+  state: GeneratorState,
+): void {
+  const pathKeys = parsePathTemplate(contract.path).keys;
+  if (!contract.pathParams) {
+    for (const key of pathKeys) {
+      addParameter(operation, {
+        name: key,
+        in: "path",
+        required: true,
+        schema: { type: "string" },
+      });
+    }
+    return;
+  }
+
+  const shape = state.introspector.getShape(contract.pathParams);
+  if (!shape) {
+    if (pathKeys.length > 0) {
+      throw new Error(
+        `Unable to introspect pathParams for contract "${contract.name}" at "${contract.path}". OpenAPI path parameters must match the path template.`,
+      );
+    }
+    return;
+  }
+
+  const shapeKeys = Object.keys(shape);
+  const missingKeys = pathKeys.filter((key) => !shapeKeys.includes(key));
+  const extraKeys = shapeKeys.filter((key) => !pathKeys.includes(key));
+  if (missingKeys.length > 0 || extraKeys.length > 0) {
+    const details = [
+      missingKeys.length > 0
+        ? `missing pathParams keys: ${missingKeys.join(", ")}`
+        : undefined,
+      extraKeys.length > 0
+        ? `extra pathParams keys: ${extraKeys.join(", ")}`
+        : undefined,
+    ]
+      .filter(Boolean)
+      .join("; ");
+    throw new Error(
+      `Path parameters for contract "${contract.name}" must match "${contract.path}" (${details}).`,
+    );
+  }
+
+  for (const key of pathKeys) {
+    const field = shape[key];
+    const paramSchemaRef = zodToSchemaRef(
+      field as ZodTypeAny,
+      `${contract.name}_path_${key}`,
+      state,
+      "input",
+    );
+
+    const description = state.introspector.getDescription(field);
+
+    const param: ParameterObject = {
+      name: key,
+      in: "path",
+      required: true,
+      schema: paramSchemaRef,
+      description,
+    };
+
+    addParameter(operation, param);
+  }
+}
+
+/**
+ * Add query parameters from contract to operation.
+ */
+function addQueryParams(
+  contract: AnyContract,
+  operation: OperationObject,
+  state: GeneratorState,
+): void {
+  if (!contract.query) return;
+
+  const shape = state.introspector.getShape(contract.query);
+  if (!shape) return;
+
+  for (const key of Object.keys(shape)) {
+    const originalField = shape[key];
+    const optional = state.introspector.isOptional(originalField);
+
+    let description = state.introspector.getDescription(originalField);
+
+    const field = originalField;
+
+    // If outer optional didn't have description, check inner type
+    if (!description && optional) {
+      description = state.introspector.getDescription(field);
+    }
+
+    const paramSchemaRef = zodToSchemaRef(
+      field as ZodTypeAny,
+      `${contract.name}_query_${key}`,
+      state,
+      "input",
+    );
+
+    const param: ParameterObject = {
+      name: key,
+      in: "query",
+      required: !optional,
+      schema: paramSchemaRef,
+      description,
+    };
+
+    addParameter(operation, param);
+  }
+}
+
+/**
+ * Add header parameters from contract to operation.
+ */
+function addHeaderParams(
+  contract: AnyContract,
+  operation: OperationObject,
+  state: GeneratorState,
+): void {
+  const headerSchemas = getContractHeaderSchemas(contract.headers);
+  for (const headerSchema of headerSchemas) {
+    const shape = state.introspector.getShape(headerSchema);
+    if (!shape) continue;
+
+    for (const key of Object.keys(shape)) {
+      const originalField = shape[key];
+      const optional = state.introspector.isOptional(originalField);
+      const description = state.introspector.getDescription(originalField);
+
+      const paramSchemaRef = zodToSchemaRef(
+        originalField as ZodTypeAny,
+        `${contract.name}_header_${key}`,
+        state,
+        "input",
+      );
+
+      addParameter(operation, {
+        name: key,
+        in: "header",
+        required: !optional,
+        schema: paramSchemaRef,
+        description,
+      });
+    }
+  }
+}
+
+/**
+ * Add request body from contract to operation
+ */
+function addRequestBody(
+  contract: AnyContract,
+  operation: OperationObject,
+  state: GeneratorState,
+): void {
+  if (!contract.body) return;
+  if (!methodSupportsRequestBody(contract.method)) {
+    throw new Error(
+      `Request bodies are not supported for ${contract.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`,
+    );
+  }
+
+  const schemaRef = zodToSchemaRef(
+    contract.body as ZodTypeAny,
+    `${contract.name}_body`,
+    state,
+    "input",
+  );
+
+  const description = state.introspector.getDescription(contract.body);
+
+  operation.requestBody = {
+    required: true,
+    description,
+    content: {
+      [state.jsonMediaType]: {
+        schema: schemaRef,
+      },
+    },
+  };
+}
+
+/**
+ * Add responses from contract to operation
+ */
+function addResponses(
+  contract: AnyContract,
+  operation: OperationObject,
+  state: GeneratorState,
+): void {
+  // Process all responses (both success and error status codes)
+  for (const [statusKey, zodSchema] of Object.entries(contract.responses)) {
+    const status = statusKey; // Keep as string
+    const catalogErrors = getCatalogErrorsForStatus(contract, Number(status));
+
+    // null schema means void/empty response (e.g. .responses({ 204: null }))
+    const hasSchema = zodSchema != null;
+
+    const schemaRef = hasSchema
+      ? catalogErrors.length > 0 && zodSchema === STANDARD_ERROR_RESPONSE_SCHEMA
+        ? catalogErrorResponseSchemaRef(
+            catalogErrors,
+            `${contract.name}_response_${status}`,
+            state,
+          )
+        : schemaToSchemaRef(
+            zodSchema,
+            `${contract.name}_response_${status}`,
+            state,
+            "output",
+          )
+      : undefined;
+
+    const described = hasSchema
+      ? state.introspector.getDescription(zodSchema)
+      : undefined;
+
+    let description: string;
+
+    if (described) {
+      description = described;
+    } else if (catalogErrors.length === 1) {
+      description = catalogErrors[0].message;
+    } else if (catalogErrors.length > 1) {
+      description = catalogErrors.map((error) => error.message).join("; ");
+    } else if (status === "200") {
+      description = "OK";
+    } else if (status === "201") {
+      description = "Created";
+    } else if (status === "204") {
+      description = "No Content";
+    } else if (status === "400") {
+      description = "Bad Request";
+    } else if (status === "401") {
+      description = "Unauthorized";
+    } else if (status === "403") {
+      description = "Forbidden";
+    } else if (status === "404") {
+      description = "Not Found";
+    } else if (status === "500") {
+      description = "Internal Server Error";
+    } else {
+      description = `HTTP ${status}`;
+    }
+
+    const examples = examplesFromCatalogErrors(catalogErrors);
+    operation.responses[status] = {
+      description,
+      content:
+        !hasSchema || status === "204"
+          ? undefined
+          : {
+              [state.jsonMediaType]: {
+                schema: schemaRef,
+                ...(examples ? { examples } : {}),
+              },
+            },
+    };
+  }
+}
+
+type CatalogErrorForOpenAPI = {
+  key: string;
+  code: string;
+  status: number;
+  message: string;
+  details?: unknown;
+};
+
+function getCatalogErrorsForStatus(
+  contract: AnyContract,
+  status: number,
+): CatalogErrorForOpenAPI[] {
+  const errors = contract.metadata?.errors;
+  if (typeof errors !== "object" || errors === null) return [];
+
+  return Object.entries(errors)
+    .map(([key, error]) => {
+      if (
+        typeof error !== "object" ||
+        error === null ||
+        typeof (error as { code?: unknown }).code !== "string" ||
+        typeof (error as { status?: unknown }).status !== "number" ||
+        typeof (error as { message?: unknown }).message !== "string"
+      ) {
+        return undefined;
+      }
+
+      const catalogError: CatalogErrorForOpenAPI = {
+        key,
+        code: (error as { code: string }).code,
+        status: (error as { status: number }).status,
+        message: (error as { message: string }).message,
+      };
+      const details = (error as { details?: unknown }).details;
+      if (details !== undefined) {
+        catalogError.details = details;
+      }
+
+      return catalogError;
+    })
+    .filter(
+      (error): error is CatalogErrorForOpenAPI =>
+        error !== undefined && error.status === status,
+    );
+}
+
+function catalogErrorResponseSchemaRef(
+  errors: CatalogErrorForOpenAPI[],
+  nameHint: string,
+  state: GeneratorState,
+): SchemaObject | ReferenceObject {
+  const schema =
+    errors.length === 1
+      ? catalogErrorResponseSchema(errors[0], nameHint, state)
+      : {
+          oneOf: errors.map((error) =>
+            catalogErrorResponseSchema(
+              error,
+              `${nameHint}_${error.key}`,
+              state,
+            ),
+          ),
+        };
+
+  if (!state.components.schemas) {
+    state.components.schemas = {};
+  }
+
+  const schemaName = normalizeSchemaName(nameHint, state);
+  if (!state.components.schemas[schemaName]) {
+    state.components.schemas[schemaName] = schema;
+  }
+
+  return { $ref: `#/components/schemas/${schemaName}` };
+}
+
+function catalogErrorResponseSchema(
+  error: CatalogErrorForOpenAPI,
+  nameHint: string,
+  state: GeneratorState,
+): SchemaObject {
+  return {
+    type: "object",
+    properties: {
+      code: { type: "string", const: error.code },
+      message: { type: "string" },
+      ...(error.details
+        ? {
+            details: schemaToSchemaRef(
+              error.details,
+              `${nameHint}_details`,
+              state,
+              "output",
+            ),
+          }
+        : { details: {} }),
+      requestId: { type: "string" },
+    },
+    required: ["code", "message"],
+  };
+}
+
+function examplesFromCatalogErrors(
+  errors: CatalogErrorForOpenAPI[],
+): Record<string, { summary?: string; value?: unknown }> | undefined {
+  if (errors.length === 0) return undefined;
+
+  return Object.fromEntries(
+    errors.map((error) => [
+      normalizeExampleKey(error.key),
+      {
+        summary: error.message,
+        value: {
+          code: error.code,
+          message: error.message,
+        },
+      },
+    ]),
+  );
+}
+
+function normalizeExampleKey(key: string): string {
+  const normalized = key.replace(/[^A-Za-z0-9._-]/g, "_");
+  return normalized || "error";
+}
+
+/**
+ * Convert a Zod schema to a JSON Schema reference, registering it in components
+ */
+function zodToSchemaRef(
+  schema: ZodTypeAny,
+  nameHint: string,
+  state: GeneratorState,
+  io: SchemaIO,
+): SchemaObject | ReferenceObject {
+  // Ensure schemas object exists
+  if (!state.components.schemas) {
+    state.components.schemas = {};
+  }
+
+  const schemaName = normalizeSchemaName(nameHint, state);
+
+  if (!state.components.schemas[schemaName]) {
+    const jsonSchema = z.toJSONSchema(schema, {
+      target: "draft-2020-12",
+      unrepresentable: "any",
+      io,
+    }) as SchemaObject;
+
+    // Remove $schema as it's not needed in OpenAPI
+    delete jsonSchema.$schema;
+
+    state.components.schemas[schemaName] = jsonSchema;
+  }
+
+  return { $ref: `#/components/schemas/${schemaName}` };
+}
+
+function schemaToSchemaRef(
+  schema: unknown,
+  nameHint: string,
+  state: GeneratorState,
+  io: SchemaIO,
+): SchemaObject | ReferenceObject {
+  if (schema === STANDARD_ERROR_RESPONSE_SCHEMA) {
+    return standardErrorResponseSchemaRef(nameHint, state);
+  }
+
+  return zodToSchemaRef(schema as ZodTypeAny, nameHint, state, io);
+}
+
+function standardErrorResponseSchemaRef(
+  nameHint: string,
+  state: GeneratorState,
+): ReferenceObject {
+  if (!state.components.schemas) {
+    state.components.schemas = {};
+  }
+
+  const schemaName = normalizeSchemaName(nameHint, state);
+  if (!state.components.schemas[schemaName]) {
+    state.components.schemas[schemaName] = {
+      type: "object",
+      properties: {
+        code: { type: "string" },
+        message: { type: "string" },
+        details: {},
+        requestId: { type: "string" },
+      },
+      required: ["code", "message"],
+    };
+  }
+
+  return { $ref: `#/components/schemas/${schemaName}` };
+}
+
+/**
+ * Normalize schema name for use in components.
+ * Appends a counter suffix only when the base name already exists.
+ */
+function normalizeSchemaName(name: string, state: GeneratorState): string {
+  const base = name.replace(/[^A-Za-z0-9]/g, "_");
+
+  // Check if base name is already used
+  if (!state.components.schemas?.[base]) {
+    return base;
+  }
+
+  // Find a unique name by appending a counter
+  let counter = 1;
+  let uniqueName = `${base}_${counter}`;
+  while (state.components.schemas[uniqueName]) {
+    counter++;
+    uniqueName = `${base}_${counter}`;
+  }
+
+  return uniqueName;
+}