@fluixi/api 0.0.0-stage → 0.1.0-alpha.3

package/dist/input.cjs

@@ -0,0 +1,91 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/input.ts
+var input_exports = {};
+__export(input_exports, {
+  DEFAULT_BODY_LIMIT: () => DEFAULT_BODY_LIMIT,
+  readJson: () => readJson,
+  readQuery: () => readQuery
+});
+module.exports = __toCommonJS(input_exports);
+
+// src/errors.ts
+var ApiError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/input.ts
+var DEFAULT_BODY_LIMIT = 1024 * 1024;
+function readQuery(url) {
+  const out = {};
+  for (const [key, value] of url.searchParams) {
+    const seen = out[key];
+    if (seen === void 0) out[key] = value;
+    else out[key] = Array.isArray(seen) ? [...seen, value] : [seen, value];
+  }
+  return out;
+}
+async function readJson(request, limit = DEFAULT_BODY_LIMIT) {
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > limit) throw tooLarge(limit);
+  if (!request.body) return void 0;
+  const type = request.headers.get("content-type") ?? "";
+  const reader = request.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel();
+      throw tooLarge(limit);
+    }
+    chunks.push(value);
+  }
+  if (size === 0) return void 0;
+  if (!isJson(type)) {
+    throw new ApiError(415, "unsupported_media_type", "Send the body as application/json.");
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    throw new ApiError(400, "invalid_json", "The body is not valid JSON.");
+  }
+}
+function isJson(type) {
+  const mime = type.split(";")[0].trim().toLowerCase();
+  return mime === "application/json" || mime.endsWith("+json");
+}
+function tooLarge(limit) {
+  return new ApiError(413, "payload_too_large", `The body is larger than ${limit} bytes.`);
+}

package/dist/input.d.ts

@@ -0,0 +1,15 @@
+/** 1 MiB. A JSON API rarely needs more; files go to storage directly, not through a route. */
+export declare const DEFAULT_BODY_LIMIT: number;
+/**
+ * The query string as a plain object: `?a=1` is `{ a: '1' }`, and a repeated key becomes an
+ * array, `?tag=x&tag=y` is `{ tag: ['x', 'y'] }`. Schemas coerce from there.
+ */
+export declare function readQuery(url: URL): Record<string, string | string[]>;
+/**
+ * The JSON body, or `undefined` when there is none.
+ *
+ * The size limit is checked on the bytes read, not only on `Content-Length`, which a client can
+ * leave out or get wrong: reading stops at the limit instead of buffering whatever arrives.
+ */
+export declare function readJson(request: Request, limit?: number): Promise<unknown>;
+//# sourceMappingURL=input.d.ts.map

package/dist/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"AAKA,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,QAAc,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAQrE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,SAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmC7F"}

package/dist/input.js

@@ -0,0 +1,73 @@
+/**
+ * Reading what a request carries, before any schema sees it.
+ */
+import { ApiError } from './errors.js';
+/** 1 MiB. A JSON API rarely needs more; files go to storage directly, not through a route. */
+export const DEFAULT_BODY_LIMIT = 1024 * 1024;
+/**
+ * The query string as a plain object: `?a=1` is `{ a: '1' }`, and a repeated key becomes an
+ * array, `?tag=x&tag=y` is `{ tag: ['x', 'y'] }`. Schemas coerce from there.
+ */
+export function readQuery(url) {
+    const out = {};
+    for (const [key, value] of url.searchParams) {
+        const seen = out[key];
+        if (seen === undefined)
+            out[key] = value;
+        else
+            out[key] = Array.isArray(seen) ? [...seen, value] : [seen, value];
+    }
+    return out;
+}
+/**
+ * The JSON body, or `undefined` when there is none.
+ *
+ * The size limit is checked on the bytes read, not only on `Content-Length`, which a client can
+ * leave out or get wrong: reading stops at the limit instead of buffering whatever arrives.
+ */
+export async function readJson(request, limit = DEFAULT_BODY_LIMIT) {
+    const declared = Number(request.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > limit)
+        throw tooLarge(limit);
+    if (!request.body)
+        return undefined;
+    const type = request.headers.get('content-type') ?? '';
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > limit) {
+            await reader.cancel();
+            throw tooLarge(limit);
+        }
+        chunks.push(value);
+    }
+    if (size === 0)
+        return undefined;
+    if (!isJson(type)) {
+        throw new ApiError(415, 'unsupported_media_type', 'Send the body as application/json.');
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new ApiError(400, 'invalid_json', 'The body is not valid JSON.');
+    }
+}
+function isJson(type) {
+    const mime = type.split(';')[0].trim().toLowerCase();
+    return mime === 'application/json' || mime.endsWith('+json');
+}
+function tooLarge(limit) {
+    return new ApiError(413, 'payload_too_large', `The body is larger than ${limit} bytes.`);
+}

