bazis 0.96.1

package/library/openapi/document.ts

@@ -0,0 +1,326 @@
+import type { OpenApiCatalogOperation, OpenApiDocumentBuildInput, OpenApiParameter, OpenApiSchema } from "./types";
+
+type OpenApiOperation = {
+  tags: string[];
+  operationId: string;
+  summary: string;
+  parameters?: OpenApiParameter[];
+  requestBody?: OpenApiSchema;
+  responses: Record<string, OpenApiSchema>;
+  security?: readonly OpenApiSchema[];
+  [extension: `x-${string}`]: unknown;
+};
+
+const HTTP_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
+const HTTP_METHOD_KEYS = new Set([...HTTP_METHODS].map((method) => method.toLowerCase()));
+
+export function buildOpenApiDocument(input: OpenApiDocumentBuildInput): OpenApiSchema {
+  const paths: Record<string, Record<string, unknown>> = {};
+  let hasSecurity = false;
+
+  for (const item of input.operations) {
+    const operation = operationFromCatalog(item);
+    if (operation.security !== undefined) {
+      hasSecurity = true;
+    }
+    addOperation(paths, item.path, item.httpMethod, operation);
+  }
+
+  const components: Record<string, unknown> = { schemas: schemasForPaths(input.schemas, paths) };
+  if (hasSecurity) {
+    components.securitySchemes = {
+      bearerAuth: {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "JWT",
+      },
+    };
+  }
+
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: input.title,
+      version: input.version,
+      ...(input.generatedBy !== undefined ? { "x-generated-by": input.generatedBy } : {}),
+    },
+    paths,
+    components,
+  };
+}
+
+/**
+ * Creates the least-privilege OpenAPI view for an effective UI surface.
+ * Only explicitly allowed operations and the schemas reachable from them are
+ * retained. A missing operation is a server configuration error, never a
+ * reason to silently publish a broader document.
+ */
+export function projectOpenApiByOperationIds(
+  document: OpenApiSchema,
+  operationIds: ReadonlySet<string> | readonly string[],
+): OpenApiSchema {
+  const requested = operationIds instanceof Set ? operationIds : new Set(operationIds);
+  const found = new Set<string>();
+  const projectedPaths: Record<string, Record<string, unknown>> = {};
+  const sourcePaths = isRecord(document.paths) ? document.paths : {};
+
+  for (const [path, sourceItem] of Object.entries(sourcePaths)) {
+    if (!isRecord(sourceItem)) {
+      continue;
+    }
+    const projectedItem: Record<string, unknown> = {};
+    let hasOperation = false;
+    for (const [key, value] of Object.entries(sourceItem)) {
+      if (HTTP_METHOD_KEYS.has(key)) {
+        if (isRequestedOperation(value, requested, found)) {
+          projectedItem[key] = value;
+          hasOperation = true;
+        }
+        continue;
+      }
+      if (key === "x-bazis-any-method") {
+        const projected = requestedAnyMethodOperations(value, requested, found);
+        if (projected !== undefined) {
+          projectedItem[key] = projected;
+          hasOperation = true;
+        }
+        continue;
+      }
+      projectedItem[key] = value;
+    }
+    if (hasOperation) {
+      projectedPaths[path] = projectedItem;
+    }
+  }
+
+  const missing = [...requested].filter((operationId) => !found.has(operationId)).sort();
+  if (missing.length > 0) {
+    throw new TypeError(`OpenAPI operations not found: ${missing.join(", ")}.`);
+  }
+
+  const sourceComponents = isRecord(document.components) ? document.components : {};
+  const sourceSchemas = isRecord(sourceComponents.schemas)
+    ? sourceComponents.schemas as Readonly<Record<string, OpenApiSchema>>
+    : {};
+  const components: Record<string, unknown> = {
+    schemas: schemasForPaths(sourceSchemas, projectedPaths),
+  };
+  if (sourceComponents.securitySchemes !== undefined) {
+    components.securitySchemes = sourceComponents.securitySchemes;
+  }
+
+  return {
+    ...(document.openapi !== undefined ? { openapi: document.openapi } : {}),
+    ...(document.info !== undefined ? { info: document.info } : {}),
+    ...(document.jsonSchemaDialect !== undefined ? { jsonSchemaDialect: document.jsonSchemaDialect } : {}),
+    ...(document.servers !== undefined ? { servers: document.servers } : {}),
+    ...(document.security !== undefined ? { security: document.security } : {}),
+    ...(document.externalDocs !== undefined ? { externalDocs: document.externalDocs } : {}),
+    paths: projectedPaths,
+    components,
+  };
+}
+
+function isRequestedOperation(
+  value: unknown,
+  requested: ReadonlySet<string>,
+  found: Set<string>,
+): boolean {
+  if (!isRecord(value) || typeof value.operationId !== "string" || !requested.has(value.operationId)) {
+    return false;
+  }
+  found.add(value.operationId);
+  return true;
+}
+
+function requestedAnyMethodOperations(
+  value: unknown,
+  requested: ReadonlySet<string>,
+  found: Set<string>,
+): unknown {
+  if (Array.isArray(value)) {
+    const operations = value.filter((item) => isRequestedOperation(item, requested, found));
+    return operations.length === 0 ? undefined : operations;
+  }
+  return isRequestedOperation(value, requested, found) ? value : undefined;
+}
+
+function operationFromCatalog(item: OpenApiCatalogOperation): OpenApiOperation {
+  const operation: OpenApiOperation = {
+    tags: [item.tag],
+    operationId: item.operationId,
+    summary: item.summary ?? `${normalizedMethod(item.httpMethod)} ${item.path}`,
+    responses: { ...item.responses },
+  };
+  const parameters = mergeParameters(item.parameters ?? []);
+  if (parameters.length > 0) {
+    operation.parameters = parameters;
+  }
+  if (item.requestBody !== undefined) {
+    operation.requestBody = item.requestBody;
+  }
+  if (item.authorized === true) {
+    operation.security = [{ bearerAuth: [] }];
+  }
+  if (item.versions !== undefined && item.versions.length > 0) {
+    operation["x-bazis-versions"] = uniqueStrings(item.versions);
+  }
+  return operation;
+}
+
+function addOperation(
+  paths: Record<string, Record<string, unknown>>,
+  path: string,
+  httpMethod: string,
+  operation: OpenApiOperation,
+): void {
+  const item = (paths[path] ??= {});
+  if (httpMethod === "*") {
+    const existing = item["x-bazis-any-method"];
+    item["x-bazis-any-method"] = mergeAnyMethod(existing, operation);
+    return;
+  }
+  if (!HTTP_METHODS.has(httpMethod)) {
+    return;
+  }
+  const key = httpMethod.toLowerCase();
+  const existing = item[key];
+  item[key] = existing && isRecord(existing) ? mergeOperations(existing, operation) : operation;
+}
+
+function mergeAnyMethod(existing: unknown, operation: OpenApiOperation): OpenApiOperation | OpenApiOperation[] {
+  if (existing === undefined) {
+    return operation;
+  }
+  return Array.isArray(existing) ? [...existing, operation] : [existing as OpenApiOperation, operation];
+}
+
+function mergeOperations(existing: Record<string, unknown>, next: OpenApiOperation): OpenApiOperation {
+  const existingOperationId = String(existing.operationId ?? next.operationId);
+  const versions = uniqueStrings([
+    ...readStringArray(existing["x-bazis-versions"]),
+    ...readStringArray(next["x-bazis-versions"]),
+  ]);
+  const parameters = mergeParameters([
+    ...readParameters(existing.parameters),
+    ...(next.parameters ?? []),
+  ]);
+  return {
+    ...next,
+    operationId: existingOperationId === next.operationId
+      ? existingOperationId
+      : `${existingOperationId}_${next.operationId}`,
+    parameters: parameters.length > 0 ? parameters : undefined,
+    responses: { ...(existing.responses as Record<string, OpenApiSchema> | undefined), ...next.responses },
+    ...(versions.length > 0 ? { "x-bazis-versions": versions } : {}),
+  };
+}
+
+function mergeParameters(parameters: readonly OpenApiParameter[]): OpenApiParameter[] {
+  const out: OpenApiParameter[] = [];
+  for (const parameter of parameters) {
+    const existingIndex = out.findIndex((item) => item.in === parameter.in && item.name === parameter.name);
+    if (existingIndex < 0) {
+      out.push({ ...parameter });
+      continue;
+    }
+    const existing = out[existingIndex] as OpenApiParameter;
+    out[existingIndex] = {
+      ...existing,
+      required: existing.required === true || parameter.required === true,
+      schema: mergeParameterSchema(existing.schema, parameter.schema),
+      // One projected operation may cover multiple query/header versions.
+      // Only their common fields are safe to offer without selecting a version.
+      ...(existing["x-bazis-sort-fields"] !== undefined || parameter["x-bazis-sort-fields"] !== undefined
+        ? { "x-bazis-sort-fields": (existing["x-bazis-sort-fields"] ?? []).filter(
+            (field) => parameter["x-bazis-sort-fields"]?.includes(field),
+          ) }
+        : {}),
+    };
+  }
+  return out;
+}
+
+function mergeParameterSchema(left: OpenApiSchema | undefined, right: OpenApiSchema | undefined): OpenApiSchema | undefined {
+  if (!left) {
+    return right;
+  }
+  if (!right) {
+    return left;
+  }
+  const leftEnum = readStringArray(left.enum);
+  const rightEnum = readStringArray(right.enum);
+  if (leftEnum.length === 0 && rightEnum.length === 0) {
+    return left;
+  }
+  return { ...left, enum: uniqueStrings([...leftEnum, ...rightEnum]) };
+}
+
+function schemasForPaths(
+  schemas: Readonly<Record<string, OpenApiSchema>>,
+  paths: Record<string, Record<string, unknown>>,
+): Record<string, OpenApiSchema> {
+  const out: Record<string, OpenApiSchema> = {};
+  const seen = new Set<string>();
+  const queue: string[] = [];
+  const add = (name: string): void => {
+    if (seen.has(name) || schemas[name] === undefined) {
+      return;
+    }
+    seen.add(name);
+    queue.push(name);
+  };
+  collectRefs(paths, add);
+  for (let index = 0; index < queue.length; index += 1) {
+    const name = queue[index] as string;
+    const schema = schemas[name] as OpenApiSchema;
+    out[name] = schema;
+    collectRefs(schema, add);
+  }
+  return out;
+}
+
+function collectRefs(value: unknown, add: (name: string) => void): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectRefs(item, add);
+    }
+    return;
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+  if (typeof value.$ref === "string") {
+    const prefix = "#/components/schemas/";
+    if (value.$ref.startsWith(prefix)) {
+      add(value.$ref.slice(prefix.length));
+    }
+  }
+  for (const item of Object.values(value)) {
+    collectRefs(item, add);
+  }
+}
+
+function normalizedMethod(method: string): string {
+  return method === "*" ? "ANY" : method;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+function readParameters(value: unknown): OpenApiParameter[] {
+  return Array.isArray(value) ? value.filter(isOpenApiParameter) : [];
+}
+
+function isOpenApiParameter(value: unknown): value is OpenApiParameter {
+  return isRecord(value) && typeof value.name === "string" && (value.in === "path" || value.in === "query" || value.in === "header");
+}
+
+function uniqueStrings(values: readonly string[]): string[] {
+  return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}

package/library/openapi/index.ts

@@ -0,0 +1,13 @@
+export { buildOpenApiDocument, projectOpenApiByOperationIds } from "./document";
+export { openApiDocsHeaders, renderOpenApiHtml, serveOpenApiDocs } from "./ui";
+export type {
+  GeneratedOpenApiMetadata,
+  GeneratedOpenApiOperationMetadata,
+  OpenApiCatalogOperation,
+  OpenApiDocsOptions,
+  OpenApiDocumentBuildInput,
+  OpenApiParameter,
+  OpenApiParameterLocation,
+  OpenApiSchema,
+  PreparedOpenApiDocs,
+} from "./types";

package/library/openapi/types.ts

@@ -0,0 +1,69 @@
+export type OpenApiSchema = Readonly<Record<string, unknown>>;
+
+export interface GeneratedOpenApiOperationMetadata {
+  readonly response?: OpenApiSchema;
+}
+
+export interface GeneratedOpenApiMetadata {
+  readonly schemas: Readonly<Record<string, OpenApiSchema>>;
+  readonly operations: Readonly<Record<string, Readonly<Record<string, GeneratedOpenApiOperationMetadata>>>>;
+}
+
+export interface OpenApiDocsOptions {
+  /**
+   * Enables or disables built-in API docs. When omitted, docs are available in
+   * debug environments and disabled in production.
+   */
+  readonly enabled?: boolean;
+  /** Absolute path of the HTML UI. Default: "/docs". */
+  readonly path?: string;
+  /** Absolute path of the OpenAPI JSON document. Default: "<path>/openapi.json". */
+  readonly specPath?: string;
+  /** OpenAPI info.title. Default: "Bazis API". */
+  readonly title?: string;
+  /** OpenAPI info.version. Default: "1.0.0". */
+  readonly version?: string;
+}
+
+export interface PreparedOpenApiDocs {
+  readonly uiPath: string;
+  readonly specPath: string;
+  readonly document: OpenApiSchema;
+  readonly json: string;
+  readonly html: string;
+}
+
+export type OpenApiParameterLocation = "path" | "query" | "header";
+
+export interface OpenApiParameter {
+  readonly name: string;
+  readonly in: OpenApiParameterLocation;
+  readonly required?: boolean;
+  readonly schema?: OpenApiSchema;
+  readonly description?: string;
+  readonly style?: string;
+  readonly explode?: boolean;
+  /** Allowed sort field names, without direction prefixes. An empty list forbids sorting. */
+  readonly "x-bazis-sort-fields"?: readonly string[];
+}
+
+export interface OpenApiCatalogOperation {
+  readonly path: string;
+  readonly httpMethod: string;
+  readonly tag: string;
+  readonly operationId: string;
+  readonly summary?: string;
+  readonly parameters?: readonly OpenApiParameter[];
+  readonly requestBody?: OpenApiSchema;
+  readonly responses: Readonly<Record<string, OpenApiSchema>>;
+  readonly authorized?: boolean;
+  readonly versions?: readonly string[];
+}
+
+export interface OpenApiDocumentBuildInput {
+  readonly title: string;
+  readonly version: string;
+  readonly operations: readonly OpenApiCatalogOperation[];
+  readonly schemas: Readonly<Record<string, OpenApiSchema>>;
+  readonly generatedBy?: string;
+}

package/library/openapi/ui.ts

@@ -0,0 +1,182 @@
+export function serveOpenApiDocs(
+  docs: { readonly uiPath: string; readonly specPath: string; readonly json: string; readonly html: string },
+  pathname: string,
+  method: string,
+): Response | undefined {
+  if (pathname !== docs.uiPath && pathname !== `${docs.uiPath}/` && pathname !== docs.specPath) {
+    return undefined;
+  }
+  if (method !== "GET" && method !== "HEAD") {
+    return new Response(JSON.stringify({ error: "Method Not Allowed" }), {
+      status: 405,
+      headers: {
+        allow: "GET, HEAD",
+        "content-type": "application/json; charset=utf-8",
+      },
+    });
+  }
+  if (pathname === docs.specPath) {
+    return new Response(docs.json, {
+      headers: openApiDocsHeaders("application/json; charset=utf-8"),
+    });
+  }
+  return new Response(docs.html, {
+    headers: openApiDocsHeaders("text/html; charset=utf-8"),
+  });
+}
+
+export function openApiDocsHeaders(contentType: string): Record<string, string> {
+  return {
+    "content-type": contentType,
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+    "referrer-policy": "no-referrer",
+    "content-security-policy": "default-src 'none'; connect-src 'self'; style-src 'unsafe-inline'; script-src 'unsafe-inline';",
+  };
+}
+
+export function renderOpenApiHtml(title: string, specPath: string): string {
+  const titleJson = JSON.stringify(title);
+  const specPathJson = JSON.stringify(specPath);
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(title)} Docs</title>
+  <style>
+    :root { color-scheme: light dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    * { box-sizing: border-box; }
+    body { margin: 0; background: Canvas; color: CanvasText; }
+    header { position: sticky; top: 0; z-index: 2; display: grid; grid-template-columns: 1fr minmax(180px, 320px) auto; gap: 12px; align-items: center; padding: 16px 20px; border-bottom: 1px solid color-mix(in srgb, CanvasText 14%, transparent); background: color-mix(in srgb, Canvas 94%, CanvasText 6%); }
+    h1 { margin: 0; font-size: 18px; line-height: 1.2; letter-spacing: 0; }
+    main { display: grid; grid-template-columns: minmax(0, 1fr) 360px; min-height: calc(100vh - 69px); }
+    #operations { padding: 18px 20px 40px; }
+    #raw { padding: 18px; border-left: 1px solid color-mix(in srgb, CanvasText 12%, transparent); background: color-mix(in srgb, CanvasText 4%, Canvas); overflow: auto; }
+    input { width: 100%; min-height: 36px; border: 1px solid color-mix(in srgb, CanvasText 22%, transparent); border-radius: 6px; padding: 8px 10px; background: Canvas; color: CanvasText; font: inherit; }
+    a, button { color: inherit; }
+    .spec-link { white-space: nowrap; font-size: 13px; text-decoration: none; border: 1px solid color-mix(in srgb, CanvasText 22%, transparent); border-radius: 6px; padding: 8px 10px; }
+    .path { margin: 0 0 18px; border: 1px solid color-mix(in srgb, CanvasText 13%, transparent); border-radius: 8px; overflow: hidden; background: Canvas; }
+    .path h2 { margin: 0; padding: 12px 14px; font-size: 14px; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; background: color-mix(in srgb, CanvasText 5%, Canvas); overflow-wrap: anywhere; letter-spacing: 0; }
+    .operation { border-top: 1px solid color-mix(in srgb, CanvasText 10%, transparent); padding: 12px 14px; }
+    .line { display: flex; gap: 10px; align-items: center; min-width: 0; }
+    .method { width: 68px; flex: 0 0 68px; text-align: center; border-radius: 5px; padding: 5px 7px; font-weight: 700; font-size: 12px; color: white; background: #64748b; }
+    .GET { background: #087f5b; } .POST { background: #1c64b7; } .PUT { background: #9a5b00; } .PATCH { background: #7c3aed; } .DELETE { background: #b42318; }
+    .summary { min-width: 0; overflow-wrap: anywhere; font-size: 14px; }
+    .meta { display: flex; flex-wrap: wrap; gap: 6px; margin: 10px 0 0 78px; }
+    .pill { border: 1px solid color-mix(in srgb, CanvasText 16%, transparent); border-radius: 999px; padding: 3px 7px; font-size: 12px; color: color-mix(in srgb, CanvasText 72%, Canvas); }
+    pre { margin: 0; font-size: 12px; line-height: 1.5; white-space: pre-wrap; overflow-wrap: anywhere; }
+    .empty { color: color-mix(in srgb, CanvasText 60%, Canvas); }
+    @media (max-width: 900px) {
+      header { grid-template-columns: 1fr; }
+      main { grid-template-columns: 1fr; }
+      #raw { border-left: 0; border-top: 1px solid color-mix(in srgb, CanvasText 12%, transparent); max-height: 45vh; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1></h1>
+    <input id="filter" type="search" placeholder="Filter operations">
+    <a class="spec-link" href="">Open JSON</a>
+  </header>
+  <main>
+    <section id="operations"></section>
+    <aside id="raw"><pre></pre></aside>
+  </main>
+  <script>
+    const docsTitle = ${titleJson};
+    const specPath = ${specPathJson};
+    const state = { spec: null, rows: [] };
+    document.querySelector("h1").textContent = docsTitle;
+    document.querySelector(".spec-link").href = specPath;
+    fetch(specPath)
+      .then((response) => response.json())
+      .then((spec) => {
+        state.spec = spec;
+        state.rows = flatten(spec);
+        document.querySelector("#raw pre").textContent = JSON.stringify(spec, null, 2);
+        render();
+      })
+      .catch((error) => {
+        document.querySelector("#operations").innerHTML = '<p class="empty">Unable to load OpenAPI document.</p>';
+        document.querySelector("#raw pre").textContent = String(error);
+      });
+    document.querySelector("#filter").addEventListener("input", render);
+    function flatten(spec) {
+      const methods = ["get", "post", "put", "patch", "delete", "options", "head"];
+      const rows = [];
+      for (const [path, item] of Object.entries(spec.paths || {})) {
+        for (const method of methods) {
+          if (item && item[method]) rows.push({ path, method: method.toUpperCase(), operation: item[method] });
+        }
+      }
+      return rows;
+    }
+    function render() {
+      const filter = document.querySelector("#filter").value.trim().toLowerCase();
+      const grouped = new Map();
+      for (const row of state.rows) {
+        const haystack = [row.method, row.path, row.operation.summary, row.operation.operationId, ...(row.operation.tags || [])].join(" ").toLowerCase();
+        if (filter && !haystack.includes(filter)) continue;
+        if (!grouped.has(row.path)) grouped.set(row.path, []);
+        grouped.get(row.path).push(row);
+      }
+      const root = document.querySelector("#operations");
+      if (grouped.size === 0) {
+        root.innerHTML = '<p class="empty">No operations found.</p>';
+        return;
+      }
+      root.innerHTML = "";
+      for (const [path, rows] of grouped) {
+        const block = document.createElement("article");
+        block.className = "path";
+        const heading = document.createElement("h2");
+        heading.textContent = path;
+        block.appendChild(heading);
+        for (const row of rows) block.appendChild(operationNode(row));
+        root.appendChild(block);
+      }
+    }
+    function operationNode(row) {
+      const node = document.createElement("section");
+      node.className = "operation";
+      const line = document.createElement("div");
+      line.className = "line";
+      const method = document.createElement("span");
+      method.className = "method " + row.method;
+      method.textContent = row.method;
+      const summary = document.createElement("span");
+      summary.className = "summary";
+      summary.textContent = row.operation.operationId || row.operation.summary || "";
+      line.append(method, summary);
+      node.appendChild(line);
+      const meta = document.createElement("div");
+      meta.className = "meta";
+      for (const parameter of row.operation.parameters || []) {
+        meta.appendChild(pill(parameter.in + ":" + parameter.name + (parameter.required ? " required" : "")));
+      }
+      if (row.operation.requestBody) meta.appendChild(pill("body"));
+      if (row.operation.security) meta.appendChild(pill("auth"));
+      for (const status of Object.keys(row.operation.responses || {})) meta.appendChild(pill(status));
+      if (meta.children.length > 0) node.appendChild(meta);
+      return node;
+    }
+    function pill(text) {
+      const item = document.createElement("span");
+      item.className = "pill";
+      item.textContent = text;
+      return item;
+    }
+  </script>
+</body>
+</html>`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}