@classytic/arc 2.10.8 → 2.11.1

package/dist/createActionRouter-C8UUB3Px.mjs

@@ -1,249 +0,0 @@
-import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
-import { n as normalizePermissionResult, t as applyPermissionResult } from "./applyPermissionResult-QhV1Pa-g.mjs";
-import { a as toJsonSchema } from "./schemaConverter-BxFDdtXu.mjs";
-//#region src/core/createActionRouter.ts
-var createActionRouter_exports = /* @__PURE__ */ __exportAll({
-	buildActionBodySchema: () => buildActionBodySchema,
-	createActionRouter: () => createActionRouter
-});
-/**
-* Create action-based state transition endpoint
-*
-* Registers: POST /:id/action
-* Body: { action: string, ...actionData }
-*
-* @param fastify - Fastify instance
-* @param config - Action router configuration
-*/
-function createActionRouter(fastify, config) {
-	const { tag, actions, actionPermissions = {}, actionSchemas = {}, globalAuth, idempotencyService, onError } = config;
-	const actionEnum = Object.keys(actions);
-	if (actionEnum.length === 0) {
-		fastify.log.warn("[createActionRouter] No actions defined, skipping route creation");
-		return;
-	}
-	const bodySchema = buildActionBodySchema(actionEnum, actionSchemas);
-	const routeSchema = {
-		tags: tag ? [tag] : void 0,
-		summary: `Perform action (${actionEnum.join("/")})`,
-		description: buildActionDescription(actions, actionPermissions),
-		params: {
-			type: "object",
-			properties: { id: {
-				type: "string",
-				description: "Resource ID"
-			} },
-			required: ["id"]
-		},
-		body: bodySchema
-	};
-	const preHandler = [];
-	const hasPublicActions = Object.entries(actionPermissions).some(([, p]) => p?._isPublic) || globalAuth && globalAuth?._isPublic;
-	const hasProtectedActions = Object.entries(actionPermissions).some(([, p]) => !p?._isPublic) || globalAuth && !globalAuth?._isPublic;
-	if (hasProtectedActions && !hasPublicActions && fastify.authenticate) preHandler.push(fastify.authenticate);
-	fastify.post("/:id/action", {
-		schema: routeSchema,
-		preHandler: preHandler.length ? preHandler : void 0
-	}, async (req, reply) => {
-		const { action, ...data } = req.body;
-		const { id } = req.params;
-		const rawIdempotencyKey = req.headers["idempotency-key"];
-		const idempotencyKey = Array.isArray(rawIdempotencyKey) ? rawIdempotencyKey[0] : rawIdempotencyKey;
-		const handler = actions[action];
-		if (!handler) return reply.code(400).send({
-			success: false,
-			error: `Invalid action '${action}'. Valid actions: ${actionEnum.join(", ")}`,
-			validActions: actionEnum
-		});
-		const permissionCheck = actionPermissions[action] ?? globalAuth;
-		if (hasPublicActions && hasProtectedActions && permissionCheck) {
-			if (!permissionCheck?._isPublic && fastify.authenticate) {
-				try {
-					await fastify.authenticate(req, reply);
-				} catch {
-					if (!reply.sent) return reply.code(401).send({
-						success: false,
-						error: "Authentication required"
-					});
-					return;
-				}
-				if (reply.sent) return;
-			}
-		}
-		if (permissionCheck) {
-			const context = {
-				user: req.user ?? null,
-				request: req,
-				resource: tag ?? "action",
-				action,
-				resourceId: id,
-				params: req.params,
-				data
-			};
-			let result;
-			try {
-				result = await permissionCheck(context);
-			} catch (err) {
-				req.log?.warn?.({
-					err,
-					resource: tag ?? "action",
-					action
-				}, "Permission check threw");
-				return reply.code(403).send({
-					success: false,
-					error: "Permission denied"
-				});
-			}
-			const permResult = normalizePermissionResult(result);
-			if (!permResult.granted) return reply.code(context.user ? 403 : 401).send({
-				success: false,
-				error: permResult.reason ?? (context.user ? `Permission denied for '${action}'` : "Authentication required")
-			});
-			applyPermissionResult(permResult, req);
-		}
-		try {
-			if (idempotencyKey && idempotencyService) {
-				const user = req.user;
-				const payloadForHash = {
-					action,
-					id,
-					data,
-					userId: (user?._id)?.toString?.() || user?.id || null
-				};
-				const idempotencyResult = await idempotencyService.check(idempotencyKey, payloadForHash);
-				if (!idempotencyResult.isNew && "existingResult" in idempotencyResult) return reply.send({
-					success: true,
-					data: idempotencyResult.existingResult,
-					cached: true
-				});
-			}
-			const result = await handler(id, data, req);
-			if (idempotencyService) await idempotencyService.complete(idempotencyKey, result);
-			return reply.send({
-				success: true,
-				data: result
-			});
-		} catch (error) {
-			if (idempotencyService) await idempotencyService.fail(idempotencyKey, error);
-			if (onError) {
-				const { statusCode, error: errorMsg, code } = onError(error, action, id);
-				return reply.code(statusCode).send({
-					success: false,
-					error: errorMsg,
-					code
-				});
-			}
-			const err = error;
-			const statusCode = err.statusCode || err.status || 500;
-			const errorCode = err.code || "ACTION_FAILED";
-			if (statusCode >= 500) req.log.error({
-				err: error,
-				action,
-				id
-			}, "Action handler error");
-			return reply.code(statusCode).send({
-				success: false,
-				error: err.message || `Failed to execute '${action}' action`,
-				code: errorCode
-			});
-		}
-	});
-	fastify.log.debug({
-		actions: actionEnum,
-		tag
-	}, "[createActionRouter] Registered action endpoint: POST /:id/action");
-}
-/**
-* Build a discriminated body schema for the unified action endpoint.
-*
-* Produces a schema of the form:
-* ```json
-* {
-*   "type": "object",
-*   "required": ["action"],
-*   "oneOf": [
-*     { "properties": { "action": { "const": "dispatch" }, "carrier": {...} }, "required": ["action", "carrier"] },
-*     { "properties": { "action": { "const": "approve" } }, "required": ["action"] }
-*   ]
-* }
-* ```
-*
-* AJV validates this natively, so an action call missing required fields is
-* rejected with HTTP 400 before the handler ever runs.
-*
-* Exported so OpenAPI generation and MCP tool generation can reuse the same
-* schema shape (single source of truth).
-*/
-function buildActionBodySchema(actionEnum, actionSchemas = {}) {
-	const branches = [];
-	for (const actionName of actionEnum) {
-		const raw = actionSchemas[actionName];
-		const { properties, required } = normalizeActionSchema(raw);
-		const branchProperties = {
-			action: {
-				type: "string",
-				const: actionName
-			},
-			...properties
-		};
-		const branchRequired = ["action", ...required.filter((r) => r !== "action")];
-		branches.push({
-			type: "object",
-			properties: branchProperties,
-			required: branchRequired
-		});
-	}
-	return {
-		type: "object",
-		required: ["action"],
-		oneOf: branches
-	};
-}
-/**
-* Normalize the accepted schema shapes into `{ properties, required }`.
-*
-* Handles:
-* 1. Full JSON Schema object (has `type: 'object'` + `properties`)
-* 2. Zod v4 schema (has `_zod` marker) — converted via `toJsonSchema`
-* 3. Legacy field map (`{ fieldName: { type: 'string' } }`) — every field required
-*    unless its schema has `nullable: true` or sentinel `required: false`
-*/
-function normalizeActionSchema(raw) {
-	if (!raw || typeof raw !== "object") return {
-		properties: {},
-		required: []
-	};
-	const converted = toJsonSchema(raw);
-	if (converted && typeof converted === "object" && (converted.type === "object" || "properties" in converted)) return {
-		properties: converted.properties ?? {},
-		required: Array.isArray(converted.required) ? converted.required : []
-	};
-	const properties = {};
-	const required = [];
-	for (const [fieldName, fieldSchema] of Object.entries(raw)) {
-		if (fieldName === "type" || fieldName === "properties" || fieldName === "required") continue;
-		if (!fieldSchema || typeof fieldSchema !== "object") continue;
-		const fs = fieldSchema;
-		properties[fieldName] = fs;
-		if (fs.required !== false) required.push(fieldName);
-	}
-	return {
-		properties,
-		required
-	};
-}
-/**
-* Build description with action details
-* Uses _roles metadata from PermissionCheck functions for OpenAPI docs
-*/
-function buildActionDescription(actions, actionPermissions) {
-	const lines = ["Unified action endpoint for state transitions.\n\n**Available actions:**"];
-	Object.keys(actions).forEach((action) => {
-		const roles = actionPermissions[action]?._roles;
-		const roleStr = roles?.length ? ` (requires: ${roles.join(" or ")})` : "";
-		lines.push(`- \`${action}\`${roleStr}`);
-	});
-	return lines.join("\n");
-}
-//#endregion
-export { createActionRouter_exports as n, buildActionBodySchema as t };