package/dist/input.mjs

@@ -0,0 +1,68 @@
+// src/errors.ts
+var ApiError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/input.ts
+var DEFAULT_BODY_LIMIT = 1024 * 1024;
+function readQuery(url) {
+  const out = {};
+  for (const [key, value] of url.searchParams) {
+    const seen = out[key];
+    if (seen === void 0) out[key] = value;
+    else out[key] = Array.isArray(seen) ? [...seen, value] : [seen, value];
+  }
+  return out;
+}
+async function readJson(request, limit = DEFAULT_BODY_LIMIT) {
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > limit) throw tooLarge(limit);
+  if (!request.body) return void 0;
+  const type = request.headers.get("content-type") ?? "";
+  const reader = request.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel();
+      throw tooLarge(limit);
+    }
+    chunks.push(value);
+  }
+  if (size === 0) return void 0;
+  if (!isJson(type)) {
+    throw new ApiError(415, "unsupported_media_type", "Send the body as application/json.");
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    throw new ApiError(400, "invalid_json", "The body is not valid JSON.");
+  }
+}
+function isJson(type) {
+  const mime = type.split(";")[0].trim().toLowerCase();
+  return mime === "application/json" || mime.endsWith("+json");
+}
+function tooLarge(limit) {
+  return new ApiError(413, "payload_too_large", `The body is larger than ${limit} bytes.`);
+}
+export {
+  DEFAULT_BODY_LIMIT,
+  readJson,
+  readQuery
+};

package/dist/middleware.cjs

@@ -0,0 +1,41 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/middleware.ts
+var middleware_exports = {};
+__export(middleware_exports, {
+  appendVary: () => appendVary,
+  withHeaders: () => withHeaders
+});
+module.exports = __toCommonJS(middleware_exports);
+function withHeaders(response, set) {
+  try {
+    set(response.headers);
+    return response;
+  } catch {
+    const copy = new Response(response.body, response);
+    set(copy.headers);
+    return copy;
+  }
+}
+function appendVary(headers, name) {
+  const vary = headers.get("vary");
+  if (!vary) headers.set("vary", name);
+  else if (!vary.split(",").some((v) => v.trim().toLowerCase() === name.toLowerCase())) headers.set("vary", `${vary}, ${name}`);
+}

package/dist/middleware.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The shape of `@fluixi/start` middleware, restated so this package does not import start:
+ * `(request, next)` to a `Response`, where `next()` runs the rest of the chain.
+ */
+export type Middleware = (request: Request, next: () => Promise<Response>) => Response | Promise<Response>;
+/** Headers set on a response, cloning it first when its headers are immutable (a fetched one). */
+export declare function withHeaders(response: Response, set: (headers: Headers) => void): Response;
+export declare function appendVary(headers: Headers, name: string): void;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE3G,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,QAAQ,CASzF;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI/D"}

package/dist/middleware.js

@@ -0,0 +1,19 @@
+/** Headers set on a response, cloning it first when its headers are immutable (a fetched one). */
+export function withHeaders(response, set) {
+    try {
+        set(response.headers);
+        return response;
+    }
+    catch {
+        const copy = new Response(response.body, response);
+        set(copy.headers);
+        return copy;
+    }
+}
+export function appendVary(headers, name) {
+    const vary = headers.get('vary');
+    if (!vary)
+        headers.set('vary', name);
+    else if (!vary.split(',').some((v) => v.trim().toLowerCase() === name.toLowerCase()))
+        headers.set('vary', `${vary}, ${name}`);
+}

