@classytic/arc 2.11.4 → 2.14.0

package/dist/openapi-D7G1V7ex.mjs

@@ -1,557 +0,0 @@
-import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
-import { n as convertRouteSchema } from "./schemaConverter-B0oKLuqI.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-sUUKDhtP.mjs";
-import { t as buildActionBodySchema } from "./createActionRouter-CIKOcNA7.mjs";
-import fp from "fastify-plugin";
-//#region src/docs/openapi.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
-	};
-}
-/**
-* Convert Fastify-style params (/:id) to OpenAPI-style params (/{id})
-*/
-function toOpenApiPath(path) {
-	return path.replace(/:([^/]+)/g, "{$1}");
-}
-/**
-* Convert OpenAPI schema to query parameters array
-* Transforms { properties: { page: { type: 'integer' } } } to [{ name: 'page', in: 'query', schema: { type: 'integer' } }]
-*/
-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;
-}
-/**
-* Default query parameters when no listQuery schema is provided
-*/
-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)"
-	}
-];
-/**
-* Generate paths for a resource
-*/
-function generateResourcePaths(resource, apiPrefix = "", additionalSecurity = []) {
-	const paths = {};
-	const basePath = `${apiPrefix}${resource.prefix}`;
-	if (resource.disableDefaultRoutes && (!resource.customRoutes || resource.customRoutes.length === 0) && (!resource.actions || resource.actions.length === 0)) return paths;
-	if (!resource.disableDefaultRoutes) {
-		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: {
-					type: "object",
-					properties: {
-						success: { type: "boolean" },
-						docs: {
-							type: "array",
-							items: { $ref: `#/components/schemas/${resource.name}` }
-						},
-						page: { type: "integer" },
-						limit: { type: "integer" },
-						total: { type: "integer" },
-						pages: { type: "integer" },
-						hasNext: { type: "boolean" },
-						hasPrev: { type: "boolean" }
-					}
-				} } }
-			} }
-		}, 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: {
-					type: "object",
-					properties: {
-						success: { type: "boolean" },
-						data: { $ref: `#/components/schemas/${resource.name}` },
-						message: { type: "string" }
-					}
-				} } }
-			} }
-		}, 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: {
-						type: "object",
-						properties: {
-							success: { type: "boolean" },
-							data: { $ref: `#/components/schemas/${resource.name}` }
-						}
-					} } }
-				},
-				"404": { description: "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: {
-						type: "object",
-						properties: {
-							success: { type: "boolean" },
-							data: { $ref: `#/components/schemas/${resource.name}` },
-							message: { type: "string" }
-						}
-					} } }
-				} }
-			}, 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: {
-					type: "object",
-					properties: {
-						success: { type: "boolean" },
-						message: { type: "string" }
-					}
-				} } }
-			} }
-		}, void 0, additionalSecurity);
-		if (Object.keys(itemPath).length > 0) paths[toOpenApiPath(`${basePath}/:id`)] = itemPath;
-	}
-	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);
-	}
-	if (resource.actions && resource.actions.length > 0) {
-		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}`);
-		}
-		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" },
-				"400": { description: "Invalid action or missing required fields" },
-				"401": { description: "Authentication required" },
-				"403": { description: "Permission denied" }
-			}
-		}, anyAuthRequired, additionalSecurity);
-	}
-	return paths;
-}
-/**
-* Create an operation object
-* @param requiresAuthOverride - Override for whether auth is required (for additional routes)
-* @param additionalSecurity - Extra security alternatives from external integrations (OR'd with bearerAuth)
-*/
-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);
-	});
-	return {
-		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: {
-			...requiresAuth && {
-				"401": {
-					description: "Authentication required — no valid Bearer token provided",
-					content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }
-				},
-				"403": {
-					description: permAnnotation?.roles ? `Forbidden — requires one of: ${permAnnotation.roles.join(", ")}` : "Forbidden — insufficient permissions",
-					content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }
-				}
-			},
-			"500": { description: "Internal server error" }
-		},
-		...extras
-	};
-}
-/**
-* 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;
-}
-/**
-* Extract path parameters from route path
-*/
-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;
-}
-/**
-* Generate 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
-*
-* Note: This is for OpenAPI documentation only - does NOT affect Fastify serialization.
-*/
-function generateSchemas(resources) {
-	const schemas = { Error: {
-		type: "object",
-		properties: {
-			success: {
-				type: "boolean",
-				example: false
-			},
-			error: { type: "string" },
-			code: { type: "string" },
-			requestId: { type: "string" },
-			timestamp: { type: "string" }
-		}
-	} };
-	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"
-				}
-			}
-		};
-		if (fieldPerms && schemas[resource.name]?.properties) {
-			const props = schemas[resource.name].properties;
-			for (const [field, perm] of Object.entries(fieldPerms)) if (props[field]) {
-				const desc = props[field]?.description ?? "";
-				const permDesc = formatFieldPermDescription(perm);
-				props[field].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;
-}
-/**
-* Format a field permission description for OpenAPI
-*/
-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;
-	}
-}
-var openapi_default = fp(openApiPlugin, {
-	name: "arc-openapi",
-	fastify: "5.x"
-});
-//#endregion
-export { openApiPlugin as n, openapi_default as r, buildOpenApiSpec as t };