@classytic/arc 1.1.0 → 2.1.3

package/dist/errorHandler-C3GY3_ow.mjs

@@ -0,0 +1,108 @@
+import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
+import { f as isArcError } from "./errors-DBANPbGr.mjs";
+import fp from "fastify-plugin";
+
+//#region src/plugins/errorHandler.ts
+var errorHandler_exports = /* @__PURE__ */ __exportAll({
+	default: () => errorHandlerPlugin,
+	errorHandlerPlugin: () => errorHandlerPlugin
+});
+async function errorHandlerPluginFn(fastify, options = {}) {
+	const isProduction = process.env.NODE_ENV === "production";
+	const { includeStack = !isProduction, onError, errorMap = {} } = options;
+	fastify.setErrorHandler(async (error, request, reply) => {
+		if (onError) try {
+			await onError(error, request);
+		} catch (callbackError) {
+			request.log.error({ err: callbackError }, "Error in onError callback");
+		}
+		const requestId = request.id;
+		const response = {
+			success: false,
+			error: error.message || "Internal Server Error",
+			code: "INTERNAL_ERROR",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			...requestId && { requestId }
+		};
+		let statusCode = 500;
+		if (isArcError(error)) {
+			statusCode = error.statusCode;
+			response.code = error.code;
+			if (error.details) response.details = error.details;
+			if (error.requestId) response.requestId = error.requestId;
+			if (error.cause) request.log.error({ cause: error.cause }, "Error cause chain");
+		} else if ("validation" in error && Array.isArray(error.validation)) {
+			statusCode = 400;
+			response.code = "VALIDATION_ERROR";
+			response.error = "Validation failed";
+			response.details = { errors: error.validation?.map((v) => ({
+				field: v.instancePath?.replace(/^\//, "") || v.params?.missingProperty || "unknown",
+				message: v.message || "Invalid value",
+				keyword: v.keyword
+			})) };
+		} else if ("statusCode" in error && typeof error.statusCode === "number") {
+			statusCode = error.statusCode;
+			response.code = statusCodeToCode(statusCode);
+		} else if (error.name && errorMap[error.name]) {
+			const mapping = errorMap[error.name];
+			statusCode = mapping.statusCode;
+			response.code = mapping.code;
+			if (mapping.message) response.error = mapping.message;
+		} else if (error.name === "ValidationError" && "errors" in error) {
+			statusCode = 400;
+			response.code = "VALIDATION_ERROR";
+			const mongooseErrors = error.errors;
+			if (includeStack) response.details = { errors: Object.entries(mongooseErrors).map(([field, err]) => ({
+				field: err.path || field,
+				message: err.message
+			})) };
+			else response.details = { errorCount: Object.keys(mongooseErrors).length };
+		} else if (error.name === "CastError") {
+			statusCode = 400;
+			response.code = "INVALID_ID";
+			response.error = "Invalid identifier format";
+		} else if (error.name === "MongoServerError" && error.code === 11e3) {
+			statusCode = 409;
+			response.code = "DUPLICATE_KEY";
+			response.error = "Resource already exists";
+			const keyValue = error.keyValue;
+			if (keyValue && includeStack) response.details = { duplicateFields: Object.keys(keyValue) };
+		}
+		if (includeStack && error.stack) response.stack = error.stack;
+		if (statusCode >= 500) request.log.error({
+			err: error,
+			statusCode
+		}, "Server error");
+		else if (statusCode >= 400) request.log.warn({
+			err: error,
+			statusCode
+		}, "Client error");
+		return reply.status(statusCode).send(response);
+	});
+}
+/**
+* Map HTTP status code to error code
+*/
+function statusCodeToCode(statusCode) {
+	return {
+		400: "BAD_REQUEST",
+		401: "UNAUTHORIZED",
+		403: "FORBIDDEN",
+		404: "NOT_FOUND",
+		405: "METHOD_NOT_ALLOWED",
+		409: "CONFLICT",
+		422: "UNPROCESSABLE_ENTITY",
+		429: "RATE_LIMITED",
+		500: "INTERNAL_ERROR",
+		502: "BAD_GATEWAY",
+		503: "SERVICE_UNAVAILABLE",
+		504: "GATEWAY_TIMEOUT"
+	}[statusCode] ?? "ERROR";
+}
+const errorHandlerPlugin = fp(errorHandlerPluginFn, {
+	name: "arc-error-handler",
+	fastify: "5.x"
+});
+
+//#endregion
+export { errorHandler_exports as n, errorHandlerPlugin as t };

package/dist/errorHandler-CW3OOeYq.d.mts

@@ -0,0 +1,72 @@
+import { t as DomainEvent } from "./EventTransport-BkUDYZEb.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$1: 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: FastifyPluginAsync<SSEOptions>;
+//#endregion
+//#region src/plugins/errorHandler.d.ts
+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
+   */
+  errorMap?: Record<string, {
+    statusCode: number;
+    code: string;
+    message?: string;
+  }>;
+}
+declare function errorHandlerPluginFn(fastify: FastifyInstance, options?: ErrorHandlerOptions): Promise<void>;
+declare const errorHandlerPlugin: typeof errorHandlerPluginFn;
+//#endregion
+export { ssePlugin as a, _default$1 as c, _default as i, cachingPlugin as l, errorHandlerPlugin as n, CachingOptions as o, SSEOptions as r, CachingRule as s, ErrorHandlerOptions as t };

package/dist/errors-DAWRdiYP.d.mts

