@classytic/arc 1.1.0 → 2.1.3

package/dist/openapi-9nB_kiuR.mjs

@@ -0,0 +1,525 @@
+import { t as getUserRoles } from "./types-DelU6kln.mjs";
+import { n as convertRouteSchema } from "./schemaConverter-Dtg0Kt9T.mjs";
+import fp from "fastify-plugin";
+
+//#region src/docs/openapi.ts
+/**
+* OpenAPI Spec Generator
+*
+* Auto-generates OpenAPI 3.0 specification from Arc resource registry.
+*
+* @example
+* import { openApiPlugin } from '@classytic/arc/docs';
+*
+* await fastify.register(openApiPlugin, {
+*   title: 'My API',
+*   version: '1.0.0',
+* });
+*
+* // Spec available at /_docs/openapi.json
+*/
+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.additionalRoutes || resource.additionalRoutes.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.additionalRoutes || []) {
+		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) : 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);
+	}
+	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 };

package/dist/org/index.d.mts

@@ -0,0 +1,68 @@
+import "../elevation-DGo5shaX.mjs";
+import { S as RouteHandler } from "../interface-e9XfSsUV.mjs";
+import { i as UserBase } from "../types-RLkFVgaw.mjs";
+import "../types/index.mjs";
+import { InvitationAdapter, InvitationDoc, MemberDoc, OrgAdapter, OrgDoc, OrgPermissionStatement, OrgRole, OrganizationPluginOptions } from "./types.mjs";
+import { FastifyPluginAsync, RouteHandlerMethod } from "fastify";
+
+//#region src/org/orgGuard.d.ts
+interface OrgGuardOptions {
+  /** Require organization context (default: true) */
+  requireOrgContext?: boolean;
+  /** Required org-level roles */
+  roles?: string[];
+}
+/**
+ * Create org guard middleware.
+ * Reads `request.scope` for org context and roles.
+ * Elevated scope always passes.
+ */
+declare function orgGuard(options?: OrgGuardOptions): RouteHandler;
+/**
+ * Shorthand for requiring org context
+ */
+declare function requireOrg(): RouteHandler;
+/**
+ * Require org context with specific roles
+ */
+declare function requireOrgRole(...roles: string[]): RouteHandler;
+//#endregion
+//#region src/org/orgMembership.d.ts
+interface OrgMembershipOptions {
+  /** Path to user's organizations array */
+  userOrgsPath?: string;
+  /** Optional DB lookup function */
+  validateFromDb?: (userId: string, orgId: string) => Promise<boolean>;
+}
+interface OrgRolesOptions {
+  /** Path to user's organizations array */
+  userOrgsPath?: string;
+}
+/**
+ * Check if user is member of organization.
+ * This is a low-level utility for checking membership from user object data.
+ * For request-level checks, use `request.scope` (isMember/isElevated guards).
+ */
+declare function orgMembershipCheck(user: UserBase | undefined | null, orgId: string | undefined | null, options?: OrgMembershipOptions): Promise<boolean>;
+/**
+ * Get user's role in organization from user object data.
+ * For request-level role checks, use `request.scope.orgRoles` (when scope is 'member').
+ */
+declare function getUserOrgRoles(user: UserBase | undefined | null, orgId: string | undefined | null, options?: OrgRolesOptions): string[];
+/**
+ * Check if user has specific role in organization from user object data.
+ * For request-level role checks, use `requireOrgRole()` permission or `request.scope`.
+ */
+declare function hasOrgRole(user: UserBase | undefined | null, orgId: string | undefined | null, roles: string | string[], options?: OrgRolesOptions): boolean;
+//#endregion
+//#region src/org/organizationPlugin.d.ts
+declare module 'fastify' {
+  interface FastifyInstance {
+    /** Middleware: require the caller to hold one of the listed org roles */
+    requireOrgRole: (roles: string[]) => RouteHandlerMethod;
+  }
+}
+declare const organizationPlugin: FastifyPluginAsync<OrganizationPluginOptions>;
+declare const _default: FastifyPluginAsync<OrganizationPluginOptions>;
+//#endregion
+export { type InvitationAdapter, type InvitationDoc, type MemberDoc, type OrgAdapter, type OrgDoc, type OrgGuardOptions, type OrgMembershipOptions, type OrgPermissionStatement, type OrgRole, type OrgRolesOptions, type OrganizationPluginOptions, getUserOrgRoles, hasOrgRole, orgGuard, orgMembershipCheck, _default as organizationPlugin, organizationPlugin as organizationPluginFn, requireOrg, requireOrgRole };