package/dist/errors-BI8kEKsO.d.mts

@@ -1,140 +0,0 @@
-//#region src/utils/errors.d.ts
-/**
- * Error Classes
- *
- * Standard error types for the Arc framework.
- */
-interface ErrorDetails {
-  code?: string;
-  statusCode?: number;
-  details?: Record<string, unknown>;
-  cause?: Error;
-  requestId?: string;
-}
-/**
- * Base Arc Error
- *
- * All Arc errors extend this class and produce a consistent error envelope:
- * {
- *   success: false,
- *   error: "Human-readable message",
- *   code: "MACHINE_CODE",
- *   requestId: "uuid",     // For tracing
- *   timestamp: "ISO date", // When error occurred
- *   details: { ... }       // Additional context
- * }
- */
-declare class ArcError extends Error {
-  name: string;
-  readonly code: string;
-  readonly statusCode: number;
-  readonly details?: Record<string, unknown>;
-  readonly cause?: Error;
-  readonly timestamp: string;
-  requestId?: string;
-  constructor(message: string, options?: ErrorDetails);
-  /**
-   * Set request ID (typically from request context)
-   */
-  withRequestId(requestId: string): this;
-  /**
-   * Convert to JSON response.
-   * Includes cause chain when present for debugging visibility.
-   */
-  toJSON(): Record<string, unknown>;
-}
-/**
- * Not Found Error - 404
- */
-declare class NotFoundError extends ArcError {
-  constructor(resource: string, identifier?: string);
-}
-/**
- * Validation Error - 400
- */
-declare class ValidationError extends ArcError {
-  readonly errors: Array<{
-    field: string;
-    message: string;
-  }>;
-  constructor(message: string, errors?: Array<{
-    field: string;
-    message: string;
-  }>);
-}
-/**
- * Unauthorized Error - 401
- */
-declare class UnauthorizedError extends ArcError {
-  constructor(message?: string);
-}
-/**
- * Forbidden Error - 403
- */
-declare class ForbiddenError extends ArcError {
-  constructor(message?: string);
-}
-/**
- * Conflict Error - 409
- */
-declare class ConflictError extends ArcError {
-  constructor(message: string, field?: string);
-}
-/**
- * Organization Required Error - 403
- */
-declare class OrgRequiredError extends ArcError {
-  readonly organizations?: Array<{
-    id: string;
-    roles?: string[];
-  }>;
-  constructor(message: string, organizations?: Array<{
-    id: string;
-    roles?: string[];
-  }>);
-}
-/**
- * Organization Access Denied Error - 403
- */
-declare class OrgAccessDeniedError extends ArcError {
-  constructor(orgId?: string);
-}
-/**
- * Rate Limit Error - 429
- */
-declare class RateLimitError extends ArcError {
-  readonly retryAfter?: number;
-  constructor(message?: string, retryAfter?: number);
-}
-/**
- * Service Unavailable Error - 503
- */
-declare class ServiceUnavailableError extends ArcError {
-  constructor(message?: string);
-}
-/**
- * Create error from status code
- */
-declare function createError(statusCode: number, message: string, details?: Record<string, unknown>): ArcError;
-/**
- * Create a domain-specific error with automatic HTTP status mapping.
- *
- * Eliminates manual `if (err.code === 'X') return status` boilerplate.
- * Arc's error handler automatically maps `statusCode` to HTTP response.
- *
- * @example
- * ```typescript
- * import { createDomainError } from '@classytic/arc';
- *
- * throw createDomainError('MEMBER_NOT_FOUND', 'Member does not exist', 404);
- * throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
- * throw createDomainError('INSUFFICIENT_BALANCE', 'Not enough credits', 402, { balance: 0 });
- * ```
- */
-declare function createDomainError(code: string, message: string, statusCode?: number, details?: Record<string, unknown>): ArcError;
-/**
- * Check if error is an Arc error
- */
-declare function isArcError(error: unknown): error is ArcError;
-//#endregion
-export { NotFoundError as a, RateLimitError as c, ValidationError as d, createDomainError as f, ForbiddenError as i, ServiceUnavailableError as l, isArcError as m, ConflictError as n, OrgAccessDeniedError as o, createError as p, ErrorDetails as r, OrgRequiredError as s, ArcError as t, UnauthorizedError as u };

