@classytic/arc 1.1.0 → 2.1.2

package/dist/errorHandler-C1okiriz.mjs

@@ -0,0 +1,109 @@
+import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
+import { f as isArcError } from "./errors-B9bZok84.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 };
+//# sourceMappingURL=errorHandler-C1okiriz.mjs.map

package/dist/errorHandler-C1okiriz.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler-C1okiriz.mjs","names":[],"sources":["../src/plugins/errorHandler.ts"],"sourcesContent":["/**\n * Error Handler Plugin\n *\n * Global error handling for Arc applications.\n * Catches all errors and returns a consistent JSON response.\n *\n * @example\n * import { errorHandlerPlugin } from '@classytic/arc/plugins';\n *\n * await fastify.register(errorHandlerPlugin, {\n *   includeStack: process.env.NODE_ENV !== 'production',\n *   onError: (error, request) => {\n *     // Log to external service (Sentry, etc.)\n *     Sentry.captureException(error);\n *   }\n * });\n */\n\nimport type { FastifyInstance, FastifyRequest, FastifyReply, FastifyError } from 'fastify';\nimport fp from 'fastify-plugin';\nimport { ArcError, isArcError, ValidationError } from '../utils/errors.js';\n\nexport interface ErrorHandlerOptions {\n  /**\n   * Include stack trace in error responses (default: false in production)\n   */\n  includeStack?: boolean;\n\n  /**\n   * Custom error callback for logging to external services\n   */\n  onError?: (error: Error, request: FastifyRequest) => void | Promise<void>;\n\n  /**\n   * Map specific error types to custom responses\n   */\n  errorMap?: Record<string, {\n    statusCode: number;\n    code: string;\n    message?: string;\n  }>;\n}\n\ninterface ErrorResponse {\n  success: false;\n  error: string;\n  code: string;\n  timestamp: string;\n  requestId?: string;\n  details?: Record<string, unknown>;\n  stack?: string;\n}\n\nasync function errorHandlerPluginFn(\n  fastify: FastifyInstance,\n  options: ErrorHandlerOptions = {}\n): Promise<void> {\n  const isProduction = process.env.NODE_ENV === 'production';\n  const {\n    includeStack = !isProduction,\n    onError,\n    errorMap = {},\n  } = options;\n\n  fastify.setErrorHandler(async (error: FastifyError | Error, request: FastifyRequest, reply: FastifyReply) => {\n    // Call custom error handler if provided\n    if (onError) {\n      try {\n        await onError(error, request);\n      } catch (callbackError) {\n        request.log.error({ err: callbackError }, 'Error in onError callback');\n      }\n    }\n\n    // Get request ID if available\n    const requestId = (request as { id?: string }).id;\n\n    // Build base response\n    const response: ErrorResponse = {\n      success: false,\n      error: error.message || 'Internal Server Error',\n      code: 'INTERNAL_ERROR',\n      timestamp: new Date().toISOString(),\n      ...(requestId && { requestId }),\n    };\n\n    let statusCode = 500;\n\n    // Handle ArcError (our error classes)\n    if (isArcError(error)) {\n      statusCode = error.statusCode;\n      response.code = error.code;\n      if (error.details) {\n        response.details = error.details;\n      }\n      if (error.requestId) {\n        response.requestId = error.requestId;\n      }\n      // Log cause chain for debugging (cause is now properly serialized via toJSON)\n      if (error.cause) {\n        request.log.error({ cause: error.cause }, 'Error cause chain');\n      }\n    }\n    // Handle Fastify validation errors\n    else if ('validation' in error && Array.isArray((error as FastifyError).validation)) {\n      statusCode = 400;\n      response.code = 'VALIDATION_ERROR';\n      response.error = 'Validation failed';\n      response.details = {\n        errors: (error as FastifyError).validation?.map((v) => ({\n          field: v.instancePath?.replace(/^\\//, '') || v.params?.missingProperty || 'unknown',\n          message: v.message || 'Invalid value',\n          keyword: v.keyword,\n        })),\n      };\n    }\n    // Handle Fastify errors with statusCode\n    else if ('statusCode' in error && typeof (error as FastifyError).statusCode === 'number') {\n      statusCode = (error as FastifyError).statusCode!;\n      response.code = statusCodeToCode(statusCode);\n    }\n    // Handle mapped error types\n    else if (error.name && errorMap[error.name]) {\n      const mapping = errorMap[error.name]!;\n      statusCode = mapping.statusCode;\n      response.code = mapping.code;\n      if (mapping.message) {\n        response.error = mapping.message;\n      }\n    }\n    // Handle Mongoose validation errors\n    else if (error.name === 'ValidationError' && 'errors' in error) {\n      statusCode = 400;\n      response.code = 'VALIDATION_ERROR';\n      const mongooseErrors = (error as { errors: Record<string, { message: string; path: string }> }).errors;\n\n      // Security: Don't expose schema field names when details are hidden\n      if (includeStack) {\n        response.details = {\n          errors: Object.entries(mongooseErrors).map(([field, err]) => ({\n            field: err.path || field,\n            message: err.message,\n          })),\n        };\n      } else {\n        response.details = { errorCount: Object.keys(mongooseErrors).length };\n      }\n    }\n    // Handle Mongoose CastError (invalid ObjectId, etc.)\n    else if (error.name === 'CastError') {\n      statusCode = 400;\n      response.code = 'INVALID_ID';\n      response.error = 'Invalid identifier format';\n    }\n    // Handle duplicate key errors (MongoDB)\n    else if (error.name === 'MongoServerError' && (error as { code?: number }).code === 11000) {\n      statusCode = 409;\n      response.code = 'DUPLICATE_KEY';\n      response.error = 'Resource already exists';\n      const keyValue = (error as { keyValue?: Record<string, unknown> }).keyValue;\n\n      // Security: Don't expose schema field names when details are hidden\n      if (keyValue && includeStack) {\n        response.details = { duplicateFields: Object.keys(keyValue) };\n      }\n    }\n\n    // Include stack trace if enabled\n    if (includeStack && error.stack) {\n      response.stack = error.stack;\n    }\n\n    // Log server errors\n    if (statusCode >= 500) {\n      request.log.error({ err: error, statusCode }, 'Server error');\n    } else if (statusCode >= 400) {\n      request.log.warn({ err: error, statusCode }, 'Client error');\n    }\n\n    return reply.status(statusCode).send(response);\n  });\n}\n\n/**\n * Map HTTP status code to error code\n */\nfunction statusCodeToCode(statusCode: number): string {\n  const codes: Record<number, string> = {\n    400: 'BAD_REQUEST',\n    401: 'UNAUTHORIZED',\n    403: 'FORBIDDEN',\n    404: 'NOT_FOUND',\n    405: 'METHOD_NOT_ALLOWED',\n    409: 'CONFLICT',\n    422: 'UNPROCESSABLE_ENTITY',\n    429: 'RATE_LIMITED',\n    500: 'INTERNAL_ERROR',\n    502: 'BAD_GATEWAY',\n    503: 'SERVICE_UNAVAILABLE',\n    504: 'GATEWAY_TIMEOUT',\n  };\n  return codes[statusCode] ?? 'ERROR';\n}\n\nexport const errorHandlerPlugin = fp(errorHandlerPluginFn, {\n  name: 'arc-error-handler',\n  fastify: '5.x',\n});\n\nexport default errorHandlerPlugin;\n"],"mappings":"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"}

package/dist/errors-B9bZok84.mjs

@@ -0,0 +1,212 @@
+//#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 };
+//# sourceMappingURL=errors-B9bZok84.mjs.map

package/dist/errors-B9bZok84.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-B9bZok84.mjs","names":[],"sources":["../src/utils/errors.ts"],"sourcesContent":["/**\n * Error Classes\n *\n * Standard error types for the Arc framework.\n */\n\nexport interface ErrorDetails {\n  code?: string;\n  statusCode?: number;\n  details?: Record<string, unknown>;\n  cause?: Error;\n  requestId?: string;\n}\n\n/**\n * Base Arc Error\n *\n * All Arc errors extend this class and produce a consistent error envelope:\n * {\n *   success: false,\n *   error: \"Human-readable message\",\n *   code: \"MACHINE_CODE\",\n *   requestId: \"uuid\",     // For tracing\n *   timestamp: \"ISO date\", // When error occurred\n *   details: { ... }       // Additional context\n * }\n */\nexport class ArcError extends Error {\n  override name: string;\n  readonly code: string;\n  readonly statusCode: number;\n  readonly details?: Record<string, unknown>;\n  override readonly cause?: Error;\n  readonly timestamp: string;\n  requestId?: string;\n\n  constructor(message: string, options: ErrorDetails = {}) {\n    // Pass cause to native Error for proper chain support (Node 16.9+)\n    super(message, options.cause ? { cause: options.cause } : undefined);\n    this.name = 'ArcError';\n    this.code = options.code ?? 'ARC_ERROR';\n    this.statusCode = options.statusCode ?? 500;\n    this.details = options.details;\n    // cause is now set by super() — keep explicit assignment for TypeScript override\n    this.cause = options.cause;\n    this.timestamp = new Date().toISOString();\n    this.requestId = options.requestId;\n\n    // Maintain proper stack trace\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, this.constructor);\n    }\n  }\n\n  /**\n   * Set request ID (typically from request context)\n   */\n  withRequestId(requestId: string): this {\n    this.requestId = requestId;\n    return this;\n  }\n\n  /**\n   * Convert to JSON response.\n   * Includes cause chain when present for debugging visibility.\n   */\n  toJSON(): Record<string, unknown> {\n    return {\n      success: false,\n      error: this.message,\n      code: this.code,\n      timestamp: this.timestamp,\n      ...(this.requestId && { requestId: this.requestId }),\n      ...(this.details && { details: this.details }),\n      ...(this.cause && {\n        cause: this.cause instanceof ArcError\n          ? this.cause.toJSON()\n          : { message: (this.cause as Error).message, name: (this.cause as Error).name },\n      }),\n    };\n  }\n}\n\n/**\n * Not Found Error - 404\n */\nexport class NotFoundError extends ArcError {\n  constructor(resource: string, identifier?: string) {\n    const message = identifier\n      ? `${resource} with identifier '${identifier}' not found`\n      : `${resource} not found`;\n\n    super(message, {\n      code: 'NOT_FOUND',\n      statusCode: 404,\n      details: { resource, identifier },\n    });\n    this.name = 'NotFoundError';\n  }\n}\n\n/**\n * Validation Error - 400\n */\nexport class ValidationError extends ArcError {\n  readonly errors: Array<{ field: string; message: string }>;\n\n  constructor(\n    message: string,\n    errors: Array<{ field: string; message: string }> = []\n  ) {\n    super(message, {\n      code: 'VALIDATION_ERROR',\n      statusCode: 400,\n      details: { errors },\n    });\n    this.name = 'ValidationError';\n    this.errors = errors;\n  }\n}\n\n/**\n * Unauthorized Error - 401\n */\nexport class UnauthorizedError extends ArcError {\n  constructor(message = 'Authentication required') {\n    super(message, {\n      code: 'UNAUTHORIZED',\n      statusCode: 401,\n    });\n    this.name = 'UnauthorizedError';\n  }\n}\n\n/**\n * Forbidden Error - 403\n */\nexport class ForbiddenError extends ArcError {\n  constructor(message = 'Access denied') {\n    super(message, {\n      code: 'FORBIDDEN',\n      statusCode: 403,\n    });\n    this.name = 'ForbiddenError';\n  }\n}\n\n/**\n * Conflict Error - 409\n */\nexport class ConflictError extends ArcError {\n  constructor(message: string, field?: string) {\n    super(message, {\n      code: 'CONFLICT',\n      statusCode: 409,\n      details: field ? { field } : undefined,\n    });\n    this.name = 'ConflictError';\n  }\n}\n\n/**\n * Organization Required Error - 403\n */\nexport class OrgRequiredError extends ArcError {\n  readonly organizations?: Array<{ id: string; roles?: string[] }>;\n\n  constructor(\n    message: string,\n    organizations?: Array<{ id: string; roles?: string[] }>\n  ) {\n    super(message, {\n      code: 'ORG_SELECTION_REQUIRED',\n      statusCode: 403,\n      details: organizations ? { organizations } : undefined,\n    });\n    this.name = 'OrgRequiredError';\n    this.organizations = organizations;\n  }\n}\n\n/**\n * Organization Access Denied Error - 403\n */\nexport class OrgAccessDeniedError extends ArcError {\n  constructor(orgId?: string) {\n    super('Organization access denied', {\n      code: 'ORG_ACCESS_DENIED',\n      statusCode: 403,\n      details: orgId ? { organizationId: orgId } : undefined,\n    });\n    this.name = 'OrgAccessDeniedError';\n  }\n}\n\n/**\n * Rate Limit Error - 429\n */\nexport class RateLimitError extends ArcError {\n  readonly retryAfter?: number;\n\n  constructor(message = 'Too many requests', retryAfter?: number) {\n    super(message, {\n      code: 'RATE_LIMITED',\n      statusCode: 429,\n      details: retryAfter ? { retryAfter } : undefined,\n    });\n    this.name = 'RateLimitError';\n    this.retryAfter = retryAfter;\n  }\n}\n\n/**\n * Service Unavailable Error - 503\n */\nexport class ServiceUnavailableError extends ArcError {\n  constructor(message = 'Service temporarily unavailable') {\n    super(message, {\n      code: 'SERVICE_UNAVAILABLE',\n      statusCode: 503,\n    });\n    this.name = 'ServiceUnavailableError';\n  }\n}\n\n/**\n * Create error from status code\n */\nexport function createError(\n  statusCode: number,\n  message: string,\n  details?: Record<string, unknown>\n): ArcError {\n  const codes: Record<number, string> = {\n    400: 'BAD_REQUEST',\n    401: 'UNAUTHORIZED',\n    403: 'FORBIDDEN',\n    404: 'NOT_FOUND',\n    409: 'CONFLICT',\n    429: 'RATE_LIMITED',\n    500: 'INTERNAL_ERROR',\n    503: 'SERVICE_UNAVAILABLE',\n  };\n\n  return new ArcError(message, {\n    code: codes[statusCode] ?? 'ERROR',\n    statusCode,\n    details,\n  });\n}\n\n/**\n * Check if error is an Arc error\n */\nexport function isArcError(error: unknown): error is ArcError {\n  return error instanceof ArcError;\n}\n"],"mappings":"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"}

package/dist/errors-ChKiFz62.d.mts

@@ -0,0 +1,125 @@
+//#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 };
+//# sourceMappingURL=errors-ChKiFz62.d.mts.map

package/dist/errors-ChKiFz62.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-ChKiFz62.d.mts","names":[],"sources":["../src/utils/errors.ts"],"mappings":";;AAMA;;;;UAAiB,YAAA;EACf,IAAA;EACA,UAAA;EACA,OAAA,GAAU,MAAA;EACV,KAAA,GAAQ,KAAA;EACR,SAAA;AAAA;;;AAgBF;;;;;;;;;;;cAAa,QAAA,SAAiB,KAAA;EACnB,IAAA;EAAA,SACA,IAAA;EAAA,SACA,UAAA;EAAA,SACA,OAAA,GAAU,MAAA;EAAA,SACD,KAAA,GAAQ,KAAA;EAAA,SACjB,SAAA;EACT,SAAA;cAEY,OAAA,UAAiB,OAAA,GAAS,YAAA;;;;EAqBtC,aAAA,CAAc,SAAA;EAAd;;;;EASA,MAAA,CAAA,GAAU,MAAA;AAAA;AAoBZ;;;AAAA,cAAa,aAAA,SAAsB,QAAA;cACrB,QAAA,UAAkB,UAAA;AAAA;;;;cAiBnB,eAAA,SAAwB,QAAA;EAAA,SAC1B,MAAA,EAAQ,KAAA;IAAQ,KAAA;IAAe,OAAA;EAAA;cAGtC,OAAA,UACA,MAAA,GAAQ,KAAA;IAAQ,KAAA;IAAe,OAAA;EAAA;AAAA;;;;cAetB,iBAAA,SAA0B,QAAA;cACzB,OAAA;AAAA;;;;cAYD,cAAA,SAAuB,QAAA;cACtB,OAAA;AAAA;AAdd;;;AAAA,cA0Ba,aAAA,SAAsB,QAAA;cACrB,OAAA,UAAiB,KAAA;AAAA;;;;cAalB,gBAAA,SAAyB,QAAA;EAAA,SAC3B,aAAA,GAAgB,KAAA;IAAQ,EAAA;IAAY,KAAA;EAAA;cAG3C,OAAA,UACA,aAAA,GAAgB,KAAA;IAAQ,EAAA;IAAY,KAAA;EAAA;AAAA;;;;cAe3B,oBAAA,SAA6B,QAAA;cAC5B,KAAA;AAAA;;;;cAaD,cAAA,SAAuB,QAAA;EAAA,SACzB,UAAA;cAEG,OAAA,WAA+B,UAAA;AAAA;;;;cAchC,uBAAA,SAAgC,QAAA;cAC/B,OAAA;AAAA;;;;iBAYE,WAAA,CACd,UAAA,UACA,OAAA,UACA,OAAA,GAAU,MAAA,oBACT,QAAA;;;;iBAsBa,UAAA,CAAW,KAAA,YAAiB,KAAA,IAAS,QAAA"}

package/dist/eventPlugin-CTrLH3mt.d.mts

@@ -0,0 +1,125 @@
+import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-BD2U0BTc.mjs";
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/events/retry.d.ts
+interface RetryOptions {
+  /**
+   * Max retry attempts (not counting the initial attempt).
+   * @default 3
+   */
+  maxRetries?: number;
+  /**
+   * Initial backoff delay in ms. Doubles on each retry (exponential backoff).
+   * @default 1000
+   */
+  backoffMs?: number;
+  /**
+   * Maximum backoff delay in ms (caps exponential growth).
+   * @default 30000
+   */
+  maxBackoffMs?: number;
+  /**
+   * Jitter factor (0-1). Adds randomness to prevent thundering herd.
+   * 0 = no jitter, 1 = full jitter (delay ∈ [0, calculated]).
+   * @default 0.1
+   */
+  jitter?: number;
+  /**
+   * Callback when all retries are exhausted. The event is "dead".
+   * Use this to publish to a `$deadLetter` channel, log, alert, etc.
+   */
+  onDead?: (event: DomainEvent, errors: Error[]) => void | Promise<void>;
+  /**
+   * Optional name for logging/debugging.
+   */
+  name?: string;
+  /**
+   * Logger for retry warnings and error messages (default: console).
+   * Pass `fastify.log` to integrate with your application logger.
+   */
+  logger?: EventLogger;
+}
+/**
+ * Wrap an event handler with retry logic and dead letter support.
+ *
+ * On failure, retries with exponential backoff (with jitter).
+ * After all retries exhausted, calls `onDead` callback if provided.
+ */
+declare function withRetry(handler: EventHandler, options?: RetryOptions): EventHandler;
+/**
+ * Create a dead letter publisher that sends failed events to a `$deadLetter` channel.
+ *
+ * @example
+ * ```typescript
+ * import { withRetry, createDeadLetterPublisher } from '@classytic/arc/events';
+ *
+ * const toDlq = createDeadLetterPublisher(fastify.events);
+ *
+ * await fastify.events.subscribe('order.created', withRetry(handler, {
+ *   maxRetries: 3,
+ *   onDead: toDlq,
+ * }));
+ *
+ * // Monitor dead letters
+ * await fastify.events.subscribe('$deadLetter', async (event) => {
+ *   console.error('Dead letter:', event.payload);
+ *   await alertOps(event.payload);
+ * });
+ * ```
+ */
+declare function createDeadLetterPublisher(events: {
+  publish: <T>(type: string, payload: T, meta?: Record<string, unknown>) => Promise<void>;
+}): (event: DomainEvent, errors: Error[]) => Promise<void>;
+//#endregion
+//#region src/events/eventPlugin.d.ts
+interface EventPluginOptions {
+  /** Event transport (default: MemoryEventTransport) */
+  transport?: EventTransport;
+  /** Enable event logging (default: false) */
+  logEvents?: boolean;
+  /**
+   * Fail-open mode for runtime resilience (default: true).
+   * - true: publish/subscribe/close errors are logged and suppressed
+   * - false: errors are thrown to caller
+   */
+  failOpen?: boolean;
+  /**
+   * Write-Ahead Log (WAL) configuration for at-least-once delivery guarantees.
+   * If provided, events will be saved to the WAL *before* passing to the transport.
+   * After a successful publish, they are acknowledged.
+   */
+  wal?: {
+    save: (event: DomainEvent) => Promise<void>;
+    acknowledge?: (eventId: string) => Promise<void>;
+  };
+  /**
+   * Auto-wrap all subscribed handlers with retry logic.
+   * When enabled, failed handler invocations are retried with exponential backoff.
+   */
+  retry?: Pick<RetryOptions, "maxRetries" | "backoffMs" | "maxBackoffMs" | "jitter">;
+  /**
+   * Dead letter queue for events that exhaust all retries.
+   * Requires `retry` to be enabled. If `retry` is set but no custom `store`,
+   * failed events are published to the `$deadLetter` event type by default.
+   */
+  deadLetterQueue?: {
+    /** Custom store function. If omitted, publishes to '$deadLetter' event type. */store?: (event: DomainEvent, errors: Error[]) => void | Promise<void>;
+  };
+  /** Callback after successful publish (for metrics/tracking) */
+  onPublish?: (event: DomainEvent) => void;
+  /** Callback on publish failure (for metrics/alerting) */
+  onPublishError?: (event: DomainEvent, error: Error) => void;
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    events: {
+      /** Publish an event */publish: <T>(type: string, payload: T, meta?: Partial<DomainEvent["meta"]>) => Promise<void>; /** Subscribe to events */
+      subscribe: (pattern: string, handler: EventHandler) => Promise<() => void>; /** Get transport name */
+      transportName: string;
+    };
+  }
+}
+declare const eventPlugin: FastifyPluginAsync<EventPluginOptions>;
+//#endregion
+export { withRetry as a, createDeadLetterPublisher as i, eventPlugin as n, RetryOptions as r, EventPluginOptions as t };
+//# sourceMappingURL=eventPlugin-CTrLH3mt.d.mts.map

package/dist/eventPlugin-CTrLH3mt.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventPlugin-CTrLH3mt.d.mts","names":[],"sources":["../src/events/retry.ts","../src/events/eventPlugin.ts"],"mappings":";;;;UAiCiB,YAAA;EAoDN;;;;EA/CT,UAAA;EA8CA;;;;EAxCA,SAAA;EA0Ca;AA6Ef;;;EAjHE,YAAA;EAkHwD;;;;;EA3GxD,MAAA;EA4GiD;;;;EAtGjD,MAAA,IAAU,KAAA,EAAO,WAAA,EAAa,MAAA,EAAQ,KAAA,cAAmB,OAAA;EAqGpB;;;EAhGrC,IAAA;EAgGA;;;;EA1FA,MAAA,GAAS,WAAA;AAAA;;;;;;AC1CX;iBDmDgB,SAAA,CACd,OAAA,EAAS,YAAA,EACT,OAAA,GAAS,YAAA,GACR,YAAA;;;;;;;;;;;;;;;;;;;;;;iBA6Ea,yBAAA,CACd,MAAA;EAAU,OAAA,MAAa,IAAA,UAAc,OAAA,EAAS,CAAA,EAAG,IAAA,GAAO,MAAA,sBAA4B,OAAA;AAAA,KAClF,KAAA,EAAO,WAAA,EAAa,MAAA,EAAQ,KAAA,OAAY,OAAA;;;UCrI3B,kBAAA;ED+BL;EC7BV,SAAA,GAAY,cAAA;ED6BkB;EC3B9B,SAAA;EDgCA;;;;;EC1BA,QAAA;EDyCuB;;;;;ECnCvB,GAAA;IACE,IAAA,GAAO,KAAA,EAAO,WAAA,KAAgB,OAAA;IAC9B,WAAA,IAAe,OAAA,aAAoB,OAAA;EAAA;EDmC5B;;;;EC7BT,KAAA,GAAQ,IAAA,CACN,YAAA;ED0GY;;;;;EClGd,eAAA;IDoGS,gFClGP,KAAA,IAAS,KAAA,EAAO,WAAA,EAAa,MAAA,EAAQ,KAAA,cAAmB,OAAA;EAAA;EDkGT;EC/FjD,SAAA,IAAa,KAAA,EAAO,WAAA;ED8FV;EC5FV,cAAA,IAAkB,KAAA,EAAO,WAAA,EAAa,KAAA,EAAO,KAAA;AAAA;AAAA;EAAA,UAInC,eAAA;IACR,MAAA;MDuF+C,uBCrF7C,OAAA,MACE,IAAA,UACA,OAAA,EAAS,CAAA,EACT,IAAA,GAAO,OAAA,CAAQ,WAAA,cACZ,OAAA,QDiFT;MC/EI,SAAA,GACE,OAAA,UACA,OAAA,EAAS,YAAA,KACN,OAAA,cD6EP;MC3EE,aAAA;IAAA;EAAA;AAAA;AAAA,cAKA,WAAA,EAAa,kBAAA,CAAmB,kBAAA"}