@classytic/arc 2.10.3 → 2.11.0

package/dist/createActionRouter-Bp_5c_2b.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/errorHandler-DRQ3EqfL.d.mts

@@ -1,218 +0,0 @@
-import { n as DomainEvent } from "./EventTransport-CUw5NNWe.mjs";
-import { FastifyInstance, FastifyPluginAsync, FastifyRequest } from "fastify";
-
-//#region src/plugins/caching.d.ts
-interface CachingRule {
-  /** Path prefix to match (e.g., '/api/products') */
-  match: string;
-  /** Cache-Control max-age in seconds */
-  maxAge: number;
-  /** Cache-Control: private vs public (default: public) */
-  private?: boolean;
-  /** stale-while-revalidate directive in seconds */
-  staleWhileRevalidate?: number;
-}
-interface CachingOptions {
-  /** Default max-age in seconds for Cache-Control (default: 0 = no-cache) */
-  maxAge?: number;
-  /** Enable ETag generation (default: true) */
-  etag?: boolean;
-  /** Enable conditional requests — 304 Not Modified (default: true) */
-  conditional?: boolean;
-  /** HTTP methods to cache (default: ['GET', 'HEAD']) */
-  methods?: string[];
-  /** Paths to exclude from caching (prefix match) */
-  exclude?: string[];
-  /** Custom cache rules per path prefix */
-  rules?: CachingRule[];
-}
-declare const cachingPlugin: FastifyPluginAsync<CachingOptions>;
-declare const _default$3: FastifyPluginAsync<CachingOptions>;
-//#endregion
-//#region src/plugins/sse.d.ts
-interface SSEOptions {
-  /** SSE endpoint path (default: '/events/stream') */
-  path?: string;
-  /** Require authentication (default: true) */
-  requireAuth?: boolean;
-  /** Event patterns to stream (default: ['*'] = all) */
-  patterns?: string[];
-  /** Heartbeat interval in ms (default: 30000) */
-  heartbeat?: number;
-  /** Filter events by organizationId from request.scope (default: false) */
-  orgScoped?: boolean;
-  /** Custom event filter function */
-  filter?: (event: DomainEvent<unknown>, request: FastifyRequest) => boolean;
-}
-declare const ssePlugin: FastifyPluginAsync<SSEOptions>;
-declare const _default$2: FastifyPluginAsync<SSEOptions>;
-//#endregion
-//#region src/plugins/metrics.d.ts
-interface MetricsOptions {
-  /** Endpoint path (default: '/_metrics') */
-  path?: string;
-  /** Prefix for all metric names (default: 'arc') */
-  prefix?: string;
-  /** Called after metrics are collected (for OTLP push, etc.) */
-  onCollect?: (metrics: MetricEntry[]) => void;
-}
-interface MetricEntry {
-  name: string;
-  type: "counter" | "histogram" | "gauge";
-  help: string;
-  values: Array<{
-    labels: Record<string, string>;
-    value: number;
-  }>;
-}
-interface MetricsCollector {
-  /** Get all metrics as structured data */
-  collect(): MetricEntry[];
-  /** Reset all metrics */
-  reset(): void;
-  /** Record a CRUD operation */
-  recordOperation(resource: string, operation: string, status: number, durationMs: number): void;
-  /** Record a cache hit */
-  recordCacheHit(resource: string): void;
-  /** Record a cache miss */
-  recordCacheMiss(resource: string): void;
-  /** Record an event publish */
-  recordEventPublish(eventType: string): void;
-  /** Record an event consume */
-  recordEventConsume(eventType: string): void;
-  /** Record a circuit breaker state change */
-  recordCircuitBreakerState(service: string, state: string): void;
-}
-declare module "fastify" {
-  interface FastifyInstance {
-    metrics: MetricsCollector;
-  }
-}
-declare const metricsPlugin: FastifyPluginAsync<MetricsOptions>;
-declare const _default$1: FastifyPluginAsync<MetricsOptions>;
-//#endregion
-//#region src/plugins/versioning.d.ts
-interface VersioningOptions {
-  /** Versioning strategy */
-  type: "header" | "prefix";
-  /** Default version when none specified (default: '1') */
-  defaultVersion?: string;
-  /** Header name to read (default: 'accept-version') */
-  headerName?: string;
-  /** Response header name (default: 'x-api-version') */
-  responseHeader?: string;
-  /** Deprecated versions — adds Deprecation + Sunset headers */
-  deprecated?: string[];
-  /** Sunset date for deprecated versions (ISO 8601) */
-  sunset?: string;
-}
-declare module "fastify" {
-  interface FastifyRequest {
-    apiVersion: string;
-  }
-}
-declare const versioningPlugin: FastifyPluginAsync<VersioningOptions>;
-declare const _default: FastifyPluginAsync<VersioningOptions>;
-//#endregion
-//#region src/plugins/errorHandler.d.ts
-/** Class-based error mapper — maps thrown error instances to HTTP responses */
-interface ErrorMapper<T extends Error = Error> {
-  /** Error class to match (uses instanceof) */
-  type: new (...args: unknown[]) => T;
-  /** Convert the error to an HTTP response shape */
-  toResponse: (error: T) => {
-    status: number;
-    code?: string;
-    message?: string;
-    details?: Record<string, unknown>;
-  };
-}
-interface ErrorHandlerOptions {
-  /**
-   * Include stack trace in error responses (default: false in production)
-   */
-  includeStack?: boolean;
-  /**
-   * Custom error callback for logging to external services
-   */
-  onError?: (error: Error, request: FastifyRequest) => void | Promise<void>;
-  /**
-   * Map specific error types to custom responses (by error.name string)
-   */
-  errorMap?: Record<string, {
-    statusCode: number;
-    code: string;
-    message?: string;
-  }>;
-  /**
-   * Class-based error mappers — checked via `instanceof`, highest priority.
-   *
-   * Register your domain error classes once; Arc auto-catches and maps them
-   * in every handler. Handlers just `throw` — no try/catch needed.
-   *
-   * @example
-   * ```typescript
-   * class AccountingError extends Error {
-   *   constructor(message: string, public status: number, public code: string) {
-   *     super(message);
-   *   }
-   * }
-   *
-   * const app = await createApp({
-   *   errorHandler: {
-   *     errorMappers: [
-   *       {
-   *         type: AccountingError,
-   *         toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
-   *       },
-   *     ],
-   *   },
-   * });
-   *
-   * // Now handlers just throw:
-   * handler: async (req) => {
-   *   await ledger.post(id); // throws AccountingError → Arc maps to proper HTTP response
-   * }
-   * ```
-   */
-  errorMappers?: ErrorMapper[];
-  /**
-   * Classify an error as a duplicate-key / unique-constraint violation →
-   * mapped to `409 Conflict` with `code: "DUPLICATE_KEY"`.
-   *
-   * Mirrors `RepositoryLike.isDuplicateKeyError` for the Fastify layer: errors
-   * that escape a controller (custom routes, user hooks, raw driver calls)
-   * still land here, so the classifier is duplicated at the edge. Defaults
-   * cover MongoDB (`code 11000` / `codeName "DuplicateKey"`), Prisma
-   * (`code "P2002"`), and Postgres (`code "23505"`). Override to add other
-   * backends (DynamoDB `ConditionalCheckFailedException`, etc.) or to disable
-   * the built-in detection.
-   */
-  isDuplicateKeyError?: (err: unknown) => boolean;
-}
-/**
- * Default duplicate-key detector covering the mainstream drivers arc sees
- * most. Detection is strictly by known driver codes — never by message
- * string matching — because false positives on dup-key silently mask real
- * errors (WriteConflict, NotWritablePrimary, etc.) as 409s. For long-tail
- * drivers (Neo4j, MSSQL, DynamoDB, custom kits), compose rather than
- * replace:
- *
- * ```ts
- * import { defaultIsDuplicateKeyError } from '@classytic/arc/plugins';
- *
- * errorHandler: {
- *   isDuplicateKeyError: (err) =>
- *     defaultIsDuplicateKeyError(err) || isNeo4jDupKey(err),
- * }
- * ```
- *
- * Drizzle apps get coverage transitively (Drizzle doesn't wrap driver
- * errors — pg/mysql2/better-sqlite3 codes propagate as-is). Neon is
- * Postgres-wire-compatible → `23505` covers `@neondatabase/serverless`.
- */
-declare function defaultIsDuplicateKeyError(err: unknown): boolean;
-declare function errorHandlerPluginFn(fastify: FastifyInstance, options?: ErrorHandlerOptions): Promise<void>;
-declare const errorHandlerPlugin: typeof errorHandlerPluginFn;
-//#endregion
-export { CachingRule as _, VersioningOptions as a, MetricEntry as c, _default$1 as d, metricsPlugin as f, CachingOptions as g, ssePlugin as h, errorHandlerPlugin as i, MetricsCollector as l, _default$2 as m, ErrorMapper as n, _default as o, SSEOptions as p, defaultIsDuplicateKeyError as r, versioningPlugin as s, ErrorHandlerOptions as t, MetricsOptions as u, _default$3 as v, cachingPlugin as y };

package/dist/errors-CCSsMpXE.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 };