package/dist/middleware.mjs

@@ -0,0 +1,20 @@
+// src/middleware.ts
+function withHeaders(response, set) {
+  try {
+    set(response.headers);
+    return response;
+  } catch {
+    const copy = new Response(response.body, response);
+    set(copy.headers);
+    return copy;
+  }
+}
+function appendVary(headers, name) {
+  const vary = headers.get("vary");
+  if (!vary) headers.set("vary", name);
+  else if (!vary.split(",").some((v) => v.trim().toLowerCase() === name.toLowerCase())) headers.set("vary", `${vary}, ${name}`);
+}
+export {
+  appendVary,
+  withHeaders
+};

package/dist/openapi.cjs

@@ -0,0 +1,282 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/openapi.ts
+var openapi_exports = {};
+__export(openapi_exports, {
+  createOpenApiDocument: () => createOpenApiDocument,
+  describedBy: () => describedBy,
+  includeDocument: () => includeDocument,
+  openApiRoute: () => openApiRoute,
+  setJsonSchemaConverter: () => setJsonSchemaConverter
+});
+module.exports = __toCommonJS(openapi_exports);
+
+// src/input.ts
+var DEFAULT_BODY_LIMIT = 1024 * 1024;
+
+// src/route.ts
+var CONTRACT = /* @__PURE__ */ Symbol.for("fluixi.api.contract");
+function contractOf(handler) {
+  return typeof handler === "function" ? handler[CONTRACT] : void 0;
+}
+
+// src/openapi.ts
+var convert;
+function setJsonSchemaConverter(converter) {
+  convert = converter;
+}
+var METHODS = ["get", "post", "put", "patch", "delete"];
+var DESCRIBES = /* @__PURE__ */ Symbol.for("fluixi.api.describes");
+var DESCRIBED_BY = /* @__PURE__ */ Symbol.for("fluixi.api.described-by");
+function describedBy(document, handler) {
+  Object.defineProperty(handler, DESCRIBED_BY, { value: document });
+  return handler;
+}
+var ERROR_SCHEMA = {
+  type: "object",
+  required: ["error"],
+  properties: {
+    error: {
+      type: "object",
+      required: ["code", "message"],
+      properties: {
+        code: { type: "string", description: "Machine-readable, stable: `validation_failed`, `not_found`, `internal`." },
+        message: { type: "string", description: "For people. May change between versions." },
+        details: { description: "For `validation_failed`, the list of `{ path, message }` issues." }
+      }
+    }
+  }
+};
+function createOpenApiDocument(routes, info) {
+  const paths = {};
+  const securitySchemes = {};
+  for (const route of routes) {
+    if (!route.path) continue;
+    for (const method of METHODS) {
+      const handler = route.mod[method.toUpperCase()];
+      if (typeof handler !== "function") continue;
+      const marks = handler;
+      if (marks[DESCRIBES] || marks[DESCRIBED_BY]) continue;
+      (paths[route.path] ??= {})[method] = operation(method, route.path, contractOf(handler), securitySchemes);
+    }
+  }
+  const { servers, ...rest } = info;
+  return {
+    openapi: "3.1.0",
+    info: rest,
+    ...servers?.length ? { servers } : {},
+    paths,
+    components: { schemas: { Error: ERROR_SCHEMA }, ...Object.keys(securitySchemes).length ? { securitySchemes } : {} }
+  };
+}
+function openApiRoute(routes, info) {
+  let cached;
+  const handler = async () => {
+    cached ??= describe(routes(), info).catch((error) => {
+      cached = void 0;
+      throw error;
+    });
+    return new Response(await cached, { headers: { "content-type": "application/json; charset=utf-8" } });
+  };
+  Object.defineProperty(handler, DESCRIBES, { value: true });
+  return handler;
+}
+async function describe(routes, info) {
+  const doc = createOpenApiDocument(routes, info);
+  const mounts = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    if (!route.path) continue;
+    for (const handler of Object.values(route.mod)) {
+      const source = typeof handler === "function" ? handler[DESCRIBED_BY] : void 0;
+      if (source && !mounts.has(source)) mounts.set(source, route.path.replace(/\/\{[^}]+\}$/, ""));
+    }
+  }
+  for (const [source, mount] of mounts) includeDocument(doc, await source(), mount);
+  return JSON.stringify(doc, null, 2);
+}
+function includeDocument(target, source, mount) {
+  const prefix = pascal(mount.split("/").filter(Boolean).pop() ?? "included");
+  const components = target.components ??= {};
+  const prefixed = (name) => prefix + name[0].toUpperCase() + name.slice(1);
+  const renames = /* @__PURE__ */ new Map();
+  for (const [section, entries] of Object.entries(source.components ?? {})) {
+    for (const [name, value] of Object.entries(entries)) {
+      const existing = components[section]?.[name];
+      if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(value)) {
+        renames.set(`#/components/${section}/${name}`, `#/components/${section}/${prefixed(name)}`);
+      }
+    }
+  }
+  const rewrite = (node) => {
+    if (Array.isArray(node)) return node.map(rewrite);
+    if (!node || typeof node !== "object") return node;
+    const out = Object.fromEntries(
+      Object.entries(node).map(([key, value]) => [key, key === "$ref" && typeof value === "string" ? renames.get(value) ?? value : rewrite(value)])
+    );
+    return "nullable" in out ? nullable(out) : out;
+  };
+  for (const [section, entries] of Object.entries(source.components ?? {})) {
+    const into = components[section] ??= {};
+    for (const [name, value] of Object.entries(entries)) {
+      const renamed = renames.has(`#/components/${section}/${name}`) ? prefixed(name) : name;
+      into[renamed] = rewrite(value);
+    }
+  }
+  const paths = target.paths ??= {};
+  const ids = new Set(Object.values(paths).flatMap((item) => Object.values(item).map((op) => op?.operationId)));
+  for (const [path, item] of Object.entries(source.paths ?? {})) {
+    const described = rewrite(item);
+    for (const [method, op] of Object.entries(described)) {
+      if (Array.isArray(op.security)) {
+        op.security = op.security.map(
+          (requirement) => Object.fromEntries(
+            Object.entries(requirement).map(([name, scopes]) => [
+              renames.has(`#/components/securitySchemes/${name}`) ? prefixed(name) : name,
+              scopes
+            ])
+          )
+        );
+      }
+      if (METHODS.includes(method) && !op.summary) op.summary = summaryOf(op, method, mount + path);
+      if (typeof op.operationId === "string" && ids.has(op.operationId)) {
+        op.operationId = prefix[0].toLowerCase() + prefix.slice(1) + op.operationId[0].toUpperCase() + op.operationId.slice(1);
+      }
+      if (typeof op.operationId === "string") ids.add(op.operationId);
+    }
+    paths[mount + path] = described;
+  }
+  const tags = source.tags ?? [];
+  if (tags.length) {
+    const known = target.tags ??= [];
+    for (const tag of tags) if (!known.some((t) => t.name === tag.name)) known.push(tag);
+  }
+}
+function nullable(schema) {
+  const { nullable: isNullable, ...rest } = schema;
+  if (isNullable !== true) return rest;
+  if (typeof rest.type === "string") return { ...rest, type: [rest.type, "null"] };
+  if (Array.isArray(rest.type)) return rest.type.includes("null") ? rest : { ...rest, type: [...rest.type, "null"] };
+  return { anyOf: [rest, { type: "null" }] };
+}
+function summaryOf(op, method, path) {
+  const description = typeof op.description === "string" ? op.description.split(/\.\s|\n/)[0].trim() : "";
+  if (description && description.length <= 60) return description.replace(/\.$/, "");
+  return typeof op.operationId === "string" ? op.operationId.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/^./, (c) => c.toUpperCase()) : summaryFor(method, path);
+}
+function pascal(word) {
+  return word.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}
+function operation(method, path, contract, schemes) {
+  const operationId = contract?.operationId ?? idFor(method, path);
+  if (!contract) {
+    return {
+      operationId,
+      tags: [tagFor(path)],
+      summary: `${method.toUpperCase()} ${path}`,
+      description: "This route declares no contract, so nothing about its input or output is known.",
+      "x-fluixi-contract": false,
+      responses: { default: { description: "Undocumented." } }
+    };
+  }
+  const parameters = [
+    ...parametersFrom(contract.params, "path", pathNames(path)),
+    ...parametersFrom(contract.query, "query", [])
+  ];
+  const success = contract.status ?? (contract.response ? 200 : 204);
+  const responses = {
+    [success]: contract.response ? { description: "Success.", content: { "application/json": { schema: schemaFor(contract.response, "output") } } } : { description: "Success, no content." }
+  };
+  const error = (description) => ({ description, content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } });
+  if (contract.params || contract.query || contract.body) responses[400] = error("The request is not valid: `validation_failed`, `invalid_json`.");
+  if (contract.body) {
+    responses[413] = error("The body is over the limit.");
+    responses[415] = error("The body is not JSON.");
+  }
+  const guard = contract.guard;
+  if (guard) {
+    const refuses = guard.refuses ?? [401];
+    if (refuses.includes(401)) responses[401] = error("Not signed in: `unauthorized`.");
+    if (refuses.includes(403)) responses[403] = error("Signed in, not allowed: `forbidden`, or a more precise code.");
+    if (refuses.includes(503)) responses[503] = error("A service the check depends on cannot answer now; try again.");
+  }
+  if (pathNames(path).length) responses[404] = error("Nothing at this path.");
+  responses[500] = error("A fault on the server. Its detail is logged, never sent.");
+  return {
+    operationId,
+    tags: contract.tags?.length ? contract.tags : [tagFor(path)],
+    // Tools name the request after it (Postman does), so there is always one.
+    summary: contract.summary ?? summaryFor(method, path),
+    ...contract.description ? { description: contract.description } : {},
+    ...contract.deprecated ? { deprecated: true } : {},
+    // Stated on every contracted route, so a public one reads as public rather than unknown.
+    security: security(guard, schemes),
+    ...parameters.length ? { parameters } : {},
+    ...contract.body ? { requestBody: { required: true, content: { "application/json": { schema: schemaFor(contract.body, "input") } } } } : {},
+    responses
+  };
+}
+function security(guard, schemes) {
+  if (!guard?.security) return [];
+  const { name, scheme, scopes } = guard.security;
+  schemes[name] = scheme;
+  return [{ [name]: scopes ?? [] }];
+}
+function parametersFrom(schema, where, names) {
+  if (!schema) return where === "path" ? names.map((name) => ({ name, in: "path", required: true, schema: { type: "string" } })) : [];
+  const json = schemaFor(schema, "input");
+  const properties = json.properties ?? {};
+  const required = new Set(json.required ?? []);
+  return Object.entries(properties).map(([name, property]) => ({
+    name,
+    in: where,
+    required: where === "path" ? true : required.has(name),
+    ...typeof property.description === "string" ? { description: property.description } : {},
+    schema: property,
+    ...where === "query" && property.type === "array" ? { style: "form", explode: true } : {}
+  }));
+}
+function schemaFor(schema, io) {
+  const standard = schema["~standard"].jsonSchema;
+  try {
+    const json = standard?.[io]({ target: "draft-2020-12", libraryOptions: { unrepresentable: "any" } }) ?? convert?.(schema, io);
+    if (json) {
+      const { $schema: _dialect, ...rest } = json;
+      return rest;
+    }
+  } catch {
+  }
+  return { "x-fluixi-unconverted": schema["~standard"].vendor };
+}
+function pathNames(path) {
+  return [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+}
+function tagFor(path) {
+  const segments = path.split("/").filter((s) => s && !s.startsWith("{"));
+  const meaningful = segments.filter((s, i) => !(i === 0 && s === "api") && !/^v\d+$/.test(s));
+  return meaningful[0] ?? "default";
+}
+function summaryFor(method, path) {
+  const words = idFor(method, path).replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  return words[0].toUpperCase() + words.slice(1);
+}
+function idFor(method, path) {
+  const words = path.split("/").filter((s) => s && s !== "api" && !/^v\d+$/.test(s)).map((s) => s.startsWith("{") ? `By-${s.slice(1, -1)}` : s).flatMap((s) => s.split(/[^a-zA-Z0-9]+/)).filter(Boolean);
+  return method + words.map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}