@classytic/arc 2.11.4 → 2.14.0

package/dist/openapi-noXno2CV.mjs

@@ -0,0 +1,968 @@
+import { t as getUserRoles } from "./types-D57iXYb8.mjs";
+import { n as convertRouteSchema } from "./schemaConverter-De34B1ZG.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-CyUkQu6O.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-CBxLLbn3.mjs";
+import fp from "fastify-plugin";
+//#region src/docs/openapi/canonical-schemas.ts
+/**
+* Static canonical schemas — referenced once, from
+* `components.schemas`. Per-resource schemas (paginated `oneOf` with
+* the resource's `items.$ref`) are built via
+* `buildPaginatedListSchema(itemRef)` below.
+*/
+const CANONICAL_SCHEMAS = {
+	ErrorDetail: {
+		type: "object",
+		required: ["code", "message"],
+		description: "Single field-scoped error detail. Mirrors `@classytic/repo-core/errors` ErrorDetail.",
+		properties: {
+			path: {
+				type: "string",
+				description: "Dot-path pointer to the offending field (e.g. `lines.0.quantity`)."
+			},
+			code: { type: "string" },
+			message: { type: "string" },
+			meta: {
+				type: "object",
+				additionalProperties: true
+			}
+		}
+	},
+	ErrorContract: {
+		type: "object",
+		required: ["code", "message"],
+		description: "Canonical error wire shape emitted by arc's error handler. Mirrors `@classytic/repo-core/errors` ErrorContract — flat top-level `code` / `message`, NOT nested under `{ error: { ... } }`.",
+		properties: {
+			code: {
+				type: "string",
+				description: "Hierarchical machine code (e.g. `not_found`, `validation_error`, `order.validation.missing_line`). Arc's legacy UPPER_SNAKE codes (`'NOT_FOUND'`, `'VALIDATION_ERROR'`) also flow through this field for back-compat."
+			},
+			message: {
+				type: "string",
+				description: "Human-readable, safe-for-client message."
+			},
+			status: {
+				type: "integer",
+				description: "Suggested HTTP status code."
+			},
+			details: {
+				type: "array",
+				items: { $ref: "#/components/schemas/ErrorDetail" }
+			},
+			correlationId: {
+				type: "string",
+				description: "Trace identifier for support lookups."
+			},
+			meta: {
+				type: "object",
+				additionalProperties: true,
+				description: "Non-PII metadata. Safe to log, safe to return."
+			}
+		}
+	},
+	DeleteResult: {
+		type: "object",
+		required: ["message"],
+		description: "Arc's HTTP DELETE wire shape. The handler returns `{ message, id?, soft? }` (see `BaseCrudController.delete`). // arc-specific extension to repo-core's DeleteResult TYPE — repo-core's type carries internal `count?` for batch adapters that surface counts inline; arc's HTTP handler does not project that to the wire. // arc-specific extension: `meta` (e.g. `{ message: 'Deleted successfully' }`) is merged at the top level by `fastifyAdapter` — `message` already covers that, no second nesting.",
+		properties: {
+			message: {
+				type: "string",
+				description: "Human-readable success message."
+			},
+			id: {
+				type: "string",
+				description: "Primary key of the removed document (string form)."
+			},
+			soft: {
+				type: "boolean",
+				description: "True when a soft-delete plugin intercepted the operation."
+			}
+		}
+	}
+};
+/**
+* Build the per-resource paginated list response schema as a plain
+* `oneOf` of the four canonical list envelopes:
+*
+*   - offset (`{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`)
+*   - keyset (`{ method: 'keyset', data, limit, hasMore, next }`)
+*   - aggregate (`{ method: 'aggregate', data, page, limit, total, pages, hasNext, hasPrev }`)
+*   - bare    (`{ data }`)
+*
+* The first three carry the `method` literal as a discriminant string;
+* codegen tools narrow on `method`. Bare lacks `method` — consumers
+* narrow on its absence.
+*
+* NOTE on shape parity with repo-core/pagination/types.ts:
+*   - Keyset uses `hasMore` (boolean) + `next: string | null` — see
+*     `KeysetPaginationResultCore`. We model `next` as nullable string.
+*   - Offset/aggregate are structurally identical save for the
+*     `method` literal (the discriminant exists so consumers can route
+*     "this came from an aggregate, not a plain find").
+*/
+function buildPaginatedListSchema(itemRef) {
+	return {
+		description: "List response — discriminated union of arc's four canonical list shapes. Branch on `method` (`'offset' | 'keyset' | 'aggregate'`) for paginated results; absence of `method` indicates a bare (unpaginated) list.",
+		oneOf: [
+			{
+				type: "object",
+				required: [
+					"method",
+					"data",
+					"page",
+					"limit",
+					"total",
+					"pages",
+					"hasNext",
+					"hasPrev"
+				],
+				description: "Offset-paginated result.",
+				properties: {
+					method: {
+						type: "string",
+						enum: ["offset"]
+					},
+					data: {
+						type: "array",
+						items: { $ref: itemRef }
+					},
+					page: { type: "integer" },
+					limit: { type: "integer" },
+					total: { type: "integer" },
+					pages: { type: "integer" },
+					hasNext: { type: "boolean" },
+					hasPrev: { type: "boolean" }
+				}
+			},
+			{
+				type: "object",
+				required: [
+					"method",
+					"data",
+					"limit",
+					"hasMore",
+					"next"
+				],
+				description: "Keyset-paginated result.",
+				properties: {
+					method: {
+						type: "string",
+						enum: ["keyset"]
+					},
+					data: {
+						type: "array",
+						items: { $ref: itemRef }
+					},
+					limit: { type: "integer" },
+					hasMore: { type: "boolean" },
+					next: {
+						type: "string",
+						nullable: true,
+						description: "Opaque cursor for the next page, or null when `hasMore` is false. Round-trip verbatim as the `after` query param."
+					}
+				}
+			},
+			{
+				type: "object",
+				required: [
+					"method",
+					"data",
+					"page",
+					"limit",
+					"total",
+					"pages",
+					"hasNext",
+					"hasPrev"
+				],
+				description: "Aggregate-paginated result.",
+				properties: {
+					method: {
+						type: "string",
+						enum: ["aggregate"]
+					},
+					data: {
+						type: "array",
+						items: { $ref: itemRef }
+					},
+					page: { type: "integer" },
+					limit: { type: "integer" },
+					total: { type: "integer" },
+					pages: { type: "integer" },
+					hasNext: { type: "boolean" },
+					hasPrev: { type: "boolean" }
+				}
+			},
+			{
+				type: "object",
+				required: ["data"],
+				description: "Bare (unpaginated) list — `{ data: T[] }` only.",
+				properties: { data: {
+					type: "array",
+					items: { $ref: itemRef }
+				} }
+			}
+		]
+	};
+}
+//#endregion
+//#region src/docs/openapi/field-permissions.ts
+/**
+* Field permission descriptions — appended to schema-property
+* `description` strings during component generation so codegen surfaces
+* the perm rule next to the field type.
+*/
+/**
+* Format a field permission rule for an OpenAPI field description.
+*
+* Mirrors the runtime field-permission types — the four supported rule
+* kinds map to a sentence each.
+*/
+function formatFieldPermDescription(perm) {
+	switch (perm.type) {
+		case "hidden": return "Hidden — never returned in responses";
+		case "visibleTo": return `Visible to: ${(perm.roles ?? []).join(", ")}`;
+		case "writableBy": return `Writable by: ${(perm.roles ?? []).join(", ")}`;
+		case "redactFor": return `Redacted for: ${(perm.roles ?? []).join(", ")}`;
+		default: return perm.type;
+	}
+}
+//#endregion
+//#region src/docs/openapi/components.ts
+/**
+* Generate component schema definitions from pre-stored registry
+* schemas.
+*
+* Schemas are generated at resource definition time and stored in the
+* registry. Response schema priority:
+*   1. If resource provides explicit `openApiSchemas.response`, use it
+*      as-is.
+*   2. Otherwise, auto-generate from `createBody` + `_id` + timestamps.
+*   3. Fallback to a placeholder doc with just `_id` + timestamps.
+*
+* Note: this emits OpenAPI documentation only — does NOT affect Fastify
+* serialization.
+*/
+function generateSchemas(resources) {
+	const schemas = { ...CANONICAL_SCHEMAS };
+	for (const resource of resources) {
+		const storedSchemas = resource.openApiSchemas;
+		const fieldPerms = resource.fieldPermissions;
+		if (storedSchemas?.response) schemas[resource.name] = {
+			type: "object",
+			description: resource.displayName,
+			...storedSchemas.response
+		};
+		else if (storedSchemas?.createBody) schemas[resource.name] = {
+			type: "object",
+			description: resource.displayName,
+			properties: {
+				_id: {
+					type: "string",
+					description: "Unique identifier"
+				},
+				...storedSchemas.createBody.properties ?? {},
+				createdAt: {
+					type: "string",
+					format: "date-time",
+					description: "Creation timestamp"
+				},
+				updatedAt: {
+					type: "string",
+					format: "date-time",
+					description: "Last update timestamp"
+				}
+			}
+		};
+		else schemas[resource.name] = {
+			type: "object",
+			description: resource.displayName,
+			properties: {
+				_id: {
+					type: "string",
+					description: "Unique identifier"
+				},
+				createdAt: {
+					type: "string",
+					format: "date-time",
+					description: "Creation timestamp"
+				},
+				updatedAt: {
+					type: "string",
+					format: "date-time",
+					description: "Last update timestamp"
+				}
+			}
+		};
+		const resourceSchema = schemas[resource.name];
+		if (fieldPerms && resourceSchema?.properties) {
+			const props = resourceSchema.properties;
+			for (const [field, perm] of Object.entries(fieldPerms)) {
+				const propSchema = props[field];
+				if (propSchema) {
+					const desc = propSchema.description ?? "";
+					const permDesc = formatFieldPermDescription(perm);
+					propSchema.description = desc ? `${desc} (${permDesc})` : permDesc;
+				} else if (perm.type === "hidden") {}
+			}
+		}
+		if (storedSchemas?.createBody) {
+			schemas[`${resource.name}Input`] = {
+				type: "object",
+				description: `${resource.displayName} create input`,
+				...storedSchemas.createBody
+			};
+			if (storedSchemas.updateBody) schemas[`${resource.name}Update`] = {
+				type: "object",
+				description: `${resource.displayName} update input`,
+				...storedSchemas.updateBody
+			};
+		} else schemas[`${resource.name}Input`] = {
+			type: "object",
+			description: `${resource.displayName} input`
+		};
+	}
+	return schemas;
+}
+//#endregion
+//#region src/docs/openapi/operations.ts
+/**
+* Standard error responses that every CRUD route ships. Per-route
+* additions (e.g. 404 on get/update/delete, 409 on create/update) are
+* merged on top via `extras.responses`.
+*
+* @internal
+*/
+function buildErrorResponses(opts) {
+	const responses = {};
+	if (opts.requiresAuth) {
+		responses["401"] = {
+			description: "Authentication required — no valid Bearer token provided",
+			content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorContract" } } }
+		};
+		responses["403"] = {
+			description: opts.permRoles?.length ? `Forbidden — requires one of: ${opts.permRoles.join(", ")}` : "Forbidden — insufficient permissions",
+			content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorContract" } } }
+		};
+	}
+	responses["500"] = {
+		description: "Internal server error",
+		content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorContract" } } }
+	};
+	return responses;
+}
+/**
+* Validation / not-found / conflict — appended to specific CRUD
+* operations. Every shape references `ErrorContract`.
+*/
+function errorResponse(description) {
+	return {
+		description,
+		content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorContract" } } }
+	};
+}
+/**
+* Create an operation object.
+*
+* @param requiresAuthOverride Override for whether auth is required (used by
+*  custom routes that pass `permissions: allowPublic()` etc., which the
+*  generic `permissions.{operation}` lookup wouldn't find).
+* @param additionalSecurity Extra security alternatives from external
+*  integrations (OR'd with bearerAuth) — e.g. plugin-injected
+*  `apiKeyAuth + orgHeader` combos.
+*/
+function createOperation(resource, operation, summary, extras, requiresAuthOverride, additionalSecurity = []) {
+	const operationPermission = (resource.permissions || {})[operation];
+	const isPublic = operationPermission?._isPublic === true;
+	operationPermission?._roles;
+	const requiresAuth = requiresAuthOverride !== void 0 ? requiresAuthOverride : typeof operationPermission === "function" && !isPublic;
+	const permAnnotation = describePermissionForOpenApi(operationPermission);
+	const descParts = [];
+	if (permAnnotation) descParts.push(`**Permission**: ${permAnnotation.type === "public" ? "Public" : permAnnotation.type === "requireRoles" ? `Requires roles: ${(permAnnotation.roles ?? []).join(", ")}` : "Requires authentication"}`);
+	if (resource.presets && resource.presets.length > 0) descParts.push(`**Presets**: ${resource.presets.join(", ")}`);
+	const applicableSteps = (resource.pipelineSteps ?? []).filter((s) => {
+		if (!s.operations) return true;
+		return s.operations.includes(operation);
+	});
+	const op = {
+		tags: [resource.tag || "Resource"],
+		summary: `${summary} ${(resource.displayName || resource.name).toLowerCase()}`,
+		operationId: `${resource.name}_${operation}`,
+		...descParts.length > 0 && { description: descParts.join("\n\n") },
+		...requiresAuth && { security: [{ bearerAuth: [] }, ...additionalSecurity] },
+		...permAnnotation && { "x-arc-permission": permAnnotation },
+		...applicableSteps.length > 0 && { "x-arc-pipeline": applicableSteps.map((s) => ({
+			type: s.type,
+			name: s.name
+		})) },
+		responses: buildErrorResponses({
+			requiresAuth,
+			permRoles: permAnnotation?.roles
+		}),
+		...extras
+	};
+	if (extras.responses) op.responses = {
+		...buildErrorResponses({
+			requiresAuth,
+			permRoles: permAnnotation?.roles
+		}),
+		...extras.responses
+	};
+	return op;
+}
+/**
+* Describe a permission check function for OpenAPI.
+* Extracts role, org role, and team permission metadata from permission
+* functions.
+*/
+function describePermissionForOpenApi(check) {
+	if (!check || typeof check !== "function") return void 0;
+	const fn = check;
+	if (fn._isPublic === true) return { type: "public" };
+	const result = { type: "requireAuth" };
+	if (Array.isArray(fn._roles) && fn._roles.length > 0) {
+		result.type = "requireRoles";
+		result.roles = fn._roles;
+	}
+	if (Array.isArray(fn._orgRoles) && fn._orgRoles.length > 0) result.orgRoles = fn._orgRoles;
+	return result;
+}
+//#endregion
+//#region src/docs/openapi/parameters.ts
+/**
+* Default query parameters for list endpoints when the resource hasn't
+* provided an explicit `openApiSchemas.listQuery` schema. These match
+* the defaults arc's `QueryParser` honours, so codegen consumers get
+* working scaffolds even for kits that don't surface a typed list query.
+*/
+const DEFAULT_LIST_PARAMS = [
+	{
+		name: "page",
+		in: "query",
+		schema: { type: "integer" },
+		description: "Page number"
+	},
+	{
+		name: "limit",
+		in: "query",
+		schema: { type: "integer" },
+		description: "Items per page"
+	},
+	{
+		name: "sort",
+		in: "query",
+		schema: { type: "string" },
+		description: "Sort field (prefix with - for descending)"
+	}
+];
+/**
+* Convert Fastify-style params (`/:id`) to OpenAPI-style params
+* (`/{id}`).
+*/
+function toOpenApiPath(path) {
+	return path.replace(/:([^/]+)/g, "{$1}");
+}
+/**
+* Convert a JSON-Schema `{ type: 'object', properties: {...} }` into an
+* OpenAPI parameter array — each property becomes one query parameter.
+*
+* `description` is lifted from the property to the Parameter level
+* (OpenAPI's preferred location); the rest of the schema body stays in
+* `param.schema`.
+*/
+function convertSchemaToParameters(schema) {
+	const params = [];
+	const properties = schema.properties || {};
+	const required = schema.required || [];
+	for (const [name, prop] of Object.entries(properties)) {
+		const description = prop.description;
+		const { description: _, ...schemaProps } = prop;
+		const param = {
+			name,
+			in: "query",
+			required: required.includes(name),
+			schema: schemaProps
+		};
+		if (description) param.description = description;
+		params.push(param);
+	}
+	return params;
+}
+/**
+* Extract path parameters from a route path (e.g. `/foo/:id/bar/:slug`
+* → `[{ name: 'id', ...}, { name: 'slug', ...}]`). All extracted params
+* are typed as `string` — Fastify path captures are always strings.
+*/
+function extractPathParams(path) {
+	const params = [];
+	const matches = path.matchAll(/:([^/]+)/g);
+	for (const match of matches) {
+		const paramName = match[1];
+		if (paramName) params.push({
+			name: paramName,
+			in: "path",
+			required: true,
+			schema: { type: "string" }
+		});
+	}
+	return params;
+}
+//#endregion
+//#region src/docs/openapi/action-paths.ts
+/**
+* Action endpoint emitter — `POST /:resource/:id/action`.
+*
+* Generates a single dispatch endpoint per resource that lists every
+* declared action via the `action` discriminant. Body schema is built
+* via the SAME `buildActionBodySchema` runtime uses, so docs and
+* validation stay in sync (one source of truth for the action envelope
+* shape).
+*
+* NOTE: action **response** shape varies per action — the dispatcher
+* returns whatever the handler returned. We can't statically type the
+* response without the handler exposing its return type, and most
+* handlers return either the mutated resource document or a kit-defined
+* envelope. We declare the `200` body schema as an empty object (`{}`)
+* which `@hey-api/openapi-ts` and friends compile to `unknown` — that's
+* the most accurate thing we can say without lying to consumers about
+* shape. Per-action shape is documented in the `description` field;
+* future work could let resource authors declare a per-action
+* `responseSchema`.
+*/
+/**
+* Append the action-dispatch path (`POST /:basePath/:id/action`) when
+* the resource declares any `actions`.
+*/
+function appendActionPaths(paths, resource, basePath, additionalSecurity) {
+	if (!resource.actions || resource.actions.length === 0) return;
+	const actionPath = toOpenApiPath(`${basePath}/:id/action`);
+	const actionEnum = resource.actions.map((a) => a.name);
+	const actionSchemas = {};
+	for (const a of resource.actions) if (a.schema) actionSchemas[a.name] = a.schema;
+	const bodySchema = buildActionBodySchema(actionEnum, actionSchemas);
+	const descLines = [
+		"Unified action endpoint for state transitions.",
+		"",
+		"**Available actions:**"
+	];
+	for (const a of resource.actions) {
+		const roles = a.permissions?._roles;
+		const roleStr = roles?.length ? ` — requires: ${roles.join(" or ")}` : "";
+		const descStr = a.description ? ` — ${a.description}` : "";
+		descLines.push(`- \`${a.name}\`${roleStr}${descStr}`);
+	}
+	descLines.push("", "Response shape depends on the action handler — typically the mutated resource document or a kit-defined result envelope. See the per-action description above.");
+	const anyAuthRequired = resource.actions.some((a) => {
+		const effective = resolveActionPermission({
+			action: { permissions: a.permissions },
+			resourcePermissions: resource.permissions,
+			resourceActionPermissions: resource.actionPermissions
+		});
+		return typeof effective === "function" && !effective._isPublic;
+	});
+	if (!paths[actionPath]) paths[actionPath] = {};
+	paths[actionPath].post = createOperation(resource, "action", `Perform action (${actionEnum.join(" / ")})`, {
+		parameters: [{
+			name: "id",
+			in: "path",
+			required: true,
+			schema: { type: "string" },
+			description: "Resource ID"
+		}],
+		description: descLines.join("\n"),
+		requestBody: {
+			required: true,
+			content: { "application/json": { schema: bodySchema } }
+		},
+		responses: {
+			"200": {
+				description: "Action executed successfully",
+				content: { "application/json": { schema: {} } }
+			},
+			"400": errorResponse("Invalid action or missing required fields"),
+			"404": errorResponse("Resource not found")
+		}
+	}, anyAuthRequired, additionalSecurity);
+}
+//#endregion
+//#region src/docs/openapi/aggregation-paths.ts
+/**
+* Emit one OpenAPI path entry per declared aggregation.
+*
+* Path:     `GET /:resource/aggregations/<name>`
+* Response: `{ rows: AggregationRow[] }` where each row is keyed by
+*           the groupBy fields (nested object for joined-alias paths)
+*           plus the measure aliases.
+*/
+function appendAggregationPaths(paths, resource, basePath, additionalSecurity) {
+	if (!resource.aggregations) return;
+	for (const agg of resource.aggregations) {
+		const path = toOpenApiPath(`${basePath}/aggregations/${agg.name}`);
+		const requiresAuth = !agg.permissions?._isPublic;
+		const rowSchema = buildAggregationRowSchema(normalizeGroupByForOpenApi(agg.groupBy), agg.measures, agg.lookupAliases);
+		const querystring = {
+			type: "object",
+			properties: {},
+			additionalProperties: true
+		};
+		if (agg.requireDateRange) {
+			const props = querystring.properties;
+			const f = agg.requireDateRange.field;
+			props[`${f}[gte]`] = {
+				type: "string",
+				description: `Lower bound (inclusive) of required date range on \`${f}\`.`
+			};
+			props[`${f}[lte]`] = {
+				type: "string",
+				description: `Upper bound (inclusive) of required date range on \`${f}\`.`
+			};
+		}
+		if (agg.requireFilters?.length) {
+			const props = querystring.properties;
+			for (const f of agg.requireFilters) props[f] = {
+				type: "string",
+				description: `Required filter on \`${f}\` — request rejected (400) if missing.`
+			};
+		}
+		const descLines = [];
+		if (agg.description) descLines.push(agg.description);
+		descLines.push("Portable aggregation. Caller filters via query string narrow the base + tenant scope; response shape is `{ rows: [...] }` matching repo-core's `AggResult` contract.");
+		if (Object.keys(agg.measures).length > 0) {
+			const measureLines = Object.entries(agg.measures).map(([alias, op]) => `- \`${alias}\` — \`${op}\``).join("\n");
+			descLines.push("", "**Measures:**", measureLines);
+		}
+		if (agg.requireDateRange) descLines.push("", `**Required date range** on \`${agg.requireDateRange.field}\` — supply \`?${agg.requireDateRange.field}[gte]=...&${agg.requireDateRange.field}[lte]=...\`.` + (agg.requireDateRange.maxRangeDays ? ` Range cap: ${agg.requireDateRange.maxRangeDays} days.` : ""));
+		if (!paths[path]) paths[path] = {};
+		paths[path].get = createOperation(resource, `aggregation.${agg.name}`, agg.summary ?? `Aggregation: ${agg.name}`, {
+			description: descLines.join("\n"),
+			parameters: [{
+				name: "querystring",
+				in: "query",
+				required: false,
+				schema: querystring,
+				description: "Filter narrowing — composes with base filter + tenant scope."
+			}],
+			responses: {
+				"200": {
+					description: "Aggregation result",
+					content: { "application/json": { schema: {
+						type: "object",
+						required: ["rows"],
+						properties: { rows: {
+							type: "array",
+							items: rowSchema
+						} }
+					} } }
+				},
+				"400": errorResponse("Missing required filter or invalid date range"),
+				"422": errorResponse("Result row count exceeded `maxGroups` cap"),
+				"501": errorResponse("Adapter does not implement `aggregate()`"),
+				"504": errorResponse("Aggregation execution timed out")
+			}
+		}, requiresAuth, additionalSecurity);
+	}
+}
+/**
+* Build the JSON Schema for a single aggregation row. Combines the
+* groupBy field shape (nested for joined-alias paths) with the
+* measure-alias scalars.
+*
+* Group keys with dotted paths (e.g. `'category.code'`) emit a nested
+* `category: { code: string }` object, matching the cross-kit
+* `nestDottedKeys` output. Plain group keys are flat.
+*
+* Measure scalars are always `number` — every measure op
+* (`count` / `sum` / `avg` / `min` / `max` / `countDistinct`)
+* produces a numeric result.
+*/
+function buildAggregationRowSchema(groupByFields, measures, _lookupAliases) {
+	const properties = {};
+	for (const field of groupByFields) setNestedSchemaProp(properties, field.split("."), { type: "string" });
+	for (const alias of Object.keys(measures)) properties[alias] = { type: "number" };
+	return {
+		type: "object",
+		properties,
+		additionalProperties: false
+	};
+}
+function normalizeGroupByForOpenApi(groupBy) {
+	if (!groupBy) return [];
+	return typeof groupBy === "string" ? [groupBy] : groupBy;
+}
+function setNestedSchemaProp(target, path, leaf) {
+	if (path.length === 1) {
+		target[path[0]] = leaf;
+		return;
+	}
+	const head = path[0];
+	const rest = path.slice(1);
+	let nested = target[head];
+	if (!nested || typeof nested !== "object") {
+		nested = {
+			type: "object",
+			properties: {}
+		};
+		target[head] = nested;
+	}
+	if (!nested.properties) nested.properties = {};
+	setNestedSchemaProp(nested.properties, rest, leaf);
+}
+//#endregion
+//#region src/docs/openapi/crud-paths.ts
+/**
+* Append the default-CRUD paths (`GET /` list + `POST /` create on the
+* collection path; `GET/PATCH|PUT/DELETE /:id` on the item path).
+* Honours `disableDefaultRoutes`, `disabledRoutes`, and `updateMethod`.
+*/
+function appendCrudPaths(paths, resource, basePath, additionalSecurity) {
+	if (resource.disableDefaultRoutes) return;
+	const disabledSet = new Set(resource.disabledRoutes ?? []);
+	const updateMethod = resource.updateMethod ?? "PATCH";
+	const collectionPath = {};
+	if (!disabledSet.has("list")) collectionPath.get = createOperation(resource, "list", "List all", {
+		parameters: resource.openApiSchemas?.listQuery ? convertSchemaToParameters(resource.openApiSchemas.listQuery) : DEFAULT_LIST_PARAMS,
+		responses: {
+			"200": {
+				description: "List of items",
+				content: { "application/json": { schema: buildPaginatedListSchema(`#/components/schemas/${resource.name}`) } }
+			},
+			"400": errorResponse("Validation error — bad filter / sort / pagination params")
+		}
+	}, void 0, additionalSecurity);
+	if (!disabledSet.has("create")) collectionPath.post = createOperation(resource, "create", "Create new", {
+		requestBody: {
+			required: true,
+			content: { "application/json": { schema: { $ref: `#/components/schemas/${resource.name}Input` } } }
+		},
+		responses: {
+			"201": {
+				description: "Created successfully",
+				content: { "application/json": { schema: { $ref: `#/components/schemas/${resource.name}` } } }
+			},
+			"400": errorResponse("Validation error — request body failed schema validation"),
+			"409": errorResponse("Conflict — duplicate key on a unique-indexed field")
+		}
+	}, void 0, additionalSecurity);
+	if (Object.keys(collectionPath).length > 0) paths[basePath] = collectionPath;
+	const itemPath = {};
+	if (!disabledSet.has("get")) itemPath.get = createOperation(resource, "get", "Get by ID", {
+		parameters: [{
+			name: "id",
+			in: "path",
+			required: true,
+			schema: { type: "string" }
+		}],
+		responses: {
+			"200": {
+				description: "Item found",
+				content: { "application/json": { schema: { $ref: `#/components/schemas/${resource.name}` } } }
+			},
+			"404": errorResponse("Not found")
+		}
+	}, void 0, additionalSecurity);
+	if (!disabledSet.has("update")) {
+		const updateOp = createOperation(resource, "update", "Update", {
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" }
+			}],
+			requestBody: {
+				required: true,
+				content: { "application/json": { schema: { $ref: `#/components/schemas/${resource.name}Input` } } }
+			},
+			responses: {
+				"200": {
+					description: "Updated successfully",
+					content: { "application/json": { schema: { $ref: `#/components/schemas/${resource.name}` } } }
+				},
+				"400": errorResponse("Validation error — request body failed schema validation"),
+				"404": errorResponse("Not found"),
+				"409": errorResponse("Conflict — duplicate key on a unique-indexed field")
+			}
+		}, void 0, additionalSecurity);
+		if (updateMethod === "both") {
+			itemPath.put = updateOp;
+			itemPath.patch = updateOp;
+		} else if (updateMethod === "PUT") itemPath.put = updateOp;
+		else itemPath.patch = updateOp;
+	}
+	if (!disabledSet.has("delete")) itemPath.delete = createOperation(resource, "delete", "Delete", {
+		parameters: [{
+			name: "id",
+			in: "path",
+			required: true,
+			schema: { type: "string" }
+		}],
+		responses: {
+			"200": {
+				description: "Deleted successfully",
+				content: { "application/json": { schema: { $ref: "#/components/schemas/DeleteResult" } } }
+			},
+			"404": errorResponse("Not found")
+		}
+	}, void 0, additionalSecurity);
+	if (Object.keys(itemPath).length > 0) paths[toOpenApiPath(`${basePath}/:id`)] = itemPath;
+}
+//#endregion
+//#region src/docs/openapi/custom-paths.ts
+/**
+* Append every entry in `resource.customRoutes` to the `paths` map.
+*/
+function appendCustomRoutePaths(paths, resource, basePath, additionalSecurity) {
+	for (const route of resource.customRoutes || []) {
+		const fullPath = toOpenApiPath(`${basePath}${route.path}`);
+		const method = route.method.toLowerCase();
+		if (!paths[fullPath]) paths[fullPath] = {};
+		const handlerName = route.operation ?? (typeof route.handler === "string" ? route.handler : "handler");
+		const isPublicRoute = route.permissions?._isPublic === true;
+		const requiresAuthForRoute = !!route.permissions && !isPublicRoute;
+		const extras = {
+			parameters: extractPathParams(route.path),
+			responses: { "200": { description: route.description || "Success" } }
+		};
+		const rawSchema = route.schema;
+		const routeSchema = rawSchema ? convertRouteSchema(rawSchema, "openapi-3.0") : void 0;
+		if (routeSchema?.body && [
+			"post",
+			"put",
+			"patch"
+		].includes(method)) extras.requestBody = {
+			required: true,
+			content: { "application/json": { schema: routeSchema.body } }
+		};
+		if (routeSchema?.querystring) {
+			const queryParams = convertSchemaToParameters(routeSchema.querystring);
+			extras.parameters = [...extras.parameters || [], ...queryParams];
+		}
+		if (routeSchema?.response) {
+			const responseSchemas = routeSchema.response;
+			for (const [statusCode, schema] of Object.entries(responseSchemas)) extras.responses[statusCode] = {
+				description: schema.description || `Response ${statusCode}`,
+				content: { "application/json": { schema } }
+			};
+		}
+		paths[fullPath][method] = createOperation(resource, handlerName, route.summary ?? handlerName, extras, requiresAuthForRoute, additionalSecurity);
+	}
+}
+//#endregion
+//#region src/docs/openapi/paths.ts
+/**
+* Generate the OpenAPI `paths` entries for a single resource.
+*/
+function generateResourcePaths(resource, apiPrefix = "", additionalSecurity = []) {
+	const paths = {};
+	const basePath = `${apiPrefix}${resource.prefix}`;
+	appendCrudPaths(paths, resource, basePath, additionalSecurity);
+	appendCustomRoutePaths(paths, resource, basePath, additionalSecurity);
+	appendActionPaths(paths, resource, basePath, additionalSecurity);
+	appendAggregationPaths(paths, resource, basePath, additionalSecurity);
+	return paths;
+}
+//#endregion
+//#region src/docs/openapi/index.ts
+const openApiPlugin = async (fastify, opts = {}) => {
+	const { title = "Arc API", version = "1.0.0", description, serverUrl, prefix = "/_docs", apiPrefix = "", authRoles = [] } = opts;
+	const buildSpec = () => {
+		const arc = fastify.arc;
+		const resources = arc?.registry?.getAll() ?? [];
+		const externalPaths = arc?.externalOpenApiPaths ?? [];
+		return buildOpenApiSpec(resources, {
+			title,
+			version,
+			description,
+			serverUrl,
+			apiPrefix
+		}, externalPaths.length > 0 ? externalPaths : void 0);
+	};
+	fastify.get(`${prefix}/openapi.json`, async (request, reply) => {
+		if (authRoles.length > 0) {
+			const user = request.user;
+			const roles = getUserRoles(user);
+			if (!authRoles.some((r) => roles.includes(r)) && !roles.includes("superadmin")) {
+				reply.code(403).send({ error: "Access denied" });
+				return;
+			}
+		}
+		return buildSpec();
+	});
+	fastify.log?.debug?.(`OpenAPI spec available at ${prefix}/openapi.json`);
+};
+/**
+* Build OpenAPI spec from registry resources.
+* Shared by HTTP docs endpoint and CLI export command.
+*/
+function buildOpenApiSpec(resources, options = {}, externalPaths) {
+	const { title = "Arc API", version = "1.0.0", description, serverUrl, apiPrefix = "" } = options;
+	const paths = {};
+	const tags = [];
+	const additionalSecurity = externalPaths?.flatMap((ext) => ext.resourceSecurity ?? []) ?? [];
+	for (const resource of resources) {
+		const tagDescParts = [`${resource.displayName || resource.name} operations`];
+		if (resource.presets && resource.presets.length > 0) tagDescParts.push(`Presets: ${resource.presets.join(", ")}`);
+		if (resource.pipelineSteps && resource.pipelineSteps.length > 0) {
+			const stepNames = resource.pipelineSteps.map((s) => `${s.type}(${s.name})`);
+			tagDescParts.push(`Pipeline: ${stepNames.join(" → ")}`);
+		}
+		if (resource.events && resource.events.length > 0) tagDescParts.push(`Events: ${resource.events.join(", ")}`);
+		tags.push({
+			name: resource.tag || resource.name,
+			description: tagDescParts.join(". ")
+		});
+		const resourcePaths = generateResourcePaths(resource, apiPrefix, additionalSecurity);
+		Object.assign(paths, resourcePaths);
+	}
+	if (externalPaths) for (const ext of externalPaths) {
+		for (const [path, methods] of Object.entries(ext.paths)) paths[path] = paths[path] ? {
+			...paths[path],
+			...methods
+		} : methods;
+		if (ext.tags) {
+			for (const tag of ext.tags) if (!tags.find((t) => t.name === tag.name)) tags.push(tag);
+		}
+	}
+	const externalSecuritySchemes = externalPaths?.reduce((acc, ext) => ({
+		...acc,
+		...ext.securitySchemes
+	}), {}) ?? {};
+	const externalSchemas = externalPaths?.reduce((acc, ext) => ({
+		...acc,
+		...ext.schemas
+	}), {}) ?? {};
+	return {
+		openapi: "3.0.3",
+		info: {
+			title,
+			version,
+			...description && { description }
+		},
+		...serverUrl && { servers: [{ url: serverUrl }] },
+		paths,
+		components: {
+			schemas: {
+				...generateSchemas(resources),
+				...externalSchemas
+			},
+			securitySchemes: {
+				bearerAuth: {
+					type: "http",
+					scheme: "bearer",
+					bearerFormat: "JWT"
+				},
+				orgHeader: {
+					type: "apiKey",
+					in: "header",
+					name: "x-organization-id"
+				},
+				...externalSecuritySchemes
+			}
+		},
+		tags
+	};
+}
+var openapi_default = fp(openApiPlugin, {
+	name: "arc-openapi",
+	fastify: "5.x"
+});
+//#endregion
+export { openApiPlugin as n, openapi_default as r, buildOpenApiSpec as t };