package/dist/fields-CTMWOUDt.mjs

@@ -1,126 +0,0 @@
-//#region src/permissions/fields.ts
-/**
-* Field-Level Permissions
-*
-* Control field visibility and writability per role.
-* Integrated into the response path (read) and sanitization path (write).
-*
-* @example
-* ```typescript
-* import { fields, defineResource } from '@classytic/arc';
-*
-* const userResource = defineResource({
-*   name: 'user',
-*   adapter: userAdapter,
-*   fields: {
-*     salary: fields.visibleTo(['admin', 'hr']),
-*     internalNotes: fields.writableBy(['admin']),
-*     email: fields.redactFor(['viewer']),
-*     password: fields.hidden(),
-*   },
-* });
-* ```
-*/
-/** Type guard for Mongoose-like documents with toObject() */
-function isMongooseDoc(obj) {
-	return !!obj && typeof obj === "object" && "toObject" in obj && typeof obj.toObject === "function";
-}
-const fields = {
-	hidden() {
-		return { _type: "hidden" };
-	},
-	visibleTo(roles) {
-		return {
-			_type: "visibleTo",
-			roles
-		};
-	},
-	writableBy(roles) {
-		return {
-			_type: "writableBy",
-			roles
-		};
-	},
-	redactFor(roles, redactValue = "***") {
-		return {
-			_type: "redactFor",
-			roles,
-			redactValue
-		};
-	}
-};
-/**
-* Apply field-level READ permissions to a response object.
-* Strips hidden fields, enforces visibility, and applies redaction.
-*
-* @param data - The response object (mutated in place for performance)
-* @param fieldPermissions - Field permission map from resource config
-* @param userRoles - Current user's roles (empty array for unauthenticated)
-* @returns The filtered object
-*/
-function applyFieldReadPermissions(data, fieldPermissions, userRoles) {
-	if (!data || typeof data !== "object") return data;
-	const result = { ...isMongooseDoc(data) ? data.toObject() : data };
-	for (const [field, perm] of Object.entries(fieldPermissions)) switch (perm._type) {
-		case "hidden":
-			delete result[field];
-			break;
-		case "visibleTo":
-			if (!perm.roles?.some((r) => userRoles.includes(r))) delete result[field];
-			break;
-		case "redactFor":
-			if (perm.roles?.some((r) => userRoles.includes(r))) result[field] = perm.redactValue ?? "***";
-			break;
-		case "writableBy": break;
-	}
-	return result;
-}
-/**
-* Apply field-level WRITE permissions to request body.
-*
-* Returns both the filtered body and the list of denied fields. Callers are
-* expected to reject the request when `deniedFields.length > 0` — silently
-* stripping fields hides misconfigurations and real attacks. See
-* `BodySanitizer` for the default policy.
-*
-* @param body - The request body (returns a new filtered copy)
-* @param fieldPermissions - Field permission map from resource config
-* @param userRoles - Current user's roles
-*/
-function applyFieldWritePermissions(body, fieldPermissions, userRoles) {
-	const result = { ...body };
-	const deniedFields = [];
-	for (const [field, perm] of Object.entries(fieldPermissions)) switch (perm._type) {
-		case "hidden":
-			if (field in result) {
-				deniedFields.push(field);
-				delete result[field];
-			}
-			break;
-		case "writableBy":
-			if (field in result && !perm.roles?.some((r) => userRoles.includes(r))) {
-				deniedFields.push(field);
-				delete result[field];
-			}
-			break;
-	}
-	return {
-		body: result,
-		deniedFields
-	};
-}
-/**
-* Resolve effective roles by merging global user roles with org-level roles.
-*
-* Global roles come from `req.user.role` (normalized via getUserRoles()).
-* Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).
-*
-* When no org context exists, returns global roles only — backward compatible.
-*/
-function resolveEffectiveRoles(userRoles, orgRoles) {
-	if (orgRoles.length === 0) return [...userRoles];
-	if (userRoles.length === 0) return [...orgRoles];
-	return [...new Set([...userRoles, ...orgRoles])];
-}
-//#endregion
-export { resolveEffectiveRoles as i, applyFieldWritePermissions as n, fields as r, applyFieldReadPermissions as t };