@@ -0,0 +1,124 @@
+//#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;
+/**
+ * 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, createError as f, ForbiddenError as i, ServiceUnavailableError as l, ConflictError as n, OrgAccessDeniedError as o, isArcError as p, ErrorDetails as r, OrgRequiredError as s, ArcError as t, UnauthorizedError as u };

package/dist/errors-DBANPbGr.mjs

@@ -0,0 +1,211 @@
+//#region src/utils/errors.ts
+/**
+* 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
+* }
+*/
+var ArcError = class ArcError extends Error {
+	name;
+	code;
+	statusCode;
+	details;
+	cause;
+	timestamp;
+	requestId;
+	constructor(message, options = {}) {
+		super(message, options.cause ? { cause: options.cause } : void 0);
+		this.name = "ArcError";
+		this.code = options.code ?? "ARC_ERROR";
+		this.statusCode = options.statusCode ?? 500;
+		this.details = options.details;
+		this.cause = options.cause;
+		this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+		this.requestId = options.requestId;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+	}
+	/**
+	* Set request ID (typically from request context)
+	*/
+	withRequestId(requestId) {
+		this.requestId = requestId;
+		return this;
+	}
+	/**
+	* Convert to JSON response.
+	* Includes cause chain when present for debugging visibility.
+	*/
+	toJSON() {
+		return {
+			success: false,
+			error: this.message,
+			code: this.code,
+			timestamp: this.timestamp,
+			...this.requestId && { requestId: this.requestId },
+			...this.details && { details: this.details },
+			...this.cause && { cause: this.cause instanceof ArcError ? this.cause.toJSON() : {
+				message: this.cause.message,
+				name: this.cause.name
+			} }
+		};
+	}
+};
+/**
+* Not Found Error - 404
+*/
+var NotFoundError = class extends ArcError {
+	constructor(resource, identifier) {
+		const message = identifier ? `${resource} with identifier '${identifier}' not found` : `${resource} not found`;
+		super(message, {
+			code: "NOT_FOUND",
+			statusCode: 404,
+			details: {
+				resource,
+				identifier
+			}
+		});
+		this.name = "NotFoundError";
+	}
+};
+/**
+* Validation Error - 400
+*/
+var ValidationError = class extends ArcError {
+	errors;
+	constructor(message, errors = []) {
+		super(message, {
+			code: "VALIDATION_ERROR",
+			statusCode: 400,
+			details: { errors }
+		});
+		this.name = "ValidationError";
+		this.errors = errors;
+	}
+};
+/**
+* Unauthorized Error - 401
+*/
+var UnauthorizedError = class extends ArcError {
+	constructor(message = "Authentication required") {
+		super(message, {
+			code: "UNAUTHORIZED",
+			statusCode: 401
+		});
+		this.name = "UnauthorizedError";
+	}
+};
+/**
+* Forbidden Error - 403
+*/
+var ForbiddenError = class extends ArcError {
+	constructor(message = "Access denied") {
+		super(message, {
+			code: "FORBIDDEN",
+			statusCode: 403
+		});
+		this.name = "ForbiddenError";
+	}
+};
+/**
+* Conflict Error - 409
+*/
+var ConflictError = class extends ArcError {
+	constructor(message, field) {
+		super(message, {
+			code: "CONFLICT",
+			statusCode: 409,
+			details: field ? { field } : void 0
+		});
+		this.name = "ConflictError";
+	}
+};
+/**
+* Organization Required Error - 403
+*/
+var OrgRequiredError = class extends ArcError {
+	organizations;
+	constructor(message, organizations) {
+		super(message, {
+			code: "ORG_SELECTION_REQUIRED",
+			statusCode: 403,
+			details: organizations ? { organizations } : void 0
+		});
+		this.name = "OrgRequiredError";
+		this.organizations = organizations;
+	}
+};
+/**
+* Organization Access Denied Error - 403
+*/
+var OrgAccessDeniedError = class extends ArcError {
+	constructor(orgId) {
+		super("Organization access denied", {
+			code: "ORG_ACCESS_DENIED",
+			statusCode: 403,
+			details: orgId ? { organizationId: orgId } : void 0
+		});
+		this.name = "OrgAccessDeniedError";
+	}
+};
+/**
+* Rate Limit Error - 429
+*/
+var RateLimitError = class extends ArcError {
+	retryAfter;
+	constructor(message = "Too many requests", retryAfter) {
+		super(message, {
+			code: "RATE_LIMITED",
+			statusCode: 429,
+			details: retryAfter ? { retryAfter } : void 0
+		});
+		this.name = "RateLimitError";
+		this.retryAfter = retryAfter;
+	}
+};
+/**
+* Service Unavailable Error - 503
+*/
+var ServiceUnavailableError = class extends ArcError {
+	constructor(message = "Service temporarily unavailable") {
+		super(message, {
+			code: "SERVICE_UNAVAILABLE",
+			statusCode: 503
+		});
+		this.name = "ServiceUnavailableError";
+	}
+};
+/**
+* Create error from status code
+*/
+function createError(statusCode, message, details) {
+	return new ArcError(message, {
+		code: {
+			400: "BAD_REQUEST",
+			401: "UNAUTHORIZED",
+			403: "FORBIDDEN",
+			404: "NOT_FOUND",
+			409: "CONFLICT",
+			429: "RATE_LIMITED",
+			500: "INTERNAL_ERROR",
+			503: "SERVICE_UNAVAILABLE"
+		}[statusCode] ?? "ERROR",
+		statusCode,
+		details
+	});
+}
+/**
+* Check if error is an Arc error
+*/
+function isArcError(error) {
+	return error instanceof ArcError;
+}
+
+//#endregion
+export { OrgAccessDeniedError as a, ServiceUnavailableError as c, createError as d, isArcError as f, NotFoundError as i, UnauthorizedError as l, ConflictError as n, OrgRequiredError as o, ForbiddenError as r, RateLimitError as s, ArcError as t, ValidationError as u };